跳转至
  • frontend_vue3/src/types/link-error.ts(全新)
  • frontend_vue3/src/stores/linkStore.ts(扩 errors[] / validate / clearErrors / subscribeBackendErrors)
  • frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(数据绑定 · 高亮+跳转交互)
  • frontend_vue3/src/composables/useLinkErrorWS.ts(全新 · 订阅 error_event WS 帧)
  • frontend_vue3/tests/stores/linkStore-errors.test.ts(新增)
  • frontend_vue3/tests/components/BottomProblems.test.ts(新增) occupies: [P1.K-link-store(写), P1.K-bottom-panel(写), P1.K-types(写)] adr: docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md ref_section: §2.2 链路错误检查机制 + §4.1 fork P1.U-link-error-check derived_from: ADR-AIOS-08 created: 2026-05-30 last_modified: 2026-05-30 15:37 dispatched_at: 2026-05-30 09:28 estimated: 1.5d unblocks:
  • 验证 ADR-08 §2.2 链路错误闭环(用户原话场景"模块未连接没有错误显示")
  • ADR-08 §3.2 边界铁律 #4(warning/info 不阻断 audio path)前端验证 related_zombie:
  • P0.U-meter-types-v3(9fc31c4 · 同部门前端 · types 扩展模式参考)
  • P0.U-right-inspector-framework(77b7a50 · linkStore 扩展模式参考) related_dispatched:
  • P5.U-error-channel(同 ADR-08 §2.2 后端配套 · 提供 error_event WS 扩展 7 类码 · 本任务可先按 ADR contract 跑 mock 后切真接口)
  • P0.U-measurement-rms-fft-phase(ADR-12 #5 · 前端不同 stage · 文件正交)
  • P3.U-autotune-phase1-measure-v2(ADR-11 fork 1 v2 · 前端 stages/xitune/* · 文件正交)

P1.UA8-link-error-check · 链路错误前端 UI(ADR-AIOS-08 §2.2 fork · 前端配套)

Worker:TBD(用户分配 · isolation: file · 主仓 04_development/ 任一空闲前端 worker)· 部门:前端 (frontend_vue3) 预计:1.5d · 优先级:P1 · 状态:dispatched 隔离:🧵 文件隔离(stages/xilink/bottom/BottomProblems.vue + linkStore.ts errors[] 字段 + types/link-error.ts · 与 ADR-12 stages/xitest/ + ADR-11 stages/xitune/ 完全正交)

🔍 触发与解锁链

触发 状态 影响
ADR-AIOS-08 accepted v1.1 ✅ 2026-05-29 17:25 10 fork 启动 · 用户 09:23 拍板 start 三前端 fork
.clinerules v1.4 §任务隔离类型分配准则 ✅ 2026-05-30 09:25 本 fork 标 isolation: file · 不绑定 worker(用户拍板分配)
用户拍板方向 A 就地扩展 ✅ 2026-05-30 09:00 "zhujian" 后端 P5.U-error-channel 不新建 /ws/errors · 复用 error_event 形态
P5.U-error-channel(同期派) 🟢 dispatched 后端扩展 error_event 7 类码 · 前端先按 ADR §2.2 contract 跑 mock · 后切真接口

→ 跨栈独立(纯前端) · 不修改 contract-v1.0(已 frozen) · 与 ADR-12 / ADR-11 前端 fork 文件正交 · 同 worktree 同 branch 并行 OK。

任务定义(基于 ADR-AIOS-08 §2.2)

按 ADR-08 §2.2 链路错误检查机制 · 实装前端 UI 闭环:types/link-error.ts 7 类码 schema + linkStore.errors[] 状态管理 + BottomProblems.vue 数据绑定 + 高亮跳转交互 + 订阅后端 error_event WS 扩展帧。

后端 P5.U-error-channel 同期派(0.5d)· 本任务不强等其 zombie:先按 ADR §2.2 schema 跑 mock 帧 · 后端 zombie 后切真接口零改动(WS schema 已对齐)。

完整 prompt(直接复制粘贴 worker 终端)

[U-thread]   P1.UA8-link-error-check(alias: P1.U-link-error-check)
[部门]       前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies]   P1.K-link-store(写 · linkStore.ts errors[] / validate / clearErrors / subscribeBackendErrors) + P1.K-bottom-panel(写 · BottomProblems.vue 数据绑定) + P1.K-types(写 · types/link-error.ts 全新)
[隔离]       🧵 文件隔离(.clinerules v1.4 §任务隔离类型分配准则)· 仅写:
             - frontend_vue3/src/types/link-error.ts(全新)
             - frontend_vue3/src/stores/linkStore.ts(扩展 · 现有逻辑零回归)
             - frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(数据绑定 + 交互 · 现有壳已 mount)
             - frontend_vue3/src/composables/useLinkErrorWS.ts(全新)
             - frontend_vue3/tests/* 新增
             严禁动 stages/xitest/* (#5/#6/#7) · stages/xitune/*(ADR-11) · stages/xilink/drawers/*(本 ADR 其他前端 fork)
[优先级]     P1 · 1.5d · ADR-08 §2.2 前端配套 · 与 P5.U-error-channel(后端)同期跑 · 文件正交于 ADR-12/ADR-11 前端 fork
[ADR]        d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md(必读 §2.2 + §3.2 边界铁律 #4 + §4.1 fork P1.U-link-error-check)
[业务行为契约引用] ADR-AIOS-08 §2.2 链路错误检查机制 · 7 类错误码 + LinkError 8 字段 + BottomProblems 高亮+跳转交互
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md(主 ADR · §2.2 必读 + §3.2 边界铁律 #4)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/active/P5.U-error-channel.md(后端配套 prompt · 同期派 · WS schema 真值源)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(壳已存在 · 本任务填实数据绑定 + 交互)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stores/linkStore.ts(1768 行 · 现有链路状态管理 · 本任务扩 errors[] 字段不破坏现有 API)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xilink/(看现有 stage 结构 · 高亮 module + portId 用现有 hover/focus 机制)
  - 同部门标本(强制 read · 4 维度对齐):d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/active/P0.U-measurement-rms-fft-phase.md(同部门前端 · ADR-12 fork · frontmatter + 8 段格式参考)
  - contract-v1.0(已 frozen · 不改):d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/contracts/protocol-v1.md(本任务走 error_event WS 扩展 · 不入 v1)

【背景】
ADR-AIOS-08 accepted v1.1(2026-05-29 17:25)· 议题② 链路错误检查机制:用户原话"链路检错机制不健全 · 当前链路当有模块没有连接等错误状态的情况下没有错误检查机制 · 底部 tab 的错误窗口也不会有 log 显示"。

🚨 **真值核查发现**:`stages/xilink/bottom/BottomProblems.vue` 壳已存在但无逻辑 · `linkStore.ts` 1768 行无 errors[] 字段。本任务实装数据闭环。

后端 P5.U-error-channel(同期派)在用户拍板"方向 A 就地扩展"下:
- ✅ 不新建 /ws/errors channel · 复用现有 `error_event` WS 形态(MetricsAggregator.cs 154-165 行已实装)
- ✅ JSON 形态扩展 4 字段:`severity` / `moduleId?` / `portId?` / `timestamp` / `source`(向后兼容 · 旧 type/level/code/message 保留)
- ✅ 7 类链路错误码:MODULE_NOT_CONNECTED / MODULE_PORT_MISMATCH / MODULE_PARAM_MISSING / CHAIN_CYCLE_DETECTED / CHAIN_ORPHAN_NODE / RUNTIME_PLATFORM_MISMATCH / SUBGRAPH_INTERFACE_INVALID

**本任务执行策略**(不强等后端 zombie):
- Phase A:按 ADR §2.2 schema 实装 types + linkStore + BottomProblems · 跑 mock 帧(useLinkErrorWS 内置 dev mock)
- Phase B:后端 P5.U-error-channel zombie 后 · 切真 WS 订阅(改 useLinkErrorWS 一处 · 其他零改动)

【执行步骤】

Step 1 · read 已有基础(只读 · 必做)
- read ADR-AIOS-08 §2.2 全文(含 7 类码 enum + LinkError 8 字段 + BottomProblems 数据绑定描述 + 高亮跳转交互)
- read 同期 P5.U-error-channel.md(看后端 JSON schema 真值源 · 字段名/单位对齐)
- read frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue 当前壳代码
- read frontend_vue3/src/stores/linkStore.ts(1768 行 · 找现有 module/edge 索引方式 · errors[] 字段如何挂入 state)
- read frontend_vue3/src/stages/xilink/(看现有 module 节点 hover/focus 高亮机制 · 复用)
- read 标本 prompts/active/P0.U-measurement-rms-fft-phase.md(同部门前端 frontmatter + 8 段格式)

Step 2 · 新建 frontend_vue3/src/types/link-error.ts(全新 · 与后端 LinkError record 字段一对一)
- export type LinkErrorCode(7 类 · 字符串 union 类型 · 与 ADR §2.2 + 后端 enum 完全一致)
- export type LinkErrorSeverity = 'error' | 'warning' | 'info'
- export type LinkErrorSource = 'frontend' | 'backend' | 'dsp'
- export interface LinkError {
    code: LinkErrorCode
    severity: LinkErrorSeverity
    message: string                  // 本地化键(中文显示)
    moduleId?: string                // 错误源模块
    portId?: string                  // 错误源端口
    timestamp: number                // ms epoch
    source: LinkErrorSource
    // 兼容字段(后端 JSON 仍带 level · 前端不读 · 保留兼容)
    level?: LinkErrorSeverity
  }

Step 3 · 扩展 frontend_vue3/src/stores/linkStore.ts(零回归 · 仅加新字段)
- state 加:errors: LinkError[](默认 [])
- actions 加(沿用 pinia 风格):
  · validate(): LinkError[] — 触发本地全链路校验(本期 MVP 仅检测 MODULE_NOT_CONNECTED · 其他码留 mock 推送 / 后端推送)
  · clearErrors(): void — 清空(链路修改时自动调 · 加监听 modules/edges watch)
  · clearErrorsByModule(moduleId: string): void — 模块删除时清理对应错误
  · pushError(err: LinkError): void — 单条推入(WS 订阅或本地 validate 调用)
  · pushErrors(errs: LinkError[]): void — 批量推入
  · subscribeBackendErrors(): () => void — 订阅 useLinkErrorWS · 返回 unsubscribe
- getters 加:
  · errorsBySeverity:Map<severity, LinkError[]>(error/warning/info 三栏)
  · errorsByModule:Map<moduleId, LinkError[]>(画布高亮用)
  · errorCountTotal: number
- ❌ 不修改现有 modules/edges/serialization 等 1768 行任何业务逻辑

Step 4 · 新建 frontend_vue3/src/composables/useLinkErrorWS.ts(订阅 + mock 双模式)
- 接收 ws client 实例(复用现有 ws 单例)
- onMessage 过滤 type === 'error_event' 的帧 · 解析 JSON · 转 LinkError(优先 severity · 兜底 level)
- 调 linkStore.pushError(err)
- dev/test 环境下提供 `__mockPushError(err)` 全局 helper(给 vitest 注入测试帧)
- 返回 { subscribe(), unsubscribe(), __mockPushError }

Step 5 · 实装 frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(数据绑定 + 交互)
- 从 linkStore.errorsBySeverity 读取 · 三栏分组渲染(error/warning/info)
- 每行显示:severity icon + message + moduleId(若有)+ portId(若有)+ timestamp(相对时间 "5s ago")
- 点击错误项 → emit('focus-module', { moduleId, portId }) → 父级监听 → linkStore 调画布高亮(复用现有 hover/focus 机制 · 不重新设计)
- 双击错误项 → emit('jump-to-property', { moduleId }) → 跳转到该 module 的 PropertyPanel
- 错误为空时显示"链路无错误 · 实时监控中"占位
- 响应式 · 不阻塞主线程(virtualScroll 若条目 > 100)

Step 6 · 单元测试 + e2e mock 真值
- 新增 tests/stores/linkStore-errors.test.ts(>= 6 case:pushError 单条 + pushErrors 批量 + clearErrors + clearErrorsByModule + validate MODULE_NOT_CONNECTED + getters errorsBySeverity 分组)
- 新增 tests/components/BottomProblems.test.ts(>= 4 case:渲染三栏 + 点击 emit focus-module + 双击 emit jump-to-property + 空状态占位)
- 新增 tests/composables/useLinkErrorWS.test.ts(>= 3 case:订阅 + 解析 8 字段帧 + level/severity 双名兜底)
- 至少 13 个新 case
- typecheck + build + test:unit 基线 356/3 → 目标 ≥ 369/3(+13 用例)

Step 7 · 端到端真值(.clinerules v1.8 §业务行为契约必填段)
- vitest 真值脚本:__mockPushError 注入 MODULE_NOT_CONNECTED 帧(moduleId='eq.high', portId='in')→ 断言 BottomProblems 显示 1 条 warning · 点击后 emit focus-module 含正确字段
- 注入 7 类码各 1 条 → 断言三栏分组正确

Step 8 · Commit + push
- git status / git pull origin xistudio --no-rebase / git add 隔离文件清单
- 三元组 trailer 必须含 [files=...] 列出全部修改文件路径(供后续 fork 派发时核查文件正交性)
- git push origin xistudio

【验收】

形式合规:
- npm run typecheck → ✓ exit 0
- npm run build → ✓ 零错误
- npm run test:unit → ≥ 369/3(基线 +13 用例)
- 6-9 文件落地(types ×1 + stores ×1 改 + composables ×1 + components ×1 改 + tests ×3)

业务行为契约自查清单(ADR §2.2):
- [ ] ① 7 类错误码 enum 与后端完全一致(字符串值匹配)
- [ ] ② LinkError 8 字段(含 severity/level 双名兼容)
- [ ] ③ linkStore.errors[] 实装 + 5 actions(validate/clearErrors/clearErrorsByModule/pushError/pushErrors)
- [ ] ④ BottomProblems 三栏分组(error/warning/info)
- [ ] ⑤ 高亮+跳转交互(focus-module / jump-to-property emit)
- [ ] ⑥ 空状态占位 + 响应式渲染
- [ ] ⑦ ADR §3.2 边界铁律 #4 验证:warning/info 错误不阻断 audio path(本任务前端只显示 · 不调 audio engine 任何 stop/suspend)
- [ ] ⑧ Phase A mock 跑通后 · ① 输入输出 schema 与 Phase B 真接口零改动切换(留 useLinkErrorWS 切换点 TODO 注释)

【commit】
subject:`feat(P1.UA8-link-error-check): types/link-error + linkStore.errors[] + BottomProblems data binding · ADR-08 §2.2 frontend`

trailer(必须精确):
[step=8/8] [pid=P1] [uid=UA8-link-error-check] [occupies=P1.K-link-store+P1.K-bottom-panel+P1.K-types]
[files=frontend_vue3/src/types/link-error.ts, frontend_vue3/src/stores/linkStore.ts, frontend_vue3/src/composables/useLinkErrorWS.ts, frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue, frontend_vue3/tests/stores/linkStore-errors.test.ts, frontend_vue3/tests/components/BottomProblems.test.ts, frontend_vue3/tests/composables/useLinkErrorWS.test.ts]
[ipc=ws/error_event(consumer · 8-fields)]
[isolation] file(同 worktree 同 branch · 文件正交于 ADR-12/ADR-11 前端 fork)
[derived_from] ADR-AIOS-08 §2.2 fork

【禁止】
1. ❌ 不动 stages/xitest/*(ADR-12 #5/#6/#7 派发中 · 必须文件正交)
2. ❌ 不动 stages/xitune/*(ADR-11 fork 1 v2 派发中)
3. ❌ 不动 stages/xilink/drawers/*(留本 ADR 其他前端 fork:dock-cleanup / perf-monitor / runtime-selector / subgraph-canvas)
4. ❌ 不动 linkStore.ts 1768 行现有业务逻辑(modules/edges/serialization 等 · 仅 read · 仅加新字段+actions)
5. ❌ 不嵌入完整 Vue SFC 骨架(.clinerules v1.6 §prompt 内容硬约束)· worker 自决具体实现风格
6. ❌ 不绑定 worker(本 prompt frontmatter worker: TBD · isolation: file · 用户分配 worker)
7. ❌ 不新建 /ws/errors WS 订阅 channel(后端 P5.U-error-channel 已 freeze 用 error_event 复用)
8. ❌ 不验"typecheck 全绿就 commit"——必须按 ADR §2.2 8 项契约 + e2e mock 真值脚本
9. ❌ 不强等 P5.U-error-channel zombie 才开工(Phase A mock 先跑 · Phase B 切真接口零改动 · useLinkErrorWS 内置 mock)

解锁链(本任务 zombie 后)

  • ✅ ADR-08 §2.2 前端闭环验证(用户原话场景"模块未连接错误显示")
  • ✅ ADR-08 §3.2 边界铁律 #4 验证(warning/info 不阻断 audio path)
  • ✅ Phase B 切真接口零改动(后端 P5.U-error-channel zombie 后 · useLinkErrorWS 切一处 · 其他不动)
  • ✅ ADR-08 §2.2 前后端联动测试基线(给 K2-protocol-v2 起草提供 LinkError 实测数据)

风险评估

风险 缓解
⚠️ linkStore 1768 行扩展引起回归 本任务零修改现有业务逻辑 · 仅加新字段+actions · 现有测试套件全跑保证零回归
⚠️ Phase A mock 帧 schema 与 Phase B 后端真帧不一致 mock 帧严格按 P5.U-error-channel.md JSON 形态构造 · 字段一对一 · level/severity 双名
⚠️ BottomProblems 高亮机制依赖现有画布 hover 实现(可能多种) step 1 强制 read 现有 hover/focus 机制 · 选最稳的复用 · 不重新设计
⚠️ MODULE_NOT_CONNECTED 误报(链路初始化中态) linkStore 在"链路 ready"状态才触发 validate · watch modules/edges 加 debounce 100ms
⚠️ 与同期 P5.U-error-channel 后端字段名分歧 step 1 强制 read 后端 prompt LinkError record 字段 · 字段一对一 · commit 前 grep 双方 enum 字面值

历史

时间 事件 hash
2026-05-30 09:28 dispatched · 用户拍板 start 三前端 fork(.clinerules v1.4 §UID 命名规范首次落地 · UID 升级 P1.U → P1.UA8 · alias 兼容 · isolation: file 标注) —
2026-05-30 15:37 zombie · 用户拍板"链路错误检查前端实装已完成"· types/link-error.ts + linkStore.errors[] + BottomProblems 数据绑定 + useLinkErrorWS 落地 · ADR-08 §2.2 前端闭环 ad34568