项目简介

TraceBase 是一个面向 AI 编码代理的机构知识管理系统，旨在帮助代理避免重复探索已知的死胡同，从而提升问题解决效率并降低推理成本。

该系统的核心价值主张是：不是模型能力不足，而是代理在每次调用时都会重新探索死胡同。TraceBase 通过三字段追踪格式对问题情境、避免方案和解决方案进行编码，引导模型绕过失败模式，减少浪费的步骤和错误输出。

资料来源：www/src/app/whitepaper/page.tsx

核心架构

两阶段检索系统

TraceBase 采用两阶段检索排名架构，结合六种检索信号实现精准知识匹配：

graph TD
    A[用户查询] --> B[第一阶段: 候选集缩小]
    B --> C[Fingerprint 指纹匹配]
    B --> D[BM25 FTS5 全文搜索]
    C --> E[第二阶段: 重排]
    D --> E
    E --> F[结构相似度]
    E --> G[余弦相似度]
    E --> H[新鲜度]
    E --> I[权重学习 Thompson采样]
    F --> J[最终排名结果]
    G --> J
    H --> J
    I --> J

资料来源：www/src/app/whitepaper/page.tsx

追踪格式设计

追踪格式遵循四个研究原则，采用三字段结构编码知识：

graph LR
    A[问题情境] --> D[Situation]
    B[避免方案] --> E[Dead Ends]
    C[解锁方案] --> F[Unlock]
    D --> G[验证方法 Verification]
    E --> G
    F --> G

三字段追踪结构：

资料来源：src/core/block-serving.ts

注入有效载荷构建

系统通过 build-injection-payload.ts 将追踪知识注入到代理上下文中：

// 导入标签用于区分外部导入的修复方案
const IMPORTED_TAG_OPEN = `<prior_fix source="imported">`;
const IMPORTED_TAG_CLOSE = `</prior_fix>`;

// 紧凑格式渲染示例：
// • <Situation, capitalized>. Mechanism: <…>. Fix: <unlock>. Verify: <verification>.
// (Avoid: a; b 仅在存在死胡同时添加)

资料来源：src/core/build-injection-payload.ts

安全防护机制

防护墙系统

TraceBase 内置多层安全防护，防止恶意注入攻击：

graph TD
    A[用户输入] --> B{防护墙检查}
    B --> C[system-spoof 检测]
    B --> D[delimiter-spoof 检测]
    B --> E[secret-exfil 检测]
    C --> F{通过?}
    D --> F
    E --> F
    F -->|是| G[允许通过]
    F -->|否| H[拦截并记录]

资料来源：src/core/guard.ts

防护设计原则

1. 反跳过头检查：文档化的标签（如 ` <system> `）不会触发匹配
2. 边界限制：对短术语（如 env）设置更严格的检测阈值
3. 注入前缀信任继承防护：防止攻击者通过伪造分隔符继承系统信任级别

资料来源：src/core/guard.ts

评估体系

基准测试方法

TraceBase 使用多轮评估方法验证系统效果：

graph LR
    A[Round 0] -->|空知识库| B[基线测试]
    B -->|成功补丁| C[生成追踪]
    C --> D[Round 1]
    D -->|热知识库| E[对比测试]
    E --> F{结果对比}
    F -->|准确率提升| G[验证有效]
    F -->|无变化| H[需优化]

资料来源：www/src/app/whitepaper/page.tsx

评估指标体系

资料来源：www/src/app/whitepaper/page.tsx

应用集成

仪表板功能

TraceBase 提供 Web 仪表板用于管理项目和工作区：

资料来源：www/src/components/dashboard/OverviewView.tsx

工程师大脑模块

IssuesView 组件提供对 GitHub Issue、PR 和 CI 失败的一体化视图：

graph TD
    A[连接仓库] --> B[拉取 Issues]
    B --> C[拉取 PRs]
    C --> D[拉取 CI 失败]
    D --> E[生成背景笔记]
    E --> F[代理可用的只读上下文]

用户可通过 Generate background notes 功能生成代理可用的上下文，包含相关文件、相关工作和先前经验。

资料来源：www/src/components/engineering-brain/IssuesView.tsx

快速启动

用户可通过 CLI 快速集成项目：

npx tracebase-ai init

该命令在项目目录中创建链接，使项目出现在工作区仪表板中。

资料来源：www/src/components/dashboard/OverviewView.tsx

技术栈概览

复现指南

所有基准测试代码、fixture、种子和原始轨迹数据均开源在仓库中：

复现命令：

pip install mini-swe-agent
npx tsx eval/agentic/runner.ts --all     # TypeScript 基准测试
bash eval/swebench/run-benchmark.sh      # SWE-bench Verified

资料来源：www/src/app/whitepaper/page.tsx

许可与开源

TraceBase 采用 MIT 许可证开源，所有代码和文档可在公共仓库中获取。

前置要求

资料来源：src/cli/install-targets.ts:32-49

安装流程概览

graph TD
    A[运行 npx tracebase-ai init] --> B{检测 Agent 类型}
    B -->|Claude Code| C[创建 CLAUDE.md]
    B -->|Cursor| D[创建 AGENTS.md]
    B -->|Codex| E[配置 codex.json]
    C --> F[配置 MCP 服务]
    D --> F
    E --> F
    F --> G[运行 doctor 检查]
    G --> H{检查结果}
    H -->|通过| I[安装完成]
    H -->|警告| J[修复问题]
    J --> G
    H -->|失败| K[查看错误信息]

