From 0fd2c1d7679e60989d9f89f0164760d50ba9cb38 Mon Sep 17 00:00:00 2001 From: Jasontopia Date: Sat, 26 Sep 2026 17:24:21 -0600 Subject: [PATCH 1/2] =?UTF-8?q?fix(chapters):=20=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E3=80=8C=E4=BA=8C=E5=89=AF=20/=20secondmate=E3=80=8D=E5=91=88?= =?UTF-8?q?=E7=8E=B0=E6=A0=BC=E5=BC=8F=E5=B9=B6=E8=A1=A5=E5=85=A8=E7=A1=AC?= =?UTF-8?q?=E8=A7=84=E7=9F=A9=E4=B8=80=E4=BE=8B=E5=A4=96=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 第 1 章首次出现「二副」处补上英文对照，并补上 AGENTS.md 硬规矩一原文 中遗漏的「继承本地资料的传播」并列项；同时修正练习 1 里「船长 / captain」 的顺序。第 7、8、9 章及 README 里各种「second mate（二副）」等写法统一 成「二副 / secondmate」格式；README 概述段落「船员（crewmate）」同样 统一成「船员 / crewmate」。 --- README.md | 4 ++-- chapters/01-what-is-firstmate.md | 4 ++-- chapters/07-backlog-and-captain-decisions.md | 2 +- chapters/08-supervision-and-wakeups.md | 2 +- chapters/09-secondmates-and-routing.md | 6 +++--- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2083aec..2177d29 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ FirstMate 的中文入门教程与动手练习。 ## 这个仓库是什么 -FirstMate（大副 / firstmate）是一个「agent distro」- 一个可移植的指令、技能、工具、策略与状态约定的目录，它把一个通用的编码 agent 变成一个专门的 agent。你只跟一个 agent 对话，它替你调度和监督一整支 agent 船员（crewmate）队伍，最后把可以合并的 PR、已批准的本地合并，或者独立的调查报告交到你手上。 +FirstMate（大副 / firstmate）是一个「agent distro」- 一个可移植的指令、技能、工具、策略与状态约定的目录，它把一个通用的编码 agent 变成一个专门的 agent。你只跟一个 agent 对话，它替你调度和监督一整支 agent 船员 / crewmate 队伍，最后把可以合并的 PR、已批准的本地合并，或者独立的调查报告交到你手上。 这个仓库不是 FirstMate 本身，而是学它的地方。它把 FirstMate 的每一项功能拆成一节，每节先讲清楚这项功能解决什么问题、它的规矩是什么，再给一个你可以真的让 FirstMate 跑一遍的练习。目标很直接：读完并做完之后，你能把这些做法直接用在自己的真实项目上。 @@ -33,7 +33,7 @@ FirstMate（大副 / firstmate）是一个「agent distro」- 一个可移植的 | 6 | [scout（侦察）任务与调查报告](chapters/06-scout-tasks-and-reports.md) | 什么时候该派侦察而不是直接开工，报告长什么样、存在哪里，以及一份报告为什么不等于动工的授权。 | 已写 | | 7 | [backlog（工单）与船长决策](chapters/07-backlog-and-captain-decisions.md) | 工单队列怎么记录在办和待办的活，一个等你拍板的决策为什么本身也是一张工单，以及它怎么被关闭。 | 已写 | | 8 | [supervision（监督）与唤醒机制](chapters/08-supervision-and-wakeups.md) | 大副怎么在不烧 token 的前提下盯住整支队伍，什么事件会把它叫醒，什么时候才该轮到你被打扰。 | 已写 | -| 9 | [second mate（二副）与分工路由](chapters/09-secondmates-and-routing.md) | 队伍变大之后怎么按领域拆出常驻的二副，一件活按什么规则路由给谁，以及哪些活必须留在主家。 | 已写 | +| 9 | [二副 / secondmate 与分工路由](chapters/09-secondmates-and-routing.md) | 队伍变大之后怎么按领域拆出常驻的二副，一件活按什么规则路由给谁，以及哪些活必须留在主家。 | 已写 | | 10 | [afk 离席模式](chapters/10-afk-mode.md) | 你离开键盘期间谁接手监督，离席期间它敢自己做什么、必须留着等你什么，以及你回来时怎么交接回来。 | 已写 | | 11 | [运行时与 harness 选择](chapters/11-harness-and-runtime-backend.md) | 哪个工具在跑你的船员，运行时后端与 harness 怎么配，以及什么时候值得为一件活单独指定。 | 已写 | | 12 | [Relay](chapters/12-relay.md) | 默认关闭的公开提及接入，开启它意味着授权了什么，以及哪些动作它永远不会自动替你做。 | 已写 | diff --git a/chapters/01-what-is-firstmate.md b/chapters/01-what-is-firstmate.md index f7ab5f7..57fc302 100644 --- a/chapters/01-what-is-firstmate.md +++ b/chapters/01-what-is-firstmate.md @@ -59,7 +59,7 @@ FirstMate 用航海的比喻给三个角色命名。第一次出现时给出中 原文是 "Never write to a project."：大副不在 `projects/` 或任何项目工作副本下编辑、提交、或运行任何会改变状态的命令 - 大副读项目，船员改项目。 -只有几条极窄的例外：受守护的项目初始化、fleet sync、二副同步、自我更新、已批准的 `local-only` 合并路径，以及船长在当下就某个具体项目、具体操作明确批准的一次性操作。而且这些例外**从不**授权强推、stash、丢弃未落地的工作，也从不授权大副手写项目的 `AGENTS.md`。 +只有几条极窄的例外：受守护的项目初始化、fleet sync、二副 / secondmate 同步与继承本地资料的传播、自我更新、已批准的 `local-only` 合并路径，以及船长在当下就某个具体项目、具体操作明确批准的一次性操作。而且这些例外**从不**授权强推、stash、丢弃未落地的工作，也从不授权大副手写项目的 `AGENTS.md`。 **为什么**：如果大副既当调度员又当施工队，那它自己的改动就没有任何一关来把关 - 没有隔离的工作副本，没有质检流水线，没有 PR 审查。更要紧的是，大副是那个要在多件活之间做仲裁的角色；一个同时在改代码的仲裁者，会不自觉地把自己那份改动当成既成事实。把它挡在代码外面，才能保证**每一处项目改动都走同一条有关卡的路**。 @@ -240,7 +240,7 @@ FirstMate 用航海的比喻给三个角色命名。第一次出现时给出中 - 一段用平实语言讲出来的职责边界，而不是把 `AGENTS.md` 原文贴给你。 - 它会说到自己不写项目代码、不在未经你同意时合并 PR、不销毁未落地的工作、以及船员不直接找你这几条。 - 它会指出出处，主要是 `AGENTS.md` 第 1 节。 -- 它会在消息里至少称呼你一次「captain / 船长」- 这是 `AGENTS.md` 明文要求的强制性尊称。 +- 它会在消息里至少称呼你一次「船长 / captain」- 这是 `AGENTS.md` 明文要求的强制性尊称。 **怎么判断做成了** diff --git a/chapters/07-backlog-and-captain-decisions.md b/chapters/07-backlog-and-captain-decisions.md index 30f23e9..fa31bf8 100644 --- a/chapters/07-backlog-and-captain-decisions.md +++ b/chapters/07-backlog-and-captain-decisions.md @@ -12,7 +12,7 @@ `AGENTS.md` 第 10 节开头就定了 backlog 的位置：「The configured `tasks-axi` backend is the durable queue... It tracks work items only, never agents; persistent secondmates never appear as backlog items.」 -翻成大白话：backlog（工单队列）是这支队伍手上所有活的**持久记录**，靠 `tasks-axi` 这套工具管理，落地文件默认是 `data/backlog.md`。它记的是**活本身**，不是船员这个人 —— 一个常驻的二副（secondmate）永远不会作为一个条目出现在这份队列里，队列里的每一行是一件事，不是一个人。 +翻成大白话：backlog（工单队列）是这支队伍手上所有活的**持久记录**，靠 `tasks-axi` 这套工具管理，落地文件默认是 `data/backlog.md`。它记的是**活本身**，不是船员这个人 —— 一个常驻的二副 / secondmate 永远不会作为一个条目出现在这份队列里，队列里的每一行是一件事，不是一个人。 一件活在队列里只会落在三档之一，出处是 `docs/configuration.md`「Backlog backend」一节：「On the default markdown adapter, tasks-axi and manual edits produce the same `## In flight`, `## Queued`, and `## Done` sections.」 diff --git a/chapters/08-supervision-and-wakeups.md b/chapters/08-supervision-and-wakeups.md index 79f61a0..9d19a80 100644 --- a/chapters/08-supervision-and-wakeups.md +++ b/chapters/08-supervision-and-wakeups.md @@ -131,4 +131,4 @@ state: · source: 大副，讲清楚二副 / second mate 到底是什么 - 它跟你自己（大副）以及普通船员分别是什么关系，它比普通船员多出了哪两样东西。再讲清楚为什么不该在队伍刚起步时就先建好几个二副，什么样的信号才说明真的值得为一个领域拆一个常驻的二副出来。回答里指出你是根据 `AGENTS.md` 哪一节说的。这只是让我核对认识，不要创建任何工单，也不要真的去建一个二副或派任何船员。 +> 大副，讲清楚二副 / secondmate 到底是什么 - 它跟你自己（大副）以及普通船员分别是什么关系，它比普通船员多出了哪两样东西。再讲清楚为什么不该在队伍刚起步时就先建好几个二副，什么样的信号才说明真的值得为一个领域拆一个常驻的二副出来。回答里指出你是根据 `AGENTS.md` 哪一节说的。这只是让我核对认识，不要创建任何工单，也不要真的去建一个二副或派任何船员。 **预期会看到什么** From b7588df3d5517ef8c7b1e88b028fcd02d5ed387e Mon Sep 17 00:00:00 2001 From: Jasontopia Date: Sat, 26 Sep 2026 17:31:51 -0600 Subject: [PATCH 2/2] =?UTF-8?q?no-mistakes(review):=20{"summary":=20"fix(c?= =?UTF-8?q?hapters):=20unify=20remaining=20=E4=BA=8C=E5=89=AF/secondmate?= =?UTF-8?q?=20term=20in=20chapter=208"}?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- chapters/08-supervision-and-wakeups.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/08-supervision-and-wakeups.md b/chapters/08-supervision-and-wakeups.md index 9d19a80..6587205 100644 --- a/chapters/08-supervision-and-wakeups.md +++ b/chapters/08-supervision-and-wakeups.md @@ -4,7 +4,7 @@ 第 6 章讲了侦察任务怎么产出一份报告，第 7 章讲了工单队列怎么记录在办和待办的活、以及一个决策本身怎么变成一张工单。这两章都是从**一件活**的角度看问题。这一章把镜头拉远：当队伍里同时有好几件活在跑的时候，大副 / firstmate 怎么盯住整支船员 / crewmate 队伍，而不需要为了「盯着」这件事本身持续消耗 token。 -这一章只回答三个问题：大副是怎么在没有事情发生的时候完全不跑、不烧 token 的；几种唤醒（wake）事件分别代表什么；唤醒之后，哪些事大副自己按规矩就能拍板，哪些才轮到船长 / captain 被打扰。二副 / second mate 怎么帮大副分担这些监督工作，是下一章的内容，这里不展开。 +这一章只回答三个问题：大副是怎么在没有事情发生的时候完全不跑、不烧 token 的；几种唤醒（wake）事件分别代表什么；唤醒之后，哪些事大副自己按规矩就能拍板，哪些才轮到船长 / captain 被打扰。二副 / secondmate 怎么帮大副分担这些监督工作，是下一章的内容，这里不展开。 本章依据的权威文件：FirstMate 仓库 `AGENTS.md` 第 8 节「Supervision protocol」和第 9 节「Escalation and captain etiquette」，以及 `docs/architecture.md` 里「Event-driven supervision」一节和 `bin/fm-watch.sh`、`bin/fm-crew-state.sh` 的头部注释。每个小节会指出具体出处。