从 Skills 到可靠的 Bugfix Agent
一次 Bug 修复看似可能只是 “改几行代码”，实际上一般会横跨禅道、语雀文档、Git 分支、异常代码定位、独立 CodeReview、GitLab MR、GitLab CI 和 OMP 部署环境等系统的多个动作。其中任何一个环节单纯依靠口口相传的约定，都会让整个流程链路容易出现断裂。
Bugfix Agent 的目标不是让 Agent 无限制地自动操作，而是把这些系统、步骤的约定固化为一个可恢复、可审核、会在不确定时暂停的完整工作流。
我们是袋鼠云数栈 UED 团队，致力于打造优秀的一站式数据中台产品。我们始终保持工匠精神，探索前端道路，为社区积累并传播经验价值。
本文作者：琉易
面向需要把禅道 Bug 修复推进到 Gitlab、CI 和 OMP 的研发团队
禅道：产品 BUG 管理平台
OMP：内部多环境管理平台（部署）
背景
一次 Bug 修复看似可能只是 “改几行代码”，实际上一般会横跨禅道、语雀文档、Git 分支、异常代码定位、独立 CodeReview、GitLab MR、GitLab CI 和 OMP 部署环境等系统的多个动作。其中任何一个环节单纯依靠口口相传的约定，都会让整个流程链路容易出现断裂。
Bugfix Agent 的目标不是让 Agent 无限制地自动操作，而是把这些系统、步骤的约定固化为一个可恢复、可审核、会在不确定时暂停的完整工作流。
下方描述以所在公司的内部链路为例，通用场景可参考设计思路。
Bugfix 链路
日常的 Bug 修复通常有三个痛点：
- 信息分散：禅道现象、语雀技术文档补充、分支命名规则与切换、提交信息规范、MR 描述模板、验收条件等需要人工拼接执行或等待 AI 执行后手动要求进入下一流程
- 外部动作不可逆：切分支、提交、创建 MR、部署都可能因重试或异常中断而重复执行
- 自动化容易越权：OMP 环境不唯一、部署服务无法映射、bugfix 改动要求证据不足时，继续 “猜” 比暂停更容易出现偏差
因此，一个有用的 Bugfix Agent 不应只回答 “怎么修”，还必须回答：
- 当前是否具备继续执行的证据？
- 这个外部动作是否已经执行过？
- 失败后能否从正确阶段恢复（Loop）？
- 怎么独立判断修复是否匹配问题（Review）？
设计目标
目标与约束
自动推进，但不替人做未经授权的决定
Bugfix Agent 的核心原则是：把确定性的步骤自动化，把不确定的决策显式交还给用户。
| 目标 | 对应约束 |
|---|---|
| 自动推进 | 禅道、分支、修复、MR、部署等动作按阶段衔接 |
| 修改代码前由用户确认修改思路，提交前由用户确认修改内容； | |
| 敏感步骤由用户确认，减少返工；同时支持发送 “全自动” 直接交付最终结果 | |
| 不重复副作用 | MR、OMP 部署前读取运行状态，已有产物不重复创建 |
| 不盲猜 | productName 缺失、来源分支不存在、环境/服务不唯一时暂停 |
| 可独立复核 | 修复 Agent 与 Reviewer 分离，审核结论控制提交限制 |
| 跨宿主复用 | Codex 与 Claude Code 共用一份业务协议，仅 adapter 不同 |
流程可靠性
可靠性来自停止条件，而不是更多自动操作
流程最有价值的部分往往不是 “自动完成”，而是知道什么时候不该继续：
- 本地 git 工作区有代码变更，此时暂停
- Reviewer 无法建立判断证据（最多两轮 Loop），不强行提交
- CI、OMP 未被用户要求，不擅自轮询 CI 状态/部署状态
- OMP 环境或服务不唯一，不默认选择
这些停止条件让 Bugfix Agent 的行为可解释，用户看到暂停原因、已完成内容和需要确认的事项，就能准确地接住流程，而不是让用户最终面对一个不可追踪或复杂回撤的失败结果。
架构设计
薄 Skill、共享协议、宿主 Adapter
Bugfix Agent 没有把所有规则塞进单个 Agent，而是拆成三个层次：
薄入口 Skill
入口只负责触发和编排，不负责切分支、git commit、CI、OMP 等业务细节：
# Codex
$bugfix-workflow <bugId|bug-url> <appName> <version> [OMP] [CI轮询]
# Claude Code
/bugfix-workflow <bugId|bug-url> <appName> <version> [OMP] [CI轮询]
自然语言同样可触发，但仍需补齐最关键的 Bug ID，子产品名称和版本可以通过禅道信息推断。这样既保留对话式使用体验，也避免输入信息不足时误入错误分支或环境。
共享协议
references/workflow-protocol.md 是唯一的业务规则来源。它定义：
- 如何用禅道信息判断分支前缀
fix与hotfix - 分支准备、定制化标识传递和来源分支校验
- CI、OMP 的查询与持续监控边界
- 暂停条件、重试上限和统一对外输出的格式
把规则集中在协议里，Codex 的 toml Agent 与 Claude Code 的 Markdown Agent 只保留角色、权限与协议入口，避免两端规则逐渐漂移。
运行状态
bugfix_run.py 用 repo + bugId 识别一次运行，持久化处理分支、MR、CI、OMP 和重试次数。每次 git commit、push、创建 MR 或提交部署前先读取状态：如果已有 commit SHA、MR ID 或 OMP deployId，就不重复执行。
保留运行状态可以让 “重试一次” 不再等价于“再创建一次 MR 或再部署一次”。
灵活配置
- 当 BUG 较为简单时，可以要求
全自动推进，直接输出结果 - 当 BUG 在本地服务中排查定位完成时，明确思路后可以直接把切分支、创建 MR 等繁琐动作交给
Bugfix Agent执行 - 当 BUG 简单且已明确修改的代码无异常时，可以要求跳过独立审核 Review 步骤，节省 Token
Bugfix 实际流转
读取事实依据，暂不改代码
Bugfix Agent 先通过 zentao-api 获取 Bug 详情；若禅道内容包含或单独提供语雀技术文档链接，再使用 yuque-reader 读取语雀文档补充上下文。随后提取禅道标题、现象、复现路径、影响版本、关键字段和验收点。
分支准备，保护本地工作
在任何分支切换前执行 git status --porcelain，工作区有已跟踪、未跟踪或暂存改动时暂停，避免自动化覆盖本地工作。
分支命名和来源分支的判断交给 git-branch-naming。处理分支创建前必须 git fetch origin，切到来源后必须 git pull。若来源只在远程存在，则创建跟踪分支；本地与远程都不存在则暂停。
对于 hotfix，来源必须按 release 分支规则确定。来源分支中版本号后的定制化标识需要保留到处理分支；标准 test 分支的 v{迭代号} 不被当作定制化标识。
执行与审核分离
执行 Agent bugfix-worker 先使用 superpowers:systematic-debugging 建立代码根因证据，再做最小必要修复。修复完成后，主会话将分析和代码 diff 分派给只读 Reviewer。Reviewer 检查：
- 根因是否匹配禅道现象和验收点
- 修改范围是否过大
- 是否遗漏同类入口或边界状态
- 是否存在明显回归风险
Reviewer 给出 “需要修复” 时，执行 Agent bugfix-worker 回到修复阶段；
证据不足、需求歧义或无法判断时，流程暂停并请求用户确认。这样，独立审核是 commit 前的重要限制，而不是 MR 创建后的装饰动作。
验证和依赖恢复
本地验证优先读取 .gitlab-ci.yml 及其包含配置，运行与改动相关且可本地执行的检查。
若失败明确来自依赖不完整，例如缺少 node_modules、command not found 或 Cannot find module，workflow 会先保存当前分支、未跟踪文件列表和已跟踪 diff 临时补丁，再执行一次：
pnpm install --frozen-lockfile
安装后必须确认仍在原处理分支、业务 diff 没有丢失、pnpm-lock.yaml 与其他已跟踪文件没有额外变化，然后重跑原检查。安装失败、无法恢复或修复超过两轮时，流程暂停。
MR、CI 与 OMP
提交阶段只暂存本次修复相关文件，使用 commit-message 生成提交，再用 dt-create-mr 创建 GitLab MR。
CI 不是默认轮询项：用户明确要求查询时，按 MR ID 查询；只有要求等待、监控或通知时，才创建 gitlab-mr-ci-watch heartbeat。这样可以避免一个普通修复在用户未授权时持续访问外部系统。
OMP 默认不执行部署，要求部署时会先通过 omp-skill 获取真实环境，不凭名称猜 envId，再按 标品/定制化、目标版本、定制化标识、环境名和服务名称逐层缩小候选。环境或服务名称无法唯一映射时暂停。
实践记录
在 Codex 和 ClaudeCode 中 plugin 的形式进行分发安装：
在实际使用过程中发现，禅道 BUG 描述等上游资料对解决问题的成功率有较高影响。
目前部分重交互的子产品有些禅道 BUG 标题作为问题描述，内容为一张 gif，这样的搭配对人友好，但对 AI 不够友好，部分不能识图的文本模型仅能通过 zentao-api Skill 的文字 OCR 理解禅道信息，不如直接读图片的效果好。
这往往需要开发人员收到禅道 BUG 后，依据开发经验在点击确认 BUG 时备注基于开发者视角更详细的问题描述。
添加较为详细的上下文后，开发者可以借助 Bugfix Agent 自动完成后续一长串的操作链路，完成后会给到 MR 地址、部署环境等相关信息。
Token 节省优化
大仓库分支定向查询
当 Monorepo 仓库以分支区分子产品时，累积分支如果超过数千，对于确认来源分支会有较大的 Token 消耗，因此使用子产品名称前缀及 --list 进行定向模式的查询。
主规约解耦与安全瘦身
主规约 workflow-protocol.md 一度超过 25 KB，主会话每轮执行都需要读该文档，将底层执行细节分别下沉。
确认环节支持跳过 Review
独立审核环境会重新读一遍上游材料及代码变更以判断是否能完成 BUG 修复，简单问题支持跳过可节约耗时与 Token。
写在结尾
一个 Bugfix 的 Agent 是否可靠，不取决于它能调用多少工具，而取决于它是否能在正确的时机重试或停止、保存上下文、避免重复外部动作，并能独立复核。Bugfix Agent 把这些约束放在 Skill、共享协议、SubAgent 和状态脚本的边界上：Skill 负责入口和编排，协议负责规则，执行 Agent 负责修复，Reviewer 负责挑战结论，状态脚本负责让流程可以恢复。
当你准备结合自己的实际场景进行尝试时，参考设计思路，按你的日常步骤拆解出原子化的 Skill，满足每个动作的落实位置，使用主 Agent 当作关节串起一整条链路。
最后
欢迎关注【袋鼠云数栈 UED 团队】~
袋鼠云数栈 UED 团队持续为广大开发者分享技术成果，相继参与开源了欢迎 star
浙公网安备 33010602011771号