opencode-skills-doctor 0.8.1 → 0.9.3

package/README.md

@@ -2,25 +2,41 @@
   <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/banner.svg" alt="skills-doctor — audit the hidden token cost of agent skills" width="100%">
 </p>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/v/opencode-skills-doctor?style=flat-square&color=3fb950" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=flat-square" alt="npm downloads"></a>
-  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=flat-square&color=58a6ff" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/node-%E2%89%A520-3fb950?style=flat-square" alt="Node ≥ 20">
-  <a href="LICENSE"><img src="https://img.shields.io/npm/l/opencode-skills-doctor?style=flat-square" alt="MIT license"></a>
-  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml"><img src="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg?style=flat-square" alt="tests"></a>
-</p>
+<h1 align="center">skills-doctor</h1>
 
 <p align="center">
   <b>Audit, fix and update the skills your coding agent loads.</b><br>
   Measure the per-step token tax, find shadowed duplicates and broken references — then fix them safely.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/v/opencode-skills-doctor?style=for-the-badge&color=3fb950" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=for-the-badge&color=2ea043" alt="npm downloads"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=for-the-badge&color=58a6ff" alt="GitHub stars"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml"><img src="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/runs%20locally-100%25-3fb950?style=for-the-badge" alt="runs locally">
+  <img src="https://img.shields.io/badge/telemetry-none-3fb950?style=for-the-badge" alt="no telemetry">
+  <img src="https://img.shields.io/badge/user%20data-never%20read-3fb950?style=for-the-badge" alt="user data is never read">
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-3fb950?style=for-the-badge" alt="Node ≥ 20">
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/opencode-skills-doctor?style=for-the-badge" alt="MIT license"></a>
+</p>
+
 <p align="center">
   English · <a href="docs/README.zh-CN.md">简体中文</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="SECURITY.md">Security</a> · <a href="docs/REFERENCE.md">Full reference</a>
 </p>
 
