[Git] 工作流助手：分支、提交、PR、review comment 和冲突辅助

[v833]

标签建议：area/git, area/dx, priority/P1, type/feature

背景

当前能力：

• q-code 运行在用户仓库内，能通过 shell 执行 git 命令，并已有部分 GitHub PR/CI 相关技能工作流。
• 项目协作规则要求保护 dirty worktree，不覆盖用户改动，不随意 amend，不使用破坏性 git 命令。
• 用户常见任务包括建分支、整理提交、创建 PR、处理 review comment、解决冲突和同步 CI 结果。

痛点：

• 直接让 Agent 执行 git 命令容易有风险，例如误 stage 不相关文件、覆盖用户改动或提交敏感文件。
• Review comment 修复需要关联 PR、评论位置、本地文件和测试命令，流程重复。
• 冲突处理需要清晰展示双方改动和安全确认。

需要补齐：

• 一个面向 Git 工作流的安全助手层。
• 分支、stage、commit、PR、review comment 和冲突辅助的统一交互。
• 与 approval policy、diff/patch 和验证策略协同。

目标

实现 Git 工作流助手：安全辅助创建/切换分支、选择性 stage、生成提交、创建 PR、处理 review comments 和解决冲突，同时保护用户未提交改动并提供清晰验证报告。

用户故事

• 作为开发者，我希望 q-code 只 stage 本轮修改的文件，以便不会把我的无关改动提交进去。
• 作为 PR 作者，我希望 q-code 能读取 review comments 并逐条定位修复，以便减少上下文切换。
• 作为维护者，我希望提交前自动检查 diff、敏感文件和测试结果，以便降低坏提交风险。
• 作为冲突处理者，我希望 q-code 展示冲突双方意图并生成安全 patch，以便避免误删代码。

详细需求

1. 分支管理

• 支持按约定创建 codex/ 前缀分支，除非用户指定其他名称。
• 切换分支前检查 dirty worktree，并提示未提交改动风险。
• 不使用 git reset --hard 或 git checkout -- 等破坏性命令，除非用户明确批准。

2. Stage 与提交

• 根据本轮变更或用户选择进行精确 stage。
• 提交前展示 staged diff 摘要、敏感文件检查和推荐测试结果。
• 生成中文或项目风格 commit message，并允许用户确认。
• 不 amend，除非用户明确要求。

3. PR 创建与更新

• 支持读取远端、推送分支、创建 draft/ready PR。
• PR 正文包含问题背景、变更摘要、测试结果和风险。
• GitHub 凭据不可用时，输出可手动执行的步骤和正文。

4. Review comment 处理

• 读取当前分支对应 PR 的 review comments。
• 将评论映射到本地文件和行号，按主题分组。
• 每条评论处理后可标记回复或生成总结。
• 与现有 gh-address-comments 技能保持兼容。

5. 冲突辅助

• 检测 merge/rebase/cherry-pick 冲突状态。
• 展示 ours/theirs 和上下文，生成可审查 patch。
• 用户确认后写入解决方案，并建议相关测试。

输出样例

准备提交:

Staged:
- src/runtime/config.ts
- tests/unit/runtime-config.test.ts

未包含用户改动:
- docs/prd/local.md

测试:
- pnpm typecheck: pass
- pnpm test:unit: pass

验收标准

• 创建分支默认使用 codex/ 前缀，并在 dirty worktree 时给出保护提示。
• Stage 只包含用户确认或本轮生成的文件，不自动纳入无关改动。
• 提交前展示 staged diff 摘要、测试结果和敏感文件检查。
• PR 创建失败时能给出可手动提交的标题和正文。
• Review comments 能按文件/主题分组并映射到本地代码。
• 冲突辅助不会静默覆盖 ours/theirs，解决方案走 patch 预览。
• Git 操作关键步骤写入审计日志。
• README/AGENTS 如新增 Git 工作流约定，按需同步更新。

测试方案

• tests/unit/git-workflow.test.ts：覆盖分支命名、dirty worktree 检测、stage 计划、PR body 生成。
• tests/integration/git-flow.test.ts：在临时 git repo 中覆盖分支、stage、commit dry-run、冲突状态。
• 手动验证：GitHub token 可用/不可用、review comments、dirty worktree、未跟踪文件、冲突文件。
• 与 [Verification] 自动验证策略：测试选择、失败归因、flaky 检测和风险评分 #26 验证策略联动测试：提交前测试摘要可被 PR body 引用。

不在本期范围

• 替代完整 Git GUI。
• 自动强推、自动 rebase 或自动 merge main。
• 大规模批量 PR 管理。
• 修改 GitHub 仓库权限或保护规则。

依赖 / 风险

• Git 操作风险高，必须遵守“不覆盖用户改动、不使用破坏性命令”的协作约定。
• 依赖 GitHub 认证和网络；认证失败需要优雅降级。
• 与 [Tools] Diff / Patch：预览确认后写入和本轮回滚 #23 patch 预览、[Verification] 自动验证策略：测试选择、失败归因、flaky 检测和风险评分 #26 验证策略、[Security] Secret 防泄漏：依赖漏洞、敏感内容和输出脱敏拦截 #28 secret 扫描有强关联。
• Windows 路径、换行和 git 输出编码需要处理。

工作量评估

• Branch/stage/commit 安全流程：2 人日
• PR 创建与正文生成：1.5 人日
• Review comment 映射：2 人日
• 冲突辅助与测试：2 人日
• 合计：~7.5 人日