Tracewood：将 AI 编码 Agent 遥测数据变为 3D 森林可视化

Tracewood：将 AI 编码 Agent 遥测数据变为 3D 森林可视化 | 前端进阶之旅

Full translation

完整中文译文

Introduction: Beyond Flat Dashboards

过去的两年里，我们与代码之间的关系发生了根本性的变化。我们不再手工逐字逐句地编写代码，而是与自主运行的 AI 编程 Agent 结对编程——如 Claude Code、Cursor、GitHub Copilot、Windsurf、Cline 和 Aider。

这些 Agent 会执行数千次工具调用，生成涉及多个文件的 diff，重构整个模块，并在后台测试实现。然而，这些工作的呈现方式仍然被困在干燥的 CLI stdout 日志或短暂的聊天侧边栏中。

如果你的编程历史不是一个日志文件，而是一片活的数字森林呢？

在 Tracewood 中，你创建的每一个项目都是一棵有机的 3D 树。树干随着工具执行次数增加而变粗，树枝沿着语义开发主题生长，枝叶簇在为每一个完成的 Agent 会话绽放，地下发光的菌丝管道用 HydraDB 映射跨仓库的架构模式。

以下是我们的构建方法。

1. System Architecture

Tracewood 采用本地优先架构。它不需要任何合成种子数据，立即摄取安装在机器上的任何编程 Agent 的原始记录。

┌────────────────────────────────────────────────────────────────────────┐
│                        10+ LOCAL AGENT SOURCES                         │
│   Claude Code · Cursor · Copilot · Windsurf · Cline · Aider · Gemini   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Raw JSONL / SQLite / Markdown
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      UNIVERSAL INGESTION ENGINE                        │
│             Normalizes Tool Calls, Diffs, Timestamps & CWD             │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Normalized Nodes & Edges
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      HYDRADB GRAPH CONTEXT ENGINE                      │
│   • Entities: Project, Topic, Session, ToolEvent, DecisionNode         │
│   • Edges: CONTAINS, SHARED_PATTERN_WITH, OVERWROTE, DEPENDS_ON        │
│   • Traversals: Mycelium Connectivity & Overwrite Conflict Detection   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Graph Stream & Events
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      3D PROCEDURAL VISUALIZER                          │
│   • React Three Fiber (R3F) Canvas                                     │
│   • Organic Phyllotaxis / Sunflower Spiral Forest Distribution         │
│   • Curved Trunk Splines, Soft Leaf Shaders & Mycelium Bezier Conduits │
│   • Smooth 360° Flying Camera & Interactive Glass HUD                  │
└────────────────────────────────────────────────────────────────────────┘

2. Ingesting Real Telemetry Without Seed Data

Tracewood 的一个主要架构要求是零配置：你启动应用程序的那一刻，它就应该反映你实际的编程历史。

通用爬虫（src/ingestion/universal/index.ts）查询现代 AI 编程 Agent 在 macOS/Linux 上存储会话日志的标准目录：

// Example: Concurrently discovering installed agents
const [claudeSess, cursorSess, copilotSess, windsurfSess, clineSess] = await Promise.all([
  scanClaudeHistory(),    // ~/.claude/projects/ & ~/.claude/history.jsonl
  scanCursorHistory(),    // ~/Library/Application Support/Cursor/User/workspaceStorage/
  scanCopilotHistory(),   // ~/.copilot/ & VS Code Chat telemetry
  scanWindsurfHistory(),  // ~/.codeium/ & Windsurf Cascade logs
  scanClineHistory()      // ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/tasks/
]);

每个会话都被规范化为统一结构：

工作区路径与项目名称
语义意图（feature、refactor、bugfix、exploration）
工具调用速率（如 bash 命令、文件编辑、git 操作）
结果状态（success、failed、interrupted）

Important Architectural Decisions

3. HydraDB at the Core: Graph Modeling for Agent Memory

向量数据库擅长语义文本搜索，但在建模关系型、时间感知的 Agent 记忆时却力不从心：

Project B 中的 Agent 是在什么时候采用了在 Project A 中建立的架构模式的？
哪个会话覆盖或逆转了之前的设计决策？

这正是 HydraDB（src/database/hydra.ts）作为核心图上下文底层发挥作用的地方。

我们使用五种节点类型和四种方向性边关系来建模 Agent 生态系统：

