opencode-skills-doctor 0.3.9 → 0.3.10

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;

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 互相遮蔽——你改的可能是一份永远不会加载的文件；
@@ -252,7 +252,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.10",
+  "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/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)) {