前言¶

在 DSH 里写插件，常见失败点不在业务逻辑，而在 dsh boot 加载阶段的硬校验：dsh.bundle 声明、patch 顶层数组、insert 的 id/name、files 白名单、main/types、入口导出的 name 与 apply 等，任一不符合规范，往往在启动时直接报错，排查成本高。社区里也有人靠反复试跑来对齐规则，效率不高。

@snow-the/dsh-plugin-guide（维护者 snow-The，GitHub：snow-The/dsh-plugin-guide）把上述校验固化成可执行的扫描规则，并提供内置的官方能力地图，便于发布前自检和查阅 ctx.*、排程、agent、bundle 等用法。本文基于仓库 README 与 package.json 介绍其定位、工具与安装方式。

这是什么¶

一句话：DSH 插件写作指南与合规扫描器（DSH plugin authoring guide & conformance scanner）。

• guide_scan：按 boot 硬校验扫描插件目录（含 plugin 与 profile 相关模式）。
• guide_learn：查询 DSH 官方能力地图（overview、bundle、schedule、agent、ctx、official 等主题，或按关键词检索）。

分类为工作流；当前 GitHub 星标为 0。许可证 MIT；package 版本 0.1.7。engines.dsh 要求 >=0.2.1-rc.2 <0.3.0-0，dsh.compatibility 中列有 0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.2，verifiedAgainst 为 0.2.1-rc.2。

核心功能¶

guide_scan：发布前合规扫描¶

对指定插件目录逐条对照 boot 加载器的校验逻辑，覆盖例如：

• dsh.bundle 声明
• patch 顶层数组（避免「只有注释」等无效 patch）
• insert 条目是否具备 id、name
• files 白名单（例如是否包含 dist）
• main、types
• 入口是否导出 name 与 apply

README 说明扫描规则对齐 @deepseek-ai/dsh-app-boot 的 parsePatchList / loadOverlayPatches 校验；缺 dsh.bundle、patch 仅注释、insert 缺 id/name、files 缺 dist 等，均为启动失败的常见原因。

典型调用方式（由 agent 在构建与测试之后执行）：

pnpm build && pnpm test
# 然后让 agent 调用 guide_scan 扫你的插件目录

工具形式为 guide_scan <dir>，具体参数以插件在 DSH 中注册的工具名为准。

guide_learn：官方能力地图¶

guide_learn <topic> 用于查官方能力用法，主题包括：

也可直接搜 ctx.llm、dsh-schedule 等关键词。

内置地图要点（README 摘要）：

• ctx.*：llm、tools、agents、skills、sessions、settings、storage、jobs、goals、workflowEngine、subagents、credentials、fs、userQuestions 等，附来源包、类型与示例说明。
• 排程：dsh-schedule（agent 作用域持久提醒、事件日志溯源）与 cordis-plugin-timer 底层。
• 官方 bundle 层叠：dsh-base（核心）→ dsh-web-app（web 表面）→ 用户 patch，按行 id 后写覆盖先写。
• 官方包目录：12 个领域（LLM、agent、工具、会话持久化、技能、排程、文件沙箱、shell、web 宿主、凭证安全、任务目标、外部集成）。

安装与启用¶

在 web profile 下添加插件（命令来自 README）：

dsh plugin --profile web add @snow-the/dsh-plugin-guide

或手动：在 package.json 的 dependencies 中加入 @snow-the/dsh-plugin-guide，并在 dsh.profile.bundles 中登记同一包名，然后执行 pnpm install 并重启 DSH。

插件通过 cordis.patch.yml 挂载 bundle patch；发布产物在 dist（main 为 ./dist/index.js）。

典型用法小结¶

1. 安装并重启 DSH，确认当前进程 DSH 版本满足 >=0.2.1-rc.2 <0.3.0-0（或与 dsh.compatibility 中列出的 RC 一致）。
2. 开发插件时，本地先 pnpm build && pnpm test。
3. 对目标插件目录调用 guide_scan，根据扫描结果修正 bundle 与入口导出。
4. 不确定 API 或 bundle 写法时，用 guide_learn 查 ctx、schedule、bundle 等主题。

上游仓库自测为 node --test（README 写明 11 个用例：合规好/坏样例与能力查询），可作为扫描与查询行为的参考。

适用场景与注意¶

适合谁：正在编写或维护 DSH 插件、希望在发布前对齐 boot 校验的开发者；需要快速查阅官方 ctx.*、排程、agent、bundle 约定而非翻散文档时。

权限与安全：插件在已安装的 DSH 进程权限下运行，可访问该进程能触达的资源。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，自行评估是否纳入你的工作流 profile。

生态说明：DSH 采用「一切皆插件」的扩展方式；社区插件目录站点（如 SkillHub 目录页）为独立收录，与 DeepSeek / 幻方无官方从属关系。

结尾¶

@snow-the/dsh-plugin-guide 把 boot 阶段的常见踩坑收成可扫描规则，并内置官方能力地图，适合作为插件开发工作流里的自检与查阅环节。更多说明见目录页与仓库 README：

• 目录页：https://www.skillhub.cn/plugins/snow-The/dsh-plugin-guide
• GitHub：https://github.com/snow-The/dsh-plugin-guide