Skip to content

Latest commit

 

History

History
438 lines (308 loc) · 47.9 KB

reference.zh.md

File metadata and controls

438 lines (308 loc) · 47.9 KB

opencode-switchman — 完整手册

README · 参考手册(中文) · English Reference

README 刻意保持简短,其余内容都在这里:安装细节、完整配置项表、手动覆盖命令,以及插件的内部工作原理。

目录

安装

一键安装/更新命令见 README,这里是完整版。

前置条件

  • opencode——强烈推荐以 CLI/TUI 为主力界面(插件的操作面——侧栏状态面板、/poolConfig / /modelRank 弹窗、实时横幅——在 TUI 里最完整):建议先用 TUI 完成全部配置,之后可自行选择是否换用桌面端体验;两端共享同一份配置与状态
  • 任意 opencode 供应商均可接入,以下三池额外享有额度控制(可任意组合,全部可选):
    • GitHub Copilot:opencode 内 GitHub 登录(/connect)即可
    • GLM:自定义 provider(zhipuai-coding-plan,baseURL https://open.bigmodel.cn/api/coding/paas/v4 + apiKey)
    • DeepSeek:自定义 provider(deepseek + apiKey)
  • 凭证零配置:插件从 opencode 鉴权层(auth.json / provider options / 环境变量)只读获取,不另存密钥、绝不自行刷新 token

让 AI 替你安装

AI 时代强烈推荐由 AI 自主完成安装配置——AI 能读取你的真实环境、写入正确的值,并自行验证结果,比手动复制粘贴更不容易出错。把下面这段话直接复制给你当前使用的 AI:

请严格按照官方说明为我的 opencode 安装并配置 opencode-switchman 插件。

官方来源(以此为准,不要凭记忆猜测):
- GitHub 仓库:https://github.com/mrzturn/opencode-switchman
- npm 包:https://www.npmjs.com/package/opencode-switchman
请先阅读仓库 README 的「安装」章节,然后严格照做。

步骤:
1. 安装 npm 上发布的最新版本:运行 `npx -y opencode-switchman@latest`(或 `bunx opencode-switchman@latest`),它会把我的 opencode 配置里的 `plugin` 条目改写为精确最新版本(若我用的是项目级 `opencode.json`,它同样适用)。
2. 完成功能配置:插件全部配置都在我 opencode 配置目录下独立的 `opencode-switchman.jsonc` 文件中,首次启动自动生成并带注释;请对照我的 provider(如 `zhipuai-coding-plan` / `deepseek` / `github-copilot`)检查并按需调整。
3. 校验配置正确性、确保 opencode 能正常加载启动运行该插件:在 opencode 内运行 `/switchman-doctor` 出本地脱敏诊断报告并修复所有报错;然后重启 opencode 确认插件确实已加载——日志应出现 `[opencode-switchman] injected N model shells (agents)`,且主模型的系统提示中应带有实时 `[ROUTES]/[WATERMARK]/[LIMITS]` 横幅块。

三个步骤全部通过才算完成;请汇报你做的改动并给出验证证据。

安装 / 更新:一键命令实际做了什么

两条命令均同时覆盖首次安装与后续更新(幂等,可重复执行):自动把 opencode 配置与 tui.jsonc 的 plugin 条目改写为最新精确版本 opencode-switchman@x.y.z(JSONC 注释原样保留)、清理旧插件缓存(~/.cache/opencode/packages/opencode-switchman*),升级场景在横幅标记「已升级待重启」——重启 opencode 后生效。

插件内升级入口 /switchman-update 调用的是同一更新器(旧版直接 npm install 的方式对 opencode 实际加载路径无效)。

为什么条目是精确版本,而不是裸包名 / @latest:opencode ≤1.18.x 的插件缓存按 spec 名固定目录(如 ~/.cache/opencode/packages/opencode-switchman),首次装入后不再向 npm 查询新版本——裸名与 @latest 会一直复用旧缓存(实测从 0.0.1 钉死不升级)。精确版本号每个版本一个独立缓存目录,所以更新器直接改写版本号。

方式:npm 安装(手动)

在 opencode 配置(~/.config/opencode/opencode.json 或项目 opencode.json)中添加:

{
  "plugin": ["opencode-switchman"]
}

opencode 启动时会自动经 Bun 安装并加载该 npm 包,无需其他步骤。后续升级请用上面的「一键更新」,或在 opencode 内执行 /switchman-update。

除插件安装外无需改 opencode 配置:全部插件配置(水位、计费、高峰、阈值、横幅、矩阵、自定义档链等)都在独立文件 opencode-switchman.jsonc 中(见下节),首启自动生成、带注释。旧的元组 options(["opencode-switchman", {...}] 第二项)已弃用,兼容保留一代(显式值仍优先,/switchman-doctor 会提示 SWM044 并建议迁移)。

方式:源码安装

git clone https://github.com/mrzturn/opencode-switchman.git
cd opencode-switchman
bun install
bun run build   # 生成 dist/opencode-switchman.js

然后二选一:

a) 配置引用(推荐,随仓库更新)——在 opencode 配置的 plugin 数组中用 file:// 指向仓库目录:

{
  "plugin": ["file:///absolute/path/to/opencode-switchman"]
}

插件直接加载仓库内的 dist 产物;git pull 后重跑 bun run build 并重启 opencode 即完成升级。此方式与 plugins 目录部署二选一,同时使用会双重注入。

b) 部署单文件——bun run deploy 构建并复制到全局插件目录 ~/.config/opencode/plugins/opencode-switchman.js,自动加载。桌面端内嵌核心跑 Node 运行时,deploy 产出的单文件 bundle 即为此设计。

注意:plugin 数组中的 file:// 引用与 plugins 目录部署不可并存(同名插件会加载两份);发布 npm 后,把 file://... 换成 "opencode-switchman" 即可切换为 npm 安装。重启 opencode 生效。

