JianFeeeee 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

..

en

docs(en): 建立英文文档目录 —— 索引 + 教训全文 + 设计摘要

2026-11-04 20:05:10 +08:00

zh

docs(en): 建立英文文档目录 —— 索引 + 教训全文 + 设计摘要

2026-11-04 20:05:10 +08:00

git-branching.md

feat(security): 插件按工具声明内容策略 + 目录名统一

2026-11-03 09:51:11 +08:00