前言¶
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
