opencode2pi 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FanchangWang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+# opencode2pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 **omp** / **pi** 里直接用 [OpenCode Zen](https://opencode.ai/zen) 的**匿名免费模型**。
+
+**无需 API key · 无需注册 · 无需登录 · 无需子进程 · 无需本地端口**
+
+> ⚠️ **这是匿名免费通道，上游随时可能改闸门或直接关停。**
+> 它不依赖任何凭据，所以上游一旦调整请求形状校验，本扩展会**全线 403**。
+> 出问题先跑 `/opencode2pi doctor`，它会直接告诉你闸门还在不在。
+
+---
+
+## 安装
+
+```sh
+# 推荐：npm（已发布，自动带 provenance）
+omp install npm:opencode2pi
+pi  install npm:opencode2pi
+
+# 备用：git @stable（最近一次发版）
+omp install git:https://github.com/FanchangWang/opencode2pi@stable
+pi  install git:https://github.com/FanchangWang/opencode2pi@stable
+
+# 追踪最新代码：装的是"此刻 main 指向的 commit"，含未发布的改动，之后不会自动更新
+omp install git:https://github.com/FanchangWang/opencode2pi@main
+pi  install git:https://github.com/FanchangWang/opencode2pi@main
+```
+
+**为什么 npm 优先**：git 装的是源码快照，宿主要现读现编译；npm 装的是已发布的
+tarball，带 provenance 签名（可在 npmjs.com 包页面核验），且 tag 与版本号一一对应。
+注意 **omp/pi 不支持直接装 `.tgz` 文件**（实测报 `package.json not found`），
+所以只能用 npm spec 或 git URL。
+
+`@stable` 是最近一次发版的版本，随发版前移；要固定到某一版，去
+[releases](https://github.com/FanchangWang/opencode2pi/releases) 挑一个 tag，
+把 `@stable` 换成那个 tag 名或 commit SHA。上游随时可能改闸门，只有钉死才能复现"当时能用"的状态。
+
+`@latest` 用不了：git 没有这个 ref，omp 解析会报错。
+
+### 从源码运行（开发用）
+
+```sh
+git clone https://github.com/FanchangWang/opencode2pi.git
+cd opencode2pi
+
+# 链接当前目录：改代码立即生效，不用重装
+omp install .
+
+# 单次试用，不落盘
+omp -e ./src/index.ts -p --model opencode-zen-free/big-pickle "你好"
+```
+
+`omp install .` 是**链接而非拷贝**：装的是路径，所以改 `src/` 下的代码下次启动就生效。
+代价是删掉或移动这个目录，扩展就失效了 —— 所以本地开发用它，给别人用请走上面的 npm 或 git。
+
+> **不要只复制 `src/index.ts`**。扩展是多文件模块，`index.ts` 依赖同目录的其它模块。
+> 要手动常驻就整目录复制：`cp -r src ~/.omp/agent/extensions/opencode2pi`。
+
+---
+
+## 使用
+
+### 选模型
+
+会话里用 `/model` 选择，provider 名是 `opencode-zen-free`。
+
+命令行要用 `--model <provider>/<model>`，**不要**用 `--provider`：
+
+```sh
+# 对
+omp -p --model opencode-zen-free/big-pickle "你好"
+
+# 错，会报 Unknown provider
+omp --provider opencode-zen-free
+```
+
+> 扩展注册的 provider 在参数校验阶段还不可见，所以 `--provider` 一定失败。
+> 同理 `omp models` **不列出**这个 provider，查清单请用会话内的 `/model`
+> 或 `/opencode2pi status`。
+
+### 模型列表是自动发现的
+
+免费池轮换频繁，所以列表不是写死的，而是实时发现 + 元数据判定：
+
+| 级 | 来源 | 作用 |
+| --- | --- | --- |
+| S1 | `GET {zen}/v1/models` | 谁现在真的在售 |
+| S2 | [models.dev](https://models.dev) | 免费判定 + 真实能力参数 |
+| S3 | 内置静态种子 | 完全离线时的兜底 |
+
+实测当前发现 **7 个** 免费模型（2026-10-11 实测后从 13 个减下来，恒定被拒的
+id 已进 denylist，见 `docs/FINDINGS.md` §2.2）。付费模型不会进列表；断网也能用
+（退回内置种子，能力参数不会变成错误的默认值）。
+
+### 图片输入
+
+能否附加图片取决于模型本身。把图片作为消息的一部分传入即可：
+
+```sh
+omp -p "@photo.png" "这张图是什么颜色？"
+```
+
+只支持文本的模型会收到明确的拒绝提示，而不是模糊的 400。
+
+### 能力参数
+
+上下文长度、最大输出、计价、reasoning effort 都取自 models.dev 的真实数据，
+不是拍脑袋的默认值。某个字段上游没给时，会落到**保守默认值并写进日志**，
+而不是悄悄用一个错的数字。
+
+---
+
+## `/opencode2pi`
+
+omp 没有扩展设置页，斜杠命令是本扩展唯一的界面。
+
+| 命令 | 作用 |
+| --- | --- |
+| `/opencode2pi doctor` | 检查**形状闸门是否仍然成立**。上游一改闸门，这里立刻告警 |
+| `/opencode2pi status` | 显示上次探测的结果；**从未探测过的模型（含新发现的）会当场补测** |
+| `/opencode2pi probe` | 重新探测全部模型 |
+| `/opencode2pi filter` | 选择要在 `/model` 里隐藏哪些模型（默认一个都不隐藏） |
+
+不带参数执行会弹出四项菜单。
+
+### 健康标记
+
+| 标记 | 含义 |
+| --- | --- |
+| ✅ | 可用 |
+| ⚠️ | **现在不行**（5xx、400、无法归类的错误），不代表模型没了 |
+| 🚧 | **配额受限**（429 / transport 超时）。这是通道的匿名额度用完了，不是模型的问题，等一会儿会自动恢复 |
+| ❌ | 确定死了（地区封锁，或连续两次 `ModelError`） |
+| ❓ | 闸门或凭据被拒 —— 全 roster 的问题，跑 `doctor` |
+
+每行末尾直接带上原因（HTTP 状态与上游原文）和探测时间，所以不存在
+「这个模型到底怎么回事」需要另外去查的情况。超过 6 小时的结果标 `（已过期）`，
+并提示你去跑 `probe` —— `status` 不会替你重探。
+
+**默认只标注、不隐藏。** 这条通道波动很大，单次失败不足以判死刑 ——
+实测有模型一分钟内先 `401 ModelError`、再 `200`，所以一次 `ModelError` 只标 ⚠️，
+连续两次才升级 ❌，任何一次成功都会清零。
+
+### 想让失败的模型不出现在 `/model` 里
+
+`/opencode2pi filter`（或每次 `probe` 结束后自动询问）可以隐藏地区封锁的、以及所有
+探测失败的模型。这个选择记在数据目录的 `filters.json` 里，重启后仍然有效；
+随时可以改回「全部保留」。
+
+**配额耗尽和链路故障不会隐藏任何模型**：那是通道的状态，不是模型的。被隐藏的只是
+不进 `/model` 与 `--model`，`status` 里照样能看到全部。
+
+---
+
+## 排障
+
+### 先跑 doctor
+
+大部分「全都不能用」的情况，先跑 `/opencode2pi doctor`。它会直接告诉你闸门还在不在。
+
+### 错误对照表
+
+扩展会把上游错误翻译成人能看懂的原因：
+
+| 你看到的 | 归类 | 原因 / 处理 |
+| --- | --- | --- |
+| `上游形状闸门拒绝（FreeTierError）` | `SHAPE_REJECTED` | 闸门条件被破坏，通常是代码回归 —— 提 issue |
+| `该模型在当前网络地区不可用（RegionError）` | `REGION_BLOCKED` | **地区封锁，不是凭据问题**。换模型或换网络节点 |
+| `模型已下线（ModelError）` | `MODEL_GONE` | 上游已不再支持该模型 |
+| `匿名配额按出口 IP 限流（429）` | `RATE_LIMIT` | 等配额恢复，或设 `PI_PROXY_OPENCODE_ZEN_FREE` 换出口 |
+| `上游拒绝了请求（400）` | `REQUEST_REJECTED` | 模型无法处理这次输入，最常见是给只支持文本的模型发图片 |
+| `上游暂时不可用（5xx）` | `UPSTREAM` | 上游临时故障，换模型重试 |
+
+### 其它常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| `Unknown provider "opencode-zen-free"` | 用了 `--provider`。改用 `--model opencode-zen-free/<id>` |
+| `omp models` 查不到这个 provider | 已知行为（实测），用会话内 `/model` 或 `/opencode2pi status` |
+| 断网了还能用吗 | 能。退回内置种子，能力参数是正确的实测值 |
+
+---
+
+## 它做了什么、没做什么
+
+宿主内建的 `opencode-zen` provider 需要付费 `OPENCODE_API_KEY`；本扩展走的是 Zen 的
+匿名通道（`Authorization: Bearer public`），拿到的是那一批免费模型。
+
+流式引擎、tool call 分片聚合、reasoning、图片 modality、模型选择器 —— 全部由
+omp/pi 内建，本扩展不重复实现。它只补上匿名通道要求的那部分请求形状，
+其余全部委托给宿主。细节见 [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)。
+
+**不做**：付费 Zen 通道、OpenAI/Anthropic 协议互转、IP 池轮换、子进程。
+
+---
+
+## 文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | 架构、闸门条件、宿主 API 实测行为、模块说明、验证与发布流程 |
+| [`docs/FINDINGS.md`](docs/FINDINGS.md) | 实测结论存档：闸门精确条件、宿主扩展 API 的真实行为、同类扩展为什么都不能用 |
+| [`docs/PLAN.md`](docs/PLAN.md) | 任务清单与验收标准 |
+| [`AGENTS.md`](AGENTS.md) | 给接手的 AI：项目地图、验证命令、别踩的坑 |
+
+---
+
+## 致谢
+
+灵感与闸门条件的逆向，来自 [`FishBottle7/opencode2dsh`](https://github.com/FishBottle7/opencode2dsh)
+（DSH 版的同类工具，其 `legacy/` 里的 Go sidecar 源自 [`opencode2api`](https://github.com/jasonxu114514/opencode2api)）。
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "opencode2pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "OpenCode Zen's anonymous free models (no API key) as a native omp/pi provider extension.",
+  "license": "MIT",
+  "author": "FanchangWang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FanchangWang/opencode2pi.git"
+  },
+  "keywords": [
+    "omp",
+    "pi",
+    "pi-extension",
+    "opencode",
+    "opencode-zen",
+    "free-models",
+    "pi-package"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "smoke": "omp -e ./src/index.ts -p --model opencode-zen-free/big-pickle \"Reply with exactly OK\"",
+    "registry": "npm --registry=https://registry.npmjs.org/",
+    "whoami": "npm --registry=https://registry.npmjs.org/ whoami",
+    "dry-run": "npm --registry=https://registry.npmjs.org/ pack --dry-run",
+    "release:check": "npm run typecheck && npm test && npm run dry-run"
+  },
+  "devDependencies": {
+    "@oh-my-pi/pi-coding-agent": "^18.6.1",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
+    "typescript": "^5.9.0"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,254 @@
+/**
+ * `/opencode2pi` — the extension's only interface (docs/PLAN.md §T5).
+ *
+ * omp has no settings page for extensions, so a slash command plus the TUI is
+ * the whole surface. Four capabilities, each answering a question the user
+ * cannot answer any other way once the lane lives inside omp:
+ *
+ *   doctor — the shape gate is hardcoded here, so when upstream changes it the
+ *            only symptom is a silent wall of 403s. This turns that into one
+ *            explicit alarm.
+ *   status — report the last sweep: models it has never asked about are probed
+ *            on the spot, and aged verdicts are flagged rather than re-run.
+ *   probe  — sweep the whole roster, because that costs real inference and is
+ *            therefore the user's call, not a side effect of looking.
+ *   filter — ask what the roster should hide, and remember the answer.
+ */
+
+import type { ExtensionCommandContext, ProviderModelConfig } from '@oh-my-pi/pi-coding-agent'
+
+import { discoverFreeModels } from './discovery.ts'
+import { runDoctor } from './doctor.ts'
+import { hidden, publishFilters, publishHealth, saveFilters } from './filters.ts'
+import {
+	HEALTH_MARK,
+	HEALTH_TTL_MS,
+	isStale,
+	loadHealth,
+	probeAll,
+	saveHealth,
+	summarizeHealth,
+	type HealthRecord,
+	type HealthStore,
+	type ProbeResult,
+} from './health.ts'
+import { SEED_MODELS } from './seed.ts'
+
+/** Model used for the gate check: a verified id, not whatever is selected. */
+const DOCTOR_MODEL = SEED_MODELS[0]?.id ?? 'big-pickle'
+
+const USAGE = '用法：/opencode2pi <doctor|status|probe|filter>'
+
+const AGE = (record: HealthRecord): string => {
+	const minutes = Math.max(0, Math.round((Date.now() - record.checkedAt) / 60_000))
+	if (minutes < 1) return '刚刚探测'
+	if (minutes < 60) return `${minutes} 分钟前探测`
+	const hours = Math.round(minutes / 60)
+	return hours < 24 ? `${hours} 小时前探测` : `${Math.round(hours / 24)} 天前探测`
+}
+
+/**
+ * Render one roster line. Every model appears, whatever its verdict, and every
+ * line carries the reason: a mark alone leaves the reader to guess whether ⚠️
+ * means a 503, a 400 or a timeout, and those have different remedies.
+ *
+ * A model we hold no record for says so in words instead of borrowing a verdict
+ * mark. `·` is not one of the five verdicts — it says we have not asked, which
+ * is a fact about the last probe, not about the model.
+ */
+function rosterLine(model: ProviderModelConfig, record: HealthRecord | undefined): string {
+	if (!record) return `· ${model.id} — ${model.name} · 未探测`
+	const stale = isStale(record) ? '（已过期）' : ''
+	return `${HEALTH_MARK[record.health]} ${model.id} — ${model.name} · ${record.detail} · ${AGE(record)}${stale}`
+}
+
+/** Render one finished probe: the verdict, the reason, and what it cost. */
+function resultLine(result: ProbeResult, done: number, total: number): string {
+	const seconds = (result.latencyMs / 1000).toFixed(1)
+	return `[${done}/${total}] ${HEALTH_MARK[result.health]} ${result.modelId} — ${result.detail} · ${seconds}s`
+}
+
+async function currentRoster(): Promise<readonly ProviderModelConfig[]> {
+	// Never throws and never returns empty, so the roster is always showable.
+	const { models } = await discoverFreeModels()
+	return models.length > 0 ? models : SEED_MODELS
+}
+
+/**
+ * Probe a slice of the roster, printing each verdict as it lands.
+ *
+ * A sweep costs minutes of real inference, so batching the output until the end
+ * means a user staring at an unchanged screen cannot tell "slow model" from
+ * "hung". One line per model, immediately, answers that as it goes.
+ *
+ * `keep` is the whole roster, not the slice being probed: pruning to the batch
+ * would delete every verdict a partial sweep deliberately left alone.
+ */
+async function sweep(
+	models: readonly ProviderModelConfig[],
+	keep: ReadonlySet<string>,
+	ctx: ExtensionCommandContext,
+): Promise<HealthStore> {
+	const results = await probeAll(models, (done, total, result) => {
+		ctx.ui.setWorkingMessage(`正在探测 ${done}/${total}：${result.modelId}`)
+		ctx.ui.notify(resultLine(result, done, total))
+	})
+	ctx.ui.setWorkingMessage()
+	const merged = await saveHealth(results, keep)
+	publishHealth(merged)
+	return merged
+}
+
+/**
+ * Report the roster, probing only what we have never asked about.
+ *
+ * `status` answers "what does the last probe say", and the store is that answer:
+ * re-probing the whole roster on every `status` would burn minutes of real
+ * inference to redraw a picture the user already has. Two cases are exceptions,
+ * because they are gaps rather than pictures — a model that has never been probed
+ * (which includes every model discovered since the last sweep) is probed right
+ * here, because showing `未探测` for something we could have asked about is a
+ * worse answer than asking. A verdict that has merely aged out is not a gap: it
+ * is a real result that has stopped being current, so it is reported with its
+ * age and one line pointing at `probe`. Re-probing on age would make `status` a
+ * `probe` with extra steps.
+ */
+async function showStatus(ctx: ExtensionCommandContext): Promise<void> {
+	const roster = await currentRoster()
+	const stored = await loadHealth()
+	publishHealth(stored)
+
+	const unprobed = roster.filter((model) => !stored[model.id])
+	const aged = roster.filter((model) => stored[model.id] && isStale(stored[model.id]))
+	const keep = new Set(roster.map((model) => model.id))
+
+	let merged = stored
+	if (unprobed.length) {
+		if (!ctx.hasUI) {
+			// Print mode cannot render a progress indicator for minutes at a
+			// time; say so rather than hang a headless run on nothing.
+			ctx.ui.notify(
+				`有 ${unprobed.length} 个模型从未探测（${unprobed.map((model) => model.id).join(', ')}）。` +
+					'逐模型探测需要交互式 TUI，请在 TUI 里运行 status 或 probe。',
+				'warning',
+			)
+		} else {
+			ctx.ui.notify(
+				`正在探测 ${unprobed.length} 个尚未探测过的模型（${unprobed.map((model) => model.id).join(', ')}）…`,
+			)
+			merged = await sweep(unprobed, keep, ctx)
+		}
+	}
+
+	ctx.ui.notify(
+		`opencode2pi 模型状态：${summarizeHealth(roster, merged)}\n` +
+			`${roster.map((model) => rosterLine(model, merged[model.id])).join('\n')}` +
+			hiddenNote() +
+			staleNote(aged.map((model) => model.id)),
+	)
+}
+
+/** A trailing line pointing at `probe` when the report it just showed has aged. */
+function staleNote(aged: readonly string[]): string {
+	if (!aged.length) return ''
+	return (
+		`\n⚠️ ${aged.length} 个模型的结果已超过 ${HEALTH_TTL_MS / 3_600_000} 小时（${aged.join(', ')}）。` +
+		'免费池波动很快，运行 /opencode2pi probe 重新探测全部模型。'
+	)
+}
+
+/** Probe the whole roster, report it, and ask about hiding. */
+async function runProbe(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify('逐模型探测需要交互式 TUI（打印模式下不可用）。')
+		return
+	}
+
+	const roster = await currentRoster()
+	const keep = new Set(roster.map((model) => model.id))
+	ctx.ui.notify(
+		`正在探测 ${roster.length} 个模型（每个模型一条结果，陆续输出；全部结束后给出汇总与完整列表）…`,
+	)
+	const merged = await sweep(roster, keep, ctx)
+	// The per-model lines stream in completion order; this closing block is the
+	// canonical snapshot — every model, in roster order, with verdict and reason.
+	ctx.ui.notify(
+		`探测完成：${summarizeHealth(roster, merged)}\n` +
+			`${roster.map((model) => rosterLine(model, merged[model.id])).join('\n')}` +
+			hiddenNote(),
+	)
+	// The verdicts are only useful if they can change something, and whether to
+	// hide is the one decision we refuse to make on the user's behalf.
+	await chooseFilters(ctx)
+}
+
+/** A trailing line saying what the current filters remove, or that they do not. */
+function hiddenNote(): string {
+	const excluded = [...hidden()]
+	return excluded.length ? `\n已从列表隐藏：${excluded.join(', ')}（用 /opencode2pi filter 调整）` : ''
+}
+
+/**
+ * Ask what the roster should hide, and apply the answer.
+ *
+ * This is the user's call, not ours: the same model can answer ✅ on one lane and
+ * be region-blocked on another, so an automatic rule would be wrong half the
+ * time. Cancelling changes nothing — the default is to hide nothing.
+ */
+async function chooseFilters(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify('过滤设置需要交互式 TUI（打印模式下不可用）。')
+		return
+	}
+	const choice = await ctx.ui.select('opencode2pi · 模型过滤', [
+		{ label: '全部保留（只标注，不隐藏）', description: '默认：任何模型都不从列表里移除' },
+		{ label: '隐藏地区封锁的', description: '上游按当前出口拒绝的模型（403 · not available in your country）' },
+		{ label: '隐藏所有探测失败的', description: '下线、地区封锁、请求被拒、上游故障；配额与链路问题不算' },
+	])
+	const next =
+		choice === '隐藏地区封锁的'
+			? { hideRegionBlocked: true, hideFailed: false }
+			: choice === '隐藏所有探测失败的'
+				? { hideRegionBlocked: true, hideFailed: true }
+				: choice === '全部保留（只标注，不隐藏）'
+					? { hideRegionBlocked: false, hideFailed: false }
+					: undefined
+	if (!next) return
+	await saveFilters(next)
+	publishFilters(next)
+	ctx.ui.notify(`已更新过滤：当前隐藏 ${hidden().size} 个模型（/model 与 --model 里不再出现）`)
+}
+
+async function showMenu(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(USAGE)
+		return
+	}
+	const choice = await ctx.ui.select('opencode2pi', [
+		{ label: 'doctor', description: '检查形状闸门是否仍然成立（发一个最小闸门形状请求）' },
+		{ label: 'status', description: '显示上次探测的结果；从未探测过的模型会自动补测' },
+		{ label: 'probe', description: '重新探测全部模型（并发，2 并发）' },
+		{ label: 'filter', description: '选择要在 /model 里隐藏哪些模型（默认一个都不隐藏）' },
+	])
+	// `select` resolves to the chosen label, so the labels double as the keys.
+	if (choice === 'doctor') await runDoctorCommand(ctx)
+	else if (choice === 'status') await showStatus(ctx)
+	else if (choice === 'probe') await runProbe(ctx)
+	else if (choice === 'filter') await chooseFilters(ctx)
+}
+
+async function runDoctorCommand(ctx: ExtensionCommandContext): Promise<void> {
+	if (ctx.hasUI) ctx.ui.notify('正在检查形状闸门…')
+	const report = await runDoctor(DOCTOR_MODEL)
+	ctx.ui.notify(`${report.headline}\n${report.detail}`, report.ok ? 'info' : 'error')
+}
+
+export async function handleCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	const sub = args.trim().split(/\s+/)[0]?.toLowerCase() ?? ''
+	if (sub === 'doctor') return runDoctorCommand(ctx)
+	if (sub === 'status') return showStatus(ctx)
+	if (sub === 'probe') return runProbe(ctx)
+	if (sub === 'filter') return chooseFilters(ctx)
+	if (sub === '') return showMenu(ctx)
+	ctx.ui.notify(USAGE, 'warning')
+}