# 代理操作时间线：比较时间戳，避免被它们误导

代理操作时间线即使每个系统都记录了真实时间戳，也可能讲出一个令人信服的谎言。谎言往往出现在调查人员把本地时钟显示、API 服务器接收时间和审计记录，当成同一时刻的等价证据时。

请按实际观察结果存储时间戳，同时保留数值偏移量和来源。之后把它们当成含义不同的独立时钟进行比较。这样需要的数据比单独一个 `created_at` 字段多一些，却能避免事故报告中常见的错误，例如代理看起来在收到审批前就执行了操作，或者 API 请求看起来在开始前就已经完成。

## 一个时间戳无法描述一次操作

一次操作通常有多个有意义的时间点。代理可能在某个瞬间决定调用 API，稍后发送字节，再晚一些到达服务器，最后在服务器完成工作后收到结果。当有人询问代理是否超出了权限时，这些事件中的每一个都可能很重要。

一条典型记录至少包含以下几种声明：

- 代理进程声明它何时开始操作。
- 接收服务器声明它何时接受请求。
- 接收服务器还可能声明它何时提交或完成工作。
- 操作网关声明它何时收到并放行请求。
- 用户界面可能向人展示一个本地时间。

这些不是同一个字段的互相冲突的版本，而是因果顺序中不同节点的描述。如果在采集时把它们压缩成一个标准化时间戳，就会丢失能够解释队列、网络延迟、重试、等待审批和长时间调用的关键区别。

我见过团队把 API 审计条目标记为代理“完成操作”的时间，但那条记录实际上只表示请求被接受。端点如果先将工作排入队列，过了很久才执行变更，这个错误就会带来高昂代价。代理可能在变更发生前已经停止，但它发出的请求仍然造成了变更。

请使用能够说明事件的名称。`agent_action_started_at`、`gateway_received_at`、`server_received_at` 和 `server_completed_at` 会迫使读者询问每个时间点发生了什么。名为 `timestamp` 的模糊字段，则会鼓励人们在事后自行猜答案。

## 偏移量保留时间点，时区解释显示方式

数值 UTC 偏移量可以把墙上时钟读数转换为一个确定的时间点。命名时区则解释产生该读数的民用时间规则。很多时候二者都需要，但它们解决的是不同问题。

请看下面两个值：

```text
2025-11-02T01:30:00-04:00
2025-11-02T01:30:00-05:00
```

两者的表盘时间都是凌晨 1:30，但它们相差一小时。在北美夏令时回拨期间，本地时间会重复出现。像 `2025-11-02 01:30:00` 这样的无限定值，会让调查人员无法判断究竟发生在哪个时间点。

RFC 3339 直接解决了这个问题。它的时间戳格式使用完整的日期和时间，并配合表示 UTC 的 `Z` 或数值偏移量。RFC 还允许使用 `-00:00`，表示来源知道时间，但不知道本地偏移量。这种区别本身就是有用的证据。不要悄悄把 `-00:00` 改写成 `Z`，因为 UTC 声明了来源并未声明的事实。

当人工审批、支持工单或屏幕录制涉及当地办公室时间时，仍然值得保存诸如 `America/Los_Angeles` 这样的时区标识符。它能让调查人员重现该地点适用的日历规则，但不能替代偏移量。时区规则可能变化，同一个时区在一年中的不同时间也可能使用不同偏移量。

请将收到的时间戳作为字符串保存，保留原始偏移量，并推导出 UTC 时间点用于排序。不要只保存渲染后的本地字符串。渲染应发生在边缘，由人选择显示时区。

## 本地、服务器和审计时钟回答不同问题

本地时间说明操作员或代理主机认为当时几点。服务器时间说明远程服务何时观察到或执行了工作。审计时间说明记录系统何时接受了事件。调查人员应比较这三种时间，而不是选出其中一个作为普遍真相。

先确定事件边界。代理请求 `POST /deployments` 时，本地操作时间可以帮助说明它的意图。服务器接收时间可以确定远程服务何时开始对该请求负责。服务器完成时间可以确定部署状态何时改变。审计条目可以确定你的控制点何时观察到这次尝试，以及它是否批准了请求。

网络延迟会在这些值之间产生正常间隔，队列会造成更大的间隔。重试会让问题更复杂，因为客户端可能为多次尝试使用同一个操作标识，而服务器会分别记录每次尝试。只显示第一个本地时间的时间线会隐藏这些信息。

除非你知道设备如何同步时间，否则不要用浏览器显示、终端提示符或截图中的时钟来决定先后。这些显示通常有助于解释某个人当时的认知，却很少能解决接近的顺序争议。

