opencode-skills-doctor 0.3.0 → 0.3.3

package/README.md

@@ -60,6 +60,7 @@ skills-doctor fix --hide academic-paper,deep-research --dry-run   # hide low-fre
 
 - Only shadowed duplicates are touched; the effective definition is never moved;
 - Files installed by `update` are skipped — use `update` to bring them back;
+- Default scope is project-only; pass `--all` to also archive global sources;
 - After fixing, `check` should report no `shadowed` findings.
 
 ### `update` (updater)
@@ -111,6 +112,34 @@ It registers:
 
 `@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
 
+### OpenCode 1.x
+
+1.x uses a different plugin API: it resolves the `./server` export for npm plugins and needs `@opencode-ai/plugin` at runtime. The reliable setup is a one-line local plugin file.
+
+1. Install the package where OpenCode resolves plugins:
+
+```powershell
+npm i --prefix ~/.config/opencode opencode-skills-doctor
+```
+
+2. Create `~/.config/opencode/plugins/skills-doctor.js`:
+
+```js
+export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
+```
+
+3. Reference it from `opencode.json` (1.x uses `plugin`, not `plugins`):
+
+```jsonc
+{
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
+}
+```
+
+It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command hook).
+
+> The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
+
 ## Rules
 
 | Rule | Level | Meaning |
@@ -148,7 +177,7 @@ It registers:
 4. project `.agents/skills`
 5. `~/.config/opencode/skills`
 6. project `.opencode/skills`
-7. the `skills` array in `opencode.json(c)` (relative paths resolve from the working directory; supports `~/`, absolute paths and HTTP catalogs)
+7. the `skills` array in `opencode.json(c)` (2.x) or `skills.paths` (1.x); relative paths resolve from the working directory; supports `~/`, absolute paths and HTTP catalogs
 
 ## JSON output
 

package/README.zh-CN.md

@@ -60,6 +60,7 @@ skills-doctor fix --hide academic-paper,deep-research --dry-run   # 隐藏低频
 
 - 只动被遮蔽的重复定义，生效版本永远不会被移动；
 - 由 `update` 安装的文件会跳过——用 `update` 恢复；
+- **默认只处理项目内的 skill**，要动全局来源（`~/.config/opencode/skills` 等）加 `--all`；
 - 修完再跑 `check`，`shadowed` 应该消失。
 
 ### `update`（更新器）
@@ -111,6 +112,34 @@ skills-doctor update --into .\team-skills
 
 `@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
 
+### OpenCode 1.x
+
+1.x 用的是另一套插件 API：npm 插件会解析 `./server` 导出，运行时需要 `@opencode-ai/plugin`。最稳的接法是加一个一行的本地插件文件。
+
+1. 先把包装到 OpenCode 解析插件的位置：
+
+```powershell
+npm i --prefix ~/.config/opencode opencode-skills-doctor
+```
+
+2. 新建 `~/.config/opencode/plugins/skills-doctor.js`：
+
+```js
+export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
+```
+
+3. 在 `opencode.json` 里引用（1.x 用 `plugin`，不是 `plugins`）：
+
+```jsonc
+{
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
+}
+```
+
+它会注册同样的 `skills_doctor` 工具（1.x 没有 `/skills-doctor` 命令钩子）。
+
+> 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
+
 ## 检测规则
 
 | 规则 | 级别 | 含义 |
@@ -148,7 +177,7 @@ skills-doctor update --into .\team-skills
 4. 项目 `.agents/skills`
 5. `~/.config/opencode/skills`
 6. 项目 `.opencode/skills`
-7. `opencode.json(c)` 的 `skills` 数组（相对路径按当前工作目录解析，支持 `~/`、绝对路径、HTTP catalog）
+7. `opencode.json(c)` 的 `skills` 数组（2.x）或 `skills.paths`（1.x）；相对路径按当前工作目录解析，支持 `~/`、绝对路径、HTTP catalog
 
 ## JSON 输出
 

package/package.json

