@fanglinwei/agent-fit 0.8.0 → 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/.codex-plugin/plugin.json +1 -1
- package/README.md +33 -131
- package/VERSION +1 -1
- package/adapters/codex/model-bindings.json +7 -0
- package/adapters/codex/modes.json +112 -112
- package/adapters/codex/skills/agent-fit/SKILL.md +11 -10
- package/adapters/codex/skills/agent-fit/assets/AGENTS.fragment.md +2 -2
- package/adapters/codex/skills/agent-fit/assets/codex/agents/task-execute.toml +0 -2
- package/adapters/codex/skills/agent-fit/assets/codex/agents/task-review.toml +0 -2
- package/adapters/codex/skills/agent-fit/assets/codex/agents/task-scan.toml +0 -2
- package/adapters/codex/skills/agent-fit/evals/evals.json +44 -0
- package/adapters/codex/skills/agent-fit/references/calibration.md +8 -2
- package/adapters/codex/skills/agent-fit/references/configuration.md +11 -2
- package/adapters/codex/skills/agent-fit/references/dispatch-contract.md +15 -1
- package/adapters/codex/skills/agent-fit/references/failure-policy.md +4 -4
- package/adapters/codex/skills/agent-fit/references/task-routing.md +19 -19
- package/bin/agent-fit.mjs +16 -5
- package/docs/README.md +10 -12
- package/docs/implementation-review.md +24 -140
- package/docs/usage.md +78 -154
- package/lib/codex.mjs +24 -3
- package/lib/install.mjs +85 -21
- package/lib/models.mjs +6 -3
- package/lib/scopes.mjs +1 -1
- package/package.json +1 -1
- package/web/app.js +3 -3
- package/adapters/codex/profiles/terra-evaluation.json +0 -134
package/docs/usage.md
CHANGED
|
@@ -1,28 +1,22 @@
|
|
|
1
1
|
# 使用说明
|
|
2
2
|
|
|
3
|
-
`agent-fit` 0.
|
|
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.
|
|
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
|
|
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
|
|
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,19 +107,19 @@ L1–L4 保留为推理复杂度;在最终等级内通过 `--task` 选择模
|
|
|
117
107
|
|
|
118
108
|
| 类型 | 等级 | cut / official 主候选 |
|
|
119
109
|
| --- | --- | --- |
|
|
120
|
-
| `mechanical`:确定性机械任务 | L1 |
|
|
121
|
-
| `bounded`:普通有界任务 | L2 |
|
|
122
|
-
| `scan`:大型有界扫描或审查 | L1/L2 |
|
|
123
|
-
| `deep`:大型确定性深度处理 | L1/L2 |
|
|
124
|
-
| `complex`:有界复杂任务 | L2/L3 |
|
|
125
|
-
| `uncertain`:高歧义、高耦合或高后果且难验收 | L3/L4 |
|
|
126
|
-
| `reasoning`:复杂推理或已证实推理不足 | L3/L4 |
|
|
127
|
-
| `visual`:视觉理解与图像推理 | L1/L2/L3 |
|
|
128
|
-
| `computer`:有界电脑操作 | L1/L2/L3 |
|
|
129
|
-
| `writing`:自然写作与修订 | L1/L2/L3 |
|
|
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 |
|
|
130
120
|
| `latency`:明确追求低延迟 | 任意等级 | 须显式配置,不保证实际延迟 |
|
|
131
121
|
|
|
132
|
-
|
|
122
|
+
这些是待校准的本地策略,不代表已经验证模型能力或延迟。普通旗舰候选默认 low,复杂推理或有证据的质量升级最多 medium;更高强度需要明确授权。**用户明确选择 high/fire 即授权其展示的高强度组合**;预览或保存不构成选择,预算、宿主支持和 fire 会话验证继续适用。已选择的自定义档位执行明确保存的组合。
|
|
133
123
|
|
|
134
124
|
先判断等级,再核对组合的工具、输入、上下文与验收能力。无法明确匹配任务候选时使用本级基线,仍需能力检查;候选适用依据与 L2/L3 complex 的边界见 [任务路由](../adapters/codex/skills/agent-fit/references/task-routing.md#基线与候选的选择边界)。同一组合改标签不构成质量升级,也不存在固定的跨模型升级顺序。
|
|
135
125
|
|
|
@@ -140,13 +130,13 @@ agent-fit explain --level L3 --task uncertain --role task_scan --json
|
|
|
140
130
|
agent-fit explain --level L3 --task reasoning --role task_execute --json
|
|
141
131
|
```
|
|
142
132
|
|
|
143
|
-
聊天仍须使用会话作用域及目标项目、线程上下文。`--task` 只查表,不自动分类、切档或发模型请求;不传时返回原等级基线。类型与等级不匹配会被拒绝;明确请求但快照未配置时返回 `TASK_ROUTE_NOT_CONFIGURED
|
|
133
|
+
聊天仍须使用会话作用域及目标项目、线程上下文。`--task` 只查表,不自动分类、切档或发模型请求;不传时返回原等级基线。类型与等级不匹配会被拒绝;明确请求但快照未配置时返回 `TASK_ROUTE_NOT_CONFIGURED`,不能借用包内新值或自行拼组合。已部署快照缺少候选时,先预览并更新配置再查询;基础规则更新后需重启。
|
|
144
134
|
|
|
145
|
-
每级可选 `tasks`,键为上表类型,每项完整包含 `model`、`effort`、`fallback`(可为 null)。复制档位、三层作用域和任务快照均保留候选;单级 CLI 配置只改基线,候选通过整表 JSON 或网页“任务候选 JSON”编辑,`{}`
|
|
135
|
+
每级可选 `tasks`,键为上表类型,每项完整包含 `model`、`effort`、`fallback`(可为 null)。复制档位、三层作用域和任务快照均保留候选;单级 CLI 配置只改基线,候选通过整表 JSON 或网页“任务候选 JSON”编辑,`{}` 清空本级候选。三个专长候选各带有通用备用组合;latency 仍须独立显式配置,不能凭模型名承诺低延迟。
|
|
146
136
|
|
|
147
137
|
三个作用域的复制内容均与同一作用域下 `mode show <源档位>` 显示的完整定义一致。源档位对应已部署快照时复制该快照;旧快照没有的候选不会因复制而自动加入。
|
|
148
138
|
|
|
149
|
-
候选使用自己的备用。质量升级可以在原 L3/L4 中由 uncertain
|
|
139
|
+
候选使用自己的备用。质量升级可以在原 L3/L4 中由 uncertain 的旗舰模型/low 转向 reasoning 的旗舰模型/medium;先证实推理不足,继续沿用原快照、职责与验收,计入同一任务最多三次委派。不能用故障备用代替质量升级,也不自动转到更高强度。
|
|
150
140
|
|
|
151
141
|
当前档位的手动主模型检测同时覆盖基线和任务候选,按组合去重、排除备用,确认框列出数量。配置、切档、查询与账号页面仍不自动检测。
|
|
152
142
|
|
|
@@ -164,146 +154,84 @@ agent-fit explain --level L4 --role task_review
|
|
|
164
154
|
|
|
165
155
|
详细查询分开呈现已配置值、预设值、潜在覆盖与运行未验证。检查相关项目及祖先目录,不扫描全电脑;不输出账号凭据、私有指令、完整 TOML 或认证记录。范围外注册路径与未确定的 profile 只报告候选及未检查原因,不跟随任意文件。
|
|
166
156
|
|
|
167
|
-
`explain --mode MODE` 查询非活动档位或在未安装时预览,只返回候选组合,不改变已部署角色;派发角色统一为 `task_delegate`,获授权评估时显式传入候选 model/effort
|
|
157
|
+
`explain --mode MODE` 查询非活动档位或在未安装时预览,只返回候选组合,不改变已部署角色;派发角色统一为 `task_delegate`,获授权评估时显式传入候选 model/effort 并保留原权限契约。省略 --scope 的全局查询仅在固定角色组合匹配且不是 L4 时返回固定角色;显式作用域查询统一使用 task_delegate。
|
|
168
158
|
|
|
169
159
|
同一档位重复切换不重写、不提醒重启;普通切档及当前自定义定义更新也不要求重启。仅保存非活动定义不激活该档位。配置版本或格式不匹配时,读取与写入都会被拒绝,不做自动转换。
|
|
170
160
|
|
|
171
161
|
无需全局安装的 npm 查询,以及本地包查询:
|
|
172
162
|
|
|
173
163
|
```sh
|
|
174
|
-
npm exec --package="/path/to/fanglinwei-agent-fit-0.
|
|
164
|
+
npm exec --package="/path/to/fanglinwei-agent-fit-0.9.0.tgz" -- agent-fit status --details
|
|
175
165
|
```
|
|
176
166
|
|
|
177
167
|
## 委派收益检查
|
|
178
168
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
收益可以来自模型适配、独立判断、上下文隔离或缩短总耗时。开销包含启动、上下文交接、等待、汇总、验证与返工。估算采用已有观测或保守值,未知开销不算零;不为估算额外调用模型,不用模型名称推断账单。收益不明确而主代理具备能力时继续本地完成;必要能力、证据或前提缺失时保留原验收并报告受影响部分。
|
|
169
|
+
主代理先核对委派授权,再比较直接完成、工具并行和子代理委派。计入启动、交接、等待、汇总、验证与返工;收益不明确时由主会话完成。工具并行不能替代独立复核,项目要求的独立复核仍须满足。
|
|
182
170
|
|
|
183
|
-
|
|
171
|
+
收益判断与并行约束由 [Skill 的委派收益检查](../adapters/codex/skills/agent-fit/SKILL.md#委派收益检查)统一规定。CLI 不测量收益、不派发任务;没有对照测量不宣称实际加速。
|
|
184
172
|
|
|
185
|
-
|
|
186
|
-
| --- | --- |
|
|
187
|
-
| 两个已知文件各读 3 秒,子代理交接需 35 秒 | 独立读取可直接工具并行,由主会话判断;换模型不足以抵消交接成本 |
|
|
188
|
-
| 两项独立调查各 90 秒,串行预计 180 秒;两个空闲槽,每名代理启动 40 秒,另需交接 35 秒、汇总 25 秒、验证 20 秒 | 委派预计 40 + 90 + 35 + 25 + 20 = 210 秒;只有提速诉求时由主会话完成 |
|
|
189
|
-
| 45 秒的复核需 60 秒交接,但项目要求独立复核 | 保留独立复核,按原职责派发;无法执行则报告阻塞,不用作者自查替代 |
|
|
190
|
-
| 两项独立研究各 8 分钟,委派总开销约 1 分钟且有两个空闲槽 | 委派预计约 9 分钟,对比串行约 16 分钟,有明确余量;同模型也可获得并行收益 |
|
|
173
|
+
拆分针对上下文、并行、独立验证、权限或能力与成本约束,不按岗位凑齐角色。主会话配合工具和按需加载的 Skills 足以完成时无需拆分;明确委派和强制独立复核的原要求仍保留。交接提供自包含任务、可访问的权威材料和验收,审查不以作者结论为前提,回传精炼结论及可复核证据;完成即返回,复用须有上下文收益且满足原独立性要求,细节见[派发模板](../adapters/codex/skills/agent-fit/references/dispatch-contract.md)。
|
|
191
174
|
|
|
192
|
-
|
|
175
|
+
上下文、文件和权限隔离分别核实:新线程或 `fork_turns="none"` 不自动创建独立工作树或受限沙箱,也不能保证独立判断。指令限制不等于环境强制隔离;缺少所需隔离时停止受影响部分,不能借此扩大权限。
|
|
193
176
|
|
|
194
177
|
## 任务等级与委派职责
|
|
195
178
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
复杂度与职责由主代理判断,配置查表与 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#配置查询与失败分流) 处理;静态结果不证明实际运行身份或可用性。
|
|
199
|
-
|
|
200
|
-
| 等级 | 判定依据 | 不足以单独升级的因素 |
|
|
201
|
-
| --- | --- | --- |
|
|
202
|
-
| L1:明确执行 | 方法、输入和验收已知,几乎不需要选择方案 | 文件多、文本长、重复步骤多 |
|
|
203
|
-
| L2:有边界的推理 | 目标与验收明确,需要局部分析或有限方案选择 | 开发、调试、审查等职责名称 |
|
|
204
|
-
| L3:复杂推理 | 相互影响的约束、竞争假设或矛盾证据需要权衡 | 单纯多步,或要求执行者独立 |
|
|
205
|
-
| L4:高不确定性推理 | 关键假设尚未建立,需要构造并检验多条解释,或处理强耦合的开放问题 | 缺少资料、凭据或环境不通;这些情况先补前提 |
|
|
206
|
-
|
|
207
|
-
高影响且缺乏可靠验收时采用至少 L3 的本地保障下限,说明复杂度与保障调整各自的理由;这不是经过实测的能力保证。易于确定验收的机械任务可保留 L1。所选组合仍须满足实际能力和原验收,独立或专业验证遵循原任务要求;更强模型不能替代必要证据。
|
|
208
|
-
|
|
209
|
-
| 任务等级 | cut(经济) | official(官方) | high(高级) | fire(全开,验证通过后) |
|
|
210
|
-
| --- | --- | --- | --- | --- |
|
|
211
|
-
| L1:明确执行 | Luna / high | Luna / high | Luna / max | Astra / ultra |
|
|
212
|
-
| L2:有边界的推理 | Luna / high¹ | Sol 6.1 / medium | Sol 6.1 / ultra | Astra / ultra |
|
|
213
|
-
| L3:复杂推理 | Sol 6.1 / medium | Sol 6.1 / high | Astra / ultra | Astra / ultra |
|
|
214
|
-
| L4:高不确定性推理 | Sol 6.1 / high | Sol 6.1 / xhigh | Astra / ultra | Astra / ultra |
|
|
215
|
-
|
|
216
|
-
L1–L4 是任务需求,cut/official/high/fire 是资源策略。相邻等级共用组合有效:cut 的 L1/L2、high 的 L3/L4、fire 的全部等级相同,不能据此宣称存在四档实际能力。¹ cut 的 L2 仅用于容易核验的产出,复杂部分提高等级。model 与 effort 含义不同,但执行时使用配置中的完整组合,不临时拼接;跨模型同名 effort 不证明等效,更高 effort 也不保证更合适。
|
|
217
|
-
|
|
218
|
-
完整 id:`gpt-6-luna`、`gpt-6.1-sol`、`gpt-6-astra`;备用另使用 `gpt-6-sol`。名称不证明价格、能力或账号权限。高影响结果需要独立证据与专业验证。
|
|
219
|
-
|
|
220
|
-
`official` 是依据 [OpenAI 官方建议](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning) 制定的本地映射,官方没有固定 L1–L4 表。`high` 各模型使用最高受支持的 effort;预设写入不证明账号可调用。
|
|
221
|
-
|
|
222
|
-
`fire` 每个会话首次委派前须实际验证 Astra/ultra,并核对可信运行 metadata 与当前会话上下文。模型、effort、供应商或账号变化后重验,不保存跨会话验证缓存。目录查询和口头确认不能代替验证;`models check --verify` 通过独立 Responses 请求验证,不启动 Codex 任务线程或工具执行器。
|
|
223
|
-
|
|
224
|
-
检查失败、未完成或最高组合不可用时,使用用户明确指定的模型与推理强度;未另行指定时继承父代理当前实际组合。通过 `task_delegate` 保留原职责,并核对全局子代理默认与角色覆盖;无法确认父代理组合时阻断该委派。不自动切换 high,不绕过原预算、能力和权限规则。fire 的继承备用是运行时选择,静态 fallback 为 null。
|
|
225
|
-
|
|
226
|
-
四个职责:
|
|
179
|
+
L1–L4 表示推理需求,职责限定允许的动作。主代理判定等级与职责,CLI 只查配置;高影响且缺乏可靠验收时采用至少 L3 的保障下限,必要材料、工具和证据仍须满足。
|
|
227
180
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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 |
|
|
232
187
|
|
|
233
|
-
|
|
188
|
+
上表使用用途,具体模型以绑定 home 的 `mode show` 或 `explain` 为准。cut/L2 面向易核验产出,复杂部分提高等级。相邻等级可共用组合;跨模型同名 effort 不证明等效,模型名称不证明能力、价格或权限。`official` 是依据[官方建议](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning)制定的本地映射,官方没有固定 L1–L4 表。
|
|
234
189
|
|
|
235
|
-
|
|
|
236
|
-
| --- | --- |
|
|
237
|
-
|
|
|
238
|
-
|
|
|
239
|
-
|
|
|
240
|
-
|
|
|
241
|
-
| 多机制交互且关键假设未知,需要构造与检验多条解释 | L4;若缺少必需材料,先补前提 |
|
|
242
|
-
| 操作机械但涉及权限边界,错误后果高且缺乏可靠验收 | 说明复杂度可能为 L1,因保障下限采用至少 L3;无法满足原验收时补前提或阻断 |
|
|
190
|
+
| 职责 | 允许范围 | 固定绑定 |
|
|
191
|
+
| --- | --- | --- |
|
|
192
|
+
| `task_scan` | 只读取证 | L1 |
|
|
193
|
+
| `task_execute` | 明确独占范围内产出 | L2 |
|
|
194
|
+
| `task_review` | 独立复核 | L3 |
|
|
195
|
+
| `task_delegate` | 保留原请求职责 | 无固定 model/effort |
|
|
243
196
|
|
|
244
|
-
|
|
197
|
+
固定组合不匹配、L4、用户指定或继承时使用 task_delegate。作用域查询也统一返回 task_delegate,显式传 model/effort 与 `fork_turns="none"`,完整交接;省略参数不证明继承。
|
|
245
198
|
|
|
246
|
-
|
|
199
|
+
`high/fire` 的最高强度须经明确选档授权。fire 每会话先验证实际调用、可信身份及上下文匹配,模型/effort/账号/供应商变化后重验;独立 CLI passed 不能单独放行。失败时仅使用用户指定组合,否则继承已确认的父代理实际组合,不能自动切 high。
|
|
247
200
|
|
|
248
|
-
|
|
201
|
+
分级、快照、能力检查与权限的完整合同见 [Skill](../adapters/codex/skills/agent-fit/SKILL.md),交接字段见[派发模板](../adapters/codex/skills/agent-fit/references/dispatch-contract.md)。
|
|
249
202
|
|
|
250
203
|
## 组合校准
|
|
251
204
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
先由主代理预检本次涉及的配置查询、JSON 封套与职责契约,再进入模型候选评估;预检不发模型请求,查询故障不记为候选能力失败。分级规则核验检查“等级判断是否一致”;组合能力评估检查“实际任务是否通过原验收”,三者不能互相替代。优先比较不同的 model + effort,不对 high 的 L3/L4 或 fire 的相同组合重复计费。范围用于限定职责与上下文;时延要求只在满足质量的候选间取舍,不对任务信号强制打分。
|
|
255
|
-
|
|
256
|
-
分级边界核验分别记录任务本身复杂度、保障后的拟采用等级、是否需先补前提及理由;被测上下文不手工猜模型组合,主代理再用 CLI 取值。输入和预期分开冻结,覆盖文件数、职责名称、时限等干扰;同一批案例不算多次独立重复,未发现违规证据时保留原分级与默认映射。
|
|
257
|
-
|
|
258
|
-
结果按请求组合与可信运行 metadata 分别记录;运行身份未验证时,模型归因标 PARTIAL。保留全部首次尝试、失败和未知项,批量子问题不冒充独立重复样本,缺失耗时或资源证据不能填零。先核对质量,再比较返工、端到端耗时和可信资源用量;较强模型调用比例不等于验收通过率。只有证据稳定并在独立样本复核后,才按用户授权保存自定义档位;样本不足保留原映射。
|
|
205
|
+
预设映射仍需按任务验收。用户要求评估或调优时,按[离线校准指南](../adapters/codex/skills/agent-fit/references/calibration.md)冻结输入、候选、预算与独立预期,分别验证配置契约、分级判断和实际产出。保留首次失败及未知项,运行身份未核验时模型归因标 PARTIAL。
|
|
259
206
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
任务信号借鉴 [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
|
+
先比较质量,再比较返工、端到端耗时与可信资源用量;批量子问题不算独立重复,较强模型调用比例不等于验收通过率。日常任务不自动对照、采集账本或修改默认映射,普通切档也不以追加评测为前提。
|
|
263
208
|
|
|
264
209
|
## 职责与模型一致性检查
|
|
265
210
|
|
|
266
|
-
`
|
|
267
|
-
|
|
268
|
-
| 角色 | 核对要求 |
|
|
269
|
-
| --- | --- |
|
|
270
|
-
| `task_scan` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L1 |
|
|
271
|
-
| `task_execute` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L2 |
|
|
272
|
-
| `task_review` | 文件名与 `name` 对应,model 和 effort 均匹配当前 L3 |
|
|
273
|
-
| `task_delegate` | 文件名与 `name` 对应,必须同时省略 model 和 effort;预期等级与组合为 `null`,实际继承仍需宿主证据 |
|
|
274
|
-
|
|
275
|
-
任一项不匹配时,已安装 home 的诊断返回 `ROLE_CONTRACT_MISMATCH`,完整性标为 `drifted`,配置写入在覆盖前停止。该语义检查独立于文件摘要检查;它不会自动修复用户修改。原有文件漂移、注册路径冲突、符号链接与恢复保护继续适用,`restore` 仍须通过原有恢复条件。
|
|
276
|
-
|
|
277
|
-
开发测试以 `ROLES` 为本工具的职责登记源,双向核对发布资产中的角色 TOML 与 `assets/codex/config.toml` 注册表,包含嵌套目录中的多余定义,并检查官方初始模板显式设置两个模型参数;所有档位生成时继续使用各自的组合。这借鉴 [Castwright 的角色、模型和 effort 对应检查](https://github.com/dudarenok-maker/Castwright/blob/main/.claude/skills/model-routing/SKILL.md),只约束本工具发布的四个角色,不要求用户将其他自定义角色纳入本工具登记。
|
|
211
|
+
`status --details --json` 的 `roles` 并列返回预期等级、model/effort 与磁盘配置。`matches_mode` 核对文件可解析、名称正确及组合匹配;task_delegate 必须同时省略 model 和 effort。未安装时该值为 null。
|
|
278
212
|
|
|
279
|
-
|
|
213
|
+
不匹配返回 `ROLE_CONTRACT_MISMATCH`,已安装 home 标为 drifted,写入在覆盖前停止;摘要、路径、符号链接和恢复保护继续适用,不自动修复用户修改。磁盘一致不证明实际模型、账号权限或职责已执行。
|
|
280
214
|
|
|
281
215
|
## 备用与模型不可用
|
|
282
216
|
|
|
283
217
|
| 档位 | L1 备用 | L2 备用 | L3 备用 | L4 备用 |
|
|
284
218
|
| --- | --- | --- | --- | --- |
|
|
285
|
-
| cut
|
|
286
|
-
| official
|
|
287
|
-
| high
|
|
288
|
-
| fire
|
|
219
|
+
| cut | 通用用途/medium | 通用用途/medium | 通用备用用途/medium | 通用备用用途/high |
|
|
220
|
+
| official | 通用用途/medium | 通用备用用途/medium | 通用备用用途/high | 通用备用用途/xhigh |
|
|
221
|
+
| high | 通用用途/high | 通用备用用途/ultra | 通用用途/ultra | 通用用途/ultra |
|
|
222
|
+
| fire | 用户指定,否则继承父代理 | 同左 | 同左 | 同左 |
|
|
289
223
|
|
|
290
|
-
cut
|
|
224
|
+
候选使用自己的备用,主代理从原任务完整快照取值。已选择的 cut/official/high 或自定义档位,在授权、预算、能力和宿主均允许时可使用本级非空 fallback;仅保存或预览不算选择,null 不借用其他档位。用户锁定模型或禁止备用优先。
|
|
291
225
|
|
|
292
|
-
|
|
226
|
+
认证、权限、额度、账单及未知原因停止受影响路径;模型不可用、effort 不支持或有限重试后的临时故障才按条件接续。初次、重试、质量升级及备用共用每任务最多三次委派,同组合最多额外一次,累计重试等待不超过 30 秒并遵守 Retry-After;宿主重试未知时不叠加,拆分不重置。
|
|
293
227
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
Astra 不可用:先区分认证、权限、额度、临时故障或能力不支持。允许备用且全部条件满足才用当前档位的候选,fire 使用用户指定组合,否则继承父代理;用户强制只用 Astra、预算不允许或旧 worker 停止未知时,受影响部分 BLOCKED,继续其他独立工作。缺资料或工具故障先补前提,不能靠强模型掩盖。
|
|
297
|
-
|
|
298
|
-
每任务最多三次父代理发起的委派,同一组合最多额外一次;拆分困难部分不重置计数。累计重试等待不超过 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)。
|
|
299
229
|
|
|
300
230
|
## 验收失败与质量升级
|
|
301
231
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
比较实际 model + effort,相邻等级组合相同不重派;可核对下一不同组合,但自定义高等级不保证能力更强。high 的 L3→L4 与 fire 的升等级都没有实际组合提升,无适合候选时报告上限。若有新证据或具体方法修正,可以在余量内重试原组合,并如实称为重试;不机械地先加 effort 或先换模型。
|
|
232
|
+
请求成功但产出未达原验收时,先指出可复核失败,再区分前提缺失、方法遗漏和推理不足。前提先补齐;有限重试或质量升级使用原任务快照,保留职责、验收、预算与累计次数,不能用可用性 fallback 代替升级。
|
|
305
233
|
|
|
306
|
-
|
|
234
|
+
比较实际 model + effort;相同组合改等级或标签不算升级。写入者停止未知、次数耗尽、组合被锁定或无合适候选时停止受影响委派,报告 PARTIAL/BLOCKED 并继续独立工作。完整条件见[质量升级](../adapters/codex/skills/agent-fit/references/failure-policy.md#质量升级)。
|
|
307
235
|
|
|
308
236
|
## 自定义档位
|
|
309
237
|
|
|
@@ -340,11 +268,11 @@ JSON
|
|
|
340
268
|
|
|
341
269
|
最高 64 KiB UTF-8 JSON;必须明确全部等级与备用/null;每级可选 tasks,候选也须完整提供 model、effort 和 fallback/null,拒绝未知字段、无效类型/等级、缺级、半对参数或主备用相同。与单级参数互斥。活动定义与部署角色同一事务保存;非活动定义只保存,不激活。
|
|
342
270
|
|
|
343
|
-
###
|
|
271
|
+
### 专长路线
|
|
344
272
|
|
|
345
|
-
|
|
273
|
+
cut/official 的 visual/computer/writing 使用同一专长用途,L1 low、L2 medium、L3 high;故障备用为通用模型 medium、medium、high。high/fire 按原高强度策略处理这三类任务,L4 不提供专长路线。
|
|
346
274
|
|
|
347
|
-
先确定复杂度与保障要求,再核对主要工作是否属于专长、关键事实和约束是否已知、结果是否可核验。开放研究、强耦合或高后果且难验收的任务仍使用基线或 uncertain/reasoning
|
|
275
|
+
先确定复杂度与保障要求,再核对主要工作是否属于专长、关键事实和约束是否已知、结果是否可核验。开放研究、强耦合或高后果且难验收的任务仍使用基线或 uncertain/reasoning;含有图片或产出文章不足以选择专长候选。电脑操作仍须原工具与写入授权,不能扩大只读职责。
|
|
348
276
|
|
|
349
277
|
```sh
|
|
350
278
|
agent-fit explain --level L1 --task visual --role task_scan --json
|
|
@@ -354,22 +282,19 @@ agent-fit explain --level L3 --task writing --role task_review --json
|
|
|
354
282
|
|
|
355
283
|
聊天中补齐 Skill 要求的 session、project 与 thread 参数。已有自定义定义和任务快照不自动合并新候选;可从当前内置定义创建新档位,或通过完整定义编辑。配置与规则同步后重启一次 Codex,随后按新任务查询;不需要先追加模型评测。
|
|
356
284
|
|
|
357
|
-
###
|
|
285
|
+
### 模型绑定与换代
|
|
358
286
|
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
以下命令在包根目录执行。先替换 home、项目及目标聊天 ID;只创建、保存和预览会话自定义档位,不执行 mode set,不修改当前选择。导入的是完整冻结定义,不与本机已有配置逐字段合并。
|
|
287
|
+
内置策略在 [modes.json](../adapters/codex/modes.json) 中引用用途别名,包内默认模型 id 集中在 [model-bindings.json](../adapters/codex/model-bindings.json)。同用途换代无需改写策略或更新共享 Skill。五种用途为 `economy`(经济)、`general`(通用)、`general_backup`(通用备用)、`frontier`(旗舰)、`visual_work`(视觉、电脑操作和写作)。
|
|
362
288
|
|
|
363
289
|
```sh
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
agent-fit mode create "Terra 评估" --from official --scope session --codex-home "$evaluation_home" --project "$evaluation_project" --thread "$evaluation_thread"
|
|
368
|
-
agent-fit mode configure "Terra 评估" --definition-stdin --scope session --codex-home "$evaluation_home" --project "$evaluation_project" --thread "$evaluation_thread" < adapters/codex/profiles/terra-evaluation.json
|
|
369
|
-
agent-fit explain --mode "Terra 评估" --level L2 --task bounded --role task_execute --scope session --codex-home "$evaluation_home" --project "$evaluation_project" --thread "$evaluation_thread" --json
|
|
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"
|
|
370
293
|
```
|
|
371
294
|
|
|
372
|
-
|
|
295
|
+
从目录选定具体 id 后,预览会列出每个受影响档位、等级或任务类型的主选和备用变更;令牌对应这个 home、当前配置和这份变化。确认模型能力、预算及变化范围后,用预览返回的令牌应用(JSON 字段 `data.model_binding.preview_token`)。应用会重新查目录;配置有变化、目录未完成,或新组合不在可见目录及支持的 effort 中,均不会写入。不会自动晋升新模型、调整 effort 或调用推理。自定义供应商的目录不提供 effort,不能用于此命令;需要时可直接保存自定义档位中的具体组合。
|
|
296
|
+
|
|
297
|
+
更新存入绑定 home 的 `.agent-fit/model-bindings.json`,覆盖包内默认绑定。该 home 后续所有作用域的内置档位使用更新后的组合;当前全局内置档位如受影响,其快照和角色配置一并更新。已开始任务、自定义档位和其他 home 的组合不变。需要撤销某条绑定时,用原模型 id 重新预览并应用。模型目录不证明能力或实际调用;`fire` 仍须按新组合重新验证。
|
|
373
298
|
|
|
374
299
|
### 配置与模型检查分开执行
|
|
375
300
|
|
|
@@ -403,7 +328,7 @@ agent-fit models check --verify
|
|
|
403
328
|
agent-fit models check --verify --discover
|
|
404
329
|
```
|
|
405
330
|
|
|
406
|
-
|
|
331
|
+
日常配置操作不附带账号或模型检查;显式检查、绑定预览与应用会查询所选 home 的目录。
|
|
407
332
|
|
|
408
333
|
检查通过 stdio app-server 在空临时目录读取当前 home 的账号与生效配置,无认证刷新参数、无项目加载,不输出原始 RPC、stderr、邮箱、账号 ID 或凭据。官方默认上下文的目录使用 Codex `model/list`,最多 100 页,单帧 1 MiB、总接收 8 MiB。第三方供应商或自定义 API 地址使用同一供应商的 `GET /models` 获取候选,不使用 Codex 目录补齐。沿用同一配置的地址、请求头、查询参数和授权,最多 1000 个候选、响应最多 2 MiB;只保留模型标识,不猜测推理强度。当前支持完整单页列表;有后续分页会明确标记未完成并停止批量验证。目录整轮共享 30 秒期限。自定义供应商的空账号不直接判无权限。
|
|
409
334
|
|
|
@@ -436,23 +361,22 @@ agent-fit serve --codex-home "/path/to/codex-home" --open
|
|
|
436
361
|
agent-fit serve --port 17321
|
|
437
362
|
```
|
|
438
363
|
|
|
439
|
-
|
|
364
|
+
仅监听 `127.0.0.1`,默认端口 0 自动分配,也可指定 1024–65535;占用即失败。`--open` 失败时复制终端 URL。Ctrl+C 等待正在执行的 CLI 安全完成后停止服务。home、项目和可选线程在启动时绑定,换上下文需重新启动。
|
|
440
365
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
档位页的“检测当前档位主模型”由用户点击并确认后触发,使用已保存且设为当前的档位,按 model/effort 去重检测 L1–L4 基线及同级任务候选,实际调用次数由去重后的组合数量决定,备用不参与。未安装、查看非当前档位、有未保存草稿、授权切换中或其他操作执行时禁用。确认框展示档位、完整组合、次数与费用提示,取消不发请求;保存、激活、刷新与重新设置均不自动触发检测。
|
|
366
|
+
| 页面 | 操作 |
|
|
367
|
+
| --- | --- |
|
|
368
|
+
| 档位 | 编辑草稿后保存或应用;候选 JSON 随整表事务提交 |
|
|
369
|
+
| 委派规则 | 展示有效来源、四级基线和候选;点击查询依据、备用及权限,其他档位为只读预览 |
|
|
370
|
+
| 账号配置 | 管理已有授权、登录、取消和退出;不展示模型目录或历史 |
|
|
371
|
+
| 恢复 | 预览并撤销整个 home 的安装,包含全部作用域 |
|
|
448
372
|
|
|
449
|
-
|
|
373
|
+
“检测当前档位主模型”需点击确认,可能产生费用。仅检测当前已保存档位的基线与候选,按 model/effort 去重,排除备用;未安装、非当前档位、有草稿、授权切换中或其他操作执行时禁用。确认框列出组合与次数,取消零请求;配置操作不自动检测。
|
|
450
374
|
|
|
451
|
-
|
|
375
|
+
检测使用 `models check --verify --expect-revision REV`。配置、来源或授权变化后旧结果失效;可调用、响应身份与 fire 会话验证分别报告,详见[模型检查](#模型检查)。
|
|
452
376
|
|
|
453
|
-
|
|
377
|
+
配置、规则与恢复动作仅执行白名单 CLI,账号页使用官方 RPC;不执行任意 shell。接口校验 Host/Origin、会话 Cookie 与 CSRF token,使用 CSP;不开放远程监听或 CORS。桌面侧栏、手机顶部导航,详情和变更确认随屏宽排列。
|
|
454
378
|
|
|
455
|
-
|
|
379
|
+
版本冲突保留草稿且零写入,先“刷新后比较”再保存。断线或结果未知时先刷新,不自动重试写操作;查询失败不保留旧解释。草稿仅在内存,页面关闭可能丢失;取消草稿不会删除已创建的档位。
|
|
456
380
|
|
|
457
381
|
## JSON、退出码与冲突
|
|
458
382
|
|
|
@@ -523,4 +447,4 @@ npm pack
|
|
|
523
447
|
PLAYWRIGHT_MODULE=/path/to/playwright CHROME_PATH=/path/to/chrome npm run test:browser
|
|
524
448
|
```
|
|
525
449
|
|
|
526
|
-
|
|
450
|
+
已有验收记录与未覆盖范围见[验证范围](implementation-review.md)。历史校准材料不随 npm 包交付,不代表当前安装或发布状态。
|
package/lib/codex.mjs
CHANGED
|
@@ -11,8 +11,29 @@ export const ROLES = { task_scan: 'L1', task_execute: 'L2', task_review: 'L3', t
|
|
|
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
|
-
|
|
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 = [...
|
|
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 };
|