diff --git a/GLOSSARY.md b/GLOSSARY.md index 283fc9c..7e12940 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -72,6 +72,19 @@ | away mode / afk | 离席模式(afk) | | quiet mode | 静默模式 | | return (from afk) | 回来 | +| supervision host | 监督宿主 | + +## 命令与技能 + +| 英文原词 | 译法 | +| --- | --- | +| skill | 技能 | +| slash command | 斜杠命令 | +| agent-only reference skill | 大副专用技能 | +| digest | 摘要 | +| board(Lavish board) | 看板 | +| completion receipt | 回执 | +| pinned(记忆条目) | 固定 | ## 分派与 Relay diff --git a/README.md b/README.md index 51e1b36..5d6467f 100644 --- a/README.md +++ b/README.md @@ -44,3 +44,4 @@ FirstMate 是一个「agent 发行版」(agent distro):一个目录,里 - [agent-skills 对 FirstMate 有没有用(2026-09-28)](references/agent-skills-evaluation-2026-09-28.md):`addyosmani/agent-skills` 的九个命令、六个阶段和 25 个 skill,按编排、交付验证、工程纪律、产品定义四层看它和 FirstMate 哪里重叠、互补、冲突,船员怎样在项目里挑着装这些 skill,和 Superpowers、Spec Kit、OpenSpec、Kiro、BMAD 等方案的对比,以及推荐做法。 - [先做哪个 AI 工具小网站(2026-09-29)](references/ai-tool-site-research-2026-09-29.md):拿核实过的收入数据检验 2026 年「小工具赚钱」的说法,定选题标准和打分,约 27 个候选方向的淘汰理由,6 个入围方向的对比,以及推荐方向 AI 扒谱网站的关键词、竞品、MVP 范围、技术路线、单位经济、获客、风险和下一步。 +- [命令与技能使用说明(2026-10-15)](references/commands-and-skills-guide-2026-10-15.md):`/afk`、`/quiet`、`/ahoy`、`/bearings`(含 `file`、`lavish`)、`/stow`、`/updatefirstmate`、`/calm`、`/supervision-model` 各自做什么、什么时候用、有什么例子、自己绝不会做什么;你能调用的技能和大副专用技能各有哪些;以及把日常需求对应到命令的场景对照表。 diff --git a/references/commands-and-skills-guide-2026-10-15.md b/references/commands-and-skills-guide-2026-10-15.md new file mode 100644 index 0000000..3da2866 --- /dev/null +++ b/references/commands-and-skills-guide-2026-10-15.md @@ -0,0 +1,341 @@ +# FirstMate 命令与技能使用说明 + +核对日期:2026-10-15 +读的版本:FirstMate 仓库 `a24f4cb`(main)。同日对照上游 main(`230db82`),两者相差 5 个提交,只改了 `docs/` 下与本页无关的几处,`README.md`、`AGENTS.md`、`.agents/skills/`、`skills/` 都没变。 + +> **参考资料,不是教程章节。** 这是一份给船长(captain)查的速查页:FirstMate 里有哪些命令、哪些技能,各自管什么,什么时候用。它不配练习,也不替代各章。每一条说法都能在 FirstMate 仓库里找到出处,出处写在各节末尾。技能文件会随版本改,行为以你手里那一版为准。 +> +> 本页里的「例子」是根据技能原文推出来的,不是真实跑出来的记录。原文没写清楚的地方,直接写「文档没说清」,没有替它补。 + +## 先弄清两件事 + +**命令就是技能。** FirstMate 把可以由你直接敲的东西做成技能(skill),也就是仓库里的 `SKILL.md` 文件。你敲的 `/afk`、`/quiet` 这类斜杠命令(slash command),背后就是同名技能。Claude 和 Grok 用 `/afk`,Codex 用同样的名字加 `$`,写成 `$afk`。 + +**技能分两类。** 一类是你可以敲的,文件里写着 `user-invocable: true`,一共 6 个。另一类是大副 / firstmate 专用的参考技能,写着 `user-invocable: false`,你不用调用,大副走到对应的场合会自己加载。第二部分把这两类都列全。 + +另外有两个命令不是技能,是 harness 自己注册的:`/calm`(Pi 和 Claude Code)和 `/supervision-model`(只有 Pi)。 + +依据:`README.md` 的「Built-in skills」一节和「Two-tier skill layout」一节,`.agents/skills/*/SKILL.md` 开头的 `user-invocable` 字段。 + +## 常见场景对照表 + +| 你想做的事 | 输入什么 | 备注 | +| --- | --- | --- | +| 要去睡觉,或者走开几个小时 | `/afk` 加一两句交代,比如「走完质检流水线的活按原来的节奏推进,其他等我回来」 | 说完就生效,不等你确认。回来随便发一句话就行,不需要 `/back` | +| 人在,但不想被例行动静打扰 | `/quiet`;想恢复,输入 `/quiet off` | 普通聊天不会退出静默模式 | +| 想看一份「现在到哪了」的摘要 | `/bearings` | 只在对话里给四节摘要,不写文件 | +| 想要一份能留存的报告 | `/bearings file` | 只说「帮我写个报告」不算,必须带 `file` | +| 想要一块能直接点选答复的决策看板 | `/bearings lavish` | 同样必须带 `lavish`。看板上的「Merge now」等于你对那一个 PR 说了合并 | +| 摘要里也想看 PR 的实时情况 | `/bearings include PRs` | 可以和 `file`、`lavish` 一起用 | +| 只想知道刚才这段对话里发生了什么,以及哪些决定还悬着 | `/ahoy` | 只回顾对话里已经看得到的事,不去查最新状态 | +| 更新 FirstMate | `/updatefirstmate`,或者直接说「update firstmate」 | 只做快进更新,不强制 | +| 要重置会话,想把会话里学到的东西存下来 | `/stow` | 会话里的内容重置后就没了,先 stow | +| 嫌转录里的工具调用、思考标签太吵 | `/calm`(Pi,或设了环境变量的 Claude Code) | 只改显示,不改大副实际收到的内容 | +| Pi 上想给监督用更便宜的模型 | `/supervision-model` | 只影响监督,不影响你自己的对话 | +| 派活、答复大副的问题、批准合并 | 没有命令,直接用一句话说 | 见第 2 章、第 5 章、第 7 章 | + +## 一、你能敲的命令 + +### `/afk`:离席 + +**做什么。** 进入离席模式。你打 `/afk` 就是「开始」,不是请求批准:大副会在同一轮里、做任何别的事之前,把你交代的话原样记下来,然后告诉你记下了什么、有哪些事它做不了。离席期间,监督会话按你留下的话办事;拿不准的、需要你的,留着等你回来。 + +**什么时候用。** 你要走开,可能不会再看屏幕。如果只是想少收点例行动静,人还在,用 `/quiet`。 + +**例子。** 输入: + +> `/afk 走完质检流水线的活按原来的节奏推进,其他的等我回来。` + +大概会发生的事: + +- 大副先把这句话原样写进离席记录,不等你回复。 +- 然后告诉你:只有「留着等你回来」这一档,没有手机通知;你的话已经记下;它会用自己的话把你的话复述一遍,并说明哪句话离席期间做不了。 +- 这些只是告知,它不会问你要不要继续。理解错了,再发一次 `/afk` 加新的话,新的话会替换旧的,旧的存档留给你回来时看。 + +只打 `/afk`、不带话也可以,大副会说没有记下任何交代。 + +**怎么回来。** 不需要 `/back`。你发的第一条正常消息就是回来的信号。大副先跑一遍回来的交接,把离席期间的事交代清楚,再处理你那句话。交接里有没有处理完的阻塞(blocker),要先清掉,才会继续动队伍;这期间你仍然可以要 `/bearings`。离席期间已经合入、等着收尾清理的任务,交接完后大副会收尾并告诉你。离席期间再打 `/afk`,是刷新,不是回来。 + +**它不会自己做的事。** + +- 不会放宽任何权限。离席只改两件事:怎么通知你,以及遇到该你拍板的事时是等你还是照你事先说的办。 +- 破坏性的、不可逆的、涉及安全的操作,不管你走之前怎么说,都不能提前授权。 +- 你的话只管字面上说到的事,不会类推。没把握的,等你回来。 +- CI 没通过(红)的 PR 不会合并。只在本地合入(local-only)的活,永远等你回来。`--allow-red`、`--allow-missing` 在离席期间会被拒绝。 +- 合并只在你的话明确要求时才可能发生,而且必须是同步完成、能立刻证明已合入的合并。 + +**文档没说清。** + +- 离席记录里有「预计回来时间」和「花费上限」两项,复述时也会提到,但技能没写船长该怎么设置它们。要不要靠自然语言写进话里、会不会被当成上限,没有出处,不要假设。 +- 谁来接手监督因 harness 而异:Pi 上是内置的监督分支,默认的 Claude 主会话上是监督宿主(supervision host),其他情况是守护进程(daemon)。对你来说怎么用没有区别,各自的机制见第 10 章和 `afk` 技能。 + +依据:`README.md` 的「Built-in skills」,`.agents/skills/afk/SKILL.md`,`.agents/skills/away-quiet-supervision/SKILL.md`,`bin/fm-afk-launch.sh` 开头的注释。第 10 章有更完整的讲解。 + +### `/quiet`:静默模式 + +**做什么。** 你人在,只想让例行动静别占用对话。进入后,进展、重试这类例行的事留在后台,决定、失败、凭据、可以评审的活照样来找你。 + +**和 `/afk` 的区别。** `/afk` 里你发任何正常消息都算回来;静默模式里,你随便聊都不会退出,只有明确说 `/quiet off`(或者明确说想恢复正常监督)才退出。在静默模式里再打 `/quiet` 是刷新。 + +**什么时候用。** 你守在会话里,但不想每个船员的小动静都占一轮对话。 + +**例子。** 输入 `/quiet`,大副大概回:静默模式开着,例行更新它先攒着,只把决定、失败、凭据、可评审的活报给你,普通聊天不会退出,想恢复就说 `/quiet off`。这是技能里写好的那句确认话的大意。 + +**它可能什么都不开。** 在 Pi 上,以及运行「在场监督宿主」的主会话上,监督本来就不会把例行动静放进你的对话。这时 `/quiet` 不会启动任何东西,只告诉你「这里本来就是这样」。如果监督会话当时处于暂停,它会改说例行更新会到你这儿,并告诉你它什么时候重试。 + +**如果你正处在离席状态。** 先按回来处理(交接、清掉阻塞),然后再看静默模式要不要开。 + +**它不会自己做的事。** + +- 不改变谁批准什么。合并仍按原来的合并权限,ask-user 类问题仍按原来的规矩。 +- 不会把决定或失败藏起来。它只改呈现,不改要不要来找你。 +- 不会替你等。你人在,所以你要求的事(合并、派活、本地合入)都是现在就办,不像离席那样留着等回来。 +- 不是默认开启的,只有你明确打 `/quiet` 才进入。 + +依据:`README.md` 的「Built-in skills」,`.agents/skills/quiet/SKILL.md`,`docs/supervision-host.md` 的「Quiet mode」一节,`AGENTS.md` 第 8 节「Away-mode and quiet-mode stub」。 + +### `/ahoy`:回顾这段对话 + +**做什么。** 给你一份只看对话本身的简短回顾。它找到你上一条真正由你发的消息,把那之后、这条 `/ahoy` 之前,对话里看得见的事讲一遍:结果、已合入的活、失败、已经做的决定、新要你决定的事、还在跑的活。对话里出现过的 PR 完整链接会原样保留。回顾之后,如果还有悬着没回答的决定,它一次只拿出一个,按它判断的影响大小排序(并说明这个顺序是它的挑选),讲清决定是什么、为什么要紧、有哪些选项、它推荐什么。你答完一个,它给下一个,直到没有。 + +**什么时候用。** 你离开了一会儿又回来,想快速知道刚才发生了什么,顺便把积压的决定清一遍。想看整支队伍当下的真实状态,用 `/bearings`。 + +**例子。** 输入 `/ahoy`。大概会看到:一段回顾,接着是「最需要你拍板的一个决定」,带上下文、选项和推荐。你回答之后,才会出现下一个。 + +**它不会自己做的事。** + +- 回顾部分只读对话里已经出现过的内容:不跑命令、不查队伍状态、不查 GitHub、不读写文件、不生成报告、不记录任何东西。所以「还在跑」只代表你上次看到的情况,不代表现在。 +- 如果对话经过压缩,上一条消息的位置找不到了,它会明说边界不清楚,只总结看得到的。 +- 不会悄悄变成 `/bearings`。唯一的例外:这是会话里你发的第一条真正的消息,这时它改走 `/bearings`,不会把回顾和 Bearings 混在一起。 +- 会话刚开、大副还没完成开工检查的话,它会先跑一次开工检查脚本,这一步通常早已完成。 + +依据:`README.md` 的「Built-in skills」,`.agents/skills/ahoy/SKILL.md`。 + +### `/bearings`:现状摘要 + +**做什么。** 从队伍当下的真实状态生成一份「接着上次往下做」的摘要,让你睡一觉、休息一阵或会话重置之后,一次读完就能接上。 + +**四种用法。** + +| 输入 | 得到什么 | +| --- | --- | +| `/bearings` | 只在对话里给一份四节摘要,不写任何文件 | +| `/bearings file` | 同样的摘要,另外把今天的详细报告 `data/status-report-<日期>.md` 从头重写一份,摘要里附上链接 | +| `/bearings lavish` | 同样的摘要,另外生成一块交互式的队伍看板,你可以直接在看板上答复「等你出手」的事,看板地址放在摘要里 | +| 以上任一个加 `include PRs` | 额外去查 GitHub 上 PR 的实时情况;不加就不查 | + +`file`、`lavish` 必须是你敲命令时写上的选项词。自然语言说「写个报告」「存成文件」「做个看板」,都不会触发它们。而要一份普通摘要,直接说「where did I leave off」「what's in the works」「morning brief」「status report」「catch-up」这类话也行,这是技能列出来的触发词;中文说法能不能触发,文档没写,稳妥就敲 `/bearings`。 + +**四节摘要。** 每次都完整给出这四节,没有内容的节也保留,写一句「没有」: + +| 节名 | 里面是什么 | +| --- | --- | +| `Captain's Call` | 只有需要你亲自处理的事:要你做的决定、等你批准或合并的 PR、需要你提供的凭据或登录、只有你能清除的阻塞 | +| `Recently Landed` | 最近完成的:已合并的 PR、调研任务(scout)完成、本地合入的活 | +| `Underway` | 正在自己往前走的活,每个船员一行当前状态 | +| `Charted Next` | 排在后面或在等条件的活(等别的任务、等某个日期),以及延后或搁置过久的决定、队伍记录的完整性警告 | + +**什么时候用。** 早上开工、过夜之后、会话重置之后、离席回来之后。 + +**例子。** 输入 `/bearings`,大概会看到四节,每一项一行,PR 全是完整链接。哪一节是空的,就是一句「没有」。如果「Captain's Call」是空的、而队伍里又有没查到的部分,它会说「没有记录到决定」并给出已查/总数,不会硬说「没事」。 + +**它不会自己做的事。** 这条命令只读。生成摘要的过程中,它不会拆除任务、不会合并 PR、不会派新活、不会指挥船员、不会替你回答决定、不会清理、不会改待办队列或任务状态。有哪些事该做,它会写在对应的那一节里,留给平时的流程和你的权限去办。只有这几处写入: + +- `file` 模式写那份报告。 +- `lavish` 模式生成看板,并登记看板的答复通道。 +- 刷新远程 FirstMate 目录账本的缓存。 +- 发现某个二副(secondmate)的自家记录前后矛盾时,记下一条「稍后通知它自己修」的请求,不会当场替它改。 + +**看板上的「Merge now」要当真。** 在 `lavish` 看板上点「Merge now」,就是你对那一个 PR 明确说了「合并」,大副不会再问第二遍。但它仍会重新核对:PR 还开着、CI 全部通过;红的或已经变了的,它拒绝并告诉你,不会硬合。只有答案恰好是 `merge` 才算数;你在答复里写了自由文字的,大副当成给它的指示去读、去判断,不会自动合并。看板上答「以后再说」,会被记成延后,不是关闭。 + +依据:`README.md` 的「Built-in skills」和「Bearings invocation examples」,`.agents/skills/bearings/SKILL.md`。 + +### `/stow`:把会话里的东西存下来 + +**做什么。** 一次完整的「重置前整理」,做四件事: + +1. **扫一遍会话。** 找出只存在于对话里、值得长期保留的东西:你随口说的偏好、操作上的经验、已经定下来的决定、还没做的下一步。 +2. **各归各处。** 你的偏好和工作习惯进 `data/captain.md`;本机的操作经验进 `data/learnings.md`;单个任务的笔记写进那张工单;调研发现留在调研报告里。项目自己的 `AGENTS.md` 它不会写,要放在 `data/learnings.md` 或者回执里提出来,由你自己去加。 +3. **补记工作记录。** 把这个会话知道、但还没记下来的开放事项补进记录,把它知道已经过时的记录改正。范围只限这个会话手里掌握的事。 +4. **整理启动记忆。** 对 `data/captain.md`、`data/captain-shared.md`、`data/learnings.md` 按本机的预算整理:过期的条目归档,不删除;预算还不够,再把「只在特定场合才需要」的内容迁到用到时才加载的地方,比如只存在本机、不进 git 的本地技能。每次 `/stow` 都会做完这一整遍,哪怕这次会话没学到新东西。 + +在主 FirstMate 目录里打 `/stow`,做完自己的,会自动再让每个二副各自整理一遍,每个目录按各自的预算算,不合在一起算。在二副自己的目录里打,只整理自己。 + +**什么时候用。** 要重置会话或上下文要被压缩之前,要长时间离开之前,或者隔一阵定期做一次,让大副的启动记忆保持准确。 + +**例子。** 输入 `/stow`。做完你会收到一份回执(completion receipt),大概包含:启动记忆的预算以及整理前后的估算大小;三个记忆文件各自做了什么(不变 / 新增 / 改写 / 精简 / 转交 / 归档 / 提议迁出);归档了哪些、为什么;补记或改正了哪些工作记录;如果有二副,每个二副一条;最后,只有在所有东西都记好、没有遗留问题、都在预算之内时,才会说「可以安全重置」。 + +**「可以安全重置」是什么意思。** 它只表示:这个会话里知道的东西没有丢。它不表示大副所有的记录都是对的,因为这条命令没有检查那些会话没提到的记录。 + +**它不会自己做的事。** + +- 不会拿待办队列去对照仓库或 PR 的实际情况(不做对账)。它只处理这个会话手里的事。 +- 不会往你的项目的 `AGENTS.md` 里加东西。 +- 不会创建或改写 FirstMate 仓库里跟踪的技能。它只会写只存在本机、不进 git 的本地技能:省预算时,它可以不问你,把普通条目迁进已经存在的本地技能;新建本地技能,只为放你逐条同意迁出的「固定」(pinned)条目,见下一条。 +- 不会直接删掉一条唯一的过期事实,只归档,保留出处,之后能找回。 +- 标记为「固定」的条目,不会自动迁出,只会提议;要你逐条明确同意才迁。你不答复,就什么都不动,也不算已经省下预算。 +- 远程二副如果当前没有活着的 agent,它没有办法替那个目录整理,会把这件事当作遗留问题报告,不会擅自重启那个二副。 +- 通用于所有 FirstMate 用户的经验,要走正常的分支、质检流水线、PR 流程才能进共享仓库,而且只有你的目录有向上游发布的权限时才行。没有的话,它留在 `data/learnings.md`,或留一份本地草稿,由你自己决定要不要带到上游。 + +**另外一个 `stow`。** `skills/stow/` 下还有一份对外安装用的同名技能,是给任何项目用的,和这里讲的大副内部版互相独立,见第二部分。 + +依据:`README.md` 的「Built-in skills」,`.agents/skills/stow/SKILL.md`,`AGENTS.md` 第 6 节,`docs/architecture.md` 的「Operational memory routing」,`docs/configuration.md` 里关于启动记忆预算和 `config/stow-pass-horizon` 的几节。 + +### `/updatefirstmate`:更新 FirstMate + +**做什么。** 把正在运行的大副和所有二副更新到上游(origin)的最新版本,更新方式是快进(fast-forward)。更新完,如果大副自己的指令变了,它重读一遍 `AGENTS.md`;然后把每个活着的二副重启一遍,让它们真正用上新指令。已经是最新的二副也会重启,因为启动时才确定的那些接线,光看文件差异看不出有没有变。 + +**什么时候用。** 想拿到上游新合入的技能、脚本、规则。也可以直接说「update firstmate」或「pull the latest firstmate」。 + +**例子。** 输入 `/updatefirstmate`。大副跑更新脚本,逐个目标报一行:`updated`(已更新)/ `reconciled redundant divergence`(本地内容已经包含在上游里,所以放心对齐)/ `already current`(本来就是最新)/ `skipped`(跳过,带原因)。然后重读、重启,最后用一句话告诉你结果,比如「大副和两个二副都已经更新到最新」。如果有哪个二副只收到了「请重读」的提醒、没能真正重启,它会明说,不会把这种情况说成已经重新加载。 + +**它不会自己做的事。** + +- 不强制:不会强推、不建合并提交、不暂存(stash)。 +- 本地有改动(dirty)、和上游分叉、离线、不在默认分支的目标,一律跳过并告诉你,原样留着。真正分叉的,会留一条持久的记录,之后每次开工检查和更新都会再提醒,直到对齐。 +- 只动 FirstMate 仓库和它自己的工作树,不碰 `projects/` 下你的项目。 +- 不会拆掉任何东西。重启一个二副之前,先请它把只存在于对话里的未登记工作写下来,等它自己回复了才重启;它的船员继续在各自的会话窗口里跑。重启不需要你逐个确认。 +- 它是从上游拉取,不是向上游发布,所以不受「是否有向上游发布权限」的限制。 + +**要知道的限制。** 技能原文承认:运行中的 agent 加载过的 `AGENTS.md` 和技能是固定的,没有哪个 harness 提供热重载。技能没有给主会话安排重启,只让它在 `AGENTS.md` 变了的时候重读。原文说,重读只是再追加一份指令,碰不到已经加载的技能,所以主会话里已加载的技能不会因为这次更新而换新。 + +依据:`README.md` 的「Built-in skills」,`.agents/skills/updatefirstmate/SKILL.md`,`AGENTS.md` 第 12 节,`docs/architecture.md` 的「Self-updates stay safe」。 + +### `/calm`:安静显示 + +**做什么。** 一个开关。打开后,转录里一部分显示上的杂项被隐藏:折叠的思考标签、工具调用外壳、一部分大副内部的消息行、过程中的短旁白;工作中的「Working...」换成一艘小帆船的动画。再打一次关闭。选择按 FirstMate 目录保存,默认关闭,下次开会话还是你上次选的。 + +**哪些 harness 上有。** Pi 上完整支持。Claude Code 上需要先设环境变量 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`(早期功能,默认关闭)。没有这个变量,`/calm` 这个命令根本不存在,FirstMate 也从不替你设置。README 和文档只提到这两个 harness,其他 harness 上有没有,没有写。 + +**什么时候用。** 你觉得转录里工具调用的杂项太多,想要一个更安静的界面。 + +**例子。** 在 Pi 里输入 `/calm`,之后工作中的那一行变成小帆船。在 Claude Code 里,输入后输入框下面会短暂出现「Calm on」或「Calm off」的提示。 + +**它不会自己做的事。** + +- 只改显示。模型实际收到的内容、消息的送达与顺序、权限、存储、导出,都不变;被隐藏的内容仍然在。 +- 有实质内容的话不会被藏:夹在工具调用之间的助手文字,只要带换行或者长度达到 240 个字符,就会保留。 +- 写不进偏好文件时,保持原来的选择,并告诉你没存成。 +- Pi 上有些行仍然看得到(比如展开的推理、用户直接运行 bash 的行),这是 Pi 提供的显示接口的限制,不是漏藏。 + +依据:`README.md` 的 `/calm` 一段,`docs/calm.md`,`docs/configuration.md` 的「Calm preference」。 + +### `/supervision-model`:给监督选模型(只有 Pi) + +**做什么。** 在 Pi 上,打开两个选择器:先选监督分支用哪个模型(第一项是「Follow main」,也就是跟着你对话用的模型走),再选推理强度。 + +**什么时候用。** 监督是比你自己对话更简单的活,想让它用更便宜的模型和更浅的推理强度。不设的话,监督分支通常跟着你对话的模型和强度走。 + +**例子。** 输入 `/supervision-model`,选一个模型,再选强度,命令最后会告诉你两项实际会按什么生效。 + +**它不会自己做的事。** 只改监督分支,不改你自己对话用的模型和强度。取消模型选择,两项都不改;只取消强度选择,强度保持原样,模型选择照常生效。选择按 FirstMate 目录保存,不会传给二副,二副要在自己的目录里自己设。 + +依据:`README.md` 里关于 `/supervision-model` 的一段,`docs/configuration.md` 的「Pi supervision branch model and effort」。 + +## 二、技能 + +### 你能调用的技能(6 个) + +它们都在 `.agents/skills/<名字>/SKILL.md`,写着 `user-invocable: true`。 + +| 技能 | 对应命令 | 管什么 | +| --- | --- | --- | +| `afk` | `/afk` | 进入和退出离席模式 | +| `quiet` | `/quiet` | 在场时的静默模式 | +| `ahoy` | `/ahoy` | 回顾对话并逐个带你过悬着的决定 | +| `bearings` | `/bearings` | 队伍现状摘要、报告文件、交互看板 | +| `stow` | `/stow` | 存会话知识、补记工作记录、整理启动记忆 | +| `updatefirstmate` | `/updatefirstmate` | 更新大副和二副 | + +这 6 个技能的 frontmatter 里都写着 `metadata.internal: true`。这个标记的作用是让 `npx skills add` 这类安装工具看不到它们,因为它们都假设你有一个正在运行的 FirstMate 目录,装到别处没有意义,甚至会误导。对大副自己怎么加载没有影响。 + +### 另一个 `stow`:可以装到任何项目里的版本 + +`skills/` 目录放的是对外的、可以单独安装到任何项目的技能,不依赖 FirstMate 的路径、工具和术语。现在里面只有一个:`skills/stow`。它和大副内部的 `stow` 同名,但是两份独立的文件,没有共用代码,大副自己不加载它。 + +它做的是同类的事:扫一遍对话,找出该长期保留的东西,按下面的优先级决定存到哪里: + +1. 你明确指定的地方优先。要存到外部系统(比如 issue 跟踪器),只有这一条路;仅仅因为项目配了 git 远端,不会推断出去,也不会往那里写。 +2. 项目里本来就有的约定:`CLAUDE.md`、`AGENTS.md`,或者已有的 `TODO`、`BACKLOG`、`NOTES` 文件。 +3. 都没有,就用当前目录下的 `.stow-notes.md`,并把它加进该目录的 `.gitignore`。 + +两个约定都合适时,它问你一次,再征得同意后把选择记下来。它也有条目分级、过期归档和「安全结束」的结论。它不会往技能里存东西;除非你明确指定,也不会往外部系统写。 + +依据:`README.md` 的「Two-tier skill layout」,`skills/stow/SKILL.md`。 + +### 大副专用的技能(你不调用) + +下面这些技能,frontmatter 里写的是 `user-invocable: false`,不是给你敲的。大副走到对应的场合,自己加载它们。你不会在命令列表里看到它们,只会在大副的行为里看到效果。`agent-skill-trigger-index` 是它们的触发条件总表。 + +**开工与恢复** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `operational-home-layout` | 要找、读或改 FirstMate 目录、配置、数据、状态、项目路径时 | +| `session-start-recovery` | 开工检查报告了没做完的检查、可操作的诊断,或者输出需要解读时 | +| `bootstrap-diagnostics` | 开工检查的启动或网络检查部分打出了可操作的诊断行(`MISSING`、`NEEDS_GH_AUTH`、`FLEET_SYNC` 之类)时 | +| `stuck-crewmate-recovery` | 船员的会话窗口死了、卡住、一直打转、没回应,或者船员说质检流水线挂了、连不上、超时时 | + +**派活、质检和交付** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `project-management` | 添加、创建、克隆、移除、初始化项目,以及交付方式、自主程度、对外同意的决定 | +| `harness-adapters` | 要派出或恢复船员 / 二副、处理信任对话框、给特定 harness 发技能调用、中断或退出 agent 时;记录着各个 harness 的验证过的事实 | +| `quota-array-dispatch` | 一条派工规则匹配到多个候选配置时,按额度和优先级挑一个 | +| `firstmate-orca` | 切换到 Orca 运行时后端、派出或监督 Orca 上的活、排查 Orca 任务状态时 | +| `validation-supervision` | 一个交付任务开始跑质检流水线,或流水线正在跑、中途改了要求或出了问题;回答 ask-user 类问题之前 | +| `ask-user-authority` | 决定怎么处理 ask-user 类问题之前;它是这类决定的唯一依据:明确符合已确认设计的,大副自己判断;真正含糊、扩大范围或有破坏性的,才来问你 | +| `ship-landing` | 交付任务报告了 PR 或可合入的分支、判断或监控怎么合入、做收尾清理之前 | +| `scout-completion` | 调研任务报告完成、拿出一份要反复修改的可视成果,或考虑把它转成交付任务时 | +| `captain-hold-lifecycle` | 把一次调研或评审当作完成之前,以及记录、转交你的答复时;保证没有答复的问题不会在收尾时丢掉 | +| `decision-hold-lifecycle` | 只是个转指:旧简报里提到「决定」时,让大副改去加载 `captain-hold-lifecycle`。准备下一个版本移除 | +| `diagnostic-reasoning` | 对已报告的 bug 划定范围之前,以及采信一份诊断报告之前;规定要先按用户的实际操作复现 | + +**监督与二副** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `secondmate-provisioning` | 创建、预置、验证、启动、交接待办、恢复、退役二副,以及改 `data/secondmates.md` 之前 | +| `away-quiet-supervision` | 只要 `/afk` 或 `/quiet` 被用到、存在离席或静默的记录,或收到监督机制发来的带标记消息,就会同时加载;是前两者共享的安全规则 | +| `process-event-sources` | 登记一个由大副持有的长轮询事件源、登记「某条件成立就做某事」的监视,或收到相应的事件源唤醒时(`/bearings lavish` 看板的答复也走这条路) | + +**Relay 与外部工具** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `fmx-respond` | 只在 Relay 打开时才会加载:处理 Relay 的提及和后续回复,以及发出对公开提及的最终答复 | +| `firstmate-codexapp` | 要协调可见的 Codex Desktop 线程、评估「让 Codex App 成为 FirstMate 原生后端」的请求时 | + +**改 FirstMate 自己** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `firstmate-self-repo` | 任务的目标是 FirstMate 仓库本身,或者任何 push、PR、issue、评论、fork 可能到达 FirstMate 上游之前;划定能不能对外发布的边界 | +| `firstmate-coding-guidelines` | 要改 FirstMate 共享的、被 git 追踪的内容之前,大副自己改或交给船员改都一样 | + +**索引** + +| 技能 | 管什么,什么时候用上 | +| --- | --- | +| `agent-skill-trigger-index` | 只在审计或维护这份「大副专用技能触发总表」时才加载 | + +依据:`.agents/skills/agent-skill-trigger-index/SKILL.md`,以及各技能 `SKILL.md` 开头的 `name` 和 `description`。`AGENTS.md` 第 13 节说明:技能的描述就是常驻的触发索引,大副只在描述写明的触发场合加载专用技能。 + +## 三、本页没有覆盖的 + +- **`.agents/skills/firstmate-calm`**:这是指向 `.claude/mods/firstmate-calm` 的链接,是 Claude Code 上 `/calm` 的实现,不是单独的技能。行为已经写在 `/calm` 一节里。 +- **其他斜杠命令**:README 和文档里没有当作船长命令来讲的,一律没有收录。 +- **脚本的详细参数**:`bin/` 下各脚本的选项(比如 `bin/fm-afk-launch.sh` 的 `--expected-return`、`--spend`)是大副用的,本页只在影响你时才提。要看细节,读脚本开头的注释或 `--help`。 +- **各 harness 上的差别**:不同 harness 在监督机制、重启方式上有差别,这里只讲对你有影响的部分。想看细节,读第 10、11 章和 `docs/` 下对应的后端文档。 + +## 来源 + +以下路径都是 FirstMate 仓库里的文件: + +- `README.md`:「Built-in skills」、「Two-tier skill layout」、`/calm` 和 `/supervision-model` 的说明 +- `AGENTS.md`:第 6 节、第 8 节「Away-mode and quiet-mode stub」、第 12 节、第 13 节 +- `.agents/skills/afk/`、`quiet/`、`ahoy/`、`bearings/`、`stow/`、`updatefirstmate/`、`away-quiet-supervision/`、`agent-skill-trigger-index/` 的 `SKILL.md`,其余技能的 `SKILL.md` 开头的 `name` 和 `description` +- `skills/stow/SKILL.md` +- `docs/calm.md`、`docs/configuration.md`、`docs/architecture.md`、`docs/supervision-host.md` +- `bin/fm-afk-launch.sh` 开头的注释