opencode-skills-doctor 0.5.0 → 0.5.2

package/README.md

@@ -23,7 +23,7 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **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** | 53 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 55 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -264,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
@@ -339,10 +354,20 @@ DSH ships an MCP client bundle (`@deepseek-ai/dsh-mcp-client`). Add one entry to
     args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
-Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor`.
+Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor` and accepts `directory`, `budget`, `lang`, `global` and `html`.
 
 On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
 
+#### Optional skill (tells the model when to audit)
+
+The repo ships a DSH skill at `skills/dsh-skills-doctor/`:
+
+```powershell
+Copy-Item -Recurse skills\dsh-skills-doctor "$env:USERPROFILE\.dsh\skills\"
+```
+
+DSH watches skill roots, so `skills-doctor-audit` appears in the catalog without a restart. The skill runs `check`/`plan`, explains the token impact, and only proposes fixes — it never edits skills without confirmation.
+
 ## How it works
 
 **Audit pipeline**
@@ -492,7 +517,7 @@ Executing code is free, but the tool definition is part of the model's context.
 ## Development and contributing
 
 ```powershell
-npm test          # 53 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

@@ -23,7 +23,7 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 53 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 55 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -264,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
@@ -339,10 +354,20 @@ DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile
     args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
-重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现。
+重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现，参数支持 `directory`、`budget`、`lang`、`global`、`html`。
 
 Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
 
+#### 可选技能包（告诉模型什么时候该体检）
+
+仓库自带一个 DSH skill：`skills/dsh-skills-doctor/`：
+
+```powershell
+Copy-Item -Recurse skills\dsh-skills-doctor "$env:USERPROFILE\.dsh\skills\"
+```
+
+DSH 会监听 skill 目录，`skills-doctor-audit` 无需重启就会出现在目录里。它会跑 `check`/`plan`、解释 token 影响，并且只提出修复建议 —— 不经确认不会改 skill 文件。
+
 ## 工作原理
 
 **审计流程**
@@ -492,7 +517,7 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 ## 开发与贡献
 
 ```powershell
-npm test          # 53 个测试（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.5.0",
+  "version": "0.5.2",
   "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": {
@@ -37,6 +37,7 @@
     "bin",
     "src",
     "docs",
+    "skills",
     "README.md",
     "SECURITY.md",
     "SECURITY.zh-CN.md"

package/skills/dsh-skills-doctor/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: skills-doctor-audit
+description: Audit installed agent skills for per-step token cost, shadowed duplicates, broken references and budget overruns, then propose concrete fixes.
+whenToUse: Use when the user mentions too many skills, context bloat, token cost, duplicate or missing skills, or asks for a skill health check.
+metadata:
+  author: wangyuchen5110
+  source: opencode-skills-doctor
+---
+
+# Skill audit workflow
+
+Audit the user's installed skills and turn the result into a short, actionable answer.
+Never modify skill files without explicit confirmation.
+
+## 1. Run the read-only audit
+
+```powershell
+npx -y opencode-skills-doctor check --json
+```
+
+Read `summary.advertisedTokens` (cost per model step), `summary.advertised` and `findings[]`.
+If the command fails, fall back to `opencode-skills-doctor` when installed globally, or ask the user to run it from the repo.
+
+## 2. Explain the top findings
+
+Report at most three findings, in plain language, each with its token impact:
+
+- `token-budget` — descriptions cost roughly N tokens on **every** model step;
+- `shadowed` — the same skill ID loads from several places, only one wins;
+- `long-description` / `large-body` — descriptions or bodies that are paid on every step / every invocation;
+- `broken-reference` — a `references/` or `scripts/` file the skill points at is missing.
+
+## 3. Show what can actually be saved
+
+```powershell
+npx -y opencode-skills-doctor plan --json
+```
+
+Report `recommended.savings` (per step), `recommended.final` and `recommended.stepsSavings`
+(per 100 steps). Explain the difference: trimming descriptions keeps discoverability; hiding a skill
+(`autoinvoke: false`) removes it from the advertised list but keeps `@id` loading.
+
+## 4. Propose fixes — do not apply silently
+
+- Hide low-frequency skills: `npx -y opencode-skills-doctor fix --hide id1,id2`
+- Archive shadowed duplicates (reversible): `npx -y opencode-skills-doctor fix`
+- Trim descriptions manually, keeping them discoverable
+- Ask first, then re-run `check` to confirm the new cost
+
+## 5. Optional shareable report
+
+```powershell
+npx -y opencode-skills-doctor check --html skills-report.html --open
+```

package/src/cli.mjs

@@ -71,6 +71,7 @@ function parseArgs(argv) {
     into: null,
     checkOnly: false,
     prune: false,
+    client: "auto",
     configDir: null,
     noNpm: false,
     html: null,
@@ -148,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
@@ -586,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()
@@ -610,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))
@@ -617,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 })))
@@ -632,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))
@@ -639,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 })))

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/i18n.mjs

@@ -36,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
@@ -111,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.",
@@ -245,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   本次运行跳过自动更新检查
@@ -320,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 }
 }