---
name: 调试修复
slug: tri-fix
version: 1.4.0
displayName: 调试修复
description: 调试修复下游执行 skill（I12）——先造出一条能变红的紧密反馈循环，再定位根因，最后最小化修复。当用户说「调试」「debug 一下」「查一下这个 bug」「帮我看看这个报错」，或报告程序报错/崩溃/抛异常/跑不通/结果不对/数据错乱/偶发失败/线上才复现/变慢了/接口超时时激活；也在 tri-intent 快照 §三 下游路由建议指向本 skill 时激活。目标代码尚不存在的新功能交 tri-coding，只看不改的代码审查交 tri-review，只求解释不求修复交 tri-ask。支持独立安装，含上游依赖检测三态逻辑（快照模式/引导安装/降级模式）。
summary: 以「没有能变红的循环就没有假设阶段」为铁律的系统化调试方法论——6 阶段（建立反馈循环→复现最小化→假设生成→插桩验证→修复回归→清理复盘）串联三道审批门，强制因果确认与最小化修复。
tags: [debugging, bug-fix, root-cause, feedback-loop, workflow, approval-gate, regression-test]
license: MIT
---

# 调试修复（下游路由 · I12）

> 本 skill 是 tri-intent 的下游执行 skill，依据快照 `snapshot.md` §三 结构化结论自主管理完整调试工作流。
> 用户心智：把 AI 当诊断专家，期望精准定位根因并彻底修复，而非打补丁。

## 强制执行契约（Execution Contract · 最高优先级）

0. **版本检查前置硬门（第零步）**：MUST 先通过 §版本检查与更新机制（连接 skillhub 校验版本，非最新版 MUST 自动执行 `skillhub upgrade <slug>` 升级；升级成功后继续，升级通道不可用则标注 D 态降级继续）——此为执行流程第零步，优先于后续所有步骤。版本检查完成前 NEVER 进入后续步骤。本条目优先级高于所有其他强制前置条目。

1. **强制前置**：收到 tri-intent 快照且 `下游路由建议` 指向本 skill，MUST 先读取快照 §三，再按调试工作流串行推进。独立使用时（未经 tri-intent 路由）MUST 先走 §上游依赖检测 判定模式。
2. **红循环铁律（本 skill 的第一性规则）**：**没有能变红的反馈循环，就没有假设阶段。** 「红」= 一条你已至少真实运行过一次、且在本 bug 上失败的命令。在这条命令存在之前，MUST 停留在阶段 1；此时唯一允许的动作是构造循环，代码阅读只服务于构造循环，NEVER 由代码阅读直接跳到根因结论或修复补丁。
3. **逃生舱（无法建立循环时的唯一出口）**：若穷尽 §阶段 1 构造方式仍无法让循环变红，MUST 停下并向用户明示：① 已尝试过的构造方式清单；② 索取三者之一——(a) 能复现问题的环境访问权限、(b) 抓取产物（HAR / 日志转储 / core dump / 带时间戳录屏）、(c) 添加临时生产插桩的许可。在拿到其一之前 MUST 停在阶段 1，NEVER 以「先猜一个方向试试」推进到阶段 3。
4. **双审批门 + 执行前确认 + 任务清单硬性规则**：I12 属设计类，MUST 严格串行经过**两道落盘审批门 + 执行前确认 + 任务清单执行**；修复代码只在门③确认通过后随 `fix-tasks.md` 执行产出：
   - **门①（故障确认）**：先产出 `bug-report.md`（故障报告），含能变红的反馈循环 + 最小化复现用例，向用户结构化复述供审计；**通过后**方可进入门②。
   - **门②（诊断审计）**：据已审批的 bug-report.md 产出 `diagnosis.md`（根因诊断报告），含 3-5 个可证伪假设 + 因果确认证据，再交用户审计；**通过后**方可产出 `fix-tasks.md`。
   - **门③（执行前确认）**：门②通过后产出 `fix-tasks.md`（原子化修复任务+回归测试清单），**进入执行前 MUST 主动询问用户两件事**：① 是否需要调用其它 skill 协同（如 tri-review 代码审查、tri-coding 技术栈加载等）；② 是否有需要补充的约束/素材。用户确认无补充 → 进入执行；用户提出补充 → 据反馈更新 `fix-tasks.md`（涉及诊断缺陷则回退门②更新 `diagnosis.md`）后再次确认，**通过后方可执行**，禁止跳门抢跑。
   - **任务执行**：门③确认通过后，按 `fix-tasks.md` 清单逐项执行（含回归测试，测试不过回炉 fix-tasks.md），执行完成产出 `fix-report.md`（修复报告）。**复选框状态切换规则（核心机制）**：fix-tasks.md 中每个原子任务和测试条目均含「完成状态」复选框字段，默认 `` `- [ ]` ``（未完成）；**执行完成** → MUST 切换为 `` `- [x]` ``；**回炉重做** → MUST 重置回 `` `- [ ]` ``。复选框状态与「状态明细」字段同步更新。
   - 完整链路：`bug-report.md → 审计① 通过 → diagnosis.md → 审计② 通过 → fix-tasks.md → 执行前确认③ 通过 → 执行 → fix-report.md`。任一门未通过则携反馈回炉，不得跳门或抢跑修复。
