企业官网建设流程全解析

Archon archon-post-review-to-pr 详解：将代码审查结果自动发布为 GitHub PR 评论的确定性 Agent 命令模板

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

本文以 Archon 仓库中的默认命令文件 .archon/commands/defaults/archon-post-review-to-pr.md 为主体，完整解读这条 Agent 命令模板的设计：它如何从工作流工件（artifact）中读取代码审查结论，按 GitHub 友好的格式构建评论正文，通过ghCLI 发布到 Pull Request 并做存在性校验。读完本文，你将掌握 Archon 命令体系的核心范式——以工件为唯一交接媒介、以阶段检查点约束行为、以确定性失败路径兜底——并能据此为自己的项目编写同风格的 Agent 命令。

1. 命令定位：一条 Markdown 提示词模板，而非可执行代码

在 Archon 中，workflow 节点引用一个command时（例如- command: post-review），引擎会按顺序做四件事：加载命令文档、替换$ARGUMENTS等变量、把整份文档作为提示词发给 AI、由 AI 按指令产出输出。官方指南 Authoring Commands 对此的总结是：Commands are prompts, not code（命令是提示词，不是代码）。

archon-post-review-to-pr就是一条典型的“文件型命令”（file-backed command），其文件结构由 frontmatter 与正文两部分构成：

--- description: Post code review findings as a comment on the PR argument-hint: (none - reads from artifacts) --- # Post Review to PR ...

两个 frontmatter 字段的含义，可对照 authoring-commands.md 中的字段表理解：

argument-hint的值本身就传递了关键设计信息：这条命令的输入不来自用户消息，而来自上一次运行阶段留在磁盘上的工件。这正是它能在多节点工作流中作为“收尾节点”独立执行的前提。

命令的存放位置也值得注意。按 authoring-commands.md 的约定，共享命令位于工作目录下的.archon/commands/，其中defaults/子目录是“维护者领地”——专属于随 Archon 一同分发的内置命令，且构建时会被嵌入二进制（即生成 bundled-defaults.generated.ts，archon-post-review-to-pr的全文就内嵌在该文件的对应条目中，见 bundled-defaults.generated.ts#L64）。配套测试 bundled-defaults.test.ts#L35-L59 还会校验BUNDLED_COMMANDS必须包含.archon/commands/defaults/下的每一个.md文件，防止命令目录与打包产物漂移。

2. 使命与整体数据流

命令正文开头（Mission 一节）只有一句话，但定义了整条命令的职责边界：

Read the code review findings artifact and post a formatted summary as a comment on the PR. （读取代码审查结论工件，并将其格式化为一条 PR 评论发布。）

它是一条“读工件 → 格式化 → 写 GitHub”的单向管道，不修改任何仓库文件，也不做新的审查判断。整体数据流如下：

上游节点(如 archon-code-review-agent) │ 写入 $ARTIFACTS_DIR/review/code-review-findings.md ▼ archon-post-review-to-pr Phase 1 LOAD 读 .pr-number + code-review-findings.md Phase 2 FORMAT 构建 GitHub 评论正文 Phase 3 POST gh pr comment + 校验 Phase 4 OUTPUT 向用户报告 │ ▼ GitHub PR 上出现一条 "🔍 Code Review" 评论

官方文档 how-it-works.md 中的步骤表也把该命令登记为“Post review”环节：读取review-findings工件并作为评论发布到 PR。理解了这条链路后，下面按原文档的四个阶段逐一展开。

3. Phase 1: LOAD —— 从工件目录装载上下文

3.1 读取 PR 编号

PR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)

.pr-number是一个约定俗成的“PR 注册文件”，由工作流早期的 bash 节点写入。可以举一个本仓库内的真实例证：maintainer-review-pr.yaml 的fetch-pr节点在拉取 PR 元数据前，先执行echo "$PR_NUM" > "$ARTIFACTS_DIR/.pr-number"（第 59 行），把从用户消息中解析出的 PR 编号固化到工件目录；后续所有节点（包括post-review节点，见 第 179-189 行）都通过cat "$ARTIFACTS_DIR/.pr-number"取回它。这种“先落盘、后消费”的写法让节点之间无需共享内存——每个节点都可以context: fresh冷启动。

命令对缺失情况给出了明确的失败文案：

❌ No PR number found at $ARTIFACTS_DIR/.pr-number Cannot post review without a PR number.

3.2 读取审查结论

cat $ARTIFACTS_DIR/review/code-review-findings.md

