# RAG + Karpathy(wiki) 攻关 · 总细则

> **效力**：本文件是「RAG + Karpathy(wiki) 攻关」这一**最重要项目**的总细则——人能读、可执行、每条都能判定。
> **上位规范**：`docs/internal/SEMANTIC-ARCHITECTURE-SPEC.md`（条款 S1–S10、§4 阶段门、§4.1 不采纳项、§5 施工顺序、§7 立场、附录 A–F）；接口与预算见 `docs/internal/THREE-LAYER-CONTRACT.md`（I1–I7、C1–C7）；白板契约见 `docs/internal/WB-FORMAT-CONVENTION.md`；排期见图 `docs/internal/TODO-GRAPH.html`，主线见 `docs/internal/ROADMAP.md`，待办总表见 `docs/internal/TODO-BACKLOG.md`。
> **建立**：2026-09-14。**边界**：不新增条款、不改接口形状；本文件只**下拆与判定**，条款冲突以 SPEC 为准。
> **纪律**：下文凡引用数字/行号/卡片 id 的，均为本次实际读取所得；未读到的写「未找到，需查」。

---

## 1. 一句话定位

**把「检索」从"每轮靠模型自觉去查"改成"设备端零 token 的自动注入 + 逐层下探取证"，同时把 Karpathy 式 wiki 的"索引即自然语言 / 整理 / 答案回流"落到本仓白板上。**

- 语义侧要解决的是 **S1/S2/S4/S5 四处草台**（SPEC §3 结论：本轮之前检索侧"算法"只有 S3/S6 是对的）。施工范围就是这四条。
- wiki 侧要解决的是 **S10 六条**（白板锚点进语料、索引派生、lint 补齐、答案归档回流、人机分区）。
- **与已完成的三层（open-viking 式）的关系**：三层 = 语义的**接口**（Tier-0 目录 / Tier-1 L0 摘要 / Tier-2 原文块），语义算法 = **层内算法**。接口没冻结就改算法 = 白改（SPEC §4 硬约束）。三层现况**未完成**：C1/C2/C4/C7 已完成，**C3/C5/C6 未做**（`THREE-LAYER-CONTRACT.md` §7 表；`TODO-GRAPH.html` P0-2 状态"施工中（C1/C2/C4 ✅；C3/C5/C6 待做）"）。此前"三层已做完"的判断已被明确纠正。

---

## 2. 成本模型（谁付费）

**判据不是"RAG vs 长上下文"，而是"谁付费" —— 且必须分档回答**（SPEC §7，**v2 分档口径**）。下表 = SPEC §7 v2 的分档表 + 补本仓选择列：

| 替代方案 | 真实主张 | 隐含前提 | 对最优档 | 对兼容档 | **我们的选择** |
| --- | --- | --- | --- | --- | --- |
| LLM Wiki（Karpathy） | 传统 RAG 的病是**没有知识积累**：每次查询都从零重新发现；改为让 LLM 渐进维护持久 wiki（实体页/概念页/交叉引用/矛盾标注/综合结论），靠 `index.md` + `log.md` 导航 | 写入侧与维护侧**由 LLM 长期承担**；原文称在"约 100 份资料、数百页"规模下**可避开嵌入式 RAG 基础设施** | ✅ 可用（查询侧多花 token 换整合质量） | ⚠️ 只能作**可选增强**（查询侧仍要 LLM 读页） | **吸收"索引即自然语言"**：Tier-0 目录 + L0 摘要 = 我们的 `index.md`；维护走**模板化写入**（自动沉淀 + 结构化日志），不让 LLM 自由重写 |
| Grep agentic（Claude Code） | "早期版本用了 RAG + 本地向量库，很快发现 agentic search 更好"；"模型驱动的 glob 和 grep 打败了一切"；GrepTool 默认只回文件名、`head_limit` 250 | **每轮多轮 LLM 工具调用**（token 乘数）+ 语料是**精确 token 可匹配**的 | ⚠️ 可作**补充臂** | ❌ 多轮即乘数；自然语言记忆没有可 grep 的字面 | **只吸收"要不要搜由智能判断"**，**默认**判断交给**本地线性分类器 fv2（0 token）**；不引入多轮 LLM（最优档若要，按 S9.2 带三件套） |
| 长上下文 / 全灌 | 每轮 token ∝ 语料规模 | 上下文无限、token 不计价 | ⚠️ 注入预算 `injectBudgetChars` 默认 **2000** 字符（可配）是硬约束 | ❌ 这一档正是 token 敏感 | **否决**；只给目录，命中不足才下探 |
| **本地检索（本仓）** | 设备算力，一次性，0 token | 设备能跑端侧嵌入（e5 / BGE-M3） | ✅ 主线（**允许叠加 LLM 增强**，按 S9.2） | ✅ 唯一契合 | **主线** |

