⚡ Traceplane

Multi-Agent Continuity Layer

让多个 Agent 的工作接成一条不断档、可回看、可交接的工作主线。

🌐 官网 · 📦 文档 · 🐛 Issues · 💬 讨论

---

为什么需要 Traceplane？

当你同时使用多个 AI Agent（Claude Code、OpenCode、Gemini CLI……），你会发现：

痛点	后果
同样的上下文反复讲给不同 Agent	浪费 token，信息不一致
Agent 做到一半，另一个接不上	工作断档，重复劳动
工作散落在聊天记录和文件里	无法复盘，无法追溯

Traceplane 解决的核心问题：不是让 Agent 更聪明，而是让 Agent 之间的工作不断档。

---

产品界面

Project Overview KPI 仪表盘 + Episode 列表 + 实时事件流	Episode Detail 执行时间线 + Trace 可视化 + Artifact 追溯
Dashboard 运行时健康状态 + 全局治理指标	Website Terminal Brutalist 官网 · 中英双语

---

核心概念

🧠 Episode — Agent 的意识载体

Episode 是系统主索引。不是附件字段，不是日志行——是一个完整的执行上下文，可恢复、可复用、可交接。

🔄 Surgical Replay — 像 git 一样回到过去

从任意执行节点 Fork 出新路径。git checkout 回到代码的某个状态，Traceplane 回到 Agent 工作的某个状态。

🤝 Handoff Brief — 无损交接

自动生成交接文档：目标、上下文、产物、风险。下一个 Agent 直接基于 brief 继续，不丢信息，不偏意图。

👁️ Full-Stack Observability — 一体化追踪

Agent 行为、Artifact 沉淀、风险指标在同一块舞台里被看到。每个事件可回链到来源 trace。

---

快速开始

安装

git clone https://github.com/jaxxchen003/Traceplane.git
cd Traceplane
npm install
cp .env.example .env
# 确保 .env 里的 DATABASE_URL 指向可访问的 Postgres 实例
npm run db:setup
npm run dev
# → http://localhost:3000

Agent SDK（推荐）

import { TraceplaneSDK } from '@traceplane/agent-sdk';

const sdk = new TraceplaneSDK({
  baseUrl: 'http://localhost:3000',
  projectId: 'customer-pulse',
  agentId: 'claude-code'
});

// 创建 Episode
const session = await sdk.startEpisode({
  title: '分析客户反馈',
  goal: '生成周报'
});

// 追踪每一步
await session.step('收集数据', '已收集500条反馈');
await session.toolUse('sentiment-analyzer', '分析', '完成');

// 完成 — 上下文已保存，随时可交接
await session.complete('周报生成完毕');

REST API

# 创建 Episode
curl -X POST http://localhost:3000/api/episodes \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "q2-customer-pulse",
    "primaryAgentId": "research-agent",
    "titleI18n": {"zh": "分析任务", "en": "Analysis Task"},
    "goalI18n": {"zh": "目标", "en": "Goal"}
  }'

MCP 工具

npm run mcp:host -- claude-code .mcp.json

# Agent 现在可以直接调用：
# create_episode · append_trace · write_memory · create_artifact · get_episode_brief
# get_orchestrator_context · register_subtask · report_subtask_result · get_task_graph_status

---

数据与监控

Traceplane 内置完整的使用分析能力，无需额外部署第三方工具。

功能	位置	说明
Episode 统计	/projects	查看各项目的 Episode 数量、活跃度
审计日志	/audit	权限拒绝、策略命中、关键读写事件
实时事件流	项目详情页	SSE 推送的实时执行事件
Agent 接入状态	/connect	各 Host 的最新信号和接入状态

自托管友好：所有数据存储在你自己的 Postgres 实例中，不经过第三方服务器。

如需接入外部分析，可配置 Google Analytics 4（NEXT_PUBLIC_GA_MEASUREMENT_ID in .env）。

---

Agent 接入支持

Agent	SDK	MCP	状态
Claude Code	✅	✅	Ready
OpenCode	✅	✅	Ready
Gemini CLI	✅	✅	Ready
自定义 Agent	✅	—	Ready

---

技术栈

层	选型	原因
Framework	Next.js 16 (App Router)	SSR + API Routes 一体
UI	React 19 + Tailwind v4	组件化 + CSS-first 主题
Database	Postgres / Supabase Postgres	本地自托管，云端可扩展
Object Storage	Cloudflare R2	S3 兼容，无出站费
Agent Protocol	MCP (Model Context Protocol)	Claude / OpenCode / Gemini 通用
SDK	TypeScript	类型安全，零依赖

---

API 参考

Core APIs

端点	方法	说明
/api/projects	POST	创建 Project
/api/agents	POST	注册 Agent
/api/episodes	POST	创建 Episode
/api/episodes/{id}/status	PATCH	更新状态
/api/episodes/{id}/context	GET	获取机器可读的恢复上下文
/api/episodes/fork	POST	Fork Episode
/api/episodes/brief	GET	获取交接文档
/api/episodes/link	POST	连接 Episode 关系
/api/traces	POST	上报 Trace
/api/memory	POST/GET	Memory CRUD
/api/artifacts	POST	创建 Artifact
/api/task-graphs	POST	创建 Task Graph
/api/task-graphs/{id}/status	GET	查询 Task Graph 聚合状态
/api/webhooks/symphony	POST	接收 Symphony 运行时事件
/api/events/stream	GET	SSE 实时事件
/api/graph	GET	查询节点关系图
/api/audit	GET	查询审计事件

MCP Tools

工具	说明
create_episode	创建 Episode
update_episode_status	更新 Episode 生命周期状态
link_episode	连接两个 Episode 的工作关系
append_trace	上报 Trace
write_memory	写入 Memory
create_artifact	创建产物
query_context	查询项目和 Episode 相关上下文
get_episode_brief	获取交接文档
get_orchestrator_context	获取 Symphony Orchestrator 恢复上下文
register_subtask	将 worker subtask 注册为 Task Graph Episode
report_subtask_result	上报 worker Episode 结果并更新聚合状态
get_task_graph_status	查询 Task Graph 聚合进度

---

项目结构

traceplane/
├── app/                    # Next.js App Router
│   ├── api/                # REST API 路由
│   └── [locale]/           # i18n 页面路由
├── components/             # React 组件
├── packages/agent-sdk/     # Agent SDK (TypeScript)
├── scripts/                # 工具脚本
├── prisma/                 # 数据模型
├── examples/               # 集成示例
├── tests/                  # 测试套件
└── docs/                   # 文档

---

测试

# SDK 单元测试
cd packages/agent-sdk && npm test

# API 集成测试
npm run test:run

# 覆盖率
npm run test:coverage

---

开源策略

Traceplane 采用 MIT + Open Core 模式：

• Core（本仓库）：MIT 协议，完全开源免费
• Enterprise：高级治理、RBAC、合规审计等功能为付费扩展

详见 ENTERPRISE_PREVIEW.md

---

贡献

我们欢迎所有形式的贡献！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交改动：git commit -m 'feat: add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

详见 CONTRIBUTING.md

---

☕ 支持这个项目

如果 Traceplane 对你有帮助，欢迎请我喝杯咖啡！

---

让 Agent 工作在一条连续的主线上，不再断档。

Made with ⚡ by jaxxchen · MIT License