mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-03 07:47:45 +00:00
4963d70215
## 上一轮的遗漏 上次只补了"缺状态行"，但**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 文档索引
建立于 2026-10-31。目的：让读者知道该信哪一篇、哪些是历史记录。
此前本目录 32 篇文档混着三种时态 —— 当时实测、历史推演、设计规划 —— 外观完全相同，读者无从分辨。曾有文档写着「
main.go仍走串行代码」 而实际早已接完（滞后一整轮发布）。所以先分类，再读内容。
一、怎么判断一篇文档的可信度
每篇文档首部应有状态行，取值只允许这四种：
| 状态 | 含义 | 能不能当事实用 |
|---|---|---|
| 已实现并部署 | 文中描述与代码一致，关键处给了取数命令 | ✅ 可以直接信 |
| 部分实现 | 先说清哪部分生效、哪部分没有（附实测调用点） | ⚠️ 只信标了"生效"的部分 |
| 设计 / 未实现 | 是方案，不是现状。代码里可能没有 | ❌ 只能当设计意图 |
| 归档说明 | 历史记录，故意保留当时的写法 | ❌ 不要改它，也不要信它 |
判据名的可信度规则（重要）
文档里出现的 TestXxx 名字，不保证现在还存在：
- 已实现并部署类文档里的判据名 → 应当存在。找不到就是缺陷（报告它）
- 设计 / 未实现类文档里的判据名 → 是规划的名字，可能从未实现
- 归档说明类文档里的判据名 → 记录的是当时的事实，可能已改名或删除
历史上有过一次真实漂移：BootCtx 改名为 KernelState 后，
TestBootCtxCloseAllIsReverseOrder 随之变成
TestKernelStateCloseAllIsReverseOrder，而文档没跟上。
核对命令（任何时候都可以自己跑）：
# 列出本目录引用的全部判据名里，仓库中找不到的那些
for n in $(grep -rhoE '`Test[A-Z][A-Za-z0-9_]+`' docs/zh/*.md | tr -d '`' | sort -u); do
grep -rq "func $n(" --include="*_test.go" internal cmd 2>/dev/null || echo "缺失: $n"
done
跑出来有缺失不一定是缺陷 —— 先看它出在哪类文档里。
当前基线（2026-10-31）：27 条缺失，分布如下，全部已知且已说明：
| 篇数 | 文档 | 性质 |
|---|---|---|
| 18 | commondev-design.md / commondev-agent-runtime-design.md |
「设计 · 未实现」类，判据名是规划名 |
| 7 | kernel-modularization-design.md |
§2.7.3 的对照表左栏（有意的历史记录），其中 4 条已登记 future-plan §2.3 |
| 2 | multimodal-space.md |
视频能力未纳入契约，判据为规划名 |
⇒ 在「已实现并部署」类文档的正文里（非历史对照表）找不到判据名，才是缺陷。
二、文档清单（按状态分类）
2.1 已实现并部署 —— 可以直接当事实
| 文档 | 内容 |
|---|---|
kernel-modularization-design.md |
装配架构权威：依赖声明、BFS 分层、Group 0、实例化粒度 |
kernel-secret-firewall-design.md |
安全防火墙（部分实现，见文首接线状态表） |
input-scheduler-design.md |
两类别输入 + L1–L4 中断 + 可抢占 |
resident-subagent-design.md |
驻留子：轻量内核、两级记忆、父子 L3/L4 |
toolcall-contract-and-sequence-design.md |
工具调用契约与顺序 |
ci-cd-runbook.md |
CI/CD 操作手册 |
deploy-runbook.md |
部署手册 |
site-infra-runbook.md |
站点基础设施 |
2.2 参考 / 实测报告 —— 数据可信，结论看日期
| 文档 | 内容 |
|---|---|
kernel-performance.md |
性能实测数据 |
production-recall-validation.md |
生产召回验证（含未解决的 3 条遗留边） |
recall-as-association.md |
召回作为关联的机制说明 |
recall-capability-tiers.md |
召回能力分层（含 2 个未补的缺口） |
multimodal-space.md |
多模态向量空间 |
vector-provider-decision.md |
向量 provider 选型决策 |
abstention-criterion.md |
弃答判据 |
triple-extract-attention.md |
三元组抽取与注意力 |
2.3 设计 / 未实现 —— 只能当设计意图
| 文档 | 状态 |
|---|---|
commondev-design.md |
标题即写明「设计 · 未实现」；架构已变更，见其 §12 |
commondev-agent-runtime-design.md |
架构已按前篇 §12 调整，部分未落地 |
interrupt-subsystem-split-plan.md |
探测结论 + 实施计划 |
toolcall-parallel-execution-plan.md |
并行化执行计划（含遗留项） |
memory-blockflow-repair-plan.md |
记忆块流修复计划 |
memory-restructure-plan.md |
记忆重构计划 |
memory-usability-plan.md |
记忆可用性计划 |
scene-memory-fix-plan.md |
场景记忆修复计划 |
legacy-table-retirement.md |
遗留表退役（收尾中） |
entities-retirement-plan.md |
实体表退役 |
prod-migration-checklist.md |
生产迁移清单 |
triple-distill-llm-design.md |
已实现并部分否决 |
2.4 归档说明 —— 历史记录，不要改也不要信
| 文档 | 说明 |
|---|---|
context-overflow-l4-design.md |
术语已过时（memory_* 等旧工具名保留原样） |
live-run-evidence-2026-10-04.md |
某次实跑证据快照 |
legacy-issues.md |
遗留问题清单 |
为什么归档文档里有旧工具名却不改：它们是证据快照。 把
memory_recall改成stablemem_recall等于篡改当时的记录， 让后来的人无法判断"这条结论是在哪个版本上得出的"。
2.5 唯一未做登记处
| 文档 | 内容 |
|---|---|
future-plan.md |
全仓唯一的「尚未实现 / 已知缺口」登记处 |
规则：任何设计文档都不再自己维护「未做」小节，一律登记到 future-plan。 历史上各文档各自维护，结果滞后过 —— 已完成仍写未做，未做被当成已完成。
三、写文档的三条纪律
-
数字类断言必须给取数命令（如模块数用
go run ./cmd/homed-depgraph -print），不要凭记忆写数字。 本文档集历史上写错过一次（17 模块 vs 实际 20）。 -
区分「机制存在」与「接线生效」。本项目的头号缺陷形态是 机制写对了、判据全绿、生产里零调用方。描述能力时写实测的生产调用点， 不要只写"已实现"。
-
判据要能红。写判据时先问：把对应实现删掉，这条判据会红吗？ 本仓踩过两次：
security_toolgate_test.go手动调SetSecurity把缺失的接线补上了；retention_test.go手写合规文件名， 从没跑过真实产物。两者都永远绿。