xingzhen199186/dsh-insight-tree

DSH Insight Tree

English README

DSH Insight Tree 是一个面向 DeepSeek Harness（DSH）的运行可观测、故障诊断与插件运维插件。
它把 Profile 配置、实际安装包、Loader 运行状态、会话活动和上游版本信息合并成一份可解释的报告，
再通过插件树、当前会话活动和独立诊断页帮助用户完成“发现问题 → 判断影响 → 采取处理”的闭环。

除了查看状态，它还可以处理当前 Profile 中已安装的非核心插件：在 DSH 内暂时关闭、重新启用（重载）、更新或卸载插件；
如果配置变更或更新需要重启 DSH 才能完全生效，界面会明确提示。即使 DSH 本体没有运行，用户也可以通过命令行单独启动
独立诊断页面，读取 Profile、检查插件状态，并执行可用的关闭、重新启用和卸载操作；当启动包装命令确认启动失败与非核心插件有关时，
该页面还会自动打开。

它不是插件市场，也不是第三方插件安全审计器。它回答的是：

- 当前 Profile 安装了什么、装配了什么？
- 插件是否真的被 Loader 加载，当前处于什么阶段？
- 当前插件与 DSH 本体及配套包是否兼容？
- 本轮会话实际使用了哪些插件能力？
- 当前已安装插件是否需要关闭、重新启用（重载）、更新或卸载？
- DSH 尚未运行时，能否独立检查并处理插件配置？
- 启动失败时，问题是否能归因到某个非核心插件？

当前版本：0.1.2。仓库已公开到 GitHub；npm 上的已发布版本见
。

包形态

这是一个单 npm 包，包含四个使用面：

- Host 入口：lib/index.js，负责报告生成、路由、Loader/Session 接入和操作接口；
- Client bundle：lib/client.js，由 DSH Web 注入导航栏插件树和本轮活动界面；
- 独立诊断命令：dsh-insight-tree-diagnose，对应 bin/diagnose.mjs；
- 失败包装命令：dsh-insight-tree-web，对应 bin/web-with-diagnostics.mjs；
- DSH 装配声明：cordis.patch.yml，把插件接入 DSH 的 bundle/Loader 链路。

运行时依赖包括 js-yaml、semver 和 zod；Loader、Session Projection、Session Query 等
DSH 组件以 peer dependency 接入，缺少可选组件时插件会降级而不是直接崩溃。

安装

从 npm 安装到 DSH

在 PowerShell 中执行：

dsh plugin --profile web add dsh-insight-tree

安装完成后重启 DSH Web，使 host、client bundle 和 cordis.patch.yml 装配生效：

schtasks /run /tn DSHWebRestart

也可以用以下命令确认插件已经写入 web Profile：

dsh --profile web --dump-config

启动 DSH 后，在“设置 → 插件 → 插件树”打开面板；对话页右侧的“本轮活动”入口只在 DSH 内显示。

如果 pnpm 的 supply-chain 策略拦截了刚发布的依赖，只对本次安装命令临时放宽：

dsh plugin --profile web add dsh-insight-tree --config.minimum-release-age=0

本地开发安装

从源码目录 link 安装：

dsh plugin --profile web add I:\DSH\dsh-insight-tree

修改源码并重新构建后，需要重启 DSH Web 才会加载新的 lib/。

独立诊断页面

独立诊断命令随 npm 包安装，可在 DSH 运行或未运行时单独启动：

dsh-insight-tree-diagnose --profile web --port 3092

然后访问 http://127.0.0.1:3092/。如果尚未全局可用，也可以直接执行包内脚本：

node node_modules\dsh-insight-tree\bin\diagnose.mjs --profile web --port 3092

正常启动 DSH 不会自动打开独立页面；只有启动失败且报告明确归因到非核心插件时，包装命令才会自动打开诊断页。

设计思路

插件的核心不是某一个页面，而是一条“证据汇总”链路：

Profile / package.json / node_modules / cordis.patch.yml
|
v
DSH Loader / Fiber 状态
|
v
Session Projection / Query
|
v
InsightTreeReport
/      |      \
v       v       v
插件树  本轮活动  独立诊断

报告模型位于 src/model.ts，当前 schema 为 v3。所有界面都消费这份报告，避免运行中页面、
独立诊断页和导出结果各自维护一套不一致的判断逻辑。

六个观察维度

1. 安装：Profile 的 package.json、实际 node_modules 和包元数据。
2. 装配：dsh.profile.bundles 与 cordis.patch.yml 中的 Loader 装配关系。
3. 加载：ctx.loader 暴露的真实条目，以及对应的 Fiber 阶段。
4. 兼容：DSH 本体版本、配套 DSH 包版本和 npm 发布版本的 semver 判断。
5. 使用：当前会话的 session/event、持久投影和历史会话查询。
6. 上游：插件目录、npm packument 和 GitHub 元数据；网络不可用时使用缓存或明确标注离线。

判断时遵循几个原则：

- 运行时 Loader 证据优先于静态声明；
- 实际安装版本优先于 Profile spec，配置中的 dshVersion 只作 fallback；
- 明确的工具 owner 优先，无法确认时标记为未确认，不伪装成精确归属；
- 独立诊断没有 Loader 运行证据，因此不会虚构“当前正在运行”的状态；
- 缺少必要上下文时显示“暂时无法确认”，不把未知误报为“不适配”。

