| name | zc-bug-fix |
| description | Use when the user asks to fix a bug, resolve an issue, or provides a bug URL/bug ID from 禅道, GitLab, GitHub, Jira, or similar systems; especially when the work needs a full workflow of reading the bug, fixing code, verifying, creating issue/MR, and writing status back to the tracker. |
Bug-Fix 用户优先分阶段执行协议
本 skill 采用“用户指定优先、前置条件按需补齐”的分阶段流程。 如果用户明确要求“从阶段 4 开始”或“从某个阶段继续”，就从该阶段执行；不要因为固定流程强制退回阶段 0。真正的安全前置条件（保护分支、MR 前禁止回写禅道、bug_type 通过 browser 字段写入等）仍然必须满足。
⛔ 全局禁令（违反任何一条即为严重错误）
| 编号 | 禁令 |
|---|
| F1 | 禁止在 develop / main / master 分支上直接 commit 或 push |
| F2 | 禁止无视用户明确指定的起点；缺少当前阶段必需信息时必须先补齐，不能盲目执行 |
| F3 | 禁止在没有创建 MR 的情况下回写禅道 |
| F4 | 禁止把 bug 分类/类型写入评论 — 必须通过脚本写入 browser 字段 |
| F5 | 禁止把 issue / MR 描述内容直接拼成命令行参数 — 必须先写入文件 |
| F6 | 禁止提交与当前 bug 无关的代码改动 |
| F7 | 禁止在验证未通过的情况下宣称"已完成" |
| F8 | 禁止不经用户确认就创建分支、推送代码、创建 MR |
启动总则（用户优先）
- 用户明确说“从阶段 N 开始 / 从阶段 N 继续” → 直接从阶段 N 开始。 前面阶段只做必要补位，不做仪式化重跑。
- 用户说明“代码已经改好了 / bug 已经处理了”但没说阶段 → 先分析当前工作区修改、已暂存内容、分支状态、已有 Issue/MR/禅道信息，再从最接近的阶段继续。 这类场景通常优先考虑阶段 4。
- 只在当前阶段缺少关键信息时再提问。 例如当前阶段需要
bug_id / 禅道链接，而上下文里没有时，再向用户索要；不要一上来把阶段 0→3 全部重跑。
- 用户明确要求进入阶段 4 / 5 / 6 / 7，可视为对该阶段动作的授权。 不要针对同一动作重复索要“是否允许创建分支 / 提交 / 推送 / 建 MR”。
- 真正的硬前置条件不能跳过。 尤其阶段 7 之前，必须有验证结果、远程分支、
ISSUE_URL、MR_URL。
阶段 0: 按需检查配置
只有当当前或下一步需要访问禅道 / GitLab 时才执行本阶段。
fetchcreate-issuecreate-mrzentao-writeback- 备用的
zentao-confirm / zentao-set-browser-type / zentao-resolve
如果用户从阶段 4 开始，且当前只需要分析现有改动、创建分支、提交、推送，可暂不执行本阶段。
执行：
python3 $SKILL_DIR/scripts/bugfix_flow.py check-config
如果输出 CONFIG_OK： 进入阶段 1。
如果输出 MISSING_CONFIG 或 MISSING_FIELD： ⛔ 立即停止，告知用户创建配置文件：
cp $SKILL_DIR/zc-bug-fix.config.example ./zc-bug-fix.config
⛔ 配置不完整时，禁止执行依赖配置的后续阶段。
阶段 1: 读取禅道 Bug
仅在需要补齐 Bug 背景或缺少 bug_id / 禅道链接时执行。
- 如果用户已经提供了足够的 Bug 信息，或当前从阶段 4 / 5 / 6 / 7 继续且所需信息已齐，可以不回头强制执行本阶段。
- 如果当前阶段需要引用禅道 Bug，但上下文里没有
bug_id 或禅道链接，先向用户索要，再继续。
执行：
python3 $SKILL_DIR/scripts/bugfix_flow.py fetch <bug_id>
必须从返回的 JSON 中提取以下信息：
- Bug 标题、严重程度、优先级
- 环境信息（版本、硬件）
- 重现步骤
- 期望结果 vs 实际结果
- 日志/报文（如有）
- 相关人员：报告人（openedBy）、定位人、验证人
同时完成 Bug 根因分类预判：
阅读 Bug 内容后，从下方分类表选择一个最贴近根因的中文分类名。低置信度且准备进入阶段 7 前，才需要向用户补确认。此分类将在阶段 7 通过脚本写入禅道 browser 字段。
允许的分类（必须精确匹配）：
| 分类 |
|---|
| 需求不清问题 |
| 需求错误问题 |
| 设计_系统整体设计问题 |
| 设计_功能间接口问题 |
| 设计_功能交互问题 |
| 设计_边界值设计问题 |
| 设计_流程逻辑设计问题 |
| 设计_算法设计问题 |
| 编码_流程逻辑实现问题 |
| 编码_编程规范语法问题 |
| 编码_编程规范内存问题 |
| 编码_编程规范初始化 |
| 编码_编程规范函数用错 |
| 编码_编程规范指针调用 |
| 编码_代码合并问题 |
| 编码_模块间接口问题 |
| 编码_库使用问题 |
| 编码_库修改问题 |
| 编码-内核保护机制问题 |
⛔ 禁止选择：空值、继承或历史遗留、未明确定位、非问题。
⛔ bug_type 不是评论内容 — 是一个用于写入 browser 字段的分类标签。
检查点： 向用户报告 Bug 摘要和预判分类，确认理解正确后进入阶段 2。
阶段 2: 分析并修复代码
要求：
- 搜索定位相关代码
- 先读文件再修改 — 禁止盲改
- 只修改与当前 Bug 直接相关的代码
- 所有新增/修改的函数必须补中文注释
- 必须保证编译通过，且修改的代码静态检查无新警告
如果用户已经改好了代码并要求从阶段 4 或更后阶段继续：
- 不要强制回到“重新修复代码”的流程。
- 先分析当前工作区 / 已暂存改动（
git status、git diff、git diff --cached）。
- 提炼修改文件、根因、修复思路、潜在影响，作为阶段 4 / 5 / 6 的输入。
- 如果发现明显与当前 Bug 无关的改动，提醒用户并在阶段 4 只提交相关文件。
⛔ 本阶段禁止创建分支、推送代码、操作禅道。
检查点： 修改完成后，列出所有改动文件和修改摘要；如果用户已经明确要求继续推进，不必在这里停住等待。
阶段 3: 按需自测验证
如果用户明确要求从阶段 4 开始，不要机械退回阶段 0；优先利用用户已提供的验证结果。只有在准备进入阶段 7 / 8，或你无法说明验证结果时，才补做必要自测。
建议按以下顺序补齐验证证据：
- 扫描代码库(包含.test等隐藏目录)，运行相关测试用例（如果有）
make -C .test 2>/dev/null || true
- 如果有类似 meter-protocol-serial 的串口通讯skill，必须根据修改的内容，发送、读取相关协议报文进行自测验证，后续把自测的相关报文附加到议题中。
⛔ 如果当前目标是进入阶段 7 / 8，验证未全部通过时必须返回阶段 2 修复。
检查点： 向用户报告自测验证结果；如果用户已经明确要求继续推进，可直接进入阶段 4，但进入阶段 7 / 8 前必须能说明验证结果。
阶段 4: 创建分支 + 提交 + 推送
⛔ 必须有用户明确意图才能执行本阶段。 用户直接说“从阶段 4 开始”或“帮我提交并推送”或“BUG已经改完了，从后面的阶段开始”即可视为已授权且从该阶段直接开始，不要重复追问。
4.0 如果代码已经存在，先分析当前修改：
- 查看
git status --short
- 查看
git diff --stat、git diff、git diff --cached
- 提炼修改文件、根因、修复思路、验证摘要
- 确认本次提交只包含与当前 Bug 直接相关的改动
如果缺少 bug_id 或禅道链接： 先向用户索要。分支名、提交信息、Issue/MR 模板都依赖它。
4.1 创建 bugfix 分支（脚本自动从 develop 创建）：
python3 $SKILL_DIR/scripts/bugfix_flow.py create-branch <bug_id> <short-desc>
分支名格式：bugfix/<bug_id>-<short-desc>
4.2 提交代码（只提交相关文件）：
git add <file1> <file2> ...
git commit -m "fix(bug#<bug_id>): <简要描述问题和修复方案>"
⛔ 禁止 git add . 或 git add -A。只添加与本次修复相关的文件。
⛔ 禁止在 develop/main/master 上 commit。脚本会拒绝。
4.3 推送分支（脚本自动拒绝推送到保护分支）：
python3 $SKILL_DIR/scripts/bugfix_flow.py push-branch
检查点： 确认远程分支已创建。记住分支名，阶段 6 需要用。
阶段 5: 创建 GitLab Issue
如果用户明确要求从阶段 5 开始，即视为允许创建 Issue；不要再重复询问。若缺少禅道链接 / bug_id，先向用户索要，因为模板必须引用它。
5.1 准备 Issue 内容：
参考模板 $SKILL_DIR/templates/issue_6d_template.md，将完整 6D 内容写入文件：
cat > /tmp/issue_<bug_id>.md << 'EOF'
... 6D 内容 ...
EOF
Issue 必须至少包含：
- 禅道链接
- Bug 描述（环境、步骤、期望、实际、日志）
- 根因分析（根因、直接原因、代码位置、为什么没发现、检讨）
- 解决方案（思路、修改点、理由、副作用评估）
- 验证结果
- 黑盒测试建议
- 后续改进
- 责任人
5.2 创建 Issue：
python3 $SKILL_DIR/scripts/bugfix_flow.py create-issue <bug_id> /tmp/issue_<bug_id>.md "bug,<标签>"
检查点： 从脚本输出的 JSON 中提取 web_url 字段，保存为 ISSUE_URL。阶段 7 必须使用。
格式形如：http://172.17.0.100:8080/<group>/<project>/-/issues/<number>
阶段 6: 创建 GitLab MR
如果用户明确要求从阶段 6 开始，即视为允许创建 MR；不要再重复询问。MR 描述中的修复内容、根因、修改文件、验证结果应优先复用前面已分析好的信息，而不是重新回退到阶段 0。
6.1 准备 MR 描述：
参考模板 $SKILL_DIR/templates/mr_template.md，将 MR 描述写入文件：
cat > /tmp/mr_<bug_id>.md << 'EOF'
... MR 描述 ...
EOF
MR 描述必须包含：修复内容、根因、修改文件、验证结果、禅道链接、Issue 链接、责任人。
6.2 创建 MR：
python3 $SKILL_DIR/scripts/bugfix_flow.py create-mr <bug_id> "bugfix/<bug_id>-<short-desc>" /tmp/mr_<bug_id>.md
检查点： 从脚本输出的 JSON 中提取 web_url 字段，保存为 MR_URL。阶段 7 必须使用。
格式形如：http://172.17.0.100:8080/<group>/<project>/-/merge_requests/<number>
阶段 7: 回写禅道（一条命令完成全部操作）
如果用户直接要求从阶段 7 开始，可以直接准备本阶段；但只补齐本阶段缺少的关键信息，不要为了“走流程”回头重跑无关阶段。
⛔ 前置条件（全部满足才能执行）：
- ✅ 阶段 3 验证已通过
- ✅ 阶段 4 代码已 push 到远程
- ✅ 阶段 5 已创建 Issue，有 ISSUE_URL
- ✅ 阶段 6 已创建 MR，有 MR_URL
- 缺少任何一项，⛔ 禁止执行本阶段
使用一条命令完成全部禅道回写：
python3 $SKILL_DIR/scripts/bugfix_flow.py zentao-writeback <bug_id> "<bug_type>" "<ISSUE_URL>" "<MR_URL>"
这条命令会自动完成以下四步：
- ✅ 检查 Bug 当前状态（避免重复操作）
- ✅ 确认 Bug — 评论自动附带 Issue 可点击链接
- ✅ 设置 Bug 分类到
browser 字段（不是评论！）
- ✅ 解决 Bug — 评论自动附带 MR 可点击链接，自动转派给项目负责人
参数说明：
| 参数 | 内容 | 示例 |
|---|
bug_id | 禅道 Bug 编号 | 5245 |
bug_type | 阶段 1 预判的中文分类名 | "编码_流程逻辑实现问题" |
ISSUE_URL | 阶段 5 获得的 GitLab Issue URL | "http://172.17.0.100:8080/grp/proj/-/issues/42" |
MR_URL | 阶段 6 获得的 GitLab MR URL | "http://172.17.0.100:8080/grp/proj/-/merge_requests/9" |
⛔ 四个参数全部必填 — 脚本会拒绝不完整的调用
⛔ 严禁手动拼接禅道 API 调用来替代本命令
⛔ 严禁把 bug_type 写入评论 — 它通过脚本写入 browser 字段
检查点： 确认脚本输出 ✅ 禅道回写完成。如果失败，查看错误信息并使用备用命令（见文末）。
阶段 8: 总结报告
向用户输出最终总结表格：
| 项目 | 内容 |
|---|
| 禅道 Bug | #bug_id - 标题 |
| Bug 分类 | bug_type（已写入 browser 字段） |
| 修复分支 | bugfix/bug_id-short-desc |
| GitLab Issue | ISSUE_URL |
| GitLab MR | MR_URL |
| 修改文件 | 文件列表 |
| 验证结果 | 静态检查 ✅ / 构建 ✅ |
附上需要硬件/协议人工验证的测试场景表。
备用命令（仅在 zentao-writeback 整体失败时逐步补救）
python3 $SKILL_DIR/scripts/bugfix_flow.py zentao-confirm <bug_id> "已创建 GitLab issue: <ISSUE_URL>"
python3 $SKILL_DIR/scripts/bugfix_flow.py zentao-set-browser-type <bug_id> "<bug_type>"
python3 $SKILL_DIR/scripts/bugfix_flow.py zentao-resolve <bug_id> "已创建 GitLab MR: <MR_URL>" "" "<bug_type>"
配置说明
配置文件位于项目根目录 zc-bug-fix.config。
环境变量 ZC_BUG_FIX_CONFIG 可覆盖路径（相对路径按项目根目录解析）。
必填字段：
| 字段 | 说明 |
|---|
ZENTAO_URL | 禅道地址 |
ZENTAO_ACCOUNT | 禅道账号 |
ZENTAO_PASSWORD | 禅道密码 |
GITLAB_URL | GitLab 地址 |
GITLAB_TOKEN | GitLab Personal Access Token |
GITLAB_PROJECT_ID | GitLab 项目 ID |
TARGET_BRANCH | MR 目标分支（默认 develop） |
PROJECT_OWNER | 项目负责人禅道用户名（bug 解决后转派） |
初始化：
cp $SKILL_DIR/zc-bug-fix.config.example ./zc-bug-fix.config
文件结构
$SKILL_DIR/
├── SKILL.md ← 本文件（用户优先协议）
├── zc-bug-fix.config.example ← 配置模板
├── scripts/
│ ├── bugfix_flow.py ← 主控脚本（优先使用）
│ ├── check_config.py ← 配置检查
│ ├── config_paths.py ← 路径解析
│ ├── zentao.py ← 禅道 API
│ └── gitlab.py ← GitLab API
├── templates/
│ ├── issue_6d_template.md ← Issue 6D 模板
│ └── mr_template.md ← MR 描述模板
└── tests/
└── test_config_paths.py ← Python 测试（pytest）
