企业官网建设流程全解析

先问一个问题：你在本地跑代码 Agent（比如自动写代码、自动改 Bug、自动跑测试的 AI 工具）时，有没有过这种体验——Agent 运行了十几分钟，最后给你的结果完全不对，而且你根本不知道它中间到底做了什么？你只能看到最终提交的 diff，但看不到它为什么选这条路、改过哪些文件、报过哪些错、重试了几次。

传统的日志系统只能记下“哪一秒调用了哪个函数”，但 Agent 的执行过程是高度动态的：它会自己读文件、改代码、执行命令、看报错、再调整方案。这个过程如果不可见，出了问题就只能当黑盒处理，排查效率非常低。

本文要介绍的 ORG2，就是一套专门为代码 Agent 设计的“行车记录仪”。它会给 20 多种主流代码 Agent 装上完整的录制回放能力，让你能像回看行车录像一样，精确回放 Agent 的每一步操作、每一次决策、每一段代码变更。

如果你是 AI Agent 开发者、代码工具使用者，或者正在把 Agent 接入团队开发流程，这篇文章会帮你理解 ORG2 的核心设计、接入方式、数据模型和落地经验。读完你会知道：一个可观测的 Agent 系统应该记录什么、怎么记录、以及记录之后如何分析和排查。

1. 背景与核心概念

1.1 代码 Agent 为什么需要“行车记录仪”

先解释一下代码 Agent 是什么。

代码 Agent 是指一类能够自主完成编程任务的 AI 程序。它不只是“根据提示生成一段代码”，而是会像人类开发者一样工作：

1. 阅读理解用户的需求。
2. 浏览项目目录结构。
3. 读取相关源码文件。
4. 编写或修改代码。
5. 运行测试命令。
6. 根据报错信息调整策略。
7. 重复上述过程，直到完成任务或达到上限。

目前主流的代码 Agent 包括 GitHub Copilot Workspace、Cursor Agent、Devin、SWE-agent、OpenHands（原 OpenDevin）、AutoGPT 等，它们能力不同，但工作模式很相似：都是一个“感知 - 决策 - 执行 - 观察”的循环。

这个循环带来了一个传统软件没有的新问题：不可复现性。

普通程序的执行过程是确定的：同一份输入，走同一条代码路径，产生同样的输出。但代码 Agent 依赖大模型决策，每一步都有随机性。即使给了完全相同的任务和仓库，Agent 两次运行的路径也可能完全不同：第一次先改了 A 文件，第二次可能先改了 B 文件。

这就导致了一个尴尬的局面：

• Agent 说“完成了”，你只能拿到最后的 diff，不知道它绕了多远。
• 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 在文件系统上的所有操作，常见的动作类型包括：

每一项动作都会记录四个基本信息：发生了什么、发生在哪个文件/命令上、发生在什么时间、执行结果是什么。

2.2 录制与回放

录制与回放是 ORG2 最有辨识度的功能。

录制阶段，ORG2 把 Agent 的每一步操作按时间顺序写入存储。回放阶段，你可以像看视频一样，把整个过程从头到尾重新走一遍。

回放有两种模式：

1. 时间轴模式：按时间顺序展示所有动作，适合整体回顾。
2. 聚焦模式：只看某类动作，例如只看文件写入，或只看命令执行。

聚焦模式在排查问题时特别有用。比如想确认 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+\n+def 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 为例，建议环境如下：

注意，这里不需要限定具体版本号，因为不同 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_name="demo-repo", session_name="fix-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_id="sess_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.py

5.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_factory=datetime.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_factory=dict) @dataclass class Session: session_id: str agent_name: str status: str = "running" start_time: datetime = field(default_factory=datetime.utcnow) end_time: Optional[datetime] = None actions: list[Action] = field(default_factory=list)

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(parents=True, exist_ok=True) self.sessions = [] self.current_session: Session | None = None def create_session(self, agent_name: str) -> str: session_id = f"sess_{uuid.uuid4().hex[:12]}" session = Session(session_id=session_id, agent_name=agent_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", encoding="utf-8") as f: f.write(json.dumps(action.__dict__, default=str) + "\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", encoding="utf-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, encoding="utf-8").read() self.recorder.record( Action( type="file_read", session_id=self.recorder.current_session.session_id, path=path, metadata={"size": len(content)}, ) ) return content def write_file(self, path: str, content: str) -> None: with open(path, "w", encoding="utf-8") as f: f.write(content) self.recorder.record( Action( type="file_write", session_id=self.recorder.current_session.session_id, path=path, diff=f"+{content}", ) ) def run_command(self, command: str, cwd: str | None = None) -> str: result = subprocess.run( command, shell=True, capture_output=True, text=True, cwd=cwd, ) self.recorder.record( Action( type="command_run", session_id=self.recorder.current_session.session_id, command=command, output=result.stdout + result.stderr, exit_code=result.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_name="simple-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 事件丢失

排查顺序：

1. 先确认记录器是否正常开启，打印 Recorder 实例状态。
2. 再确认 Agent 的实际调用链，看是否有绕过包装的路径。
3. 最后在操作系统的文件监听层做验证，确保事件是否到达采集层。

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 生成的代码做生产发布，那么审查级别的要求会比调试级别更高。

两个场景的要求不同：

如果是生产场景，建议在 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_id="sess_xxx") prompt = f"参考上一次任务的执行经验：{history}，现在开始新任务。"

这种“经验回放”的方法能明显提升 Agent 在重复任务上的稳定性，尤其是同一仓库内的烂摊子修复类任务。

7.6 日志级别与采样策略

最后提醒一下日志级别的设计。不是所有动作都值得完整记录。

建议按重要度分级：

这样既能保证问题可追溯，又不会让存储爆炸。

8. 总结

本文围绕“给代码 Agent 装上行车记录仪”这个主题，完整介绍了 ORG2 的背景、核心能力、数据模型、接入方式和落地经验。重点内容可以归纳为以下几点：

第一，代码 Agent 的执行过程具有不可复现性，传统日志不足以支撑调试和审查，需要一套以事件流为核心的过程记录体系。

第二，ORG2 通过“会话 - 任务 - 动作”三层数据模型，把 Agent 的每一步操作统一记录，并提供录制回放、进度追踪、工作空间快照、多 Agent 兼容等能力。

第三，接入过程的核心思路是在 Agent 的工具调用层做透明包装。你已经看到了一个最小可运行的记录器实现，它能记录文件读取、文件写入和命令执行，并支持按会话回放。

第四，落地时要注意数据量控制、时间同步、安全边界和行为审查。

如果你手头正好有代码 Agent 的项目，我建议你先不要急着部署完整方案，而是先跑一个 30 分钟的试点：选一个真实任务，记录一次完整的 Agent 执行过程，回放一遍，看看能发现哪些之前看不到的问题。这个过程会让你对“Agent 可观测性”有非常直观的体感。