该工件的产出方是同目录下的兄弟命令archon-code-review-agent，其 frontmatter 声明的 Output artifact 正是$ARTIFACTS_DIR/review/code-review-findings.md（见 bundled-defaults.generated.ts#L47）。因此“先审查、后发布”的前置依赖被显式化为文件依赖：文件不存在时，命令要求立即报错并提示“Run code review first.”：

❌ No review findings found at $ARTIFACTS_DIR/review/code-review-findings.md Run code review first.

3.3 阶段检查点（PHASE_1_CHECKPOINT）

- [ ] PR number loaded - [ ] Review findings loaded

每个阶段末尾的 checkpoint 清单是这条命令的通用范式：把模糊的自然语言指令拆成可勾选的完成判据，让 Agent 在阶段边界自我核对，也便于人工审计运行记录。

3.4 源码层面：$ARTIFACTS_DIR从何而来

$ARTIFACTS_DIR不是命令自己创建的路径，而是执行引擎注入的环境变量。在 exec-environment.ts#L15-L36 的buildExecNodeEnvironment中可以看到，引擎为每个执行类节点统一注入ARTIFACTS_DIR、STATE_DIR、LOG_DIR、WORKFLOW_ID、BASE_BRANCH、ARGUMENTS等变量；同时$ARTIFACTS_DIR还会被直接替换（substitute）进脚本/提示词正文——dag-executor.ts#L266 的注释明确了这一替换语义，而 dag-executor.test.ts 中有专门测试验证“executeBashNode injects ARTIFACTS_DIR into the script's environment”，并覆盖了对含非 ASCII 字符（如日本語）的工件子目录的健壮性。

关于工件目录的物理位置，authoring-commands.md 说明工件存放在仓库之外的 Archon 工作区目录：

~/.archon/workspaces/owner/repo/artifacts/runs/{workflow-id}/

这一设计保证工件不会污染 git 工作树，也让.pr-number这类运行级状态天然与具体 workflow run 一一对应。

4. Phase 2: FORMAT —— 构建 GitHub 友好的评论正文

4.1 从结论工件中提取四类信息

命令要求从 review findings 中提取：

• Verdict（裁决）：APPROVE/REQUEST_CHANGES/NEEDS_DISCUSSION三选一；
• Summary：2–3 句概述；
• Findings：全部发现项，含严重级别与位置；
• Statistics：按严重级别统计的发现项数量。

4.2 评论正文模板（完整继承）

这是本命令最具复用价值的部分——一份可直接套用的 GitHub PR 评论模板：

## 🔍 Code Review **Verdict**: {APPROVE ✅ | REQUEST_CHANGES ❌ | NEEDS_DISCUSSION 💬} {Summary from findings} --- ### Findings {For each finding:} #### {severity emoji} {title} **Severity**: {CRITICAL|HIGH|MEDIUM|LOW} · **Category**: {category} · **Location**: `{file}:{line}` {Issue description} <details> <summary>Suggested Fix</summary> ```typescript {recommended fix code}

Why: {reasoning}

{End of findings}

Summary

{If positive observations exist:}

What's Done Well

{Positive observations from review}

Automated code review

模板中几个值得注意的 GitHub 渲染细节： 1. **`<details>/<summary>` 折叠建议修复**：每个发现项的修复代码块被包进折叠区。PR 评论默认视图因此保持紧凑——评审者先看到结论与位置，再按需展开修复方案； 2. **位置用 `` `{file}:{line}` `` 反引号标注**：与 GitHub 的代码定位习惯对齐，便于评审者跳转； 3. **严重级别统计用 Markdown 表格**：四种级别各占一行，数量一目了然； 4. **结尾固定落款 `*Automated code review*`**：明确该评论来自自动化流程，避免与人工评审混淆； 5. **“What's Done Well” 为条件段落**：仅当审查结论中存在正面观察时才输出，避免模板僵化。 ### 4.3 严重级别与 emoji 映射 | 严重级别 | Emoji | |----------|-------| | CRITICAL | 🔴 | | HIGH | 🟠 | | MEDIUM | 🟡 | | LOW | 🔵 | Verdict 也有固定表情约定：APPROVE ✅、REQUEST_CHANGES ❌、NEEDS_DISCUSSION 💬。这类“词汇表”在提示词中显式枚举，是约束 LLM 输出稳定性的常用手段——Agent 不需要自行发明格式，只需做槽位填充。 ### 4.4 PHASE_2_CHECKPOINT

