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

@ -1,5 +1,16 @@
# 驻留式子 Agent 设计(轻量内核 · 两级记忆 · 父子中断)
> **状态:已实现并部署。** 驻留子、两级记忆、父子 L3/L4 中断、残余任务四态均已落地。
> 本轮(2026-10-31)校订时补充的下沉事实:
>
> - 安全:驻留子会**继承父的安全运行时实例**,但**权限不继承** —— 父在
> `SpawnResident` 时通过 `ResidentOptions.AllowedTools / DenyTools`
> **为这个子单独声明**主体策略,内核持有并执行;子销毁时撤销。
> 工具面参数名:`allowed_tools` / `deny_tools`。
> - 本文正文里的 `memory_recall` 等旧工具名已统一改为现行的 `stablemem_*`。
>
> **未实现项**不在本文维护,见 [`future-plan.md`](./future-plan.md)。
>
> **前置**:本文建立在《输入调度器设计》(`docs/zh/input-scheduler-design.md`)之上。
> 那里已经落地了:两类别输入(中断 / 排队)、四级中断优先级、可抢占、
> 现场保存/恢复、中断栈(LIFO,结构上界 4 帧)、任务级回执、panic→L4。
@ -502,7 +513,7 @@
| **A 记忆整理流水线** | `distill.go`(10):`archiveLoop` / `reviewLoop` / `mergeLoop` / `detectEntityMerge` / `reviewRelations` / `archiveColdDocs` | `Recall`, `ClearSentenceID`, `CleanupOrphanedSentences` | **root-only**(后台定时器) |
| **B 记忆块 + 媒体桥** | `graphmedia.go`(18)、`medialoop.go`(4) | `PutMemoryBlocks`, `AddMemoryBlockEdge`, `BlocksForNode`, `PutDocumentNode`, `MemoryBlocks`, `MigrateLegacyMediaEntities`, `mediaContextFor*` | **root-only** |
| **C 记忆整理工具** | `toolcall.go::executeMemoryTool`(8) | `Introspect`, `MergeEntities`, `DeleteEntity`, `Purge`, `Commit` | **root-only**(`memory_merge`/`memory_delete_entity`/`memory_block_merge`/`memory_purge`/`memory_edit`/`memory_stats`) |
| **D 共同面** | `graphmedia.go:114`(自动写入)、`toolcall.go:130`(`memory_recall`) | **只有 `Recall` + `Commit`** | 根与子都要 |
| **D 共同面** | `graphmedia.go:114`(自动写入)、`toolcall.go`(`stablemem_recall`) | **只有 `Recall` + `Commit`** | 根与子都要 |
| **E 判空/状态** | 22 处 `if a.memory != nil` + `GetKernelStatus` + `buildToolDefs` | — | 既有关卡 |
⇒ **子 agent 需要的记忆面只有 `Recall` + `Commit`**;其余全是"整理记忆 / 记忆整理流水线"
@ -527,7 +538,7 @@ type GraphMemory interface {
(`executeMemoryTool` 开头已经是 `if a.memory == nil { return "图记忆系统不可用" }`)。
- 唯一要拆的是**自动写入路径** `commitTriplesWithMedia`:
图部分 → `a.graph.Commit`;块/媒体部分 → 由 `a.memory != nil` 守卫。
- 工具表:`memory_recall`(读)对子开放;整理类
- 工具表:`stablemem_recall`(读)对子开放;整理类
(`memory_merge`/`memory_delete_entity`/`memory_block_merge`/`memory_purge`/`memory_edit`/`memory_stats`)
**不进子的工具表**(而不是让它们进去再报"不可用")。
- 轻量 profile 另外不接线的装配:doc 记忆 / context 动态上下文(`pruneOnInput` 等)/