pikasTech-HWLAB/docs/reference/spec-v03-workbench-vue-migration.md

# v0.3 Workbench Vue 迁移语义合同

本文定义 Cloud Workbench 从 React `useWorkbenchStore` 迁移到 Vue/Pinia 时必须保留的 API、store 和 trace 语义。Vue 实现可以复用 Sub2API frontend 的 api/store/composable 分层形态，但不能照搬 Sub2API 的 bearer token 鉴权和通用刷新模型。

## 基线来源

| 来源 | 基线文件 | 可迁移结论 |
|---|---|---|
| HWLAB React Workbench | `web/hwlab-cloud-web/src/state/workbench.ts`、`runner-trace.ts`、`trace-reattach.ts`、`services/api/client.ts`、`types/domain.ts` | 当前语义权威。Vue 迁移必须保持显式 session、inactivity-timeout、trace reattach、result/trace 同源 API 和 HWPOD evidence label。 |
| HWLAB Web 规格 | `docs/reference/spec-v02-hwlab-cloud-web.md` | Code Agent 没有浏览器侧 total-timeout / attempt cap；唯一 abort 信号是 `activityRef` 驱动的 inactivity-timeout。 |
| Sub2API frontend `v0.1.136` | `src/api/client.ts`、`src/stores/auth.ts`、`src/stores/app.ts`、`src/composables/useAutoRefresh.ts`、`src/composables/useClipboard.ts` | 可复用 Composition API Pinia store、独立 api module、toast/clipboard/auto-refresh composable 的组织方式；不可复用 localStorage bearer token 鉴权。 |

## React Workbench 语义提取

| React 模块 | 当前语义 | Vue 迁移归属 |
|---|---|---|
| `services/api/client.ts::fetchJson` / `fetchText` | 同源 `fetch`、`credentials=same-origin`、统一 `ApiResult<T>`、`recordApiTiming`；`activityRef` 每秒重算 idle window，超时错误必须说明 `waitingFor` 和 `lastEventLabel`。 | `src/api/client.ts` 保持 fetch client，不换成 Sub2API axios bearer client。 |
| `services/api/client.ts::api` | 同源代理覆盖 auth bootstrap、live probe、workspace、conversation、Code Agent send/steer/result/cancel、HWPOD node-ops、skills 等端点。 | 拆成 `src/api/workbench.ts`、`src/api/auth.ts`；只拆模块，不改 endpoint path 和 timeout contract。 |
| `state/workbench.ts::initialState` | `providerProfile`、`codeAgentTimeoutMs`、`gatewayShellTimeoutMs` 从 localStorage 读取并 clamp；默认 Code Agent inactivity budget 为 `1_800_000ms`。 | `stores/workbench` state 初始化；持久化 key 保持 `hwlab.workbench.*.v1`。 |
| `state/workbench.ts::hydrate` | 并发读取 `/v1/workbench/workspace` 和 `/v1/agent/conversations`，用 workspace selected conversation 生成 message 列表并记住 projectId。 | `stores/workbench.hydrate()`；首屏可由 `useWorkspaceBootstrap` 提供 workspace 快照，后续再补 conversation list。 |
| `state/workbench.ts::refreshLive` | 每 30s 读取 health/live、health、REST index、adapter、HWPOD specs、HWPOD node-ops、live-builds，并推导 Code Agent availability。 | `stores/workbench.refreshLive()` + `useAutoRefresh`；只能在 workspace 入口启用，性能页不得初始化。 |
| `state/workbench.ts::createSession` / `selectConversation` / `deleteCurrentSession` | session 由用户显式创建、选择、删除；普通 send 不隐式创建 session；select payload 带 `updatedByClient`。 | `stores/workbench` actions；Vue UI 必须先暴露 session 创建/选择入口，再允许普通 turn。 |
| `state/workbench-reducer.ts::composerFromState` | 通过当前 request、running agent message、workspace active trace 推导 composer；running turn 时 submit mode 为 `steer` 且 route 为 `/v1/agent/chat/steer`。 | `stores/workbench` getter `composer`；不要在组件中重复推导。 |
| `state/workbench.ts::submitMessage` | 生成 user/pending message，先 `persistConversation`，再 POST send/steer；submit kickoff 调 `recordActivity()`，POST 使用同一个 `activityRef`；terminal 后 merge trace/result 并再次持久化。 | `stores/workbench.submitMessage()` 调 `useTraceSubscription`；message mutation 和 persistence 保持 store 内聚。 |
| `state/runner-trace.ts::subscribeToTrace` | result 和 trace 两路同源 poll；每次成功 poll 调 `onActivity`；5xx 不刷新 activity 且继续 poll；非 5xx 失败走 infrastructure error；外层 `for(;;)` 没有 total timeout。 | `composables/useTraceSubscription.ts` 的唯一 active polling 入口。 |
| `state/runner-trace.ts::mergeTraceResults` | terminal result 与 trace snapshot 合并；优先使用 finalResponse、terminal assistant event、result text，保留 `agentRun`、events、traceSummary、terminalEvidence。 | `api/workbench` 或 `composables/useTraceSubscription` 附近的纯函数；必须有单元测试。 |
| `state/trace-reattach.ts` | hydrate 后发现 `activeTraceId` 且当前没有 pending，就创建 placeholder 并主动订阅到 terminal；完成/失败都写回 conversation。 | `composables/useTraceReattach.ts` watch `store.activeTraceId` 与 `store.chatPending`。 |
| `components/hwpod/HwpodNodeOpsSidebar.tsx` | evidence label 为 `Contract`、`Specs`、`Spec`、`Node`、`Ops`、per-op label 和 `probe`；status/freshness/blocker 来源必须是同源 `/v1/hwpod-node-ops` 与 `/v1/hwpod/specs?probe=1`。 | Vue HWPOD panel 保留同名 label、`data-hwpod-detail` 语义和 blocker/status 规则。 |

