dsh-plugin-verifier

A DeepSeek Harness tool plugin: a read-only health auditor for DSH plugins. DeepSeek Harness 工具插件：DSH 插件「健康分评估器」（只读审计）。

Registers the dsh_audit_plugin tool via defineTool(). Given an npm package name (or a GitHub repository URL) it returns a structured「体检报告」with a verdict of 建议安装 / 谨慎安装 / 不建议安装, the evidence behind it, and maintenance context.

Read-only by construction: it fetches registry metadata, extracts the tarball to a temp directory, and statically scans text. It never imports, requires, or executes any code from the plugin under audit. Temp directories are always removed, including on failure paths.

What it does / 工作方式

Stage 1 — admission checks / 阶段一 准入检查 (rejects「标签污染」的假插件):

Check	Fails when
package.json declares dsh.bundle.patch	missing — not a real DSH bundle plugin
package name starts with dsh-	warn only (cannot infer from naming)
version is not a placeholder	0.0.0 / 0.0.0-*; 0.0.1* warns
last publish within 730 days	warn only (stale maintenance)

Admission failure returns 不建议安装 immediately and skips the download.

Stage 2 — static security scan / 阶段二 安全扫描 (only for admitted packages):

• Lifecycle scripts: curl/wget piped to a shell, .npmrc / env-var reads combined with network egress, install-time network access, inline sh -c / node -e.
• Dangerous code patterns: eval(), new Function(), __proto__ pollution, remote dynamic import(), ctx.bash / ctx.subprocess use, child_process, hex obfuscation, high-entropy Base64 blobs.
• Permission surface: inject entries in the cordis patch that are too broad (bash, pwsh, shell, subprocess, terminal, fs, sandbox, *).

Each hit records the rule id, severity, file path, line number, and a code snippet.

Quick start / 快速开始

pnpm install
pnpm run build                 # tsc → dist/index.js (pure ESM)

# From the PARENT directory, install into a profile and boot:
dsh plugin --profile my-profile add ./dsh-plugin-verifier
dsh --profile my-profile       # watch for: [dsh-plugin-verifier] registered "dsh_audit_plugin" — listed=true

注意：dsh plugin add <dir> 的相对路径锚定「调用目录」，请在插件父目录执行。

Then call the tool:

{ "packageName": "dsh-skills-bridge" }                        // npm 包名
{ "packageName": "https://github.com/owner/repo" }            // 或 GitHub 仓库地址

Self-test / 自测

smoke-test.mjs drives the built tool against synthetic tarball fixtures (a malicious one and a clean one) by stubbing fetch, so it needs no registry access and publishes nothing:

pnpm run build && node smoke-test.mjs

audit.mjs is a local CLI entry that runs one real audit without booting DSH:

node audit.mjs express
node audit.mjs https://github.com/YTyangtao666/dsh-skills-bridge

Verify without an API key / 无 key 验证

dsh --profile my-profile --dump-config | grep dsh-plugin-verifier   # 配置层含本行

Dependencies pinned / 依赖锁定

• @deepseek-ai/dsh-tools: 0.1.5-rc.2 (exact — the next-tag line; npm latest is stale).
• @deepseek-ai/cordis: ^4.0.2 (peerDependency — host provides it; types-only in code).

Theme & Skin Compatibility / 主题与皮肤兼容

This plugin has no host-rendered UI of its own (tool results render through the official chat surface), so it is compatible by construction. If you later add a panel, follow the DSH Web styling contract: colors via --dsw-alias-* tokens only, and emit data-dsh-plugin / data-dsh-part / data-dsh-surface semantic attributes (dsh-web skin-center contracts).

本插件没有自有宿主 UI（工具结果走官方聊天面渲染），天然兼容。若以后加面板： 颜色只用 --dsw-alias-* 令牌，并输出 data-dsh-* 语义属性（见上方契约链接）。

Pitfalls / 坑（从真实 spike 提炼，防呆）

1. Node version: DSH requires Node ^22.19.0 || >=24.0.0. Older Node (e.g. v22.17) only warns EBADENGINE but may hit runtime issues — upgrade if you can.

   • Node 版本：DSH 要求 ^22.19.0 || >=24.0.0。旧版本（如 v22.17）只告警 EBADENGINE，不阻断，但建议升级。

2. npm dist-tag trap (the big one): @deepseek-ai/dsh-tools latest is a STALE 0.0.1-rc.1; the real line is under the next tag (0.1.0-rc.x). This scaffold pins the next-tag version for you — never npm i @deepseek-ai/dsh-tools over it.

   • npm dist-tag 坑（最大）：@deepseek-ai/dsh-tools 的 latest 是过期的 0.0.1-rc.1，正确版本在 next tag。本脚手架已锁 next 版本，勿再手动 npm i 覆盖。

3. Version-line alignment: keep every @deepseek-ai/dsh-* package on the same 0.1.0-rc.x line so pnpm does not install two module copies.

   • 版本线对齐：所有 @deepseek-ai/dsh-* 包统一用同一 0.1.0-rc.x 线，避免 pnpm 装两份模块。

4. @deepseek-ai/cordis is a peerDependency: import only type { Context } (erased at compile). At runtime the host hands you ctx — never import cordis values at runtime.

   • @deepseek-ai/cordis 是 peerDep：只 import type（编译期擦除），运行时 ctx 由宿主传入。

5. Pure ESM: package.json must set "type": "module"; build with module: esnext + moduleResolution: bundler to keep bare specifiers.

   • 纯 ESM：package.json 必须 "type": "module"；tsc 用 module:esnext + moduleResolution:bundler 保留 bare specifier。

6. dsh plugin add <dir> anchors relative paths to the INVOKING directory — run it from the parent directory, not from inside the plugin.

   • dsh plugin add 的相对路径锚定调用目录——要在插件的父目录执行。

7. In the bundle cordis.patch.yml, name is a package name (resolved via node_modules / $DSH_HOME/profiles/node_modules), not a relative path.

   • bundle 的 cordis.patch.yml 里 name 用包名（走 node_modules 解析），不要用相对路径。

8. Registrations are effects: ctx.tools.register() / ctx.on() auto-dispose on unload. Wrap your OWN resources (timers/connections) in ctx.effect(() => { acquire; return cleanup }).

   • 注册是 effect：ctx.tools.register()/ctx.on() 卸载自动清理；自己的资源（timer/连接）要包 ctx.effect(() => {…; return cleanup})。

9. Load order = service dependencies, never file order: export const inject = ['tools'] makes the plugin wait until ctx.tools is ready.

   • 加载顺序靠服务依赖（inject），不靠文件顺序。

10. Full end-to-end (model actually calls your tool) needs DEEPSEEK_API_KEY; without it --verify proves load/list/event, and the model call fails with MISSING_CREDENTIAL.

• 端到端（模型真正调工具）需 DEEPSEEK_API_KEY；无 key 时 --verify 只能证明加载/列出/事件，模型调用会 MISSING_CREDENTIAL。