5. **最小化原则（门禁规则）**：进入执行阶段前 MUST 校验变更范围是否最小化——变更仅落在根因处，重构与优化留给后续独立任务。若执行中发现需扩大变更范围（如关联缺陷、架构问题），MUST 向用户说明并确认后追加到 `fix-tasks.md`，NEVER 默默扩大范围。
6. **职责边界**：本 skill 负责「读取快照 → 建立反馈循环 → 复现最小化 → 根因诊断 → 修复方案 → 修复执行 → 回归验证 → 清理复盘」全链路。意图识别（由 tri-intent）、新功能编码开发（由 tri-coding）、代码审查（由 tri-review）不属于本 skill。
7. **自检**：作答前用一句话声明「本次意图=I12，已读取快照，当前方法论阶段=<1-6>，红循环状态=<已变红/未建立/逃生舱待补材料>」，若与上述规则冲突则停止并纠正。**阶段号一律引用 §系统化调试方法论 的 1–6 编号，全文不存在第二套阶段编号。**

## 触发时机

**激活分支**（任一命中即进入本工作流；非快照来源者先走 §上游依赖检测）：

| 触发分支 | 典型信号 | 阶段调整 |
|---|---|---|
| 快照路由 | tri-intent 快照 §三 `下游路由建议` 指向本 skill 且 `intent.L2` = I12 | 标准链路 |
| 用户口语触发 | 「调试」「debug 一下」「查一下这个 bug」「帮我看看这个报错」「定位一下原因」「为什么会这样」（伴随具体故障） | 标准链路 |
| 故障症状触发 | 报错 / 崩溃 / 抛异常 / 白屏 / 跑不通 / 结果不对 / 数据错乱 / 死锁 / 内存泄漏 / 测试挂了 | 标准链路 |
| 性能回归触发 | 「变慢了」「超时」「以前很快现在很卡」「接口 RT 涨了」「CPU 打满」 | 阶段 4 走**性能分支**（基线测量 + 二分，不打日志） |
| 偶发/非确定触发 | 「偶尔失败」「重跑就好了」「flaky」「线上才复现」「压测下才出」 | 阶段 1 目标改为**提高复现率**而非干净复现 |
| 无法本地复现 | 只有生产日志 / 用户截图 / HAR / 崩溃堆栈，本地跑不出来 | 阶段 1 先评估逃生舱（契约 §3） |

**意图编码范围**：I12 调试修复。

**不由本 skill 处理**（命中以下信号 MUST 指向对应 skill，NEVER 在本工作流内代办）：

| 信号 | 归属 |
|---|---|
| 「加个功能」「实现一个 X」——目标代码尚不存在，无可复现故障 | tri-coding（I11） |
| 「帮我 review 这段代码」——只看不改，无具体故障现象 | tri-review |
| 「这个架构该怎么改」「先出个方案」——无可复现故障，求规划 | tri-plan（I13） |
| 「这个报错是什么意思」——只求解释，不求定位与修复 | tri-ask（I01–I05） |

## 上游依赖检测（独立使用时）

> 本 skill 可独立安装。激活时 MUST 检测上游 tri-intent skill 是否可用，据检测结果选择执行模式：

| 模式 | 触发条件 | 行为 |
|---|---|---|
| **A · 快照模式** | 按 tri-intent §快照定位契约 定位到**可用快照**（`.tribro/LATEST.md` 指针 → 会话内最新 → 全局最新且 ≤30 分钟） | 读取快照 §三，按工作流推进（标准模式） |
| **A0 · 待识别** | 有 `tri-intent/` 但无可用快照（或快照已过期/损坏） | MUST 提示用户「本次请求尚未经意图识别」，引导先经 tri-intent 产出快照；NEVER 按空上下文静默执行 |
| **B · 引导安装** | 以上均不满足 | MUST 向用户提示依赖并引导安装 |
| **C · 降级模式** | 用户明确拒绝安装 | 从用户请求自构造等价输入，声明降级模式 |

**模式 B 提示语**：
> 本 skill 依赖 tri-intent 进行意图识别与输入校验。当前未检测到 tri-intent。
> 请安装：`skillhub install tri-intent --dir <目标目录>`
> 安装后重新发起请求，即可获得完整的意图识别→澄清→执行工作流。

**模式 C 降级声明**：
> 用户明确拒绝安装后，从用户请求自构造等价输入（意图判定 + 任务要点 + 交付预期），声明「当前为降级模式，意图识别精度低于完整工作流」。

## 输入契约

读取 `.tribro/snapshots/<命名>.md` 的 §三 结构化结论区：

