opencode-skills-doctor 0.5.1 → 0.6.0

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** | 55 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 57 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -342,7 +342,19 @@ It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and
 
 ### DeepSeek Harness (DSH)
 
-DSH ships an MCP client bundle (`@deepseek-ai/dsh-mcp-client`). Add one entry to your profile patch, e.g. `~/.dsh/profiles/<profile>/cordis.patch.yml`:
+One command installs both the MCP tool and a skill that tells the model when to audit:
+
+```powershell
+npx -y opencode-skills-doctor install --client dsh
+```
+
+It locates `~/.dsh/profiles/<profile>/cordis.patch.yml` (default `desktop`; otherwise `--profile <name>`), appends the `mcp-skills-doctor` entry idempotently, and copies the `skills-doctor-audit` skill into `~/.dsh/skills/`. Restart DSH to load the MCP tool; the skill is watched and appears without a restart.
+
+- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`, `html`;
+- `uninstall --client dsh` removes both the patch entry and the skill;
+- `--dsh-home <dir>` for a non-standard DSH home.
+
+Manual fallback — add this to the profile patch yourself:
 
 ```yaml
 - id: mcp-skills-doctor
@@ -354,8 +366,6 @@ 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`.
-
 On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
 
 ## How it works
@@ -507,7 +517,7 @@ Executing code is free, but the tool definition is part of the model's context.
 ## Development and contributing
 
 ```powershell
-npm test          # 55 tests (node test/doctor.test.mjs)
+npm test          # 57 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，零运行时依赖 |
-| **质量** | 55 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 57 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -342,7 +342,19 @@ args = ["-y", "opencode-skills-doctor", "mcp"]
 
 ### DeepSeek Harness（DSH）
 
-DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile 的 patch 里加一条，例如 `~/.dsh/profiles/<profile>/cordis.patch.yml`：
+一条命令同时装好 MCP 工具和「告诉模型什么时候该体检」的 skill：
+
+```powershell
+npx -y opencode-skills-doctor install --client dsh
+```
+
+它会找到 `~/.dsh/profiles/<profile>/cordis.patch.yml`（默认 `desktop`，否则用 `--profile <name>`），幂等地追加 `mcp-skills-doctor` 条目，并把 `skills-doctor-audit` 技能复制到 `~/.dsh/skills/`。重启 DSH 加载 MCP 工具；skill 目录有监听，无需重启。
+
+- 工具名 `mcp__skills_doctor__skills_doctor`，参数 `directory`、`budget`、`lang`、`global`、`html`；
+- `uninstall --client dsh` 同时移除配置条目和 skill；
+- `--dsh-home <dir>` 用于非默认的 DSH 主目录。
+
+手动兜底 —— 自己往 profile patch 里加：
 
 ```yaml
 - id: mcp-skills-doctor
@@ -354,8 +366,6 @@ DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile
     args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
-重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现。
-
 Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
 
 ## 工作原理
@@ -507,7 +517,7 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 ## 开发与贡献
 
 ```powershell
-npm test          # 55 个测试（node test/doctor.test.mjs）
+npm test          # 57 个测试（node test/doctor.test.mjs）
 npm run bench     # 100/500/1000 个 skill 的 lint 耗时
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-skills-doctor",
-  "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.",
+  "version": "0.6.0",
+  "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, Cursor and DeepSeek Harness.",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",
@@ -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

@@ -9,6 +9,7 @@ import { auditSkills } from "./audit.mjs"
 import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