从旧版(switchman.js)升级:请删除旧的 ~/.config/opencode/plugins/switchman.js,避免新旧两份插件同时注入;状态目录已迁移至 ~/.config/opencode/opencode-switchman/(旧目录可删,全部状态自动重建)。

配置:opencode-switchman.jsonc

除插件安装(opencode 配置的 plugin 数组)外,插件全部配置都在独立文件 opencode-switchman.jsonc——首次启动在 OpenCode 配置目录自动生成(优先级:OPENCODE_CONFIG_DIR、$XDG_CONFIG_HOME/opencode、~/.config/opencode),带 $schema 编辑器提示与逐键注释,坏值 fail-open 回退缺省;改文件后在 opencode 内重跑一次配置(或重启)即生效,/switchman-doctor 可出本地、脱敏且不联网的诊断报告。

providers——供应商策略段:随包内置稳定键 deepseek、zhipuai-coding-plan、github-copilot(与 opencode 官方 provider ID 一致),且任意 opencode 官方/自定义 provider 键均合法——未知键按自定义 provider 处理(通用缺省参与编排;对内置键的近似拼写 doctor 会给 warn 建议)。observe 控制配额查询与横幅展示,enabled 独立控制水位、高峰和耗尽是否参与路由(默认分别为 true、false)。billing 显式声明计费结构——subscription(评分系数 1.0)或 api(0.85,同 tier 内沉底);这是计费优先级的唯一来源(不从 models.dev/auth 推断)。peak 高峰区间使用 ISO 周日 1–7 与 [start,end) 的 HH:mm;出厂缺省 GLM 工作日 14:00–18:00、DeepSeek 工作日 09:00–12:00 与 14:00–18:00。

行为段(quota / cost / capability / matrix / banner / rules / lanes):详见下方「配置项」表——同样只写这一个文件。

配置项(opencode-switchman.jsonc)

键 默认 说明
providers.<id>.enabled / observe / billing / peak false / true / 见出厂 / 见出厂 供应商策略:路由参与、配额观察、计费结构(subscription=1.0 / api=0.85)、高峰窗口(详见上节)
quota.glmFiveHourReservePct 90 GLM 5 小时窗预留水位(%):达到即硬拦 GLM 壳避免用满 429;周额度仍只认 100%
quota.deepseekLowBalanceWarnCny 10 DeepSeek 余额预警阈值(元):低于该值横幅 [WATERMARK] 提示(仅预警不硬拦,按量计费)
cost.enabled true models.dev 计价快照作为加权模型评分的一个系数
capability.enabled / source / apiKey / tierThresholds / lmarenaCheck true / auto / – / 内置分位 / false 动态能力分级:auto=有 apiKey 先 Artificial Analysis、失败/无 key 转 OpenRouter;key 也可走环境变量 ARTIFICIAL_ANALYSIS_API_KEY
matrix.mode / watch auto / true 激活矩阵:auto 按宿主自动(desktop=可见模型 / CLI/TUI=favorites),app/tui 强制指定,legacy 旧静态矩阵;watch=配置面变化即重算并全量刷新探针(mode/watch 为启动级,重启生效)
banner.enabled true 四行横幅注入开关
rules.enabled / delegationFloor true / 3000 调度员规程(AGENTS.md)随包注入开关;delegationFloor=自做底价(token),注入规程时插值
context.gates / softTokens / hardTokens / forceTokens / readBudgetTokens / autoHandover true / 50000 / 90000 / 130000 / 1500 / true 会话上下文水位实测+自读预算闸:插件从消息 token usage 实测主会话上下文并每轮注入 [WATERMARK:SESSION] 行(附每轮增速与距硬水位剩余轮数估算)。自读从第 1 轮起按 readBudgetTokens 计费:预估超限的读取自动追加 limit 有界放行,或以精确的有界重试参数拒绝;每轮另有 2× 上限阻断连续读取,无法预估的工具输出事后记账。验证/交付类 bash(git、测试/lint、构建)全水位放行;无界历史翻查(如不带 -n 的 git log -p)任何水位一律拦截并附收窄提示;超硬水位读取类关闭(收尾模式);超压水位横幅强制立即压缩,且 autoHandover: true(默认)时自动触发 /handover:完整分叉备份+压缩,未完成的任务在摘要上下文上继续。壳子代理会话不适用本水位,改走自身的单道硬顶(见 context.subagentForceTokens / context.subagentCap);三档水位在可知时额外以当前会话模型上下文窗口(models.dev)的 90% 封顶
context.subagentForceTokens / subagentCap 跟随 forceTokens(130000)/ true 子代理上下文硬顶+软档提醒:壳子代理会话只有一道硬顶(实测=最新 assistant 消息的 input + output + reasoning + cache.read,与会话水位同口径),显式覆盖时钳制 20k..1M,并额外以壳模型上下文窗口的 90% 封顶;缺省跟随主会话 forceTokens,默认共享同一条绝对终止线。硬顶终止之前有两档柔性提醒,直接复用主会话的绝对软/硬阈值(softTokens=省着用,hardTokens=收尾交接——子代理上下文与主会话上下文同等昂贵);有效上限(含窗口封顶)按比例下拉两档,档位永不超过真实终止线。触顶即拒绝该会话所有后续工具调用并下达收尾指令,子代理的下一份纯文本答复(详细的工作进度总结)直接作为任务结果返回委派方,会话永久终止。每档每次会话最多触发一次(进程内去重,会话删除即清除;重启后重新武装);调度规程的交接转发规则把该交接块视为剩余工作的权威状态(全新派发、只注入所需上下文,绝不续接已耗尽的会话)。此后带 task_id 恢复该会话的 task 调用一律永久拒绝(持久登记 ~/.config/opencode/opencode-switchman/subagent-cap.json,重启不失效),不带 task_id 的全新派发不受影响;subagentCap: false 既阻止新的终止也一并关闭提醒。subagentForceTokens 覆盖值非法(非有限数 / 超出 20k..1M)时删除该覆盖并报 SWM037 诊断,回退跟随 forceTokens(fail-open)
builtinAgents.mode deny 内置 explore/general 与壳路由抢任务且此前放行;deny=拦截附 economy/main 改派建议,allow=恢复放行
injection.mode chain 壳注入面:chain=六档链精选∪favorites/可见集(task 工具描述每会话省约 6-10k token,链外模型点名走 denyUninjected 提示);all=可用全集(旧行为);configured=[2026-09-11] 配置了 favorites/可见集时仅注入这些模型的壳(自定义泳道/pool-config 强制保留照旧)——链外精选本就过不了运行时 activation 门,删掉纯死的每请求上下文;未配置时与 chain 行为一致。启动级,重启生效
dispatch.autoRedirect true 派发被拒时在途改写 subagent_type 到拒绝消息已点名的链首候选(单跳、同快照守卫复检)——首次派发直接落在最优可用壳上,不再烧「拒绝-重试」轮次;false 恢复拒绝-重试
dispatch: "off"(.switchman/settings.json) 缺省(fleet) 项目级派发退出:.switchman/settings.json 顶层 "dispatch": "off" 让所有派发治理对该项目的 task 调用停摆——整条 task 路径跳过(未注入/内置代理拒绝及其自动改写、全部六闸含熔断拒绝),调用不受治理直接放行。只有精确的字符串 "off" 生效,其他任何值保持 fleet 行为(存在但不同的值会记一条一次性状态日志)。刻意不停摆:子代理硬上限、语言闸、读取/水位闸、自动交接、熔断失败记账,以及横幅/水位/TODO/[LANG] 行——每轮 [ROUTE] 行是唯一隐藏的 prompt 表面。逐调用读取,切换无需重启;settings.json 完全不是合法 JSON 时按进程一次性写入状态日志警告
relay.image true 无视觉主模型:用户附带图片自动落盘并替换为路径文本+阅读指引(委托 vision 壳或交给 MCP 视觉工具);本地路径 / http URL 原样透传;全程 fail-open
lang.enabled / ask / candidates true / true / 出厂清单 项目级语言偏好:每轮 [LANG] 铁律行(会话 / 注释与提交 / 文档),首次询问未完成配置则每轮用户输入重新询问,未配置期间写入/编辑/bash/派发被硬闸门拒绝(拒绝问卷则本会话豁免),落盘 .switchman/settings.json(AGENTS.md 标记为只读回退),/switchman-lang 重新询问。问卷题文跟随检测到的界面语言(env LC_ALL → LANG,归一化——zh_CN.UTF-8 → zh-CN——无匹配回退英文;仅题文本地化,标记前缀与指令正文保持稳定英文)
lanes 内置六档链 自定义各档壳链(覆盖内置偏好序);键=economy/mechanical/main/hard/vision/review
workspace.enabled / dirname true / ".switchman" 工件工作区:每个主会话自动创建 <project-root>/.switchman/<yyyy-mm-dd>/<sessionId>-<title>/ 目录,路径每轮注入调度员规程;目录内含 SESSION.md / dispatches.jsonl / media/。关闭后不再创建目录,规程段落同步失效
tmux.enabled / rightPct / maxPanes / mini true / 60 / 3 / false tmux 窗格镜像(仅当 opencode 服务器自身运行在 tmux 中时生效):每条被委派的子代理在主 tmux 窗口右侧列实时打开一个 opencode attach 窗格;rightPct=右列宽度百分比(10..90,主窗格占其余),maxPanes=可见子代理窗格上限(1..4;超出的派发在 FIFO 队列等待),mini=用极简 attach 界面取代完整 TUI

