omp-opsx-addon

Pi Extension: OpenSpec workflow orchestration — coder/reviewer/planner agents, session title & progress.

---

架构

┌─────────────────────────────────────────────────────────┐
│  主 agent (Orchestrator)                                 │
│  system prompt 由 plugin 注入: model 选择决策 + 路由表    │
│                                                          │
│  用户说 "@coder 实现 X" → transform 成 task 委派指令      │
└───────────────────────┬─────────────────────────────────┘
                        │
                ┌───────▼────────┐
                │  omp 内置 task  │
                │ (所有 role)     │
                │  原生 subagent  │
                └───────┬────────┘
                        │
               ┌────────┴──────────┐
               │ .omp/agents/      │
               │ coder / planner   │
               │ code-reviewer /   │
               │ proposal-reviewer │
               └───────────────────┘

核心机制：主 agent 用 omp 内置 task 工具委派所有 4 个角色。model 选择由插件自动完成，不再有 acpx（外部 agent）路径。

---

Dispatch 配置 (opsx.yml)

两层 opsx.yml（全局 ~/.omp/agent/opsx.yml + 项目 <cwd>/.omp/opsx.yml，项目逐键覆盖全局）。

# role 值可以是：
#   'auto'                       — 插件按 tier + usage 自动选 model
#   'smol' / 'slow' / 'default'  — OMP role alias（由 OMP modelRoles 解析）
#   'gpt-5-pro'                  — 明确 model id
#   'anthropic/claude-opus-4-6'  — provider/model 完全限定

coder: auto
reviewer: slow
planner: slow
proposal-reviewer: default

# 可选：限制自动选择时使用的 model 池
model_allowlist:
  - "anthropic/claude-opus-*"
  - "openai/gpt-5*"

# 可选：自定义 tier 评分
tiers:
  - pattern: "*opus*"
    tier: top
  - pattern: "openai/gpt-4o-mini"
    tier: low

# 可选：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

---

Model 选择

插件启动时从 ModelRegistry.getAvailable() 拿所有有鉴权的 model，从 authStorage.fetchUsageReports() 拉用量报告，然后按 role → tier 期望 + 用量健康度自动选最优 model。

决策日志打印到 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 档选图像模型）。 保守配置示例：

  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 钉值，但不改动你的配置文件。

---

开发

npm run typecheck
bun test