| 路线 | 谁付费 | 最优档 | 兼容档 |
| --- | --- | --- | --- |
| 长上下文 / 全灌 | 每轮 token ∝ 语料规模 | ⚠️ | ❌ |
| Grep agentic | 每轮多次 LLM 调用的乘数 | ⚠️ 补充臂 | ❌ 最贵的一档 |
| LLM Wiki | 写入/维护侧 LLM token | ✅ | ⚠️ 可用，但必须模板化写入 |
| **本地检索（本仓）** | **设备算力，一次性，0 token** | ✅ 主线 | ✅ 唯一契合 |

**硬约束（v2 分档，SPEC S9）**：**兼容档** = **token 敏感 + 设备弱** → **S9.1（检索路径零额外 LLM token + 弱设备可跑）是这一档的硬约束**；**最优档**（首要用户 = 项目作者本人）= 以最优为目标，**允许**在检索路径引入 LLM，但每条必须带 **成本 + 门控 + 无 LLM 时的降级路径**三件套（**S9.2**）。两档**共用同一套接口与判据**（S9.3），**禁止**把"只能跑通兼容档"的设计当目标形态（S9.4）。
> **历史说明**：本文档 v1 时期写的是"轻度用户 = token 敏感 + 设备弱 → S9 是硬约束"，把兼容档约束当成了全项目硬约束 —— **那是定调错误，已按用户 2026-09-14 裁定更正为分档**。旧 S9.3 的"token 成本归贵侧、算力成本归设备侧"已并回 SPEC §7。

**由此推出的工程约束（SPEC §7.5 末）**：
1. 端侧嵌入必须**增量**（S1.3）——**两档共同**要求：兼容档上是"弱设备每写一条记忆就全量重嵌 → 风扇、电耗、卡顿"；最优档上是"索引追不上写节奏 → 静默丢弃注入"。
2. 查询侧加工（S2）**按档实现**：兼容档**必须本地实现**（规则（去指示词、抽实体）+ 本仓术语表 + 端侧小模型）；最优档可升级为 LLM 改写，但要按 S9.2 带三件套，且降级后回到那条本地路径。

---

## 3. 工作流总图

**六步链路**（`ROADMAP.md` §0 / `SEMANTIC-ARCHITECTURE-SPEC.md` §1）：

| 步 | 语义算力 | 本攻关归谁 | 判定条件 |
| --- | --- | --- | --- |
| ①产生 | 无 | 不在本攻关（B 线 procedural memory，P1-⑧ 封存） | — |
| ②存储 | **有**（分块/嵌入/索引） | **C 线** S1.3；A 线 C3 接线 | 改 1 条不触发全量重嵌 |
| ③选取 | **有**（查询理解→召回→精排→决策） | **C 线** S2/S4；S3/S6 已合规**不得削弱** | top-5 命中率、下探可达率 |
| ④注入 | **有**（压缩/预算/降级标注） | **A 线** C5；**C 线** S5.3 | 缺数据必带降级标注，不许静默 |
| ⑤晋升 | 无 | 不在本攻关（P1-⑧ 封存） | — |
| ⑥呈现 | 无 | **wiki 界面层，排在 RAG 之后（封存区）** | — |

**三条阶段线**（SPEC §4）：