调查表可以使用以下三列：

| 证据来源 | 保留内容 | 用来回答的问题 |
|---|---|---|
| 代理主机 | 原始本地时间戳、偏移量、时区、进程身份 | 该进程声称何时开始操作或收到结果？ |
| 远程服务 | 请求 ID、接收时间、完成时间、响应状态 | 服务何时接受并执行了工作？ |
| 审计系统 | 事件 ID、记录时间、完整性证明、授权结果 | 控制点何时观察到并允许或拒绝了调用？ |

即使增加了用于计算 UTC 排序的列，也应保留每一行自己的时间。只有一列时间的整洁表格看起来很方便，却会掩盖证据链。

## 夏令时变化会产生重复小时和缺失小时

夏令时切换会暴露时间戳方面的捷径，因为它打破了一个常见假设：每一分钟本地时间只出现一次，每天长度都相同。两个假设都不成立。

秋季回拨时，一个本地小时会重复。春季调整时，一个小时根本不存在。解析无限定本地时间戳的程序必须选择规则、拒绝输入或进行猜测。在审计路径中，猜测不可接受。

下面的记录之所以可用，是因为它同时携带了精确时间点和生成该时间的民用时间背景：

```json
{
  "event_id": "act_8f3c",
  "event": "authorization_granted",
  "observed_at": "2025-11-02T01:14:22-04:00",
  "zone": "America/New_York",
  "instant_utc": "2025-11-02T05:14:22Z",
  "clock_source": "agent_host"
}
```

`instant_utc` 是推导值，因此也要保留原始的 `observed_at` 字符串。如果解析器后来发生变化，或转换过程存在缺陷，你就能重新推导并解释差异。应把推导值当成分析输出，而不是源证据的替代品。

像 `EST` 这样的时区缩写会让事情更复杂。缩写在不同地区可能含义不同，也不能可靠说明是否处于夏令时。请使用 IANA 时区标识符表示民用时间背景，使用数值偏移量表示时间点。如果来源只能输出缩写，就原样记录，并注明其含义尚未确定。

重复执行的计划需要单独的规则。请将计划保存为本地时间加 IANA 时区，然后根据该时区的规则计算每次发生时间。实际运行的操作则保存为带偏移量的时间戳。计划说明任务原本应在何时运行，事件记录说明它实际何时运行。

## 时钟漂移会把看似精确的顺序变成错误的确定性

毫秒级精度不代表毫秒级准确度。一台未同步的笔记本可以生成六位小数的时间戳，但实际时间可能与服务器相差数分钟。休眠、网络中断、虚拟机和同步故障都会造成这个问题。

在数据模型中分开表示精度和不确定性。精度是记录了多少位数字，不确定性是你认为实际时间点可能落在哪个区间内。一台主机记录 `10:00:00.123Z`，但不确定性为两秒时，不应该用它来解决与远程 API 之间一秒钟的顺序争议。

如果条件允许，请测量时钟偏移。在代理运行前后分别从可信参考源获取时间，然后保存观察到的差值。如果参考源是远程的，还要考虑请求传输时间。在粗略的运维工作中，简单的往返中点估计通常够用，但应保留测量结果，不要把它呈现为精确修正。

例如，采集器在本地 `10:00:00.000` 发送请求，在本地 `10:00:00.200` 收到可信响应，而响应中的时间是 `10:00:00.150Z`。服务器时间发生在这次往返期间的某个时刻。本地中点是 `10:00:00.100`，因此在通常的对称传输假设下，主机看起来慢了约 50 毫秒。这个假设可能不成立，所以有用的结果应是一个范围，而不是一个真相声明。

单调时钟只能解决更小范围的问题。它在单个运行中的进程内测量经过的时间，不会因墙上时钟变化而跳动。当你需要证明同一进程内操作 B 在操作 A 之后发生时，可以同时记录单调开始值和持续时间。但不要把单调值转换成 UTC，也不要跨主机比较。

NTP 文档也作了类似的实际区分：同步估算的是偏移量和离散度，而不是授予完美时间。当顺序接近到足以影响结论时，应把这些估计作为证据的一部分。

## 在同一条记录中保留原始证据和标准化时间

可靠的事件模式会保留每个参与者实际报告的内容，并让分析可以重复进行。下面的 JSON 结构适用于代理操作，同时不会假装所有字段都来自同一个时钟。

