OpenHuman 基于 LLM Agent 的自动化 PR 修复工作流：fix.md 提示词模板深度解析-平芜编程栈

OpenHuman 基于 LLM Agent 的自动化 PR 修复工作流：fix.md 提示词模板深度解析

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

导读

本文以 OpenHuman 仓库中 scripts/shortcuts/review/prompts/fix.md 为技术主体，剖析该项目如何用一份"评审 + 修复 + 提交 + 推送"四合一提示词模板，驱动 Claude / Codex / Cursor 等 LLM Agent 完整收尾一个 GitHub PR。文章将带你逐阶段拆解这条工作流的分工设计、占位符注入机制、冲突处理策略、提交规范与安全护栏，并结合仓库内 fix.sh、lib.sh、sync.sh 等真实脚本，理解其"Agent 无关"的实现原理。读完你既能直接复用这套工作流，也能学会如何为自家仓库设计类似的高质量 Agent Prompt。

一、从一对提示词模板说起：review 与 fix 的分工

OpenHuman 的 PR 协作体系围绕scripts/shortcuts/review/目录展开，核心是两份语义互补的 Agent Prompt：

prompts/review.md：只评审不动手。要求 Agent 产出 CodeRabbit 风格评审（walkthrough、变更汇总表、逐文件分析、可执行的内联评论），通过gh pr review发布结论，并视阻塞项决定 approve 或 request changes，明确禁止修改代码。
prompts/fix.md：评审并直接修复。在完成同类评审后，要求 Agent 将每个可执行的评审意见直接落到工作树，跑完质量套件，分主题提交，并推送回 PR 的 head 分支。

两者共用一个核心判断：Agent 的任务是"完成 PR"，而不是"汇报 PR"。fix.md 开篇就用一句话划定了红线——"A response that only lists what should be done is a failure mode"（只罗列"应该做什么"的回复属于失败模式）。这条定位决定了后续所有步骤都是面向结果的执行指令，而非建议清单。

与两份提示词对应的入口脚本分别是 review.sh 与 fix.sh，它们通过 cli.sh 统一暴露为pnpm review <command>子命令。

二、工作流全景：pnpm review 命令体系

scripts/shortcuts/review/README.md 给出了五个子命令的整体视图，其中fix正是本文主角：

命令	脚本	职责
`sync`	sync.sh	拉取 PR head 为本地分支`pr/<num>`，合并`main`，配置 upstream 与 pushRemote
`review`	review.sh	sync +`pr-reviewer`Agent 评审、评论、approve
`fix`	fix.sh	sync + Agent 应用修复 +`pr-manager-lite`提交并推送
`coverage`	coverage.sh	sync + 收集覆盖率 CI 上下文 + 修复覆盖率问题并盯守 CI
`merge`	merge.sh	LLM 汇总 squash 提交正文 + 过滤 Co-authored-by +`gh pr merge`

典型用法（摘自 README）：

pnpm review sync 123 pnpm review review 123 pnpm review fix 123 pnpm review coverage 123 pnpm review merge 123 # --squash pnpm review merge 123 --rebase pnpm review --help

fix与review/coverage共享两个可调参数：--agent <tool>选择驱动 Agent 的 CLI（默认claude），末尾可追加一段<extra-prompt>逐字拼接到 Agent 提示词末尾，例如pnpm review fix 123 "focus on the retry logic"（聚焦重试逻辑）。

三、提示词注入机制：占位符如何变成真实上下文

fix.md 不是一份写死的静态文本，其中包含__PR__、__REPO__、__HEAD_REPO__、__HEAD_BRANCH__、__CONFLICT_BLOCK__五类占位符。填充逻辑位于 fix.sh：

prompt=$(REVIEW_CONFLICT_BLOCK="$conflict_block" \ awk -v pr="$REVIEW_PR" -v repo="$REVIEW_REPO_RESOLVED" \ -v head_repo="$REVIEW_HEAD_REPO" -v head_branch="$REVIEW_HEAD_BRANCH" ' BEGIN { conflict = ENVIRON["REVIEW_CONFLICT_BLOCK"] } { gsub(/__PR__/, pr); gsub(/__REPO__/, repo); gsub(/__HEAD_REPO__/, head_repo); gsub(/__HEAD_BRANCH__/, head_branch); gsub(/__CONFLICT_BLOCK__/, conflict); print } ' "$template")

这些变量的来源是 lib.sh 中的sync_pr()函数，它在脚本侧完成一次标准的 PR 同步：