| 线 | 内容 | 起点条件 | 可否并行 | 每步归谁 / 判定 |
| --- | --- | --- | --- | --- |
| **A · 接口冻结** | C3（接线 L0 向量索引 + 显式落 layer/status）→ C5（Tier-0 常驻 + 闸门 + 配额 + I7 降级标注）→ C6（三层验收套件） | 已开工 | — | 执行方；判据 = 契约 §7「验收判据」1–7 全绿 |
| **B · 立规与审计**（已启动） | 规范**已升至 v2**（§7 分档重写 + S9 拆条 + 数值口径统一）；按 S1–S8 逐条审实现；跑 E1/E3 三策略对照补齐 S7 基线 | 只要不跨界改接口即可开工 | ✅ 与 A 并行 | 执行方；判据 = **分档审计**（兼容档守住 S9.1 + 最优档每条重方案有三件套）+ 每条改造带三策略对照 |
| **C · 算法改造** | S1.3 → S5.3 → S2 → S4 | **A 全绿 + 宿主重启复核注入 Score 钉子** | ❌ 不得与 A 抢同一批文件 | 执行方；判据 = 每条一项能失败的断言 |

**依赖**：`④注入`(C5) 依赖 `②存储`(C3) 的层/状态列；`C 线` 全部依赖 `A 线`接口冻结。**C 线不得与 A 线抢同一批文件**（SPEC §4 表原话）。

---

## 4. 施工清单（阶段 C，按顺序）

| # | 条款 | 改哪个文件（实际路径与行号） | 判据（能失败的断言） | 成本 / 风险 |
| --- | --- | --- | --- | --- |
| 1 | **S1.3** 块级增量 | `python/m7_embedding_pre_v1.py:75`（`chunk_id_for`，块 ID 已内容寻址）；`lib/index-sync-pre.js:57`（`buildIndexSyncPlansPre`）/ `:62`（`miv` 取值）/ `:63`（只认 `idx_pre_` 前缀）；`lib/m4-corpus-pre.js:128`（`memoryIndexVersion` 出口）；`lib/shadow-retrieval-pre.js:145`（`memoryIndexVersion()` canonical tuples → `idx_pre_`+sha256） | 编辑 1 条只嵌变化块；删 1 条 = 零 encode（P0-4 crit 原文）；缓存键含**引擎身份**（引擎+模型+维度+归一化） | 约 1 天（P0-4 est）；**根因级**，改错 = 索引身份错乱 → 需带 S1.2 引擎身份断言 |
| 2 | **S5.3** 降级标注 | `lib/context-host-pre.js:352`（`pushDrop('index-not-ready:' + reason …)` 静默丢弃点）；`:185`（`diagCtx('ctx-host drop: …')`）；注入侧 `lib/activation-inbox-pre.js:250`（`renderReferenceTail`） | 索引未就绪期间注入**不丢空**——至少出现明确降级标注（P0-4e crit 原文）；`[语义索引未就绪 · 已降级为词法]` 字样可断言 | 约半天；低风险、止血症 |
| 3 | **S2.1/S2.2** 查询改写 + 多查询 | `lib/context-host-pre.js:230`（`buildObserveWindowText`）/ `:347`（现直接把该原文送去检索）；`:425` / `:515`（JS 决策侧同一文本） | 改写失败**必须回退原始 query**（S2.4），检索不得为空；改写后的 query 与原 query 各召回 → **共同融合**（不是取并集就地打分）；**离线可关**开关存在且默认行为可测 | 收益最大、风险最低（不碰索引、不碰接口）；**⚠️ 分档要求**：兼容档按 **S9.1** 必须本地实现（规则 + 术语表 + 端侧小模型）；最优档若做成 LLM 调用，按 **S9.2** 补三件套，且降级后回到本地路径 |
| 4 | **S4.2** 精排近似 → cross-encoder | `lib/index.js:4068`（P8 RRF 融合，`:4069` 注释 rank-space `1/(k+rank/divisor)`，`k=60`）；`lib/recall-fusion-pre.js:19`（`FUSION_RRF_K_PRE_V1 = 60`） | 先做 S4.2 近似级（融合序 + fv2 决策）并**在规范里标为近似**；精排器必须**离线可评估**；候选池 `K`=8 / `B0`=800 与 S7 判据就绪前**不上 cross-encoder** | 最贵、最后做；无资源时保持近似并标注 |

**每条都必须带**（SPEC §5）：S7 三策略对照 + 一条能失败的断言 + 引用的条款号。

**S1.2 相关**（未落，与 S1.3 同批）：缓存键 = **引擎身份** + 块 ID；换引擎即整库重建（**双引擎是 OR 关系**：普通用户 JS `multilingual-e5`，发烧友 Python `BGE-M3`）。

---

## 5. 隶属卡片映射

