fix: 保留长任务过程 trace 事件

2026-06-02 21:17:56 +08:00
parent 3018b8a937
commit ce031238f1
4 changed files with 125 additions and 24 deletions
@@ -38,7 +38,7 @@ Backend adapter 的第一阶段实现应吸收 HWLAB v0.2 已验证的 Codex std
 | --- | --- | --- |
 | Codex app-server JSON-RPC stdio | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | 支持 `initialize`、`thread/start`、`thread/resume`、`turn/start`，并处理 app-server client request；未知请求要记录 unsupported error，不能静默等待。 |
 | completed 判定 | `docs/reference/code-agent-chat-readiness.md` | 只有 Codex turn terminal completed 且 assistant reply 可聚合时才输出 completed；assistant delta、item completed、stdout 或 transport close 不能单独完成。 |
-| assistant stream 和 trace | `internal/cloud/code-agent-trace-store.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | assistant delta 只能作为 stream/progress 证据；每个非空 completed `agentMessage` item 必须输出一个 `assistant_message` event，保留 `itemId` 和顺序；`item/agentMessage:started`、`item/agentMessage:completed` 这类 lifecycle 不得额外持久化为 `backend_status`，避免同一消息在 Web/CLI trace 中重复渲染；最终 result reply 必须优先来自最后一个 completed `agentMessage` item，不能把 commentary/progress delta 与 final response 直接串接。event 必须保留 `threadId`、`turnId`、session 摘要和 redacted backend metadata。 |
+| assistant stream 和 trace | `internal/cloud/code-agent-trace-store.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | assistant delta 只能作为 stream/progress 证据；长输出过程中可以输出有界 `assistant_message.source=agent-message-delta-progress` 快照，但 `replyAuthority=false` 且不得参与最终 reply 聚合；每个非空 completed `agentMessage` item 必须输出一个 `assistant_message` event，保留 `itemId` 和顺序；`item/agentMessage:started`、`item/agentMessage:completed` 这类 lifecycle 不得额外持久化为 `backend_status`，避免同一消息在 Web/CLI trace 中重复渲染；最终 result reply 必须优先来自最后一个 completed `agentMessage` item，不能把 commentary/progress delta 与 final response 直接串接。event 必须保留 `threadId`、`turnId`、session 摘要和 redacted backend metadata。 |
 | command/tool output bounded | `docs/reference/code-agent-chat-readiness.md`、`web/hwlab-cloud-web/app-trace.ts` | `tool_call` 和 `command_output` 必须记录状态、摘要、字节数、截断标记；完整大输出只能通过后续 log/artifact 引用。 |
 | provider/profile 隔离 | `internal/cloud/code-agent-contract.ts` | `codex`、`deepseek` 与 `minimax-m3` 共享同一 backend kind，但必须使用 profile-scoped SecretRef、model/base-url/config 和 writable runtime home。 |
 | Secret redaction | `internal/cloud/code-agent-trace-store.ts` | `OPENAI_API_KEY`、auth/config、token、password、kubeconfig、URL credential 不得进入 event、result、log 或 health。 |
@@ -60,7 +60,7 @@ Registry 只表达能力和选择边界，不读取 Secret 值。Manager 负责
 Adapter 输出给 runner 的 event 类型至少包括：

 - `backend_status`：backend 启动、模型/profile、能力和阶段状态，不包含 Secret 值。
- `assistant_message`：模型输出的用户可见 assistant 文本。Codex app-server 的 `item/agentMessage/delta` 只能作为流式过程证据或缺少 completed item 时的兜底；一旦收到 completed `agentMessage` item，adapter 必须为每个非空 completed item 输出一条 `assistant_message`，并用 `itemId`、`messageIndex`、`messageCount`、`replyAuthority` 和 `final` 标明顺序与最终 reply authority。最终 result reply 必须以最后一个 `replyAuthority=true` / `final=true` 的 `assistant_message` 为准，避免把 commentary/status/progress 堆入 final response。
+- `assistant_message`：模型输出的用户可见 assistant 文本。Codex app-server 的 `item/agentMessage/delta` 只能作为流式过程证据或缺少 completed item 时的兜底；adapter 可以为长 delta 输出有界 progress 快照，必须标记 `source=agent-message-delta-progress`、`progress=true`、`replyAuthority=false` 和 `final=false`。一旦收到 completed `agentMessage` item，adapter 必须为每个非空 completed item 输出一条 `assistant_message`，并用 `itemId`、`messageIndex`、`messageCount`、`replyAuthority` 和 `final` 标明顺序与最终 reply authority。最终 result reply 必须以最后一个 `replyAuthority=true` / `final=true` 的 `assistant_message` 为准，避免把 commentary/status/progress 堆入 final response。
 - `tool_call`：工具调用摘要和 redacted 参数。
 - `command_output`：stdout/stderr 或命令输出摘要。
 - `diff`：代码变更摘要或 patch 片段；必须受长度限制。