```json
{
  "action_id": "a91c2d7e",
  "attempt": 2,
  "agent": {
    "process_id": "p_4b71",
    "started_at": "2025-04-18T14:07:12.481-07:00",
    "zone": "America/Los_Angeles",
    "monotonic_start_ms": 9184421,
    "clock_uncertainty_ms": 750
  },
  "gateway": {
    "received_at": "2025-04-18T21:07:12.661Z",
    "authorized_at": "2025-04-18T21:07:14.034Z",
    "result_released_at": "2025-04-18T21:07:14.882Z",
    "audit_event_id": "aud_3e90"
  },
  "server": {
    "request_id": "req_7c19",
    "received_at": "2025-04-18T21:07:14.301Z",
    "completed_at": "2025-04-18T21:07:14.649Z",
    "status": 201
  },
  "normalization": {
    "sort_instant_utc": "2025-04-18T21:07:12.481Z",
    "method": "RFC3339 offset conversion"
  }
}
```

这个模式划出了团队经常混淆的边界：操作标识连接各条记录，时间戳则排列该操作内部的某个事件。重试后继续使用同一个标识是合理的，但不能为每个阶段重复使用一个时间戳。

即使已经有内部操作 ID，也要记录服务器请求 ID。调查期间，服务器自己的标识往往是区分“请求超时”和“请求从未离开客户端”的唯一可靠方法。

除非生产方保证使用 UTC 并记录时钟来源，否则不要只保存 epoch 毫秒。epoch 值容易排序，却会丢失原始偏移量、显示背景，有时还会丢失单位。如果从第三方接收这类值，应明确记录单位，并保留收到时的原始表示。

## 当证据重叠时，时间线需要使用区间

当两个来源都存在不确定性时，应计算区间，而不是强行决定顺序。这样可以避免一个常见错误：调查人员看到 `10:03:01.010` 和 `10:03:01.400`，于是直接排序，并断言第一个事件导致了第二个事件，但两台机器的时钟偏移量其实未知。

假设代理报告操作开始于 `21:07:12.481Z`，不确定性为 750 毫秒。它的可能区间是 `21:07:11.731Z` 到 `21:07:13.231Z`。网关报告在 `21:07:12.661Z` 收到请求，不确定性为 20 毫秒。两个区间重叠，因此仅凭时间戳，无法证明网关是在代理声称开始操作之后收到调用的。协议顺序仍可能支持这个结论，但墙上时钟本身不能证明。

每个顺序判断都要说明依据。下面是几种不同的结论：

- “网关记录的接收时间晚于代理发出请求的时间”来自协议证据或关联的请求追踪。
- “网关接收时间戳更晚”只来自显示的墙上时钟时间。
- “在所声明的不确定性范围内，记录确定了先后顺序”适用于区间没有重叠的情况。
- 当区间重叠且没有因果证据填补空隙时，正确结论是“记录无法确定顺序”。

人们不喜欢第四种结论，因为事故报告总希望得到一个整齐的故事。制造虚假的精确度不会让故事更好，只会让下一位审阅者有理由怀疑周围的所有结论。

这也会改变告警设计。不要仅仅因为网关事件看起来比代理的本地开始时间早了几百毫秒，就标记代理异常。只有在应用已知偏移边界后仍出现负耗时，才应触发告警，否则应将其标记为时钟健康问题进行调查。

## 审批和执行必须使用独立时间戳

人工审批证明某人在特定时间允许了一项能力。它不能证明代理在同一时刻发送了请求，更不能证明远程系统就在那时完成了请求的工作。

请将审批事件与调用分开。审批记录应包含操作者、授予的范围、适用的进程或会话、观察时间，以及授权系统的事件 ID。调用记录应在适用时引用该授权，并保留自己的接收和放行时间。

在会话授权中，这个区别尤其重要。一次审批可能覆盖进程整个生命周期内的多次操作。如果后续操作造成损害，调查人员需要分别回答两个问题：授权何时发生？进程发出这次调用时是否仍在获批会话范围内？单独一个 `approved_at` 字段无法回答这两个问题。

逐次调用审批会形成更紧密的顺序，但仍然存在间隔。用户可能在 14:07:14 批准，网关在 14:07:14.1 派发，远程服务则在 14:08:02 提交。派发后的远程超时并不能排除服务已经完成操作的可能性。

对于由网关控制的工作流，也要记录拒绝事件。一次被拒绝的调用证明代理尝试过某个操作，即使不应产生远程请求。如果代理在权限变化后重试，时间线需要记录带有独立证据的多次尝试。不要用后来的成功覆盖之前的拒绝。

## 调查一次有争议的部署，但不要压平证据