核心安装命令

交互式初始化

在项目根目录运行以下命令启动交互式安装流程：

npx tracebase-ai init

该命令会自动执行以下步骤：

1. 检测 Agent 类型 — 根据环境变量和项目文件判断当前使用的 Agent
2. 创建指令文件 — 为对应 Agent 生成配置指令文件
3. 配置 MCP 服务器 — 设置 TraceBase MCP 服务连接
4. 验证安装 — 运行环境检查确保配置正确

资料来源：src/cli/commands/init.ts、src/cli/install-targets.ts:32-49

Agent 自动检测逻辑

TraceBase 支持三种主流 Agent 平台，检测优先级如下：

// 检测优先级代码逻辑
function detectAgentFromEnvironment(): InstallAgent | null {
  if (process.env.CODEX_SHELL === "1" || process.env.CODEX_CI === "1") {
    return "codex";
  }
  if (process.env.CURSOR_TRACE_ID || process.env.TERM_PROGRAM?.toLowerCase() === "cursor") {
    return "cursor";
  }
  if (process.env.CLAUDE_CODE || process.env.CLAUDE_DESKTOP) {
    return "claude-code";
  }
  return null;
}

资料来源：src/cli/install-targets.ts:32-49

为特定 Agent 安装

如需强制指定 Agent 类型：

# 仅为 Claude Code 安装
npx tracebase-ai init --agent claude-code

# 仅为 Cursor 安装
npx tracebase-ai init --agent cursor

安装后检查

运行 doctor 命令

安装完成后，务必运行健康检查以确保所有组件正常工作：

npx tracebase-ai doctor

doctor 命令执行以下检查项：

// Hook 检查逻辑
const hookInspection = inspectAgentHookConfig(projectRoot, agent);
if (hookInspection.supported) {
  const managedEvents = hookEventsForAgent(agent);
  const states = managedEvents.map(
    (e) => [e, hookInspection.events[e] ?? "missing"] as const,
  );
  const missing = states.filter(([, s]) => s === "missing");
  // 报告缺失的 Hook 事件
}

资料来源：src/cli/commands/doctor.ts:1-50

警告级别处理

doctor 命令会以不同级别报告问题：

当检测到缺少托管区块时，doctor 会提示：

warn: instruction file exists but managed section is missing
fix: Re-run `npx tracebase-ai init` to append the managed block.

资料来源：src/cli/commands/doctor.ts:10-24

仪表板使用

初始化成功后，访问 TraceBase 仪表板查看和管理安装状态。

访问入口

仪表板提供以下视图：

#### 概览视图 (OverviewView)

显示所有已链接项目的最近活动记录：

// 活动列表组件
function ActivityRow({ install }: { install: DashboardBootstrap["installations"][number] }) {
  return (
    <li>
      <CardHeaderRow
        icon={<IconRocket />}
        actor={install.projectName}
        meta={<>{install.agent} · cli {install.cliVersion}</>}
      />
    </li>
  );
}

无活动时显示引导信息：

No activity yet
Run `npx tracebase-ai init` in a project to link it here.
Once your agent uses a memory, this list fills in.

资料来源：www/src/components/dashboard/OverviewView.tsx

#### 安装管理视图 (InstallationsView)

查看所有已链接的安装：

// 安装列表渲染
{installations.map((install) => (
  <li key={install.id}>
    <CardHeaderRow
      icon={<IconAgent />}
      actor={install.projectName}
      meta={<>{install.agent} · cli {install.cliVersion}</>}
    />
    <div>linked {formatRelativeTime(install.createdAt)}</div>
  </li>
))}

资料来源：www/src/components/dashboard/InstallationsView.tsx

#### API 密钥管理 (ApiKeysView)

为 CI 环境和无头环境创建 API 密钥：

// 创建密钥命令预览
const command = `TRACEBOUND_API_KEY=${newKey} npx tracebase-ai sync`;

重要提示：每个密钥仅在创建时显示一次，请妥善保管。

资料来源：www/src/components/dashboard/ApiKeysView.tsx

#### 影响分析视图 (ImpactView)

追踪 TraceBase 对 Agent 工作效率的实际影响：

graph LR
    A[Agent Tasks] --> B[Matched Memory]
    B --> C[Shown]
    C --> D[Used]
    D --> E[Win]

资料来源：www/src/components/dashboard/ImpactView.tsx

CI 环境配置

创建 API 密钥

在仪表板的 API Keys 页面创建密钥：

# 密钥创建后显示的命令
TRACEBOUND_API_KEY=your_key_here npx tracebase-ai sync

CI 脚本集成

将密钥配置为 CI 环境变量：

# .github/workflows/ci.yml 示例
env:
  TRACEBOUND_API_KEY: ${{ secrets.TRACEBOUND_API_KEY }}

# CI 中运行同步
npx tracebase-ai sync

资料来源：www/src/components/dashboard/ApiKeysView.tsx

常见问题

安装命令无响应

确保在项目根目录运行，且当前目录包含版本控制（如 .git）。

Agent 未被识别

手动指定 Agent 类型：

npx tracebase-ai init --agent claude-code

doctor 检查全部通过但 Agent 不工作

检查 Agent 的 Hook 配置是否包含以下事件：