## Sub2API 分层对照

Sub2API `v0.1.136` 对照必须来自真实 frontend 源码，不允许凭记忆复写。当前迁移基线读取过以下文件：

| Sub2API 文件 | HWLAB 吸收结论 |
|---|---|
| `frontend/package.json`、`frontend/vite.config.ts` | Vue 3、Pinia、Vue Router、Vue I18n、Tailwind/PostCSS 作为单一前端栈；HWLAB 删除 React 入口和 React 依赖，不做长期双栈。 |
| `frontend/src/main.ts`、`frontend/src/App.vue` | `main.ts` 只负责安装 Pinia/router/i18n 并挂载 app；`App.vue` 保持全局 shell、route outlet、toast/弹窗类横切组件，不承载业务状态机。 |
| `frontend/src/router/index.ts`、`frontend/src/router/title.ts` | 路由按 public/user/admin 分段懒加载，metadata 表达 auth/admin/title；HWLAB 保留默认首屏 workbench，并保持 Cloud Web 同源入口。 |
| `frontend/src/components/layout/AppLayout.vue`、`AppSidebar.vue`、`AppHeader.vue` | 平台壳拆成 layout 组件和导航数据；HWLAB 采用同类分层，但导航语义改为 Workbench、Code Agent、HWPOD、Access、Provider。 |
| `frontend/src/components/common/NavigationProgress.vue`、`StatusBadge.vue`、`Skeleton.vue`、`EmptyState.vue` | common 组件只承载视觉/反馈原语，可复用为 HWLAB 的状态标记、加载态、空态、导航进度。 |
| `frontend/src/views/user/DashboardView.vue`、`frontend/src/views/admin/DashboardView.vue` | user/admin view 只组合 layout、common 和业务 store，不把 API fetch 散落到 app shell；HWLAB 的 workbench/dashboard/admin 页面遵循同样边界。 |
| `frontend/src/i18n/index.ts`、`frontend/src/style.css`、`frontend/tailwind.config.js` | i18n 初始化、Tailwind base/components/utilities、颜色和字体 token 集中管理；HWLAB 保留自己的文案和 Web session 约束，不照搬 Sub2API token/Secret/刷新策略。 |

