根因透视镜 · 通用缺陷深度体检与机制治本工作流（一次到位）
能力速览
| 维度 | 说明 |
|---|---|
| 定位 | 通用型缺陷深度体检 + 机制治本工作流（非垂类、非单一语言） |
| 适用工件 | 代码 / 配置 / 数据 / ETL·生成管道 / 文档报告 / 技能本身（SKILL.md·scripts·references） |
| 两阶段闭环 | ① Phase 1 根因体检（四+一维度 → 证据层，过 GC 闸门）→ ② Phase 2 机制治本（M 机制 + N 依赖消解）→ ③ 断言回归 → ④ 三态交付 |
| 核心铁律 | 宁缺勿错（确定性优先主义）；显式缺口 > 静默猜测；宣称 = 实际（✅/⚠️/❌ 三态） |
| 强制交付物 | 根因彻查报告 + 机制治本方案 + 断言回归（selftest）+ 三态对照 |
| 差异化 | 别家给建议；本技能强制"证据→机制→断言"闭环，并诚实暴露缺口 |
触发词：为什么又错了 / 缺陷反复出现 / 帮我彻查根因 / 从根上解决 / 深度体检 / 机制上杜绝
> 任何"有确定输入、确定处理逻辑、可观察输出"的工件——一段 Python 报错、一个 Excel 公式错值、一条 ETL 异常、一个配置项失效、一份文档生成错位——都能用同一套方法论做深度体检。本技能不绑定任何场景。
金融场景完整实战见 references/appendix-finance-worked-example.md（脱敏实证，作为典型领域附录保留）。
触发场景
- 用户报缺陷 / 错误 / 输出数值或行为不一致 / 功能失败
- 用户说"为什么又错了""缺陷反复出现""帮我彻查根因""从根上解决""扫雷排因""深度体检""机制上杜绝"
- 交付物对比（生成版 vs 权威版、新旧版、表 vs 文、A 输出 vs B 输出）发现差异需归因
- 技能 / 代码库大修复后的回归验证
- 任何"看起来修好了但怕下次又犯"的场景
最高准则：宁缺勿错 = 确定性优先主义（一体两面）
确定性信号优先、概率性信号出局；但在确定性信号保障下，大胆创新推测强烈鼓励。
| 面 | 内容 | 判据 |
|---|---|---|
| 禁止面（宁缺勿错） | 概率性猜测（相似度"可能是"、统计近似、无依据推断）→ 静默污染难发现 → 出局 | 无验证手段 / 无证据链 |
| 鼓励面（确定性推测） | 不变量/恒等式反推、数值指纹反查、唯一性校验、跨源勾稽等确定性信号下的推测 → 大胆做 | 可验证 / 可锁定 / 有证据链 |
判别（任何方案探索前自问）：这个推测能否被验证、锁定、留证据链？能 → 大胆做（增强系统适用性/灵活性/智能性的关键）；不能 → 宁缺勿错，留显式缺口。
> 详细确定性信号分级（L1 不变量 → L2 数值指纹 → L3 规则匹配 → L4 概率性）及选型见 §2.1.5。
一次到位执行契约（调用即生效，勿等用户指示）
- 两阶段自动串行：Phase 1 彻查 → Phase 2 机制治本，中间不暂停、不征询"要不要继续"。
- 机制治本不降级：每个根因必须完成 机制修复（消除错误产生的机制本身）+ 断言锁死（selftest 真实样本），不允许只修本次现象。
- 缺口主动暴露：做不到的项（如架构级重构需更大范围）显式标 ⚠️ 未落地 + 理由，绝不用"已固化"掩盖。
- 全程无需用户追问：证据、根因、机制方案、断言、三态对照全部自动产出。
- 探索遵循最高准则：根因与治本每一步都过"确定性优先"判别——可验证则大胆推测，不可验证则显式缺口。
决策权三层模型（L1 自动落地 / L2·L3 用户拍板）
机制治本产出分三层，决定权归属不同——执行时不得越权、也不得该问不问：
| 层 | 内容 | 决定权 | 交付形态 |
|---|---|---|---|
| L1 技术正确性修复 | 有唯一"对/错"标准（金标准/权威值/断言可验证），不改业务语义 | ✅ 技能自动落地（"修错"非"做选择"） | 断言锁死 + 备份可回滚 + 三态交付（✅已做 附行号证据），用户可否决 |
| L2 业务口径决定 | 无唯一正确答案，是业务/领域口径选择 | 👤 必须用户拍板 | 技能只出对比方案（各口径数值+差异+影响），标 ⚠️ 待用户确认，禁止替用户选口径 |
| L3 架构级重构 | 影响面大、改变工作流本身 | 👤 用户选做不做/做多少 | 技能出方案（机制/工作量/风险/推荐），用户确认后落地 |
判定：拿不准属 L1 还是 L2 → 问"存在唯一正确答案吗？"：存在→L1 自动；不存在→L2 交用户。L1 落地后必须附断言证据+备份路径+三态标注；L2/L3 未确认前禁止声称"已固化"，只能标 ⚠️ 方案待批。
铁律（违反即失败）
- 证据到位才下结论：每个根因必附 文件:行号:实测输出 三层证据。实测 = 实际运行复现（脚本输出），非代码阅读推断。
- 分维度彻查：至少覆盖 代码层 / 流程层 / 纪律层 / 约束层 四维度 + 依赖视角横切，逐类核完再定性。禁止只查一维度。
- 不拿"看起来显然"当根因：归因前先问"这是现象还是根因？根因在哪一环？"区分 设计 / 流程 / 执行纪律 缺陷。每个根因必须实测复现，代码阅读推断不算数。
- 根因未坐实前禁止抛修复方案：哪怕现象"看起来明显"，也先跑证据再谈修复。
- 估算与实测严格分列：耗时/覆盖率等数字，实测标实测（附计时方法），估算标估算（附依据）。
- 宣称-证据-状态三态对照：凡宣称"已做/已修/已固化"的项必带证据（路径+行号+实测输出）；做不到的显式标 ⚠️已验证未锁定 / ❌未做。
- 机制治本强制：交付 = 根因报告 + 机制修复 + 断言回归，缺一不可。缺任一项 = 本次调用未完成，继续补至 DoD 全绿。
- 根因确证先于自动修复（GC 闸门）：L1 修复必须先过「根因确证闸门」——复现实测 + 红绿验证是确证唯一标准，代码阅读推断不算确证。GC 未全绿 = 根因未确证 = 禁止自动修复。
- 确定性优先主义（最高准则）：确定性信号优先、概率性信号出局；但可验证/可锁定/有证据链时大胆推测。禁止把"概率性猜测"伪装成"创新"落地。
- 单点修复节奏：Phase 2 一次只修一个根因点 → 立即跑质量测试（selftest/回归）→ 全绿才动下一个。禁止批量连环修——缺陷可能相连（A→B→C）：连续修可能引入新缺陷，或上游修复已顺带消解下游。多缺陷先按依赖链排序（上游先修），修一个验一个，每轮只报"本轮点 + 质量结果 + 剩余点"。彻查阶段仍一次性扫全部同类盲区（GC-5），但修复严格单点——扫全 ≠ 修全。
根因确证闸门（GC Gate）——L1 自动修复的前置硬条件
位置：Phase 1 完成、Phase 2 动手之前。每个根因逐条过 GC 才能进入自动修复；GC 未全绿 = 根因未确证 = 只能出方案交用户或继续彻查，禁止自动修。
| # | 确证项 | 通过标准 | 失败含义 |
|---|---|---|---|
| GC-1 | 复现确证 | 有最小复现脚本，错误逐字符重现（中间量打印比对），非"看到现象"。附引入时间核查：查备份/git/旧产物，确认是新引入还是旧病 | 无复现脚本 / 未查历史版本 = 未坐实 = 禁止自动修复 |
| GC-2 | 解释确证 | 修复方案能逐环节解释复现链路（输入→处理→输出，每步为什么错） | 改得动说不清 = 黑盒修复 = 禁止 |
| GC-3 | 红→绿验证 | 用修复后代码跑同一复现脚本，错误消失且输出与金标准一致 | 修了仍红 / 修出新错 = 回退重来 |
| GC-4 | 变异拦截 | 对根因做小变异（换输入/换形态/换边界），确认修复仍能拦截 | 只修本次样本、变体仍错 = 治标 = 禁止 |
| GC-5 | 同类先确证 | 发现的同类位置，先各自复现确证再修，禁止"看着像就一起改" | 未复现就批量改 = 引入新错风险 |
判别测试（提交 L1 自动修复前自问）：
1. 这个根因我有复现脚本吗？复现输出打出来比对过吗？——没有 → 回 Phase 1
2. 缺陷是新引入还是旧病？查过备份/git/旧产物吗？——没查 → 补 GC-1 引入时间核查
3. 我能说清代码每行为什么导致这个错吗？——不能 → 继续彻查
4. 修完跑同一脚本，错误真没了吗？变体呢？——没验证 → 补 GC-3/GC-4
5. 同类位置还有几处？每处都复现确认了吗？——没查 → 补 GC-5
6. 产物读的是最新文件吗？管道有没有 ABORT 后 backup 还原旧文件？——状态判定必须看完整输出（含中断/还原字样），并核对文件时间戳
GC 与 L1/L2/L3 关系：
- L1 自动修复：GC-1~GC-5 全过才可动手
- L2 业务口径：无需 GC（本就交用户拍板）
- L3 架构重构：GC-1~GC-2 确证根因后出方案（防基于错误根因做架构），GC-3~GC-5 在用户确认落地时执行
Phase 1：彻查根因（Evidence-First Root-Cause）
1.1 锁定错误原文（现象层）
- 定位错误精确位置（文件:表:段 / 函数名 / 行号 / 用例编号）
- 记录 正确值（权威值/金标准）vs 错误值 对照表
- 判定错误落在 数据层 / 组装层 / 渲染层 / 闸门层 / 行为层 哪一层
1.2 提取"罪证链"（机制层）
- 找到产生错误的 代码/逻辑路径：输入 → 处理 → 输出 完整链路
- 标注关键函数与行号、每环节输入输出
- 实测复现：写最小复现脚本让错误逐字符重现（中间量打印）。每个根因都必须有复现脚本，无复现 = 未坐实
- 哲学挂载：根因确证本身即"宁缺勿错"体现——无证据链不落地；同时鼓励"确定性重构"：思考该环节能否用更硬信号（不变量/数值指纹/唯一性校验）替代脆弱依赖（文本命名/人工输入/顺序假设），为 Phase 2 绕行埋线
1.3 四维度彻查（分类根因）
| 维度 | 彻查问题 | 证据形态 |
|---|---|---|
| 代码层 | 解析/计算/取数/渲染/匹配哪个环节有缺陷？边界漏了？词表/规则错配？跨源取数静默写 0 / 返回 None？ | 复现脚本输出 + 源码行号 |
| 流程层 | 管道/工作流有哪些闸门？警告是否强制消费？多步串联边界是否定义？ | 入口脚本/管道定义 + 警告清单 + 闸门覆盖矩阵 |
| 纪律层 | 执行者宣称 vs 实际完成度？验收是否逐条勾对？人工改动是否对照源/权威值？ | 交付总结 + 验收处理记录 |
| 约束层 | 兜底分支语义？静默降级链？盲区是否重叠（缺校验+警告不强制+无显式标记）？ | 源码兜底分支 + 闸门覆盖矩阵 |
1.4 产出根因彻查报告
结构：错误×根因×维度总览表 → 各维度详述（附证据）→ 治本方向 → 证据索引（可复跑）。模板见 references/03-report-template.md。
Phase 2：机制治本（强制，非可选）
核心转变："让机制本身不可能出错"，而非"修完这次错误"。
2.0 机制治本 DoD 验收清单（逐项勾对，全过才算完成）
| # | 验收项 | 通过标准 | 自检 |
|---|---|---|---|
| DoD-1 | 根因↔机制对齐 | 每个根因对应一个机制修复（标 M1-M10 / N 系列），无"只修现象无机制"的裸修复 | ☐ |
| DoD-2 | 结构性防错（硬性） | 修复必引入 M 增强系 / N 绕行系之一（单一事实源/注册表+单测/硬闸门/跨源断言/确定性信号反查/不变量推导…），且代码中真实落地（有文件:行号证据）。禁止把"补词表/修正则"包装成结构性防错——单点修复不算 | ☐ |
| DoD-3 | 断言锁死 | 每处修复配 selftest 断言，用缺陷真实样本（非"代码能跑"），失败即回归红灯 | ☐ |
| DoD-4 | 全链路重跑 | 引擎/逻辑改动后全链路重跑 + 产物新鲜度校验（产物时间戳 ≥ 引擎/数据源）；消费方兼容验证 | ☐ |
| DoD-5 | 三态交付 | 交付逐项标 ✅已做 / ⚠️已验证未锁定 / ❌未做（含理由与替代），无模糊措辞 | ☐ |
| DoD-6 | 同类盲区扫描 | 主动查"同类根因是否在别处也存在"（如两处匹配器标准不一致、同源双文件不同步），一并修复或显式登记 | ☐ |
| DoD-7 | 机制治本交付物 | 交付必须含独立「机制治本落地计划」（M/N 映射 + 落地状态），与「差异修复清单」分离——修复清单不得冒充机制治本方案 | ☐ |
| DoD-8 | 依赖消解评估（强制） | 每个根因必过「依赖消解六问」（§2.1.5），报告显式记录"依赖什么/能否绕行/走 M 还是 N 还是叠加/为什么"——禁止只做 M 增强不评估 N 绕行 | ☐ |
| DoD-9 | 最高准则应用（确定性优先，强制） | 每个治本方案标确定性信号分级（L1 不变量/恒等式 → L2 数值指纹 → L3 规则匹配 → L4 概率性）；有 L1/L2 必须大胆用（绕行类），禁止 L4 概率性猜测伪装成创新落地；方案必须可验证/可锁定/留证据链 | ☐ |
DoD 未全绿 = 本次调用未完成，继续补，不交付。
DoD-2 硬性判别（防"修复冒充机制治本"）：
- 问："这个修复是引入了 M/N 级机制（改变错误产生的结构性前提），还是只修了本次输入？"
- 单点修复（补词表/修正则/改一个分支）→ 不算 DoD-2 通过，必须继续落到结构性机制（哪怕只落一道跨源断言闸门兜底）
- 每个修复在交付中必标："本修复属于 M/N 哪一层 / 或为单点止血（须附 DoD-7 机制计划对应落地项）"
结构性机制基准（DoD-2/DoD-7 引用）——两系：增强系（M1-M10）+ 绕行系（N 信号）：
- M1 单一事实源：派生值引用唯一事实源，消除"多副本不一致"
- M2 配置外置：内嵌配置 → 外置单文件引用，消除"改了没同步"
- M3 只升真歧义：一遇边界就交人工 → 评分判定主角，仅真歧义交人工
- M4 硬闸门：警告不阻断 → 工单化（severity/status），P0/P1 未确认即 ABORT
- M5 回归对账：依赖人工发现 → 金标准/基线 + 自动 diff 分类
- M6 注册表+单测：散落规则/枚举 → 注册表 + 单测，注册期即报错
- M7 显式缺口：静默降级 → 显式报错/标记，留显式缺口可查
- M8 类型过滤：贪婪提取 → 类型/上下文过滤
- M9 跨源断言：无校验 → 跨源一致性断言闸门，不一致即 ABORT
- N1 结构锚点：依赖命名/顺序 → 用结构锚点/位置定位（⚠️ 适用前提窄，见 §2.1.5）
- N2 值指纹反查：依赖命名 → 用唯一值反查定位（值比名硬）
- N3 不变量推导：依赖源读取 → 用不变量/恒等式推导（不读源、不匹配）
- N4 历史记忆：每次重匹配 → 上期已验证结论直接继承
- N5 语义匹配：规则式 → 相似度匹配（❌ 已排除：概率性信号，与宁缺勿错冲突）
> 各模式详解 + 选型决策见 references/02-mechanism-fix-patterns.md。
2.1 治本 vs 治标判别
- 治标 = 只改本次交付物/只修表象 → 下次同类缺陷复发
- 治本 = 消除产生错误的机制本身 + 配 selftest 断言锁死真实形态（用缺陷真实样本，非"代码能跑"）
- 判别：修复后自问"下次同类缺陷还会发生吗？"——会，就是治标，回机制层重来。
2.1.5 依赖消解评估（强制，DoD-8 依据）
> 若 Phase 2 只做 M 系增强（补规则/补词表），N 系绕行不会自动产出——必须追问"还有什么创新方案"才浮现，违背「一次到位」契约。本步即为此补上的硬闸门。
对每个根因，选 M 模式前先过「依赖消解六问」：
1. 这个缺陷本质上"依赖"了什么？（命名/人工输入/源数据完整性/单一数据源/顺序假设/历史配置…）
2. 这个依赖是必要的吗？还是历史实现巧合？（"匹配"只是手段，不是目的）
3. 能否用其他信号替代？——值（N2）/ 位置（N1）/ 关系（N3）/ 时间（N4）/ 语义（N5）
4. 替代信号的可靠性？（唯一性/确定性/可验证性——必须比原依赖更硬）
5. 替代后依赖消失了吗？残余依赖是什么？
6. 残余依赖如何兜底？（显式缺口 M7 / 硬闸门 M4 / 人工确认——宁缺勿错）
判据：第 3 问有更硬信号 → 走 N（绕行）或 M+N 叠加；无 → 走 M（增强）+ M7（显式缺口兜底）。产出：报告显式记录"依赖 X / 替代信号 Y / 走 M+N 哪条 / 残余依赖 Z 如何兜底"。
确定性信号分级（最高准则落地）——替代信号按确定性从高到低，优先用高确定性，禁概率性：
| 级 | 信号类型 | 示例 | 判定 |
|---|---|---|---|
| L1 不变量/恒等式 | 数学/逻辑必然关系，可复算 | 小计=明细和、A=B+C、状态机不变量（N3） | ✅ 大胆用 |
| L2 数值指纹 | 值比名硬，唯一性可校验 | 用已知值反查唯一行（N2） | ✅ 大胆用（多命中→显式缺口） |
| L3 规则匹配 | 文本规则，需维护 | 归一化/同义词表（M 系） | ⚠️ 兜底用（变体无穷，追不上） |
| L4 概率性信号 | 统计近似，不可验证 | 相似度匹配（N5） | ❌ 出局（宁缺勿错：可能静默误配） |
鼓励面：同一问题若有 L1/L2 可推导 → 大胆绕过匹配直接算/反查（N2/N3 实证）——这是"宁缺勿错不是保守主义，而是确定性优先主义"的执行模板。
2.2 机制升级模式库（每个根因至少评估 3 候选，必须同时覆盖 M 增强系与 N 绕行系）
| # | 模式 | 升级方向 | 适用 | 典型示例 |
|---|---|---|---|---|
| M1 | 硬编码值 → 派生/引用 | 写死数值 → 表达式/引用单一事实源，渲染时自动算 | 数值与来源脱节 | 比率/百分比改引用事实源 |
| M2 | 独立副本 → 单一事实源 | 第二套取数 → 引用权威事实源 | 多副本数值不一致 | 叙事段引用表格渲染结果 |
| M3 | 内嵌配置 → 外置引用 | config 内嵌 → 外置单文件引用 | 改了没同步 | ops/配置外置 |
| M4 | 人工兜底 → 真歧义才人工 | 一遇边界交人工 → 多信号评分判定主角 | 一遇边界就交人工 | 歧义评分判定 |
| M5 | 提示不阻断 → 硬闸门 | 警告列表 → 工单(severity/status) + P0/P1 未确认即 ABORT | 引擎报了没人接 | 复核工单化硬闸门 |
| M6 | 事后发现 → 回归对账 | 依赖用户发现 → 金标准/基线 + 自动 diff | 错误漏检 | 权威版对比暴露错误 |
| M7 | 静默降级 → 显式缺口 | 找不到→写0→除零 → 显式报错/【待补】+ P0 | 兜底分支隐性错位 | 句式未识别→显式缺口 |
| M8 | 贪婪提取 → 类型过滤 | findall 全抓 → 过滤非目标类型 | 无关数字混入值序列 | 过滤年份/单位 token |
| M9 | 无交叉校验 → 跨源断言 | 无 → 跨源一致性断言，不一致即 ABORT | 多源数值一致性 | 段落数字 ≡ 事实源单元格 |
| N2 | 命名匹配 → 值指纹反查 | 名字匹配 → 用唯一值反查命中 | 明细行/条目命名错配 | 用已知值反查唯一行 |
| N3 | 源读取 → 不变量推导 | 从源取 → 用不变量/恒等式推导 | 枢纽行（小计/合计/状态）缺值 | 小计=明细求和 |
| N4 | 每次重匹配 → 历史记忆继承 | 每轮重匹配 → 上期已验证结论直接继承 | 周期任务重复踩坑 | 上期映射落盘继承 |
| N1 | 命名匹配 → 结构锚点 | 靠名字找 → 按结构行序/锚点定位 | 命名差异 | ⚠️ 适用前提窄（见下） |
| N5 | 规则式 → 语义匹配 | 相似度匹配 | 规则追不上自由度 | ❌ 已排除（概率性信号） |
> 注：N1/N5 排除理由见 references/02-mechanism-fix-patterns.md §已排除方案。
2.3 落地要求（与 DoD 联动）
- 每个缺陷 = 一个根因 = 一处机制修复 + 一个断言（selftest），逐类对齐，禁止"只治了一类"
- 修复后必须全链路重跑（逻辑改动后产物新鲜度校验：产物时间戳 ≥ 引擎/数据源）
- 交付总结带三态对照（✅已做 / ⚠️已验证未锁定 / ❌未做）
- 同类盲区主动扫描（DoD-6）：如某匹配器已废弃旧策略而另一处仍沿用——两套匹配器标准必须对齐
参考文档
references/01-rootcause-methodology.md— 四+一维度彻查方法详解（含通用检查清单与证据形态）references/02-mechanism-fix-patterns.md— 机制治本模式库详解 + DoD 验收指引（M/N 模式、确定性信号分级、已排除方案）references/03-report-template.md— 根因彻查报告模板（含机制治本交付段，可直接套用）references/appendix-finance-worked-example.md— 金融典型领域实证（脱敏），作为通用技能的「领域实证附录」references/05-cross-domain-examples.md— 非金融跨领域实证（代码限流窗口 off-by-one + 配置布尔开关静默 truthy），证明方法论在任意领域骨架一致references/06-cheatsheet.md— 一页 cheat-sheet（触发词 / 两阶段 / GC / DoD / 8 条根因规律 / M·N 模式 / 三态 / 禁忌），可截图转发references/07-market-intro.md— 市场版简介/封面文案，上架展示用references/08-quickstart.md— 5 分钟上手最短路径assets/rootcause-loop.svg— 根因→机制治本闭环思维图（可截图转发）
实证断言回归（scripts/）
scripts/selftest_template.py— 通用断言回归脚手架：可复用于任意被体检技能/代码，定义"加载目标、构造缺陷真实样本、断言"的标准骨架，套用即可。- 附录
references/appendix-finance-worked-example.md为叙事性领域实证（非可运行代码）；scripts 下不随附领域专属 selftest——任意领域断言回归均通过selftest_template.py由使用者注入目标后落地。
使用流程（一次到位）
- 收缺陷报告 → 读
references/01-rootcause-methodology.md建立彻查框架（牢记最高准则：确定性优先主义） - 执行 Phase 1（锁定原文 → 罪证链 → 四维度彻查 → 报告）——每个根因必配复现脚本
- 跑 GC 闸门（GC-1~GC-5 逐条勾对）——未全绿禁止进自动修复，回 Phase 1 继续彻查
- 读
references/02-mechanism-fix-patterns.md匹配治本模式（每根因 ≥3 候选；按确定性信号分级 L1>L2>L3>L4 选型，有 L1/L2 大胆绕行，L4 出局） - 执行 Phase 2（修复 + 断言 + 全链路重跑 + 同类盲区扫描）
- 跑 DoD 验收清单逐条勾对（DoD-1~DoD-9）——全绿才交付，否则继续补
- 交付：根因报告 + GC 确证 + 机制治本落地 + 最高准则应用（确定性分级/鼓励面自查）+ selftest 结果 + 三态对照（自动产出，不等用户追问）