| 字段 | 用途 |
|---|---|
| `intent.L2_核心意图` | 必须为 I12，否则不应激活本 skill |
| `dimensions.D1_任务领域` | 决定技术栈语境（应为「编程技术」） |
| `dimensions.D2_输入形态` | 是否有报错日志/堆栈跟踪/复现步骤（关键输入） |
| `dimensions.D4_输出期望` | 应为「可执行代码」或「修复补丁」 |
| `任务要点` | 故障现象 + 复现条件 + 期望恢复正常 |
| `交付预期` | 用户期望的修复结果 |

> 若快照 `澄清门状态` = 待澄清，不应激活本 skill——先由 tri-intent 的 clarify-gate 完成澄清。

> **模式 C 降级模式输入**：当用户拒绝安装 tri-intent 时（见 §上游依赖检测 模式 C），从用户原始请求自构造等价输入——意图判定（默认 I12）+ 任务要点（从请求提取故障现象/复现条件/期望恢复）+ 交付预期（从请求推断修复结果），声明降级模式后按工作流推进。

## 职责边界

- **本 skill 负责**：依据快照结论，自主管理调试全链路（故障报告→根因诊断→修复任务→执行→修复报告），产出精准修复及配套链路文档
- **不负责**：意图识别（由 tri-intent）、新功能编码开发（由 tri-coding 的 I11）、代码审查（由 tri-review）、规划方案（由 tri-plan）
- **关键边界**：本 skill「先诊断后修复」——诊断归 bug-report.md/diagnosis.md，修复归 fix-tasks.md/执行阶段；诊断证据链完整之后才动代码
- **与 tri-coding 的协作**：调试过程中可加载 tri-coding 的技术栈 skill（`tri-coding/tech-skills/`）辅助定位技术栈特定的问题模式，加载方式参考 tri-coding 的 registry 驱动机制
- **不触发场景（Not-Trigger）**：本 skill 不接手「目标代码尚不存在的新功能开发」（属 tri-coding 的 I11，本 skill 只修复既有缺陷）；不接手「只审查不改的代码审查」（属 tri-review）；不接手「只求解释不求修复的咨询」（属 tri-ask）；不接手「识别用户意图」（由 tri-intent / 自身快照驱动）。

## 系统化调试方法论（核心能力 · 可扩展）

> 调试方法论是 tri-fix 区别于 tri-coding 的核心差异化能力。融合 **6 阶段反馈循环**（来自 diagnosing-bugs）与 **4 阶段根因验证**（来自 4phase-systematic-debug），形成「建立信号 → 收缩范围 → 生成假设 → 验证根因 → 根治修复 → 清理复盘」的完整方法论。**阶段 1–6 是本 skill 唯一的阶段编号系统**，工作流章节只引用它，不另起编号。

### 核心理念

> **不要猜测，要假设。不要乱试，要验证。不要修补，要根治。**

传统调试最大的问题在于发现问题后立刻跳到「修复」阶段——基于第一个猜测直接改代码。这种模式在复杂系统中成功率极低，往往引入新 Bug 或只修复了表象。本方法论强制在动手修复前完成反馈循环建立和根因验证。

### 阶段 1：建立反馈循环

> **这就是本技能的全部，其余都是机械操作。** 有了一条能让_这个_ bug 变红的紧密信号，二分、假设验证、插桩都只是在消耗这条信号；没有它，盯着代码看再久也无济于事。在这里投入不成比例的精力——**要激进，要有创造力，绝不放弃**。

**构造反馈循环的若干方式——大致按此顺序尝试**：

1. **失败的测试**——在任何能触达 bug 的接缝处编写：单元、集成、e2e
2. **Curl / HTTP 脚本**——对着运行中的开发服务器发请求
3. **CLI 调用**——用固定输入运行，stdout 与已知良好快照做 diff
4. **无头浏览器脚本**（Playwright/Puppeteer）——驱动 UI，对 DOM/控制台/网络断言
5. **回放抓取的 trace**——把真实请求/载荷/事件日志存盘，在隔离环境回放穿越代码路径
6. **一次性测试支架**——启动系统最小子集（一个服务，依赖被 mock），用一次函数调用驱动 bug 代码路径
7. **性质/模糊测试循环**——「偶尔输出错误」类 bug 跑 1000 个随机输入，观察失败模式
8. **二分支架**——bug 出现在两个已知状态（commit/数据集/版本）之间时，把「启动到状态 X、检查、重复」自动化，即可 `git bisect run`
9. **差分循环**——同一输入分别跑新旧版本（或两套配置），对输出做 diff
10. **HITL 脚本**——最后手段。必须由人点击时，用结构化脚本驱动_他们_，捕获输出反馈回来

**收紧循环**：把循环当作一个产品来对待。能更快吗（缓存初始化、跳过无关启动、收窄测试范围）？信号更尖锐吗（断言具体症状，而非「没崩溃」）？更确定吗（固定时间、给随机数种子、隔离文件系统、冻结网络）？——**一个 30 秒又时好时坏的循环几乎等于没有循环；一个 2 秒且确定性的循环才是调试超能力。**

