删掉多余的

2026-09-21 16:43:26 +08:00
1 parent 887c1f449e
commit 192ea96eb4
@@ -134,6 +134,11 @@
 | chat_session 会话 | `session_` | 已用 |
 | chat_message 消息 | `message_` | 已用 |
 | run 运行 | `run_` | 已用 |
+| agent_turn Agent 轮次 | `turn_` | 规范 |
+| model_call 模型调用及重试尝试 | `model_call_` | 规范 |
+| context_snapshot 模型实际上下文快照 | `context_snapshot_` | 规范 |
+| plugin_snapshot Run 固定插件集合 | `plugin_snapshot_` | 规范 |
+| diagnostic_grant 运行诊断临时授权 | `diagnostic_grant_` | 规范 |
 | event 事件 | `event_` | 已用 |
 | trace 调用链 | `trace_` | 已用 |
 | user 用户 | `user_` | 已用 |
@@ -446,7 +451,76 @@
 | `audio` | 音频 |
 | `file` | 文件 |

-### 7.5 事件类型 `event.type`
+### 7.5 Agent 轮次与模型调用诊断
+
+每个 Agent 轮次必须持久化一条 `agent_turn` 记录；同一轮可有多次模型调用和多个工具调用。轮次、模型调用、工具调用、确认、证据和消息通过稳定 ID 关联，不能把调试信息塞入一段无结构 JSON 后失去查询能力。
+
+#### 7.5.1 `agent_turn`
+
+| 字段 | 必需 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | `turn_` 前缀 ID |
+| `run_id` | 是 | 所属 Run |
+| `character_id` | 条件 | 人物前台/受托 Run 必需；无身份功能 Agent 可为空 |
+| `parent_turn_id` | 否 | 子 Agent 或续跑来源轮次 |
+| `turn_index` | 是 | Run 内从 0 开始的单调序号 |
+| `status` | 是 | 当前轮次状态；稳定值在机器 Schema 落地前不得从实现反推 |
+| `started_at` / `ended_at` | 是 | UTC 时间；未结束时 `ended_at` 为空 |
+| `input_message_ids` | 是 | 本轮实际领取的输入消息 ID |
+| `output_message_ids` | 是 | 本轮产生的可见消息 ID |
+| `context_snapshot_id` | 否 | 模型实际采用的上下文快照 |
+| `plugin_snapshot_id` | 是 | 本轮固定的插件 ID、版本、摘要和配置哈希集合 |
+| `model_call_ids` | 是 | 本轮所有模型调用，包含失败与重试 attempt |
+| `tool_call_ids` | 是 | 本轮所有工具调用，按模型请求顺序保存 |
+| `confirmation_ids` | 是 | 本轮产生或消费的请命记录 |
+| `evidence_ids` | 是 | 支撑答复、行动和工具结果的证据 |
+| `finish_reason` | 否 | 正常完成、取消、失败、预算或其他终止原因 |
+| `error_code` | 否 | 失败时的标准错误码 |
+| `trace_id` | 是 | 跨 Host、模型网关、插件、MCP、Sandbox 的调用链 |
+| `diagnostic_level` | 是 | `summary` / `detailed` / `sensitive`，控制可查询内容层级 |
+
+#### 7.5.2 `model_call`
+
+每一次上游尝试都必须单独记录；网关 failover 或 retry 不得覆盖前一次失败。字段采用 Provider 无关语义，Provider 原始响应只在独立、限期、脱敏的调试存储中保存。
+
+| 字段 | 必需 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | `model_call_` 前缀 ID |
+| `turn_id` / `run_id` | 是 | 所属轮次和 Run |
+| `attempt_index` | 是 | 同一逻辑模型请求的尝试序号 |
+| `provider` / `endpoint_id` | 是 | 实际 Provider 与 Endpoint |
+| `logical_model` / `upstream_model` | 是 | 业务逻辑模型与实际模型 |
+| `capability` | 是 | chat、embedding、rerank、ASR、TTS、image 等能力 |
+| `stream` | 是 | 是否流式 |
+| `request_started_at` / `first_token_at` / `completed_at` | 是 | 请求、首 token 和完成时间；不可用时为空 |
+| `latency_ms` / `time_to_first_token_ms` | 是 | 完整延迟与首 token 延迟 |
+| `input_tokens` | 是 | 未命中缓存、按正常输入计价的 token |
+| `output_tokens` | 是 | 输出 token；适用时包含可见文本与其他输出 |
+| `reasoning_tokens` | 否 | Provider 明确返回时记录；不保存推理正文 |
+| `cache_creation_input_tokens` | 否 | 新写入 Provider Prompt Cache 的输入 token |
+| `cache_read_input_tokens` | 否 | 从 Provider Prompt Cache 命中的输入 token |
+| `cache_hit` | 是 | `true` / `false` / `unknown`，只由真实 usage 字段判定 |
+| `cache_key_hash` | 否 | 平台自管缓存的不可逆键摘要；不得记录 Prompt 原文 |
+| `audio_input_tokens` / `audio_output_tokens` | 否 | Provider 返回音频 token 时记录 |
+| `image_input_tokens` / `image_output_tokens` | 否 | Provider 返回图像 token 时记录 |
+| `tool_use_count` | 是 | 该模型响应请求的工具数量 |
+| `finish_reason` / `stop_sequence` | 否 | Provider 标准化停止信息；停止序列需按敏感规则脱敏 |
+| `request_id` / `upstream_request_id` | 是 | 魂镜请求 ID 与 Provider 请求 ID |
+| `cost_minor` / `currency` | 是 | 以货币最小单位或定点数记录本次尝试成本 |
+| `error_type` / `error_code` | 否 | 失败分类与领域错误码 |
+| `fallback_from_id` | 否 | 本次由哪个失败调用切换而来 |
+| `usage_source` | 是 | `provider` / `gateway_estimate` / `unavailable` |
+| `usage_raw_redacted` | 否 | 仅保留脱敏后的 Provider usage 扩展字段，不含消息正文 |
+
+`input_tokens + cache_creation_input_tokens + cache_read_input_tokens` 才是该次调用的总输入规模；不同 Provider 的 usage 定义可能不同，必须同时保存 `usage_source`、Provider、模型和价格版本。不得为了填满字段伪造缓存命中或 token 数。
+
+#### 7.5.3 工具调用诊断扩展
+
+除 §13.1 的状态外，`tool_calls` 必须保存：`turn_id`、`step_index`、`call_index`、`call_id`、`tool_id`、`plugin_id`、`plugin_version`、`execution_backend`、`arguments_redacted`、`arguments_hash`、`result_redacted`、`result_size_bytes`、`is_error`、`error_code`、`started_at`、`ended_at`、`latency_ms`、`confirmation_id`、`policy_decision_id`、`execution_ticket_id`、`evidence_ids`、`trace_id` 和 `idempotency_key`。
+
+完整工具参数和结果只在用户主动生成的敏感诊断包中按范围、期限和脱敏规则提供；常规数据库默认保存结构化摘要与哈希，不保存密钥、Authorization、签名 URL、文件原文或第三方高敏内容。
+
+### 7.6 事件类型 `event.type`

 命名规则：`域名.动作`，全小写点分。事件来源 `event.source` 取值 `user` / `sensor` / `model` / `tool` / `memory` / `planner` / `system` / `knocking_pivot`。

