Repository Bugfix
按照“确认仓库 → 读取材料 → 创建诊断 worktree → 诊断 → 授权门槛 → 创建修复 worktree → 修复 → Review → 测试 → 提交推送”的顺序处理 BUG。不切换、更新或读取 <workspace>/repos/<repo> 的工作区内容。
确认仓库
用户明确提供仓库目录时直接使用。用户只提供仓库名时,使用当前运行环境明确提供的 workspace 根目录,在 <workspace>/repos 的直接子目录中,将该名称与目录名或 origin 仓库名精确比较;可忽略大小写和末尾的 .git。没有唯一匹配或运行环境没有提供 workspace 时,要求用户补充仓库路径。
不要扫描整个用户目录、磁盘、其他常用目录或未向 Agent 公开的路径;不做部分匹配,不猜测项目,不选择名称相近的仓库。
解析绝对路径。检查仓库状态:
git -C "$REPO_PATH" rev-parse --show-toplevel
git -C "$REPO_PATH" status --short --branch
目录不是 Git 仓库或仓库没有 origin 时停止,报告无法从最新远程快照创建诊断 worktree。
读取材料
读取任务已经提供的全部相关材料,包括当前表现、预期表现、复现步骤、消息上下文、截图、日志、堆栈、附件、配置、测试结果和参照功能。先穷尽已有内容,不要发送通用信息收集模板或重复询问。
分析图片时说明界面、可见文字和数值、标注位置、当前表现、预期表现、可能模块和不确定信息。不要只做 OCR,不要编造无法确认的内容。
检查材料是否包含凭据、个人数据、内部地址、私有代码或业务数据。不得在命令、日志、回复或提交中回显敏感值,只使用完成当前 BUG 所需的最小材料。
创建诊断 Worktree
用户指定基础分支时优先使用;否则使用 origin/HEAD。将用户指定的分支解析为 origin/<基础分支>。使用 Skill 自身目录中的脚本运行:
"{baseDir}/scripts/prepare-diagnosis.sh" "$REPO_PATH" "$WORKSPACE_ROOT" "$BASE_REF"
使用 origin/HEAD 时省略第三个参数。脚本 fetch origin,然后在 <workspace>/worktrees/bugfix/<repo>/diagnosis-<unique-run-id> 中创建 detached worktree,输出 BASE_REF、BASE_COMMIT 和 DIAGNOSTIC_PATH。
在 DIAGNOSTIC_PATH 中读取仓库说明、适用的 AGENTS.md、依赖清单、CI 配置、测试约定和相关源码。后续诊断全部在该 worktree 中执行。
诊断
修改前确认:
- 当前表现是否违反可验证的预期。
- 是否可能属于正常规则、配置、数据延迟、平台差异或显示口径。
- 根因位于当前仓库中的哪个模块和调用链。
- 当前仓库是否包含可以修复根因的源文件。
- 是否缺少复现条件、目标数值或业务规则。
从日志和堆栈向调用方追踪,结合功能名、配置、数据和相似实现定位。结论引用当前证据,并尽可能给出文件、符号、当前有效行号、调用链、正常与异常实现的差异以及最小修复方案。
- 不是 BUG:解释当前表现后停止。
- 证据不足:只请求阻断当前步骤的最小补充后停止。
- 根因不在当前仓库:说明证据指向的模块后停止。
- 可以在仓库中修复:根据授权门槛继续。
没有明确依据时不得猜测业务规则或目标数值。
授权门槛
- 用户只要求判断、分析或定位:只输出诊断,不创建修复分支,不修改、提交或推送。
- 用户明确要求修复:创建 worktree,并在 Review 和测试通过后提交、推送分支。
不要把诊断请求自动升级为修复。当前 Agent 或运行环境的更高优先级授权规则始终优先。
创建 Worktree
分支命名优先遵循仓库约定,没有约定时使用 fix/<bug-name>。同名本地或远程分支已存在时追加 YYYYMMDD-HHMM。
使用诊断脚本输出的 BASE_COMMIT 作为修复分支起点,运行:
"{baseDir}/scripts/create-worktree.sh" "$REPO_PATH" "$WORKSPACE_ROOT" "$BRANCH" "$BASE_COMMIT"
脚本输出 WORKTREE_PATH。后续修改、Review、测试、提交和推送全部在该 worktree 中执行。
修复 worktree 创建成功后,使用 "{baseDir}/scripts/cleanup-diagnosis.sh" "$REPO_PATH" "$WORKSPACE_ROOT" "$DIAGNOSTIC_PATH" 移除干净的诊断 worktree。用户只要求诊断或任务在诊断阶段停止时,也必须在输出结果前执行该清理脚本。清理脚本不使用 --force;失败时保留路径并报告。
基础 commit 只作为新分支起点。不得切换或修改 repos/<repo> 的分支,不得清理、删除或复用未知 worktree。
修复
搜索相关源码、配置、依赖、测试和调用链。只修改当前 BUG 所需文件,遵循仓库风格,修复根因,不添加硬编码特例、无依据的兼容分支或无关重构。
不修改缓存、构建产物、生成文件或第三方代码;需要调整生成内容时修改其源或生成配置。不删除未知文件,不覆盖原仓库已有修改。
Review
独立 Review 全部 diff:
git -C "$WORKTREE_PATH" status --short
git -C "$WORKTREE_PATH" diff --stat
git -C "$WORKTREE_PATH" diff
git -C "$WORKTREE_PATH" diff --check
确认修改解决根因且范围最小,没有明显的空值、生命周期、异步、线程、资源释放或状态同步缺陷;公共 API、数据格式和既有调用方保持兼容,除非任务明确要求改变。排除生成文件、缓存、调试日志、临时文件、密钥、敏感信息和无关改动。
发现问题时修正并重新执行完整 Review。Review 不通过时禁止提交和推送。
测试
优先运行仓库文档、CI 或现有脚本指定的相关验证,再执行与复现步骤直接相关的最小测试和 git diff --check。不要猜测工具路径或测试命令。
测试环境不可用时完成可执行的静态检查,并明确未执行项及原因。测试失败时修复后重新 Review 和测试,最多两轮;仍然失败时不提交、不推送,保留 worktree 并报告。
提交与推送
仅在 Review 和测试通过后,根据 git diff --name-only 审查文件列表并只暂存本次相关路径;不要使用 git add -A。
git -C "$WORKTREE_PATH" add -- <已审查的文件路径...>
git -C "$WORKTREE_PATH" commit -m "fix: <bug summary>"
git -C "$WORKTREE_PATH" push -u origin "$BRANCH"
禁止 force push。认证失败时停止并报告,不把凭据写入 remote URL。不自动创建 MR、合并分支或删除 worktree。
输出结果
报告状态、BUG 名称、根因与证据、修改内容、分支和文件、Review 结论、测试命令与结果、未执行项、推送结果、遗留问题和人工检查风险。
失败时额外说明失败阶段、具体错误、是否修改、是否提交、是否推送和 worktree 路径。