[jasontopia]

Intent

合了，然后按译法表改其他章。

背景：这是教程整体改写的第二步。最初的要求是：

去看一下 Learn First Mate 的教程，整体重新整理一下表述。现在这份教程主要有几个问题：1. 写得非常别扭，跟中文表达习惯不一样，读着很不顺；2. 很多名词翻译得不好，翻译要准确；3. AI 味太重，堆了一堆专业名词，句子来回冗余、不知所云，显得很繁琐。需要改掉那些 AI 的表达方式，像正常人类写的教程一样简洁明了：用简单通顺的中文，表达同样的意思。先改第一章，改完之后再看一下，觉得可以再推广到其他章。

第一章的重写（PR #17 ）已经确认并合并，其 PR 描述里的术语译法表也一并认可。这一步把同样的写法和译法表推广到 README 和其余各章（第 2 到 12 章）。

（所引用的 PR #17 的实质内容：它用简单通顺的中文重写了 chapters/01-what-is-firstmate.md，也就是这一步要沿用的写法样板；它的 PR 描述里认可的术语译法表如下：worktree = 工作树；primary checkout = 主仓库目录；endpoint = 会话窗口；landed / unlanded = 已合入 / 还没合入；teardown = 收尾清理；ship task = 交付任务；scout task = 调研任务；delivery mode = 交付方式；delivery posture = 交付方式和合并权限；yolo posture = yolo 开关；merge authority = 合并权限；arm merge poll = 开始定期查看 PR 是否已合并；isolation assertion = 隔离检查；escalate = 交给大副 / 来问你（按对象说）；reconcile = 据此调整；volatile state = 临时状态；orthogonal = 无关 / 互不影响；finding (ask-user) = ask-user 类问题；respond to gates = 流水线停下来等回复时作答；CI green = CI 全部通过；backlog / backlog item = 待办队列（backlog）/ 工单；brief = 任务简报（brief）；Captain's intent / Firstmate spec = 船长意图 / 大副规格；pipeline = 质检流水线；captain / firstmate / crewmate / secondmate = 船长 / 大副 / 船员 / 二副。）

What Changed

• Rewrote README.md and chapters 2 through 12 in the plain Chinese style of chapter 1. Every chapter now uses the same term renderings, for example 工作树, 交付任务 / 调研任务, 合并权限, 质检流水线 and 待办队列（backlog）/ 工单. Review follow-ups put back source qualifiers and first-use English terms that the rewrite had dropped. They also restored the scout threshold in chapter 6 and corrected the blocker wording in chapter 3.
• Added GLOSSARY.md as the single term table for the whole book. It lists roles, task and delivery terms and the rest, plus rules for command and tool names and for terms that are not in the table. Chapter 1 now uses 调研 instead of 调查 so it matches the table.
• Added two writing rules to AGENTS.md: translate terms exactly as GLOSSARY.md does and add any new term there, and match the plain style of chapter 1.

🤖 Generated with Claude Code

最终术语译法表

全书唯一的译法表在 GLOSSARY.md。下表是它的完整内容：PR #17 已认可的译法照旧（captain / firstmate / crewmate / secondmate 在表里拆成了四行），本 PR 新定的词标为「新增」。

英文原词	译法	备注
captain	船长
firstmate	大副
crewmate	船员
secondmate	二副
fleet / crew	队伍	新增
ship task	交付任务
scout task	调研任务
intake	立项	新增
brief	任务简报（brief）
Captain's intent / Firstmate spec	船长意图 / 大副规格
charter / charter brief	职责简报	新增
backlog / backlog item	待办队列（backlog）/ 工单
In flight / Queued / Done	在办 / 待办 / 已完成	新增
delivery mode	交付方式
delivery posture	交付方式和合并权限
yolo posture	yolo 开关
merge authority	合并权限
pipeline	质检流水线
respond to gates	流水线停下来等回复时作答
finding (ask-user)	ask-user 类问题
accepted design / accepted intent	已确认的设计	新增
CI green / red	CI 全部通过 / CI 没通过	green 已认可；red 为新增
arm merge poll	开始定期查看 PR 是否已合并
landed / unlanded	已合入 / 还没合入
teardown	收尾清理
promote (scout → ship)	转成交付任务	新增
escalate	交给大副 / 来问你（按对象说）
hold (captain hold)	挂起	新增
blocker	阻塞	新增
worktree	工作树
primary checkout	主仓库目录
isolation assertion	隔离检查
endpoint	会话窗口
primary session	主会话	新增
home（firstmate home）	FirstMate 目录	新增
main home	主 FirstMate 目录	新增
harness	harness（跑船员的 agent 工具，比如 Claude Code）	新增
runtime backend	运行时后端（提供会话窗口的终端工具，比如 tmux）	新增
status line / status file	状态行 / 状态文件	新增
volatile state	临时状态
supervision	监督	新增
wake	唤醒	新增
watcher	监控脚本	新增
daemon	守护进程	新增
heartbeat	心跳	新增
stale	久无动静	新增
away mode / afk	离席模式（afk）	新增
quiet mode	静默模式	新增
return (from afk)	回来	新增
routing	分派	新增
scope（secondmate scope）	负责范围	新增
parent channel	上报渠道	新增
Relay	Relay（保留英文）	新增
mention	提及	新增
pairing token	配对令牌	新增
trusted channel	可信渠道	新增
reconcile	据此调整
orthogonal	无关 / 互不影响
dispatch / spawn	派出（派工）	新增
verified	验证过的	新增