假设代理在开发者批准会话后请求部署。开发者后来称审批发生在下班后，而远程服务记录却显示部署在审批前开始。表面上的矛盾经常来自把本地显示时间与 UTC 服务器时间放在一起比较。

证据包含以下记录：

| 事件 | 报告时间 | 来源 |
|---|---|---|
| 会话审批 | `2025-04-18T17:58:40-07:00` | 本地授权记录 |
| 代理开始部署调用 | `2025-04-18T17:59:02-07:00` | 代理主机 |
| 网关收到调用 | `2025-04-19T00:59:02.410Z` | 网关审计日志 |
| 远程服务接受请求 | `2025-04-19T00:59:04Z` | 服务审计记录 |
| 远程服务完成部署 | `2025-04-19T01:01:18Z` | 服务审计记录 |

转换前两条记录，但保留它们收到时的原始形式。审批发生在 `00:58:40Z`，代理在 `00:59:02Z` 开始操作。网关和服务记录随后按照合理的因果顺序出现。没有任何事情发生在审批之前，只是有人把 `17:58` 和 `00:59` 放在一起看，并误以为它们使用同一个时钟显示。

现在加入一个不舒服的事实。假设代理主机因为之前处于休眠状态，估计不确定性为 90 秒。你仍然可以说，网关收到调用的时间晚于授权系统记录审批的时间，因为这些记录来自网关和授权链路。但在这个区间内，不能使用代理本地开始时间来证明更细一级的先后顺序。

调查应同时保留这两个结论。一个结论很有把握，另一个结论受到限制。这样比把整条时间线伪装得同样精确更好。

## 在相信审计记录的时间位置前，先验证其完整性

只有验证了审计日志的完整性机制，才能判断是否有人篡改、重新排序或删除证据。在使用审计条目支持事件顺序前，先完成这项验证。然后再单独询问：每条记录使用的是什么时钟。

Sallyport 项目会将会话和调用日志写入一份加密、哈希链式的审计日志，`sp audit verify` 可以直接对密文离线验证这条链。调查人员因此能够在不暴露存储密钥的情况下检查日志连续性。

完整性不会把审计时间戳变成全球完美时钟。有效条目证明日志链中包含所记录的事件，但如果要将它与外部服务器进行精细比较，仍需要有记录的时钟来源、偏移格式和不确定性策略。

请对证据副本执行验证，并将命令结果与案件材料一同保存。有用的记录应包含命令、输入产物标识符、验证结果，以及执行验证的人员或自动化任务。不要只把一行绿色状态粘贴到工单中，下一位调查人员需要能够重复同样的检查。

哈希链还会改变你处理缺口的方式。如果链表明存在缺失或篡改，不要悄悄继续使用标准化时间线。应将受影响的区间标记为不完整，并寻找独立的服务器记录。缺失的审计片段可能比其前后的记录更能说明事故情况。

## 根据明确声明的假设构建调查视图

好的调查视图会展示原始时间戳、UTC 转换结果、来源身份和不确定性。它不会用“事件时间”这样的仪表板标签隐藏转换过程。读者应该能看出显示顺序是如何得出的。

组装操作时间线时，可以按以下顺序进行：

1. 收集不可变的源记录，保留原始时间戳字符串、标识符和偏移量。
2. 确认每个时间戳标记的事件，是决定、审批、网关接收、服务器接受、完成，还是结果放行。
3. 将带偏移量的时间戳转换为 UTC，写入单独字段，并记录使用的解析器或方法。
4. 为所有可能影响争议顺序的来源估计时钟不确定性。
5. 按标准化时间点排序，然后在作出因果判断前检查重叠的不确定性区间和请求 ID。

不要给本地时间戳附加调查人员当前使用的偏移量来完成转换。如果调查人员身处其他时区，或夏令时规则不同，这种做法会移动历史事件。应解析记录中提供的偏移量。如果记录没有偏移量，在确定来源时区及其适用规则前，将其标记为未解决。

团队应该在事故发生前测试这些情况。在非生产环境中创建一个接近夏令时切换的操作，在安全测试范围内调整客户端时钟，强制执行一次重试和延迟服务器响应，然后请没有参与日志构建的人重建事件顺序。如果他必须依赖口头说明才能解释证据，说明记录格式还不完整。

代理事故中的证据很少只有时间。请求标识符、授权范围、进程身份、响应正文和篡改检查，往往能建立时钟无法建立的事实。请将这些事实保留在各自的事件中。下一次出现有争议的操作时，你会更容易解释，因为你记录的是每个系统知道什么，而不是强迫所有系统接受一个虚构的时间戳。