ARTICLE · 1364041
Uber ADR Sensor 源码笔记
这篇是 Uber ADR Sensor 组件的源码研究笔记,整理自我的阅读记录。事实、表格与结论均与我的完整笔记(bx-sec/agentic-adr-notes 仓库 sensor/source-notes.md)对齐,文中关键结论都标注了证据来源。

Sensor 组件概览速查图。图中流程与数字仅作速查,具体口径以本文正文和附录 B 的证据索引为准
01
Sensor 是什么
1.1 设计动机,可观测性鸿沟
ADR 论文(arXiv:2605.17380,MLSys 2026)指出企业 AI 代理安全面临三大持续挑战,Sensor 直接解决第一个,有限的可观测性。
现有 EDR 工具能看到文件写入,但看不到代理推理、prompt 或连接意图与执行的因果链。
传统 EDR 设计于 MCP 出现之前,仅捕获系统级遥测(文件写入、进程活动、网络调用)。当 AI 代理写入文件时,EDR 能看到 write() 系统调用,但看不到,触发该操作的用户 prompt(「帮我修复这个 bug」)、代理的推理过程(chain-of-thought)、调用了哪些 MCP 工具及其参数,以及 prompt → reasoning → tool call → outcome 的因果关系。
论文中的关键示例,用户要求「总结 Jira ticket」,但代理读取了 ~/.ssh/id_rsa 并发起 HTTP 请求。EDR 看到文件读取和网络连接,但无法判断这些行为是否偏离用户意图。Sensor 通过捕获代理会话语义链来闭合这个鸿沟(受来源日志记录完整性限制)。
1.2 在 ADR 系统中的位置
ADR 系统包含五个互补能力,Sensor 承担其中「可观测性」。Sensor 的产出(AgentEvent)是 Detector 的输入,没有 Sensor 的遥测,Detector 的两级检测架构(Tier 1 分诊 + Tier 2 深度推理)就没有数据可分析。
| ADR Sensor | ||
1.3 与 Discovery 的边界
Discovery 回答「端点上有哪些 AI 工具」,Sensor 回答「这些工具在做什么」。两者共享端点但数据模型完全不同。Discovery 发现 ~/.claude 目录存在,说明安装了 Claude Code;Sensor 解析 ~/.claude/projects/ 下的 JSONL transcripts,还原 Claude Code 的完整会话历史。
02
能力范围
2.1 能做什么
2.2 不能做什么
2.3 11 个支持的 AI 代理平台
所有来源默认回溯 14 天。平台自动跳过,不支持当前操作系统的来源会被自动跳过,例如 Linux 上 --source all 不会尝试 claude_desktop(仅 macOS/Windows)。PLATFORM_RESTRICTED_SOURCES 映射控制此行为。
2.4 四维遥测模型
重要边界,Sensor 采集的是各代理已持久化到本地的日志或数据库。不同来源对 thinking、工具进度、工具结果、历史分支和内容截断的记录并不相同。因此 chat_history[].content(role=assistant)不能一概等同于完整推理过程,日志中的 tool result 也不能单独证明操作已对操作系统产生了预期效果。Sensor 提供的是支持意图/行为分析的语义遥测数据,判断行为是否偏离用户意图、是否构成威胁,是 Detector 组件的职责。
因果链示例如下。如果因果链断裂,用户要求「总结 Jira ticket」但代理调用了 read_file("~/.ssh/id_rsa"),Sensor 采集的遥测数据会暴露这种偏离,供 Detector 进一步判断是否构成威胁。
用户 prompt: "帮我总结这个 Jira ticket" ↓代理推理: "我需要先读取 Jira ticket 内容" ↓工具调用: jira_mcp.get_ticket(id=PROJ-123) ↓工具结果: ticket 内容... ↓代理推理: "现在我总结一下" ↓代理响应: "这个 ticket 是关于..."
03
技术实现方案
3.1 整体架构。五层结构,自上而下。
① AI Agent Logs,各代理平台的原始日志(JSONL、SQLite、JSON 等),格式各异
② Source-Specific Parsers,每个代理一个解析器,都实现 BaseParser 接口
③ Unified Schema(AgentEvent),统一 schema,消除源格式差异。字段含 uuid、timestamp、source、session_id、hostname、username、host_os、model、project_path、chat_history、session_context、token_usage
④ AgentObserver,编排器,执行 Ingest → Filter → Display → Export 流水线
⑤ 输出,JSON/JSONL 文件 和/或 OTLP Logs 导出到 Collector/SIEM
3.2 AgentEvent 统一 Schema
每个解析的 session 生成一个 AgentEvent。AgentEvent 是 Session 级记录,不是逐条行为事件流——一个 AgentEvent 包含整个会话的 chat_history(消息数组 + 工具调用),OTLP 导出也将每个 AgentEvent 作为一条 adr.agent.session LogRecord 发送。一次性采集生成当前日志的全量快照;--save-sessions 的增量更新是按 session 粒度的快照刷新,不是实时事件流。
完整字段示例。
{ "uuid": "sha256-hash", "timestamp": "2025-06-15T10:30:00+00:00", "source": "claude", "session_id": "claude_abc123", "hostname": "my-laptop", "username": "developer", "host_os": "Darwin", "model": "claude-sonnet-4-20250514", "project_path": "/home/user/my-project", "chat_history": [ {"role": "user", "content": "Help me fix this bug", "tools": [], "sequence_id": "msg_0"}, {"role": "assistant", "content": "Let me look at the code.", "tools": [{"tool_name": "read_file", "tool_type": "tool_use", "arguments": {"path": "main.py"}, "result": "def hello(): ...", "status": "success"}], "sequence_id": "msg_1"} ], "session_context": { "title": "Config review", "is_dispatch": false, "init": { "tools": ["Bash", "Read"], "mcp_servers": [{"name": "github"}], "permission_mode": "acceptEdits", "model": "claude-sonnet-4", "claude_code_version": "2.1.0"} }, "token_usage": { "last_turn": {"input_tokens": 120, "output_tokens": 30, "total_tokens": 150}, "cumulative": {"input_tokens": 420, "output_tokens": 90, "total_tokens": 510}, "model_context_window": 128000}}
字段说明要点。uuid 是 SHA-256 哈希,由 hostname、username、timestamp、source、session_id、消息数量、工具数量及每条消息前 100 字符摘要拼接后求哈希,不是完整 payload 的内容指纹,工具结果变化时 session UUID 不一定改变。username 取 sensor 进程运行身份,从不从环境变量读取。session_id 格式为 <source>_<native_id>。host_os 取 platform.system() 值(Darwin、Linux、Windows)。chat_history 为 ChatMessage 数组,session_context 与 token_usage 为可选字段。
ChatMessage 结构,role(user | assistant)、content、tools(ToolUsage 数组:tool_name、tool_type、arguments、result、status)、sequence_id。tool_type 取值如 tool_use、mcp_tool 等,status 如 success、error 等。
session_context 是解析器可恢复的 session 级配置,即代理对自身权限和能力的视图,可含 title、is_dispatch、session_type、cli_session_id、memory_enabled、skills_enabled、plugins_enabled、available_slash_commands 及 init(tools、mcp_servers、permission_mode、model、plugins、skills 等)。init 中的字段因代理不同而异,但都反映代理启动时的能力配置。对安全分析而言,permission_mode 和 mcp_servers 是关键信号。
token_usage 规范化 token 计数(仅非负整数),分 last_turn(最近一轮)和 cumulative(累计),可含 input_tokens、cached_input_tokens、cache_write_input_tokens、output_tokens、reasoning_output_tokens、total_tokens,另有 model_context_window。
3.3 解析器架构
每个解析器继承 BaseParser,实现统一的解析接口,parse_all() 返回 list[AgentEvent],是所有解析器的统一出口。
from adr_sensor.parsers.base_parser import BaseParserclass MyAgentParser(BaseParser): def __init__(self, max_age_days: int = 14): self.base_path = Path.home() / ".my-agent/logs" self.max_age_days = max_age_days def parse_all(self) -> list[AgentEvent]: entries = [] # 解析代理日志文件并转换为 AgentEvent 对象 return entries
解析器注册机制。AgentObserver.SOURCES 是一个元组,注册所有支持的来源,claude(Claude Code)、cursor(Cursor IDE)、cline、claude_desktop、codex(OpenAI Codex CLI)、copilot(GitHub Copilot CLI)、dsh(DeepSeek Harness)、warp(Warp Terminal)、opencode、gemini(Gemini CLI)、antigravity(Google Antigravity)。
ingest_all() 遍历 SOURCES,通过 self.<source>_parser 查找解析器实例,无需 per-source 分支。PLATFORM_RESTRICTED_SOURCES 列表控制平台限制来源。CLI 自动从 SOURCES 构建 --source 选项。
添加新解析器四步,在 adr_sensor/parsers/ 下创建新解析器继承 BaseParser;在 parsers/__init__.py 中导出;在 observer.py 中注册(构造解析器为 self.<source>_parser、在 SOURCES 中添加 source key、如需平台限制添加到 PLATFORM_RESTRICTED_SOURCES);在 tests/ 中添加测试。
项目结构。adr_sensor/ 下有 __init__.py(包导出)、cli.py(CLI 入口)、observer.py(编排器)。
exporters/ 目录,config.py 为 OTLP/HTTP JSON 配置,opentelemetry.py 为 OpenTelemetry Logs exporter。
parsers/ 目录,base_parser.py 抽象基类 + 11 个解析器(claude、cursor、cline、claude_desktop、codex、copilot、dsh、gemini、opencode、warp、antigravity)。
schemas/ 目录,agent_event_schema.py 定义 AgentEvent、ChatMessage、ToolUsage,system_config_schema.py 定义 SystemConfiguration。utils/ 目录含 string_utils.py、timestamp_utils.py。另有 examples/opentelemetry-config.json 与 tests/ 目录。
3.4 AgentObserver 编排器。Sensor 的编排核心,执行 Ingest → Filter → Display → Export 流水线。核心方法,ingest_all() 摄入所有/特定来源返回 (events, configs),可传 source_filter="claude" 按来源过滤;display_summary(events, configs) 打印摄入摘要表;save_to_file(events, configs, output_format="json") 保存到文件。
from adr_sensor import AgentObserverobserver = AgentObserver()events, configs = observer.ingest_all()observer.display_summary(events, configs)observer.save_to_file(events, configs, output_format="json")
3.5 输出与导出
文件输出两种格式,JSON 用于单文件分析(包含所有 events),JSONL 用于大型日志集和流式处理(每行一个 event)。默认输出目录 ./output,可通过 --output-dir 自定义。--save-sessions 按 session 粒度保存并支持增量更新,保存路径默认 $XDG_CACHE_HOME/adr_sensor(默认 ~/.cache/adr_sensor)。
OpenTelemetry OTLP 导出默认禁用,仅在 --otel-config 指向 JSON 配置文件时初始化。配置字段有 endpoint(完整 OTLP/HTTP logs URL,含 /v1/logs)、service_name、headers(认证头)、timeout_seconds、flush_timeout_seconds、certificate_file(PEM 证书包,可选,相对路径从配置文件目录解析)、gen_ai_attributes(设为 true 添加 GenAI 语义约定属性,默认关闭)。
OTLP 导出关键行为。不应用脱敏或字段投影——prompts、responses、工具参数/结果、用户名、主机名、本地路径都可能被传输。每个 AgentEvent 作为 adr.agent.session LogRecord 发送,Body 为 AgentEvent.get_non_null_fields() 的完整字典。交付检查点(.adr-otel-delivery.<hash>.json)跟踪成功导出,仅存储哈希。至少一次交付语义,重试可能产生重复记录。支持 mTLS 客户端证书/密钥路径。不支持动态 HTTP 凭据提供者插件。
gen_ai_attributes: true 时,每个 source 的 native ID 映射为 gen_ai.conversation.id,映射关系如下。
· antigravity,取对话目录名
· claude,取 JSONL sessionId(subagents 用父 session 的 sessionId)
· claude_desktop,取 Metadata 的 cliSessionId(缺失时省略)
· cline,取 Task 目录名
· codex,取 session_meta payload.id
· copilot,取 session.start/session.resume 的 sessionId
· cursor,取 Composer ID
· dsh,取 Session header id
· gemini,取 sessionId(subagents 保持自己的)
· opencode,取 Session id(去掉 ses_ 前缀,映射回 ses_<id>)
· warp,取 agent_conversations.conversation_id
3.6 诊断与健康
所有诊断文件在 1 MiB 时轮转,保留 2 个备份。健康状态五种,ok(成功捕获)、empty(无有意义输出)、no_input(输入不存在)、partial(有可用输出但观察到错误)、failed(错误且无可用输出)。
健康记录示例(结构化诊断不包含 prompts、工具参数/结果、路径、session ID、异常消息、traceback)。
{ "schema_version": 1, "event": "adr.sensor.health", "timestamp": "2026-01-01T00:00:00.000+00:00", "sensor_version": "0.0.0", "source": "claude", "stage": "parse", "status": "partial", "suspected_schema_drift": false, "counts": {"events_returned": 2, "events_emitted": 2, "events_filtered": 0}, "reasons": {"record_decode_error": 1}}
隐私说明三条。结构化诊断不含敏感信息;运行时日志的 message 和 stack 可能包含本地文件路径和错误文本;--log-file-content-free 丢弃 message 和 stack,--log-identity 添加 username 和 hostname(opt-in)。
3.7 CLI
常用命令。adr-sensor 基本用法(从所有支持的代理收集);adr-sensor --source claude 指定来源;--save-sessions 保存 session 文件;--output-format jsonl 导出 JSONL;--all-history 包含所有历史;--otel-config ./opentelemetry-config.json 导出到 OTLP endpoint;--no-save --otel-config 仅导出 OTLP 不写本地文件;开发环境 uv run adr-sensor --source gemini --no-save 从源码运行。
输出流,stdout 打印进度消息,stderr 打印警告和错误,始终打印摄入摘要表。
3.8 Python API
from adr_sensor import AgentObserverobserver = AgentObserver()events, configs = observer.ingest_all(source_filter="claude")for event in events: print(f"Source: {event.source}, Session: {event.session_id}") print(f"Messages: {len(event.chat_history)}") for msg in event.chat_history: if msg.tools: for tool in msg.tools: print(f" Tool: {tool.tool_name} ({tool.tool_type})") print(f" Args: {tool.arguments}")
04
各代理日志路径与解析细节
4.1 Claude Code
· 日志路径,递归读取 ~/.claude/projects/ 下的 transcripts
· 子代理,包含 <project>/<sessionId>/subagents/agent-<agentId>.jsonl 及嵌套工作流目录
· Session ID 规则,主会话 claude_<sessionId>;子代理 claude_<sessionId>_agent_<agentId>,含 parent_session_id 和 agent_id
· 数据处理,保留字符串和文本块消息(含工具结果附带的用户文本),通过 tool-call ID 匹配结果,跳过格式错误的记录但不丢弃周围消息
· 兼容同一物理行拼接的完整 JSON 对象和对象间的 NUL 填充;不完整的尾部被跳过,不连接物理行或修复消息内文本
· 元数据,每个事件包含 raw_log_path、稳定的对话起始 timestamp、session_context.last_event_at 和 event_count
· 默认回溯 14 天(按文件修改时间);顶层工具参数字符串和工具结果在 1,000 字符处截断
· 不导入非文本内容块和单独溢出的工具输出文件
4.2 Cursor IDE
· 日志格式,SQLite 数据库(state.vscdb)
· 平台 macOS、Linux、Windows;默认回溯 14 天
4.3 Cline (Claude Dev)
· 扩展 ID,saoudrizwan.claude-dev;支持 VS Code(主要)、Cursor、VS Code Insiders、VSCodium、Windsurf
· 日志路径,macOS ~/Library/Application Support/<Editor>/User/globalStorage/saoudrizwan.claude-dev/tasks/;Linux ~/.config/<Editor>/User/globalStorage/...;Windows %APPDATA%\<Editor>\User\globalStorage\...
· 处理,扫描所有候选目录,规范化用户提示和助手工具使用(包括 <use_mcp_tool> 调用),跨编辑器去重
· 默认回溯 14 天(按 task 文件修改时间);ClineParser(base_path=...) 可限制单个 task 目录
4.4 Claude Desktop
· 覆盖 Claude Desktop 的本地代理模式(发布为 Claude Cowork),支持 macOS 和 Windows
· 交互式会话,.../local-agent-mode-sessions/<user>/<org>/local_<uuid>/audit.jsonl
· 调度会话(委派后台代理),.../<user>/<org>/agent/local_ditto_<uuid>/audit.jsonl
· 区别标识,调度会话使用 claude_desktop_dispatch_ 前缀和 is_dispatch: true 标志
4.5 OpenAI Codex CLI
· 日志路径,$CODEX_HOME/sessions/(默认 ~/.codex)
· SQLite catalogs,只读查询每个 $CODEX_HOME/state_*.sqlite 的兼容 threads 表,必须有 id 和 rollout_path 列,updated_at 和 updated_at_ms 可选;相对路径从 CODEX_HOME 解析,仅接受已存在的 .jsonl 文件
· 去重与过滤,catalog 和文件系统路径去重;使用文件修改时间和 catalog 更新时间戳中较新者
· 默认回溯 14 天;max_age_days 参数值 ≤ 0 禁用年龄过滤
4.6 GitHub Copilot CLI
· 日志路径,macOS /Users/<user>/.copilot/session-state/;Linux /home/<user>/.copilot/session-state/;Windows %USERPROFILE%\.copilot\session-state\
· 环境变量,COPILOT_HOME 覆盖配置目录,Sensor 读取 $COPILOT_HOME/session-state/
· 读取文件,每个 session 的 events.jsonl + 可选 workspace.yaml 和 vscode.metadata.json
· 默认回溯 14 天(按 events.jsonl 修改时间);仅覆盖 CLI session state,不读取 VS Code Copilot Chat 扩展的存储
4.7 DeepSeek Harness
· 日志路径,$DSH_HOME/sessions/(默认 ~/.dsh/sessions/)
· 格式,默认 Zstandard 压缩日志,也支持未压缩的 JSONL v3 日志
· Generation 处理,一个 session 目录有多代日志时,仅考虑最高 generation,且仅在 v3 格式时导入
· 规范化内容,工具参数和结果、PTC 子调度、失败状态、批准、provider/model 上下文、沙箱模式、权限预设、类型化消息内容、token 使用量
· 默认回溯 14 天
4.8 Warp Terminal
· 日志格式,SQLite 数据库(warp.sqlite)
· 平台 macOS、Windows;默认回溯 14 天
4.9 opencode
· 数据目录,~/.local/share/opencode(Linux 和 macOS),支持 $XDG_DATA_HOME 和 $OPENCODE_DB
· 后端一 SQLite(当前版本),opencode.db 或 opencode-<channel>.db(非稳定频道),只读打开,仅当包含 session、message 和 part 表时使用
· 后端二 JSON 文件树(旧版本),storage/ 目录,含 per-session、per-message 和 per-part JSON 文件
· MCP 工具命名,opencode 将 MCP 工具命名为 <server>_<tool>,含下划线的非内置工具记为 tool_type: "mcp_tool" 并填充 server_name
4.10 Gemini CLI
· 扫描根目录,macOS/Linux ~/.gemini/tmp/;Windows %USERPROFILE%\.gemini\tmp\;macOS Seatbelt 沙箱额外扫描 ~/.cache/.gemini/tmp/
· 环境变量,GEMINI_CLI_HOME 覆盖父主目录,路径变为 $GEMINI_CLI_HOME/.gemini/tmp(非 $GEMINI_CLI_HOME/tmp);GeminiParser(base_path=...) 支持自定义路径
· 读取内容,当前 chats/**/*.jsonl journals、legacy chats/*.json 对话快照、用户/助手文本、工具参数和结果、状态和批准请求、model 和 token 使用量、嵌套子代理会话
· 数据处理,Session resume 时起始时间戳保持稳定;--save-sessions 原地刷新已更改的快照;按 ID 合并重复的 journal 消息,工具进度更新不重复消息或 token 总计;rewind 和 checkpoint 后早期活动仍保留;history_scope 为 all_recorded_branches;不添加任何脱敏或截断
· 不收集,仅 prompt 的 logs.json、编辑器聊天存储、shell 历史、未保存会话及这些根之外的文件
· MCP 调用,显式 mcp_/限定工具名标识;记录名模糊时 server 归属留空
· 默认回溯 14 天(按文件修改时间);--all-history 包含更旧文件
· 契约验证对照上游 record types、journal writer、storage paths、supported platforms;测试使用合成记录在三个 host 上运行,不需要 Gemini 账户
4.11 Google Antigravity
· Brain 目录,Antigravity CLI ~/.gemini/antigravity-cli/brain/;Antigravity 2.0 ~/.gemini/antigravity2/brain/;Antigravity IDE ~/.gemini/antigravity-ide/brain/
· Legacy 路径,~/.antigravity/brain/、%APPDATA%\Google\Antigravity\brain\、~/Library/Application Support/Google/Antigravity/brain/、~/.config/google/antigravity/brain/
· 环境变量,ANTIGRAVITY_HOME 和 AGY_HOME 作为存储覆盖
· 数据文件,每个对话目录为 .system_generated/logs/transcript.jsonl + 可选 transcript_full.jsonl
· Transcript 选择,比较可用快照,选择最新记录修订版;同一修订版优先选择未截断数据和完整 transcript
· Step Types,USER_INPUT(用户提示)、PLANNER_RESPONSE(助手输出 + thinking 文本 + 工具调用)、GENERIC(模型输出);Thinking 文本以 [Thinking] 标签保留
· 工具规范化,原生工具直接记录;MCP 调用(如 mcp_<server>_<tool> 或 <server>:<tool>)解析填充 server_name 和 tool_name
· 数据保留,不截断工具参数或字符串化嵌套值;若源 transcript 报告 truncated_fields 则标记 is_truncated
· 默认回溯 14 天
05
正反例测试方法集
5.1 测试设计原则五条。合成记录驱动,所有测试使用合成 transcripts/记录,不启动实际 AI 代理;契约验证,多个解析器对照上游源码验证(record types、journal writer、storage paths);跨平台覆盖,Gemini CLI 解析器的 CI 在 macOS、Linux、Windows 三平台运行;无需账户,测试不需要任何 AI 代理的账户或 API key;可复现,所有测试可在隔离环境中独立复现。
5.2 正例测试集(完整脚本见笔记仓库,此处记录目的与预期)。
P-01 单源采集 Claude Code。验证解析器能正确解析 JSONL 日志并生成 AgentEvent。预期,输出目录含 JSONL 文件,每行合法 JSON,source 为 claude,session_id 以 claude_ 开头,chat_history 非空,timestamp 为 ISO 8601,hostname 和 username 已填充。
P-02 多源采集全量。验证 --source all 自动发现并采集所有已安装代理。预期,摘要表列出全部 11 个来源,不支持当前 OS 的来源为 no_input 或自动跳过,至少一个来源状态为 ok,未安装的代理为 no_input。
P-03 JSONL 格式导出。验证每行是合法 JSON,无解析错误。
P-04 工具调用记录。验证正确捕获工具调用的 tool_name、tool_type、arguments,且捕获数量 > 0。
P-05 增量保存。验证 --save-sessions 按 session 粒度保存,第二次运行不重新保存未变化的 session 文件。
P-06 Python API 调用。验证 AgentObserver Python API 返回 events 列表,每个 event 有 source 和 chat_history 属性。
P-07 诊断文件生成。验证诊断文件包含 schema_version、event、status 字段且 event 为 adr.sensor.health,并验证不含 password/api_key/token 等敏感信息。
5.3 反例测试集。
N-01 无日志的来源。验证未安装的代理被正确处理为 no_input 或 empty,不抛异常,退出码 0。
N-02 格式错误的日志文件。验证损坏的行被跳过、有效行仍被解析为 AgentEvent,诊断状态为 partial(有错误但有可用输出),--fail-on-error 时退出码非零。
N-03 不支持的来源。传入不存在的 source key 被正确拒绝,CLI 报错并列出可用 source 列表,退出码非零。
N-04 空目录作为日志路径。GeminiParser(base_path=...) 指向空目录,返回空列表,不抛异常。
N-05 权限不足的日志目录。权限不足的文件被跳过,不导致整个解析失败,诊断记录 denied 或类似状态。
N-06 超大日志文件。10 万条记录不导致内存溢出或超时,被聚合为 1 个 session 级 AgentEvent,处理完成或 partial 状态。注意 ClaudeParser 的 base_path 固定为 ~/.claude/projects/,不接受 base_path 参数也不支持环境变量覆盖(与 GeminiParser 的 GEMINI_CLI_HOME 不同),隔离测试只能在该目录下建子目录,测试后应删除。
N-07 OTLP 导出无可用 endpoint。OTLP 导出失败但不导致整个运行崩溃,错误记录在诊断文件中,--fail-on-error 时退出码非零。
N-08 --source all 在无任何代理的环境。Docker 隔离环境验证所有来源状态为 no_input,不抛异常,退出码 0。
5.4 边界测试集。
B-01 默认 14 天回溯窗口。创建 20 天前的旧日志,验证默认 14 天不包含,--all-history 包含。
B-02 跨平台自动跳过。Linux 上验证 claude_desktop 不出现在处理列表中。PLATFORM_RESTRICTED_SOURCES 目前只包含 claude_desktop(Darwin/Windows),被命中的来源在 ingest_all() 循环中直接 continue,不会出现在诊断记录中。warp 虽有平台限制(仅 macOS/Windows 有数据库路径)但不在该映射里,在 Linux 上会被尝试解析并产生 no_input,不属于平台跳过。
B-03 子代理会话关联。验证 Claude Code 子代理 session_id 含 _agent_ 后缀,session_context 含 parent_session_id 和 agent_id 字段。无子代理日志时应标记为手工检查。
B-04 MCP 工具调用识别。验证 MCP 工具被标记为 tool_type "mcp_tool" 且 server_name 字段存在(源码 ToolUsage dataclass 定义 server_name: Optional[str] = None,值为 None 表示记录名模糊时无法归属 MCP server,断言验证字段存在性而非值非空)。
B-05 --fail-on-error 退出码。有解析错误时返回非零退出码,无错误时返回 0。cli.py 实现是 observer.has_errors 为 True 时 raise SystemExit(1),has_errors 在诊断写入失败或任一诊断记录状态为 partial/failed 时为真,OTLP 导出失败也会触发 SystemExit(1)。测试时不要在命令后加 || true,否则退出码是 true 的而非 sensor 的。
5.5 测试运行方式。单元测试用 pytest,pip install -e ".[dev]" 后运行 pytest tests/ -v,可加 --cov=adr_sensor 生成覆盖率,ruff 做 lint。
测试特点,合成记录、跨平台(Gemini 解析器测试在三个 host 的 CI 上运行)、无需账户、契约验证(Gemini CLI 对照 record types、journal writer、storage paths、supported platforms;DeepSeek Harness 对照 JSONL persistence contract 和 v3 event declarations)。
截至 Gemini CLI 支持 commit 93ed35c,244 个 Sensor 测试在 Python 3.11 上全部通过。
集成测试从源码安装,git clone https://github.com/uber/ADR 后在 Sensor/ 目录 uv sync 或 pip install -e ".[dev]",再运行 uv run pytest tests/ -v。
CI 工作流。截至 uber/ADR@6b33dff(2026-10-16),仓库中与 Sensor 相关的实际 CI 工作流为 .github/workflows/sensor-gemini.yml。触发条件为 PR 或 push 到 main 且改动涉及 Sensor/** 或该工作流文件。执行矩阵,ubuntu-latest、macos-latest、windows-latest 三平台,固定 Python 3.12(非多版本矩阵),仅运行 pytest tests/test_gemini_parser.py -q。
pyproject.toml 声明支持的 Python 版本范围不能替代实际 CI 验证证据。其他解析器(Claude/Cursor/Cline 等)的跨平台测试覆盖情况未在仓库工作流中体现。
06
安全分析与技术权衡
6.1 与 EDR 的对比
职责边界,Sensor 的职责是解析、标准化和输出代理活动遥测。是否偏离用户意图、是否构成威胁,是 Detector 组件基于 Sensor 产出的 AgentEvent 执行的检测逻辑。AgentObserver 源码(observer.py)不包含任何意图判断、威胁检测或行为分析代码,其完整职责链为 Parser 解析 → 内容过滤 → 增量去重 → 原子写入 → 健康记录 → 摘要展示。
6.2 与网关方案的对比。论文还讨论了 LLM/MCP 网关作为替代方案。
6.3 设计权衡
07
附录
附录 A 代码坐标索引。路径相对 Sensor/adr_sensor/,基于源码快照 6b33dff(2026-10-16)。
__init__.py 包导出 | cli.py CLI 入口 | observer.py 编排器schemas/agent_event_schema.py AgentEvent, ChatMessage, ToolUsageschemas/system_config_schema.py SystemConfigurationparsers/base_parser.py BaseParser 抽象基类parsers/claude_parser.py | cursor_parser.py | cline_parser.pyclaude_desktop_parser.py | codex_parser.py | copilot_parser.pydsh_parser.py | gemini_parser.py | opencode_parser.pywarp_parser.py | antigravity_parser.pyexporters/config.py OTLP/HTTP JSON 配置exporters/opentelemetry.py OpenTelemetry Logs exporterutils/string_utils.py | utils/timestamp_utils.pyexamples/opentelemetry-config.json OTLP 配置示例 | tests/ 测试目录
附录 B 关键技术结论及证据索引。18 条结论,每条均给出证据来源。
· ADR,Agentic AI Detection and Response,Uber 开源的企业 AI 代理安全系统
· Sensor,ADR 的遥测采集组件,解析 AI 代理日志并标准化为 AgentEvent
· AgentEvent,Sensor 的统一输出 schema,Session 级记录(每 session 一个),包含会话聊天历史、工具调用、上下文和 token 用量
· AgentObserver,Sensor 的编排器,执行 ingest → filter → display → export 流水线
· BaseParser,所有解析器的抽象基类,定义 parse_all() 接口
· MCP,Model Context Protocol,AI 代理与外部工具通信的协议
· OTLP,OpenTelemetry Protocol,用于将遥测数据导出到 Collector/SIEM
· EDR,Endpoint Detection and Response,传统端点检测与响应工具
· ADR-Bench,ADR 的安全基准,302 个任务、133 个 MCP 服务器、17 种攻击技术
· Discovery,ADR 的端点资产发现组件,回答「端点上有哪些 AI 工具」
· Detector,ADR 的威胁检测组件,两级架构(Tier 1 分诊 + Tier 2 深度推理)
· session_context,AgentEvent 中的 session 级配置字段,代理对自身权限的视图
· token_usage,AgentEvent 中的 token 计数字段,分 last_turn 和 cumulative
· ChatMessage,chat_history 中的消息单元,含 role、content、tools
· ToolUsage,tools 中的工具调用记录,含 name、type、arguments、result
笔记读完的几点个人判断,放在最后。Sensor 的价值在于它不发明新数据,而是承认各代理自己已经在本地写好了足够详细的日志,然后把这些散落、异构、容易被忽视的数据规范化成安全分析可用的形态。它的边界同样清晰,不做检测、不做阻断、不做实时,只负责把「代理到底做了什么」这一层观测补上。用它之前想清楚两件事,一是 OTLP 管道按敏感数据管道管理,二是声明支持范围与 CI 验证范围之间的差距需要自己补齐。
参考材料uber/ADR 仓库 Sensor/ 目录,源码快照 6b33dff(2026-10-16)ADR 论文 arXiv:2605.17380(MLSys 2026)完整源码笔记 bx-sec/agentic-adr-notes 之 sensor/source-notes.md















































