| Sub2API 形态 | 可吸收部分 | HWLAB 必须改写部分 |
|---|---|---|
| `api/client.ts` axios instance、request/response interceptor、统一 unwrap `{ code, data }` | api client 是独立模块，业务 endpoint 放在 `src/api/*.ts`；请求取消保持原错误，便于调用方忽略。 | HWLAB 不使用 localStorage `auth_token`、`refresh_token` 或 401 token refresh queue；保留 same-origin cookie session、`ApiResult<T>` 和 `activityRef` inactivity-timeout。 |
| `stores/auth.ts` Composition API Pinia：`ref` state、`computed` getter、actions、定时器 cleanup | auth store 的组织方式、启动时 `checkAuth/bootstrap`、loading/error state 可复用。 | HWLAB `stores/auth` 只消费 `/auth/bootstrap`、`/auth/session`、`/auth/login`、`/auth/logout`；不得持久化 bearer token 或引入 Sub2API refresh token。 |
| `stores/app.ts` toast、global loading、cached settings | toast/loading 与 `useClipboard` 依赖 app store 的方式可复用。 | Workbench live refresh、workspace hydrate 不放进 app store；app store 只保留 UI 横切状态。 |
| `composables/useAutoRefresh.ts` localStorage 保存 enabled/interval/countdown/fetching，组件卸载清 timer | 可作为 Workbench live refresh 和 HWPOD panel refresh 控件基础。 | 不得用 auto-refresh 替代 Code Agent trace subscription；trace 仍由 `useTraceSubscription` 无限 poll 并使用 `activityRef`。 |
| `composables/useClipboard.ts` Clipboard API + textarea fallback + toast | 可直接迁移为工作台复制 trace/result/session id 的通用 composable。 | 成功/失败文案走 HWLAB app store/i18n；不要把复制行为和业务状态 mutation 耦合。 |

## Vue Pinia / Composable 目标映射

| 目标文件 | 责任边界 | 必须暴露的接口 |
|---|---|---|
| `src/api/client.ts` | fetch 基础设施、`ApiResult<T>`、`ActivityRef`、inactivity-timeout、RUM timing。 | `fetchJson<T>(path, options)`、`fetchText(path, options)`、`type ActivityRef`、`type ActivityRefSource`。 |
| `src/api/workbench.ts` | Workbench 业务 endpoint wrapper；只表达 HTTP path 和 timeout，不持有 UI state。 | `workspace`、`updateWorkspace`、`selectConversation`、`conversations`、`saveConversation`、`deleteConversation`、`sendAgentMessage`、`steerAgentMessage`、`getAgentChatResult`、`cancelAgentMessage`、`liveSurface`、`hwpodSpecs`、`hwpodNodeOpsHealth`。 |
| `src/api/auth.ts` | Web session bootstrap/login/logout wrapper。 | `bootstrap()`、`session()`、`login(username,password)`、`logout()`；返回同源 session 状态。 |
| `src/stores/auth.ts` | Web session 状态。 | state: `authenticated`、`user`、`actor`、`expiresAt`、`loading`、`error`; actions: `bootstrap`、`login`、`logout`; getter: `isAuthenticated`。 |
| `src/stores/workbench.ts` | Workbench durable state、derived composer、session lifecycle、message mutation、conversation persistence。 | state: `workspace`、`conversations`、`messages`、`providerProfile`、timeouts、`live`、`codeAgentAvailability`、`chatPending`、`currentRequest`、`lastActivityAt`; getters: `activeProjectId`、`activeConversationId`、`sessionTabs`、`composer`、`activeTraceId`; actions: `hydrate`、`refreshLive`、`createSession`、`selectConversation`、`deleteCurrentSession`、`submitMessage`、`cancelAgentMessage`、`retryAgentMessage`、`replayAgentTrace`、`recordActivity`、timeout/profile setters。 |
| `src/composables/useTraceSubscription.ts` | active trace polling lifecycle；替代 React `subscribeToTrace`。 | `start(config)`、`stop()`、`running`; config 包含 `traceId`、`projectId`、`initial`、`inactivityTimeoutMs`、`onActivity`、`onSnapshot`、`onComplete`、`onInfrastructureError`。 |
| `src/composables/useTraceReattach.ts` | watch store active trace and reattach after hydrate/refresh。 | 自动 watch `enabled`、`store.activeTraceId`、`store.chatPending`; 创建 placeholder、订阅、完成/失败后 persist。 |
| `src/composables/useWorkspaceBootstrap.ts` | 首屏 bootstrap 合并 auth/workspace，避免重复请求。 | `bootstrapWorkspace(projectId)` 返回 auth state + workspace snapshot；必须消费 `/auth/workspace-bootstrap?projectId=...`。 |
| `src/composables/useAutoRefresh.ts` | UI refresh control for live surface only。 | 复用 Sub2API `enabled`、`intervalSeconds`、`countdown`、`fetching`、`setEnabled`、`setInterval`；`shouldPause` 默认在 hidden/performance route 时暂停。 |
| `src/composables/useClipboard.ts` | 文本复制和 toast。 | `copyToClipboard(text, successMessage?)`、`copied`。 |

