Legacy Archaeology

---
name: legacy-archaeology
description: 从老旧黑盒代码反推「树形索引、逐层下钻」的知识库（业务逻辑/数据库/接口三层），给重构 AI 注入背景。承诺「边界内可审计覆盖 + 残余风险显式登记」，不承诺零遗漏。触发词：「老代码考古」「反推知识库」「重构前背景」「把老项目翻译成文档」「legacy 调查」。
---

# legacy-archaeology（老代码考古）

> 把一个黑盒老项目反推成「树形下钻、业务/库/接口讲清」的知识库，给后续重构的 AI 做背景注入。
> **承诺只到「边界内可审计覆盖 + 残余风险显式登记」——不吹「我没漏」，只保证「我已识别的盲区、未证实项、未获取的真值源都显式登记了」。**

这个 skill 是一个**编排器**，不是文档生成器。它指挥主 agent 粗扫、切块、派出 agent team
逐模块调查，把结果汇聚成一棵 README 层层索引的知识库树。一个项目一棵树，多个项目共享一个
平台层调用图。重构 AI 平时只读 L1，要哪块钉哪块往下读：省上下文，又能审计到每一处盲区。

---

## §1 干什么 / 不干什么（边界）

### 1.1 只产三层，不碰其余
- **产出**：业务逻辑 / 数据库 / 接口。这三层讲清楚，足够给重构 AI 注入背景。
- **不碰**：需求文档、代码实现细节、测试。它们要么是重构后才重写的（需求），要么是被替换掉的
  （代码、测试）。把它们写进来只会增重、过期、抢上下文。
- **不描述代码**：讲的是「系统做什么决策、存什么数据、暴露什么契约」，不是「类怎么继承、方法怎么调」。
  描述代码 = 把旧包袱原样搬进新系统。

### 1.2 读者是 AI，不是人
- 风格**索引重、表格化、叙事轻**。每个目录一个 README 当导航节点，逐层下钻。
- 不写给人读的连贯散文；写给 AI 检索：标题密、锚点全、状态标注清楚。

### 1.3 一次性快照
- 老项目不再大改、不会继续腐烂，所以**不设防过期机制**。这是某一时刻的考古快照，带「快照批次号」。
- 推论：不必为「文档与代码持续同步」付出任何设计成本——那是 doc-layer-system 的活，不是这里的活。

### 1.4 承诺口径（地基，全文不得违反）
> **本 skill 不承诺「业务逻辑零遗漏」。** 白盒静态扫描无法证明「我枚举出来的 = 系统里全部」，
> 把无法证明的东西写成承诺就是自欺。
>
> 本 skill 承诺的是：**① 边界内可审计覆盖**（写下来的每条都有源码锚点、可回查）；
> **② 残余风险显式登记**（没覆盖到的、没证实的、失传的，全部明确列出来，不藏）。
>
> 任何产物、任何对账，**禁止出现「已查全 / 零遗漏 / 完整」字样**。只能说「在已知枚举边界内已覆盖，
> 未覆盖部分见残余风险清单」。

### 1.5 与其他 skill 的边界
本 skill 与 `code-to-guide`、`code-to-7layer` 机制有重叠，但定位不同。逐机制区别见
`references/与现有skill边界对照.md`。一句话：**本 skill 只产「重构背景知识索引」，不产需求结论、
不产七层正式真值**；能复用的已验证机制（fan-out、证据分级、硬暂停）尽量复用，不另造轮子。

---

## §2 产出落点 & 路径命名规范（索引承重墙）

**这个 skill 的路径就是索引本身。** 重构 AI「读 L1 → 钉下去」靠的全是各层 README 里的下钻链接，
链接就是相对路径。命名不钉死 → 增量建库（一次一个项目、跨多次运行）时结构漂移、导航断链。
所以路径规范是硬约束，不是建议。

### 2.1 固定骨架（雷打不动）

