[jasontopia]

Intent

去看一下 Learn First Mate 的教程，整体重新整理一下表述。

现在这份教程主要有几个问题：

1. 写得非常别扭，跟中文表达习惯不一样，读着很不顺
2. 很多名词翻译得不好，翻译要准确
3. AI 味太重，堆了一堆专业名词，句子来回冗余、不知所云，显得很繁琐

需要改掉那些 AI 的表达方式，像正常人类写的教程一样简洁明了：用简单通顺的中文，表达同样的意思。

先整体检查一下，可以先看第一章。如果有改进空间就先改第一章，改完之后再看一下，觉得可以再推广到其他章。

（本次范围：只改第一章 chapters/01-what-is-firstmate.md。其他章等第一章的效果确认后再另做。）

What Changed

• 重写了 chapters/01-what-is-firstmate.md 全章文字，改成简短、口语化的中文。去掉了空泛的铺垫和重复句子，换掉了几个译得不准的术语，比如「隔离工作副本」改成「独立的 git 工作树（worktree）」，「第 N 关」改成「第 N 步」，「立工单」改成「登记工单」。各节标题也相应简化。
• 调整了章节结构：删掉单独的「为什么是这样设计的」一节，把设计理由拆开，写进每条硬规矩下面的「为什么这样定」。四条硬规矩现在都引用 AGENTS.md 第 1 节的英文原文，并补充了 yolo 的限制条件，以及 bin/fm-teardown.sh 拒绝清理时该怎么处理。「写任务简报」一步说明了简报由 bin/fm-brief.sh 模板生成，大副要填写「船长意图」和「大副规格」两部分。
• 改写了两个只读练习：练习 1 改名为「问大副它的边界」，练习 2 改名为「用一件真实的活对照流程」。两个练习都分成「你应该看到」和「怎么检查」两部分，检查方法是在提问前后各运行一次 git status --short 和 git diff HEAD 并对比输出，另外说明了私有目录和待办队列为空时怎么处理。

🤖 Generated with Claude Code

Risk Assessment

✅ Low: This is a docs-only rewrite of one chapter, which is what the intent asks for. I checked its FirstMate behavior claims against AGENTS.md, README.md and the fm-teardown.sh header and they match, except for one overstatement about how a brief is structured. The docs check passes and the ASCII diagram is aligned.

Testing

The baseline docs check passed, and it passed again on the target commit. The diff touches only chapter 1, as the intent requires. The round-1 fix is present: line 111 describes the brief as coming from a fixed template with two parts filled in by the firstmate. Chapter 1 has no em dashes and no absolute local paths. This is a Markdown-only tutorial repo with no runtime surface, so nothing could be driven live, and I did not capture any visual artifacts.

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

Scenario	Result	Live	Evidence
A reader opens chapter 1 and finds it reads as plain, natural Chinese with accurate terms and little AI-style padding	⏸️ untested	no	This is a docs-only change with no runtime product to drive. Whether the prose reads well is an editorial call for a human reviewer (the captain).
A reader of the 'write the brief' step learns that the brief comes from a fixed template and that the firstmate fills two parts, without being told those are the only parts	⏸️ untested	no	This is a docs-only change with no live surface. Reading the text shows the wording now matches the round-1 fix, but that is not a live run.
A reader following links in the rewritten chapter 1 reaches existing targets, and the Markdown passes the repo's hygiene rules	⏸️ untested	no	A static docs check is not a running product. The repo has no runtime surface to drive.
Scope guard: the change edits only chapter 1 and leaves the other chapters and the README alone	⏸️ untested	no	I checked this from git metadata. There is no live product surface to drive.