Risk Assessment

✅ Low: This is a docs-only rewrite. Both round-2 fixes are in the current text: chapter 6 now says 可能明显影响 at all three sites, which matches chapter 2, and chapter 3 now says a real blocker is still a reason to wait. The round-1 fixes also hold: the owner-only wording and the untrusted-context clause in ch12, the gate condition in ch7, 调研 in ch1, 主会话 in GLOSSARY.md, and the added first-use English. python3 scripts/check-docs.py passes and no em dashes remain.

Testing

This is a documentation-only change to a Chinese tutorial, and the repo has no build or runtime, so nothing could be exercised live. I re-ran the repo's only check, scripts/check-docs.py, which passed; searched for em dashes and found none; and read the text to confirm each fix the user asked for in review rounds 1 and 2. The verdict is no-surface.

• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
A reader reads the README and chapters 2 to 12 and finds plain Chinese with the same term renderings as chapter 1 and GLOSSARY.md	⏸️ untested	no	Only Markdown prose changed; there is no running product to test. Judging whether the writing reads well is a call for a human reviewer.
A reader of chapter 12 learns that Relay takes mentions only as coming from the owner, not from anyone else	⏸️ untested	no	Documentation-only change with nothing that runs; only the text could be checked.
A reader of chapters 2 and 6 sees the same bar for sending a scout: only when an open question could materially change whether or what to build	⏸️ untested	no	Documentation-only change with nothing that runs; only the text could be checked.
The tutorial's links and formatting pass the repo's docs check	⏸️ untested	no	The script checks static files and does not run the product; there is no product runtime in this repo to test live.

Evidence: Docs check and em-dash scan

checked 16 markdown file(s): no problems found em-dash count: 0

checked 16 markdown file(s): no problems found
em-dash count: 0