@@ -460,6 +534,10 @@ run.cancelled
 agent.started
 agent.turn.started
 agent.turn.ended
+model.request.started
+model.request.completed
+model.request.failed
+model.cache.observed
 agent.ended
 agent.cancelled
 agent.failed
@@ -524,7 +602,7 @@ proactive.message

 事件 `payload` 不得包含明文密钥、完整 provider 请求或高敏原文。

-### 7.6 `big_cycle.status`
+### 7.7 `big_cycle.status`

 大周天循环运行状态（architecture §3.2）。

@@ -535,7 +613,7 @@ proactive.message
 | `completed` | 循环完成 |
 | `failed` | 循环失败 |

-### 7.7 `pending_confirmations.status` 待确认记录状态
+### 7.8 `pending_confirmations.status` 待确认记录状态

 待确认工具调用的持久化记录（`pending_confirmations` 表），对应 `PendingConfirmationRecord` 模型。

@@ -1019,7 +1097,170 @@ proactive.message

 > 实现现状：代码当前 `decision` 值集与上述规范枚举存在偏差（`allow`/`deny`/`reject` 等），详见 §19 待统一项。

-### 13.4 `skills.status` / `mcp_servers.status` 能力启用状态
+### 13.4 运行诊断访问协议
+
+详细 Turn、模型调用、工具参数摘要、缓存与成本信息不随普通 Run/消息接口返回。调用方必须同时具备普通登录态和专用短期诊断授权；单独持有任一凭证均不足以读取。
+
+#### 13.4.1 请求头命名与类型
+
+新自定义 HTTP 字段不使用 `X-` 前缀。RFC 6648 已废弃以 `X-` 表示私有/实验参数的做法；产品命名空间直接使用 `Hunjing-`。HTTP 字段名按 RFC 9110 **大小写不敏感**，服务端必须把 `hunjing-diagnostic-token` 与本文规范写法视为同一字段；文档和 SDK 统一生成下表大小写。
+
+| 请求头 | ABNF / 值类型 | 必需 | 说明 |
+| --- | --- | --- | --- |
+| `Authorization` | `Bearer SP 1*b64token` | 是 | 普通访问令牌，语法遵循 RFC 6750，如 `Bearer eyJ...` |
+| `Hunjing-Diagnostic-Token` | `1*(ALPHA / DIGIT / "-" / "_")` | 是 | 不带 `Bearer` 前缀的 opaque token；规范前缀为 `hjd_`，建议总长 47 字符，即 `hjd_` + 43 个 base64url 字符 |
+| `Hunjing-Diagnostic-Purpose` | 下表枚举 token | 是 | 访问用途；不是自由文本，防止日志注入和不可聚合 |
+| `Hunjing-Request-ID` | `1*64(ALPHA / DIGIT / "-" / "_")` | 推荐 | 调用方生成的幂等/追踪 ID；不接受空格、逗号或重复字段 |
+
+`Hunjing-Diagnostic-Purpose` 取值：
+
+| 值 | 场景 |
+| --- | --- |
+| `user_inspection` | 用户检查自己的 Run |
+| `support_case` | 用户主动授权的支持工单 |
+| `security_investigation` | 经审批且对象受限的安全调查 |
+| `automated_evaluation` | 受控评测读取非敏感诊断字段 |
+
+所有字段都是**单值字段**，同名重复、逗号列表、空值、前后空白、CR/LF/NUL、超过长度上限或未知 Purpose 一律返回 `400 invalid_request`。令牌只能通过 TLS 请求头传递，不得放入 URL query、请求体、Cookie、SSE event data 或 WebSocket URL。
+
+禁止使用 `X-Debug-Token`、`X-Hunjing-*`、查询参数、Cookie 或普通管理员布尔值替代专用诊断令牌。反向代理、APM 和访问日志必须对 `Authorization` 与 `Hunjing-Diagnostic-Token` 完全脱敏。
+
+请求示例：
+
+```http
+GET /v1/runs/run_01J.../diagnostics?level=detailed HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOi...
+Hunjing-Diagnostic-Token: hjd_Qm9keV9pc19vcGFxdWVfYW5kX3JhbmRvbV9ieXRlcw
+Hunjing-Diagnostic-Purpose: user_inspection
+Hunjing-Request-ID: request_01JABCDEF
+Accept: application/json
+```
+
+#### 13.4.2 `diagnostic_grant`
+
+诊断令牌只保存哈希；明文只在签发响应中出现一次。授权记录至少包含：`id`、`token_hash`、`issuer_user_id`、`subject_user_id`、`personal_domain_id`、可选 `character_id` / `run_id` / `turn_id`、`scopes`、`diagnostic_level`、`purpose`、`support_case_id`、`issued_at`、`expires_at`、`used_at`、`max_uses`、`revoked_at`、`region_id` 和 `created_trace_id`。
+
+作用域至少区分：
+
+| Scope | 可读取内容 |
+| --- | --- |
+| `diagnostics:turn:summary` | 轮次状态、消息/调用 ID、耗时、工具名、聚合 token 与成本 |
+| `diagnostics:model:usage` | 每次模型 attempt、Provider/模型、token、缓存、延迟、成本、错误 |
+| `diagnostics:tool:summary` | 工具、插件、状态、确认、耗时、结果大小和脱敏摘要 |
+| `diagnostics:tool:sensitive` | 经额外确认后的参数/结果敏感诊断视图；默认不签发 |
+| `diagnostics:context:manifest` | Context Snapshot 的来源 ID、类型、token 数和裁剪原因，不含隐藏 CoT |
+| `diagnostics:audit:read` | 与本次诊断访问和目标 Run 相关的审计记录 |
+
+授权默认绑定一个 `run_id`，最长有效期 15 分钟、默认单次使用；支持包可绑定 `support_case_id` 并采用更短的内容保留期限。跨人物、跨镜域和跨区域授权均拒绝，管理员角色不能自动扩大令牌范围。
+
+#### 13.4.3 JSON 数据类型与空值规则
+
+诊断 API 使用 `application/json`，字段名为 `snake_case`。机器 Schema 使用 OpenAPI 3.1 / JSON Schema 2020-12。通用类型：
+
+| 语义 | JSON 类型 / 格式 | 规则 |
+| --- | --- | --- |
+| ID | `string` | 必须带契约前缀；不使用裸整数 ID |
+| 时间 | `string`, `format: date-time` | UTC RFC 3339，统一输出 `Z`；数据库可用 `TIMESTAMPTZ` |
+| 时长 | `integer` | 毫秒，字段后缀 `_ms`，必须 `>= 0` |
+| Token / 次数 / 字节 | `integer` | 必须 `>= 0`；不得使用浮点 |
+| 成本 | `integer` + `string` | `cost_minor` 为货币最小单位，`currency` 为大写 ISO 4217；禁止二进制浮点金额 |
+| 比率 / 分数 | `number` | 仅用于置信度、相似度等；Schema 明确范围 |
+| 布尔 | `boolean` | 不使用 `0/1` 或字符串 `"true"` |
+| 枚举 | `string` | 只接受契约登记值；未知新值由客户端按 unknown 分支显示，不能崩溃 |
+| 哈希 | `string` | 小写十六进制或明确 base64url；字段说明算法，如 SHA-256 |
+| 可选未知值 | `null` | Provider 未返回或尚未发生时使用；不得用 `0`、空字符串或 `false` 冒充未知 |
+| 空集合 | `array` / `object` | 已知为空时返回 `[]` / `{}`；字段不适用时用 `null` 或按 Schema 省略，二者不能混用 |
+
+规范规则：
+
+- 必需但当前未知的 usage 字段返回 `null`；已知真实值为 0 时返回 `0`；
+- `cache_hit` 是 `true | false | null`：只有 `cache_read_input_tokens > 0` 时为 `true`，Provider 明确返回 0 时为 `false`，未提供缓存 usage 时为 `null`；
+- `reasoning_tokens` 只保存数量，不保存 reasoning 内容；
+- `arguments_redacted` / `result_redacted` 类型是 JSON object 或 string，由工具 Schema 决定，并必须同时携带 `redaction_status`；
+- `usage_raw_redacted` 是 object，禁止嵌入原始消息、Prompt、工具参数、密钥和 Header；
+- API 不返回数据库 `_json` 后缀字段；
+- 大整数在 JSON 安全整数范围内使用 integer，超过范围的 Provider 原值先规范化为十进制 string 并在扩展字段注明。
+
+标准响应骨架：
+
+```json
+{
+  "run_id": "run_01J...",
+  "diagnostic_level": "detailed",
+  "turns": [
+    {
+      "id": "turn_01J...",
+      "turn_index": 3,
+      "started_at": "2026-09-02T08:00:00.000Z",
+      "ended_at": "2026-09-02T08:00:02.420Z",
+      "model_calls": [
+        {
+          "id": "model_call_01J...",
+          "attempt_index": 0,
+          "provider": "anthropic",
+          "logical_model": "default-chat",
+          "upstream_model": "provider-model-id",
+          "stream": true,
+          "input_tokens": 1240,
+          "output_tokens": 186,
+          "reasoning_tokens": null,
+          "cache_creation_input_tokens": 0,
+          "cache_read_input_tokens": 980,
+          "cache_hit": true,
+          "usage_source": "provider",
+          "latency_ms": 2310,
+          "time_to_first_token_ms": 420,
+          "tool_use_count": 1,
+          "cost_minor": 3,
+          "currency": "USD"
+        }
+      ],
+      "tool_calls": [
+        {
+          "id": "tool_call_01J...",
+          "call_index": 0,
+          "tool_id": "tool_web_search",
+          "status": "completed",
+          "arguments_redacted": {"query": "[REDACTED]"},
+          "redaction_status": "partial",
+          "result_size_bytes": 4210,
+          "latency_ms": 780,
+          "is_error": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### 13.4.4 访问规则
+
+1. 先验证普通登录态，再验证诊断令牌哈希、期限、使用次数、撤销状态、region 和 scope；
+2. 路径中的 `run_id` / `turn_id` 必须与令牌绑定对象一致，不能由调用方扩大；
+3. 用户可为自己的 Run 签发 `summary` 和 `model:usage`；敏感工具视图需要重新认证并逐次确认；
+4. 支持人员只能使用用户主动生成、绑定支持工单的令牌，日常管理员默认不能查看私密原文；
+5. 每次成功或失败访问均写不可缺审计，至少记录 actor、grant、purpose、对象、scope、结果、IP/设备摘要、时间和 trace；
+6. 响应设置 `Cache-Control: no-store, private`、`Pragma: no-cache`，不得进入 CDN、浏览器持久缓存或搜索索引；
+7. 响应按 `diagnostic_level` 脱敏，永不返回 Provider/BYOK/MCP token、Authorization、签名 URL、私箧明文或隐藏 chain-of-thought；
+8. 删除和撤权立即影响诊断查询；授权令牌不能绕过删除墓碑或区域驻留。
+
+#### 13.4.5 诊断错误码
+
+领域错误映射到 §15.1 标准错误码：
+
+| 领域错误 | 场景 | 标准错误 |
+| --- | --- | --- |
+| `diagnostic_token_missing` | 缺少专用请求头 | `permission_denied` |
+| `diagnostic_token_invalid` | 哈希、格式或签名无效 | `permission_denied` |
+| `diagnostic_token_expired` | 已过期 | `permission_denied` |
+| `diagnostic_token_revoked` | 已撤销 | `permission_denied` |
+| `diagnostic_scope_denied` | Scope 或诊断层级不足 | `permission_denied` |
+| `diagnostic_subject_mismatch` | 访问对象与绑定对象不一致 | `not_found` |
+| `diagnostic_region_mismatch` | 跨数据区域读取 | `permission_denied` |
+| `diagnostic_sensitive_confirmation_required` | 需要敏感诊断逐次确认 | `requires_confirmation` |
+
+### 13.5 `skills.status` / `mcp_servers.status` 能力启用状态

 百工能力包与 MCP 服务的启用状态，默认 `enabled`，预留 `disabled` 等扩展。