# dsh-auto-memory · RAG + Karpathy 实施方案与架构说明（v1） > **归档说明**：本文是第二轮投喂的产出（GPT-6 Astra），承接第一轮评审（`REVIEW-gpt6astra-20260914.md`）与核实表（`CLAIM-VERIFICATION-20260914.md`）。 > 投喂操作件见 `ARCH-REVIEW-ROUND2.md`。**本会话此前已压缩过一次，本文落盘前仅存在于对话中，是唯一持久副本。** > **性质**：待施工设计，不表示代码已修改或验收已通过；对方声明本轮未修改文件、未执行测试或 Git 写操作。 > **新增文件、函数、字段和配置均明确作为拟议接口。** 本文承接第一轮评审，直接采用核实表 C1–C12，不重新论证。以下内容是**待施工设计**，不表示代码已修改或验收已通过；本轮未修改文件、未执行测试或 Git 写操作。新增文件、函数、字段和配置均明确作为拟议接口。S1–S10、I1–I7 保持原文；涉及解释冲突的地方，在第三部分给出推荐裁决、影响范围和相反裁决的调整办法。 ## 目录 1. [① 目标态架构说明](#目标态) 2. [② 分阶段实施方案](#实施阶段) 3. [③ 准入与分档](#准入分档) 4. [④ 上一轮 A1–A3 的处置](#问题处置) 5. [⑤ 不需要做的事](#不需要做) ## ① 目标态架构说明 ### 1.1 目标与组件边界 **目标：最优档使用完整的本地混合检索能力，并可启用经过对照实验的查询改写和本地精排；所有档位经过同一套状态校验、快照校验、排序结果传递和最终预算组装。** 将“生成检索结果”和“把结果交给模型”分开。检索组件不能自行注入，渲染组件不能重新排序或把摘录冒充原文。Python 与 JS 负责可替换的计算实现，宿主负责共同的流程和契约校验。 ```text [用户配置 / 预算 / 增强授权] | v [记忆工具 / 自动沉淀 / 白板操作] [查询调度器：push + pull] | | v v [统一写入提交门] --------> [不可变 MemorySnapshot] | | | | Markdown / 状态记录 | | +--> [原文块读取] | | +---------> [Tier-0 目录] v v [后台增量索引调度] [词法臂 + 一个稠密引擎] | | [L0 / 原文块缓存] [共同排名融合] | | [JS 或 Python 引擎] [可选本地精排] | [fv2 决策 / 硬门] | [Tier-1 / Tier-2] | [状态、版本二次校验] | [唯一动态预算组装器] | [宿主输出 / 一次交付记账] ``` 逐组件落点如下。表中的新增模块只承担列出的职责，不另建通用框架。 | 组件 | 现有接点或拟新增模块 | 职责与禁止跨界事项 | 档位 | |---|---|---|---| | 写入提交 | [memory-writer-pre.js](D:/dsh-auto-memory/lib/memory-writer-pre.js)：`MemoryDocumentStore._queue/_commit/append/replace`；拟新增 `D:/dsh-auto-memory/lib/memory-mutation-pre.js` | 预期 digest 校验、事务恢复、状态提交、写后通知；不执行嵌入 | 两档共用 | | 统一语料与快照 | [m4-corpus-pre.js](D:/dsh-auto-memory/lib/m4-corpus-pre.js)：`buildSourceCatalog/loadCorpusSnapshot/CorpusRegistry`；拟新增 `D:/dsh-auto-memory/lib/memory-snapshot-pre.js` | 五层来源统一枚举；目录、词法、摘要、原文定位来自同一快照 | 两档共用 | | 身份计算 | [shadow-retrieval-pre.js](D:/dsh-auto-memory/lib/shadow-retrieval-pre.js)：`memoryIndexVersion`；[memory-anchor-pre.js](D:/dsh-auto-memory/lib/memory-anchor-pre.js)：`buildSidecar` | 区分内容身份、文件版本和请求版本；不比较哈希大小 | 两档共用 | | 索引调度 | [m7-index-sync-host-pre.js](D:/dsh-auto-memory/lib/m7-index-sync-host-pre.js)：`createIndexSyncHostPre/ensureIndexReady`；[l0-index-sync-pre.js](D:/dsh-auto-memory/lib/l0-index-sync-pre.js)：`sync` | 合并待办、保证同步前进、发布完整索引版本；查询不等待全库重建 | 两档共用 | | 嵌入缓存 | [l0-index-pre.js](D:/dsh-auto-memory/lib/l0-index-pre.js)：`assemble/update`；[semantic-js-pre.js](D:/dsh-auto-memory/lib/semantic-js-pre.js)：`buildIndexIfStale`；[worker_semantic_pre_v1.py](D:/dsh-auto-memory/python/worker_semantic_pre_v1.py)：`build_vectors` | 只编码实际缓存未命中的输入；出处与缓存对象分离 | 两档共用 | | 检索流程 | 拟新增 `D:/dsh-auto-memory/lib/retrieval-pipeline-pre.js`；接入 [context-host-pre.js](D:/dsh-auto-memory/lib/context-host-pre.js)：`onSegmentAccepted` 和 [index.js](D:/dsh-auto-memory/lib/index.js)：`recall` | 同一流程处理 push/pull；候选集宽度独立于注入 K | 两档共用 | | 融合与决策 | [recall-fusion-pre.js](D:/dsh-auto-memory/lib/recall-fusion-pre.js)：`rankFusionRRFPre`；[semantic-decide-pre.js](D:/dsh-auto-memory/lib/semantic-decide-pre.js)：`decideActivationV2` | 融合负责排名，fv2 负责注入决策；保留可复算特征 | 两档共用 | | 增强适配器 | 拟新增 `D:/dsh-auto-memory/lib/retrieval-enhancement-pre.js`；Python worker 增加精排请求处理 | 一次查询改写、本地 cross-encoder；不拥有注入出口 | 最优档 | | 三层装配 | [tier-layer-inject-pre.js](D:/dsh-auto-memory/lib/tier-layer-inject-pre.js)：`composeTieredInjectionPre/buildTier1SectionPre/buildTier2SectionPre` | 输出完整条目，保留身份、状态、出处；不自行查盘 | 两档共用 | | 最终预算与交付 | 拟新增 `D:/dsh-auto-memory/lib/memory-injection-budget-pre.js`；[index.js](D:/dsh-auto-memory/lib/index.js)：`renderMemoryDynamic/apply`；[activation-host-pre.js](D:/dsh-auto-memory/lib/activation-host-pre.js)：`renderTailFor` | 计量所有动态注入出口；只为实际输出的内容记交付 | 两档共用 | | 白板闭环 | 拟新增 `D:/dsh-auto-memory/lib/wb-contract-pre.js`；[index.js](D:/dsh-auto-memory/lib/index.js)：`writePlanSnapshot/writeHandoffLedger`；[client.js](D:/dsh-auto-memory/lib/client.js)：`PlanTab/SearchTab` | 写入门、用户区保护、索引派生、lint、答案归档；不新增白板状态机 | 两档共用；矛盾检测为最优档手动增强 | ### 1.2 写入路径 ```text 记忆工具 / 自动沉淀 / 白板保存 | v 准备 Mutation：txId、expectedDigest、正文变化、状态变化 | v 唯一提交队列 | +--> 白板结构校验 / 用户区校验 / 容量检查 | v 持久化恢复记录 | v 原子写正文 --> 更新 sidecar --> 提交记录状态与事务结果 | v 发布新的 MemorySnapshot，计算新的 miv | +--> 立即使旧候选失效 +--> 新快照的目录、词法立即可用 | v 后台索引队列：合并待办，但不反复取消正在执行的版本 | v L0 / 分块 --> 查缓存 --> 只编码 miss --> 校验完整性 | v 原子发布该 miv + engineIdentity 的索引 manifest ``` **［两档共用］** 写入成功不等待嵌入完成。成功只表示正文、状态和事务结果已形成可恢复的提交；语义就绪另有状态。这样能将“记忆已保存”和“该版本的语义索引可查询”分别验收，避免把索引延迟变成写入失败。状态提交必须先于新快照对查询可见。发生“正文已写、状态未提交”的中间故障时，受影响记录进入恢复检查，不能以默认 `current` 参与检索；其他完整来源仍可显式降级运行。 ### 1.3 查询路径 ```text push：接收 observation pull：memory_recall_pre(query) \ / +----> 构造 QueryRequest | v 固定一个 MemorySnapshot | v 原查询 + 可选一次改写（最多两条） | v 独立词法召回 + 当前选定引擎的稠密召回 | v current / scope / miv 校验 | v 共同 RRF 排名与去重 | v 可选 cross-encoder 精排 | v fv2 / echo / correction / 冷却门 | +-----------+-----------+ | | 无需下探需要下探 | | Tier-0 Tier-1 或经校验的 Tier-2 \ / +--> 最终状态与版本校验 | v 完整条目选择 + 全局预算 | +---------+---------+ | | 自动注入及交付 pull 工具返回 ``` **［两档共用］** Python 在目标态提供稠密查询和可选精排服务，主查询路径的融合、决策、最终排序在宿主统一执行。其余已有观察、证据等功能不随此次迁移删除；只解除 Python 对主路径激活决策的重复所有权。 **［两档共用］** 自动注入采用 `Tier-0 + Tier-1` 或 `Tier-0 + Tier-2`。进入 Tier-2 后，不再重复灌入同一条的完整 Tier-1 摘要正文；摘要仍用于内部选取。原文读取是一次检索结果的展开，不构成多轮检索。 **［两档共用］** 原文读取放在可等待的 pre-step 准备阶段，同步渲染回调只消费准备结果。现有等待接点在 [index.js:7386](D:/dsh-auto-memory/lib/index.js:7386)；现有动态出口在 [index.js:7437](D:/dsh-auto-memory/lib/index.js:7437) 和 [index.js:7515](D:/dsh-auto-memory/lib/index.js:7515)。这三处共同接线，不能只修中间装配函数。 ### 1.4 层间数据结构以下类型记法用于说明设计，实施仍使用 JavaScript ESM 与 JSDoc，不引入 TypeScript 构建依赖。 ```typescript type Layer = 'user' | 'project' | 'log' | 'reflection' | 'whiteboard'; type Status = 'current' | 'superseded' | 'retracted'; type SnapshotRef = { workspaceKey: string; miv: string; recordStateVersion: number; }; type SourceVersion = { sourceRef: string; sourceEpoch: string; sourceVersion: number; fileDigest: string; }; type RecordView = { memoryId: string; layer: Layer; status: Status; sourceRef: string; recordDigest: string; l0: string; byteStart: number; byteEnd: number; lineStart: number; lineEnd: number; }; type ChunkRef = { chunkId: string; memoryId: string; recordDigest: string; chunkDigest: string; byteStart: number; // 源文件中的 UTF-8 字节区间 byteEnd: number; lineStart: number; lineEnd: number; }; type MemorySnapshot = SnapshotRef & { sourceVersions: SourceVersion[]; records: RecordView[]; chunks: ChunkRef[]; degradations: string[]; }; type QueryRequest = { requestKey: string; observationId: string | null; sessionId: string; contextVersion: number; step: number; workspaceKey: string; scope: string; query: string; snapshot: SnapshotRef; deadlineAt: number; }; type RankedHit = { memoryId: string; chunkId: string | null; miv: string; layer: Layer; status: Status; sourceRef: string; recordDigest: string; excerpt: string; denseScore: number | null; lexicalScore: number | null; fusionScore: number; fusionRank: number; rerankScore: number | null; finalRank: number; }; type RetrievalResult = { requestKey: string; snapshot: SnapshotRef; engineIdentity: string | null; hits: RankedHit[]; ordering: 'rrf' | 'cross-encoder'; featureVersion: string; decision: object; degradations: string[]; }; ``` **［两档共用］** 缺失稠密分使用 `null`，不补成相似度零。`finalRank` 是排序结果，不能替代相似度；渲染次序与 S5.4 的关系依照第三部分 R1 执行。 `sourceRef` 必须经快照解析到允许的来源文件。候选携带的任意路径不能直接传给文件读取函数；块内容键也不能作为权限或出处身份。 ### 1.5 函数接口签名下列均为目标签名；现有公共记忆工具名称保持不变，内部返回结构统一扩展到两档。 | 接口 | 目标签名与返回值 | 落点 | |---|---|---| | 提交记忆变更 | `commitMemoryMutationPre({txId, expectedMiv, writes, stateChanges}) -> Promise<{ok, written, miv?, txId, reason?}>` | 拟新增 `memory-mutation-pre.js`；调用 `MemoryDocumentStore` | | 捕获快照 | `captureMemorySnapshotPre({workspaceKey, sources, recordStates}) -> MemorySnapshot` | 拟新增 `memory-snapshot-pre.js` | | 检验候选 | `validateHitSnapshotPre({hit, snapshot}) -> {ok, reason?}` | 同上；召回和注入两处调用 | | 规划编码增量 | `planEmbeddingDeltaPre({engineIdentity, previousAliases, vectorPool, inputs}) -> {aliases, missingInputs, removedAliases, stats}` | 拟新增 `D:/dsh-auto-memory/lib/embedding-cache-plan-pre.js` | | L0 更新 | `update({path, items, snapshot, engineIdentity}) -> Promise<{miv, encoded, aliasReused, contentReused, removed}>` | `l0-index-pre.js:createL0IndexPre` | | 入队同步 | `enqueueSnapshotPre({snapshot, reason}) -> {ticket, queuedMiv}` | `m7-index-sync-host-pre.js:createIndexSyncHostPre` | | 查询就绪状态 | `getSnapshotReadinessPre({snapshot, engineIdentity}) -> {ready, reason, buildingMiv?}` | 同上；不得触发同步等待 | | 执行检索 | `retrieveMemoryPre(request, {snapshot, lexical, dense, rewrite, rerank, policy}) -> Promise` | 拟新增 `retrieval-pipeline-pre.js` | | 排名融合 | 保留 `rankFusionRRFPre(pairs, opts)`；新增 `rankFusionListsPre({lists, k, divisor}) -> RankedHit[]` | `recall-fusion-pre.js` | | 读原文块 | `readVerifiedMemoryChunkPre({snapshot, chunk, signal}) -> Promise<{ok, text?, chunk?, miv, reason?}>` | `memory-snapshot-pre.js`；由 `index.js` 接入 | | 保存激活投影 | `recordTierGateHits(req, result) -> {requestKey, miv, contextVersion, observationId, hits}` | `activation-host-pre.js` | | 准备注入 | `prepareMemoryInjectionPre(agent, {step, deadlineAt, signal}) -> Promise` | `index.js` 新增方法 | | 三层内容装配 | `composeTieredInjectionPre({snapshot, hits, verifiedBlocks, question, limits}) -> {items, level, degradations}` | `tier-layer-inject-pre.js` 替换内部接口 | | 最终动态组装 | `composeMemoryEnvelopePre({requestKey, snapshot, items, dynamicSections, tailPacket, limits}) -> FinalEnvelope` | 拟新增 `memory-injection-budget-pre.js` | | 检查待交付尾注 | `peekClaimedPre(agent, {miv, step}) -> {ok, packet?, text?, exactDigest?, reason?}` | `activation-host-pre.js` 新增，无 seen 副作用 | | 确认交付 | `commitClaimedDeliveryPre(agent, {packetId, exactDigest, requestKey, step}) -> {ok, duplicate}` | 同上；幂等 | | 白板写入检查 | `validateWhiteboardWritePre({before, after, changes, actor, expectedDigest}) -> {ok, cards, errors}` | 拟新增 `wb-contract-pre.js` | | 白板 lint | `lintWhiteboardPre({cards, links, glossary, now, staleDays}) -> {findings, coverage}` | 同上；只报告 | | 归档结论 | `archiveAnswerPre({requestId, target, title, conclusion, evidenceRefs}, agent) -> Promise<{ok, memoryId?, path?, miv?, reason?}>` | `index.js` 新增方法，进入统一提交门 | 最终返回结构至少包含： ```typescript type FinalEnvelope = { requestKey: string; miv: string; text: string; chars: number; bytes: number; estimatedTokens: number; actualTokens: number | null; includedIds: string[]; omitted: Array<{memoryId: string; reason: string}>; deliveredPacketId: string | null; degradations: string[]; }; ``` 内部诊断信息不必全部塞入模型上下文；身份、状态、出处和必要降级说明必须随保留内容输出。计数由最终文本和实际保留条目计算。 ### 1.6 状态、版本与持久化所有权 | 对象 | 存在哪里 | 谁更新 | 谁校验 | |---|---|---|---| | 正文 | 现有 Markdown 文件 | 统一提交门调用现有 writer | writer 重读 digest；快照加载器 | | `sourceEpoch/sourceVersion` | 现有 sidecar | `buildSidecar`；内容变化增加文件版本，重建身份按既有规则处理 | 快照加载器、原文块读取器 | | `status/supersededBy` | 拟新增、按原始 `memoryId` 保存的状态清单；sidecar 可含派生投影 | `commitMemoryMutationPre` 是唯一写入者 | 召回、展开、注入 | | `recordStateVersion` | 状态清单 | 状态事务成功时递增；无变化不递增 | 快照生成与失效判断 | | `miv` | 快照对象、索引 manifest、查询结果、激活投影 | 由排序后的来源身份及状态清单摘要计算 | 查询、索引发布、原文读取、最终注入 | | `contextVersion` | 现有会话 runtime | 现有会话观察机制 | 查询归属、激活投递；不能替代 `miv` | | `requestKey` | 当前 runtime 的准备结果 | 每次 pre-step/查询分配 | 异步完成时、最终渲染时 | | `engineIdentity` | 缓存 manifest 与查询诊断 | 引擎适配器根据模型及处理配置产生 | 查缓存、索引加载、查询 | | `chunkId` | 当前快照的块清单 | 保留现有 `chunk_id_for` 规则 | 原文定位与一级缓存引用 | | `vectorKey` | 引擎独立的向量对象池 | 对实际编码输入计算摘要 | 嵌入缓存，不用于来源授权 | `miv` 是哈希身份，**不递增、不做大小比较**。先后顺序由事务序号、调度 ticket 和当前请求键决定。状态单独改变也必须改变 `miv`，否则撤回后仍可能命中旧结果。 **［两档共用］** 新索引写入新命名空间，先形成完整 bundle，再原子替换 manifest 指针。保留旧完整 bundle 用于恢复，但查询只有在 `miv` 与引擎身份匹配时才能使用它。新快照的语义索引未就绪时，使用新快照自己的词法和目录，不混入旧快照命中。 ### 1.7 保留块身份，增加计算复用按照第一轮结论，不能只把现有 `chunkId` 塞进缓存就宣称完成细粒度增量。推荐使用两级引用： ```text 一级：engineIdentity + chunkId | v 当前块的 alias | v 二级：engineIdentity + hash(exactEncoderInput) | v 实际向量对象 ``` **［两档共用］** 一级仍包含 S1.1/S1.2 要求的引擎身份和块 ID；二级依据块的实际编码输入复用向量。记录改变导致未改块重新编号时，只更新 alias，不重新编码相同输入。 `exactEncoderInput` 必须包含实际 passage 前缀、预处理结果或 token ID 序列；模型、tokenizer、池化、归一化及处理版本进入引擎身份。对展示摘录做哈希不足以证明编码输入一致。该设计兑现核实表要求的“按块内容复用”，不修改现有 `chunkId` 公式，也不把缓存对象误当作记忆条目。 --- ## ② 分阶段实施方案 ### 2.1 依赖顺序与验收方式 ```text Phase 0：注入边界和数值口径 | v Phase 1：状态提交与统一快照 | +--------------------> Phase 4：白板闭环 | v Phase 2：真增量缓存与同步 | v Phase 3：共同检索、融合与决策 | | +----------+--------------+ v Phase 5：对照实验与最优档增强 | v Phase 6：分档运行验收与发布 ``` - **［两档共用］** Phase 0 未通过，不接入新的在线算法。 - **［两档共用］** Phase 1 未通过，不发布差量索引或启用白板状态写入。 - **［两档共用］** Phase 2、3 的纯模块与 Phase 4 的纯校验模块可以并行开发；涉及同一个 `index.js` 的接线串行合并。 - **［最优档］** Phase 5 的增强适配器可用替身提前开发，但真实启用依赖 Phase 2、3、4 的稳定语料和结果。 - **［两档共用］** Phase 6 不以“测试数量”作为指标，以指定断言、失败注入与真实运行记录作为发布材料。拟新增套件统一命名为： `D:/dsh-auto-memory/tests/smoke/smoke-test-rag-phase-pre.mjs` 全部由 Node 启动，使用 `node:assert/strict`、替身 IO 和可注入时钟，零第三方测试依赖。涉及持久化的测试只使用隔离临时目录；涉及 Python 的测试由 Node 串行启动标准库测试入口并检查退出码和 JSON 结果。缺少真实 Python 运行环境时，标记该档“未执行”，不得当作通过。以下断言编号用于第四部分索引。 ### Phase 0：修复实际注入边界 **1. 目标［两档共用］：** 最终输出同时守住状态、版本、完整条目和总预算约束。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | [activation-host-pre.js](D:/dsh-auto-memory/lib/activation-host-pre.js)：`recordTierGateHits` | 替换 | 使用 1.5 签名，投影携带 `miv/contextVersion/observationId/requestKey`；不得仅凭时间复用 | | [tier-layer-inject-pre.js](D:/dsh-auto-memory/lib/tier-layer-inject-pre.js)：`composeTieredInjectionPre/buildTier1SectionPre/buildTier2SectionPre` | 替换 | 先验证 current 与快照归属，再组装完整条目；删除逐行裁剪方案 | | 拟新增 `D:/dsh-auto-memory/lib/memory-injection-budget-pre.js`：`composeMemoryEnvelopePre` | 新增 | 统一计算正文、目录、白板、账本、reflection request、尾注、标题及分隔符 | | [activation-host-pre.js](D:/dsh-auto-memory/lib/activation-host-pre.js)：`renderTailFor` | 拆分 | 新增 `peekClaimedPre/commitClaimedDeliveryPre`，将读取与交付副作用分开 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`apply/renderMemoryDynamic/buildTierLayerInjection` | 替换、仅接线 | pre-step 先刷新与校验，再准备；统一动态出口，原独立尾注出口退出 | | 拟新增 `D:/dsh-auto-memory/lib/memory-budget-pre.js`：`resolveMemoryLimitsPre(config)` | 新增 | 集中默认值、硬上限、单位、配置合法性；返回 `{ok, limits, errors}` | | [smoke-test-doc-code-consistency-pre.mjs](D:/dsh-auto-memory/tests/smoke/smoke-test-doc-code-consistency-pre.mjs)：字段检查 | 替换 | 覆盖全部预算字段与相互约束；只生成或校验数值附表，不改条款正文 | C10 的施工位置采用核实后的 [tier-layer-inject-pre.js:327](D:/dsh-auto-memory/lib/tier-layer-inject-pre.js:327)；C11 对应 [index.js:3986](D:/dsh-auto-memory/lib/index.js:3986)。直接按核实结果修复，不再重新取证。组装器先保留最小目录、边界标记和有界降级说明，再选证据和其他动态内容。删除完整条目后重新计算说明及计数，直至最终序列化长度达标；不允许在最后一次计量后追加未计费文本。 Phase 0 将已封装尾注视为不可拆包：整体放得下才输出。不能在 `exactDigest` 封装后截断尾注；后续精细分配必须发生在封包前。 **3. 能失败断言：** - **T0-1 状态：** 混合 current、superseded、retracted 候选直接进入实际注入入口；只保留 current 及其正文通过，旧条目出现或全部清空冒充成功失败。 - **T0-2 版本：** A 快照产生候选、B 快照准备输出；A 正文不出现且包含版本降级原因通过，A/B 混装失败。 - **T0-3 预算：** 同时启用所有动态段，遍历条目边界前后各一字符的预算；`text.length <= limit`、计数匹配、UTF-8 完整通过，超限或半条出处失败。 - **T0-4 交付：** 被预算排除的尾注 `seen=0`，重复渲染同一请求 `seen=1`，原尾注出口为空；任一不满足失败。 - **T0-5 异步：** 新请求先完成、旧请求后完成；最终 runtime 保留新 `requestKey` 通过，旧结果覆盖失败。 - **T0-6 数值：** 分别改变默认值、硬上限、单位或文档声明；不一致必须非零退出，数值一致但实际超限也必须失败。 - **T0-7 常驻：** 寒暄、日志冷却、无命中、索引未就绪均有受预算约束的 Tier-0 或明确空目录；整个目录被旧冷却分支跳过失败。 **4. 回滚动作：** 新增 `memoryInjectionMode='catalog-only'`，关闭 `memoryEvidenceBlocksEnabled`，保留新预算组装器及状态、版本检查。还原范围仅限本阶段的深层准备和尾注接线，不恢复已认证有缺陷的双出口扣账。若预算组装器本身故障，停用自动注入并记录停用原因，不把旧实现称作合规回退。 **5. 成本：** 额外 LLM 调用 token 为 0；增加一次最终计量和校验，时间与输出长度、候选数有关，具体延迟待测。每 runtime 只保留一个当前准备结果；无新增模型或第三方依赖。保留元数据会占用原注入额度。 **6. 风险与未决项：** 唯一动态出口可能改变宿主去重及交付时机，必须通过 T0-4 和 Phase 6 验证。推荐预算边界见 R3。Phase 0 不声称已经补齐持久撤回写入，后者由 Phase 1 完成。 ### Phase 1：统一状态提交与快照 **1. 目标［两档共用］：** 每次成功写入形成一个可恢复、可检索且状态一致的快照。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | 拟新增 `D:/dsh-auto-memory/lib/memory-mutation-pre.js`：`commitMemoryMutationPre/recoverMemoryMutationsPre` | 新增 | 全插件提交队列、恢复记录、状态清单与写后通知 | | [memory-writer-pre.js](D:/dsh-auto-memory/lib/memory-writer-pre.js)：`MemoryDocumentStore._commit` | 扩展 | 提交后回调携带 `txId/digest/dirty/sourceVersion`；dirty 不得伪装完整状态提交 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`appendText/writeFull/writeFullSingle/writePlanSnapshot` | 仅接线 | 所有相关写入进入共同提交门，工具不自行发布半更新的内存状态 | | [m4-corpus-pre.js](D:/dsh-auto-memory/lib/m4-corpus-pre.js)：`buildSourceCatalog/loadCorpusSnapshot/CorpusRegistry` | 替换、扩展 | 五层来源统一；损坏来源显式隔离；其他来源仍可读 | | [shadow-retrieval-pre.js](D:/dsh-auto-memory/lib/shadow-retrieval-pre.js)：`memoryIndexVersion` | 扩展 | 纳入状态清单摘要及快照格式版本；仍返回哈希身份 | | 拟新增 `D:/dsh-auto-memory/lib/memory-snapshot-pre.js`：`captureMemorySnapshotPre/validateHitSnapshotPre` | 新增 | 形成只读快照，提供 membership、状态及来源校验 | 事务恢复记录必须在修改正文前持久化，包含预期旧 digest、目标 digest、待提交状态和恢复所需内容。恢复时以实际 digest 判断继续完成或报告冲突；不能把已经成功写入的正文直接恢复成旧副本，覆盖作者后续修改。 supersede 由“新增声明＋旧 ID 状态变化”组成，原记录保持可审计。普通撤回不物理删除原文。状态清单是原始记忆状态的唯一持久所有者，fact/procedure 等派生存储不得反向充当其状态真源。 **3. 能失败断言：** - **T1-1 提交：** 成功提交后重启读取，正文、状态和 `miv` 同时可见通过，成功返回但状态丢失失败。 - **T1-2 故障：** 在每个持久化步骤注入异常后恢复；得到完整旧提交或完整新提交通过，半提交被当作 current 失败。 - **T1-3 撤回：** 先召回后撤回再注入；撤回 ID 在检索和注入两处均消失、审计仍可定位通过。 - **T1-4 并发：** 两个插件内写入并发，加一次外部 digest 冲突；内部写入不丢失、外部冲突拒绝覆盖通过。 - **T1-5 版本：** 仅状态变化时 `miv` 必变；完全不变提交时 `miv` 不变；按哈希字典序决定新旧失败。 - **T1-6 来源：** 五层各放一条合法记录并破坏其中一个来源；四层可检索且报告损坏来源通过，整链空白失败。 **4. 回滚动作：** 设置 `memoryMutationMode='readonly'`，保留状态读取、恢复和 Phase 0 校验；恢复本阶段 writer 接线前的代码必须同时禁止写入。不得回滚已提交 tombstone，也不得让旧代码忽略状态清单继续注入。 **5. 成本：** 额外 LLM token 为 0；每次写入增加恢复记录、状态提交和快照构建 IO。常驻增加有界快照及状态索引；磁盘增加事务记录和状态清单，无新增第三方依赖。成功写入不等待语义模型。 **6. 风险与未决项：** 是否存在多个宿主进程共享同一记忆目录属于 U2。推荐初版只允许一个写入 owner，第二个 owner 进入只读；进程内队列不能被宣称为跨进程锁。损坏状态清单必须恢复，不能用全体 current 兜底。 ### Phase 2：兑现真增量与同步前进 **1. 目标［两档共用］：** 实际编码量随变化输入增长，持续写入不再反复作废已开工同步。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | [l0-index-pre.js](D:/dsh-auto-memory/lib/l0-index-pre.js)：`assemble/update/buildFull` | 替换 | 先分类缓存命中，再调用 embedder；返回真实 `encoded` 等计数 | | 拟新增 `D:/dsh-auto-memory/lib/embedding-cache-plan-pre.js`：`planEmbeddingDeltaPre/materializeEmbeddingDeltaPre` | 新增 | 一级 alias、二级内容向量池、缺失输入去重与结果校验 | | [semantic-js-pre.js](D:/dsh-auto-memory/lib/semantic-js-pre.js)：`buildIndexIfStale/embedPassages` | 替换、接线 | 使用同一 miss 计划，不在查询入口全量编码 | | [worker_semantic_pre_v1.py](D:/dsh-auto-memory/python/worker_semantic_pre_v1.py)：`build_vectors/handle_index_commit` | 替换 | Python 采用相同缓存语义，发布完整 bundle | | [m7_embedding_pre_v1.py](D:/dsh-auto-memory/python/m7_embedding_pre_v1.py)：`chunk_id_for` 及分块辅助函数 | 保留、新增 | 保留 ID 公式；新增块原文字节区间、`chunkDigest`、实际输入摘要 | | [m7-index-sync-host-pre.js](D:/dsh-auto-memory/lib/m7-index-sync-host-pre.js)：`ensureIndexReady/ensureWorkspaceIndexReady` | 替换 | worker 级单飞、每工作区最新 pending、公平调度、最大合并等待 | | [index-sync-pre.js](D:/dsh-auto-memory/lib/index-sync-pre.js)：`buildIndexSyncPlansPre/sendIndexSyncPlanPre` | 扩展 | 后半阶段增加 `baseMiv/targetMiv/upserts/tombstones` | | [worker_pre_v1.py](D:/dsh-auto-memory/python/worker_pre_v1.py)：`handle_index_begin/page/commit` | 扩展 | 差量 base 校验、暂存、幂等提交；不匹配时请求完整快照 | | [l0-index-sync-pre.js](D:/dsh-auto-memory/lib/l0-index-sync-pre.js)：`sync` | 仅接线 | 共用快照和调度，不再独立决定语料身份 | C5 按修正位置 [l0-index-pre.js:126](D:/dsh-auto-memory/lib/l0-index-pre.js:126) 和 `:127` 施工；计数调整落在核实表 C6 对应返回结构。按三个小步交付：**2A L0 真增量 → 2B 原文缓存与完整 manifest → 2C 差量传输**。2B 可以仍传完整快照，但只编码 miss；这样先验证计算增量，再承担传输协议变化。调度时间取： ```text 开工时间 = min(lastDirtyAt + debounceMs, firstDirtyAt + maxWaitMs) ``` 后续写入更新 pending，不重置 `firstDirtyAt`。正在执行的版本只因明确超时、关闭、引擎 epoch 变化或数据损坏终止，不因新 `miv` 到来反复取消。缓存切换沿用 OR，引擎失败当轮直接词法降级，不在同一轮偷偷再跑另一个向量空间。 **3. 能失败断言：** - **T2-1 L0：** 记录真实 embedder 输入；不变更新为 0，单新增为新增输入数，状态变化为 0；只看返回计数不算通过。 - **T2-2 块复用：** 固定三块记录只改末块；前两块即使新 `chunkId`，alias 仍指向旧向量对象，实际只编码一个变化输入通过。 - **T2-3 输入身份：** 模型、tokenizer、前缀、归一化任一变化必须缓存 miss；不同引擎共享向量失败。 - **T2-4 删除：** 删除或撤回只移除有效 membership/alias，实际 encode 为 0，且旧内容不可检索。 - **T2-5 调度：** 虚拟时间每 50ms 写入，设测试参数 debounce=200ms、maxWait=1000ms；首次任务不晚于 1000ms 开工、后续写入不 abort active、worker active 数不超过 1 才通过。 - **T2-6 发布：** 每个 bundle 写入步骤故障后重启；不得出现 records 与 vectors 分属两个 `miv` 的 ready 状态。 - **T2-7 差量：** base 不匹配拒绝差量并完成一次完整同步；同一 tx 重放无重复，缺页不得发布。 - **T2-8 真适配器：** Node 串行调用 Python 标准库替身编码器，核对实际输入与 JS planner 的同组 fixture；仅 Node 协议替身通过不能代替此项。 **4. 回滚动作：** 先设 `indexDeltaSyncEnabled=false` 回到完整快照传输；必要时设 `embeddingCacheV2Enabled=false`，使用同快照词法路径。还原本阶段索引、worker、缓存文件的调用代码，保留 Phase 1 状态和 Phase 0 校验；旧、新缓存目录均不就地覆盖。 **5. 成本：** 额外 LLM token 为 0。首次建新缓存编码所有唯一输入，后续仅 miss；规划仍需遍历摘要或块清单，不能宣称全部处理均为 O(变化量)。内存包括当前与构建中 manifest、一个有界编码批次；磁盘包括 alias 和向量对象池。无新增模型依赖。 **6. 风险与未决项：** 前部插入可能改变真实分块边界，此时变化输入必须重新编码，T2-2 不承诺任意编辑都只重嵌一个块。生产 debounce、maxWait、缓存容量待 U1 实测；上述毫秒数仅是确定性测试参数。初版不做激进 GC，只回收不被已发布或在读快照引用的对象。 ### Phase 3：统一召回、融合与决策 **1. 目标［两档共用］：** push/pull 共用候选与排名流程，排序结果不会在后续投影或预算中丢失。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | 拟新增 `D:/dsh-auto-memory/lib/retrieval-pipeline-pre.js`：`retrieveMemoryPre` | 新增 | 固定快照、独立召回、状态过滤、融合、决策、结果封装 | | [context-host-pre.js](D:/dsh-auto-memory/lib/context-host-pre.js)：`onSegmentAccepted` | 替换 | 调共同流程，不再调用生产 D6 分数加权 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`recall/_jsDecide` | 替换、接线 | pull 使用同一结果；公共工具继续渲染既有返回形式 | | [recall-fusion-pre.js](D:/dsh-auto-memory/lib/recall-fusion-pre.js)：`rankFusionRRFPre` | 保留核心、扩展输入 | 复用既有 `k/divisor`；补多列表入口、稳定去重与 rank 元数据 | | [semantic-js-pre.js](D:/dsh-auto-memory/lib/semantic-js-pre.js)：`fuseD6Pre` | 删除生产引用 | 只作为对照 fixture 保留，后续清理导出另行机械检查 | | [worker_semantic_pre_v1.py](D:/dsh-auto-memory/python/worker_semantic_pre_v1.py)：`handle_recall_rank/_handle_context_push_impl/hybrid_rank` | 扩展、解除主路径调用 | 宿主拥有主路径融合和激活；worker 返回稠密候选与来源身份 | | [semantic-decide-pre.js](D:/dsh-auto-memory/lib/semantic-decide-pre.js)：`decideActivationV2` | 保留决策核、扩展外围 | 新增共同 `buildDecisionFeaturesPre(result, context)`，输出带版本的快照 | | [activation-inbox-pre.js](D:/dsh-auto-memory/lib/activation-inbox-pre.js)：`dedupeCandidates/renderReferenceTail` | 替换 | 传递排名元数据，不按裸稠密分重新决定候选选择 | | [tier-layer-inject-pre.js](D:/dsh-auto-memory/lib/tier-layer-inject-pre.js)：两层渲染函数 | 替换 | 按约定顺序消费完整条目；实施 R1 后由 `finalRank` 决定展示 | 词法臂必须独立扫描允许语料，不能只给稠密 top-K 打词法分，否则词法独有候选无法进入融合。初始试验设每臂最多 32 个候选，最终 Tier-1 仍受 K 限制；32 是可调整的候选预算，不是修改 K。多查询先在每个臂内融合，再融合词法与稠密两臂。原查询和改写查询不能通过重复命中同一个 ID 无限叠加票数。无改写时直接走现有双臂排名核心。决策同时记录 `denseTop/denseMargin/fusionMargin`，明确它们的来源；策略消费哪个 margin 必须带 `featureVersion/policyVersion`。不把新分布直接套进旧阈值。校准与上线按 R2、Phase 5 执行。 **3. 能失败断言：** - **T3-1 秩不变性：** 每臂排名不变、分数间距改变；融合 ID 顺序不变通过，否则失败。 - **T3-2 顺序贯穿：** 输入融合序与稠密序相反的 fixture；在 R1 模式下，选取、封包、裁剪、最终输出保留同一相对顺序通过。 - **T3-3 臂独立：** 词法独有候选能进入融合；关闭稠密后仍返回它且标注降级通过。 - **T3-4 决策一致：** 两适配器提供同一候选、纠正证据和上下文；共同特征与硬门结果一致通过，任一端漏掉纠正门失败。 - **T3-5 数据含义：** 缺稠密分保持 `null`；RRF 分不写成相似度；feature 版本与策略不兼容时拒绝在线启用。 - **T3-6 所有权：** 同一 observation 只能形成一个主路径 activation；宿主和 worker 同时 emit 失败。 - **T3-7 重复查询：** 同一列表重复同一 ID 不增加其贡献；原查询＋两改写的 ID 及 rank 可复算通过。 **4. 回滚动作：** 将新增 `retrievalPipelineMode='shadow'` 或 `'off'`，关闭在线增强，Phase 0 使用目录或同快照词法降级。还原 `context-host/index/worker` 的主路径接线时，不恢复 D6 作为“合规基线”；保持排名诊断和状态校验。 **5. 成本：** 基础路径额外 LLM token 为 0；融合主要为各列表排序与合并，内存随候选上限有界。Python 路径增加宿主接收候选的传输及处理成本，具体延迟待测。无新增本地模型。 **6. 风险与未决项：** R1 决定在线展示次序，R2 决定决策特征校准。两项未确认不阻止纯函数、投影和 shadow 实验，但禁止宣布新排序已符合 S5.4 或直接放量。worker 接口须有能力协商；旧 worker 不支持时退词法，不能同时保留双激活来源。 ### Phase 4：完成白板的写入、检索与归档闭环 **1. 目标［两档共用］：** 白板经过同一个写入门进入记忆语料，结论可以一次操作归档并再次检索。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | 拟新增 `D:/dsh-auto-memory/lib/wb-contract-pre.js`：`parseWhiteboardPre/validateWhiteboardWritePre/deriveWhiteboardIndexPre/lintWhiteboardPre` | 新增 | 锚点、卡片集合、用户区、索引、lint 的确定性处理 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`writePlanSnapshot` | 替换 | 所有预处理完成后比对最终待写版本；通过 Phase 1 提交 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`writeHandoffLedger` | 仅接线 | 账本保持历史追加，状态段只引用白板 | | [m4-corpus-pre.js](D:/dsh-auto-memory/lib/m4-corpus-pre.js)：`buildSourceCatalog` | 仅接线 | 使用 Phase 1 的白板来源，不另造白板索引身份 | | [index.js](D:/dsh-auto-memory/lib/index.js)：`archiveAnswerPre` | 新增 | 按目标保存卡片、记忆或 handoff；使用 `requestId` 防重复点击 | | [client.js](D:/dsh-auto-memory/lib/client.js)：`SearchTab/PlanTab` | 新增局部控件 | 对已有分析结果提供归档操作；手动 lint 入口；不重做看板界面 | 新增写入签名： ```typescript writePlanSnapshot(projectDir, content, { expectedDigest, actor: 'model' | 'user', changes: { renamed: Array<{oldId: string; newId: string}>; archived: Array<{id: string; reason: string; at: number}>; } }) // -> Promise<{ok, path?, addedIds?, changedIds?, miv?, errors?}> ``` 模型提交必须原样带回用户区，缺失或改动就拒绝；不能在拒绝后自动补一段“看起来相同”的文本。改标题需新 ID 与旧 ID supersede 同事务提交；同页重名导致 ID 冲突时拒绝写入。现有白板历史搬移也必须作为显式 archive 操作接受检查，不能绕过最终卡片集合比较。`archived` 是位置与审计记录，不增加第四种记忆状态。确定性 lint 的操作定义见 R5。语义矛盾检测只手动触发，在 Phase 5 接入模型；模型不可用时明确返回该项未检查，不能显示“无矛盾”。 **3. 能失败断言：** - **T4-1 写入门：** 少一张卡且无 archive/rename 记录时拒写，正文和用户区字节均不变。 - **T4-2 身份：** 同页重排 ID 不变；改名产生新 ID、旧 ID 状态变更与留痕同时可见。 - **T4-3 人机边界：** 模型更改用户区一个字节即拒写；合法模型区修改不改变用户区。 - **T4-4 同源索引：** 白板派生项与进入快照的记录身份一致；Tier-0 输出是经过状态、配额和预算选择后的同源子集。 - **T4-5 lint：** 给每条确定性规则一正一负 fixture，输出准确 finding；缺少语义检查显示 `notChecked`，不返回假阴性结论。 - **T4-6 回流：** 同一个归档 `requestId` 点击两次只新增一条；随后 recall 与展开能定位其结论和证据引用。 - **T4-7 写入冲突：** 用户在模型读后修改白板，旧 `expectedDigest` 的提交拒绝覆盖。 **4. 回滚动作：** 设置 `whiteboardWriteEnabled=false`、关闭新增归档按钮和矛盾检查入口；还原 `client.js` 局部控件以及 `writePlanSnapshot` 新入口调用。保留已提交状态及只读白板检索，不能重新允许绕过写入门整篇覆盖。 **5. 成本：** 确定性解析、校验、归档新增 LLM token 为 0；时间随页面长度与引用数增长。常驻只缓存当前白板解析结果，持久数据复用正文、状态和审计记录。矛盾检测成本单列 H3。 **6. 风险与未决项：** 老白板缺锚点或用户区时，先生成迁移预览，再由作者确认应用；不能把未分区文字自动认作可由模型覆盖。R5 定义 lint 的确定性范围；全文语义关系判断不在零 token 规则验收中。 ### Phase 5：实验、最优档改写与精排 **1. 目标［最优档优先；两档共用实验框架］：** 用可复现对照决定增强与预算是否启用，而不是以方案存在代替收益验收。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | 拟新增 `D:/dsh-auto-memory/tools/evaluate-retrieval-pre.mjs`：`runEvaluationPre/evaluateCasePre` | 新增 | 固定语料、题集、策略、引擎及版本；输出逐题证据与汇总 | | 拟新增 `D:/dsh-auto-memory/lib/retrieval-enhancement-pre.js`：`rewriteQueryPre/rerankCandidatesPre/checkWhiteboardConflictsPre` | 新增 | 有界、可取消、可替换的模型适配器 | | 拟新增检索流程：`retrieveMemoryPre` | 仅接线 | 原查询保留；改写最多一次；精排后统一重新过滤 | | [worker_semantic_pre_v1.py](D:/dsh-auto-memory/python/worker_semantic_pre_v1.py)：新增 `handle_rerank` | 新增 | 本地 cross-encoder 服务；模型缺失或超时返回结构化降级 | | [semantic-decide-pre.js](D:/dsh-auto-memory/lib/semantic-decide-pre.js)：策略加载外围 | 扩展 | 校验特征版本、策略版本、校准记录 | 目标增强签名： ```typescript rewriteQueryPre({request, budget, signal}) // -> Promise<{queries: string[], usage, elapsedMs, degradedReason?}> rerankCandidatesPre({request, candidates, budget, signal}) // -> Promise<{orderedIds: string[], scores, modelId, elapsedMs, degradedReason?}> checkWhiteboardConflictsPre({cardA, cardB, budget, signal}) // -> Promise<{findings, usage, checked: boolean, degradedReason?}> ``` 实施顺序为 **5A 基线与预算扫描 → 5B 单次改写实验 → 5C 本地精排实验 → 5D 二者组合实验**。每个增强先单独对照，不能只比较“全关”和“全开”，否则无法判断成本与收益来自哪一步。保留 S7 的 A/B/C 三策略，并在同一策略内比较增强开关。12 题作为已知事实验收集；增加无关查询、撤回、纠正、改名、失效索引等负例。调参集与最终验收集分离，不用同一批 12 题反复调参后再宣称泛化有效。最优档预算扫描以现有默认 2000 为基线，推荐试验 4000、6000 字符两个可配置总预算；这些是实验点，不修改冻结的分层上限，也不预设预算越大越好。 **3. 能失败断言：** - **T5-1 复现：** 固定输入、模型输出替身和版本，重复运行得到相同逐题结果及排名；缺少语料/策略身份的报告失败。 - **T5-2 原查询：** 改写超时、抛错、空结果、越预算时，原查询候选仍存在并有降级原因。 - **T5-3 限额：** 每个 request 最多一次改写、两条改写结果；超限输入跳过增强；超时后的迟到结果不能覆盖当前结果。 - **T5-4 精排：** 精排只能重排允许候选 ID；新增未知 ID、遗漏元数据、产生非有限分数均拒绝并回退 RRF。 - **T5-5 费用：** 故障、超时、重复触发也不突破预留预算；缺少可执行费用上限时不能启用在线改写。 - **T5-6 质量：** 相同预算下，增强组答案可达率高于对照、噪声比不升且所有契约断言通过，才进入作者试用；否则保持关闭。 - **T5-7 白板矛盾：** 替身检测器返回一对冲突证据时，UI/API 准确报告且不改白板；模型故障时标 `checked=false`。 - **T5-8 准入门：** 实验门要求 `top-5 ≥10/12`、答案可达 `≥10/12`；采用契约预算校准门 `≥0.9` 时，12 题必须至少 `11/12`，不得混用两个门。 **4. 回滚动作：** 分别关闭 `queryRewriteEnabled/crossEncoderEnabled/whiteboardConflictCheckEnabled`；恢复增强适配器的接线，保留 Phase 3 RRF、原查询和共同组装器。回滚不撤销已归档的作者确认结论。 **5. 成本：** H1–H3 的 token、延迟、内存、依赖和降级预算见第三部分，作为本阶段成本表。离线真实模型实验也会消耗 token，执行前计算“题数×策略数×开关组合×重复次数”的总预算。 **6. 风险与未决项：** 真实题集、计费接口、cross-encoder 模型资产分别依赖 U3/U4/U5。可以完成替身接口和可失败测试，但缺少这些材料不能把真实增强标记为可用。小题集通过只是本项目准入，不是普遍质量保证。 ### Phase 6：分档运行验收与发布 **1. 目标［最优档优先、兼容档降级保障］：** 作者可以稳定使用最优路径，组件失败时仍有经过实测的降级。 **2. 改动点：** | 文件：函数 | 改动类型 | 施工内容 | |---|---|---| | [index.js](D:/dsh-auto-memory/lib/index.js)：`loadConfig/saveConfig/debugInfo` | 扩展 | 校验档位、预算、增强授权与 manifest 能力；显示实际有效配置 | | [client.js](D:/dsh-auto-memory/lib/client.js)：现有设置与诊断控件 | 仅接线 | 展示实际引擎、降级原因、费用和资源结果，不另建配置体系 | | [tools/run-smoke.mjs](D:/dsh-auto-memory/tools/run-smoke.mjs)：`main/runSuite` | 原样复用 | 串行、超时、非零失败；不以此阶段重写测试运行器 | | 拟新增 `D:/dsh-auto-memory/tests/smoke/smoke-test-rag-phase6-pre.mjs` | 新增 | 宿主接线、故障切换、回滚、资源限额整体验证 | 按顺序运行：全部零依赖 smoke → Python 适配器 fixture → 作者设备真实 BGE 路径 → 兼容设备本地小模型与纯词法 → 持续写入与重启恢复 → 发行包隔离安装。发行包验收导入打包后的产物，不能把开发树通过直接转述为发行包通过。 **3. 能失败断言：** - **T6-1 零 LLM：** 兼容配置拦截所有生成式模型调用，调用数必须为 0，同时目录、词法和展开通过。 - **T6-2 故障降级：** 依次关闭 LLM、稠密 worker、索引文件和精排模型，均在登记期限内返回对应降级；无限等待或整轮静默空白失败。 - **T6-3 资源：** 指定设备、语料规模和负载下，P95 延迟、常驻/峰值内存、磁盘、索引积压年龄均不超过事前登记界限。 - **T6-4 切引擎：** 切换期间不混用向量；重建完成前明确词法降级；重启后状态与引擎身份仍一致。 - **T6-5 宿主：** 最终动态文本全量计费、Tier-0 常驻、尾注不重复、交付幂等；仅测中间字符串通过不算通过。 - **T6-6 回滚：** 按各阶段开关退回基础路径后，撤回项仍不出现，预算仍守住；回滚使旧状态复活失败。 - **T6-7 打包：** 在隔离目录从发行产物运行入口测试，禁止依赖开发树相对导入路径。 **4. 回滚动作：** 先关闭三个增强开关，再将 `memoryInjectionMode='catalog-only'`；索引问题关闭差量同步及新缓存读取。还原设置 UI 和发布接线时保留 Phase 0/1 的安全底座、已提交记忆和状态。 **5. 成本：** 基础验收不新增生成式调用；真实质量实验按 H1/H3 计费。性能测试增加临时运行成本，运行期诊断采用有界计数与环形记录，不无限追加常驻内存。无新增通用监控依赖。 **6. 风险与未决项：** U1 未完成时不能填写“兼容已验收”；宿主是否提供最终请求提交确认依赖 U6。当前交付记账边界只能明确为“文本已返回宿主回调”，不能等同于模型实际阅读。 --- ## ③ 准入与分档 ### 3.1 开关与档位下表是拟新增配置，不替换现有引擎选择项。最优档是目标预设；增强先通过 Phase 5，再由作者启用。 | 配置 | 用途 | 最优档 | 兼容降级 | |---|---|---|---| | `retrievalProfile` | 成本和能力预设 | `optimal` | `compatible` | | `memoryInjectionMode` | 共同注入器模式 | `full` | 正常亦可 `full`，故障退 `catalog-only` | | `memoryMutationMode` | 写入事故回退 | `readwrite` | 同左；事故退 `readonly` | | `memoryEvidenceBlocksEnabled` | 有界原文读取 | 开 | 可开；超时保留摘要并标注 | | `embeddingCacheV2Enabled` | 内容向量缓存 | 开 | 有模型时开 | | `indexDeltaSyncEnabled` | 差量传输 | Phase 2C 后开 | 同左 | | `retrievalPipelineMode` | 新流程放量 | `shadow` 验收后进入 `candidate` | 同一流程和规则 | | `whiteboardWriteEnabled` | 受保护白板写入 | Phase 4 后开 | 同左 | | `queryRewriteEnabled` | 生成式查询改写 | Phase 5 后作者显式开 | 强制关 | | `crossEncoderEnabled` | 本地精排 | Phase 5 后作者显式开 | 默认关，降级用 RRF | | `whiteboardConflictCheckEnabled` | 手动矛盾检测入口 | 可开 | 无模型时明确未检查 | 关闭增强不改变用户档位。引擎选择在一次查询开始时固定，失败当轮退词法；改选另一引擎是显式切换及重建流程，不是同轮混排。 ### 3.2 最优档重方案三件套下列数值是**建议的初始试验控制上限**，不是已测性能，也不是新规范常量。允许作者调高；调高后重新通过成本及质量门。 | 方案 | 成本与依赖 | 门控 | 无 LLM／不可用时降级 | |---|---|---|---| | **H0：BGE-M3 本地语义主线** | 生成式 token 0；首次编码全部唯一输入，增量编码 miss；常驻内存和耗时由 U1 测量；复用现有 Python 引擎资产 | 引擎身份、manifest 与请求 `miv` 一致，模型及设备预算就绪 | 无 LLM 不影响本地语义；引擎或索引不可用时，同快照词法＋目录 | | **H1：一次查询改写** | 每次总输入 ≤512、输出 ≤128，最多640个生成式 token；额外等待≤1.5秒；无新增本地模型，需服务适配器；作者付费 | 最优档、显式开启、复杂查询集合命中、当轮和累计费用有余额；最多一次、无重试 | 保留原查询及本地规范化；错误、超时、超额均标注；迟到结果丢弃 | | **H2：本地 cross-encoder** | 生成式 token 0；每批≤32对、每对模型输入≤512 token；建议额外等待≤750ms、模型驻留上限2048MiB；需兼容现有推理运行时的模型资产 | 模型预热完成、候选至少2条、预算充足、已过单独对照；同一 worker 有界并发 | 无生成式 LLM 不影响它；精排模型缺失、超时或结果非法时完整回退 RRF | | **H3：手动白板矛盾检测** | 每次输入≤1024、输出≤256，最多1280个生成式 token；建议等待≤5秒；复用 H1 服务适配器 | 用户明确点击、指定两张卡、费用有余额；一次调用，不自动扫描整库 | 确定性 lint 仍返回；矛盾项 `checked=false`，不生成“无矛盾”结论 | H1 的输入上限包含提示模板等全部计费输入；无法在上限内提交时直接跳过，不能只计算查询正文。超时请求仍可能计费，费用账本先预留上限，收到实际 usage 后结算；没有实际 usage 时保守保留预留值。 H2 的模型输入 token 是本地计算量，不是生成式 API 费用。冷加载不放在自动注入的等待链上；后台预热未完成时回退 RRF。U5 未提供真实模型资产前，只能完成适配器与替身测试。 ### 3.3 推荐裁决及相反选择的影响以下均标为**待作者确认**。推荐路线已写入阶段设计，不要求作者先回答才能开展不依赖裁决的工作。 | 编号 | 推荐裁决 | 理由与影响阶段 | 若作者选择相反裁决 | |---|---|---|---| | **R1 排序展示** | **最终选取、预算优先级和展示由 `finalRank` 决定，相似度独立呈现。待作者确认。** | 避免精排结果被渲染撤销；影响 Phase 3、5。该推荐与 S5.4/C7 若被严格解释为“按裸相似度排序”存在冲突，本文不宣称二者已兼容，也不改写条款 | 若坚持裸相似度展示，Phase 3 保留显式展示重排，精排只能影响入选集合；T3-2 改测选取序，不能继续承诺融合序贯穿展示；在线最优排序路线需重新评估 | | **R2 margin** | **同时保存独立稠密间隔和融合间隔，新策略消费带版本的融合间隔，必须重新校准。待作者确认。** | 融合后的前两名不一定是稠密前两名；影响 Phase 3 特征构造、Phase 5 策略实验 | 若保留原策略，旧 `margin` 的定义和阈值冻结，新特征只 shadow；不能把新分布直接交给旧阈值 | | **R3 预算边界** | **`injectBudgetChars` 覆盖一次请求中本插件全部动态注入，静态纪律与显式工具返回另记账。待作者确认。** | 消除独立出口各自取得完整预算的问题；影响 Phase 0、6 | 若只约束 ``，需为尾注等分别定义硬预算，并另设总动态上限；T0-3/T6-5 同时测分项与总项 | | **R4 共用契约** | **两档共用流程、字段和判据，允许适配器、数量和预算不同；自动注入采用目录＋当前所需的摘要或原文层。待作者确认。** | 落实 S9.2/S9.3，避免把“同路径”解释为相同模型调用；影响所有阶段 | 若要求逐字节相同或完全相同调用，Phase 5 只能成为独立显式工具，不能进入自动注入主路径 | | **R5 lint 范围** | **首版只对显式 ID、标题、术语表和链接关系执行确定性 lint，报告覆盖范围。待作者确认。** | “重要概念”“相关卡片”没有天然确定性判据；影响 Phase 4、H3 | 若要求任意自然语言概念与关系，增加最优档语义检查实验，不能仍以零 token 四类检查的名义验收 | | **R6 白板迁移** | **保留原文，先预览锚点和分区迁移；同页重排保留 ID，跨页移动按新身份＋supersede 处理。待作者确认。** | 现有 ID 公式包含页面路径，不能同时保证跨页移动 ID 不变；影响 Phase 4 | 若要求跨页移动保持 ID，需要单独处理身份规则变更及迁移；本方案不通过偷偷更改公式实现 | | **R7 数值与计量** | **定义源记录已批准数值，行为测试独立验证；字符估计只标估计，真实 tokenizer 计量另报。待作者确认。** | 防止“文档与代码一致”被当作“真实 token 上限成立”；影响 Phase 0、5、6 | 若只接受现有估计口径，仍可验收契约估计预算，但不得把报告中的 estimatedTokens 写成真实计费 token | R5 的初始可执行规则为：精确 ID/标题无入站引用报孤立；状态非 current 或日期超过配置阈值报陈旧；术语表中的词在至少两张卡出现却无对应卡时报缺卡；正文精确提到已有卡标题但没有其链接时报缺引用。建议陈旧阈值先设30天，均作为试验配置，不作为事实有效期，不自动撤回条目。 ### 3.4 需要补充的信息与不阻塞的施工范围 | 编号 | 缺失输入 | 如何取得 | 阻塞什么；仍可做什么 | |---|---|---|---| | **U1** | 作者与最低兼容设备配置、语料规模、写入负载、性能预算 | Phase 6 前登记设备与固定负载，测冷启动、P95、RSS、峰值、磁盘、积压年龄 | 阻塞性能认证；不阻塞 Phase 0–4 功能开发 | | **U2** | 是否多宿主共享同一记忆根目录 | 检查部署拓扑并登记支持范围 | 未确认时按单写 owner 设计；多进程写支持不得宣称通过 | | **U3** | 12题原始题集、证据块、负例、独立调参集 | 固定为只读实验 fixture，记录 corpus digest | 阻塞真实质量准入；不阻塞替身实验框架 | | **U4** | LLM 服务的计费输入、输出上限、usage、取消语义 | 用服务适配器验证能力并记录 | 阻塞 H1/H3 在线启用；原查询和确定性 lint 可用 | | **U5** | cross-encoder 模型、tokenizer、模型文件摘要与资源实测 | 按 H2 预算选择现有运行时支持的资产，实测 | 阻塞 H2 真模型启用；接口、回退和异常断言可做 | | **U6** | 宿主最终请求确认、去重和尾注交付语义 | 使用 Phase 6 宿主消息夹具及真实请求记录核对 | 阻塞“模型请求确实含该内容”的发布声明；可先验证回调输出与幂等 | | **U7** | 真实生成模型 tokenizer 的本地计量入口 | 提供计量适配器或真实 usage 对照 | 阻塞真实 token 硬上界声明；字符和契约估计预算仍可测 | --- ## ④ 上一轮 A1–A3 的处置本节只建立施工追踪，不重述已认证问题。 | 上轮条目／核实编号 | Phase 与排序理由 | 接口改动 | 断言索引 | |---|---|---|---| | **A1：C1/C2/C3，融合实现** | **Phase 3**；先有 Phase 0/1 边界及 Phase 2 可用索引，才能建立可信算法基线 | `retrieveMemoryPre` 共同入口；`rankFusionRRFPre/rankFusionListsPre` 返回 `fusionScore/fusionRank`；worker 主路径改为计算适配器 | T3-1、T3-3、T3-6、T3-7 | | **A1：C4，排序传递** | **Phase 3，R1 控制在线启用**；在此之前不叠加精排 | 激活候选、packet 内部投影增加排名元数据；`dedupeCandidates/renderReferenceTail` 消费约定顺序，`denseScore` 独立保留 | T3-2、T3-5 | | **A2：C5/C6，L0 实际编码量** | **Phase 2A**；先兑现最容易单独证明的增量计算 | `assemble/update` 先查缓存；返回 `encoded/aliasReused/contentReused/removed`；修改点使用 `l0-index-pre.js:126–127` | T2-1 | | **A2：C7，原文块复用** | **Phase 2B**；缓存计算身份与块出处分离后再做差量传输 | 保留 `chunk_id_for`；新增 `chunkDigest/vectorKey`、一级 alias 与二级内容池；`planEmbeddingDeltaPre` 返回实际 miss | T2-2、T2-3、T2-4 | | **A3：C8，双层状态过滤** | **Phase 0 修入口，Phase 1 补持久提交**；先阻止已知非 current 输入，再建立撤回闭环 | `validateHitSnapshotPre`；三层装配接收已固定快照；状态提交返回新的 `miv` | T0-1、T1-1、T1-3 | | **A3：C9，快照归属** | **Phase 0 透传和拒混版，Phase 1 统一快照所有权** | `recordTierGateHits` 增加 `miv/contextVersion/requestKey`；`composeTieredInjectionPre` 增加 snapshot；异步准备校验请求身份 | T0-2、T0-5、T1-5 | | **A3：C10/C11，预算统一** | **Phase 0**；后续成本和质量实验均依赖真实计量 | `composeMemoryEnvelopePre -> FinalEnvelope`；尾注拆分 peek/commit；修改裁剪采用修正位置 `tier-layer-inject-pre.js:327–335` | T0-3、T0-4、T6-5 | | **补充：C12，数值守卫范围** | **Phase 0**；为各阶段配置提供共同定义 | `resolveMemoryLimitsPre` 返回有效上限及单位；守卫检查完整字段与关系 | T0-6 | 没有提出对核实表的反驳，也没有重新改变第一轮的成因判断。两级缓存是对第一轮“仅加入现有块 ID 不足以兑现细粒度复用”的施工补全。 --- ## ⑤ 不需要做的事 - **［两档共用］** 不重写 S1–S10、I1–I7；本轮交付负责实现、接口和验收，解释冲突按 R1–R7 留痕处理。 - **［两档共用］** 不另建两套检索流程；共享调度、融合、决策和注入，计算能力通过适配器替换。 - **［两档共用］** 不改现有 `chunkId` 来掩盖缓存问题；两级引用已能在保留身份规则的同时复用相同输入。 - **［两档共用］** 不把旧向量结果与新目录拼装成“不断供”；新快照词法降级才保持 I6。 - **［最优档］** 不把多轮检索、自省循环设为默认；先完成一次检索中的查询加工和精排对照。 - **［两档共用］** 不在渲染末尾随意截字符串；出处、状态、计数和交付 digest 都依赖完整条目。 - **［两档共用］** 不为“测试更容易通过”预先过滤 fixture 或只检查返回计数；验收直接挑战真实入口和实际编码调用。 - **［两档共用］** 不新建白板任务状态机、跨目标依赖图或重做看板 UI；Phase 4 只补契约和归档闭环。 - **［两档共用］** 不用自动语义判断改写用户区、撤回记忆或修复 lint；模型检查只报告，写入仍走唯一提交门。 - **［最优档］** 不同时启用改写和精排后只测组合效果；先单独归因，再验证组合收益。 - **［两档共用］** 不迁移缺少可信引擎身份的旧向量；一次重建新缓存比错误复用更可验证。 - **［两档共用］** 不把关闭增强、降低能力或缺少测试环境写成“已验收”；发布材料逐项记录通过、失败和未执行。