```
<知识库根>/
  README.md                    ← 平台总览（导航总入口）
  _platform/                   ← 下划线前缀，永远排最前、区别于业务项目
    service-registry.md        ← 稳定服务标识注册表（防重名 / 防仓名漂移）
    call-graph.md              ← 服务调用图（稳定标识做主键 + 悬空边 + 待接通清单）
    platform-coverage.md       ← 覆盖率总台账（各项目进度 + 残余风险汇总）
  <服务标识>/                   ← 一个项目一棵树
    README.md                  ← L1：概况 + 模块清单 + 可选流程/场景索引 + 台账链接
    discovery-ledger.md        ← 发现来源台账（枚举策略 / 命中范围 / 未识别入口）
    coverage-ledger.md         ← 对象覆盖台账（逐对象认领状态）
    <模块名>/                   ← 裸名，无前缀
      README.md                ← L2：模块概览 + 下钻链接
      business-logic.md        ← L3 叶子（固定 ASCII 文件名）
      database.md              ← L3 叶子
      api.md                   ← L3 叶子
```

### 2.2 三条硬规则
1. **每个目录必有 `README.md`** 作导航节点：列出本层子项 + 逐个下钻相对链接。缺一个就断链。
2. **叶子文件名固定三个 ASCII 名**：`business-logic.md` / `database.md` / `api.md`。AI 不用猜去哪读。
   - 为何 ASCII：文件名是机器导航锚点。中文文件名在不同 OS / `core.quotepath` / URL 编码锚点 /
     grep 脚本上行为不一致（会被转义成乱码）。**文件名/目录骨架用 ASCII，正文内容全中文。**
3. **链接一律相对路径**（整库可整体搬迁，本地解析）。

### 2.3 拆分规则（接 long-doc-governance）
- `business-logic.md` 写长了 → 升级成 `business-logic/` 子目录（内含 `README.md` 索引 +
  若干 `business-logic-<子主题>.md`）。升级方式固定，不让 AI 自由发挥。
- **拆分必须配套修链**：拆完跑一遍全仓链接校验，修复所有指向旧 `business-logic.md#锚点` 的引用
  （复用 long-doc-governance 的引用修复步骤）。漏修 = 断链。

### 2.4 服务标识（去仓名耦合）
- `<服务标识>` 是节点的**唯一身份**，登记在 `_platform/service-registry.md`。
- **新建一个服务目录前，先查注册表防重名。** 源仓库名 / 制品名只作「来源字段」记录，**不充当唯一身份**
  ——因为仓名会改、会重复、会合并拆分、可能含敏感缩写，押在它上面会让同一服务在调用图里分裂成两个节点。

### 2.5 输出落点
- 引擎**只硬要求一件事**：一个输出根目录 + 一个快照批次号。
- 「中央知识库仓」是**推荐布局**（所有服务树 + 平台层收在一处，重构 AI 一站式读），不是硬前提。
  没有独立知识库仓的团队，给一个根目录即可。
- 开工第一件事：向用户确认 **① 输出根目录 ② 本次调查哪个项目 ③ 快照批次号**（默认日期）。

---

## §3 编排总则（有预算、有终止、状态落盘）

主 agent 全权调度，但**不是无限自由**——必须有预算、有终止、状态不放在记忆里。

### 3.1 工具语义铁律（决定整套编排形状）
> **子 agent 一旦派出，跑完才返回，无法中途停下来问用户。**

所以一切「问用户 / 拿数据库 / 确认业务背景」的交互，**只能发生在主 agent 层、在某一轮 fan-out 结束之后**。
整个流程因此是**回合制**：派一轮 → 收齐回报 → 主 agent 消化（必要时问用户）→ 决定是否再派。

### 3.2 阻塞型 vs 非阻塞型不确定（子 agent 必须区分）
子 agent 在指令里被要求区分两类不确定：
- **非阻塞型**：不影响继续写（如「这个字段是否可配，拿不准」）→ 标【推测】或进候选区，继续写完。
- **阻塞型**：不查清这点整篇就建立在错误前提上（如「一个核心状态字段的语义直接决定业务逻辑怎么写」）
  → **立即停笔、缩小该分支产出、把阻塞点标「未决-阻塞」高优先级返回**，其余非阻塞分支继续跑完。
  > 宁可交一篇带明显空洞的半成品，也不要交一篇「自洽的错」。错的前提会污染整篇，对账还会显示「已认领」。

