mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-05 16:57:32 +00:00
06f3161e1d
## 问题 仓库是公开的，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
docs/zh 文档索引
English:
../en/README.md—— 英文索引 + 教训与设计摘要。 本目录是中文原文，也是唯一权威；英文侧只做摘要，与本文冲突时以本文为准。
建立于 2026-10-31。目的：让读者知道该信哪一篇。
此前本目录混着三种时态 —— 当时实测、历史推演、执行计划 —— 外观完全相同。 曾有文档写着「
main.go仍走串行代码」而实际早已接完（滞后一整轮发布）。
一、本目录只放四类文档
| 类型 | 回答什么问题 | 有长期价值 | 命名 |
|---|---|---|---|
| 设计文档 | 为什么这样设计 | ✅ | *-design.md |
| 操作手册 | 怎么做 | ✅ | *-runbook.md |
| 教训 | 踩过什么坑 | ✅ | engineering-lessons.md |
| 未做登记 | 还剩什么没做 | ✅ | future-plan.md |
❌ 不放：执行计划
执行计划（*-plan.md / *-checklist.md）会随实施完结变成误导性读物 ——
它记录"当时打算做什么"，而读者会读成"现在是什么"。
2026-10-31 删除了 9 份已完结的计划，删前把两类内容提出来：
| 内容 | 去向 |
|---|---|
| 决策与教训 | engineering-lessons.md |
| 未完成的项 | future-plan.md |
| 实测数据 | 并入对应设计文档（如压测数据进 toolcall-contract-and-sequence-design.md 附录 A） |
唯一例外：legacy-table-retirement.md 与 interrupt-subsystem-split-plan.md 保留 ——
前者被 4 处生产代码注释当作退役依据引用，后者记录的探测事实仍被判据引用。
它们不是"执行计划"，是依据。
二、怎么判断一篇文档的可信度
每篇首部都有状态行，取值只允许这四种：
| 状态 | 含义 | 能当事实用吗 |
|---|---|---|
| 已实现并部署 | 描述与代码一致，关键处给了取数命令 | ✅ 直接信 |
| 部分实现 | 先说清哪部分生效（附实测调用点） | ⚠️ 只信标了"生效"的 |
| 设计 / 未实现 | 是方案，代码里可能没有 | ❌ 只能当设计意图 |
| 归档说明 | 历史记录，故意保留当时写法 | ❌ 不要改、也不要信 |
判据名的可信度规则
文档里的 TestXxx 不保证现在还存在：
- 已实现并部署类文档里的 → 应当存在。找不到就是缺陷
- 设计 / 未实现类文档里的 → 是规划名，可能从未实现
- 归档说明类文档里的 → 记录当时事实，可能已改名或删除
真实案例：BootCtx 改名 KernelState 后，
TestBootCtxCloseAllIsReverseOrder → TestKernelStateCloseAllIsReverseOrder，
文档没跟上。
核对命令：
for n in $(grep -rhoE '`Test[A-Z][A-Za-z0-9_]+`' docs/zh/*.md | tr -d '`' | sort -u); do
grep -rq "func $n(" --include="*_test.go" internal cmd 2>/dev/null || echo "缺失: $n"
done
有缺失不一定是缺陷，先看它出在哪类文档里。
当前基线（2026-10-31）：27 条缺失，全部已知：
| 篇数 | 文档 | 性质 |
|---|---|---|
| 18 | commondev-*.md |
「设计 · 未实现」类，判据名是规划名 |
| 7 | kernel-modularization-design.md |
§2.7.3 的对照表左栏（有意的历史记录） |
| 2 | multimodal-space.md |
视频能力未纳入契约，判据为规划名 |
⇒ 在「已实现」类文档正文里找不到，才是缺陷。
三、文档清单
3.1 设计文档 —— 可以直接当事实
| 文档 | 内容 |
|---|---|
kernel-modularization-design.md |
装配架构权威：依赖声明、BFS 分层、Group 0、实例化粒度 |
kernel-secret-firewall-design.md |
安全防火墙（部分实现，见文首接线状态表） |
input-scheduler-design.md |
两类别输入 + L1–L4 中断 + 可抢占 |
resident-subagent-design.md |
驻留子：轻量内核、两级记忆、父子 L3/L4 |
toolcall-contract-and-sequence-design.md |
工具调用契约（附录 A 是压测数据） |
commondev-design.md |
主管式多仓库开发流水线（设计 · 未实现） |
commondev-agent-runtime-design.md |
commondev 运行时与内核接入 |
context-overflow-l4-design.md |
上下文超页 L4（归档，术语过时） |
triple-distill-llm-design.md |
三元组蒸馏（已实现并部分否决） |
3.2 操作手册
ci-cd-runbook.md— CI/CDdeploy-runbook.md— 部署site-infra-runbook.md— 站点基础设施
3.3 参考 / 实测报告
| 文档 | 内容 |
|---|---|
engineering-lessons.md |
踩过的坑与共同形态（推荐先读） |
kernel-performance.md |
性能实测基线 |
production-recall-validation.md |
生产召回验证（「探针 PASS 但结论是假的」） |
recall-as-association.md |
召回作为关联 |
recall-capability-tiers.md |
召回能力分层（含 2 个未补缺口） |
multimodal-space.md |
多模态向量空间 |
vector-provider-decision.md |
向量 provider 选型（已定） |
abstention-criterion.md |
弃答判据 |
triple-extract-attention.md |
三元组抽取与注意力 |
3.4 依据类（不是计划，是退役/拆分的判断依据）
| 文档 | 为什么保留 |
|---|---|
legacy-table-retirement.md |
被 4 处生产代码注释引用；剩余读方清单在 §八/§十二 |
interrupt-subsystem-split-plan.md |
探测事实被判据引用；拆分本身未实施 |
3.5 归档说明 —— 历史记录，不要改也不要信
live-run-evidence-2026-10-04.md— 某次实跑证据快照legacy-issues.md— 遗留问题清单（部分条目已过时）
归档文档里的旧工具名（
memory_recall等）故意不改 —— 它们是证据快照， 改了就无法判断"这条结论是在哪个版本上得出的"。
3.6 单一登记处
| 文档 | 内容 |
|---|---|
future-plan.md |
全仓唯一的「尚未实现 / 已知缺口」登记处 |
四、写文档的三条纪律
-
数字类断言必须给取数命令（如模块数用
go run ./cmd/homed-depgraph -print），不要凭记忆。 本文档集写错过一次（17 模块 vs 实际 20）。 -
区分「机制存在」与「接线生效」。本项目头号缺陷形态是 机制写对了、判据全绿、生产里零调用方。描述能力时写实测的生产调用点。
-
判据要能红。写判据时先问：把对应实现删掉，这条判据会红吗？ 本仓踩过两次：
security_toolgate_test.go手动调SetSecurity把缺失的接线补上了；retention_test.go手写合规文件名， 从没跑过真实产物。两者都永远绿。