Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ A pure documentation repo: a Chinese-language tutorial teaching newcomers how to
## Writing rules

- Write in Chinese. Give the English term alongside the Chinese one on first use (船长 / captain, 大副 / firstmate, 船员 / crewmate), then use Chinese only.
- Translate every term exactly as `GLOSSARY.md` does, one rendering per term across the whole book. It is the only copy of the term table: add a new term there rather than coining a rendering inline.
- Match the plain style of `chapters/01-what-is-firstmate.md`: short plain sentences, no translationese, no filler or repeated points, sources noted once per chapter or section rather than per sentence.
- Every statement about how FirstMate behaves must be traceable to an authoritative tracked file in the local FirstMate checkout, read in this priority order: `AGENTS.md` (the firstmate supervisor contract), `README.md`, the relevant file under `docs/`, then the header comment of the relevant `bin/` script. Do not describe FirstMate behavior from memory or inference - if it has no source there, leave it out.
- That checkout is READ-ONLY. Never write to it or run a state-changing command in it.
- `.env`, `data/`, `state/`, `config/`, `projects/`, and `.no-mistakes/` in that checkout are captain-private. Never use their contents as tutorial material, and never put a captain's local absolute path into this repo.
Expand Down
95 changes: 95 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# 术语译法表

全书的术语统一按这张表翻译,同一个词只用一种译法。第一次出现时中英文并列,比如「工作树(worktree)」,之后只用中文。

命令名、脚本名、配置名、工具名一律保留原样,比如 `no-mistakes`、`yolo`、`bin/fm-spawn.sh`、`tasks-axi`、tmux。表里没有的词,按同样的原则来:中文里自然、准确,能直接说清楚做什么就不另造新词。

## 角色

| 英文原词 | 译法 |
| --- | --- |
| 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 没通过 |
| 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) | 回来 |

## 分派与 Relay

| 英文原词 | 译法 |
| --- | --- |
| routing | 分派 |
| scope(secondmate scope) | 负责范围 |
| parent channel | 上报渠道 |
| Relay | Relay(保留英文) |
| mention | 提及 |
| pairing token | 配对令牌 |
| trusted channel | 可信渠道 |

## 常用动词和形容词

| 英文原词 | 译法 |
| --- | --- |
| reconcile | 据此调整 |
| orthogonal | 无关 / 互不影响 |
| dispatch / spawn | 派出(派工) |
| verified | 验证过的 |
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,39 @@
# Learn FirstMate

FirstMate 的中文入门教程与动手练习。
FirstMate 的中文入门教程,每章配一个动手练习。

## 这个仓库是什么
## 这是什么

FirstMate(大副 / firstmate)是一个「agent distro」- 一个可移植的指令、技能、工具、策略与状态约定的目录,它把一个通用的编码 agent 变成一个专门的 agent。你只跟一个 agent 对话,它替你调度和监督一整支 agent 船员 / crewmate 队伍,最后把可以合并的 PR、已批准的本地合并,或者独立的调查报告交到你手上。
FirstMate 是一个「agent 发行版」(agent distro):一个目录,里面装着指令、技能、脚本、规则和状态约定,能把一个通用的编码 agent 变成专门带队干活的 agent。你只跟一个 agent 说话,它就是大副 / firstmate。大副替你派出和监督一队船员 / crewmate,最后交给你可以合并的 PR、你批准过的本地合并,或者一份调研报告。

这个仓库不是 FirstMate 本身,而是学它的地方。它把 FirstMate 的每一项功能拆成一节,每节先讲清楚这项功能解决什么问题、它的规矩是什么,再给一个你可以真的让 FirstMate 跑一遍的练习。目标很直接:读完并做完之后,你能把这些做法直接用在自己的真实项目上。
这个仓库不是 FirstMate 本身,是学它用的。每章讲一项功能:它解决什么问题、有哪些规矩,然后给一个你可以在自己的 FirstMate 上跑一遍的练习。读完做完,你就能在自己的项目上照着用。

教程里所有关于 FirstMate 行为的陈述,都以 FirstMate 仓库里被版本追踪的权威文件为依据 - `AGENTS.md`(大副的职责契约)、`README.md`、`docs/` 下的文档,以及 `bin/` 下脚本的头部注释。每一章都会指出对应的出处,方便你自己回去核对。
教程里关于 FirstMate 的每一条说法,都能在 FirstMate 仓库里找到出处:`AGENTS.md`(大副的工作守则)、`README.md`、`docs/` 下的文档,以及 `bin/` 下脚本开头的注释。每章开头会说明这一章依据的是哪些文件。

## 怎么用它学习
## 怎么学

每一节都是同一个节奏,两步:
每章两步:

1. **读一章。** 一章只讲一个主题,篇幅控制在一次能读完。遇到不确定的机制性说法,顺着章节里给出的出处回去读原文 - 这本身也是使用 FirstMate 的基本功。
2. **做一次练习。** 每章末尾有「动手练习」,给出你(船长 / captain)可以照着对大副说的中文原话,以及预期会看到什么、怎么判断做成了。练习都是只读或安全可逆的,不会改动别人的仓库,也不会做不可回退的操作。
1. **读。** 一章一个主题,一次能读完。哪里拿不准,就去翻这一章列出的原文。
2. **练。** 每章最后有「动手练习」,给出你(船长 / captain)可以直接对大副说的话,以及应该看到什么、怎么检查。练习都是只读或可以撤回的,不会改别人的仓库,也不会做收不回的操作。

建议按顺序走。前面几章建立的词汇和心智模型,后面的章节会一直用到。
最好按顺序读,后面的章节会用到前面讲过的概念。全书的术语译法统一收在 [术语译法表](GLOSSARY.md) 里。