主 agent 收到「未决-阻塞」后，问完用户再**补派一轮**专门收口那个模块。**这个阻塞收口轮也计入该模块的
N 轮预算（见 §3.3）；N 轮耗尽仍有阻塞点，一律降级为「待人工」封板，不无限收口。**

### 3.3 预算与终止（防无限轮次 + 防上下文爆）
- **状态全落盘，不放主 agent 记忆**：未决点、台账、回报，全部写进磁盘文件。主 agent 每轮从文件读、
  处理、写回；自身上下文只承载摘要，不承载全局状态。一个大平台几十个模块，主 agent 记忆必爆，爆了
  「记得所有未决点」这条命根子就断了。
- **单模块轮次上限**：单个模块最多深挖 N 轮（默认 3），**阻塞收口轮也计入这 N 轮**。超限**强制封板**，
  把剩余未决点（含未决-阻塞）标「待人工」，不无限挖。
- **预算模型**：先粗扫建骨架（L1/L2），再按**风险优先级**下钻（核心交易链 > 边缘工具模块）。
  每一轮都产出**可停机的阶段性交付**——随时中断都能得到一棵「已枚举对象逐行有归宿、未覆盖部分已登记」的树。

---

## §4 步骤 0 · 认栈 & 定边界 & 批量索要外部输入

### 4.1 认栈
扫构建文件（`pom.xml` / `build.gradle`）、依赖、注解，判定技术栈，推导本项目的**枚举套路**。
不预设栈——常见组合（Spring MVC/Boot、MyBatis、Feign/Dubbo、RocketMQ/Kafka、@Scheduled/Quartz）
的枚举锚点见 `references/认栈枚举手册.md`；认不出的栈走该手册的**通用兜底法**。

### 4.2 一次性批量索要外部输入（关键：提到 fan-out 之前）
因为子 agent 中途停不下来（§3.1），凡是「需要用户给、需要外部系统拿」的东西，**必须在派 team 之前
一次性问全**，否则子 agent 只能干等或瞎猜。开工就向用户索要：

- **数据库 schema / 连接方式**：让子 agent 派出时手里就握着 schema。拿不到 → 见 §7.3 降级。
- **外部真值源**（用于 §5 枚举差集，不依赖技术栈）：网关路由表、注册中心服务列表、生产 access log
  的 URL 去重、MQ broker 的 topic 列表、DB 的 `information_schema` 表清单、crontab / 调度平台导出。
  能拿几样拿几样；拿不到的，在台账里登记「该真值源缺失」。

> 把「拿不到也得继续」设计进去：外部输入是**增强**不是**前置阻塞**。缺了就标低置信 + 登记盲区，不卡死。

---

## §5 步骤 1 · 搭双台账 + 外部真值源差集

覆盖率不能用一本账自证自己（台账由枚举生成，又拿台账给枚举对账 = 循环论证：枚举漏的项，台账里根本
没那一行，对账永远绿灯）。所以拆**两本台账**，再叠一层**外部真值源差集**。

### 5.1 发现来源台账（`discovery-ledger.md`）
记录**「我是怎么找的、找的边界在哪」**，而不是「找到了什么」。头部固定声明：

```
枚举来源：注解扫描 + MyBatis XML + Feign 接口     ← 用了哪些白盒手段
已知未覆盖：反射 RPC / 运行时动态拼接 SQL / 字符串拼 topic   ← 白盒手段照不到的盲区，主动列出
外部真值源：网关路由表[已比对] / information_schema[未获取→DB 层标低置信]   ← 每个真值源的获取与比对状态
```

> 「已知未覆盖」这一栏是诚实的核心——把白盒扫描照不到的地方**主动列出来**，而不是假装不存在。

### 5.2 对象覆盖台账（`coverage-ledger.md`）
机械枚举出的每个对象一行，认领状态收敛（见 §8）。列：类型 / 标识 / 源码锚点 / 认领文档 / 状态。
枚举类型：表、HTTP 接口、RPC、MQ 收发、定时任务、外部调用。模板见 `assets/对象覆盖台账模板.md`。

### 5.3 外部真值源差集（盲区探测）