版本与兼容性语义

页面中的“当前插件”“最新插件”“最新兼容插件”都指插件自身版本，不是 DSH 本体版本。
例如：

当前插件 2.10.3　npm: dsh-pocket　已是最新兼容版本

DSH 本体会单独显示，例如：

适配当前 DSH 本体 @deepseek-ai/dsh@0.1.2-rc.1

兼容性按依赖类型分别判断：

- @deepseek-ai/dsh 或 engines.dsh：比较当前实际安装的 DSH 本体版本；
- @deepseek-ai/dsh-：比较当前 Profile 中实际安装的对应配套包版本；
- 缺少配套包上下文或范围无法解析：显示 unknown，并说明暂时无法确认。

因此，安装另一个 DSH 本体版本后，报告会重新计算适配状态；同一个插件版本可能在不同 DSH
本体或不同配套包组合下得到不同结论。

用户界面与运行边界

DSH 内部

正常打开 DSH 时不会自动打开独立诊断页面。用户可以在 DSH 内打开：

- 插件树：导航栏右侧的结构、能力、依赖、兼容性和 Loader 状态；
- 本轮活动：当前对话中实际出现的插件活动，只绑定当前 session。

独立诊断页

独立页面是一个不依赖完整 DSH Web UI 的静态诊断入口。它可以在 DSH 正在运行或完全未运行时
单独启动，读取 Profile、包元数据和 patch 文件，并提供报告、导出和受保护的配置操作。

手动启动：

node bin/diagnose.mjs --profile web --port 3092

启动后访问 http://127.0.0.1:3092/。也可以使用已安装的命令：

dsh-insight-tree-diagnose --profile web --port 3092

DSH 启动失败时，推荐使用包装命令：

dsh-insight-tree-web --profile web

包装命令会转发 dsh web 的输出，并且只有在错误能够被报告明确归因到非核心插件时，才自动启动
并打开独立诊断页。核心 DSH 本体启动失败不会误弹插件诊断页，只输出手动诊断命令。

安全边界

- HTTP 服务只监听 loopback；
- 可通过 --token 或插件配置启用请求令牌；
- 导出前会脱敏，支持 JSON、Markdown 和 CSV；
- 禁用、启用和卸载前会备份 Profile 文件，并对 YAML 做 round-trip 校验；
- 修改前执行静态配置 dry-run，失败时保留原文件并返回恢复信息；
- 核心 @deepseek-ai/ 包和当前诊断插件拒绝操作；
- 卸载有被依赖插件时会拒绝执行；
- 诊断页不加载完整插件树，也不将静态声明冒充为运行时事实。

主要源码

| 文件 | 职责 |
| --- | --- |
| src/index.ts | 插件入口、事件统计、投影注册、Loader 快照和路由装配 |
| src/model.ts | InsightTreeReport 及插件、兼容性、Finding、Activity 类型 |
| src/discovery.ts | Profile、包元数据、patch、依赖和报告生成 |
| src/loader.ts | Loader 条目到 Fiber 阶段的纯函数映射 |
| src/activity.ts | session projection 活动折叠和历史回放辅助 |
| src/owners.ts | 工具到插件的显式/稳定归属映射 |
| src/upstream.ts | 插件目录、npm/GitHub 元数据和版本兼容判定 |
| src/rules.ts | 缺包、重复装配、兼容性和启动影响规则 |
| src/route.ts | /dsh-insight-tree 报告、会话、导出、对比和操作 API |
| src/diagnostics.ts | 判断启动错误是否确实与非核心插件相关 |
| src/client/index.tsx | DSH 内的插件树和本轮活动 UI |
| bin/diagnose.mjs | 独立诊断 HTTP 服务 |
| bin/web-with-diagnostics.mjs | dsh web 包装启动器和失败诊断入口 |
| tests/.test.mjs | 报告、Loader、活动、路由、导出、版本和诊断回归测试 |

开发与验证

Node 要求：^22.19.0 或 >=24.0.0。在 Windows 上请使用 PowerShell 中的 Node 22/24，
不要使用 Git Bash 自带的 Node 18。

npm install --legacy-peer-deps --no-audit --no-fund
npm run typecheck
npm run build
npm test
node --check bin/diagnose.mjs
node --check bin/web-with-diagnostics.mjs
git diff --check

npm test 会先构建，再运行 tests/.test.mjs。最近一次完整验证为 63/63 通过，另有
typecheck、两个诊断脚本语法检查和 git diff --check 通过。
代码变更后，运行中的 DSH Web 需要重启才会加载新的 lib/；本机可使用：

schtasks /run /tn DSHWebRestart

当前限制

- Loader、session projection 和 session query 的真实可用性取决于 DSH 主机是否提供对应服务；
缺失时插件会降级并标注来源。
- 工具事件没有显式 owner 时，只能使用稳定映射或标记为未确认，不能保证精确归因。
- 单元测试不能替代真实 DSH Web 主机上的路由、SSE 回放和视觉验证。
- 上游目录、npm 和 GitHub 信息依赖网络；离线时使用缓存，缓存不可用则明确显示离线状态。