opencode-skills-doctor 0.3.9 → 0.3.11

package/README.md

@@ -4,13 +4,13 @@
 
 Local scanner, linter, fixer, updater and **OpenCode plugin** for skills — zero dependencies, Node ≥ 20.
 
-**English** | [简体中文](README.zh-CN.md)
+**English** | [简体中文](docs/README.zh-CN.md)
 
 ## Why
 
 On every model step, OpenCode advertises every skill that has a `description` — the model sees `ID + name + description` for each of them. Skills are not free: they are a permanent context tax on every request.
 
-**What this costs.** 29 skills with long descriptions ≈ **3,000+ tokens every step**. Over a 100-step session that is ~300k tokens of pure overhead — spent before the model reads a single line of your code.
+**What this costs.** 29 skills with long descriptions ≈ **3,000+ tokens every step**. Over a 100-step session that is ~300k tokens of pure overhead — spent before the model reads a single line of your code. And that is only 29 skills: many users have far more they downloaded without noticing, some already out of date. This tool helps you understand your skill repository much better.
 
 **What can go wrong.** As skills pile up:
 - duplicate IDs silently shadow each other — you may be editing a file that never loads;
@@ -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/{README.zh-CN.md → docs/README.zh-CN.md}

@@ -4,13 +4,13 @@
 
 OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **OpenCode 插件入口** —— 零依赖，Node ≥ 20。
 
-[English](README.md) | **简体中文**
+[English](../README.md) | **简体中文**
 
 ## 为什么需要它
 
 opencode 每个模型步骤都会把所有「有 description 的 skill」展示给模型（`ID + name + description`）。skill 不是免费的——它是**每一次请求都要交的上下文税**。
 
-**成本有多大**：29 个 skill、描述偏长，就是**每步 3000+ tokens**。一次 100 步的会话，光 skill 目录就烧掉约 30 万 tokens，模型还没开始读你一行代码。
+**成本有多大**：29 个 skill、描述偏长，就是**每步 3000+ tokens**。一次 100 步的会话，光 skill 目录就烧掉约 30 万 tokens，模型还没开始读你一行代码。而这只是 29 个——很多人还有更多没注意就装上的 skill，有些已经过时。这个工具能帮你真正看清自己的 skill 仓库。
 
 **会出什么问题**：skill 越攒越多，就会出现
 - 同 ID 互相遮蔽——你改的可能是一份永远不会加载的文件；
@@ -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。
@@ -252,7 +272,7 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 - `fix` / `--prune` 会移动或删除文件——先 `--dry-run` 预览；
 - 它**不是沙箱**，不限制 agent 能做什么。
 
-完整威胁模型、加固清单和私密漏洞报告方式见 [SECURITY.zh-CN.md](SECURITY.zh-CN.md)。
+完整威胁模型、加固清单和私密漏洞报告方式见 [SECURITY.zh-CN.md](../SECURITY.zh-CN.md)。
 
 ## 注意事项与已知限制
 

package/package.json

@@ -1,57 +1,59 @@
-{
-  "name": "opencode-skills-doctor",
-  "version": "0.3.9",
-  "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": {
-    ".": "./src/plugin.mjs",
-    "./plugin": "./src/plugin.mjs",
-    "./server": "./src/plugin-v1.mjs",
-    "./v1": "./src/plugin-v1.mjs",
-    "./audit": "./src/audit.mjs"
-  },
-  "bin": {
-    "skills-doctor": "./bin/skills-doctor.mjs"
-  },
-  "peerDependencies": {
-    "@opencode/plugin": ">=2.0.0",
-    "@opencode-ai/plugin": ">=1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@opencode/plugin": {
-      "optional": true
-    },
-    "@opencode-ai/plugin": {
-      "optional": true
-    }
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "test": "node test/doctor.test.mjs"
-  },
-  "files": [
-    "bin",
-    "src",
-    "README.md",
-    "README.zh-CN.md",
-    "SECURITY.md",
-    "SECURITY.zh-CN.md"
-  ],
-  "keywords": [
-    "opencode",
-    "skills",
-    "agent-skills",
-    "mcp",
-    "lint",
-    "fix",
-    "cli",
-    "plugin"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/wangyuchen5110/opencodeplugginprogram.git"
-  },
-  "license": "MIT"
-}
+{
+  "name": "opencode-skills-doctor",
+  "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": {
+    ".": "./src/plugin.mjs",
+    "./plugin": "./src/plugin.mjs",
+    "./server": "./src/plugin-v1.mjs",
+    "./v1": "./src/plugin-v1.mjs",
+    "./audit": "./src/audit.mjs"
+  },
+  "bin": {
+    "skills-doctor": "./bin/skills-doctor.mjs"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0",
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    },
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/doctor.test.mjs",
+    "bench": "node scripts/bench.mjs",
+    "prepublishOnly": "node test/doctor.test.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "SECURITY.md",
+    "SECURITY.zh-CN.md"
+  ],
+  "keywords": [
+    "opencode",
+    "skills",
+    "agent-skills",
+    "mcp",
+    "lint",
+    "fix",
+    "cli",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wangyuchen5110/opencodeplugginprogram.git"
+  },
+  "license": "MIT"
+}