- Outcome: ⚠️ 1 warning across 1 run (23.8s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 6 issues found → auto-fixed (2) ✅

• 🚨 chapters/12-relay.md:5 - Line 5 says 「打开它之后，别人在 X（原 Twitter）或 Discord 上公开提及（@）你的大副，就能叫醒它」, which tells readers anyone else can wake their firstmate. FirstMate says Relay uses owner-only routing: a mention delivered to a home counts as coming from that home's owner/captain (FirstMate docs/configuration.md:764). The chapter's own line 42 says the same thing correctly, so line 5 contradicts it. The old text did not say 「别人」, so the rewrite introduced this. Fix: remove 「别人」, e.g. 「在 X 或 Discord 上公开提及（@）你的大副就能叫醒它」.
• ⚠️ chapters/12-relay.md:42 - Line 42 now stops at 「…可能有别的公开账号的内容。」. The old text went on to say this surrounding conversation is background only, not the captain's instruction. FirstMate treats that chain as 'untrusted third-party public input' (docs/configuration.md:797). Without the clause the 「不过」 leads nowhere and the safety point is lost. Fix: add back a clause saying this content is only background and does not count as your instruction.
• ⚠️ chapters/07-backlog-and-captain-decisions.md:21 - Line 21 says bin/fm-spawn.sh and bin/fm-teardown.sh always move backlog items themselves. FirstMate says this happens only 'When the automatic transition gate applies' and has an exception for the manual backend (FirstMate AGENTS.md:556, docs/configuration.md:124-125). The old text kept the condition; the rewrite drops it. Fix: restore it, e.g. 「在自动挪动工单的机制生效时」, and point to docs/configuration.md.
• ⚠️ chapters/02-proposing-a-task.md:26 - Line 26 says a scout is for uncertainty that 「可能影响」 whether or what to build. The source says it must 'materially change' that (AGENTS.md:316), and the old text said 「实质影响」, so the rewrite lowers the bar for choosing a scout. Fix: 「可能明显影响…」. The rewrite dropped other source-backed details in the same way: 02:51 omits the second reason fm-spawn rejects a brief, a Captain's intent line that opens with a Captain label or addresses the captain (bin/fm-brief.sh:12-13); 03:30 drops that genuine blockers remain durable (AGENTS.md:332); 04:34 no longer mentions --resolve-key (AGENTS.md:387); 10:21 and 10:74 drop the /afk read-back, where the firstmate restates the captain's words after entry and the captain corrects it by sending /afk again (.agents/skills/afk/SKILL.md:5,46-50).
• ⚠️ chapters/09-secondmates-and-routing.md:5 - Several glossary terms first appear without their English, which breaks the AGENTS.md first-use rule; for most of them the old text had it. In ch9: 负责范围 (scope) at 09:5 and 上报渠道 (parent channel) at 09:50. In ch7: 挂起 (hold) at 07:7. In ch8: 监控脚本 (watcher) at 08:15, 状态文件/状态行 at 08:29/36. In ch12: 配对令牌 (pairing token) at 12:13, 提及 (mention) at 12:5 given as 「（@）」, 可信渠道 (trusted channel) at 12:44. 分派 (routing) at README.md:36 and 08:128 lacks it too, but that was already missing before this change. Fix: add the English in brackets at each first use.
• ℹ️ chapters/01-what-is-firstmate.md:31 - Chapter 1 still says 调查 (「先调查清楚」 at line 31, 「一份调查报告」 at line 35). The new GLOSSARY.md and the rewritten chapters and README use 调研 for scout work and reports, so the book now uses two renderings, which breaks the one-rendering-per-term rule. Fix: change these to 调研. 主会话, used in every exercise setup, is also missing from GLOSSARY.md.

🔧 Fix applied.
2 issues (1 warning, 1 info) still open:

• ⚠️ chapters/06-scout-tasks-and-reports.md:13 - Round 1 restored the 'materially change' qualifier in chapter 2 (02:26 now says 可能明显影响) but missed the same qualifier in chapter 6. Chapter 6 still says plain 「可能影响」 or 「会不会影响」 in three places: 06:13 (keeping bounded research inside a ship), 06:18 (the second scout trigger), and 06:20 (the stated test for choosing a scout). The source says 'could materially change whether or what to build' (FirstMate AGENTS.md:315-316). The old chapter 6 kept the threshold (「不确定性大到可能改变」), so the rewrite lowered the bar for sending a scout in the chapter that exists to explain that choice. It also contradicts the corrected chapter 2. Fix: use the same wording as 02:26 at all three sites, e.g. 「可能明显影响要不要做、做成什么样」.
• ℹ️ chapters/03-crewmates-and-worktrees.md:30 - Round 1 added 「反过来，真正的阻塞会一直挡在那里，不会自己消失。」 as the rendering of 'genuine blockers remain durable' (FirstMate AGENTS.md:332). In the source, that clause ends the rule on when to serialize: same-file editing is not a reason to wait, but a genuine blocker still is. The added sentence instead says blockers never go away by themselves, which the source does not say and which reads as a claim about how the world behaves. Fix: say plainly that a real blocker is still a reason to wait, e.g. 「但真正的阻塞仍然是要排队等的理由。」

🔧 Fix applied.
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 4 scenarios were driven live against the product); A reader reads the README and chapters 2 to 12 and finds plain Chinese with the same term renderings as chapter 1 and GLOSSARY.md: Only Markdown prose changed; there is no running product to test. Judging whether the writing reads well is a call for a human reviewer.; A reader of chapter 12 learns that Relay takes mentions only as coming from the owner, not from anyone else: Documentation-only change with nothing that runs; only the text could be checked.; A reader of chapters 2 and 6 sees the same bar for sending a scout: only when an open question could materially change whether or what to build: Documentation-only change with nothing that runs; only the text could be checked.; The tutorial's links and formatting pass the repo's docs check: The script checks static files and does not run the product; there is no product runtime in this repo to test live.
• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
A reader reads the README and chapters 2 to 12 and finds plain Chinese with the same term renderings as chapter 1 and GLOSSARY.md	⏸️ untested	no	Only Markdown prose changed; there is no running product to test. Judging whether the writing reads well is a call for a human reviewer.
A reader of chapter 12 learns that Relay takes mentions only as coming from the owner, not from anyone else	⏸️ untested	no	Documentation-only change with nothing that runs; only the text could be checked.
A reader of chapters 2 and 6 sees the same bar for sending a scout: only when an open question could materially change whether or what to build	⏸️ untested	no	Documentation-only change with nothing that runs; only the text could be checked.
The tutorial's links and formatting pass the repo's docs check	⏸️ untested	no	The script checks static files and does not run the product; there is no product runtime in this repo to test live.

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (baseline, re-run): checked 16 markdown files, no problems found
• grep -rn '—' README.md GLOSSARY.md chapters: no em dashes found
• Checked the text for each requested fix: ch12 no longer says 别人 (so it no longer suggests anyone else can wake your firstmate); ch2 and ch6 say 可能明显影响; ch3 says 「但真正的阻塞仍然是要等的理由。」; ch1 no longer uses 调查; GLOSSARY.md has 主会话 = primary session; ch7 again limits the automatic backlog move to when that mechanism applies

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.