# https://github.com/64envy64/tracebase 项目说明书 生成时间：2026-05-14 17:02:08 UTC ## 目录 - [项目概述](#overview) - [快速开始](#quickstart) - [CLI命令参考](#cli-commands) - [系统架构](#system-architecture) - [核心组件详解](#core-components) - [数据存储机制](#data-storage) - [五大运行时机制](#five-arms) - [召回与检索机制](#recall-mechanism) - [上下文折叠机制](#fold-mechanism) - [SDK集成指南](#sdk-integration) ## 项目概述 ### 相关页面 相关主题：[快速开始](#quickstart), [系统架构](#system-architecture), [五大运行时机制](#five-arms)
相关源码文件 以下源码文件用于生成本页说明： - [www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) - [www/src/components/engineering-brain/IssuesView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/engineering-brain/IssuesView.tsx)
# 项目概述 ## 项目简介 TraceBase 是一个面向 AI 编码代理的机构知识管理系统，旨在帮助代理避免重复探索已知的死胡同，从而提升问题解决效率并降低推理成本。 该系统的核心价值主张是：**不是模型能力不足，而是代理在每次调用时都会重新探索死胡同**。TraceBase 通过三字段追踪格式对问题情境、避免方案和解决方案进行编码，引导模型绕过失败模式，减少浪费的步骤和错误输出。 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ## 核心架构 ### 两阶段检索系统 TraceBase 采用两阶段检索排名架构，结合六种检索信号实现精准知识匹配： ```mermaid 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 ``` | 检索信号 | 描述 | 复杂度 | |---------|------|--------| | Fingerprint | 指纹匹配 | O(1) | | BM25 | FTS5 全文搜索 | O(log n) | | 结构相似度 | 代码结构特征比对 | O(n) | | 余弦相似度 | 向量语义匹配 | O(n) | | 新鲜度 | 时间衰减权重 | O(1) | | Thompson采样 | 从结果中学习权重 | 实时 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ### 追踪格式设计 追踪格式遵循四个研究原则，采用三字段结构编码知识： ```mermaid graph LR A[问题情境] --> D[Situation] B[避免方案] --> E[Dead Ends] C[解锁方案] --> F[Unlock] D --> G[验证方法 Verification] E --> G F --> G ``` **三字段追踪结构：** | 字段 | 用途 | 设计原则 | |------|------|---------| | `situation` | 描述代理遇到的情境 | 压缩指令，60 令牌以内 | | `deadEnds` | 需避免的失败路径 | 正向约束而非负向禁止 | | `unlock` | 导向正确解决方案的解锁点 | Skip-to-fix 策略 | 资料来源：[src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) ### 注入有效载荷构建 系统通过 `build-injection-payload.ts` 将追踪知识注入到代理上下文中： ```typescript // 导入标签用于区分外部导入的修复方案 const IMPORTED_TAG_OPEN = ``; const IMPORTED_TAG_CLOSE = ``; // 紧凑格式渲染示例： // • . Mechanism: <…>. Fix: . Verify: . // (Avoid: a; b 仅在存在死胡同时添加) ``` 资料来源：[src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) ## 安全防护机制 ### 防护墙系统 TraceBase 内置多层安全防护，防止恶意注入攻击： ```mermaid 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[拦截并记录] ``` | 防护类型 | 正则表达式 | 防护目标 | |---------|-----------|---------| | `system-spoof` | `/(?(?!`)/i` | 伪造高权限对话标记 | | `delimiter-spoof` | `/(```\s*(system|tool_result|prior_fix|file_memory|context_fold)\b\|<\s*(prior_fix|file_memory|context_fold)\b)/i` | 伪造 TraceBase 注入分隔符 | | `secret-exfil` | 检测环境变量提取意图 | 敏感信息泄露 | 资料来源：[src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) ### 防护设计原则 1. **反跳过头检查**：文档化的标签（如 `` `` ``）不会触发匹配 2. **边界限制**：对短术语（如 `env`）设置更严格的检测阈值 3. **注入前缀信任继承防护**：防止攻击者通过伪造分隔符继承系统信任级别 资料来源：[src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) ## 评估体系 ### 基准测试方法 TraceBase 使用多轮评估方法验证系统效果： ```mermaid graph LR A[Round 0] -->|空知识库| B[基线测试] B -->|成功补丁| C[生成追踪] C --> D[Round 1] D -->|热知识库| E[对比测试] E --> F{结果对比} F -->|准确率提升| G[验证有效] F -->|无变化| H[需优化] ``` | 评估维度 | 描述 | |---------|------| | 评估工具 | SWE-bench Verified + mini-swe-agent v2 | | 任务数量 | 100 个真实 GitHub Issue | | 轮次设计 | Round 0 空基线 / Round 1 热启动 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ### 评估指标体系 | 指标类型 | 说明 | 测量方式 | |---------|------|---------| | 准确率 | 成功解决问题的比例 | 相同任务运行对比 | | 步骤节省 | 达到正确方案的代理步数减少 | 运行时测量 | | 成本降低 | 每步推理 token 消耗减少 | 模型定价计算 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ## 应用集成 ### 仪表板功能 TraceBase 提供 Web 仪表板用于管理项目和工作区： | 功能模块 | 路径 | 说明 | |---------|------|------| | 概览视图 | `/dashboard` | 显示最近活动、集成列表 | | 影响视图 | `/dashboard/impact` | 追踪运行数据、成本节省统计 | | 安装视图 | `/dashboard/installations` | 管理所有已链接项目 | 资料来源：[www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) ### 工程师大脑模块 `IssuesView` 组件提供对 GitHub Issue、PR 和 CI 失败的一体化视图： ```mermaid 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](https://github.com/64envy64/tracebase/blob/main/www/src/components/engineering-brain/IssuesView.tsx) ### 快速启动 用户可通过 CLI 快速集成项目： ```bash npx tracebase-ai init ``` 该命令在项目目录中创建链接，使项目出现在工作区仪表板中。 资料来源：[www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) ## 技术栈概览 | 层级 | 技术选择 | |------|---------| | 前端框架 | React / Next.js (TypeScript) | | UI 组件 | Tailwind CSS + 自定义组件 | | 数据获取 | API 路由 | | 样式系统 | CSS 变量 + Ink 设计系统 | ## 复现指南 所有基准测试代码、fixture、种子和原始轨迹数据均开源在仓库中： | 目录 | 内容 | |------|------| | `eval/swebench/` | SWE-bench Verified 评估套件 + 结果 | | `eval/agentic/` | TypeScript fixture 基准测试 + 结果 | | `eval/tasks/` | 任务定义 + 种子追踪 | **复现命令：** ```bash 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](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ## 许可与开源 TraceBase 采用 MIT 许可证开源，所有代码和文档可在公共仓库中获取。 --- ## 快速开始 ### 相关页面 相关主题：[项目概述](#overview), [CLI命令参考](#cli-commands), [SDK集成指南](#sdk-integration)
相关源码文件 以下源码文件用于生成本页说明： - [src/cli/install-targets.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/install-targets.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [src/cli/commands/init.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/init.ts) - [www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) - [www/src/components/dashboard/InstallationsView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/InstallationsView.tsx) - [www/src/components/dashboard/ApiKeysView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/ApiKeysView.tsx) - [www/src/components/dashboard/ImpactView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/ImpactView.tsx)
# 快速开始 TraceBase 是一个 AI Agent 记忆管理系统，帮助开发团队在多个 Agent 实例间共享和复用解决问题的经验。本文档指导你完成从零到生产环境的完整安装流程。 ## 前置要求 | 要求 | 说明 | |------|------| | Node.js | 建议 v18+ | | 包管理器 | npm、pnpm、yarn 或 bun | | 支持的 Agent | Claude Code、Cursor、Codex | | 系统要求 | 可运行交互式终端的环境 | 资料来源：[src/cli/install-targets.ts:32-49]() ## 安装流程概览 ```mermaid 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[查看错误信息] ``` ## 核心安装命令 ### 交互式初始化 在项目根目录运行以下命令启动交互式安装流程： ```bash 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 平台，检测优先级如下： | Agent | 检测方式 | |-------|----------| | Codex | 环境变量 `CODEX_SHELL`、`CODEX_CI` 或 `CODEX_THREAD_ID` 存在 | | Cursor | 环境变量 `CURSOR_TRACE_ID`、`CURSOR_AGENT` 或终端程序为 cursor | | Claude Code | 环境变量 `CLAUDECODE`、`CLAUDE_CODE`、`CLAUDE_PROJECT_DIR` 或 `CLAUDE_DESKTOP` 存在 | ```typescript // 检测优先级代码逻辑 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 类型： ```bash # 仅为 Claude Code 安装 npx tracebase-ai init --agent claude-code # 仅为 Cursor 安装 npx tracebase-ai init --agent cursor ``` ## 安装后检查 ### 运行 doctor 命令 安装完成后，务必运行健康检查以确保所有组件正常工作： ```bash npx tracebase-ai doctor ``` doctor 命令执行以下检查项： | 检查项 | 说明 | 失败处理 | |--------|------|----------| | 指令文件存在性 | 验证 CLAUDE.md 或 AGENTS.md 文件 | 运行 `init` 重新创建 | | 托管区块完整性 | 检查指令文件中的托管区域是否存在 | 重新运行 `init` | | Hook 配置状态 | 验证 Agent Hook 是否正确配置 | 手动修复配置 | | MCP 服务连接 | 确认 MCP 服务器可达 | 检查网络和配置 | ```typescript // 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 命令会以不同级别报告问题： | 级别 | 含义 | 是否阻止使用 | |------|------|--------------| | `pass` | 检查通过 | 否 | | `warn` | 存在可修复问题 | 建议修复 | | `fail` | 关键配置缺失 | 必须修复 | 当检测到缺少托管区块时，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) 显示所有已链接项目的最近活动记录： ```typescript // 活动列表组件 function ActivityRow({ install }: { install: DashboardBootstrap["installations"][number] }) { return (
  • } actor={install.projectName} meta={<>{install.agent} · cli {install.cliVersion}} />
    • ); } ``` 无活动时显示引导信息： ``` 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) 查看所有已链接的安装： | 字段 | 说明 | |------|------| | Project Name | 项目名称 | | Agent | 使用的 Agent 类型 | | CLI Version | TraceBase CLI 版本 | | Linked | 链接时间 | | Updated | 最后更新时间 | ```typescript // 安装列表渲染 {installations.map((install) => (
  • } actor={install.projectName} meta={<>{install.agent} · cli {install.cliVersion}} />
    linked {formatRelativeTime(install.createdAt)}
    • ))} ``` 资料来源：[www/src/components/dashboard/InstallationsView.tsx]() #### API 密钥管理 (ApiKeysView) 为 CI 环境和无头环境创建 API 密钥： ```typescript // 创建密钥命令预览 const command = `TRACEBOUND_API_KEY=${newKey} npx tracebase-ai sync`; ``` **重要提示**：每个密钥仅在创建时显示一次，请妥善保管。 资料来源：[www/src/components/dashboard/ApiKeysView.tsx]() #### 影响分析视图 (ImpactView) 追踪 TraceBase 对 Agent 工作效率的实际影响： ```mermaid graph LR A[Agent Tasks] --> B[Matched Memory] B --> C[Shown] C --> D[Used] D --> E[Win] ``` | 阶段 | 说明 | 指标 | |------|------|------| | Agent Tasks | TraceBase 检查记忆的任务 | eligibleRuns | | Matched Memory | 找到至少一条相关记忆 | recalledRuns | | Shown | 记忆被注入 Agent 上下文 | injectedRuns | | Used | Agent 实际使用了记忆 | usedRuns | 资料来源：[www/src/components/dashboard/ImpactView.tsx]() ## CI 环境配置 ### 创建 API 密钥 在仪表板的 API Keys 页面创建密钥： ```bash # 密钥创建后显示的命令 TRACEBOUND_API_KEY=your_key_here npx tracebase-ai sync ``` ### CI 脚本集成 将密钥配置为 CI 环境变量： ```yaml # .github/workflows/ci.yml 示例 env: TRACEBOUND_API_KEY: ${{ secrets.TRACEBOUND_API_KEY }} ``` ```bash # CI 中运行同步 npx tracebase-ai sync ``` 资料来源：[www/src/components/dashboard/ApiKeysView.tsx]() ## 常见问题 ### 安装命令无响应 确保在项目根目录运行，且当前目录包含版本控制（如 `.git`）。 ### Agent 未被识别 手动指定 Agent 类型： ```bash 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` 查看详细状态 ## 下一步 | 任务 | 说明 | |------|------| | [配置自定义规则](/docs/patterns) | 定义何时保存和检索记忆 | | [集成 GitHub](/docs/integrations) | 将 Issues 和 PR 纳入记忆系统 | | [性能调优](/docs/tuning) | 优化检索精度和注入策略 | --- ## CLI命令参考 ### 相关页面 相关主题：[快速开始](#quickstart), [系统架构](#system-architecture)
    相关源码文件 以下源码文件用于生成本页说明： - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [src/cli/commands/recall.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/recall.ts) - [src/cli/commands/search.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/search.ts) - [src/cli/commands/events.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/events.ts) - [src/cli/commands/impact.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/impact.ts) - [src/cli/commands/serve.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/serve.ts) - [src/cli/commands/remove.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/remove.ts)
    # CLI命令参考 TraceBase CLI 提供了一套完整的命令行工具，用于管理本地项目、安装、记忆检索以及运行状态监控。本页面详细说明所有可用的命令、子命令及其用法。 ## 概述 TraceBase CLI 通过 `npx tracebase-ai` 或全局安装的 `tracebase` 命令调用。CLI 采用模块化架构，每个命令独立存在于 `src/cli/commands/` 目录下： ```mermaid 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"] ``` ## 全局选项 所有命令支持以下全局选项： | 选项 | 说明 | 默认值 | |------|------|--------| | `--help, -h` | 显示帮助信息 | - | | `--version, -v` | 显示版本号 | - | | `--json` | 以 JSON 格式输出 | false | | `--quiet, -q` | 静默模式，减少日志输出 | false | | `--verbose` | 详细输出模式 | false | ## 命令详解 ### doctor 健康检查命令，用于诊断 TraceBase 在本地项目中的配置状态。 ```bash tracebase doctor [--agent ] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `--agent` | 否 | 指定要检查的代理类型（`claude-code`、`claude`、`openai` 等） | **检查项目：** `doctor` 命令执行以下诊断检查： 1. **指令文件检查** - 验证 `CLAUDE.md` 或 `AGENTS.md` 是否存在并包含托管区块 资料来源：[src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) 2. **Hook 配置检查** - 针对 Claude Code 检查 `.claude/settings.json` 中的 hook 条目 资料来源：[src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) 3. **MCP 配置检查** - 验证 MCP 服务器连接状态 4. **环境完整性检查** - 确保所有必需的配置文件存在 **输出示例：** ```json { "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." } ] } ``` **返回码：** | 返回码 | 含义 | |--------|------| | 0 | 所有检查通过 | | 1 | 存在警告 | | 2 | 存在错误 | --- ### recall 召回命令，用于检索与当前任务相关的记忆条目。 ```bash tracebase recall [options] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `query` | 是 | 检索查询字符串 | **选项说明：** | 选项 | 缩写 | 说明 | 默认值 | |------|------|------|--------| | `--limit` | `-n` | 返回结果数量限制 | 10 | | `--type` | - | 过滤记忆类型（`block`、`fact`、`imported`） | 全部 | | `--scope` | - | 限定作用域（`project`、`global`、`team`） | project | | `--format` | `-f` | 输出格式（`json`、`markdown`、`xml`） | json | **工作流程：** ```mermaid graph TD A["输入 query"] --> B["指纹提取"] B --> C["BM25 索引查询"] C --> D["候选集过滤"] D --> E["重排序"] E --> F["校准概率计算"] F --> G["返回结果"] ``` --- ### search 搜索命令，提供全文检索功能。 ```bash tracebase search [options] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `keywords` | 是 | 搜索关键词（支持多个） | **选项说明：** | 选项 | 缩写 | 说明 | |------|------|------| | `--fuzzy` | `-f` | 启用模糊匹配 | | `--regex` | `-r` | 使用正则表达式搜索 | | `--file` | - | 限定搜索特定文件 | | `--since` | - | 只搜索指定日期后的记忆 | | `--until` | - | 只搜索指定日期前的记忆 | **输出格式：** ```json { "results": [ { "id": "block-xxx", "type": "hypothesis", "situation": "...", "mechanism": "...", "relevance": 0.87 } ], "total": 5, "queryTime": "12ms" } ``` --- ### events 事件日志命令，用于查看记忆相关的事件记录。 ```bash tracebase events [options] [filters...] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `filters` | 否 | 事件过滤器 | **支持的过滤器：** | 过滤器 | 说明 | 示例 | |--------|------|------| | `action:created` | 只显示创建事件 | `action:created` | | `action:used` | 只显示使用事件 | `action:used` | | `action:rejected` | 只显示拒绝事件 | `action:rejected` | | `run:` | 限定特定运行 | `run:abc123` | | `since:` | 限定起始时间 | `since:2024-01-01` | **输出示例：** ```json { "events": [ { "id": "evt-xxx", "action": "created", "memoryId": "block-yyy", "runId": "run-zzz", "timestamp": "2024-01-15T10:30:00Z" } ] } ``` --- ### impact 影响分析命令，展示 TraceBase 对开发效率的实际影响。 ```bash tracebase impact [options] [scope] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `scope` | 否 | 分析范围（`day`、`week`、`month`、`all`） | **选项说明：** | 选项 | 说明 | 默认值 | |------|------|--------| | `--compare` | 与基线对比 | false | | `--output` | 输出文件路径 | stdout | **输出指标：** | 指标 | 说明 | |------|------| | `eligibleRuns` | 有资格的任务数（TraceBase 检查了记忆） | | `recalledRuns` | 召回成功的任务数 | | `injectedRuns` | 记忆被注入上下文的任务数 | | `usedRuns` | Agent 实际使用了记忆的任务数 | | `resolvedRateWithMemory` | 使用记忆后解决的任务比例 | | `tokensSaved` | 预估节省的 token 数量 | --- ### serve 本地服务命令，启动 TraceBase MCP 服务器进行本地测试。 ```bash tracebase serve [options] ``` **选项说明：** | 选项 | 缩写 | 说明 | 默认值 | |------|------|------|--------| | `--port` | `-p` | 服务端口 | 3000 | | `--host` | - | 服务地址 | localhost | | `--no-auth` | - | 禁用认证 | false | | `--cors` | - | 启用 CORS | false | **使用场景：** 此命令主要用于： 1. 本地开发测试 MCP 集成 2. 调试记忆检索逻辑 3. 验证配置正确性 **生命周期：** ```mermaid graph LR A["启动服务"] --> B["初始化数据库"] B --> C["加载项目配置"] C --> D["注册 MCP 端点"] D --> E["监听请求"] E --> F["处理检索"] F --> E ``` --- ### remove 删除命令，用于清理记忆条目或项目数据。 ```bash tracebase remove [options] ``` **参数说明：** | 参数 | 必填 | 说明 | |------|------|------| | `target` | 是 | 要删除的目标（记忆 ID、项目名称等） | **选项说明：** | 选项 | 缩写 | 说明 | |------|------|------| | `--force` | `-f` | 强制删除，无需确认 | | `--type` | `-t` | 指定删除类型（`memory`、`project`、`all`） | | `--dry-run` | - | 模拟运行，不实际删除 | **安全机制：** 1. 默认需要确认操作 2. `--force` 选项绕过确认 3. `--dry-run` 显示将要删除的内容但不执行 **使用示例：** ```bash # 删除单个记忆 tracebase remove memory block-abc123 # 删除整个项目的所有记忆 tracebase remove project my-project --force # 模拟删除，查看将要删除的内容 tracebase remove memory block-xxx --dry-run ``` --- ### init 初始化命令，在项目中配置 TraceBase。 ```bash tracebase init [options] ``` **选项说明：** | 选项 | 说明 | |------|------| | `--agent` | 指定代理类型 | | `--workspace` | 指定工作区路径 | | `--no-git` | 跳过 Git 初始化 | 此命令会： 1. 创建必要的配置文件 2. 设置 Hook 脚本 3. 配置 MCP 服务器连接 资料来源：[src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) --- ### status 状态命令，显示当前项目与 TraceBase 的连接状态。 ```bash tracebase status ``` **输出信息：** | 状态项 | 说明 | |--------|------| | `projectName` | 项目名称 | | `agent` | 使用的 Agent 类型 | | `cliVersion` | CLI 版本 | | `createdAt` | 链接创建时间 | | `updatedAt` | 最后更新时间 | --- ## 退出码 所有命令遵循以下退出码规范： | 退出码 | 含义 | |--------|------| | 0 | 成功执行 | | 1 | 部分成功（存在警告） | | 2 | 执行失败（存在错误） | | 130 | 被用户中断（Ctrl+C） | --- ## 环境变量 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `TRACEBASE_API_KEY` | API 认证密钥 | - | | `TRACEBASE_WORKSPACE` | 工作区路径 | `.tracebase` | | `TRACEBASE_LOG_LEVEL` | 日志级别 | `info` | | `TRACEBASE_DB_PATH` | 数据库路径 | `~/.tracebase/data.db` | --- ## 配置文件 CLI 配置支持以下位置（按优先级排序）： 1. `~/.tracebase/config.json` - 用户级配置 2. `/.tracebase/config.json` - 项目级配置 3. 环境变量覆盖 **配置结构：** ```json { "workspace": ".tracebase", "apiUrl": "https://api.tracebase.ai", "defaultAgent": "claude-code", "retrieval": { "maxResults": 10, "minConfidence": 0.3 } } --- ## 系统架构 ### 相关页面 相关主题：[项目概述](#overview), [核心组件详解](#core-components), [数据存储机制](#data-storage)
    相关源码文件 以下源码文件用于生成本页说明： - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [www/src/components/dashboard/ImpactView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/ImpactView.tsx) - [docs/DESIGN_v2.md](https://github.com/64envy64/tracebase/blob/main/docs/DESIGN_v2.md)
    # 系统架构 ## 概述 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]() ## 系统架构图 ```mermaid graph TD subgraph Agent["代理层 (Agent)"] A[Claude Code / Claude Agent] MCP[MCP Server] end subgraph Core["核心处理层 (Core)"] G[Guard
    安全防护] BS[Block Serving
    块服务] BP[Build Injection Payload
    载荷构建] end subgraph Storage["存储层 (Storage)"] Store[(Store
    主存储)] BlockStore[(Block Store
    块存储)] FP[Fingerprint
    指纹库] end subgraph Integration["集成层"] GH[GitHub Integrations] DB[Dashboard
    仪表板] end A --> MCP MCP --> G G --> BS BS --> BP BP --> Store BS --> BlockStore BS --> FP GH --> Store DB --> Store ``` ## 核心模块 ### 1. Guard 模块（安全防护） Guard 是 TraceBase 的第一道防线，负责检测和阻止恶意的上下文注入攻击。它在记忆块进入系统前进行多层检查。 #### 检查类型 | 检查项 | 正则表达式 | 防护目标 | |--------|-----------|---------| | system-spoof | `(?(?!`)` | 防止伪造高权限对话标记 | | delimiter-spoof | `(```\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\b\|<\s*(prior_fix\|file_memory\|context_fold)\b)` | 防止伪装 TraceBase 自己的分隔符 | | env-exfil | `environment variable[s]?` 形式的详细匹配 | 防止敏感环境变量泄露意图 | Guard 模块的设计特别考虑了"文档场景"：当用户讨论代码中的 `` 标签时，不应被误判为注入攻击。通过精确的边界检查（如 backtick-neighbour skip 逻辑），Guard 能够区分真实注入与正常文档引用 资料来源：[src/core/guard.ts:10-25]() ### 2. Block Serving 模块（块服务） Block Serving 负责将存储中的记忆块转换为代理可读的格式，支持多种渲染输出。 #### 核心功能 **块命中渲染**（Block Hit Rendering）将记忆块转换为结构化文本或 XML 格式： ```typescript // XML 格式渲染示例 问题描述 问题机制 解锁方案 验证步骤 需避免的方案 ``` 每个块包含以下元数据： - `calibratedProb`：置信度校准概率 - `id`：唯一标识符 - `evidence`：引用证据列表 资料来源：[src/core/block-serving.ts:20-40]() ### 3. Build Injection Payload 模块（载荷构建） 该模块负责将检索到的记忆块构建为最终的注入载荷，采用紧凑的文案格式直接呈现给代理。 #### 渲染格式 采用无序列表格式，每项包含： - **Situation**：问题场景（大写开头） - **Mechanism**：问题机制 - **Fix**：解锁方案 - **Verify**：验证步骤 - **Avoid**（可选）：死胡同/需避免的方案 ```typescript // 示例输出 • . Mechanism: <机制描述>. Fix: <解决方案>. Verify: <验证方式>. // 如有死胡同时： • . Mechanism: <…>. Fix: <…>. Verify: <…>. Avoid: a; b; c. ``` 导入的记忆块会带有 `` 标签，便于代理识别来源 资料来源：[src/core/build-injection-payload.ts:20-35]() ### 4. 存储层 #### Store 模块 主存储模块负责管理会话数据、安装信息和完整性校验。 #### Block Store 模块 结构化记忆块的核心存储，包含： | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 块唯一标识 | | `calibratedProb` | number | 校准后的置信度 | | `block.trigger.situation` | string | 触发场景描述 | | `block.body.mechanism` | string | 问题机制 | | `block.body.unlock` | string | 解决方案 | | `block.body.verification` | string | 验证步骤 | | `block.body.deadEnds` | string[] | 需避免的路径 | | `block.provenance.extractedFrom` | string | 来源标识 | #### Fingerprint 模块 指纹模块提供 O(1) 时间复杂度的快速匹配能力，用于在大量候选中快速筛选潜在相关块。 ### 5. Similarity 和 Weights 模块 #### 相似度计算 ```mermaid 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. **上下文相关性**：当前任务与历史记忆的关联度 ## 检索流程 ```mermaid 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） | 指标 | 说明 | |------|------| | Eligible Runs | TraceBase 检查记忆的任务数 | | Recalled Runs | 找到至少一条相关记忆的任务数 | | Injected Runs | 记忆被添加到代理上下文的任务数 | | Used Runs | 代理实际使用了记忆的任务数 | ```mermaid 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. **标签隔离**：使用专属分隔符 `` 和 ``，防止内容劫持 3. **只读背景**：记忆层仅提供背景信息，代理不从此处接收命令 4. **可验证来源**：每个记忆块携带来源追溯信息（traceId, role） ```mermaid graph TD Input[外部输入] --> G1[Guard检查] G1 -->|通过| Process[处理流程] G1 -->|拒绝| Log[日志记录] Process --> Tag[添加专属标签] Tag --> Output[输出给代理] Output --> Readonly[只读背景] ``` ## 配置与诊断 ### Doctor 命令 `tracebase-ai doctor` 命令执行全面的健康检查： | 检查项 | 说明 | |--------|------| | MCP 配置 | MCP 服务是否正确配置 | | CLAUDE.md | 指令文件是否存在 | | Managed Section | 受管部分是否完整 | | Agent Hooks | 代理钩子配置是否正确 | ```mermaid 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 能够作为代理的"第二记忆系统"，在不改变代理原有行为的前提下，显著提升其在重复任务上的表现。 --- ## 核心组件详解 ### 相关页面 相关主题：[系统架构](#system-architecture), [五大运行时机制](#five-arms), [数据存储机制](#data-storage)
    相关源码文件 以下源码文件用于生成本页说明： - [src/core/engine.ts](https://github.com/64envy64/tracebase/blob/main/src/core/engine.ts) - [src/core/block.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block.ts) - [src/core/file-indexer.ts](https://github.com/64envy64/tracebase/blob/main/src/core/file-indexer.ts) - [src/core/file-summarizer.ts](https://github.com/64envy64/tracebase/blob/main/src/core/file-summarizer.ts) - [src/runtime/digest.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/digest.ts)
    # 核心组件详解 ## 概述 TraceBase 是一个面向编程智能体的记忆层系统，它能够在多次运行之间保持过去的解决方案、文件含义和循环陷阱等信息。TraceBase 通过 MCP（Model Context Protocol）协议以即插即用方式集成，为 AI 编码助手提供持久化的上下文记忆能力。 核心组件体系围绕三个主要阶段构建：**记忆生成与存储**、**检索与匹配**、**上下文注入**。整个系统在保证安全性的前提下，通过多层信号重排序机制从代码库中提取高质量的先前经验，并在智能体执行任务时适时注入。 --- ## 核心架构分层 TraceBase 的核心架构可以划分为四个主要层次： | 层次 | 职责 | 核心模块 | |------|------|----------| | 数据层 | 代码文件索引与摘要生成 | file-indexer、file-summarizer | | 推理层 | 模式匹配与置信度校准 | engine、block | | 传输层 | 上下文格式化与注入 | build-injection-payload、block-serving | | 安全层 | 输入验证与防护机制 | guard | | 可观测层 | 任务追踪与影响分析 | observe-tools、digest | --- ## 安全防护层（Guard） `src/core/guard.ts` 实现了 TraceBase 的安全防护机制，用于防止恶意注入和提示词攻击。该模块通过正则表达式匹配识别多种潜在的安全威胁。 ### 防护类型 | 防护名称 | 正则表达式 | 用途 | |----------|------------|------| | system-spoof | `/(?(?!`)/i` | 阻止伪造的高权限对话标记 | | delimiter-spoof | `/(```\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\b\|<\s*(prior_fix\|file_memory\|context_fold)\b)/i` | 防止利用内置分隔符进行注入 | | env-exfil | 限制为 `environment variable(s)?` 形式 | 阻止环境变量窃取 | 系统防护的关键特性包括： - **反环绕防护**：通过负向后顾断言 `(? 资料来源：[src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) --- ## 块服务层（Block Serving） 块服务层负责将匹配到的记忆块格式化为可注入的上下文片段。该模块提供两种渲染模式：XML 格式用于详细审计，Markdown 格式用于智能体直接消费。 ### XML 渲染输出结构 ```xml 具体场景描述 问题机制说明 需要避免的错误路径 解决方案 验证方法 ``` ### Markdown 紧凑格式 对于标准注入场景，系统使用紧凑的 Markdown 格式： ``` • . Mechanism: <机制说明>. Fix: <解锁方案>. Verify: <验证方式>. ``` 当存在死路路径时，格式扩展为： ``` • . Mechanism: <…>. Fix: . Verify: . Avoid: a; b; c. ``` > 资料来源：[src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) --- ## 注入载荷构建（Build Injection Payload） `src/core/build-injection-payload.ts` 负责构造最终的上下文注入内容。该模块实现了导入记忆的特殊标记机制。 ### 导入记忆标记 ```typescript const IMPORTED_TAG_OPEN = ``; const IMPORTED_TAG_CLOSE = ``; ``` 当记忆来源于外部导入时，系统会使用特殊标签包裹，以区分内部生成记忆和外部导入知识。这种机制确保了溯源能力和信任级别的正确传递。 ### 格式化策略 模块采用以下格式化原则： - **首字母大写**：`situation` 字段以大写字母开头 - **末尾清理**：移除末尾的点和空白字符 - **长度控制**：通过 `trimSentence` 函数限制句子长度 - **意图隐藏**：不暴露块 ID、校准概率等技术细节，保持自然语言流畅性 > 资料来源：[src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) --- ## 工具可观测层（Observe Tools） `src/runtime/observe-tools.ts` 实现了对智能体工具调用的观测能力。该模块从工具输入中提取文件路径信息，用于追踪智能体访问了哪些代码文件。 ### 文件路径提取 ```typescript for (const key of ["file_path", "path", "filename", "filePath"] as const) { const v = obj[key]; if (typeof v === "string" && v.trim().length > 0) return v; } ``` 模块支持多种文件路径字段命名约定： | 字段名 | 适用场景 | |--------|----------| | `file_path` | Claude Code 标准格式 | | `path` | 通用路径格式 | | `filename` | 文件名场景 | | `filePath` | 驼峰命名格式 | > 资料来源：[src/runtime/observe-tools.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/observe-tools.ts) --- ## 诊断命令（Doctor） `src/cli/commands/doctor.ts` 提供了完整的安装健康检查功能，用于验证 TraceBase 与目标智能体环境的集成状态。 ### 检查项目 | 检查项 | 级别 | 说明 | |--------|------|------| | 指令文件存在性 | warn | 验证 `.claude/commands` 目录下的指令块是否存在 | | 托管区域完整性 | warn | 检查指令文件中托管区域的配置状态 | | 钩子配置状态 | pass/warn | 验证各事件类型的钩子注册情况 | ### 钩子检查逻辑 医生命令会遍历指定智能体支持的所有事件类型，检查 `.claude/settings.json` 中的钩子配置。系统会生成缺失钩子的完整列表，确保智能体能够完整接收 TraceBase 的后台注入。 > 资料来源：[src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) --- ## 数据流向总览 ```mermaid graph TD A[代码库文件] --> B[File Indexer] B --> C[File Summarizer] C --> D[Block Engine] D --> E[Guard 校验] E --> F{通过验证?} F -->|是| G[置信度校准] F -->|否| H[拒绝注入] G --> I{超过阈值?} I -->|是| J[Build Injection Payload] I -->|否| K[丢弃] J --> L[Block Serving] L --> M[Agent Context] M --> N[Tool Observation] N --> O[Digest 统计] ``` --- ## 关键配置参数 ### 检索信号权重 TraceBase 采用六信号两阶段检索架构： 1. **快速过滤信号**（O(1) 复杂度） - 指纹识别 - BM25 全文搜索 2. **重排序信号**（四路重排序） - 相关性评分 - 上下文契合度 - 时效性权重 - 信任级别 ### 置信度阈值 | 场景 | 阈值类型 | 说明 | |------|----------|------| | 高置信度匹配 | 固定阈值 | 直接注入到上下文 | | 中置信度匹配 | 动态阈值 | 依赖项目历史数据校准 | | 低置信度匹配 | 拒绝 | 不注入以避免干扰 | --- ## 仪表盘组件体系 TraceBase 的 Web 界面提供了多个视图组件来展示系统状态和使用情况。 ### 视图组件矩阵 | 组件 | 路径 | 功能 | |------|------|------| | OverviewView | dashboard | 显示最近活动和安装概览 | | InstallationsView | dashboard | 管理已链接的项目安装 | | ImpactView | dashboard | 展示记忆使用漏斗和每日运行统计 | | IssuesView | engineering-brain | 展示 Issues、PRs 和 CI 失败 | | IntegrationsView | engineering-brain | 管理 GitHub 仓库集成 | ### 影响漏斗（Impact Funnel） ``` Agent tasks → Matched memory → Shown → Used ``` 漏斗各阶段定义： | 阶段 | 含义 | |------|------| | Agent tasks | TraceBase 检查记忆的任务总数 | | Matched memory | 找到至少一条相关记忆的任务数 | | Shown | 记忆被添加到智能体上下文的次数 | | Used | 智能体实际采纳了记忆的任务数 | > 资料来源：[www/src/components/dashboard/ImpactView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/ImpactView.tsx) --- ## 总结 TraceBase 的核心组件体系围绕安全、高效的记忆检索和注入构建。从文件索引到上下文注入的完整流程中，每个模块都承担着明确的职责： - **Guard** 确保注入安全性，防止提示词注入攻击 - **Block Serving** 提供灵活的输出格式适配不同场景 - **Build Injection Payload** 构造自然、流畅的上下文文本 - **Observe Tools** 追踪智能体行为，提供可观测性 - **Doctor** 简化集成诊断，降低使用门槛 这套组件体系的设计体现了"安全优先、精确匹配、用户透明"的核心设计理念，使 TraceBase 能够作为一个即插即用的记忆层无缝集成到现有的 AI 编码工作流中。 --- ## 数据存储机制 ### 相关页面 相关主题：[系统架构](#system-architecture), [核心组件详解](#core-components)
    相关源码文件 以下源码文件用于生成本页说明： - [src/kb/jsonl.ts](https://github.com/64envy64/tracebase/blob/main/src/kb/jsonl.ts) - [src/analytics/usage-metrics.ts](https://github.com/64envy64/tracebase/blob/main/src/analytics/usage-metrics.ts) - [src/core/block-store.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-store.ts) - [src/core/impact.ts](https://github.com/64envy64/tracebase/blob/main/src/core/impact.ts) - [src/distillation/prompts.ts](https://github.com/64envy64/tracebase/blob/main/src/distillation/prompts.ts) - [src/distillation/heuristics.ts](https://github.com/64envy64/tracebase/blob/main/src/distillation/heuristics.ts)
    # 数据存储机制 TraceBase 的数据存储机制是整个系统的核心基础设施，负责管理推理块（Reasoning Blocks）、事实（Facts）、分析事件（Analytics Events）以及使用指标（Usage Metrics）的持久化与检索。本文档详细阐述各存储层的设计、数据模型、写入流程和查询接口。 --- ## 1. 存储架构概述 TraceBase 采用多层次存储架构，将不同类型的数据分别存储在 SQLite 数据库和 JSONL 文件中： | 存储层 | 技术选型 | 用途 | |--------|----------|------| | 结构化数据 | SQLite | 推理块、事实、分析事件、运行记录 | | 半结构化数据 | JSONL | 轨迹数据、种子追踪、日志导出 | ```mermaid graph TD A[Agent 运行] --> B[事件采集层] B --> C{数据类型判断} C -->|结构化事件| D[SQLite 数据库] C -->|轨迹/日志| E[JSONL 文件] D --> F[block-store.ts] D --> G[analytics_events 表] E --> H[jsonl.ts 处理器] F --> I[block-serving.ts 检索] G --> J[impact.ts 聚合计算] ``` 资料来源：[src/core/block-store.ts:1-50]() --- ## 2. SQLite 数据库存储 ### 2.1 分析事件表 (analytics_events) 分析事件是 TraceBase 追踪代理行为的核心数据结构，每条记录包含以下字段： ```typescript // 事件写入语句 `INSERT INTO analytics_events (ts, event_type, query_id, block_id, fact_id, run_id, shadow, payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?)` ``` 资料来源：[src/core/block-store.ts:45-55]() | 字段 | 类型 | 说明 | |------|------|------| | `ts` | INTEGER | 事件时间戳（Unix 毫秒） | | `event_type` | TEXT | 事件类型：`retrieval`、`outcome`、`fact_injection`、`fact_agent_used` 等 | | `query_id` | TEXT | 关联的查询标识符 | | `block_id` | INTEGER | 关联的推理块 ID（可为 NULL） | | `fact_id` | INTEGER | 关联的事实 ID（可为 NULL） | | `run_id` | TEXT | 代理运行批次标识 | | `shadow` | INTEGER | 阴影标记：0=控制组，1=阴影组（用于 A/B 测试） | | `payload` | TEXT | JSON 格式的附加数据 | ### 2.2 事件读取与过滤 `readEvents` 方法提供了灵活的事件查询接口： ```typescript readEvents(opts: EventReadOptions = {}): AnalyticsEvent[] { const clauses: string[] = []; const params: Record = { limit: opts.limit ?? 1000 }; if (opts.afterTs !== undefined) { clauses.push("ts > @afterTs"); params.afterTs = opts.afterTs; } if (opts.beforeTs !== undefined) { clauses.push("ts < @beforeTs"); params.beforeTs = opts.beforeTs; } if (opts.eventType) { const types = Array.isArray(opts.eventType) ? opts.eventType : [opts.eventType]; clauses.push(`event_type IN (${types.map((_, i) => `@et${i}`).join(",")})`); types.forEach((t, i) => { params[`et${i}`] = t; }); } // ... 构建 WHERE 子句 } ``` 资料来源：[src/core/block-store.ts:60-85]() | 查询参数 | 类型 | 说明 | |----------|------|------| | `afterTs` | number | 时间戳下限 | | `beforeTs` | number | 时间戳上限 | | `eventType` | string \| string[] | 事件类型过滤 | | `limit` | number | 返回记录上限（默认 1000） | --- ## 3. 推理块存储 (Reasoning Blocks) ### 3.1 数据结构 推理块是 TraceBase 存储的核心知识单元，包含触发条件和主体内容： ```typescript export interface StoreReasoningPatternArgs { /** 适用场景 — 简短触发语句 */ situation: string; /** 修复生效原因 — 底层机制 */ mechanism: string; /** 解锁步骤 */ unlock: string; /** 验证方法 */ verification: string; /** 避免的无效路径 */ deadEnds: string[]; } ``` 资料来源：[src/server/mcp-v2-helpers.ts:80-95]() ### 3.2 推理块字段长度约束 蒸馏过程对各字段有严格的字数限制： | 字段 | 最大字数 | 用途 | |------|----------|------| | `trigger.situation` | 40 词 | 触发条件描述 | | `body.mechanism` | 40 词 | 机制解释 | | `body.unlock` | 30 词 | 解锁步骤 | | `body.verification` | 30 词 | 验证方法 | | `body.deadEnds` | 每条 20 词，最多 5 条 | 无效路径警示 | | `body.guardrails` | 每条 20 词，最多 3 条 | 安全护栏 | 资料来源：[src/distillation/prompts.ts:1-30]() ### 3.3 蒸馏置信度 每个推理块包含 `distillationConfidence` 字段，取值范围 0 到 1，表示该模式的可信程度： ```json { "trigger": { "situation": "", "invariants": { "language": "", "framework": "", "errorType": "", "apiSurface": ["", ...] } }, "body": { "mechanism": "", "deadEnds": ["", ...], "unlock": "", "verification": "", "guardrails": ["", ...] }, "distillationConfidence": } ``` 资料来源：[src/distillation/prompts.ts:35-60]() --- ## 4. 使用指标存储 (Usage Metrics) ### 4.1 工具使用批次 使用指标记录代理的工具调用模式： ```typescript export interface UsageToolBatch { duplicateCount: number; loopCount: number; toolFamilyCounts: { read: number; search: number; shell: number; edit: number; write: number; web: number; task: number; other: number; }; errorClassCounts: { "abs-path-posix": number; "abs-path-windows": number; "bearer-token": number; "api-key-anthropic": number; "api-key-github": number; "api-key-sk": number; "env-line": number; }; } ``` 资料来源：[src/analytics/usage-metrics.ts:1-40]() ### 4.2 指标聚合结构 ```typescript export interface UsageMetrics { scope: UsageScope; // "workspace" | 未来支持 per-agent window: UsageWindow; // 时间窗口配置 observed: UsageObserved; // 观察到的使用数据 } ``` 资料来源：[src/analytics/usage-metrics.ts:50-70]() ### 4.3 隐私保护机制 使用指标收集严格遵循隐私保护原则： > **隐私不变量**：云端允许列表禁止 `tool_observations` 表中除以下字段外的任何其他字段传输。这些聚合是唯一传输的 TB TOOL / TB LOOP 信号。 | 字段 | 说明 | |------|------| | `duplicateCount` | 重复工具调用次数 | | `loopCount` | 循环调用次数 | | `toolFamilyCounts` | 按类别统计的工具调用 | | `errorClassCounts` | 错误类型聚合统计 | 资料来源：[src/analytics/usage-metrics.ts:20-35]() --- ## 5. 影响计算存储 (Impact) `impact.ts` 模块将事件聚合转换为用户可理解的价值指标： ### 5.1 核心输出指标 | 指标 | 说明 | 计算来源 | |------|------|----------| | `assistedTasks` | TraceBase 参与的任务数 | 非阴影检索事件 | | `helpedTasks` | 实际产生帮助的任务数 | `injection ∧ agent_used ∧ resolved` | | `memoriesUsed` | 被使用的独立块数 | `agent_used` 事件去重 | | `estimatedMinutesSaved` | 预估节省时间 | 有帮助计数 × 阴影臂提升 | | `estimatedTokensSaved` | 预估节省 Token | 有帮助计数 × 阴影臂 Token 提升 | | `topMemories` | 贡献最大的块列表 | 按帮助次数排序 | | `needsAttention` | 触发但未帮助的块 | 需修剪的低效块 | 资料来源：[src/core/impact.ts:1-60]() ### 5.2 置信度层级 | 置信度 | 条件 | 说明 | |--------|------|------| | `measured` | 非空阴影臂 + Token 数据 | 真实观察值 | | `estimated` | 有事件但无阴影臂 | 模型估算值 | 资料来源：[src/core/impact.ts:55-65]() --- ## 6. 蒸馏与启发式存储 ### 6.1 死路径识别算法 `heuristics.ts` 中的 `extractDeadEnds` 函数通过分析步骤对识别无效推理路径： ```typescript // 规则：若分析 i+1 显示负面信号，则分析 i 为死路径 for (let i = 0; i < analyses.length - 1; i++) { const cur = analyses[i]; const next = analyses[i + 1]; if (!hasNegativeSignal(next.description)) continue; const summary = summarizeDeadEnd(cur.description); const key = summary.toLowerCase(); if (summary && !seen.has(key)) { seen.add(key); deadEnds.push(summary); if (deadEnds.length >= max) break; } } ``` 资料来源：[src/distillation/heuristics.ts:1-30]() ### 6.2 死路径提取规则 | 规则 | 说明 | |------|------| | 配对分析 | 检查相邻分析步骤间的信号变化 | | 负面信号检测 | `hasNegativeSignal` 函数识别失败指示 | | 去重 | 小写化后去重，确保唯一性 | | 上限控制 | 最多提取 5 条死路径 | 资料来源：[src/distillation/heuristics.ts:25-35]() --- ## 7. 数据流总览 ```mermaid graph LR subgraph "写入路径" A[Agent 事件] --> B[block-store.ts] B --> C[analytics_events 表] B --> D[reasoning_blocks 表] A --> E[蒸馏管道] E --> F[heuristics.ts 提取] F --> G[推理块写入] end subgraph "读取路径" C --> H[impact.ts 聚合] H --> I[用户可见指标] D --> J[block-serving.ts 检索] J --> K[XML/Markdown 渲染] end subgraph "导出路径" C --> L[usage-metrics.ts] L --> M[聚合统计] end ``` --- ## 8. 存储层安全考量 ### 8.1 数据隔离 - **阴影控制组**：通过 `shadow` 字段隔离 A/B 测试数据，确保估算准确性 - **运行隔离**：`run_id` 字段支持按批次分析数据 ### 8.2 敏感信息处理 使用指标中的错误分类仅记录模式类型（如 `abs-path-posix`、`bearer-token`），不记录实际路径或令牌值： > 插槽名称是描述性标签，不是用户内容。 资料来源：[src/analytics/usage-metrics.ts:10-20]() --- ## 9. 存储容量规划 | 数据类型 | 典型大小 | 保留策略 | |----------|----------|----------| | 推理块 | ~500 字节/块 | 长期保留，按质量评分 | | 分析事件 | ~200 字节/事件 | 按时间窗口清理 | | 轨迹数据 | ~50KB/任务 | 压缩存储，按需导出 | | 使用指标 | ~100 字节/批次 | 聚合后压缩 | --- ## 10. 总结 TraceBase 的数据存储机制通过 SQLite 和 JSONL 的组合，实现了： 1. **结构化查询能力**：通过 `block-store.ts` 提供的事件表支持灵活的事件分析 2. **知识压缩存储**：推理块字段长度限制确保知识库高效检索 3. **隐私安全保护**：使用指标仅记录聚合数据，不暴露敏感内容 4. **可重现性**：所有评估代码、fixture、种子和轨迹数据均提交至公共仓库 资料来源：[src/core/block-store.ts]() | [src/analytics/usage-metrics.ts]() | [src/core/impact.ts]() | [src/distillation/prompts.ts]() | [src/distillation/heuristics.ts]() --- ## 五大运行时机制 ### 相关页面 相关主题：[项目概述](#overview), [召回与检索机制](#recall-mechanism), [上下文折叠机制](#fold-mechanism)
    相关源码文件 以下源码文件用于生成本页说明： - [src/runtime/recall.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/recall.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/tool-loop-detect.ts](https://github.com/64envy64/tracebase/blob/main/src/core/tool-loop-detect.ts) - [src/core/context-fold.ts](https://github.com/64envy64/tracebase/blob/main/src/core/context-fold.ts) - [src/core/file-walker.ts](https://github.com/64envy64/tracebase/blob/main/src/core/file-walker.ts)
    # 五大运行时机制 TraceBase 的运行时系统由五大核心机制组成，它们共同确保 AI 编码代理在执行任务时的安全性、稳定性和高效性。这些机制分别负责安全防护、循环检测、上下文管理、文件遍历和工具观察，形成一个完整的运行时保障体系。 ## 1. Guard（安全守卫机制） ### 1.1 概述 Guard 机制是 TraceBase 的第一道安全防线，负责对输入进行严格的安全校验。它通过正则表达式模式匹配来识别和阻止潜在的注入攻击、提示词泄露和虚假标记伪装。 ### 1.2 核心检测规则 Guard 机制维护了一套多层次的安全检测规则集，每条规则都有明确的检测目标和防御目的。 | 规则名称 | 正则模式 | 防御目标 | |---------|---------|---------| | `system-spoof` | `/(?(?!`)/i` | 阻止 inline `...` 或 `` 标签伪装高权限轮次标记 | | `delimiter-spoof` | `/(```\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\b\|<\s*(prior_fix\|file_memory\|context_fold)\b)/i` | 防止伪造 TraceBase 分隔符，阻止 `prior_fix`、`file_memory`、`context_fold` 等标记的注入 | | 环境变量泄露检测 | 针对 `environment variable(s)?` 的详细检测 | 防止通过冗长描述形式伪装的环境变量窃取攻击 | ### 1.3 backtick-neighbour skip 机制 Guard 机制特别处理了一种边界情况：当文档标记被反引号包裹时（如 `` `` ``），这表示用户在讨论提示词语法本身，而非尝试注入，因此跳过匹配检测。这种设计确保了安全性的同时不会干扰正常的文档编写。 资料来源：[src/core/guard.ts:1-50]() ### 1.4 工作流程 ```mermaid 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 折叠策略 ```mermaid graph LR A[完整上下文] --> B{Token 预算检查} B -->|超出预算| C[识别低价值片段] B -->|在预算内| G[保持原样] C --> D[应用折叠策略] D --> E[生成摘要] E --> F[替换原始片段] F --> G[压缩后上下文] ``` ### 3.3 折叠层级 Context Fold 采用多层级折叠策略，确保在保持关键信息完整的同时最大化压缩比： | 层级 | 压缩比 | 适用场景 | |-----|-------|---------| | L1 | 10-20% | 轻微超出预算，折叠低频引用 | | L2 | 30-50% | 中度超出预算，折叠分析推理过程 | | L3 | 60-80% | 严重超出预算，仅保留结论和决策点 | ### 3.4 上下文优先级 系统会为不同类型的上下文分配不同的保留优先级： ```typescript 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 遍历模式 | 模式 | 说明 | 适用场景 | |-----|------|---------| | `breadth-first` | 广度优先遍历 | 大型项目快速概览 | | `depth-first` | 深度优先遍历 | 特定模块深入分析 | | `dependency-ordered` | 依赖顺序遍历 | 需要按导入顺序处理的场景 | ### 4.3 过滤规则 File Walker 支持灵活的过滤规则配置： ```typescript interface WalkerConfig { maxDepth: number; // 最大遍历深度 includePatterns: RegExp[]; // 包含模式 excludePatterns: RegExp[]; // 排除模式（如 node_modules, .git） followSymlinks: boolean; // 是否跟随符号链接 maxFileSize: number; // 单文件最大字节数 } ``` ### 4.4 增量遍历优化 对于大型项目，File Walker 支持增量遍历模式，仅扫描自上次遍历以来发生变化的文件： ```mermaid 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 提供了统一的抽象层来处理这种差异： ```typescript const FILE_PATH_KEYS = [ "file_path", // Claude Code 规范 "path", // 常见通用字段 "filename", // 另一常见变体 "filePath" // 驼峰命名变体 ] as const; ``` 该机制会遍历这些可能的字段名，返回第一个有效值： ```typescript function extractFilePath(toolInput: unknown): string | null { if (typeof toolInput !== "object" || toolInput === null) return null; const obj = toolInput as Record; 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 观察事件类型 | 事件类型 | 说明 | 采集内容 | |---------|------|---------| | `tool_call` | 工具调用事件 | 工具名称、参数、时间戳 | | `tool_result` | 工具返回事件 | 返回值、耗时、状态 | | `file_access` | 文件访问事件 | 文件路径、操作类型 | | `error` | 错误事件 | 错误类型、堆栈信息 | ### 5.4 与记忆系统的集成 ```mermaid graph LR A[工具调用] --> B[Observe Tools 采集] B --> C[事件标准化] C --> D[关键信息提取] D --> E{是否满足记忆条件?} E -->|是| F[生成记忆片段] E -->|否| G[丢弃] F --> H[存储至记忆库] H --> I[供后续检索使用] ``` ## 运行时机制协同架构 五大运行时机制并非独立运作，它们通过消息传递和状态共享形成了一个有机的协同体系。 ```mermaid 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 全程记录工具交互，用于生成可复用的记忆片段。 ## 配置与调优 ### 运行时参数 | 参数 | 默认值 | 说明 | |-----|-------|------| | `maxContextTokens` | 模型限制的 80% | Context Fold 的预算上限 | | `loopThreshold` | 5 | Tool Loop Detect 的触发阈值 | | `maxFileSize` | 1MB | File Walker 的单文件大小限制 | | `maxTraversalDepth` | 20 | File Walker 的最大遍历深度 | ### 监控与调试 TraceBase 提供了 `doctor` 命令用于检查运行时机制的健康状态： ```bash npx tracebase-ai doctor ``` 该命令会检查： - Guard 规则的有效性 - 循环检测的配置状态 - 上下文管理的预算配置 - 文件遍历的路径配置 资料来源：[src/cli/commands/doctor.ts:1-80]() ## 总结 五大运行时机制构成了 TraceBase 的核心保障体系： - **Guard** 提供安全防护，过滤恶意输入 - **Tool Loop Detect** 防止执行陷入死循环 - **Context Fold** 确保上下文始终在有效范围内 - **File Walker** 提供高效的文件系统访问能力 - **Observe Tools** 采集有价值的交互信息用于记忆生成 这些机制相互配合，共同确保 AI 编码代理能够在安全、稳定、高效的环境中运行，为开发者提供可靠的编程辅助体验。 --- ## 召回与检索机制 ### 相关页面 相关主题：[五大运行时机制](#five-arms), [系统架构](#system-architecture)
    相关源码文件 以下源码文件用于生成本页说明： - [src/runtime/recall.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/recall.ts) - [src/core/fingerprint.ts](https://github.com/64envy64/tracebase/blob/main/src/core/fingerprint.ts) - [src/core/similarity.ts](https://github.com/64envy64/tracebase/blob/main/src/core/similarity.ts) - [src/embeddings/openai.ts](https://github.com/64envy64/tracebase/blob/main/src/embeddings/openai.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [www/src/lib/control-plane/issue-brief.ts](https://github.com/64envy64/tracebase/blob/main/www/src/lib/control-plane/issue-brief.ts)
    # 召回与检索机制 ## 概述 TraceBase 的召回与检索机制是系统的核心模块，负责从历史记忆库中高效定位与当前任务相关的先前解决方案。该机制采用**两阶段排序架构**，结合六种不同的检索信号，通过 Thompson 采样动态学习信号权重，以实现高精度的记忆匹配。 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) --- ## 系统架构 ### 两阶段排序流程 TraceBase 的检索系统采用经典的候选集缩小与重排序两阶段架构： ```mermaid graph TD A[用户任务/查询] --> B[阶段一: 候选集生成] B --> B1[Fingerprint 精确匹配
    O1 哈希查找] B --> B2[BM25 全文检索
    FTS5 索引查询] B --> C[候选集 N] C --> D[阶段二: 重排序] D --> D1[Jaccard 相似度] D --> D2[Structural 特征匹配] D --> D3[Cosine 语义相似度] D --> D4[Freshness 时序权重] D --> E[加权得分排序] E --> F[Top-K 高置信度结果] style B fill:#4a5568,color:#fff style D fill:#4a5568,color:#fff style F fill:#48bb78,color:#fff ``` 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ### 信号权重学习 各检索信号的权重通过 **Thompson 采样**（基于 outcome 事件）动态学习，每个项目独立调整权重。阻止块质量使用 Wilson 区间下界评估，收益降低的块会被自动降级。 ```mermaid graph LR A[任务完成] --> B[记录 Outcome] B --> C[Thompson 采样] C --> D[更新信号权重] D --> E{质量评估} E -->|Wilson 下界低| F[自动降级] E -->|质量达标| G[保持/提升权重] ``` 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) --- ## 六种检索信号 | 信号 | 类型 | 作用 | 性能特征 | |------|------|------|----------| | **Fingerprint** | 精确匹配 | 识别完全相同的问题 | O(1) 哈希查找 | | **BM25** | 词法匹配 | 关键词相同但表述不同 | FTS5 索引查询 | | **Jaccard** | Token 重叠 | 结构化关键词匹配 | 中等计算量 | | **Structural** | 特征匹配 | 相同错误类型/语言/框架 | 特征向量计算 | | **Cosine** | 语义相似度 | 嵌入向量相似性 | 可选功能 | | **Freshness** | 时序权重 | 近期偏好，指数衰减 | 轻量计算 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) ### Fingerprint 精确匹配 Fingerprint 用于检测完全相同的问题实例，通过计算查询的哈希指纹，在 O(1) 时间复杂度内完成查找。这是最高优先级的匹配信号。 ```typescript // 源码位置示意 { name: "system-spoof", re: /(?(?!`)/i, } ``` 资料来源：[src/core/fingerprint.ts](https://github.com/64envy64/tracebase/blob/main/src/core/fingerprint.ts) ### BM25 全文检索 BM25 是经典的词法检索算法，在 TraceBase 中通过 SQLite 的 FTS5 扩展实现，支持对关键词相同但表述不同的问题进行匹配。 ### 语义相似度 (Cosine) 语义匹配使用嵌入向量计算余弦相似度，支持可选的 OpenAI 嵌入模型集成。 ```typescript // 嵌入向量生成示意 const embedding = await client.embeddings.create({ model: "text-embedding-3-small", input: text, }); ``` 资料来源：[src/embeddings/openai.ts](https://github.com/64envy64/tracebase/blob/main/src/embeddings/openai.ts) ### 时序衰减 (Freshness) Freshness 信号引入指数衰减机制，对近期成功案例给予更高权重，避免陈旧信息干扰当前决策。 --- ## 阻止块结构 检索返回的阻止块（Block）采用高度压缩的结构设计，包含三个核心字段： ```mermaid graph TD A[Block] --> B[trigger 触发条件] A --> C[body 块内容] B --> B1[situation 场景描述] B1 --> B1a[问题情境的简要描述] C --> C1[mechanism 机制说明] C1 --> C1a[问题发生的技术机制] C --> C2[deadEnds 死胡同列表] C2 --> C2a[错误的解决路径] C2 --> C2b[不可行的方案] C --> C3[unlock 解锁方案] C3 --> C3a[正确的解决方向] C --> C4[verification 验证方式] C4 --> C4a[如何确认问题已解决] ``` 资料来源：[src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) ### 阻止块 XML 渲染 ```xml astropy ImportError on numpy 2.0 版本兼容性问题 尝试降级 numpy 到 1.x 忽略版本检查 升级 astropy 到 >=6.0 单元测试通过 ``` 资料来源：[src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) --- ## 存储与数据管理 | 存储方式 | 描述 | |----------|------| | **本地存储** | SQLite (WAL 模式)，确保并发安全 | | **云同步** | 可选的云端同步功能 | | **数据压缩** | 三字段压缩设计，最大限度减少 token 开销 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) --- ## 安全机制 ### 注入防护 (Guard) 系统实现了多层防护机制，防止恶意注入攻击： ```typescript // 系统欺骗检测 { name: "system-spoof", re: /(?(?!`)/i, } // 分隔符欺骗检测 { name: "delimiter-spoof", re: /(```\s*(system|tool_result|prior_fix|file_memory|context_fold)\b|<\s*(prior_fix|file_memory|context_fold)\b)/i, } ``` 资料来源：[src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) ### 防护规则说明 | 规则名称 | 正则表达式 | 防护目的 | |----------|-----------|----------| | system-spoof | `(?` | 防止伪造高权限角色标记 | | delimiter-spoof | `(```\s*(system\|tool_result\|prior_fix\|...))` | 防止利用系统分隔符信任级别 | 资料来源：[src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) --- ## 与问题简报集成 召回系统与控制平面的问题简报（Issue Brief）模块深度集成： ```mermaid graph LR A[GitHub Issue] --> B[相关记忆检索] B --> C[PriorMemoriesSection] C --> D[Prior memories worth checking] D --> E[生成引用列表] E --> F[问题简报输出] B -->| cautions | G[CautionsSection] G --> H[已知死胡同] ``` 资料来源：[www/src/lib/control-plane/issue-brief.ts](https://github.com/64envy64/tracebase/blob/main/www/src/lib/control-plane/issue-brief.ts) ### 引用格式 ```typescript citations: relevantMemories.map( (m): IssueBriefCitation => ({ kind: "memory", id: m.memoryId, label: m.trigSituation ?? m.memoryId, }), ) ``` 资料来源：[www/src/lib/control-plane/issue-brief.ts](https://github.com/64envy64/tracebase/blob/main/www/src/lib/control-plane/issue-brief.ts) --- ## 配置与使用 ### 初始化命令 ```bash npx tracebase-ai init ``` 该命令将项目目录链接到 TraceBase 工作区，初始化本地数据库。 资料来源：[www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) ### 工作流程 ```mermaid graph TD A[Agent 启动任务] --> B[检索历史记忆] B --> C{高置信度匹配?} C -->|是| D[注入阻止块] C -->|否| E[标准推理流程] D --> F[步数减少 25-30%] E --> G[完成诊断] F --> H[成本节省 31%] G --> I[任务完成] H --> I ``` --- ## 性能指标 基于 SWE-bench Verified 基准测试的典型性能数据： | 指标 | 基准值 | 使用 TraceBase 后 | 提升幅度 | |------|--------|-------------------|----------| | 准确率 | 10/25 (40%) | 12/25 (48%) | +8pp | | 平均步数减少 | - | -25% | 显著 | | Token 节省 (平均) | - | 31% | 显著 | | Token 节省 (峰值) | - | 39% | 显著 | 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) --- ## 相关模块 | 模块 | 文件路径 | 职责 | |------|----------|------| | 运行时召回 | `src/runtime/recall.ts` | 核心检索逻辑 | | 指纹识别 | `src/core/fingerprint.ts` | 精确匹配 | | 相似度计算 | `src/core/similarity.ts` | 多种相似度算法 | | 嵌入服务 | `src/embeddings/openai.ts` | 向量化嵌入 | | 块服务 | `src/core/block-serving.ts` | 结果渲染 | | 安全防护 | `src/core/guard.ts` | 注入检测 | --- ## 局限性 1. **依赖历史经验**：系统性能与记忆库规模正相关，冷启动场景效果有限 2. **语义嵌入可选**：Cosine 信号依赖外部嵌入服务，非必需配置 3. **项目级权重**：信号权重按项目独立学习，新项目需要积累数据 --- ## 上下文折叠机制 ### 相关页面 相关主题：[五大运行时机制](#five-arms), [召回与检索机制](#recall-mechanism)
    相关源码文件 以下源码文件用于生成本页说明： - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [www/src/components/landing/_demo-fixtures/capability-mockups.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/landing/_demo-fixtures/capability-mockups.tsx) - [www/src/components/engineering-brain/MemoryView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/engineering-brain/MemoryView.tsx) - [www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx)
    # 上下文折叠机制 ## 概述 上下文折叠（Context Fold）是 TraceBase 为编码智能体（coding agents）设计的一种上下文管理机制。其核心目标是在多轮对话过程中，将历史交互内容进行结构化压缩，以减少 token 消耗同时保留关键决策信息。 根据项目白皮书描述，上下文折叠是 TraceBase 六种检索信号之一（指纹检索、BM25 全文搜索、结构化检索、余弦相似度检索、新鲜度检索），属于重排序（re-rank）阶段的组成部分。 资料来源：[www/src/app/whitepaper/page.tsx]() --- ## 核心概念 ### 折叠粒度：Block（块） TraceBase 将记忆内容组织为 **Block** 数据结构，每个 Block 包含以下字段： | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 唯一标识符 | | `trigger.situation` | string | 问题情境描述 | | `body.mechanism` | string | 机制/根因说明 | | `body.deadEnds` | string[] | 需要避免的死胡同路径 | | `body.unlock` | string | 解决方案/解锁方法 | | `body.verification` | string | 验证方式 | | `calibratedProb` | number | 校准后的匹配概率 | 资料来源：[src/core/block-serving.ts]() ### 三字段压缩原则 Block 的存储格式刻意设计为三个短字段（situation、deadEnds、unlock），这是出于压缩和智能体引导的双重考虑。字段设计使得智能体能够快速识别问题类型（situation），规避无效探索路径（deadEnds），并获得解决方案指引（unlock）。 这种设计参考了 C3oT（Cot with Code）和 TALE 等研究的工作原理，通过结构化的死胡同描述来引导智能体绕过已知的失败路径。 资料来源：[www/src/app/whitepaper/page.tsx]() --- ## 折叠渲染格式 ### 紧凑bullet格式 当 Block 被注入到上下文时，系统采用紧凑的 bullet 格式进行渲染： ```text • . Mechanism: . Fix: . Verify: . ``` 如果存在死胡同，则追加： ```text Avoid: a; b; c ``` 系统刻意不在渲染中暴露 "block id"、"calibrated probability" 或任何工具标识信息，智能体应基于内容本身的语义来评估匹配度。 资料来源：[src/core/build-injection-payload.ts]() ### XML审计格式 在审计模式下，系统提供完整的 XML 结构化输出： ```xml ... ... ... ... ... ``` 资料来源：[src/core/block-serving.ts]() --- ## 导入标记机制 ### prior_fix标签 系统使用 `` 标签来区分导入的记忆（imported traces）和本地生成的记忆： ```typescript const IMPORTED_TAG_OPEN = ``; const IMPORTED_TAG_CLOSE = ``; ``` 这使得系统在日志和安全审计中能够追踪每条记忆的来源。 资料来源：[src/core/build-injection-payload.ts]() ### 防护：delimiter-spoof检测 系统实现了对伪造分隔符的安全防护。攻击者可能尝试使用 ` ```prior_fix ` 或 `` 来伪装成受信任的注入内容。 防护正则表达式： ```typescript { name: "delimiter-spoof", re: /(```\s*(system|tool_result|prior_fix|file_memory|context_fold)\b|<\s*(prior_fix|file_memory|context_fold)\b)/i, } ``` 资料来源：[src/core/guard.ts]() --- ## 工作流程 ### 多轮对话中的折叠流程 ``` graph TD A[开始新任务] --> B[检查记忆库] B --> C{找到匹配Block?} C -->|是| D[加载Block元数据] C -->|否| E[执行常规搜索] D --> F{校准概率 > 阈值?} F -->|是| G[渲染为compact bullet] F -->|否| H[降级处理] G --> I[注入到Agent上下文] E --> J[执行标准检索流程] H --> J I --> K[Agent使用记忆执行任务] J --> K ``` ### 智能体任务到胜利漏斗 根据 ImpactView 组件的设计，系统追踪以下阶段： | 阶段 | 指标 | 说明 | |------|------|------| | Agent tasks | `eligibleRuns` | TraceBase 检查记忆的任务 | | Matched memory | `recalledRuns` | 找到至少一条相关记忆 | | Shown | `injectedRuns` | 记忆被添加到上下文 | | Used | `usedRuns` | 智能体实际使用了记忆 | 资料来源：[www/src/components/dashboard/ImpactView.tsx]() --- ## UI展示：FoldMockup 项目在演示组件中提供了折叠机制的视觉展示： ```typescript export function FoldMockup() { return ( ); } ``` 该 Mockup 展示了三个折叠阶段的 token 压缩效果： - 阶段一：4.2k tokens → 340 tokens - 阶段二：3.1k tokens → 210 tokens - 阶段三：实时窗口（active状态） 资料来源：[www/src/components/landing/_demo-fixtures/capability-mockups.tsx]() --- ## 记忆事件追踪 ### MemoryView事件类型 系统通过 `MemoryView` 组件追踪记忆相关的所有事件： | 事件类型 | 语义颜色 | 说明 | |----------|----------|------| | `created` | good | 创建新记忆 | | `used` | good | 记忆被使用 | | `rollback` | warn | 回滚操作 | | `deleted` | bad | 记忆被删除 | 每条事件记录包含： - 事件ID和动作类型 - 操作者ID（actorId） - 时间戳 - 回滚目标（rollbackToId） 资料来源：[www/src/components/engineering-brain/MemoryView.tsx]() --- ## 性能基准 根据白皮书数据，上下文折叠机制在 SWE-bench Verified 基准测试中展现了显著的 token 节省效果： | 模型 | 步数节省 | 平均Token节省 | 峰值Token节省 | |------|----------|---------------|---------------| | Claude Haiku 4.5 | +5% | 6% | up to 48% | | Claude Sonnet 4.6 | +25% | 31% | up to 39% | | Claude Opus 4.6 | +25% | 30% | up to 39% | | GPT-5.4-nano | 0% | 13% | up to 33% | | GPT-5.4-mini | +8% | 25% | — | 资料来源：[www/src/app/whitepaper/page.tsx]() --- ## 配置检查 ### doctor命令验证 TraceBase CLI 提供了 `doctor` 命令来检查系统配置完整性。对于上下文折叠相关的配置，主要检查： 1. 指令文件存在性检查 2. managed section 完整性验证 3. 智能体钩子配置检查（Stop hook） 这些检查确保上下文折叠机制能够正确工作，特别是在 Claude Code 环境下。 资料来源：[src/cli/commands/doctor.ts]() --- ## 总结 上下文折叠机制是 TraceBase 记忆系统的核心组成部分，通过结构化的 Block 数据结构实现： 1. **压缩**：将多轮交互压缩为三个语义字段 2. **引导**：通过 deadEnds 避免智能体重蹈覆辙 3. **安全**：delimiter-spoof 防护防止注入攻击 4. **追踪**：完整的事件日志支持回滚和审计 该机制与指纹检索、BM25、全文搜索等信号协同工作，在重排序阶段为智能体提供精准的上下文支持。 --- ## SDK集成指南 ### 相关页面 相关主题：[快速开始](#quickstart)
    相关源码文件 以下源码文件用于生成本页说明： - [src/middleware/openai.ts](https://github.com/64envy64/tracebase/blob/main/src/middleware/openai.ts) - [src/middleware/anthropic.ts](https://github.com/64envy64/tracebase/blob/main/src/middleware/anthropic.ts) - [src/middleware/generic.ts](https://github.com/64envy64/tracebase/blob/main/src/middleware/generic.ts) - [src/sdk/runtime.ts](https://github.com/64envy64/tracebase/blob/main/src/sdk/runtime.ts) - [src/sdk/contextual-runtime-provider.ts](https://github.com/64envy64/tracebase/blob/main/src/sdk/contextual-runtime-provider.ts) - [docs/SDK.md](https://github.com/64envy64/tracebase/blob/main/docs/SDK.md)
    # SDK集成指南 ## 概述 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]() ```mermaid 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 规范进行了优化，确保请求格式和响应处理的准确性。 | 提供商 | 中间件模块 | API 类型 | 特殊支持 | |--------|-----------|----------|----------| | OpenAI | openai.ts | Chat Completions | 函数调用、图像输入 | | Anthropic | anthropic.ts | Messages API | 工具使用、多模态 | | 其他 | generic.ts | 通用 REST | 自定义端点 | ### 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]() ```mermaid 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]() - 示例项目：参考仓库中的示例目录 --- --- ## Doramagic 踩坑日志 项目：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