mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00

Files

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

4.1 KiB

Raw Blame History

docs/en — English documentation index

Status: index (current). Established 2026-11-04.

中文索引: ../zh/README.md

Why this directory exists

The repository's documentation grew Chinese-first, but this is a public repository and README.md / README_EN.md are already bilingual. That asymmetry meant an English-speaking reader could read the front page and then hit a wall at docs/.

This directory is the English side. It does not mirror docs/zh/ file-for-file — see "Translation policy" below.

Translation policy

Not everything is worth translating, and pretending otherwise produces stale translations that are worse than none.

Document class	Translated?	Why
Lessons (`engineering-lessons`)	✅ Full	Highest reuse value; the failure shapes recur across the codebase
Runbooks (`deploy-`, `ci-cd-`, `site-infra-`)	✅ Full	Operators who cannot read Chinese cannot deploy
Index (this file, `../zh/README.md`)	✅ Full	Entry point; without it nothing else is discoverable
Design docs (`*-design.md`)	⚠️ Summary only	Full translation of ~7000 lines would rot faster than it could be maintained. Each gets an English summary + status line, with a pointer to the Chinese original as the authority
Historical snapshots / evidence	❌ No	Time-stamped by nature; translation adds no value
Unimplemented plans	❌ No	Will change; see `docs/zh/README.md` §一 for why plans are not kept anyway

Rule of thumb: if a document's content changes faster than a translation can be reviewed, translate its summary instead of its body.

Document classes (same taxonomy as `docs/zh/`)

Class	Answers	Naming
Design	Why is it built this way?	`*-design.md`
Runbook	How do I do it?	`*-runbook.md`
Lessons	What went wrong before?	`engineering-lessons.md`
Open work	What is not done yet?	`future-plan.md`

Plans (*-plan.md, *-checklist.md) are not kept: once executed they read as "what we intended" while being read as "what is". See docs/zh/README.md for the full rationale.

English documents

Document	Class	Status
`engineering-lessons.md`	Lessons	✅ Translation of the criteria-shape sections (§1, §5)
`design-summaries.md`	Design	✅ One-page summary per design doc

Chinese-only documents (with English summary available)

Document	Class	English summary
`docs/zh/kernel-modularization-design.md`	Design	`design-summaries.md`
`docs/zh/kernel-secret-firewall-design.md`	Design	`design-summaries.md`
`docs/zh/input-scheduler-design.md`	Design	`design-summaries.md`
`docs/zh/resident-subagent-design.md`	Design	`design-summaries.md`
`docs/zh/toolcall-contract-and-sequence-design.md`	Design	`design-summaries.md`
`docs/zh/context-overflow-l4-design.md`	Design	`design-summaries.md`
`docs/zh/commondev-design.md`	Design	plugin-side, Chinese only
`docs/zh/commondev-agent-runtime-design.md`	Design	plugin-side, Chinese only
`docs/zh/deploy-runbook.md`	Runbook	Chinese only — deploy targets are local hosts
`docs/zh/ci-cd-runbook.md`	Runbook	Chinese only — see `.github/workflows/` for the authoritative steps

How to keep this honest

Two rules, both learned from docs/zh/README.md's own history:

Every document carries a status line. Allowed values: current, implementation record, archive (historical), plan (not implemented). A document without one is assumed stale.
This index must be updated in the same commit that adds, removes, or reclassifies a document. An index that lags is worse than no index — it teaches readers to trust the wrong map.

4.1 KiB Raw Blame History