opencode-skills-doctor 0.3.12 → 0.3.14

package/README.md

@@ -58,7 +58,7 @@ skills-doctor check
 What a run looks like:
 
 ```text
-skills-doctor 0.3.11
+skills-doctor 0.3.13
   sources: 5 (2 exist)  definitions: 29  unique IDs: 29  advertised: 29  description budget: ~3074 tokens
 
 [E] token-budget   Advertised skill descriptions cost about 3074 tokens per model step, over 2x the 1200 budget
@@ -201,7 +201,7 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 }
 ```
 
-It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command hook).
+It registers the same `skills_doctor` tool. 1.x plugins cannot register commands, so `skills-doctor install` writes a `/skills-doctor` markdown command.
 
 > The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
@@ -225,6 +225,19 @@ Once installed you get:
 - the `/skills-doctor` command (1.x: generated markdown command; 2.x: plugin command);
 - a one-time system-prompt warning when the skill description budget is exceeded.
 
+### Uninstall
+
+```powershell
+npx opencode-skills-doctor uninstall
+```
+
+- **2.x** — removes `opencode-skills-doctor` from `plugins`;
+- **1.x** — removes the config entry, deletes the generated plugin entry and `/skills-doctor` command, and uninstalls the package (`--no-npm` skips that);
+- only files generated by the installer are deleted — anything you edited is kept and reported;
+- config files are backed up before editing; `--dry-run` previews, `--config-dir` targets a custom location.
+
+Your data is never touched: `.skills-doctor.json`, `.skills-doctor.lock.json` and `.skills-doctor-archive/` stay until you delete them. MCP entries in other clients (Claude Code, Codex, DSH) are per-client configs and must be removed there.
+
 ## MCP server (Claude Code, Codex, Kimi Code, any MCP client)
 
 `skills-doctor mcp` speaks the Model Context Protocol over stdio and exposes one tool: `skills_doctor` with arguments `directory?`, `budget?`, `lang?` and `global?`. It does not need OpenCode installed.
@@ -351,7 +364,7 @@ See [SECURITY.md](SECURITY.md) for the full threat model, hardening checklist an
 
 - OpenCode **2.x**: add `"plugins": ["opencode-skills-doctor"]` to `opencode.jsonc` — done.
 - OpenCode **1.x**: needs `npm i --prefix ~/.config/opencode opencode-skills-doctor` plus a one-line local plugin file (`export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"`), because 1.x resolves plugins differently and `@opencode-ai/plugin` is an optional peer.
-- 1.x has **no `/skills-doctor` command** — only the `skills_doctor` tool.
+- 1.x has no plugin-registered `/skills-doctor` command; `skills-doctor install` writes a markdown command file instead.
 
 **Safety / behavior**
 

package/docs/README.zh-CN.md

@@ -58,7 +58,7 @@ skills-doctor check
 跑出来大概是这样：
 
 ```text
-skills-doctor 0.3.11
+skills-doctor 0.3.13
   来源: 5 个（存在 2 个）  定义: 29  唯一 ID: 29  会展示: 29  描述预算: ~3074 tokens
 
 [E] token-budget   模型每步要看到的 skill 描述约 3074 tokens，超过预算 1200 的 2 倍
@@ -201,7 +201,7 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 }
 ```
 
-它会注册同样的 `skills_doctor` 工具（1.x 没有 `/skills-doctor` 命令钩子）。
+它会注册同样的 `skills_doctor` 工具。1.x 插件无法注册命令，`skills-doctor install` 会生成 `/skills-doctor` 的 markdown 命令。
 
 > 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
@@ -225,6 +225,19 @@ npx opencode-skills-doctor install
 - `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
 - 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
+### 卸载
+
+```powershell
+npx opencode-skills-doctor uninstall
+```
+
+- **2.x** —— 从 `plugins` 移除 `opencode-skills-doctor`；
+- **1.x** —— 移除配置条目、删除生成的插件入口和 `/skills-doctor` 命令、卸载 npm 包（`--no-npm` 可跳过）；
+- 只删除安装器生成的文件；你手改过的文件会保留并提示；
+- 改配置前会备份；`--dry-run` 预览，`--config-dir` 指定目录。
+
+你的数据不会被自动删除：`.skills-doctor.json`、`.skills-doctor.lock.json`、`.skills-doctor-archive/` 需要手动清理。其他客户端（Claude Code、Codex、DSH）的 MCP 配置也需在各自配置里删除。
+
 ## MCP server（Claude Code、Codex、Kimi Code、任何 MCP 客户端）
 
 `skills-doctor mcp` 用 stdio 讲 Model Context Protocol，只暴露一个工具：`skills_doctor`，参数 `directory?`、`budget?`、`lang?`、`global?`。不需要装 OpenCode。
@@ -351,7 +364,7 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 
 - OpenCode **2.x**：在 `opencode.jsonc` 加 `"plugins": ["opencode-skills-doctor"]` 即可。
 - OpenCode **1.x**：需要 `npm i --prefix ~/.config/opencode opencode-skills-doctor`，再加一个一行本地插件文件（`export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"`）——因为 1.x 解析插件的机制不同，且 `@opencode-ai/plugin` 是可选 peer 依赖。