• Outcome: ⚠️ 1 warning across 1 run (21.3s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ⚠️ chapters/01-what-is-firstmate.md:123 - The new text says "简报分两部分" (the brief has two parts: 「船长意图」 and 「大副规格」). That is wrong. FirstMate AGENTS.md section 11 says the brief is generated from the bin/fm-brief.sh scaffold, which the author must "use as the contract". The firstmate then fills in two task sections, ## Captain's intent and ## Firstmate spec. The scaffold also carries other required parts, such as the worktree-isolation assertion that Step 2 of this same chapter relies on ("船员启动后会自己再检查一遍"). The old text said "简报里 ... 放 ...", which was correct. A reader of the new text would think a brief contains only those two sections. Suggested fix: reword to something like "简报里有两部分由大副来填：..." so the chapter no longer claims the brief has only two parts.
• ℹ️ chapters/01-what-is-firstmate.md:122 - The rewrite uses new Chinese terms that the rest of the book does not use yet. Chapter 1 now says 交付任务 / 调研任务 for ship / scout (line 122) and 工作树 for worktree (line 36 and throughout). README.md's roadmap and chapter titles, plus chapters 2, 3 and 6, still say 出活 / 侦察 and 工作副本. Examples: README row 6 'scout（侦察）任务', row 3 '船员与隔离工作副本', chapters/02-proposing-a-task.md:31 'ship（出活）... scout（侦察）'. A reader going from chapter 1 to chapter 2 sees two different Chinese names for the same concept. The intent limits this change to chapter 1 and plans the other chapters later, so this mismatch is expected for now. Decision needed: accept the mismatch until the rollout, or align the README roadmap titles in this change.

🔧 Fix applied.
1 info still open:

• ℹ️ chapters/01-what-is-firstmate.md:122 - The rewrite uses new Chinese terms that the rest of the book does not use yet. Chapter 1 now says 交付任务 / 调研任务 for ship / scout (line 122) and 工作树 for worktree (line 36 and throughout). README.md's roadmap and chapter titles, plus chapters 2, 3 and 6, still say 出活 / 侦察 and 工作副本. Examples: README row 6 'scout（侦察）任务', row 3 '船员与隔离工作副本', chapters/02-proposing-a-task.md:31 'ship（出活）... scout（侦察）'. A reader going from chapter 1 to chapter 2 sees two different Chinese names for the same concept. The intent limits this change to chapter 1 and plans the other chapters later, so this mismatch is expected for now. Decision needed: accept the mismatch until the rollout, or align the README roadmap titles in this change.

⚠️ **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 opens chapter 1 and finds it reads as plain, natural Chinese with accurate terms and little AI-style padding: This is a docs-only change with no runtime product to drive. Whether the prose reads well is an editorial call for a human reviewer (the captain).; A reader of the 'write the brief' step learns that the brief comes from a fixed template and that the firstmate fills two parts, without being told those are the only parts: This is a docs-only change with no live surface. Reading the text shows the wording now matches the round-1 fix, but that is not a live run.; A reader following links in the rewritten chapter 1 reaches existing targets, and the Markdown passes the repo's hygiene rules: A static docs check is not a running product. The repo has no runtime surface to drive.; Scope guard: the change edits only chapter 1 and leaves the other chapters and the README alone: I checked this from git metadata. There is no live product surface to drive.
• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
A reader opens chapter 1 and finds it reads as plain, natural Chinese with accurate terms and little AI-style padding	⏸️ untested	no	This is a docs-only change with no runtime product to drive. Whether the prose reads well is an editorial call for a human reviewer (the captain).
A reader of the 'write the brief' step learns that the brief comes from a fixed template and that the firstmate fills two parts, without being told those are the only parts	⏸️ untested	no	This is a docs-only change with no live surface. Reading the text shows the wording now matches the round-1 fix, but that is not a live run.
A reader following links in the rewritten chapter 1 reaches existing targets, and the Markdown passes the repo's hygiene rules	⏸️ untested	no	A static docs check is not a running product. The repo has no runtime surface to drive.
Scope guard: the change edits only chapter 1 and leaves the other chapters and the README alone	⏸️ untested	no	I checked this from git metadata. There is no live product surface to drive.

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (baseline, and re-run on the target commit): 15 files checked, no problems
• git diff --stat 308527097f676ef7a588715e4dc28a451adedd7e HEAD: only chapters/01-what-is-firstmate.md changed
• grep -n 简报 chapters/01-what-is-firstmate.md: confirmed the fixed-template wording for the brief at line 111
• grep for the em dash character and for absolute paths like /Users/ or /home/ in chapter 1: none found

⚠️ **Document** - 1 info

• ℹ️ chapters/03-crewmates-and-worktrees.md:5 - Several later chapters quote or point to chapter 1 wording that the rewrite removed. The facts are still in chapter 1, but the exact wording and labels are gone. ch3:5 quotes 「一个船员一件活，每人一个可见的会话端点...和一份独立的 git 工作副本」 and 流程图里「派出船员到隔离工作副本」这一关. ch4:5 quotes 「review、修复、测试、文档、push、开 PR、CI 全部由 no-mistakes 独占」. ch2:5/7 says 第 0 关到第 1 关 and 第 1 关之后的旅程, but chapter 1 now numbers these as 第 N 步. The rule numbers (规矩二 / 规矩四) and 练习 1 still exist, so those references are fine. I left the other chapters alone because the intent limits this change to chapter 1, and the captain already accepted cross-chapter wording mismatches until the later rollout. Follow-up: when the rewrite reaches chapters 2-4, change these quotes to paraphrases or to the new wording in chapter 1.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

术语译法表

之后改其他章沿用这张表。

英文原词	原译法	新译法	理由
worktree	工作副本 / 隔离工作副本	工作树	git 通行译法；「副本」易与 SVN working copy 混淆
primary checkout	主检出目录 / 主检出 / 主目录	主仓库目录	「检出」是直译，读者不懂
endpoint	端点 / 会话端点	会话窗口	指 tmux 窗口、Herdr 标签页等，「端点」是网络术语
landed / unlanded	落地 / 未落地	已合入 / 还没合入	指已合进主分支（或本地主分支）
teardown	拆掉 / 清理收尾	收尾清理	统一一个说法
ship task	出活	交付任务	产出项目改动
scout task	侦察	调研任务	产出调查报告，不开 PR
delivery mode	交付路径	交付方式	no-mistakes / direct-PR / local-only 三选一
delivery posture	交付姿态	交付方式和合并权限	「姿态」是直译，拆成两个具体概念
yolo posture	yolo 姿态	yolo 开关	README 称其为 flag
merge authority	合并权限	合并权限	不变
arm merge poll	武装合并轮询	开始定期查看 PR 是否已合并	直接说做什么
isolation assertion	隔离断言	隔离检查	「断言」是编程术语
escalate	上交	交给大副 / 来问你	按对象说清楚
reconcile	对上	据此调整	意思更明确
volatile state	易变状态	临时状态	通顺
orthogonal	正交的维度	无关 / 互不影响	去掉数学术语
finding (ask-user)	发现	ask-user 类问题	「发现」作名词生硬
respond to gates	回应关卡	流水线停下来等回复时作答	直接描述动作
CI green	CI 转绿	CI 全部通过	不依赖行话
backlog / backlog item	backlog / 工单	待办队列（backlog）/ 工单	队列与其中一项分开称呼
brief	任务简报（brief）	任务简报（brief）	不变
Captain's intent / Firstmate spec	船长意图 / 大副规格	船长意图 / 大副规格	不变
pipeline	质检流水线	质检流水线	不变
captain / firstmate / crewmate / secondmate	船长 / 大副 / 船员 / 二副	同左	项目规定保留