企业官网建设流程全解析

ZeroClaw GitHub PR 技能实战：从模板驱动的 PR 创建到智能更新与作者卫生检查

【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 🦀项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw

本篇技术指南围绕 ZeroClaw 仓库中的github-pr技能（.claude/skills/github-pr/SKILL.md）展开，系统讲解如何用一条自然语言指令完成"创建新 PR"与"更新既有 PR"两类任务：包括以.github/pull_request_template.md为唯一事实来源的模板解析与预填、基于变更面的验证证据收集（cargo fmt/cargo clippy/cargo test/ 文档链接门禁）、以及禁止机器人署名（bot/AI attribution）的作者卫生检查。读完本文，你将掌握 ZeroClaw 中一套可复现的 PR 自动化工作流，并理解其与仓库内 CI 门禁、路径/大小标签自动机、评审会话与 squash-merge 技能如何协同构成从分支到合入的完整闭环。

技能定位与触发场景

github-pr技能是 ZeroClaw 为 AI 助手编写的 Agent 技能（skill），核心职责只有两件事：创建带着完整模板正文的 PR，以及更新既有 PR 的标题、正文章节、标签与评论。技能的触发非常宽泛——用户说"submit this for review"、"push and open for merge"，甚至没有明确出现 "PR" 字样时，只要意图是提交变更供评审，都应命中本技能；而当用户说出 "open a new PR" 这类明确创建意图时，则进入创建模式。

从源码结构看，该技能与同目录下的 github-issue、github-issue-triage、github-pr-review-session、squash-merge 共同构成 ZeroClaw 的 GitHub 协作技能族。其中 squash-merge 技能中有一张完整的端到端协作链路表，明确标注了各技能的分工边界：选单/分诊用github-issue-triage，建 issue 用github-issue，分支就绪后开 PR / 更新 PR 用github-pr，合入前评审用github-pr-review-session，最后落地 master 用 squash-merge。这说明github-pr是整条流水线中"提交"环节的标准入口。

双模式识别：Open 与 Update

技能支持两种模式，模式判定完全依赖上下文：

• Open（创建）：当前分支没有已打开的 PR，或用户明确要求新建。
• Update（更新）：当前分支已存在打开的 PR，且用户没有说 "open a new PR"，此时默认进入更新模式。

这一设计避免了重复建 PR 的常见事故：只要分支上已有 PR，助手应当"接力"而不是"另起炉灶"。

共享步骤一：PR 模板是唯一事实来源

无论创建还是更新，技能的第一步永远是读取并解析.github/pull_request_template.md，绝不硬编码章节名、字段或顺序——因为模板会随时间演进，技能必须始终反映其当前状态。解析时需提取四类信息：

1. ##顶级章节标题（PR 正文的一级结构）；
2. 每个章节内的要点、字段与提示语；
3. 哪些章节标记为(required)（必填）vs 可选/推荐；
4. 内联格式约定（反引号选项、Yes/No 字段等）。

对照仓库中的 .github/pull_request_template.md，ZeroClaw 的 PR 模板由以下必填/条件章节构成，这正是技能需要解析并逐节填充的对象：

模板末尾还有两条贯穿全文的硬约束：Labels 只存在于 GitHub 标签 UI，不写在正文里（路径标签由.github/labeler.yml驱动的 PR path labeler 负责，size:*标签由 PR size labeler 负责）；以及禁止在 PR 正文或提交信息尾部添加 bot/AI 署名页脚，人工 co-author trailer 仅在"取代（supersede）他人贡献"场景下按隐私契约允许。

共享步骤二：作者卫生检查（Authorship Hygiene）

ZeroClaw 的 PR 正文与最终合入的提交信息尾部不得包含任何 bot/AI 署名，例如Co-authored-by: Claude <...>、Co-authored-by: Codex <...>，或Created with Claude Code/Generated with Claude Code这类生成工具页脚。技能在开 PR 前必须扫描本地提交信息与草拟的 PR 正文：

git log origin/master..HEAD --format=%B | rg -i '(^[[:space:]]*(Co-authored-by|Co-Authored-By):.*(Claude|Codex|ChatGPT|Copilot|GitHub Copilot|Gemini|\[bot\]|dependabot|github-actions|web-flow|blacksmith|noreply@(anthropic|openai)\.com)|^[[:space:]]*(Created with Claude Code|Generated with Claude Code)[[:space:]]*$)'

若命中，则从展示或提交的 PR 文本中移除这些 trailer 与页脚。这里有一条重要的边界：如果尚未推送的本地提交包含这些页脚，必须先告知用户并征得同意，才能重写提交历史；绝不允许仅为清理署名而擅自改写已推送分支或贡献者分支。这条卫生检查会同时约束"创建 PR"和"更新 PR"两个模式，与模板末尾的禁令、squash-merge 技能中合入前对$COMMITS的清洗逻辑构成三处一致的防线。

模式一：创建新 PR 的完整流程

Step 1：收集上下文

并行执行以下命令，为预填 PR 正文收集证据：

