diff --git a/docs/reference/spec-v01-agentrun-mgr.md b/docs/reference/spec-v01-agentrun-mgr.md index 4bd1f71..cfdfe95 100644 --- a/docs/reference/spec-v01-agentrun-mgr.md +++ b/docs/reference/spec-v01-agentrun-mgr.md @@ -158,9 +158,12 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB | `status` | run/command 当前聚合状态,只能由 command state 和 terminal_status 推导。 | | `terminalStatus` | `completed`、`failed`、`blocked` 或 `cancelled`;没有 terminal event 时为 `null` 或 equivalent running 状态。 | | `completed` / `terminalSource` | `completed=true` 只能来自 terminal completed;`terminalSource` 标明来自 `terminal_status` event、run record 或暂无 terminal。 | -| `reply` | 从 `assistant_message` 聚合的最终用户可见文本;若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`,必须取最后一条作为 reply;没有这些标记时才按 legacy chunk 聚合。没有 terminal completed 时不得伪造 completed reply。 | +| `reply` / `finalResponse` | 从 `assistant_message` 聚合的最终用户可见文本;若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`,必须取最后一条作为 authoritative reply。没有 authoritative final 时,result 可以 fallback 到 terminal 前最后一条非空 assistant 文本,但必须在 `finalResponse` 暴露 `seq`、`source`、`replyAuthority`、`final`、`textTruncated` 和 `outputTruncated`,让消费侧知道它是可见性 fallback,不是 backend final authority。没有 terminal completed 时不得伪造 completed reply。 | +| `finalAssistantSeq` / `finalAssistantSource` | 必须指向 result 本次选中的 assistant event;长 trace、steer 或 progress snapshot 场景不能让早期 assistant row 继续冒充最终摘要。 | +| `finalAssistantTextTruncated` / `finalAssistantOutputTruncated` | 必须原样暴露被选中 assistant event 的截断标记;被选中的最终摘要截断时,消费侧应继续读 events 或 trace,而不是把截断隐藏成完整 final。 | | `failureKind` / `blocker` | 结构化失败分类和摘要;必须 redacted。 | -| `lastSeq` / `eventCount` | 支持调用方增量轮询和 result/trace reconciliation。 | +| `lastSeq` / `eventCount` / `eventsCapped` / `nextAfterSeq` | 支持调用方增量轮询和 result/trace reconciliation。result 聚合必须分页读取 events,不能只读取第一页后静默返回过期 `reply` 或 `lastSeq`;如果达到服务端聚合上限,必须 `eventsCapped=true` 并给出 continuation cursor。 | +| `scopedLastSeq` / `scopedEventCount` | 指定 `commandId` 时暴露 command-scoped 聚合范围,方便上层区分 run 全局 cursor 和当前 command 事件范围。 | | `runId` / `commandId` / `attemptId` | 支持调用方持久关联和问题定位。 | | `artifactSummary` | 第一阶段只放有界摘要、字节数、截断标记和必要引用;不内嵌大 stdout/stderr。 | | `toolCallSummary` | 输出有界、脱敏的 tool call 状态摘要,至少包含 `count`、`statusCounts`、`exitCodeCounts` 和最近若干条 `items` 的 `method/toolName/type/status/exitCode/command`。消费侧必须用它区分 AgentRun command terminal、agent 内部工具执行和后置诊断,不得用单一 `hwpodExitCode` 覆盖 AgentRun 成功终态。 | @@ -169,6 +172,8 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB 当 `commandId` 已指定,result envelope 必须只聚合该 command 的 assistant/output/error/terminal 事件;同一 run 的其他 command reply 不能串入当前 command result。未指定 `commandId` 时可默认选择最新 command。 +长 trace / steer 场景的验收标准是:raw events 已有 terminal seq 时,`commands result` 的 `lastSeq` 与 `eventCount` 必须覆盖同一终态事件范围,`finalAssistantSeq` 必须指向 terminal 前最后一条可用 assistant 或 authoritative final,且 silent first-page truncation 一律视为 result 合同失败。 + ## 测试规格 ### T1 Manager health/readiness diff --git a/docs/reference/spec-v01-backend-adapter.md b/docs/reference/spec-v01-backend-adapter.md index a05243b..0511b6f 100644 --- a/docs/reference/spec-v01-backend-adapter.md +++ b/docs/reference/spec-v01-backend-adapter.md @@ -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 证据;长输出过程中可以输出有界 `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。 | +| 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`,不能作为 authoritative final;每个非空 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 直接串接。若 provider 未产生 completed/final assistant,manager result 的可见性 fallback 与 `finalResponse` 标记规则以 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md#result-envelope) 为准。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` 与 `dsflash-go` 共享同一 backend kind,但必须使用 profile-scoped SecretRef、model/base-url/config/model catalog 和 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。 | @@ -61,7 +61,7 @@ Registry 只表达能力和选择边界,不读取 Secret 值。Manager 负责 Adapter 输出给 runner 的 event 类型至少包括: - `backend_status`:backend 启动、模型/profile、能力和阶段状态,不包含 Secret 值。 -- `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。 +- `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 堆入 authoritative final response;无 authoritative final 时的 manager fallback 必须显式暴露 `finalResponse.source`、`finalResponse.seq` 和截断标记。 - `tool_call`:工具调用摘要和 redacted 参数。 - `command_output`:stdout/stderr 或命令输出摘要。 - `diff`:代码变更摘要或 patch 片段;必须受长度限制。 diff --git a/docs/reference/spec-v01-hwlab-manual-dispatch.md b/docs/reference/spec-v01-hwlab-manual-dispatch.md index 642a424..4f53ba3 100644 --- a/docs/reference/spec-v01-hwlab-manual-dispatch.md +++ b/docs/reference/spec-v01-hwlab-manual-dispatch.md @@ -112,7 +112,7 @@ AgentRun 标准 events 必须稳定到足以被 HWLAB 转换: - `error`:`failureKind`、message、retryable、provider/infra/backend 分类和 redacted details。 - `terminal_status`:`completed`、`failed`、`blocked` 或 `cancelled`,是 completed 的唯一终态来源。 -面向 HWLAB 的 result envelope 至少应能回答:`status`、`terminalStatus`、`reply`、`failureKind`、`blocker`、`lastSeq`、`eventCount`、`artifactSummary`、`runId`、`commandId` 和 `attemptId`。partial assistant 文本、transport close、idle timeout 或 stdout 存在都不能单独升级为 `completed`。 +面向 HWLAB 的 result envelope 权威规则见 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md#result-envelope)。HWLAB 至少应消费 `status`、`terminalStatus`、`reply/finalResponse`、`failureKind`、`blocker`、`lastSeq`、`eventCount`、`eventsCapped`、`nextAfterSeq`、`finalAssistantSeq`、`artifactSummary`、`runId`、`commandId` 和 `attemptId`。partial assistant 文本、transport close、idle timeout 或 stdout 存在都不能单独升级为 `completed`;当 `eventsCapped=true` 或 final assistant 标记截断时,HWLAB 应继续读取 AgentRun events/trace,而不是把当前摘要当作完整归档。 command terminal 与 run terminal 必须分离。普通 turn completed 只终结对应 command,并更新 SessionRef/thread 摘要;同一 run 保持可继续接收 command,已启动 runner Job 在 idle timeout 内继续 poll。只有显式 run cancel、runner 级不可恢复失败或未来 scheduler/retention 策略要求时,run 才进入 terminal。