• Stop Hook：会话结束时捕获记忆
• Before System Prompt Hook：注入相关记忆

仪表板显示无活动

1. 确认 Agent 会话使用了 TraceBase 记忆
2. 检查项目目录下的 .tracebase 配置是否正确
3. 运行 npx tracebase-ai status 查看详细状态

下一步

概述

TraceBase CLI 通过 npx tracebase-ai 或全局安装的 tracebase 命令调用。CLI 采用模块化架构，每个命令独立存在于 src/cli/commands/ 目录下：

graph TD
    A["tracebase CLI"] --> B["doctor"]
    A --> C["recall"]
    A --> D["search"]
    A --> E["events"]
    A --> F["impact"]
    A --> G["serve"]
    A --> H["remove"]
    A --> I["init"]
    A --> J["status"]

全局选项

所有命令支持以下全局选项：

命令详解

doctor

健康检查命令，用于诊断 TraceBase 在本地项目中的配置状态。

tracebase doctor [--agent <agent-name>]

参数说明：

检查项目：

doctor 命令执行以下诊断检查：

1. 指令文件检查 - 验证 CLAUDE.md 或 AGENTS.md 是否存在并包含托管区块 资料来源：src/cli/commands/doctor.ts

1. Hook 配置检查 - 针对 Claude Code 检查 .claude/settings.json 中的 hook 条目 资料来源：src/cli/commands/doctor.ts

1. MCP 配置检查 - 验证 MCP 服务器连接状态

1. 环境完整性检查 - 确保所有必需的配置文件存在

输出示例：

{
  "checks": [
    {
      "name": "claude-code-instruction",
      "level": "pass",
      "message": "managed section present"
    },
    {
      "name": "claude-code-hooks",
      "level": "warn",
      "message": "Stop hook is missing",
      "fix": "Run `tracebase init` to configure hooks."
    }
  ]
}

返回码：

概述

TraceBase 是一个面向编码代理（coding agent）的记忆层系统，旨在解决代理在长期任务中重复犯错、无法保留历史解决方案的问题。其核心设计理念是通过结构化的记忆存储与智能检索，让代理在遇到曾处理过的类似问题时，能够自动获取历史解决方案上下文，从而显著提升任务完成效率和准确性。

TraceBase 的架构围绕"安全注入"（safe injection）机制展开，确保代理收到的记忆信息可信、可用，同时防止恶意内容的注入攻击。

核心设计原则

TraceBase 的架构设计遵循以下关键原则：

• 记忆复用优先：系统不改变代理的决策流程，而是提供高质量的先验知识，让代理自行判断是否采纳 资料来源：src/core/build-injection-payload.ts:9-15
• 两阶段检索：先通过轻量级指纹（Fingerprint）和 BM25 全文搜索缩小候选集，再通过多信号重排序选出最优匹配 资料来源：docs/DESIGN_v2.md
• 安全注入防护：采用多层防护机制（guard），阻止恶意内容伪装成可信记忆注入代理上下文 资料来源：src/core/guard.ts:1-10
• 隐私与完整性并重：记忆数据可导入、可管理，代理仅接收只读背景信息，不会从这里接收指令 资料来源：www/src/components/engineering-brain/IssuesView.tsx:9-14

系统架构图

graph TD
    subgraph Agent["代理层 (Agent)"]
        A[Claude Code / Claude Agent]
        MCP[MCP Server]
    end

    subgraph Core["核心处理层 (Core)"]
        G[Guard<br/>安全防护]
        BS[Block Serving<br/>块服务]
        BP[Build Injection Payload<br/>载荷构建]
    end

    subgraph Storage["存储层 (Storage)"]
        Store[(Store<br/>主存储)]
        BlockStore[(Block Store<br/>块存储)]
        FP[Fingerprint<br/>指纹库]
    end

    subgraph Integration["集成层"]
        GH[GitHub Integrations]
        DB[Dashboard<br/>仪表板]
    end

    A --> MCP
    MCP --> G
    G --> BS
    BS --> BP
    BP --> Store
    BS --> BlockStore
    BS --> FP
    GH --> Store
    DB --> Store

核心模块

1. Guard 模块（安全防护）

Guard 是 TraceBase 的第一道防线，负责检测和阻止恶意的上下文注入攻击。它在记忆块进入系统前进行多层检查。

#### 检查类型

Guard 模块的设计特别考虑了"文档场景"：当用户讨论代码中的 <system> 标签时，不应被误判为注入攻击。通过精确的边界检查（如 backtick-neighbour skip 逻辑），Guard 能够区分真实注入与正常文档引用 资料来源：src/core/guard.ts:10-25

2. Block Serving 模块（块服务）

Block Serving 负责将存储中的记忆块转换为代理可读的格式，支持多种渲染输出。

#### 核心功能

块命中渲染（Block Hit Rendering）将记忆块转换为结构化文本或 XML 格式：

// XML 格式渲染示例
<hypothesis id="xxx" calibrated="0.85">
  <situation>问题描述</situation>
  <mechanism>问题机制</mechanism>
  <unlock>解锁方案</unlock>
  <verification>验证步骤</verification>
  <dead_ends>需避免的方案</dead_ends>
</hypothesis>

每个块包含以下元数据：

• calibratedProb：置信度校准概率
• id：唯一标识符
• evidence：引用证据列表 资料来源：src/core/block-serving.ts:20-40