来源：`docs/internal/TODO-GRAPH.html` 的 `DATA.items`（本次实际读取，行号见下）。**未在图中出现的本攻关条目，一律标「不在图中」**。

| 卡片 id | 图内 lvl / 标题 | 图内现状（原文摘要） | 落在哪条施工项 |
| --- | --- | --- | --- |
| `P0-1` | P0-① 解锁会话检索 | 待开工（口径已定） | **本攻关前置**（D1 已拍板 C+B；依赖它才能跑检索） |
| `P0-2` | P0-② OpenViking 式三层补全（验收实测未过 · **阶段门**） | 施工中（C1/C2/C4 ✅；C3/C5/C6 待做） | **A 线全部**（C3/C5/C6）＝ 本攻关的开工条件 |
| `P0-3` | P0-③ 分级精确检索：Tier-0 目录 → L0 摘要 → 原文 | 待开工 | **A 线 C5** 的下探闸门；S5.2 配额 |
| `P0-4` | P0-④ 记忆增删 × 少重建：块级向量缓存 + 检索 fail-open | 待开工 | **施工项 1（S1.3）** |
| `P0-4b` | P0-④b supersede 改正语义 | 待开工 | S1.3 后半（supersede 声明 + 双层屏蔽）；P1-⑧ 依赖它 |
| `P0-4c` | P0-④c 差量同步：upsert + tombstone | 待开工 | S1.3（miv 退化为诊断用；缓存键改 `memoryId → recordDigest` 集合） |
| `P0-4d` | P0-④d 注入压缩上限 + 可排除来源 | 待开工（口径待 D4 确认） | **S5.2 配额 + S5.1 压缩**（C5） |
| `P0-4e` | P0-④e 索引同步防抖（实测卡死 20 分钟） | 已实测复现 | **施工项 2（S5.3）** + 施工项 1 |
| `P1-5` | P1-⑤ 验收判据换代：能力可达性套件 | 待开工 | **C6**（每条能力一个"默认配置下可达"的断言） |
| `P1-6` | P1-⑥ 白板 combine：实时进展 + 全流程可视化 | 契约层已落地（B 线）；**界面层封存（3.1）** | **第 7 节 wiki 契约层**；界面层排在 RAG 之后 |
| `P1-8` | P1-⑧ procedural memory 重构 | 封存（3.1） | 不在本攻关（依赖 P0-4b，但属 ⑤晋升步） |
| `P1-9` | P1-⑨ 语义架构规范 v2（已立）：用规范 RAG 策略清单审计并约束检索 | 规范已立（v2；B 线，可与三层施工并行）；**审计待跑** | **B 线全部**；四线顺序与 S9 分档审计在此卡 |
| `CHK-1` | P1-⑬ 记忆文件卫生：空行残留 / 标题层级 / 容量逼近上限 | 本机已复现（已清理一轮，机制待修） | 与 **S5.3/⑤** 相关（笔记容量 94% → 写入被拒会打断链路） |
| `P1-14` | P1-⑭ 语义臂会静默失效：miv 一变，0-1 相似度排序就消失 | 已实测复现（含根因） | **施工项 1 + 2**（块级缓存 + 显式降级标注） |
| `P1-15` | P1-⑮ 注入层不是语义唤回：注入块里看不到 0-1 相似度 | 已修（待宿主重启验证） | **C7 已落**（S5.4）；残留"注入层骨架未升级为 Tier-0 目录"归 **P0-③ / C5** |
| `P1-16` | P1-⑯ 三层检索的量化实验 | 词法基线已跑，待语义臂恢复后正式跑 | **第 6 节实验**（S7，E1/E3） |
| `P2-7` | P2-⑦ 跨 Agent 记忆入检索（外部文档 + 外部会话） | 待拍板（见 D5） | **不在本攻关**（依赖 P0-3；路径 C 分期） |

**说明**：`P0-1`/`P1-5`/`P1-6`/`P1-8`/`P2-7` 列在此表是**边界声明**（前置 / 依赖 / 明确不属本攻关），不是施工项。实际参与本攻关施工的是：`P0-2 / P0-3 / P0-4 / P0-4b / P0-4c / P0-4d / P0-4e / P1-5 / P1-9 / CHK-1 / P1-14 / P1-15 / P1-16`（共 13 张）。

---

## 6. 实验与判据（S7）

**核心纪律**：**没有实验就没有资格改算法**（S7）。每条改造必须带三策略对照。

