dsh-plugin-check

一句话定位

给 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 plugin --profile web add github:omdsh-dev/dsh-plugin-check

配置项

工具通过 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）

English

DSH 插件健康检查工具 —— 扫描插件仓库，诊断清单协议 / patch 格式 / 构建陷阱 / hub 收录状态，输出合规报告与修复建议。只读，不修改、不构建被检查仓库。

动机

组织内插件仓库持续增长，作者踩过的坑（cordis 双副本、tsconfig 三件套、patch name 不一致、产物 .ts 残留——运行时必崩）本可以自动化拦截。本工具把全部实测踩坑变成可自动检查的门禁：模型或 CI 直接对仓库目录跑一次 plugin_check，拿合规报告与修复建议。

安全模型

• 只读：仅 readdir/stat/readFile，绝不修改或构建被检查仓库
• 零业务依赖：仅 node 内置模块（fs/path/child_process）
• hub 检查离线优先：先读本地 hub catalog（DSH_HUB_SOURCE 或 cwd/hub/ 下），再通过 gh 读取公开 omdsh-dev/dsh-hub-workshop/catalog.json；兼容 dsh-hub-index/v0.4 与旧 repos[].name；全部失败静默降级 skipped（报告如实标注，不算警告）
• 不执行 tsc：构建陷阱全部静态文本扫描（快、无副作用）

工具声明

注册 plugin_check 工具（@deepseek-ai/dsh-plugin-check，row id tool-plugin-check），统一输出 JSON 文本。

Actions

形态识别与检测项（按形态适用，33 项）

生态合规四项（immediate-adjustments-bundle-profile-plan §4.5）：

• core-row-id：patch 条目使用官方核心 row（tools/session/llm/web/permission）；
• missing-profile-install-example：README 缺 dsh plugin --profile ... add 示例；
• manual-install-only：无法通过标准 Profile Bundle 安装（无 patch 或 README 无示例）；
• core-modification-required：默认安装流程要求修改 DSH 核心（git apply / cp 进 monorepo；明确标注"手动安装与旧版本兼容"的段落不计入）。

命名策略：invalid-name-format 仅表示 npm 格式错误；合法的个人 scoped/unscoped 名称只产生 non-org-recommended-name（warning），不会 fail。推荐范围为 @deepseek-ai/*、@dsh-external/*、@omdsh/* 和 dsh-*。

verdict：0 error → pass；有 error → fail；仅 warning → warn。 kind：registry / skill / collection / tool-bundle / bundle / infra / unknown——按形态套用不同检查集（X-01 共享矩阵）。 checks：固定检查项的执行结果（total/passed/failed/warned/skipped），不再是 issue 数。

示例

plugin_check { action: "check", path: "C:/Users/admin/Desktop/dshext/dsh-tool-csv" }
  → {"repo":"dsh-tool-csv","kind":"tool-bundle","verdict":"pass","checks":{"total":24,"passed":24,...}}

plugin_check { action: "scan", path: "C:/Users/admin/Desktop/dshext" }
  → {"root":"...","scanned":11,"reports":[...]}   # dsh-my-rsi 等不合规仓库会带 error+suggestions

npm 0.1.0-rc.8 兼容（已验证）

本插件已迁移到 npm 0.1.0-rc.8 依赖线，并在 @deepseek-ai/[email protected] 的隔离 consumer 中完成全链路验证：

• 类型/运行时：@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）；不再依赖 unscoped cordis
• 独立构建：npm install（devDependencies 自包含 typescript/vitest/@types/node）→ npm run typecheck → npm test → npm run build → npm pack
• 消费验证：tarball 装入 0.1.0-rc.8 consumer → dsh --profile compat --dump-config 出现本插件 row → 工具真实注册与执行通过
• 启动方式：npx -p @deepseek-ai/[email protected] dsh web（lib 生产模式；勿 install -g 全局安装）

安装

Profile Bundle（推荐）

仓库位于 omdsh-dev/dsh-plugin-check（public）。将本插件作为独立 bundle 安装到 profile（DSH 0.1.0-rc.8（npm））：

# 交互式（web）profile
dsh plugin --profile web add github:omdsh-dev/dsh-plugin-check
# 一次性任务（headless）profile —— dsh run 默认使用 headless
dsh plugin --profile headless add github:omdsh-dev/dsh-plugin-check

包内 dsh.bundle.patch 会在安装后自动把插件加入 profile 的 layer stack（row id：tool-plugin-check）。插件缺失的 peer 依赖（cordis、@deepseek-ai/dsh-tools）由 profile 的 healed profiles/node_modules 回退安装提供。

⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。Windows 路径使用正斜杠（C:/...）。

npm pack tarball 安装

本地构建后用 tarball 路径安装（不依赖 GitHub）：

# tarball 方式（web 为例；headless 同）
npm pack
dsh plugin --profile web add <npm pack 产物 tarball 路径>

验证安装

dsh --profile web --dump-config | grep tool-plugin-check

运行验证

dsh run "使用 plugin_check 工具检查一个插件仓库"

手动安装与旧版本兼容

旧场景（monorepo 集成、不支持 Profile Bundle 的旧快照或插件开发调试环境——本地 junction/symlink、手动编辑 profile 层）。

测试

node <monorepo>/node_modules/vitest/vitest.mjs run tests   # 38 用例

• manifest.spec.ts / patch.spec.ts / build-check.spec.ts：每项检测的命中与不误报（fixtures 临时目录生成）
• report.spec.ts：verdict 判定（含 strict 升级）、suggestions 模板、hub-skipped 不升级
• register.spec.ts：注册契约（AUDIT-CROSS-02 风格）

自检基线（2026-08-08 实测）

组织内 8 个插件（time/encoding/json/calculator/csv/regex/markdown/session-health）全部 pass、零 error、零 warning。检查过程发现并修复了 4 个旧插件的真实合规缺陷（tsconfig 缺三件套——重建会产生坏产物；缺 build/prepack scripts）。

许可

MIT