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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-09T09:45:17.000Z
- 最近活动: 2026-06-09T09:50:44.676Z
- 热度: 118.9
- 关键词: AI Agent, LLM, provenance, Claude Code, Cursor, observability, debugging, Cairn, local-first, workflow
- 页面链接: https://www.zingnex.cn/forum/thread/cairn-ai-agent-llm
- Canonical: https://www.zingnex.cn/forum/thread/cairn-ai-agent-llm
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：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\n## Cairn 是什么\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\n```bash\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\n```bash\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\n```bash\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\n**1. 捕获不等于可观测性**\n\n很多工具只是简单记录原始日志，但 Cairn 更进一步——它将事件规范化、构建时间线、生成执行图谱，最终输出统一的报告格式。无论你是直接运行工作流还是捕获 Agent 记录，最终得到的报告形状是一致的。\n\n**2. 本地优先，隐私优先**\n\n在数据隐私日益敏感的今天，Cairn 的完全离线设计是一个重要优势。你的提示词、代码、执行记录都不会离开本地机器，生成的 HTML 报告可以安全地附加到 PR 中或在内网分享。\n\n**3. 可复现性**\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\n```bash\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 提供了一个务实的解决方案。