opencode-skills-doctor 0.4.2 → 0.5.1

package/README.md

@@ -20,9 +20,10 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **What it finds** | shadowed IDs, duplicates, long descriptions, oversized bodies, per-step token budget, broken file references, invalid frontmatter, empty bodies, stale skills |
 | **What it fixes** | archives shadowed definitions (reversible), hides low-frequency skills, syncs catalogs with drift detection |
 | **Reports** | terminal, JSON, or a self-contained HTML report (`--html [file] --open`) |
+| **Plan** | exact token savings: trim descriptions and/or hide skills, projected over N steps |
 | **Cost** | CLI: 0 tokens. Plugin: ~191 tokens/step for the tool definition, plus a one-time warning per session |
 | **Requirements** | Node ≥ 20, zero runtime dependencies |
-| **Quality** | 50 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 55 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -102,6 +103,23 @@ skills-doctor check --html report.html --open
 
 The plugin and MCP tool accept the same thing as an `html` argument, so the agent can ask you where to save it — for example: *"save the report to D:\reports\skills.html"*.
 
+### `plan` (how many tokens can I actually save?)
+
+```powershell
+skills-doctor plan
+skills-doctor plan --budget 800 --desc-target 160 --steps 200
+skills-doctor plan --json
+```
+
+It answers "how much can I cut, exactly?":
+
+- only **advertised** definitions cost tokens — archiving shadowed duplicates saves 0, and the plan says so instead of pretending;
+- **Option A** trims every description longer than `--desc-target` (default 160 chars, cut at sentence boundaries) and computes the exact saving;
+- **Option B** hides the fewest skills needed to reach the budget (still loadable with `@id`; picking the largest savings first is optimal for "minimal hides");
+- **Recommended** trims first, then hides, with no double counting, and projects the saving over `--steps` model steps (default 100).
+
+`check` prints a one-line pointer when you are over budget, and the HTML report shows the same potential-savings card.
+
 ### `scan`
 
 Lists every skill with its source, precedence, whether the model can see it, and token cost.
@@ -246,6 +264,21 @@ It registers the same `skills_doctor` tool. 1.x plugins cannot register commands
 
 > The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
+### OpenCode Desktop
+
+The desktop app bundles the same OpenCode core and reads the **same config directory** as the CLI (`~/.config/opencode`; its UI settings live elsewhere), so one install covers both:
+
+```powershell
+npx opencode-skills-doctor install --client desktop
+```
+
+- detects the app in the standard install locations and reads its bundled core version from `resources/app.asar` (e.g. 1.17.11), then uses the matching plugin API;
+- writes the same plugin entry and `/skills-doctor`, `/skills-report`, `/skills-upgrade` commands as the CLI install — restart the desktop app afterwards;
+- `--client auto` (default) prefers the CLI version when both are installed; `--client opencode` skips desktop detection;
+- `uninstall --client desktop` reverses it.
+
+Verified on Windows: app at `%LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe`, sharing config with the `opencode` CLI.
+
 ### Deep integration (one command)
 
 ```powershell
@@ -468,13 +501,13 @@ Executing code is free, but the tool definition is part of the model's context.
 
 ## Roadmap
 
-- v0.5: CI governance (baseline that only reports new issues, official GitHub Action), content-aware suggestions (which skills are never used), catalog signature verification
+- v0.6: CI governance (baseline that only reports new issues, official GitHub Action), content-aware suggestions (which skills are never used), catalog signature verification
 - Later: V1/Claude skill migration report
 
 ## Development and contributing
 
 ```powershell
-npm test          # 50 tests (node test/doctor.test.mjs)
+npm test          # 55 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/docs/README.zh-CN.md

@@ -20,9 +20,10 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
 | **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
 | **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
+| **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 50 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 55 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -102,6 +103,23 @@ skills-doctor check --html report.html --open
 
 插件和 MCP 工具同样接受 `html` 参数，所以可以让 agent 先问你要存哪里——例如：*"把报告存到 D:\reports\skills.html"*。
 
+### `plan`（到底能省多少 token？）
+
+```powershell
+skills-doctor plan
+skills-doctor plan --budget 800 --desc-target 160 --steps 200
+skills-doctor plan --json
+```
+
+回答「能省多少、怎么省」：
+
+- 只有**会展示给模型**的定义才花 token —— 归档遮蔽重复定义省 0，方案里会明说，不糊弄；
+- **方案 A**：把所有超过 `--desc-target`（默认 160 字符，按句子边界截断）的 description 精简，算出精确节省；
+- **方案 B**：用最少的隐藏数量把总量压进预算（仍可 `@id` 加载；按单项节省从大到小取，对「最少隐藏数」是最优的）；
+- **推荐方案**：先精简再隐藏，不重复计算，并按 `--steps`（默认 100）折算总节省。
+
+超预算时 `check` 会打印一行提示，HTML 报告里有同样的「potential savings」卡片。
+
 ### `scan`
 
 列出所有 skill 及其来源、优先级、是否会被模型看到、token 占用。