• Comment body formatted
• All findings included
• Statistics table present

其中“**All findings included**”一条尤其关键：它把“不能漏项”写成可检查的完成条件，防止 Agent 在长列表中截断输出。 ## 5. Phase 3: POST —— 用 `gh` CLI 发布并校验 ### 5.1 发布评论 ```bash gh pr comment {PR_NUMBER} --body "$(cat <<'EOF' {formatted comment body} EOF )"

这里使用带引号的 heredoc（<<'EOF'）把正文原样传入--body，避免正文中的$、反引号等字符被 shell 提前展开——对包含代码片段的评论正文这一点是必要的。

5.2 存在性校验

# Check the comment was posted gh pr view {PR_NUMBER} --comments --json comments --jq '.comments | length'

发布后立即回读评论数量，把“发出去了”从主观声称变成可验证事实。本仓库的并行实现 maintainer-review-pr.yaml#L179-L189 的post-reviewbash 节点采用了同一模式的另一变体：把评论正文先落成$ARTIFACTS_DIR/review/review-comment.md，再执行gh pr comment "$PR_NUM" --body-file "$ARTIFACTS_DIR/review/review-comment.md"，并在文件缺失时exit 1让节点显式失败。两条实现殊途同归：评论落盘/构建与发布解耦，发布前有输入完整性检查。

5.3 PHASE_3_CHECKPOINT

- [ ] Comment posted to PR - [ ] Verified comment exists

6. Phase 4: OUTPUT —— 向用户报告结果

命令最后要求以固定格式向用户汇报：

## Review Posted to PR **PR**: #{PR_NUMBER} **Verdict**: {verdict} **Findings**: {total count} ({critical} critical, {high} high, {medium} medium, {low} low) Review comment has been posted to the pull request.

该报告只陈述已验证的事实（PR 号、裁决、分级计数），不做额外发挥。对于“输出会被转发/展示”的命令，这种收敛的输出契约能显著降低噪声。

7. 错误处理与成功判据

原文档为三类典型异常各给了处置策略，这套“分支化错误处理”是命令模板可独立运行的关键：

第三行值得单独强调：它处理了“零发现”这一边界条件。若无此分支，Agent 面对空结论时行为不可预测——可能报错、可能沉默、可能编造发现。把边界条件写进模板，是让流程“deterministic and repeatable”（这正是 Archon 项目的自我定位）的基本功。

命令末尾还给出三个成功判据（Success Criteria），与四个阶段的 checkpoint 一一对应，可作为自动化验收断言：

• FINDINGS_LOADED：review 工件读取成功；
• COMMENT_FORMATTED：包含全部发现项的评论正文已构建；
• COMMENT_POSTED：评论在 PR 上可见。

8. 从这条命令能学到的编写范式

把 archon-post-review-to-pr.md 放回 Archon 的完整命令族（同目录还有 archon-code-review-agent.md、archon-synthesize-review.md、archon-workflow-summary.md 等 36 个默认命令）中观察，可以提炼出四条可迁移到自研命令的写法：

1. 工件是唯一交接协议。节点间不共享上下文，只共享$ARTIFACTS_DIR下的文件；输入文件名（.pr-number、review/code-review-findings.md）在命令中显式写明，并与上游命令声明的 Output artifact 精确对齐。引擎侧的变量注入见 exec-environment.ts，工件目录约定见 authoring-commands.md；
2. 每个阶段都有 CHECKPOINT 清单。把“做到什么算做完”写成勾选项，行为约束从散文变成核对表；
3. 失败路径与成功路径同等详细。缺失文件、认证失败、空结论都预置了动作序列，且错误信息自带排查线索（“Run code review first.”）；
4. 输出契约固定。评论模板与最终报告模板都是带槽位的定式，Agent 的职责是填充而非创作，这保证了同一输入产生结构一致的结果。

9. 小结

archon-post-review-to-pr是 Archon 内置命令包中“审查结果投递”环节的代表：它以零参数、纯工件驱动的方式，把上游 Agent 产出的code-review-findings.md转换成结构统一、可折叠、带统计表的 GitHub PR 评论，并通过ghCLI 发布与回读校验形成闭环。对使用者而言，读懂这条命令意味着掌握了 Archon 命令体系的完整解剖样本——frontmatter 元数据、阶段化提示词、工件约定、检查点与错误分支如何协同，使 AI 编码流程中的“审查反馈”这一步变得可预期、可审计、可复现。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon