📦 ThoughtDAG 详细部署教程

ThoughtDAG 是一个“思维图谱”工具，它提供了一个无限画布，让 LLM 对话可以生长成可编辑的思维图。它的核心理念是“连线即上下文”(Wires are the context)：模型看到的内容，完全由连接到当前节点的连线决定。通过编辑图谱，你就能直接编辑模型的“记忆”。ThoughtDAG 支持多种运行方式，从无需安装的 CLI 到功能完整的桌面应用。

⚙️ 部署前准备

根据你选择的部署方式，需要不同的环境：

Node.js 环境：大部分方式（CLI、源码、Harness 插件）都需要 Node.js 22.19 或更新版本。
操作系统：桌面应用支持 macOS、Windows 和 Linux。
（可选）支持的 Agent：Session Atlas 功能可以读取 Claude Code、Codex、DeepSeek Harness 和 Pi 的本地会话。

🚀 部署方式

方式一：CLI 与 MCP 工具（无需安装，快速体验）

这是最快速的入门方式，可以立即在终端中搜索和查询本地 Agent 会话。

直接运行（无需安装）：
使用 npx 可以立即执行，无需安装任何东西。

# 查找与某个代码文件相关的会话记录
npx thoughtdag why src/lib/api.ts

# 在会话中查找特定的短语
npx thoughtdag find "你记得的某个短语"

全局安装（方便日常使用）：
如果觉得有用，可以安装为全局命令。
1
npm install -g thoughtdag
配置 MCP 工具（让 AI Agent 调用）：
你可以将 ThoughtDAG 的查询功能作为只读工具，提供给其他 AI Agent (如 Claude Code) 使用。
1
thoughtdag setup mcp
之后，你的 Agent 就可以直接调用 why_check、why_file、find 和 recall_turn 等工具来检索上下文了。

方式二：桌面应用（功能最完整）

桌面应用提供了完整的可视化画布、Session Atlas、PDF 阅读器、模型连接、剪贴和导出功能。

macOS (Homebrew)：
1
brew install --cask thoughtdag
其他系统 (Windows, Linux)：
请访问 ThoughtDAG 的下载页面获取对应操作系统的安装包。
首次启动：
打开应用后，你可以：
- 连接一个本地模型 (如 Ollama) 或任何 OpenAI 兼容的端点。
- 开始创建新的思维图谱，或导入已有的会话。
- 所有数据默认保存在本地，无需联网。

方式三：作为 DeepSeek Harness 插件运行

如果你已经在使用 DeepSeek Harness，可以将其作为插件集成，在 Harness 的 Web UI 中获得一个“对话/思维图”切换视图。

安装插件：

1	dsh plugin --profile web add dsh-thoughtdag

启动 Harness Web UI：
1
dsh web
使用方式：
- 在 Harness 的聊天界面顶部，切换到“思维图”视图。
- 画布上可以编辑节点和连线，连线决定了 Harness 模型在下一轮对话中能看到什么上下文。
- 你可以从画布上直接提问，并选择 Harness 的模型或 Agent 模式来运行。

注意：此方式需要 DeepSeek Harness 0.1.2-rc 或更高版本，并已安装 Node 22.19+。

方式四：从源码运行（适合开发或自定义）

如果你想修改或贡献代码，可以克隆仓库并本地运行。

克隆并安装依赖：

1
2
3

git clone https://github.com/chenxiachan/thoughtdag.git
cd thoughtdag
npm install

启动开发服务器：

# 启动本地 LLM 代理服务器 (端口 :3001)
npm run server

# 在另一个终端中，启动前端开发服务器
npm run dev

之后访问 http://localhost:5173 即可。

配置模型：
应用内可以直接连接任何 OpenAI 兼容的端点。详细的环境变量和连接配置请参考项目 docs/setup.md。

方式五：浏览器在线演示（快速预览）

如果你只是想快速看一眼，不需要安装任何东西，可以使用官方托管的浏览器演示版本。请注意，此版本是功能子集，不支持 Session Atlas、本地会话发现等桌面/本地独有功能。

访问 ThoughtDAG 官网或项目 README 中提供的演示链接即可。

🔧 核心功能使用

Session Atlas (会话图谱)：将分散在 Claude Code、Codex、DeepSeek Harness 和 Pi 等不同 Agent 中的对话，统一带入一个可编辑的上下文图谱。源会话保持只读。
上下文干预：删除一条“噪音”连线，再次提问，模型会给出完全不同的、更干净的答案。这就是“连线即上下文”的威力。
导出思维地图：可以将当前的图谱结构导出为明暗两种主题的“思维地图”(Thought Map)，用于展示或记录。
模型与隐私：支持 Ollama 等本地模型，实现完全离线运行。在桌面应用中，所有画布、密钥和文档都只保存在你的机器上。

❓ 常见问题

Q: CLI 命令找不到？
- A: 确保 Node.js 版本符合要求 (≥22.19)。如果使用 npx 仍失败，可以尝试全局安装 (npm install -g thoughtdag)。
Q: 桌面应用无法连接模型？
- A: 检查模型服务是否运行 (如 Ollama 是否启动)，并确认在应用设置中填写的 API 地址和密钥是否正确。
Q: Session Atlas 找不到我的 Agent 会话？
- A: 目前支持 Claude Code、Codex、DeepSeek Harness 和 Pi 的本地会话。请确认这些 Agent 的会话文件存储在默认位置，并且 ThoughtDAG 有权限读取。更多 Agent 支持正在开发中。
Q: 如何更新桌面应用？
- A: macOS 用户重新运行 brew upgrade --cask thoughtdag；其他系统用户请从官网下载最新安装包覆盖安装。源码运行的用户可以 git pull 并重新 npm install。