# @coda-console/review 中文文档 规范地址：https://npmcn.com/package/%40coda-console/review/ 版本：2\.9\.1 npm 元数据更新时间：2026-10-31T18:47:21.146Z 中文译文更新时间：2026-10-31T19:58:39.537Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40coda-console/review 原文对照：https://npmcn.com/package/%40coda-console/review/?lang=original 项目主页：https://github.com/coda-console/coda-plugins#readme 源码仓库：https://github.com/coda-console/coda-plugins ## 关键信息（来自 npm 元数据） - 包体积（解压后）：107 kB，18 个文件 - TypeScript 类型：未声明 - 运行依赖：0 个 - 首次发布：2026-10-21T05:24:20.644Z - 最新版本发布：2026-10-31T18:47:20.821Z - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 会话开的 PR 从开出来起一条流程：每个新版本先跑项目声明的检查，再请另一家 Agent 评审，要求修改时交给开 PR 的会话处理、有分歧时交给你仲裁；通过后请你批准合并，跑过项目的合并前检查再合并，合并后按你的选择删除远程分支、调用项目的部署和发布流程，PR 合并或关闭时结束。 ## 安装 ```sh npm install @coda-console/review ``` 也可以使用：`pnpm add @coda-console/review`、`yarn add @coda-console/review`、`bun add @coda-console/review` ## README # PR 生命流程 `review`：会话开的 PR 从开出来起由流程 `pull-request` 跟着走，一个 PR 一条运行，到合并或关闭才结束。 它只用 Coda 流程的公开原语（PR 事件、Agent 步骤、人工任务、调用其他流程），也是写 PR 流程的样例：要不一样的流程，照着它改一份（见文末「改成自己的」）。 它依赖内置的 GitHub 插件（`extensionDependencies`）：PR 事件由 GitHub 插件的「PR 观察」发布；装 review 时先装 GitHub 插件，卸载 GitHub 插件时 review 一起卸载。 运行的标题是「PR #号 标题」（手动发起的是参数 `pr`，评审查出 PR 后是「PR #号（地址）」），卡片上有「检查」「评审」「合并」三段；草稿、叠放的 PR 另有「草稿」「叠放」，选了部署或发布的，合并后再有「部署与发布」。 流程通过 `coda:key` 声明 PR 地址为主键：在同一项目中，自动、手动发起共享一条未结束的运行，包括排队、等答复和取消收尾。地址不区分大小写。结束后新请求可再发起；旧请求重试仍返回原运行。 也可以 `workflow_run pull-request` 手动发起（必填 `pr`：GitHub 返回的完整 PR 地址，可选 `focus`）。已有运行时返回它，沿用原进度、关注点和结果接收会话；草稿中的运行也照旧等标记为可评审。没有运行时只评审一次、不计次数、不进入合并；如果随后 PR 观察发来事件，在同一条运行里接上完整流程。是否接入完整流程按 `github.event.coda.heard` 判断：手动运行尚未收到事件时为空。 `pr` 须在创建运行前明确。编号、旧仓库地址或带后缀的链接先用 `gh pr view <编号或链接> --json url --jq .url` 取得 GitHub 返回的地址，再传入；流程不从 origin 猜仓库身份。需要查最近开的 PR 时先用 GitHub 插件的 `github-reported-pr` 找到它，再用 `gh pr view` 确认当前地址。输入不接受编号、末尾斜线、查询参数或片段，避免不同拼写创建不同主键。此版本需要支持 `coda:key` 的 Coda 流程引擎。 ``` .coda/workflows/pull-request.bpmn 流程本身 scripts/checks.mjs 等 GitHub 检查 scripts/review.mjs 交叉评审：选评审方、开会话、读结论、写 PR 评论 scripts/base.mjs 看 base（叠放） scripts/approval.mjs 记下批准：时刻与合并后要做的事 scripts/merge.mjs 合并 scripts/delete-branch.mjs 合并确认后删除远程源分支 scripts/notes.mjs 发布流程的参数（更新说明与 publish） scripts/step.mjs 各脚本共用：读参数、写输出与摘要、读 PR 的 base prompts/review.md 评审方收到的提示词 prompts/rules.md 评审的规则：评审方照它评审，开 PR 的会话照它判断意见成不成立 prompts/principles/ 评审重点，一项一段，按设置取用 ``` | 设置 | 类型 | 默认 | | --- | --- | --- | | `review.reviewers` 评审组合 | 表格：作者匹配 → Agent 组合 | Claude 由 Codex 评审，Codex 由 Claude 评审，Kimi、Grok 由 Codex 评审，OpenCode 由 Claude 评审 | | `review.blockingSeverity` 阻塞级别 | P0–P3 之一 | P2 | | `review.principles` 评审重点 | 多选：`state` 状态与失败、`defense` 多余的防御、`architecture` 架构与腐化、`tests` 测试；勾选的那几段（`prompts/principles/` 下同名文件）放进提示词 | 都选 | | `review.maxReviews` 一条运行最多自动评审几次 | 整数 1–100 | 3 | | `review.mergeMethod` 合并方式 | `squash`、`merge`、`rebase` 之一 | `squash` | | `review.mergeOptions` 合并时默认勾选 | 多选：删除远程分支、部署、发布预览版、发布正式版、全部完成后通知 Agent | 都不选 | 插件设置列出全部合并选项；目录设置继承插件的选择，也可整组覆盖或恢复继承。目录里只显示该目录有的部署、发布类别。默认值在运行开始时读取，已经打开的卡片保持原来的选择。需要支持勾选项 `default` 与设置选项 `workflowKind` 的 Coda。 ## 项目提供的部分 插件管流程，项目在自己的仓库里提供四样，跟着代码走： - **评审准则**：`.coda/review.md`，从 PR 的 **base 提交**读取，交给评审方，也写进「处理评审意见」交给开 PR 的会话。PR 改它只从合并后的评审起生效；文件不存在就省略，读不出 base 提交时这次评审失败。 - **检查**：仓库里声明为 `coda:kind="check"` 的流程（第 2 步），每个版本都跑。 - **合并前检查**：声明为 `coda:kind="premerge"` 的流程（第 5 步），你批准后在要合并的提交上只跑一次；每个版本都跑嫌贵的验证（如整套回归）放这里。 - **部署与发布**：声明为 `coda:kind="deploy"`、`preview`、`release` 的流程（第 6 步）。 ## 流程 1. **草稿**：PR 是草稿就等作者标记为可评审（`pull_request.ready_for_review`）；有新提交时按它带来的草稿状态重新判断，关闭则结束。 推送和标记为可评审落在 Coda 的同一次查看之间时，只有新提交这一个事件，它说已不是草稿就去评审。 2. **检查**：机器检查便宜，先过了它们再请 Agent 评审。 - 「跑项目的检查」在 PR 的提交上调用项目声明的检查（`coda:kind="check"`）并等它们结束；没通过的检查让自己的运行失败，有一个失败就交给开 PR 的会话。 检查可以同时往提交上写一条 GitHub 状态，一句话结论在描述里。项目没有检查就直接过去。 - 「等 GitHub 检查」（`checks.mjs`）再每隔几秒读一次 `gh pr checks`，等这个提交在 GitHub 上的检查（commit status 与 check run，包括 GitHub Actions）都有了结果， 一小时没等到这一步失败。都通过就去评审，各项的一句话结论交给评审方、写在批准卡上；有没通过的同样交给开 PR 的会话。 - 「检查没通过：处理后答复」：是改动导致的就推送新提交，从头再来；检查本身出了问题就处理好后答复，项目的检查再跑一遍（GitHub 上的其他检查由它自己重跑）。 它做不了交给你「检查没通过：等你处理」。有新提交就打断，从「草稿吗」重来。手动发起的评审不跑检查。 3. **评审**：有新提交就打断，从「草稿吗」重来。 - 「评审吗」：同一个提交在同一个 base 上评审通过过就不再评；这条运行已自动评审 `review.maxReviews` 次（手动发起的不数），交给你「评审次数已到上限」：放行当前版本，或再评审一次。 - 「交叉评审」（`review.mjs`）：按评审组合最具体的一行选出评审方（行键是 `*`、`agent`、`agent|model`、`agent|model|effort`，没有适用的行就失败）， 用 `coda-agent` 在被评审的提交上开一个新会话，交给它填好的提示词：去哪看改动、这个提交上各项检查的结论、作者写的标题与正文（夹在作者猜不到的标记之间，声明只是参考资料）、 这条运行上一次评审的发现、评审的规则（`rules.md` 填好的全文：项目评审准则、通用要求、开着的评审重点、严重程度的定义）、关注点。会话失败或结果未知时每隔 20 秒重试，最多 3 次；取消或参数错误不重试。 评审默认复用已有验证证据；较早提交的结果先判断后续改动是否影响其覆盖范围。只有具体疑点或影响结论的验证缺口才补跑最小检查，并先说明原因；生命周期声明的检查与合并前门禁仍由流程执行。 - 评审方按 P0（最严重）到 P3 给每条发现定级，在回复末尾的 `review` 代码块里以 JSON 列出；脚本按阻塞级别得出结论： | 结论 | 条件 | 之后 | | --- | --- | --- | | `APPROVE` | 没有发现 | 通过 | | `COMMENT` | 只有低于阻塞级别的发现 | 通过，低优问题写在 PR 评论和批准卡上 | | `REQUEST_CHANGES` | 有阻塞级别及以上的发现 | 「处理评审意见」交给开 PR 的会话 | | 未完成 | 评审会话没正常结束，或没按格式给出结论（任何一条不合格式都算） | 这一步失败，运行失败，唤醒开 PR 的会话 | 每次评审在 PR 上留一条评论，写结论、评审方与发现；写失败只记在摘要里。GitHub 不允许给自己的 PR 批准或要求修改，所以结论不以 PR review 的形式发出。 「交叉评审」的摘要只给用户看（`coda:audience="user"`）：交给会话的任务只带阻塞项，完整评审在批准卡上，你点「让 Agent 处理评审意见」才交出去。 - 「处理评审意见」：任务里有阻塞级别、阻塞的发现和评审方依据的规则（与交给评审方的原文相同），会话照规则核实，判断该不该不同意。 会话修改、推送后答复 `completed`，运行「等新提交」；不同意就答复 `rejected` 并写明理由和依据的规则，交给你「仲裁评审意见」： 放行就接着走，按评审意见修改则把「处理评审意见」再交给会话。 4. **叠放**：只合并进仓库的默认分支。「看 base」（`base.mjs`）读 PR 现在的 base 与默认分支，base 是别的分支时不请你批准，停在「叠放」等 base 变了（`pull_request.edited`）， 再从「草稿吗」重来：base 变了改动就变了，重新评审。在「合并」里（等你批准、等会话处理时）base 变了也一样从头再看，批准卡撤回。 仓库开了合并后删分支时，下层 PR 合并后 GitHub 自己把 base 改到默认分支；没开就由作者用 `gh pr edit --base` 改。 5. **合并**： - 「批准合并」交给你，卡片写明评审结论、改动（按路径第一段分组，如 `backend/ 2 · Sources/ 1`）、PR 链接、各项检查和最近一次评审。 主按钮「合并」按 `review.mergeOptions` 的默认值提交；右侧箭头或长按打开勾选面板，选项是「合并后删除远程分支」「部署」「发布预览版」「发布正式版」「全部完成后通知 Agent」，初始按设置勾选，点面板内「合并」才提交。取消不保存本次调整，再打开恢复默认值。未设置时全部不选。 卡片之前的「看项目有哪些部署、发布」（`workflow-kinds`）查项目在这个提交上有哪几类流程，部署和发布选项只给项目有的那几类（`coda:shown`）； 比如只有部署流程的项目，面板里有「合并后删除远程分支」「部署」和「全部完成后通知 Agent」。没给的那几项按不勾算。需要 Coda 745f85c 及之后。 另有「让 Agent 处理评审意见」：连同你的备注交给开 PR 的会话「处理你交付的评审意见」，它推送后重新评审、再请你批准，它做不了就回到批准卡；以及「关闭 PR」（`gh pr close`）。 - 「合并前检查」：你选了合并后，先「记下批准」（`approval.mjs`）：批准的时刻，和你勾的删分支、部署、发布、通知（合并后都照它做），再在评审通过的提交上调用项目声明的合并前检查（`coda:kind="premerge"`）并等它们结束； 项目没有就直接过去。有一个没通过就交给开 PR 的会话「合并前检查没通过：处理后答复」：改动导致的就推送新提交，照常检查、评审，通过后按你这次的选择合并，不再问； 检查本身出了问题就处理好后答复，再跑一遍。它做不了交给你「合并前检查没通过：等你处理」。合并没成功后重试合并不再跑合并前检查（同一个提交已经通过）。 需要认识 `premerge` 这一类的 Coda。 - 「合并」（`merge.mjs`）：先读 PR 现在的 base，不是默认分支就不合（Coda 下次查看 PR 时才得知 base 变了，可能晚于你批准）； 再 `gh pr merge --<合并方式> --match-head-commit <通过的提交>`，只合评审通过（或你放行）的那个提交，分支动过 GitHub 就不合； 不打开 GitHub 的自动合并，它会合并之后推送、还没评审的版本。目标分支要求合并队列时，GitHub 把它放进队列。 - 没有合并（base 不是默认分支、冲突、要先合入目标分支、草稿、检查没过等）：原因交给开 PR 的会话「合并没成功：处理后答复」。它推送新提交就照常评审， 通过后按你这次的选择直接合并，不再问；处理好别的（标记为可评审、等检查通过）就答复 `completed` 重试。它做不了，交给你「合并没成功：等你处理」：重试合并或关闭 PR。 - 批准在评审再要求修改时作废：「交叉评审」逐次接力输出最近一次要求修改的时刻 `changesAt`，「记下批准」输出你批准的时刻 `at`， 「按原批准合并吗」只在 `at` 晚于 `changesAt` 时不再问你。 - 交给 GitHub 后在「等 GitHub 确认」等关闭事件，它带来合并提交；期间有新提交（被移出了合并队列）就从头再来。 我们发起的合并、关闭命令正常收尾；它们产生的关闭事件先到时留在收件箱，不打断命令，也不把合并阶段记为取消。 合并命令结束后再读取确认，照你的勾选接着做。等待批准、合并前检查或人工处理时收到关闭，仍立即结束相应等待。 合并前，「交给 GitHub」记下要交出去的提交；合并受阻、等人处理时才收到这个提交的合并确认，仍照原批准继续。 合并前检查没过、还在等人处理时被别处合并，不算这条运行的合并。 - 勾选「合并后删除远程分支」时，确认合并后、部署与发布前运行「删除远程分支」（`delete-branch.mjs`）。它从 PR 读取源仓库（包括 fork）与源分支， 只删除仍指向这次批准合并的提交的远程分支；本地分支与会话工作树保留。分支或源仓库已删除就跳过，有了其他提交、是默认分支或合并目标分支则保留，原因记在步骤摘要。 删除用 Git 的 `--force-with-lease=:`，推送期间分支变动也不会误删。读取或删除失败会让运行失败，处理后可从失败处继续，之后再部署与发布。 不勾选时流程不主动删分支；GitHub 仓库自身的「合并后自动删除分支」设置仍独立生效。 6. **部署与发布**：合并确认后按你的勾选，在合并提交（`merge_commit_sha`）上调用其他流程：先 `run-workflows kind=deploy`， 再交给开 PR 的会话「写更新说明」（它做不了交给你写；你选「不再发布」，运行正常结束），然后按勾选调用 `kind=preview`、`release` 或 `preview,release`， 参数 `notes`（更新说明）与 `publish`（`"true"`）。没声明某个参数的流程不会拿到它；项目没有这一类的流程，这一步直接过去。 部署或发布失败时运行失败，结果交回开 PR 的会话，由它查明后手动重跑对应的流程。 - PR 在 GitHub 网页上合并或关闭（不经这条运行的「等 GitHub 确认」，也不是上面那种你批准的版本在合并时先送到的关闭），运行随之结束，交出去的任务和卡片撤回，不删除分支、不部署、不发布。 - 正常结束只更新运行与卡片、结清等待，不唤醒 Agent；勾选「全部完成后通知 Agent」则在合并及所选删除分支、部署、发布都结束后回传一次。未处理的失败照常回传；手动发起的评审交回结论。 - 流程只按检查、评审结果、PR 状态与你的批准推进，不读取作者会话的忙闲、后台任务或其他运行；合并前要先完成的验证写成检查（第 2 步）或合并前检查（第 5 步）。 ## 改成自己的 - **只改评审的措辞**：改 `prompts/review.md`；评审的规则在 `prompts/rules.md`，改了评审方和开 PR 的会话同时生效。 `{{…}}` 由评审脚本换成整段文字，文件开头的注释列出各个占位（注释不发出去）；只有回复末尾的 `review` 代码块是脚本读结论的约定，不能改。 - **改流程**：把这个目录复制到你自己的仓库，在 Coda 的「设置 › 插件」里卸载内置的 `review`，再「从仓库添加…」装你的那份（同名替换）， 之后按你的仓库更新、回退。改了插件 ID 也要先卸载内置的，否则每个 PR 会跑两条流程。 - 改这里的 `review` 本身，照本仓库的规矩提 PR、升 `version`；Coda 再同步到合并后的提交（见仓库根的 README）。 ## 常见问题 ### @coda-console/review 是什么？ 会话开的 PR 从开出来起一条流程：每个新版本先跑项目声明的检查，再请另一家 Agent 评审，要求修改时交给开 PR 的会话处理、有分歧时交给你仲裁；通过后请你批准合并，跑过项目的合并前检查再合并，合并后按你的选择删除远程分支、调用项目的部署和发布流程，PR 合并或关闭时结束。 ### 如何安装 @coda-console/review？ 在项目目录运行 npm install @coda-console/review，或使用 pnpm add / yarn add / bun add。 ### @coda-console/review 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/coda-console\_\_review 是否存在。 ### @coda-console/review 可以商用吗？ @coda-console/review 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @coda-console/review 还在维护吗？ 最新版本 2\.9\.1 发布于 2026/11/01（2 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/10/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。