Thoughtbox

Thoughtbox

可审计的多 Agent 协作推理。 Thoughtbox 是一个用于结构化多 Agent 推理的 MCP 服务，并配有用于工作区和检查流程的 Web 应用。每一步都会作为结构化思考记录在持久化推理账本中，可视化、导出和分析。

运行模式： 本地开发可使用文件系统或内存存储。部署模式使用由 Supabase 提供支持的存储，目前的生产 MCP 服务运行在 Cloud Run 上。

Observatory UI 展示了一个包含 14 条思考的推理会话，以及一个从思考 5 分支出来的分支探索（紫色节点 13-14）。

代码模式

Thoughtbox 使用代码模式，提供恰好 两个 MCP 工具：

• thoughtbox_search — 编写 JavaScript 以查询操作/提示词/资源目录。大模型可以对目录进行全面的程序化筛选。
• thoughtbox_execute — 使用 tb SDK 编写 JavaScript 以串联操作。通过统一的命名空间访问思考、会话、知识、笔记本、hub、可观测性和协议工具。

工作流： 先搜索以发现可用操作，再执行代码调用这些操作。使用 console.log() 进行调试——输出会记录在响应日志中。

这种方式用两个工具取代了逐个注册操作的做法，既能扩展，也不会让上下文窗口膨胀。

多 Agent 协作

Hub 是协作层。Agent 使用特定角色的配置文件注册、加入共享工作区，并通过结构化的问题解决工作流开展工作——所有操作都通过 thoughtbox_execute 完成。

工作流： 注册 → 创建工作区 → 创建问题 → 认领 → 开展工作 → 提出解决方案 → 同行评审 → 合并 → 达成共识

工作区原语：

• 问题 — 一个工作单元，可包含依赖项和子问题，并跟踪状态（open → in-progress → resolved → closed）
• 提案 — 提出的解决方案，包含源分支引用和评审工作流
• 共识 — 与思考引用关联的决策标记，便于追溯
• 频道 — 针对某个问题的消息流，用于讨论

Agent 配置文件： MANAGER、ARCHITECT、DEBUGGER、SECURITY、RESEARCHER、REVIEWER——每种配置文件都会提供特定领域的思维模型和行为引导。

涵盖身份、工作区管理、问题、提案、共识、频道和状态报告的 28 项操作。

可审计的推理

每条思考都是图中的一个节点——都有编号和时间戳，与前序节点相连，并持久化保存，跨会话保留。由此形成可审计的轨迹，记录结论是如何得出的。

Agent 可以向前思考、逆向规划、分支开展并行探索，也可以修订较早的结论。每种模式都是一项一等操作：

模式	说明	用例
正向	按顺序从 1→2→3→N 推进	探索、发现、开放式分析
逆向	从目标（N）出发，反向推演至起点（1）	规划、系统设计、从已知目标出发开展工作
分支	分叉开展并行探索（A、B、C……）	比较替代方案、A/B 场景
修订	根据新信息更新较早的思考	错误纠正、完善理解

每条思考都带有语义 thoughtType（reasoning、decision_frame、action_report、belief_snapshot、assumption_update、context_snapshot、progress），用于对思考的类型进行分类，与所使用的过程模式相互独立。

详见 模式手册，其中包含完整示例。

实时可观测性

Observatory 是一个内置的 Web UI，地址为 http://localhost:1729，可用于实时查看推理过程。

• 实时图谱 — 思路通过 WebSocket 实时显示为节点
• 分支导航 — 分支会折叠为可点击的占位项；可深入查看并返回
• 详情面板 — 点击任意节点即可查看完整的思路内容
• 多会话 — 在活跃的推理会话之间切换
• 深度分析 — 分析会话中的推理模式、认知负荷和决策点

完整的可观测性技术栈包括 OpenTelemetry 跟踪、Prometheus 指标和 Grafana 仪表板。

知识与推理工具

知识图谱 — 跨会话的持久化记忆。将见解、概念、工作流和决策保存为带类型的实体，并通过带类型的关系（BUILDS_ON、CONTRADICTS、SUPERSEDES 等）和可见性控制（public、agent-private、team-private）进行管理。