旧元组 options 迁移:quota.*.enabled→providers.<id>.observe(SWM042)、billingWindow.*→providers.<id>.peak(SWM043)、其余行为段(quota 阈值/cost/capability/matrix/banner/rules/lanes)→同名 jsonc 段(SWM044);providers.glm/deepseek(凭证收集清单)从未实际生效,已删除。元组显式配置兼容一代(值仍优先),下个大版本移除。

验证安装

启动 opencode 后,主模型每轮系统提示中会出现实时横幅(即调度依据):

[ROUTES] economy: glm-53f-low→glm-47-off→glm-5t-off | mechanical: glm-53f-high→glm-47-off | main: glm-53f-high | hard: glm-53-high | vision: glm-53f-high | review: glm-53-high-ro
[WATERMARK] GLM 5h 10% weekly 38% (refreshed 09-11 10:00) | Copilot credits 0% left (refreshes 2026-10-01) | DeepSeek balance exhausted | advice: ...
[WATERMARK:SESSION] measured session context ~37k (soft 50k/hard 90k/force 130k) | growth ~5k/turn, ~8 turns to hard | self-read this turn 178/3000
[LIMITS] down: none | reviewer prefers cross-family (same-family self-review = DOWNGRADED, allowed only when no cross-family reviewer exists) | api-billed & unknown models sink by coefficient (explicit billing=subscription wins) | matrix: cli·watch/ok | manual capability rank: 9 models, task-pool selection: 6 pools active (/modelRank /poolConfig to adjust)
[TODO] 0/6 done · in_progress: 撰写 README 章节 — keep todowrite current (update as each item starts/finishes)
[LANG] conversation=zh-CN comments=en docs=en (source: project settings) — 用会话语言回复与推理;代码注释、提交信息与生成文档各随其设置
[UPDATE] new version available: /switchman-update or /switchman-ignore

同时日志可见 [opencode-switchman] injected N model shells (agents)——N 随有凭证 provider 的模型面动态变化。六档候选由能力分×档位亲和×计费/未知组系数算法生成,并经 vision/review 结构门过滤,无任何厂商预留席位;运行期再按健康、水位与成本选出当前链首。

侧边栏状态面板(TUI 插件,可选)

