@fanglinwei/agent-fit 0.7.4 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/usage.md CHANGED
@@ -1,28 +1,22 @@
1
1
  # 使用说明
2
2
 
3
- `agent-fit` 0.7.4,npm 包名为 `@fanglinwei/agent-fit`,命令和 Skill 名仍为 `agent-fit`。首版支持 Codex;Node.js 22+。命令、网页和生成的 Skill 使用同一套档位数据。
3
+ `agent-fit` 0.9.0,npm 包名为 `@fanglinwei/agent-fit`,命令和 Skill 名仍为 `agent-fit`。首版支持 Codex;Node.js 22+。命令、网页和生成的 Skill 使用同一套档位数据。
4
4
 
5
5
  工具只处理当前格式与版本的配置;独立 home 全程使用显式指定的路径。
6
6
 
7
7
  ## 安装与配置
8
8
 
9
- 从 GitHub v0.7.4 Release 下载发行包,或在项目目录运行 `npm pack` 后使用 `npm install -g ./fanglinwei-agent-fit-0.7.4.tgz` 安装。npm registry 获取的是该渠道当前已发布版本;两种方式都需要 Node/npm。本版按全新安装处理,不增加旧配置兼容。已有其他版本配置时,先保留所需自定义方案,用原版本 CLI 对原绑定 home 预览并实际 restore,之后再安装新版并 setup;不自动迁移旧档位或恢复记录。
9
+ 从 GitHub v0.9.0 Release 下载发行包,或在项目目录运行 `npm pack` 后使用 `npm install -g ./fanglinwei-agent-fit-0.9.0.tgz` 安装。npm registry 获取的是该渠道当前已发布版本;两种方式都需要 Node/npm。本版按全新安装处理,不增加旧配置兼容。已有其他版本配置时,先保留所需自定义方案,用原版本 CLI 对原绑定 home 预览并实际 restore,之后再安装新版并 setup;不自动迁移旧档位或恢复记录。
10
10
 
11
11
  ```sh
12
- npm install -g @fanglinwei/agent-fit
12
+ npm install -g ./fanglinwei-agent-fit-0.9.0.tgz
13
13
  agent-fit setup --mode official --dry-run
14
14
  agent-fit setup --mode official
15
15
  ```
16
16
 
17
- 一行安装并配置:
18
-
19
- ```sh
20
- npm install -g @fanglinwei/agent-fit && agent-fit setup --mode official
21
- ```
22
-
23
17
  目标目录优先级为 `--codex-home PATH`、`CODEX_HOME`、用户 `~/.codex`。空格路径需要 shell 引号。命令不会设置主代理模型、全局子代理默认、供应商、审批、沙箱、并发或子代理启用开关。
24
18
 
25
- Skill 名称为 `agent-fit`,调用为 `$agent-fit`,默认安装目录为 `~/.agents/skills/agent-fit/`。npm 安装命令获取已发布版本;当前内测开发代码通过 `npm pack` 构建本地包。
19
+ Skill 调用为 `$agent-fit`,默认目录为 `~/.agents/skills/agent-fit/`。
26
20
 
27
21
  首次 setup 默认官方(official);同版本重复 setup 保留当前选择与首次恢复基线。npm 安装没有 postinstall 配置动作。`--dry-run` 不创建目标 home、锁或状态文件。
28
22
 
@@ -78,10 +72,6 @@ Git 目录解析到当前 worktree 根,子目录共用,不同 worktree 独
78
72
 
79
73
  作用域 explain 返回完整 `task_profile`、`configuration_revision`、`context`、`effective_scope`,以及 `task_delegate` 派发建议。主代理保存任务快照,后续重试、升级与备用沿用该完整档位;新任务重新查询。显式传 model/effort,当前宿主使用 `fork_turns="none"` 并完整交接职责与上下文。切换不会改变运行中的子代理,也不重置三次委派上限。
80
74
 
81
- 首次安装、更新基础 Skill、AGENTS 或角色职责内容,以及恢复原配置后需要重启。普通全局、项目和会话切档、当前自定义档位的模型/effort 调整、重复设置无需重启。若同一次操作还部署了基础规则更新,则仍提示重启。
82
-
83
- 本机 Codex 0.162.1 已验证:同一进程、同一会话的下一轮可重新加载全局角色模型和 effort 绑定,无需重启;项目与会话选择供后续新任务查询。已开始任务沿用原快照。该证据证明宿主配置加载,不等于真实云端子代理模型身份已验证;实际模型身份仍需可信宿主 metadata 核验。
84
-
85
75
  ## 命令表
86
76
 
87
77
  默认智能体为 Codex;省略 `--agent` 与显式指定 `--agent codex` 等价。业务命令支持 `--codex-home PATH`。除 serve 外都支持 `--json`;写命令支持 `--dry-run` 和 `--expect-revision REV`。
@@ -117,16 +107,21 @@ L1–L4 保留为推理复杂度;在最终等级内通过 `--task` 选择模
117
107
 
118
108
  | 类型 | 等级 | cut / official 主候选 |
119
109
  | --- | --- | --- |
