# 运行观测契约

## 1. 聚合层次

```text
Run
  └─ Turn
      ├─ ModelCall attempt
      └─ ToolCall
```

普通 Run API 返回状态、可见消息和聚合 usage；详细对象只通过诊断 API 返回。

## 2. `turn`

必需字段：

- `id`、`run_id`、可选 `parent_turn_id`；
- `turn_index`、`status`、`started_at`、`ended_at`；
- `input_message_ids`、`output_message_ids`；
- `context_snapshot_id`、`plugin_snapshot_id`；
- `finish_reason`、`error_code`、`trace_id`。

## 3. `model_call`

每次上游 attempt 单独记录：

| 字段 | 说明 |
| --- | --- |
| `id`、`turn_id`、`attempt_index` | 关联和重试顺序 |
| `provider`、`endpoint_id` | 实际上游 |
| `logical_model`、`upstream_model` | 业务模型与实际模型 |
| `request_started_at`、`first_token_at`、`completed_at` | 时间点 |
| `latency_ms`、`time_to_first_token_ms` | 延迟 |
| `input_tokens` | 未缓存输入 |
| `cache_creation_input_tokens` | Provider 缓存写入 |
| `cache_read_input_tokens` | Provider 缓存读取 |
| `output_tokens` | Provider 输出 |
| `reasoning_tokens` | 供应商明确返回时记录数量 |
| `audio_*`、`image_*` | 适用且供应商返回时记录 |
| `cache_hit` | `true` / `false` / `null` |
| `cost_minor`、`currency`、`price_version` | 可重算成本 |
| `request_id`、`upstream_request_id` | 本地与供应商请求关联 |
| `finish_reason`、`error_type`、`error_code` | 结果 |
| `usage_source` | provider / estimate / unavailable |

总输入：

```text
total_input_tokens =
  input_tokens +
  cache_creation_input_tokens +
  cache_read_input_tokens
```

`cache_hit=true` 仅当 `cache_read_input_tokens > 0`；供应商明确返回 0 时为 false；未提供相关字段时为 null。

上述公式定义的是 **Hunjing 标准化语义**。Adapter 必须先处理供应商差异：Anthropic 的 `input_tokens` 是未缓存部分，可直接映射；OpenAI 的 `input_tokens` 通常包含 `input_tokens_details.cached_tokens`，因此标准化时将后者映射到 `cache_read_input_tokens`，并将两者之差映射到本字段的 `input_tokens`。原始 usage 经脱敏后另存 `usage_raw_redacted`，便于核对，不能直接混加造成重复计数。

| 标准字段 | Anthropic | OpenAI |
| --- | --- | --- |
| `upstream_request_id` | `request-id` / error `request_id` | `x-request-id` |
| `input_tokens` | `usage.input_tokens` | `usage.input_tokens - usage.input_tokens_details.cached_tokens` |
| `cache_read_input_tokens` | `usage.cache_read_input_tokens` | `usage.input_tokens_details.cached_tokens` |
| `cache_creation_input_tokens` | `usage.cache_creation_input_tokens` | 无对应字段时为 `null` |
| `output_tokens` | `usage.output_tokens` | `usage.output_tokens` |

字段路径按具体 API 端点和 SDK 版本适配；表中缺失表示“该端点未返回”，不是数值 0。

## 4. 字段来源

### 供应商原生

供应商返回且 Adapter 原样标准化：

- 上游模型 ID；
- request ID；
- stop/finish reason；
- input/output/cache/reasoning token（若存在）；
- server tool usage（若存在）；
- 供应商错误类型。

### 平台计算

- `latency_ms`、`time_to_first_token_ms`；
- logical model、endpoint、attempt index；
- 成本与价格版本；
- cache hit 三态；
- retry/fallback 关联；
- Context 和 Plugin snapshot；
- 业务 trace。

平台计算字段不能标记 `usage_source=provider`。

## 5. `tool_call`

字段：

- `id`、`turn_id`、`step_index`、`call_index`；
- `tool_id`、`plugin_id`、`plugin_version`、`execution_backend`；
- `arguments_redacted`、`arguments_hash`、`redaction_status`；
- `result_redacted`、`result_size_bytes`、`is_error`；
- `status`、`error_code`、`started_at`、`ended_at`、`latency_ms`；
- `confirmation_id`、`policy_decision_id`；
- `trace_id`、`idempotency_key`、`evidence_ids`。

常规表禁止保存 Authorization、密钥、签名 URL、文件原文和第三方高敏正文。

## 6. Context Manifest

ContextSnapshot 保存：

- 来源对象 ID 与版本；
- 来源类型：system、character、message、memory、knowledge、tool result；
- 每项估算或真实 token；
- 采用、裁剪、压缩或拒绝原因；
- 最终顺序和不可逆内容摘要；
- cache breakpoint 位置与 Provider cache usage。

不保存隐藏 chain-of-thought。完整 Prompt 仅在用户明确生成敏感支持包时限期保存。

## 7. 普通与诊断响应

| 数据 | 普通 Run API | Summary | Detailed | Sensitive |
| --- | ---: | ---: | ---: | ---: |
| 状态、可见消息 | 是 | 是 | 是 | 是 |
| 聚合 token/cost | 是 | 是 | 是 | 是 |
| Model attempt | 否 | 摘要 | 是 | 是 |
| Tool 名、状态、耗时 | 否 | 是 | 是 | 是 |
| 脱敏参数/结果 | 否 | 否 | 是 | 是 |
| 受限敏感内容 | 否 | 否 | 否 | 额外确认 |
| 隐藏推理 | 否 | 否 | 否 | 否 |