**非确定性 bug**：目标不是干净利落地复现，而是**更高的复现率**。把触发条件循环 100 次、并行化、加压、收窄时间窗、注入 sleep。50% 概率偶发的 bug 可调试；1% 的不可调试——持续提高复现率直到可调试为止。

**当确实无法建立循环时**：按契约 §3 走逃生舱——列出已尝试的构造方式，向用户索取环境访问权限 / 抓取产物 / 生产插桩许可三者之一，在拿到之前停在本阶段。

**完成标准**——你能说出**一条命令**（脚本路径、测试调用、curl），你已**至少真实跑过一次**（贴出调用与输出），并且它：

- [ ] **能变红** —— 驱动真正的 bug 代码路径，断言**用户描述的确切症状**；修好后变绿。判据是「能抓住这个特定的 bug」，而不是「运行不报错」
- [ ] **确定性** —— 每次运行结论一致（偶发 bug：已固定到高复现率）
- [ ] **快速** —— 秒级，而不是分钟级
- [ ] **agent 可运行** —— 可无人值守运行；仅 HITL 脚本方式允许人介入

### 阶段 2：复现 + 最小化

跑循环，看着它变红——bug 出现了。

**确认**：
- [ ] 循环产生的失败模式正是**用户**所描述的——不是恰好邻近的另一个失败。**错的 bug = 错的修复**
- [ ] 失败在多次运行中可复现（或复现率高到足以调试）
- [ ] 已捕获确切症状（错误信息、错误输出、缓慢的耗时），供后续阶段验证修复确实解决了它

**最小化**：把复现收缩到**仍然会变红的最小场景**。一次**单独**切掉一种输入、调用方、配置、数据或步骤，每次切完都重跑循环——只保留对失败起支撑作用的部分。最小复现能缩小阶段 3 的假设空间，并成为阶段 5 的干净回归测试。

**边界测绘**：

| 条件 | 有 Bug | 无 Bug |
|---|---|---|
| 输入类型=A | ✅ | |
| 输入类型=B | | ✅ |
| 并发=1 | | ✅ |
| 并发=10 | ✅ | |

**完成标准**：**每一个剩余元素都起支撑作用**——移除其中任何一个都会让循环变绿。

### 阶段 3：假设生成

> 单一假设生成会把人锚定在第一个看似合理的想法上。**强制 3-5 个排序假设**防止锚定。

**假设生成前的证据增强（三式，按成本从低到高，先做再生成假设——假设质量取决于喂进去的证据）**：

1. **近期变更扫描**：`git diff`/最近提交/新依赖/配置变更/环境差异——「什么变了」往往是最高性价比的第一批假设来源；bug 在变更点附近的比例远超随机分布。
2. **多组件断裂点埋点**：系统有多个组件时（CI → 构建 → 签名，API → 服务 → DB），先在每个组件边界记录进入/离开的数据与环境传递，执行一次收集证据、定位断裂层，再针对该层生成假设——**先定位断裂层，再猜具体原因**，NEVER 跨层盲猜。
3. **正常示例对比（模式分析）**：在同一代码库找到处理同类问题的正常代码，逐项列 出问题代码与它的差异（无论多小，NEVER 预判「这不可能有影响」）；实现某个模式出问题时完整阅读参考实现，理解隐含依赖后再对比。

每个假设必须**可证伪**，说明它会做出的预测：

> 格式：「若 \<X\> 是原因，则 \<改变 Y\> 会让 bug 消失 / \<改变 Z\> 会让它更严重。」

说不出预测的，那是感觉不是假设——丢弃它，或把它打磨到能说出预测为止。

**优先级排序**：按 `可能性(1-5) / 验证成本(1-5)` 排序，优先测试高可能性 + 低验证成本的假设。

**展示给用户**：排序后的清单展示给用户，他们往往有领域知识能瞬间重排（「我们刚对 #3 部署了一次改动」）或知道哪些已被排除。低成本检查点，巨大省时利器。不阻塞——用户不在就按排序继续。

**完成标准**：
- [ ] 至少生成 3 个独立、可证伪的假设（不超过 7 个）
- [ ] 每个假设有对应的实验设计与预测句
- [ ] 假设已按可能性/成本排序
- [ ] 排序清单已展示给用户（非阻塞）

### 阶段 4：插桩验证

> 每个探针都必须对应阶段 3 的某个具体预测。**一次只改一个变量。**

**工具优先级**：
1. **调试器/REPL 检查**——一个断点胜过十条日志
2. **定向日志**——打在能区分假设的边界处
3. 日志范围限定在能区分假设的边界，全局日志再 grep 属于反模式（见 §调试反模式）

**调试日志标签**：每条调试日志打唯一前缀标签 `[DEBUG-a4f2]`，最终清理就变成一次 grep。有标签的日志会被清掉，没标签的会残留。

