ECC 智能提交（Smart Commit）实战指南：用自然语言精准定位文件，让/prp-commit自动完成 Git 暂存与提交
【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC
/prp-commit是 ECC（The agent harness performance optimization system）命令体系中 PRP 工作流系列的一员，它把「暂存哪些文件」这件 Git 操作中最容易出错的事，交给自然语言来描述：你只需说the auth changes、except tests或only new files，命令就会自动解析意图、暂存对应文件、生成符合 Conventional Commits 规范的提交信息并完成提交。读完本文，你将掌握该命令的四阶段执行模型、全部输入解析模式、提交信息规范，以及它在 PRP 工作流（PRD → Plan → Implement → Commit → PR）中的精确位置与上下游衔接方式。
命令概览：面向 Agent 的自然语言快速提交
/prp-commit的定义文件位于 commands/prp-commit.md，在 docs/COMMAND-REGISTRY.json 的命令注册表中被登记为：
{ "command": "prp-commit", "description": "Quick commit with natural language file targeting — describe what to commit in plain English", "type": "testing", "primaryAgents": [], "allAgents": [], "skills": [], "path": "commands/prp-commit.md" }命令头部元信息定义了它的调用方式：
description：自然语言指定文件的快速提交——用平实语言描述要提交什么（日文版写作「自然言語でファイルを指定するクイックコミット」）。argument-hint：[ターゲットの説明]（空欄 = すべての変更），即参数可空，留空表示提交全部更改。- 输入：
$ARGUMENTS——用户在斜杠命令后附加的自然语言描述或文件名/glob。
命令文档开头标注了出处：PRPs-agentic-eng の Wirasm による適応。PRPワークフローシリーズの一部。（改编自 Wirasm 的 PRPs-agentic-eng，属于 PRP 工作流系列）。它在仓库中拥有日文（docs/ja-JP/commands/prp-commit.md）和中文（docs/zh-CN/commands/prp-commit.md）等多语言版本，便于不同语言环境的 Agent 与开发者使用。
整个命令的执行被划分为四个阶段：ASSESS（评估）→ INTERPRET & STAGE（解析与暂存）→ COMMIT（提交）→ OUTPUT（输出）。下面逐一展开。
阶段 1 — ASSESS：先看清工作区现状
任何提交的第一步都不是「动手」，而是「看清现状」。命令首先执行：
git status --short- 如果输出为空 →立即停止，并提示："コミットするものがありません。"（没有可提交的内容）。
- 如果存在变更，则向用户展示一份变更摘要，区分四类状态：新增（added）、修改（modified）、删除（deleted）、未跟踪（untracked）。
这一步的价值在于：它把「工作区到底发生了什么」显式呈现给用户，为后续的自然语言解析提供事实基础——git status的输出不仅是给用户看的，更是阶段 2 中用来「匹配自然语言描述」的检索语料。
阶段 2 — INTERPRET & STAGE：解析意图并暂存
这是整个命令的核心。它解析$ARGUMENTS，将其映射到具体的 Git 暂存操作。原文档给出了完整的输入—解释—命令对照表：
| 输入 | 解释 | Git 命令 |
|---|---|---|
| （空白 / 未输入） | 暂存所有内容 | git add -A |
staged | 使用已暂存的内容 | （不执行 git add） |
*.ts或*.py等 | 暂存匹配的 glob | git add '*.ts' |
except tests | 全部暂存后取消暂存测试 | git add -A && git reset -- '**/*.test.*' '**/*.spec.*' '**/test_*' 2>/dev/null \|\| true |
only new files | 仅暂存未跟踪文件 | git ls-files --others --exclude-standard \| grep . && git ls-files --others --exclude-standard \| xargs git add |
the auth changes | 从 status/diff 中解释——检测 auth 相关文件 | git add <匹配到的文件> |
| 具体文件名 | 暂存这些文件 | git add <files> |
自然语言输入的处理方式
对于"the auth changes"这类自然语言输入，命令要求交叉引用git status输出与git diff来识别相关文件：先看哪些文件发生了变更，再结合 diff 内容判断哪些与用户描述的主题（如认证 auth）相关。关键要求是向用户展示你暂存了哪些文件、以及为什么暂存它们——这一透明性原则让 Agent 的自动判断始终处于用户的可监督之下。
暂存后的强制验证
无论以何种方式完成暂存，随后都要执行验证：
git add <确定的文件> git diff --cached --stat- 若暂存区为空 →停止，提示："説明に一致するファイルがありません。"（没有文件匹配你的描述）。
这一「暂存后必验证」的机制，从流程上杜绝了「命令执行成功但什么都没暂存」的静默失败——git diff --cached --stat是对暂存结果的客观确认。
阶段 3 — COMMIT：生成符合规范的提交信息
暂存确认无误后，命令以祈使语气生成单行提交信息，格式为：
{type}: {description}类型（type）一览
| 类型 | 含义 |
|---|---|
feat | 新功能或能力 |
fix | 缺陷修复 |
refactor | 不改变行为的代码重构 |
docs | 文档变更 |
test | 测试的新增或更新 |
chore | 构建、配置、依赖 |
perf | 性能改进 |
ci | CI/CD 变更 |
这 8 种类型与 Conventional Commits 规范完全对齐，确保了整个 PRP 工作流产出的提交历史风格统一——这一点在下游/prp-pr命令中会被直接复用：prp-pr在分析提交时会按类型前缀归纳 PR 标题与变更摘要（见 commands/prp-pr.md 的 Commit Analysis 部分）。
信息编写五条规则
- 祈使语气：写
add feature，而不是added feature； - 类型前缀之后小写；
- 末尾不加句号；
- 72 字符以内；
- 描述「改了什么（WHAT）」而非「怎么改的（HOW）」。
随后执行真正的提交：
git commit -m "{type}: {description}"阶段 4 — OUTPUT：结构化汇报与下一步引导
提交完成后，命令以固定格式向用户汇报结果：
Committed: {hash_short} Message: {type}: {description} Files: {count} file(s) changed Next steps: - git push → 推送到远程 - /prp-pr → 创建拉取请求 - /code-review → 推送前进行审查这一输出同时承担了两个职责：一是给出可验证的客观结果（短哈希、提交信息、变更文件数）；二是衔接工作流的下游环节——git push推送远程、/prp-pr创建 PR、/code-review推送前审查。
在 PRP 工作流中的位置与上下游衔接
/prp-commit不是孤立命令，它处于 ECC 的 PRP（Plan-Review-Publish）工作流链条之中。整套链条在commands/目录下依次为：
- /prp-prd：以问题优先、假设驱动的方式生成 PRD；
- /prp-plan：从 PRD 阶段生成包含全部模式、约定与验证命令的实施计划；
- /prp-implement：按计划逐任务执行并持续验证；
/prp-commit：将实现成果以规范提交固化；- /prp-pr：基于未推送的提交创建 Pull Request。
从源码结构看，这种衔接是双向的：
- 上游指向：commands/prp-implement.md 的 Next Steps 明确写着
Run /prp-commit to commit with a descriptive message，即实现完成后下一步就是调用本命令； - 下游依赖：commands/prp-pr.md 在 VALIDATE 阶段检查工作区时，若发现未提交的变更，会提示
Use /prp-commit to commit——提交信息的规范性直接影响后续 PR 标题与变更摘要的自动生成质量。
实战示例速查
原文档给出了 6 个典型调用场景，覆盖了阶段 2 的各类输入模式：
| 你说 | 实际发生 |
|---|---|
/prp-commit | 暂存所有内容，自动生成提交信息 |
/prp-commit staged | 仅提交已经暂存的内容 |
/prp-commit *.ts | 暂存所有 TypeScript 文件并提交 |
/prp-commit except tests | 暂存除测试文件以外的所有内容 |
/prp-commit the database migration | 从 status 中检出数据库迁移文件并暂存 |
/prp-commit only new files | 仅暂存未跟踪文件 |
最佳实践与使用建议
结合命令定义与 PRP 工作流整体设计，可以总结出以下使用要点：
- 留空即全量：需要一次性提交所有变更时，直接
/prp-commit即可，无需任何参数； - 细分提交优先于大杂烩：
only new files、*.ts、except tests等模式允许你把不同类型的工作拆成语义清晰的多次提交，这比一个大而全的提交更利于后续/prp-pr生成结构化 PR； - 自然语言描述要对应「变更主题」而非「文件路径」：如
the auth changes、the database migration，命令会依据git status与git diff做交叉匹配；描述越贴近实际变更内容，匹配越准确； - 提交前留意输出中的验证信息：阶段 2 的
git diff --cached --stat与阶段 4 的 Files 计数，都是确认「暂存了预期内容」的客观信号；若出现"没有文件匹配你的描述"的停止提示，应先确认描述与工作区变更是否一致； - 遵循提交信息五条规则：祈使语气、前缀后小写、无句号、72 字符内、写 WHAT 不写 HOW，这些规则产出的规范提交历史，正是 PRP 工作流下游自动生成 PR 标题与变更摘要的基础。
小结
/prp-commit用四个阶段把「评估工作区 → 解析自然语言意图 → 暂存 → 规范提交 → 汇报与衔接」串成了一条可预测、可验证的自动化链路。它在 ECC 命令体系中承担着 PRP 工作流「成果固化」的关键一环：向下承接prp-implement的实现产出，向上为prp-pr提供规范化的提交素材。对 Agent 使用者而言，它把 Git 提交从「手工选择文件 + 手工写信息」降维为「一句话描述」，同时用透明的暂存展示和强制验证保证了每一次提交都在用户的监督与确认之下。
【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
