dsh-plugin-inspector：在插件详情页直接查看声明式配置与代码

前言¶

DSH 的理念是「一切皆插件」，插件通过 profile 里的 cordis.patch.yml 打进 UI，再由 Host 加载 package.json 里的声明。问题是：想知道某个插件究竟声明了什么、装了哪些文件，只能回到命令行翻 profile 目录和 node_modules，UI 上没有入口。对于排查「这个插件为什么会改变某棵树」这类问题，这是个高频的排查起点。

dsh-plugin-inspector（包名 @liuweibing7/dsh-plugin-inspector，版本 1.0.0，MIT，作者 liuweibing7）把这件事收进了插件详情页：维护者的工具分类是客户端，浏览器端在插件页内新增一个 inspector 区，把声明用的 YAML 原文和实际安装的代码文件分两个标签页列出来。目前 GitHub 星标为 0，属于很新的小工具。

这个插件是什么¶

一句话定位：一个 DSH 客户端插件，在 http:// Web GUI 的插件详情页上加一个 inspector 区，展示目标插件由哪些 YAML patch 条目声明、背后安装了哪些代码文件。它解决的是「插件声明与实际文件对不上」的排查问题，让你不用离开界面去读 profile 和包目录。

它不是插件管理器，也不做安装、启用或卸载。它只读、只展示。

核心功能¶

下面两节按 README 里的描述整理，分「声明」与「代码」两块。

Declaration 标签页：插件是怎么声明的¶

读取当前 profile 的 cordis.patch.yml 和插件 bundle 自带的 cordis.patch.yml，定位声明该插件的精确 YAML list-item。
每一段展示来源文件路径、具体文本、对应条目，并提供整份文件的查看。
页面打开即加载声明，不需要切标签。

Code 标签页：插件装了哪些文件¶

列出插件安装出来的文件：package.json、Host 入口、浏览器 bundle、随包发布的 src/ 源码、README 和类型入口。
YAML、JSON、JS/TS、Markdown 均有语法高亮。
Markdown 默认渲染，并提供 rendered/raw 切换。
该标签页只在你首次打开时才发起加载，不是默认拉取。

浏览器端不能直接读文件，所有文本都来自 Host 侧接口，这是后文「工作流程」要展开的地方。

安装与启用¶

先说明前提：这个能力要求 DSH Web GUI 跑在 http:// 下，file:// 外壳里该区块不可用；并且目标插件必须有对应页面（bundle 页、行配置页或官方插件页），否则 inspector 无从挂载。

远端安装（来自 README）：

dsh plugin --profile <profile> add github:liuweibing7/dsh-plugin-inspector

本地 checkout 安装：

dsh plugin --profile <profile> add /path/to/dsh-plugin-inspector

装完根据宿主情况重启或刷新 Web UI。插件本身注册一个详情页区块（slot plugins.detail.section，id plugin-inspector）和一个 Host 路由（/plugin-inspector），不改动其他 UI。

典型用法¶

安装完成后，在 Plugins 界面打开任意插件详情页，滚动到 inspector 区即可。README 给出的 screenshots 展示了三个时点：插件详情页中的 inspector 区、Declaration 标签页（yaml 原文与文件路径并列）、Code 标签页（语法高亮与 rendered/raw 切换）。

如果你要排查某个插件为什么生效，操作路径是：打开它的详情页 → 先看 Declaration，确认是哪条 patch 条目把它接进来的 → 再切到 Code，看实际入口和 bundle 与声明是否一致。类比手工排查时在 profile 目录里 grep YAML、在 node_modules 里翻 package.json，这两步就是 inspector 的替代。

工作流程¶

README 描述了两端各自的职责：

Host 半（index.js、blocks.js）注册同源 POST /plugin-inspector 路由，读取当前 profile 的 patch 文件和已安装的包文件，返回 JSON，不做任何写入。blocks.js 负责精确提取 YAML list-item。
浏览器半（client.js）注册 plugins.detail.section 并渲染两个标签页，所有文本来自 Host 路由。
路由拒绝跨域请求，也不设置 CORS 头；服务由 Host 的 loopback Web 服务器提供。
声明与代码的载荷在页面内按目标缓存，上限 10 个目标；Code 标签首次打开才请求。

权限范围与安全注意¶

这部分直接关系到能不能放心在生产环境使用，README 有明确声明：

这是本地排查工具。它会读当前 profile 的 cordis.patch.yml / cordis.yml / patch overlays，以及你打开的插件包的 package.json 和已安装文件。
它不写文件、不向网络发送任何内容、不执行插件代码。
渲染 Markdown 时输出的是转义后的 HTML：README 里的裸 HTML 按文本显示，javascript: 链接不会被渲染成可点的链接，链接一律在新标签页打开。
受限于 dsh 进程本身的权限，它能读到的就是你启动 DSH 时能看到的文件。安装前如需严格审计，仍应自行检查插件源码与许可证（本包为 MIT），而不是默认信任。

边界与已知限制¶

大多数包只发布构建后的 lib/*.js，TypeScript 源码只在包发布 src/ 时可见（例如 @deepseek-ai/cordis）。
单文件截断到 256 KiB，整体响应上限 1.6 MiB，最多返回 16 个文件；高亮只覆盖单段的前 120 KiB。
Markdown 渲染覆盖标题、段落、列表、引用、围栏/行内代码、链接、强调、分隔线和简单表格；嵌套列表会被拍平，图片转成链接，裸 HTML 被转义。
file:// 运行时不可用。

开发形态¶

无构建步骤。包是纯 ESM 加一个手写浏览器 bundle，由 window.__ModuleLoader__ 加载。关键文件划分如下：

package.json         dsh.bundle.patch + dsh.client + exports
cordis.patch.yml     插入 plugin-inspector 行
index.js             Host 半：路由 + profile/patch/package 读取
blocks.js            精确 YAML list-item 提取
client.js            浏览器半：插槽、标签页、高亮、Markdown
locale/*.json        展示元数据（标题/描述）
icon.svg             插件图标

package.json 中 dsh.client 声明 platform: web、immediately: true，注入 @deepseek-ai/dsh-client-locale；dsh.bundle.patch 指向 ./cordis.patch.yml。

结尾¶

dsh-plugin-inspector 把插件「声明了什么、装了哪些文件」这两件事搬到详情页里，省掉了翻 profile 和 node_modules 的往返。它只读不写、不联网、不执行代码，属于排查阶段的辅助工具，而不是插件管理方案。

目录页：https://www.skillhub.cn/plugins/liuweibing7/dsh-plugin-inspector

GitHub：https://github.com/liuweibing7/dsh-plugin-inspector

需要说明的是，社区插件目录是独立站点，与 DeepSeek / 幻方无官方从属关系。