docs: 补齐文档状态分类 + 校正两轮代码改动后的失真

## 背景

上一次文档校订(b9b5ac0)之后又有两次代码提交(5194a96 / 8293282),
把 future-plan §1.1 整节变成了错的 —— 它还写着「档位没有生效点」
和「在 prepareInputTask 里加一次 activateSecurityProfile 调用」,
而后者正是被后来的收敛**否定掉的方案**。

## 新增 docs/zh/README.md(文档索引)

32 篇文档此前混着三种时态(当时实测 / 历史推演 / 设计规划),外观相同。
索引给出**状态分类与可信度规则**:

| 状态 | 能不能当事实用 |
|---|---|
| 已实现并部署 | ✅ 直接信 |
| 部分实现 | ⚠️ 只信标了"生效"的部分 |
| 设计 / 未实现 | ❌ 只能当设计意图 |
| 归档说明 | ❌ 不要改、也不要信 |

并写死**判据名可信度规则**:文档里的 `TestXxx` 不保证还存在。
给了核对命令,以及当前基线(27 条缺失的分布 —— 18 条属"设计未实现"类
文档的规划名、7 条是 §2.7.3 有意保留的历史对照表左栏、2 条属视频能力
未纳入契约)。判定标准:**在"已实现"类文档正文里找不到才是缺陷**。

## 重写 future-plan §1.1(已结案)

原节写的是错的方案。改成记录**真正的缺陷分三层**:

```
第 3 层(表面):activateSecurityProfile 零调用方
第 2 层:agent/core 在替 security 做策略决策
         (自己抠 security_profile / 自己选判定链 /
           自己写 Kind:"resident" 声明主体类别 —— 提权口子)
第 1 层(根因):security 缺少「输入接入点」
```

并补上「每 agent 一个实例」的最终形态(共享注册表 + per-agent 执行视图,
sessionProfile / longtimeProfile 两层,优先级 session > longtime 本身是安全语义)。

§〇「机制 ≠ 接线」表格里档位那一条从 🔴 改为 ✅。

## 各文档状态行

此前 14 篇缺状态行(runbook / 实测报告 / 计划类)。逐篇补上**符合实际内容**
的声明,而不是统一套一句。特别地:

- `commondev-design.md` 标题本就写「设计 · 未实现」→ 归到"设计"类
- `live-run-evidence-2026-10-04.md` → 明确标注"历史证据快照,不要用它的
  结论覆盖现在的实现判断"
- `legacy-issues.md` → 写明它与 future-plan 的分工(前者收已知问题,
  后者收能力缺失与零调用方)

## 正文里两处判据名漂移

- `TestBootCtxCloseAllIsReverseOrder` → 实际是
  `TestKernelStateCloseAllIsReverseOrder`(`BootCtx` 改名时判据跟着改的)
- `TestNilTypedBusSafety` → 标注为"规划名,仓库中不存在"

## 新增 §2.7.5 模块产物的实例化粒度

依赖图保证"设施已就绪",但没说该有几个实例 —— 这是独立决策。
记下 security 的两个答案:全局基线共享(否则插件声明对部分 agent 不生效)、
轮次状态 per-agent。并给出给未来新模块的两条判断标准。

## 安全文档

状态头补「架构形态」段(防火墙定位、per-agent 视图、两层档位);
接线状态表里 `ActivateProfile` 从 🔴 改为 ✅(2026-10-31 接通)。

## README

文档列表加索引与 future-plan 入口 —— 此前从 README 找不到 docs/zh 的任何指引。

## 核对

- docs/zh 32 篇全部有状态行
- 索引里列的文档全部存在,无遗漏
- 分类与各文档自述一致(逐篇抽查)
- go build 仍通过(纯文档改动)
This commit is contained in:
JianFeeeee
2026-10-31 07:50:58 +08:00
parent 82932821c0
commit cf14b840ef
20 changed files with 280 additions and 39 deletions

View File

@ -864,6 +864,34 @@ platform-check → heartbeat-early → logging → data-dirs
- `internal/kernelmod/all/bootgraph_test.go` 的 5 条整机判据 —— 真实登记表装配、
层间有序、逆序关闭、无残留、模块不漏挂
#### 2.7.5 模块产物的**实例化粒度**(2026-10-31 补充)
依赖图保证的是"设施**已就绪**",但没说设施该有几个实例。这在本模块化设计里
是个独立决策,已有两个不同的答案:
| 设施 | 粒度 | 理由 |
|---|---|---|
| `memory` / `knowledge` / `llm` | **进程级 1 个** | 共享同一份数据源,复制没有意义 |
| `security` | **1 个 Runtime + 每 agent 1 个执行视图** | 全局基线共享(否则插件声明对部分 agent 不生效),但**轮次状态**必须 per-agent |
security 的切分值得记下来,因为**整份复制是错的**:
```
共享(进程级 1 份) per-agent(N 份)
───────────────────── ─────────────────────
gate / policy / content sessionProfile ← 轮次级,End 即清
profiles / principals longtimeProfile ← agent 生命期,跨轮保留
scopes / eventPolicy
```
若把整个 Runtime 复制给每个 agent:插件往 A `DeclareProfile("qq.guest")`,
B 就看不到这个档位 ⇒ B 上注入 `qq.guest` 报"未声明"。那是最难查的一类缺陷
(表现为"时灵时不灵")。所以切分原则是**共享注册表 + per-agent 执行视图**。
**给未来新模块的判据**:决定实例化粒度时先问两件事 ——
1. 这份状态是**共享的事实**(配置/注册表)还是**某个执行体的私有状态**(轮次/会话)?
2. 复制它会不会让"某个模块声明的东西"对另一个实例不可见?
### 2.8 完整启动流程与真实依赖(逐行核对,2026-10-16)
@ -960,7 +988,9 @@ func (d *Distiller) distillLoop() {
原 main 用 `defer closeMem()` 等 5 处,释放顺序 = **注册顺序的逆序**(LIFO)。
模块化后改为 `Put("<facility>.close", fn)` + `CloseAll()` 按**发布顺序逆序**执行
⇒ 语义**逐字等价**(判据 `TestBootCtxCloseAllIsReverseOrder` 守)。
⇒ 语义**逐字等价**(判据 `TestKernelStateCloseAllIsReverseOrder` 守 ——
原名 `TestBootCtxCloseAllIsReverseOrder`,`BootCtx` 改名为 `KernelState` 时判据跟着改名,
本文此前未同步,2026-10-31 更正)。
**(D) 包级 `init()` 注册(BuiltinFactory)**
@ -1353,7 +1383,8 @@ var i SyncState = nb // ★ i != nil!经典的 typed-nil 陷阱
接口值**非 nil**(它带类型信息),于是 `bus.IsReady(...)` 解引用空指针 ⇒ **panic**。
**实测复现**:`TestNilTypedBusSafety` 确认 panic 真实发生
**实测复现**:`TestNilTypedBusSafety`(**规划中的判据名,仓库中不存在**;
该 panic 形态由 §2.6 的 `SyncBus` 现行为规避)确认 panic 真实发生
(`invalid memory address or nil pointer dereference`)。
而 panic 在**插件拉起路径**上 ⇒ 整个内核启动失败。