Claude Traced 是一个 Electron 桌面应用，通过 ACP（Agent Client Protocol） 选择并驱动 Claude Code，搭配 Bun Sidecar 实现全链路 OpenTelemetry 可观测性。
- Electron 桌面壳 — 主进程管理窗口生命周期、拉起/回收 Sidecar；Renderer 使用 React
- ACP 驱动 Claude Code — Renderer 选择 Claude Code（默认），经 Main 进程通过 JSON-RPC 2.0 与之通信
- 全链路 Trace — Renderer
fetch携带traceparent，Sidecar 采集 Span，React Flow 可视化工具链 - 纯 Web 模式 — 保留
dev:web+dev:api模式，不依赖 Electron 也可调试
claude-traced/
├── apps/
│ ├── desktop/ # Electron 桌面壳（主进程 + 预加载脚本 + Renderer）
│ ├── web/ # React 渲染层（Electron Renderer / 纯 Web 双模式）
│ └── api/ # Bun 后端 API（Sidecar，由 desktop 主进程拉起）
│
├── packages/
│ ├── shared/ # 跨端类型、常量、工具
│ ├── tracing-claude/ # Claude / GenAI Span 封装（不含 OTEL Provider）
│ ├── tracing-react/ # 前端 Trace Hook / fetch 包装
│ ├── electron-ipc/ # Main ↔ Renderer IPC 通道定义
│ ├── acp-client/ # ACP Client 协议层（JSON-RPC、Session、权限）
│ ├── domain-agent/ # Agent 业务域
│ ├── domain-conversation/ # 会话 / 消息业务域
│ ├── domain-tool/ # Tool 注册与执行业务域
│ └── domain-user/ # 用户 / 鉴权业务域
│
├── docs/ # 技术文档（00–10）
├── scripts/ # 开发 / 部署 / 打包脚本
├── infra/ # 可观测性基础设施（OTEL Collector、Jaeger/Tempo）
├── electron-builder.yml # 桌面端打包配置
├── .env.example
├── bunfig.toml
├── package.json
├── tsconfig.base.json
└── README.md
# 1. 安装依赖
bun install
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，设置 ANTHROPIC_API_KEY
# 3. 启动可观测性基础设施（需要 Docker）
docker compose -f infra/docker/docker-compose.observability.yml up -d
# 4. 启动 API Sidecar（单独调试用）
bun run dev:api
# 5. 启动纯 Web 模式（浏览器调试）
bun run dev:web
# 6. 启动 Electron 桌面模式（推荐）
bun run dev:desktop| 业务模块 | 主要 Span | 说明 |
|---|---|---|
features/chat |
— | 触发请求；traceparent 由 tracedFetch 携带 |
ChatService |
http.server |
Bun 入站请求根 Span |
ChatService + Claude |
invoke_agent |
单次 Agent 调用 |
ToolOrchestrator |
execute_tool |
每个 Tool 一次子 Span |
claude/client |
llm_request（可选） |
直连 Messages API |
claude/subprocess |
继承父 Trace | 通过 TRACEPARENT 关联 CLI Span |
features/tools/graph |
— | Span / ToolRun → React Flow 流程图 |
features/trace/TraceDebugPage |
— | Debug 页流程图 Tab |
apps/desktop/main |
— | 窗口 + Sidecar 生命周期 |
apps/desktop/preload |
— | IPC 桥，Renderer 不直接访问 Node |
features/agent/AcpAgentSelector |
— | Renderer 选择 Claude Code（ACP） |
packages/acp-client |
— | ACP JSON-RPC Client |
apps/desktop/main/acp |
— | ACP Agent stdio 桥 + TRACEPARENT |
- 运行时: Bun 1.3
- 桌面壳: Electron 33
- 前端: React 19 + Vite 6 + TypeScript 5.7
- 可视化: @xyflow/react（React Flow）+ dagre 自动布局
- 协议: ACP（Agent Client Protocol）— JSON-RPC 2.0
- Agent: @agentclientprotocol/claude-agent-acp → Claude Code
- 可观测性: OpenTelemetry SDK 1.29（sdk-trace-base）
- Trace 传播: W3C Trace Context（traceparent）
- Exporter: OTLP HTTP → OpenTelemetry Collector
- 可视化: Jaeger / Grafana Tempo
# 类型检查
bun run lint
# 构建所有包
bun run build
# 构建桌面安装包
bun run build:desktop
# 检查环境变量
bun run check:env
# 种子数据
bun run seed详见 docs/ 目录:
- 00-overview — 项目概述
- 01-architecture — 架构与 Trace 拓扑
- 02-deps-and-workspace — 依赖与 Workspace
- 03-server-sdk — sdk-trace-base 初始化
- 04-bun-runtime — Bun Context、HTTP、子进程
- 05-claude-instrumentation — GenAI 语义约定
- 06-react-client — 前端埋点模式
- 07-debugging — 联调与断链排查
- 08-production-checklist — 生产 Checklist
- 09-electron-desktop — Electron 主进程、Sidecar、打包
- 10-acp-claude-code — ACP 协议、Claude Code 选择与会话
MIT