@mison/ling 1.0.0

package/.spec/skills/cybernetic-systems-engineering/SKILL.md

@@ -0,0 +1,792 @@
+---
+name: cybernetic-systems-engineering
+description: |
+  用“系统工程 + 工程控制论 + 总体设计（GDA）”的方法做软件工程闭环控制。
+  适用：真实代码库中的 bugfix、feature、refactor、性能、迁移、事故复盘、测试设计、架构审计、门禁验证。
+  尤其适合：问题复杂、跨模块、需要最小可验证变更、需要离线/在线双层验证、需要防止“测试全绿但真实环境失败”的任务。
+  不适用：纯知识问答、翻译、创作、一次性聊天建议、无需验证的单句结论。
+---
+
+# Cybernetic Systems Engineering（CSE）
+
+把软件开发当作一个**闭环控制系统**来做：
+
+- **被控对象（Plant）**：代码库 + 运行时环境 + 依赖 + 数据 + 测试系统
+- **控制器（Controller）**：你（Agent）+ 你的计划、策略、节奏控制
+- **传感器（Sensors）**：测试、构建日志、运行日志、指标、复现脚本、审计文档
+- **执行器（Actuators）**：代码修改、配置变更、依赖升级、回滚、文档更新、测试补强
+- **参考输入（Reference）**：需求、issue、验收标准、SLO/SLA、业务边界
+- **输出（Output）**：实际行为（通过/失败测试、运行结果、性能数据、门禁结果）
+- **误差（Error）**：参考输入与输出之间的差距
+- **扰动（Disturbance）**：环境差异、并发、flake、脏状态、真实 schema 漂移
+- **时滞（Delay）**：慢测试、CI 排队、真实环境依赖、发布窗口
+
+本 skill 的目标不是“让你会用控制论术语”，而是让你在复杂工程任务中：
+
+1. 先建立正确的观测与误差定义  
+2. 再用最小控制输入减少误差  
+3. 用分层验证防止振荡与假收敛  
+4. 用总体设计视角控制复杂性
+
+## 项目级控制拓扑
+
+CSE 不只处理“当前这一条任务怎么修”，还要先回答“这个项目由谁控制、在哪一层控制、跨模块如何协调”。
+
+从控制层级看，CSE 默认同时存在两套闭环：
+
+- **任务级闭环**
+  - 面向单个 issue、单次 patch、单轮验证
+  - 关注最小控制输入、最小 failing case、分层验证
+- **项目级控制拓扑**
+  - 面向多模块、多团队、多阶段演化
+  - 关注总体设计部、控制结构、跨模块协调、边界冻结与升级路径
+
+如果只建立任务级闭环，而没有项目级控制拓扑，常见结果是：
+
+- 单个 patch 看起来正确，但把复杂性偷偷转移到别的模块
+- 局部验证通过，但共享接口、共享状态或共享基础设施被无意破坏
+- 每个人都在改“自己眼前那一层”，但没有人对整体误差负责
+
+因此在以下场景，必须先补项目级控制拓扑，再进入具体修复：
+
+- 改动跨 2 个及以上模块、服务或语言边界
+- 需要同时改代码、配置、schema、运行流程中的两类以上对象
+- 任务会影响共享接口、共享状态、共享基础设施或统一门禁
+
+项目级控制拓扑至少要回答四个问题：
+
+1. **总体设计部在哪里**
+   - 谁负责维护项目级参考输入、关键边界和最终裁决
+2. **控制结构是什么**
+   - 本次问题主要落在哪些层，哪些层只能观测，哪些层允许施加控制输入
+3. **跨模块协调怎么发生**
+   - 哪些模块存在强耦合，改动会沿什么路径外溢，谁需要被显式通知或升级
+4. **哪些边界先冻结**
+   - 哪些接口、schema、门禁口径在本轮不能被顺手改写
+
+### 控制面 / 数据面 / 状态面
+
+为了避免“看起来只是改一行代码，实际上改穿了整个系统”，复杂任务开始前必须先识别本次改动主要落在哪一面：
+
+- **控制面**
+  - 负责决定系统如何调节自己
+  - 典型对象：限流、重试、熔断、路由、灰度、回滚、门禁、调度策略
+- **数据面**
+  - 负责承载真实业务流量和核心处理路径
+  - 典型对象：请求处理、任务执行、核心计算、主链调用、用户可见结果
+- **状态面**
+  - 负责保存共享事实、恢复锚点与跨节点一致性
+  - 典型对象：数据库、schema、缓存、队列、事件日志、检查点、幂等键
+
+默认要求：
+
+1. 先标出本次改动的**主落点**在哪一面
+2. 再标出会被连带影响的次级面
+3. 如果一次改动同时触碰两面以上，必须显式写出复杂性是如何转移的
+
+一个典型例子：
+
+- 把重试、限流从业务代码下沉到 mesh 或统一网关
+  - 不是“复杂性消失了”
+  - 而是复杂性从数据面转移到了控制面
+- 把会话、任务进度或幂等信息从应用内存迁到 Redis / 数据库
+  - 不是“状态更简单了”
+  - 而是状态复杂性从节点内部转移到了状态面
+
+如果主落点都判断不清，默认先不要改实现，而是先补控制结构说明。
+
+### 复杂性转移账本
+
+复杂性不会凭空消失，只会被下沉、上浮或转移到别处。
+
+因此每次声称“系统更简单了”时，都应至少记一条复杂性转移账本：
+
+| 字段 | 说明 |
+| --- | --- |
+| 复杂性原位置 | 复杂性原来压在哪一层、哪个模块、哪条链路 |
+| 新位置 | 复杂性被转移到了哪里 |
+| 收益 | 本次转移换来了什么 |
+| 新成本 | 新增了什么依赖、运维成本或观测成本 |
+| 失效模式 | 转移后最可能新增什么故障模式 |
+
+典型例子：
+
+- 把重试、限流、路由从应用代码下沉到 mesh
+  - 复杂性原位置：数据面应用逻辑
+  - 新位置：控制面基础设施
+  - 收益：业务代码更薄、统一治理更强
+  - 新成本：调试链变长、配置漂移风险上升
+  - 失效模式：控制面误配导致全局放大
+- 把会话、幂等键或任务恢复点外包到 Redis / 数据库
+  - 复杂性原位置：节点内内存与本地状态
+  - 新位置：状态面共享存储
+  - 收益：重启恢复更稳定、横向扩展更容易
+  - 新成本：一致性、超时、容量与运维复杂度上升
+  - 失效模式：状态面抖动放大为全局故障
+- 把同步调用改成异步补偿
+  - 复杂性原位置：同步链路上的时延与阻塞
+  - 新位置：队列、重试、补偿和对账流程
+  - 收益：主链解耦、峰值承压更强
+  - 新成本：最终一致性与对账成本上升
+  - 失效模式：补偿堆积、重复消费、长尾未收敛
+
+项目级控制拓扑的默认治理协议如下：
+
+### 最小 owner matrix
+
+| 角色 | 默认职责 | 有权决定什么 | 无权单独决定什么 |
+| --- | --- | --- | --- |
+| 总体设计部 | 维护项目级参考输入、关键边界、升级路径与最终裁决 | 跨模块优先级、冻结边界、变更窗口、最终 gate 口径 | 直接跳过模块 owner 的局部约束与证据 |
+| 模块 owner | 维护本模块不变量、主链入口与回归边界 | 模块内部实现、局部回归、局部重构 | 擅自改共享接口、共享状态、共享门禁 |
+| 共享边界 owner | 维护共享 API、schema、队列、缓存、统一门禁等共享事实源 | 共享契约演化节奏、兼容窗口、迁移前置条件 | 在未通知受影响模块时直接改共享契约 |
+
+### 默认升级路径
+
+按风险从低到高，默认这样升级：
+
+1. **模块内局部改动**
+   - 模块 owner 可在本模块边界内完成分析、修改与验证
+2. **跨模块但不改共享契约**
+   - 必须显式通知受影响模块 owner，并记录外溢路径
+3. **触碰共享接口、共享状态、统一门禁**
+   - 必须升级到总体设计部裁决，再进入实现
+4. **触碰冻结边界或发布窗口**
+   - 默认停止当前 patch，先拿到明确批准
+
+### 接口冻结条件
+
+以下任一对象在本轮默认视为冻结边界，不能顺手改写：
+
+- 共享 API 输入输出结构
+- 数据库 schema 与持久化字段语义
+- 队列、缓存、事件格式等共享状态契约
+- 统一门禁口径、核心指标口径、发布与回滚流程
+
+要解冻这些边界，至少要同时满足：
+
+1. 有明确变更理由，而不是“顺便改一下更优雅”
+2. 有受影响模块清单与兼容路径
+3. 有总体设计部或对应共享边界 owner 的显式裁决
+
+### 跨模块裁决规则
+
+凡是跨模块变更，最终裁决责任默认不属于“谁先改代码”，而属于总体设计部。
+
+它至少要回答：
+
+- 为什么这次改动值得跨模块扩散
+- 哪些模块只需要被通知，哪些模块需要同步修改
+- 哪些边界继续冻结，哪些边界被批准打开
+- 如果跨模块协调失败，当前 patch 应该收缩到哪里
+
+如果这些问题答不出来，默认结论不是“继续改”，而是：
+
+- 先补控制拓扑
+- 先画清边界
+- 先确认谁对整体误差负责
+
+后续章节中的 Control Contract、GDA 四步法、传感器工程与验证分层，都是建立在这层项目级控制拓扑之上执行的。
+
+## 0. 何时触发
+
+以下任一场景，优先使用本 skill：
+
+- 需要修改代码并验证结果
+- 任务跨多个模块/服务/语言边界
+- 需要从 bugfix 推进到测试补强、门禁、handoff
+- 用户要求做“严格 review”“系统性复盘”“架构与测试一起收口”
+- 出现“离线通过，真实环境失败”“测试通过，业务不闭环”“修一个坏两个”的迹象
+
+如果任务时间跨度长、步骤多、存在中断恢复需求，应**同时配合 `harness`** 使用。
+
+## 1. 五维心智模型（执行时要内化）
+
+执行任务时必须同时考虑以下五个维度：
+
+1. **第一性原理**
+   - 找系统不变量、硬约束、物理边界
+   - 不先问“用什么框架”，先问“系统真正不能妥协的是什么”
+
+2. **公理化思维**
+   - 契约先于实现
+   - 明确哪些接口、状态转换、schema、事件语义是不可破坏的公理
+
+3. **多模型思维**
+   - 至少用 3 个视角看问题：
+     - 数据流
+     - 状态机
+     - 时序 / 并发 / 排队
+
+4. **类比迁移**
+   - 遇到拥堵、震荡、雪崩、阻塞时，主动寻找物理同构：
+     - 队列 / 水库 / 缓冲
+     - 熔断 / 断路器
+     - PID / 弹性控制
+
+5. **反馈与验证**
+   - 没有可观测闭环的设计，不算完成
+   - 特别注意：
+     - 时滞
+     - 非线性
+     - 假阳性测试
+     - 真实环境与离线环境的分层差异
+
+详细方法论与例子见：
+
+- `references/gda-framework.md`
+
+## 2. 启动动作：先写 Control Contract
+
+在真正改代码前，先产出一个极短的控制合同 v2（可在回复、计划或审计文档里）：
+
+- **Primary Setpoint**
+  - 本轮最主要的目标变量，必须是一句能判断成败的话
+- **Acceptance**
+  - 哪些测试、命令、日志或指标能证明主目标已达成
+- **Guardrail Metrics**
+  - 哪些护栏指标不能被顺手打坏，例如错误率、尾延迟、成本、吞吐
+- **Sampling Plan**
+  - 用什么频率、在哪些观察点采样，避免只看一次结果就下结论
+- **Known Delays / Delay Budget**
+  - 已知时滞在哪里，以及本轮允许消耗多少时滞预算，例如 CI 排队、异步队列、缓存刷新、灰度传播
+- **Recovery Target**
+  - 如果本轮控制失败，允许多快恢复到安全状态，例如 MTTR 预算或回滚时限
+- **Rollback Trigger**
+  - 一旦出现什么信号，默认停止推进并回滚，而不是继续硬顶
+- **Constraints**
+  - 不能破坏什么硬约束、不变量、合规边界或真实环境前提
+- **Boundary**
+  - 本次允许触碰的模块、文件、配置、schema 与运行流程范围
+- **Coupling Notes**
+  - 这次改动会和哪些模块、共享接口、共享状态发生耦合
+- **Approximation Validity**
+  - 本轮采用的近似、stub 或离线验证在哪些条件下才成立
+- **Actuator Budget**
+  - 本轮允许施加多少控制输入，例如允许改代码、配置、观测点中的哪几类
+- **Risks**
+  - 1~3 个主要风险与缓解方式
+
+如果用户没给验收标准，先从：
+
+- issue
+- 失败日志
+- 现有测试
+- 文档契约
+
+中提炼；仍缺失时，补最小合理验收。
+
+## 3. GDA 四步执行骨架
+
+### Step 1：Axiom & Boundary
+
+开始前必须回答：
+
+- 系统真正目标是什么
+- 不能违反的硬约束是什么
+- 现有实现的关键不变量是什么
+- 物理/环境边界在哪里（网络、磁盘、数据库 schema、构建环境）
+
+### Step 2：Multi-model Construction
+
+至少同时建立以下三个模型中的两个，复杂任务必须三个都建：
+
+- **静态契约域**
+  - API / schema / 事件格式 / 配置项
+- **动态状态域**
+  - 状态机 / 生命周期 / 回调矩阵 / 状态收口
+- **容量与排队域**
+  - 队列、缓冲、吞吐、时滞、阻塞点
+
+复杂任务还应显式补一个**黑盒输入-输出影响矩阵**：
+
+- 把系统先当成黑盒，不急着解释内部实现
+- 先列：
+  - 当前准备调哪个 **control input / knob**
+  - 希望影响哪个 **output**
+  - 影响方向是增、减、延后还是收敛更快
+  - 会不会外溢到相邻模块、共享状态或共享基础设施
+
+如果系统是多变量耦合的，再补一个**解耦矩阵**：
+
+- 哪些输入主要影响哪个输出
+- 哪些输入会顺带打坏别的输出
+- 哪些输入必须成组调整，不能单独动
+
+一个典型例子：
+
+- 调高重试次数
+  - 目标 output：短期成功率可能上升
+  - 连带 output：尾延迟、下游 QPS、队列积压、成本可能一起上升
+- 调低限流阈值
+  - 目标 output：下游压力下降
+  - 连带 output：入口拒绝率、任务完成时间可能恶化
+
+默认规则：
+
+1. 复杂任务在改实现前，先列控制输入、目标输出、影响方向与外溢风险
+2. 如果一个 knob 同时强影响多个 output，默认把它视为高耦合输入
+3. 高耦合输入优先做小步试探，而不是一次拉满
+
+### Step 3：Cybernetic Control
+
+一次只施加一个最小控制输入：
+
+- 一个最强假设
+- 一个最小修改
+- 一组最便宜的验证
+
+如果出现振荡：
+
+- 降低步长
+- 回到最小 failing case
+- 加观测点，而不是继续盲改
+
+### Step 4：Closed-loop Verification
+
+验证必须分层：
+
+- **L0 快回路**
+  - lint / typecheck / 单测子集 / 静态审计
+- **L1 中回路**
+  - 相关模块测试 / 小集成
+- **L2 慢回路**
+  - 全量回归 / 真实环境 / 性能 / gate
+
+原则：
+
+- L0/L1 不稳定，不进入 L2
+- 离线通过不等于真实环境通过
+- 必须显式标注哪些风险只在 L2 才能验证
+
+## 4. 传感器工程（Harness Engineering）
+
+### 4.1 基线建立
+
+默认顺序：
+
+1. `git status` / `git diff`
+2. 读取 issue、相关代码、最近改动、已有 review
+3. 跑最便宜的验证路径
+4. 记录失败命令、失败用例、关键信号
+
+### 4.2 传感器去噪
+
+如果信号不稳定：
+
+- 重跑 3~5 次
+- 固定随机种子 / 时区 / 并发
+- 隔离外部依赖
+- 把偶现变成最小稳定复现
+
+### 4.3 特别规则：schema-sensitive 路径
+
+凡是涉及以下任一因素：
+
+- 真实数据库列类型
+- SQL cast
+- 驱动参数序列化
+- `PG_CH` / 真实 broker / 真实文件系统 / 真实扩展加载
+
+都必须明确区分：
+
+1. **语义测试**
+   - fake fetcher / stub / resolver 白盒
+2. **schema 契约测试**
+   - 锁定关键 SQL / schema / 分支行为
+3. **真实环境 gate**
+   - Windows / VPN / 真实数据库 / 真实 broker
+
+禁止把：
+
+- “resolver 语义通过”
+- “cargo test 全绿”
+
+直接写成：
+
+- “真实环境通过”
+
+### 4.4 动态控制病：采样与观测新鲜度
+
+性能和稳定性问题默认先审查观测质量，而不是先改实现。
+
+必须显式检查：
+
+- **采样周期**
+  - 采样过慢会把瞬时尖峰、短时雪崩、短时队列积压平均掉
+  - 采样过快但没有聚合窗口，会把瞬时噪声误判成系统趋势
+- **观测新鲜度**
+  - 延迟到达的 metrics、异步刷新的 trace、缓存后的 dashboard，可能让你基于旧世界做新决策
+  - 任何观测结果都要先确认时间戳、刷新周期和传播时滞
+- **采样别名**
+  - 用粗粒度采样看周期性抖动时，容易把真实震荡看成稳定
+  - 典型后果是把“周期性过载”误判成“偶发 flake”
+- **陈旧指标**
+  - 指标本身还在更新，但语义已经落后于当前发布版本、schema 或流量路径
+  - 典型后果是优化了旧瓶颈，却把新主链打坏
+- **观测盲区**
+  - 只看入口成功率，不看下游队列、缓存击穿、回放链路，会把局部成功误判成整体稳定
+
+默认规则：
+
+1. 遇到性能或稳定性问题，先写清本轮采样周期、观测新鲜度和主要盲区
+2. 任何“趋势判断”都必须说明观测窗口，而不是只引用单次结果
+3. 如果怀疑存在采样别名或陈旧指标，先补观测点或换采样方式，再决定是否改代码
+
+### 4.5 动态控制病：去抖、滞回、退避与冷却
+
+很多系统不是“控制能力不足”，而是“控制动作太频繁”。
+
+默认要检查四种抑振手段：
+
+- **告警去抖**
+  - 当同类告警在短时间内反复触发时启用
+  - 目的不是隐藏故障，而是避免把瞬时尖峰误当成稳定故障模式
+- **滞回区间**
+  - 当扩缩容、限流、熔断或降级阈值存在边缘来回抖动时启用
+  - 进入阈值和退出阈值不应完全相同，否则系统会反复横跳
+- **退避策略**
+  - 当重试、探测、轮询、恢复动作连续失败时启用
+  - 失败后必须扩大间隔，而不是用固定频率继续打系统
+- **控制冷却时间**
+  - 当一次控制动作刚施加、系统尚未完成传播和收敛时启用
+  - 在冷却窗口内默认禁止同类控制动作再次触发
+
+执行规则：
+
+1. 只要控制动作会修改阈值、流量、路由、重试或容量，就必须声明是否存在滞回和冷却窗口
+2. 只要恢复动作依赖轮询、重试或探测，就必须声明退避策略
+3. 默认禁止连续重复同类控制动作不带冷却窗口
+4. 如果没有去抖或滞回设计，任何“阈值附近反复跳变”都应先视为控制病，而不是先怪业务逻辑
+
+### 4.6 动态控制病：anti-chatter、anti-windup 与控制器冲突
+
+当系统已经进入震荡区，继续叠加控制器通常只会把问题放大。
+
+- **anti-chatter**
+  - 指防止控制动作在相邻状态之间高速来回切换
+  - 典型场景：熔断开关在半开与关闭之间反复横跳，或扩缩容在相邻副本数之间频繁切换
+- **anti-windup**
+  - 指防止控制器在执行器已经饱和时，仍然继续累积“应该再加一把力”的内部误差
+  - 典型场景：下游已经限流或队列已经打满，但上游重试、补偿或扩容信号仍不断叠加，最终形成重试风暴或扩缩容超调
+- **控制器冲突**
+  - 指两个及以上控制器同时修改同一 knob，却没有统一仲裁
+  - 典型场景：应用内重试、sidecar 重试、网关重试同时打开；HPA、队列消费调度器、人工扩容同时改副本数
+
+默认规则：
+
+1. 同一 knob 只能有一个主控制器，其他控制器要么只观测，要么通过明确仲裁接入
+2. 只要执行器已经饱和，就必须显式考虑 anti-windup，而不是继续累积恢复动作
+3. 只要系统出现高频开关、周期性回摆或阈值附近来回跳变，就必须先排查 anti-chatter
+4. 遇到重试风暴、补偿堆积、扩缩容超调，默认先查控制器冲突，再查业务逻辑
+
+### 4.7 无观测，不优化
+
+任何性能或稳定性优化，默认都要先拿到观测基线。
+
+最小入场券：
+
+- **trace**
+  - 先看跨服务链路到底卡在哪一跳
+- **flame graph**
+  - 先看 CPU / wall time 真正烧在什么调用栈
+- **profiling baseline**
+  - 先记录修改前的基线，不要只拿修改后的单次结果自嗨
+- **golden signals**
+  - 至少关注延迟、流量、错误、饱和度这类核心信号
+- **对照实验**
+  - 能做 A/B、shadow、canary 或前后对照时，优先做对照，而不是纯猜测
+
+默认规则：
+
+1. 无观测，不优化
+2. 观测不足时，默认先补观测点、profiling 或链路追踪，再决定是否改代码
+3. 任何“感觉这里慢”“猜这里有瓶颈”的说法，都不能直接升级成优化动作
+4. 优化结果至少要和修改前的 profiling baseline 做一次对照
+
+## 5. 决策准则
+
+当多个方案都能修时，优先：
+
+1. **最小风险**
+2. **最强可验证**
+3. **最可逆**
+4. **最符合模块业务区位**
+
+特别注意：
+
+- 不为了通过测试而偏离原始语义
+- 不为了抽象而扩大不该公开的 API 面
+- 不把测试便利性凌驾于模块职责之上
+
+### 5.1 机制优于策略
+
+默认优先设计“生成策略的机制”，而不是把人的经验直接硬编码成静态策略。
+
+默认禁止把以下对象直接写死成“经验常数”后就当作稳定设计：
+
+- timeout
+- retry 次数
+- 熔断阈值
+- 连接池大小
+- 扩缩容阈值
+
+优先选择的机制包括但不限于：
+
+- **自适应控制**
+  - 根据延迟、错误率、队列长度、资源利用率动态调整控制输入
+- **反馈回路**
+  - 让上一次控制结果影响下一次控制强度，而不是重复拍脑袋
+- **搜索或在线学习**
+  - 当最优点未知且环境持续漂移时，用搜索、探索或在线更新替代静态猜测
+
+裁决规则：
+
+1. 能用机制吸收环境变化时，默认不要把人的经验写成永久阈值
+2. 静态策略只能作为启动值、护栏值或临时保守值，不能伪装成长期真理
+3. 如果一个策略需要频繁人工调参，优先怀疑“缺机制”，而不是继续加参数
+
+例外条件：
+
+- 环境几乎不变、观测明确且失效成本极高时，可以短期采用静态策略
+- 但必须同时写清监控条件、失效信号与后续替换计划
+
+### 5.2 MTTR-first 与 crash-only
+
+对现代复杂系统，默认优先级不是“尽量永不出错”，而是“出错后多快回到安全状态”。
+
+默认裁决：
+
+- **MTTR 优先于 MTBF**
+  - 当两种方案不能同时兼得时，优先选择更快恢复而不是更长时间不出错
+- **crash-only**
+  - 遇到不可恢复、未定义或无法证明安全的状态，优先显式失败、退出或重启，而不是维持僵尸状态
+- **自动回滚**
+  - 只要风险可外溢到共享接口、共享状态或核心链路，就要优先设计自动回滚信号
+- **故障注入**
+  - 不能只验证“正常时能跑”，还要验证“坏了能多快恢复”
+
+执行规则：
+
+1. Control Contract 里的 `Recovery Target` 不是装饰项，必须给出恢复时间预算或安全回退时限
+2. 只要系统进入不可恢复状态，默认先显式失败，而不是静默维持
+3. 只要回滚条件可被机器识别，就优先设计自动回滚，而不是依赖人工盯盘
+4. 任何声称“高可用”的路径，都应至少经过一次故障注入或等价恢复演练
+
+特别注意：
+
+- crash-only 不是吞错后假装恢复，而是让失败可见、可重启、可回退
+- 快速恢复不等于快速掩盖，必须保留故障证据、恢复路径和恢复时间
+
+### 5.3 抽象审查协议
+
+抽象的默认目标不是“减少重复”，而是“减少错误耦合”。
+
+默认原则：
+
+- **允许 WET**
+  - 如果两段逻辑当前相似，但未来不保证一起变化，允许先物理重复
+- **优先物理解耦**
+  - 宁可保留两份小实现，也不要为了复用把两个生命周期不同的模块绑死
+- **按共变关系做抽象**
+  - 决定是否抽象的依据，不是代码长得像，而是未来是否真的会同时变化
+
+判定规则：
+
+1. 只要两个调用点的发布节奏、故障域或 owner 不同，默认先不要抽象
+2. 只要抽象会扩大共享 API 面、共享状态面或统一门禁面，先怀疑这是错误抽象
+3. 代码相似但业务语义、失败模式或演化方向不同，不应因为“长得一样”就抽象
+4. 在决定抽象前，至少回答一次：它们未来真的会同时变化吗
+
+反过来说：
+
+- DRY 不是被废除，而是要服从模块职责、故障隔离和长期演化
+- 如果抽象让系统更难切分、更难回滚、更难定位责任，就不是好抽象
+
+### 5.4 演进式架构与可逆决策
+
+复杂系统默认不是被一次性设计出来的，而是从简单可用系统逐步长出来的。
+
+默认原则：
+
+- **先长出简单可用系统，再逐步演化**
+  - 没有真实反馈前，不要预支未来 5 年的复杂性
+- **two-way door 决策优先快试**
+  - 可逆决策优先小步试、快反馈、保留回退路径
+- **one-way door 决策优先控边界**
+  - 不可逆决策必须先冻结契约、清点依赖、确认迁移窗口
+
+执行规则：
+
+1. 每个重要架构决策都应先判断它是 **two-way door** 还是 **one-way door**
+2. two-way door 决策优先用小范围实验、最小实现、短反馈回路验证
+3. one-way door 决策必须显式写出桥接期、回退条件和受影响模块
+4. 契约默认先稳后扩，不要在桥接期一边迁移一边改口径
+
+桥接期协议：
+
+- 迁移默认存在一个**桥接期**
+- 桥接期内优先使用：
+  - **shadow**
+    - 新链路跟跑、不接管主裁决
+  - **canary**
+    - 小流量、小范围、可快速回退
+- 桥接期结束前，默认保留旧事实源或旧主链作为对照基线
+
+如果一个方案：
+
+- 无法定义桥接期
+- 无法解释怎么回退
+- 无法说明契约何时冻结
+
+那它默认不是成熟的演进式架构方案
+
+## 6. 高风险反模式（必须主动检查）
+
+1. **假收敛**
+   - 单测通过，但真实环境条件未覆盖
+
+2. **双真相**
+   - 文档一套、主链一套、备用路径一套
+
+3. **影子实现**
+   - callback_dispatcher 更完整，但主链不用
+   - helper 存在，但主链不可达
+
+4. **弱断言**
+   - 只有 `is_ok()`，没有行为语义断言
+
+5. **测试驱动代码偏离职责**
+   - 为了测试方便扩大 `pub` 面
+   - 暴露本不该公开的内部实现
+
+6. **把离线测试当 gate**
+   - 真实 schema / 真实扩展 / 真实网络问题无法由 stub 替代
+
+## 7. 交付格式
+
+最终交付优先按下面结构组织：
+
+1. **Summary**
+2. **State Estimate / Root Cause**
+3. **Changes**
+4. **Verification**
+5. **Recovery Evidence**
+6. **Observability Evidence**
+7. **Residual Risks / Gate Boundary**
+
+其中：
+
+- **Recovery Evidence**
+  - 说明怎么恢复、多久恢复、触发了什么回滚或重启语义、恢复预算是否满足
+- **Observability Evidence**
+  - 说明依据什么判断问题存在、优化有效或风险仍在
+  - 至少给出本轮关键日志、指标、trace、profiling 或 gate 证据中的一类
+
+如果是长任务，还应同步：
+
+- 审计文档
+- 回归矩阵
+- handoff 文档
+
+## 8. 实战剧本
+
+### Bugfix / 回归
+
+1. 最小复现
+2. 最小 failing test
+3. 根因假设
+4. 最小修复
+5. 相关回归
+6. 全量相关回归
+
+### 测试补强
+
+1. 审计当前覆盖层次
+2. 找“语义层 / schema 层 / 真实环境层”缺口
+3. 先补最能拦截真实风险的离线测试
+4. 再补回归矩阵
+5. 最后明确 gate 边界
+
+### 架构收口 / 清理
+
+1. 先证明主链实际入口
+2. 再证明影子实现是否仍被使用
+3. 删除或收敛重复事实源
+4. 用测试或调用链审计防止回归
+
+### 性能退化
+
+1. 先拿 profiling baseline 与 golden signals
+2. 再定位是 CPU、IO、锁竞争、网络还是排队
+3. 画输入-输出影响矩阵，避免错改高耦合 knob
+4. 小步优化并做前后对照
+5. 记录收益、代价与残余风险
+
+### 异步队列背压
+
+1. 先确认队列长度、消费速率、重试率、死信情况
+2. 再区分是数据面过载、状态面卡死还是控制面误配
+3. 检查 anti-windup、退避与扩容是否互相打架
+4. 先止血，再恢复，再补治理
+5. 明确消息堆积的恢复边界
+
+### 迁移 cutover
+
+1. 先定义桥接期与冻结边界
+2. 再安排 shadow、canary 或双写对照
+3. 明确切流条件、回退条件、终止旧链路条件
+4. 分层验证 cutover 前、中、后状态
+5. 最后关闭桥接并归档证据
+
+### 部分故障 / 依赖 brownout
+
+1. 先确认故障是全挂还是 brownout
+2. 再查重试、熔断、降级是否放大故障
+3. 识别依赖是否已进入不可恢复状态
+4. 优先保主链和恢复预算
+5. 记录恢复动作和隔离边界
+
+### 配置回滚
+
+1. 先确认问题是否由配置变更触发
+2. 再识别配置属于控制面、数据面还是状态面
+3. 检查是否满足自动回滚触发条件
+4. 回滚后验证关键护栏指标是否恢复
+5. 补配置审计与冻结规则
+
+### Flake Triage
+
+1. 先稳定复现，确认是否真 flake
+2. 固定随机种子、时区、并发与外部依赖
+3. 区分测试抖动、环境抖动、时序抖动、观测误判
+4. 用最小观测点把偶发现象变成稳定信号
+5. 再决定是修实现、修测试还是修环境
+
+### 成本失控
+
+1. 先确认成本是流量驱动、重试驱动还是闲置浪费
+2. 再看哪个 control input 把成本推高
+3. 检查是否存在过量重试、过量扩容、过量缓存或重复计算
+4. 优先找可逆的小步降本动作
+5. 明确降本对成功率、延迟与可靠性的护栏
+
+### SLO 漂移
+
+1. 先确认是瞬时波动还是长期漂移
+2. 再看 setpoint、guardrail 与采样窗口是否仍有效
+3. 检查控制器是否已经失调或环境是否变了
+4. 优先调恢复与观测，再调业务逻辑
+5. 明确是改 SLO、改实现，还是改治理策略
+
+## 9. 引用导航
+
+如果需要更完整的理论和场景化方法，请按需读取：
+
+- `references/gda-framework.md`
+  - 五维方法论
+  - GDA 四步法
+  - 软件总体设计视角
+- `references/README.md`
+  - 引用索引
+- `assets/quickstart.md`
+  - 快速用法与交付模板