|
|
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 |
|
