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
88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
# docs/en — English documentation index
|
|
|
|
> **Status: index (current).** Established 2026-11-04.
|
|
>
|
|
> **中文索引**: [`../zh/README.md`](../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`](./engineering-lessons.md) | Lessons | ✅ Translation of the criteria-shape sections (§1, §5) |
|
|
| [`design-summaries.md`](./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`](./design-summaries.md#kernel-modularization) |
|
|
| `docs/zh/kernel-secret-firewall-design.md` | Design | [`design-summaries.md`](./design-summaries.md#secret-firewall) |
|
|
| `docs/zh/input-scheduler-design.md` | Design | [`design-summaries.md`](./design-summaries.md#input-scheduler) |
|
|
| `docs/zh/resident-subagent-design.md` | Design | [`design-summaries.md`](./design-summaries.md#resident-subagent) |
|
|
| `docs/zh/toolcall-contract-and-sequence-design.md` | Design | [`design-summaries.md`](./design-summaries.md#toolcall-contract) |
|
|
| `docs/zh/context-overflow-l4-design.md` | Design | [`design-summaries.md`](./design-summaries.md#context-overflow-l4) |
|
|
| `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:
|
|
|
|
1. **Every document carries a status line.** Allowed values: `current`,
|
|
`implementation record`, `archive (historical)`, `plan (not implemented)`.
|
|
A document without one is assumed stale.
|
|
2. **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.
|