# 分支与提交上下文 git branch --show-current git log master..HEAD --oneline git diff master...HEAD --stat # 检查分支是否已推送 git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null # 环境信息（用于验证证据） rustc --version 2>/dev/null

同时审阅变更文件与提交信息，判断变更性质（bug fix / feature / refactor / docs / chore）以及受影响的子系统。这一判断将决定后续如何填写 Summary、Security 与 Compatibility 章节。

Step 1a：收集验证证据（起草前必做）

起草 PR 正文之前，必须确定覆盖变更面的证据。原则是：

• 新鲜的必要 CI 即可作为有效证据：只要它运行在当前 head 上、覆盖相同的目标、功能集与行为边界，就不必为了重复覆盖而再跑一遍本地 Cargo；
• 只为真实缺口补充本地检查：例如只做过编译检查的平台、lint 任务覆盖不到的路径、未触发的桌面端覆盖、PR 矩阵之外的发布目标，或 CI 过期/不可用的情况。

Rust/代码变更的常用本地验证命令：

cargo fmt --all -- --check cargo clippy --all-targets -- -D warnings cargo test

纯文档变更：运行scripts/ci/docs_quality_gate.sh与scripts/ci/docs_links_gate.sh（这两个门禁脚本均存在于仓库的 scripts/ci 目录，docs_links_gate 负责校验文档内部链接完整性）；改动引导类脚本：追加bash -n install.sh做语法检查（仓库根目录的 install.sh 即为此类目标）。

证据记录要求：写明依赖了哪些必要 CI 及其覆盖原因、已知缺口；本地跑过的命令要粘贴相关输出尾段、失败与警告；若某条命令故意跳过（如平台受限），必须用一行理由显式注明，"Skipped" 而不解释是不可接受的。验证输出若出现任何WARN/ERROR/warning:行，必须以评审者视角追查：确认是 master 上已存在的根因，或标记为开 PR 前必须处理的问题——不允许带着自己无法解释的警告去发 PR。若必要检查或本地命令失败，应先修复再起草，绝不在破损的树（broken tree）上写 PR。

Step 2：预填模板

基于解析出的模板结构 + 收集到的上下文，起草完整 PR 正文：

• 为模板中每个##章节依据提交、diff 与变更文件填写 bullet 与字段；
• 用字段描述与占位文本作为填写指引；
• 对 Yes/No 字段从 diff 推断（例如没有改动src/security/下的文件，安全影响大概率全为 No）；
• 必填章节必须给出实质性回答；可选章节若有足够上下文则填，否则保留模板提示语；
• 按 Conventional Commits 风格起草 PR 标题，例如feat(provider): add retry budget override、fix(channel): handle disconnect gracefully、chore(ci): update workflow targets；
• 展示或提交前应用共享的作者卫生检查。

值得一提的是，How I tested的填写必须诚实：只写实际运行过的检查，贴上真实输出尾段，说明覆盖范围与剩余缺口或跳过的理由。不要把 pending 状态的 CI 当作证据，也不要把没跑过的本地命令描述成通过。

关于标题格式，仓库有硬性 CI 门禁支撑：.github/workflows/pr-title.yml会在 PR opened/reopened/edited/synchronize 时调用 scripts/check-pr-title.sh，其校验正则要求type(scope): description且 type 限定为build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test之一、scope 必填。因此技能草拟的标题若不符合该格式，即使助手放行，CI 也会拒绝——预填时按此规范生成标题是从源头规避返工。

Step 3：展示草稿供评审

向用户完整展示草稿，格式固定为：

## PR Draft: <title> **Branch**: <head> -> master **Labels**: <suggested labels> <full body with all sections filled>

并请用户确认："Here's the pre-filled PR. Review and let me know what to change, or say 'submit' to open it." 之后迭代修改直到用户批准。

Step 4：推送并创建

1. 若分支尚未推送，先推分支并设置上游跟踪：

   git push -u origin <branch>

2. 用 HEREDOC 承载正文创建 PR（避免引号与特殊字符转义问题）：

   gh pr create --title "<title>" --base master --body "$(cat <<'PR_BODY_EOF' <full body> PR_BODY_EOF )"

3. 若已商定标签，添加标签：

   gh pr edit <number> --add-label "<label1>,<label2>"

4. 将 PR URL 返回给用户。

注意 base 固定为master，这与模板中 "Base branch:master(all contributions)" 的约定一致，也符合仓库所有 PR 工作流均以 master 为目标分支的事实（参见.github/workflows/master-branch-flow.md）。

模式二：更新既有 PR 的完整流程

Step 1：识别目标 PR

优先级依次为：用户显式给出 PR 编号/URL → 当前分支自动检测：

gh pr view --json number,title,body,labels,state,author,url,headRefName 2>/dev/null

→ 都失败则询问用户 PR 编号。识别后必须校验作者身份：

CURRENT_USER=$(gh api user --jq '.login') PR_AUTHOR=$(gh pr view <number> --json author --jq '.author.login')

若当前用户不是 PR 作者，立即停止并告知用户——这从机制上防止了越权修改他人 PR。

Step 2：拉取当前状态

