技术文档摘要

🚦 分支思考 MCP 工具

新功能（2025-04）：

• 高级可视化：聚类（k-means/度数）、中心性覆盖、边捆绑以及任务和优先级的代理覆盖
• 代理缓存与预取：LRU+TTL 缓存用于嵌入、摘要、分析以及主动代理缓存预热
• 增强分析：实时、多分支支持；代理优化元数据
• 升级文档和代理及用户入门指南

---

功能

• 🌳 分支管理： 创建、聚焦并导航多个思路
• 🔗 交叉引用： 在分支之间链接相关想法（类型化、评分）
• 💡 AI 洞察： 自动洞察和摘要生成
• 🧠 语义搜索： 使用嵌入查找相关想法
• 📊 高级可视化：
  • 节点聚类（k-means/度数）
  • 中心性覆盖（接近度、介数）
  • 边捆绑
  • 任务覆盖（状态、优先级、下一步操作）
  • 所有节点/边的代理覆盖和元数据
  • FocusNode 和多分支可视化
• ⚡ 代理缓存与预取：
  • LRU+TTL 缓存用于嵌入、摘要、分析
  • 主动缓存预热以优化代理工作流
• 🗂️ 持久存储： 可查询、可扩展且永不丢失一个想法
• 🔄 实时与多分支： 实时可视化和分析多个分支和节点
• 🛠️ 生产级： 强大的错误处理、性能优化以及代理/人类友好的API

---

🛠️ 技术栈

• Node.js (18+)
• TypeScript (4.x)
• @dagrejs/graphlib: 图结构、算法和分析
• ml-kmeans: 可视化的聚类
• lru-cache: LRU+TTL 缓存用于嵌入、摘要、分析
• @xenova/transformers: 嵌入和摘要流水线
• @modelcontextprotocol/sdk: MCP协议和代理集成
• chalk: CLI输出样式
• Mermaid: Gantt/路线图可视化
• pnpm: 快速依赖管理

---

路线图 (甘特图)

gantt
    title 分支思考 MCP 路线图 (2.025)
    dateFormat  YYYY-MM-DD
    section Q2 2025
    高级可视化/分析 :done,      vis1, 2025-04-01,2025-04-20
    代理缓存与预取         :done,      cache1, 2025-04-10,2025-04-22
    增强代理文档            :done,      doc1, 2025-04-15,2025-04-25
    实时协作          :active,    collab1, 2025-04-20,2025-06-01
    网页可视化仪表板      :active,    webviz1, 2025-04-25,2025-06-15
    section Q3 2025
    插件系统                    :planned,   plugin1, 2025-06-15,2025-07-15
    移动/平板UI                 :planned,   mobile1, 2025-07-01,2025-08-01
    AI分支合并                :planned,   merge1, 2025-07-15,2025-08-15
    知识库同步              :planned,   sync1, 2025-08-01,2025-09-01

<!-- 只有一个甘特图存在并且是最新的。 -->

---

目录

• 为什么分支思考？
• 总结
• 功能
• 快速开始
• 入门指南
• 实际使用案例
• 架构与流程
• 路线图 (甘特图)
• 测试与质量
• 安全
• 无障碍与国际化
• 故障排除与常见问题解答
• 最佳实践
• 贡献
• 变更日志
• 参考资料及相关项目
• 致谢
• 许可证

---

为什么分支思考？

• 设计为代理： 适用于人类和AI工作流——每个命令都是代理友好的。
• 真正的分支： 并行组织、交叉链接和推理想法、代码和任务。
• AI原生： 语义搜索、自动摘要和洞察生成开箱即用。
• 持久与可视化： 永不丢失一个想法——一切都是可查询、可视化的和可扩展的。

总结

分支思考 MCP 工具 是一个先进的代理平台，用于管理和可视化分支思想、任务、代码和知识。它使AI代理和人类能够通过强大的基于分支的范式来组织复杂的项目、交叉链接想法并自动化洞察生成。凭借语义搜索、可视化和持久的任务/代码管理，它旨在支持下一代协作和自主工作流。

分支思考 MCP 工具 是一个先进的代理平台，用于管理和可视化分支思想、任务、代码和知识。它使AI代理和人类能够通过强大的基于分支的范式来组织复杂的项目、交叉链接想法并自动化洞察生成。凭借语义搜索、可视化和持久的任务/代码管理，它旨在支持下一代协作和自主工作流。

---

架构与流程

flowchart TD
    用户([用户/代理 🤖])
    CLI([CLI/API])
    BM[分支管理器 🧠]
    EmbCache[[嵌入/摘要缓存]]
    存储[(持久存储 💾)]
    可视化([可视化/分析])
    任务([任务提取])
    片段([代码片段存储])

    用户-->|命令/查询|CLI
    CLI-->|管理/查询|BM
    BM-->|缓存|EmbCache
    BM-->|保存/加载|存储
    BM-->|可视化|可视化
    BM-->|任务|任务
    BM-->|片段|片段
    BM-->|结果|CLI
    CLI-->|输出|用户

---

快速开始

几秒钟内启动：

pnpm install  # 推荐用于速度 (或 npm install)
pnpm build
node dist/index.js --help  # 查看可用命令