@@ -246,6 +264,21 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 
 > 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
+### OpenCode Desktop
+
+桌面版内置的是同一套 OpenCode core，读的也是**同一个配置目录**（`~/.config/opencode`；桌面 UI 的设置另存），所以一次安装两边都生效：
+
+```powershell
+npx opencode-skills-doctor install --client desktop
+```
+
+- 在标准安装位置探测桌面版，并从 `resources/app.asar` 读出内置 core 版本（例如 1.17.11），据此选择对应插件 API；
+- 写入与 CLI 相同的插件条目和 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 命令 —— 装完重启桌面应用；
+- `--client auto`（默认）在同时装了 CLI 时优先 CLI 版本；`--client opencode` 跳过桌面探测；
+- `uninstall --client desktop` 反向撤销。
+
+已在 Windows 验证：应用位于 `%LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe`，与 `opencode` CLI 共用配置。
+
 ### 一键深度集成
 
 ```powershell
@@ -468,13 +501,13 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 
 ## Roadmap
 
-- v0.5：CI 治理（baseline 只报新增问题、官方 GitHub Action）、内容层建议（哪些 skill 从未被使用）、catalog 签名校验
+- v0.6：CI 治理（baseline 只报新增问题、官方 GitHub Action）、内容层建议（哪些 skill 从未被使用）、catalog 签名校验
 - 后续：V1/Claude skill 兼容迁移报告
 
 ## 开发与贡献
 
 ```powershell