**三策略（S7.1**，`THREE-LAYER-CONTRACT.md` §4.5 同名 E3）：

| 策略 | 内容 |
| --- | --- |
| **A** | 只给上层目录（Tier-0） |
| **B** | 目录 + 命中条摘要（Tier-0 + Tier-1 top-`K`） |
| **C** | 目录 + 候选集全灌（上限 `injectBudgetChars` **2000** 字符；旧文写 4800 是更早的默认值，已作废，见 SPEC §0.2） |

**四项指标（S7.2）**：`top-1/top-3/top-5 命中率`、`下探后答案可达率`、`注入 token 成本`、`噪声比`。
**判据必须能失败（S7.3）**：写成"若实现被改坏则报红"，不允许"声明了就算过"。

**当前词法基线（2026-09-14，词法臂，语义臂卡死期间；SPEC S7 现状基线原文）**：
- 3 条事实 → L0 **top-1 命中 1/3**、**top-5 命中 2/3**（`P1-16` 补充：m73 根因那条 top-5 未中）。
- 命中原因**全是词法、0 条带语义分**。
- 观察到单字母 token 污染（`词法×3(agent,检索,a)`）。
- **样本量 3 条 ⇒ 该基线只有方向性意义**；正式实验样本为 **12 条已知答案的事实**（`P1-16` 实验一定义），判据 **top-5 命中 ≥ 10/12 且下探后答案可达 ≥ 10/12**。**正式数字：待跑**（前置 = 语义臂恢复）。

**两个实验定义（`P1-16` 原文）**：
- **实验一 · 下探准确性**：12 条事实 → top-1/3/5 命中率 + expand 后答案可达率 + 每跳 token 成本 + 需要几跳。
- **实验二 · 直接灌是否够用**：同一批问题跑 A/B/C；指标 = 盲测答题正确率、注入 token 数、噪声比；**结论要能直接决定"中间概览层要不要补"**。

**预算校准（`THREE-LAYER-CONTRACT.md` §4.5）**：E1 扫 `L1 ∈ {60,90,140,220,400}`、`B0 ∈ {200,400,800,1600}`，记录命中率与答案可达率；选值规则 = **满足"答案可达率 ≥ 0.9"的前提下取最小预算**（膝盖点）；结果回写契约表并同步 `TODO-GRAPH.html` 的 P1-⑯。

**token 计量口径**：预算门取 `max(ceil(chars/2), 仓库口径)`（保守值恒 ≥ 仓库值）；仓库 `estimateSessionTokens = ceil(chars/4)+4`（`lib/index.js:2471`）**对 CJK 低估 2–4 倍**，直接当预算门会静默突破 I1。

---

## 7. Karpathy(wiki) 侧的落地（S10）

**S10 六条的施工拆分**（SPEC §8.3 表 + S10.1–S10.6 原文）：

| 条款 | 要做什么 | 载体 / 现状 | 判定 |
| --- | --- | --- | --- |
| **S10.1** 页面即语料 | 白板页面/卡片必须带锚点 `<!-- memory:mem_<32hex> -->` → 白板内容**自动进检索语料**，无需新机制；同时解掉"双状态源" | `WB-FORMAT-CONVENTION.md` §2 锚点契约（id = `mem_`+sha256(workspaceKey+页面路径+卡片标题) 前 32 位） | 每张卡锚点过 `^mem_[0-9a-f]{32}$`；重排 id 不变、改标题 id 变且旧 id 有 supersede 留痕 |
| **S10.2** 索引自动生成 | `index` 由页面**派生**（每条 = 链接 + 一句话 + `layer`/`status`），与白板**不得各写一份** | `WB-FORMAT-CONVENTION.md` §3 派生格式 | 派生出的 index 与 **Tier-0 目录条目一致** |
| **S10.3** lint 补齐 | 零 token 四类：①孤立条目 ②陈旧 ③被提及却无独立页 ④缺交叉引用；**只有"矛盾检测"需要 LLM，必须按需触发（用户点一下），不得进自动路径** | `WB-FORMAT-CONVENTION.md` §6 五类清单；**现状 = 缺** | 造一个孤立条目 → lint 报出；造一对矛盾结论 → 手动触发时报出；lint **只报告不自动改** |
| **S10.4** 不建状态机 | 白板是视图层；状态归**记忆条目**（`layer`+`status` 三值）与 sidecar；lint 只做只读检查 + 留痕 | 沿用既有拍板 | 新增状态 = 违规 |
| **S10.5** 答案归档回流 | 一次检索/分析的结论要能**一键**存成白板页面或记忆条目（现有 `memory_note_pre` / handoff 即为通道） | **目前半闭环**（SPEC 原文） | 任何"只活在对话里"的结论都算流程不合格 |
| **S10.6** 人机分区 | 模型维护区 / 用户备注区，`<!-- model -->` / `<!-- user -->`，整篇重写必须原样带回用户段 | `WB-FORMAT-CONVENTION.md` §5 | 模型整篇重写后 `<!-- user -->` 段**逐字节保留** |

