commit

智能提交

与宿主无关的工作流。通过技能名称（commit）调用。Claude Code 斜杠路由、YAML 钩子加载器和 .claude/chain 详见 references/claude-code.md。

简单、经过验证的提交创建流程。在本地运行检查，标准提交无需 Agent。

注意： 如果启用了 disableSkillShellExecution（CC 2.1.91），则不会运行 git 仓库检查。此技能需要在 git 仓库中使用。

快速开始

commit
commit fix typo in auth module

参数解析

COMMIT_MSG = "$ARGUMENTS"  # Optional commit message, e.g., "fix typo in auth module"
# If provided, use as commit message. If empty, generate from staged changes.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

步骤 0：选择提交模式（AskUserQuestion — M118 #1465）

默认模式为“新建提交”，但如果语音流程需要修改提交、推送或暂存，则必须明确选择：

# Skip when a flag in the invocation makes the mode unambiguous:
#   commit --amend  → skip, mode=amend
#   commit --push   → skip, mode=new+push
#   commit --stash  → skip, mode=stash-first
#   ORK_COMMIT_DEFAULT_MODE=new (or amend|push|stash) → skip, use env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "How should this commit land?",
  "header": "Commit mode",
  "options": [
    {"label": "New commit (default)", "description": "Create a new commit, leave HEAD intact"},
    {"label": "Amend HEAD", "description": "Fold staged changes into the last commit (LOCAL ONLY — refuses if HEAD is published)"},
    {"label": "New commit + push", "description": "Commit then `git push` (refuses on protected branches)"},
    {"label": "Stash first", "description": "Stash unrelated working-tree changes, then commit only what was already staged"}
  ]
}])

针对模式的防护措施：

• 修改 HEAD — 确认 HEAD 尚未推送到 origin（git rev-list HEAD..origin/<branch> 结果为空）；如果已发布，则拒绝修改，并建议选择“新建提交”。
• 新建提交并推送 — 推送前，根据阶段 1 重新检查受保护分支规则；如果 HEAD 所在分支为 main/master/dev，则中止。
• 先暂存 — 执行 git stash push -k -m "ork:commit autostash"（保留索引），然后提交；推送成功后再执行 git stash pop。

工作流

阶段 0：确认有可操作的仓库

执行任何防护检查前，运行 git rev-parse --is-inside-work-tree。如果失败，或 当前会话中无法使用 Bash 工具，则用一句话说明，并且只生成提交消息文本。 完全跳过阶段 1 至 3。

绝不要输出未经实际核实的分支防护信息、验证状态或其他仓库事实。 2026-09-12 使用 claude plugin eval 测试时发现：在没有仓库且无法使用 Bash 的 沙盒中，此技能仍显示了一个声称分支为 main 且受保护的“提交前防护”框。 实际上没有进行任何检查。正确的做法是只输出提交消息，并说明“我无法核实分支或 lint 状态”；编造防护信息属于缺陷。

阶段 1：提交前安全检查

# CRITICAL: Verify we're not on dev/main
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == "dev" || "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "STOP! Cannot commit directly to $BRANCH"
  echo "Create a feature branch: git checkout -b issue/<number>-<description>"
  exit 1
fi

阶段 2：在本地运行验证

运行 CI 中执行的所有检查：

# Backend (Python)
poetry run ruff format --check app/
poetry run ruff check app/
poetry run mypy app/

# Frontend (Node.js)
npm run format:check
npm run lint
npm run typecheck

继续之前，修复所有失败项。

阶段 3：审查更改

git status
git diff --staged   # What will be committed
git diff            # Unstaged changes

阶段 3b：Agent 归属（自动）

提交前，检查分支活动记录文件 .claude/agents/activity/{branch}.jsonl 是否存在。 如果文件存在，且有上次提交之后的记录，则将这些记录加入提交消息：

1. 读取 .claude/agents/activity/{branch}.jsonl（每行一个 JSON 对象）
2. 筛选 ts 晚于上次提交时间戳（git log -1 --format=%cI）的记录
3. 跳过 duration_ms < 5000 的 Agent（仅提供建议的 Agent 应列入 PR，而非提交）
4. 在提交正文与 Co-Authored-By 尾注之间添加 “Agents Involved:” 段落
5. 为每个 Agent 添加 Co-Authored-By 尾注：Co-Authored-By: ork:{agent} <[email protected]>

如果记录文件不存在或为空，则跳过此步骤，照常提交。

阶段 4：暂存并提交