笔记本 — 交互式文学式编程，将文档与可在隔离环境中执行的 JavaScript/TypeScript 相结合。

客户端兼容性

Thoughtbox 目前针对 Claude Code 进行了优化。我们正在积极开发对更多 MCP 客户端的支持。由于 MCP 生态系统中各项能力的支持情况存在差异——包括服务端功能（提示词、资源、工具）、客户端功能（根目录、采样、引导），以及 listChanged 通知等行为——我们针对许多客户端实现了自定义适配。

如果你使用的客户端不是 Claude Code，并遇到问题，请提交问题，说明你使用的客户端和遇到的问题。

安装

Thoughtbox 以基于 Docker 的 MCP 服务形式运行。它需要 Docker 和 Docker Compose。

快速开始

git clone https://github.com/Kastalien-Research/thoughtbox.git
cd thoughtbox
docker compose up --build

这会启动 Thoughtbox 和完整的可观测性技术栈。MCP 服务监听端口 1731，Observatory UI 可通过 http://localhost:1729 访问。

MCP 客户端配置

由于 Thoughtbox 使用 HTTP 传输，请将 MCP 客户端配置为通过 URL 连接。

Claude Code

将以下内容添加到 ~/.claude/settings.json 或项目的 .claude/settings.json 中：

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

如需通过可观测性 sidecar 连接（会添加 OpenTelemetry 跟踪）：

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Cline / VS Code

将以下内容添加到 MCP 设置或 .vscode/mcp.json 中：