package/src/catalog.mjs

@@ -68,6 +68,41 @@ function lockEntryVersion(entry) {
   return null
 }
 
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** fetch + 有限重试（5xx 与网络错误），避免 catalog 抖动直接失败。 */
+async function fetchWithRetry(fetchImpl, url, timeoutMs, attempts = 3) {
+  let lastError
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) })
+      if (res.status >= 500 && attempt < attempts - 1) {
+        await sleep(200 * 2 ** attempt)
+        continue
+      }
+      return res
+    } catch (err) {
+      lastError = err
+      if (attempt < attempts - 1) await sleep(200 * 2 ** attempt)
+    }
+  }
+  throw lastError ?? new Error("fetch failed")
+}
+
+/** 先写临时文件再原子替换，避免中途失败留下半截文件。 */
+function writeFileAtomic(target, data) {
+  const tmp = `${target}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`
+  fs.writeFileSync(tmp, data)
+  try {
+    fs.renameSync(tmp, target)
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {}
+    throw err
+  }
+}
+
 function pruneEmptyDirs(dir, stopDir) {
   const stop = path.resolve(stopDir)
   let current = path.resolve(dir)
@@ -96,7 +131,7 @@ function filesMatch(into, name, files, t) {
 /** 抓取 <url>/index.json。未知字段一律忽略（向上兼容）。 */
 export async function fetchCatalogIndex(url, { fetchImpl = fetch, timeoutMs = 15000, t = translator("en") } = {}) {
   const base = url.replace(/\/+$/, "")
-  const res = await fetchImpl(`${base}/index.json`, { signal: AbortSignal.timeout(timeoutMs) })
+  const res = await fetchWithRetry(fetchImpl, `${base}/index.json`, timeoutMs)
   if (!res.ok) throw new Error(t("catalog.indexHttp", { status: res.status }))
   const json = await res.json()
   if (!json || !Array.isArray(json.skills)) throw new Error(t("catalog.indexShape"))
@@ -162,12 +197,12 @@ export async function updateCatalogs(
           const encodedPath = file.split("/").map(encodeURIComponent).join("/")
           const fileUrl = new URL(`${encodeURIComponent(entry.name)}/${encodedPath}`, baseUrl)
           if (fileUrl.origin !== baseUrl.origin) throw new Error(t("catalog.crossOrigin", { file }))
-          const res = await fetchImpl(fileUrl, { signal: AbortSignal.timeout(30000) })
+          const res = await fetchWithRetry(fetchImpl, fileUrl, 30000)
           if (!res.ok) throw new Error(t("catalog.fileHttp", { name: entry.name, file, status: res.status }))
           const buffer = Buffer.from(await res.arrayBuffer())
           const target = resolveInside(path.join(into, entry.name), file, t)
           fs.mkdirSync(path.dirname(target), { recursive: true })
-          fs.writeFileSync(target, buffer)
+          writeFileAtomic(target, buffer)
           hashes[file] = sha1Buffer(buffer)
           result.files++
         }
@@ -219,7 +254,7 @@ export async function updateCatalogs(
     lock.version = LOCK_VERSION
     lock.generatedAt = new Date().toISOString()
     fs.mkdirSync(path.dirname(lockPath), { recursive: true })
-    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8")
+    writeFileAtomic(lockPath, JSON.stringify(lock, null, 2) + "\n")
   }
 
   return { lockPath, lockTooNew, results }

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

@@ -157,16 +157,20 @@ export function lint(skills, options = {}) {
     })
   }
 
-  // 5) 描述近似
-  const withDesc = described
+  // 5) 描述近似（token 集合只算一次；先按集合大小做 0.75 上界预筛）
+  const withDesc = described.map((skill) => ({ skill, tokens: tokenSet(skill.description) }))
   const pairs = []
   for (let i = 0; i < withDesc.length; i++) {
     for (let j = i + 1; j < withDesc.length; j++) {
       const a = withDesc[i]
       const b = withDesc[j]
-      if (a.id === b.id) continue
-      const score = jaccard(tokenSet(a.description), tokenSet(b.description))
-      if (score >= NEAR_DUPLICATE_THRESHOLD) pairs.push({ a: a.id, b: b.id, score })
+      if (a.skill.id === b.skill.id) continue
+      const min = Math.min(a.tokens.size, b.tokens.size)
+      const max = Math.max(a.tokens.size, b.tokens.size)
+      // Jaccard ≤ min/max，所以比值低于阈值时不可能达到阈值
+      if (!min || min / max < NEAR_DUPLICATE_THRESHOLD) continue
+      const score = jaccard(a.tokens, b.tokens)
+      if (score >= NEAR_DUPLICATE_THRESHOLD) pairs.push({ a: a.skill.id, b: b.skill.id, score })
     }
   }
   for (const pair of pairs.slice(0, 15)) {

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()
+}