OrcaSlicer 仓库的 Claude Code 自定义命令：commit-push-pr 一键完成 Git 提交与 PR 创建

导读

.claude/commands/commit-push-pr.md 是 OrcaSlicer 仓库中面向 Claude Code 的自定义斜杠命令（slash command），它将"查看变更 → 切分支 → 提交 → 推送 → 创建 Pull Request"这一完整 Git 工作流收敛为一次对话中的单条命令调用。本文以该命令文件为核心，逐字段解析其 frontmatter 权限白名单、内联命令上下文采集机制与五步任务编排，并结合仓库内的提交规范（AGENTS.md）、PR 模板（.github/pull_request_template.md）与真实提交记录，说明在 OrcaSlicer 这样的 C++ 大型开源项目中，如何让 AI Agent 以可审计、可约束的方式安全地完成代码提交流程。读完本文，你将掌握 Claude Code 自定义命令的设计范式，并能在自己的仓库中复刻这套"权限收紧 + 上下文自采 + 单消息完成"的自动化工作流。

一、命令文件概览：它解决了什么问题

在 OrcaSlicer 这类拥有数十万行代码、跨 Windows/macOS/Linux 三平台构建、并通过 GitHub Actions 承载 CI 的开源仓库（构建工作流见 .github/workflows/build_orca.yml）中，贡献者每天都要重复"查看差异、写提交信息、推分支、开 PR"的机械操作。而交给 AI Agent 执行时，最大的风险不是 Agent 不会敲命令，而是它在过程中"越权"——比如擅自 rebase、删分支、改配置。

commit-push-pr.md 的设计初衷正是通过两层机制化解这一风险：

1. 工具权限白名单（allowed-tools）：在命令执行前就声明 Agent 只能调用哪些 Bash 模式，超出范围的操作一律不被批准；
2. 单消息强制收敛（Task 第 5 步）：要求 Agent 在一条消息内并行完成所有工具调用，不输出任何多余文本，避免对话发散。

命令文件的完整内容（位于 .claude/commands/commit-push-pr.md）：

---
allowed-tools: Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)
description: Commit, push, and open a PR
---

## Context

- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`

## Your task

Based on the above changes:
1. Create a new branch if on main
2. Create a single commit with an appropriate message
3. Push the branch to origin
4. Create a pull request using `gh pr create`
5. You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.

二、Frontmatter 权限白名单：每一类 Bash 调用的精确含义

命令文件的 YAML frontmatter 声明了两个关键字段，其中 allowed-tools 是整份文件的安全基石。它以逗号分隔的 Bash(模式:*) 列表，逐条声明 Agent 被允许执行的命令前缀：

权限模式	授权含义	在五步工作流中的角色
Bash(git checkout --branch:*)	允许以 --branch 形式新建并切换分支	第 1 步：离开 main 分支
Bash(git add:*)	允许暂存文件变更	第 2 步：为提交准备暂存区
Bash(git status:*)	允许查看工作区状态	Context 阶段：采集变更概览
Bash(git push:*)	允许推送分支到远程	第 3 步：推送到 origin
Bash(git commit:*)	允许创建 Git 提交	第 2 步：固化变更
Bash(gh pr create:*)	允许通过 GitHub CLI 创建 PR	第 4 步：发起代码评审

这里有三个值得注意的设计细节：

• 模式通配符粒度：权限精确到子命令与选项级别，例如只授权 git checkout --branch:*，意味着 Agent 不能执行 git checkout main（切换已有分支）或 git checkout -- <file>（丢弃文件改动），从源头堵住了"误切分支 / 误还原文件"这类高危操作；
• 未授权即拒绝：列表之外的任何命令（如 git rebase、git push --force、gh pr merge）都会被 Claude Code 的权限系统拦截，需要人工确认才能放行；
• description 字段：Commit, push, and open a PR 用一句话声明命令用途，既服务于命令菜单展示，也作为 Agent 理解任务目标的锚点。

同类设计在仓库其他命令中一脉相承：.claude/commands/oncall-triage.md 仅开放 Bash(gh issue list:*)、Bash(gh issue view:*)、Bash(gh issue edit:*) 与 TodoWrite，且明确"只添加 oncall 标签、绝不删除标签、不向 issue 发表评论"；.claude/commands/dedupe.md 则只开放 gh issue/gh search/gh api 相关命令。可见"最小权限 + 行为边界文字化"是该仓库约束 Agent 的一贯原则。

三、Context 动态采集：内联命令让 Agent 基于真实变更决策

命令文件的 ## Context 小节使用了 Claude Code 的内联命令语法 !`command`——在提示词展开时实际执行命令，并把命令输出作为上下文注入对话：

• !`git status`：采集工作区与暂存区的变更文件列表（新增/修改/删除/重命名），让 Agent 知道"改了什么"；
• !`git diff HEAD`：采集相对 HEAD 的完整差异（包含已暂存与未暂存部分），是生成提交信息的事实依据；
• !`git branch --show-current`：采集当前分支名，供第 1 步判断"是否在 main 上、是否需要新建分支"。

这一机制的价值在于：提交信息不是 Agent 凭空生成的，而是从 git diff HEAD 的真实补丁内容中归纳出来的。Task 中 "Based on the above changes" 一句，正是要求 Agent 严格以 Context 采集到的差异为准来撰写 commit message，避免出现"描述与改动不符"的典型 AI 提交事故。

四、五步任务编排：从分支到 PR 的完整链路

Task 小节把工作流拆解为五个明确步骤，对应一条可复现的执行链：

第 1 步：在 main 上时创建新分支

git checkout --branch <feature-branch>

仅当 git branch --show-current 返回 main 时才需要执行；若已在特性分支上则跳过，避免嵌套建分支。分支名应由 Agent 依据变更内容拟定（例如修复某项功能时取与改动语义一致的名称）。这一设计保证 main 分支永远保持可发布状态，符合 OrcaSlicer 这类持续发版项目（version.inc、build_release_vs2022.bat 等发布脚本所在仓库）的分支管理惯例。

第 2 步：创建单个提交

git add <变更文件>
git commit -m "<提交信息>"

命令文件要求"Create a single commit"——把一次任务的变更收敛为一个提交，而不是零散堆叠。提交信息的风格应遵循仓库规范（详见第五节），由 Agent 基于 git diff HEAD 的上下文概括。

第 3 步：推送分支到 origin

git push origin <分支名>

注意权限模式是 Bash(git push:*)，即只放行普通推送；强制推送（--force）不在白名单内，这是对历史重写类操作的明确拒绝。

第 4 步：创建 Pull Request

gh pr create --title "<标题>" --body "<描述>"

通过 GitHub CLI 直接基于当前分支发起 PR。PR 的标题与描述内容需对接仓库的评审要求（见第五节模板），包括改动摘要、关联 issue 与测试说明。

第 5 步：单消息内并行完成全部工具调用

这是命令文件中最具约束力的行为指令："You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls."

它同时施加了三重约束：

• 时间约束：全部操作必须发生在同一条 Agent 回复中，不允许分多条消息逐步执行；
• 工具约束：除了上述 git/gh 命令，不得调用其他任何工具（文件编辑、网页抓取、MCP 服务等）；
• 文本约束：不得夹带与工具调用无关的叙述文字。

其用意在于：把整个流程当作一次确定性事务执行，减少对话轮次，也杜绝 Agent"顺手做别的事"的漂移风险——这与 .claude/commands/dedupe.md 中"Do not use other tools, beyond gh"的约束逻辑完全一致。

五、仓库配套规范：提交信息风格与 PR 模板

要让第 2、4 步的输出真正符合 OrcaSlicer 的评审标准，需要结合仓库的两份权威规范：

提交信息风格（AGENTS.md）

仓库的 Commit & Pull Request Guidelines 明确要求：

• 句式的主题行（sentence-style subject line），可附带 issue 引用，示例：Fix grid lines origin for multiple plates (#10724)；
• 本地 squash fixup：在开 PR 前把零散修复合并进既有提交；
• PR 中说明依赖升级与配置迁移（dependency bumps / profile migrations），供维护者重点评审。

仓库实际提交记录也印证了这一风格，例如当前分支的提交 Fix artifact name conflict between workflows——动词开头、单句概括、无冗余修饰。Agent 生成提交信息时应以这类历史提交为基准模板。

PR 模板（.github/pull_request_template.md）

仓库的 PR 模板固定为三节：

1. Description：说明本 PR 解决或修复的 issue、引入的新特性、是否存在破坏性变更或依赖调整；
2. Screenshots/Recordings/Graphs：UI 变更必须附截图，帮助评审者直观理解改动；
3. Tests：描述已执行的验证，包括自动化测试与手工打印验证。

此外 AGENTS.md 还要求通过 Closes #NNNN 关联 issue、为 UI 变更附复现步骤，并在自动化覆盖不足时于 PR 中记录手工切片验证结果。Agent 在 gh pr create 的 body 中应直接按这三节组织内容——这也是"Create a pull request"这一步骤在 OrcaSlicer 语境下的完整含义。

六、与仓库自动化生态的关系

这份命令并非孤立存在，它属于仓库整体"AI 辅助维护"体系的一部分：

• 问题去重：.claude/commands/dedupe.md 驱动 Agent 查找最多 3 个疑似重复 issue 并评论，配合 .github/workflows/auto-close-duplicates.yml 定时执行 scripts/auto-close-duplicates.ts 实现自动关闭；
• 值班分诊：.claude/commands/oncall-triage.md 让 Agent 扫描近 3 天高互动量的 open bug，为真正阻塞用户的关键 issue 打上 oncall 标签；
• 持续集成：.github/workflows/ 下的构建矩阵（如 build_linux_appimage.yml、build_windows_bridge.yml）会在 PR 上自动执行三平台编译与检查。

commit-push-pr 位于这条链路的出口端：前序的 issue 分诊、去重负责"发现问题"，本文命令负责"把修复干净利落地送入评审"。三者共享同一套设计哲学——用受限工具集 + 明确行为规范，让 Agent 在开源协作中扮演可预测、可审计的角色。

七、使用方式与排障要点

触发方式

在 Claude Code 会话中直接输入命令名即可触发（命令名取自文件名 commit-push-pr）：

/commit-push-pr

触发后，Claude Code 会自动执行 ## Context 中的三条内联命令，将当前工作区状态注入上下文，随后 Agent 按五步流程执行。由于 OrcaSlicer 仓库当前处于 main 分支且与 origin/main 同步，典型触发场景是：本地完成代码修改后调用该命令，Agent 会先感知"在 main 上"这一事实，自动进入建分支流程。

权限被拒时的处理

如果 Agent 试图调用白名单之外的命令（例如想用 git remote -v 检查远程、或 gh pr view 预览结果），Claude Code 会发起权限确认。此时应当：

1. 检查是否确实需要该命令——大多数情况下白名单内的命令已足够完成流程；
2. 如确有必要，可通过 Claude Code 的权限配置按需放行单次调用；
3. 注意命令文件的 allowed-tools 是作者刻意收紧的边界，日常使用中应尽量保持其原样，这正是本命令安全性的来源。

落地到其他仓库的适配建议

若要复用该命令，需要按目标仓库调整三处：

• 提交规范：将 Task 第 2 步的"appropriate message"映射到目标仓库的提交约定（可参照目标仓库的 AGENTS.md 或历史提交记录）；
• PR 模板：在 Task 第 4 步补充目标仓库 PR 模板要求的结构化 body（OrcaSlicer 的模板见 .github/pull_request_template.md）；
• 权限边界：根据团队允许的操作增删 allowed-tools 条目，例如是否放行 git push --force、是否允许 gh pr ready 等。

总结

.claude/commands/commit-push-pr.md 用 18 行 Markdown 定义了一个完整的、可安全交由 AI 执行的 Git 提交流程：frontmatter 以 allowed-tools 白名单划定 Agent 的能力边界，## Context 通过内联命令让 Agent 基于真实 diff 决策，## Your task 以五步任务加单消息约束确保流程的确定性与专注度。配合仓库既有的提交风格规范与 PR 模板，它成为 OrcaSlicer 生态中"AI 提 PR"的标准入口，也为其他开源仓库提供了一份可直接借鉴的 Claude Code 自定义命令设计范本。