Spanory：跨运行时AI智能体可观测性工具的设计与实战

1. 项目概述为什么我们需要一个跨运行时的AI智能体可观测性工具如果你和我一样日常开发中重度依赖Claude Code、Codex这类AI编程助手那你肯定遇到过这样的场景助手帮你写了一段代码调用了几个工具执行了几条shell命令整个过程看起来行云流水。但当你回过头想复盘一下——“刚才那个函数重构AI到底是怎么一步步思考的”或者“这次会话里它调用MCPModel Context Protocol服务的成功率如何”——你会发现除了聊天窗口里那一长串的对话记录你几乎找不到任何结构化的、可供分析的数据。这就是当前AI智能体生态的一个普遍痛点数据丰富但观测缺失。每个智能体运行时Runtime——无论是Claude Code、Codex还是新兴的OpenClaw、OpenCode——都在本地生成了包含“回合”Turn、工具调用、MCP交互、Shell命令等丰富信息的会话记录。但这些数据是孤立的、非结构化的散落在各个运行时的配置目录里格式各异。你没有一个统一的视角去收集、追踪和观测这些事件更谈不上进行跨会话、跨运行时的聚合分析与性能洞察。Spanory就是为了解决这个问题而生的。它不是一个全新的监控系统而是一个桥梁一个翻译器。它的核心设计哲学是不改变你使用AI助手的习惯也不侵入助手的核心逻辑而是通过标准化的钩子Hook和插件Plugin机制悄无声息地将各个运行时产生的“方言”日志翻译成通用的“普通话”——OpenTelemetry追踪数据然后发送到你熟悉的观测后端比如Langfuse。简单来说Spanory让你能用一条统一的CLI命令为所有主流的AI编程助手装上“黑匣子”和“数据仪表盘”。你不再需要为每个助手单独写解析脚本或者手动从JSON文件里扒数据。无论是实时观测每一次工具调用的耗时还是离线回溯分析过去一周所有会话中Shell命令的使用模式Spanory都提供了一套完整的、开箱即用的方案。2. 核心架构解析从“方言”到“普通话”的统一事件模型要理解Spanory怎么工作得先看看它怎么“思考”。它的架构非常清晰遵循了“采集-转换-输出”的管道模式并且每个环节都是可插拔的。2.1 核心数据流与组件职责整个系统的数据流可以概括为RuntimeAdapter → Canonical Events → BackendAdapter → OTLP Core → OTLP HTTP。RuntimeAdapter运行时适配器这是数据入口。每个支持的AI智能体运行时如claude-codecodex都有一个对应的适配器。它的职责是理解该运行时特有的日志格式和存储位置例如Claude Code的~/.claude/state/sessions/ Codex的~/.codex/sessions/并将原始日志解析出来。Canonical Events规范事件模型这是Spanory内部定义的、统一的数据表示层即SpanoryEvent。无论原始数据来自哪里最终都会被映射成这个模型。它定义了观测AI智能体所需的核心实体turn: 一次完整的用户与AI的交互回合。agent_command: AI助手发出的高层指令如“分析代码”。shell_command: 在终端中执行的具体Shell命令。mcp: 通过Model Context Protocol进行的工具或服务调用。agent_task: AI内部拆解的子任务。tool: 调用的具体工具函数。 这个模型是Spanory的“灵魂”它确保了不同来源的数据在语义上是一致的后续的分析和上报才有了共同的基础。BackendAdapter后端适配器这是数据出口的抽象。虽然当前主要甚至是唯一的输出方式是OpenTelemetry OTLP但设计上预留了适配其他后端的可能性。bububuger/backend-langfuse就是一个后端适配器的实现它知道如何将规范的SpanoryEvent转换成Langfuse期望的OTLP格式和字段。OTLP Core Transport这是实际的传输层。bububuger/otlp-core封装了OpenTelemetry Protocol的构建和发送逻辑处理诸如批处理、重试、压缩等网络传输细节。这种架构的好处是高内聚、低耦合。如果你想支持一个新的AI助手只需要实现一个新的RuntimeAdapter如果你想将数据发送到Datadog或Jaeger也只需要实现一个新的BackendAdapter。核心的解析逻辑和事件模型是稳定的。2.2 插件化设计与零Cron理念Spanory另一个巧妙的设计是它对“实时性”的处理。传统的日志收集往往依赖定时任务Cron去轮询扫描新文件。但对于AI交互这种高频、即时的事件轮询不仅有延迟还浪费资源。Spanory采用了“钩子Hook 插件Plugin”的模式来实现近实时Near Real-Time采集对于支持钩子的运行时如Claude Code、CodexSpanory会将自己配置为SessionEnd会话结束或Stop每回合结束事件的钩子命令。当事件触发时运行时会将当前会话的上下文Payload通过标准输入stdin传递给spanory hook命令后者立即解析并上报。特别推荐绑定Stop事件这样你几乎能在AI每回答完一句话后就看到对应的追踪数据出现在观测平台上体验是实时的。对于支持插件的运行时如OpenClaw、OpenCodeSpanory提供了原生插件。插件直接运行在智能体进程内可以监听更精细的内部事件实现真正的“零延迟”采集。安装后数据上报对用户完全透明。“零Cron”意味着你不需要设置任何定时任务。数据流动是由智能体自身的事件驱动的既高效又及时。同时Spanory也提供了backfill命令用于补录历史数据兼顾了实时与离线的需求。3. 实战部署从安装配置到数据上链理论讲完了我们动手把它跑起来。我会以macOS/Linux环境为主Windows用户请参考项目README中的PowerShell命令逻辑是完全相通的。3.1 安装Spanory CLI安装有三种方式推荐顺序如下方式一下载预编译二进制文件最推荐这是最干净、依赖最少的方式。直接去项目的GitHub Releases页面找到对应你系统架构的最新版本压缩包。# 以macOS Apple Silicon (arm64) 为例版本号请替换为最新的如 v0.2.0 TAGv0.2.0 OS_ARCHdarwin-arm64 curl -fL -o spanory.tar.gz \ https://github.com/Bububuger/spanory/releases/download/${TAG}/spanory-${TAG#v}-${OS_ARCH}.tar.gz tar -xzf spanory.tar.gz chmod x spanory # 移动到系统路径方便全局调用 sudo mv spanory /usr/local/bin/ # 验证安装 spanory --help注意${TAG#v}这个语法是为了去掉版本号前的v字符。例如TAGv0.2.0那么${TAG#v}的结果就是0.2.0这与发布包的文件名匹配。方式二通过npm/npx安装如果你已经有一个Node.js环境这也很方便。# 一次性运行不全局安装 npx bububuger/spanorylatest --help # 或者全局安装 npm install -g bububuger/spanory spanory --help方式三从源码构建适合开发者或想体验最新代码的用户。git clone https://github.com/Bububuger/spanory.git cd spanory npm install # 将CLI包链接到全局 npm install -g ./packages/cli spanory --help3.2 配置观测后端以Langfuse为例Spanory的数据需要发送到一个地方进行存储和展示这里我们以开源可观测平台Langfuse为例。你需要先搭建或拥有一个Langfuse实例本地部署或云服务。获取Langfuse的OTLP接入点Endpoint和认证信息。在Langfuse项目的设置中找到“OpenTelemetry (OTLP)”配置你会看到Endpoint: 通常是https://your-domain.langfuse.com/api/public/otel/v1/tracesPublic Key和Secret Key设置环境变量。这是Spanory寻找后端地址和认证方式的标准途径。# 将以下变量替换为你自己的值 export OTEL_EXPORTER_OTLP_ENDPOINThttps://cloud.langfuse.com/api/public/otel/v1/traces export OTEL_EXPORTER_OTLP_HEADERSAuthorizationBasic $(echo -n pk-lf-xxx:sk-lf-yyy | base64)关键细节OTEL_EXPORTER_OTLP_HEADERS的格式是KeyValue多个头用逗号分隔。对于Langfuse必须使用Basic认证即base64(public_key:secret_key)。这里使用echo -n是为了避免在字符串末尾添加换行符导致base64编码错误。你可以将这两行命令添加到你的Shell配置文件如~/.zshrc或~/.bashrc中以便每次打开终端都自动设置。3.3 一键安装与配置所有运行时这是Spanory最强大的功能之一一条命令为所有你安装的AI助手完成配置。# 1. 首先检查当前系统状态看看Spanory能检测到哪些运行时 spanory status # 输出会显示已安装/未安装的运行时例如claude-code: installed, codex: not-installed, openclaw: not-detected... # 2. 执行一键安装。--runtimes参数指定要配置的运行时用逗号分隔。 spanory install --runtimes claude-code,codex,openclaw,opencode这条install命令是幂等的意味着你可以安全地多次运行它只会进行必要的更新不会造成重复配置或冲突。这条命令背后为你做了哪些事对于Claude Code在Claude Code的配置中为Stop和SessionEnd事件写入钩子命令spanory hook --last-turn-only。将内置的spanory-statusline插件安装到~/.claude/plugins/目录下。更新Claude Code的settings.json将状态栏statusline的命令指向Spanory的插件启动器这样你就能在Claude Code界面底部看到简略的观测状态。对于Codex清理旧版本可能遗留的配置如notify脚本。启用Codex的钩子功能codex_hooks true。在~/.codex/hooks.json中配置同步的Stop钩子指向spanory runtime codex hook命令。对于OpenClaw如果检测到openclaw命令在PATH中则安装并启用Spanory插件。对于OpenCode将Spanory插件加载器安装到其插件目录~/.config/opencode/plugin中。安装后验证 强烈建议运行doctor命令进行健康检查。spanory doctor --runtimes claude-code,codex,openclaw,opencode这个命令会详细检查每一项配置二进制是否存在、钩子是否正确写入、环境变量是否加载、插件是否可被加载等并给出明确的通过/失败提示和修复建议。这是排查问题的一大利器。3.4 验证数据流进行一次手动导出测试在依赖钩子自动运行前我们先手动触发一次数据导出确保从解析到上报的整个链路是通的。# 首先我们需要找到一个已有的会话ID。以Claude Code为例其会话文件通常位于 # ~/.claude/state/sessions/project_id/session_id.jsonl # 你可以用ls或find命令找一个最近的会话文件。 # 假设我们找到了一个项目ID为“my-app”会话ID为“sess_abc123”的会话。 spanory runtime claude-code export \ --project-id my-app \ --session-id sess_abc123 \ --endpoint $OTEL_EXPORTER_OTLP_ENDPOINT \ --headers $OTEL_EXPORTER_OTLP_HEADERS如果配置正确这条命令会解析指定的会话文件并将生成的追踪数据发送到Langfuse。稍等片刻刷新你的Langfuse追踪Traces页面应该就能看到一条新的追踪记录里面包含了该次AI会话的详细步骤。实操心得在首次安装后务必进行这个手动测试。它能帮你快速定位问题是出在环境变量认证失败、网络无法连接端点还是会话解析上。如果手动导出成功但钩子不工作那问题很可能就出在钩子配置或运行时的事件触发机制上。4. 深入各运行时配置细节与高级用法不同的AI智能体运行时由于其架构和扩展机制不同Spanory的集成方式也略有差异。理解这些细节有助于你更好地利用和排查问题。4.1 Claude Code钩子与状态栏插件的双剑合璧Claude Code是Spanory支持最完善的运行时之一提供了两种集成方式。钩子Hook配置详解安装命令已经在你的~/.claude/config.json中写入了类似下面的配置{ hooks: { Stop: [spanory, hook, --last-turn-only], SessionEnd: [spanory, hook, --last-turn-only] } }Stop在AI完成每一轮Turn回答后触发。这是实现近实时观测的关键。推荐始终启用。SessionEnd在整个会话关闭对话窗口时触发。作为兜底确保即使某个Stop钩子执行失败最终数据也能被上报。--last-turn-only这是一个重要的优化参数。它告诉Spanory钩子被调用时会话文件可能还未被完全写入尤其是Stop事件触发时。使用此参数Spanory会智能地只处理最新完成的那一轮对话避免解析不完整的文件内容。状态栏插件Statusline Plugin除了后台的钩子Spanory还为Claude Code提供了一个前端状态栏插件。安装后你可以在Claude Code窗口的底部看到一个小部件实时显示最近一次Spanory上报的状态例如“✅ Sent”或“⚠️ Error”。这是一个非常直观的反馈机制。 如果状态栏没有显示或报错可以运行spanory doctor --runtimes claude-code检查插件安装情况或查看日志tail -f ~/.claude/state/spanory-hook.log。4.2 Codex基于文件监听的灵活采集策略Codex这里指的是Cursor的AI引擎的集成方式与Claude Code不同它主要基于对会话文件目录~/.codex/sessions/的监控。标准钩子模式安装后Spanory会配置Codex使用其内置的钩子系统。当Codex完成一个回合时它会调用spanory runtime codex hook命令。这种方式的实时性也很好。代理劫持模式高级用于深度捕获如果你需要更详细的数据比如AI与上游API如OpenAI交互的完整请求和响应体经过脱敏处理可以使用代理模式。# 在一个终端启动Spanory的代理服务器 spanory runtime codex proxy --listen 127.0.0.1:8787 --upstream https://api.openai.com # 在另一个终端设置环境变量将Codex的流量导向这个代理 export OPENAI_BASE_URLhttp://127.0.0.1:8787 # 然后正常启动或使用Codex代理会拦截流量提取出结构化的请求/响应信息并将其作为额外的Span附加到追踪数据中。请注意此模式会捕获可能包含敏感信息的数据Spanory内置了强脱敏规则但使用时仍需确保符合你的安全策略。离线回溯与补录Codex的所有会话都以jsonl文件形式存储。Spanory提供了强大的离线处理能力# 导出单个会话 spanory runtime codex export --session-id 你的会话ID # 批量补录某个时间点之后的所有会话例如安装Spanory之前的会话 spanory runtime codex backfill --since 2024-03-20T00:00:00Z --limit 100backfill命令会按文件的修改时间mtime排序处理最新的N个会话非常适合在新安装Spanory后补全历史数据。4.3 OpenClaw 与 OpenCode原生插件集成对于OpenClaw和OpenCode这类较新的、插件体系更原生的运行时Spanory直接提供了插件。OpenClaw# 安装插件 spanory runtime openclaw plugin install # 启用插件通常安装后默认启用 spanory runtime openclaw plugin enable # 检查插件状态 spanory runtime openclaw plugin doctor插件安装后OpenClaw会在启动时自动加载它实现无感知的数据采集。OpenCodeOpenCode的插件安装类似。一个特别有用的功能是插件会自动加载~/.spanory/.env文件中的环境变量仅填充缺失的变量。这意味着即使你从GUI启动OpenCode没有在图形界面设置环境变量插件也能正确获取到OTEL_EXPORTER_OTLP_ENDPOINT等配置。spanory runtime opencode plugin install spanory runtime opencode plugin doctor你可以通过环境变量控制刷新模式export SPANORY_OPENCODE_FLUSH_MODEturn # 默认每回合结束后立即上报实时 # export SPANORY_OPENCODE_FLUSH_MODEsession # 仅在会话结束时上报5. 数据消费报告、告警与问题排查数据上报到Langfuse后你可以在其强大的UI界面进行可视化分析。但Spanory的CLI本身也提供了一系列本地分析工具用于快速生成聚合报告和设置规则告警。5.1 生成聚合报告你可以将Spanory导出的原始JSON数据通过--export-json参数作为输入生成各种维度的报告。# 导出一些数据到本地文件 spanory runtime claude-code export --project-id my-app --session-id sess_xyz --export-json /tmp/session_data.json # 生成会话概览报告 spanory report session --input-json /tmp/session_data.json # 输出示例会话时长、总回合数、工具调用次数等。 # 分析MCP工具使用情况 spanory report mcp --input-json /tmp/session_data.json # 输出示例调用最频繁的MCP服务器、平均耗时、错误率。 # 分析Shell命令使用情况 spanory report command --input-json /tmp/session_data.json # 输出示例最常用的命令、命令执行的成功/失败统计。 # 其他报告类型agent代理行为 cache缓存命中 tool工具调用 context上下文使用 turn-diff回合间差异分析这些报告对于在CI/CD流水线中自动化分析AI助手的行为模式非常有用比如检查一次代码重构是否引入了不安全的Shell命令。5.2 设置规则告警Spanory支持基于JSON规则文件的告警系统。你可以定义一些规则当分析数据满足条件时触发告警。创建规则文件alerts.json[ { name: high-failure-mcp, description: MCP调用失败率超过20%, type: mcp, condition: failure_rate 0.2, severity: warning }, { name: dangerous-command, description: 会话中包含了危险命令如 rm -rf /, type: command, condition: command matches rm\\s-rf\\s/, severity: critical } ]运行告警评估spanory alert \ --input-json /path/to/your/sessions \ --rules ./alerts.json \ --fail-on-alert--input-json可以是一个文件也可以是一个包含多个导出文件的目录。--fail-on-alert参数是关键如果任何告警被触发命令会以退出码2结束。这可以完美集成到CI流程中比如在代码评审前自动运行如果AI助手在生成代码时试图执行危险操作则阻断合并请求。告警还可以配置webhook将通知发送到Slack、钉钉等协作工具。5.3 常见问题排查实录即使配置再仔细也难免会遇到问题。以下是我在多次部署中总结的常见“坑点”和解决方法。问题一钩子执行了但Langfuse里看不到数据无报错这是最令人困惑的情况。钩子日志显示成功但后端没收到。排查思路1检查环境变量作用域。钩子通常是由AI助手进程在某个特定上下文中触发的子进程。确保OTEL_EXPORTER_OTLP_ENDPOINT等环境变量在父进程即AI助手本身启动时就已设置。对于图形化应用如Claude Code桌面版你可能需要在其启动脚本或桌面快捷方式中设置环境变量而不仅仅是在终端里export。排查思路2查看详细钩子日志。Spanory的钩子命令会写日志。# Claude Code的钩子日志 tail -f ~/.claude/state/spanory-hook.log # 检查是否有“Export successful”或具体的错误信息。排查思路3手动模拟钩子调用。这是最有效的诊断方法。找到最近的一个会话文件手动构造一个钩子负载进行测试。# 从会话文件中提取最后一条消息的ID等信息模拟Stop事件这里需要根据实际文件格式调整 # 假设一个简化测试直接让spanory解析整个文件 echo {\event\:\SessionEnd\, \sessionPath\: \/Users/you/.claude/state/sessions/my-app/sess_abc123.jsonl\} | spanory hook --dry-run使用--dry-run参数不会真正发送数据而是将解析后的规范事件打印到终端让你确认解析逻辑是否正确。问题二OTLP 401 Unauthorized 错误这明确是认证问题。确认Header格式确保OTEL_EXPORTER_OTLP_HEADERS的值是AuthorizationBasic base64_string并且base64编码的原文是public_key:secret_key中间是冒号。一个常见的错误是使用了Bearer Token格式或者漏掉了Basic前缀。检查Key是否正确确认你使用的Public Key和Secret Key来自Langfuse项目的正确环境生产/开发且没有过期或被撤销。使用spanory doctor运行spanory doctor会检查环境变量是否已设置并尝试验证端点连通性如果后端支持它能给出明确的错误提示。问题三ERR_MODULE_NOT_FOUND错误常见于源码安装或链接后这通常是Node.js模块解析路径问题。确保在项目根目录执行链接如果你使用npm link或从源码安装务必在Spanory项目的根目录下执行npm install和链接命令。cd /path/to/spanory npm install npm link -w packages/cli # 使用workspace链接检查Node版本确保你的Node.js版本符合项目package.json中engines字段的要求。使用预编译二进制如果问题复杂难解最彻底的办法就是放弃npm安装直接使用预编译的二进制文件彻底摆脱Node环境依赖。问题四数据延迟或丢失确认绑定的是Stop钩子如果只绑定了SessionEnd那么只有关闭会话窗口时数据才会上报。绑定Stop以实现回合级实时上报。检查网络和后台队列Spanory的OTLP核心有内置的重试和批处理机制。在网络不稳定或后端暂时不可用时数据可能会在内存队列中短暂缓冲。可以查看是否有相关警告日志。验证会话文件权限确保运行Spanory钩子的进程有权限读取AI助手生成的会话文件。6. 进阶融入团队工作流与CI/CDSpanory不仅是一个个人工具更能很好地融入团队工程实践。团队代码风格与质量门禁项目自带的docs/standards/project-workflow.md定义了一套开发和贡献规范。对于团队而言可以借鉴其思路将AI助手的行为观测也纳入代码质量检查。 例如在Git的pre-commit钩子或CI流水线中可以运行# 导出最近一次代码编辑会话假设通过环境变量传递了SESSION_ID spanory runtime codex export --session-id $LAST_CODEX_SESSION --export-json /tmp/last_session.json # 运行安全检查规则 spanory alert --input-json /tmp/last_session.json --rules ./security-rules.json --fail-on-alert如果规则检测到AI试图执行sudo或修改敏感文件等高风险操作CI就会失败要求人工复核。自动化巡检与报告可以设置一个轻量的定时任务虽然Spanory采集是零Cron但聚合报告可以定时跑定期生成团队AI使用情况报告。# 每周一生成上周的AI使用报告 spanory runtime codex backfill --since $(date -v-7d %Y-%m-%dT%H:%M:%SZ) --limit 500 --export-json /tmp/last_week_sessions.json spanory report session --input-json /tmp/last_week_sessions.json weekly_ai_report.md spanory report mcp --input-json /tmp/last_week_sessions.json weekly_ai_report.md将报告发送到团队频道帮助大家了解AI助手的整体效能、常用工具以及潜在问题。与内部系统集成Spanory的模块化设计使得它可以相对容易地与内部监控系统集成。如果你公司内部使用其他的可观测平台如自研的APM你可以参考bububuger/backend-langfuse包实现一个自己的BackendAdapter将SpanoryEvent转换成内部平台所需的格式。在我自己的使用中Spanory已经从一个单纯的调试工具演变为团队研发效能洞察的一个重要数据来源。它让我能清晰地看到AI助手如何帮助我们思考、编码和解决问题哪些工具链最高效哪些环节容易出错。这种可观测性带来的不仅是问题的快速定位更是对“人机协作”这一新工作模式的深度理解和持续优化。