**白板契约（`WB-FORMAT-CONVENTION.md` 五要素）**：锚点契约（§2）／lint 五类（§6）／人机分区（§5）／答案归档（§7）／写入门"只比对卡片集合，丢卡可检出"（§4）。

**顺序（已在 `TODO-GRAPH.html` P1-6 内定，2026-09-14）**：
- **契约层（格式 / 锚点 / 索引派生）必须在 RAG 底层之前** —— 它决定语料形状，先做 RAG 就得对语料重做一遍。→ 已提前进 B 线，落地为 `WB-FORMAT-CONVENTION.md` v1。
- **界面层（`lib/client.js` 渲染 / 看板交互）必须排在 RAG 之后** —— 它只是视图。→ **封存（3.1）**。

---

## 8. 不采纳清单（照 SPEC §4.1）

| 不采纳项 | 理由（SPEC §4.1 原文要点） |
| --- | --- |
| **迭代式 RAG（多轮检索/自省循环）** | 我们的场景是**每轮自动注入**，多轮检索会把延迟与 token 乘 2 以上；而"要不要检索"已由 **S6**（fv2 决策 + echo veto + 冷却）承担。迭代式 RAG 适用于"单次检索明显不够 + 允许用户等"的问答场景，不是本仓形态。**不作为默认形态（两档皆然）**；最优档若要当可选增强，按 S9.2 带三件套 |
| **重排（S4）：先做近似级，cross-encoder 留给最优档** | 在候选池（`K`=8 / `B0`=800）与 S7 实验判据就绪前上重排，只会增加延迟而无从证明它比 RRF 融合序更好。**先做 S4.2 的近似级，用实验说话**；判据就绪后 cross-encoder 作为**最优档**重方案上线（按 S9.2 标注成本），兼容档停在近似级 |
| **多引擎混排：禁止** | 双引擎是 **OR** 关系（JS `multilingual-e5` 或 Python `BGE-M3`），切换即整库重建；两套向量空间混排即错误结果（S1.2）。切换引擎属**换档**（S9.3 允许换引擎与预算） |
| （隐含）**Query 改写：兼容档不做 LLM 调用** | **S9.1**：兼容档检索路径零额外 LLM token。**S9.2**：最优档可以引入 LLM 改写，但凡要在路径上引入 LLM 的方案，**必须写明 token 成本、触发门控与无 LLM 时的降级路径**，三件套缺一不予采纳 |
| （隐含）**语义臂不可用时静默** | S3.3/S5.3/I7：必须显式标注，**不得静默** |

---

## 9. 风险与已知坑

