From 4963d702150b10f82d1fdb12e20fa777af5a51f8 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 31 Oct 2026 08:20:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=80=90=E7=AF=87=E6=A0=B8=E5=AE=9E?= =?UTF-8?q?=E5=85=A8=E9=83=A8=E6=96=87=E6=A1=A3=E7=9A=84=E5=AE=8C=E6=88=90?= =?UTF-8?q?=E7=8A=B6=E6=80=81=20=E2=80=94=E2=80=94=20=E4=BF=AE=E6=AD=A3=20?= =?UTF-8?q?6=20=E5=A4=84=E4=B8=8E=E4=BB=A3=E7=A0=81=E4=B8=8D=E7=AC=A6?= =?UTF-8?q?=E7=9A=84=E8=87=AA=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 上一轮的遗漏 上次只补了"缺状态行"，但**32 篇正文里的状态声明基本没动**。而那些声明 大多是 1~2 周前写的，代码早已推进。本轮逐篇对代码核实。 ## 逐篇核实结果（方法：读当前代码，不看文档的历史描述） ### 1. memory-usability-plan：待执行 → 已实施 文档写「状态：**待执行**（2026-10-22）」。三条根因实测**全部已修**： | 根因 | 实测 | |---|---| | R1 向量化输入是 jieba 词袋 | ✅ `coldcontext.go` 的 `denseFor` 明写「用事件正文（原文），不用 Summary（jieba 词袋）」 | | R2 媒体块无语义 | ✅ 块 union 化，媒体即块自带描述 | | R3 提示词无引导 | ✅ `tooldefs.go` 明写 `coldcontext_query` 把历史**插回时序**，并下沉到 kernel-memory skill | ### 2. entities-retirement-plan：执行中 → 方案已定、执行未完成 写「三表全退，执行中」，容易被读成"快完成了"。实测生产库： `entities 1292 / relations 978 / sentences 66` 行**仍在用**。 迁移工具就绪，但生产未切换 —— 这个区别对判断风险很关键。 ### 3. scene-memory-fix-plan：部分落地 → 7 步里 5 步完成 逐条核实：步骤 1/2/3/5/6 已完成（含 SDK 的 `ScenePolicy`、 `scene_emerge.go` 已区分 `peer:group_*` 与 `peer:user_*`）； 步骤 4（清现网垃圾场景）与 7（收口验证）属现场操作，未复核。 ### 4. prod-migration-checklist：⚠️ 最危险的一处 写「**状态**：HologramAgent 已停机（inactive + disabled）」—— 那是一次性迁移（2026-10-04）当场的真实状态，**不是现在的**。 照着它读会以为服务停着。改为明确归档说明 + 指向现行 runbook。 ### 5. abstention-criterion：「拒答尚未接入生产路径」已不成立 实测拒答已下沉到图库层（`RecallBlocksGuarded`），生产路径 `toolcall.go:1312` 与端到端探针**走同一条路**。保留了下沉的理由 （第一版放上层，探针绕过它 ⇒ 判据测不到被测路径）。 剩余两项（泛指词检测、n=10 样本偏小）仍开放。 ### 6. toolcall-parallel-execution-plan：阶段 0.5 起为待办 → 全部已完成 实测阶段 0/0.2/0.5/1/2/2.5 与 3/4 全部完成，遗留项也已解决。 ## 顺带修正两处写法 - `memory-restructure-plan.md`：顶部有「执行结果摘要」但正文各步骤仍写 `✗ 未开始`（原始计划快照，有意保留）。加一句读法说明， 避免读者拿正文的快照当现状。 - `future-plan.md` §六：新增 5 条实测确认的待办并去掉 2 条重复项 （遗留表退役、中断子系统原先各出现两次）。 ## 核对 - docs/zh 32 篇全部有状态行，且与代码实测一致 - 代码块全部配平；文档间相对链接全部有效 - go build 通过（纯文档改动） --- docs/zh/abstention-criterion.md | 14 +++++++++++--- docs/zh/entities-retirement-plan.md | 16 +++++++++++++++- docs/zh/future-plan.md | 7 +++++-- docs/zh/memory-restructure-plan.md | 4 ++++ docs/zh/memory-usability-plan.md | 14 +++++++++++++- docs/zh/prod-migration-checklist.md | 8 +++++++- docs/zh/scene-memory-fix-plan.md | 14 +++++++++++++- docs/zh/toolcall-parallel-execution-plan.md | 6 +++++- 8 files changed, 73 insertions(+), 10 deletions(-) diff --git a/docs/zh/abstention-criterion.md b/docs/zh/abstention-criterion.md index d1003578..0bfb1633 100644 --- a/docs/zh/abstention-criterion.md +++ b/docs/zh/abstention-criterion.md @@ -88,11 +88,19 @@ ## 未完成 -- 拒答逻辑尚未接入生产路径（`recallByBlocks` 仍无条件返回内容） -- 泛指词检测未实现 -- n=10 的判据仍偏小，但方向与上一轮 n=4 时的判断相反： +> **2026-10-31 复核**：第一条已不成立，其余仍开放。 + +- ~~拒答逻辑尚未接入生产路径~~ ✅ **已接入**： + `GraphDB.RecallBlocksGuarded` 把拒答下沉到**图库层**， + 生产路径 `toolcall.go:1312` 与端到端探针**走同一条路**。 + （下沉的理由值得记住：第一版把拒答放在 `core/toolcall.go` 里， + 探针绕过它 ⇒「判据测不到被测路径，判据就等于不存在」。） +- ❌ 泛指词检测仍未实现 +- ⚠️ n=10 的判据仍偏小，但方向与上一轮 n=4 时相反： 这次是**确定性事实 + 完全分离 + 新增样本不破**，而不是「差 0.047 的运气」 +两者已登记到 [`future-plan.md`](./future-plan.md) §六。 + ## 迁移前后对照（2026-10-04，生产快照实测） 用同一份生产库快照，迁移前后各跑一次 `TestProbe_生产规模召回`： diff --git a/docs/zh/entities-retirement-plan.md b/docs/zh/entities-retirement-plan.md index 4e9a4dfb..3fd66fe4 100644 --- a/docs/zh/entities-retirement-plan.md +++ b/docs/zh/entities-retirement-plan.md @@ -6,7 +6,21 @@ > 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准；本文保留作为决策记录。 -> 状态：已确认（方案 A：三表全退），执行中 +> 状态：**方案已定，执行未完成**（2026-10-31 复核）。 +> +> 方案是「三表全退」（`entities` / `relations` / `sentences` 并入 +> `memory_blocks`）。迁移代码在（`internal/memory/migrate_entities.go`）， +> 但**生产库仍在用旧表**： +> +> ``` +> entities 1292 行 +> relations 978 行 +> sentences 66 行 +> ``` +> +> ⇒ 本计划的「执行中」不能读成"快完成了"，而是**迁移工具就绪、 +> 生产尚未切换**。切换前的剩余读方清单见 +> [`legacy-table-retirement.md`](./legacy-table-retirement.md) §八 / §十二。 > 范围：含生产实例 ${HA_DATA}（用户 2026-10-02 确认迁移） > 前置：docs/zh/memory-restructure-plan.md（重构计划） > 原则：一次迁移，删除所有 entities 遗留，避免后续误导。 diff --git a/docs/zh/future-plan.md b/docs/zh/future-plan.md index 4ae3d30d..cdd9383d 100644 --- a/docs/zh/future-plan.md +++ b/docs/zh/future-plan.md @@ -370,12 +370,15 @@ retention 修好之后这些会被逐步清掉，但不会立刻（要等跨月 | 待办 | 在原文档 | 性质 | |---|---|---| +| **弃答：泛指词检测未实现** | `abstention-criterion.md` §未完成 | 🟡 拒答主路径已接（`RecallBlocksGuarded`），泛指词这一支没做 | +| **弃答：n=10 判据样本偏小** | 同上 | ⚪ 方向确定（确定性事实+完全分离），样本可扩 | +| **遗留表退役：生产仍在用旧三表** | `entities-retirement-plan.md`、`legacy-table-retirement.md` | 🔴 迁移工具已就绪，生产未切换（entities 1292 / relations 978 / sentences 66 行仍在） | +| **场景：现网垃圾场景清理 + 收口验证** | `scene-memory-fix-plan.md` 步骤 4 / 7 | ⚪ 属现场操作，代码侧 5/7 步已完成 | +| **中断子系统独立化** | `interrupt-subsystem-split-plan.md` | ⚪ 计划未实施；当前中断实现仍在 `agent/core`（`interrupt.go` + `scheduler.go`） | | 测试模板库（压力/接口/编译预置模板） | `commondev-design.md` §4「尚未做」 | ⚪ 机制已落地，模板按需补 | | 记忆召回「形态 3 / 形态 4」两个缺口 | `recall-capability-tiers.md` §「待补的能力」 | 🟡 需新实验，方向已列 | | 判据口径与契约对齐 | `abstention-criterion.md` §「待办」 | 🟡 | -| 中断子系统 `maxQueue` 对中断队列的约束 | `interrupt-subsystem-split-plan.md` §「阶段 1.5 遗留」 | ⚪ | | 工具并行化的遗留项 | `toolcall-parallel-execution-plan.md` §「遗留项状态」 | ⚪ | -| 遗留表退役的剩余读方 | `legacy-table-retirement.md` §八 / §十二 | ⚪ 迁移收尾 | | 生产召回验证的 3 条遗留 sentence→块 边 | `production-recall-validation.md` | ⚪ 非迁移产生 | | 遗留问题清单 | `legacy-issues.md` §二「真正待办」 | ⚪ 长期清单 | diff --git a/docs/zh/memory-restructure-plan.md b/docs/zh/memory-restructure-plan.md index 8d6337f4..ed4113f4 100644 --- a/docs/zh/memory-restructure-plan.md +++ b/docs/zh/memory-restructure-plan.md @@ -11,6 +11,10 @@ > > ## 执行结果摘要（2026-10-04 回填） > +> ★ **读法**：下面「三、分步执行」里各步骤仍写着 `✗ 未开始` —— 那是 +> **计划当时的原始快照**，有意不改（改了就看不出计划与实际的差距）。 +> **以本摘要为准。** +> > | 步骤 | 状态 | 关键提交 | > |---|---|---| > | ① 重写设计文档 | ✅ | `6a0d6b7` `971cd72` `7248558` | diff --git a/docs/zh/memory-usability-plan.md b/docs/zh/memory-usability-plan.md index f1742c3f..226e9006 100644 --- a/docs/zh/memory-usability-plan.md +++ b/docs/zh/memory-usability-plan.md @@ -6,7 +6,19 @@ > 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准；本文保留作为决策记录。 -> 状态：**待执行**（2026-10-22） +> 状态：**已实施**（2026-10-22 计划，2026-10-31 逐条复核确认）。 +> +> 三条根因的实测结论（复核方法：读当前代码，不看本文的历史描述）： +> +> | 根因 | 本文当时的判断 | 2026-10-31 实测 | +> |---|---|---| +> | R1 向量化输入是 jieba 词袋 | 需改为正文 | ✅ 已修 —— `coldcontext.go` 的 `denseFor` 明写「用事件正文（原文），不用 Summary（jieba 词袋）」 | +> | R2 媒体块无语义 | 需补 | ✅ 已修（块 union 化，媒体即块，自带描述） | +> | R3 提示词无引导 | 需补 L1/L2/L3 与回填语义 | ✅ 已修 —— `tooldefs.go` 明写 `coldcontext_query` **把历史事件插回时序**，并下沉到 kernel-memory skill | +> +> 本文保留作为**「结构判据不能替代质量判据」**的决策记录 —— +> 那条教训（16 条判据 6 个变异全绿，而没有一条验证"检索结果与查询相关"） +> 比计划本身更值得留。 > 前置：`docs/zh/memory-blockflow-repair-plan.md`（L1↔L2 结构同构，已实施） > 本文修的是**上一轮没修的那一层**：结构对了，但检索质量与提示词仍然不可用。 diff --git a/docs/zh/prod-migration-checklist.md b/docs/zh/prod-migration-checklist.md index e0b1d010..8d88385a 100644 --- a/docs/zh/prod-migration-checklist.md +++ b/docs/zh/prod-migration-checklist.md @@ -2,7 +2,13 @@ **日期**：2026-10-04 **分支**：`feat/context-overflow-l4`（未 push） -**状态**：HologramAgent 已停机（inactive + disabled） +**状态**：⚠️ **归档（2026-10-04 的一次性操作清单）** + +> 本文记录的是那次停机迁移的**执行现场**。其中「已停机」是当时的真实状态， +> **不是现在的状态** —— 现在就别照着这份清单判断服务是否在跑。 +> +> 现行部署操作见 [`deploy-runbook.md`](./deploy-runbook.md)； +> 服务当前状态用 `systemctl status hologramagent` 查。 --- diff --git a/docs/zh/scene-memory-fix-plan.md b/docs/zh/scene-memory-fix-plan.md index da632d33..4af9b3c5 100644 --- a/docs/zh/scene-memory-fix-plan.md +++ b/docs/zh/scene-memory-fix-plan.md @@ -1,6 +1,18 @@ # 场景式记忆修复 plan -> **状态：计划（部分落地）。** 是修复计划，不是现状描述。 +> **状态：大部分落地（2026-10-31 复核）。** 7 个步骤里 5 步已完成。 +> +> | 步骤 | 状态 | +> |---|---| +> | 1 修 R1+R2（归一化、时段污染主键） | ✅ 已完成 | +> | 2 SDK 补 `ScenePolicy` 声明项 | ✅ 已完成（`sdk/plugin.go` 有 `ScenePolicyAuto` / `ScenePolicyNone`） | +> | 3 修 R3（图整理覆盖全库） | ✅ 已完成 | +> | 4 清理现网垃圾场景 | ❓ 未复核（属现场操作，不在代码里） | +> | 5 修 R5（证据桶别全表清） | ✅ 已完成 | +> | 6 修 R4 覆盖面（peer / 语义场景） | ✅ 已完成（`scene_emerge.go` 已区分 `peer:group_*` 与 `peer:user_*`） | +> | 7 验证与收口 | ❓ 未复核 | +> +> 剩余不确定项已索引到 [`future-plan.md`](./future-plan.md) §六。 > 未完成项已索引到 [`future-plan.md`](./future-plan.md) §六。 > 起点：2026-09-26 生产库实测（`${HA_DATA}/memory/graph.db`）。 diff --git a/docs/zh/toolcall-parallel-execution-plan.md b/docs/zh/toolcall-parallel-execution-plan.md index 98e5e95a..002d334f 100644 --- a/docs/zh/toolcall-parallel-execution-plan.md +++ b/docs/zh/toolcall-parallel-execution-plan.md @@ -3,7 +3,11 @@ > **设计依据**：`docs/zh/toolcall-contract-and-sequence-design.md`（本文只讲**怎么一步步做**， > 设计取舍与实证依据在那份文档里，不重复）。 > -> **状态**：阶段 0 已完成。阶段 0.5 起为待办。 +> **状态：全部阶段已完成**（2026-10-31 复核）。 +> +> 阶段 0 → 0.2 → 0.5 → 1 → 2 → 2.5（内核主线）与 3/4（序列插件） +> 均已完成。原先这里写着「阶段 0.5 起为待办」，是计划初期的状态，已过时。 +> 遗留项状态见文末「遗留项状态」小节（全部已解决）。 > **纪律**：每个阶段的「判据」必须**先写且必须能失败**，再改实现； > 判据通过前不进入下一阶段（见文末「阶段纪律」）。