同步main（git pull origin main、git fetch upstream、git merge upstream/main、git submodule update --init --recursive）；
用gh pr view <pr> -R <repo> --json headRefName,headRepository,headRepositoryOwner解析 PR 的 head 仓库与分支；
将 PR head 抓取为本地分支pr/<num>并 checkout；
执行git merge --no-edit main，冲突不中止流程，而是收集冲突文件列表（git diff --name-only --diff-filter=U）置入REVIEW_CONFLICT_FILES；
复用或新建指向贡献者 fork 的 remote（remote-<pr>），设置branch.pr/<num>.pushRemote与branch.pr/<num>.merge；
导出REVIEW_PR、REVIEW_REPO_RESOLVED、REVIEW_HEAD_REPO、REVIEW_HEAD_BRANCH、REVIEW_PUSH_REMOTE、REVIEW_HAS_CONFLICTS等环境变量供 fix.sh 拼装提示词。

仓库解析遵循REVIEW_REPO=owner/name覆盖 →upstreamremote →origin的优先级（lib.sh）。这套"脚本做重活、Agent 做判断"的设计，让提示词模板保持简洁，同时确保 Agent 拿到的上下文与本地 git 状态完全一致。

四、冲突优先：合并冲突的强制前置处理

sync_pr在合并main时不因冲突而中止（git merge --no-edit main失败后继续），因此 fix.sh 会依据REVIEW_HAS_CONFLICTS是否为1生成__CONFLICT_BLOCK__注入提示词（fix.sh）：

⚠️ Merge conflicts to resolve FIRST
When the PR branch was merged with currentmain, the following files were left with unresolved conflict markers...

冲突块对 Agent 下达了四条硬性指令：

逐个通读冲突文件，理解双方意图（结合周边代码、main上的近期提交与 PR 意图），而不是机械选择一边；
通过"正确组合两边内容"来消解冲突，明确禁止--ours/--theirs一刀切策略，也禁止git rebase --skip；
git add已解决文件，以清晰的合并提交收尾（git commit --no-edit，冲突解决的合并信息已 staged）；
对解决后的文件重新跑格式化 / 类型检查 / 测试，确认无回归。

只有冲突干净解决后，才允许进入后续的评审-修复流程。与 review-only 的 review.md 相比，两者对冲突的处理取向截然不同：review 模式只要求 Agent 在 walkthrough 中把冲突作为 blocker 标出并 request changes，而 fix 模式要求 Agent 亲自解决。这种差异正是两份提示词"评审 vs 执行"定位的缩影。

五、十阶段执行流程逐层拆解

fix.md 将 Agent 的执行过程组织为 0～9 十个阶段，下面按原文骨架逐层展开，并结合仓库证据说明每步的设计意图。

阶段 0：工作区卫生检查（Sanity check）

git status --short # should be empty or only your own staged work git branch --show-current # should be pr/__PR__ git rev-parse --abbrev-ref @{u} # upstream must be set git log --oneline -5

四条命令分别验证工作树干净、当前分支正确、upstream 已配置、近期提交可追溯。规则强调：若工作树出现预期外的脏状态，停下来询问，绝不 stash 或丢弃。这是整条工作流的安全基座——Agent 被授权"推送到贡献者 fork"，因此开局校验比常规流程更严格。

阶段 1：抓取 PR 元数据与存量评审意见

fix.md 要求 Agent 先掌握完整的 PR 上下文，核心命令：

gh pr view __PR__ -R __REPO__ --json number,title,headRefName,headRepositoryOwner,headRepository,baseRefName,isCrossRepository,state,author,url,body,mergeable,statusCheckRollup gh pr diff __PR__ -R __REPO__ # 顶层评审（CodeRabbit 摘要、维护者总评） gh pr view __PR__ -R __REPO__ --json reviews --jq '.reviews[] | {author: .author.login, state: .state, body: .body, submittedAt: .submittedAt}' # 内联代码评审意见 gh api repos/__REPO__/pulls/__PR__/comments --paginate # 通用对话评论 gh api repos/__REPO__/issues/__PR__/comments --paginate

关键动作：确认 PR 处于open状态，对 closed/merged 的 PR 中止（除非用户明确要求）。同时校验跨仓库 fork 场景——如果本地pr/__PR__被推到自己的origin而非贡献者 fork，推送只会更新你的副本、不会更新真实 PR，必须在最终报告中明确标注。

阶段 2：全文阅读每个改动文件

"对于 diff 中的每个文件，读取整个文件（而非仅 diff hunk）。上下文很重要。"新增文件要读同级兄弟文件以掌握本地约定；移动/重命名文件要同时检查新旧两个路径。fix.md 明确警告：跳过这一步会产生肤浅的修复（shallow fixes）。

阶段 3：CodeRabbit 风格评审 + 意见分类

fix.md 给出了四个评审轴，其中"项目标准"直接引用仓库根目录的 CLAUDE.md 约定，例如：

