研究进度树 CrazeBox/dsh-ExploreTree

dsh-ExploreTree — 研究进度树（Research Progress Tree）

仓库地址：

把长期探究过程（科研、调研、迁移分析、写作、代码探索……）可视化成树状图：做了什么、做到哪、哪个分支成功/失败（含原因），跨会话留存，实时跟随 agent 工作进度。

形态：Web 界面侧边栏按钮 + 右侧思维导图式悬浮面板（SVG 树、状态色节点、焦点模式缩放、悬停详情、双击跳转会话），界面预览见 USAGE.md 的「界面操作指南」。

⚠️ Vibe Coding 产物声明

本项目是 vibe coding 的产物：需求由使用者与 AI 助手在对话中逐轮明确（见 REQUIREMENTS.md），代码由 AI 生成并经多轮迭代调试。它：

- ✅ 在本机 DSH 环境（0.1.0-rc.6，web profile）上通过了冒烟测试（host 26 项 / client 18 项）并实际运行验证
- ❌ 未经传统意义上的工程化评审（code review、测试矩阵、安全审计、跨版本兼容性测试）
- ⚠️ 请自行评估使用风险；欢迎 fork 改进；遇到问题欢迎提 issue

这是什么

- 一个 DSH 插件（Cordis 动态插件，Host + Client 双端），注册在 web profile 的 host 层：
- tree_node 工具对所有模式的会话可见（standard / code / minimal / 自定义 preset）
- Web 界面侧边栏底部出现「🌳 研究树」按钮，点击弹出思维导图式悬浮面板
- 一个研究主题一棵树：有 goal 的会话自动建树；无 goal 的会话惰性建树（agent 第一次调用 tree_node 才建）
- 跨会话续接：上下文不够时开新对话，tree_node list → tree_node resume 继续画同一棵树

特性一览

- 思维导图式渲染：SVG 分层布局，横向/竖向可切换（⇄/⇅ 按钮，记忆选择；深链研究用竖向、宽分支用横向）；节点 = 短标题 + 一行说明
- 标题与描述分层：title 是短标签（节点上截断 11 字），desc 是「在这个节点干了什么」（长文本，悬停/点击详情看全文），reason 是结论原因——三件事分开写，标题不再又长又挤
- 状态可视化（结论 = 线的命运）：绿=走通、红=走不通（✕ 角标）、橙=卡住、灰=没走完、蓝脉冲=进行中、浅灰=未开始；实线 = 有结论/进行中，虚线 = 未定局（计划/卡住/没走完/未开始）；角落有图例
- 结论语义：success=走通、failed=走不通（两者对称，都是"这条线有结论"，被否证也是科研产出）、abandoned=没走完、blocked=暂时卡住——这是探索线的结局，不是对"猜想是否成立"的判定；科研内容在 reason 里（如"构造出反例，此路不通"）
- 画布交互（市面思维导图同款）：任意位置拖动平移、滚轮缩放锚定鼠标、焦点模式（点击面板后滚轮直接缩放，不干扰页面）
- 面板自由：拖标题栏移动、四边四角拉伸、位置/尺寸记忆（localStorage）
- 详情：悬停节点看详细说明（说明/结论/原因/时间/产出文件），点击固定；固定卡片可 ✎ 直接编辑标题/描述（保存即写回，乐观更新，无需改 JSON）
- 跳转：双击节点跳转到其所属会话
- 自动骨架：goal 轮次、子代理、工作流自动挂到树上；子代理节点自动补全内容（任务 = 子会话首条消息，结果 = 最终输出截取），不再空壳
- 自动记录员：树更新落后对话活动时，后台自动调 LLM 把新事件补记成树节点（agent 忘了记也不会断更；可配置关闭）
- 自动收尾：分支全部结束后 plan/root 自动结束（不再残留"进行中"），计划自动汇总结论（"子任务完成：2 走通、1 走不通"）；goal 完成/阻塞时整树收尾；子代理配对持久化（重启后 end 事件不丢）；启动时自动修复历史残留状态
- 同会话多树：转换研究主题时开新树（plan-root newTree=true），旧树保留可切回
- 树的生命周期独立：对话归档/删除不影响树；面板里可随时归档/恢复/删除树（归档 = 从列表隐藏、数据保留；删除 = 软删除，文件留备份）
- 树数据持久化到本地 JSON（跨会话、重启不丢；默认存 $DSH_HOME/research-tree/）