export type HydraNodeType = 'Project' | 'Topic' | 'Session' | 'ToolEvent' | 'DecisionNode';
export type HydraEdgeType = 'CONTAINS' | 'SHARED_PATTERN_WITH' | 'OVERWROTE' | 'DEPENDS_ON';

1. Cross-Project Knowledge Web (Underground Mycelium)

在自然界中，菌丝网络在树木之间传递营养和化学信号。在 Tracewood 中，HydraDB 遍历图以寻找共享底层架构模式（如认证、数据库 schema、状态管理）的仓库：

public getMyceliumLinks(): MyceliumLink[] {
  const links: MyceliumLink[] = [];
  const projects = Array.from(this.nodes.values()).filter(n => n.type === 'Project');

  for (let i = 0; i < projects.length; i++) {
    for (let j = i + 1; j < projects.length; j++) {
      const topicsA = projectTopics[projects[i].id];
      const topicsB = projectTopics[projects[j].id];

      const shared = Array.from(topicsA).filter(t => topicsB.has(t) && t !== 'general');
      if (shared.length > 0) {
        links.push({
          id: `mycelium_${projects[i].id}_${projects[j].id}`,
          sourceProjectId: projects[i].id,
          targetProjectId: projects[j].id,
          topic: shared.join(', '),
          strength: Math.min(1.0, 0.3 + shared.length * 0.2),
          reason: `Shared architectural patterns: ${shared.join(', ')}`
        });
      }
    }
  }
  return links;
}

2. Tracking Agent Decision Overwrites (LongMemEval Track 3)

当 Agent 重构代码时，它通常会使之前的约束失效。HydraDB 将这些修订记录为指向 DecisionNode 实体的 OVERWROTE 边：

if (session.intent === 'refactor' || session.intent === 'bugfix') {
  const decisionId = `decision_${session.id}`;
  hydra.addNode({
    id: decisionId,
    type: 'DecisionNode',
    label: `Refactor in ${topic.name}`,
    properties: { description: session.summary },
    timestamp: session.startedAt
  });

  hydra.addEdge(session.id, decisionId, 'OVERWROTE', {
    reason: session.summary
  });
}

4. 3D Procedural Visualization with Three.js & R3F

将抽象的图数据转化为美观、响应式的 3D 世界需要精细的程序化数学：

1. Sunflower Spiral (Phyllotaxis) Tree Placement

我们使用黄金角（约 137.5°）叶序分布，而不是刚性的网格或把树推出屏幕的 sprawling ring：

const goldenAngle = 137.5 * (Math.PI / 180);
const spacing = 3.6;

projects.forEach((p, idx) => {
  const r = Math.sqrt(idx + 1) * spacing;
  const theta = idx * goldenAngle;

  const x = Math.cos(theta) * r;
  const z = Math.sin(theta) * r;
  positions[p.id] = [x, 0, z];
});

这样无论你有 3 个项目还是 100 个项目，森林都能自然地从中心向外扩展，零死角。

2. Curved Trunks and Fluffy Leaf Canopies

每棵树的树干由沿正弦曲线旋转堆叠的圆柱体段动态生成：

树干高度：与会话量成正比（height = min(8.0, 3.2 + sessions * 0.18)）
树干围长：与工具执行次数成正比
树冠：多层球体重叠的叶子云，带有自定义 emissive shader，在当天活跃时发光。里程碑式的突破会萌生金色的八面体。

3. Bioluminescent Mycelium Conduits

地下关系被渲染为发光的 3D 二次贝塞尔管道，它们潜入起伏的苔藓地形之下：

const curve = new THREE.QuadraticBezierCurve3(
  new THREE.Vector3(posA[0], 0.1, posA[2]),
  new THREE.Vector3((posA[0] + posB[0]) / 2, -0.15, (posA[2] + posB[2]) / 2),
  new THREE.Vector3(posB[0], 0.1, posB[2])
);

<mesh>
  <tubeGeometry args={[curve, 24, 0.08, 6, false]} />
  <meshStandardMaterial
    color="#81c784"
    emissive="#388e3c"
    emissiveIntensity={0.6}
    transparent
    opacity={0.65}
  />
</mesh>

通过将 AI 编程 Agent 遥测、 HydraDB 的图数据库关系和实时 3D 程序化图形相结合，Tracewood 证明了开发者可观测性不必是一组柱状图的仪表盘。它可以是一个你想要探索、分享和反思的活的数字花园。

快去查看代码，启动你自己的本地森林，并告诉我们你种出了什么！

Code & more: https://www.dailybuild.xyz/project/225-tracewood