---

入门指南

1. 克隆并安装

git clone https://github.com/your-org/branch-thinking-mcp.git
cd branch-thinking-mcp
pnpm install  # 或 npm install
pnpm build   # 或 npm run build

2. 配置 (可选)

对于 Claude Desktop 集成，在您的 claude_desktop_config.json 中添加：

"branch-thinking": {
  "command": "node",
  "args": [
    "/your-custom-mcp-dir-here/branch-thinking/dist/index.js"
  ]
}

3. 运行

node dist/index.js

---

实际使用案例

1. 知识捕获与链接

# 批量捕获会议笔记
add-thought dev "讨论语义搜索改进" 笔记
add-thought dev "同意重构API" 决定
# 链接相关想法
link-thoughts t1 t2 支持 "API重构支持搜索改进"

2. 代理任务提取

# 从研究分支中提取和管理任务
extract-tasks 研究
list-tasks 研究 开放
update-task-status task-1 进行中

3. 视觉化以获得洞察

# 生成并解释知识图谱
visualize dev
# 审查AI生成的摘要
summarize-branch dev

---

🧑‍💻 实例：代理工作流

# 1. 为您的项目或想法创建一个新的分支
create-branch "AI研究"

# 2. 添加想法和观察
add-thought [branchId] "探索代理工作流中的语义搜索" 分析
add-thought [branchId] "测试交叉链接和摘要生成" 观察

# 3. 链接相关想法
link-thoughts [thoughtId1] [thoughtId2] 支持 "想法2验证想法1"

# 4. 查看您的知识图谱
visualize [branchId]

# 5. 提取任务并获取AI审查
extract-tasks [branchId]
review-branch [branchId]

替换 [branchId] 和 [thoughtIdX] 为实际ID，来自 list 和 history。

---

命令参考

分支管理

命令	描述
list	显示所有分支及其状态
focus [branchId]	切换到一个分支
history [branchId?]	显示想法历史
summarize-branch [branchId?]	AI摘要分支
review-branch [branchId?]	AI审查分支
visualize [branchId?]	可视化连接图

想法与洞察管理

命令	描述
insights [branchId?]	获取AI生成的洞察
crossrefs [branchId?]	显示交叉引用
hub-thoughts [branchId?]	列出枢纽想法
semantic-search [query]	查找相似的想法
link-thoughts [from] [to] [type] [reason?]	链接两个想法
add-snippet [content] [tags]	保存代码片段
snippet-search [query]	搜索代码片段
doc-thought [thoughtId]	文档化一个想法

任务管理

命令	描述
extract-tasks [branchId?]	提取可执行项
list-tasks [branchId] [status] [assignee] [due]	列出/筛选任务
update-task-status [taskId] [status]	更新任务的状态
summarize-tasks [branchId]	汇总任务

AI & 知识

命令	描述
ask [question]	从知识库中获取AI答案

最佳实践

• 始终从 create-branch 开始，确保上下文清晰。
• 使用 list 和 focus 在项目或思路之间导航。
• 在添加几个想法后，利用 summarize-branch 和 insights 获取AI生成的上下文。
• 使用 link-thoughts 明确连接想法、任务或代码，以形成更丰富的语义图。
• 在代码更改后，始终运行 pnpm lint 和 pnpm build 以尽早捕捉错误。
• 将复杂目标分解为一系列想法/任务/洞察命令。
• 迭代和适应：使用摘要、审查和可视化反馈来细化下一步行动。
• 明确指定参数（branchId、status、assignee等）以获得精确结果。
• 使用交叉引用和多跳链接来激发创造力并连接想法。
• 提示代理（Claude、GPT-4等）“逐步思考”或“使用链式思维”以获得最佳结果。

安全

• 所有持久数据都存储在本地（默认：项目目录或 MCP_STORAGE_PATH）
• 除非配置，否则没有外部API调用
• 代理/用户负责存储的想法和任务的隐私
• 如需报告安全问题，请打开一个问题或联系维护者。

故障排除和常见问题解答

Q: 工具没有响应！ A: 检查MCP服务器日志并确保配置正确。

Q: 如何重置存储？ A: 删除或移动持久存储目录（参见配置）。

Q: 如何添加新命令？ A: 在 src/index.ts 中扩展 handleCommand 并在README中记录它。

无障碍与国际化

• 所有徽章/图像都有描述性的alt文本。
• 默认语言是英语；欢迎为翻译做出贡献。
• 如果您想帮助本地化此工具，请打开一个PR或问题。

贡献

欢迎提出贡献、问题和功能请求！请在GitHub上打开一个PR或问题。

1. 分叉这个仓库
2. 创建一个新的分支 (git checkout -b feature/your-feature)
3. 提交您的更改
4. 推送到分支
5. 打开一个拉取请求

参考资料及相关项目

• 模型上下文协议 (MCP)
• 顺序思考工具
• Obsidian
• Logseq

---

致谢

• 概念与测试： @ssdeanx
• 核心代码生成： Claude, GPT-4, and Cascade
• 实现、修复和文档： @ssdeanx

---

许可证

MIT