docs: 全量校订文档到当前代码状态 + 建立 future-plan 作为唯一未做登记处

## 为什么

文档里混着三种时态:当时实测、历史推演、描述现状但已失真。三者外观相同,
读者无从分辨。本次逐条用实测核对,把失真的改成事实,把「已做」从「未做」
里摘出来,把「真没做」集中登记到一处。

## 新文件:docs/zh/future-plan.md

此前「未做」散落在各设计文档的「待办/剩余/遗留」小节,时间一长就与代码
脱节(已完成却仍写未做,未做却被当成已完成)。新建本文作为**唯一登记处**,
收录规则明确:只收「代码里确实没有」与「有机制但零生产调用方」两类。

它同时把本仓一个反复出现的缺陷形态显式化 —— **机制 ≠ 接线**。已攒够 5 例:

| 能力 | 曾经/现在的状态 |
|---|---|
| `Policy.CheckTool` | 曾 `Agent.security` 恒 nil → 2026-10-30 修 |
| `CheckToolFor` | 曾 0 生产调用方 → 2026-10-30 修 |
| `ActivateProfile` | **现在仍 0 调用方** |
| `ScanContent` | **现在仍 0 调用方** |
| `CheckPath` / `CheckNetwork` | **现在仍 0 调用方** |

## 已失真的表述(逐条实测后更正)

**kernel-modularization-design.md**

- §2.7.4 原标题是「未做(Step 4b 的剩余)」,写着「main.go 仍走原来的串行代码,
  下一步是把 Run(plan) 真接进 main」。**实际 `main.go:229` 早已调用
  `RunKernelModules` → `kernelboot.Run`**,插件调度也已归位 plugin-host。
  改为「已完成」并给出两处代码位置 + 生产日志证据。
- §2.7 分层数字「6 层 / 17 模块,最宽层 9」→ 实测 **20 模块 / 6 层 / 最宽 10**。
  同时给出取数命令,并要求「数字一律现场取,不凭文档记忆」。
- §2.3.5 那段标着「当前已产出的分层结果(实测)」的 4 层 14 模块表,是
  2026-10-16 的推演。改为明确标注「已过时,仅作设计推演保留」。
- §2.7.3 判据表 7 条**全部不存在**(随 3864f36 删死包迁包时丢失)。改为
  左右栏对照:左边当时名字、右边现仓库真实判据,找不到对应物的 4 条明确标 ❌。
- 文件头补状态声明、与 future-plan 的分工、数字取数方式。

**kernel-secret-firewall-design.md**

- 状态从「已实现」改为「部分实现」。原来那句会让读者以为整套安全能力都在跑。
- 新增接线状态表:逐个写**实测的生产调用点**(不写 ✅/❌ 定性)。
  事实是:凭据三件套与工具闸生效;**敏感词/注入、路径沙箱、网络闸三条
  机制完整但零生产调用方**;档位声明侧通、激活侧零调用方。
- §5 T1–T10:T2/T3/T4 早已落地却仍挂在「待办」表里。改为现状列,
  并把真未做的 T5–T10 迁入 future-plan §1.5。

**对外文档的工具名**(外部读者正在看错的名字)

- `ARCHITECTURE.md` 6 处、`OVERVIEW.md` 1 处、`README.md` / `README_EN.md` 各 3 处、
  `resident-subagent-design.md` 2 处:`memory_*` / `doc_query` → `stablemem_*` / `coldcontext_*`
- README 的 v1.1.1 发布说明保留原名(那是历史事实),加一句现名注记

**input-scheduler-design.md / resident-subagent-design.md**

- 补状态头。input-scheduler 记入 rtchild 不走四级阶梯(单槽覆盖)这一下游差异;
  resident-subagent 记入「继承安全运行时实例但**不继承权限**」这一下沉事实。

## 未动的(有意为之)

历史归档文档(`legacy-*`、`*-plan.md`、`live-run-evidence-*`、
`production-recall-validation.md`、`context-overflow-l4-design.md`、
`entities-retirement-plan.md`、`memory-*-plan.md`)**一律不改** ——
它们是历史记录,改了就篡改证据。其中的待办以索引形式登记在
future-plan §六,原文档保留。

