opencode-skills-doctor 0.3.7 → 0.3.9

package/README.md

@@ -183,6 +183,24 @@ Any other MCP client: run `npx -y opencode-skills-doctor mcp` and allow the `ski
 
 It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and global), so it can audit skills used by other agents too.
 
+### DeepSeek Harness (DSH)
+
+DSH ships an MCP client bundle (`@deepseek-ai/dsh-mcp-client`). Add one entry to your profile patch, e.g. `~/.dsh/profiles/<profile>/cordis.patch.yml`:
+
+```yaml
+- id: mcp-skills-doctor
+  name: "@deepseek-ai/dsh-mcp-client"
+  config:
+    serverName: skills_doctor
+    transport: stdio
+    command: npx
+    args: ["-y", "opencode-skills-doctor", "mcp"]
+```
+
+Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor`.
+
+On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
+
 ## Rules
 
 | Rule | Level | Meaning |
@@ -226,6 +244,16 @@ It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and
 
 `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/README.zh-CN.md

@@ -183,6 +183,24 @@ args = ["-y", "opencode-skills-doctor", "mcp"]
 
 它扫描 `.opencode/skills`、`.claude/skills`、`.agents/skills`（项目和全局），所以其他 agent 用的 skill 也能一起体检。
 
+### DeepSeek Harness（DSH）
+
+DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile 的 patch 里加一条，例如 `~/.dsh/profiles/<profile>/cordis.patch.yml`：
+
+```yaml
+- id: mcp-skills-doctor
+  name: "@deepseek-ai/dsh-mcp-client"
+  config:
+    serverName: skills_doctor
+    transport: stdio
+    command: npx
+    args: ["-y", "opencode-skills-doctor", "mcp"]
+```
+
+重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现。
+
+Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
+
 ## 检测规则
 
 | 规则 | 级别 | 含义 |
@@ -226,6 +244,16 @@ args = ["-y", "opencode-skills-doctor", "mcp"]
 
 `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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.7",
+  "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": {
@@ -35,7 +35,9 @@
     "bin",
     "src",
     "README.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "SECURITY.md",
+    "SECURITY.zh-CN.md"
   ],
   "keywords": [
     "opencode",