diff --git a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md index 9c56e465..2a5ccb79 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md +++ b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md @@ -22,7 +22,7 @@ | 短名 | Agent编排 | | 层级 | L1 方向 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-serve-session-aggregate-authority | +| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-serve-session-aggregate-authority; draft-2026-06-25-p0-session-warm-runner-contract | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -66,6 +66,7 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 | RuntimeAssembly | HWLAB 为 runner 准备镜像、profile、资源包、workspace、工具、Secret 和执行参数的装配结果。 | | ResourceBundleRef | 指向 gitbundle、工具、prompt、skill 和 workspaceFiles 的资源装配引用。 | | Backend Profile | AgentRun 中选择具体 Codex-compatible provider/profile 的配置边界。 | +| session execution lane | 将一个用户可见会话内连续 command 映射到同一 AgentRun run、session runner lease 或等价 warm runner channel 的执行通道。 | ## 4. 系统边界和接口 @@ -148,4 +149,6 @@ HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有 Serve/session aggregate authority 要求职责进一步分离：AgentRun 拥有 run、command、runner job、cancel delivery、terminal report 和 execution diagnostic；HWLAB Workbench 拥有用户态 session aggregate、input/command fact、message/part、trace/timing、sealed final response 和 projection diagnostic。AgentRun 应暴露稳定 runId、commandId、event/result id、terminal status、failureKind、cancel/no-op 和 stale/blocked diagnostic，使 Workbench input/command fact 能回绑执行事实；AgentRun 不拥有 Workbench message/final/timing 显示权，也不通过旧 conversation/session 路径覆盖 Workbench read model。 +Agent编排必须为 Workbench 多 turn 提供可验证的 session execution lane。若选择同一 run 多 command 模型，runner 在普通 command 完成后应继续 poll 同一 run 的后续 command，直到 idle timeout、run cancel、lease 冲突或不可恢复失败；若选择跨 run warm runner lease 或 session command channel，AgentRun 必须把 lease/channel identity、handoff、cancel fencing、idle timeout 和诊断状态作为 durable facts 暴露。每个 Workbench turn 都新建独立 run-scoped runner Job 的实现，只能作为 fresh-run diagnostic，不能满足 runner reuse、10x canary 或 120s 性能红线验收。 + Web CaseRun 的 Agent 执行部分同样遵守该合同边界。CaseRun service 可以引用 AgentRun runId、commandId、traceId、terminal status、diff 和 final response，但不得通过 stdout 尾部、partial assistant、runner pod phase 或用户手工 steer 推断 CaseRun 成功。硬件动作、operation result 和 aggregate 仍由硬件池与 HarnessRL 生产，Agent编排只交付可引用的执行事实。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md b/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md index b54ea44e..2f027d14 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md +++ b/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md @@ -19,7 +19,7 @@ | 短名 | HWLAB接入 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-17-r0; PJ2026-0104010803 唯一投影 draft-2026-06-19-p1-agentrun-incremental-cursor | +| 实现引用版本 | draft-2026-06-17-r0; PJ2026-0104010803 唯一投影 draft-2026-06-19-p1-agentrun-incremental-cursor; draft-2026-06-25-p0-session-warm-runner-contract | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -34,6 +34,8 @@ HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文 HWLAB接入不拥有 AgentRun run、command、runner job、lease 或 terminal status 的执行事实。HWLAB 只负责在 admission 阶段生成业务 session/turn/message/trace 标识和 AgentRun 委托请求，并在后续通过 AgentRun durable events/result/diagnosis API 消费执行事实，再交给 WorkbenchProjectionWriter/Finalizer 写入 HWLAB 用户态投影。manager rolling、runner stale、terminal report delayed 或不可恢复 blocker 都必须先在 AgentRun 写侧形成 durable facts 或 diagnostic，HWLAB 不得通过 GET、result polling、trace tail、Web reducer 或人工 resubmit 补造执行状态。 +Workbench 多 turn 接入还必须保持 session execution lane。HWLAB adapter 不得把同一 Workbench session 的连续 prompt、steer、cancel 和 retry 映射成彼此无关的 AgentRun run-scoped runner Job，再用 `sessionPolicy`、thread metadata 或 PVC 复用标称为 runner reuse。若当前 AgentRun 能力只能通过同一 run 多 command 让 runner 继续 poll 后续 command，HWLAB 应复用该 run/session command channel；若采用未来 warm runner lease，也必须把 lease/channel identity 和 command handoff 暴露给 Workbench projection diagnostic。 + ### 2.2 范围内 - HWLAB 业务 dispatcher 创建 AgentRun run、command 和 runner job 的字段映射。 @@ -64,6 +66,8 @@ HWLAB接入不拥有 AgentRun run、command、runner job、lease 或 terminal st | transientEnv | 单次 runner job 的短期 env 上下文，由 AgentRun 转为短期 Secret 投影并脱敏输出。 | | 自然语言单一路由 | `/v1/agent/chat` 中自然语言请求统一进入 AgentRun Code Agent turn，不由 Cloud API 做关键词分流或文本 fallback。 | | AgentRun durable facts | AgentRun 写侧持久化的 run、command、event、runner job、lease、terminal report state、result 和 diagnosis，是 HWLAB 接入消费执行状态的唯一上游事实。 | +| session execution lane | HWLAB Workbench session 到 AgentRun run/session command channel 或 warm runner lease 的稳定映射，用于承载连续 prompt、steer、cancel 和 retry。 | +| warm runner contract | 连续 turn 不重复支付完整 runner Job 冷启动成本的执行合同；同一 session 内后续 command 应由同一 run runner loop、session runner lease 或等价机制承接。 | ## 4. 系统边界和接口 @@ -101,6 +105,8 @@ HWLAB接入应通过 AgentRun 手动调度 API 为已创建的 run/command 显 手动调度只启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn，也不把 Kubernetes Job 删除作为正式取消语义。重复提交必须按 idempotency key 返回既有 job 或结构化失败。 +手动调度入口只能作为创建或恢复 execution lane 的短返回控制面，不能在同一 Workbench session 的每个 turn 上无条件创建新的独立 run-scoped runner Job。若调用方显式请求新 run，响应或 diagnostic 必须能说明这是 fresh run、复用失败、runner lease 不可用还是策略要求；不能把每 turn fresh runner 标记为 reuse。 + ### 6.2 AR-HWLAB-REQ-002 HWLAB 到 AgentRun 字段映射 | 编号 | 短名 | 主责模块 | 关联模块 | @@ -153,6 +159,8 @@ HWLAB接入应使用 AgentRun durable cancel、SessionRef、thread continuation 取消、Steer、retry 和 follow-up 必须绑定明确 conversation/session/turn，不得通过“最新 session”、workspace selected、runner latest 或 trace polling 推断目标。命令输入区的发送、取消和 Steer 状态应来自 TurnSnapshot 与 message projection，而不是来自浏览器本地 pending 状态。 +同一 Workbench session 的 follow-up、steer 和 retry 应优先进入已有 AgentRun run 的后续 command 或已声明的 session runner lease。若必须新建 run/runner Job，HWLAB接入必须把原因写入 durable input/command diagnostic，并让 Workbench CLI trace 视图能看到 fresh-run/fresh-runner 与 warm-runner 失效的边界。`workbench-dsflash-go-tool-call-10x` 这类多 turn 验收不能把每 turn fresh runner 当作通过。 + ### 6.6 AR-HWLAB-REQ-006 自然语言单一路由 | 编号 | 短名 | 主责模块 | 关联模块 | diff --git a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md index d64c2723..7749f98b 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -19,7 +19,7 @@ | 短名 | Web工作台 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority | +| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority; draft-2026-06-25-p0-session-warm-runner-contract | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -94,6 +94,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 显示层本地 now | 浏览器组件为了展示“最近 X 秒前”和运行中“耗时 X 秒”而读取的当前时间；它只能作为直接渲染输入，不能写回 Server State、投影、session/message/turn lifecycle 或诊断事实，也不能通过平滑、滤波、单调 floor、跳变 cap 或二次缓存伪造一个更好看的时间事实。 | | 唯一投影 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的状态链路：AgentRun 执行事实只经 HWLAB projection writer/finalizer 写入 durable Workbench facts，REST、SSE、CLI、fake-server 和 Web 前端只消费该投影。 | | Serve Session Aggregate Authority | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的会话级权威链路；Web 的 prompt、steer、cancel、retry、run-state、message/part、trace/timing 和 final response 只能消费该 aggregate read model。 | +| session execution lane | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的会话执行通道；Web 只能展示其 read model 和 diagnostic，不从 DOM active card 或本地 pending 状态推断是否复用了 runner。 | | sealed final response | 唯一投影 terminal commit 写入的 assistant 主正文、finalResponse、message/turn terminal status 和 sealed 标记；它是主消息区用户结果的唯一权威，不被后续读侧诊断、trace hydration 失败、turn polling 失败或 SSE gap 覆盖。 | | 破坏性投影权 | 删除 session、清空 active session、清空当前消息页、把 composer 改为无 session 或把 session lifecycle 改写为 not-found/archived/deleted 的权力。Web 前端 reducer、selectors、route hydrate、GET/list/detail/messages/SSE consumer 和测试 helper 没有破坏性投影权；只有显式用户 mutation 成功或后端 canonical lifecycle projection 可以改变这些事实。 | | 读侧推理 | Web、API、CLI、fake-server 或测试根据 trace tail、message text、tool event、result cache、session summary、list row、workspace snapshot、localStorage 或 elapsed timeout 推断 lifecycle、terminal、running 或 final response 的行为；Web工作台禁止该模式。 | diff --git a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md index 90d2a32c..4162f5c2 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md +++ b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md @@ -19,7 +19,7 @@ | 短名 | Workbench唯一投影 | | 层级 | L4 专项规格切片 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-24-p1-opencode-message-part-authority; draft-2026-06-25-p0-serve-session-aggregate-authority | +| 实现引用版本 | draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-24-p1-opencode-message-part-authority; draft-2026-06-25-p0-serve-session-aggregate-authority; draft-2026-06-25-p0-session-warm-runner-contract | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | | 关联规格 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md)、[PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | @@ -115,6 +115,8 @@ D601 v0.3 可以在 `hwlab-v03` namespace 内为 `hwlab-workbench-runtime` 使 | CLI trace 视图 | `web-probe analyze` 从采样事实渲染的文字版 trace 视图，包含多 turn 的 `turn-summary` 和单 turn/单 frame 的 `trace-frame` 两层；它用于人工复核自动 finding，不保存新事实，不从 DOM 重新推断。 | | Serve Session Aggregate Authority | Workbench 会话级聚合根，统一接收 prompt admission、steer、cancel、retry、run-state、message/part、trace/timing 和 terminal/final response 的写入序列；它是 Web、REST、SSE、CLI 和 web-probe 可见状态的上游 authority。 | | durable input/command fact | 用户输入或控制命令进入执行前写入的持久事实，至少绑定 `sessionId`、`turnId`、`messageId`、`commandId`、action、target、admittedSeq、status 和 no-op/blocker；它先于 AgentRun dispatch 或 Kubernetes job 创建。 | +| session execution lane | 同一 Workbench session 的受控执行 lane，把连续 prompt、steer、cancel 和 retry 串到同一 AgentRun session/run command channel、warm runner lease 或等价机制；它不能只是 metadata。 | +| warm runner contract | AgentRun/HWLAB 对连续 turn 的低延迟执行合同：已创建的 runner 在同一 session/run lane 内继续 poll 后续 command，或由明确 runner lease/session channel 承接后续 command；每 turn 新建独立 run-scoped runner Job 不能标称为 runner reuse。 | ## 4. 系统边界和接口 @@ -599,6 +601,8 @@ Workbench session 必须是用户可见执行状态的 aggregate root。prompt 同一 session 必须有一条受控 execution lane。wake、interrupt、steer、cancel、retry 和 runner terminal 之间必须按 session aggregate seq 判定新旧；stale wake、late runner event、旧 turn polling、DOM active card、session list summary、last trace row 或浏览器 local state 都不能覆盖更新 turn 的状态。没有 active turn 的 cancel/steer 必须返回结构化 no-op 或 error；已 terminal 的 cancel 必须返回 already-terminal/no-op 或触发 terminal projection catch-up，不能重新打开 sealed turn 或覆盖 terminal facts。 +同一 session execution lane 必须有可审计的 AgentRun 承载机制。优先形态是同一个 AgentRun run 接收连续 command，并让已 claim 的 runner 在 idle timeout 内继续 poll 后续 command；若后续实现选择 session runner lease 或跨 run warm runner channel，也必须暴露稳定 session/channel/lease identity、command handoff、cancel/interrupt fencing 和 terminal diagnostic。仅在 `sessionPolicy`、metadata、thread id 或 PVC 上标记“reuse”，但每个 Workbench turn 都新建独立 run-scoped runner Job，不满足本要求，也不能作为 10x canary 或 120s 性能验收通过证据。 + Message/part 是用户结果的显示权威。assistant final response 只能来自 sealed assistant final/text part，diagnostic、stdout/stderr、transport error、steer/cancel accepted 文案和 analyzer summary 必须分仓展示。trace rows、turn timing、session running、completion row 和 duration 必须从同一 session aggregate/event stream/read model 派生；`trace-frame --trace-id newTrace` 不得显示旧 trace 行。若缺少 order、缺少 terminal 或存在 projection 矛盾，CLI/API/Web 必须暴露 projection blocker 或 warning，而不是读侧补齐。 兼容 `/v1/agent/*`、conversation path、旧 Web route、CLI renderer、SSE 和 fake-server 都只能调用同一个 mutation/read model。保留 wrapper 时，它只能做鉴权、schema 映射和旧字段降级，不拥有第二套 prompt admission、status、final response、timing 或 trace authority。 @@ -616,3 +620,5 @@ web-probe 历史窗口 trace 乱序、完成行非最后、耗时不一致和红 Workbench turn/message/trace 投影 authority 与 CLI trace 视图收敛的架构修复执行 issue 为 [#2079](https://github.com/pikasTech/HWLAB/issues/2079)，正式 20 轮长程采样父 issue 为 [#2072](https://github.com/pikasTech/HWLAB/issues/2072)，运行中 steer 与前 1-5 轮采样子 issue 为 [#2078](https://github.com/pikasTech/HWLAB/issues/2078)。后续实现必须引用 `draft-2026-06-24-p1-opencode-message-part-authority`，并在各阶段子 issue 中说明是否已经消除 final response 误选、turn-summary/trace-frame traceId 误归因、completion row 非最后、duration 不一致、prompt/steer/cancel 边界误判和 analyzer-only 误判。 Workbench serve/session aggregate authority 架构修复执行 issue 为 [#2125](https://github.com/pikasTech/HWLAB/issues/2125)。阶段跟踪必须以子 issue 为准：P0 SPEC-first [#2128](https://github.com/pikasTech/HWLAB/issues/2128)、P1 durable input/command 与 session aggregate seq [#2127](https://github.com/pikasTech/HWLAB/issues/2127)、P2 message/part/turn/trace read model 与 terminal atomic commit [#2126](https://github.com/pikasTech/HWLAB/issues/2126)、P3 prompt/steer/cancel run-state authority [#2129](https://github.com/pikasTech/HWLAB/issues/2129)、P4 REST/SSE/CLI/Web 单源消费与 legacy wrapper 降级 [#2131](https://github.com/pikasTech/HWLAB/issues/2131)、P5 删除 fallback/repair/renderer 补丁路径 [#2130](https://github.com/pikasTech/HWLAB/issues/2130)、P6 fake-server 与 D601/v03 20轮原入口验收 [#2132](https://github.com/pikasTech/HWLAB/issues/2132)。后续实现必须引用 `draft-2026-06-25-p0-serve-session-aggregate-authority`，并在关闭各阶段 issue 时说明 prompt admission、steer/cancel、run-state、message/part、trace/timing、final response 是否已经共享同一 session aggregate authority。 + +dsflash-go 10x canary 超过 120s、同一 Workbench session 连续 turn 创建多个独立 AgentRun runner/job、DOM trace rows 与后端 trace API 不一致的证据 issue 为 [#2171](https://github.com/pikasTech/HWLAB/issues/2171)。后续实现必须同时引用 `draft-2026-06-25-p0-session-warm-runner-contract`，并在 P1/P3/P6 closeout 中证明同一 session 的连续 turn 已进入同一 execution lane 或等价 warm runner/session command channel；若仍出现每 turn 新建 run-scoped runner Job，必须保持验收 red，而不是提高 120s 预算、减少轮数或用 renderer/probe fallback 掩盖。