3. Build Injection Payload 模块（载荷构建）

该模块负责将检索到的记忆块构建为最终的注入载荷，采用紧凑的文案格式直接呈现给代理。

#### 渲染格式

采用无序列表格式，每项包含：

• Situation：问题场景（大写开头）
• Mechanism：问题机制
• Fix：解锁方案
• Verify：验证步骤
• Avoid（可选）：死胡同/需避免的方案

// 示例输出
• <Situation, 首字母大写>. Mechanism: <机制描述>. Fix: <解决方案>. Verify: <验证方式>.
// 如有死胡同时：
• <Situation>. Mechanism: <…>. Fix: <…>. Verify: <…>. Avoid: a; b; c.

导入的记忆块会带有 <prior_fix source="imported"> 标签，便于代理识别来源 资料来源：src/core/build-injection-payload.ts:20-35

4. 存储层

#### Store 模块

主存储模块负责管理会话数据、安装信息和完整性校验。

#### Block Store 模块

结构化记忆块的核心存储，包含：

#### Fingerprint 模块

指纹模块提供 O(1) 时间复杂度的快速匹配能力，用于在大量候选中快速筛选潜在相关块。

5. Similarity 和 Weights 模块

#### 相似度计算

graph LR
    Q[查询 Query] --> R[候选块 Ranking]
    R --> F1[Fingerprint 指纹匹配]
    R --> B1[BM25 全文搜索]
    R --> S1[语义相似度]
    R --> W1[工作流匹配]
    R --> T1[任务类型匹配]
    F1 --> W[加权融合]
    B1 --> W
    S1 --> W
    W1 --> W
    T1 --> W
    W --> Rank[最终排序]

Weights 模块定义了四个重排序信号的权重配置：

1. 语义相似度：基于嵌入向量的余弦相似度
2. 工作流匹配：问题解决路径的相似性
3. 任务类型匹配：问题域的匹配程度
4. 上下文相关性：当前任务与历史记忆的关联度

检索流程

sequenceDiagram
    participant Agent as 代理
    participant Guard as Guard模块
    participant Retriever as 检索引擎
    participant Ranker as 排序器
    participant Payload as 载荷构建器

    Agent->>Guard: 发送记忆请求
    Guard->>Retriever: 验证通过，转发请求
    Retriever->>Retriever: 1. Fingerprint 快速筛选
    Retriever->>Retriever: 2. BM25 FTS5 全文搜索
    Retriever-->>Ranker: 返回候选集
    Ranker->>Ranker: 3. 四信号重排序
    Ranker-->>Payload: 返回排序结果
    Payload->>Payload: 构建紧凑注入文本
    Payload-->>Agent: 返回可注入的上下文

仪表板集成

TraceBase 提供 Web 仪表板用于可视化记忆使用情况：

影响视图（Impact View）

graph LR
    subgraph 漏斗
        E[Eligible] --> R[Recalled]
        R --> I[Injected]
        I --> U[Used]
    end

完整性检查

仪表板还提供完整性诊断，包括：

• Shadow Control Mismatches：影子控制不匹配数
• Outcomes Without Retrieval：无检索的结果数

这些非零值不推翻核心统计，但表明上游仪表化存在问题 资料来源：www/src/components/dashboard/ImpactView.tsx:50-80

代理集成

MCP 协议

TraceBase 通过 MCP（Model Context Protocol）协议与代理通信，作为可插入的记忆层（MCP Server）工作。

Hook 配置

支持代理级别的 Hook 配置，用于：

• 静默注入：后台自动添加记忆到上下文
• 背景捕获：在代理运行时捕获相关上下文
• 权限提示：当无法静默注入时的后备提示

doctor 命令用于检查这些配置的完整性，确保 MCP 和 Hook 都正确配置 资料来源：src/cli/commands/doctor.ts:40-60

GitHub 集成

TraceBase 支持与 GitHub 仓库集成，可以：

• 拉取 Issues 和 PR
• 获取 Review Comments
• 接入 CI 失败信息

这些信息可用于生成"背景笔记"，为代理提供项目相关的先验知识 资料来源：www/src/components/engineering-brain/IntegrationsView.tsx:1-30

安全模型

TraceBase 的安全模型建立在以下原则之上：

1. 最小信任原则：外部输入（GitHub Issues、导入数据）均经过 Guard 检查
2. 标签隔离：使用专属分隔符 <prior_fix> 和 <file_memory>，防止内容劫持
3. 只读背景：记忆层仅提供背景信息，代理不从此处接收命令
4. 可验证来源：每个记忆块携带来源追溯信息（traceId, role）

graph TD
    Input[外部输入] --> G1[Guard检查]
    G1 -->|通过| Process[处理流程]
    G1 -->|拒绝| Log[日志记录]
    Process --> Tag[添加专属标签]
    Tag --> Output[输出给代理]
    Output --> Readonly[只读背景]

配置与诊断

Doctor 命令

tracebase-ai doctor 命令执行全面的健康检查：

flowchart TD
    Start[doctor 命令] --> MCP1{MCP配置存在?}
    MCP1 -->|是| Doc1{CLAUDE.md存在?}
    Doc1 -->|是| Hook{Hook配置完整?}
    Hook -->|是| Pass[检查通过]
    Hook -->|否| WarnHook[警告: Hook缺失]
    Doc1 -->|否| WarnDoc[警告: 文档缺失]
    MCP1 -->|否| ErrMCP[错误: MCP未配置]