**第一步·按服务边界裁剪真值源（关键，否则单项目视角会误报海量盲区）。** 网关路由表 / 注册中心 /
broker topic / `information_schema` 通常是**整个平台共享**的，里面绝大多数路由 / topic / 库表属于
**别的服务**。一次只查一个项目，直接拿全平台真值源做差集，差出的「盲区」绝大部分是别家服务的噪声，
真盲区被淹没。所以先按服务边界过滤：
- 网关路由表 → 按本服务的路由前缀过滤
- broker topic → 按本服务的 producer / consumer group 或 topic 命名约定过滤
- `information_schema` → 按本服务独占的库 / schema 名过滤
- **真值源切不开服务边界时** → 差出的项标「全局盲区（含他服务，待平台层裁剪）」，而非本项目盲区

**第二步·裁剪后再做差集：**

```
本服务的 information_schema 表 − 台账已枚举的表  = 白盒漏掉的表（盲区！）
本服务的网关路由 − 台账已枚举的接口            = 白盒漏掉的接口（盲区！）
本服务的 broker topic − 台账已枚举的 MQ         = 白盒漏掉的 topic（盲区！）
```

**第三步·逐项闭环，不许写一句汇总。** 每个差出来的盲区登进发现来源台账的「外部差集盲区清单」
（逐项：对象类型 / 外部标识 / 真值源 / 白盒缺失原因 / 处置状态 / 认领文档 / 剩余风险），
并且**每一项要么补查后补进对象覆盖台账、要么明列入残余风险**——**禁止**只留一句「发现 N 个漏掉的接口」。

**拿不到外部真值源时**，该类对象在对象覆盖台账的「分类置信度声明」里标
「仅白盒、未经运行时校验、可能漏列」——**绝不给绿灯**。

---

## §5b 粒度标尺（铁律，整 skill 的灵魂）

业务逻辑写到什么粒度，决定这个 skill 是「废话」「抄代码」还是「真有用」。

### 5b.1 试金石（判定单条该不该记）
> **「新系统违反了就是 bug」→ 记录；「只是旧代码碰巧这么写」→ 丢弃。**
> 即把「行为等价」翻译成动作：重写后必须保留才一致的，记；纯实现碰巧的，扔。

### 5b.2 但二分后移——子 agent 不在源头丢弃
判断一条逻辑「是有意的业务规则」还是「碰巧的实现」，需要**业务意图**，而这恰是黑盒老代码最缺、
无业务背景的子 agent 最判不准的。所以：

- **子 agent 阶段只做三件事：发现 → 保全候选 → 标证据强度。绝不在源头做「业务 vs 碰巧」的丢弃。**
- 模糊项默认进叶子文档的**「候选区」**小节（保留），不静默扔。
- 「是不是真规则」这个二分，留给**主 agent 在有业务输入的归并回合**裁决（用户能补背景时）。
- 理由：源头丢弃的东西，下游任何关卡都找不回来。宁可多保全、后过滤，不可早丢弃、永久失。

### 5b.3 业务规则单位 = 业务规则（不是方法、不是代码行）

**正面 · 按业务决策类型分类（一条不漏）：**
1. 状态机：状态 + 合法流转 + 触发条件
2. 判断 / 分支条件：真实谓词、阈值、资格规则
3. 计算规则：公式 + **运算顺序**（优惠叠加先后是经典暗雷）
4. 校验规则：校验了什么、规则是什么
5. 副作用 / 触发：发什么事件、调谁、写什么
6. 边界 / 异常的**业务**处理：超时、幂等、补偿、回滚（是业务行为，不是 try-catch 机制）
7. 隐藏规则：magic number、状态码语义、控制行为的配置开关、定时任务周期
8. **权限策略**（谁能做什么）
9. **租户隔离**（数据按租户隔离的规则）
10. **数据生命周期**（归档、软删、保留期）
11. **补偿流程**（失败后的业务补偿）
12. **批处理重跑**（批任务的幂等与重跑语义）
13. **灰度开关**（按开关切换的业务分支）
14. **配置驱动规则**（行为由配置表/中心决定的）