## 核对结论

- 文档现在只描述两种内容:**已落地的实现**(附实测证据/取数命令)与
  **尚未实现的事项**(统一在 future-plan)
- 数字类断言全部给出取数命令
- 跨文档的「未做」引用统一指向 future-plan,避免再次分叉
This commit is contained in:
JianFeeeee
2026-10-31 06:58:17 +08:00
parent e78a38b3d8
commit b9b5ac0282
9 changed files with 549 additions and 55 deletions

View File

@ -228,12 +228,13 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样
③ Graph (图数据库 — 顶层仍是三元组,节点即记忆块)
SQLite — memory_blocks(节点) + memory_block_edges(边)
三元组 = 【节点】【关系边】【节点】;putTripleBlocksTx 落为 src --edge_type--> dst
写入: memory_commit / 冷文档蒸馏 / Pipeline 规则蒸馏 / memory_merge
写入: stablemem_commit / 冷文档蒸馏 / Pipeline 规则蒸馏 / stablemem_merge
读取:
├── 自动召回: Indexer.BuildContext(input)
│ → CleanText → 向量实体搜索 + jieba关键词 → SQLite LIKE + BFS depth=2
│ → 【记忆索引】→ system prompt
└── LLM主动: memory_recall / memory_merge / memory_purge / memory_edit / memory_delete_entity
└── LLM主动: stablemem_recall / stablemem_merge / stablemem_purge /
stablemem_edit / stablemem_delete_entity
Social: person_query / set_trait / relate (包装 GraphDB)
④ 四个独立心跳循环(各自独立的 ticker 和配置间隔)
@ -356,20 +357,26 @@ Core ◀─入向审查── 外部
| 工具 | 作用 |
| ------ | ------ |
| `memory_recall` | 从 Graph 召回 |
| `memory_commit` | 写入 Graph 三元组 |
| `memory_merge` | 合并两个实体节点 |
| `memory_purge` | 删除指定实体 |
| `memory_edit` | 编辑已有实体/关系 |
| `memory_delete_entity` | 删除实体及其所有关系 |
| `memory_introspect` | 查看记忆统计 |
| `stablemem_recall` | 从 Graph 召回 |
| `stablemem_commit` | 写入 Graph 三元组 |
| `stablemem_merge` | 合并两个实体节点 |
| `stablemem_block_merge` | 合并两个记忆块 |
| `stablemem_purge` | 删除指定实体 |
| `stablemem_edit` | 编辑已有实体/关系 |
| `stablemem_delete_entity` | 删除实体及其所有关系 |
| `stablemem_introspect` | 查看记忆统计 |
| `coldcontext_query` | 从冷上下文(cold context)召回 |
| `coldcontext_commit` | 写入冷上下文 |
`memory_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
> ★ 工具名以 `stablemem_` / `coldcontext_` 为前缀(v1.2 起,旧的
> `memory_*` / `doc_*` 已废弃)。权威定义在
> `internal/agent/core/tooldefs.go`;核对命令:
> `grep -rhoE '"(stablemem|coldcontext)_[a-z_]+"' --include=*.go internal | sort -u`
`stablemem_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
`[<mime> <短digest>] <描述>` 标记补进句子/正文——**标记由内核拼,模型只给 digest**。
要求调用方知道格式,等于让一个拼写错误静默切断引用绑定而全链路无人报错。
`memory_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。
`stablemem_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。
### 媒体记忆(块 union:媒体即块)

View File

@ -46,7 +46,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev
- **无独立 GC、无引用计数、无 keep-set**:记忆块遵循单层不变量——Context → Document → Graph
是块的**迁移**,不是复制、也不靠引用保活;**删除块即删内容**
- **v1.1.1 起贯通插件边界**:插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体,
模型可用 `memory_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体
模型可用 `stablemem_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体
- **旧机制已整体拆除**:此前把视觉模型生成的描述写进正文、以 `[<mime> <短digest>] <描述>` 标记
参与检索的**描述式索引**,以及 `media_refs` 引用计数,均已在 v1.2.0 删除——描述是模型生成的
二手信息,检索「别人转述的图片」不如检索图片自己的向量