跳转至
  • frontend_vue3/src/types/perf-frame.ts(全新 · MetricsSnapshot + ModuleMetrics 扩展字段)
  • frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue(双层 UI · Layer 1 概况 + Layer 2 per-module)
  • frontend_vue3/src/composables/useMetricsWS.ts(全新 · 订阅 metrics_update WS 帧)
  • frontend_vue3/src/composables/usePerfPerModule.ts(全新 · GET /api/perf/per-module REST poll)
  • frontend_vue3/tests/components/DrawerMetrics.test.ts(新增)
  • frontend_vue3/tests/composables/useMetricsWS.test.ts(新增)
  • frontend_vue3/tests/composables/usePerfPerModule.test.ts(新增) occupies: [P1.K-drawer-metrics(写), P1.K-types(写), P1.K-composables(写)] adr: docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md ref_section: §2.3 性能监控实装 + §3.2 边界铁律 #5 + §4.1 fork P1.U-perf-monitor-frontend derived_from: ADR-AIOS-08 created: 2026-05-30 last_modified: 2026-05-30 16:17 dispatched_at: 2026-05-30 09:30 estimated: 1.5d unblocks:
  • 验证 ADR-08 §2.3 双层界面(Layer 1 概况 + Layer 2 per-module 详细)
  • DSP 调音工程师可定位算力/内存瓶颈到具体 module related_zombie:
  • P0.U-meter-types-v3(9fc31c4 · 同部门前端 · types 扩展模式参考) related_dispatched:
  • P5.U-perf-service(同 ADR-08 §2.3 后端配套 · MetricsAggregator per-module 填充 + /api/perf/per-module REST · 本任务先按 ADR contract 跑 mock 后切真接口)
  • P1.UA8-link-error-check(同 ADR-08 前端 · 文件正交 · 同期跑)
  • P0.U-measurement-rms-fft-phase(ADR-12 #5 · 不同 stage · 文件正交)

P1.UA8-perf-monitor-frontend · 性能监控前端 UI(ADR-AIOS-08 §2.3 fork · 前端配套)

Worker:TBD(用户分配 · isolation: file · 主仓 04_development/ 任一空闲前端 worker)· 部门:前端 (frontend_vue3) 预计:1.5d · 优先级:P1 · 状态:dispatched 隔离:🧵 文件隔离(stages/xilink/drawers/DrawerMetrics.vue + composables/useMetricsWS+usePerfPerModule + types/perf-frame.ts · 与 ADR-08 P1.UA8-link-error-check 文件正交 · 与 ADR-12/ADR-11 stages 完全正交)

🔍 触发与解锁链

触发 状态 影响
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-perf-service 不新建 PerformanceService 类 · 扩展现有 MetricsAggregator
P5.U-perf-service(同期派) 🟢 dispatched 后端填充 Modules[] 字段 + /api/perf/per-module REST · 前端先按 ADR §2.3 contract 跑 mock

→ 跨栈独立(纯前端) · 不修改 contract-v1.0(已 frozen) · 与同 ADR P1.UA8-link-error-check 文件正交(本 fork 改 drawers/ · 那个改 bottom/) · 与 ADR-12/ADR-11 前端 fork 完全正交。

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

按 ADR-08 §2.3 双层界面 · 实装 DrawerMetrics 真业务:Layer 1 概况(CPU% / Mem / Latency / Buffer / TickHz)+ Layer 2 per-module 详细表格(InstanceId / PeakCPU / AvgCPU / PeakMem / TickRate · 排序切换 PeakCPU/AvgCPU/PeakMem)。

后端 P5.U-perf-service 同期派(2.0d)· 本任务不强等其 zombie:先按 ADR §2.3 schema 跑 mock 帧 · 后端 zombie 后切真接口零改动。

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

[U-thread]   P1.UA8-perf-monitor-frontend(alias: P1.U-perf-monitor-frontend)
[部门]       前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies]   P1.K-drawer-metrics(写 · DrawerMetrics.vue 双层) + P1.K-types(写 · types/perf-frame.ts 全新) + P1.K-composables(写 · useMetricsWS + usePerfPerModule)
[隔离]       🧵 文件隔离(.clinerules v1.4 §任务隔离类型分配准则)· 仅写:
             - frontend_vue3/src/types/perf-frame.ts(全新)
             - frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue(从空壳/简单展示 → 双层真业务)
             - frontend_vue3/src/composables/useMetricsWS.ts(全新)
             - frontend_vue3/src/composables/usePerfPerModule.ts(全新)
             - frontend_vue3/tests/* 新增
             严禁动 stages/xilink/bottom/*(P1.UA8-link-error-check 拥有 BottomProblems 所有权) · stages/xilink/drawers/DrawerEngine.vue(留 P1.UA8-runtime-selector-ui)· stages/xitest/* / stages/xitune/*
[优先级]     P1 · 1.5d · ADR-08 §2.3 前端配套 · 与 P5.U-perf-service(后端 2.0d)同期跑 · 文件正交于 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.3 + §3.2 边界铁律 #5 + §4.1 fork P1.U-perf-monitor-frontend)
[业务行为契约引用] ADR-AIOS-08 §2.3 双层界面 · Layer 1 概况(5 字段)+ Layer 2 per-module 表格(5 字段排序)
[参考文档](绝对路径)
  - 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.3 必读)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/active/P5.U-perf-service.md(后端配套 prompt · 同期派 · WS + REST schema 真值源)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue(壳已存在 · 本任务实装双层 UI)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/backend_csharp/Services/Metrics/MetricsAggregator.cs(167 行 · WS metrics_update 真值源 · 本任务 read 字段名/单位)
  - 同部门标本(强制 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 · WS 订阅 + 双层 UI 渲染模式参考)
  - 同 ADR 同期前端 fork(读以同步 namespace):d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/active/P1.UA8-link-error-check.md(看 useLinkErrorWS 模式 · 本任务 useMetricsWS 仿写)
  - contract-v1.0(已 frozen · 不改):d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/contracts/protocol-v1.md

【背景】
ADR-AIOS-08 accepted v1.1(2026-05-29 17:25)· 议题③ 性能监控实装:用户原话"右侧的性能监控,需要进一步实装,cpu 的算力占比,内存情况,延时等概况统计,还需要有详细统计界面,可以将链路中的每一个模块的算力内存时钟等占用情况做详细的 peak 平均统计"。

🚨 **真值核查发现**:
- 后端 `MetricsAggregator.cs` 已实装 167 行 · 100ms 推送 `metrics_update` WS · 系统级 5 字段 99% 就位(仅缺 Mem 和 TickHz · 同期 P5.U-perf-service 补齐)
- 后端 `MetricsSnapshot.Modules` 当前永远为空 list(同期 P5.U-perf-service 填充)
- 前端 `DrawerMetrics.vue` 壳已存在 · 但无数据 · 本任务实装双层 UI 闭环

**ADR §2.3 双层界面**:
- Layer 1 概况(默认视图):CPU% gauge + 内存 progress bar + 链路延时 + 缓冲区水位 + Tick 频率
- Layer 2 详细(切换 tab "Per-Module"):表格显示每 module 的 PeakCPU / AvgCPU / PeakMem / TickRate · 排序切换(PeakCPU 降序 / AvgCPU / PeakMem)

**本任务执行策略**(不强等后端 zombie):
- Phase A:按 ADR §2.3 schema 实装 DrawerMetrics 双层 UI · WS订阅mock + REST mock(useMetricsWS / usePerfPerModule 内置 dev mock)
- Phase B:后端 P5.U-perf-service zombie 后 · 切真 WS / REST(改两个 composable 一处 · UI 零改动)

**契约策略**:不修改 contract-v1.0(已 frozen) · `metrics_update` WS 字段扩展 + REST `/api/perf/per-module` 走 dev-api(待 K2-protocol-v2 §performance-monitor 正式入)。

【执行步骤】

Step 1 · read 已有基础(只读 · 必做)
- read ADR-AIOS-08 §2.3 全文(双层界面 ASCII 图 + 5+5 字段定义 + Per-Module 排序规则)
- read 同期 P5.U-perf-service.md(看后端 metrics_update JSON 扩展字段 + /api/perf/per-module REST schema 真值源)
- read backend_csharp/Services/Metrics/MetricsAggregator.cs 现有 167 行(MetricsSnapshot/ModuleMetrics 字段 · 100ms 推送 metrics_update 已有 4 字段)
- read frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue 当前壳代码
- read 标本 prompts/active/P0.U-measurement-rms-fft-phase.md(同部门 · 前端 WS 订阅 + 双层 UI 模式)
- read 同期 prompts/active/P1.UA8-link-error-check.md(看 useLinkErrorWS 风格 · 本任务 useMetricsWS 仿写)

Step 2 · 新建 frontend_vue3/src/types/perf-frame.ts(与后端 MetricsAggregator 字段对齐)
- export interface MetricsSnapshotFrame {
    cpuLoadPercent: number          // 系统级 CPU%(EWMA)
    cpuLoadPeak: number             // 系统级 CPU 峰值
    underrunCount: number
    overrunCount: number
    totalLatencyMs: number          // 链路延时(ms)
    processMemoryBytes?: number     // 系统级内存(P5.U-perf-service 新增 · 可选向后兼容)
    tickRateHz?: number             // 系统级 Tick 频率(P5.U-perf-service 新增 · 可选)
    bufferLevelPercent?: number     // 缓冲区水位(若后端提供)
    modules: ModuleMetricsRow[]     // P5.U-perf-service 填充 · 旧版可空
    timestampMs: number
  }
- export interface ModuleMetricsRow {
    instanceId: string
    moduleType?: string
    peakCpuPercent: number
    avgCpuPercent: number
    peakMemoryBytes: number
    moduleTickRateHz: number
  }
- export type PerfSortBy = 'PeakCpu' | 'AvgCpu' | 'PeakMem'

Step 3 · 新建 frontend_vue3/src/composables/useMetricsWS.ts(订阅 metrics_update + mock 双模式)
- 接收 ws client 实例(复用现有 ws 单例 · 同 useLinkErrorWS 模式)
- onMessage 过滤 type === 'metrics_update' 的帧 · 解析 JSON · 转 MetricsSnapshotFrame
- 暴露 Vue ref<MetricsSnapshotFrame | null>(组件订阅)
- 当 DrawerMetrics 关闭时调 stop() 释放(ADR §3.2 边界铁律 #5 · 不打开不采集)
- dev/test 提供 __mockPushFrame(frame) 全局 helper
- 返回 { frame, start(), stop(), __mockPushFrame }

Step 4 · 新建 frontend_vue3/src/composables/usePerfPerModule.ts(REST poll · GET /api/perf/per-module)
- 提供 fetch(sortBy?: PerfSortBy) Promise<ModuleMetricsRow[]>
- DrawerMetrics 切到 "Per-Module" tab 时调 · 默认 5 秒轮询(ADR §2.3 不要求实时 · 用户主动刷新场景)
- 错误处理:链路未启动返回 200 + 空 modules · 显示"暂无数据"
- dev/test 提供 __mockResponse(rows) helper
- 返回 { modules, isLoading, error, fetch(), startPoll(intervalMs?), stopPoll() }

Step 5 · 实装 frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue(双层 UI)
- Layer 1 默认视图(订阅 useMetricsWS):
  · CPU% gauge 仪表盘(0-100 · 70% 黄 / 90% 红 · 复用现有 chart 组件或简单 svg)
  · 内存 progress bar(processMemoryBytes 转 MB · 显示 "142 MB / 总进程内存")
  · 链路延时数字(totalLatencyMs · 趋势线最近 60 个采样点 · 复用 sparkline 风格)
  · 缓冲区水位 progress bar(若 bufferLevelPercent 存在)
  · Tick 频率(tickRateHz · 显示 "1000Hz")
- Layer 2 Per-Module tab(订阅 usePerfPerModule):
  · 表格 5 列:Module / PeakCPU% / AvgCPU% / PeakMem (MB) / Tick (Hz)
  · 列头点击切换排序(PeakCpu 默认 · 切 AvgCpu / PeakMem)
  · 行 hover 高亮 · 点击 emit('focus-module', { instanceId }) → 复用 P1.UA8-link-error-check 同款 emit
  · 空表格显示"暂无 module 数据"占位
- Tab 切换:Tab 头部 [概况] [Per-Module] · 默认概况
- Drawer 关闭时调 useMetricsWS.stop() + usePerfPerModule.stopPoll()(ADR §3.2 边界铁律 #5)

Step 6 · 单元测试 + e2e mock 真值
- 新增 tests/composables/useMetricsWS.test.ts(>= 4 case:订阅 metrics_update + 解析新字段(processMemoryBytes/tickRateHz/modules)+ 旧客户端兼容(无新字段帧)+ stop 释放)
- 新增 tests/composables/usePerfPerModule.test.ts(>= 4 case:fetch 默认排序 + sortBy=AvgCpu + 空链路 200 + startPoll/stopPoll)
- 新增 tests/components/DrawerMetrics.test.ts(>= 5 case:Layer 1 渲染 5 字段 + 70%/90% 阈值色 + Tab 切换 + Per-Module 表格排序 + 关闭释放)
- 至少 13 个新 case
- typecheck + build + test:unit 基线 356/3 → 目标 ≥ 369/3(+13 用例)

Step 7 · 端到端真值(.clinerules v1.8 §业务行为契约必填段)
- vitest 真值脚本:__mockPushFrame 注入(cpuLoadPercent=76 · processMemoryBytes=149_000_000 · totalLatencyMs=12 · modules=[{instanceId:'eq.high', peakCpuPercent:12.3, avgCpuPercent:8.1, peakMemoryBytes:4_400_000}])→ 断言 Layer 1 显示 "76%" gauge + "142 MB" + "12 ms" · Tab 切 Per-Module → 表格首行 "eq.high · 12.3% · 8.1% · 4.2 MB"
- 排序切换:点击 AvgCPU 列头 → 表格按 avgCpuPercent 降序排列

Step 8 · Commit + push
- git status / git pull origin xistudio --no-rebase / git add 隔离文件清单
- 三元组 trailer 必须含 [files=...] · 列全部修改文件
- git push origin xistudio

【验收】

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

业务行为契约自查清单(ADR §2.3):
- [ ] ① Layer 1 概况:5 字段渲染(CPU% gauge / 内存 / 延时 / 缓冲区 / TickHz)· 70%/90% 黄/红阈值色
- [ ] ② Layer 2 Per-Module:表格 5 列 · 排序切换 PeakCpu/AvgCpu/PeakMem · 行 hover/click 交互
- [ ] ③ Tab 切换 [概况] / [Per-Module] · 默认概况
- [ ] ④ ADR §3.2 边界铁律 #5 验证:Drawer 关闭时停止采集(useMetricsWS.stop + usePerfPerModule.stopPoll · 单测覆盖)
- [ ] ⑤ 旧客户端兼容:无 modules / processMemoryBytes / tickRateHz 字段时 UI 优雅降级(显示 "—" 而非 undefined)
- [ ] ⑥ Phase A mock 跑通后 · ① 输入输出 schema 与 Phase B 真接口零改动切换(留 useMetricsWS / usePerfPerModule TODO 切换点)
- [ ] ⑦ 与 P1.UA8-link-error-check focus-module emit 复用(交互一致性)

【commit】
subject:`feat(P1.UA8-perf-monitor-frontend): DrawerMetrics two-tier UI + useMetricsWS + usePerfPerModule · ADR-08 §2.3 frontend`

trailer(必须精确):
[step=8/8] [pid=P1] [uid=UA8-perf-monitor-frontend] [occupies=P1.K-drawer-metrics+P1.K-types+P1.K-composables]
[files=frontend_vue3/src/types/perf-frame.ts, frontend_vue3/src/stages/xilink/drawers/DrawerMetrics.vue, frontend_vue3/src/composables/useMetricsWS.ts, frontend_vue3/src/composables/usePerfPerModule.ts, frontend_vue3/tests/composables/useMetricsWS.test.ts, frontend_vue3/tests/composables/usePerfPerModule.test.ts, frontend_vue3/tests/components/DrawerMetrics.test.ts]
[ipc=ws/metrics_update(consumer · extended-modules-field), api/perf/per-module(consumer)]
[isolation] file(同 worktree 同 branch · 文件正交于 ADR-08 P1.UA8-link-error-check + ADR-12/ADR-11 前端 fork)
[derived_from] ADR-AIOS-08 §2.3 fork

【禁止】
1. ❌ 不动 stages/xilink/bottom/*(P1.UA8-link-error-check 拥有 · 必须文件正交)
2. ❌ 不动 stages/xilink/drawers/DrawerEngine.vue(留 P1.UA8-runtime-selector-ui)
3. ❌ 不动 stages/xilink/drawers/Drawer{Connection,Inspector,Log,Modules,Profile,Project,PropertyPanel}.vue(本 fork 仅 DrawerMetrics)
4. ❌ 不动 stages/xitest/* / stages/xitune/*(ADR-12 / ADR-11 派发中)
5. ❌ 不嵌入完整 Vue SFC 骨架(.clinerules v1.6 §prompt 内容硬约束)· worker 自决具体实现风格
6. ❌ 不绑定 worker(本 prompt frontmatter worker: TBD · isolation: file · 用户分配 worker)
7. ❌ 不新建 /ws/perf 订阅 channel(后端 P5.U-perf-service 已 freeze 用 metrics_update 复用)
8. ❌ 不在 DrawerMetrics 关闭时仍订阅 WS(ADR §3.2 边界铁律 #5 · 严禁 perf 数据 daemon 长跑)
9. ❌ 不验"typecheck 全绿就 commit"——必须按 ADR §2.3 7 项契约 + e2e mock 真值脚本(注入 76% CPU + 142MB + per-module 表格)
10. ❌ 不强等 P5.U-perf-service zombie 才开工(Phase A mock 先跑 · Phase B 切真接口零改动)

解锁链(本任务 zombie 后)

  • ✅ ADR-08 §2.3 双层界面前端闭环验证(用户原话场景"详细统计界面 · peak 平均")
  • ✅ ADR-08 §3.2 边界铁律 #5 验证(Drawer 关闭停止采集 · 不引入 daemon)
  • ✅ Phase B 切真接口零改动(后端 P5.U-perf-service zombie 后 · 两 composable 切换点零 UI 改动)
  • ✅ 给 K2-protocol-v2 §performance-monitor 起草提供 PerfFrame + per-module 实测数据

风险评估

风险 缓解
⚠️ 100ms 高频 WS 帧导致 UI 卡顿 useMetricsWS 内 requestAnimationFrame 节流 · DrawerMetrics 关闭时 stop · gauge 用 svg 简单实现不用复杂 chart
⚠️ Layer 2 表格 N=20 module 排序性能 computed + 排序 stable · 切换排序时内存零分配(in-place sort copy)· 单测覆盖 N=50 场景
⚠️ 70%/90% 阈值硬编码与设计文档分歧 ADR §2.3 + MetricsAggregator.cs 注释一致使用 70/90 · 本 fork 沿用 · 不重新定义
⚠️ 旧客户端无 processMemoryBytes/tickRateHz 字段时显示 "undefined" types/perf-frame.ts 标可选 · UI 渲染处用 ?? "—" 兜底 · 单测覆盖无新字段帧
⚠️ Tab 切换时未 release 上一个 composable DrawerMetrics watch tab 切换 · 切到 Per-Module 时启动 poll · 切回概况时 stopPoll(单测覆盖)

历史

时间 事件 hash
2026-05-30 09:30 dispatched · 用户拍板 start 三前端 fork(.clinerules v1.4 §UID 命名规范 · UID 升级 P1.U → P1.UA8 · alias 兼容 · isolation: file 标注) —
2026-05-30 16:17 zombie · 用户拍板 stop · DrawerMetrics 双层 UI(Layer 1 概况 + Layer 2 per-module)+ useMetricsWS + usePerfPerModule 落地 · ADR-08 §2.3 前端闭环 · Phase B 切真接口零改动 834f86a