**负面 · 条件保留（不再「必丢」）：**
- 默认丢：代码结构 / 继承 / 设计模式 / DI、框架样板。
- **条件保留**：日志、纯技术异常、DTO 字段搬运——**若影响外部可见行为 / 合规 / 数据落库则保留**。
  遗留系统里它们可能承载审计、对账、兼容协议、监管留痕——丢了就丢了真规则。

### 5b.4 三粒度对照例

| 粒度 | 写法 | 判定 |
|---|---|---|
| 太粗 | 「系统会自动关闭超时订单。」 | ❌ 废话，重构 AI 学不到东西 |
| 刚好 | 触发:每 5 分钟扫【事实｜OrderJob:30】· 条件:待支付且超 30 分钟【事实｜OrderService:88】· 动作:置已关闭+回滚库存 · ⚠ 30 分钟是否可配【推测】 | ✅ 阈值/条件/副作用/不确定项齐全、挂锚点 |
| 太细 | 「OrderJob 用 @Scheduled 注入 OrderService，for 循环调 selectExpired()，执行 Mapper 88 行 SQL…」 | ❌ 在描述代码 |

### 5b.5 数据库标尺
- 丢**纯物理 DDL**（存储引擎、字符集、物理索引页）。
- **保留承载业务语义的约束**：非空 / 唯一 / 默认值 / 级联 / 精度长度（金额精度、唯一去重规则常**就是**业务规则）。
- 外加：字段业务含义、主键、**隐式外键（应用层 join 关系）**、状态码字典、揭示访问模式的关键索引。
- 粒度 = 「重建这张表 + 读懂它承载的业务语义所需的一切」，不是 DDL 复制。

### 5b.6 接口标尺
- **契约**：方法 + 路径、关键入参（带业务约束）、关键出参（带状态码语义）、幂等、鉴权。
- **运行语义**：重试、超时退化、错误码映射、调用顺序限制——**失败后业务怎么走**，正是重构最易踩雷处。
- **兼容性约束**：兼容旧字段。
- **谁在调它** 拆两栏：
  - 本服务内调用方（静态可确定）
  - 跨服务调用方（一次只查一个项目看不到别的服务，**平台层调用图只给到服务级调用方线索；要精确到「谁调我这个接口」须人工核对**，建库不全时标「未知/待补」）
  > 绝不把「调用方:A、B」写成完整列表——跨服务的 C、D 可能在别的服务里，漏写会让重构 AI 误判「可以放心改签名」。

### 5b.7 安全阀 & 长度
- 拿不准 → 记【推测】或进候选区，**绝不静默丢**。
- **长度靠拆不靠省**：业务规则一条都不许为压长度而省略；过长按 §2.3 升级子目录拆开。

---

## §6 步骤 2 · 切模块 & 派 agent team

### 6.1 主 agent 粗扫切块
先读项目结构（包结构、模块划分、构建子模块），把项目切成若干**内聚业务块**。切块要点：
- 跨切面（跨模块事务、共享状态、异步回调链）单独归口，别切碎到两个子 agent 各以为对方负责。
- 按风险优先级排序（§3.3），核心交易链先查。

### 6.2 子 agent 会话启动提示词（硬约束模板）

派出的每个子 agent 收到这样一份指令（照 task-control-doc §7 子任务工作包的「做完即停」写法）：

```
你负责调查【模块 X】，只产出三层：业务逻辑 / 数据库 / 接口。硬约束：

1. 不描述代码实现（不写类怎么继承、方法怎么调），只写「系统做什么决策、存什么数据、暴露什么契约」。
2. 每条业务规则必须挂源码锚点（文件:行 或 表.字段）。挂不上锚点的，不许写成事实。
3. 证据分级：代码能证=【事实｜锚点】；行为推断=【推测】；查到痕迹但细节已不可考=【待人工｜疑似失传】
   （你无权直接标「失传」，那是主 agent 走完三件套+人工背书才能定的终态）；是不是业务规则拿不准=进「候选区」。
4. 不做「业务 vs 碰巧」的丢弃——只负责发现、保全候选、标证据强度（见粒度标尺 §5b.2）。
5. 区分两类不确定：
   - 非阻塞 → 标【推测】或进候选区，继续写完。
   - 阻塞型（不查清整篇就建立在错误前提上）→ 立即停笔、缩小该分支产出、
     标「未决-阻塞」高优先级返回，其余非阻塞分支继续跑完。禁止瞎猜补全。
6. 产出落盘到指定文件，回填对象覆盖台账的认领状态。
7. 只做本模块，做完即停，把「待确认清单」（需用户补的业务背景 / DB 信息）随产出一并返回。
```

