opencode-skills-doctor 0.3.10 → 0.3.11

package/README.md

@@ -157,6 +157,26 @@ It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command
 
 > The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
+### Deep integration (one command)
+
+```powershell
+npx opencode-skills-doctor install
+```
+
+The installer detects your OpenCode version and wires everything up:
+
+- **2.x** — adds `"plugins": ["opencode-skills-doctor"]` to `opencode.json(c)`;
+- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, adds a `/skills-doctor` command, sets `"type": "module"`;
+- backs up the config file as `<config>.bak-<timestamp>` before editing.
+
+Use `--dry-run` to preview, `--config-dir <dir>` for a custom config location, and `--no-npm` to skip the package install.
+
+Once installed you get:
+
+- the `skills_doctor` tool;
+- 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.
+
 ## 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.

package/docs/README.zh-CN.md

@@ -157,6 +157,26 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 
 > 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
+### 一键深度集成
+
+```powershell
+npx opencode-skills-doctor install
+```
+
+安装器会自动识别 OpenCode 版本并接好：
+
+- **2.x** —— 在 `opencode.json(c)` 里加 `"plugins": ["opencode-skills-doctor"]`；
+- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor` 命令、补 `"type": "module"`；
+- 改配置前会备份为 `<config>.bak-<timestamp>`。
+
+支持 `--dry-run` 预览、`--config-dir <dir>` 指定配置目录、`--no-npm` 跳过装包。
+
+装好后你会得到：
+
+- `skills_doctor` 工具；
+- `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
+- 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
+
 ## MCP server（Claude Code、Codex、Kimi Code、任何 MCP 客户端）
 
 `skills-doctor mcp` 用 stdio 讲 Model Context Protocol，只暴露一个工具：`skills_doctor`，参数 `directory?`、`budget?`、`lang?`、`global?`。不需要装 OpenCode。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "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,6 +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 { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -56,12 +57,14 @@ function parseArgs(argv) {
     into: null,
     checkOnly: false,
     prune: false,
+    configDir: null,
+    noNpm: false,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "mcp", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "install", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -116,6 +119,12 @@ function parseArgs(argv) {
       case "--prune":
         options.prune = true
         break
+      case "--config-dir":
+        options.configDir = path.resolve(args[++i] ?? ".")
+        break
+      case "--no-npm":
+        options.noNpm = true
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -444,6 +453,28 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "install") {
+    const result = installOpenCode({
+      configDir: options.configDir ?? undefined,
+      dryRun: options.dryRun,
+      installPackage: !options.noNpm,
+    })
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      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 })))
+      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("install.next")))
+    }
+    process.exitCode = result.errors.length ? 1 : 0
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/i18n.mjs

@@ -10,6 +10,7 @@ Usage:
   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
+  skills-doctor install [options]  wire the plugin into OpenCode (1.x / 2.x)
   skills-doctor mcp                run as an MCP server (Claude Code, Codex, any MCP client)
 
 Options:
@@ -27,6 +28,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)
   -h, --help           show this help
   -v, --version        print version
 
@@ -74,6 +77,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.pruned": "  · pruned {count} skills no longer in the catalog: {names}",
     "update.orphaned": "  ! {count} skills are no longer in the catalog (use --prune to delete them)",
     "update.lock": "  lock: {path} ({name})",
+    "install.title": "OpenCode integration",
+    "install.version": "  OpenCode: {version}",
+    "install.configDir": "  config dir: {dir}",
+    "install.dryRun": "  (dry run: nothing is written)",
+    "install.error": "  ✗ {error}",
+    "install.failed": "Integration failed.",
+    "install.next": "Restart OpenCode to activate.",
     "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).",
@@ -156,6 +166,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   skills-doctor scan   [选项]   列出所有 skill 及其来源/优先级
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
+  skills-doctor install [选项]  把插件接入 OpenCode（1.x / 2.x）
   skills-doctor mcp            以 MCP server 方式运行（Claude Code、Codex 等任何 MCP 客户端）
 
 选项:
@@ -173,6 +184,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）
   -h, --help          帮助
   -v, --version       版本
 
@@ -220,6 +233,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.pruned": "  · 清理 catalog 中已移除的 skill {count} 个: {names}",
     "update.orphaned": "  ! {count} 个 skill 已不在 catalog 中（加 --prune 可删除本地残留）",
     "update.lock": "  lock: {path}（{name}）",
+    "install.title": "OpenCode 集成",
+    "install.version": "  OpenCode: {version}",
+    "install.configDir": "  配置目录: {dir}",
+    "install.dryRun": "  （dry run：不会写入任何内容）",
+    "install.error": "  ✗ {error}",
+    "install.failed": "集成失败。",
+    "install.next": "重启 OpenCode 生效。",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",
     "update.noCatalogs": "没有配置 HTTP catalog。在 opencode.json(c) 的 skills 数组里写 https://... 即可。",

package/src/install.mjs

@@ -0,0 +1,211 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+import { spawnSync, execFileSync } from "node:child_process"
+import { stripJsonc } from "./discover.mjs"
+
+export const PACKAGE_NAME = "opencode-skills-doctor"
+const PLUGIN_FILE = "skills-doctor.js"
+const COMMAND_FILE = "skills-doctor.md"
+
+const V1_PLUGIN_SOURCE = `// Generated by skills-doctor install\n// OpenCode 1.x plugin entry\nexport { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"\n`
+
+const V1_COMMAND = `---
+description: Audit local skills with skills-doctor
+---
+Use the skills_doctor tool to audit the skills in this project. Summarize the top findings and propose concrete fixes (archive shadowed duplicates, hide low-frequency skills). $ARGUMENTS
+`
+
+export function defaultConfigDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
+  return path.join(base, "opencode")
+}
+
+function readJsonc(file) {
+  return JSON.parse(stripJsonc(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")))
+}
+
+function writeJson(file, data) {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8")
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")
+  } catch {
+    return null
+  }
+}
+
+function detectVersion() {
+  try {
+    const out = execFileSync("opencode", ["--version"], { encoding: "utf8", timeout: 15000 })
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(out))
+    if (match) return match[0]
+  } catch {}
+  return null
+}
+
+function configFile(dir) {
+  const candidates = ["opencode.jsonc", "opencode.json"]
+    .map((name) => path.join(dir, name))
+    .filter((file) => fs.existsSync(file))
+
+  // 优先沿用已经在配置 plugin/plugins 的文件，避免把插件写进另一个配置文件后被覆盖
+  for (const file of candidates) {
+    try {
+      const config = readJsonc(file)
+      if (config.plugin !== undefined || config.plugins !== undefined) return file
+    } catch {}
+  }
+
+  return candidates[0] ?? path.join(dir, "opencode.json")
+}
+
+function backup(file, stamp) {
+  if (!fs.existsSync(file)) return null
+  const target = `${file}.bak-${stamp}`
+  fs.copyFileSync(file, target)
+  return target
+}
+
+function ensureUniqueEntry(list, entry) {
+  if (!Array.isArray(list)) return [entry]
+  return list.includes(entry) ? list : [...list, entry]
+}
+
+function installPackage(dir) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm"
+  const result = spawnSync(npm, ["install", "--prefix", dir, PACKAGE_NAME + "@latest", "--no-audit", "--no-fund"], {
+    stdio: "inherit",
+    env: process.env,
+    timeout: 180000,
+  })
+  return result.status === 0
+}
+
+/**
+ * 把 skills-doctor 装进 OpenCode：
+ * - 2.x：写入 plugins 数组（OpenCode 自己从 npm 拉包）
+ * - 1.x：在配置目录安装包、写本地插件入口、写 /skills-doctor 命令、补插件数组
+ */
+export function installOpenCode({ configDir = defaultConfigDir(), version = null, dryRun = false, installPackage: 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
+
+  if (dryRun) dry(`config dir: ${dir}`)
+  if (!fs.existsSync(dir)) {
+    if (!dryRun) fs.mkdirSync(dir, { recursive: true })
+    act(`created config dir ${dir}`)
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+
+  if (major >= 2) {
+    const next = { ...config, plugins: ensureUniqueEntry(config.plugins, PACKAGE_NAME) }
+    const changed = !Array.isArray(config.plugins) || !config.plugins.includes(PACKAGE_NAME)
+    if (changed) {
+      if (!dryRun) {
+        const backupFile = backup(cfgFile, stamp)
+        if (backupFile) act(`backup ${backupFile}`)
+        writeJson(cfgFile, next)
+        act(`added "${PACKAGE_NAME}" to plugins in ${cfgFile}`)
+      } else dry(`add "${PACKAGE_NAME}" to plugins in ${cfgFile}`)
+    } else {
+      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 }
+  }
+
+  // 1.x
+  const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
+  const commandFile = path.join(dir, "command", COMMAND_FILE)
+  const pluginPath = pluginFile
+
+  const hasPackage = fs.existsSync(path.join(dir, "node_modules", PACKAGE_NAME, "package.json"))
+  if (!hasPackage) {
+    if (withPackage && !dryRun) {
+      act(`installing ${PACKAGE_NAME} into ${dir}`)
+      if (!installPackage(dir)) errors.push(`npm install failed for ${PACKAGE_NAME}`)
+      else act(`installed ${PACKAGE_NAME}`)
+    } else if (dryRun) {
+      dry(`install ${PACKAGE_NAME} into ${dir}`)
+    } else {
+      act(`skipped npm install; run: npm i --prefix "${dir}" ${PACKAGE_NAME}`)
+    }
+  } else {
+    act(`${PACKAGE_NAME} already installed in ${dir}`)
+  }
+
+  if (!fs.existsSync(pluginFile)) {
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(pluginFile), { recursive: true })
+      fs.writeFileSync(pluginFile, V1_PLUGIN_SOURCE, "utf8")
+      act(`wrote plugin entry ${pluginFile}`)
+    } else dry(`write plugin entry ${pluginFile}`)
+  } else {
+    act(`plugin entry already exists ${pluginFile}`)
+  }
+
+  if (!fs.existsSync(commandFile)) {
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(commandFile), { recursive: true })
+      fs.writeFileSync(commandFile, V1_COMMAND, "utf8")
+      act(`wrote command ${commandFile}`)
+    } else dry(`write command ${commandFile}`)
+  } else {
+    act(`command already exists ${commandFile}`)
+  }
+
+  const nextPlugin = ensureUniqueEntry(config.plugin, pluginPath)
+  const pluginChanged = !Array.isArray(config.plugin) || !config.plugin.includes(pluginPath)
+  if (pluginChanged) {
+    if (!dryRun) {
+      const backupFile = backup(cfgFile, stamp)
+      if (backupFile) act(`backup ${backupFile}`)
+      writeJson(cfgFile, { ...config, plugin: nextPlugin })
+      act(`added plugin entry to ${cfgFile}`)
+    } else dry(`add plugin entry to ${cfgFile}`)
+  } else {
+    act("plugin array already configured")
+  }
+
+  const pkgFile = path.join(dir, "package.json")
+  const pkgText = readText(pkgFile)
+  let pkg = {}
+  if (pkgText !== null) {
+    try {
+      pkg = JSON.parse(pkgText)
+    } catch {}
+  }
+  if (pkg.type !== "module") {
+    if (!dryRun) {
+      pkg.type = "module"
+      fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + "\n", "utf8")
+      act(`set "type": "module" in ${pkgFile}`)
+    } else dry(`set "type": "module" in ${pkgFile}`)
+  }
+
+  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 }
+}

