Firstmate 的 Model 与 Effort 双轴契约：harness 适配层的选择、优先级与记录机制

导读

本文解读 firstmate 仓库中 harness 适配层（harness-adapters）的公共参考文档 model-and-effort.md，它定义了 crewmate / secondmate 启动时--model与--effort两个轴从"自然语言规则"到"具体 CLI 参数"的全部契约：包括优先级链、六档 effort 词汇表、ultra原生契约、record-and-omit 兜底策略，以及 harness 身份与模型 provider 的严格区分。读完本文，你将掌握 firstmate 是如何在fm-spawn.sh、fm-harness.sh与任务元数据之间完成模型/推理强度决策的，并能对照源码与测试用例验证每个环节。

双轴模型：从自然语言规则到具体 CLI 参数

在 firstmate 的架构里，自然语言的分派规则归 firstmate 自己判断，而脚本只接收"具体轴值"（concrete axes）。bin/fm-spawn.sh在入口处接受三种具体参数：

fm-spawn.sh <task-id> <project-dir> --harness <name|harness|launch-command> \ --model <name> --effort <level> [--backend <name>]

• --harness：显式的 per-spawn harness/profile 适配器；
• --model：具体模型名（如xai/grok-4.5-*、codex-native/<model>）；
• --effort：具体推理强度级别，取值被严格限定为low | medium | high | xhigh | max | ultra（fm-spawn.sh 中的校验错误信息原文：--effort must be one of low, medium, high, xhigh, max, ultra）。

参数解析位于 fm-spawn.sh，支持--effort <level>与--effort=<level>两种写法。脚本从不解析自然语言分派规则——规则匹配是 firstmate 的判断职责，脚本只消费已经选定的具体值。这也解释了为什么.agents/skills/harness-adapters/references/common/model-and-effort.md开头就要求"在选定、校验或变更任一轴之前，先加载所选工具参考"：工具参考（tool reference）记录的是已验证的 flag、可接受值、省略行为与发现方式（discovery），是双轴决策的事实底座。

Effort 优先级链：每任务指令 > 分派配置/固定值 > 回退值

文档给出了明确的 effort 优先级（effort precedence），三层自上而下：

1. per-task captain instruction（每任务船长指令）：最高优先级，本次分派内有效；
2. applicable dispatch profile 或 secondmate pin：即 crew-dispatch.json 中命中规则的 profile 中声明的effort，或config/secondmate-harness中的 effort token（其行格式为<harness> [<model>] [<effort>]，见 configuration.md）；
3. fallback（回退值）：仅当前两者都没有指定 effort 时才启用。

契约要求：绝不替换更高优先级的取值，回退值只在两者均未指定时使用。这条规则在 dispatch.md 中有更完整的表述：config/crew-dispatch.json可用具体 harness/model/effort 轴覆盖静态默认；当 opt-in 的bin/fm-dispatch-resolve.sh开启时，其clear答案直接给出具体轴值。

Effort 六档词汇与回退选择指南

回退值的选择不是随意的，文档给出了明确的语义：

• low：用于理解充分（well-understood）、路径明确有界（explicit bounded path）的工作；
• xhigh：用于模糊调查（ambiguous investigation）或设计类任务；
• 中间级别：随复杂度（complexity）、不确定性（uncertainty）、影响半径（blast radius）或开放式推理（open-ended reasoning）上升而逐级选择。

两条红线：

• cap 而非静默省略：如果适配器不支持xhigh，应封顶到其支持的最高非max级别，而不是把意图静默丢弃；
• max永远不允许通过回退值选择：只有显式的 per-task 或 standing captain 偏好才允许max。

从源码看，这个"封顶"动作体现在 fm-spawn.sh 的effort_flag_for_harness：grok 只接受low|medium|high（--reasoning-effort），因此xhigh/max被省略而非传入已知坏值；agy 1.2.0 的--effort同样只接受low|medium|high。注意源码注释（fm-spawn.sh）特别说明：grok 同时暴露--effort与--reasoning-effort，而 firstmate 的 profile 轴对应的是推理旋钮，且 grok 0.2.99 起--reasoning-effort明确拒绝xhigh与max。

ultra原生契约：模型范围的拒绝校验

ultra是共享词汇表中的显式原生（native）值，它不走普通映射路径，而是受"模型范围拒绝契约"（model-scoped refusal contract）约束——由bin/fm-harness.sh validate-native-effort独占：

fm-harness.sh validate-native-effort <harness> <model> <effort>

对应实现位于 fm-harness.sh：当effort=ultra时，只有harness为pi或pi-signed且model显式形如codex-native/<model>才放行；否则直接报错：

error: ultra effort requires pi or pi-signed with an explicit codex-native/<model> model

配套的发射逻辑在 fm-spawn.sh：Pi / Pi-signed 收到ultra后发射的是--codex-effort ultra，而不是--thinking ultra——ultra属于 native Codex 会话的扩展 flag，与 Pi 自身的 thinking 级别（low|medium|high|xhigh|max经--thinking发射）严格分离。这一点在 pi.md 工具参考 中也有记录："Native Codex sessions may requestultrathrough the native extension flag... it is separate from Pi's thinking levels."

实测证据见 tests/fm-pi-codex-native.test.sh：模拟的model/listRPC 返回模型gpt-6-astra，其supportedReasoningEfforts为['high','ultra']，而启动参数在非 resume 场景下显式 push--codex-effort ultra（同文件 L181）。

Record-and-omit：不支持的值绝不传参，但绝不丢迹

这是双轴契约中最能体现"保成功"哲学的机制：