| 坑 | 证据（文档原文 / 代码位置） | 对策 |
| --- | --- | --- |
| **整份哈希 miv ⇒ 写一条记忆就全库重嵌** | `lib/index-sync-pre.js:62` 取 `memoryIndexVersion`、`:63` 只校验 `idx_pre_` 前缀；SPEC S3 现状："索引身份是**整份语料哈希** `memoryIndexVersion`（`lib/index-sync-pre.js:57`），任何细节改动 → miv 变 → 全量重发 + 全量重嵌" | 施工项 1（S1.3）：块 ID 进缓存键，只嵌新增块 |
| **索引未就绪 ⇒ 静默丢弃注入**（曾是注入消失的直接原因） | `lib/context-host-pre.js:352` `pushDrop('index-not-ready:' + …)`；P0-4e 现场：诊断日志 07:43→08:01 每轮刷 `ctx-host drop: index-not-ready:sync-in-progress`（cv 175→612），期间注入被显式丢弃；P1-14 决定性证据：**每轮**都在 drop，从 07:43 起持续 20 分钟未就绪 → packet 归零 | 施工项 2（S5.3）：显式降级标注 + 防抖；未就绪期不得丢空 |
| **"不是重建慢，是同步状态机卡死"** | P0-4e 08:09 补测：worker 子进程 CPU 累计 659.4s、**3 秒内增加 0.00s（在闲着）**，索引产物 26 分钟零更新；对比此前一次重建只花 **6 秒**（07:42:50→07:42:56） | 别按"加速重建"下药；按"任务被反复作废/饥饿"复测 |
| **语义分整段消失 = miv 一变那条链** | P1-14 根因链：07:53:33 改项目笔记 → 语料变 → miv 变 → 新 miv 对应向量文件不存在 → worker 三重过滤（workspaceRef + scope + miv）返回空分 → 静默退化为纯词法 | 同施工项 1+2；并给 S8.2 语料/索引/向量三件套身份一次打印 |
| **`l0-index-pre.js` 曾零引用未接线** ⇒ L0 层没有自己的向量索引（现有向量是对**原文块**做的） | P0-2 实测缺口④、P1-16 原文 | A 线 C3 接线（模块已完成，接线点待做） |
| **`renderReferenceTail` 从不打印 `item.score`** ⇒ 看得见"要不要注入"、看不见"到底多像" | P1-15 原文：分值上游一直算得出来（`act.candidates[].score` → `packet.references[].score`），但只渲染 Source/Reason/Reference 三行；reason 串也只有 lane/decision/reasonCodes | **C7 已修**（`lib/activation-inbox-pre.js:210` `renderItemBlock` 增第四行；Python 侧 `python/worker_semantic_pre_v1.py:707` 补 `intent/dense/margin`） |
| **粗粒度注入骨架 ≠ Tier-0 目录** | P1-15 残留项：注入层骨架（日志尾/反思摘要/笔记头…）仍未升级为带 `layer/status` 的 Tier-0 目录 | A 线 C5 |
| **改 `TODO-GRAPH.html` 时把 ASCII 双引号写进 JS 字符串 ⇒ 解析失败** | **今日工作日志**记为 `Unexpected identifier`；本次在 `docs/` 内**未找到**书面记载（`grep` 无命中） | 改图统一用 `「」`；**每次改图必须跑 verify**（日志记载 verify exit=0 且卡片数不变） |
| **笔记容量逼近上限会打断链路** | CHK-1：笔记容量 **11,308/12,000 = 94%**，随时撞上"超容量 → 写入被拒" | 容量到 90% 就主动折叠，而不是等写入被拒 |
| **CJK token 被低估** | `THREE-LAYER-CONTRACT.md` §4.6：`estimateSessionTokens = ceil(chars/4)+4`（`lib/index.js:2471`）对 CJK 低估 2–4 倍，直接当预算门会**静默突破 I1** | 预算门取 `max(ceil(chars/2), 仓库口径)` |
| **三层同给必超预算** | 契约 §4.1 实测：`800 token(≈1600 字符) + 8×140 + 2400 = 5120 字符 > injectBudgetChars 2000`（旧文写 4800，是更早的默认值；改成 2000 后这个结论**更强**） | **逐层下探**，不同时给 |

---

## 10. 一页速查

**现在在哪**
> **状态校准（本行由 2026-09-14 口径同步轮补上）**：本节的 A 线旧文字（"C3 待接线、C5 待做、C6 待做"）**已过期** —— 按 `ARCH-REVIEW-BRIEF.md` §4.2 与实测：**C3/C5/C6 均已完成**，C5 套件 **83/0**、C6 套件 **122/0**（本轮复跑）。A 线状态以该文件为准；下面几条未逐条重写的旧描述请按此读。
- A 线（接口冻结）：C1/C2/C4/C7 已完成；**C3 已接线、C5 已交付、C6 已交付**（旧文字：C3 待接线、C5/C6 待做）。
- B 线（立规与审计）：规范 **v2** 已立（`SEMANTIC-ARCHITECTURE-SPEC.md`，v1→v2：§7 分档 + S9 拆条 + 数值口径），白板契约 v1 已立（`WB-FORMAT-CONVENTION.md`）；**审计待跑**、**S7 基线只有 3 条样本**。
- C 线（算法改造）：**未开工**（S1.3 / S5.3 / S2 / S4 全部待做）。
- 重启后已复核：注入块 `Score: 0.xx (rank n/m)` 出现且严格降序（**C7 钉子通过**）；但同批注入 reason 为 `intent=1.00 dense=0.00` ⇒ **候选全部来自词法臂，稠密臂零贡献**（列入实验线追查）。