## 学习路线图
## 章节

章节顺序是按「先懂全局,再懂每一关,最后懂长期运营」排的:第 1 章先给你整幅地图;第 2 到 5 章沿着一件活的真实旅程往下走,每章钉住旅程中的一关;第 6 到 8 章是从单件活扩展到一支队伍要处理的事 - 知识产出、排队决策、无人值守的监督;第 9 到 11 章是规模、离席、以及「到底是哪个工具在跑你的船员」这类进阶话题;第 12 章单独讲 Relay,它默认关着,不开就完全不影响你。
第 1 章先讲全貌。第 2 到 5 章跟着一件活往下走,每章讲其中一步。第 6 到 8 章讲活多了以后的事:调研报告、待办队列、监督。第 9 到 11 章讲进阶话题:二副、离席、用什么工具跑船员。第 12 章讲 Relay,它默认关着,不打开就不影响你。

| # | 章节 | 这章要解决什么问题 | 状态 |
| -- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---- |
| 1 | [FirstMate 是什么:三方分工与一件活的旅程](chapters/01-what-is-firstmate.md) | 船长、大副、船员各自负责什么,一件活从人开口到落地合并要过哪几关,以及为什么要这样切分。 | 已写 |
| 2 | [如何提出一件活](chapters/02-proposing-a-task.md) | 一句话的请求怎么变成一件有明确项目、明确交付形态、明确验收边界的活,以及你怎么说能少走弯路。 | 已写 |
| 3 | [船员与隔离工作副本](chapters/03-crewmates-and-worktrees.md) | 每个船员为什么要在自己的一份 git 工作副本里干活,并行的多件活为什么不会互相踩,出事时怎么看。 | 已写 |
| 4 | [no-mistakes 质检流水线](chapters/04-no-mistakes-pipeline.md) | 交付前那道自动化关卡都查什么,它自己修什么,什么情况下会停下来问人,以及问到人时该怎么回答。 | 已写 |
| 5 | [PR 与合并权限](chapters/05-pr-merge-authority.md) | 为什么默认必须你点头才合并,yolo 姿态放开了什么、没放开什么,以及红色 CI 为什么依然不能合。 | 已写 |
| 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 | [二副 / 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) | 默认关闭的公开提及接入,开启它意味着授权了什么,以及哪些动作它永远不会自动替你做。 | 已写 |
| # | 章节 | 讲什么 |
| -- | ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 1 | [FirstMate 是什么](chapters/01-what-is-firstmate.md) | 船长、大副、船员各管什么,四条硬规矩,一件活从提出到合并要经过哪几步。 |
| 2 | [怎么提出一件活](chapters/02-proposing-a-task.md) | 一句话的要求怎么变成项目、任务类型、交付方式和验收标准都明确的任务。 |
| 3 | [船员与工作树](chapters/03-crewmates-and-worktrees.md) | 为什么每个船员有自己的工作树,几件活同时做为什么不打架,出事时怎么查。 |
| 4 | [no-mistakes 质检流水线](chapters/04-no-mistakes-pipeline.md) | 流水线查什么、自己修什么,什么时候停下来问人,问到时大副怎么答。 |
| 5 | [PR 与合并权限](chapters/05-pr-merge-authority.md) | 为什么默认要你同意才合并,`yolo` 开关放开了什么,CI 没通过为什么不能合。 |
| 6 | [调研任务与报告](chapters/06-scout-tasks-and-reports.md) | 什么时候该先调研,报告放在哪里,为什么报告本身不等于同意动手改。 |
| 7 | [待办队列与船长决策](chapters/07-backlog-and-captain-decisions.md) | 待办队列怎么记活,等你拍板的问题为什么也是一张工单,你的回答怎么关掉它。 |
| 8 | [监督与唤醒](chapters/08-supervision-and-wakeups.md) | 大副怎么在不耗 token 的情况下盯住队伍,什么事会叫醒它,什么事才来找你。 |
| 9 | [二副与分派](chapters/09-secondmates-and-routing.md) | 队伍大了以后怎么按领域设常驻的二副,一件活怎么分派(routing)给谁,哪些活留在大副这边。 |
| 10 | [离席模式(afk)](chapters/10-afk-mode.md) | 你走开时谁来监督,大副能自己做什么、必须等你什么,你回来时怎么交接。 |
| 11 | [harness 与运行时后端](chapters/11-harness-and-runtime-backend.md) | 船员是用什么工具、在什么终端里跑的,默认怎么选,什么时候值得单独指定。 |
| 12 | [Relay](chapters/12-relay.md) | 默认关着的公开提及功能,打开它等于同意了什么,哪些事它永远不会自己做。 |
4 changes: 2 additions & 2 deletions chapters/01-what-is-firstmate.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ FirstMate 借用了船上的称呼。

你所有项目上的软件工作,都只跟大副说。它负责:

- 判断这件活属于哪个项目,是直接改,还是先调查清楚。
- 判断这件活属于哪个项目,是直接改,还是先调研清楚。
- 登记工单,给船员写任务简报(brief)。
- 派船员干活,每个船员一个独立的 git 工作树(worktree)。
- 盯着整支队伍把活干完,只在真正需要你决定时才来找你。
- 用简单的话告诉你结果:一个 PR、一次你批准过的本地合并,或者一份调查报告。
- 用简单的话告诉你结果:一个 PR、一次你批准过的本地合并,或者一份调研报告。

大副自己不改项目代码,原因见下面的规矩一。

Expand Down
Loading
Loading