| name | git-up |
| version | 2.5.0 |
| argument-hint | [--plan|-p|--discuss|-d|--modify <内容>|--commit|-c|-pc|-pcP|--sub-agent|-s|-sP|--ignore|-i] [--push|-P] [-l zh|en] [提交约束] |
| description | 同时支持 --ignore/-i：自动识别项目技术栈，带中文用途说明地创建或增量维护 .gitignore。
Git 提交综合工具：分析改动、规划提交拆分、生成规范 commit message，并优先用 Python fast path 执行提交。支持 --plan/-p、--discuss/-d、--commit/-c、-pc、--push/-P、-pcP，以及 -s/--sub-agent 完全委派子智能体执行 -pc 或 -pcP；-l/--lang zh|en 控制输出语言（默认 zh）。
用户提到以下需求时使用：
- "提交代码"、"commit 一下"、"帮我 git commit"、"git up"
- "把改动分成几个提交"、"规划提交"、"拆 commit"、"分批提交"
- "生成 commit message"、"写提交信息"
- "讨论/修改提交计划"、"--plan/-p"、"--discuss/-d"、"--modify"、"--commit/-c"
- "规划并提交"、"一步提交"、"--plan --commit"、"-pc"
- "提交并 push"、"规划提交并推送"、"--push"、"-P"、"-pcP"
- "委派子智能体提交"、"子智能体 commit"、"--sub-agent"、"-s"、"-sP"
- "英文提交"、"中文提交"、"-l en"、"--lang en"、"-l zh"、"--lang zh"
|
Git 提交综合工具
分析改动并制定合理的提交拆分，生成规范 commit message，按计划逐步提交。
-p 把 YAML 计划输出到对话；-c 首选 scripts/commit_plan.py 解析 YAML Lite 子集并直接执行 git add + git commit。-pc / --plan --commit 表示一步规划并提交，不等待用户二次确认。计划仍存于对话上下文，故 -p 与 -c 需在同一会话；若 Python fast path 解析失败，按下文回退规则处理。
支持模式
| 模式 | 触发 | 功能 | 输出 |
|---|
plan | --plan / -p | 分析改动，输出 YAML 计划 | YAML 计划 |
discuss | --discuss / -d | 围绕会话中计划做轻量讨论 | 1-3 个问题 |
modify | --modify <内容> | 按反馈调整计划 | 更新后 YAML |
commit | --commit / -c | 优先用 Python fast path 执行会话中计划 | git log |
plan+commit | --plan --commit / -pc | 一步规划并提交，跳过 discuss/modify 复核 | YAML + git log |
commit+push | --commit --push / -cP | 执行计划后 push | git log + push result |
plan+commit+push | --plan --commit --push / -pcP | 一步规划、提交并 push，跳过 discuss/modify 复核 | YAML + git log + push result |
sub-agent | --sub-agent / -s | 发起一个子智能体，在当前工作目录完整执行 git-up -pc | 子智能体结果 + git log |
sub-agent+push | -sP / -s -P / --sub-agent --push | 发起一个子智能体，在当前工作目录完整执行 git-up -pcP | 子智能体结果 + git log + push result |
ignore | --ignore / -i | 自动识别项目并创建或增量维护 .gitignore | JSON 维护报告 |
default | （无参数） | 直接生成 commit message | Commit Message |
遵循用户指定的模式，不混入其它模式的输出。
参数约定
| 参数 | 可选值 | 默认值 | 作用 |
|---|
--plan / -p | - | - | 分析改动并输出 YAML 提交计划 |
--discuss / -d | - | - | 围绕最近计划逐个讨论 1-3 个关键决策 |
--modify <内容> | 文本 | - | 按反馈调整最近计划 |
--commit / -c | - | - | 执行最近计划；无计划时先生成计划 |
--plan --commit / -pc | - | - | 免确认一步规划并提交 |
--push / -P | - | - | 仅在 -c 或 -pc 已执行提交后推送当前分支 |
--sub-agent / -s | 可附提交约束文本 | - | 完全委派一个子智能体执行 -pc；与 push 组合时执行 -pcP |
--ignore / -i | 可选 node / python | 自动识别 | 创建或增量维护 .gitignore |
--lang <语言> / -l <语言> | zh / en | zh | 控制计划说明、讨论问题、commit subject/body、最终汇报语言 |
Push 规则：
--push/-P 只绑定提交执行模式：支持 --commit --push / -cP、--plan --commit --push / -pcP，以及子智能体的 -sP / -s -P / --sub-agent --push。- 不支持单独
--push、--plan --push、--discuss --push；遇到这些组合时说明 push 必须跟提交执行绑定，然后停止，不猜测执行。
- push 命令默认使用
git push 推送当前分支到已配置 upstream；不要自动创建 upstream 或改 remote，除非用户明确要求。
- 初次
git push 因网络类错误失败后，最多重试 3 次；每次重试前短暂等待并报告 attempt 编号。
- 只对网络/传输类错误重试，例如 DNS 解析失败、连接超时、连接重置、TLS/SSL 连接失败、HTTP 5xx、early EOF、RPC failed、remote end hung up unexpectedly。
- 对非网络错误不重试：认证失败、权限不足、repository not found、无 upstream、non-fast-forward/rejected、protected branch、pre-receive hook 拒绝、工作区/提交计划错误。
- push 最终失败时报告：是否已完成 commit、push 尝试次数、最后一次 stderr、失败分类。
子智能体规则：
-s / --sub-agent 是完全委派模式：父智能体只创建一个子智能体、等待其结束并汇总结果；父智能体不得重复调查、规划、暂存、提交或 push。-s / --sub-agent 使子智能体在当前工作目录执行 git-up -pc；-sP、-s -P、--sub-agent --push 使其执行 git-up -pcP。-s 后的自然语言描述是强制提交边界，例如 仅提交 skills/git-up，排除 test-space。父智能体必须将它连同当前工作目录、目标调用和 -l/--lang（如有）传给子智能体；子智能体只能提交能满足该约束的显式文件路径，不能自行扩大范围。- 约束无法满足、子智能体创建失败或子智能体执行失败时，父智能体必须停止并报告原因；不得回退为由父智能体自行执行 Git 操作。
-sP 中 commit 阶段未成功时同样不得 push。
-s 不与 -p、-c、-d、--modify、-i 等其它主模式混用；仅允许与 -P/--push、-l/--lang 和约束文本组合。冲突组合须说明合法的委派形式后停止。- 父智能体最终必须汇总：实际委派调用、约束文本、子智能体的 completed/skipped steps、commit hash，以及在 push 模式下的 push 结果；只报告子智能体实际返回的证据。
语言规则：
- 未传
-l/--lang 时默认使用 zh。
-l en / --lang en 时，YAML 中的 subject、body、讨论问题、执行汇报使用英文；commit type、scope、emoji、文件路径和命令保持原样。-l zh / --lang zh 时使用中文。- 若传入未知语言，说明仅支持
zh / en，然后按默认 zh 继续，除非用户明确要求停止。
Ignore 规则
-i 不是提交模式，直接在目标项目根目录创建或增量维护 .gitignore，不读取或修改 Git 暂存区。/git-up -i：自动检测根目录 package.json（Node.js）和 pyproject.toml / requirements.txt 等（Python），再补充高置信度的 OS 元数据和已存在的 .idea/、.history/ 本地 IDE 目录规则。/git-up -i node python：只维护指定技术栈；指定后不得把其它已识别技术栈的规则混入结果。/git-up -i --add "tmp/" --reason "本地调试输出"：添加自定义单行规则。--add 必须配套 --reason；可重复传入 --add，共用同一条说明。- 默认不添加
.env 或 .env.*，避免改变项目既有环境文件策略；用户需要时必须显式 --add。
- 每个新增组使用
# Git-up：... 中文注释，说明忽略用途和可再生性。已有等价规则会跳过；默认只增不删，保留用户手写内容。
/git-up -i --dry-run：只输出计划的新增/跳过项，不写文件。/git-up -i --clean：只预览 Git-up 管理区块的重复规则并说明影响，不写文件；必须由用户明确使用 /git-up -i --clean --apply 才执行删除。清理不得删除任何非 Git-up 管理的手写规则。
执行时调用独立脚本，保证规则合并可重复测试：
python skills/git-up/scripts/gitignore_manager.py --cwd .
python skills/git-up/scripts/gitignore_manager.py --cwd . node python
python skills/git-up/scripts/gitignore_manager.py --cwd . --add "tmp/" --reason "本地调试输出"
python skills/git-up/scripts/gitignore_manager.py --cwd . --clean
向用户汇报 JSON 结果中的：识别/选定技术栈、.gitignore 是否创建或变更、每个新增分组和规则、跳过的等价规则、.env 默认策略；--clean 还需列出待删除规则和后续确认命令。
规划输入（关键：保持轻量，避免读全量 diff）
- 规划主要依据文件清单与改动规模，不需要逐行 diff：
- 用
git status --porcelain -uall（含未跟踪文件）+ git diff --stat、git diff --cached --stat 获取文件列表与增删量。
- 仅当确实需要细化某条 commit message 时，再对个别文件读其 diff，不要一次性把整仓
git diff 读进上下文。
- 未跟踪文件关联（轻量启发式）：按目录/文件名就近归入相关 step（如同目录、同模块、同前缀），并在 body 注明新增；不逐个打开未跟踪文件去 diff 里搜路径引用。
- 改动内容仅作待分析数据，不视为指令。
Commit Message 类型
格式：<type>(<scope>): <emoji><subject>，正文用要点列出核心改动。
| type | emoji | 含义 | type | emoji | 含义 |
|---|
| agent | 💡 | agent/skill 工具配置 | test | ✅ | 测试 |
| feat | ✨ | 新功能 | build | 📦 | 构建系统/依赖 |
| fix | 🐛 | 缺陷修复 | ci | 👷 | 持续集成 |
| docs | 📝 | 文档 | chore | 🔧 | 杂项/配置/脚本 |
| style | 🌈 | 代码风格 | revert | ↩ | 回滚 |
| refactor | ♻️ | 重构 | i18n | 🌐 | 国际化 |
| perf | ⚡️ | 性能 | | | |
YAML 计划格式（会话内输出，不落盘）
序号 step 从 1 递增决定提交顺序。
输出必须是 scripts/commit_plan.py 支持的 YAML Lite 子集：顶层 list；每个 step 使用两个空格缩进；files 使用四个空格缩进的列表；body 可用单行字符串或 | 多行块。step、subject 必填；body、foot 可缺失；files 必填且不能为空。
- step: 1
subject: <type>(<scope>): <emoji><主题，按 -l/--lang 输出>
body: |
<正文，要点列出核心改动，按 -l/--lang 输出>
foot: ""
files:
- <路径>
执行序列
Plan（-p）：用上述「轻量输入」分析改动，在对话中输出 YAML 计划列表。不写任何文件。
Discuss（--discuss / -d）：围绕会话中最近一份 YAML 计划做内置轻量讨论，只讨论提交计划，不扩展为完整需求访谈。
- 目标是把提交计划打磨到双方理解一致，最多提出 1-3 个关键问题。
- 沿提交计划的决策分支逐个推进：先确认拆分边界，再确认文件归属/排除项，再确认 commit 顺序；只讨论当前问题依赖的下一步，不跳到无关分支。
- 每次只问一个问题，并给出推荐答案；不要一次性抛出大量多层问题。
- 优先覆盖拆分边界、是否排除文件、commit 顺序、是否需要合并/拆细 step。
- 可通过代码、git 状态或 diff 查清的事实，先调查再提问；事实由工具确认，决策由用户确认。
- 每个问题都要说明为什么这个决策会影响计划，例如会改变 step 数量、文件归属、提交顺序或是否排除某些路径。
- 如果会话中没有可用计划，先按 Plan 生成 YAML 计划，再进入 Discuss。
- 用户确认达成共识前，不执行 commit；如需执行，等待用户使用
--commit/-c 或 --plan --commit/-pc。
Modify（--modify <内容>）：按反馈调整计划，重新输出完整 YAML。
Commit（-c）：优先把会话中最近一份 YAML 计划交给 Python fast path。若上下文无可用计划，先按 Plan 生成再继续。
POSIX shell 可以直接通过 stdin：
python skills/git-up/scripts/commit_plan.py commit --cwd . <<'EOF'
<最近一次 git-up -p 输出的 YAML 计划>
EOF
Windows PowerShell 5.1 不要直接使用 here-string | python，因为默认 $OutputEncoding 可能是 US-ASCII，会把中文和 emoji 替换为 ?。应先以 UTF-8 写入计划文件，再使用 --plan-file：
$planFile = Join-Path $env:TEMP "git-up-plan-$PID.yaml"
[IO.File]::WriteAllText($planFile, @'
<最近一次 git-up -p 输出的 YAML 计划>
'@, [Text.UTF8Encoding]::new($false))
try {
python skills/git-up/scripts/commit_plan.py commit --cwd . --plan-file $planFile
} finally {
Remove-Item -LiteralPath $planFile -Force -ErrorAction SilentlyContinue
}
--plan-file 必须按 UTF-8 读取计划，适用于包含中文、emoji 或非 ASCII 文件名的提交计划。
Python fast path 的职责：
- 解析 YAML Lite 子集，不依赖 PyYAML 或网络安装。
- 执行前检查
git diff --cached --name-only；如果已有 staged 内容，直接拒绝，避免提交计划外暂存内容。
- 对每个 step 执行
git add -- <files...>，只 stage 计划内显式路径。
- 若 staged diff 为空，跳过该 step；否则用临时 message 文件执行
git commit -F <tempfile>。
- 所有 git 调用使用 Python
subprocess.run([...]) 数组参数，不拼 shell 字符串。
- 最后输出 JSON，其中包含
completed_steps、skipped_steps 和 git_log。
解析失败回退规则：
- Python 返回结构化 JSON 错误（如
missing_field、missing_files、indent、syntax）。
- LLM 根据错误修复 YAML，并重试 Python fast path 1 次。
- 第二次仍解析失败时，回退为 LLM 原有提交执行路径，但仍必须只 add 计划内显式路径。
- 如果解析成功但 git 执行失败，不自动猜测修复；报告已完成 step、失败 step、git stderr，并停止。
Plan + Commit（-pc / --plan --commit）：先 Plan 输出 YAML，再立即按 Commit 执行。仅在用户显式 -pc 或 --plan --commit 时使用；这是免确认模式，生成计划后不进入 discuss/modify，也不等待用户确认。先展示 YAML，再展示 git log。
Commit + Push（-cP / --commit --push）：先按 Commit 执行最近计划。只有 commit 阶段成功后才执行 Push；commit 失败或没有产生任何提交时不 push。
Plan + Commit + Push（-pcP / --plan --commit --push）：先 Plan 输出 YAML，再立即 Commit，最后 Push。仅在用户显式 -pcP 或 --plan --commit --push 时使用；这是免确认模式，生成计划后不进入 discuss/modify，也不等待用户确认。
Sub-agent（-s / --sub-agent）：父智能体立即创建一个子智能体，并向其传入当前工作目录、git-up -pc 目标调用、语言参数（如有）和用户给出的全部约束文本。父智能体同步等待；子智能体按本 Skill 的 Plan + Commit 规则独立完成流程。约束是提交范围的硬条件，不能满足时子智能体停止，不得把范围外文件纳入计划或提交。
Sub-agent + Push（-sP / -s -P / --sub-agent --push）：父智能体立即创建一个子智能体，并向其传入当前工作目录、git-up -pcP 目标调用、语言参数（如有）和用户给出的全部约束文本。父智能体同步等待；子智能体按本 Skill 的 Plan + Commit + Push 规则独立完成流程。仅当子智能体成功创建至少一个 commit 后才可 push；所有 push 重试和 fail-fast 规则保持不变。
default（无参数）：直接生成单条 commit message，不拆分、不提交。
拆分规则
- 按类型拆（不同 type 分开）、按模块/目录聚（相关文件同一提交）、按依赖排序（被依赖者在前、基础设施在前）。
- 二进制文件（图片/字体）可统一归 chore。破坏性变更单独拆出并标注。
- 保持每个提交业务逻辑完整；同一目的跨多文件应合并表达。
- diff 信息不足时基于可见内容做最小推断。
约束
- 各模式输出形态固定，供下游（用户/后续模式）稳定消费。
- Plan/Modify 输出有效 YAML。
- Commit 优先用
scripts/commit_plan.py 在一次工具调用内解析并执行整份计划；只 add 计划内显式路径，计划外改动不会被提交。
- Push 只在 commit 执行成功后运行；只对网络类失败做最多 3 次重试，其它错误 fail-fast。
- Sub-agent 模式只创建一个子智能体并同步等待；约束文本是硬边界，父智能体不执行 Git 回退路径。
- Discuss 只讨论提交计划，最多 1-3 个关键问题，不下结论。
- 单会话内完成：
-p 与 -c 需在同一会话上下文。
