Skip to main content

dsh-plugin-check

27Stars2Forks1Issues0Watchers

Plugin health checks: manifest protocol / patch format / build traps, zero-dependency and read-only.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
main
diagnosticsdshdsh-pluginlintingplugin-health

Install

cmdweb profile
$ dsh plugin --profile web add github:omdsh-dev/dsh-plugin-check

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin omdsh-dev/dsh-plugin-check for me: review the repository at https://github.com/omdsh-dev/dsh-plugin-check first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

一句话定位

给 DSH 插件仓库做体检:按插件形态分流检查清单协议、patch 格式、构建陷阱和 hub 收录状态,输出合规报告与修复建议,适合在 CI 或模型门禁中用作自动拦截。

核心能力

  • 识别仓库形态:registry(dsh.plugin.json)/ skill(SKILL.md)/ collection(catalog.json)/ bundle / tool-bundle / infra / unknown,并按形态套用不同检查集
  • 检查清单协议:package.json 的 name / main / types / files / peerDependencies / dsh.bundle.patch 声明是否完整且路径合规
  • 检查 cordis.patch.yml 格式:insert / update / disable section 解析、行内注释剥离、row id 唯一性、tool-bundle 名称一致性
  • 检查构建陷阱:tsconfig 三件套(allowImportingTsExtensions / rewriteRelativeImportExtensions / outDir 布局)、lib 产物 .ts 残留、build/prepack 脚本缺失
  • 检查 hub 收录状态:离线优先读本地 catalog(DSH_HUB_SOURCE),失败通过 gh 拉取公开仓库,失败时静默降级为 skipped
  • 检查 Profile Bundle 安装边界:README 是否给出标准 dsh plugin --profile ... add 示例、是否要求修改 DSH 核心(git apply / cp 到 monorepo)

技术实现

  • 语言: TypeScript
  • 关键依赖: @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools 0.0.1-rc.1–0.2.0、@deepseek-ai/dsh-invariants 0.0.1-rc.1–0.2.0(皆 peer;本地执行仅依赖 node:fs/path/child_process)
  • 架构模式: 通过 cordis.patch.yml 注入宿主 tools 服务,注册一个名为 plugin_check 的工具(row id tool-plugin-check),由工具参数 action 路由到 checkRepo / scanDir / CHECK_SCHEMA 输出
  • 入口文件: src/index.ts(含 apply 注册 defineTool 与顶层 runAction 路由)

适用场景

插件作者提交前自检、CI 流水线对一批插件仓库做合并门禁、模型辅助评审时先跑一次拿结构化报告、hub 维护者批量摸底未收录仓库。当你手头要 review 的仓库不止一个、或希望把"踩过的坑"沉淀为可重复执行的检查时,这个工具最合适。

前置依赖与兼容性

依赖最低版本说明
DSH(cordis)^4.0.1peerDependencies 声明,宿主提供
@deepseek-ai/dsh-tools>=0.0.1-rc.1 <0.2.0peerDependencies 声明,提供 defineTool
@deepseek-ai/dsh-invariants>=0.0.1-rc.1 <0.2.0peerDependencies 声明,配套 invariant companion
Node.js^22.19.0
平台macOS / Windows / Linux跨平台,Windows 路径需用正斜杠

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-plugin-check

配置项

配置类型说明默认值
actionstring(必填)操作类型:check(检查单个仓库)/ scan(扫描父目录下所有 dsh-* 仓库)/ schema(输出全部检查项及形态适用矩阵)无
pathstring被检查的仓库目录(check)或父目录(scan);不填则使用当前工作目录当前工作目录
strictboolean严格模式:所有 warning 升级为 error 并影响 verdictfalse

工具通过 cordis.patch.yml 自动注册到 profile,无需在 README 之外额外配置;环境变量 DSH_HUB_SOURCE 可指向本地 hub catalog 路径以离线优先查询。

常见问题

Q: 这个插件会修改被检查的仓库吗?

A: 不会。安全模型为只读,只用 readdir / stat / readFile 等只读系统调用;构建陷阱全部通过静态文本扫描识别,不会执行 tsc,也不会触发被检查仓库的构建脚本。

Q: 它和 tsc --noEmit 这种类型检查有什么区别?

A: 本工具不检查类型正确性,重点是清单协议、patch 文件格式、产物布局和构建配置等"作者容易踩坑但 tsc 不会报错"的问题,例如 tsconfig 缺 rewriteRelativeImportExtensions 会导致产物残留 .ts 相对导入,运行时 ESM 必崩——这类问题 tsc 检测不到。

Q: strict: true 在 CI 里怎么用合理?

A: 默认 verdict 由 error 数量决定(0 → pass;仅 warning → warn;有 error → fail)。CI 合并门禁通常设 strict: true 把 warning 也当作 fail 处理,避免"全 warning 仍 pass"放过低质提交;本地自检可以保持 strict: false 只看致命问题。

Q: hub 检查失败时会怎样?

A: 优先读 DSH_HUB_SOURCE 环境变量或本地 hub/catalog.source.json;失败再通过 gh api 拉公开 catalog;全部失败时记为 hub-skipped(info 级),不会升级为 warning,因此离线/CI 沙箱不会因网络问题误报。

Q: 支持哪些仓库形态?

A: registry(dsh.plugin.json 协议)/ skill(SKILL.md)/ collection(catalog.json)/ bundle(cordis 插件包)/ tool-bundle(TypeScript + dsh-tools)/ infra(多包基础设施)/ unknown。unknown 和 infra 会明确标记 unsupported-kind,不会强行判 fail。

Q: 扫描父目录时会上限多少个仓库?

A: scan action 在父目录下最多检查 50 个 dsh-* 命名的子目录(每个必须是目录、非符号链接、且含 package.json / dsh.plugin.json / SKILL.md / catalog.json 或 skills/*/SKILL.md 之一),超出后停止追加,避免大目录拖垮检查。

上手难度

入门 — 只通过一个工具的三个 action 调用即可跑完整流程,无需修改被检查仓库本身。

已知问题与限制

  • scan action 一次最多处理 50 个仓库(src/index.ts:193 硬编码 MAX_REPOS = 50),超出后停止追加报告,超大目录需自行分批
  • src 文本扫描有 4MB / 400 文件的资源预算(src/paths.ts:94),超过会记 scan-truncated 并跳过剩余检查,超大源码仓库可能不完整
  • hub 收录检查依赖 gh 命令或本地 catalog,两者都不可用时不会报错而是降级为 skipped(README.md:17、src/hub.ts:208-215),需要离线评估时务必配置 DSH_HUB_SOURCE
  • 仓库命名推荐范围为 @deepseek-ai/*、@dsh-external/*、@omdsh/*、dsh-*,合法但不在范围内的名字仅触发 warning(non-org-recommended-name),不会 fail(src/manifest.ts:33-35)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-plugin-check)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory