前言¶
在 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> 用于查官方能力用法，主题包括：
| topic | 用途（据 README） |
|---|---|
overview |
总览 |
bundle |
官方 bundle 层叠与 patch |
schedule |
排程相关 |
agent |
agent 框架 |
ctx |
ctx.* 服务 |
official |
官方包与集成 |
也可直接搜 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）。
典型用法小结¶
- 安装并重启 DSH，确认当前进程 DSH 版本满足
>=0.2.1-rc.2 <0.3.0-0（或与dsh.compatibility中列出的 RC 一致）。 - 开发插件时，本地先
pnpm build && pnpm test。 - 对目标插件目录调用
guide_scan，根据扫描结果修正 bundle 与入口导出。 - 不确定 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
