先问一个问题你在本地跑代码 Agent比如自动写代码、自动改 Bug、自动跑测试的 AI 工具时有没有过这种体验——Agent 运行了十几分钟最后给你的结果完全不对而且你根本不知道它中间到底做了什么你只能看到最终提交的 diff但看不到它为什么选这条路、改过哪些文件、报过哪些错、重试了几次。传统的日志系统只能记下“哪一秒调用了哪个函数”但 Agent 的执行过程是高度动态的它会自己读文件、改代码、执行命令、看报错、再调整方案。这个过程如果不可见出了问题就只能当黑盒处理排查效率非常低。本文要介绍的 ORG2就是一套专门为代码 Agent 设计的“行车记录仪”。它会给 20 多种主流代码 Agent 装上完整的录制回放能力让你能像回看行车录像一样精确回放 Agent 的每一步操作、每一次决策、每一段代码变更。如果你是 AI Agent 开发者、代码工具使用者或者正在把 Agent 接入团队开发流程这篇文章会帮你理解 ORG2 的核心设计、接入方式、数据模型和落地经验。读完你会知道一个可观测的 Agent 系统应该记录什么、怎么记录、以及记录之后如何分析和排查。1. 背景与核心概念1.1 代码 Agent 为什么需要“行车记录仪”先解释一下代码 Agent 是什么。代码 Agent 是指一类能够自主完成编程任务的 AI 程序。它不只是“根据提示生成一段代码”而是会像人类开发者一样工作阅读理解用户的需求。浏览项目目录结构。读取相关源码文件。编写或修改代码。运行测试命令。根据报错信息调整策略。重复上述过程直到完成任务或达到上限。目前主流的代码 Agent 包括 GitHub Copilot Workspace、Cursor Agent、Devin、SWE-agent、OpenHands原 OpenDevin、AutoGPT 等它们能力不同但工作模式很相似都是一个“感知 - 决策 - 执行 - 观察”的循环。这个循环带来了一个传统软件没有的新问题不可复现性。普通程序的执行过程是确定的同一份输入走同一条代码路径产生同样的输出。但代码 Agent 依赖大模型决策每一步都有随机性。即使给了完全相同的任务和仓库Agent 两次运行的路径也可能完全不同第一次先改了 A 文件第二次可能先改了 B 文件。这就导致了一个尴尬的局面Agent 说“完成了”你只能拿到最后的 diff不知道它绕了多远。Agent 说“失败了”你想知道卡在哪一步但日志里只有一行报错。Agent 改了不该改的文件你想追溯是哪次决策导致的结果没有任何记录。Agent 花了一小时跑任务你想优化它的效率却看不到瓶颈在哪。所谓“行车记录仪”指的就是一套完整的过程记录体系维度传统日志行车记录仪式记录内容文本日志结构化的操作事件流含完整上下文时间记录时刻记录先后顺序和持续时间决策不可见记录 Agent 的思考过程和选择原因文件不感知记录每次读取和写入的具体内容命令可能记录记录命令输入、输出、退出码回放不支持可按时间逐帧重放整个过程1.2 ORG2 是什么ORG2 是一个面向代码 Agent 的可观测性与过程记录框架。它的核心定位是在 Agent 与项目仓库之间加一层透明的“记录仪”以无侵入或低侵入的方式把 Agent 的每一步操作录制下来统一存储并提供查询、分析和回放能力。这里的关键词是“透明”。ORG2 的设计目标不是替代 Agent也不是拦截 Agent 的决策而是旁路记录。Agent 该做什么还做什么ORG2 只负责把过程完整保存下来。用一个比喻来理解代码 Agent 是驾驶员。项目仓库是道路。最终代码是目的地。ORG2 是装在车上的记录仪它不决定往哪开但记录每一帧画面。1.3 ORG2 解决的核心问题把需求归纳一下ORG2 主要解决四个问题第一个问题过程可见。Agent 运行期间到底访问了哪些文件执行了哪些命令修改了哪些内容这些信息会被完整记录而不是只保留最终结果。第二个问题失败可复现。Agent 报错后不必重新运行整个任务。直接回放记录就能看到出错前最后几步做了什么从而定位根因。第三个问题行为可比对。同一任务在不同 Agent、不同参数下的表现可以横向对比。哪条执行路径更短、哪次修改更合理都能基于数据判断而不是拍脑袋。第四个问题历史可追溯。任何一次 Agent 生成的代码都能追溯到它读过的文件、参考过的资料、做过的尝试。这对代码审查、合规审计、团队协作都很有价值。1.4 适用场景实际使用中ORG2 常见的落地场景包括Agent 开发调试开发自己的 Agent 时用它观察 Agent 的决策过程。Agent 能力评测同时跑多个 Agent对比它们处理同一任务的行为差异。自动化任务监控在 CI/CD 流水线中监控 Agent 生成的代码质量。代码安全审计追溯 Agent 对代码仓库的所有变更确认没有越权操作。教学与研究分析 Agent 如何一步步解决编程问题。2. ORG2 的核心能力拆解理解了背景再来看 ORG2 具体提供哪些能力。2.1 动作捕获动作捕获是 ORG2 的基础能力。它会记录 Agent 在文件系统上的所有操作常见的动作类型包括动作类型说明示例file_read读取文件读取src/main.pyfile_write写入文件修改src/main.pyfile_edit编辑文件在指定行插入代码command_run执行命令运行pytest test_main.pycommand_output命令输出测试结果文本search搜索代码搜索函数定义位置agent_messageAgent 中间节点输出模型的思考文本每一项动作都会记录四个基本信息发生了什么、发生在哪个文件/命令上、发生在什么时间、执行结果是什么。2.2 录制与回放录制与回放是 ORG2 最有辨识度的功能。录制阶段ORG2 把 Agent 的每一步操作按时间顺序写入存储。回放阶段你可以像看视频一样把整个过程从头到尾重新走一遍。回放有两种模式时间轴模式按时间顺序展示所有动作适合整体回顾。聚焦模式只看某类动作例如只看文件写入或只看命令执行。聚焦模式在排查问题时特别有用。比如想确认 Agent 是否执行了危险命令直接过滤command_run就行不用在大量文件读取记录里翻找。2.3 进度追踪与任务状态机Agent 执行任务是有状态的。ORG2 会维护一个任务状态机持续追踪当前进度。一个典型的代码 Agent 任务状态流如下pending等待中 → running运行中 → tool_call调用工具 → observation观察结果 → sleeping模型推理中 → running继续运行 → finished完成 → failed失败状态机的好处是你可以随时知道 Agent 处于哪个阶段而不是只能干等。如果 Agent 卡住了你能看到它卡在“工具调用”还是“模型推理”阶段。2.4 工作空间快照Agent 运行过程中工作目录会不断变化。结构可能被创建、删除、重命名文件内容会被频繁改写。ORG2 会定期对工作空间做快照。快照不是完整备份整个目录而是记录文件系统的变更情况哪些目录被新建了哪些文件被修改了哪些路径被删除了修改前后的内容分别是什么有了快照你可以精确回答“Agent 运行结束时仓库相比开始时多了什么、少了什么、改了哪里”。这一点在日常使用中非常实用。比如 Agent 声称“只改了测试文件”但快照显示它悄悄改了生产代码问题很快就能暴露。2.5 多 Agent 兼容层ORG2 支持 20 多种代码 Agent靠的是适配层设计。不同 Agent 的接口、模型、工具调用方式各不相同ORG2 通过统一的接口定义把每个 Agent 的独有行为映射到标准事件模型上。从这个角度来说你不需要为每个 Agent 单独开发一套监控系统。接好一个 ORG2所有受支持的 Agent 都能获得一致的可观测能力。3. 技术架构与数据模型如果不谈数据模型只讲“记录”是很空洞的。这一节拆解 ORG2 的架构分层和数据结构。3.1 架构分层从整体看ORG2 分为四层第一层采集层。负责捕获 Agent 的动作。可能通过文件系统监听、命令包装、API 回调等方式实现。采集层只负责记录不修改 Agent 的行为。第二层存储层。负责把采集到的事件持久化。要求能支持高频写入、顺序追加、按时间范围查询。实践中有几种选择比如本地文件存储、SQLite、PostgreSQL或者对象存储加索引。第三层组织层。负责把原始事件归类为会话、任务、动作三步结构。这一步是为了让海量事件变得可管理。第四层呈现层。负责把存储的数据展示给用户包括时间轴、状态图、文件变更视图、命令执行列表等。3.2 三层数据组织ORG2 用“会话 - 任务 - 动作”三层结构组织数据这是理解它的关键。一层一层来看会话Session会话是最高层级。一次完整的 Agent 运行过程就是一个会话。每个会话都有独立的 ID包含启动时间、结束时间、使用的 Agent 名称和模型信息。动作Action动作是最小的事件单位。一次文件读取、一次命令执行、一次搜索都算一个动作。动作记录的内容包括动作类型、目标文件、命令、输入/输出、时间戳。任务Task任务介于会话和动作之间。一个会话可能拆分成多个子任务每个子任务由一组动作组成。比如“理解项目结构”是一个任务里面包含多次文件读取和搜索动作。3.3 事件结构实例下面是一个简化的动作事件结构用 JSON 表示{ action_id: act_8f3a9c2b, session_id: sess_20240615_001, task_id: task_explore_repo, timestamp: 2024-06-15T10:23:45.123Z, agent: swe-agent, model: gpt-4o, action: { type: file_write, path: src/utils.py, language: python, diff: from typing import Optional\n\ndef find_by_id(items: list, id: int) - Optional[dict]:\n for item in items:\n if item.get(id) id:\n return item\n return None\n } }这个结构包含几个关键信息action_id动作唯一标识。session_id / task_id动作所属的会话和任务。timestamp时间戳。agent / model执行者信息。action.type动作类型。action.path作用的文件路径。action.diff文件变更内容。命令执行事件的格式类似{ action_id: act_5b2e1d90, session_id: sess_20240615_001, task_id: task_run_tests, timestamp: 2024-06-15T10:25:01.450Z, agent: swe-agent, model: gpt-4o, action: { type: command_run, command: pytest tests/test_utils.py -x, cwd: /workspace/demo-repo, exit_code: 1, output: ___________ FAILURE ___________\ntest_utils.py:10: in test_find_by_id\n assert find_by_id([{\id\: 1}], 1) {\id\: 1}\nE AssertionError: assert None {id: 1}\n } }注意这里exit_code和output是很重要的字段。AI Agent 的核心能力就是“看到报错后自我纠正”因此命令输出是分析 Agent 行为的关键上下文。3.4 状态追踪模型状态追踪的难点在于 Agent 的执行不是线性的。Agent 可能会在多个工具间来回切换也会在模型推理阶段“停住”实际上是在等待大模型返回。因此状态模型本身需要记录当前状态running / sleeping / tool_call 等。状态持续的时间。状态切换的原因。只有把状态、动作、时间三者关联起来才能回答“Agent 的时间都花在哪了”这类问题。通常一次代码 Agent 任务的耗时分布是模型推理约 40% - 60% 工具执行约 20% - 30% 命令运行约 20% - 40%如果模型推理占比过高说明上下文太长或提示词设计不合理如果命令运行占比过高说明 Agent 在反复尝试执行测试或安装依赖。4. 环境准备与快速接入接下来进入实操部分。由于 ORG2 的 API 和服务形态可能随版本变化本文以通用实践思路为主重点讲清楚接入结构实际使用时请以你下载版本的官方文档为准。4.1 环境要求以在本地调试一个 Python 代码 Agent 为例建议环境如下组件说明操作系统Linux / macOSWindows 需要 WSL 或 Docker 环境Python3.9 及以上代码 Agent任选一种受支持的 Agent如 SWE-agent、OpenHandsORG2安装对应版本的 SDK存储默认 SQLite生产环境可切换 PostgreSQL注意这里不需要限定具体版本号因为不同 Agent 和 ORG2 版本的兼容关系需要以官方发布信息为准。关键是理解接入模式。4.2 安装 ORG2 客户端假设 ORG2 提供了 Python SDK安装方式大致如下pip install org2-sdk如果是通过源码接入也可以把 SDK 目录加入项目路径git clone https://example.com/org2/org2-sdk.git cd org2-sdk pip install -e .安装完成后验证导入是否成功python -c import org2; print(org2.__version__)如果输出版本号说明安装成功。4.3 初始化 ORG2 记录器记录器的初始化是接入的第一步。核心参数包括存储路径、会话名称、以及要追踪的 Agent 名称。from org2 import Recorder # 初始化记录器 recorder Recorder( storage_path./.org2_store, project_namedemo-repo, session_namefix-login-bug, )这里重点说明几个参数的作用storage_path事件数据的存储目录。project_name项目标识用于区分不同仓库的记录。session_name会话名称建议按任务命名方便后续检索。4.4 包装 Agent 的执行记录器准备好后需要把它“挂”到 Agent 的调用链上。不同 Agent 的接入方式不同但核心思路是一致的在 Agent 执行前开启记录在执行过程中捕获动作在执行结束后保存并关闭。# 使用上下文管理器方式接入 with recorder.start(): result agent.run(task修复登录接口的 bug)如果 AGENT 提供了回调机制或钩子函数可以在钩子里显式上报动作def on_action(action): recorder.record(action) agent.on_action on_action agent.run(task修复登录接口的 bug)需要注意这里不要直接修改 Agent 的源码逻辑。优先使用官方提供的适配方式。如果 SDK 还没有适配你使用的 Agent也可以在 Agent 的工具调用层做一层薄包装把每一步转发给 ORG2。4.5 查看录制结果录制完成后可以查看会话列表和详情。下面演示一个简化的查询流程from org2 import QueryClient client QueryClient(storage_path./.org2_store) # 获取所有会话 sessions client.list_sessions() for s in sessions: print(s.session_id, s.name, s.status) # 获取某个会话的所有动作 actions client.list_actions(session_idsess_20240615_001) for a in actions: print(f[{a.timestamp}] {a.type} - {a.path or a.command})这段代码演示了三个常用操作列会话、查动作、查看命令结果。这是日常调试使用频率最高的功能。5. 数据采集模块的完整实现示例为了让理解更落地下面用一个简化的 Python 模块演示“一个轻量 Agent 记录仪”是怎么实现的。这不是要重复造 ORG2 的轮子而是帮助你理解底层机制。5.1 项目结构demo-recorder/ ├── recorder/ │ ├── __init__.py │ ├── models.py │ └── recorder.py ├── agent_adapter.py └── main.py5.2 定义数据模型先定义事件的数据结构用dataclass表示# 文件路径demo-recorder/recorder/models.py from dataclasses import dataclass, field from datetime import datetime from typing import Any, Optional dataclass class Action: type: str session_id: str timestamp: datetime field(default_factorydatetime.utcnow) path: Optional[str] None command: Optional[str] None output: Optional[str] None exit_code: Optional[int] None diff: Optional[str] None metadata: dict[str, Any] field(default_factorydict) dataclass class Session: session_id: str agent_name: str status: str running start_time: datetime field(default_factorydatetime.utcnow) end_time: Optional[datetime] None actions: list[Action] field(default_factorylist)5.3 实现记录器记录器负责追加事件和序列化存储# 文件路径demo-recorder/recorder/recorder.py import json import uuid from pathlib import Path from .models import Action, Session class Recorder: def __init__(self, storage_path: str): self.storage_path Path(storage_path) self.storage_path.mkdir(parentsTrue, exist_okTrue) self.sessions [] self.current_session: Session | None None def create_session(self, agent_name: str) - str: session_id fsess_{uuid.uuid4().hex[:12]} session Session(session_idsession_id, agent_nameagent_name) self.current_session session self.sessions.append(session) return session_id def record(self, action: Action) - None: if self.current_session is None: raise RuntimeError(请先创建会话) self.current_session.actions.append(action) self._append_to_file(action) def _append_to_file(self, action: Action) - None: file_path self.storage_path / f{self.current_session.session_id}.jsonl with open(file_path, a, encodingutf-8) as f: f.write(json.dumps(action.__dict__, defaultstr) \n) def finish_session(self) - None: if self.current_session: self.current_session.status finished self.current_session.end_time datetime.utcnow() def replay(self, session_id: str) - list[dict]: file_path self.storage_path / f{session_id}.jsonl if not file_path.exists(): return [] events [] with open(file_path, r, encodingutf-8) as f: for line in f: events.append(json.loads(line)) return events这段代码虽小但已经包含了记录器的核心逻辑create_session新建会话。record记录动作并追加到 JSONL 文件。replay读取会话的历史事件。5.4 Agent 适配层下面模拟一个简单的 Agent并给它加上记录能力。# 文件路径demo-recorder/agent_adapter.py import subprocess from recorder.models import Action from recorder.recorder import Recorder class SimpleAgent: def __init__(self, recorder: Recorder): self.recorder recorder def read_file(self, path: str) - str: content open(path, encodingutf-8).read() self.recorder.record( Action( typefile_read, session_idself.recorder.current_session.session_id, pathpath, metadata{size: len(content)}, ) ) return content def write_file(self, path: str, content: str) - None: with open(path, w, encodingutf-8) as f: f.write(content) self.recorder.record( Action( typefile_write, session_idself.recorder.current_session.session_id, pathpath, difff{content}, ) ) def run_command(self, command: str, cwd: str | None None) - str: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, cwdcwd, ) self.recorder.record( Action( typecommand_run, session_idself.recorder.current_session.session_id, commandcommand, outputresult.stdout result.stderr, exit_coderesult.returncode, ) ) return result.stdout result.stderr这个适配层的意义在于所有 Agent 与外部世界的交互都经过一层包装而这层包装天然记录了全部动作。真实 ORG2 的适配原理和这个类似只是做得更通用、更健壮。5.5 模拟 Agent 执行最后写一个主程序模拟 Agent 执行一个简单的修复任务# 文件路径demo-recorder/main.py from agent_adapter import SimpleAgent from recorder.models import Action from recorder.recorder import Recorder def main(): recorder Recorder(storage_path./.org2_demo_store) session_id recorder.create_session(agent_namesimple-agent) agent SimpleAgent(recorder) print(开始执行任务修复 utils.py 中的 find_by_id 函数) # 1. 读取文件 content agent.read_file(utils.py) print(f读取到 {len(content)} 字节) # 2. 检查测试 output agent.run_command(pytest test_utils.py -x, cwd.) print(f测试输出长度{len(output)}) # 3. 根据失败信息修改文件 fixed_content content.replace( return None, return item if item else None ) agent.write_file(utils.py, fixed_content) # 4. 再次运行测试 output agent.run_command(pytest test_utils.py -x, cwd.) print(f测试输出长度{len(output)}) recorder.finish_session() print( 回放记录 ) for event in recorder.replay(session_id): print(f[{event[timestamp]}] {event[type]}: {event.get(path) or event.get(command)}) if __name__ __main__: main()运行方式python main.py预期输出大致如下开始执行任务修复 utils.py 中的 find_by_id 函数 读取到 356 字节 测试输出长度512 测试输出长度463 回放记录 [2024-06-15 10:30:00.123] file_read: utils.py [2024-06-15 10:30:00.456] command_run: pytest test_utils.py -x [2024-06-15 10:30:00.789] file_write: utils.py [2024-06-15 10:30:01.123] command_run: pytest test_utils.py -x从这个演示可以看到Agent 做了什么、怎么做的、做了几次全部有据可查。这就是行车记录仪的基本形态。6. 常见问题与排查思路在实际落地 ORG2 或类似方案时会遇到一些典型问题。下面整理成排查清单。6.1 事件丢失问题现象常见原因解决思路部分动作没有记录工具调用走的路径没有经过采集层检查 Agent 是否有内置命令执行路径绕过了包装文件写入动作丢失使用了批量写入或原子写入 macOS 特性增加对os.replace、shutil.move的监听子进程命令未记录Agent 内部用了 subprocess 直接调用确保在进程级做命令包装排查顺序先确认记录器是否正常开启打印 Recorder 实例状态。再确认 Agent 的实际调用链看是否有绕过包装的路径。最后在操作系统的文件监听层做验证确保事件是否到达采集层。6.2 数据量过大代码 Agent 运行一次可能产生上千条事件长时间使用后存储占用增长很快。建议的缓解方式隔离存储每个项目或每个会话单独一个目录。定期归档把超过 30 天的会话压缩打包。按需采样对大量重复的轮询事件可以降低采样频率。精简保存命令输出可以截断前 2000 字符或后 500 字符。6.3 回放速度慢回放慢通常是因为需要逐条加载事件再重新渲染。优化方式按 session 建立索引避免全表扫描。回放时只加载需要的动作类型。对超大会话做分页回放而不是一次性全部加载。6.4 Agent 不兼容如果 ORG2 还没有适配你使用的 Agent可以先做一层手动包装。原理已经在上面的示例中展示过了。手动包装的注意点不要改 Agent 源码。优先用 Agent 暴露的插件接口或回调机制。只记录不拦截保证最小侵入。6.5 时间不同步Agent 运行时如果跨多台机器不同节点的时间戳可能出现偏差。解决方式使用统一的 NTP 服务同步系统时间。时间戳尽量使用 ISO 8601 格式带时区。在会话元数据中记录执行节点信息方便校准。7. 最佳实践与工程建议这一节是给已经在用 ORG2、或者准备在团队内部落地 Agent 可观测性的读者看的。建议偏工程实践向。7.1 事件字段要结构化不要只记录“做了什么”要把关键上下文一起保存。结构化字段的价值体现在后续检索和分析上。上一节的事件结构示例就是一个好模板建议在此基础上补充{ request_context: { task: 修复登录接口 bug, user: zhangsan, repo: org2/demo, branch: feature/login-fix }, model_info: { provider: openai, model: gpt-4o, temperature: 0.2 } }有了这些上下文回放时才能还原“当时为什么这么做”而不只是“当时做了什么”。7.2 区分“可观测”和“可审查”如果你的团队要用 Agent 生成的代码做生产发布那么审查级别的要求会比调试级别更高。两个场景的要求不同场景关注点记录要求开发调试找到失败原因记录命令输出、错误信息即可生产审查确认行为合法、合规必须记录修改前后的完整 diff、涉及文件清单、执行时间、审批人如果是生产场景建议在 Agent 任务完成后自动生成一份“变更报告”内容包括修改了哪些文件。新增了哪些文件。删除或重命名了哪些文件。是否执行了包安装命令。是否运行了数据库迁移命令。最终测试是成功还是失败。7.3 控制安全边界Agent 本身也是一段代码它运行的命令必须受到约束。行车记录仪不负责拦车但你要自己设置路障。常用的安全建议包括在沙箱容器或隔离环境中运行 Agent。限制 Agent 可读写的目录范围。对命令执行做白名单禁止高危命令。对网络访问做限制避免 Agent 下载未知依赖。定期核查 Agent 的权限使用最小权限原则。尤其是当 Agent 自动修改代码时需要设置“人工审批后才可合入”的门禁。行车记录仪可以做事后追溯但事前拦截仍然不能省。7.4 按任务粒度建立索引会话层级太粗动作层级太细。日常使用时按任务粒度建立索引是最实用的。建议的索引维度任务 ID。Agent 名称。使用的模型。任务状态成功、失败、超时。涉及的文件列表。执行时长。有了任务级索引团队就能快速回答“上周所有失败的 Agent 任务有哪些”“哪个 Agent 改文件最频繁”这类管理问题。7.5 让 Agent 自己也“看到”记录这是一个更进阶的用法把历史记录作为上下文反馈给 Agent。当 Agent 再次执行类似任务时可以先读取上一次记录的摘要避免重复踩坑。也就是说行车记录仪不仅能供人查看也能变成 Agent 的“驾驶经验”。比如history client.get_session_summary(session_idsess_xxx) prompt f参考上一次任务的执行经验{history}现在开始新任务。这种“经验回放”的方法能明显提升 Agent 在重复任务上的稳定性尤其是同一仓库内的烂摊子修复类任务。7.6 日志级别与采样策略最后提醒一下日志级别的设计。不是所有动作都值得完整记录。建议按重要度分级级别动作类型保存策略CRITICAL文件写入、命令执行、模型决策必须完整保存INFO文件读取、搜索保存路径即可不必保存全文DEBUG完整输出、重复轮询按需开启默认关闭这样既能保证问题可追溯又不会让存储爆炸。8. 总结本文围绕“给代码 Agent 装上行车记录仪”这个主题完整介绍了 ORG2 的背景、核心能力、数据模型、接入方式和落地经验。重点内容可以归纳为以下几点第一代码 Agent 的执行过程具有不可复现性传统日志不足以支撑调试和审查需要一套以事件流为核心的过程记录体系。第二ORG2 通过“会话 - 任务 - 动作”三层数据模型把 Agent 的每一步操作统一记录并提供录制回放、进度追踪、工作空间快照、多 Agent 兼容等能力。第三接入过程的核心思路是在 Agent 的工具调用层做透明包装。你已经看到了一个最小可运行的记录器实现它能记录文件读取、文件写入和命令执行并支持按会话回放。第四落地时要注意数据量控制、时间同步、安全边界和行为审查。如果你手头正好有代码 Agent 的项目我建议你先不要急着部署完整方案而是先跑一个 30 分钟的试点选一个真实任务记录一次完整的 Agent 执行过程回放一遍看看能发现哪些之前看不到的问题。这个过程会让你对“Agent 可观测性”有非常直观的体感。
代码Agent也需要行车记录仪？ORG2让执行过程完整可回放
先问一个问题你在本地跑代码 Agent比如自动写代码、自动改 Bug、自动跑测试的 AI 工具时有没有过这种体验——Agent 运行了十几分钟最后给你的结果完全不对而且你根本不知道它中间到底做了什么你只能看到最终提交的 diff但看不到它为什么选这条路、改过哪些文件、报过哪些错、重试了几次。传统的日志系统只能记下“哪一秒调用了哪个函数”但 Agent 的执行过程是高度动态的它会自己读文件、改代码、执行命令、看报错、再调整方案。这个过程如果不可见出了问题就只能当黑盒处理排查效率非常低。本文要介绍的 ORG2就是一套专门为代码 Agent 设计的“行车记录仪”。它会给 20 多种主流代码 Agent 装上完整的录制回放能力让你能像回看行车录像一样精确回放 Agent 的每一步操作、每一次决策、每一段代码变更。如果你是 AI Agent 开发者、代码工具使用者或者正在把 Agent 接入团队开发流程这篇文章会帮你理解 ORG2 的核心设计、接入方式、数据模型和落地经验。读完你会知道一个可观测的 Agent 系统应该记录什么、怎么记录、以及记录之后如何分析和排查。1. 背景与核心概念1.1 代码 Agent 为什么需要“行车记录仪”先解释一下代码 Agent 是什么。代码 Agent 是指一类能够自主完成编程任务的 AI 程序。它不只是“根据提示生成一段代码”而是会像人类开发者一样工作阅读理解用户的需求。浏览项目目录结构。读取相关源码文件。编写或修改代码。运行测试命令。根据报错信息调整策略。重复上述过程直到完成任务或达到上限。目前主流的代码 Agent 包括 GitHub Copilot Workspace、Cursor Agent、Devin、SWE-agent、OpenHands原 OpenDevin、AutoGPT 等它们能力不同但工作模式很相似都是一个“感知 - 决策 - 执行 - 观察”的循环。这个循环带来了一个传统软件没有的新问题不可复现性。普通程序的执行过程是确定的同一份输入走同一条代码路径产生同样的输出。但代码 Agent 依赖大模型决策每一步都有随机性。即使给了完全相同的任务和仓库Agent 两次运行的路径也可能完全不同第一次先改了 A 文件第二次可能先改了 B 文件。这就导致了一个尴尬的局面Agent 说“完成了”你只能拿到最后的 diff不知道它绕了多远。Agent 说“失败了”你想知道卡在哪一步但日志里只有一行报错。Agent 改了不该改的文件你想追溯是哪次决策导致的结果没有任何记录。Agent 花了一小时跑任务你想优化它的效率却看不到瓶颈在哪。所谓“行车记录仪”指的就是一套完整的过程记录体系维度传统日志行车记录仪式记录内容文本日志结构化的操作事件流含完整上下文时间记录时刻记录先后顺序和持续时间决策不可见记录 Agent 的思考过程和选择原因文件不感知记录每次读取和写入的具体内容命令可能记录记录命令输入、输出、退出码回放不支持可按时间逐帧重放整个过程1.2 ORG2 是什么ORG2 是一个面向代码 Agent 的可观测性与过程记录框架。它的核心定位是在 Agent 与项目仓库之间加一层透明的“记录仪”以无侵入或低侵入的方式把 Agent 的每一步操作录制下来统一存储并提供查询、分析和回放能力。这里的关键词是“透明”。ORG2 的设计目标不是替代 Agent也不是拦截 Agent 的决策而是旁路记录。Agent 该做什么还做什么ORG2 只负责把过程完整保存下来。用一个比喻来理解代码 Agent 是驾驶员。项目仓库是道路。最终代码是目的地。ORG2 是装在车上的记录仪它不决定往哪开但记录每一帧画面。1.3 ORG2 解决的核心问题把需求归纳一下ORG2 主要解决四个问题第一个问题过程可见。Agent 运行期间到底访问了哪些文件执行了哪些命令修改了哪些内容这些信息会被完整记录而不是只保留最终结果。第二个问题失败可复现。Agent 报错后不必重新运行整个任务。直接回放记录就能看到出错前最后几步做了什么从而定位根因。第三个问题行为可比对。同一任务在不同 Agent、不同参数下的表现可以横向对比。哪条执行路径更短、哪次修改更合理都能基于数据判断而不是拍脑袋。第四个问题历史可追溯。任何一次 Agent 生成的代码都能追溯到它读过的文件、参考过的资料、做过的尝试。这对代码审查、合规审计、团队协作都很有价值。1.4 适用场景实际使用中ORG2 常见的落地场景包括Agent 开发调试开发自己的 Agent 时用它观察 Agent 的决策过程。Agent 能力评测同时跑多个 Agent对比它们处理同一任务的行为差异。自动化任务监控在 CI/CD 流水线中监控 Agent 生成的代码质量。代码安全审计追溯 Agent 对代码仓库的所有变更确认没有越权操作。教学与研究分析 Agent 如何一步步解决编程问题。2. ORG2 的核心能力拆解理解了背景再来看 ORG2 具体提供哪些能力。2.1 动作捕获动作捕获是 ORG2 的基础能力。它会记录 Agent 在文件系统上的所有操作常见的动作类型包括动作类型说明示例file_read读取文件读取src/main.pyfile_write写入文件修改src/main.pyfile_edit编辑文件在指定行插入代码command_run执行命令运行pytest test_main.pycommand_output命令输出测试结果文本search搜索代码搜索函数定义位置agent_messageAgent 中间节点输出模型的思考文本每一项动作都会记录四个基本信息发生了什么、发生在哪个文件/命令上、发生在什么时间、执行结果是什么。2.2 录制与回放录制与回放是 ORG2 最有辨识度的功能。录制阶段ORG2 把 Agent 的每一步操作按时间顺序写入存储。回放阶段你可以像看视频一样把整个过程从头到尾重新走一遍。回放有两种模式时间轴模式按时间顺序展示所有动作适合整体回顾。聚焦模式只看某类动作例如只看文件写入或只看命令执行。聚焦模式在排查问题时特别有用。比如想确认 Agent 是否执行了危险命令直接过滤command_run就行不用在大量文件读取记录里翻找。2.3 进度追踪与任务状态机Agent 执行任务是有状态的。ORG2 会维护一个任务状态机持续追踪当前进度。一个典型的代码 Agent 任务状态流如下pending等待中 → running运行中 → tool_call调用工具 → observation观察结果 → sleeping模型推理中 → running继续运行 → finished完成 → failed失败状态机的好处是你可以随时知道 Agent 处于哪个阶段而不是只能干等。如果 Agent 卡住了你能看到它卡在“工具调用”还是“模型推理”阶段。2.4 工作空间快照Agent 运行过程中工作目录会不断变化。结构可能被创建、删除、重命名文件内容会被频繁改写。ORG2 会定期对工作空间做快照。快照不是完整备份整个目录而是记录文件系统的变更情况哪些目录被新建了哪些文件被修改了哪些路径被删除了修改前后的内容分别是什么有了快照你可以精确回答“Agent 运行结束时仓库相比开始时多了什么、少了什么、改了哪里”。这一点在日常使用中非常实用。比如 Agent 声称“只改了测试文件”但快照显示它悄悄改了生产代码问题很快就能暴露。2.5 多 Agent 兼容层ORG2 支持 20 多种代码 Agent靠的是适配层设计。不同 Agent 的接口、模型、工具调用方式各不相同ORG2 通过统一的接口定义把每个 Agent 的独有行为映射到标准事件模型上。从这个角度来说你不需要为每个 Agent 单独开发一套监控系统。接好一个 ORG2所有受支持的 Agent 都能获得一致的可观测能力。3. 技术架构与数据模型如果不谈数据模型只讲“记录”是很空洞的。这一节拆解 ORG2 的架构分层和数据结构。3.1 架构分层从整体看ORG2 分为四层第一层采集层。负责捕获 Agent 的动作。可能通过文件系统监听、命令包装、API 回调等方式实现。采集层只负责记录不修改 Agent 的行为。第二层存储层。负责把采集到的事件持久化。要求能支持高频写入、顺序追加、按时间范围查询。实践中有几种选择比如本地文件存储、SQLite、PostgreSQL或者对象存储加索引。第三层组织层。负责把原始事件归类为会话、任务、动作三步结构。这一步是为了让海量事件变得可管理。第四层呈现层。负责把存储的数据展示给用户包括时间轴、状态图、文件变更视图、命令执行列表等。3.2 三层数据组织ORG2 用“会话 - 任务 - 动作”三层结构组织数据这是理解它的关键。一层一层来看会话Session会话是最高层级。一次完整的 Agent 运行过程就是一个会话。每个会话都有独立的 ID包含启动时间、结束时间、使用的 Agent 名称和模型信息。动作Action动作是最小的事件单位。一次文件读取、一次命令执行、一次搜索都算一个动作。动作记录的内容包括动作类型、目标文件、命令、输入/输出、时间戳。任务Task任务介于会话和动作之间。一个会话可能拆分成多个子任务每个子任务由一组动作组成。比如“理解项目结构”是一个任务里面包含多次文件读取和搜索动作。3.3 事件结构实例下面是一个简化的动作事件结构用 JSON 表示{ action_id: act_8f3a9c2b, session_id: sess_20240615_001, task_id: task_explore_repo, timestamp: 2024-06-15T10:23:45.123Z, agent: swe-agent, model: gpt-4o, action: { type: file_write, path: src/utils.py, language: python, diff: from typing import Optional\n\ndef find_by_id(items: list, id: int) - Optional[dict]:\n for item in items:\n if item.get(id) id:\n return item\n return None\n } }这个结构包含几个关键信息action_id动作唯一标识。session_id / task_id动作所属的会话和任务。timestamp时间戳。agent / model执行者信息。action.type动作类型。action.path作用的文件路径。action.diff文件变更内容。命令执行事件的格式类似{ action_id: act_5b2e1d90, session_id: sess_20240615_001, task_id: task_run_tests, timestamp: 2024-06-15T10:25:01.450Z, agent: swe-agent, model: gpt-4o, action: { type: command_run, command: pytest tests/test_utils.py -x, cwd: /workspace/demo-repo, exit_code: 1, output: ___________ FAILURE ___________\ntest_utils.py:10: in test_find_by_id\n assert find_by_id([{\id\: 1}], 1) {\id\: 1}\nE AssertionError: assert None {id: 1}\n } }注意这里exit_code和output是很重要的字段。AI Agent 的核心能力就是“看到报错后自我纠正”因此命令输出是分析 Agent 行为的关键上下文。3.4 状态追踪模型状态追踪的难点在于 Agent 的执行不是线性的。Agent 可能会在多个工具间来回切换也会在模型推理阶段“停住”实际上是在等待大模型返回。因此状态模型本身需要记录当前状态running / sleeping / tool_call 等。状态持续的时间。状态切换的原因。只有把状态、动作、时间三者关联起来才能回答“Agent 的时间都花在哪了”这类问题。通常一次代码 Agent 任务的耗时分布是模型推理约 40% - 60% 工具执行约 20% - 30% 命令运行约 20% - 40%如果模型推理占比过高说明上下文太长或提示词设计不合理如果命令运行占比过高说明 Agent 在反复尝试执行测试或安装依赖。4. 环境准备与快速接入接下来进入实操部分。由于 ORG2 的 API 和服务形态可能随版本变化本文以通用实践思路为主重点讲清楚接入结构实际使用时请以你下载版本的官方文档为准。4.1 环境要求以在本地调试一个 Python 代码 Agent 为例建议环境如下组件说明操作系统Linux / macOSWindows 需要 WSL 或 Docker 环境Python3.9 及以上代码 Agent任选一种受支持的 Agent如 SWE-agent、OpenHandsORG2安装对应版本的 SDK存储默认 SQLite生产环境可切换 PostgreSQL注意这里不需要限定具体版本号因为不同 Agent 和 ORG2 版本的兼容关系需要以官方发布信息为准。关键是理解接入模式。4.2 安装 ORG2 客户端假设 ORG2 提供了 Python SDK安装方式大致如下pip install org2-sdk如果是通过源码接入也可以把 SDK 目录加入项目路径git clone https://example.com/org2/org2-sdk.git cd org2-sdk pip install -e .安装完成后验证导入是否成功python -c import org2; print(org2.__version__)如果输出版本号说明安装成功。4.3 初始化 ORG2 记录器记录器的初始化是接入的第一步。核心参数包括存储路径、会话名称、以及要追踪的 Agent 名称。from org2 import Recorder # 初始化记录器 recorder Recorder( storage_path./.org2_store, project_namedemo-repo, session_namefix-login-bug, )这里重点说明几个参数的作用storage_path事件数据的存储目录。project_name项目标识用于区分不同仓库的记录。session_name会话名称建议按任务命名方便后续检索。4.4 包装 Agent 的执行记录器准备好后需要把它“挂”到 Agent 的调用链上。不同 Agent 的接入方式不同但核心思路是一致的在 Agent 执行前开启记录在执行过程中捕获动作在执行结束后保存并关闭。# 使用上下文管理器方式接入 with recorder.start(): result agent.run(task修复登录接口的 bug)如果 AGENT 提供了回调机制或钩子函数可以在钩子里显式上报动作def on_action(action): recorder.record(action) agent.on_action on_action agent.run(task修复登录接口的 bug)需要注意这里不要直接修改 Agent 的源码逻辑。优先使用官方提供的适配方式。如果 SDK 还没有适配你使用的 Agent也可以在 Agent 的工具调用层做一层薄包装把每一步转发给 ORG2。4.5 查看录制结果录制完成后可以查看会话列表和详情。下面演示一个简化的查询流程from org2 import QueryClient client QueryClient(storage_path./.org2_store) # 获取所有会话 sessions client.list_sessions() for s in sessions: print(s.session_id, s.name, s.status) # 获取某个会话的所有动作 actions client.list_actions(session_idsess_20240615_001) for a in actions: print(f[{a.timestamp}] {a.type} - {a.path or a.command})这段代码演示了三个常用操作列会话、查动作、查看命令结果。这是日常调试使用频率最高的功能。5. 数据采集模块的完整实现示例为了让理解更落地下面用一个简化的 Python 模块演示“一个轻量 Agent 记录仪”是怎么实现的。这不是要重复造 ORG2 的轮子而是帮助你理解底层机制。5.1 项目结构demo-recorder/ ├── recorder/ │ ├── __init__.py │ ├── models.py │ └── recorder.py ├── agent_adapter.py └── main.py5.2 定义数据模型先定义事件的数据结构用dataclass表示# 文件路径demo-recorder/recorder/models.py from dataclasses import dataclass, field from datetime import datetime from typing import Any, Optional dataclass class Action: type: str session_id: str timestamp: datetime field(default_factorydatetime.utcnow) path: Optional[str] None command: Optional[str] None output: Optional[str] None exit_code: Optional[int] None diff: Optional[str] None metadata: dict[str, Any] field(default_factorydict) dataclass class Session: session_id: str agent_name: str status: str running start_time: datetime field(default_factorydatetime.utcnow) end_time: Optional[datetime] None actions: list[Action] field(default_factorylist)5.3 实现记录器记录器负责追加事件和序列化存储# 文件路径demo-recorder/recorder/recorder.py import json import uuid from pathlib import Path from .models import Action, Session class Recorder: def __init__(self, storage_path: str): self.storage_path Path(storage_path) self.storage_path.mkdir(parentsTrue, exist_okTrue) self.sessions [] self.current_session: Session | None None def create_session(self, agent_name: str) - str: session_id fsess_{uuid.uuid4().hex[:12]} session Session(session_idsession_id, agent_nameagent_name) self.current_session session self.sessions.append(session) return session_id def record(self, action: Action) - None: if self.current_session is None: raise RuntimeError(请先创建会话) self.current_session.actions.append(action) self._append_to_file(action) def _append_to_file(self, action: Action) - None: file_path self.storage_path / f{self.current_session.session_id}.jsonl with open(file_path, a, encodingutf-8) as f: f.write(json.dumps(action.__dict__, defaultstr) \n) def finish_session(self) - None: if self.current_session: self.current_session.status finished self.current_session.end_time datetime.utcnow() def replay(self, session_id: str) - list[dict]: file_path self.storage_path / f{session_id}.jsonl if not file_path.exists(): return [] events [] with open(file_path, r, encodingutf-8) as f: for line in f: events.append(json.loads(line)) return events这段代码虽小但已经包含了记录器的核心逻辑create_session新建会话。record记录动作并追加到 JSONL 文件。replay读取会话的历史事件。5.4 Agent 适配层下面模拟一个简单的 Agent并给它加上记录能力。# 文件路径demo-recorder/agent_adapter.py import subprocess from recorder.models import Action from recorder.recorder import Recorder class SimpleAgent: def __init__(self, recorder: Recorder): self.recorder recorder def read_file(self, path: str) - str: content open(path, encodingutf-8).read() self.recorder.record( Action( typefile_read, session_idself.recorder.current_session.session_id, pathpath, metadata{size: len(content)}, ) ) return content def write_file(self, path: str, content: str) - None: with open(path, w, encodingutf-8) as f: f.write(content) self.recorder.record( Action( typefile_write, session_idself.recorder.current_session.session_id, pathpath, difff{content}, ) ) def run_command(self, command: str, cwd: str | None None) - str: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, cwdcwd, ) self.recorder.record( Action( typecommand_run, session_idself.recorder.current_session.session_id, commandcommand, outputresult.stdout result.stderr, exit_coderesult.returncode, ) ) return result.stdout result.stderr这个适配层的意义在于所有 Agent 与外部世界的交互都经过一层包装而这层包装天然记录了全部动作。真实 ORG2 的适配原理和这个类似只是做得更通用、更健壮。5.5 模拟 Agent 执行最后写一个主程序模拟 Agent 执行一个简单的修复任务# 文件路径demo-recorder/main.py from agent_adapter import SimpleAgent from recorder.models import Action from recorder.recorder import Recorder def main(): recorder Recorder(storage_path./.org2_demo_store) session_id recorder.create_session(agent_namesimple-agent) agent SimpleAgent(recorder) print(开始执行任务修复 utils.py 中的 find_by_id 函数) # 1. 读取文件 content agent.read_file(utils.py) print(f读取到 {len(content)} 字节) # 2. 检查测试 output agent.run_command(pytest test_utils.py -x, cwd.) print(f测试输出长度{len(output)}) # 3. 根据失败信息修改文件 fixed_content content.replace( return None, return item if item else None ) agent.write_file(utils.py, fixed_content) # 4. 再次运行测试 output agent.run_command(pytest test_utils.py -x, cwd.) print(f测试输出长度{len(output)}) recorder.finish_session() print( 回放记录 ) for event in recorder.replay(session_id): print(f[{event[timestamp]}] {event[type]}: {event.get(path) or event.get(command)}) if __name__ __main__: main()运行方式python main.py预期输出大致如下开始执行任务修复 utils.py 中的 find_by_id 函数 读取到 356 字节 测试输出长度512 测试输出长度463 回放记录 [2024-06-15 10:30:00.123] file_read: utils.py [2024-06-15 10:30:00.456] command_run: pytest test_utils.py -x [2024-06-15 10:30:00.789] file_write: utils.py [2024-06-15 10:30:01.123] command_run: pytest test_utils.py -x从这个演示可以看到Agent 做了什么、怎么做的、做了几次全部有据可查。这就是行车记录仪的基本形态。6. 常见问题与排查思路在实际落地 ORG2 或类似方案时会遇到一些典型问题。下面整理成排查清单。6.1 事件丢失问题现象常见原因解决思路部分动作没有记录工具调用走的路径没有经过采集层检查 Agent 是否有内置命令执行路径绕过了包装文件写入动作丢失使用了批量写入或原子写入 macOS 特性增加对os.replace、shutil.move的监听子进程命令未记录Agent 内部用了 subprocess 直接调用确保在进程级做命令包装排查顺序先确认记录器是否正常开启打印 Recorder 实例状态。再确认 Agent 的实际调用链看是否有绕过包装的路径。最后在操作系统的文件监听层做验证确保事件是否到达采集层。6.2 数据量过大代码 Agent 运行一次可能产生上千条事件长时间使用后存储占用增长很快。建议的缓解方式隔离存储每个项目或每个会话单独一个目录。定期归档把超过 30 天的会话压缩打包。按需采样对大量重复的轮询事件可以降低采样频率。精简保存命令输出可以截断前 2000 字符或后 500 字符。6.3 回放速度慢回放慢通常是因为需要逐条加载事件再重新渲染。优化方式按 session 建立索引避免全表扫描。回放时只加载需要的动作类型。对超大会话做分页回放而不是一次性全部加载。6.4 Agent 不兼容如果 ORG2 还没有适配你使用的 Agent可以先做一层手动包装。原理已经在上面的示例中展示过了。手动包装的注意点不要改 Agent 源码。优先用 Agent 暴露的插件接口或回调机制。只记录不拦截保证最小侵入。6.5 时间不同步Agent 运行时如果跨多台机器不同节点的时间戳可能出现偏差。解决方式使用统一的 NTP 服务同步系统时间。时间戳尽量使用 ISO 8601 格式带时区。在会话元数据中记录执行节点信息方便校准。7. 最佳实践与工程建议这一节是给已经在用 ORG2、或者准备在团队内部落地 Agent 可观测性的读者看的。建议偏工程实践向。7.1 事件字段要结构化不要只记录“做了什么”要把关键上下文一起保存。结构化字段的价值体现在后续检索和分析上。上一节的事件结构示例就是一个好模板建议在此基础上补充{ request_context: { task: 修复登录接口 bug, user: zhangsan, repo: org2/demo, branch: feature/login-fix }, model_info: { provider: openai, model: gpt-4o, temperature: 0.2 } }有了这些上下文回放时才能还原“当时为什么这么做”而不只是“当时做了什么”。7.2 区分“可观测”和“可审查”如果你的团队要用 Agent 生成的代码做生产发布那么审查级别的要求会比调试级别更高。两个场景的要求不同场景关注点记录要求开发调试找到失败原因记录命令输出、错误信息即可生产审查确认行为合法、合规必须记录修改前后的完整 diff、涉及文件清单、执行时间、审批人如果是生产场景建议在 Agent 任务完成后自动生成一份“变更报告”内容包括修改了哪些文件。新增了哪些文件。删除或重命名了哪些文件。是否执行了包安装命令。是否运行了数据库迁移命令。最终测试是成功还是失败。7.3 控制安全边界Agent 本身也是一段代码它运行的命令必须受到约束。行车记录仪不负责拦车但你要自己设置路障。常用的安全建议包括在沙箱容器或隔离环境中运行 Agent。限制 Agent 可读写的目录范围。对命令执行做白名单禁止高危命令。对网络访问做限制避免 Agent 下载未知依赖。定期核查 Agent 的权限使用最小权限原则。尤其是当 Agent 自动修改代码时需要设置“人工审批后才可合入”的门禁。行车记录仪可以做事后追溯但事前拦截仍然不能省。7.4 按任务粒度建立索引会话层级太粗动作层级太细。日常使用时按任务粒度建立索引是最实用的。建议的索引维度任务 ID。Agent 名称。使用的模型。任务状态成功、失败、超时。涉及的文件列表。执行时长。有了任务级索引团队就能快速回答“上周所有失败的 Agent 任务有哪些”“哪个 Agent 改文件最频繁”这类管理问题。7.5 让 Agent 自己也“看到”记录这是一个更进阶的用法把历史记录作为上下文反馈给 Agent。当 Agent 再次执行类似任务时可以先读取上一次记录的摘要避免重复踩坑。也就是说行车记录仪不仅能供人查看也能变成 Agent 的“驾驶经验”。比如history client.get_session_summary(session_idsess_xxx) prompt f参考上一次任务的执行经验{history}现在开始新任务。这种“经验回放”的方法能明显提升 Agent 在重复任务上的稳定性尤其是同一仓库内的烂摊子修复类任务。7.6 日志级别与采样策略最后提醒一下日志级别的设计。不是所有动作都值得完整记录。建议按重要度分级级别动作类型保存策略CRITICAL文件写入、命令执行、模型决策必须完整保存INFO文件读取、搜索保存路径即可不必保存全文DEBUG完整输出、重复轮询按需开启默认关闭这样既能保证问题可追溯又不会让存储爆炸。8. 总结本文围绕“给代码 Agent 装上行车记录仪”这个主题完整介绍了 ORG2 的背景、核心能力、数据模型、接入方式和落地经验。重点内容可以归纳为以下几点第一代码 Agent 的执行过程具有不可复现性传统日志不足以支撑调试和审查需要一套以事件流为核心的过程记录体系。第二ORG2 通过“会话 - 任务 - 动作”三层数据模型把 Agent 的每一步操作统一记录并提供录制回放、进度追踪、工作空间快照、多 Agent 兼容等能力。第三接入过程的核心思路是在 Agent 的工具调用层做透明包装。你已经看到了一个最小可运行的记录器实现它能记录文件读取、文件写入和命令执行并支持按会话回放。第四落地时要注意数据量控制、时间同步、安全边界和行为审查。如果你手头正好有代码 Agent 的项目我建议你先不要急着部署完整方案而是先跑一个 30 分钟的试点选一个真实任务记录一次完整的 Agent 执行过程回放一遍看看能发现哪些之前看不到的问题。这个过程会让你对“Agent 可观测性”有非常直观的体感。