@@ -69,9 +69,9 @@ Adapter 输出给 runner 的 event 类型至少包括：

 事件必须有上限和分页友好形态。大型日志、完整 stdout 或完整 trace 应进入 logPath 或后续 artifact，不得一次性塞入单个 event 造成输出爆炸。

-Codex app-server 的低价值内部 notification 必须在 AgentRun adapter 层收敛，不得要求 HWLAB Web/CLI 或其他消费侧自行过滤。以下事件默认不作为 durable trace event 持久化：`item/reasoning/textDelta`、纯 `reasoning` item 的 `item/started|item/completed`、非 `commandExecution` item 的通用 `item/started|item/completed`、`thread/tokenUsage/updated`、`account/rateLimits/updated`、普通 `warning` 和 `configWarning`。adapter 可以输出一条有界 `backend_status.phase=codex-app-server-notifications-suppressed` 摘要，只包含总数、`methods: [{ method, count }]` 和 `itemTypes: [{ itemType, count }]`，不包含 reasoning 文本、Secret、token 或 env value。method 和 item type 不得作为 JSON object key 输出，避免 `thread/tokenUsage/updated` 这类协议名被 redaction 误判为敏感 key。真实 `agentMessage`、`commandExecution`、`command_output`、error、terminal 和关键生命周期事件必须继续保留。
+Codex app-server 的低价值内部 notification 必须在 AgentRun adapter 层收敛，不得要求 HWLAB Web/CLI 或其他消费侧自行过滤。以下事件默认不作为 durable trace event 持久化：`item/reasoning/textDelta`、纯 `reasoning` item 的 `item/started|item/completed`、非用户可见工具 item 的通用 `item/started|item/completed`、`thread/tokenUsage/updated`、`account/rateLimits/updated`、普通 `warning` 和 `configWarning`。adapter 可以输出一条有界 `backend_status.phase=codex-app-server-notifications-suppressed` 摘要，只包含总数、`methods: [{ method, count }]` 和 `itemTypes: [{ itemType, count }]`，不包含 reasoning 文本、Secret、token 或 env value。method 和 item type 不得作为 JSON object key 输出，避免 `thread/tokenUsage/updated` 这类协议名被 redaction 误判为敏感 key。真实 `agentMessage`、`commandExecution`、`webSearch`、`command_output`、error、terminal 和关键生命周期事件必须继续保留。

-`commandExecution` 的 `tool_call` event 只能输出面向人和消费侧的扁平字段，例如 `method`、`itemId`、`toolName`、`type`、`command`、`cwd`、`status`、`processId` 和 `valuesPrinted=false`。不得把 Codex app-server 的原始 `item` JSON、`itemPreview` 或嵌套协议摘要写入 `message`、`outputSummary`、`stdoutSummary` 或 payload；命令实际 stdout/stderr 只通过 `command_output` 或 completed `commandExecution` 摘要输出。
+用户可见工具生命周期的 `tool_call` event 只能输出面向人和消费侧的扁平字段，例如 `method`、`itemId`、`toolName`、`type`、`command`、`cwd`、`status`、`processId` 和 `valuesPrinted=false`。当前可见工具类型包括 `commandExecution` 和 `webSearch`；不得把 Codex app-server 的原始 `item` JSON、`itemPreview` 或嵌套协议摘要写入 `message`、`outputSummary`、`stdoutSummary` 或 payload；命令实际 stdout/stderr 只通过 `command_output` 或 completed `commandExecution` 摘要输出。

 ## Failure Mapping