## Trace / Result 不变量

- `submitMessage` 和 `useTraceReattach` 必须共享 `useTraceSubscription`，不得拆成 submit-only 和 hydrate-only 两套 polling。
- `getAgentChatResult(resultUrl, inactivityTimeoutMs, activityRef)` 的 timeout 入参不随 wall-clock 缩小；外层循环没有累计耗时上限、attempt cap 或 `timeoutMs * N` 兜底。
- 每一次成功 result poll 或 trace poll 都调用 `store.recordActivity()`；5xx retry 不调用，非 5xx 业务失败进入 infrastructure error。
- terminal 完成前至少尝试合并 trace snapshot；final assistant text 优先级保持 `finalResponse`、terminal assistant event、result text、普通 assistant event。
- steer POST 如果 timeout/ECONNRESET 但目标 trace 仍 running，Vue store 必须释放本次 submit lock、保留原 agent message running/steerable，不得把原 turn 标 failed。
- `session_failed`、`thread-resume-failed`、provider continuation 失效、运行面中断或用户取消后，不得自动滚动新 session；下一步必须由用户显式创建或选择 session。

## 迁移顺序

1. 先迁 `types/domain.ts`、trace merge 纯函数和 `api/client.ts`，用无浏览器单测锁住 `activityRef` inactivity 行为。
2. 再迁 `api/workbench.ts` 与 `stores/auth.ts`，确认同源 session contract 未引入 bearer token。
3. 迁 `useTraceSubscription` 和 `useTraceReattach`，用 fake API 断言无 total-timeout、成功 poll 刷新 activity、5xx 不刷新 activity、terminal result 合并 trace。
4. 迁 `stores/workbench.ts`，把 React reducer 的 action 语义变成 Pinia action/getter；组件只读 getter 和调 action。
5. 最后迁 UI 组件，HWPOD、trace panel、session sidebar 和 composer 只消费 store/composable，不内联业务推导。

## 验证要求

- 源码层：Vue 迁移 PR 至少覆盖 `api/client` inactivity、`useTraceSubscription` polling、`stores/workbench.composer`、`useTraceReattach` placeholder/terminal persistence、HWPOD label mapping。
- 静态检查：保留 `bun run --cwd web/hwlab-cloud-web check` 或 Vue 等价入口；不得恢复旧 quick prompt、旧 layout smoke 或与当前契约无关的门禁。
- 同路径验收：显式创建或选择 Code Agent session 后，通过 Web 同源 path 提交 turn，`result/trace --render web` 使用同一 trace row；未选择 session 的普通 send 必须返回 `session_required`。
- HWPOD 验收：Vue 面板必须从 `/v1/hwpod-node-ops` 与 `/v1/hwpod/specs?probe=1` 显示 status/freshness/blocker，不得用 fixture 或 blocked fallback 声称真实硬件 DEV-LIVE。