总结

TraceBase 采用分层架构设计，从底层的指纹索引和 BM25 全文搜索，到上层的重排序和载荷构建，形成了一套完整的记忆检索与安全注入管道。其核心优势在于：

• 高效的候选筛选：O(1) 指纹匹配 + FTS5 全文搜索
• 精确的相关性排序：四信号加权重排序
• 严密的安全防护：多层 Guard 机制
• 透明的记忆呈现：紧凑、结构化的无标记文本

这套架构使得 TraceBase 能够作为代理的"第二记忆系统"，在不改变代理原有行为的前提下，显著提升其在重复任务上的表现。

概述

TraceBase 是一个面向编程智能体的记忆层系统，它能够在多次运行之间保持过去的解决方案、文件含义和循环陷阱等信息。TraceBase 通过 MCP（Model Context Protocol）协议以即插即用方式集成，为 AI 编码助手提供持久化的上下文记忆能力。

核心组件体系围绕三个主要阶段构建：记忆生成与存储、检索与匹配、上下文注入。整个系统在保证安全性的前提下，通过多层信号重排序机制从代码库中提取高质量的先前经验，并在智能体执行任务时适时注入。

1. Guard（安全守卫机制）

1.1 概述

Guard 机制是 TraceBase 的第一道安全防线，负责对输入进行严格的安全校验。它通过正则表达式模式匹配来识别和阻止潜在的注入攻击、提示词泄露和虚假标记伪装。

1.2 核心检测规则

Guard 机制维护了一套多层次的安全检测规则集，每条规则都有明确的检测目标和防御目的。

1.3 backtick-neighbour skip 机制

Guard 机制特别处理了一种边界情况：当文档标记被反引号包裹时（如 ` <system> `），这表示用户在讨论提示词语法本身，而非尝试注入，因此跳过匹配检测。这种设计确保了安全性的同时不会干扰正常的文档编写。

资料来源：src/core/guard.ts:1-50

1.4 工作流程

graph TD
    A[用户输入] --> B{Guard 检查}
    B --> C{匹配 system-spoof?}
    C -->|是| D[拒绝请求]
    C -->|否| E{匹配 delimiter-spoof?}
    E -->|是| D
    E -->|否| F{匹配环境变量泄露?}
    F -->|是| D
    F -->|否| G[通过验证]

2. Tool Loop Detect（工具循环检测）

2.1 概述

Tool Loop Detect 机制负责监控代理的工具调用行为，识别可能导致死循环或无限重复的调用模式。当检测到异常的工具调用模式时，该机制会触发相应的处理逻辑，防止资源耗尽。

2.2 检测策略

该机制通过分析工具调用的时序特征和调用频率来识别潜在的循环问题。检测算法会维护一个滑动窗口，记录最近的工具调用历史，并基于以下维度进行分析：

• 相同工具的连续调用次数
• 调用序列的周期性模式
• 工具返回结果与输入的相似度

2.3 响应机制

当检测到循环模式时，系统会根据循环的严重程度采取不同的响应措施：

3. Context Fold（上下文折叠）

3.1 概述

Context Fold 机制是 TraceBase 的上下文管理核心，负责在长对话中智能地压缩和精简上下文内容，以保持在模型上下文窗口限制内的高效运行。

3.2 折叠策略

graph LR
    A[完整上下文] --> B{Token 预算检查}
    B -->|超出预算| C[识别低价值片段]
    B -->|在预算内| G[保持原样]
    C --> D[应用折叠策略]
    D --> E[生成摘要]
    E --> F[替换原始片段]
    F --> G[压缩后上下文]

3.3 折叠层级

Context Fold 采用多层级折叠策略，确保在保持关键信息完整的同时最大化压缩比：

3.4 上下文优先级

系统会为不同类型的上下文分配不同的保留优先级：

const PRIORITY_ORDER = {
  systemInstruction: 1,      // 最高优先级
  currentTask: 2,            // 当前任务描述
  criticalDecisions: 3,     // 关键决策点
  recentToolResults: 4,      // 近期的工具结果
  historicalAnalysis: 5,     // 历史分析过程
  explorationLogs: 6         // 探索日志 - 最先折叠
};

资料来源：src/core/context-fold.ts:1-80

4. File Walker（文件遍历器）

4.1 概述

File Walker 机制负责高效地遍历和分析项目文件结构，为检索增强生成（RAG）提供文件级别的上下文支持。它支持多种遍历策略和过滤规则，以适应不同规模和结构的项目。

4.2 遍历模式

4.3 过滤规则

File Walker 支持灵活的过滤规则配置：

interface WalkerConfig {
  maxDepth: number;           // 最大遍历深度
  includePatterns: RegExp[];  // 包含模式
  excludePatterns: RegExp[]; // 排除模式（如 node_modules, .git）
  followSymlinks: boolean;   // 是否跟随符号链接
  maxFileSize: number;       // 单文件最大字节数
}

4.4 增量遍历优化

对于大型项目，File Walker 支持增量遍历模式，仅扫描自上次遍历以来发生变化的文件：

graph TD
    A[完整遍历] --> B[记录文件状态]
    B --> C[等待触发]
    C --> D{增量触发?}
    D -->|是| E[计算差异]
    E --> F[仅遍历变更]
    D -->|否| G[完整遍历]

