Cairn：AI Agent 与 LLM 工作流的本地溯源工具

Cairn 是一款本地优先的 AI Agent 溯源工具，能够记录提示词、工具调用、生成产物和 Token 消耗，并生成可离线查看的 HTML 报告，支持 Claude Code、Cursor、Codex 等多种 Agent 来源。

• 原作者/维护者：Harsh-Daga
• 来源平台：github
• 原始标题：Cairn: Local-first provenance for AI agents and LLM workflows
• 原始链接：https://github.com/Harsh-Daga/Cairn
• 来源发布时间/更新时间：2026-06-09T09:45:17Z

原作者与来源

• 原作者/维护者：Harsh-Daga
• 来源平台：github
• 原始标题：Cairn: Local-first provenance for AI agents and LLM workflows
• 原始链接：https://github.com/Harsh-Daga/Cairn
• 来源发布时间/更新时间：2026-06-09T09:45:17Z 原作者与来源\n\n- 原作者/维护者：Harsh Daga\n- 来源平台：GitHub\n- 原始标题：Cairn: Local-first provenance for AI agents and LLM workflows\n- 原始链接：https://github.com/Harsh-Daga/Cairn\n- 发布时间：2026年6月9日\n\n背景：Agent 时代的溯源困境\n\n随着 Claude Code、Cursor、GitHub Copilot 等 AI 编程助手的普及，开发者的日常编码工作流正在被重构。然而，这种变革带来了一个被严重低估的问题：溯源（Provenance）的碎片化。\n\n当你混合使用 Claude Code 的对话、Cursor 的代码生成、以及直接调用 LLM API 的脚本时，所有的执行记录散落在各处——JSONL 日志文件、聊天导出、SaaS 平台仪表盘。当需要复盘某个决策是如何做出的、某个 bug 是如何引入的，或者向团队证明代码的可靠性时，你会发现自己面对的是一个信息黑洞。\n\n这正是 Cairn 试图解决的问题。\n\nCairn 是什么\n\nCairn 是一个本地优先的溯源框架，它的核心使命很简单：记录你的 AI Agent 和 LLM 工作流实际做了什么，并将其转化为可分享的 HTML 报告。\n\n关键特性包括：\n\n- 单一账本：统一的规范化事件格式，无论数据来自哪个 Agent 或 API\n- 执行图谱：可视化展示调用链、依赖关系和执行时间线\n- 完全离线：生成的报告是独立的 HTML 文件，无需服务器、无需账号、无需 CDN\n- 双模式支持：既可以直接运行 LLM 工作流（Provider 模式），也可以捕获已有 Agent 的执行记录（Capture 模式）\n\n两种使用路径\n\n路径一：Provider 模式——直接运行 LLM 工作流\n\n在 Provider 模式下，你需要在项目中声明 cairn.toml 配置文件，定义工作流步骤。Cairn 会基于内容哈希缓存结果，支持离线回放。\n\n典型的工作流程：\n\nbash\n验证配置\ncairn validate\n\n查看可用工作流\ncairn workflow list\n\n离线模式运行（使用缓存记录）\ncairn build --yes --provider-mode recorded\n\n实时模式运行（调用真实 API）\ncairn build --yes --provider-mode live\n\n生成报告\ncairn report --json\ncairn render -o outputs/bundle --zip\n\n\nCairn 支持通过 Ollama Cloud 运行实时构建，只需配置 API Key 即可：\n\nbash\nexport OLLAMA_CLOUD_API_KEY=your-key\ncairn doctor\ncairn build --yes --provider-mode live --refresh summaries\n\n\n路径二：Agent Capture 模式——捕获已有 Agent 的执行记录\n\n这是 Cairn 更常见的使用场景。你不需要修改现有项目结构，只需在任意 Git 仓库中运行捕获命令：\n\nbash\n从 Claude Code 导入会话\ncairn ingest --source claude-code\n\n列出所有会话\ncairn sessions list\n\n查看特定会话详情\ncairn show sess-redacted-001\n\n生成报告\ncairn render --session sess-redacted-001 -o outputs/capture-bundle\n\n本地预览\ncairn live serve --session sess-redacted-001 --port 8787\n\n\n目前支持的 Agent 来源包括 Claude Code，未来计划支持更多主流 Agent 平台。\n\n核心设计哲学\n\nCairn 的设计体现了几个值得关注的理念：\n\n1. 捕获不等于可观测性\n\n很多工具只是简单记录原始日志，但 Cairn 更进一步——它将事件规范化、构建时间线、生成执行图谱，最终输出统一的报告格式。无论你是直接运行工作流还是捕获 Agent 记录，最终得到的报告形状是一致的。\n\n2. 本地优先，隐私优先\n\n在数据隐私日益敏感的今天，Cairn 的完全离线设计是一个重要优势。你的提示词、代码、执行记录都不会离开本地机器，生成的 HTML 报告可以安全地附加到 PR 中或在内网分享。\n\n3. 可复现性\n\n通过版本化的提示词和基于内容哈希的缓存机制，Cairn 确保了工作流的可复现性。这对于需要审计追踪的企业场景尤为重要。\n\n技术实现细节\n\nCairn 基于 Python 开发，使用 pyproject.toml 管理依赖。项目结构清晰，包含：\n\n- cairn/：核心库代码\n- examples/e2e-demo/：端到端演示\n- tests/：测试套件\n- docs/：文档\n- .github/workflows/：CI/CD 配置\n\n安装方式简单，支持通过 curl 一键安装：\n\nbash\ncurl -fsSL https://raw.githubusercontent.com/Harsh-Daga/Cairn/main/install.sh | bash\n\n\nWindows 用户可使用 PowerShell 安装脚本 install.ps1。\n\n应用场景\n\nCairn 适用于多种场景：\n\n- 代码审查：将 Agent 的完整执行过程作为 PR 附件，让审查者了解变更背后的推理过程\n- 故障排查：当 Agent 产生意外结果时，通过执行图谱快速定位问题根源\n- 合规审计：企业需要记录 AI 辅助开发过程以满足合规要求\n- 知识沉淀：将成功的 Agent 会话转化为可复用的工作流模板\n\n局限与展望\n\n作为早期项目，Cairn 目前主要支持 Claude Code 作为 Agent 来源，对其他流行平台（如 Cursor、GitHub Copilot Chat）的支持仍在开发中。此外，执行图谱的交互性和可视化效果还有提升空间。\n\n但 Cairn 提出的"本地优先溯源"理念无疑是正确的方向。在 AI Agent 日益成为开发工作流核心组件的今天，我们需要更好的工具来理解、记录和分享这些智能助手的工作过程。\n\n总结\n\nCairn 填补了 AI Agent 生态中的一个重要空白——可审计、可分享、完全离线的执行溯源。对于希望引入 AI 编程助手但又担心失去透明度和控制权的团队来说，Cairn 提供了一个务实的解决方案。