-npm test          # 50 个测试（node test/doctor.test.mjs）
+npm test          # 55 个测试（node test/doctor.test.mjs）
 npm run bench     # 100/500/1000 个 skill 的 lint 耗时
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, HTML reports, catalog sync. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI and Cursor skill layouts.",
   "type": "module",
   "exports": {

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { writeHtmlReport, openReport } from "./html.mjs"
+import { planBudget } from "./plan.mjs"
 import {
   checkForUpdate,
   resolveMode,
@@ -70,18 +71,21 @@ function parseArgs(argv) {
     into: null,
     checkOnly: false,
     prune: false,
+    client: "auto",
     configDir: null,
     noNpm: false,
     html: null,
     open: false,
     apply: false,
     updateCheck: true,
+    descTarget: 160,
+    steps: 100,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
+  const commands = new Set(["check", "scan", "plan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -101,6 +105,12 @@ function parseArgs(argv) {
       case "--stale-days":
         options.staleDays = Number(args[++i])
         break
+      case "--desc-target":
+        options.descTarget = Number(args[++i])
+        break
+      case "--steps":
+        options.steps = Number(args[++i])
+        break
       case "--strict":
         options.strict = true
         break
@@ -139,6 +149,10 @@ function parseArgs(argv) {
       case "--config-dir":
         options.configDir = path.resolve(args[++i] ?? ".")
         break
+      case "--client": {
+        options.client = String(args[++i] ?? "").toLowerCase()
+        break
+      }
       case "--no-npm":
         options.noNpm = true
         break
@@ -279,6 +293,92 @@ function printCheck(audit, result, options, t) {
     console.log(bold(t("check.hints")))
     for (const rule of usedRules) console.log(dim(`  - ${t(HINT_KEYS[rule])}`))
   }
+
+  if (audit.summary.advertisedTokens > audit.budget) {
+    const plan = planBudget(audit)
+    if (plan.recommended.savings > 0) {
+      console.log("")
+      console.log(yellow(t("check.planHint", { tokens: plan.recommended.savings })))
+    }
+  }
+}
+
+function printPlan(plan, t) {
+  console.log(bold(t("plan.title")))
+  console.log(dim(t("plan.current", { tokens: plan.current, count: plan.advertised })))
+  console.log(dim(t("plan.budget", { budget: plan.budget, gap: plan.gap })))
+  console.log(dim(t("plan.steps", { steps: plan.steps })))
+  console.log("")
+
+  const sessionLine = (savings) => {
+    if (plan.steps > 0 && savings > 0) console.log(dim(t("plan.session", { tokens: savings * plan.steps, steps: plan.steps })))
+  }
+
+  if (plan.current <= plan.budget) {
+    console.log(green(t("plan.under")))
+    if (plan.trim.count) {
+      console.log("")
+      console.log(bold(t("plan.trimTitle", { chars: plan.descTarget })))
+      console.log(
+        t("plan.trimLine", {
+          count: plan.trim.count,
+          savings: plan.trim.savings,
+          final: Math.max(0, plan.current - plan.trim.savings),
+        }),
+      )
+      sessionLine(plan.trim.savings)
+    }
+    return
+  }
+
+  console.log(bold(t("plan.trimTitle", { chars: plan.descTarget })))
+  if (plan.trim.count) {
+    console.log(
+      t("plan.trimLine", {
+        count: plan.trim.count,
+        savings: plan.trim.savings,
+        final: Math.max(0, plan.current - plan.trim.savings),
+      }),
+    )
+    for (const item of plan.trim.items.slice(0, 10)) {
+      console.log(dim(t("plan.trimItem", { id: item.id, saving: item.saving })))
+    }
+    if (plan.trim.items.length > 10) console.log(dim(t("plan.more", { count: plan.trim.items.length - 10 })))
+  } else {
+    console.log(dim(t("plan.trimNone")))
+  }
+  console.log("")
+
+  console.log(bold(t("plan.hideTitle")))
+  if (plan.hideOnly.count) {
+    console.log(
+      t("plan.hideLine", {
+        count: plan.hideOnly.count,
+        savings: plan.hideOnly.savings,
+        final: plan.hideOnly.final,
+      }),
+    )
+  } else {
+    console.log(dim(t("plan.hideNone")))
+  }
+  console.log("")
+
+  console.log(bold(t("plan.recTitle")))
+  console.log(
+    t("plan.recLine", {
+      trims: plan.trim.count,
+      hides: plan.recommended.hides.length,
+      final: plan.recommended.final,
+      savings: plan.recommended.savings,
+    }),
+  )
+  for (const item of plan.recommended.hides) {
+    console.log(dim(t("plan.hideItem", { id: item.id, tokens: item.tokens })))
+  }
+  if (plan.recommended.hidesEverything) console.log(yellow(t("plan.hidesAll")))
+  sessionLine(plan.recommended.savings)
+  console.log("")
+  console.log(dim(t("plan.next")))
 }
 
 function printScan(discovered, options, managed, t) {
@@ -491,6 +591,12 @@ export async function main(argv) {
     process.exit(2)
   }
 
+  if (!["auto", "opencode", "desktop"].includes(options.client)) {
+    console.error("unsupported --client: expected auto, opencode or desktop")
+    process.exitCode = 2
+    return
+  }
+
   const cwd = path.resolve(options.root)
   const loaded = loadConfig(cwd, options.config)
   const lang = normalizeLang(options.lang) ?? normalizeLang(loaded.config.lang) ?? detectLang()
@@ -515,6 +621,7 @@ export async function main(argv) {
       configDir: options.configDir ?? undefined,
       dryRun: options.dryRun,
       installPackage: !options.noNpm,
+      client: options.client,
     })
     if (options.json) {
       console.log(JSON.stringify(result, null, 2))
@@ -522,6 +629,12 @@ export async function main(argv) {
       console.log(bold(t("install.title")))
       console.log(dim(t("install.version", { version: result.version ?? "unknown" })))
       console.log(dim(t("install.configDir", { dir: result.configDir })))
+      console.log(dim(t("install.client", { client: result.client?.mode ?? options.client })))
+      if (result.client?.desktop) {
+        console.log(
+          dim(t("install.desktop", { version: result.client.desktop.version ?? "unknown", exe: result.client.desktop.exe })),
+        )
+      }
       if (result.dryRun) console.log(dim(t("install.dryRun")))
       for (const action of result.actions) console.log(`  · ${action}`)
       for (const error of result.errors) console.log(red(t("install.error", { error })))
@@ -537,6 +650,7 @@ export async function main(argv) {
       configDir: options.configDir ?? undefined,
       dryRun: options.dryRun,
       removePackage: !options.noNpm,
+      client: options.client,
     })
     if (options.json) {
       console.log(JSON.stringify(result, null, 2))
@@ -544,6 +658,12 @@ export async function main(argv) {
       console.log(bold(t("uninstall.title")))
       console.log(dim(t("install.version", { version: result.version ?? "unknown" })))
       console.log(dim(t("install.configDir", { dir: result.configDir })))
+      console.log(dim(t("install.client", { client: result.client?.mode ?? options.client })))
+      if (result.client?.desktop) {
+        console.log(
+          dim(t("install.desktop", { version: result.client.desktop.version ?? "unknown", exe: result.client.desktop.exe })),
+        )
+      }
       if (result.dryRun) console.log(dim(t("install.dryRun")))
       for (const action of result.actions) console.log(`  · ${action}`)
       for (const error of result.errors) console.log(red(t("install.error", { error })))
@@ -592,6 +712,21 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "plan") {
+    const audit = auditSkills({
+      cwd,
+      includeGlobal: options.global,
+      lang,
+      configPath: options.config,
+      budget: options.budget,
+      staleDays: options.staleDays,
+    })
+    const plan = planBudget(audit, { descTarget: options.descTarget, steps: options.steps })
+    if (options.json) console.log(JSON.stringify(plan, null, 2))
+    else printPlan(plan, t)
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/desktop.mjs

@@ -0,0 +1,80 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+const APP_NAME = "OpenCode"
+
+/** 各平台 OpenCode Desktop 的常见安装位置。 */
+export function desktopCandidates(platform = process.platform, env = process.env, home = os.homedir()) {
+  if (platform === "win32") {
+    const local = env.LOCALAPPDATA || path.join(home, "AppData", "Local")
+    return [
+      path.join(local, "Programs", "@opencode-aidesktop", "OpenCode.exe"),
+      path.join(local, "Programs", "opencode", "OpenCode.exe"),
+      path.join(local, "Programs", "opencode-desktop", "OpenCode.exe"),
+      path.join(local, "opencode-desktop", "OpenCode.exe"),
+    ]
+  }
+  if (platform === "darwin") {
+    return ["/Applications/OpenCode.app/Contents/MacOS/OpenCode", path.join(home, "Applications", "OpenCode.app", "Contents", "MacOS", "OpenCode")]
+  }
+  return ["/usr/bin/opencode-desktop", "/usr/local/bin/opencode-desktop", "/opt/OpenCode/opencode-desktop", "/opt/opencode-desktop/opencode-desktop"]
+}
+
+function asarPathFor(exe) {
+  if (process.platform === "darwin" || exe.includes(".app")) {
+    return path.join(path.dirname(path.dirname(path.dirname(path.dirname(exe)))), "Resources", "app.asar")
+  }
+  return path.join(path.dirname(exe), "resources", "app.asar")
+}
+
+/**
+ * 读取 app.asar 里的 package.json.version（不解包整个 asar）。
+ * asar 头结构：[u32 4][u32 headerSize][u32 stringSize][u32 jsonSize][json][content…]
+ */
+export function readAsarVersion(asarFile) {
+  let fd
+  try {
+    fd = fs.openSync(asarFile, "r")
+    const head = Buffer.alloc(16)
+    fs.readSync(fd, head, 0, 16, 0)
+    const headerSize = head.readUInt32LE(4)
+    const jsonSize = head.readUInt32LE(12)
+    if (!jsonSize || jsonSize > 64 * 1024 * 1024) return null
+    const json = Buffer.alloc(jsonSize)
+    fs.readSync(fd, json, 0, jsonSize, 16)
+    const header = JSON.parse(json.toString("utf8"))
+    const entry = header?.files?.["package.json"]
+    if (!entry || typeof entry.offset !== "string") return null
+    const size = Number(entry.size ?? 0)
+    if (!Number.isFinite(size) || size <= 0 || size > 1024 * 1024) return null
+    const contentStart = 8 + headerSize
+    const data = Buffer.alloc(size)
+    fs.readSync(fd, data, 0, size, contentStart + Number(entry.offset))
+    const pkg = JSON.parse(data.toString("utf8"))
+    return typeof pkg.version === "string" ? pkg.version : null
+  } catch {
+    return null
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd)
+      } catch {}
+    }
+  }
+}
+
+/**
+ * 探测本机是否装了 OpenCode Desktop，并读取它内置 core 的版本。
+ * Desktop 与 CLI 共用 ~/.config/opencode，所以插件/命令配置不需要第二份。
+ */
+export function detectDesktop({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  for (const exe of desktopCandidates(platform, env, home)) {
+    if (!fs.existsSync(exe)) continue
+    const version = readAsarVersion(asarPathFor(exe))
+    return { installed: true, exe, version, asar: asarPathFor(exe) }
+  }
+  return { installed: false, exe: null, version: null, asar: null }
+}
+
+export const DESKTOP_APP = APP_NAME

package/src/html.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs"
 import path from "node:path"
 import { spawn } from "node:child_process"
+import { planBudget } from "./plan.mjs"
 
 function esc(value) {
   return String(value ?? "").replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char])
@@ -13,6 +14,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
   const summary = audit.summary
   const counts = audit.counts
   const budget = audit.budget
+  const plan = planBudget(audit)
   const ratio = budget > 0 ? Math.min(1.5, summary.advertisedTokens / (budget * 2)) : 0
   const barWidth = Math.min(100, Math.round(ratio * 100))
   const barClass = summary.advertisedTokens > budget * 2 ? "over" : summary.advertisedTokens > budget ? "warn" : "ok"
@@ -89,6 +91,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
     <div class="card"><div class="k">unique IDs</div><div class="v">${summary.unique}</div></div>
     <div class="card"><div class="k">advertised</div><div class="v">${summary.advertised}</div></div>
     <div class="card"><div class="k">description tokens / step</div><div class="v">${summary.advertisedTokens}</div></div>
+    <div class="card"><div class="k">potential savings / step</div><div class="v">${plan.recommended.savings}</div></div>
     <div class="card error"><div class="k">errors</div><div class="v">${counts.errors}</div></div>
     <div class="card warn"><div class="k">warnings</div><div class="v">${counts.warnings}</div></div>
     <div class="card info"><div class="k">info</div><div class="v">${counts.infos}</div></div>
@@ -97,6 +100,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
   <h2>Context budget</h2>
   <div class="bar"><span class="${barClass}"></span></div>
   <div class="sub">${summary.advertisedTokens} tokens vs budget ${budget}${summary.advertisedTokens > budget * 2 ? " (over 2x)" : summary.advertisedTokens > budget ? " (over)" : " (ok)"}</div>
+  <div class="sub">plan: trim ${plan.trim.count} + hide ${plan.recommended.hides.length} → ~${plan.recommended.final} tokens/step (saves ~${plan.recommended.savings}; ~${plan.recommended.stepsSavings} over ${plan.steps} steps)</div>
 
   <h2>Findings (${audit.findings.length})</h2>
   <div class="toolbar">

package/src/i18n.mjs

@@ -7,6 +7,7 @@ const dict = {
 
 Usage:
   skills-doctor check  [options]   check sources, conflicts and context budget (default)
+  skills-doctor plan   [options]   estimate how many tokens you can save, and how
   skills-doctor scan   [options]   list every skill with its source and precedence
   skills-doctor fix    [options]   archive shadowed definitions (safe structural fixes)
   skills-doctor update [options]   compare and download skills from HTTP catalogs
@@ -19,6 +20,8 @@ Options:
   --root <dir>         working directory (default: current directory)
   --no-global          skip ~/.claude, ~/.agents and ~/.config/opencode
   --budget <n>         tokens allowed for advertised descriptions (default 1200)
+  --desc-target <n>    plan: target description length in chars (default 160)
+  --steps <n>          plan: project savings over n model steps (default 100)
   --stale-days <n>     report skills not updated in n days (default: off)
   --strict             exit non-zero on warnings too
   --json               print JSON
@@ -33,6 +36,7 @@ Options:
   --html [file]        check: write a self-contained HTML report (default: skills-report.html)
   --open               check: open the HTML report after writing it
   --config-dir <dir>   install/uninstall: OpenCode config directory (default: ~/.config/opencode)
+  --client <name>      install/uninstall: auto | opencode | desktop (default auto)
   --no-npm             install/uninstall: do not run npm (1.x)
   --apply              upgrade: run npm install -g opencode-skills-doctor@latest
   --no-update-check    skip the automatic update check for this run
@@ -56,6 +60,27 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": " (--strict: warnings also fail)",
     "check.hints": "Hints:",
+    "check.planHint": "  ! potential: about {tokens} tokens/step can be saved; run `skills-doctor plan` for the breakdown",
+
+    "plan.title": "skills-doctor plan",
+    "plan.current": "  current: ~{tokens} tokens/step ({count} advertised skills)",
+    "plan.budget": "  budget: {budget}  gap: {gap}",
+    "plan.steps": "  projection: {steps} model steps",
+    "plan.under": "Under budget — no changes needed.",
+    "plan.trimTitle": "Option A — trim descriptions to {chars} chars (stays discoverable)",
+    "plan.trimLine": "  {count} skills, saves ~{savings} tokens/step → ~{final} tokens",
+    "plan.trimNone": "  nothing to trim.",
+    "plan.trimItem": "    - {id} (−{saving})",
+    "plan.hideTitle": "Option B — hide skills (autoinvoke: false, still loadable with @id)",
+    "plan.hideLine": "  hide {count} skills, saves ~{savings} tokens/step → ~{final} tokens",
+    "plan.hideNone": "  no hide needed.",
+    "plan.recTitle": "Recommended",
+    "plan.recLine": "  trim {trims} + hide {hides} → ~{final} tokens/step (saves ~{savings})",
+    "plan.hideItem": "    - hide {id} (−{tokens})",
+    "plan.hidesAll": "  ! this would hide every skill; consider raising the budget instead.",
+    "plan.session": "  over {steps} steps that saves ~{tokens} tokens",
+    "plan.more": "    …and {count} more",
+    "plan.next": "Next: hide with `skills-doctor fix --hide <ids>`, or trim descriptions and keep discoverability.",
 
     "scan.title": "skills-doctor {version} — scan",
     "scan.workdir": "  working dir: {dir}",
@@ -87,6 +112,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.title": "OpenCode integration",
     "install.version": "  OpenCode: {version}",
     "install.configDir": "  config dir: {dir}",
+    "install.client": "  client: {client}",
+    "install.desktop": "  OpenCode Desktop: {version} ({exe})",
     "install.dryRun": "  (dry run: nothing is written)",
     "install.error": "  ✗ {error}",
     "install.failed": "Integration failed.",
@@ -192,6 +219,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
 
 用法:
   skills-doctor check  [选项]   检查来源、冲突与上下文预算（默认命令）
+  skills-doctor plan   [选项]   估算能省多少 token、怎么省
   skills-doctor scan   [选项]   列出所有 skill 及其来源/优先级
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
@@ -204,6 +232,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --root <dir>        以该目录为工作目录（默认当前目录）
   --no-global         不扫描 ~/.claude、~/.agents、~/.config/opencode
   --budget <n>        模型每步可看的 description token 预算（默认 1200）
+  --desc-target <n>   plan: description 目标字符数（默认 160）
+  --steps <n>         plan: 按 n 个模型步骤折算节省量（默认 100）
   --stale-days <n>    超过 n 天未更新的 skill 给出提示（默认关闭）
   --strict            有 warning 也返回非 0
   --json              输出 JSON
@@ -218,6 +248,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --html [file]       check: 生成自包含 HTML 报告（默认 skills-report.html）
   --open              check: 写完报告后用浏览器打开
   --config-dir <dir>  install/uninstall: OpenCode 配置目录（默认 ~/.config/opencode）
+  --client <name>     install/uninstall: auto | opencode | desktop（默认 auto）
   --no-npm            install/uninstall: 不执行 npm（1.x）
   --apply             upgrade: 执行 npm install -g opencode-skills-doctor@latest
   --no-update-check   本次运行跳过自动更新检查
@@ -241,6 +272,27 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": "（--strict：warning 也会非 0 退出）",
     "check.hints": "建议:",
+    "check.planHint": "  ! 预计每步还能省约 {tokens} tokens；运行 `skills-doctor plan` 看具体方案",
+
+    "plan.title": "skills-doctor 省 token 方案",
+    "plan.current": "  当前: 约 {tokens} tokens/步（{count} 个会展示的 skill）",
+    "plan.budget": "  预算: {budget}  差距: {gap}",
+    "plan.steps": "  折算: {steps} 个模型步骤",
+    "plan.under": "已在预算内，无需改动。",
+    "plan.trimTitle": "方案 A —— 精简 description 到 {chars} 字符（仍可被发现）",
+    "plan.trimLine": "  {count} 个 skill，每步省约 {savings} tokens → 约 {final} tokens",
+    "plan.trimNone": "  没有需要精简的。",
+    "plan.trimItem": "    - {id}（−{saving}）",
+    "plan.hideTitle": "方案 B —— 隐藏 skill（autoinvoke: false，仍可 @id 加载）",
+    "plan.hideLine": "  隐藏 {count} 个，每步省约 {savings} tokens → 约 {final} tokens",
+    "plan.hideNone": "  无需隐藏。",
+    "plan.recTitle": "推荐方案",
+    "plan.recLine": "  精简 {trims} 个 + 隐藏 {hides} 个 → 约 {final} tokens/步（省约 {savings}）",
+    "plan.hideItem": "    - 隐藏 {id}（−{tokens}）",
+    "plan.hidesAll": "  ! 这样会把所有 skill 都隐藏；建议改为提高预算。",
+    "plan.session": "  按 {steps} 步计算，共省约 {tokens} tokens",
+    "plan.more": "    …还有 {count} 个",
+    "plan.next": "下一步：用 `skills-doctor fix --hide <ids>` 隐藏，或精简 description 保留可发现性。",
 
     "scan.title": "skills-doctor {version} — scan",
     "scan.workdir": "  工作目录: {dir}",
@@ -272,6 +324,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.title": "OpenCode 集成",
     "install.version": "  OpenCode: {version}",
     "install.configDir": "  配置目录: {dir}",
+    "install.client": "  客户端: {client}",
+    "install.desktop": "  OpenCode Desktop: {version}（{exe}）",
     "install.dryRun": "  （dry run：不会写入任何内容）",
     "install.error": "  ✗ {error}",
     "install.failed": "集成失败。",

package/src/install.mjs

@@ -3,6 +3,7 @@ import path from "node:path"
 import os from "node:os"
 import { spawnSync, execFileSync } from "node:child_process"
 import { stripJsonc } from "./discover.mjs"
+import { detectDesktop } from "./desktop.mjs"
 
 export const PACKAGE_NAME = "opencode-skills-doctor"
 const PLUGIN_FILE = "skills-doctor.js"
@@ -106,7 +107,13 @@ function installPackage(dir) {
  * - 2.x：写入 plugins 数组（OpenCode 自己从 npm 拉包）
  * - 1.x：在配置目录安装包、写本地插件入口、写 /skills-doctor 命令、补插件数组
  */
-export function installOpenCode({ configDir = defaultConfigDir(), version = null, dryRun = false, installPackage: withPackage = true } = {}) {
+export function installOpenCode({
+  configDir = defaultConfigDir(),
+  version = null,
+  dryRun = false,
+  installPackage: withPackage = true,
+  client = "auto",
+} = {}) {
   const dir = path.resolve(configDir)
   const actions = []
   const errors = []
@@ -125,14 +132,31 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
     }
   }
 
-  const resolvedVersion = version ?? detectVersion()
+  const desktop = client === "opencode" ? { installed: false, exe: null, version: null } : detectDesktop()
+  if (client === "desktop" && !desktop.installed) {
+    errors.push("OpenCode Desktop not found in the standard install locations")
+    act("install OpenCode Desktop first (https://opencode.ai/download), or use --client auto")
+    return { version: null, major: null, configDir: dir, configFile: cfgFile, actions, errors, dryRun, client: { mode: client, desktop: null } }
+  }
+
+  const resolvedVersion = version ?? detectVersion() ?? desktop.version
   const inferredMajor = config.plugin !== undefined ? 1 : 2
   const major = resolvedVersion ? Number(resolvedVersion.split(".")[0]) : inferredMajor
+  const clientInfo = {
+    mode: client,
+    desktop: desktop.installed ? { exe: desktop.exe, version: desktop.version } : null,
+  }
+  if (desktop.installed) act(`OpenCode Desktop ${desktop.version ?? "unknown"} detected at ${desktop.exe}`)
+  if (desktop.installed) act("desktop and CLI share the same config directory")
 
   if (dryRun) dry(`config dir: ${dir}`)
   if (!fs.existsSync(dir)) {
-    if (!dryRun) fs.mkdirSync(dir, { recursive: true })
-    act(`created config dir ${dir}`)
+    if (!dryRun) {
+      fs.mkdirSync(dir, { recursive: true })
+      act(`created config dir ${dir}`)
+    } else {
+      dry(`create config dir ${dir}`)
+    }
   }
 
   const stamp = new Date().toISOString().replace(/[:.]/g, "-")
@@ -151,7 +175,7 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
       act(`plugins already contains "${PACKAGE_NAME}"`)
     }
     act("restart OpenCode; the /skills-doctor command and skills_doctor tool will be available")
-    return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+    return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun, client: clientInfo }
   }
 
   // 1.x
@@ -226,7 +250,7 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
   }
 
   act("restart OpenCode; the skills_doctor tool and /skills-doctor command will be available")
-  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun, client: clientInfo }
 }
 
 function removePackage(dir) {
@@ -243,7 +267,13 @@ function removePackage(dir) {
  * 撤销 install：移除配置里的插件条目、删除安装器生成的文件、可选卸载 npm 包。
  * 只删除「由安装器生成」的文件，用户自己改过的一律保留并提示。
  */
-export function uninstallOpenCode({ configDir = defaultConfigDir(), version = null, dryRun = false, removePackage: withPackage = true } = {}) {
+export function uninstallOpenCode({
+  configDir = defaultConfigDir(),
+  version = null,
+  dryRun = false,
+  removePackage: withPackage = true,
+  client = "auto",
+} = {}) {
   const dir = path.resolve(configDir)
   const actions = []
   const errors = []
@@ -262,7 +292,13 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
     }
   }
 
-  const resolvedVersion = version ?? detectVersion()
+  const desktop = client === "opencode" ? { installed: false, exe: null, version: null } : detectDesktop()
+  const clientInfo = {
+    mode: client,
+    desktop: desktop.installed ? { exe: desktop.exe, version: desktop.version } : null,
+  }
+
+  const resolvedVersion = version ?? detectVersion() ?? desktop.version
   const inferredMajor = config.plugin !== undefined ? 1 : 2
   const major = resolvedVersion ? Number(resolvedVersion.split(".")[0]) : inferredMajor
   const stamp = new Date().toISOString().replace(/[:.]/g, "-")
@@ -280,7 +316,7 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
       act(`"${PACKAGE_NAME}" is not configured in plugins`)
     }
     act("restart OpenCode to finish removal")
-    return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+    return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun, client: clientInfo }
   }
 
   const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
