为什么需要 Traceplane？

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

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
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

数据与监控

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

自托管友好：所有数据存储在本地 SQLite/Postgres，不经过第三方服务器。

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

Agent 接入支持

技术栈

API 参考

Core APIs

MCP Tools

项目结构

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