# SPEC-004: RSI 副轨漏洞巡检与原理级代码修复规范

- **规格编号**：`SPEC-004`
- **标题**：RSI 副轨漏洞巡检与系统级原理修复工程规格说明书
- **状态**：已批准 (Approved) ✅
- **关联 ADR**：[`docs/adr/0002-系统级原理修复与意图保真门禁架构.md`](../adr/0002-系统级原理修复与意图保真门禁架构.md)
- **关联研报**：[`docs/research/RESEARCH-007-SOTA标杆逆向解构与RSI副轨自动化治理架构实证研报.md`](../research/RESEARCH-007-SOTA标杆逆向解构与RSI副轨自动化治理架构实证研报.md)
- **统一语言遵循**：[`CONTEXT.md`](../../CONTEXT.md)
- **编写时间**：2026年10月

---

## 1. 用户故事与目标 (User Story & Objectives)

- **作为** 一名追求系统稳定与架构优雅的软件开发者/系统架构师，
- **我希望** 系统拥有能够自动感知深层机理漏洞、分析变更爆炸半径、杜绝投机补丁的后台巡航治理机制，
- **以便于** 在代码修复与迭代演进中，系统永远符合我的真实心智模型，彻底摆脱“改了A漏了B、按下葫芦浮起瓢”的疲惫循环。

---

## 2. 功能模块与技术实现规格 (Technical Specifications)

系统由三大核心工程脚本与工具链组成，位于 `scripts/` 目录下：

```mermaid
flowchart LR
    Diff["Git Diff / 代码修改"] --> Validator["1. 意图保真校验器<br>(verify_intent_fidelity.py)"]
    Diff --> Hunter["2. 爆炸半径分析器<br>(blast_radius_hunter.py)"]
    
    Validator & Hunter --> Crucible["3. RSI 副轨巡航引擎<br>(crucible_runner.py)"]
    Crucible --> Result{"门禁通过判定"}
    
    Result -->|通过| Pass["允许提交 / 架构完全保真 ✅"]
    Result -->|阻断| Block["拦截并生成机理因果证据链 ❌"]
```

### 模块 1：意图保真与反投机补丁校验器 (`scripts/verify_intent_fidelity.py`)
1. **输入**：待审阅的 Git Commit、暂存区变更或文件路径；
2. **审查规则**：
   - **规则 A (Anti-Bare-Try-Catch)**：检测是否存在无错误处理或仅打印日志而忽略根本状态损坏的裸 `try-catch` / `try-except`；
   - **规则 B (Anti-Defensive-Spam)**：检测在核心领域层是否滥用局部 `if (val == null) return` 伪修补，破坏了原本的契约前提；
   - **规则 C (Anti-Signature-Break)**：检测对外暴露的公共模块接缝（Seam）签名是否未经 ADR 授权发生破坏性变更；
3. **输出**：结构化 JSON 报告与终端高亮提示，发现违规立即返回退出码 1。

### 模块 2：AST 变更爆炸半径全域分析器 (`scripts/blast_radius_hunter.py`)
1. **输入**：修改的文件列表及符号定义；
2. **分析机理**：
   - 解析全工作区代码的抽象语法树（AST），建立符号定义与调用依赖关系图（Symbol Call Graph）；
   - 计算变更符号的直接调用集合（Direct Callers）与间接递归调用集合（Transitive Callers）；
   - 交叉比对本次 Git 变更集（Diff Files）：若某公共符号的调用方存在未修改的文件，发出**“散弹式修改遗漏预警 (Shotgun Surgery Alert)”**；
3. **输出**：输出变更影响拓扑图及未同步更新的关联调用位置（精确到文件名与行号）。

### 模块 3：RSI 副轨巡航对抗引擎 (`scripts/crucible_runner.py`)
1. **运行环境**：支持在当前工作区沙盒或独立 Git Worktree 中被调度；
2. **核心行为**：
   - 串联调用意图校验器与爆炸半径分析器；
   - 运行变异对抗探矿流程（检测边界条件、不变式守护）；
   - 当探测到系统级缺陷时，自动提炼出包含可复现断言的 Markdown 工单，并落盘至 `docs/issues/`。

---

## 3. 验收标准 (Acceptance Criteria)

1. **[AC-1 脚本可用性]**：`scripts/verify_intent_fidelity.py`、`scripts/blast_radius_hunter.py`、`scripts/crucible_runner.py` 均为纯原生零第三方外部依赖（基于 Python 标准库），可在任意环境中即时运行；
2. **[AC-2 投机补丁精准拦截]**：构造包含裸吞异常与无脑判空的测试补丁，意图校验器能够 100% 识别并成功阻断；
3. **[AC-3 爆炸半径拓扑输出]**：修改公共接口时，分析器能够完整列出所有调用方并准确提示未同步更新的目标；
4. **[AC-4 资产拓扑完备]**：在 `docs/issues/system-repair-rsi-loop/` 完整沉淀阻断示踪工单；在 `docs/index.html` 挂载 ADR 与 Spec 资产卡片。