docs: 固化 Code Agent steer 短连接语义

This commit is contained in:
Codex Agent
2026-06-06 17:38:39 +08:00
parent b9c1a124b0
commit b7d00dc106
4 changed files with 10 additions and 4 deletions
@@ -13,6 +13,7 @@
## 会话和执行边界
- HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authorityAgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identityAgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session,也不要把复用 workspace selection 当作 session state。
- AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令,不创建新的 HWLAB session,也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`,并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收;目标 turn 后续 terminal 状态按原 command/result 判定。
- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段:`tenantId=hwlab``projectId=pikasTech/HWLAB``providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId``metadata.hwlabWorkspaceId``workspaceRef` 子字段保存,不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染,临时处理是修 adapter 的字段归一化并重放最小真实请求,不放宽 AgentRun tenant policy。
- `providerProfile` 由显式 HWLAB session 负责。`client agent session create --provider-profile <profile>` 建立 session 的 provider profile,并映射为 AgentRun `backendProfile`;后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时必须继承该 session 的 `providerProfile`。账号 workspace 的 provider profile 只在 workspace 当前 selected session 与本次目标 session 完全一致时作为 fallback;旧 workspace 状态不得覆盖显式 session。
- 同一 HWLAB session 的 resume 判定看同一个 `sessionId``threadId``providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC,而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job,但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时,才算 session 持久化恢复证据;它不替代 runner reuse window 内复用同一 run/runner 的长期目标。