gh pr view <number> --json number,title,body,labels,state,baseRefName,headRefName,url,author,reviewDecision,statusCheckRollup,commits

并展示摘要：

## PR #<number>: <title> **State**: <open/closed/merged> **Branch**: <head> -> <base> **Labels**: <label list> **Checks**: <pass/fail/pending> **URL**: <url>

Step 3：确定要更新的内容

技能支持七类更新操作，全部基于gh pr edit与gh pr comment：

Step 4：处理正文章节编辑

编辑指定章节时遵循最小改动原则：

1. 按##头把当前 PR 正文解析为章节；
2. 将用户请求与模板中对应章节匹配；
3. 展示该章节的当前内容与拟替换内容（diff 对比）；
4. 确认后只修改该章节，重建完整正文并提交。

Step 5：新提交后的智能更新

当用户推送新变更后要求同步 PR 描述：

1. 识别新提交：

   gh pr view <number> --json commits --jq '.commits[].messageHeadline' git log <base>..<head> --oneline git diff <base>...<head> --stat

2. 重新读取 PR 模板，基于新变更判断哪些章节已过时——用模板的章节名与字段描述定位，而不是依赖硬编码假设；
3. 依据 Step 1a 的标准重新评估证据，只重跑证据已过时、且新鲜必要 CI 无法覆盖的本地检查。技能特别强调："过时的验证证据比没有证据更糟，因为它会误导评审者"；
4. 提交前再次应用作者卫生检查；
5. 逐章节展示拟更新内容，确认后再应用。

Step 6：应用更新

• 标题/标签类变更直接用gh pr edit的标志位；
• 正文变更用 HEREDOC：

  gh pr edit <number> --body "$(cat <<'PR_BODY_EOF' <full updated body> PR_BODY_EOF )"

• 评论变更用 HEREDOC：

  gh pr comment <number> --body "$(cat <<'COMMENT_EOF' <comment text> COMMENT_EOF )"

Step 7：确认

拉取并展示更新后的状态：

gh pr view <number> --json number,title,labels,url

返回 PR URL 收尾。

重要规则：十条红线

技能结尾明确了十条必须遵守的红线，其中几条尤其值得注意：

1. 每次填充或编辑 PR 正文前都必须读.github/pull_request_template.md，绝不假设章节名、字段或结构——它是事实来源且可能变化；
2. 更新时只修改请求的章节，其余内容原样保留；
3. 应用正文编辑前必须展示 diff，逐章节对比当前 vs 拟改；
4. 绝不在 PR 内容中包含个人/敏感数据——这是 ZeroClaw 的隐私契约（merge gate）；
5. 绝不包含 bot/AI 署名页脚，提交任何 PR 文本前执行作者卫生检查；
6. 标签变更只用仓库中真实存在的标签，不确定时先gh label list核实；
7. 编辑前必须拉取最新正文，避免覆盖并发变更（clobber）；
8. 新 PR 必须先推送分支（-u设置上游跟踪）再创建。

与仓库协作体系的协同关系

从仓库源码与工作流配置看，github-pr技能并非孤立存在，其预填行为与 CI 自动机、评审与合入技能环环相扣：

• 标签自动化：技能建议的标签仅作为参考，实际由自动机接管——.github/workflows/pr-path-labeler.yml依据 .github/labeler.yml 中按路径映射的标签规则（如channel:telegram命中src/channels/telegram.rs与crates/zeroclaw-channels/src/telegram.rs，provider:gemini命中 provider 相关源文件）自动打路径/范围标签；.github/workflows/pr-size-labeler.yml则运行 scripts/github/pr_size_label.py 依据 PR 元数据打size:*标签；risk:*等人工标签由具备权限的维护者在侧栏设置。因此正文的 Labels 字段只做快照记录，不承载标签管理职责；
• 标题门禁：pr-title.yml工作流强制 Conventional Commits 带 scope 格式，技能按同一规范草拟标题，两者标准一致；
• 评审侧：github-pr-review-session 会以.github/pull_request_template.md核对 PR 模板完整性（template completeness check），并遵循docs/book/src/contributing/pr-review-protocol.md中的评审协议——这意味着技能预填的质量直接决定评审能否顺利通过；
• 合入侧：squash-merge 技能在合入时会再次执行与本文相同的 bot 署名清洗正则，并把 PR 标题加工为PR_TITLE (#NUMBER)形式的 squash 提交主题，强制要求 Conventional Commits 格式——技能预填的标题质量会沿用到最终落地 master 的提交上。

适用前提与限制

• 本技能面向 ZeroClaw 仓库的协作流程设计，PR 目标分支固定为master，标签体系、路径映射与模板结构均以仓库现状为准；
• 技能的指令以 bash/ghCLI 为基础，执行环境需具备可用的ghCLI、git、rg（ripgrep）以及 Rust 工具链（cargo/rustc）——其中rg用于作者卫生扫描，cargo系列命令用于验证证据收集；
• 仓库为只读镜像形态时，上述命令用于本地查看、验证与配置说明；实际执行推送、建 PR、加标签等写操作需在具备相应权限的仓库副本上由用户触发。

【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 🦀项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw