# Repo Bugfix

> 诊断和修复 Git 仓库中的 BUG。分析请求只做只读诊断；用户明确要求修复时，在独立 worktree 中完成最小根因修复，经 Review 和测试后提交并推送。

- Skill: `crownjoker07/repo-bugfix` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add crownjoker07/repo-bugfix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crownjoker07/repo-bugfix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: CrownJoker07 (https://skillmd.com/u/crownjoker07)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/crownjoker07/repo-bugfix

---


# Repository Bugfix

按照“确认仓库 → 读取材料 → 创建诊断 worktree → 诊断 → 授权门槛 → 创建修复 worktree → 修复 → Review → 测试 → 提交推送”的顺序处理 BUG。不切换、更新或读取 `<workspace>/repos/<repo>` 的工作区内容。

## 确认仓库

用户明确提供仓库目录时直接使用。用户只提供仓库名时，使用当前运行环境明确提供的 workspace 根目录，在 `<workspace>/repos` 的直接子目录中，将该名称与目录名或 `origin` 仓库名精确比较；可忽略大小写和末尾的 `.git`。没有唯一匹配或运行环境没有提供 workspace 时，要求用户补充仓库路径。

不要扫描整个用户目录、磁盘、其他常用目录或未向 Agent 公开的路径；不做部分匹配，不猜测项目，不选择名称相近的仓库。

解析绝对路径。检查仓库状态：

```bash
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 自身目录中的脚本运行：

```bash
"{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 中执行。

## 诊断

修改前确认：

1. 当前表现是否违反可验证的预期。
2. 是否可能属于正常规则、配置、数据延迟、平台差异或显示口径。
3. 根因位于当前仓库中的哪个模块和调用链。
4. 当前仓库是否包含可以修复根因的源文件。
5. 是否缺少复现条件、目标数值或业务规则。

从日志和堆栈向调用方追踪，结合功能名、配置、数据和相似实现定位。结论引用当前证据，并尽可能给出文件、符号、当前有效行号、调用链、正常与异常实现的差异以及最小修复方案。

- 不是 BUG：解释当前表现后停止。
- 证据不足：只请求阻断当前步骤的最小补充后停止。
- 根因不在当前仓库：说明证据指向的模块后停止。
- 可以在仓库中修复：根据授权门槛继续。

没有明确依据时不得猜测业务规则或目标数值。

## 授权门槛

- 用户只要求判断、分析或定位：只输出诊断，不创建修复分支，不修改、提交或推送。
- 用户明确要求修复：创建 worktree，并在 Review 和测试通过后提交、推送分支。

不要把诊断请求自动升级为修复。当前 Agent 或运行环境的更高优先级授权规则始终优先。

## 创建 Worktree

分支命名优先遵循仓库约定，没有约定时使用 `fix/<bug-name>`。同名本地或远程分支已存在时追加 `YYYYMMDD-HHMM`。

使用诊断脚本输出的 `BASE_COMMIT` 作为修复分支起点，运行：

```bash
"{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：

```bash
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`。

```bash
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 路径。