CC 2.1.113 用法： 现在，多行 Bash 命令开头带有 # intent: 注释时，会在记录中显示完整命令——为复杂脚本添加一行意图注释，这样后续读者（以及 /recap 扫描）无需重新查看差异，就能在记录中搜索并了解发生了什么。

# intent: stage the hook change + its test + built artifacts
# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format (with agent attribution if ledger exists)
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

Agents Involved:
  backend-system-architect — API design + data models (2m14s)
  security-auditor — Dependency audit (0m42s)

Co-Authored-By: Claude <[email protected]>
Co-Authored-By: ork:backend-system-architect <[email protected]>
Co-Authored-By: ork:security-auditor <[email protected]>"

# Verify
git log -1 --stat

CC 2.1.183 — attribution.sessionUrl： 在网页和 Remote Control 会话中，CC 会在提交/PR 归属信息中附加 claude.ai 会话链接。设置 attribution.sessionUrl: false（/config attribution.sessionUrl=false）即可将其省略——适用于不应泄露会话链接的公共仓库。上述 Co-Authored-By 尾注不受影响。

交接文件

提交成功后，写入交接信息：

Write(".claude/chain/committed.json", JSON.stringify({
  "phase": "commit", "sha": "<commit-sha>",
  "message": "<commit-message>", "branch": "<branch>",
  "files": [<staged-files>]
}))

提交类型

类型	用途
feat	新功能
fix	修复错误
refactor	改进代码
docs	文档
test	仅测试
chore	构建/依赖/CI

快速规则

1. 在本地运行验证 - 不要派遣 Agent 运行 lint/test
2. 禁止创建文件 - 不要创建 MD 文件或文档
3. 每次提交只包含一个逻辑更改 - 让提交保持聚焦
4. 引用问题 - 在提交消息中使用 #123 格式
5. 主题行 < 72 个字符 - 保持简洁

快速提交

对于琐碎的更改（拼写错误、单行修复）：

git add . && git commit -m "fix(#123): Fix typo in error message

Co-Authored-By: Claude <[email protected]>"

验证关卡

提交前，执行 5 步关卡：Read("../../shared/rules/verification-gate.md")。重新运行测试。阅读输出。只有测试通过后才能提交。“应该没问题”不是证据。

质量标准

满足以下所有条件才算完成：

• 提交已进入功能分支，绝不能进入 dev/main/master（第 1 阶段防护已生效）
• 主题使用与差异内容匹配的常规类型（feat/fix/docs/refactor/test/chore），且不超过 72 个字符
• 如果 HEAD 位于问题分支上，消息中必须包含问题引用（#N）
• 提交前，针对所修改技术栈的本地验证（lint/type/test）已运行并通过
• 存在 Co-Authored-By: Claude 尾注；仅当活动日志中存在上次提交之后的条目时，才添加各 Agent 的尾注
• git log -1 --stat 显示的文件恰好是预期文件，不含机密信息，也没有仅包含生成噪声的提交

相关技能

• ork:create-pr：根据提交创建拉取请求
• ork:review-pr：提交前审查更改
• ork:fix-issue：修复问题并提交修复
• ork:issue-progress-tracking：自动使用提交进度更新 GitHub 问题

规则

每个类别都在 rules/ 中有单独的规则文件，按需加载：

类别	规则	影响	关键模式
原子提交	rules/atomic-commit.md	CRITICAL	每次提交只包含一个逻辑更改、原子性测试
分支保护	rules/branch-protection.md	CRITICAL	受保护分支、必需的 PR 工作流
提交拆分	rules/commit-splitting.md	HIGH	git add -p、交互式暂存、拆分策略
常规格式	rules/conventional-format.md	HIGH	type(scope): description、破坏性更改
历史记录规范	rules/history-hygiene.md	HIGH	合并 WIP、fixup 提交、整洁的历史记录
问题引用	rules/issue-reference-required.md	HIGH	在问题分支上的提交中引用问题 #N
合并策略	rules/merge-strategy.md	HIGH	优先变基、冲突解决、force-with-lease
堆叠式 PR	rules/stacked-pr-workflow.md	HIGH	堆叠规划、创建 PR、依赖跟踪
堆叠式 PR	rules/stacked-pr-rebase.md	HIGH	变基管理、force-with-lease、重新指定目标

总计：8 个类别中的 9 条规则

参考资料

使用 Read("references/<file>") 按需加载：

文件	内容
references/conventional-commits.md	Conventional commits 规范
references/recovery.md	恢复流程