opencode-skills-doctor 0.3.8 → 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;
@@ -244,6 +244,16 @@ On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `arg
 
 `check --json`, `scan --json` and `update --json` all print structured JSON, ready for CI or a web report. Fields include `summary`, `findings[]` and `skills[]` (with `managed: { version, url, root }`).
 
+## Security
+
+This tool reads and writes skill files. Before using it against a real setup:
+
+- `update` downloads catalog content **without signature verification** — treat catalogs as code;
+- `fix` / `--prune` move or delete files — preview with `--dry-run` first;
+- it is **not a sandbox** and does not constrain what an agent can do.
+
+See [SECURITY.md](SECURITY.md) for the full threat model, hardening checklist and private vulnerability reporting.
+
 ## Caveats and known limitations
 
 **Install / plugin**

package/SECURITY.md

@@ -0,0 +1,68 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.3.x | ✅ |
+| < 0.3 | ❌ |
+
+Pre-1.0: only the latest minor receives fixes.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue**. Use GitHub private vulnerability reporting:
+
+<https://github.com/wangyuchen5110/opencodeplugginprogram/security/advisories/new>
+
+Include the version, a reproduction, the impact, and a suggested fix if you have one. Best-effort response within 7 days.
+
+## What this tool does with your system
+
+- Runs locally with the privileges of the invoking user. **No telemetry.**
+- Network access only for `update` (HTTP catalogs) and for `npx` when you install/run the package that way.
+- Reads skill files and frontmatter, `opencode.json(c)` / `opencode.jsonc`, and `.skills-doctor.lock.json`. It does **not** read model credentials, API keys, or conversation content.
+- Writes only on explicit commands:
+  - `fix` — moves shadowed definitions into `.skills-doctor-archive/`, optionally edits `metadata.opencode/autoinvoke` (`--hide`);
+  - `update` — writes downloaded files into a skill directory and updates the lock;
+  - everything else (`check`, `scan`, `mcp`) is read-only.
+
+## Risk areas and mitigations
+
+### `update` downloads untrusted content
+
+- There is **no signature verification**. The catalog's `version` field is trusted as-is.
+- Downloads are restricted to the same origin as `index.json`; path traversal (`..`, absolute paths, schemes) is rejected; files are written only under the target skill directory.
+- Downloaded skills are **instructions for an agent**. Treat catalogs as code: use a catalog you control, pin it, review diffs, and run `update --check-only` before applying.
+- The updater executes no code from the catalog. It only fetches and writes files.
+
+### `fix` and `--prune` change files
+
+- `fix` archives only definitions that are **shadowed** (never loaded). The effective skill is not moved. Archived files go to `.skills-doctor-archive/<timestamp>/` and can be restored by moving them back.
+- `fix` defaults to **project-only**; `--all` extends it to global sources (`~/.config/opencode/skills`, `~/.claude/skills`, ...).
+- `update --prune` **deletes** skill directories that disappeared from a catalog. Without `--prune` they are only reported.
+- Always use `--dry-run` first and review the paths that would change.
+
+### MCP server and plugins
+
+- `skills-doctor mcp` only runs the local audit. It does not proxy, execute, or store MCP content.
+- The OpenCode plugin runs inside the OpenCode process with your privileges. It registers one tool and one command; it does not intercept unrelated tool calls.
+- The MCP client / plugin may start the package through `npx`, which downloads the published package from npm. Pin a version (`opencode-skills-doctor@0.3.9`) if you need reproducibility.
+
+### Not a sandbox
+
+This tool audits configuration and files. **It does not constrain what an agent can do.** Use the permission and sandbox controls of your agent runtime (OpenCode permissions, OS sandboxing, containers) for containment.
+
+## Hardening checklist
+
+- Run `check` and `fix --dry-run` before letting `fix` or `--prune` modify anything.
+- Use `--no-global` on CI unless you explicitly want machine-wide skills audited.
+- Pin the package version in automation: `npx -y opencode-skills-doctor@0.3.9 check --strict`.
+- Review `.skills-doctor-archive/` and delete it when you no longer need the backups.
+- Treat every catalog and every downloaded `SKILL.md` as code you are installing.
+
+## Out of scope
+
+- Vulnerabilities in OpenCode, Claude Code, Codex, Codeium/Kimi Code, DeepSeek Harness, or any other host runtime.
+- Malicious content inside third-party skills or catalogs (that is a trust decision for the operator; see above).
+- Behavior of the models that read the skills.

package/SECURITY.zh-CN.md

@@ -0,0 +1,68 @@
+# 安全策略
+
+## 支持的版本
+
+| 版本 | 支持 |
+|---|---|
+| 0.3.x | ✅ |
+| < 0.3 | ❌ |
+
+1.0 之前，只维护最新的次版本。
+
+## 报告漏洞
+
+**请不要开公开 issue**，使用 GitHub 的私密漏洞报告：
+
+<https://github.com/wangyuchen5110/opencodeplugginprogram/security/advisories/new>
+
+请附上版本、复现步骤、影响，以及你建议的修复。我们会尽力在 7 天内响应。
+
+## 这个工具会对你的系统做什么
+
+- 以调用者的权限**在本机**运行，无遥测。
+- 只有 `update`（HTTP catalog）和通过 `npx` 安装/运行时才会联网。
+- 读取 skill 文件与 frontmatter、`opencode.json(c)` / `opencode.jsonc`、`.skills-doctor.lock.json`；**不读取**模型凭据、API key 或对话内容。
+- 只在明确命令下写入：
+  - `fix` —— 把被遮蔽的定义移入 `.skills-doctor-archive/`，`--hide` 会改 `metadata.opencode/autoinvoke`；
+  - `update` —— 下载文件写入 skill 目录并更新 lock；
+  - 其余（`check`、`scan`、`mcp`）都是只读。
+
+## 风险点与缓解措施
+
+### `update` 会下载不受信内容
+
+- **没有签名校验**，catalog 的 `version` 字段被直接信任。
+- 下载限制为与 `index.json` 同源；拒绝路径穿越（`..`、绝对路径、协议前缀）；文件只会写在目标 skill 目录内。
+- 下载的 skill 本质是**给 agent 的指令**。把 catalog 当代码对待：只用你控制的 catalog、固定版本、审查 diff、先跑 `update --check-only`。
+- 更新器不会执行 catalog 里的任何代码，只做抓取和写文件。
+
+### `fix` 与 `--prune` 会改文件
+
+- `fix` 只归档**被遮蔽**（永远不会加载）的定义，不会移动生效版本。归档到 `.skills-doctor-archive/<时间戳>/`，移回去即可恢复。
+- `fix` 默认**只处理项目内**；`--all` 才会扩展到全局来源（`~/.config/opencode/skills`、`~/.claude/skills` 等）。
+- `update --prune` 会**删除**已从 catalog 下架的 skill 目录；不加 `--prune` 只提示不删。
+- 一律先用 `--dry-run` 确认会改哪些路径。
+
+### MCP server 与插件
+
+- `skills-doctor mcp` 只执行本地审计，不代理、不执行、不存储 MCP 内容。
+- OpenCode 插件运行在 OpenCode 进程内，使用你的权限；只注册一个工具和一个命令，不会拦截无关的工具调用。
+- MCP 客户端/插件可能通过 `npx` 启动，会从 npm 下载已发布的包。需要可复现时固定版本（`opencode-skills-doctor@0.3.9`）。
+
+### 它不是沙箱
+
+这个工具只审计配置和文件，**不限制 agent 能做什么**。隔离请使用 agent 运行时的权限/沙箱能力（OpenCode permissions、操作系统沙箱、容器等）。
+
+## 加固清单
+
+- 让 `fix` / `--prune` 改任何东西之前，先跑 `check` 和 `fix --dry-run`。
+- CI 里用 `--no-global`，除非你确实想审计整机 skill。
+- 自动化里固定版本：`npx -y opencode-skills-doctor@0.3.9 check --strict`。
+- 定期审查并清理 `.skills-doctor-archive/`。
+- 把每个 catalog 和每个下载的 `SKILL.md` 都当成你要安装的代码。
+
+## 不在范围内
+
+- OpenCode、Claude Code、Codex、Kimi Code、DeepSeek Harness 等宿主运行时自身的漏洞。
+- 第三方 skill / catalog 里的恶意内容（这是使用方的信任决策，见上）。
+- 读取这些 skill 的模型本身的行为。

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 互相遮蔽——你改的可能是一份永远不会加载的文件；
@@ -244,6 +244,16 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 
 `check --json` / `scan --json` / `update --json` 都会输出结构化 JSON，方便接 CI 或做网页报告。字段包括 `summary`、`findings[]`、`skills[]`（含 `managed: { version, url, root }`）。
 
+## 安全
+
+这个工具会读写 skill 文件。对真实环境使用前：
+
+- `update` 下载的 catalog 内容**没有签名校验**——把 catalog 当代码对待；
+- `fix` / `--prune` 会移动或删除文件——先 `--dry-run` 预览；
+- 它**不是沙箱**，不限制 agent 能做什么。
+
+完整威胁模型、加固清单和私密漏洞报告方式见 [SECURITY.zh-CN.md](../SECURITY.zh-CN.md)。
+
 ## 注意事项与已知限制
 
 **安装 / 插件**

package/package.json

@@ -1,55 +1,59 @@
-{
-  "name": "opencode-skills-doctor",
-  "version": "0.3.8",
-  "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"
-  ],
-  "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)) {