资料来源：src/core/file-walker.ts:1-100

5. Observe Tools（工具观察器）

5.1 概述

Observe Tools 机制负责监控和记录代理与外部工具的交互过程，提取有价值的上下文信息用于后续的记忆生成和检索。

5.2 文件路径标准化

不同的工具和 SDK 使用的文件路径字段名可能不同，Observe Tools 提供了统一的抽象层来处理这种差异：

const FILE_PATH_KEYS = [
  "file_path",    // Claude Code 规范
  "path",         // 常见通用字段
  "filename",     // 另一常见变体
  "filePath"      // 驼峰命名变体
] as const;

该机制会遍历这些可能的字段名，返回第一个有效值：

function extractFilePath(toolInput: unknown): string | null {
  if (typeof toolInput !== "object" || toolInput === null) return null;
  const obj = toolInput as Record<string, unknown>;
  for (const key of FILE_PATH_KEYS) {
    const v = obj[key];
    if (typeof v === "string" && v.trim().length > 0) return v;
  }
  return null;
}

资料来源：src/runtime/observe-tools.ts:1-30

5.3 观察事件类型

5.4 与记忆系统的集成

graph LR
    A[工具调用] --> B[Observe Tools 采集]
    B --> C[事件标准化]
    C --> D[关键信息提取]
    D --> E{是否满足记忆条件?}
    E -->|是| F[生成记忆片段]
    E -->|否| G[丢弃]
    F --> H[存储至记忆库]
    H --> I[供后续检索使用]

运行时机制协同架构

五大运行时机制并非独立运作，它们通过消息传递和状态共享形成了一个有机的协同体系。

graph TD
    subgraph 输入层
        A[用户输入]
    end
    
    subgraph 安全层
        B[Guard 验证]
    end
    
    subgraph 执行层
        C[Tool Loop Detect]
        D[Observe Tools]
    end
    
    subgraph 资源层
        E[Context Fold]
        F[File Walker]
    end
    
    subgraph 输出层
        G[代理响应]
        H[记忆存储]
    end
    
    A --> B
    B -->|通过| C
    B -->|拒绝| I[安全拦截]
    C --> D
    D --> E
    D --> F
    E --> G
    F --> H
    H --> E

协同工作流程

1. Guard 优先：所有输入首先经过 Guard 机制的安全验证，未通过验证的请求直接拦截。
2. 循环检测：通过验证的请求进入执行层，Tool Loop Detect 监控执行过程中的循环模式。
3. 上下文管理：Context Fold 根据当前上下文大小和 token 预算动态调整上下文内容。
4. 文件支持：File Walker 在需要时提供文件级别的上下文支持。
5. 观察记录：Observe Tools 全程记录工具交互，用于生成可复用的记忆片段。

配置与调优

运行时参数

监控与调试

TraceBase 提供了 doctor 命令用于检查运行时机制的健康状态：

npx tracebase-ai doctor

该命令会检查：

• Guard 规则的有效性
• 循环检测的配置状态
• 上下文管理的预算配置
• 文件遍历的路径配置

资料来源：src/cli/commands/doctor.ts:1-80

总结

五大运行时机制构成了 TraceBase 的核心保障体系：

• Guard 提供安全防护，过滤恶意输入
• Tool Loop Detect 防止执行陷入死循环
• Context Fold 确保上下文始终在有效范围内
• File Walker 提供高效的文件系统访问能力
• Observe Tools 采集有价值的交互信息用于记忆生成

这些机制相互配合，共同确保 AI 编码代理能够在安全、稳定、高效的环境中运行，为开发者提供可靠的编程辅助体验。

概述

TraceBase 的召回与检索机制是系统的核心模块，负责从历史记忆库中高效定位与当前任务相关的先前解决方案。该机制采用两阶段排序架构，结合六种不同的检索信号，通过 Thompson 采样动态学习信号权重，以实现高精度的记忆匹配。

资料来源：www/src/app/whitepaper/page.tsx

概述

上下文折叠（Context Fold）是 TraceBase 为编码智能体（coding agents）设计的一种上下文管理机制。其核心目标是在多轮对话过程中，将历史交互内容进行结构化压缩，以减少 token 消耗同时保留关键决策信息。

根据项目白皮书描述，上下文折叠是 TraceBase 六种检索信号之一（指纹检索、BM25 全文搜索、结构化检索、余弦相似度检索、新鲜度检索），属于重排序（re-rank）阶段的组成部分。

资料来源：www/src/app/whitepaper/page.tsx

概述

TraceBase SDK 是 TraceBase 项目的核心组件，提供了一套完整的中间件和运行时系统，用于在 AI 编码代理的 API 调用过程中注入上下文记忆。该 SDK 支持多种主流 AI 提供商，包括 OpenAI 和 Anthropic，并通过统一的接口设计实现跨平台兼容性。资料来源：src/sdk/runtime.ts

SDK 的主要职责是在保持现有代码结构不变的前提下，无缝集成到编码代理的工作流程中。当代理发起 API 请求时，SDK 负责拦截、检索相关记忆、格式化上下文内容，并将其注入到请求载荷中，确保代理能够利用历史经验和已解决的类似问题来提升任务完成效率。

架构设计

