1. 项目概述一个可审计的多智能体协作推理引擎如果你和我一样长期在AI应用开发的一线肯定遇到过这样的困境让大语言模型LLM进行复杂推理时过程就像一个黑盒。它给出了一个答案但你完全不知道这个结论是怎么一步步推导出来的——中间有哪些假设、考虑了哪些分支、又放弃了哪些可能性。更别提让多个AI智能体协同工作了那简直是“群聊混乱”的数字化版本每个智能体自说自话最后的结果难以追溯、无法审计。Thoughtbox就是为了解决这个核心痛点而生的。它不是另一个简单的AI聊天框架而是一个基于Docker的MCP模型上下文协议服务器专门为多智能体协作推理设计并且每一步思考都被结构化地记录和持久化。你可以把它理解为一个“思维实验室”AI智能体们在这里通过共享的工作空间进行协作认领问题、提出解决方案、相互评审工作最终达成共识。而所有这些交互都会形成一个可追溯、可可视化、可分析的“推理账本”。最让我欣赏的是它的“本地优先”理念。整个系统完全运行在你的机器上所有数据都存放在~/.thoughtbox/目录下没有任何信息会离开你的本地网络。这对于处理敏感数据、进行内部技术论证或者单纯想要完全掌控数据流向的开发者来说是一个巨大的优势。2. 核心设计理念极简工具表面与结构化思维2.1 “代码模式”下的双工具哲学很多AI工具框架喜欢注册几十甚至上百个工具Tools导致LLM的上下文窗口被大量工具描述塞满真正用于推理的令牌所剩无几。Thoughtbox反其道而行之它采用了“代码模式”只暴露两个核心MCP工具thoughtbox_search用JavaScript编写查询在操作/提示/资源目录中进行搜索。这相当于给了LLM一个强大的程序化过滤能力让它能动态地发现当前可用的能力。thoughtbox_execute用JavaScript调用内置的tbSDK来链式执行操作。通过这个统一的命名空间智能体可以访问思维、会话、知识图谱、笔记本、协作中心等所有功能。工作流变得异常清晰先用search探索有什么可用的“积木”然后用execute编写逻辑把这些“积木”搭建成完整的解决方案。你甚至可以用console.log()来调试输出会被捕获并记录在响应日志中。这种设计从根本上解决了工具泛滥导致的上下文污染问题让智能体能更专注于问题本身。2.2 多智能体协作的“工作空间”范式Thoughtbox的协作核心是“中心”。智能体们需要先注册并携带特定的角色档案如MANAGER、ARCHITECT、DEBUGGER等然后加入共享的工作空间。这模仿了人类团队的协作模式。在工作空间内所有工作都围绕几个核心原语展开问题一个工作单元包含依赖关系、子问题和状态跟踪开放→进行中→已解决→已关闭。提案一个附有源代码分支引用的解决方案建议并带有评审工作流。共识一个与特定思维节点绑定的决策标记确保可追溯性。频道一个限定在某个问题范围内的消息流用于讨论。这种结构化的协作流程注册→创建工作空间→创建问题→认领→工作→提出方案→同行评审→合并→达成共识确保了多智能体交互的秩序和可审计性。每个角色档案都内置了特定领域的思维模型和行为引导让智能体能更好地扮演其专业角色。注意这里的“智能体”在初始使用阶段往往是由你开发者通过同一个LLM会话以不同角色视角交替使用Thoughtbox工具来模拟的。真正的多智能体自动协作需要更上层的编排器来调度但Thoughtbox已经提供了所有必要的底层基础设施和数据结构。2.3 可审计的推理思维即节点这是Thoughtbox的灵魂。每一次推理步骤都被记录为一个结构化的“思维”它是推理图中的一个节点。每个思维都有唯一的编号、时间戳并链接到它的前驱节点。这些思维会跨会话持久化形成一个完整的、可审计的结论推导轨迹。思维不仅记录内容还通过thoughtType进行语义分类例如reasoning逻辑推导过程。decision_frame决策框架或选项评估。action_report执行某项操作后的报告。belief_snapshot在某一时刻的信念或知识状态快照。更重要的是Thoughtbox将几种常见的思维模式提升为一等公民操作模式描述适用场景正向思维顺序推进 1→2→3→N探索、发现、开放式分析逆向思维从目标(N)开始反向推导至起点(1)规划、系统设计、从已知目标出发分支思维分叉进行并行探索 (A, B, C...)比较备选方案、A/B场景分析修订思维用新信息更新早期思维错误纠正、理解细化批判思维通过MCP采样请求自主的LLM评审自检、质量门控例如在系统设计时你可以从“目标系统支撑10k QPS且延迟100ms”开始逆向推导需要的组件。在方案选型时你可以从同一个节点分支分别探索SQL和NoSQL路径的优劣最后再合成一个综合决策节点。这种显式的模式记录让事后的分析变得极具价值。3. 环境部署与核心配置实战3.1 基于Docker的一键部署Thoughtbox强烈推荐使用Docker Compose进行部署这是最快体验其完整能力的方式尤其是内置的Observatory观测台UI和可观测性技术栈。# 1. 克隆仓库 git clone https://github.com/Kastalien-Research/thoughtbox.git cd thoughtbox # 2. 构建并启动所有服务包括Prometheus和Grafana docker compose up --build这条命令会启动下表所列的完整服务栈服务端口描述thoughtbox1731 (MCP), 1729 (Observatory)核心MCP服务器 观测台Web UImcp-sidecar4000带OpenTelemetry追踪的可观测性代理otel-collector4318 (HTTP), 8889 (metrics)OpenTelemetry收集器prometheus9090指标存储与告警grafana3001仪表盘和可视化所有持久化数据思维记录、指标数据、Grafana配置都保存在Docker的命名卷中thoughtbox-data,prometheus-data,grafana-data即使容器重启也不会丢失。实操心得第一次启动时因为要构建镜像和初始化多个服务可能需要几分钟。确保你的Docker环境有至少4GB的可用内存否则Grafana等组件可能启动失败。启动成功后立即打开http://localhost:1729你就能看到空白的观测台界面等待思维图的出现。3.2 关键环境变量解析Thoughtbox的许多行为可以通过环境变量调节。以下是一些最关键变量的详解理解它们能帮你更好地定制运行时环境变量描述默认值实战建议THOUGHTBOX_DATA_DIR持久化存储的基础目录~/.thoughtbox可以修改到SSD硬盘或更大容量的分区提升I/O性能。THOUGHTBOX_PROJECT用于会话隔离的项目范围_default强烈建议为不同项目设置不同值如THOUGHTBOX_PROJECTmy_web_app。这会在数据目录下创建独立的子目录实现思维记录的天然隔离。THOUGHTBOX_STORAGE存储后端fsfs文件系统适合本地开发supabase用于云原生部署需配合SUPABASE_URL和SUPABASE_SERVICE_ROLE_KEY使用。THOUGHTBOX_OBSERVATORY_ENABLED启用观测台Web UIfalseDocker Compose默认启用。如果你只用CLI或API可以禁用以节省资源。THOUGHTBOX_AGENT_ID/THOUGHTBOX_AGENT_NAME预分配的智能体ID和名称(无)在自动化脚本或CI/CD流水线中运行Thoughtbox时预先设置此变量可以确保所有产生的思维都被正确归属到该“机器智能体”名下。DISABLE_THOUGHT_LOGGING禁止将思维记录打印到stderrfalse当你在终端运行并希望减少日志干扰时可以设置为true。思维依然会被持久化存储只是不输出到控制台。配置示例如果你想要一个专注于“后端API优化”项目的独立环境并希望数据存放到特定位置可以这样启动export THOUGHTBOX_DATA_DIR/opt/thoughtbox_data export THOUGHTBOX_PROJECTapi_optimization docker compose up --build3.3 客户端配置以Claude Code为例Thoughtbox是一个MCP服务器需要你的AI客户端如Claude Code、Cursor、Windsurf去连接它。由于它使用HTTP传输协议配置的核心就是告诉客户端服务器的URL。对于Claude Code你需要编辑其MCP服务器配置文件。通常位置在~/.claude/settings.json全局配置或你项目根目录的.claude/settings.json项目特定配置。基础连接配置直接连接核心服务器{ mcpServers: { thoughtbox: { url: http://localhost:1731/mcp } } }通过可观测性边车连接推荐可获得完整的OpenTelemetry追踪链路{ mcpServers: { thoughtbox: { url: http://localhost:4000/mcp } } }重要提示Thoughtbox目前主要针对Claude Code进行了优化。其他MCP客户端如Cursor可能因为对MCP协议特性如listChanged通知、提示词、资源等的支持程度不同而遇到兼容性问题。如果遇到问题最好的方式是去项目GitHub仓库提交Issue说明你使用的客户端和具体现象。配置后的验证配置保存后重启你的Claude Code。在聊天界面你应该能看到可用的工具列表里出现了thoughtbox_search和thoughtbox_execute。你可以尝试发送一条消息“使用thoughtbox_search工具查看有哪些可用的操作。” 如果配置正确Claude会调用该工具并返回操作目录。4. 核心工作流与SDK深度使用指南4.1 搜索与执行从探索到构建Thoughtbox的工作流始于探索终于执行。我们通过一个具体的例子来感受一下。假设我们想分析一个Web应用的性能瓶颈。第一步探索可用操作我们让Claude Code执行搜索。虽然你可以用自然语言描述但直接使用thoughtbox_search工具并编写JavaScript查询更精准。// 这是一个在thoughtbox_search工具中可能使用的查询示例 // 搜索目录中与“分析”、“性能”或“问题”相关的操作 const catalog await tb.catalog; const relevantOps catalog.operations.filter(op op.name.toLowerCase().includes(analy) || op.description.toLowerCase().includes(performance) || op.tags.includes(problem) ); return relevantOps.map(op ({name: op.name, description: op.description}));执行后你可能会得到一系列操作比如hub.problem.create,hub.problem.analyze,thought.forward等。这个搜索过程是动态的完全由你或智能体的查询逻辑控制。第二步链式执行构建解决方案现在我们知道了有哪些“积木”接下来用thoughtbox_execute来搭建一个完整的性能分析流程。// 在thoughtbox_execute工具中执行的代码 const tb require(thoughtbox/sdk); // 1. 创建一个问题Performance Issue const problem await tb.hub.problem.create({ title: Web App Checkout Performance Degradation, description: Users report slow checkout times averaging 45s, exceeding the target of 10s., priority: high }); // 2. 记录初始分析思维正向思维 await tb.thought.forward({ content: Initial analysis: Checkout process involves 3 sequential API calls to inventory, pricing, and shipping services. No caching layer observed., thoughtType: reasoning }); // 3. 提出并评估多个解决方案分支思维 const branchA await tb.thought.branch({ parentThoughtId: 2, // 假设上一步思维ID是2 branchId: caching-solution, content: Solution A: Implement Redis cache for product inventory and pricing data. Estimated latency reduction: 70%. Complexity: Medium. }); const branchB await tb.thought.branch({ parentThoughtId: 2, branchId: parallel-calls, content: Solution B: Refactor API calls to run in parallel where possible. Estimated latency reduction: 50%. Complexity: High due to async error handling. }); // 4. 基于评估做出决策 await tb.thought.forward({ content: Synthesis: Given time constraints and team expertise, Solution A (Redis cache) offers the best risk/reward ratio. Will proceed with a phased rollout: cache product data first, then pricing., thoughtType: decision_frame }); // 5. 将决策关联到问题并创建解决方案提案 const proposal await tb.hub.proposal.create({ problemId: problem.id, branchRef: branchA.id, // 引用分支A的思维 summary: Implement Redis caching layer for checkout service }); console.log(Analysis complete. Problem ID: ${problem.id}, Proposal ID: ${proposal.id});这段代码模拟了一个完整的智能体推理流程定义问题、分析现状、探索方案、做出决策、形成提案。所有步骤都被结构化的思维节点记录下来。4.2 多智能体协作模拟实战Thoughtbox的Hub模块让模拟多角色评审成为可能。继续上面的例子假设现在需要架构师和安全工程师来评审这个缓存方案。// 模拟架构师角色进行评审 await tb.hub.agent.register({ agentId: architect_01, name: System Architect, profile: ARCHITECT }); const archReview await tb.hub.proposal.review({ proposalId: proposal.id, agentId: architect_01, comment: 从架构角度看引入Redis是合理的。建议明确缓存失效策略TTL vs 写时失效和集群方案以防单点故障。, status: approved_with_suggestions }); // 模拟安全工程师角色进行评审 await tb.hub.agent.register({ agentId: security_01, name: Security Engineer, profile: SECURITY }); const secReview await tb.hub.proposal.review({ proposalId: proposal.id, agentId: security_01, comment: 需要评估1. Redis是否启用TLS加密传输。2. 缓存中是否可能包含PII数据。3. 访问控制列表ACL配置。建议安全评审通过后再上线。, status: changes_requested }); // 根据评审意见更新提案或思维 await tb.thought.revision({ targetThoughtId: branchA.id, // 修订之前的分支思维 content: Revised Solution A: Implement Redis cluster with TLS, ACL, and a 5-minute TTL cache policy for non-PII data. Security review pending., }); // 最终如果评审通过可以达成共识 if (archReview.status approved secReview.status approved) { await tb.hub.consensus.create({ problemId: problem.id, thoughtRef: branchA.id, // 共识指向最终的决策思维 decision: Proceed with the secured Redis caching implementation., agentsInAgreement: [architect_01, security_01] }); }这个流程展示了Thoughtbox如何将松散的“讨论”变成结构化的、可追溯的“评审工作流”。每个角色的反馈都被锚定在具体的提案和思维上最终的共识也有明确的出处。4.3 知识图谱与笔记本超越单次会话的记忆Thoughtbox的强大之处在于它的状态是持久的。知识图谱允许你在不同会话、不同项目中积累和关联知识。// 将本次性能分析的关键洞察保存到知识图谱 await tb.knowledge.entity.create({ type: ArchitecturalPattern, id: cache-layer-pattern, content: { name: Redis Cache Layer for Latency Reduction, description: Placing a Redis cluster between stateless services and databases to absorb read load., bestFor: [High-read scenarios, Data with low real-time requirement], considerations: [Cache invalidation strategy, Cluster sizing, Security (TLS/ACL)] } }); // 建立关系本次问题采用了这个模式 await tb.knowledge.relation.create({ source: problem:${problem.id}, target: entity:ArchitecturalPattern:cache-layer-pattern, type: APPLIES }); // 未来在另一个会话中可以查询相关知识 const relatedPatterns await tb.knowledge.relation.list({ source: problem:${problem.id}, type: APPLIES });笔记本功能则提供了交互式的编程环境你可以混合编写Markdown文档和可执行的JavaScript/TypeScript代码块用于记录实验过程、编写可复用的分析脚本或者创建教学示例。5. 观测、分析与问题排查5.1 实时观测台可视化思维流部署完成后访问http://localhost:1729就打开了Thoughtbox的观测台。这是理解智能体“思考过程”最直观的方式。核心功能点实时思维图每当一个思维节点被创建它会以WebSocket方式近乎实时地出现在图中央。节点颜色和形状可能对应不同的thoughtType。分支导航分支思维会被视觉化地折叠成“存根”。你可以点击一个分支存根如下图中的紫色节点13-14来深入查看该分支下的所有细节思维也可以随时返回主干。详情面板点击任何一个思维节点右侧面板会显示其完整内容、元数据时间戳、父节点、分支ID和原始JSON。多会话切换顶部通常有会话选择器你可以查看当前项目下不同时间、不同主题的推理会话。深度分析观测台可能提供会话级别的分析比如统计各类思维模式的使用比例、识别关键的决策点、评估推理路径的复杂度等。使用技巧在进行复杂决策时保持观测台打开。你可以亲眼看到智能体是如何“犹豫不决”创建多个分支又是如何“下定决心”合并分支或选择其一的。这对于调试智能体的决策逻辑非常有帮助。5.2 可观测性技术栈指标与追踪除了UIThoughtbox还集成了完整的云原生可观测性套件Prometheus(http://localhost:9090)收集Thoughtbox服务器自身的性能指标如请求延迟、错误率、活跃会话数、思维创建频率等。你可以在这里编写自定义告警规则。Grafana(http://localhost:3001)默认用户名/密码通常是admin/admin。这里预置了仪表盘将Prometheus的指标以更友好的图表形式展示例如“每分钟思维创建数”、“各类型工具调用耗时”、“会话活跃时长分布”。OpenTelemetry通过mcp-sidecar端口4000代理的请求会被自动注入追踪信息。如果你在分布式系统中使用Thoughtbox这些追踪数据可以帮助你分析一次AI推理在整个调用链中的耗时占比。排查性能问题如果感觉Thoughtbox响应变慢首先去Grafana查看请求延迟和错误率图表。其次检查Prometheus中关于存储后端的指标如果使用fs后端可以关注文件写入延迟。这些数据能帮你定位问题是出在网络、计算还是I/O上。5.3 常见问题与解决方案速查在实际集成和使用中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案Claude Code无法连接Thoughtbox提示“无法连接到MCP服务器”。1. Thoughtbox服务未启动。2. 防火墙或端口冲突。3. Claude Code配置错误。1. 运行docker ps确认thoughtbox和mcp-sidecar容器在运行。2. 检查端口1731或4000是否被占用lsof -i :1731。3. 核对settings.json中的URL是否正确特别注意是http而非https。观测台 (localhost:1729) 无法打开或页面空白。1. Observatory服务未启用。2. 浏览器CORS问题。3. WebSocket连接失败。1. 确认THOUGHTBOX_OBSERVATORY_ENABLED未设置为false。2. 检查Docker Compose日志中Observatory服务的启动信息。3. 打开浏览器开发者工具查看Console和Network标签页的错误信息。thoughtbox_execute执行JavaScript代码时报语法错误或tb is not defined。1. SDK对象引用错误。2. 代码运行环境隔离问题。1. 确保代码中通过const tb require(thoughtbox/sdk);或全局tb对象来调用SDK。2.thoughtbox_execute工具会在一个隔离的JavaScript环境中运行你的代码确保没有使用该环境不支持的API如某些Node.js内置模块。思维节点没有出现在观测台中。1. WebSocket连接断开。2. 思维未成功持久化。3. 当前观测台会话与思维所属会话不匹配。1. 刷新观测台页面重新建立WebSocket连接。2. 检查Thoughtbox容器的日志看是否有存储错误。3. 确认你正在查看的会话Session是否正确。观测台默认可能显示最新会话使用会话切换器查看所有会话。存储目录 (~/.thoughtbox) 增长过快。1. 产生了大量会话和思维数据。2. 旧会话数据未清理。1. Thoughtbox默认持久化所有数据。定期手动清理不需要的旧项目目录rm -rf ~/.thoughtbox/projects/old_project_name。2. 可以考虑编写脚本基于时间戳归档或删除旧会话。未来版本可能提供数据保留策略配置。使用Supabase存储后端时连接失败。1. 环境变量SUPABASE_URL或SUPABASE_SERVICE_ROLE_KEY未设置或错误。2. Supabase项目网络策略限制。1. 仔细核对环境变量值确保Service Role Key具有足够的数据库操作权限。2. 在Supabase控制台的Database - Settings - Network中确保允许Docker容器所在IP的访问或配置为允许所有IP仅用于测试。一个深度排查案例假设你在执行一个复杂的thoughtbox_execute脚本时超时了。首先去观测台查看思维图看它停在了哪个节点。然后检查Docker容器的日志docker logs thoughtbox-thoughtbox-1 --tail 100寻找错误堆栈。接着在Grafana中查看该时间点附近的请求延迟和错误计数。最后可以考虑简化你的脚本分步执行或者检查脚本中是否有死循环或非常耗时的同步操作。6. 开发、测试与扩展6.1 本地开发环境搭建如果你想要贡献代码或者深度定制Thoughtbox需要搭建本地开发环境。它要求Node.js 22和pnpm。# 克隆代码 git clone https://github.com/Kastalien-Research/thoughtbox.git cd thoughtbox # 安装依赖 pnpm install # 构建项目 pnpm build # 以开发模式运行支持热重载 pnpm dev运行pnpm dev会启动开发服务器通常监听在1731端口。此时你可以修改源代码服务器会自动重启。这对于调试或添加新功能非常方便。6.2 测试套件详解Thoughtbox拥有完善的测试体系确保代码质量和功能稳定。# 运行单元测试快速反馈 npx vitest run # 运行完整测试套件包括构建 pnpm test # 运行“智能体”测试 - 这是重点 # 这些测试会模拟真实LLM调用Thoughtbox工具的场景验证端到端流程。 pnpm test:agentic # 完整智能体测试构建运行 pnpm test:agentic:tool # 仅工具级别的智能体测试 pnpm test:agentic:quick # 快速智能体测试不重新构建 # 运行行为契约测试 pnpm test:behavioral给贡献者的建议在提交Pull Request前务必运行pnpm test确保所有测试通过。如果添加了新功能请为其编写相应的单元测试在src/下对应目录的*.test.ts文件和可能的智能体测试在tests/agentic/目录下。智能体测试尤其重要它能保证你的修改不会破坏与真实LLM交互的预期行为。6.3 架构扩展点添加自定义操作Thoughtbox的架构非常清晰扩展性很好。假设你想添加一个自定义操作比如一个调用外部天气API的工具。定义操作在src/hub/operations.ts的操作目录中添加你的新操作定义。需要指定名称、描述、输入参数模式和实现函数。// 示例在operations.ts的catalog对象中添加 export const catalog { // ... 其他操作 weather.getCurrent: { name: weather.getCurrent, description: Fetches current weather for a given city., inputSchema: { type: object, properties: { city: { type: string, description: Name of the city } }, required: [city] } as const, handler: async ({ city }: { city: string }) { // 在这里实现调用天气API的逻辑 const response await fetch(https://api.weather.example?city${city}); const data await response.json(); return { temperature: data.temp, conditions: data.conditions }; } } };注册工具确保该操作被包含在src/server-factory.ts或相应的工具处理器中注册的列表里。更新SDK类型为了让thoughtbox_execute中的代码有类型提示你需要更新src/code-mode/sdk-types.ts文件在TB接口中添加对应的方法定义。重建并测试运行pnpm build然后pnpm dev。现在你就可以在thoughtbox_search的结果中看到weather.getCurrent并在thoughtbox_execute中通过await tb.hub.weather.getCurrent({ city: Beijing })来调用它了。存储后端扩展如果你需要除了fs、memory、supabase之外的存储比如S3、MySQL可以实现src/persistence/storage.ts中定义的Storage接口并在工厂函数中添加你的新后端。7. 项目适配与进阶思考经过一段时间的深度使用我认为Thoughtbox的价值在几个特定场景下会被放大场景一复杂技术决策的审计追踪。当团队需要就是否引入新技术、选择何种架构进行深入论证时让AI智能体或由人扮演的不同角色在Thoughtbox中展开辩论所有论点、论据、假设和最终结论都被完整记录。这份“推理账本”本身就是一份极佳的技术决策文档。场景二自动化代码审查与知识传承。可以配置一个“审查者”智能体其知识图谱中灌输了团队的代码规范、安全红线、性能模式。当新代码提交时触发该智能体在Thoughtbox中进行分析生成结构化的审查报告包含问题、建议、引用规范并保存到知识库。新人可以通过查询这些历史审查记录来快速学习团队规范。场景三教育研究与认知科学。Thoughtbox的思维记录功能为研究AI的推理过程提供了绝佳的工具。研究者可以设计不同的提示词和协作流程观察并分析AI智能体是如何解决问题的从而更好地理解大语言模型的“思维”模式。当前局限与应对Thoughtbox的核心抽象非常强大但其生态仍处于早期。最大的挑战在于如何将这种结构化的协作流程与现有的开发工具链如GitHub、Jira、Slack无缝集成。目前这需要你编写一些胶水代码通过Thoughtbox的API或直接读取文件系统数据来同步状态。另一个挑战是学习曲线开发者需要适应“代码模式”和思维图的概念这比使用传统的自然语言聊天需要更多的前期投入。不过一旦跨越了这个门槛你会发现它带来的清晰度、可控性和可追溯性是传统“黑盒”AI交互方式无法比拟的。它不是在替代你的思考而是在为你和你的AI伙伴提供一个严谨的、可复现的思考工作台。