diff --git a/README.md b/README.md index c30a7e8..79ce5cc 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,16 @@ Since TUI plugins have no directory auto-discovery, add the same package spec to } ``` +## Quick Start — five steps to a working matrix + +Installed? Five steps and you're done (full walkthrough with screenshots and exact scope/conditions: **[docs/quick-start.md](./docs/quick-start.md)** / 中文 **[docs/quick-start.zh.md](./docs/quick-start.zh.md)**): + +1. **Connect providers** — run `/connect` in the TUI: sign in to GitHub Copilot (OAuth), paste your DeepSeek API key; for the GLM Coding Plan add the `zhipuai-coding-plan` custom provider (baseURL + apiKey) to `opencode.json`. Any opencode provider works; these three additionally get quota-aware routing. +2. **Pick the models that join orchestration** — TUI: `/models` then `ctrl+f` to favorite; desktop app: "Manage models" toggles. Favorites/visible models form the activation surface and sync bidirectionally (nothing picked → active session models fill in). +3. **(Optional) `/modelRank`** — pin your own capability ranking (TUI dialog, or conversational `/modelRank-chat`); a manual rank overrides base capability scores everywhere. +4. **(Optional) `/poolConfig`** — curate per-pool candidate lists for the six task pools (TUI dialog, or `/poolConfig-chat`); a pool's manual list replaces the system default candidates. +5. **Restart, verify, watch** — restart opencode, confirm the `[ROUTES]`/`[LIMITS]` banner and the sidebar `switchman` panel, run `/switchman-doctor` if anything looks off, then just use opencode normally. + ## Manual overrides: /poolConfig and /modelRank (new in v0.2.5) Two manual commands let your configuration beat system defaults. All state is persisted to editable files with mtime hot-reload and instant effect — edits trigger an immediate banner/sidebar refresh via a directory watcher. The conversational (AI-driven) variants are the same names with a `-chat` suffix: diff --git a/README.zh.md b/README.zh.md index 7eb80c5..0c796c1 100644 --- a/README.zh.md +++ b/README.zh.md @@ -150,6 +150,16 @@ TUI 插件没有目录自动发现机制,需要在 **`tui.jsonc`/`tui.json`** } ``` +## 快速上手 — 五步跑通矩阵 + +装好了?五步即可(完整图文版,含截图与确切生效范围:**[docs/quick-start.zh.md](./docs/quick-start.zh.md)** / English **[docs/quick-start.md](./docs/quick-start.md)**): + +1. **连接 provider** —— 在 TUI 运行 `/connect`:GitHub Copilot 走 OAuth 登录、DeepSeek 粘贴 API key;GLM Coding Plan 在 `opencode.json` 里加 `zhipuai-coding-plan` 自定义 provider(baseURL + apiKey)。任意 opencode provider 均可;这三家额外获得配额感知路由。 +2. **挑选参与编排的模型** —— TUI:`/models` 后按 `ctrl+f` 收藏;桌面 app:「管理模型」开关。收藏/可见模型构成启用面且双向同步(都不选 → 回落活跃会话模型)。 +3. **(可选)`/modelRank`** —— 固定你自己的能力排名(TUI 弹窗,或会话式 `/modelRank-chat`);手动排名在所有决策面压过基础能力分。 +4. **(可选)`/poolConfig`** —— 为六个任务池定制候选清单(TUI 弹窗,或 `/poolConfig-chat`);某池的手动清单替换系统默认候选。 +5. **重启、验证、观察** —— 重启 opencode,确认 `[ROUTES]`/`[LIMITS]` 横幅与侧栏 `switchman` 面板,有不对劲就跑 `/switchman-doctor`,之后正常使用即可。 + ## 手动覆盖层:/poolConfig 与 /modelRank(v0.2.5 新增) 两个手动配置命令让你用配置压过系统默认决策,全部状态落盘、可手改、保存即热加载(mtime 感知,即时生效,侧栏同步刷新)。会话式(AI 交互换算 CLI)版本为同名的 `-chat` 后缀命令: diff --git a/docs/assets/app-model-management.png b/docs/assets/app-model-management.png new file mode 100644 index 0000000..b245ec6 Binary files /dev/null and b/docs/assets/app-model-management.png differ diff --git a/docs/assets/app-modelrank-chat-command.png b/docs/assets/app-modelrank-chat-command.png new file mode 100644 index 0000000..764107a Binary files /dev/null and b/docs/assets/app-modelrank-chat-command.png differ diff --git a/docs/assets/app-modelrank-chat.png b/docs/assets/app-modelrank-chat.png new file mode 100644 index 0000000..5b77fd0 Binary files /dev/null and b/docs/assets/app-modelrank-chat.png differ diff --git a/docs/assets/app-poolconfig-chat.png b/docs/assets/app-poolconfig-chat.png new file mode 100644 index 0000000..401ea82 Binary files /dev/null and b/docs/assets/app-poolconfig-chat.png differ diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..e39b29c --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,147 @@ +# Quick Start — from zero to a routed matrix in five steps + +**English** | [Chinese](./quick-start.zh.md) + +This walkthrough is for users who have just installed the plugin (or are about to) and want the shortest path to "everything works, and I know why". Each step tells you exactly what to type, shows a screenshot of what you should see, and states the exact scope and conditions under which that setting takes effect. + +> **Where to configure**: use the **CLI/TUI first** — dialogs, the sidebar panel, and live banners are richest there. The **desktop app** is an optional alternative afterwards; both share the same config and state, and every manual override below works in either surface. + +The five steps: + +1. [Connect providers](#step-1--connect-providers) — give opencode credentials so models exist +2. [Pick the models that join orchestration](#step-2--pick-the-models-that-join-orchestration-favorites--visible-set) — favorites in the TUI, toggles in the app +3. [Rank models yourself (optional)](#step-3--optional-rank-models-yourself-modelrank-and-modelrank-chat) — `/modelRank` / `/modelRank-chat` +4. [Curate task pools (optional)](#step-4--optional-curate-task-pools-poolconfig-and-poolconfig-chat) — `/poolConfig` / `/poolConfig-chat` +5. [Restart, verify, and watch it route](#step-5--restart-verify-and-watch-it-route) — banners, sidebar, `/switchman-doctor` + +--- + +## Step 1 — Connect providers + +The plugin routes across **any opencode provider** — whatever has credentials in opencode becomes part of the orchestration surface. Three providers additionally get **quota-aware routing** (water levels, peak windows, exhaustion handling): GitHub Copilot, GLM, and DeepSeek. + +In the TUI, run: + +```text +/connect +``` + +- **GitHub Copilot** — search for *GitHub Copilot*, follow the OAuth device flow (enter the code at github.com/login/device). No API key needed. +- **DeepSeek** — search for *DeepSeek*, paste your API key from platform.deepseek.com. +- **GLM Coding Plan** — not in the `/connect` list; add it as a custom provider in your opencode config (`~/.config/opencode/opencode.json` or project `opencode.json`) and put your API key from open.bigmodel.cn: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "provider": { + "zhipuai-coding-plan": { + "npm": "@ai-sdk/openai-compatible", + "name": "Zhipu AI Coding Plan", + "options": { + "baseURL": "https://open.bigmodel.cn/api/coding/paas/v4", + "apiKey": "YOUR_GLM_CODING_PLAN_API_KEY" + } + } + } +} +``` + +In the desktop app you can reach provider sign-in from the model-management dialog's **"Connect provider"** button (top-right in the screenshot in Step 2). + +> **Scope & conditions** +> - The plugin reads credentials **read-only** from opencode's auth layer (auth.json / provider options / env vars) — it never stores or refreshes secrets. +> - Provider keys matter: `zhipuai-coding-plan`, `deepseek`, and `github-copilot` are the stable keys the plugin recognizes for quota routing (near-miss spellings get a `/switchman-doctor` warning). Any other provider key is legal and routed with generic defaults. +> - Restart opencode after editing `opencode.json` so the provider surface is picked up. + +## Step 2 — Pick the models that join orchestration (favorites / visible set) + +Not every model a provider offers needs to join the matrix. You decide the **activation surface** — the set of models the plugin builds shells and lane chains from: + +- **TUI**: open the model picker (`/models`) and press `ctrl+f` on a model to **favorite / unfavorite** it. Favorites are grouped at the top of the picker. + +![OpenCode model picker — ctrl+f to favorite, ctrl+a to connect a provider](assets/tui-model-picker.png) + +- **Desktop app**: open the model-management dialog and toggle models **on** (shown) or **off** (hidden). + +![Desktop app model management — toggles decide which models are shown](assets/app-model-management.png) + +> **Scope & conditions** +> - With the default `matrix.mode=auto`: **CLI/TUI activation surface = favorites**; **desktop app activation surface = models toggled on** (visible set). +> - Both surfaces **sync bidirectionally** (the fresher side wins by file mtime), so you can favorite in the TUI and see it reflected in the app, and vice versa. +> - **No favorites / nothing toggled on?** The plugin falls back to *active session models* (the union of current models across running main sessions) — you still get a working matrix, just a minimal one. +> - Favorites also carry a routing hint: within the same capability tier, favorited models are preferred in lane chains. +> - Surface changes (favorite added/removed, toggle flipped) trigger an immediate recomputation and probe refresh — no restart needed for this step. + +## Step 3 — (Optional) Rank models yourself: /modelRank and /modelRank-chat + +By default, model capability comes from an automatic cascade (live third-party index → bundled snapshot → curated table). If you disagree — your workload, your ranking. + +**TUI**: run `/modelRank` — a dialog lists every model by effective capability; select a model to pin it to top, move it up/down, or remove it from the ranking. + +![/modelRank — capability ranking with manual-rank vs base-score provenance](assets/tui-model-rank.png) + +**Conversational** (TUI or desktop app — same flow in both): run `/modelRank-chat`. The agent shows the current ranking and asks what to adjust; you answer in plain language ("build a new ranking: glm-5.3 first, then gpt-5.4, then claude-opus-4.7") and it persists the result. + +![Typing /modelRank-chat in the app input box](assets/app-modelrank-chat-command.png) + +![/modelRank-chat — the agent asks for your adjustment intent](assets/app-modelrank-chat.png) + +> **Scope & conditions** +> - A manual ranking **overrides the base capability score** for the models it contains (including prefix variants); unranked models are unaffected. Clearing the ranking (or removing a model from it) restores base scores. +> - Ranked models get an S/A/B/C tier from their position: ≤4 entries map to S/A/B/C in order; ≥5 entries use quantile buckets (top 20% S / next 20% A / next 20% B / rest C). Within a tier, rank position breaks ties. +> - The ranking feeds **every** decision surface: lane chains, effort affinity, capability gates, and deny/redirect hints. +> - Persisted to `~/.config/opencode/opencode-switchman/capability-rank.json` (order = strongest first); the file is hot-reloaded on change (mtime), instant effect, sidebar refreshes immediately. The `[LIMITS]` banner reports it as `manual capability rank: N models`. +> - CLI alternative: `node /dist/switchman-config.js rank list|set|add|remove|clear`. + +## Step 4 — (Optional) Curate task pools: /poolConfig and /poolConfig-chat + +Dispatches land in one of six task pools — `economy` / `mechanical` / `main` / `hard` / `vision` / `review`. By default each pool considers every activated model, sorted by capability. Curation makes each pool deliberately different (lightweights only for economy, heavy thinkers only for hard). + +**TUI**: run `/poolConfig` — pick a pool, then toggle models in/out of it. + +![/poolConfig step 1 — pick a task pool, each showing how many models participate](assets/tui-pool-config-pools.png) + +![/poolConfig step 2 — toggle models per pool with capability tiers and select-all / clear shortcuts](assets/tui-pool-config-models.png) + +**Conversational** (TUI or desktop app): run `/poolConfig-chat` — the agent shows a per-pool overview, you answer in plain language ("economy: keep only the flash models"), and it persists the change. + +![/poolConfig-chat — the agent asks which task pool to configure](assets/app-poolconfig-chat.png) + +> **Scope & conditions** +> - A pool's manual list **replaces the system default candidate set** for that pool; models inside it are still recommended by capability. Pools without a configured (or with an empty) list keep the system default. "Clear config" restores the default for that pool. +> - The same model may join multiple pools. +> - Only models from the activation surface (Step 2) can be curated into pools — favorite/enable models first if something is missing from the list. +> - Persisted to `~/.config/opencode/opencode-switchman/pool-config.json` (key = pool name, value = model array); hot-reloaded on change, instant effect. The `[LIMITS]` banner reports it as `task-pool selection: M pools`. +> - CLI alternative: `node /dist/switchman-config.js pool list|add|remove|set|clear` (pool name = economy/mechanical/main/hard/vision/review). + +## Step 5 — Restart, verify, and watch it route + +1. **Restart opencode** (required after Step 1 config edits; harmless otherwise). +2. **Check the banner** — every system prompt of your primary model now carries the live `[ROUTES]` / `[WATERMARK]` / `[LIMITS]` block. `[ROUTES]` shows the six lane chains; `[LIMITS]` reports your manual overrides (`manual capability rank: N models, task-pool selection: M pools`). +3. **Check the log** for `[opencode-switchman] injected N model shells (agents)` — N follows your activation surface from Step 2. +4. **Watch the sidebar** `switchman` panel — provider water levels, peak warnings, and each lane's current head candidate, refreshed every 2 seconds. + +![Sidebar status panel — water levels, lane candidates, and status notices](assets/tui-sidebar-status.png) + +5. **Anything off?** Run `/switchman-doctor` — a local, credential-free diagnostic report that pinpoints missing credentials, misconfigurations, and near-miss provider keys. + +That's it — from here just use opencode normally. Your primary model is now a dispatcher: it delegates by cognitive tier, respects quota water levels and peak windows, and every routing decision is traceable in the banner, the sidebar, and the `.switchman/` workspace. + +--- + +## Cheat sheet: command × surface × scope + +| Command / action | Where it works | What it controls | Takes effect | Persisted to | +| --- | --- | --- | --- | --- | +| `/connect` | TUI & app | Provider credentials | Models of credentialed providers join the selectable surface (restart after `opencode.json` edits) | opencode auth layer (plugin reads it read-only) | +| `ctrl+f` in the model picker (`/models`) | TUI | Favorites = CLI/TUI activation surface; same-tier preferred | Immediately (recompute + probe refresh) | opencode state (`model.json`), synced with the app | +| Model-management toggles | Desktop app | Visible set = app activation surface; synced with TUI favorites | Immediately (recompute + probe refresh) | opencode state (`opencode.global.dat`), synced with the TUI | +| `/modelRank` | TUI | Manual capability ranking, overrides base scores | Immediately (hot reload) | `~/.config/opencode/opencode-switchman/capability-rank.json` | +| `/modelRank-chat` | TUI & app | Same as `/modelRank`, conversational | Immediately (hot reload) | Same file as `/modelRank` | +| `/poolConfig` | TUI | Per-pool candidate lists, replace pool defaults | Immediately (hot reload) | `~/.config/opencode/opencode-switchman/pool-config.json` | +| `/poolConfig-chat` | TUI & app | Same as `/poolConfig`, conversational | Immediately (hot reload) | Same file as `/poolConfig` | +| `/expert ` | TUI & app | One-off expert consultation via the strongest read-only shell | Per call | — | +| `/switchman-doctor` | TUI & app | Local, credential-free diagnostics | Per call | — | +| `/switchman-update` | TUI & app | Upgrade the plugin to the latest release | After restart | opencode plugin config | + +> Deeper dives: [Manual overrides](../README.md#manual-overrides-poolconfig-and-modelrank-new-in-v025) · [Options (`opencode-switchman.jsonc`)](../README.md#options-opencode-switchmanjsonc) · [How it works](../README.md#how-it-works) diff --git a/docs/quick-start.zh.md b/docs/quick-start.zh.md new file mode 100644 index 0000000..6da3364 --- /dev/null +++ b/docs/quick-start.zh.md @@ -0,0 +1,147 @@ +# 快速上手 — 五步从零到矩阵路由 + +**[English](./quick-start.md)** | 中文 + +这篇指南面向刚装好插件(或正准备装)的用户,目标是用最短路径达到「一切正常工作,而且我知道为什么」。每一步都会告诉你确切要输入什么、展示你应看到界面的截图,并说明该配置的**生效范围与条件**。 + +> **在哪里配置**:**先用 CLI/TUI**——弹窗、侧边栏面板与实时横幅等操作面在 TUI 里最完整。之后可选换用**桌面 app**;两端共享同一份配置与状态,下述所有手动覆盖在任一端都能操作。 + +五个步骤: + +1. [连接 provider](#step-1)——给 opencode 凭证,让模型可用 +2. [挑选参与编排的模型](#step-2)——TUI 收藏、app 开关 +3. [自己排能力名次(可选)](#step-3)——`/modelRank` / `/modelRank-chat` +4. [定制任务池(可选)](#step-4)——`/poolConfig` / `/poolConfig-chat` +5. [重启、验证、观察路由](#step-5)——横幅、侧栏、`/switchman-doctor` + +--- + +## Step 1 — 连接 provider + +插件可以在**任意 opencode provider** 之间路由——凡在 opencode 里有凭证的 provider 都会进入编排面。以下三家额外获得**配额感知路由**(水位、高峰区间、耗尽处理):GitHub Copilot、GLM、DeepSeek。 + +在 TUI 中运行: + +```text +/connect +``` + +- **GitHub Copilot**——搜索 *GitHub Copilot*,走 OAuth 设备码流程(在 github.com/login/device 输入代码),无需 API key。 +- **DeepSeek**——搜索 *DeepSeek*,粘贴 platform.deepseek.com 的 API key。 +- **GLM Coding Plan**——不在 `/connect` 列表中;作为自定义 provider 写进 opencode 配置(`~/.config/opencode/opencode.json` 或项目级 `opencode.json`),API key 来自 open.bigmodel.cn: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "provider": { + "zhipuai-coding-plan": { + "npm": "@ai-sdk/openai-compatible", + "name": "Zhipu AI Coding Plan", + "options": { + "baseURL": "https://open.bigmodel.cn/api/coding/paas/v4", + "apiKey": "你的_GLM_CODING_PLAN_API_KEY" + } + } + } +} +``` + +桌面 app 端可从模型管理对话框右上角的**「连接提供商」**按钮进入登录(见 Step 2 截图右上角)。 + +> **生效范围与条件** +> - 插件对凭证**只读**(读 opencode 的 auth.json / provider options / 环境变量),自身不存储、不刷新任何密钥。 +> - provider 键名有讲究:`zhipuai-coding-plan`、`deepseek`、`github-copilot` 是插件识别配额路由的稳定键(近似拼写会被 `/switchman-doctor` 警告);其他任意 provider 键均合法,按通用缺省参与编排。 +> - 改完 `opencode.json` 后重启 opencode,provider 面才会被拾取。 + +## Step 2 — 挑选参与编排的模型(收藏 / 可见集) + +不是 provider 提供的每个模型都要进矩阵。**启用面**由你决定——插件据此构建壳与六档链: + +- **TUI**:打开模型选择器(`/models`),对模型按 `ctrl+f` **收藏 / 取消收藏**。收藏项会置顶分组显示。 + +![OpenCode 模型选择器——ctrl+f 收藏、ctrl+a 连接 provider](assets/tui-model-picker.png) + +- **桌面 app**:打开「管理模型」对话框,用开关把模型**打开(显示)或关闭(隐藏)**。 + +![app 端管理模型——开关决定哪些模型显示](assets/app-model-management.png) + +> **生效范围与条件** +> - 默认 `matrix.mode=auto` 下:**CLI/TUI 启用面 = 收藏(favorites)**;**桌面 app 启用面 = 打开开关的模型(可见集 visible set)**。 +> - 两端**双向同步**(按文件 mtime 取更新的一侧)——TUI 里收藏,app 里即刻可见,反之亦然。 +> - **完全没配置?** 插件回落到「活跃会话模型」(所有运行中主会话当前模型的并集)——矩阵照样工作,只是规模最小。 +> - 收藏还带路由语义:同一能力档内,收藏的模型在链中优先。 +> - 启用面变化(收藏增删、开关切换)会立即触发重算与探针刷新——这一步无需重启。 + +## Step 3 —(可选)自己排能力名次:/modelRank 与 /modelRank-chat + +默认模型能力来自自动级联(实时第三方指数 → 内置快照 → 策展表)。不同意?你的工作负载你说了算。 + +**TUI**:运行 `/modelRank`——弹窗按有效能力列出所有模型;选中模型可「置顶 / 上移 / 下移 / 移出排名」。 + +![/modelRank——模型能力排名:手动命中优先于基础能力分](assets/tui-model-rank.png) + +**会话式**(TUI 与桌面 app 流程一致):运行 `/modelRank-chat`——agent 展示当前排名并询问调整意图,你用自然语言回答(「新建排名:先 glm-5.3,再 gpt-5.4,再 claude-opus-4.7」),由它换算落盘。 + +![在 app 输入框键入 /modelRank-chat](assets/app-modelrank-chat-command.png) + +![/modelRank-chat——agent 询问你的调整意图](assets/app-modelrank-chat.png) + +> **生效范围与条件** +> - 手动排名对命中的模型(含其前缀变体)**优先于基础能力分**;未排名模型不受影响。清空排名(或把模型移出)即恢复基础分。 +> - 命中模型按排名序位获得 S/A/B/C 档:≤4 项时依次映射 S/A/B/C;≥5 项按分位桶(top 20% S / 次 20% A / 次 20% B / 其余 C);同档内按序位线性细分。 +> - 排名参与**所有**决策面:六档链排序、档位亲和、能力等级闸、deny 改派建议。 +> - 落盘于 `~/.config/opencode/opencode-switchman/capability-rank.json`(数组顺序 = 能力降序);文件改动 mtime 热加载、即时生效,侧栏同步刷新。横幅 `[LIMITS]` 行标注 `manual capability rank: N models`。 +> - CLI 直操作:`node <包目录>/dist/switchman-config.js rank list|set|add|remove|clear`。 + +## Step 4 —(可选)定制任务池:/poolConfig 与 /poolConfig-chat + +派发会落入六个任务池之一——`economy` / `mechanical` / `main` / `hard` / `vision` / `review`。默认每池考虑全部启用模型并按能力排序;定制能让各池**体现差异化**(economy 只配轻量模型、hard 只配重思考模型)。 + +**TUI**:运行 `/poolConfig`——先选任务池,再逐个勾选/取消模型。 + +![/poolConfig 第一步——选择任务池,各池显示已参与模型数](assets/tui-pool-config-pools.png) + +![/poolConfig 第二步——按能力档逐个勾选模型,支持全选/全部取消/清除快捷项](assets/tui-pool-config-models.png) + +**会话式**(TUI 与桌面 app):运行 `/poolConfig-chat`——agent 展示各池选配总览,你用自然语言回答(「economy 只留 flash 系」),由它换算落盘。 + +![/poolConfig-chat——agent 询问要配置哪个任务池](assets/app-poolconfig-chat.png) + +> **生效范围与条件** +> - 某池的手动清单**替换该池系统默认候选集**;清单内模型仍按能力等级排序推荐。未配置/空清单的池走系统默认;「清除配置」= 恢复该池默认。 +> - 同一模型可重复参与多个池。 +> - 只有启用面(Step 2)里的模型能配进池——清单里缺谁,先回去收藏/打开它。 +> - 落盘于 `~/.config/opencode/opencode-switchman/pool-config.json`(键 = 池名,值 = 模型数组);改动热加载、即时生效。横幅 `[LIMITS]` 行标注 `task-pool selection: M pools`。 +> - CLI 直操作:`node <包目录>/dist/switchman-config.js pool list|add|remove|set|clear`(池名 = economy/mechanical/main/hard/vision/review)。 + +## Step 5 — 重启、验证、观察路由 + +1. **重启 opencode**(Step 1 改过配置文件后必须;其余情况重启也无害)。 +2. **看横幅**——主模型每轮系统提示现在携带实时 `[ROUTES]` / `[WATERMARK]` / `[LIMITS]` 块。`[ROUTES]` 展示六档链;`[LIMITS]` 报告你的手动覆盖(`manual capability rank: N models, task-pool selection: M pools`)。 +3. **看日志**中的 `[opencode-switchman] injected N model shells (agents)`——N 随 Step 2 的启用面动态变化。 +4. **盯侧边栏** `switchman` 面板——provider 水位、高峰标记、六档当前链首,每 2 秒刷新。 + +![侧边栏状态面板——水位、档位候选与状态通知](assets/tui-sidebar-status.png) + +5. **有不对劲?** 运行 `/switchman-doctor`——本地、脱敏、不联网的诊断报告,定位缺失凭证、配置错误与 provider 键近似拼写。 + +到此完成——之后正常使用 opencode 即可。你的主模型现在是调度员:按认知档位派发、遵守水位与高峰、每个路由决策都能在横幅、侧栏与 `.switchman/` 工作区中追溯。 + +--- + +## 速查表:命令 × 界面 × 生效范围 + +| 命令 / 操作 | 可用界面 | 控制什么 | 生效时机 | 落盘位置 | +| --- | --- | --- | --- | --- | +| `/connect` | TUI & app | provider 凭证 | 有凭证 provider 的模型进入可选面(改 `opencode.json` 后需重启) | opencode auth 层(插件只读) | +| 模型选择器内 `ctrl+f`(`/models`) | TUI | 收藏 = CLI/TUI 启用面;同档内优先 | 即时(重算 + 探针刷新) | opencode 状态(`model.json`),与 app 双向同步 | +| 「管理模型」开关 | 桌面 app | 可见集 = app 启用面;与 TUI 收藏同步 | 即时(重算 + 探针刷新) | opencode 状态(`opencode.global.dat`),与 TUI 双向同步 | +| `/modelRank` | TUI | 手动能力排名,压过基础分 | 即时(热加载) | `~/.config/opencode/opencode-switchman/capability-rank.json` | +| `/modelRank-chat` | TUI & app | 同 `/modelRank`,会话式 | 即时(热加载) | 与 `/modelRank` 同文件 | +| `/poolConfig` | TUI | 各任务池候选清单,替换池默认 | 即时(热加载) | `~/.config/opencode/opencode-switchman/pool-config.json` | +| `/poolConfig-chat` | TUI & app | 同 `/poolConfig`,会话式 | 即时(热加载) | 与 `/poolConfig` 同文件 | +| `/expert <问题>` | TUI & app | 经最强只读壳的一次性专家咨询 | 单次调用 | — | +| `/switchman-doctor` | TUI & app | 本地、脱敏诊断 | 单次调用 | — | +| `/switchman-update` | TUI & app | 升级插件到最新版 | 重启后生效 | opencode 插件配置 | + +> 延伸阅读([README.zh.md](../README.zh.md)):手动覆盖层 · 配置项(opencode-switchman.jsonc) · 工作原理