TraceBase SDK 采用分层架构设计，核心由中间件层和运行时层组成。中间件层负责与具体 AI 提供商的 API 进行交互，拦截并处理请求响应；运行时层则负责记忆检索、上下文管理和注入逻辑。这种分层设计使得 SDK 能够轻松扩展支持新的 AI 提供商，同时保持核心逻辑的稳定性。资料来源：src/sdk/contextual-runtime-provider.ts

graph TD
    A[编码代理 Agent] --> B[TraceBase SDK]
    B --> C{AI 提供商类型}
    C -->|OpenAI| D[openai.ts 中间件]
    C -->|Anthropic| E[anthropic.ts 中间件]
    C -->|其他| F[generic.ts 中间件]
    D --> G[运行时运行时 Runtime]
    E --> G
    F --> G
    G --> H[记忆库 Knowledge Base]
    G --> I[上下文注入模块]
    I --> J[增强后的 API 请求]
    J --> K[AI 提供商]
    K --> L[AI 响应]

中间件层职责

中间件层是 SDK 与外部 AI API 之间的桥梁，负责处理提供商特定的请求格式和响应解析。每种支持的 AI 提供商都有对应的专用中间件模块，该模块负责将通用请求转换为特定提供商的格式，并解析返回的响应数据。中间件还负责注入特定的认证头、版本信息和元数据，确保与提供商 API 的完全兼容。

运行时层职责

运行时层是 SDK 的核心引擎，负责执行记忆检索和上下文注入的核心逻辑。当请求通过中间件到达运行时层时，系统会首先分析请求内容，提取关键信息如项目标识、任务类型和上下文线索。然后，运行时层会查询记忆库，检索与当前任务最相关的历史记录和解决方案。最后，系统会将检索到的记忆内容格式化为特定格式，注入到 API 请求的适当位置。资料来源：src/sdk/runtime.ts

支持的 AI 提供商

TraceBase SDK 通过专门的中间件模块支持多种主流 AI 提供商。每个中间件都针对相应提供商的 API 规范进行了优化，确保请求格式和响应处理的准确性。

OpenAI 中间件

OpenAI 中间件 (openai.ts) 专门处理 OpenAI 系列的 API 调用，包括 GPT-4、GPT-4-Turbo 等模型。该中间件支持 OpenAI 的标准 Chat Completions 格式，能够正确处理系统消息、用户消息和助手消息的注入。对于使用函数调用（Function Calling）功能的请求，中间件会智能地将上下文内容注入到函数描述和参数中，确保代理能够准确理解任务需求。

OpenAI 中间件还支持流式响应处理，在保持实时反馈的同时注入上下文信息。中间件会跟踪对话状态，确保在多轮对话场景中记忆检索的连贯性和准确性。资料来源：src/middleware/openai.ts

Anthropic 中间件

Anthropic 中间件 (anthropic.ts) 针对 Claude 系列模型进行了专门优化，支持 Anthropic 的 Messages API 格式。该中间件能够正确处理 Claude 的系统提示、用户消息格式，并支持工具使用（Tools）和多模态输入功能。

Anthropic 中间件在处理上下文注入时会考虑 Claude 的令牌限制和提示结构要求，确保注入的内容不会超出模型的上下文窗口，同时保留最重要的记忆信息。中间件还会分析对话历史，避免重复注入相同或相似的记忆内容。资料来源：src/middleware/anthropic.ts

通用中间件

通用中间件 (generic.ts) 为未提供专用中间件的 AI 提供商提供了标准化接口。该中间件遵循 REST API 的通用规范，支持自定义端点和方法，能够适应大多数基于 HTTP 的 AI 服务。

通用中间件的设计允许开发者通过配置文件指定请求格式、响应解析规则和上下文注入点，使其能够灵活适配各种 AI 服务提供商。这种设计大大扩展了 SDK 的适用范围，降低了集成新提供商的门槛。资料来源：src/middleware/generic.ts

上下文运行时提供者

上下文运行时提供者（Contextual Runtime Provider）是 SDK 的核心组件，负责协调中间件层和运行时层的交互。该组件维护了系统的运行状态，管理记忆检索的配置参数，并提供统一的接口供中间件调用。

运行时提供者采用延迟初始化策略，仅在首次需要时创建相关资源。这种设计减少了应用启动时的开销，同时保证了资源的高效利用。提供者还实现了连接池和缓存机制，优化了记忆检索的性能表现。资料来源：src/sdk/contextual-runtime-provider.ts

核心功能

上下文运行时提供者提供以下核心功能：记忆检索配置管理运行时状态跟踪、性能指标收集、错误处理和重试逻辑、以及与外部记忆库的安全通信。所有这些功能都通过统一的异步接口暴露，确保了良好的可测试性和可维护性。

上下文注入机制

TraceBase SDK 的上下文注入机制是实现记忆共享的关键。该机制能够将检索到的历史记忆、解决方案和经验教训，以结构化的方式注入到 AI 代理的上下文中，使其能够在执行当前任务时参考过去的成功经验。

注入格式

上下文注入支持多种格式，以适应不同 AI 提供商的要求。默认格式为 Markdown 风格的文本块，包含情境描述、解决机制和验证步骤。对于支持结构化数据的提供商，系统还可以生成 XML 格式的注入内容，便于解析和处理。资料来源：src/sdk/runtime.ts