新 Rust 功能放在src/openhuman/<domain>/子目录，而非根级.rs文件；
领域能力通过schemas.rs+ registry 暴露，禁止在src/core/cli.rs/src/core/jsonrpc.rs里硬编码分支；
生产环境app/src代码禁止动态import()；
前端VITE_*环境变量统一经app/src/utils/config.ts读取；
app/src-tauri仅限桌面端；
事件总线必须走publish_global/subscribe_global/register_native_global/request_native_global，禁止直接构造EventBus/NativeRegistry；
CEF webview 不得新增 JS 注入；
新流程要有调试日志（入口/出口、分支、重试），使用可 grep 的前缀，不得记录密钥/PII；
单文件尽量不超过约 500 行；
能力变更需同步更新src/openhuman/platform/about_app/。

这些标准在 CLAUDE.md 中有更完整的表述（如schemas.rs承载 controller 模式与handle_*函数、RPC 面定义等），fix.md 相当于把最常被评审命中的条目提炼成 Agent 的内置检查清单。

其余三个轴为：

正确性：逻辑 bug、off-by-one、null/undefined、async/await 误用、竞态、错误传播（Result<T>/RpcOutcome<T>）；
测试：新行为必须带测试，改动行覆盖率门槛 ≥ 80%；
安全：凭据、命令注入、SQL 注入、路径穿越、XSS。

每条既有评论与新增发现被归入五类：

actionable-trivial（笔误、重命名、格式化、缺失 import）→ 直接修复；
actionable-non-trivial（逻辑/架构/测试缺口）→ 方向明确则修复，否则延后；
already-addressed（当前代码已满足）→ 记录即可；
stale-outdated（不再适用）→ 记录即可；
disagree/defer-human/question→ 进入最终报告，并通过gh api回帖到 PR，绝不静默忽略。

阶段 4：应用修复与提交纪律（REQUIRED）

执行原则：应用所有actionable-trivial与方向明确的actionable-non-trivial修复；每次编辑前重读周边代码（评审意见写出后代码状态可能已漂移，尤其是 CodeRabbit 的 suggestion 块）。

提交规范要求"一个逻辑关注点一个 commit"：

fix(<area>): <what changed> (addresses @<reviewer> on <file>:<line>) refactor(<area>): <what changed> test(<area>): <what added> docs(<area>): <what changed> chore(pr-fix): apply formatting chore(pr-fix): lint autofix

未应用的项需记录原因并进入最终报告；同时明确"不要扩大范围"（Don't expand scope）。

阶段 5：运行质量套件（Quality suite）

fix.md 按改动范围给出了可并行执行的命令矩阵：

# 前端（若 app/ 有改动） cd app && pnpm compile cd app && pnpm lint cd app && pnpm format # auto-fix cd app && pnpm test:unit # Rust（若 src/ 或 app/src-tauri 有改动） cargo fmt --manifest-path Cargo.toml cargo check --manifest-path Cargo.toml cargo check --manifest-path app/src-tauri/Cargo.toml cargo test --manifest-path Cargo.toml

规则：与 diff 无关的套件可以跳过，但代码有改动时格式化与类型检查/ lint必须跑。测试疑似 flake 时允许重跑一次，仍失败则停下来报告，而不是死循环。这与 CLAUDE.md 中的双轨 CI 模型（CI Lite 按改动区域做限定检查 + ≥ 80% diff 覆盖率门槛）相互印证：Agent 在本地先跑一遍收敛套件，再依赖 CI 做全量兜底。

阶段 6 与 7：自动修复提交与推送（REQUIRED）

pnpm format/cargo fmt的改动 →chore(pr-fix): apply formatting；
非平凡的 lint 自动修复 →chore(pr-fix): lint autofix；
推送前git status --short必须为空；
除非 pre-push 钩子因与你无关的既有破坏而失败，否则禁用--no-verify（确需使用时必须在最终报告注明）；
绝不 amend 已发布提交，未经用户明确批准绝不 force-push。

推送的关键设计是 pushRemote 指向贡献者 fork（由 sync 阶段配置），因此 fix.md 反复强调：

git status --short # must be empty git push # pushes to the contributor's fork (__HEAD_REPO__:__HEAD_BRANCH__) — updates the PR

pushRemote已配置到贡献者 fork，git push直接更新真实 PR，不要推origin，也不要发明其他 remote。两条降级路径被明确禁止或约束：被拒绝（非 fast-forward，即你工作时贡献者又推了新提交）时用git pull --rebase后重推，绝不 force-push；推送遇到权限错误（无 fork 写权限）时停止，不得回退到origin，而是报告让用户获取权限或让贡献者自行拉取。

阶段 8：将延后/异议/疑问项回帖到 PR

所有disagree/defer-human/question项通过gh api发布为内联评审评论，确保不丢失在对话里：

