Skip to content
dsh marketplace

dsh-plugin-guardian

Verified

@chenlipingjian-alt/dsh-plugin-guardian · v0.1.0 · Apache-2.0

Searches community DSH plugins, audits each pinned commit against a fixed security checklist, installs only approved candidates, and verifies the result with evidence, for DeepSeek Harness.

Install

dsh plugin add @chenlipingjian-alt/dsh-plugin-guardian

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

Plugin Guardian

简体中文 | English

License DSH

一句话：给 DSH 装上"插件采购员 + 安检员"——按需求搜候选、对固定 commit 逐项排雷、只在批准后安装、装完逐项核验，每一步都给出可核对的证据。

功能

  • 搜索有边界：只在 GitHub topic:dsh-plugin 内按关键词搜索，一次最多 3 个候选；命中总数多于返回数时明确标注 truncated: true，绝不把切片当成全集。每个候选带 repo 全名、描述、stars、最后 push、默认分支、HEAD commit SHA 与来源 URL。
  • 排查有清单：对锁定 commit 执行固定的十项检查——来源与可疑抢注、许可证、维护状态、依赖漏洞（OSV 实时查询）、安装期脚本（逐字原文引用）、权限与能力（shell/eval/文件写入/凭证读取）、数据外传域名、代码混淆与二进制、commit 可固定性、DSH 引擎与 bundle 兼容性。每项都给出 文件:行号 或 API URL。
  • 判定有闸门：结论为「推荐 / 谨慎 / 拒绝」。出现凭证读取、可疑外传、混淆代码、提权等红线直接判「拒绝」，此后任何安装调用都会被拒绝。
  • 安装有授权：先输出安装预览（候选、commit、审计摘要、命令、预计变更）并发放一次性令牌；真正安装必须同时提供该令牌、同一个 auditId 与同一个 commit SHA。工具永不批准安装期脚本，需要构建脚本的包会失败并保持失败，不重试、不提权、不绕过。
  • 校核有证据：装完检查六项——依赖完整性、来源与审计 commit 是否一致、配置层是否挂载、插件是否真正激活、可选的功能冒烟、实际权限是否超出声明。任一项失败即 ok: false，并给出失败证据。

安装

环境要求：DeepSeek Harness 版本满足 0.2.1-rc.3。本插件为 host-only bundle，可在任意 profile 中使用（已在 desktop 验证）。

从 GitHub 安装

固定到某个 Release tag：

dsh plugin --profile desktop add github:local/dsh-plugin-guardian#v0.1.0

安装后重启 DSH（桌面版请重启应用），刷新页面。命令会装到你平时使用的 DSH；如果你设置了自己的 DSH_HOME，请在同一个环境中运行。

本地目录安装

dsh plugin --profile desktop add /绝对路径/dsh-plugin-guardian

从源码安装用于开发调试，见 docs/development.md。

使用

四个工具构成一条链路，按顺序调用即可；也可以只调用其中一步。

  1. 用一句话说明需求，例如"我想要一个能在会话里显示插件市场的插件"。
  2. Agent 调用 guardian_search，得到不超过 3 个候选（带 HEAD SHA）。
  3. Agent 对候选调用 guardian_audit，得到十项清单、auditId 与锁定的 installSpec。
    • 结论「拒绝」→ 到此为止，只报告失败项与证据。
  4. 决定安装时，Agent 先用 guardian_install 的 dryRun: true 拿到预览与令牌，把候选、commit、审计摘要、命令、预计变更展示给你。
  5. 你明确批准后，Agent 才用同一个 auditId、同一个 commit SHA 和该令牌执行安装。
  6. Agent 调用 guardian_verify 逐项校核；提供 smokeTool 时可再做一次功能冒烟（请给临时数据）。

配置

键 默认值 说明
enabled true 启用插件。
githubToken "" 可选 GitHub token；留空则读取环境变量 GITHUB_TOKEN。
maxCandidates 3 单次搜索返回的候选上限，规范上限为 3。
downloadTimeoutSeconds 120 固定 commit 归档的下载期限；超时即标 download_truncated + audit_incomplete，不给通过结论。
installSource github 审计时假定的安装来源：github（源码直装）或 npm（发布包）。决定 prepare 是否算安装期脚本。

归档下载器尊重 HTTPS_PROXY / HTTP_PROXY（含 https_proxy / http_proxy 小写形式，支持 user:pass@），因为 Node 的全局 fetch 不读这些变量；GitHub API 与 OSV 仍走 fetch。

配置保存在 profile 的 cordis.patch.yml（bundle 默认值在安装包的 cordis.patch.yml 中）。githubToken 以明文保存在该文件里；未认证时 GitHub 每小时仅 60 次 API 调用，搜索 3 个候选约用 4 次。

审计与安装记录写入 $DSH_HOME/guardian/ledger.json（默认 ~/.dsh/guardian/ledger.json），用于把审批令牌绑定到"某个 commit + 某次判定"。

更新、回滚与卸载

版本变更与升级说明见 更新日志。

更新或回滚时请写明版本号，然后重启 DSH（新版本发布后 24 小时内，不带版本号的安装命令可能仍会装到旧版本）：

dsh plugin --profile desktop add github:local/dsh-plugin-guardian#vX.Y.Z

卸载：

dsh plugin --profile desktop remove @chenlipingjian-alt/dsh-plugin-guardian

卸载后不留下任何运行时数据；如需清除审计记录，可手动删除 ~/.dsh/guardian/ledger.json。

隐私与数据

  • 本插件不出站任何遥测。联网目的地只有：api.github.com（搜索、仓库元数据、tags）、codeload.github.com（下载锁定 commit 的归档用于内存扫描）、api.osv.dev（依赖漏洞查询）。
  • 审计时归档只解压到内存，不落盘、不执行；代码只做文本匹配。
  • 不读取 ~/.ssh、~/.aws、.npmrc、id_rsa 等凭证文件，也不读取任何密钥型环境变量（只有可选的 GITHUB_TOKEN 用于提高 API 配额）。
  • 本地写入只有 $DSH_HOME/guardian/ledger.json。

兼容性

见 docs/compatibility.md。已知限制：dsh --profile desktop --dump-config 因 profile 由 Electron 应用独占管理而不可用，校核改用运行中的 plugin manager 视图，并在报告中注明。

开发

见 docs/development.md 与 CONTRIBUTING.md。使用 AI agent 开发、发布或维护时，让它先读 AGENTS.md。

pnpm install
pnpm verify   # typecheck + build + tests + package check

许可证

Apache License 2.0