• 若请求的 effort 超出所选适配器的可接受集合，spawn记录effort=<请求值>到任务元数据，但不发射任何 effort flag；
• 没有已验证交互式 effort flag 的 harness（如 rovo 的run无--effort、Devin 的 effort 属于 model id）走同一个 record-and-omit 契约（fm-spawn.sh）；
• 目的：保留启动成功（preserve launch success），而不是把已知坏值（known-bad value）传给 CLI。

元数据落点在state/<id>.meta，格式为effort=<值>（fm-spawn.sh），与harness=、model=并列，供恢复（recovery）与控制操作读取——这正呼应了 SKILL.md 的恢复规则："使用state/<id>.meta中精确的harness=，绝不要从模型或 provider 推断它"。

端口回归测试可直接复用：tests/fm-agy-harness.test.sh 的test_agy_effort_xhigh_is_recorded_but_omitted验证了完整闭环：

• 用--model gemini-3.8-flash-low --effort xhigh启动 agy，spawn 仍应成功（exit 0）；
• 捕获的 launch.log不得包含--effort（已知坏值未被传出）；
• 而state/<id>.meta中必须保留effort=xhigh（轴值未丢失）。

同文件的 test_agy_launch_carries_the_brief_with_model_effort_and_autonomy 则验证了支持路径：low被原样发射为--effort 'low'，且model=与effort=low同时进入 meta。

Harness 身份与 Provider 独立：名字不可互相推断

文档用两个反例确立了一条关键原则——harness 身份独立于模型 provider：

• harness=pi+model=xai/grok-*：这是Pi 使用 xAI 的模型，不是独立版 Grok Build，也不需要 Grok CLI 登录；
• harness=cursor+model=cursor-grok-4.5-*：这是Cursor 路由 Grok 模型，而不是harness=grok。

任何脚本都不会替你解析凭据来源（credential provenance）。正确做法是从工具的发现面（discovery surface）与quota-axi auth --json的逐 provider 来源建立事实，并展示推理过程，而不是从名字推断。这一契约的工程后果在恢复场景中尤其致命：SKILL.md 明确要求恢复与控制操作使用state/<id>.meta中记录的精确harness=，绝不从模型或 provider 推断——因为模型名完全可能跨 provider 路由。

Discovery：把模型知识当"当前发现"，而非永久命名空间

文档要求把模型与 provider 知识视作当前发现（current discovery），而非永久命名空间或固定映射。原因是可用性随版本、账户、配置变化，因此要以所选工具参考在当前认证环境下的权威面（authoritative surface）为准。

对不熟悉的命名空间（unfamiliar namespace），建立支持与 provider 身份的唯一途径是：

1. 该 harness 的 CLI help（如--help）；
2. 模型列表（model listing，如 Pi 的<executable> --list-models [search]、agy 的agy models、omp 的omp models --json、Cursor 的--list-models）；
3. 当前版本文档。

同时，文档定义了两种结果的严格语义：

• 账户可达的列表遗漏了某模型= 具体的（concrete）不支持证据：阻止该候选并引用（quote）列表证据。对应源码行为见 fm-spawn.sh（omp 模型不在omp models --json中则拒绝）与 L2419（Cursor 模型不在--list-models中则拒绝）；
• 不可达的列表不建立任何结论：此时报告不确定性（uncertainty）而非定论。同样有源码对应：agy 的models命令超时或不可达时，spawn 以--model未校验状态继续并打印 notice（fm-spawn.sh）。

这两条语义其实是一对互补的容错设计：可达且缺失 = 拒绝，不可达 = 不确定，绝不允许用"列表没响应"当作"模型不存在"的判决。

与 dispatch 参考的衔接：Profile 数组回到 quota-array-dispatch

文档末尾给出了一条流程约束：对于命中的 profile 数组（matched profile array），只有在建立了每个候选的 harness 支持、provider 关系与不确定性之后，才回到quota-array-dispatch做配额感知的最终选择。

这对应 SKILL.md 的路由矩阵（.agents/skills/harness-adapters/SKILL.md）中model-effort操作的两个场景：

即：仅做轴选择时加载双轴参考；涉及已配置 profile 的优先级（configured profile precedence）时，再叠加 dispatch 参考。而 dispatch.md 进一步解释了 inheritance 语义：secondmate 的 worker 会收到字面的config/crew-harness与config/crew-dispatch.json（分派配置被继承），但 primary-only 的config/secondmate-harness从不被继承——secondmate 不会再派发 secondmate。具体值（如codex）会带入 secondmate home；unset/default则不带具体值，其 worker 使用该 home 自身或检测到的 harness。

源码纵深：各 harness 的 effort 映射全景表

将文档的"cap / omit"契约落到 effort_flag_for_harness 的实现，可以得到一张完整的映射表（全部行为均有源码注释佐证，版本号为注释中记录的被验证版本）：

这张表正是"cap / omit / record-and-omit"三种策略的完整集合：cap（muse 的 max→ultra、codex 的 max 限定模型）、omit（grok/agy 的 xhigh、max）、以及纯record（kimi、devin 与一切无 effort flag 的 harness）。

小结

model-and-effort.md虽然短小，却是 firstmate harness 适配层最核心的"双轴契约"：它界定了脚本与自然语言规则的边界、effort 的优先级链与回退语义、ultra的原生拒绝模型、record-and-omit 的保成功哲学，以及 harness 身份与 provider 的严格分离。所有契约都能在 fm-spawn.sh 的参数解析与 flag 映射、fm-harness.sh 的validate-native-effort、以及 fm-agy-harness.test.sh 与 fm-pi-codex-native.test.sh 的回归测试中找到一一对应的实现与验证。理解这套契约，等于掌握了 firstmate 如何在不传坏参、不丢信息、不越权推断的前提下，把"哪个模型、多大推理强度"这个决策安全地下放到每一次 crewmate / secondmate 启动。