**假设状态标记**：
- `✅ CONFIRMED`：实验结果与「假设正确」的预期一致 → 进入因果确认
- `❌ REFUTED`：实验结果不一致 → 该假设被证伪，取下一个假设
- `⚠️ INCONCLUSIVE`：无法判别 → 重新设计实验

**因果确认测试**（关键步骤，不可跳过）：
1. 去掉疑似根因 X：验证 Bug 消失 ✓/✗
2. 加回 X：验证 Bug 重现 ✓/✗
3. **因果关系确认**：X 是根因 ✓/✗

**性能分支**：对性能回归，日志通常是错的。改用基线测量（计时支架、`performance.now()`、profiler、查询计划）+ 二分。**先测量，后修复。**

**迭代规则**：
- 假设被证伪 → 回到假设列表取下一个
- 假设被证实 → 因果确认 → 进入修复
- 所有假设被证伪 → 回到阶段 3 重新生成假设
- **最多 3 轮**：全部证伪且未能生成新假设 → 停止并质疑架构——每次修复都暴露新的共享状态/耦合/别处新症状、或修复需要大规模重构才能实现，说明是**架构缺陷信号**而非假设失败；NEVER 未做架构讨论就盲试第 4 次，此时把架构问题写入 fix-report.md 复盘并建议 tri-review 审查（升级求助与架构质疑并行，不互斥）

### 阶段 5：修复 + 回归测试

> **先写回归测试再修**——但仅当存在**正确的接缝**时。

**正确的接缝**：测试在调用点真实复现**真正的 bug 模式**。如果唯一可用的接缝太浅（bug 需要多调用方却只有单调用方测试；单元测试无法复现触发 bug 的调用链），在那里的回归测试只会给人虚假的信心。**如果没有正确的接缝，这本身就是发现**——如实记录「无可用接缝」，交阶段 6 作为架构改进输入。

**修复流程**：
1. 把最小化复现转成该接缝处的一条失败测试
2. 看着它失败
3. 应用修复——变更仅落在根因处
4. 看着它通过
5. 用阶段 1 的反馈循环对原始（未最小化）场景再跑一遍

**回归门禁**（五项，阶段 6 直接引用本清单，不再复述）：
- [ ] 原始复现不再复现（重跑阶段 1 的循环）
- [ ] 回归测试通过（或已记录「无可用接缝」）
- [ ] 全量单元测试通过
- [ ] 全量集成测试通过（如有）
- [ ] Lint / 类型检查通过

### 阶段 6：清理 + 事后复盘

宣布完成前必须满足：

- [ ] §阶段 5 回归门禁五项全过
- [ ] 所有 `[DEBUG-...]` 插桩已移除（用前缀 grep 验证，贴出结果）
- [ ] 一次性原型已删除（或移到明确标注的调试位置）
- [ ] 最终证明正确的假设已写入 commit / PR message——让下一位调试者也能学到

**事后复盘**：问「什么本可以避免这个 bug？」若答案涉及架构改动（没有好的测试接缝、调用方纠缠不清、隐藏的耦合），把具体情况交接给 tri-review 或列为架构改进建议。**在修复落地之后**再给建议——此刻你掌握的信息远多于起初。

### 调试反模式（对照识别）

> 每条给出**特征**（怎么发现自己正在犯）与**替代做法**（改做什么）。执行中命中任一特征，MUST 回到对应阶段。

| 反模式 | 特征 | 替代做法 |
|---|---|---|
| **直觉修复** | 还没有一条能变红的命令就开始改代码；理由是「我大概知道在哪」 | 停在阶段 1，先造出会变红的命令（契约 §2） |
| **单假设锚定** | 只有 1 个「一定是它」的猜测，直接去验证 | 阶段 3 强制 3–5 个可证伪假设并排序 |
| **霰弹插桩** | 大面积打日志再 grep，探针与预测无对应关系 | 每个探针对应一条预测，一次只改一个变量 |
| **症状修复** | 改到「报错不出现了」就收工，未做因果确认 | 阶段 4 三步因果确认：去掉→消失→加回→重现 |
| **错的 bug** | 循环变红了，但红的是邻近的另一个失败 | 阶段 2 逐字比对失败模式与用户描述 |
| **顺手重构** | 修 bug 时一并整理代码/改命名/优化性能 | 变更仅落在根因处；扩大范围先经用户确认追加进 fix-tasks.md |
| **虚假回归** | 在太浅的接缝上写测试，测试绿但 bug 仍可发生 | 如实记录「无可用接缝」，交阶段 6 架构建议 |
| **插桩残留** | 修复合入，`[DEBUG-` 标签留在生产代码里 | 阶段 6 前缀 grep 清零并贴出结果 |

### 可扩展性

> 以下扩展点均为**表格追加一行**，不改工作流、审批门与契约。