@@ -1,21 +1,28 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.0",
-  "description": "Local scanner, linter, fixer and updater for OpenCode skills, with an OpenCode plugin entry",
+  "version": "0.3.3",
+  "description": "Local scanner, linter, fixer and updater for OpenCode skills, with OpenCode 2.x and 1.x plugin entries",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",
-    "./plugin": "./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/plugin": ">=2.0.0",
+    "@opencode-ai/plugin": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "@opencode/plugin": {
       "optional": true
+    },
+    "@opencode-ai/plugin": {
+      "optional": true
     }
   },
   "engines": {

package/src/cli.mjs

@@ -48,6 +48,7 @@ function parseArgs(argv) {
     lang: null,
     config: null,
     dryRun: false,
+    all: false,
     hide: [],
     into: null,
     checkOnly: false,
@@ -91,6 +92,9 @@ function parseArgs(argv) {
       case "--dry-run":
         options.dryRun = true
         break
+      case "--all":
+        options.all = true
+        break
       case "--hide":
         options.hide.push(
           ...String(args[++i] ?? "")
@@ -339,9 +343,12 @@ async function runUpdate(discovered, options, cwd, t) {
 }
 
 function runFix(audit, options, t) {
-  const { plan, skipped } = planFixes(audit.skills, audit.managed)
+  const { plan, skipped, skippedGlobal } = planFixes(audit.skills, audit.managed, { includeGlobal: options.all })
   const archived = applyFixes(plan, { dryRun: options.dryRun })
-  const hidden = options.hide.length ? hideSkills(audit.skills, options.hide, { dryRun: options.dryRun }) : { changed: [], errors: [], missing: [] }
+  const hideCandidates = options.all ? audit.skills : audit.skills.filter((s) => s.source.scope !== "global")
+  const hidden = options.hide.length
+    ? hideSkills(hideCandidates, options.hide, { dryRun: options.dryRun })
+    : { changed: [], errors: [], missing: [] }
 
   const errors = [...archived.errors, ...hidden.errors]
 
@@ -353,9 +360,11 @@ function runFix(audit, options, t) {
           version: pkg.version,
           lang: audit.lang,
           dryRun: options.dryRun,
+          all: options.all,
           archived: archived.moved.map((m) => ({ id: m.id, from: m.from, to: m.target })),
           hidden: hidden.changed,
           skipped: skipped.map((s) => ({ id: s.id, file: s.file })),
+          skippedGlobal: skippedGlobal.map((s) => ({ id: s.id, file: s.file })),
           missing: hidden.missing,
           errors: errors.map((e) => ({ id: e.id, error: e.error })),
         },
@@ -366,7 +375,8 @@ function runFix(audit, options, t) {
     return errors.length ? 1 : 0
   }
 
-  const nothing = !plan.length && !skipped.length && !hidden.changed.length && !hidden.missing.length
+  const nothing =
+    !plan.length && !skipped.length && !skippedGlobal.length && !hidden.changed.length && !hidden.missing.length
   if (nothing) {
     console.log(bold(t("fix.title")))
     console.log(`  ${t("fix.none")}`)
@@ -378,6 +388,7 @@ function runFix(audit, options, t) {
   for (const item of archived.moved) console.log(green(t("fix.moved", { from: item.from, to: item.target })))
   for (const item of hidden.changed) console.log(green(t("fix.hidden", { id: item.id, file: item.file })))
   for (const item of skipped) console.log(dim(t("fix.skippedManaged", { path: item.file })))
+  for (const item of skippedGlobal) console.log(dim(t("fix.skippedGlobal", { path: item.file })))
   for (const id of hidden.missing) console.log(yellow(t("fix.unknownHide", { id })))
   for (const item of errors) console.log(red(t("fix.error", { path: item.file ?? item.from, error: item.error })))
   console.log("")
@@ -385,7 +396,7 @@ function runFix(audit, options, t) {
     t("fix.summary", {
       moved: archived.moved.length,
       hidden: hidden.changed.length,
-      skipped: skipped.length,
+      skipped: skipped.length + skippedGlobal.length,
     }),
   )
   console.log(dim(t("fix.rerun")))

package/src/discover.mjs

@@ -104,6 +104,11 @@ function configCandidates(dir) {
   return CONFIG_FILES.map((name) => path.join(dir, name))
 }
 
+function isUnder(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child))
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+}
+
 /**
  * 按官方文档的注册顺序返回 skill 来源（顺序即优先级，越后越高）：
  *  1. ~/.claude/skills
@@ -158,7 +163,12 @@ export function discoverSources({ cwd = process.cwd(), home = os.homedir(), incl
       missing.push({ kind: "config-error", path: file, error: err.message })
       continue
     }
-    const entries = Array.isArray(config?.skills) ? config.skills : []
+    // 2.x: skills: [...]；1.x: skills: { paths: [...] }
+    const entries = Array.isArray(config?.skills)
+      ? config.skills
+      : Array.isArray(config?.skills?.paths)
+        ? config.skills.paths
+        : []
     for (const entry of entries) {
       if (typeof entry !== "string" || !entry.trim()) continue
       const value = entry.trim()
@@ -168,8 +178,9 @@ export function discoverSources({ cwd = process.cwd(), home = os.homedir(), incl
       }
       const expanded = expandHome(value, home)
       const abs = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded)
-      if (fs.existsSync(abs)) addSource("config-path", "config", abs)
-      else missing.push({ kind: "missing-path", path: abs, entry: value, config: file })
+      if (fs.existsSync(abs)) {
+        addSource("config-path", isUnder(projectRoot, file) ? "project" : "global", abs)
+      } else missing.push({ kind: "missing-path", path: abs, entry: value, config: file })
     }
   }
 

package/src/fix.mjs

@@ -33,7 +33,7 @@ function archiveTarget(skill, stamp) {
  * 规划安全的结构性修复：只归档「被遮蔽、永远不会加载」的定义。
  * 由更新器管理的文件不碰（应通过 update 恢复）。
  */
-export function planFixes(skills, managed = new Map(), { now = new Date() } = {}) {
+export function planFixes(skills, managed = new Map(), { now = new Date(), includeGlobal = false } = {}) {
   const winners = resolveWinners(skills)
   const byId = new Map()
   for (const skill of skills) {
@@ -44,12 +44,17 @@ export function planFixes(skills, managed = new Map(), { now = new Date() } = {}
   const stamp = now.toISOString().replace(/[:.]/g, "-")
   const plan = []
   const skipped = []
+  const skippedGlobal = []
 
   for (const [id, defs] of byId) {
     if (defs.length <= 1) continue
     const winner = winners.get(id)
     for (const loser of defs) {
       if (loser === winner) continue
+      if (!includeGlobal && loser.source.scope === "global") {
+        skippedGlobal.push(loser)
+        continue
+      }
       if (managed.has(loser.file)) {
         skipped.push(loser)
         continue
@@ -64,7 +69,7 @@ export function planFixes(skills, managed = new Map(), { now = new Date() } = {}
     }
   }
 
-  return { plan, skipped }
+  return { plan, skipped, skippedGlobal }
 }
 
 export function applyFixes(plan, { dryRun = false } = {}) {

package/src/i18n.mjs

@@ -21,6 +21,7 @@ Options:
   --lang <en|zh>       output language (default: auto from system locale)
   --config <file>      config file (default: .skills-doctor.json)
   --dry-run            fix: only print what would change
+  --all                fix: also touch global sources (default: project only)
   --hide <ids>         fix: hide skills with metadata.opencode/autoinvoke: false (comma separated)
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
@@ -79,6 +80,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "fix.dryRun": "  (dry run: nothing is moved)",
     "fix.moved": "  ✓ archived {from} → {to}",
     "fix.skippedManaged": "  · skipped {path} (installed by the updater; run update instead)",
+    "fix.skippedGlobal": "  · skipped {path} (global skill; pass --all to include)",
     "fix.none": "Nothing to fix.",
     "fix.summary": "{moved} archived, {hidden} hidden, {skipped} skipped",
     "fix.error": "  ✗ failed to archive {path}: {error}",
@@ -160,6 +162,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --lang <en|zh>      输出语言（默认按系统 locale 自动选择）
   --config <file>     配置文件（默认 .skills-doctor.json）
   --dry-run           fix: 只打印将要变更的内容，不实际修改
+  --all               fix: 同时处理全局来源的 skill（默认只动项目内）
   --hide <ids>        fix: 给指定 skill 加 metadata.opencode/autoinvoke: false（逗号分隔）
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
@@ -218,6 +221,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "fix.dryRun": "  （dry run：不会移动任何文件）",
     "fix.moved": "  ✓ 已归档 {from} → {to}",
     "fix.skippedManaged": "  · 跳过 {path}（由更新器管理，请用 update）",
+    "fix.skippedGlobal": "  · 跳过 {path}（全局 skill，加 --all 才会处理）",
     "fix.none": "没有需要修复的内容。",
     "fix.summary": "归档 {moved} 个，隐藏 {hidden} 个，跳过 {skipped} 个",
     "fix.error": "  ✗ 归档 {path} 失败: {error}",

package/src/plugin-v1.mjs

@@ -0,0 +1,31 @@
+import { tool } from "@opencode-ai/plugin"
+import { auditSkills, formatMarkdown } from "./audit.mjs"
+
+const z = tool.schema
+
+/**
+ * OpenCode 1.x 插件入口（V1 API：`server` 函数 + tool()）。
+ * 在 1.x 里通过 opencode.json 配置：
+ *   { "plugin": ["opencode-skills-doctor/v1"] }
+ * 2.x 请使用包根导出（V2 的 Plugin.define）。
+ */
+export const SkillsDoctorPlugin = async ({ directory }) => ({
+  tool: {
+    skills_doctor: tool({
+      description:
+        "Audit local OpenCode skills: duplicates, shadowing, context budget and fix hints. Returns a markdown report.",
+      args: z.object({
+        directory: z.string().optional().describe("Directory to audit (defaults to the current project)"),
+        budget: z.number().optional().describe("Description token budget (default 1200)"),
+      }),
+      execute: async (args) => {
+        const cwd = args.directory || directory || process.cwd()
+        const audit = auditSkills({ cwd, budget: typeof args.budget === "number" ? args.budget : null, lang: "en" })
+        return formatMarkdown(audit)
+      },
+    }),
+  },
+})
+
+export const server = SkillsDoctorPlugin
+export default { id: "skills-doctor", server: SkillsDoctorPlugin }