v0.2.0 在 OpenCode TUI 侧边栏底部新增实时 switchman 面板,v1.0.0 又做了全面的排版与配色打磨(并完成英文本地化):各家 provider 的水位以渐变条呈现、对齐到全局 8 列网格(标签、进度条与刷新时间跨块对齐,非零小额配额也保证至少一格填充),带高峰标记、observe-only 折叠标签、六个任务档位当前链首、新增模型/provider 的「需要重启」标记、走马灯行上的版本信息(当前运行版本——本地构建会附上所在提交短 SHA——更新检查发现新版本时以绿色显示 → v<最新版>,本地构建显示 → origin/main;已安装升级待重启时闪烁 [RESTART NEEDED] 标记),以及最新一条运行通知。面板每 2 秒轮询本地状态;非横幅 stderr 通知不会刷屏或遮挡输入框。这是一套独立的 TUI Slot 插件(src/tui.tsx,导出路径 opencode-switchman/tui),与 server 端 hook 插件互相独立。

推荐工作流:先用 TUI 完成全部配置——选好模型收藏、调好 /poolConfig 与 /modelRank、盯着侧栏看它路由;之后可自行选择是否换用桌面端(两端共享同一份配置与状态,而弹窗、侧栏、横幅等操作面在 TUI 里最完整)。

Switchman 侧边栏:水位、高峰、任务档位候选与状态通知

OpenCode 模型选择器与 Switchman TUI 集成

TUI 插件没有目录自动发现机制,需要在 tui.jsonc/tui.json 的 plugin 数组里加入同一个包 spec(npm 安装或 opencode plugin <spec> 会自动完成;只有手改配置或从源码用 mode:local/mode:prod 时才需要手动确认):

{
  "plugin": ["opencode-switchman"]
}

手动覆盖层

手动配置命令让你用配置压过系统默认决策,全部状态落盘、可手改、保存即热加载(mtime 感知,即时生效,侧栏同步刷新)。会话式(AI 交互换算 CLI)版本为同名的 -chat 后缀命令。/poolConfig 与 /modelRank 于 v0.2.5 引入;/switchman-setup 于 v1.2.0 引入。

/switchman-setup —— 引导式首次配置(手动向导;会话式用 /switchman-setup-chat)

  • TUI(/switchman-setup):可续跑的一站式向导——首页展示实时完成状态(「开始」直达第一个未完成步骤),按车道序逐池弹出多选框(Enter 切换 [x]/[ ],每行标注能力档,含全选/全部取消/返回,每池确认即刻落盘、每池至少一个模型),随后在入选模型并集上按能力强到弱逐个点选排名(至少一个),完成页汇总各池选配、排名次序与仍需重启的 provider。
  • 非 TUI / 会话内(/switchman-setup-chat):同流程会话式——agent 展示当前池/排名状态,逐池多选提问,询问能力强到弱的排名,经内置 CLI 落盘,校验六池加排名齐备后收尾。
  • 语义——配置硬门槛:未配置的任务池不再默认「全部模型参与」。六池各有 ≥1 模型且排名 ≥1 条之前,主会话的任务派发被拒并附向导指引;未完成期间主会话每轮携带 [SETUP] 指令。壳/内部会话豁免,且无豁免开关。门槛叠加于语言闸:项目语言偏好未配置前,语言询问保持唯一拦截声音。配置 mtime 热加载——最后一个文件保存的瞬间门槛即开,无需重启(重启只为注册全新 provider)。
  • 配置文件:与下方 /poolConfig、/modelRank 相同的 pool-config.json + capability-rank.json。

/poolConfig —— 任务池选配(手动弹窗;会话式用 /poolConfig-chat)

  • TUI(/poolConfig):弹出选择框(与选模型/思考等级同款交互)——先选任务池(economy / mechanical / main / hard / vision / review),再对全部可用模型上下勾选:选中即参与该池、再选即移出,附能力档标注。快捷项:「全选」与「全部取消」(重建模式——只勾选想保留的几个;一个都没勾就退出则保持原选配不变,清空后第一次勾选即写入新清单)。改动实时落盘并 toast 回执。
  • 非 TUI / 会话内(/poolConfig-chat):会话式流程——注入各池选配总览(带池名可看 [x]/[ ] 完整清单),回复「main 只留 3 5」「economy 勾 1、取消 2」由 agent 调 switchman-config.js 落盘。
  • 语义:选配=让各任务池的候选模型体现差异化(如 economy 只配轻量模型、hard 只配重思考模型)——某池的手动清单优先于系统默认候选集,清单内模型仍按能力等级排序推荐;同一模型可重复参与多个池;未配置/空清单的池走系统默认决策。「清除配置」=恢复该池系统默认。
  • 配置文件:~/.config/opencode/opencode-switchman/pool-config.json(键=任务池名,值=参与该池的 modelId 数组)。

/poolConfig 第一步——选择任务池,各池显示已参与模型数

/poolConfig 第二步——按能力档逐个勾选模型,支持全选/全部取消/清除快捷项

