前言¶
DSH 的插件模型强调「一切皆插件」。社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不应理解为官方应用商店。
对 DSH 插件作者、维护者和工具链建设者来说，安装前最关心的问题通常很具体：这个本地插件是否声明了 package.json 和 dsh.bundle.patch？DSH、Cordis、Node 版本范围是否兼容？运行时依赖是否声明？patch 是否会带来重复 id、路径包含问题或未求值的 !!js 表达式？
dsh-plugin-observatory 为这类问题提供一个只读检查点：先做安装前静态审计，再看激活后的有界 Loader 生命周期观察。
这是什么¶
dsh-plugin-observatory 由 CMSKL 维护，许可证为 MIT。当前首个 stable release 是 0.1.0。
它提供两个只读工具：
plugin_audit：检查本地插件包的package.json与声明的dsh.bundle.patch。plugin_observe：投影当前非 group Loader 条目，并展示自该插件激活后观察到的有界 root-Fiber 转换。
它解决的核心问题是：在插件进入 DSH profile 之前，先给出一个确定性、机器可读的兼容性信号；激活后，也保留一个有限的观察入口，而不是让插件状态完全不可见。
核心功能¶
plugin_audit：静态兼容性审计¶
plugin_audit 检查一个本地包的 package.json 和声明的 dsh.bundle.patch。
它覆盖以下检查项：
1、manifest 完整性
2、DSH、Cordis、Node 版本范围
3、运行时依赖声明
4、安装生命周期脚本
5、patch 行
6、重复 id
7、路径包含关系
8、未求值 !!js 表达式
审计结果返回确定性、机器可读报告。结论可以是：
compatibleneeds-reviewincompatible
plugin_audit 只读取 package 元数据和声明的 patch。它不导入目标 JavaScript，也不求值 patch 表达式。因此它适合作为安装前信号，而不是目标插件的完整运行时测试。
plugin_observe：有界 Loader 生命周期观察¶
plugin_observe 投影当前非 group Loader 条目，并展示自该插件激活后观察到的有界 root-Fiber 转换。
它是进程本地的、有界的。用于查看当前过程中的 Loader 状态和保留的转换，不作为 Loader 当前状态的第二个权威来源。
PluginObservatoryService¶
PluginObservatoryService.audit 将同一静态审计暴露给可信插件。
snapshot 返回脱离的即时生命周期报告。
assertObservedTransition 支持 invariant companion。
读取与解析边界¶
package 与 patch 读取为字节有界，要求有效 UTF-8，解析符号链接，并保持在允许列表根下。
解析后的 patch 图也受嵌套深度和对象/数组访问上限约束。循环 YAML 别名会生成 incompatible 报告，而不是进入递归耗尽路径。
报告不带时间戳，并按确定性顺序排序 findings。
安装与启用¶
未指定版本安装只解析到 stable release：
dsh plugin --profile demo add dsh-plugin-observatory
如果要固定到首个 stable release：
dsh plugin --profile demo add dsh-plugin-observatory@0.1.0
安装后可以查看组合配置：
dsh --profile demo --dump-config
如需移除：
dsh plugin --profile demo remove dsh-plugin-observatory
版本策略上，0.1.0 是首个 stable release，并作为 npm latest dist-tag 发布。未来 release candidates 保留在 next。未指定版本安装只解析到 stable release。
典型用法¶
先安装：
dsh plugin --profile demo add dsh-plugin-observatory@0.1.0
然后让模型审计一个本地插件包：
Use plugin_audit on the local package at /path/to/my-plugin. Return the verdict, issues, and inserted bundle entries.
这一步会返回审计结论、问题项，以及插入的 bundle entries。
如果要查看当前运行时中的 Loader 状态：
Use plugin_observe and list the non-group Loader entries and their retained transitions.
检查组合配置：
dsh --profile demo --dump-config
移除插件：
dsh plugin --profile demo remove dsh-plugin-observatory
配置与限制¶
默认配置包含以下项：
allowedRoots：包目录必须解析到允许列表根下。maxManifestBytes：默认262144，最大接受值为32 MiB。maxPatchBytes：默认1048576，最大接受值为32 MiB。maxPatchDepth：默认64，最大接受值为256。maxPatchNodes：默认10000，最大接受值为100000。maxObservedEntries：默认256，保留 Loader entry 历史上限。maxTransitionsPerEntry：默认64，单个 Loader entry 保留的近期转换上限。
这些限制的目标是保持审计和观察过程可预测：读取有边界，解析有深度和节点上限，观察条目和转换也有保留上限。
环境与发布¶
package.json 的 engines 要求：
node ^22.19.0 || >=24.0.0
所需兼容性矩阵在 Node 22.19.0 和 Node 24 上运行 DSH 0.1.0-rc.6。
运行时 DSH 和 Cordis 包是 peer dependencies。开发使用已发布版本，而不是官方 Harness 仓库 workspace links。
从 Git checkout 安装需要 pnpm build authorization，因为 source package 使用 prepare 编译 TypeScript。npm package 和 attached GitHub Release tarball 包含预构建 lib/ 文件。
适用场景与注意¶
适合以下使用者：
- DSH 插件作者
- DSH 插件维护者
- 构建 DSH 工具链的人
- 需要在 profile 安装前检查本地插件声明的开发者
需要注意：
1、plugin_audit 是静态检查，只读取声明的 package 元数据和 patch，不导入目标 JavaScript，也不求值 patch 表达式。
2、plugin_observe 是有界的、进程本地的观察，不是 Loader 当前状态的权威来源。
3、插件以当前 dsh 进程权限运行，安装前应检查源码、依赖和 MIT 许可证。
4、报告确定性地排序 findings，不带时间戳，适合作为可比较的机器可读输出。
结尾¶
dsh-plugin-observatory 把两件事放在同一个 DSH 插件里：安装前给出静态兼容性结论，激活后保留有界的 Loader 生命周期观察。对于需要在 profile 启动前判断插件是否声明正确、又想查看当前非 group Loader 条目的人，这是一个比较直接的入口。
GitHub 仓库：https://github.com/CMSKL/dsh-plugin-observatory