graph LR
    A[记忆库检索] --> B[内容过滤]
    B --> C[格式化处理]
    C --> D{提供商类型}
    D -->|OpenAI| E[Markdown / JSON]
    D -->|Anthropic| F[Text Block]
    D -->|通用| G[自定义格式]
    E --> H[API 请求注入]
    F --> H
    G --> H

记忆优先级

系统根据多个维度计算记忆的优先级，包括相关度评分、时间衰减因子、使用频率和来源可信度。高优先级的记忆会被优先注入到上下文中，确保最重要的信息不会因上下文长度限制而被忽略。系统还支持记忆的置信度校准，根据历史使用效果动态调整优先级权重。

验证机制

每个注入的记忆都附带验证信息，指导代理如何确认记忆内容是否适用于当前任务。验证机制包括问题检查点、预期结果描述和边界条件说明，确保代理能够在应用记忆前正确评估其适用性。

集成配置

环境变量配置

SDK 支持通过环境变量进行配置，这是最基础的配置方式。开发者可以通过设置相应的环境变量来指定 API 端点、认证凭证、检索参数等配置项。环境变量配置适用于容器化部署和 CI/CD 环境，提供了便捷的运行时配置能力。

配置文件配置

对于更复杂的配置需求，SDK 支持通过 JSON 配置文件进行设置。配置文件允许开发者定义多个提供商配置、记忆检索规则、自定义注入模板等高级选项。配置文件的路径可以通过环境变量或编程方式指定，SDK 会在启动时自动加载并应用配置。

编程式配置

开发者还可以通过 SDK 提供的编程接口进行配置，这种方式提供了最大的灵活性。编程式配置允许在运行时动态调整配置参数，适合需要根据不同场景切换配置的应用。SDK 提供了类型安全的配置接口，确保配置参数的正确性。

安全考虑

输入验证

SDK 在处理外部输入时实施了严格的验证机制。所有来自 AI 提供商的响应都会经过安全扫描，防止注入攻击和恶意内容。记忆检索结果也会经过内容过滤，确保注入到上下文中的信息符合安全策略。

认证管理

SDK 支持多种认证方式，包括 API 密钥、OAuth 令牌和自定义认证头。敏感凭证会通过加密存储，不会以明文形式出现在日志或错误信息中。SDK 还实现了凭证自动刷新机制，避免因凭证过期导致的请求失败。资料来源：src/middleware/generic.ts

数据隔离

SDK 确保不同项目和工作空间的数据隔离，防止未授权的跨项目记忆访问。每个安装实例都有独立的标识符，记忆检索会严格限制在当前项目的范围内。这种隔离机制保护了用户数据的隐私和项目信息的机密性。

性能优化

缓存策略

SDK 实现了多级缓存策略，包括内存缓存和持久化缓存。频繁访问的记忆会被缓存到内存中，减少对后端存储的访问压力。缓存使用 LRU（最近最少使用）淘汰策略，确保内存使用保持在合理范围内。

异步处理

所有 IO 操作都采用异步处理模式，不会阻塞主线程。SDK 使用 Promise 和 async/await 语法提供简洁的异步接口，同时支持并发检索以提高整体吞吐量。对于需要等待响应的场景，SDK 提供了取消令牌支持，便于实现请求取消和超时控制。

连接复用

SDK 实现了 HTTP 连接池和 Keep-Alive 机制，复用与 AI 提供商的连接，减少连接建立的开销。连接池的大小可以通过配置调整，以适应不同的并发需求场景。

错误处理

错误分类

SDK 将错误分为可恢复错误和不可恢复错误两类。可恢复错误包括网络超时、服务暂时不可用等，这类错误会触发自动重试机制。不可恢复错误包括认证失败、参数错误等，这类错误会直接抛出并建议开发者检查配置。

重试策略

对于可恢复错误，SDK 实现了指数退避重试策略。重试次数和间隔时间可以通过配置调整，默认配置会进行最多三次重试，每次重试的间隔时间呈指数增长。重试策略还考虑了请求的幂等性，确保重试不会导致重复操作。

日志记录

SDK 提供了详细的日志记录功能，记录内容包括请求参数、响应状态、错误详情和性能指标。日志级别可以通过配置调整，支持 debug、info、warn、error 四个级别。生产环境建议使用 warn 或 error 级别，以减少日志量并保护敏感信息。

扩展开发

自定义中间件开发

开发者可以通过继承基础中间件类来创建自定义中间件，以支持未提供官方支持的 AI 提供商。自定义中间件需要实现特定的接口方法，包括请求转换、响应解析和上下文注入等核心功能。

插件系统

SDK 支持插件扩展，允许开发者注册自定义的记忆检索器、格式化器和验证器。插件通过统一的注册接口加载，SDK 会在相应的处理阶段调用插件提供的功能。这种设计使得 SDK 能够适应各种定制化需求，无需修改核心代码。

相关资源

• 完整 SDK 文档：docs/SDK.md
• 中间件源码：src/middleware/
• 运行时源码：src/sdk/runtime.ts
• 示例项目：参考仓库中的示例目录

Pitfall Log / 踩坑日志

项目：64envy64/tracebase

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1203006515 | https://github.com/64envy64/tracebase | host_targets=mcp_host, claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1203006515 | https://github.com/64envy64/tracebase | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1203006515 | https://github.com/64envy64/tracebase | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1203006515 | https://github.com/64envy64/tracebase | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | release_recency=unknown