package/src/plugin-v1.mjs

@@ -1,5 +1,6 @@
 import { tool } from "@opencode-ai/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { budgetWarning } from "./warning.mjs"
 
 const z = tool.schema
 
@@ -25,6 +26,10 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
       },
     }),
   },
+  "experimental.chat.system.transform": async (input, output) => {
+    const warning = budgetWarning({ cwd: directory, sessionID: input?.sessionID })
+    if (warning) output.system.push(warning)
+  },
 })
 
 export const server = SkillsDoctorPlugin

package/src/plugin.mjs

@@ -1,5 +1,6 @@
 import { Plugin } from "@opencode/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { budgetWarning } from "./warning.mjs"
 
 /**
  * OpenCode 插件入口：把 skills-doctor 暴露成 skills_doctor 工具和 /skills-doctor 命令。
@@ -48,5 +49,11 @@ export default Plugin.define({
         },
       })
     })
+
+    // 每个会话最多注入一次预算预警，避免刷屏
+    await ctx.session.hook("context", (event) => {
+      const warning = budgetWarning({ cwd: ctx.location.directory, sessionID: event.sessionID })
+      if (warning) event.system.push({ type: "text", text: warning })
+    })
   },
 })

package/src/warning.mjs

@@ -0,0 +1,37 @@
+import { auditSkills } from "./audit.mjs"
+
+const cache = new Map()
+const warned = new Set()
+
+/**
+ * 每个会话最多注入一次「skill 预算超标」提醒。
+ * 只在存在 error（默认预算超标 2 倍）时提醒，避免刷屏。
+ */
+export function budgetWarning({ cwd = process.cwd(), sessionID = "global", ttlMs = 60000, includeGlobal = true } = {}) {
+  const key = `${cwd}::${sessionID}`
+  if (warned.has(key)) return null
+
+  const now = Date.now()
+  let entry = cache.get(cwd)
+  if (!entry || now - entry.at > ttlMs) {
+    const audit = auditSkills({ cwd, includeGlobal })
+    const over = audit.counts.errors > 0
+    entry = {
+      at: now,
+      text: over
+        ? `[skills-doctor] ${audit.summary.unique} skills use ~${audit.summary.advertisedTokens} tokens of descriptions per step (budget ${audit.budget}); ${audit.counts.errors} error(s), ${audit.counts.warnings} warning(s). Use the skills_doctor tool for details, then hide low-frequency skills with \`skills-doctor fix --hide <ids>\`.`
+        : null,
+    }
+    cache.set(cwd, entry)
+  }
+
+  if (!entry.text) return null
+  warned.add(key)
+  return entry.text
+}
+
+/** 测试用：清空缓存与已提醒集合。 */
+export function resetWarningState() {
+  cache.clear()
+  warned.clear()
+}