|
|
06f3161e1d
|
docs(en): 建立英文文档目录 —— 索引 + 教训全文 + 设计摘要
## 问题
仓库是公开的，README / README_EN 已经双语，但 `docs/` 只有 `docs/zh/`：
英文读者读完首页就撞墙。
## 做法：摘要而非全译，并写明为什么
`docs/zh/` 有 27 份文档、约 7000 行设计。**全译会烂得比审得还快**，
而一份陈旧的译文比没有更糟 —— 读者不知道它落后于原文多少。
所以按"内容变化速度"分级：
| 类型 | 译法 | 理由 |
| --- | --- | --- |
| 教训 | ✅ 全文 | 复用价值最高，失败形态会反复出现 |
| 索引 | ✅ 全文 | 没有它其余都不可发现 |
| 设计文档 | ⚠️ 一页摘要 + 状态行 | 7000 行全译跟不上演进 |
| 历史快照/证据 | ❌ 不译 | 时点产物，翻译无增益 |
| 未实施计划 | ❌ 不译 | 会变；且按 §4.3 本就不该进仓 |
判据写在 `docs/en/README.md` 里：
> 如果一份文档的内容变化速度快过译文能被审阅的速度，就译它的**摘要**而不是正文。
## 三份文件
**docs/en/README.md** —— 索引。含分类表（哪些已译、哪些只有中文摘要、
哪些不译）、状态行约定、以及"本索引必须在同一提交里更新"这条硬规则
（滞后的索引比没有索引更糟：它教读者信任错的地图）。
**docs/en/engineering-lessons.md** —— §1（判据会骗人）+ §5（判据形态）
全文翻译，§2–§4 摘要。§5 是本轮新增的核心内容：
5.1 判据必须把被测模块当黑箱（含三个正当例外）
5.2 禁止读源码做断言（附"想保证什么 → 错误做法 → 正确做法"表）
5.2.1 判据不得以文档为依据
5.3 测试与业务代码分离
5.3.1 三种测试位置的实测边界
5.3.2 覆盖率必须用 -coverpkg=./...
5.4 CI 必须覆盖每个独立 module
5.5 CI 与本地必须跑同一套门
每个小节都带实测数据与变异验证结果，不是原则罗列。
**docs/en/design-summaries.md** —— 6 份核心设计的一页摘要：
kernel-modularization 6 层 20 模块；依赖图在构建期算好并嵌进二进制；
depgraph.bin 必须与二进制同目录，放数据目录会崩溃循环
secret-firewall security 是外围到核心之间的防火墙，自持数据结构、
只接受事实不接受策略；出入向都要洗
input-scheduler L1–L4 + 现场保存；工具执行是临界区不可抢占
resident-subagent 与 rtchild 语义相反；单数/复数共用 Cleanup
toolcall-contract assistant(tool_calls) 后必须紧跟每个 id 的 tool
消息；批内不得插入任何东西
context-overflow-l4 下沉到冷上下文而非截断；InactivePages 是本次渲染
的临时标记（json:"-"）
另有 13 份（插件相关 / 数据报告型）列为 "Chinese only" 并说明理由。
## 中文索引加了英文入口
`docs/zh/README.md` 顶部增加指向 `../en/README.md` 的一行，并明确：
> 本目录是**中文原文，也是唯一权威**；英文侧只做摘要，与本文冲突时以本文为准。
这一条很重要 —— 否则两份文档会逐渐分叉，而读者不知道该信哪个。
## 验证
go build ./... PASS
go vet ./... PASS
gofmt -l 干净
go test ./... 65 包全过，0 FAIL
|
2026-11-04 20:05:10 +08:00 |
|
|
|
a402bfd777
|
docs: 删除 7 份已完结的执行计划，把教训与数据提出来
## 为什么删
执行计划在实施完结后**会变成误导性读物**：它记录的是"当时打算做什么"，
而读者会读成"现在是什么"。
这在本仓已经造成真实误读 —— `prod-migration-checklist.md` 写着
「状态：HologramAgent 已停机」，那是一次性迁移（2026-10-04）当场的状态，
但照着读会以为服务现在还停着。
## 删了 7 份，删前提取三类内容
| 删掉的文档 | 行数 |
|---|---|
| `memory-restructure-plan.md` | 168 |
| `memory-blockflow-repair-plan.md` | 450 |
| `memory-usability-plan.md` | 309 |
| `scene-memory-fix-plan.md` | 271 |
| `toolcall-parallel-execution-plan.md` | 578 |
| `prod-migration-checklist.md` | 157 |
| `entities-retirement-plan.md` | 118 |
**提取去向**：
1. **教训 → 新建 `engineering-lessons.md`**
这些是它们唯一还有长期价值的部分。汇总成一篇，并按形态归类：
- 判据类（5 条）：结构判据不能替代质量判据 / 测「接线之后」≠测「有没有接线」/
验证通过≠架构正确 / fixture 照臆测字段编 / 先改代码再写测试
- 接线类（3 条）：机制≠接线 / 依赖图是唯一保证顺序的地方 / 单数改了复数漏了
- 权限与生命周期（3 条）：「接上了」有三层 / 以调用方名字为键的表要清理 /
提权口子：让调用方声明自己是谁
- 流程类（3 条）：长任务纪律 / 数字要现场取 / 计划不进仓库
文末点出它们共同的形态：**某种"看起来对了"的信号与"真的对了"之间存在缺口。**
2. **实测数据 → 并入 `toolcall-contract-and-sequence-design.md` 附录 A**
那是新旧内核的对比压测（288 条输入 × 两版），核心结论值得留：
```
场景 旧版中位/工具数 新版中位/工具数
slowbatch8 0.220s / 0 个 0.409s / 8 个
```
★ **旧版"更快"是假的** —— 它的 `openai.lua` 缺 `stream_index` 透传，
多个分片并到槽 0 ⇒ 每个工具报参数错误而一个都没真跑。
这是「只看耗时会被骗」的典型。
另附 stage 锁告警的完整归因（不是内核缺陷，成因在插件进程侧运行时）。
3. **未完成的项 → `future-plan.md` §六**
尤其 `entities-retirement-plan` 那条：方案是"三表全退"，但 2026-10-31
实测生产库 `entities 1292 / relations 978 / sentences 66` 行**仍在用**。
这个事实不能随文档一起消失。
## 保留两份（它们不是计划，是依据）
- `legacy-table-retirement.md` —— 被 **4 处生产代码注释**引用（`graph.go` ×2、
`commit_blocks_test.go`、`probe_prod_test.go`），是退役判断的依据
- `interrupt-subsystem-split-plan.md` —— 探测事实被 `interrupt_invariant_test.go`
引用；拆分本身确实未实施
## 索引重写
`docs/zh/README.md` 现在是「四类文档」的规则说明：
| 类型 | 回答什么 | 命名 |
|---|---|---|
| 设计文档 | 为什么这样设计 | `*-design.md` |
| 操作手册 | 怎么做 | `*-runbook.md` |
| 教训 | 踩过什么坑 | `engineering-lessons.md` |
| 未做登记 | 还剩什么没做 | `future-plan.md` |
并明确写「**不放执行计划**」及例外条件。
## 顺带修掉的引用
删除后 4 处引用指向不存在的文件：
- `deploy-runbook.md` → 改指 `toolcall-contract-and-sequence-design.md`
- SDK 仓 `guide/stream-tool-call-index.md` / `guide/parallel-tool-declaration.md`
→ 同样改指（这两个在 SDK 仓，随后单独提交）
## 验证
- docs/zh 27 篇，索引里列的全部存在、无遗漏
- 全仓无指向已删文档的引用（代码 + 文档）
- 代码块全部配平
- go build 通过
|
2026-10-31 08:50:39 +08:00 |
|
|
|
cf14b840ef
|
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 仍通过（纯文档改动）
|
2026-10-31 07:50:58 +08:00 |
|