| 扩展点 | 零改动扩展方式 |
|---|---|
| 新增反馈循环构造方式 | 在 §阶段 1 构造方式清单追加一条（含适用场景与优先级位置） |
| 新增技术栈特定故障模式 | 由 tri-coding `tech-skills/` registry 加载，本 skill 不内置技术栈知识 |
| 新增回归门禁项 | 在 §阶段 5 回归门禁清单追加一行；`templates/fix-tasks.md` 同步加一条复选框 |
| 新增调试反模式 | 在 §调试反模式表追加一行（特征 + 替代做法） |
| 新增质量标准 | 在 §质量标准表追加一行（维度 / 标准 / 验证方式），测试用例 H 组同步追加 |


## 版本检查与更新机制（强制技术约束 · 硬红线）

> 家族级强制技术约束，优先级与「强制执行契约」同级。skill 任一执行入口启动后的**第零步**，先于核心执行阶段。
> **细则唯一真源**：`tri-forge/references/version-check-spec.md`。**可执行实现（single source of truth for logic）**：本 skill 自带 `scripts/check_update.py`（与 tri-intent 同源一致，按 `--slug` 自动适配）。
> **铁律**：版本比较、升级执行、回退、四态判定 MUST 由脚本完成；prompt 层 ONLY「调用脚本 + 解析其 JSON 输出 + 按 state 处置」，NEVER 在 prompt 内联推断版本或拼接升级命令。修订规则只改真源一处，脚本与真源保持同步。

**执行方式（MUST）**

1. 任一执行入口启动后、核心执行前，运行脚本并取 JSON：
   ```bash
   python scripts/check_update.py --slug tri-fix --json
   ```
   - 节流：结果持久化缓存（默认 1440 分钟 / 24h 仅校验一次），`--force` 强制重查，`--dry-run` 只判定不真升级。
   - 脚本自动定位 skill 目录（默认脚本上级目录），`--slug` 显式指定自身 slug（如上）。
2. 解析 JSON 的 `state` 字段，按态处置：
   - `A` 校验通过 / `B` 离线降级 / `C` 通道降级 / `D` 升级降级 → **一律放行**，进入后续阶段；并据 `warnings` / `notes` / `actions` 在交付物或日志标注对应口径（如「版本校验未完成（离线）」「版本陈旧·自动升级失败」）。
   - `BLOCK` → **绝对禁止执行**，按 `block_code`（P2/P3/P4）输出结构化恢复指引（手动命令见 `actions` 字段）。
3. 退出码语义（供 shell 编排）：`0`=A 放行；`10`=B；`11`=C；`12`=D；`20`=阻断。判定规则：`<20` 放行，`>=20` 阻断。脚本自身异常时兜底降级放行（退出码 11），NEVER 因版本门自身故障导致 skill 无法启动。

**执行要点**

