@genee/omp-opsx-addon 0.3.0 → 0.5.0

package/README.md

@@ -63,6 +63,15 @@ tiers:
 # 可选：role → tier 期望
 role_tiers:
   planner: top
+
+# 可选：OMP 内置/自定义 model role → tier 期望（或 skip 排除）
+# 仅影响 /pick-model 后 session 覆盖写入哪些模型；合法值 tiny/low/mid/high/top/skip
+model_role_tiers:
+  advisor: skip
+  plan: skip
+  tiny: skip
+  vision: skip   # vision 固定 high 档候选，仅 skip 有效（见下文）
+  task: low
 ```
 
 ---
@@ -73,6 +82,79 @@ role_tiers:
 
 决策日志打印到 stderr：`[omp-opsx-addon] planner → anthropic/claude-opus-4-6 (tier=top, gap=0, remaining=0.80)`
 
+
+### 子 agent 模型落点：session-scoped modelRoles
+
+`/pick-model <selector>` / `refresh` / `reset` 应用选择结果时，插件**不**再按 agent 名写
+`task.agentModelOverrides`，而是写 OMP session 运行时覆盖
+`settings.overrideModelRoles({ …全 role… })`——覆盖**宿主当前已知的全部 model role**
+（10 个内置 role + 自定义 role：`getKnownRoleIds` 从 cycleOrder/modelRoles/modelTags 汇总）：
+
+- 每个 role 跟随一个 tier 的选中模型；同一 tier 的多个 role 共用同一个模型（同候选集
+  排序结果唯一）。mid/high 复用 opsx 4 role 的选择（coder→mid、reviewer→high），
+  tiny/low/top 在同一过滤候选集上补选。
+- **内置 role 默认 tier 映射**：
+
+  | role | tier | 触发场景 |
+  | --- | --- | --- |
+  | `tiny` | tiny | 极小任务 |
+  | `smol` | mid | scout 等快速任务 |
+  | `task` | mid | task 工具委派的全能力子 agent（与 scout 同档，防能力倒挂） |
+  | `commit` | low | AI commit |
+  | `default` | high | 主会话 / reviewer |
+  | `designer` | high | designer agent |
+  | `vision` | high | `/vision`、图像输入（**能力门控**，见下） |
+  | `slow` | top | 深度思考 |
+  | `plan` | top | plan mode |
+  | `advisor` | top | advisor 会话 |
+
+  **激活语义**：advisor/plan/tiny 等默认未配置的 role 被写入覆盖后，**只在对应功能真正
+  触发时**（plan mode、advisor 会话、auto-thinking、AI commit、`/vision`）才会解析到
+  selector 模型；功能不触发就不产生消耗。覆盖 session 结束即还原。
+- **自定义 role**（cycleOrder/modelTags 里出现、不在内置表中的 role）默认跟随 `high`，
+  并一次性 warn 提示可用 `model_role_tiers` 调档或排除。
+- **`model_role_tiers`（opsx.yml）**：OMP role 名 → `tiny/low/mid/high/top` 或 `skip`，
+  覆盖上表默认值；自定义 role 也可配。`skip` 是唯一逃生舱——该 role **不写** session
+  覆盖、保留你的 config 值（默认策略是全量覆盖，包含 config 里的 `modelRoles.*` 钉值，
+  不做「自动跳过钉值」）。**例外：`vision` role 固定使用 high 档候选**（仅在具备 image
+  能力的模型中挑选，见下条），`model_role_tiers.vision` **仅 `skip` 生效**——配
+  `top/low/…` 等其他 tier 值会被静默接受但**不改变其选档**（仍按 high 档选图像模型）。
+  保守配置示例：
+
+  ```yaml
+  model_role_tiers:
+    advisor: skip   # 不想让 advisor 会话走 selector 模型
+    plan: skip      # plan mode 保留 config 钉值
+    tiny: skip      # 无 tiny 档模型时避免回落
+    vision: skip    # 不覆盖 vision（vision 固定 high 档选图像模型，仅 skip 有效）
+    task: low       # 显式降档
+  ```
+
+- **vision 能力门控**：vision 候选**固定按 high 档**、只从声明 `input` 含 `image` 的模型
+  中挑选（不按 `model_role_tiers.vision` 的 tier 值选档，该键仅 `skip` 有效）；当前选择里
+  没有图像模型时，vision role **不写覆盖**（warn 汇总为 `vision(capability)`，绝不写入
+  纯文本模型），vision 功能回落 config/default。恢复手段：换一个含图像模型的 selector
+  或用 `model_allowlist` 纳入图像模型；**`model_role_tiers.vision` 改 tier 绕不过门控、
+  也不改选档**。
+- **auto role 的 agent 定义**在 `.omp/agents/*.md` frontmatter 注入带引号的 tier alias
+  （coder `model: "@smol"`，其余三者 `model: "@default"`）；task 工具经 modelRoles 解析。
+- 因此**所有经 role 解析的 agent 都跟随切换**——包括插件未枚举的 OMP 内置/bundled/
+  project agent（例如内置 scout 走 `smol`，`/pick-model` selector/refresh/reset 后
+  scout 自动换到选中模型）。
+- auto role 与 omp-alias（如 `slow`，值无 `/`）的 dispatch 提示词**不传 `model=`**，
+  由 frontmatter alias 声明式接管；pinned 具体 provider/model 仍显式传 model，行为不变。
+- 某 tier 补选没有可用模型（候选耗尽/allowlist 全过滤）时，该 tier 的各 role 不写覆盖、
+  warn 汇总（`no-pick`），命令不中断；无任何模型时计划为空，与既有「模型注册表不可用」
+  分支一致。
+- 覆盖为 **session 作用域、不写盘**：`overrideModelRoles` 只写 runtime overlay，
+  session 结束即还原；不会修改你的 `~/.omp/agent/config.yml`。每次应用前先
+  `clearOverride('modelRoles')`，避免上一 selector 的旧 role 值残留；`reset` 重算无约束
+  默认并覆盖（**不清空**，否则回落 config 硬钉）。
+
+> **手动清理建议**：若全局 `~/.omp/agent/config.yml` 里有 `modelRoles.smol` 钉在会耗尽的
+> 套餐模型（scout 会一直打它直到被 session 覆盖压过），或 `task.agentModelOverrides` 残留
+> 已删除的 `tester` 等 key，可手动删除这些钉值；插件运行期间会以 session 空串中和 per-agent
+> 钉值，但不改动你的配置文件。
 ---
 
 ## 开发