120
- | `mechanical`:确定性机械任务 | L1 | Luna / medium |
121
- | `bounded`:普通有界任务 | L2 | Luna / high |
122
- | `scan`:大型有界扫描或审查 | L1/L2 | Luna / xhigh |
123
- | `deep`:大型确定性深度处理 | L1/L2 | Luna / max |
124
- | `complex`:有界复杂任务 | L2/L3 | Sol / medium |
125
- | `uncertain`:高歧义、高耦合或高后果且难验收 | L3/L4 | Astra / low |
126
- | `reasoning`:复杂推理或已证实推理不足 | L3/L4 | Astra / medium |
127
- | `latency`:明确追求低延迟 | 任意等级 | 须显式配置;不自动启用 Terra |
128
-
129
- 这些是待校准的本地策略,不代表已经验证模型能力或延迟。普通自动 Astra 路由默认 low,复杂推理或有证据的质量升级最多 medium;更高强度需要明确授权。**用户明确选择 high/fire 即授权其展示的最高强度,包含 Astra/ultra**;预览或保存不构成选择,预算、宿主支持和 fire 会话验证继续适用。已选择的自定义档位执行明确保存的组合。
110
+ | `mechanical`:确定性机械任务 | L1 | 经济用途 / medium |
111
+ | `bounded`:普通有界任务 | L2 | 经济用途 / high |
112
+ | `scan`:大型有界扫描或审查 | L1/L2 | 经济用途 / xhigh |
113
+ | `deep`:大型确定性深度处理 | L1/L2 | 经济用途 / max |
114
+ | `complex`:有界复杂任务 | L2/L3 | 通用用途 / medium |
115
+ | `uncertain`:高歧义、高耦合或高后果且难验收 | L3/L4 | 旗舰用途 / low |
116
+ | `reasoning`:复杂推理或已证实推理不足 | L3/L4 | 旗舰用途 / medium |
117
+ | `visual`:视觉理解与图像推理 | L1/L2/L3 | 专长用途 / low、medium、high |
118
+ | `computer`:有界电脑操作 | L1/L2/L3 | 专长用途 / low、medium、high |
119
+ | `writing`:自然写作与修订 | L1/L2/L3 | 专长用途 / low、medium、high |
120
+ | `latency`:明确追求低延迟 | 任意等级 | 须显式配置,不保证实际延迟 |
121
+
122
+ 这些是待校准的本地策略,不代表已经验证模型能力或延迟。普通旗舰候选默认 low,复杂推理或有证据的质量升级最多 medium;更高强度需要明确授权。**用户明确选择 high/fire 即授权其展示的高强度组合**;预览或保存不构成选择,预算、宿主支持和 fire 会话验证继续适用。已选择的自定义档位执行明确保存的组合。
123
+
124
+ 先判断等级,再核对组合的工具、输入、上下文与验收能力。无法明确匹配任务候选时使用本级基线,仍需能力检查;候选适用依据与 L2/L3 complex 的边界见 [任务路由](../adapters/codex/skills/agent-fit/references/task-routing.md#基线与候选的选择边界)。同一组合改标签不构成质量升级,也不存在固定的跨模型升级顺序。
130
125
 
131
126
  ```sh
132
127
  agent-fit explain --level L1 --task mechanical --role task_execute --json
@@ -135,13 +130,13 @@ agent-fit explain --level L3 --task uncertain --role task_scan --json
135
130
  agent-fit explain --level L3 --task reasoning --role task_execute --json
136
131
  ```
137
132
 
138
- 聊天仍须使用会话作用域及目标项目、线程上下文。`--task` 只查表,不自动分类、切档或发模型请求;不传时返回原等级基线。类型与等级不匹配会被拒绝;明确请求但快照未配置时返回 `TASK_ROUTE_NOT_CONFIGURED`,不能借用包内新值或自行拼组合。旧安装尚无候选时,预览并更新基础配置后再查询;本次基础 Skill 更新部署后仍需重启一次。
133
+ 聊天仍须使用会话作用域及目标项目、线程上下文。`--task` 只查表,不自动分类、切档或发模型请求;不传时返回原等级基线。类型与等级不匹配会被拒绝;明确请求但快照未配置时返回 `TASK_ROUTE_NOT_CONFIGURED`,不能借用包内新值或自行拼组合。已部署快照缺少候选时,先预览并更新配置再查询;基础规则更新后需重启。
139
134
 
140
- 每级可选 `tasks`,键为上表类型,每项完整包含 `model`、`effort`、`fallback`(可为 null)。复制档位、三层作用域和任务快照均保留候选;单级 CLI 配置只改基线,候选通过整表 JSON 或网页“任务候选 JSON”编辑,`{}` 清空本级候选。例如 L1 的 `tasks.latency` 可保存用户明确提供的 Terra 模型 ID、high 及适当备用;必须满足原能力要求,不能凭模型名承诺低延迟。
135
+ 每级可选 `tasks`,键为上表类型,每项完整包含 `model`、`effort`、`fallback`(可为 null)。复制档位、三层作用域和任务快照均保留候选;单级 CLI 配置只改基线,候选通过整表 JSON 或网页“任务候选 JSON”编辑,`{}` 清空本级候选。三个专长候选各带有通用备用组合;latency 仍须独立显式配置,不能凭模型名承诺低延迟。
141
136
 
142
137
  三个作用域的复制内容均与同一作用域下 `mode show <源档位>` 显示的完整定义一致。源档位对应已部署快照时复制该快照;旧快照没有的候选不会因复制而自动加入。
143
138
 
144
- 候选使用自己的备用。质量升级可以在原 L3/L4 中由 uncertain 的 Astra/low 转向 reasoning 的 Astra/medium;先证实推理不足,继续沿用原快照、职责与验收,计入同一任务最多三次委派。不能用故障备用代替质量升级,也不自动转到更高强度。
139
+ 候选使用自己的备用。质量升级可以在原 L3/L4 中由 uncertain 的旗舰模型/low 转向 reasoning 的旗舰模型/medium;先证实推理不足,继续沿用原快照、职责与验收,计入同一任务最多三次委派。不能用故障备用代替质量升级,也不自动转到更高强度。
145
140
 
146
141
  当前档位的手动主模型检测同时覆盖基线和任务候选,按组合去重、排除备用,确认框列出数量。配置、切档、查询与账号页面仍不自动检测。
147
142
 
@@ -159,146 +154,84 @@ agent-fit explain --level L4 --role task_review
159
154
 
160
155
  详细查询分开呈现已配置值、预设值、潜在覆盖与运行未验证。检查相关项目及祖先目录,不扫描全电脑;不输出账号凭据、私有指令、完整 TOML 或认证记录。范围外注册路径与未确定的 profile 只报告候选及未检查原因,不跟随任意文件。
161
156
 
162
- `explain --mode MODE` 查询非活动档位或在未安装时预览,只返回候选组合,不改变已部署角色;派发角色统一为 `task_delegate`,获授权评估时显式传入候选 model/effort 并保留原权限契约。为旧调用兼容,省略 --scope 的全局查询仅在固定角色组合匹配且不是 L4 时返回固定角色;显式作用域查询统一使用 task_delegate。
157
+ `explain --mode MODE` 查询非活动档位或在未安装时预览,只返回候选组合,不改变已部署角色;派发角色统一为 `task_delegate`,获授权评估时显式传入候选 model/effort 并保留原权限契约。省略 --scope 的全局查询仅在固定角色组合匹配且不是 L4 时返回固定角色;显式作用域查询统一使用 task_delegate。
163
158
 
164
159
  同一档位重复切换不重写、不提醒重启;普通切档及当前自定义定义更新也不要求重启。仅保存非活动定义不激活该档位。配置版本或格式不匹配时,读取与写入都会被拒绝,不做自动转换。
165
160
 
166
161
  无需全局安装的 npm 查询,以及本地包查询:
167
162
 
168
163
  ```sh
169
- npm exec --package="/path/to/fanglinwei-agent-fit-0.7.4.tgz" -- agent-fit status --details
164
+ npm exec --package="/path/to/fanglinwei-agent-fit-0.9.0.tgz" -- agent-fit status --details
170
165
  ```
171
166
 
172
167
  ## 委派收益检查
173
168
 
174
- 主代理先决定执行方式,再为需要委派的任务选择等级与模型。依次考虑主会话直接完成、独立工具调用并行,以及有明确收益的子代理委派。工具并行仍由同一主代理解释结果,不能替代独立复核。用户禁止子代理时不委派;用户明确要求委派或项目要求独立复核时,在授权、预算与宿主限制内执行,无法满足时说明阻塞。
169
+ 主代理先核对委派授权,再比较直接完成、工具并行和子代理委派。计入启动、交接、等待、汇总、验证与返工;收益不明确时由主会话完成。工具并行不能替代独立复核,项目要求的独立复核仍须满足。
175
170
 
176
- 收益可以来自模型适配、独立判断、上下文隔离或缩短总耗时。开销包含启动、上下文交接、等待、汇总、验证与返工。估算采用已有观测或保守值,未知开销不算零;不为估算额外调用模型,不用模型名称推断账单。收益不明确而主代理具备能力时继续本地完成;必要能力、证据或前提缺失时保留原验收并报告受影响部分。
171
+ 收益判断与并行约束由 [Skill 的委派收益检查](../adapters/codex/skills/agent-fit/SKILL.md#委派收益检查)统一规定。CLI 不测量收益、不派发任务;没有对照测量不宣称实际加速。
177
172
 
178
- 比较耗时时,两侧使用相同验收口径。委派侧先按依赖和可用槽位计算实际可重叠的执行时间,再计入协调开销;共享文件、构建状态或运行资源有冲突时不能直接并行。只为提速而委派,须扣除开销后仍有明确余量;独立复核等质量收益可以值得额外时间,但须单独说明。用一句话说明执行方式和主要理由,预计节省不等于已测得加速。
173
+ 拆分针对上下文、并行、独立验证、权限或能力与成本约束,不按岗位凑齐角色。主会话配合工具和按需加载的 Skills 足以完成时无需拆分;明确委派和强制独立复核的原要求仍保留。交接提供自包含任务、可访问的权威材料和验收,审查不以作者结论为前提,回传精炼结论及可复核证据;完成即返回,复用须有上下文收益且满足原独立性要求,细节见[派发模板](../adapters/codex/skills/agent-fit/references/dispatch-contract.md)。
179
174
 
180
- | 场景 | 选择与理由 |
181
- | --- | --- |
182
- | 两个已知文件各读 3 秒,子代理交接需 35 秒 | 独立读取可直接工具并行,由主会话判断;换模型不足以抵消交接成本 |
183
- | 两项独立调查各 90 秒,串行预计 180 秒;两个空闲槽,每名代理启动 40 秒,另需交接 35 秒、汇总 25 秒、验证 20 秒 | 委派预计 40 + 90 + 35 + 25 + 20 = 210 秒;只有提速诉求时由主会话完成 |
184
- | 45 秒的复核需 60 秒交接,但项目要求独立复核 | 保留独立复核,按原职责派发;无法执行则报告阻塞,不用作者自查替代 |
185
- | 两项独立研究各 8 分钟,委派总开销约 1 分钟且有两个空闲槽 | 委派预计约 9 分钟,对比串行约 16 分钟,有明确余量;同模型也可获得并行收益 |
186
-
187
- 上述时间仅为说明判断方法的假设,不是固定门槛或宿主性能承诺。此检查借鉴 [codex-auto-model-router 的收益与协调开销判断](https://github.com/orange-the-weak/codex-auto-model-router/blob/main/SKILL.md),沿用本工具的授权边界、四档模型配置和失败策略,不引入其自动授权或固定时间阈值。判断由主代理按 Skill 执行,CLI 的 `explain` 仍只静态解释等级与角色;它不会测量成本、派发任务或证明收益。基础规则更新部署后需重启 Codex,日常档位切换无需重启;工作区文件变更不表示已安装 home 已更新。
175
+ 上下文、文件和权限隔离分别核实:新线程或 `fork_turns="none"` 不自动创建独立工作树或受限沙箱,也不能保证独立判断。指令限制不等于环境强制隔离;缺少所需隔离时停止受影响部分,不能借此扩大权限。
188
176
 
189
177
  ## 任务等级与委派职责
190
178
 
191
- 先按歧义、耦合与实际推理需求判断复杂度,再检查错误后果、可验证性、输入/工具/上下文能力,最后从当前档位读取 model + effort。职责决定允许做什么,等级决定使用哪个配置;角色名称不决定等级。CLI 的 `explain --level` 只解释传入的等级,不调用分类模型,也不评估任务文本。
192
-
193
- 复杂度与职责由主代理判断,配置查表与 JSON 解析直接使用工具,不为此额外派发子代理。选好等级后执行 `agent-fit explain --codex-home <绑定 home> --level <等级> --role <原职责> --json`;退出码为 0、顶层 `errors` 为空,且 `data.mode_id`、`data.level`、`data.requested_role` 正确后,再使用 `data.primary`、`data.dispatch_role` 和 `data.permission_contract`。日常委派使用当前模式,获授权的非活动候选评估才传 `--mode`。工具不可用与查询失败分别按 [配置查询说明](../adapters/codex/skills/agent-fit/references/configuration.md#配置查询与失败分流) 处理;静态结果不证明实际运行身份或可用性。
194
-
195
- | 等级 | 判定依据 | 不足以单独升级的因素 |
196
- | --- | --- | --- |
197
- | L1:明确执行 | 方法、输入和验收已知,几乎不需要选择方案 | 文件多、文本长、重复步骤多 |
198
- | L2:有边界的推理 | 目标与验收明确,需要局部分析或有限方案选择 | 开发、调试、审查等职责名称 |
199
- | L3:复杂推理 | 相互影响的约束、竞争假设或矛盾证据需要权衡 | 单纯多步,或要求执行者独立 |
200
- | L4:高不确定性推理 | 关键假设尚未建立,需要构造并检验多条解释,或处理强耦合的开放问题 | 缺少资料、凭据或环境不通;这些情况先补前提 |
201
-
202
- 高影响且缺乏可靠验收时采用至少 L3 的本地保障下限,说明复杂度与保障调整各自的理由;这不是经过实测的能力保证。易于确定验收的机械任务可保留 L1。所选组合仍须满足实际能力和原验收,独立或专业验证遵循原任务要求;更强模型不能替代必要证据。
179
+ L1–L4 表示推理需求,职责限定允许的动作。主代理判定等级与职责,CLI 只查配置;高影响且缺乏可靠验收时采用至少 L3 的保障下限,必要材料、工具和证据仍须满足。
203
180
 
204
- | 任务等级 | cut(经济) | official(官方) | high(高级) | fire(全开,验证通过后) |
205
- | --- | --- | --- | --- | --- |
206
- | L1:明确执行 | Luna / high | Luna / high | Luna / max | Astra / ultra |
207
- | L2:有边界的推理 | Luna / high¹ | Sol 6.1 / medium | Sol 6.1 / ultra | Astra / ultra |
208
- | L3:复杂推理 | Sol 6.1 / medium | Sol 6.1 / high | Astra / ultra | Astra / ultra |
209
- | L4:高不确定性推理 | Sol 6.1 / high | Sol 6.1 / xhigh | Astra / ultra | Astra / ultra |
210
-
211
- L1–L4 是任务需求,cut/official/high/fire 是资源策略。相邻等级共用组合有效:cut 的 L1/L2、high 的 L3/L4、fire 的全部等级相同,不能据此宣称存在四档实际能力。¹ cut 的 L2 仅用于容易核验的产出,复杂部分提高等级。model 与 effort 含义不同,但执行时使用配置中的完整组合,不临时拼接;跨模型同名 effort 不证明等效,更高 effort 也不保证更合适。
212
-
213
- 完整 id:`gpt-6-luna`、`gpt-6.1-sol`、`gpt-6-astra`;备用另使用 `gpt-6-sol`。名称不证明价格、能力或账号权限。高影响结果需要独立证据与专业验证。
214
-
215
- `official` 是依据 [OpenAI 官方建议](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning) 制定的本地映射,官方没有固定 L1–L4 表。`high` 各模型使用最高受支持的 effort;预设写入不证明账号可调用。
216
-
217
- `fire` 每个会话首次委派前须实际验证 Astra/ultra,并核对可信运行 metadata 与当前会话上下文。模型、effort、供应商或账号变化后重验,不保存跨会话验证缓存。目录查询和口头确认不能代替验证;`models check --verify` 通过独立 Responses 请求验证,不启动 Codex 任务线程或工具执行器。
218
-
219
- 检查失败、未完成或最高组合不可用时,使用用户明确指定的模型与推理强度;未另行指定时继承父代理当前实际组合。通过 `task_delegate` 保留原职责,并核对全局子代理默认与角色覆盖;无法确认父代理组合时阻断该委派。不自动切换 high,不绕过原预算、能力和权限规则。fire 的继承备用是运行时选择,静态 fallback 为 null。
220
-
221
- 四个职责:
181
+ | 等级 | 需求 | cut | official | high | fire |
182
+ | --- | --- | --- | --- | --- | --- |
183
+ | L1 | 方法、输入与验收明确 | 经济用途 / high | 经济用途 / high | 经济用途 / max | 旗舰用途 / ultra |
184
+ | L2 | 有边界的局部分析或有限方案选择 | 经济用途 / high | 通用用途 / medium | 通用用途 / ultra | 旗舰用途 / ultra |
185
+ | L3 | 权衡相互影响的约束或矛盾证据 | 通用用途 / medium | 通用用途 / high | 旗舰用途 / ultra | 旗舰用途 / ultra |
186
+ | L4 | 关键假设未知或强耦合的开放问题 | 通用用途 / high | 通用用途 / xhigh | 旗舰用途 / ultra | 旗舰用途 / ultra |
222
187
 
223
- - `task_scan`:L1 固定预设,只读取证。
224
- - `task_execute`:L2 固定预设,只在明确独占范围产出。
225
- - `task_review`:L3 固定预设,独立复核。
226
- - `task_delegate`:不固定 model/effort,用于用户指定、继承、L4 或固定组合不匹配;保留原请求职责。
188
+ 上表使用用途,具体模型以绑定 home 的 `mode show` 或 `explain` 为准。cut/L2 面向易核验产出,复杂部分提高等级。相邻等级可共用组合;跨模型同名 effort 不证明等效,模型名称不证明能力、价格或权限。`official` 是依据[官方建议](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning)制定的本地映射,官方没有固定 L1–L4 表。
227
189
 
228
- 等级与职责互相独立。例如经济模式下复杂产出升为 L3 时,不能继续用固定 Luna 的 task_execute 覆盖选择;应使用 task_delegate 请求 Sol/medium,同时保留范围内产出的权限契约。继承需核对宿主全局默认,省略参数不证明继承。
229
-
230
- | 场景 | 选择与理由 |
231
- | --- | --- |
232
- | 核对 20 个名称是否符合给定精确格式 | L1,只读复核;固定复核角色组合不符时使用 task_delegate,保留只读权限 |
233
- | 按已批准表替换 200 个文件,可确定核验 | L1 的机械产出;文件数不证明需要复杂推理,写入范围与共享资源仍须明确 |
234
- | 在单模块实现验收明确的小功能 | L2 的局部推理;并非所有实现任务都需要 L3 |
235
- | 只读取证,分析异步状态与持久化竞争的矛盾证据 | L3 的复杂推理;不能因只读而固定使用 L1 |
236
- | 多机制交互且关键假设未知,需要构造与检验多条解释 | L4;若缺少必需材料,先补前提 |
237
- | 操作机械但涉及权限边界,错误后果高且缺乏可靠验收 | 说明复杂度可能为 L1,因保障下限采用至少 L3;无法满足原验收时补前提或阻断 |
190
+ | 职责 | 允许范围 | 固定绑定 |
191
+ | --- | --- | --- |
192
+ | `task_scan` | 只读取证 | L1 |
193
+ | `task_execute` | 明确独占范围内产出 | L2 |
194
+ | `task_review` | 独立复核 | L3 |
195
+ | `task_delegate` | 保留原请求职责 | 无固定 model/effort |
238
196
 
239
- 一次派发用一句话说明即可,例如:“跨模块状态约束与矛盾证据需要 L3,采用 official 的 Sol 6.1/high,通过 task_delegate 保留只读取证职责。”不用逐次生成评分表。
197
+ 固定组合不匹配、L4、用户指定或继承时使用 task_delegate。作用域查询也统一返回 task_delegate,显式传 model/effort 与 `fork_turns="none"`,完整交接;省略参数不证明继承。
240
198
 
241
- AGENTS 管理入口要求启动时读取 Skill,每次创建、重新委派或模型变化前按 Skill 检查。用户选择、预算、宿主和项目规则优先,工具不自动授权委派。主代理保留最终设计、共享裁决、集成、关键验证及完成声明。子代理禁止递归、外部环境和代理配置改动;独占写入、局部适配/阻断、最小充分验证及 PARTIAL 返回在全部档位保留。
199
+ `high/fire` 的最高强度须经明确选档授权。fire 每会话先验证实际调用、可信身份及上下文匹配,模型/effort/账号/供应商变化后重验;独立 CLI passed 不能单独放行。失败时仅使用用户指定组合,否则继承已确认的父代理实际组合,不能自动切 high。
242
200
 
243
- 本工具不额外限制 Git 操作或图像生成,也不设置 `features.image_generation`。实际工具能力与操作授权遵循宿主、用户和项目规则。
201
+ 分级、快照、能力检查与权限的完整合同见 [Skill](../adapters/codex/skills/agent-fit/SKILL.md),交接字段见[派发模板](../adapters/codex/skills/agent-fit/references/dispatch-contract.md)。
244
202
 
245
203
  ## 组合校准
246
204
 
247
- 当前映射是待校准预设。日常委派不自动运行对照、训练路由器、采集任务账本或修改默认配置;用户要求评估或调优时,按 [离线校准指南](../adapters/codex/skills/agent-fit/references/calibration.md) 冻结任务、候选、预算与原验收,独立执行并记录结果。指南随 Skill 部署到 `references/calibration.md`,普通任务不必加载。
248
-
249
- 先由主代理预检本次涉及的配置查询、JSON 封套与职责契约,再进入模型候选评估;预检不发模型请求,查询故障不记为候选能力失败。分级规则核验检查“等级判断是否一致”;组合能力评估检查“实际任务是否通过原验收”,三者不能互相替代。优先比较不同的 model + effort,不对 high 的 L3/L4 或 fire 的相同组合重复计费。范围用于限定职责与上下文;时延要求只在满足质量的候选间取舍,不对任务信号强制打分。
250
-
251
- 分级边界核验分别记录任务本身复杂度、保障后的拟采用等级、是否需先补前提及理由;被测上下文不手工猜模型组合,主代理再用 CLI 取值。输入和预期分开冻结,覆盖文件数、职责名称、时限等干扰;同一批案例不算多次独立重复,未发现违规证据时保留原分级与默认映射。
252
-
253
- 结果按请求组合与可信运行 metadata 分别记录;运行身份未验证时,模型归因标 PARTIAL。保留全部首次尝试、失败和未知项,批量子问题不冒充独立重复样本,缺失耗时或资源证据不能填零。先核对质量,再比较返工、端到端耗时和可信资源用量;较强模型调用比例不等于验收通过率。只有证据稳定并在独立样本复核后,才按用户授权保存自定义档位;样本不足保留原映射。
205
+ 预设映射仍需按任务验收。用户要求评估或调优时,按[离线校准指南](../adapters/codex/skills/agent-fit/references/calibration.md)冻结输入、候选、预算与独立预期,分别验证配置契约、分级判断和实际产出。保留首次失败及未知项,运行身份未核验时模型归因标 PARTIAL。
254
206
 
255
- 失败接续另用冻结场景核对下一步动作、组合、原职责、已用次数与停止理由,不实际执行案例任务;决策核验通过不证明宿主已执行重派。预期答案与输入分开保存,规则部署文字检查不能替代该核验。
256
-
257
- 任务信号借鉴 [codex-auto-model-router](https://github.com/orange-the-weak/codex-auto-model-router/blob/main/references/routing-criteria.md),校准思路借鉴 [RouteLLM](https://github.com/lm-sys/RouteLLM),验收后再考虑升级的思路参考 [FrugalGPT 的模型级联](https://arxiv.org/abs/2305.05176)。本工具不移植其模型列表、训练系统或研究中的成本收益数字;职责配置检查继续借鉴 Castwright,复杂度判定不按职责固定。
207
+ 先比较质量,再比较返工、端到端耗时与可信资源用量;批量子问题不算独立重复,较强模型调用比例不等于验收通过率。日常任务不自动对照、采集账本或修改默认映射,普通切档也不以追加评测为前提。
258
208
 
259
209
  ## 职责与模型一致性检查
260
210
 
261
- `agent-fit status --details --json` 的 `roles` 为每个受管理角色并列给出 `task_level`、`expected_model`、`expected_effort`,以及 `configured_name`、`configured_model`、`configured_effort`。`matches_mode` 同时检查文件存在且可解析、角色名称正确、模型和 effort 与当前已部署档位一致;未安装时为 `null`。
262
-
263
- | 角色 | 核对要求 |
264
- | --- | --- |
265
- | `task_scan` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L1 |
266
- | `task_execute` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L2 |
267
- | `task_review` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L3 |
268
- | `task_delegate` | 文件名与 `name` 对应,必须同时省略 model 和 effort;预期等级与组合为 `null`,实际继承仍需宿主证据 |
269
-
270
- 任一项不匹配时,已安装 home 的诊断返回 `ROLE_CONTRACT_MISMATCH`,完整性标为 `drifted`,配置写入在覆盖前停止。该语义检查独立于文件摘要检查;它不会自动修复用户修改。原有文件漂移、注册路径冲突、符号链接与恢复保护继续适用,`restore` 仍须通过原有恢复条件。
211
+ `status --details --json` 的 `roles` 并列返回预期等级、model/effort 与磁盘配置。`matches_mode` 核对文件可解析、名称正确及组合匹配;task_delegate 必须同时省略 model 和 effort。未安装时该值为 null。
271
212
 
272
- 开发测试以 `ROLES` 为本工具的职责登记源,双向核对发布资产中的角色 TOML 与 `assets/codex/config.toml` 注册表,包含嵌套目录中的多余定义,并检查官方初始模板显式设置两个模型参数;所有档位生成时继续使用各自的组合。这借鉴 [Castwright 的角色、模型和 effort 对应检查](https://github.com/dudarenok-maker/Castwright/blob/main/.claude/skills/model-routing/SKILL.md),只约束本工具发布的四个角色,不要求用户将其他自定义角色纳入本工具登记。
273
-
274
- 以上结果描述磁盘配置及声明的职责对应关系,不能证明自然语言职责已被执行、账号可调用或实际运行模型与 effort 已生效;运行验证仍单独报告。
213
+ 不匹配返回 `ROLE_CONTRACT_MISMATCH`,已安装 home 标为 drifted,写入在覆盖前停止;摘要、路径、符号链接和恢复保护继续适用,不自动修复用户修改。磁盘一致不证明实际模型、账号权限或职责已执行。
275
214
 
276
215
  ## 备用与模型不可用
277
216
 
278
217
  | 档位 | L1 备用 | L2 备用 | L3 备用 | L4 备用 |
279
218
  | --- | --- | --- | --- | --- |
280
- | cut(经济) | Sol 6.1/medium | Sol 6.1/medium | Sol 6/medium | Sol 6/high |
281
- | official(官方) | Sol 6.1/medium | Sol 6/medium | Sol 6/high | Sol 6/xhigh |
282
- | high(高级) | Sol 6.1/high | Sol 6/ultra | Sol 6.1/ultra | Sol 6.1/ultra |
283
- | fire(全开) | 用户指定,否则继承父代理 | 同左 | 同左 | 同左 |
284
-
285
- cut、official、high 默认允许原已授权任务自动使用本级唯一备用,无需逐次确认;用户明确锁定模型或禁止降级时不切换。模型不可用、effort 不支持,或临时故障有限重试后仍失败时可触发;认证、权限、额度、账单限制及原因 unknown 时停止受影响路径。每任务最多三次委派(初次、重试、质量升级与备用共用),同一组合最多额外一次,累计重试等待不超过 30 秒并遵守 Retry-After;宿主内部重试次数未知时不叠加。备用耗尽后报告原因、实际组合和部分产出,不自动尝试其他模型或切换档位。L3、L4 不自动降到 Luna。
286
-
287
- 自定义档位采用同样条件与预算:用户选择已保存的档位后,本级非空 fallback(包括从内置档位按值复制的备用)允许自动接续;仅创建、保存或预览候选不构成选择。fallback 为 null 时没有可用性备用,不借用其他档位或 fire 的父代理继承规则;用户锁定模型或禁止备用仍优先。
219
+ | cut | 通用用途/medium | 通用用途/medium | 通用备用用途/medium | 通用备用用途/high |
220
+ | official | 通用用途/medium | 通用备用用途/medium | 通用备用用途/high | 通用备用用途/xhigh |
221
+ | high | 通用用途/high | 通用备用用途/ultra | 通用用途/ultra | 通用用途/ultra |
222
+ | fire | 用户指定,否则继承父代理 | 同左 | 同左 | 同左 |
288
223
 
289
- 备用是候选,需要同时满足用户选择、原预算、宿主支持、原工具/输入能力、原职责与验收不变。写入任务还必须确认旧 worker 已停止并检查部分产出。接续由主代理按生成的 Skill 使用 task_delegate 显式指定备用组合执行,CLI 和网页仅配置、展示与检查,不转发推理或自动重派,不换账号或供应商。配置写入和测试通过不证明宿主运行时已接续。
224
+ 候选使用自己的备用,主代理从原任务完整快照取值。已选择的 cut/official/high 或自定义档位,在授权、预算、能力和宿主均允许时可使用本级非空 fallback;仅保存或预览不算选择,null 不借用其他档位。用户锁定模型或禁止备用优先。
290
225
 
291
- Astra 不可用:先区分认证、权限、额度、临时故障或能力不支持。允许备用且全部条件满足才用当前档位的候选,fire 使用用户指定组合,否则继承父代理;用户强制只用 Astra、预算不允许或旧 worker 停止未知时,受影响部分 BLOCKED,继续其他独立工作。缺资料或工具故障先补前提,不能靠强模型掩盖。
226
+ 认证、权限、额度、账单及未知原因停止受影响路径;模型不可用、effort 不支持或有限重试后的临时故障才按条件接续。初次、重试、质量升级及备用共用每任务最多三次委派,同组合最多额外一次,累计重试等待不超过 30 秒并遵守 Retry-After;宿主重试未知时不叠加,拆分不重置。
292
227
 
293
- 每任务最多三次父代理发起的委派,同一组合最多额外一次;拆分困难部分不重置计数。累计重试等待不超过 30 秒并遵守 Retry-After。宿主已重试或次数未知时不追加。异常或部分结果标 PARTIAL,不自动撤销其他人的修改。完整分类见 [失败处理](../adapters/codex/skills/agent-fit/references/failure-policy.md)。
228
+ 写入任务先确认旧 worker 已停止并检查部分产出。主代理通过 task_delegate 显式派发,CLI 不自动重派或更换账号/供应商。完整分流和 fire 例外见[失败处理](../adapters/codex/skills/agent-fit/references/failure-policy.md)。
294
229
 
295
230
  ## 验收失败与质量升级
296
231
 
297
- 请求成功而结果未达原验收属于质量问题,不能当作模型不可用。主代理先指出可复核的失败,再区分材料/环境前提、方法或交接遗漏、推理不足;前提缺失先补齐,方法遗漏可补正后有限重试,推理不足或新暴露复杂约束才重评困难部分等级。用户选择、原预算与宿主能力允许时,选择原任务快照中的同级任务候选或更高等级主组合,保留原职责和验收;本级 fallback 仅供可用性接续。
232
+ 请求成功但产出未达原验收时,先指出可复核失败,再区分前提缺失、方法遗漏和推理不足。前提先补齐;有限重试或质量升级使用原任务快照,保留职责、验收、预算与累计次数,不能用可用性 fallback 代替升级。
298
233
 
299
- 比较实际 model + effort,相邻等级组合相同不重派;可核对下一不同组合,但自定义高等级不保证能力更强。high 的 L3→L4 与 fire 的升等级都没有实际组合提升,无适合候选时报告上限。若有新证据或具体方法修正,可以在余量内重试原组合,并如实称为重试;不机械地先加 effort 或先换模型。
300
-
301
- 例如使用等级基线时,official/L2 产出未通过原测试,且证据显示遗漏跨模块状态约束,可将困难部分重评为 L3,使用 Sol 6.1/high,通过 task_delegate 保留产出职责。凭据无效则停止认证路径,不按质量升级。每次接续先确认旧写入者停止并检查已有产出;初次、重试、质量升级和备用共用三次总额,拆分不重置。次数耗尽、用户锁定组合、预算不足或无合适候选时停止受影响委派,报告 PARTIAL/BLOCKED,继续独立工作。CLI 不执行自动升级或重派。
234
+ 比较实际 model + effort;相同组合改等级或标签不算升级。写入者停止未知、次数耗尽、组合被锁定或无合适候选时停止受影响委派,报告 PARTIAL/BLOCKED 并继续独立工作。完整条件见[质量升级](../adapters/codex/skills/agent-fit/references/failure-policy.md#质量升级)。
302
235
 
303
236
  ## 自定义档位
304
237
 
@@ -335,6 +268,34 @@ JSON
335
268
 
336
269
  最高 64 KiB UTF-8 JSON;必须明确全部等级与备用/null;每级可选 tasks,候选也须完整提供 model、effort 和 fallback/null,拒绝未知字段、无效类型/等级、缺级、半对参数或主备用相同。与单级参数互斥。活动定义与部署角色同一事务保存;非活动定义只保存,不激活。
337
270
 
271
+ ### 专长路线
272
+
273
+ cut/official 的 visual/computer/writing 使用同一专长用途,L1 low、L2 medium、L3 high;故障备用为通用模型 medium、medium、high。high/fire 按原高强度策略处理这三类任务,L4 不提供专长路线。
274
+
275
+ 先确定复杂度与保障要求,再核对主要工作是否属于专长、关键事实和约束是否已知、结果是否可核验。开放研究、强耦合或高后果且难验收的任务仍使用基线或 uncertain/reasoning;含有图片或产出文章不足以选择专长候选。电脑操作仍须原工具与写入授权,不能扩大只读职责。
276
+
277
+ ```sh
278
+ agent-fit explain --level L1 --task visual --role task_scan --json
279
+ agent-fit explain --level L2 --task computer --role task_execute --json
280
+ agent-fit explain --level L3 --task writing --role task_review --json
281
+ ```
282
+
283
+ 聊天中补齐 Skill 要求的 session、project 与 thread 参数。已有自定义定义和任务快照不自动合并新候选;可从当前内置定义创建新档位,或通过完整定义编辑。配置与规则同步后重启一次 Codex,随后按新任务查询;不需要先追加模型评测。
284
+
285
+ ### 模型绑定与换代
286
+
287
+ 内置策略在 [modes.json](../adapters/codex/modes.json) 中引用用途别名,包内默认模型 id 集中在 [model-bindings.json](../adapters/codex/model-bindings.json)。同用途换代无需改写策略或更新共享 Skill。五种用途为 `economy`(经济)、`general`(通用)、`general_backup`(通用备用)、`frontier`(旗舰)、`visual_work`(视觉、电脑操作和写作)。
288
+
289
+ ```sh
290
+ agent-fit models check --codex-home "$CODEX_HOME"
291
+ agent-fit models bind general "$NEW_MODEL" --dry-run --codex-home "$CODEX_HOME"
292
+ agent-fit models bind general "$NEW_MODEL" --apply "$PREVIEW_TOKEN" --codex-home "$CODEX_HOME"
293
+ ```
294
+
295
+ 从目录选定具体 id 后,预览会列出每个受影响档位、等级或任务类型的主选和备用变更;令牌对应这个 home、当前配置和这份变化。确认模型能力、预算及变化范围后,用预览返回的令牌应用(JSON 字段 `data.model_binding.preview_token`)。应用会重新查目录;配置有变化、目录未完成,或新组合不在可见目录及支持的 effort 中,均不会写入。不会自动晋升新模型、调整 effort 或调用推理。自定义供应商的目录不提供 effort,不能用于此命令;需要时可直接保存自定义档位中的具体组合。
296
+
297
+ 更新存入绑定 home 的 `.agent-fit/model-bindings.json`,覆盖包内默认绑定。该 home 后续所有作用域的内置档位使用更新后的组合;当前全局内置档位如受影响,其快照和角色配置一并更新。已开始任务、自定义档位和其他 home 的组合不变。需要撤销某条绑定时,用原模型 id 重新预览并应用。模型目录不证明能力或实际调用;`fire` 仍须按新组合重新验证。
298
+
338
299
  ### 配置与模型检查分开执行
339
300
 
340
301
  setup、设置或激活内置/自定义档位、应用当前自定义修改,以及重复设置当前档位只处理本地配置,不启动 Codex 账号/模型检查进程,不查询供应商目录、不发送推理请求,也不生成模型检查记录。配置结果与退出码仅反映本地配置操作,模型不可用或历史记录目录异常不影响配置保存。
@@ -367,7 +328,7 @@ agent-fit models check --verify
367
328
  agent-fit models check --verify --discover
368
329
  ```
369
330
 
370
- 配置操作不附带账号或模型检查;仅在用户显式执行模型检查命令,或在档位页确认检测时查询所选 home。
331
+ 日常配置操作不附带账号或模型检查;显式检查、绑定预览与应用会查询所选 home 的目录。
371
332
 
372
333
  检查通过 stdio app-server 在空临时目录读取当前 home 的账号与生效配置,无认证刷新参数、无项目加载,不输出原始 RPC、stderr、邮箱、账号 ID 或凭据。官方默认上下文的目录使用 Codex `model/list`,最多 100 页,单帧 1 MiB、总接收 8 MiB。第三方供应商或自定义 API 地址使用同一供应商的 `GET /models` 获取候选,不使用 Codex 目录补齐。沿用同一配置的地址、请求头、查询参数和授权,最多 1000 个候选、响应最多 2 MiB;只保留模型标识,不猜测推理强度。当前支持完整单页列表;有后续分页会明确标记未完成并停止批量验证。目录整轮共享 30 秒期限。自定义供应商的空账号不直接判无权限。
373
334
 
@@ -400,23 +361,22 @@ agent-fit serve --codex-home "/path/to/codex-home" --open
400
361
  agent-fit serve --port 17321
401
362
  ```
402
363
 
403
- 只监听 `127.0.0.1`。默认端口 0 自动分配,指定端口允许 1024–65535;占用即失败。`--open` 打开浏览器,失败时手动复制终端 URL;Ctrl+C 等待正在执行的 CLI 安全完成后停止服务。
404
-
405
- 服务绑定一个 home 和启动 cwd。换 home 时重新启动。四页入口为档位、委派规则、账号配置、恢复。先编辑草稿,再保存/应用;自定义四级由一个 stdin 命令事务提交。未保存的非活动定义不能直接激活。取消只清除草稿;已创建的档位会保留。
364
+ 仅监听 `127.0.0.1`,默认端口 0 自动分配,也可指定 1024–65535;占用即失败。`--open` 失败时复制终端 URL。Ctrl+C 等待正在执行的 CLI 安全完成后停止服务。home、项目和可选线程在启动时绑定,换上下文需重新启动。
406
365
 
407
- 委派规则页默认展示当前作用域已保存且生效的档位,顶部标明作用域与继承来源。四级概览直接展示 L1–L4 默认模型与推理强度;每级列出判断依据、典型任务和适用任务候选的路由,缺失候选明确标为“未配置”,不猜测或借用等级默认。内置 high/fire 的普通任务按本级最高组合显示,低延迟候选仍须显式配置。其他档位仅供只读预览,查看不切换配置,也不构成最高强度授权。
408
-
409
- 点击等级或任务即可查询选择依据、备用与条件;职责和权限在详情中按需展开,完整模型 ID、来源与诊断继续折叠。桌面在右侧显示详情,窄屏在所选等级下显示。切换查看档位、刷新配置或查询失败时不保留旧解释冒充新结果;版本冲突后先刷新。页面不自动调用模型检测,静态路由不证明账号可用性或运行身份;需要编辑时使用“前往档位配置”。
410
-
411
- 档位页的“检测当前档位主模型”由用户点击并确认后触发,使用已保存且设为当前的档位,按 model/effort 去重检测 L1–L4 基线及同级任务候选,实际调用次数由去重后的组合数量决定,备用不参与。未安装、查看非当前档位、有未保存草稿、授权切换中或其他操作执行时禁用。确认框展示档位、完整组合、次数与费用提示,取消不发请求;保存、激活、刷新与重新设置均不自动触发检测。
366
+ | 页面 | 操作 |
367
+ | --- | --- |
368
+ | 档位 | 编辑草稿后保存或应用;候选 JSON 随整表事务提交 |
369
+ | 委派规则 | 展示有效来源、四级基线和候选;点击查询依据、备用及权限,其他档位为只读预览 |
370
+ | 账号配置 | 管理已有授权、登录、取消和退出;不展示模型目录或历史 |
371
+ | 恢复 | 预览并撤销整个 home 的安装,包含全部作用域 |
412
372
 
413
- 检测复用 `models check --verify --expect-revision REV`,实际调用与响应身份分别呈现。请求成功但缺少身份元数据时保留“可调用 / 身份未确认”,不描述为严格验证通过;返回不同模型或强度时标记未确认。配置版本变化、来源未确认或登录切换后,旧结果失效或清除。结果仅代表本次请求,不代替 fire 的当前会话验证;CLI 仍按原规则保存记录,账号页不展示目录和检测历史。
373
+ “检测当前档位主模型”需点击确认,可能产生费用。仅检测当前已保存档位的基线与候选,按 model/effort 去重,排除备用;未安装、非当前档位、有草稿、授权切换中或其他操作执行时禁用。确认框列出组合与次数,取消零请求;配置操作不自动检测。
414
374
 
415
- 桌面左侧导航切换页面,上方选择档位,中央查看或编辑 L1–L4 模型分配,右侧核对变更并应用或预览。手机使用顶部导航,变更确认放在模型配置下方。备用组合按需展开;仅选择档位不会写入配置;应用日常档位切换无需重启,后续新任务读取新配置。首次安装、基础规则更新或恢复后仍需重启。
375
+ 检测使用 `models check --verify --expect-revision REV`。配置、来源或授权变化后旧结果失效;可调用、响应身份与 fire 会话验证分别报告,详见[模型检查](#模型检查)。
416
376
 
417
- 档位、规则和恢复页面通过白名单动作实际 spawn 本包 CLI,显示命令与结果;账号页仅使用官方账号 RPC。页面不直接写配置、不执行任意 shell。HTTP 使用精确 Host/Origin、会话 Cookie、随机 CSRF token、CSP;不支持远程监听、CORS、CDN、守护进程或自动排队。
377
+ 配置、规则与恢复动作仅执行白名单 CLI,账号页使用官方 RPC;不执行任意 shell。接口校验 Host/Origin、会话 Cookie 与 CSRF token,使用 CSP;不开放远程监听或 CORS。桌面侧栏、手机顶部导航,详情和变更确认随屏宽排列。
418
378
 
419
- 配置版本冲突保留草稿并零写入,点击“刷新后比较”后再决定保存。断线或结果未知不自动重试写操作,先刷新状态。页面关闭/重载可能丢失内存草稿,未使用浏览器持久存储。
379
+ 版本冲突保留草稿且零写入,先“刷新后比较”再保存。断线或结果未知时先刷新,不自动重试写操作;查询失败不保留旧解释。草稿仅在内存,页面关闭可能丢失;取消草稿不会删除已创建的档位。
420
380
 
421
381
  ## JSON、退出码与冲突
422
382
 
@@ -487,4 +447,4 @@ npm pack
487
447
  PLAYWRIGHT_MODULE=/path/to/playwright CHROME_PATH=/path/to/chrome npm run test:browser
488
448
  ```
489
449
 
490
- 跨平台 API 设计不代替实机验收;Linux/Windows、其他 Codex 客户端及真实账号推理仍需单独验证。当前验证结果与边界见 [实施验收记录](implementation-review.md)。
450
+ 已有验收记录与未覆盖范围见[验证范围](implementation-review.md)。历史校准材料不随 npm 包交付,不代表当前安装或发布状态。
package/lib/codex.mjs CHANGED
@@ -6,13 +6,34 @@ import { parse, stringify } from 'smol-toml';
6
6
  export const PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url));
7
7
  export const VERSION = (await readFile(new URL('../VERSION', import.meta.url), 'utf8')).trim();
8
8
  export const LEVELS = ['L1', 'L2', 'L3', 'L4'];
9
- export const TASKS = { mechanical: ['L1'], bounded: ['L2'], scan: ['L1', 'L2'], deep: ['L1', 'L2'], complex: ['L2', 'L3'], uncertain: ['L3', 'L4'], reasoning: ['L3', 'L4'], latency: LEVELS };
9
+ export const TASKS = { mechanical: ['L1'], bounded: ['L2'], scan: ['L1', 'L2'], deep: ['L1', 'L2'], complex: ['L2', 'L3'], uncertain: ['L3', 'L4'], reasoning: ['L3', 'L4'], visual: ['L1', 'L2', 'L3'], computer: ['L1', 'L2', 'L3'], writing: ['L1', 'L2', 'L3'], latency: LEVELS };
10
10
  export const ROLES = { task_scan: 'L1', task_execute: 'L2', task_review: 'L3', task_delegate: null };
11
11
  export const START = '<!-- agent-fit:start -->';
12
12
  export const END = '<!-- agent-fit:end -->';
13
13
  const policy = JSON.parse(await readFile(new URL('../adapters/codex/modes.json', import.meta.url), 'utf8'));
14
+ const defaultBindings = JSON.parse(await readFile(new URL('../adapters/codex/model-bindings.json', import.meta.url), 'utf8'));
14
15
  export const FALLBACK_CONDITIONS = policy.fallback_conditions;
15
- export const BUILTINS = policy.modes.map(mode => ({ ...mode, kind: 'builtin', fallback_conditions: FALLBACK_CONDITIONS }));
16
+
17
+ export function validateModelBinding(slot, model) {
18
+ if (!Object.hasOwn(defaultBindings, slot)) throw argumentError(`未知模型用途;可选 ${Object.keys(defaultBindings).join('、')}。`, 'MODEL_SLOT_INVALID');
19
+ return validateText(model, 200, '模型');
20
+ }
21
+
22
+ export function builtinModes(overrides = {}) {
23
+ for (const [slot, model] of Object.entries(overrides)) validateModelBinding(slot, model);
24
+ const bindings = { ...defaultBindings, ...overrides };
25
+ const pair = ({ slot, effort }) => ({ model: Object.hasOwn(bindings, slot) ? bindings[slot] : undefined, effort });
26
+ const route = value => ({ ...pair(value), fallback: value.fallback === null ? null : pair(value.fallback) });
27
+ return policy.modes.map(({ levels, ...mode }) => ({
28
+ ...mode, kind: 'builtin', fallback_conditions: FALLBACK_CONDITIONS,
29
+ levels: validateDefinition({ levels: Object.fromEntries(Object.entries(levels).map(([level, value]) => [level, {
30
+ ...route(value),
31
+ ...(value.tasks && { tasks: Object.fromEntries(Object.entries(value.tasks).map(([task, candidate]) => [task, route(candidate)])) }),
32
+ }])) }),
33
+ }));
34
+ }
35
+
36
+ export const BUILTINS = builtinModes();
16
37
 
17
38
  export function argumentError(message, code = 'INVALID_ARGUMENT') {
18
39
  return Object.assign(new Error(message), { code, exitCode: 2 });
@@ -57,9 +78,9 @@ export function validateDefinition(input) {
57
78
  }));
58
79
  }
59
80
 
60
- export function resolveDefinition(selector, customModes = []) {
81
+ export function resolveDefinition(selector, customModes = [], builtins = BUILTINS) {
61
82
  const name = typeof selector === 'string' ? selector.trim().normalize('NFC') : selector;
62
- const matches = [...BUILTINS.filter(mode => mode.id === selector), ...customModes.filter(mode => mode.id === selector || mode.name === name)];
83
+ const matches = [...builtins.filter(mode => mode.id === selector), ...customModes.filter(mode => mode.id === selector || mode.name === name)];
63
84
  if (matches.length !== 1) throw argumentError('档位不存在或名称不唯一;内置档位请用 cut、official、high、fire,自定义档位请用 mode list 显示的 id 或名称。', 'MODE_NOT_FOUND');
64
85
  const mode = matches[0];
65
86
  return { ...mode, levels: validateDefinition({ levels: mode.levels }), fallback_conditions: FALLBACK_CONDITIONS };