### 6.3 收集回报
所有子 agent 回报**落盘成结构化文件**，主 agent 只读摘要（§3.3）。回报含：草稿、待确认清单、
「未决-阻塞」高优项、台账认领回填。**回报落盘格式见 `assets/子agent回报模板.md`**（本轮产出文件 /
台账变更 / 未决-阻塞清单 / 待确认清单 / 建议补派范围 / 轮次计数），主 agent 二轮补派据此稳定消费，
不靠从自然语言里捞。

---

## §7 步骤 3 · 消化回报（自由轮次有上限）

### 7.1 主 agent 逐轮消化
从落盘的回报里读「待确认清单 + 未决-阻塞项」，决定：
- 需用户补业务背景 → 攒成一批，**一次性问用户**（不逐条骚扰）。
- 需深挖 → 在轮次上限内补派子 agent。
- 用户也不清楚、白盒也挖不动 → 按 §8 的失传门槛处理。

### 7.2 终止
持续到「无未决点」**或**触达单模块轮次上限（§3.3）。触上限则封板，剩余未决标「待人工」。

### 7.3 数据库硬降级（防死锁）
DB schema 在 §4.2 已尝试批量索要。若用户没给：
- **等一次**（明确再问一次）。仍没有 → 该项目**数据库层整层进「推测模式」**：按代码推断表结构 /
  应用层 join 推断隐式外键，**整层标低置信**，在台账登记「DB 层未经 schema 校验」，**带缺口完成**。
- 绝不因为缺 DB 信息就卡住整个流程不结束（那是死锁）。

---

## §8 步骤 4 · 台账对账（盲区显式登记）

### 8.1 逐行收敛
对象覆盖台账每一行的状态必须收敛到下列**终态或显式中间态**之一，无「待调查」残留：

| 状态 | 含义 | 进入门槛 |
|---|---|---|
| 已记录 | 有锚点、已写进某叶子文档 | 锚点齐 |
| 推测 | 行为推断、未被代码完全证实 | 标明推断依据 |
| 失传 | 已穷尽白盒 + 已问用户 + 用户确认不可考 | **三件套齐全 + 人工背书**（缺一只能标「待人工」） |
| 待人工 | 还没问用户 / 超轮次封板 | —— |
| 未决-阻塞 | 子 agent 报的阻塞点，待主 agent 收口（**仅过程态，对账前必须清空**） | —— |

> **「失传」是终态，权力很大（标了就不再查、对账也收敛），所以门槛最硬：必须三件套齐全且有人工背书。**
> 任何一件没做到，只能标「待人工」或「推测」，不许图省事洗成「失传」。**子 agent 无权标「失传」**
> （它给不了人工背书），最多标「待人工｜疑似失传」；「失传」只能由主 agent 归并 + 人工背书后回填。
>
> **「未决-阻塞」是过程态、不是终态**：最终对账前，所有未决-阻塞必须经补派收口转为「已记录/推测」，
> 或封板转「待人工」——诚实陈述里不出现未决-阻塞。

### 8.2 不给绿灯
对账完成 ≠ 宣称查全。对账的产物是一句诚实陈述：
> 「在已知枚举边界内，N 个对象已记录 / M 个推测 / K 个失传 / J 个待人工（无未决-阻塞残留）；
> 外部真值源差集发现的盲区见发现来源台账的『已知未覆盖』与『外部差集盲区清单』。」

**禁止**输出「已查全 / 零遗漏 / 完整」。

---

## §9 步骤 5 · 残缺性审计关卡（复用 adversarial-review）

收尾跑一道 `adversarial-review`，但**职责是「残缺性审计」，不是「完整性保证」**。