1. **端点取自配置**：API 主机 MUST 读自 `~/.skillhub/metadata.json`，NEVER 硬编码域名。营销官网 `skillhub.cn` 与 API 主机 `api.skillhub.cn` 是两个站点——官网对任意路径都返回 `200 + HTML` 兜底页，绝不可作校验端点。读不到配置即判通道不可用。
2. **校验请求**：`GET {api_host}/api/v1/skills/{slug}`，超时 ≤ 5s，失败重试 1 次，会话内仅校验一次。
3. **最新版取值**：`latestVersion.version`，缺失时回退 `skill.tags.latest`。平台**不提供** `min_compatible` / `deprecated` / `checksum_sha256` / `signature`，NEVER 依赖这些字段。
4. **响应有效性**（三条件同时成立）：HTTP 200 **且** `Content-Type` 含 `application/json` **且** 能解析出版本字段。仅看状态码会被 SPA 兜底页击穿。
5. **版本比较**：按 [SemVer](https://semver.org/lang/zh-CN/) 逐段整数比较，NEVER 字符串比较。
6. **四态判定**：
   - **A 校验通过**（响应有效且 `current >= latest`）→ 放行。
   - **B 离线降级**（网络不可达）→ 标注「版本校验未完成（离线）」后以当前版本继续。
   - **C 通道降级**（可达但响应无效 / 404 / 405 / 读不到配置）→ 标注「版本校验未完成（通道不可用）」+ 输出通道异常告警后继续。
   - **D 升级降级**（陈旧且已真实尝试自动升级但未完成）→ 标注「版本陈旧·自动升级失败」+ 输出手动升级指引后继续。
   - 四态 NEVER 用于绕过「已检出陈旧却不尝试升级」——MUST 先真实执行一次自动升级，失败方可落 D 态。
7. **更新通道（自动执行）**：检出陈旧 MUST 自动执行 `skillhub upgrade <slug>` → `skillhub verify <slug>`，升级前备份、签名明确不一致则回滚。CLI 不在 PATH 时回退 `python ~/.skillhub/skills_store_cli.py upgrade <slug>`；CLI 缺失或升级失败 → 落 D 态降级继续，NEVER 阻断。以 junction 指向源码树的 `source: local` skill 跳过自动更新，改为提示维护者手动同步。命令细则、CLI 定位顺序与已知陷阱见真源。
8. **阻断条件 P1–P4** 与四处版本同步点见真源；发布前 MUST 通过 `python tri-forge/scripts/sync_registry.py --check`。

## 调试工作流（设计类链路）
> 执行顺序固定：§版本检查与更新机制（第零步）→ 上游依赖检测 → 读取快照 §三 → 核心执行。版本检查未通过前 NEVER 进入以下任一执行步骤。



```
tri-intent 快照 §三 (I12)
        │
        ▼
  bug-report.md（故障报告）
  · 阶段1：建立反馈循环（构造能变红的紧密信号）
  · 阶段2：复现+最小化（收缩到最小场景+边界测绘）
        │
     门①·故障确认 ──不通过──→ 携反馈更新 bug-report.md → 再门①
        │通过
        ▼
    diagnosis.md（根因诊断报告）
  · 阶段3：假设生成（3-5个可证伪假设+排序）
  · 阶段4：插桩验证（一次一变量+因果确认）
        │
     门②·诊断审计 ──不通过──→ 携反馈更新 diagnosis.md → 再门②
        │通过                       （涉及故障信息缺失则回退门①）
        ▼
    fix-tasks.md（修复任务+回归测试清单）
  · 阶段5前半：修复方案+回归测试计划
        │
     门③·执行前确认 ──有补充──→ 更新 fix-tasks.md（诊断缺陷回退门②）→ 再门③
        │无补充
        ▼
    执行（修复+回归测试）
  · 阶段5后半：应用修复+回归门禁
        │              测试不过 ──→ 回炉 fix-tasks.md → 再执行
        ▼
    fix-report.md（修复报告）
  · 阶段6：清理插桩+事后复盘+根因归档
```

> **阶段 ↔ 产物 ↔ 审批门 ↔ 模板** 的对应关系见 §交付产物机制 §三产物清单（**唯一事实源**）。门的通过/不通过规则与复选框切换机制见 §强制执行契约；各阶段详细内容见 §系统化调试方法论。

### 执行节点补充规则（对应方法论阶段 5 后半）

> 契约 §4 已定义复选框切换与回炉规则，此处只补充调试执行策略。

| 维度 | 执行策略 |
|---|---|
| 修复策略 | 变更仅落在根因处 → 不越界 → 重构与优化留给后续独立任务 |
| 回归验证 | 先写回归测试再修 → MRC 变绿 → 回归门禁五项全过 → 边界逐项验证 |
| 举一反三 | 指出同类隐患 → 建议防御（类型/断言/日志/测试）→ 标记架构改进 |
| 插桩清理 | 所有 `[DEBUG-xxx]` 标签 grep 清除 → 一次性原型删除 |

> **技术栈规范约束力**：若在 bug-report.md 阶段加载了 tri-coding 的技术栈 skill，其编码规范条目在修复执行阶段具有约束力。

## 交付产物机制

### 一、文件命名规范

沿用 tri-intent 快照命名：`<问题类型>_<日期>_<时间>_<会话ID>`

- 示例：`I12_20250211_143022_6a5c037d`

### 二、存放目录

```
.tribro/                    # 若不存在则先创建
├── snapshots/              tri-intent 产出（已存在）
│   └── <命名>.md
└── fixes/                  tri-fix 链路文档
    └── <命名>/
        ├── bug-report.md     # 故障报告（门①载体）
        ├── diagnosis.md      # 根因诊断报告（门②载体）
        ├── fix-tasks.md      # 修复任务+回归测试清单（门③载体+执行蓝图）
        └── fix-report.md     # 修复报告（最终交付物）
```

### 三、产物清单（阶段 ↔ 产物 ↔ 门 ↔ 模板 · 唯一事实源）

> 本表是「方法论阶段—链路节点—产物—审批门—模板」对应关系的唯一事实源，§调试工作流 与 §系统化调试方法论 均引用本表，不再另立映射表。

| 方法论阶段 | 链路节点 | 产物 | 文件名 | 内容 | 审批门 | 模板 |
|---|---|---|---|---|---|---|
| 1 + 2 | 故障确认 | 故障报告 | `bug-report.md` | 故障现象 + 能变红的反馈循环 + 最小化复现 + 边界测绘 | 门① | `templates/bug-report.md` |
| 3 + 4 | 根因诊断 | 根因诊断报告 | `diagnosis.md` | 3–5 个可证伪假设 + 排序 + 实验设计 + 验证结果 + 因果确认（故障信息缺失则回退门①） | 门② | `templates/diagnosis.md` |
| 5 前半 | 修复计划 | 修复任务清单 | `fix-tasks.md` | 原子化修复任务 + 回归测试清单（先写测试再修）+ 依赖图 | 门③ | `templates/fix-tasks.md` |
| 5 后半 | 修复执行 | 修复补丁 | —（落用户工作区） | 按 `fix-tasks.md` 逐项修复 + 回归门禁五项 + 复选框状态切换 | — | — |
| 6 | 清理复盘 | 修复报告 | `fix-report.md` | 修复记录 + 回归结果 + 插桩清理确认 + 事后复盘 + 遗留架构建议 | 无（验收载体） | `templates/fix-report.md` |

## 质量标准

> 每条标准都可被独立验证。交付前逐行核对，任一不达标则回到对应阶段。

| 维度 | 标准 | 验证方式 |
|---|---|---|
| 反馈循环 | 循环能变红、确定性、秒级、agent 可无人值守运行 | `bug-report.md` 贴出命令与至少一次真实运行输出 |
| 最小化复现 | 移除任一剩余元素循环即变绿 | `bug-report.md` 逐项裁剪记录 + 边界测绘表 |
| 症状一致 | 循环所红的失败模式与用户描述逐字一致 | `bug-report.md` 症状原文 vs 循环输出对照 |
| 假设质量 | 3–5 个独立可证伪假设，每个含「若 X…则 Y…」预测并已排序 | `diagnosis.md` 逐条核对预测句式与排序表 |
| 因果确认 | 去掉根因→消失→加回→重现，三步均有实验证据 | `diagnosis.md` 因果确认三步记录 |
| 修复范围 | 变更仅落在根因处，无顺带重构/优化 | `fix-tasks.md` 任务清单与实际 diff 逐项比对 |
| 回归门禁 | §阶段 5 五项全过 | `fix-report.md` 回归结果章节，逐项复选框为 `- [x]` |
| 插桩清理 | `[DEBUG-` 前缀全局 grep 无残留，一次性原型已删除 | `fix-report.md` 清理确认章节贴出 grep 结果 |
| 事后复盘 | 已回答「什么本可以避免这个 bug」并给出防御或架构建议 | `fix-report.md` 复盘章节 |

## 落盘规则

- 快照由 tri-intent 已落盘于 `.tribro/snapshots/`
- 本 skill 链路文档落盘于 `.tribro/fixes/<命名>/`
- 链路文档可覆盖更新（以最新一轮为准），审计记录留痕于各文档审计章节
- 最终修复补丁就地落盘于用户工作区项目目录（实际交付物，非 .tribro/）
- 产物归档：`.tribro/` 不存在时 MUST 先创建；每轮执行 MUST 在 `.tribro/fixes/<命名>/` 落 `delivery-manifest.md`，记录本次交付/修改的文件路径清单与说明，保证产物可追溯
- 调试日志（含 `[DEBUG-xxx]` 标签）在清理前临时记录于 diagnosis.md，清理后确认已移除

## 代码版权与许可证合规（硬红线）

> **原则**：本 skill 产出的修复补丁必须**原创、可合规使用与发布**。版权与许可证问题零容忍——任何疑似侵权或许可证冲突的补丁，在解决前不得提交、发布或交付。

**五条硬红线（提交/发布/交付前全过才可出）**：

- **原创不照搬**：补丁依据 `diagnosis.md` 的根因结论原创实现，NEVER 从 StackOverflow / GitHub issue / 博客整段照搬；确需复用开源片段则完整保留其 LICENSE 与版权声明。
- **许可证兼容**：为修 bug 引入新依赖或上游 patch 前 MUST 核对许可证兼容性，NEVER 引入与目标仓库不兼容者（如 GPL 传染）。
- **依赖已授权**：只用可商用、来源可信的公共包并记录版本与来源，NEVER 换用来源不明的 fork 或私有付费包；对第三方库的 monkey patch MUST 在 `fix-report.md` 显式披露。
- **披露到位**：平台/雇主/开源社区要求披露 AI 生成代码时按其最新政策标注；向上游回补须遵循该项目 CLA / DCO 要求。
- **LICENSE 已声明**：补丁落盘时按目标仓库许可证写入声明或头部注释。

> 📖 **详见 `references/license-compliance.md`**——含四类风险与预防（调试场景特化）、生成期源头杜绝、6 步硬性自检清单、平台/仓库条款速查、商用授权与原创存证、侵权应急处置、五条底线判定表。

## 目录结构

```
tri-fix/
├── SKILL.md              # 主入口：调试工作流 + 双审批门 + 系统化调试方法论 + 质量标准 + 合规红线
├── README.md             # 特性/目录结构/安装/使用/测试/设计原则
├── CHANGELOG.md          # 版本变更历史（Keep a Changelog + SemVer）
├── references/           # 静态参考资料（非流程逻辑）
│   └── license-compliance.md   # 代码版权与许可证合规完整参考（调试场景特化）
├── templates/
│   ├── bug-report.md     # 故障报告模板（门①载体）
│   ├── diagnosis.md      # 根因诊断报告模板（门②载体）
│   ├── fix-tasks.md      # 修复任务+回归测试清单模板（门③载体+执行蓝图）
│   └── fix-report.md     # 修复报告模板（最终交付物）
└── tests/
    └── tri-fix-full-testcases.md   # 全场景测试用例
```