/modelRank —— 模型能力排名(手动弹窗;会话式用 /modelRank-chat)

  • TUI(/modelRank):弹窗按有效能力给出单一合并排序——手动条目与基础分模型交错排列;上移/下移会给模型锚定一个介于新上下邻居之间的手动分(一次挪一格,无需把上面的模型全排一遍),另有置顶/移出排名,即时生效。
  • 非 TUI / 会话内(/modelRank-chat):会话式流程——注入当前排名与参考排序,回复「把 glm-5.3 排到最前」「清空排名」由 agent 换算 rank 命令落盘。
  • 语义:手动排名优先于基础能力分(实时第三方指数 → 内置快照 → 策展表全部让位)——命中模型(含其前缀变体)按排名序位取能力分与 S/A/B/C 档:排名 ≤4 项时依次 S/A/B/C;≥5 项按分位口径(top20% S / 次20% A / 次20% B / 其余 C,与 OpenRouter 序位派生同口径);同档内按序位线性分细排。未排名模型不受影响。排名参与所有决策面:六档链排序、档位亲和、能力等级闸与 deny 改派建议。
  • 配置文件:~/.config/opencode/opencode-switchman/capability-rank.json(models 数组顺序=能力降序,#1 最强)。

/modelRank——模型能力排名:手动命中优先于基础能力分

/expert —— 专家咨询(会话式)

  • 用法:/expert <你的需求或设计问题> — 描述会原样传给专家;不带描述时代理会先询问。
  • 行为:把需求派发给当前最强的可用专家——优先 review 链头(跨家族专家席位,只读壳);review 池无可用候选时降级到 hard 链头的只读(-ro)壳,并声明 DOWNGRADED。
  • 专家结论完整转述,末尾注明所用壳与车道(如 expert: <shell> (review))。

上述命令亦可用随包 CLI 直操作:node <包目录>/dist/switchman-config.js pool list|add|remove|set|clear(池名=economy/mechanical/main/hard/vision/review)/ rank list|set|add|remove|clear(编号引用 list 输出)。横幅 [LIMITS] 行会标注当前生效的手动覆盖(「manual capability rank: N models / task-pool selection: M pools」)。

核心思想

问题

多订阅并存的真实痛点:

  1. 认知错配:让旗舰模型干扫描清点的杂活,token 花在不该花的地方;让轻量模型做架构设计,返工反而最贵
  2. 水位盲飞:GLM 5 小时窗耗尽了还在硬撞、Copilot premium 积分月底作废没花完、DeepSeek 余额见底才发现
  3. 单点视角:复审用同一个模型族自查,盲区相同,审不出问题
  4. 协议松弛:「让 XX 帮我看看」式委派无结构、无校验,子代理拿到的是含糊任务

解法:调度员 + 壳矩阵 + 确定性拦截

opencode-switchman 把编排拆成三层,各司其职:

层 载体 职责
认知层 主模型(调度员)+ 随包注入的调度员规程 任务四维画像(认知强度×机械度×上下文×紧急度)、决定自做还是委派、选档选壳、写 DELEGATION_V1 委派 prompt
执行层 「模型×档位」空壳子代理(如 glm-mx-53-high) 只绑定模型与思考档位,角色由委派 prompt 动态赋予(programmer/tester/reviewer 等 14 角色)
确定性层 插件本体 六闸拦截、ROUTE_META 校验(缺失→按 lane 合成、非法→拒绝)、加权模型评分、配额/成本感知选链、探针 / 熔断 / 实调隔离自愈、四行横幅实时注入

Token 经济学为第一性原则:返工是最贵的 token。由此派生六档认知分层——

档位 典型角色 用什么
economy clerk / scouter 扫描清点 最便宜的轻量模型,medium→high→low→minimal 档(先支持哪个用哪个)
mechanical tester / ops 回归与脚本 轻量模型,medium→high→xhigh→max 档
main programmer / uiux / data-analyst 主力模型,medium→high→xhigh→max 档
hard planner 架构核心 最强模型,high→xhigh→max 档
vision observer 看图 视觉模型,medium→high→xhigh→max 档
review reviewer / 专家席 审案 强制异模型族(防同族盲区),high→xhigh→max 档

思考档位偏好是独立的一层路由算法:每档按上表偏好序选思考档(首个被支持的档位即默认档);off 档只作 lane 级兜底——仅当该档没有思考档候选可用时(如只支持开/关的模型)才进链,绝不排到思考档候选之前。壳在排序前还按能力面划池:review 只从 ro(只读)壳池选,其余 lane 只从 rw 壳池选,仅当本池为空才跨池兜底。只读壳以 edit: "deny" 运行,并配只读 bash 白名单(git 查看类子命令——git status/diff/log/show/blame/rev-parse/ls-files/grep/shortlog/describe/merge-base、git stash list,以及 git branch/tag/remote/worktree/config 的仅列表形态——加上 rg、grep、cat、ls、head、tail、stat、tree 等检索/查看工具);其余命令(含带变异形态的 find/sed/awk/echo)全部落到兜底 deny,ro 提示词末尾附一行说明,要求只汇报结论、绝不尝试写入。

水位只影响排序(用满不浪费),唯一硬拦是「调用必失败」(额度确定耗尽或硬门命中);按量计费(billing: "api")provider 在自动路由中不会被 deny——它们经 0.85 系数在同能力档内沉底,未知 provider 模型经 0.75 惩罚沉底,无需任何厂商专属的链尾席位或 deny 规则。

工作原理

生命周期流程

flowchart TD
    A[opencode 启动] --> B[config 钩子<br/>注入全量壳矩阵到 cfg.agent<br/>+ 凭证收集]
    B --> C[后台预热<br/>探针矩阵 / 三池配额 / 计价快照<br/>10min 周期自愈刷新]
    C --> D[主模型工作<br/>按调度员规程决策]
    D --> E{自做 or 委派?}
    E -->|小任务| Z[主模型直接完成]
    E -->|委派| F[选档选壳<br/>写 DELEGATION_V1 + ROUTE_META]
    F --> G[task 派发<br/>tool.execute.before 拦截]
    G --> H{六闸判定}
    H -->|放行| I[壳子代理执行]
    H -->|deny| J[报错附原因+改派候选<br/>主模型按链改派]
    I --> K{执行结果}
    K -->|成功| L[摘要回传主模型]
    K -->|失败| M[event 钩子记账<br/>classifyFailure + 隔离<br/>600s 窗 ≥2 败 → 熔断 600s]
    M --> D
    J --> D
    D -.每轮 LLM 请求.-> N[system.transform<br/>注入调度员规程 + 四行横幅<br/>路由/水位/限制 实时可见]
Loading

六闸拦截(顺序即优先级)

主模型派发子代理时,插件在 task 工具执行前做确定性校验,任一命中即 deny 并附改派候选:

闸 判定 语义
1 注册表 壳未启用/未探测 禁派未注册面
2 探针矩阵 组合实测 down / retired 拦明确不可用;连续 404 下线消失模型
3 熔断 / 隔离 600s 窗内 ≥2 败或实调隔离中 「连续失败熔断中,约 10 分钟自动恢复」/「实调失败后隔离中」
4 池耗尽 配额判定必失败 附人读原因(GLM 100% / Copilot 确定耗尽 / DS 欠费)
5 协议 ROUTE_META 缺失/非法 缺失或无法解析的行 → 按壳所在 lane 合成 META 后放行并记状态日志;存在但错误(非法值 / 缺必填字段)→ deny 附样例与合法值表
6 语义 同族复审 / rw→ro 壳 / 图像→非视觉壳 「复审须异族视角」等

ROUTE_META 是嵌在委派 prompt 内的单行协议,六键六值,插件逐字段校验:

ROUTE_META {"lane":"main","role":"programmer","producer_family":"glm","capability":"rw","modality":"text","source":"auto"}

数据面(全部自动、fail-open)

  • 探针:对三大额度池发起真实请求探活(其余供应商 fail-open 放行),矩阵落盘(TTL 600s)。配置面变化立即全量刷新;平时由 10 分钟周期自愈。
  • 配额:GLM monitor / DeepSeek balance / Copilot copilot_internal/user 直查,无代理、分层 TTL 缓存。
  • 失败分类:厂商无关的 classifyFailure 归一为 rate_limit / quota / auth / not_found / server / network / unknown。探针 429 仅置 strained(降权留链);实调 429 不再误置 Copilot 池耗尽,只有 402 或 403 且含 quota 文案才置耗尽。1 小时窗内连续 3 次 404 会自动 retired:链路排除、闸 deny、横幅标注。
  • 实调失败隔离:探针 ok 但实际委派失败时,combo 进入内存隔离 30 分钟(rate_limit 类 10 分钟),所有会话即时感知,重启即清;它与既有 600s 熔断双轨并行。
  • 成本与评分:models.dev 计价与策展能力分共同进入加权评分;硬门命中的候选先出局再评分。
  • 决策日志:每次横幅重建把候选链与因子分写入 state/routing-decisions.jsonl(环形 200 行)。
  • 横幅:每轮系统提示注入 [ROUTES][WATERMARK][LIMITS][UPDATE] 四行,调度员实时可见。[LIMITS] 行包含下线模型数量与降级标注;[UPDATE] 行在发现新版本时给出升级 / 忽略命令入口。
  • 自更新:启动检查缓存 24 小时。prod 模式对比 npm registry,可执行 /switchman-update 静默升级,随后横幅显示「已升级待重启」并提醒重启;/switchman-ignore 仅忽略本会话,重启后恢复提示。local 模式对比 origin/main,只提示手动更新并仅注册 /switchman-ignore。
  • fail-open 铁律:任何钩子异常只写 stderr 绝不阻塞主流程;配额未知不硬拦,熔断、探针与实调隔离互为独立事实源。

状态目录

~/.config/opencode/opencode-switchman/:shells.json(可选自定义覆盖,缺省用插件内置矩阵)、model-matrix.json(探针)、routing.json(熔断)、routing-decisions.jsonl(200 行评分审计环形日志)、failures.log(记账)、*-quota.json / ds-balance.json(配额缓存)、costs.json(计价)、delegation-template.md(委派模板全文)。

动态激活矩阵

壳矩阵不再是静态清单,而是运行期动态构建、实时更新:

  • desktop app 可见模型与 CLI/TUI favorites 双向同步。mtime 决定更新方向;同毫秒平局不写任一侧,必要时使用默认 CLI 路径兜底。
  • 两者皆未设置时,自动回退为「当前活跃会话正在使用的模型」;多会话并行取并集,任何会话切换模型,矩阵在下一请求实时跟进。
  • 模型管理 / favorites 变更实时监听(fs.watch + mtime 轮询兜底)。任一配置面变化都会立即重算激活矩阵并触发全量探针刷新,不等待 TTL;10 分钟周期刷新继续负责自愈。
  • 新增 provider 实时检测并横幅提示(agent 注册表运行期不可变,对应壳重启 opencode 后自动纳入,无需手动维护)。
  • 启动即注入超集壳(有凭证 provider 的全部可对话模型 × models.dev 档位),matrix.mode=legacy 可完整回退旧静态矩阵行为。

模型评分引擎

路由现在是显式、可追溯的评分,而不是隐藏偏好序:

  • base 能力分主导:策展的 S/A/B/C 能力分按 exact 模型 id → 前缀 → family → global fallback 四路匹配,并记录命中路径。tier 分组不可逆:低档永远压不过高档。
  • 加权系数:最终分数乘以 effortFit × health × water × costBias × peak × billingBoost × unknownPenalty。health 为 ok=1.0 / strained=0.6;water 取两个窗口中更吃紧者,并会在 Copilot 富余且临期时反向提权烧积分;peak 对任意 provider 的高峰窗口做同档 ×0.93 让位,绝不跨能力级出局。billingBoost 只由 opencode-switchman.jsonc 显式 billing 字段驱动(subscription=1.0、api=0.85)——编排规则零厂商硬编码;unknownPenalty=0.75 施加给精确→前缀→family 全链未命中的未知组模型,同 tier 排已知模型之后。
  • 硬门不参与打分:down、熔断、池耗尽、retired、实调隔离中的组合先出局再评分。immediate 紧急档改按探针延迟排序。
  • 决策日志:每次横幅重建都会把各档候选与六因子评分写入 state/routing-decisions.jsonl,保留 200 行环形日志。

子代理上下文硬顶

主会话享有软/硬/压三档水位+自动交接;被委派的壳子代理会话此前完全没有上下文控制,一路跑过 18 万 token 也无人拦截。现在每个壳子代理会话只有一道硬顶(context.subagentForceTokens,可选——缺省跟随主会话 forceTokens,即默认 130,000 token,与主会话共享同一条绝对终止线;显式覆盖时钳制 20k..1M,并在可知时额外以壳模型上下文窗口的 90% 封顶),实测口径与会话水位相同:最新 assistant 消息的 input + output + reasoning + cache.read。硬顶终止之前有两档柔性提醒,直接复用主会话的绝对软/硬阈值(softTokens 省着用 / hardTokens 收尾交接——子代理上下文与主会话上下文同等昂贵),有效上限按比例下拉两档。触顶后,插件拒绝该子代理会话内的所有后续工具调用并下达收尾指令;子代理随后给出的纯文本答复——一份详细的工作进度总结(已完成 / 关键发现含 file:line 证据 / 未完成 / 下一步)——即作为任务结果返回给委派方,会话随即永久终止(终止事件写入状态日志)。合规两侧预先约定:子代理系统提示的壳规则第 6 条(首次触顶拒绝即停止、交回总结),随包调度员规程第 2 节约定编排侧契约(绝不重试已终止的会话;重新派发、只注入所需上下文)。

终止是永久且有意的:此后任何通过 task_id 恢复该会话的 task 调用都会被永久拒绝(持久登记 ~/.config/opencode/opencode-switchman/subagent-cap.json,重启不失效),不带 task_id 的全新派发不受影响。理由:子代理是可复现的工人(其规格写在委派 prompt 里),「终止并交回」优于「压缩后续跑」。context.subagentCap: false 只阻止新的终止——已终止的会话不复活。

由 opencode-switchman.jsonc 的 context.subagentForceTokens(可选——缺省跟随 forceTokens)/ context.subagentCap(默认 true)配置(详见配置项表)。

工件工作区(.switchman)

每个主会话(main)创建时,插件都会自动建立项目内目录 <project-root>/.switchman/<yyyy-mm-dd>/<sessionId>-<title>/(日期取会话创建当天;标题 slug 段会在会话标题生成或修改时自动重命名)。注入的调度员规程每轮插值该目录路径,方案、实现进度、过程管控笔记、设计文档等中间工件默认落到会话目录,不再散落仓库各处或堆进对话。插件同时在目录内维护以下文件:

  • SESSION.md — 会话元数据(id / 标题 / 项目 / 时间戳)
  • dispatches.jsonl — 每条被放行的任务委派一行 JSON(ts / shell / lane / role / source / redirected)
  • media/ — 视觉委派中转的图片(已从旧全局状态目录迁来,fail-open 兜底)

由 opencode-switchman.jsonc 的 workspace.enabled / workspace.dirname 配置(默认 true / ".switchman");关闭后不再创建任何目录,规程中的对应段落同步失效。

tmux 窗格镜像(可选)

opencode 服务器自身运行在 tmux 中时,每条被委派的子代理会话都会以 opencode attach <server> -s <session> 实时窗格打开,在主 tmux 窗口右侧纵向堆叠(主窗格保持左侧份额——默认 40%,子代理列占右侧 60%)。窗口只会在主窗格(服务器启动时所在窗格,即启动时的 TMUX_PANE)上切分:你自己的侧边窗格与 tmux 状态栏绝不会被触碰;从其他窗格接入的 TUI 客户端同样能在那里看到这些子代理窗格。

tmux 分屏镜像:主会话居左,子代理实时 pane 竖排居右

开箱即用,无需任何配置。唯一前提:在 tmux 会话中运行 opencode;tmux 之外该功能完全惰性、零副作用。

  • 可见上限+FIFO:子代理窗格最多同时可见 3 个(tmux.maxPanes,1..4);超出的并发派发在 FIFO 队列中等待,某个可见子代理结束后,排队者原地接管其窗格(原地重生,窗格数不变)。每次完成都会收缩右列并重新均分布局:3→2 均分 → 1 独占右列 → 0 = 只剩主窗格(全宽恢复)。
  • 卫生:窗格通过 pane 标题标记为 swm:<agent-name>;上次崩溃残留的窗格会在插件启动时清扫(kill,按标题前缀或 attach 启动命令匹配)。每次布局操作后都会恢复窗口的活动窗格(焦点保持)。
  • 天生安全:不在 tmux 中或 tmux.enabled=false 时完全惰性;所有 tmux 失败一律 fail-open——只写状态日志,绝不阻塞派发。
  • 观看须知:该窗格是附加到子代理会话的真实交互式 TUI——不要在里面打字(按键会进入子代理会话)。退出观看窗格只是移除显示,子代理继续运行。

由 opencode-switchman.jsonc 的可选 tmux 段配置(enabled / rightPct / maxPanes / mini,默认 true / 60 / 3 / false)。

模型矩阵维护

默认(matrix.mode=auto)矩阵在运行期动态构建:desktop 可见模型与 TUI favorites 自动双向同步,会话模型兜底,任一配置面变化都会触发全量探针重算,无需任何维护;模型临时 down 由探针自愈(每 10 分钟后台刷新,自动进降级/熔断),连续 404 的消失模型会 retired,直到配置面再次变化。

超集保底=opencode 自带免费模型(OpenCode Zen:models.dev opencode provider 下 -free 后缀模型+big-pickle 特例,且剔除 status=deprecated 的已轮换旧模型=「今日可用」集,随目录每 24h 滚动、无需手工维护);目录不可用(无网冷启动)时 fail-open 回退内置静态清单。

内置静态矩阵仅作为 legacy 模式与离线兜底。如需自定义 legacy 静态面:

# 1. 同步权威启用面(opencode 模型管理中打开的模型,每行 provider/model-id)
$EDITOR scripts/visible-models.txt
# 2. 重生成内置矩阵(拉取 models.dev 档位声明)
bun run gen:shells
# 3. 重启 opencode(legacy 模式生效)

开发与验证

bun install
bun test            # 行为契约 fixture(META/六闸/选链/评分/熔断/配额/更新)
bunx tsc --noEmit   # 类型检查
bun run build       # 重新生成矩阵并打包单文件 bundle

本地调试与正式包可用幂等脚本一键切换,切换后重启 opencode 生效:

bun run mode:local              # build + 三处配置切到 file:// 本仓库(仓库根自动推导)
bun run mode:prod               # 拉 npm 最新版,切到精确版本条目 + 清旧插件缓存 + 升级横幅
bun run mode:prod --version 0.2.0  # 指定版本回切(免联网)

两条命令都会同步三处配置(行级手术保留注释与第三方插件,幂等可重复执行):

  • opencode.jsonc/opencode.json 与 tui.jsonc/tui.json 的 plugin 数组(tui 缺失自动补建,侧边栏状态面板跟随 hook 插件一起切源)
  • 主配置 opencode-switchman.jsonc 的 $schema(local 指向仓库内 schema,prod 指向 GitHub main)

prod 与一键安装器共用同一套改写/缓存清理逻辑(scripts/update-cli.mjs);从源码切换后若要长期使用正式版,仍推荐 npx -y opencode-switchman@latest。

版本亮点

分版本的用户向摘要;完整发布说明与升级指南见 CHANGELOG.md。

v1.x——确定性上下文治理与更强的手动覆盖(1.0.0 之后)

  • 壳子代理上下文硬顶:每条壳子代理会话现在都有硬性上下文上限(context.subagentForceTokens,默认 100k token)——越过上限后每次工具调用都会被拒绝并附收尾指令,子代理以一份详细的进度总结作为任务结果交回主会话,且该会话永远无法再经 task_id 续接(持久化注册表)。详见 子代理上下文硬顶。
  • 常开逐次调用读预算(核心算法更新):用确定性预算闸取代旧的「每工具一次性提醒」(那种优惠券式提醒会被模型用重试/试探理性烧掉)。自第 1 轮起,每次读取都按 context.readBudgetTokens(默认 1500)计费——预估超限的读取就地追加 limit 有界放行,或以精确的有界重试参数拒绝;每轮 2× 自读上限(用户发言即重置)阻断连续读取链;无法预估的工具输出事后记账。水位只保留生命周期职责(软=建议、硬=收尾拒绝、压=自动交接)。交付/验证类 bash(git、测试/lint、构建)任何水位放行;无界翻史(不带 -n 的 git log -p)任何水位拦截并附收窄提示。
  • 项目级语言偏好:每轮注入 [LANG] 铁律行(会话 / 注释与提交 / 文档三种语言),首次使用时询问并按项目落盘(未配置则每轮用户输入都会重新询问,且写入/编辑/bash/派发调用会被硬闸门拒绝并指回问卷;用户明确拒绝则本会话豁免),/switchman-lang 可随时修改。
  • 待办纪律:规程 §0.7 + 每轮 [TODO] 状态行,主会话待办实时更新(含委派壳的结果)。
  • /expert 专家咨询与随包 agent skills:需求一键派给当前最强跨家族专家;开箱技能启动时同步进 opencode 全局技能目录(只增改不删、标记门控清理、fail-open)。
  • review 档兜底:跨家族只读壳全灭时保留最优 ro 壳、允许同族评审并标注 DOWNGRADED,不再出现空链。
  • 自动交接健壮性:[backup] 备份自行编号(重启不乱、编号不回收)、压缩走与手动 /compact 相同通道、压缩腿异步化不再死锁会话。
  • 侧栏版本行:走马灯行显示当前运行版本,更新检查发现新版本时同时显示最新版本;闪烁的 [RESTART NEEDED] 标记现在也覆盖「已安装升级但未生效」的场景。
  • tmux 窗格镜像:opencode 服务器自身跑在 tmux 里时,每条被委派的子代理都会在主 tmux 窗口右侧列以实时 opencode attach 窗格打开——可见窗格封顶+FIFO 队列、原地接管、完成即重新均分布局,全程 fail-open。详见 tmux 窗格镜像。

v1.0.0——英文优先的稳定版

  • 协议资产、运行期消息、代码注释与文档全面英文化;横幅锚点更名为 [ROUTES] / [WATERMARK] / [WATERMARK:SESSION] / [LIMITS] / [UPDATE]。
  • TUI 侧栏排版配色打磨:8 列对齐的配额网格、渐变水位条叠于暗色轨道、400 级亮色系、observe-only 折叠标签。

v0.2.0——实时能力感知编排

v0.2.0 将 switchman 从固定多供应商调度器升级为实时、能力感知的编排层。

  • TUI 运行视图:可选侧边栏面板集中展示水位、高峰窗口、六档链首、待重启状态和最新运行通知。
  • 动态激活矩阵:双向同步 desktop 可见模型和 CLI/TUI favorites;未配置时以活跃会话模型兜底;模型面变化即刻重算并刷新探针。
  • 能力感知路由:运行期动态分级,强模型优先于低级模型;再以档位亲和、健康、水位、高峰、显式计费和未知模型置信度做可追溯的同级排序。
  • 供应商中立策略:任意 OpenCode 官方或自定义 provider 都可参与;由显式 billing: "subscription" | "api" 取代厂商专属路由偏好。
  • 更可靠的在线运行:新增实调失败隔离、重复缺失模型下线、路由决策审计日志和更清晰的重启/更新提示,让失败可观察、可自愈。
  • 更简单的配置与升级:全部插件配置统一到自动生成的 opencode-switchman.jsonc;旧元组 options 会被诊断,并再兼容一个版本。/handover 直接执行(无 AI 往返):把当前完整会话分叉为 [backup] 备份并就地压缩当前会话,留在同一会话内(不同于内置 /fork 会切到分叉会话)。越过压水位也会自动触发(context.autoHandover,默认开启),未完成的任务在压缩后的上下文上继续。

延伸文档