> 为什么改名：adversarial-review 拿文档评文档，能挑出「这条规则自相矛盾 / 这个分支讲不通」，
> 但它**没有独立真值源去发现「代码里有而文档里没有」的未枚举入口**——除非把整个老代码重扫一遍
> （等于把考古重做）。所以它检不出「漏了什么」，只能检「写错了什么」。把它当完整性关卡是名实不符。

这一关卡让评审 agent 重点审：
- **覆盖边界**：发现来源台账的「已知未覆盖」是否诚实、有没有漏列明显盲区。
- **枚举策略**：认栈枚举有没有明显照不到的入口类型。
- **未证明区域**：哪些【推测】其实证据薄弱、哪些「失传」其实没走够三件套门槛。
- 若 §5.3 已拿到外部真值源，在此做一遍差集核对。

产物是一份「残缺性审计意见」，补进残余风险清单。**不宣称「审计通过 = 完整」。**

---

## §10 步骤 6 · 回填平台层（增量）

每查完一个项目，往 `_platform/` 增量补一笔，**不要求一次建全**。

- **服务标识**：先在 `service-registry.md` 登记 / 查重（§2.4）。
- **调用图**：`call-graph.md` 的边用**稳定服务标识做主键**。被调方此刻可能还没建库 →
  这条边是**悬空边**，显式标「被调方未建库」，并登进**「待接通清单」**。
- **回接**：每新建一个服务，强制扫一遍待接通清单，把指向它的悬空边接通。
- **冲突不静默覆盖**：多次运行对同一调用关系可能给不同结论。增量记录带**时间 / 来源 / 置信度 /
  替代关系**；冲突时显式标注两个结论并存，不许后者悄悄盖掉前者。

---

## §11 产物格式 & 可选跨层索引

- 六个模板见 `assets/`：发现来源台账、对象覆盖台账、叶子文档（业务逻辑/数据库/接口三合一，含 L2 模块
  README 迷你骨架）、项目主 README、平台调用图、子 agent 回报。
- **可选跨层流程 / 场景索引**：异步补偿、事务边界、批量导入这类**跨「业务/库/接口」三层的流程**，
  三个叶子各记一段会割裂。在项目 README 的导航里加一个可选「流程索引 / 场景索引」小节，把跨层流程
  串成一条线指向相关叶子。保留三层叶子结构不变，这只是加一层跨层导航（按需，不强制）。

---

## §12 项目补丁挂载点

项目特定值不硬编码进引擎，运行时由用户提供 / 项目补丁声明：

| 挂载项 | 取值方式 |
|---|---|
| 输出根目录 | 运行时问用户 |
| 快照批次号 | 运行时问用户（默认当天日期） |
| 公司特有技术栈的枚举锚点 | 项目补丁补进 `references/认栈枚举手册.md` 的扩展区 |
| 服务标识映射规则 | 项目补丁声明（如何从仓名/制品名映射到稳定标识） |
| 外部真值源获取方式 | 运行时问用户（网关/注册中心/DB 在哪） |

---

## §13 执行禁止项（红线）

- **禁脑补当事实**：挂不上源码锚点的，不许写成【事实】。
- **禁描述代码实现**：讲决策/数据/契约，不讲类继承、方法调用链。
- **禁源头丢弃候选**：子 agent 不做「业务 vs 碰巧」的二分丢弃，只发现 + 保全 + 标级。
- **禁给绿灯**：拿不到外部真值源 / schema，整层标低置信、登记盲区，**绝不输出「查全/零遗漏/完整」**。
- **失传须三件套门槛 + 人工背书**，否则只能标「待人工/推测」；**子 agent 无权标「失传」**。
- **每个未决点必须有归宿**：已记录 / 推测 / 失传 / 待人工 / 未决-阻塞，五选一，无「待调查」残留；
  **未决-阻塞是过程态，最终对账前必须清空**（转已记录/推测，或封板转待人工）。
- **外部差集必须逐项闭环**：每个差出的盲区要么补进对象覆盖台账、要么明列入残余风险，
  不许只留一句「发现 N 个漏掉的接口」的汇总。
- **阻塞型不确定高优返回**，主 agent 二轮补派，不许子 agent 瞎猜补全写出「自洽的错」。