+import { installDsh, uninstallDsh } from "./dsh.mjs"
 import { writeHtmlReport, openReport } from "./html.mjs"
 import { planBudget } from "./plan.mjs"
 import {
@@ -72,6 +73,8 @@ function parseArgs(argv) {
     checkOnly: false,
     prune: false,
     client: "auto",
+    profile: null,
+    dshHome: null,
     configDir: null,
     noNpm: false,
     html: null,
@@ -153,6 +156,12 @@ function parseArgs(argv) {
         options.client = String(args[++i] ?? "").toLowerCase()
         break
       }
+      case "--profile":
+        options.profile = args[++i] ?? null
+        break
+      case "--dsh-home":
+        options.dshHome = path.resolve(args[++i] ?? ".")
+        break
       case "--no-npm":
         options.noNpm = true
         break
@@ -591,8 +600,8 @@ export async function main(argv) {
     process.exit(2)
   }
 
-  if (!["auto", "opencode", "desktop"].includes(options.client)) {
-    console.error("unsupported --client: expected auto, opencode or desktop")
+  if (!["auto", "opencode", "desktop", "dsh"].includes(options.client)) {
+    console.error("unsupported --client: expected auto, opencode, desktop or dsh")
     process.exitCode = 2
     return
   }
@@ -616,6 +625,29 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "install" && options.client === "dsh") {
+    const result = installDsh({
+      home: options.dshHome ?? undefined,
+      profile: options.profile ?? undefined,
+      dryRun: options.dryRun,
+    })
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      console.log(bold(t("dsh.title")))
+      if (result.profile) console.log(dim(t("dsh.profile", { profile: result.profile })))
+      if (result.patchFile) console.log(dim(t("dsh.patch", { file: result.patchFile })))
+      if (result.skillDir) console.log(dim(t("dsh.skill", { dir: result.skillDir })))
+      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 })))
+      console.log("")
+      console.log(result.errors.length ? red(t("dsh.failed")) : dim(t("dsh.restart")))
+    }
+    process.exitCode = result.errors.length ? 1 : 0
+    return
+  }
+
   if (options.command === "install") {
     const result = installOpenCode({
       configDir: options.configDir ?? undefined,
@@ -645,6 +677,27 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "uninstall" && options.client === "dsh") {
+    const result = uninstallDsh({
+      home: options.dshHome ?? undefined,
+      profile: options.profile ?? undefined,
+      dryRun: options.dryRun,
+    })
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      console.log(bold(t("dsh.uninstallTitle")))
+      if (result.profile) console.log(dim(t("dsh.profile", { profile: result.profile })))
+      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 })))
+      console.log("")
+      console.log(result.errors.length ? red(t("dsh.failed")) : dim(t("dsh.restart")))
+    }
+    process.exitCode = result.errors.length ? 1 : 0
+    return
+  }
+
   if (options.command === "uninstall") {
     const result = uninstallOpenCode({
       configDir: options.configDir ?? undefined,

package/src/dsh.mjs

@@ -0,0 +1,185 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+import { fileURLToPath } from "node:url"
+
+export const ENTRY_ID = "mcp-skills-doctor"
+export const SERVER_NAME = "skills_doctor"
+export const SKILL_NAME = "skills-doctor-audit"
+
+const ENTRIES = `- id: ${ENTRY_ID}
+  name: "@deepseek-ai/dsh-mcp-client"
+  config:
+    serverName: ${SERVER_NAME}
+    transport: stdio
+    command: npx
+    args: ["-y", "opencode-skills-doctor", "mcp"]
+`
+
+export function dshHome(env = process.env) {
+  return env.DSH_HOME || path.join(os.homedir(), ".dsh")
+}
+
+export function profileDir(home, profile) {
+  return path.join(home, "profiles", profile)
+}
+
+/** DSH profile 目录（含 package.json 的子目录）。 */
+export function listProfiles(home) {
+  const dir = path.join(home, "profiles")
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(dir, entry.name, "package.json")))
+      .map((entry) => entry.name)
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+function pickProfile({ home, profile }) {
+  const profiles = listProfiles(home)
+  if (profile) {
+    if (!profiles.includes(profile)) {
+      return { error: `DSH profile "${profile}" not found under ${path.join(home, "profiles")}` }
+    }
+    return { profile, profiles }
+  }
+  if (profiles.includes("desktop")) return { profile: "desktop", profiles }
+  if (profiles.length === 1) return { profile: profiles[0], profiles }
+  if (!profiles.length) return { error: `no DSH profile found under ${path.join(home, "profiles")}` }
+  return { error: `multiple DSH profiles found (${profiles.join(", ")}); pass --profile <name>` }
+}
+
+function skillSourceDir() {
+  return fileURLToPath(new URL("../skills/dsh-skills-doctor", import.meta.url))
+}
+
+function copySkill(source, target, dryRun, act, dry) {
+  if (!fs.existsSync(source)) return false
+  const file = path.join(source, "SKILL.md")
+  if (!fs.existsSync(file)) return false
+  const targetFile = path.join(target, "SKILL.md")
+  if (fs.existsSync(targetFile) && fs.readFileSync(targetFile, "utf8") === fs.readFileSync(file, "utf8")) {
+    act(`skill already up to date ${target}`)
+    return true
+  }
+  if (dryRun) {
+    dry(`install skill ${SKILL_NAME} into ${target}`)
+    return true
+  }
+  fs.mkdirSync(target, { recursive: true })
+  fs.copyFileSync(file, targetFile)
+  act(`wrote skill ${targetFile}`)
+  return true
+}
+
+/** 在 cordis.patch.yml 里追加 MCP 条目（幂等）。 */
+function appendEntry(patchFile, dryRun, act, dry) {
+  const existing = fs.existsSync(patchFile) ? fs.readFileSync(patchFile, "utf8") : ""
+  if (existing.includes(ENTRY_ID) || existing.includes(`serverName: ${SERVER_NAME}`)) {
+    act(`MCP entry already present in ${patchFile}`)
+    return false
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+  if (dryRun) {
+    dry(`append ${ENTRY_ID} to ${patchFile}`)
+    return true
+  }
+  if (existing) fs.copyFileSync(patchFile, `${patchFile}.bak-${stamp}`)
+  const header = existing
+    ? (existing.endsWith("\n") ? "" : "\n")
+    : "# DSH profile patch layer\n"
+  const next = `${existing}${header}${existing.trim() ? "\n" : ""}${ENTRIES}`
+  fs.writeFileSync(patchFile, next, "utf8")
+  act(`appended ${ENTRY_ID} to ${patchFile}`)
+  return true
+}
+
+function removeEntry(patchFile, dryRun, act, dry) {
+  if (!fs.existsSync(patchFile)) return false
+  const text = fs.readFileSync(patchFile, "utf8")
+  const lines = text.split(/\r?\n/)
+  const index = lines.findIndex((line) => line.trim() === `- id: ${ENTRY_ID}`)
+  if (index < 0) return false
+
+  let end = index + 1
+  while (end < lines.length) {
+    const line = lines[end]
+    if (line.trim() === "" || /^[ \t]/.test(line)) end++
+    else break
+  }
+  if (dryRun) {
+    dry(`remove ${ENTRY_ID} from ${patchFile}`)
+    return true
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+  fs.copyFileSync(patchFile, `${patchFile}.bak-${stamp}`)
+  fs.writeFileSync(patchFile, lines.slice(0, index).concat(lines.slice(end)).join("\n"), "utf8")
+  act(`removed ${ENTRY_ID} from ${patchFile}`)
+  return true
+}
+
+function removeSkill(target, dryRun, act, dry) {
+  const file = path.join(target, "SKILL.md")
+  if (!fs.existsSync(file)) return false
+  const text = fs.readFileSync(file, "utf8")
+  if (!text.includes("Skill audit workflow")) {
+    act(`kept ${target} (not the generated skill)`)
+    return false
+  }
+  if (dryRun) {
+    dry(`delete skill ${target}`)
+    return true
+  }
+  fs.rmSync(target, { recursive: true, force: true })
+  act(`deleted skill ${target}`)
+  return true
+}
+
+export function installDsh({ home = dshHome(), profile = null, dryRun = false } = {}) {
+  const actions = []
+  const errors = []
+  const dry = (message) => actions.push(`[dry-run] ${message}`)
+  const act = (message) => actions.push(message)
+
+  const picked = pickProfile({ home, profile })
+  if (picked.error) {
+    errors.push(picked.error)
+    return { ok: false, home, actions, errors, dryRun }
+  }
+
+  const dir = profileDir(home, picked.profile)
+  const patchFile = path.join(dir, "cordis.patch.yml")
+  const skillDir = path.join(home, "skills", SKILL_NAME)
+
+  if (dryRun) dry(`profile: ${picked.profile} (${dir})`)
+  else act(`profile: ${picked.profile}`)
+
+  appendEntry(patchFile, dryRun, act, dry)
+  copySkill(skillSourceDir(), skillDir, dryRun, act, dry)
+
+  return { ok: errors.length === 0, home, profile: picked.profile, patchFile, skillDir, actions, errors, dryRun }
+}
+
+export function uninstallDsh({ home = dshHome(), profile = null, dryRun = false } = {}) {
+  const actions = []
+  const errors = []
+  const dry = (message) => actions.push(`[dry-run] ${message}`)
+  const act = (message) => actions.push(message)
+
+  const picked = pickProfile({ home, profile })
+  if (picked.error) {
+    errors.push(picked.error)
+    return { ok: false, home, actions, errors, dryRun }
+  }
+
+  const dir = profileDir(home, picked.profile)
+  const patchFile = path.join(dir, "cordis.patch.yml")
+  const skillDir = path.join(home, "skills", SKILL_NAME)
+
+  removeEntry(patchFile, dryRun, act, dry)
+  removeSkill(skillDir, dryRun, act, dry)
+  return { ok: errors.length === 0, home, profile: picked.profile, patchFile, skillDir, actions, errors, dryRun }
+}

package/src/i18n.mjs

@@ -36,7 +36,9 @@ 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)
+  --client <name>      install/uninstall: auto | opencode | desktop | dsh (default auto)
+  --profile <name>     dsh: profile to install into (default: desktop, or the only one)
+  --dsh-home <dir>     dsh: DSH home directory (default: ~/.dsh)
   --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
@@ -120,6 +122,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.next": "Restart OpenCode to activate.",
     "uninstall.title": "Remove OpenCode integration",
     "uninstall.next": "Restart OpenCode to finish removal.",
+    "dsh.title": "DSH integration",
+    "dsh.uninstallTitle": "Remove DSH integration",
+    "dsh.profile": "  profile: {profile}",
+    "dsh.patch": "  patch: {file}",
+    "dsh.skill": "  skill: {dir}",
+    "dsh.restart": "Restart DSH to load the MCP tool (the skill updates live).",
+    "dsh.failed": "DSH integration failed.",
     "update.toolAvailable":
       "  ! skills-doctor {latest} is available (you have {current}); update with: {cmd}  ·  {url}",
     "upgrade.title": "skills-doctor upgrade",
@@ -248,7 +257,9 @@ 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）
+  --client <name>     install/uninstall: auto | opencode | desktop | dsh（默认 auto）
+  --profile <name>    dsh: 安装到哪个 profile（默认 desktop，或唯一的一个）
+  --dsh-home <dir>    dsh: DSH 主目录（默认 ~/.dsh）
   --no-npm            install/uninstall: 不执行 npm（1.x）
   --apply             upgrade: 执行 npm install -g opencode-skills-doctor@latest
   --no-update-check   本次运行跳过自动更新检查
@@ -332,6 +343,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.next": "重启 OpenCode 生效。",
     "uninstall.title": "撤销 OpenCode 集成",
     "uninstall.next": "重启 OpenCode 完成卸载。",
+    "dsh.title": "DSH 集成",
+    "dsh.uninstallTitle": "撤销 DSH 集成",
+    "dsh.profile": "  profile: {profile}",
+    "dsh.patch": "  patch: {file}",
+    "dsh.skill": "  skill: {dir}",
+    "dsh.restart": "重启 DSH 加载 MCP 工具（skill 会即时更新）。",
+    "dsh.failed": "DSH 集成失败。",
     "update.toolAvailable": "  ! skills-doctor 有新版本 {latest}（当前 {current}）；更新：{cmd}  ·  {url}",
     "upgrade.title": "skills-doctor 自更新",
     "upgrade.current": "  当前版本: {version}",