gh api -X POST repos/__REPO__/pulls/__PR__/comments \ -f body="<your reply>" \ -f commit_id="$(gh pr view __PR__ -R __REPO__ --json headRefOid --jq .headRefOid)" \ -f path="<file path>" \ -F line=<line number> \ -f side=RIGHT

commit_id取自 head 提交 SHA，side=RIGHT表示评论挂在 diff 的新侧行上，这与 review.md 阶段 5 的内联评论发布方式完全一致，保证评审与修复两套流程产出的评论格式互通。

阶段 9：面向用户的最终报告

fix.md 提供了结构化的 Markdown 报告模板，包含：前置条件核验（工作树干净、分支/upstream、跨仓库 fork 状态与推送目标）、已处理评审意见清单（@reviewer on file:line - 一句话 -> fixed / already addressed / deferred / disagree）、新增发现清单（severity + file:line + 处理方式）、项目标准 pass/warn/fail 明细、检查结果表（typecheck/lint/format/unit/cargo check/cargo test）、已推送提交 SHA 列表、遗留人工事项以及 PR 链接。这份模板把 Agent 的全部行为收敛为可审计的产出，方便维护者快速复核。

六、安全护栏（Guardrails）

fix.md 末尾以 6 条护栏收束整个流程，构成工作流的安全边界：

绝不未经明确批准推main、force-push、跳过钩子、amend 已发布提交、执行破坏性 git 命令；
绝不提交密钥（.env、*.key、凭据）；
工作树开局出现预期外脏状态 →停止，不 stash；
测试 flake → 重跑一次；仍失败 → 报告而非循环；
始终停留在 PR 分支，绝不误提交到main；
保持评审诚实——PR 干净就明说，不要用编造的问题凑数。

其中"绝不提交密钥"在 CLAUDE.md 中同样被列为硬约束，且 fix.md 阶段 3 的 Security 轴（凭据、命令注入、SQL 注入、路径穿越、XSS）正是对这条护栏的评审前置化。

七、Agent 无关性与无头运行模式

fix.sh 将提示词模板完整内联交给所选 Agent（fix.sh 注释说明："The prompt is loaded from prompts/fix.md so the workflow is agent-agnostic (no reliance on Claude Code's named subagent registry)"）。这意味着工作流不依赖任何特定 Agent 的命名子代理机制，任何能接受-p "<prompt>"并输出到 stdout 的 CLI 都可驱动。

真正的执行差异收敛在 lib.sh 的agent_exec()：为了让无头/后台/CI 场景不被逐工具权限询问卡死，不同 Agent 以各自的"yolo 模式"启动：

case "$agent" in claude) exec claude --dangerously-skip-permissions "$prompt" ;; codex) exec codex --dangerously-bypass-approvals-and-sandbox "$prompt" ;; cursor|cursor-agent) exec cursor-agent --yolo "$prompt" ;; *) exec "$agent" "$prompt" ;; esac

同时提供逃生阀：设置REVIEW_AGENT_SAFE=1时改为裸调用（保留权限询问），适合交互式本地运行、希望逐步审查每个动作的场景。README 中的说明与这段实现一致：review/fix/coverage子命令默认驱动 Agent 为claude。

八、从 fix.md 到可复用的 Agent 工作流设计要点

复盘这份提示词，可以提炼出几条对设计同类工作流有直接借鉴价值的模式：

脚本负责确定性、Agent 负责判断：分支同步、占位符注入、remote 配置全部在 Bash 侧完成，提示词只描述"做什么、按什么标准判断"，避免提示词承担易错的 git 机械操作。
状态前置注入，而非让 Agent 自行推导：PR 号、仓库、head 分支、冲突文件列表在启动前就拼进提示词，Agent 无需猜测也不易跑偏。
明确成功判据与失败模式："finish the PR, not to report on it" 定义了行为边界；"never stash"、"never force-push"、"stop and report" 定义了异常时的收敛动作，而不是放任 Agent 自由发挥。
产出可审计：九阶段报告模板 + 分主题提交 + 内联评论回帖，让一次全自动修复全程可追溯、可人工复核。
诚实原则贯穿始终：不编造问题、已解决的如实标注、PR 干净就大方承认——这既是提示词要求，也是 review.md 与 CLAUDE.md 共同强调的 Agent 行为基线。

结语

fix.md 是 OpenHuman 将"人工 PR 收尾"压缩为"一条 Agent 指令"的典型样本：它继承 CodeRabbit 风格的评审方法论，叠加仓库级项目标准与质量门槛，再辅以 fix.sh / sync.sh / lib.sh 的脚本编排与安全护栏，最终形成一套可重复、可审计、Agent 无关的自动修复闭环。对于希望用 LLM 提效 PR 维护的团队，这份提示词模板及其配套脚本本身就是一份可直接借鉴的工程范本。