【免费下载链接】agent-beaconThe cross-harness, self-improving memory layer for AI agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-beacon点击查看免费下载agent-beaconBeacon是面向 AI Agent 的本地优先遥测系统它的**事件模式Event Schema**把来自本地终端、CI 任务和云端 Agent 的海量异构信号统一归一化成一种可直接查询的JSONL 事件格式。本文用通俗易懂的方式带你吃透这套事件模式的三块基石JSONL 必需字段、实体模型Entity Model和归一化机制帮你在第一次打开runtime.jsonl时就能读懂每一行日志。一、事件从哪里来一图看懂 agent-beacon 的数据流AI Agent 的活动分散在太多地方本地开发机上的 Claude Code、Cursor、Codex浏览器会话CI 流水线里的临时任务还有各种云端的 Coding Agent。每个来源都有自己的事件名、字段名、标识方式——同一个工具调用动作在不同运行时里可能叫tool.invoked、PreToolUse或tool.execute.before。Beacon 的做法是在中间插入一层归一化事件层如上图的 NORMALIZE 环节上游Local Agents、Browser、Agent SDKs、CI Pipelines、Cloud Agents、第三方 AI SaaS 各自以钩子hook、插件plugin、OTLP 导出、轮询poll等方式上报信号下游统一的 JSONL 事件流可以直接接入 Datadog、Splunk、Elastic、Snowflake、AWS S3、Palo Alto 等任意 SIEM 或对象存储。这意味着你写的检测规则、仪表盘查询、SIEM 解析器只需要认识一种事件形状而不必为每个运行时单独适配。二、JSONL 日志基础文件在哪、每行长什么样Beacon 的默认输出是本地runtime JSONL 日志——每行一个完整的 JSON 事件对象安装模式日志路径用户模式默认~/.beacon/endpoint/logs/runtime.jsonl系统模式/var/log/beacon-agent/runtime.jsonl日志在 10 MiB 时自动轮转保留 5 个带编号的归档如runtime.jsonl.1活跃路径保持稳定方便仪表盘和外部传输器持续读取。官方说明见 本地 JSONL 日志。一个典型的命令事件长这样字段含义后文详解{ timestamp: 2026-05-11T22:21:00.418302511Z, vendor: beacon, product: endpoint-agent, schema_version: 1.0, event: { kind: agent_runtime, action: command.executed, category: command }, severity: info, endpoint: { hostname: example-mac, os: darwin, agent_version: 0.0.11 }, harness: { name: cursor }, session: { id: conversation-1, working_directory: /Users/local-user/repo }, tool: { name: Shell, command: go test ./... }, command: { command: go test ./... }, message: Shell command executed }三、JSONL 事件模式必需字段清单每个事件都带有一组骨架字段完整定义见 统一遥测模式字段含义新手速记timestampUTC 事件时间RFC3339 纳秒精度跨来源排序的主键vendor固定为beacon表明事件出处product当前为endpoint-agent产品标识schema_version当前公开版本1.0版本兼容依据event.kind事件族当前为agent_runtime事件大类event.action归一化动作如command.executed、tool.invoked核心字段发生了什么event.category事件类别运行时提供或由event.action推断便于按类筛选severityinfo/low/medium/high/critical严重程度endpoint主机名、操作系统等上下文在哪台机器发生harness产生信号的 Agent 运行时是哪个 Agent 干的event.action是整套事件模式的心脏。常见归一化动作包括归一化动作含义prompt.submitted用户提交了提示词tool.invoked/tool.completed/tool.failed工具被调用 / 完成 / 失败command.executed执行了 Shell 命令file.read/file.modified读取 / 修改文件approval.requested/approval.allowed/approval.denied审批流程mcp.tool_invoked调用 MCP 工具另外两个可选但非常重要的字段是来源溯源Provenance字段下文第六节详述。四、实体模型一个事件 动作 一组类型化实体Beacon 的**实体模型Entity Model约定每个事件由一个动作action加上一组类型化实体typed entities**组成实体描述谁、在哪、对什么参与了该动作。完整字段参考见 模式字段源码实现在 pkg/asymptoteobserve/。最核心的几个实体如下实体用途常用字段endpoint设备与 Agent 上下文hostname、os、agent_versionuser本地操作系统用户name、uidharness产生信号的 Agent 运行时name、version、executable_pathorigin事件来源local/ci/cloud区分本地、CI、云端runCI 或临时运行上下文provider、run_id、workflow、job、commit、prsession会话上下文id、working_directorytool工具调用含类 Shell 工具name、command、pathfile文件活动path、operation、diff_hash、diff_bytescommand命令执行command、exit_code、duration_msmcpMCP 服务器/工具/方法server、tool、method.name、session.idapproval审批决策required、decision、reasonpolicy策略决策id、decision、enforcementprompt提示词文本若源端允许保留textcontent内容处理状态included、redacted、truncatedgen_aiOpenTelemetry GenAI 语义上下文request、response、usage、tool新手理解技巧实体是可组合的。一条命令事件可以同时带toolcommand一条文件编辑可以同时带filesessionrepositorybranch一条 CI 事件带originrun。查询时按实体字段筛选即可例如找出所有harness.name cursor且event.action file.modified的事件。顶层还有若干共享字段sequence写序号用于同时间戳排序、model归一化模型名、repository、branch、message、raw、field_truncated截断标记。五、归一化机制把千奇百怪的源字段映射进统一契约归一化Normalization是 agent-beacon 事件模式最值钱的部分——不同运行时的字段名五花八门Beacon 把它们映射到同一套契约字段。映射表全量见 归一化规则这里挑最实用的几条1. 字段映射不同源、同一个名字源信号各运行时写法归一化字段 / 动作gen_ai.request.model、model、ai.modelmodel标准化gen_ai.provider.namegen_ai.tool.name、tool_name、function_nametool.nameprocess.command_linecommand.commandfile.pathfile.pathconversation.idsession.idvcs.repository.url/git.branchrepository/branch类 Prompt 事件prompt.submittedShell/执行事件command.executed文件写入/编辑事件file.modified审批事件approval.requested例如 Claude Code 的 OTel 日志里 MCP 工具名写成mcp__server__tool这种拼接串Beacon 会在缺少结构化mcp.*属性时自动拆解出mcp.server和mcp.tool两个独立字段。2. 模型名标准化让 Token 报表不再重影model字段在写入时即被标准化去除空白、转小写、剥离供应商前缀——Anthropic/Claude-Sonnet-4-5、anthropic/claude-sonnet-4-5、claude-sonnet-4-5都会记录为claude-sonnet-4-5。供应商前缀不会丢失而是单独记入gen_ai.provider.name保持可查询。这么做的原因是所有 Token 报表都按model分组若不标准化同一个模型经由两个不同运行时上报时会变成报表里的两行读者无法分辨。同时注意模型 id 本身绝不会被改写gpt-4.1不会被折叠成gpt-4-1——可看见的分裂行好过凭空发明的 id。3. 上下文占用 ≠ Token 消耗这是新手最容易混淆的一对字段字段语义能否求和gen_ai.usage.*累计消耗量花了多少 token✅ 报表对其求和gen_ai.context.*某一时刻窗口占用率窗口有多满❌ 求和无意义Qwen Code 的多轮会话曾暴露这个问题它的Stop钩子上报的input_tokens其实已包含前几轮的累计量直接累加会让会话总量随长度平方增长。Beacon 的判定规则是只有当input_tokens旁边同时上报了窗口上限如context_limit时才把它记入gen_ai.context否则按消耗量处理。4. Token 用量归一化缓存计数不重复计算OTel GenAI 语义约定中gen_ai.usage.input_tokens按定义应包含缓存 token而 Beacon 的口径是仅未缓存输入。因此对三个包含缓存的源字段名Beacon 会扣除同一记录上的cache_read与cache_creation计数后再入库Claude Code 的裸input_tokens本身就是 Anthropic 的未缓存口径直接保留raw字段始终保存上报原值。gen_ai.usage.cost_usd只承载运行时上报的费用从不按本地价格表推算。六、事件身份与排序如何确认这是同一个事件1. 双重身份字段每个事件都携带两个身份标识事件身份gen_ai.tool.call.id运行时自己给一次工具调起的名字Claude Code 叫tool_use_id、Codex/OpenCode 叫call_id、Cline 叫callId。它把工具调用 ↔ 其结果 ↔ 对应的审批串成一条链——两个事件共享同一个 call id就描述同一次调用写入方只记一次。event.idBeacon 自己生成的确定性 UUID。当运行时自己命名了动作时UUID 由会话 动作 目标 调用 id 派生于是钩子路径和采集器路径对同一个动作的描述在数秒后写入、字段各异却携带同一个event.id重新读取日志会复现原来的 id天然幂等去重。2. 排序规则先 timestamp后 sequence字段作用timestamp跨来源排序主键两条采集路径用同一时钟、纳秒精度、固定宽度按字符串比较与按时间戳比较结果一致sequence单个写入方的单调发射计数器从 1 开始仅用于打破时间戳平局重要陷阱不要按日志行位置排序钩子是同步写入拦截瞬间落盘导出器按固定间隔批量写入所以先发生的事件经常后落盘。beacon scan和仪表盘的检测视图都会先按(timestamp, sequence)排序再评估关联规则。sequence只是单个写入方自己的序号——钩子适配器和采集导出器互相看不到对方的计数器编号 1 的钩子事件完全可能发生在编号 900 的导出器事件之后。3. Provenance事件是亲眼所见还是推理得出两个可选溯源字段让你能掂量每条事件的分量字段取值含义harness.collection_methodhook/plugin/otlp/poll事件靠什么机制离开运行时的event.fidelityobserved/inferred动作是源端明确命名的还是 Beacon 推断的动作推断的优先级显式动作属性observed→ 结构化操作属性observed→ 已知运行时事件名observed→ 对日志正文做模式匹配inferred→ 无法识别时回退tool.invokedinferred。对审批事件这点尤其关键部分运行时只暴露工具调用前通知而没有审批钩子Beacon 会把前者的通知合成approval.allowed事件供审批类检测有东西可匹配——但这些事件标记为inferred统计真实人工决策时应排除它们。检测规则可以直接要求确定性e.event.action approval.allowed e.event.fidelity observed。七、隐私与内容处理截断、脱敏与截断标记写入 JSONL 之前Beacon 会先做脱敏redaction、净化、截断和事件体积限制每条保留的字符串有 4 KB 上限pkg/asymptoteobserve/privacy.go超长工具输出、命令输出或 diff 的超出部分永不落盘被截断的事件会用顶层field_truncated和事件级content.truncated明确标记这里被裁过content实体会记录该事件内容是被包含、脱敏还是截断included/redacted/truncated。这换来的是隐私与事件体积可控下游 SIEM 拿到的数据边界是明确且可解释的。八、归一化之后的效果仪表盘里的真实视图上图是 Beacon 本地仪表盘仅回环地址可访问的安全总览页你可以看到归一化契约的直接红利Agent Harnesses面板cursor1015 条、endpoint5 条、factory5 条——不同运行时的事件被归一到同一harness.name下统计Top Actions面板tool.invoked380、approval.allowed167、file.modified153、command.executed112——全部是归一化后的event.action词汇与源端原始事件名无关Models面板gpt-5.5、composer-2-fast——经过前缀剥离和标准化的model字段Runtime Inventory卡片Claude Code、Codex CLI、Factory Droid、Cursor 各自的检测与遥测开启状态。同一份runtime.jsonl还支撑beacon endpoint status、beacon endpoint doctor等本地诊断以及 Wazuh、Splunk HEC、Elastic、Datadog、Sumo Logic、AWS S3/GCS 等转发通道。九、延伸阅读与模块路径速查资源路径统一遥测模式事件模式总览、必需字段、排序docs/telemetry-schema/event-schema.mdx归一化机制源字段映射、模型名、用量口径docs/telemetry-schema/normalization.mdx实体模型与全量字段参考docs/telemetry-schema/fields.mdx完整 JSONL 事件示例与内容处理docs/telemetry-schema/examples.mdx本地 JSONL 日志路径与轮转docs/log-forwarding/local-jsonl.mdx核心概念词表Endpoint event、Entity model 等docs/concepts/core-concepts.mdx隐私限制与脱敏实现pkg/asymptoteobserve/privacy.go运行时的标准化命名harness.namepkg/asymptoteobserve/harness.go威胁规则模式消费事件模式的规则写法spec/threat-rules/SPEC.md小结agent-beacon 事件模式的精髓可以用三句话概括——必需字段给每条事件一个稳定的骨架实体模型把谁、在哪、做了什么拆成可组合的类型化上下文归一化机制把各运行时的方言翻译成统一词汇并诚实地标注每个动作是所见还是所推。读懂这套模式你就能在任何 SIEM、脚本或仪表盘里自如查询 AI Agent 的每一步行为。赞分享【免费下载链接】agent-beaconThe cross-harness, self-improving memory layer for AI agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-beacon点击查看免费下载相关推荐AI Agent 技能终极指南用 Skills for Real Engineers 把模糊想法拷问成可交付决策AI Agent 技能终极指南用 Skills for Real Engineers 把模糊想法拷问成可交付决策 Skills for Real EngineAI 技能AI 插件Argo Workflows WorkflowStep 全字段详解Java SDK 类型参考与 steps 模板实战指南Argo Workflows WorkflowStep 全字段详解Java SDK 类型参考与 steps 模板实战指南 WorkflowStep步骤是云原生容器编排工作流自动化任务调度后端MaaAssistantArknights 任务配置 Schema 详解resource/tasks 字段全参考、表达式运算与模板任务继承机制MaaAssistantArknights 任务配置 Schema 详解resource/tasks 字段全参考、表达式运算与模板任务继承机制 MaaAssi计算机视觉GUI自动化RPA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