安装

详细安装步骤见 USAGE.md（含 Windows / macOS / Linux 的差异）。

前提：已安装 DSH（dsh CLI 可用，web profile 存在），并已准备好 pnpm（方式一）或 Node.js（方式二）。

方式一：官方命令注册（推荐，需要 pnpm）

git clone https://github.com/CrazeBox/dsh-ExploreTree.git
cd dsh-ExploreTree
npm install # 安装 host 依赖（@deepseek-ai 包，版本与 DSH 匹配）
dsh plugin --profile web add file:"$(pwd)" # 注册进 web profile
重启 dsh web 服务，浏览器强刷（Ctrl+F5）

方式二：手动注册（无 pnpm 时）

git clone https://github.com/CrazeBox/dsh-ExploreTree.git
cd dsh-ExploreTree
npm install

然后编辑 $DSH_HOME/profiles/web/package.json：

{
"dependencies": {
"research-tree-plugin": "file:/绝对路径/dsh-ExploreTree" },
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "research-tree-plugin"]
}
}
}
并在 $DSH_HOME/profiles/web/node_modules/ 下把插件目录链接进来：

Windows（管理员或开发者模式）： mklink /J "$env:USERPROFILE\.dsh\profiles\web\node_modules\research-tree-plugin" "D:\绝对路径\dsh-ExploreTree" macOS / Linux： ln -s /绝对路径/dsh-ExploreTree "$HOME/.dsh/profiles/web/node_modules/research-tree-plugin"

重启 dsh web 服务，浏览器强刷。成功后侧边栏底部出现「🌳 研究树」按钮。

验证：dsh --profile web --dump-config | grep research-tree 能看到 research-tree 行。

快速开始

1. 新建一个会话（任意模式）
2. 对 agent 说："用 tree_node 建一棵研究进度树"（或直接开始研究，agent 会自然使用）
3. 点侧边栏底部「🌳 研究树」按钮，看树实时生长

agent 侧工具用法、UI 操作指南、跨会话续接、FAQ 见 USAGE.md。

树数据存储

默认存于 $DSH_HOME/research-tree/（DSH 数据根目录下，不依赖服务启动目录，任何机器上行为一致；每棵树一个 JSON 文件）。

固定到其他目录（推荐，避免"换启动位置树不见了"）：在本机 profile 的用户层 $DSH_HOME/profiles/web/cordis.patch.yml 按 id 覆盖 root：

- id: research-tree
config:
root: 'D:/your/workspace/research-vault/trees'

改完重启 dsh web 生效。迁移历史数据：把旧目录下的 JSON 文件拷到新目录即可。

仓库结构

dsh-ExploreTree/
├── README.md # 本文件（介绍 + 安装） ├── USAGE.md # 使用文档（工具参考 / UI 指南 / FAQ） ├── REQUIREMENTS.md # 需求规格（vibe coding 的需求对话记录） ├── cordis.patch.yml # DSH 组合行（host 注册） ├── package.json # 插件包声明（dsh.bundle / dsh.client / 依赖） ├── lib/ │ ├── index.js # Host 半端：tree_node 工具 + 事件订阅 + 持久化 + 网关端点 │ └── client.js # 浏览器半端：思维导图面板（手写 bundle，零构建依赖） └── test/ ├── smoke-host.mjs # Host 冒烟测试（真实 cordis 运行时） └── smoke-client.mjs # Client 冒烟测试（布局/状态/纯函数）

兼容性

- 开发验证环境：DSH 0.1.0-rc.6（web profile），Windows
- 依赖 @deepseek-ai/dsh-typert-protocol、@deepseek-ai/dsh-tools（rc 版本，建议与你的 DSH 安装版本一致）
- 客户端 bundle 仅依赖浏览器内核提供的 seed 模块（react），无需构建工具

License

MIT © 2026 CrazeBox