**下一步做什么（按顺序，可直接执行）**
1. **C3 接线**：把 `lib/l0-index-pre.js` 的 `createL0IndexPre`（此前全仓零引用）接进端侧嵌入通道 `createJsSemanticEnginePre` 的 `embedPassages`，新增配置项（**2026-09-14 用户裁定：默认开** `l0IndexEnabled: true`，设 false 才回到零 IO）；接线点必须传 `layer`（`lib/l0-index-pre.js:171/192` 两条入口已透传 `layer`）。验收：`tests/smoke/smoke-test-l0-index-pre.mjs` 全绿 + 旧索引文件不被无谓重建。
2. **C5 注入层改造**：`lib/index.js` + `lib/context-host-pre.js` —— Tier-0 常驻目录（`lib/tier0-catalog-pre.js` 已出生成器，真实语料 **788 token ≤ 800**）+ per-layer 配额（`project ≤ 60%·B0`；`whiteboard`/`user` 各保底 10%）+ 闸门下探（默认只给 Tier-0；命中 < 2 条或问题含「为什么/怎么/具体/复现」→ 下探 Tier-1）+ **I7 显式降级标注**，并把 `lib/context-host-pre.js:352` 的 `index-not-ready` 静默丢弃改为**降级但仍注入目录层**。
3. **C6 验收套件**：`tests/smoke/smoke-test-three-layer-pre.mjs`，落地契约 §7 判据 1–7（尤其"造一条被 supersede 的记忆 → 断言它在**结果与注入两处都不出现**，但审计视图可见"+"故意破坏一个源文件 → 仍返回词法命中 + 明确降级标注"）。
4. **B 线补实验**：跑 E1（预算—召回曲线）+ E3（A/B/C 三策略），样本 12 条事实，回写契约 §4.3 表与 `TODO-GRAPH.html` P1-⑯。
5. **（A 线全绿 + 宿主重启复核 Score 钉子后）** 才启动 C 线施工项 1–4：S1.3 → S5.3 → S2（**兼容档必须本地实现；最优档要 LLM 改写则按 S9.2 另立**）→ S4。

**常用命令**
```powershell
node --test tests/smoke/                      # 全量套件（78 套件）；建议改走 tools/run-smoke.mjs（单套件超时按进程树强杀后继续）
                                              # 注：smoke-test-consolidate-isolation.mjs 的「忙等卡死」已于 2026-09-14 定案修复，无需再回避该套件
node tests/smoke/smoke-test-tail-score-visible-pre.mjs   # C7 钉子（29 断言）
node tests/smoke/smoke-test-tier0-catalog-pre.mjs        # C4 目录（33 断言）
node tests/smoke/smoke-test-l0-index-pre.mjs             # C3 L0 索引
node tests/smoke/smoke-test-layer-filter-pre.mjs         # 检索侧 layer/status 过滤（I5）
node tests/smoke/smoke-test-l0-layer-pre.mjs             # 抽取层 layer/status（C1）
node tests/smoke/smoke-test-doc-code-consistency-pre.mjs # 代码默认值 ↔ 文档「默认」标注（新增守卫）
```

**未确认 / 需查（不许猜）**
- 「`edit` 改图时 ASCII 引号写进 JS 字符串 → `Unexpected identifier`」：证据在**今日工作日志**，`docs/internal/` 内**未找到**书面记载。
- 正式实验数字（12 条样本的 top-1/3/5、下探可达率、A/B/C 正确率与 token 对照）：**待跑**（前置 = 语义臂恢复 + 重启）。
- 稠密臂零贡献（`dense=0.00`）的根因：**未定**，列入实验线追查（可能与 miv 未就绪/向量文件缺失同源）。
- `TODO-GRAPH.html` 中是否存在其他未被 `P0-*`/`P1-*` 前缀覆盖的本攻关卡片：本次按 `DATA.items` 全量读取（`:145`–`:366`），**未发现**漏项。