@@ -338,5 +374,5 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
   }
 
   act("restart OpenCode to finish removal")
-  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun, client: clientInfo }
 }

package/src/plan.mjs

@@ -0,0 +1,142 @@
+import { estimateTokens } from "./parse.mjs"
+import { resolveWinners } from "./lint.mjs"
+
+export const DEFAULT_DESC_TARGET = 160
+export const DEFAULT_STEPS = 100
+
+function costOf(skill, description = skill.description) {
+  return estimateTokens(`${skill.id} ${skill.displayName} ${description}`)
+}
+
+/**
+ * 把 description 截到目标长度，优先在句子边界断开（中英文标点都算）。
+ * 纯函数：相同输入永远得到相同输出，便于在报告里预览「如果这么改会省多少」。
+ */
+export function trimDescription(text, limit = DEFAULT_DESC_TARGET) {
+  const value = String(text ?? "")
+  if (value.length <= limit) return value
+  const slice = value.slice(0, limit)
+  const cut = Math.max(
+    slice.lastIndexOf("。"),
+    slice.lastIndexOf("."),
+    slice.lastIndexOf("！"),
+    slice.lastIndexOf("？"),
+    slice.lastIndexOf("；"),
+    slice.lastIndexOf(";"),
+    slice.lastIndexOf("\n"),
+  )
+  const trimmed = cut >= limit * 0.5 ? value.slice(0, cut + 1).trim() : slice.trim()
+  return trimmed || slice.trim()
+}
+
+/** 在候选中选「数量最少」的一组，使节省量 ≥ gap；按单项节省降序取前缀即为最优。 */
+function pickMinimal(items, gap) {
+  if (gap <= 0) return { count: 0, savings: 0, items: [], enough: true }
+  const sorted = [...items].sort((a, b) => b.tokens - a.tokens || a.id.localeCompare(b.id))
+  const picked = []
+  let savings = 0
+  for (const item of sorted) {
+    if (savings >= gap) break
+    picked.push(item)
+    savings += item.tokens
+  }
+  return { count: picked.length, savings, items: picked, enough: savings >= gap }
+}
+
+/**
+ * 预算规划：当前每步消耗多少、精简到多少、隐藏多少、最终能省多少。
+ *
+ * 规则：
+ * - 只有会被「展示给模型」的定义才有成本；被遮蔽的重复定义省不出 token（诚实很重要）。
+ * - 精简 description 不改变可发现性；隐藏（autoinvoke: false）省掉整条成本，但仍可用 @id 加载。
+ * - 推荐方案先精简所有超长描述，再按「单项节省最大」贪心隐藏，直到进入预算。
+ *   被隐藏的技能若也被精简过，其节省按原始成本计，不会重复计算。
+ */
+export function planBudget(
+  audit,
+  { budget = audit.budget, descTarget = DEFAULT_DESC_TARGET, steps = DEFAULT_STEPS } = {},
+) {
+  const target = Number.isFinite(budget) && budget > 0 ? budget : audit.budget
+  const winners = [...resolveWinners(audit.skills).values()]
+  const advertised = winners.filter((skill) => skill.advertised)
+
+  const current = advertised.reduce((sum, skill) => sum + costOf(skill), 0)
+  const gap = Math.max(0, current - target)
+
+  // 1) 精简：所有 description 超过目标的，按句子边界截断
+  const trimMap = new Map()
+  const trims = []
+  for (const skill of advertised) {
+    if (skill.description.length <= descTarget) continue
+    const preview = trimDescription(skill.description, descTarget)
+    const before = costOf(skill)
+    const after = costOf(skill, preview)
+    const saving = Math.max(0, before - after)
+    if (!saving) continue
+    trimMap.set(skill.id, { preview, cost: after })
+    trims.push({
+      id: skill.id,
+      file: skill.file,
+      before,
+      after,
+      saving,
+      preview,
+    })
+  }
+  trims.sort((a, b) => b.saving - a.saving || a.id.localeCompare(b.id))
+  const trimSavings = trims.reduce((sum, item) => sum + item.saving, 0)
+
+  // 2) 只隐藏（不精简）的方案
+  const hideCandidates = advertised.map((skill) => ({
+    id: skill.id,
+    file: skill.file,
+    tokens: costOf(skill),
+  }))
+  const hideOnly = pickMinimal(hideCandidates, gap)
+
+  // 3) 推荐方案：先精简，再在「精简后的成本」上隐藏
+  const afterTrim = advertised.map((skill) => ({
+    id: skill.id,
+    file: skill.file,
+    tokens: trimMap.get(skill.id)?.cost ?? costOf(skill),
+    originalTokens: costOf(skill),
+  }))
+  const postTrimTotal = afterTrim.reduce((sum, item) => sum + item.tokens, 0)
+  const recommendedHides = pickMinimal(afterTrim, Math.max(0, postTrimTotal - target))
+  const hideSavings = recommendedHides.savings
+  const savings = trimSavings + hideSavings
+  const final = Math.max(0, current - savings)
+
+  return {
+    cwd: audit.cwd,
+    budget: target,
+    descTarget,
+    steps,
+    current,
+    gap,
+    advertised: advertised.length,
+    trim: {
+      count: trims.length,
+      savings: trimSavings,
+      items: trims,
+    },
+    hideOnly: {
+      count: hideOnly.count,
+      savings: hideOnly.savings,
+      final: Math.max(0, current - hideOnly.savings),
+      enough: hideOnly.enough,
+      items: hideOnly.items,
+    },
+    recommended: {
+      trims: trims.map((item) => item.id),
+      hides: recommendedHides.items,
+      trimSavings,
+      hideSavings,
+      savings,
+      final,
+      reachable: final <= target,
+      stepsSavings: savings * steps,
+      hidesEverything: advertised.length > 0 && recommendedHides.count === advertised.length,
+    },
+  }
+}