{
  "servers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

使用示例

正向思考 — 问题分析

Thought 1: "Users report slow checkout. Let's analyze..."
Thought 2: "Data shows 45s average, target is 10s..."
Thought 3: "Root causes: 3 API calls, no caching..."
Thought 4: "Options: Redis cache, query optimization, parallel calls..."
Thought 5: "Recommendation: Implement Redis cache for product data"

逆向思考 — 系统设计

Thought 8: [GOAL] "System handles 10k req/s with <100ms latency"
Thought 7: "Before that: monitoring and alerting operational"
Thought 6: "Before that: resilience patterns implemented"
Thought 5: "Before that: caching layer with invalidation"
...
Thought 1: [START] "Current state: 1k req/s, 500ms latency"

分支 — 比较备选方案

Thought 4: "Need to choose database architecture..."

Branch A (thought 5): branchId="sql-path"
  "PostgreSQL: ACID compliance, mature tooling, relational integrity"

Branch B (thought 5): branchId="nosql-path"
  "MongoDB: Flexible schema, horizontal scaling, document model"

Thought 6: [SYNTHESIS] "Use PostgreSQL for transactions, MongoDB for analytics"

环境变量

变量	说明	默认值
DISABLE_THOUGHT_LOGGING	禁止将思路记录到 stderr	false
THOUGHTBOX_DATA_DIR	持久化存储的基础目录	~/.thoughtbox
THOUGHTBOX_PROJECT	用于隔离会话的项目范围	_default
THOUGHTBOX_TRANSPORT	传输类型（stdio 或 http）	http
THOUGHTBOX_STORAGE	存储后端（fs、memory 或 supabase）	fs
THOUGHTBOX_OBSERVATORY_ENABLED	启用 Observatory Web UI	false
THOUGHTBOX_OBSERVATORY_PORT	Observatory UI 端口	1729
THOUGHTBOX_OBSERVATORY_CORS	Observatory 的 CORS 来源（以逗号分隔）	（无）
THOUGHTBOX_AGENT_ID	预先分配的 Hub Agent ID	（无）
THOUGHTBOX_AGENT_NAME	预先分配的 Hub Agent 名称	（无）
SUPABASE_URL	Supabase 项目 URL（使用 supabase 存储时必需）	（无）
SUPABASE_SERVICE_ROLE_KEY	Supabase 服务角色密钥（使用 supabase 存储时必需）	（无）
PORT	HTTP 服务端口	1731
HOST	HTTP 服务绑定地址	0.0.0.0
NODE_ENV	Node 环境	（无）
PROMETHEUS_URL	Prometheus 端点（Docker）	http://prometheus:9090
GRAFANA_URL	Grafana 端点（Docker）	http://grafana:3000

开发

本地开发（需要 Node.js 22+）：

pnpm install
pnpm build
pnpm dev      # Development with hot reload

测试

npx vitest run              # Unit tests
pnpm test                   # Full suite (build + vitest)
pnpm test:agentic           # Agentic tests — full suite (build + run)
pnpm test:agentic:tool      # Agentic tests — tool-level only
pnpm test:agentic:quick     # Agentic tests — quick (no build)
pnpm test:behavioral        # Behavioral contract tests

Docker Compose

docker compose up --build 可启动完整技术栈：

服务	端口	说明
thoughtbox	1731 (MCP), 1729 (Observatory)	核心 MCP 服务 + Observatory 界面
mcp-sidecar	4000	集成 OpenTelemetry 的可观测性代理
otel-collector	4318 (HTTP), 8889 (metrics)	OpenTelemetry Collector
prometheus	9090	指标存储 + 告警
grafana	3001	仪表板和可视化

持久化数据存储在命名卷中：thoughtbox-data、prometheus-data、grafana-data。

架构

src/
├── index.ts                # Entry point (Streamable HTTP transport)
├── server-factory.ts       # MCP server factory with tool registration
├── thought-handler.ts      # Core thought recording logic
├── types.ts                # Shared type definitions
├── database.types.ts       # Supabase generated types
├── code-mode/              # Code Mode tool surface
│   ├── search-tool.ts      # thoughtbox_search — catalog query via JS
│   ├── execute-tool.ts     # thoughtbox_execute — operation chaining via tb SDK
│   ├── search-index.ts     # Frozen catalog of operations/prompts/resources
│   └── sdk-types.ts        # TypeScript definitions for the tb SDK
├── thought/                # Thought operations and tool definitions
├── sessions/               # Session management
├── persistence/            # Storage layer
│   ├── storage.ts          # InMemoryStorage with LinkedThoughtStore
│   ├── filesystem-storage.ts  # FileSystemStorage with atomic writes
│   └── supabase-storage.ts # SupabaseStorage for deployed/cloud usage
├── observatory/            # Real-time visualization
│   ├── ui/                 # Self-contained HTML/CSS/JS
│   └── ws-server.ts        # WebSocket server for live updates
├── hub/                    # Multi-agent collaboration
│   ├── identity.ts         # Agent registration
│   ├── workspace.ts        # Workspace management
│   ├── problems.ts         # Problem tracking with dependencies
│   ├── proposals.ts        # Solution proposals with reviews
│   ├── consensus.ts        # Decision recording
│   ├── channels.ts         # Problem-scoped messaging
│   ├── hub-handler.ts      # Hub operation dispatcher
│   └── operations.ts       # 28-operation catalog
├── channel/                # Hub event channels and SSE streaming
├── protocol/               # Ulysses and Theseus protocol tools
├── knowledge/              # Knowledge graph memory
├── auth/                   # API key authentication
├── audit/                  # Audit manifest generation
├── evaluation/             # LangSmith evaluation and online monitoring
├── notebook/               # Literate programming engine
├── events/                 # Event emission system
├── observability/          # Prometheus/Grafana integration
├── prompts/                # MCP prompt definitions
├── references/             # Anchor parsing and resolution
├── revision/               # Revision indexing
├── operations-tool/        # Operations tool handler
└── resources/              # Documentation and patterns cookbook

存储

Thoughtbox 支持三种存储后端：

• InMemoryStorage：用于测试的易失性存储，使用 LinkedThoughtStore 实现 O(1) 思想查找
• FileSystemStorage：支持原子写入和项目隔离的持久化存储（默认）
• SupabaseStorage：基于 Supabase Postgres 的云原生存储，适用于已部署的实例

默认情况下，数据存储在 ~/.thoughtbox/ 中（FileSystemStorage）：

~/.thoughtbox/
├── config.json           # Global configuration
└── projects/
    └── {project}/
        └── sessions/
            └── {date}/
                └── {session-id}/
                    ├── manifest.json
                    └── {thought-number}.json

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解以下内容：

• 开发环境设置
• 提交规范（针对 thick_read 代码理解进行了优化）
• 使用 vitest 和智能体脚本进行测试
• 拉取请求流程

许可证

MIT License — 可免费使用、修改和分发。