-- 1.x **没有 `/skills-doctor` 命令**，只有 `skills_doctor` 工具。
+- 1.x 没有「插件注册 /skills-doctor 命令」的能力；`skills-doctor install` 会生成 markdown 命令文件来代替。
 
 **安全性 / 行为**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Audit, fix and update agent skills: per-step context cost, shadowed duplicates, safe archive, catalog sync. CLI, OpenCode plugin and MCP server (Claude Code / Codex / any MCP client).",
   "type": "module",
   "exports": {

package/src/cli.mjs

@@ -8,7 +8,7 @@ import { planFixes, applyFixes, hideSkills } from "./fix.mjs"
 import { auditSkills } from "./audit.mjs"
 import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
-import { installOpenCode } from "./install.mjs"
+import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -64,7 +64,7 @@ function parseArgs(argv) {
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "install", "mcp", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -475,6 +475,28 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "uninstall") {
+    const result = uninstallOpenCode({
+      configDir: options.configDir ?? undefined,
+      dryRun: options.dryRun,
+      removePackage: !options.noNpm,
+    })
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      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 })))
+      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("install.failed")) : dim(t("uninstall.next")))
+    }
+    process.exitCode = result.errors.length ? 1 : 0
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/i18n.mjs

@@ -11,6 +11,7 @@ Usage:
   skills-doctor fix    [options]   archive shadowed definitions (safe structural fixes)
   skills-doctor update [options]   compare and download skills from HTTP catalogs
   skills-doctor install [options]  wire the plugin into OpenCode (1.x / 2.x)
+  skills-doctor uninstall [options] remove it again (config entry, generated files, package)
   skills-doctor mcp                run as an MCP server (Claude Code, Codex, any MCP client)
 
 Options:
@@ -28,8 +29,8 @@ Options:
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
   --prune              update: delete skills that disappeared from the catalog
-  --config-dir <dir>   install: OpenCode config directory (default: ~/.config/opencode)
-  --no-npm             install: do not run npm install (1.x)
+  --config-dir <dir>   install/uninstall: OpenCode config directory (default: ~/.config/opencode)
+  --no-npm             install/uninstall: do not run npm (1.x)
   -h, --help           show this help
   -v, --version        print version
 
@@ -84,6 +85,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.error": "  ✗ {error}",
     "install.failed": "Integration failed.",
     "install.next": "Restart OpenCode to activate.",
+    "uninstall.title": "Remove OpenCode integration",
+    "uninstall.next": "Restart OpenCode to finish removal.",
     "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
     "update.detector": "  check now sees these skills ({dir} is where opencode reads)",
     "update.noCatalogs": "No HTTP catalog configured. Add https://... to the skills array in opencode.json(c).",
@@ -167,6 +170,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
   skills-doctor install [选项]  把插件接入 OpenCode（1.x / 2.x）
+  skills-doctor uninstall [选项] 撤销安装（配置条目、生成的文件、npm 包）
   skills-doctor mcp            以 MCP server 方式运行（Claude Code、Codex 等任何 MCP 客户端）
 
 选项:
@@ -184,8 +188,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
   --prune             update: 删除 catalog 中已移除的 skill
-  --config-dir <dir>  install: OpenCode 配置目录（默认 ~/.config/opencode）
-  --no-npm            install: 不执行 npm install（1.x）
+  --config-dir <dir>  install/uninstall: OpenCode 配置目录（默认 ~/.config/opencode）
+  --no-npm            install/uninstall: 不执行 npm（1.x）
   -h, --help          帮助
   -v, --version       版本
 
@@ -240,6 +244,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.error": "  ✗ {error}",
     "install.failed": "集成失败。",
     "install.next": "重启 OpenCode 生效。",
+    "uninstall.title": "撤销 OpenCode 集成",
+    "uninstall.next": "重启 OpenCode 完成卸载。",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",
     "update.noCatalogs": "没有配置 HTTP catalog。在 opencode.json(c) 的 skills 数组里写 https://... 即可。",