----
+> **Runs 100% locally.** No telemetry, no account, no uploads — your skills,
+> prompts and files never leave your machine. See [Privacy](#privacy-local-only-no-data-collection).
+
+## Contents
+
+- [The 30-second version](#the-30-second-version) · [Privacy](#privacy-local-only-no-data-collection)
+- [See it](#see-it) · [How it works](#how-it-works) · [Quick start](#quick-start)
+- [Install](#install) · [Use it in CI](#use-it-in-ci-github-action) · [Commands](#commands) · [Works where you work](#works-where-you-work)
+- [Why it is safe](#why-it-is-safe) · [Development](#development)
 
 ## The 30-second version
 
@@ -36,6 +52,20 @@ Every agent skill with a `description` is advertised to the model on **every sin
 | **Report** | terminal, JSON, or a self-contained HTML report |
 | **Run it** | CLI · OpenCode plugin (1.x/2.x/Desktop) · MCP server · DeepSeek Harness skill |
 
+## Privacy: local-only, no data collection
+
+`skills-doctor` runs entirely on your machine. There is no telemetry, no analytics, no account, no API key, and nothing is uploaded — not your skills, prompts, conversations or files.
+
+| | |
+|---|---|
+| **Reads** | only skill definitions (`SKILL.md` plus the `references/`, `scripts/`, `assets/` files they point at), agent config (`opencode.json(c)`, `.skills-doctor.json`, DSH patch, MCP configs) and the lockfile |
+| **Never reads** | conversation history, session transcripts, source code, documents, credentials, API keys or environment secrets |
+| **Uploads** | nothing: there is no server component and no remote endpoint besides the two optional calls below |
+| **Network** | only when you ask for it. `update` fetches the HTTP catalogs **you** configure; `upgrade` / the daily update check reads the npm registry for the latest version number (cached 24 h — disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`) |
+| **Writes** | only what you asked for: the HTML/JSON report, `.skills-doctor-archive/`, `.skills-doctor.json`, the lockfile, and the plugin/MCP/skill entries created by `install` |
+
+`opencode.json(c)` and MCP configs can contain credentials; they are parsed locally only to find the relevant entries, and those values are never sent anywhere nor included in a report. Reports contain file paths and skill descriptions (which are part of your skill files), never file bodies. `check`, `plan`, `scan`, `fix --dry-run` and `mcp` all work with the network fully offline.
+
 ## See it
 
 <p align="center">
@@ -44,6 +74,23 @@ Every agent skill with a `description` is advertised to the model on **every sin
 
 A real `check --html` run: summary cards, the context-budget bar, filterable findings, and the exact potential savings.
 
+## How it works
+
+```mermaid
+flowchart LR
+  A["skill roots<br/>OpenCode · Claude · Grok · Cursor · Hermes · Kimi · DSH"] --> B["discover<br/>precedence resolved"]
+  B --> C["scan SKILL.md<br/>frontmatter + body + hash"]
+  C --> D["lint<br/>16 rules + token budget"]
+  D --> E{"findings?"}
+  E -->|"yes"| F["plan / fix<br/>trim · hide · archive"]
+  E -->|"always"| G["report<br/>terminal · JSON · HTML"]
+  F --> G
+  G --> H["you · CI · the agent"]
+```
+
+Everything runs in one pass and is deterministic: the same skill files produce the
+same numbers, so a report is safe to diff in CI.
+
 ## Quick start
 
 ```powershell
@@ -89,7 +136,38 @@ npx -y opencode-skills-doctor mcp
 { "mcpServers": { "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] } } }
 ```
 
-Nothing to configure for **skills discovery**: it reads `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills` and their user-level equivalents. See the [full reference](docs/REFERENCE.md) for OpenCode 1.x, DSH YAML, Codex TOML and Claude Code details.
+Nothing to configure for **skills discovery**: it reads `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `.hermes/skills`, `.kimi-code/skills`, `.dsh/skills` (plus `$DSH_HOME`) and their user-level equivalents. See the [full reference](docs/REFERENCE.md) for OpenCode 1.x, DSH YAML, Codex TOML and Claude Code details.
+
+## Use it in CI (GitHub Action)
+
+A composite action ships in this repo: no install step, no runtime dependencies —
+it runs the checked-out code directly.
+
+```yaml
+name: skills
+on: [push, pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write # only needed for `comment: true`
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.3
+        with:
+          budget: "1200"
+          fail-on: warn             # error | warn | never
+          html: skills-report.html  # written and uploaded as an artifact
+          comment: "true"           # post the summary on the PR
+```
+
+It writes a summary to the job page, uploads the HTML report, optionally comments
+on the pull request, and fails the job according to `fail-on`. Outputs:
+`exit-code`, `error-count`, `warning-count`, `advertised-tokens`. Anything else
+goes through `extra-args` (for example `--no-global`).
 
 ## Commands
 
@@ -113,11 +191,12 @@ All commands accept `--json`, `--lang en|zh`, `--budget`, `--root` and `--no-glo
 | **OpenCode 2.x** | `plugins: ["opencode-skills-doctor"]` → tool + commands + budget warning |
 | **OpenCode 1.x** | `install` writes the local plugin entry and markdown commands |
 | **OpenCode Desktop** | shares the CLI config; `--client desktop` detects the app and its bundled core |
-| **DeepSeek Harness** | `install --client dsh` adds the MCP entry and the `skills-doctor-audit` skill |
+| **DeepSeek Harness** | `install --client dsh` adds the MCP entry and the `skills-doctor-audit` skill; `$DSH_HOME/skills` is scanned |
 | **Claude Code / Codex** | MCP server (`npx -y opencode-skills-doctor mcp`) |
 | **Grok CLI / Cursor** | their skill roots are scanned natively |
 | **Hermes Agent** | MCP entry in `~/.hermes/config.yaml`; `~/.hermes/skills` is scanned |
 | **Kimi Code** | `install --client kimi` writes `~/.kimi-code/mcp.json` + the audit skill |
+| **OpenClaw** | separate wrapper with its own native plugin: [openclaw-skills-doctor](https://github.com/wangyuchen5110/openclaw-skills-doctor) |
 
 ## Why it is safe
 

package/SECURITY.md

@@ -27,6 +27,15 @@ Include the version, a reproduction, the impact, and a suggested fix if you have
   - `update` — writes downloaded files into a skill directory and updates the lock;
   - everything else (`check`, `scan`, `mcp`) is read-only.
 
+## Data handling and privacy
+
+- **Nothing leaves your machine.** No telemetry, analytics, accounts, or crash reporting. There is no backend service.
+- **No network by default.** Two opt-in/opt-out exceptions: `update` fetches the catalog URLs you configure, and the daily update check reads only the latest version number from the npm registry (24 h cache; disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`).
+- **No user data is read.** The tool reads skill files, their referenced resources, agent configuration and its own lockfile. It does not read chat history, session transcripts, source code, documents, model credentials or API keys — and it does not upload anything it reads.
+- **Config files may hold secrets** (`opencode.json(c)`, MCP configs). They are parsed locally only to locate the entries the tool needs; values are never transmitted, printed, or copied into reports.
+- **Reports are local files.** HTML/JSON reports contain file paths and skill descriptions, never file bodies. They can reveal your directory layout, so review them before sharing.
+- `check`, `plan`, `scan`, `fix --dry-run` and `mcp` are fully offline; you can run them with networking disabled.
+
 ## Risk areas and mitigations
 
 ### `update` downloads untrusted content

package/SECURITY.zh-CN.md

@@ -27,6 +27,15 @@
   - `update` —— 下载文件写入 skill 目录并更新 lock；
   - 其余（`check`、`scan`、`mcp`）都是只读。
 
+## 数据处理与隐私
+
+- **数据不会离开你的机器。** 没有遥测、统计、账号或崩溃上报，也没有任何后端服务。
+- **默认不联网。** 只有两个例外：`update` 抓取你配置的 catalog URL；每日更新检查只从 npm registry 读取最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭）。
+- **不读取用户数据。** 只读 skill 文件及其引用资源、agent 配置和自身 lockfile；不读对话历史、会话记录、源代码、文档、模型凭据或 API key，也不上传任何读到的内容。
+- **配置文件可能含密钥**（`opencode.json(c)`、MCP 配置）：只在本地解析以定位需要的条目，值不会被传输、打印或写进报告。
+- **报告是本地文件。** HTML/JSON 报告含文件路径和 skill 描述，不含文件正文；可能暴露目录结构，分享前请自行检查。
+- `check`、`plan`、`scan`、`fix --dry-run`、`mcp` 完全离线，可在断网环境运行。
+
 ## 风险点与缓解措施
 
 ### `update` 会下载不受信内容

package/docs/README.zh-CN.md

@@ -2,24 +2,42 @@
   <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/banner.svg" alt="skills-doctor" width="100%">
 </p>
 
+<h1 align="center">skills-doctor</h1>
+
 <p align="center">
   <b>审计、修复、更新你的 coding agent 加载的 skill。</b><br>
   量出每步 token 税，找出遮蔽重复和断链，再安全地修掉。
 </p>
 
-# skills-doctor
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/v/opencode-skills-doctor?style=for-the-badge&color=3fb950" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=for-the-badge&color=2ea043" alt="downloads"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=for-the-badge&color=58a6ff" alt="stars"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml"><img src="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/runs%20locally-100%25-3fb950?style=for-the-badge" alt="本地运行">
+  <img src="https://img.shields.io/badge/telemetry-none-3fb950?style=for-the-badge" alt="无遥测">
+  <img src="https://img.shields.io/badge/user%20data-never%20read-3fb950?style=for-the-badge" alt="不读取用户数据">
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-3fb950?style=for-the-badge" alt="Node ≥ 20">
+  <a href="../LICENSE"><img src="https://img.shields.io/npm/l/opencode-skills-doctor?style=for-the-badge" alt="MIT"></a>
+</p>
 
-[English](../README.md) · [完整英文参考](REFERENCE.md)
+<p align="center">
+  <a href="../README.md">English</a> · 简体中文 · <a href="../CHANGELOG.md">变更记录</a> · <a href="../SECURITY.zh-CN.md">安全策略</a> · <a href="REFERENCE.md">完整参考</a>
+</p>
 
-[![npm](https://img.shields.io/npm/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![downloads](https://img.shields.io/npm/dw/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![node](https://img.shields.io/node/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![license](https://img.shields.io/npm/l/opencode-skills-doctor)](../LICENSE)
-[![test](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg)](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml)
+> **纯本地运行。** 无遥测、不需要账号、不上传 —— 你的 skill、提示词和文件不会离开你的机器。见[隐私](#隐私纯本地运行不收集数据)。
 
 OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **OpenCode 插件入口** —— 零依赖，Node ≥ 20。
 
-[English](../README.md) | **简体中文** · [变更记录](../CHANGELOG.md) · [安全策略](../SECURITY.zh-CN.md)
+## 目录
+
+- [一张表看懂](#一张表看懂) · [隐私](#隐私纯本地运行不收集数据)
+- [为什么需要它](#为什么需要它) · [快速开始](#快速开始) · [命令](#命令)
+- [工作原理](#工作原理) · [检测规则](#检测规则) · [安全](#安全)
+- [常见问题](#常见问题faq) · [开发与贡献](#开发与贡献)
 
 ## 一张表看懂
 
@@ -27,14 +45,28 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 |---|---|
 | **是什么** | 审计、修复、更新 coding agent 加载的 skill |
 | **形态** | CLI · OpenCode 插件（1.x / 2.x）· MCP server（Claude Code、Codex、DSH…）· 兼容 Grok CLI |
-| **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`.grok/skills`、`.cursor/skills`、`opencode.json(c)` 配置、HTTP catalog |
+| **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`.grok/skills`、`.cursor/skills`、`.hermes/skills`、`.kimi-code/skills`、`.dsh/skills`（含 `$DSH_HOME`）、`opencode.json(c)` 配置、HTTP catalog |
 | **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
 | **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
 | **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 58 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 63 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+
+## 隐私：纯本地运行，不收集数据
+
+`skills-doctor` 完全在你自己的机器上运行。没有遥测、没有统计、不需要账号和 API key，也不会把你的 skill、提示词、对话或文件上传到任何地方。
+
+| | |
+|---|---|
+| **会读** | 只读 skill 定义（`SKILL.md` 及其引用的 `references/`、`scripts/`、`assets/` 文件）、agent 配置（`opencode.json(c)`、`.skills-doctor.json`、DSH patch、MCP 配置）和它自己的 lockfile |
+| **不会读** | 对话历史、会话记录、源代码、文档、凭据、API key、环境变量里的密钥 |
+| **不会上传** | 任何东西：没有服务端组件，除下面两个可选联网外没有任何远端地址 |
+| **联网** | 只在你主动触发时发生：`update` 抓取**你自己配置**的 HTTP catalog；`upgrade` / 每日更新检查只读 npm registry 的最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭） |
+| **会写** | 只写你要求的内容：HTML/JSON 报告、`.skills-doctor-archive/`、`.skills-doctor.json`、lockfile，以及 `install` 生成的插件/MCP/skill 条目 |
+
+`opencode.json(c)` 和 MCP 配置里可能有凭据；它们只在本地被解析用来定位相关条目，值不会被发送，也不会出现在报告里。报告只含文件路径和 skill 描述（本来就是你的 skill 文件内容），不包含正文。`check`、`plan`、`scan`、`fix --dry-run`、`mcp` 都可以在断网环境下运行。
 
 ## 为什么需要它
 

package/docs/REFERENCE.md

@@ -478,9 +478,11 @@ It merges `skills-doctor` into `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.
 10. project `.hermes/skills`
 11. `~/.kimi-code/skills`
 12. project `.kimi-code/skills`
-13. `~/.config/opencode/skills`
-14. project `.opencode/skills`
-15. 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
+13. `$DSH_HOME/skills` (default `~/.dsh/skills`) — DeepSeek Harness, where `install --client dsh` puts its skill
+14. project `.dsh/skills`
+15. `~/.config/opencode/skills`
+16. project `.opencode/skills`
+17. 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.8.1",
-  "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, HTML reports, catalog sync. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI, Cursor and DeepSeek Harness.",
+  "version": "0.9.3",
+  "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, HTML reports, catalog sync. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI, Cursor, Hermes Agent, Kimi Code and DeepSeek Harness.",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",

package/src/audit.mjs

@@ -17,13 +17,15 @@ export function auditSkills({
   budget = null,
   staleDays = null,
   extraDirs = [],
+  home = undefined,
+  env = undefined,
 } = {}) {
   const loaded = loadConfig(cwd, configPath)
   const config = loaded.config
   const resolvedLang = normalizeLang(lang) ?? normalizeLang(config.lang) ?? detectLang()
   const t = translator(resolvedLang)
 
-  const discovered = scanAll(discoverSources({ cwd, includeGlobal, extraDirs }))
+  const discovered = scanAll(discoverSources({ cwd, includeGlobal, extraDirs, home, env }))
   const managedInfo = inspectManaged(discovered.scans, { t })
 
   const effectiveBudget = Number.isFinite(budget) && budget > 0 ? budget : config.budget ?? 1200

package/src/catalog.mjs

@@ -19,6 +19,20 @@ function safeRelPath(p) {
   return true
 }
 
+/**
+ * A catalog entry name becomes a directory under the target root, so it must be
+ * exactly one plain path segment - otherwise `../x` or `a/b` escapes `into`.
+ */
+function safeSkillName(name) {
+  if (typeof name !== "string") return false
+  const value = name.trim()
+  if (!value || value === "." || value === "..") return false
+  if (value.includes("/") || value.includes("\\")) return false
+  if (path.isAbsolute(value)) return false
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) return false
+  return true
+}
+
 function resolveInside(baseDir, rel, t) {
   const base = path.resolve(baseDir)
   const target = path.resolve(base, rel)
@@ -32,6 +46,7 @@ export function validateCatalogEntry(entry, t = translator("en")) {
   const problems = []
   if (!entry || typeof entry !== "object") return [t("catalog.entryNotObject")]
   if (typeof entry.name !== "string" || !entry.name.trim()) problems.push(t("catalog.missingName"))
+  else if (!safeSkillName(entry.name)) problems.push(t("catalog.safeName", { name: entry.name }))
   if (typeof entry.version !== "string" && typeof entry.version !== "number") {
     problems.push(t("catalog.missingVersion"))
   }
@@ -151,6 +166,26 @@ export async function updateCatalogs(
   const lockTooNew = Number(lock.version ?? 1) > LOCK_VERSION
   const results = []
 
+  // Never rewrite a lock written by a newer tool: its semantics are unknown and
+  // downgrading it could silently break drift detection for that version.
+  if (lockTooNew) {
+    return {
+      lockPath,
+      lockTooNew,
+      results: catalogs.map((catalog) => ({
+        url: catalog.url,
+        error: t("catalog.lockTooNew", { found: lock.version, supported: LOCK_VERSION }),
+        updated: [],
+        unchanged: [],
+        invalid: [],
+        orphaned: [],
+        pruned: [],
+        removedFiles: [],
+        files: 0,
+      })),
+    }
+  }
+
   for (const catalog of catalogs) {
     const result = {
       url: catalog.url,
@@ -226,7 +261,8 @@ export async function updateCatalogs(
       const validNames = new Set(
         skills.filter((entry) => validateCatalogEntry(entry, t).length === 0).map((entry) => entry.name),
       )
-      const orphaned = Object.keys(previousSkills).filter((name) => !validNames.has(name))
+      // A tampered or older lock can carry unsafe names; never touch those paths.
+      const orphaned = Object.keys(previousSkills).filter((name) => safeSkillName(name) && !validNames.has(name))
       result.orphaned = orphaned
 
       if (!checkOnly) {

package/src/desktop.mjs

@@ -21,8 +21,10 @@ export function desktopCandidates(platform = process.platform, env = process.env
   return ["/usr/bin/opencode-desktop", "/usr/local/bin/opencode-desktop", "/opt/OpenCode/opencode-desktop", "/opt/opencode-desktop/opencode-desktop"]
 }
 
-function asarPathFor(exe) {
-  if (process.platform === "darwin" || exe.includes(".app")) {
+function asarPathFor(exe, platform = process.platform) {
+  // Callers may probe another platform (tests, cross-platform tooling), so use
+  // the requested platform instead of the host one.
+  if (platform === "darwin" || exe.includes(".app")) {
     return path.join(path.dirname(path.dirname(path.dirname(path.dirname(exe)))), "Resources", "app.asar")
   }
   return path.join(path.dirname(exe), "resources", "app.asar")
@@ -71,8 +73,9 @@ export function readAsarVersion(asarFile) {
 export function detectDesktop({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
   for (const exe of desktopCandidates(platform, env, home)) {
     if (!fs.existsSync(exe)) continue
-    const version = readAsarVersion(asarPathFor(exe))
-    return { installed: true, exe, version, asar: asarPathFor(exe) }
+    const asar = asarPathFor(exe, platform)
+    const version = readAsarVersion(asar)
+    return { installed: true, exe, version, asar }
   }
   return { installed: false, exe: null, version: null, asar: null }
 }

package/src/discover.mjs

@@ -14,6 +14,11 @@ export function expandHome(p, home = os.homedir()) {
 
 /** 去掉 JSONC 的注释和尾逗号，字符串内的内容不动。 */
 export function stripJsonc(text) {
+  return stripTrailingCommas(stripJsonComments(text))
+}
+
+/** First pass: drop `//` and `/* *\/` comments, leaving strings untouched. */
+function stripJsonComments(text) {
   let out = ""
   let inString = false
   let escaped = false
@@ -63,7 +68,41 @@ export function stripJsonc(text) {
     out += ch
   }
 
-  return out.replace(/,(\s*[}\]])/g, "$1")
+  return out
+}
+
+/**
+ * Second pass: drop commas that only precede a closing brace/bracket.
+ * Done character by character so a `,}` inside a string survives.
+ */
+function stripTrailingCommas(text) {
+  let out = ""
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === "\\") escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === ",") {
+      let j = i + 1
+      while (j < text.length && /\s/.test(text[j])) j++
+      if (text[j] === "}" || text[j] === "]") continue
+    }
+    out += ch
+  }
+
+  return out
 }
 
 export function readJsoncFile(file) {
@@ -124,17 +163,26 @@ function isUnder(parent, child) {
  * 10. 项目 .hermes/skills
  * 11. ~/.kimi-code/skills（Kimi Code）
  * 12. 项目 .kimi-code/skills
- * 13. ~/.config/opencode/skills
- * 14. 项目 .opencode/skills（项目根 → cwd）
- * 15. opencode.json(c) 里的 skills 数组 / skills.paths
+ * 13. $DSH_HOME/skills（默认 ~/.dsh/skills，DeepSeek Harness）
+ * 14. 项目 .dsh/skills
+ * 15. ~/.config/opencode/skills
+ * 16. 项目 .opencode/skills（项目根 → cwd）
+ * 17. opencode.json(c) 里的 skills 数组 / skills.paths
  */
-export function discoverSources({ cwd = process.cwd(), home = os.homedir(), includeGlobal = true, extraDirs = [] } = {}) {
+export function discoverSources({
+  cwd = process.cwd(),
+  home = os.homedir(),
+  includeGlobal = true,
+  extraDirs = [],
+  env = process.env,
+} = {}) {
   const projectRoot = findProjectRoot(cwd) ?? path.resolve(cwd)
   const projectChain = pathChain(projectRoot, cwd)
   const sources = []
   const catalogs = []
   const missing = []
   const seen = new Set()
+  const dshHome = env.DSH_HOME ? path.resolve(expandHome(env.DSH_HOME, home)) : path.join(home, ".dsh")
 
   const addSource = (kind, scope, dir) => {
     const abs = path.resolve(dir)
@@ -161,6 +209,9 @@ export function discoverSources({ cwd = process.cwd(), home = os.homedir(), incl
   if (includeGlobal) addSource("kimi-global", "global", path.join(home, ".kimi-code", "skills"))
   for (const dir of projectChain) addSource("kimi-project", "project", path.join(dir, ".kimi-code", "skills"))
 
+  if (includeGlobal) addSource("dsh-global", "global", path.join(dshHome, "skills"))
+  for (const dir of projectChain) addSource("dsh-project", "project", path.join(dir, ".dsh", "skills"))
+
   if (includeGlobal) addSource("opencode-global", "global", path.join(home, ".config", "opencode", "skills"))
   for (const dir of projectChain) addSource("opencode-project", "project", path.join(dir, ".opencode", "skills"))
 
@@ -268,8 +319,12 @@ function walkForSkillMd(dir, source, out, depth, seen) {
 
 function buildSkill({ id, file, source, form }) {
   let text = ""
+  let bytes = 0
   try {
-    text = fs.readFileSync(file, "utf8")
+    const buffer = fs.readFileSync(file)
+    bytes = buffer.length
+    // Strip a UTF-8 BOM so the frontmatter fence is found (Windows editors add one).
+    text = buffer.toString("utf8").replace(/^\uFEFF/, "")
   } catch {
     text = ""
   }
@@ -309,7 +364,7 @@ function buildSkill({ id, file, source, form }) {
     body,
     bodyChars: body.trim().length,
     bodyTokens: estimateTokens(body),
-    bytes: Buffer.byteLength(text),
+    bytes,
     descriptionTokens: estimateTokens(description),
     hash: sha1(body.replace(/\s+/g, " ").trim()),
     mtime,

package/src/i18n.mjs

@@ -148,7 +148,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "upgrade.upToDate": "Already up to date.",
     "upgrade.done": "Upgraded to the latest version.",
     "upgrade.failed": "Upgrade failed; run it manually: {cmd}",
-    "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
+    "update.lockTooNew": "  ! lock is newer than this tool; refusing to rewrite it (upgrade skills-doctor)",
     "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).",
     "update.driftRepair": "{name} {version} (drift repaired)",
@@ -229,6 +229,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "catalog.missingVersion": "missing version",
     "catalog.missingFiles": "missing files",
     "catalog.safePath": "unsafe file path: {file}",
+    "catalog.safeName": "unsafe skill name (one plain path segment required): {name}",
+    "catalog.lockTooNew": "lock version {found} is newer than supported ({supported}); refusing to rewrite it - upgrade skills-doctor",
     "catalog.missingEntryFile": "files has no SKILL.md or <name>.md",
   },
 
@@ -377,7 +379,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "upgrade.upToDate": "已是最新版本。",
     "upgrade.done": "已升级到最新版本。",
     "upgrade.failed": "升级失败，请手动执行: {cmd}",
-    "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
+    "update.lockTooNew": "  ! lock 版本比本工具新，拒绝改写（请升级 skills-doctor）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",
     "update.noCatalogs": "没有配置 HTTP catalog。在 opencode.json(c) 的 skills 数组里写 https://... 即可。",
     "update.driftRepair": "{name} {version}（修复 drift）",
@@ -452,6 +454,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "catalog.missingVersion": "缺少 version",
     "catalog.missingFiles": "缺少 files",
     "catalog.safePath": "不安全的文件路径: {file}",
+    "catalog.safeName": "不安全的 skill 名（必须是一个普通路径段）: {name}",
+    "catalog.lockTooNew": "lock 版本 {found} 比本工具支持的 {supported} 新，拒绝改写 —— 请升级 skills-doctor",
     "catalog.missingEntryFile": "files 里没有 SKILL.md 或 <name>.md",
   },
 }

package/src/install.mjs

@@ -236,12 +236,17 @@ export function installOpenCode({
   const pkgFile = path.join(dir, "package.json")
   const pkgText = readText(pkgFile)
   let pkg = {}
+  let pkgParsed = pkgText === null
   if (pkgText !== null) {
     try {
       pkg = JSON.parse(pkgText)
-    } catch {}
+      pkgParsed = true
+    } catch (err) {
+      // Never overwrite a package.json we could not parse - that would drop it.
+      errors.push(`cannot parse ${pkgFile}: ${String(err?.message ?? err)}`)
+    }
   }
-  if (pkg.type !== "module") {
+  if (pkgParsed && pkg.type !== "module") {
     if (!dryRun) {
       pkg.type = "module"
       fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + "\n", "utf8")

package/src/lint.mjs

@@ -203,18 +203,19 @@ export function lint(skills, options = {}) {
     })
   }
 
-  // 5) 描述近似（token 集合只算一次；先按集合大小做 0.75 上界预筛）
-  const withDesc = described.map((skill) => ({ skill, tokens: tokenSet(skill.description) }))
+  // 5) 描述近似（token 集合只算一次；按大小升序后用 Jaccard 上界提前结束）
+  const withDesc = described
+    .map((skill) => ({ skill, tokens: tokenSet(skill.description) }))
+    .filter((entry) => entry.tokens.size > 0)
+    .sort((x, y) => x.tokens.size - y.tokens.size)
   const pairs = []
   for (let i = 0; i < withDesc.length; i++) {
+    const a = withDesc[i]
     for (let j = i + 1; j < withDesc.length; j++) {
-      const a = withDesc[i]
       const b = withDesc[j]
       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
+      // 大小升序：a 为空集已过滤，|a|/|b| 随 j 单调下降，低于阈值后再无可能命中。
+      if (a.tokens.size / b.tokens.size < NEAR_DUPLICATE_THRESHOLD) break
       const score = jaccard(a.tokens, b.tokens)
       if (score >= NEAR_DUPLICATE_THRESHOLD) pairs.push({ a: a.skill.id, b: b.skill.id, score })
     }

package/src/mcp.mjs

@@ -10,7 +10,7 @@ export function toolDefinition() {
   return {
     name: TOOL_NAME,
     description:
-      "Audit local agent skills (OpenCode / Claude Code / .agents): duplicate and shadowed definitions, per-step description token budget, oversized bodies and fix hints. Returns a markdown report.",
+      "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowed duplicates, per-step description token budget, oversized bodies and fix hints. Returns a markdown report.",
     inputSchema: {
       type: "object",
       properties: {

package/src/parse.mjs

@@ -6,10 +6,13 @@ import { createHash } from "node:crypto"
 
 /** @param {string} text */
 export function parseFrontmatter(text) {
-  const empty = { data: {}, body: text, hasFrontmatter: false }
-  if (!text.startsWith("---")) return empty
+  // A UTF-8 BOM (Windows editors add one) would otherwise hide the opening `---`
+  // and make the whole skill look like it has no frontmatter.
+  const source = String(text ?? "").replace(/^\uFEFF/, "")
+  const empty = { data: {}, body: source, hasFrontmatter: false }
+  if (!source.startsWith("---")) return empty
 
-  const lines = text.split(/\r?\n/)
+  const lines = source.split(/\r?\n/)
   if (lines[0].trim() !== "---") return empty
 
   let end = -1

package/src/plugin-v1.mjs

@@ -33,7 +33,7 @@ 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.",
+        "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowing, per-step token 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)"),

package/src/plugin.mjs

@@ -35,7 +35,7 @@ export default Plugin.define({
       editor.namespace({ name: "skills", description: "OpenCode skill diagnostics" })
       editor.add({
         name: "doctor",
-        description: "Audit local OpenCode skills: duplicates, shadowing, context budget and fix hints",
+        description: "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowing, per-step token budget and fix hints",
         input: {
           type: "object",
           properties: {