package/src/install.mjs

@@ -209,3 +209,111 @@ 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 }
 }
+
+function removePackage(dir) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm"
+  const result = spawnSync(npm, ["uninstall", "--prefix", dir, PACKAGE_NAME, "--no-audit", "--no-fund"], {
+    stdio: "inherit",
+    env: process.env,
+    timeout: 180000,
+  })
+  return result.status === 0
+}
+
+/**
+ * 撤销 install：移除配置里的插件条目、删除安装器生成的文件、可选卸载 npm 包。
+ * 只删除「由安装器生成」的文件，用户自己改过的一律保留并提示。
+ */
+export function uninstallOpenCode({ configDir = defaultConfigDir(), version = null, dryRun = false, removePackage: withPackage = true } = {}) {
+  const dir = path.resolve(configDir)
+  const actions = []
+  const errors = []
+  const dry = (message) => actions.push(`[dry-run] ${message}`)
+  const act = (message) => actions.push(message)
+
+  const cfgFile = configFile(dir)
+  const existingText = readText(cfgFile)
+  let config = {}
+  if (existingText !== null) {
+    try {
+      config = readJsonc(cfgFile)
+    } catch (err) {
+      errors.push(`cannot parse ${cfgFile}: ${err.message}`)
+      return { version, major: null, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+    }
+  }
+
+  const resolvedVersion = version ?? detectVersion()
+  const inferredMajor = config.plugin !== undefined ? 1 : 2
+  const major = resolvedVersion ? Number(resolvedVersion.split(".")[0]) : inferredMajor
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+
+  if (major >= 2) {
+    if (Array.isArray(config.plugins) && config.plugins.includes(PACKAGE_NAME)) {
+      const next = config.plugins.filter((entry) => entry !== PACKAGE_NAME)
+      if (!dryRun) {
+        const backupFile = backup(cfgFile, stamp)
+        if (backupFile) act(`backup ${backupFile}`)
+        writeJson(cfgFile, { ...config, plugins: next })
+        act(`removed "${PACKAGE_NAME}" from plugins in ${cfgFile}`)
+      } else dry(`remove "${PACKAGE_NAME}" from plugins in ${cfgFile}`)
+    } else {
+      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 }
+  }
+
+  const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
+  const commandFile = path.join(dir, "command", COMMAND_FILE)
+
+  if (Array.isArray(config.plugin) && config.plugin.includes(pluginFile)) {
+    const next = config.plugin.filter((entry) => entry !== pluginFile)
+    if (!dryRun) {
+      const backupFile = backup(cfgFile, stamp)
+      if (backupFile) act(`backup ${backupFile}`)
+      writeJson(cfgFile, { ...config, plugin: next })
+      act(`removed plugin entry from ${cfgFile}`)
+    } else dry(`remove plugin entry from ${cfgFile}`)
+  } else {
+    act("plugin entry is not configured")
+  }
+
+  if (fs.existsSync(pluginFile)) {
+    const content = readText(pluginFile) ?? ""
+    if (content.includes("Generated by skills-doctor install")) {
+      if (!dryRun) {
+        fs.rmSync(pluginFile, { force: true })
+        act(`deleted ${pluginFile}`)
+      } else dry(`delete ${pluginFile}`)
+    } else {
+      act(`kept ${pluginFile} (not generated by skills-doctor)`)
+    }
+  }
+
+  if (fs.existsSync(commandFile)) {
+    const content = readText(commandFile) ?? ""
+    if (content.includes("skills_doctor tool")) {
+      if (!dryRun) {
+        fs.rmSync(commandFile, { force: true })
+        act(`deleted ${commandFile}`)
+      } else dry(`delete ${commandFile}`)
+    } else {
+      act(`kept ${commandFile} (not generated by skills-doctor)`)
+    }
+  }
+
+  const hasPackage = fs.existsSync(path.join(dir, "node_modules", PACKAGE_NAME, "package.json"))
+  if (withPackage && hasPackage) {
+    if (dryRun) {
+      dry(`uninstall ${PACKAGE_NAME} from ${dir}`)
+    } else {
+      act(`uninstalling ${PACKAGE_NAME} from ${dir}`)
+      if (removePackage(dir)) act(`uninstalled ${PACKAGE_NAME}`)
+      else errors.push(`npm uninstall failed for ${PACKAGE_NAME}`)
+    }
+  }
+
+  act("restart OpenCode to finish removal")
+  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+}