ADR-AIOS-21-R1 · 右 Dock 3 类固定节点 selector + Phase/Transfer 双击悬浮窗入口
状态:v0.1 accepted · 2026-06-15 12:04(用户拍板
accept ADR-AIOS-21-R1· 4 R1 hotfix 解锁派发) 修订对象:ADR-21 §3.1 + §3.3 + §3.4 + §4 实施清单 F1/F4/F6 三 fork 保留对象:ADR-21 §1 §2 §3.2 §5 §6 决议主体不动 + F2/F3/F5 三 zombie 不动
§0 修订记录(Revision History)
| 时间 | 版本 | 事件 |
|---|---|---|
| 2026-06-13 09:55 | ADR-21 v0.1 proposed | 用户拍板 5 点新需求 |
| 2026-06-13 12:51 | ADR-21 v0.1 accepted | 7 fork ready |
| 2026-06-15 09:32~09:42 | F2/F4/F6 三连 zombie | 4ed8699 / 2d5de9c / 50834d7 |
| 2026-06-15 09:45 | F7 e2e dispatched | DASHBOARD v5.1.1 |
| 2026-06-15 10:24 | ⛔ 用户反馈框架错误 | 见 §1.1 verbatim |
| 2026-06-15 10:44~10:49 | 4 路真值核查 | ADR §3.3/§3.4 0 处"双击悬浮窗" + F4/F6 严格落地错 ADR + FFT popup 标杆已存在 |
| 2026-06-15 10:50 | 用户拍板方向 B | ADR-21-R1 修订 |
| 2026-06-15 11:00 | F7 e2e abort | 文件 move |
| 2026-06-15 11:21 | 用户二次澄清 | 见 §1.2 verbatim · 3 类 selector + 5 meter 整理 |
| 2026-06-15 11:30 | R1 v0.1 proposed | 4 R1 hotfix(F1/F2/F4/F6) |
| 2026-06-15 12:04 | R1 v0.1 accepted 🆕 | 用户拍板 accept ADR-AIOS-21-R1 · F1-R1 ready 解锁起手 · F2-R1 blocked-by-F1-R1 · F4-R1/F6-R1 file isolation 可与 F2-R1 三并行 |
§1 修订触发与用户原话
§1.1 6/15 用户纠错原话(verbatim · 10:24)
执行F7之前我有需要纠正你一个十分严重的理解错误 1. xilink中新增的phase和transfer 功能要和当前已经是先的fft module对标;当前是双击直接悬浮弹窗fft窗体,而不是你现在做的再右侧dock中弹出窗体; 2. 右侧dock的fft rms 等可以基于当前的这个悬浮窗改造,区别是右侧dock可以监控链路中所有的固定节点,比如source的输出,sink的数据,log module等特定节点的数据; 3. 当前所有右侧dock都没有数据更新 4. 请做hotfix来修正这个框架设计错误
§1.2 6/15 用户二次澄清原话(verbatim · 11:21)
selector 保留三类，输入设备/source 都属于输入 ，输出设备sink属于输出，logmodule 输入节点监控 右侧dock主要对应xilink中的meter module 一共目前有五种，当前实现中有重复，请重新整理右侧dock，scope，fft，phase，rms，transfer；
§1.3 误读分析(ADR-21 起草病根)
ADR-21 起草时(6/13)Cline-AIOS 选择了用户原话「4 和 5 也需要作为右 dock 的插件注入」的"dock 容器"义,而忽略了「类似 fft 的功能」的"双击悬浮窗范式"义 · 起草时未 read components/popups/FftModulePopup.vue 现存范式 → 6/15 用户实测后纠错。
§1.4 4 路真值核查关键证据
| 证据 | 结论 |
|---|---|
| E1 ADR-21 全文 grep | 双击 / dblclick / 悬浮 / floating / Popup 出现 0 次 |
| E2 F4/F6 commit show --stat | 实际文件 DrawerDockPhase.vue / DrawerDockTransfer.vue · 0 处 dblclick |
| E3 popups/ 目录 | FFT 范式标杆 FftModulePopup.vue(374 行) + xilink LinkEditor.vue 行 129/353 双击骨架已存在 + 全局管理器 usePopupModuleManager.ts |
| E4 F1 5 类 selector | 后 2 类(xilink-module/xitune-module)语义错位 |
§2 修订决议(Decision Revision)
§2.1 三个核心修订点
| 修订点 | 原 ADR-21 | R1 修订后 |
|---|---|---|
| §3.1 Dock selector | 5 类 | 3 类:input(物理输入 + source)/ output(物理输出 + sink)/ log_module |
| §3.3 Phase UX | 仅 DrawerDockPhase | 双路径:① 双击 mini-node → PhaseModulePopup(主入口)② Dock(辅助) |
| §3.4 Transfer UX | 仅 DrawerDockTransfer | 双路径:① TransferModulePopup(双击主入口)② Dock(辅助) |
§2.2 5 种 dock meter 整理
右 Dock 是独立辅助插件 · 显示 5 种 meter:scope / fft / rms / phase / transfer · 每种共用 3 类 selector + chart 渲染。抽 useDockMeterFrame.ts composable 统一 WS 订阅 + 节点切换 + channelMask · 5 个 Drawer 组件薄壳化(只保留 chart 渲染差异)。
§2.3 数据 tap 通路修复
用户实测「所有右 dock 无数据更新」→ F1 a5b52de 引入的 nodeRef → WS endpoint 订阅通路有 bug · R1 F1-R1 hotfix 必修。
§2.4 §3.2 fft/scope 控件(F2 4ed8699)关系
F2 控件增强(displayMode/peakHold/peakTrack/trigger/persistence/timePerDiv 9 控件)完全保留 · R1 后用 useFftScopeControls.ts composable 统一在 popup + dock 双端共享。
§3 业务行为契约修订
§3.1-R1 DockHost 通用化(superseding ADR-21 §3.1)
① 输入/输出契约
// R1 修订:selector 3 类
type DockNodeKind =
| 'input' // 物理输入设备 + source 链路源(归并: ADR-17 F6 physical-input + xilink chain source)
| 'output' // 物理输出设备 + sink 链路宿(归并: sink-pre + xilink chain sink)
| 'log_module'; // ADR-17 F5 log_module_v1 关键监控点
interface DockNodeRef {
nodeId: string;
nodeKind: DockNodeKind;
channelCount: number;
sampleRate: number;
endpointUrl: string; // R1 显式锁定 WS endpoint(修数据 tap bug)
}
// 5 种 meter 共用输入
interface DockMeterInput {
meterKind: 'scope' | 'fft' | 'rms' | 'phase' | 'transfer';
selectedNodeId: string;
channelMask: boolean[];
scaleX: { min: number; max: number };
scaleY: { min: number; max: number };
}
② 收敛/成功判据
| 判据 | 阈值 |
|---|---|
| selector 仅 3 类 | dropdown 含 input/output/log_module · 不含 xilink-module/xitune-module |
| 数据 tap 通路 | 节点选定 ≤ 500ms WS 帧首达 + chart 刷新 ✅ R1 必修 |
| 5 meter 共用 selector | scope/fft/rms/phase/transfer 切节点行为一致 |
| FPS | ≥ 30fps |
③ 失败回退(沿用 ADR-21 §3.1 ③ + R1 新增)
- WS endpoint 路由错(R1 修复目标):nodeRef 绑定 5s 内 0 帧 → dock 显示 "Data tap timeout · check WS endpoint"
④ 用户操作流
- 右 dock 点 "+ fft"(或 scope/rms/phase/transfer)
- 顶部 selector 出 3 类 · 默认
input(链路 source) - 切
output→ sink 数据 chart 刷新 - 切
log_module→ 链路 N 个 log_module 实例选定后刷新 - 滚轮缩放(沿用 ADR-21)
⑤ 端到端真值 e2e
test('R1 · 3 类 selector + 数据 tap', async ({ page }) => {
await page.goto('/xilink');
await page.click('[data-testid="dock-add-fft"]');
const opts = await page.locator('[data-testid="node-selector"] option').allTextContents();
expect(opts).toEqual(['input', 'output', 'log_module']);
await page.selectOption('[data-testid="node-selector"]', 'output');
await page.waitForFunction(() => {
const c = document.querySelector('[data-testid="fft-canvas"]') as HTMLCanvasElement;
return c && c.toDataURL().length > 1000;
}, { timeout: 500 });
});
§3.3-R1 Phase Module(superseding ADR-21 §3.3)
① 双路径契约
// 路径 A · components/popups/PhaseModulePopup.vue(R1 新建 · 对标 FftModulePopup)
interface PhaseModulePopupProps {
config: PhaseModuleConfig; // 复用 ADR-21 §3.3 controls schema
x: number; y: number; zIndex: number;
}
type PhaseModulePopupEmits = {
close: []; bringToFront: []; move: [x: number, y: number];
};
// 路径 B · stages/xilink/drawers/DrawerDockPhase.vue(R1 改造保留)
interface DrawerDockPhaseProps {
selectedNodeId: string; // 来自 3 类 selector
channelMask: boolean[];
// chart 渲染与 PhaseModulePopup 共享(useDockMeterFrame composable)
}
// 算法层 frame schema 不变(ADR-12 §3.4 MeterFrame_Phase)
② 收敛判据(R1 新增)
| 判据 | 阈值 |
|---|---|
| 双击 mini-node → popup | ≤ 200ms · 浮窗在 viewport 内 · 可拖拽 · 可关闭 |
| 三段图(wrapped/unwrapped/groupDelay) | popup 与 dock 渲染一致 |
| popup ↔ dock 状态独立 | popup 关闭不影响 dock |
③ 失败回退(R1 新增)
- popup 加载失败 → LinkEditor 捕获 + console.warn + UI 提示 + fallback 不阻塞链路
④ 用户操作流(双路径)
路径 A(主):链路图找 phase mini-node → 双击 → PhaseModulePopup 浮现 → 切 displayMode
路径 B(辅助):右 dock 点 "+ phase" → 顶部 selector 默认 input → 切 output/log_module 看不同节点 phase
⑤ e2e
test('R1 · Phase popup 双击 + dock 双路径独立', async ({ page }) => {
await loadXilinkProject(page, 'phase-test-fixture.xilink');
await page.locator('[data-testid="mini-node-phase-v1"]').dblclick();
await expect(page.locator('[data-testid="phase-module-popup"]')).toBeVisible({ timeout: 200 });
await page.click('[data-testid="dock-add-phase"]');
await page.selectOption('[data-testid="node-selector"]', 'output');
await page.click('[data-testid="phase-module-popup"] [data-testid="close-btn"]');
await expect(page.locator('[data-testid="dock-phase-canvas"]')).toBeVisible();
});
§3.4-R1 Transfer Module(superseding ADR-21 §3.4)
修订模式与 §3.3-R1 一致:加 TransferModulePopup.vue(双击主入口)+ DrawerDockTransfer.vue 改造保留(辅助入口)。
// 路径 A · components/popups/TransferModulePopup.vue(R1 新建)
interface TransferModulePopupProps { config: TransferModuleConfig; x: number; y: number; zIndex: number; }
type TransferModulePopupEmits = { close: []; bringToFront: []; move: [x: number, y: number]; };
// 路径 B · stages/xilink/drawers/DrawerDockTransfer.vue(R1 改造保留)
// Smaart 4 chart(Mag/Phase/Coherence/Delay)双路径共享(useTransferFrame composable 沿用 F6 50834d7)
收敛判据 + 失败回退 + 操作流 + e2e 同 §3.3-R1 模板(双击触发 ≤ 200ms · popup ↔ dock 独立 · 沿用 ADR-21 §3.4 ②③④⑤ 算法验收 + 加 R1 双击触发 e2e case)。
§4-R1 实施清单(superseding ADR-21 §4 · F1+F4+F6 supersede)
§4.1 supersede 矩阵
| 原 fork | 状态 | R1 处理 |
|---|---|---|
F1 dock-host-generalize a5b52de |
zombie | ❌ supersede by F1-R1 |
F2 fft-scope-controls-enhance 4ed8699 |
zombie | ✅ 保留 |
F3 phase-module-algorithm 8eaaf40(dsp_algo) |
zombie | ✅ 保留(算法层与 UI 解耦) |
F4 phase-module-frontend 2d5de9c |
zombie | ❌ supersede by F4-R1 |
F5 transfer-module-algorithm eb84bab(dsp_algo) |
zombie | ✅ 保留 |
F6 transfer-module-frontend 50834d7 |
zombie | ❌ supersede by F6-R1 |
| F7 e2e | aborted 11:00 | ⛔ 已 abort · R1 闭环后另起 P_e2e.A21R1.F7 |
§4.2 R1 hotfix fork 表
| F# | UID | 部门 | Worker | 工作量 | 描述 | blocked-by |
|---|---|---|---|---|---|---|
| F1-R1 | P1.UA21R1.F1-dock-selector-3-categories-and-data-tap |
前端 P1-xilink | ClaudeA | 1.0d | DockHost selector 5→3 类(input/output/log_module · source/sink 归并语义)+ 修 nodeRef WS endpoint 数据 tap bug · grep 现有 fft/rms/scope dock 不破回归 | 无(ready) |
| F2-R1 | P1.UA21R1.F2-dock-5-meters-cleanup |
前端 P1-xilink | ClaudeA | 1.5d | 整理 5 种 meter dock(scope/fft/rms/phase/transfer)消除重复 + 抽 useDockMeterFrame.ts composable + 5 Drawer 组件薄壳化(chart 渲染差异保留) |
F1-R1 |
| F4-R1 | P1.UA21R1.F4-phase-popup-frontend |
前端 P1-xilink | ClaudeA | 0.5d | 新建 components/popups/PhaseModulePopup.vue 对标 FftModulePopup · 注册 LinkEditor onModuleDoubleClick phase 路由(已有 mini-node 行 129/353 骨架)· usePopupModuleManager.openModulePopup('phase-module', instanceId) |
F1-R1(可与 F2-R1 并行) |
| F6-R1 | P1.UA21R1.F6-transfer-popup-frontend |
前端 P1-xilink | ClaudeA | 0.8d | 新建 components/popups/TransferModulePopup.vue · Smaart 4 chart 移到 popup · transfer mini-node 双击路由 · ref/measure 双 selector 在 popup 内 |
F1-R1(可与 F4-R1 并行) |
| F7-R1(后续) | P_e2e.A21R1.F7-truth-e2e-popup-and-fixed-nodes |
测试编排 | ClaudeC | 1.5d | 4 R1 hotfix 闭环后 · playwright e2e 双路径(popup 双击 + dock 3 类 selector)+ 5 meter cleanup 真值断言 ≥ 12 case | F1-R1 + F2-R1 + F4-R1 + F6-R1 |
| 合计 | 3.8d 4 hotfix + 1.5d e2e = 5.3d | 4 R1 hotfix(全前端 P1-xilink · ClaudeA)+ 1 e2e |
关键路径:F1-R1 → (F2-R1 || F4-R1 || F6-R1 三并行)→ F7-R1 e2e
isolation:全部 file isolation(同 worktree 同 branch · 04_development/frontend_vue3/ · 与同期 active fork 文件正交)
§5 风险与缓解
| 风险 | 缓解 |
|---|---|
| F1-R1 数据 tap 通路修复需深入定位 WS endpoint 路由 | F1-R1 prompt Step 0 强制 read DockHost.vue + useChainNodeMetadata + grep 后端 WS endpoint 真实路径 + 端到端 5s timeout 自检 |
| F2-R1 5 meter cleanup 抽 composable 风险破坏现有 fft/scope dock | F2-R1 prompt 强制 vitest 基线零回归(356/3 已知 fail 不增)+ 端到端 dock 5 种 meter 都能拿到数据 |
| F4-R1 / F6-R1 popup 与 dock 双路径状态独立性 | popup usePopupModuleManager 全局管理 · dock useDockMeterFrame 节点订阅 · 两套独立 store · e2e 必跑独立性 case |
| ADR-23 mini-node 双击协议复用兼容性 | F4-R1 / F6-R1 必读 ADR-23 mini-node 双击 + LinkEditor.vue 行 129/353/1610 现有协议骨架 |
| Phase/Transfer 算法层 frame 字段在 popup vs dock 双路径渲染一致性 | useDockMeterFrame + PhaseModulePopup 共用同一 frame schema(ADR-12 §3.3/§3.4 已锁)· 不允许字段漂移 |
| F7-R1 e2e 待 4 hotfix 全 zombie 才能起 | DASHBOARD §📋 显式 blocked-by F1-R1+F2-R1+F4-R1+F6-R1 · 4 zombie 后自动 ready |
§6 决议者签名
- proposed by:Cline-AIOS(2026-06-15 11:30)
- revision trigger:user(2026-06-15 10:24 + 11:21 二次澄清 + 11:30 拍板方向 B)
- review by:user(待 accept)
- accepted by:(待用户
accept ADR-AIOS-21-R1)
§7 状态流转
| 时间 | 事件 | 备注 |
|---|---|---|
| 2026-06-15 11:30 | R1 v0.1 proposed | 4 R1 hotfix(F1/F2/F4/F6)+ F7-R1 e2e |
| (待) | R1 v0.1 accepted | 等用户 accept 派发 F1-R1 |
| (待) | F1-R1 zombie | dock selector 3 类 + 数据 tap 修复 |
| (待) | F2-R1 / F4-R1 / F6-R1 三并行 zombie | 5 meter cleanup + phase popup + transfer popup |
| (待) | F7-R1 e2e zombie | 双路径 + 5 meter 全矩阵真值 |
| (待) | R1 fulfilled 🏆 | ADR-21 整体闭环(含 R1) |
§8 关联文档
- ADR-AIOS-21(父 ADR · 本 R1 修订 §3.1+§3.3+§3.4)
- ADR-AIOS-17(F5 log_module_v1 · 本 R1 §3.1 复用)
- ADR-AIOS-18(F7 fft-module · components/popups/FftModulePopup.vue 双击悬浮窗范式)
- ADR-AIOS-23(mini-node 双击协议 · 本 R1 phase/transfer popup 复用)
- F7 abort 历史:
prompts/done/ADR-AIOS-21/P_e2e.A21.F7-...aborted-2026-06-15-1100-superseded-by-ADR-21-R1.md
§9 教训沉淀(R1 修订专属)
§9.1 ADR 起草未 read 现存范式标杆教训
ADR-21 起草时(6/13)Cline-AIOS Plan 模式起草 §3.3 Phase / §3.4 Transfer · 未 read 项目内现有 components/popups/FftModulePopup.vue 双击悬浮窗范式标杆 · 直接凭"右 dock 容器"思路自创 · 与项目既有约定背离 · 6/15 用户实测后纠错 · 走 R1 修订路径。
沉淀到 .clinerules/aios-orchestration.md 候选条目:Plan 模式起 ADR 前必 search_files 关键词 Popup|@dblclick|usePopupModuleManager 找现存范式 · 核查"已存在范式优先约束" Hard Constraint。
§9.2 ADR §3 Constraints 缺"已存在范式优先"checklist
ADR-21 §3 Constraints 没列「必须对标项目内现有 module UX 范式」硬约束 · 导致对标方向漂移。
沉淀:.clinerules ADR 11 节模板 §3 Constraints 加"已存在范式优先约束"checklist:
- [ ] 已 search_files 现有 popup/widget/dock 范式标杆
- [ ] 已确认本 ADR 引入的 UX 路径与现有约定一致 / 显式说明背离理由
- [ ] 已识别现有 LinkEditor / Shell / 全局管理器 API 复用点
§9.3 派发前 v1.1 铁律 ≠ 业务契约核查
F7 派发时严格对齐 e2e prompt 标本(P_e2e.A17.F7-8fe8d00)+ 4 维度对齐 · 但没核查"业务契约本身被 worker 落地是否正确"(F4/F6 commit diff 当时未 git show --stat 验证 vs ADR §3.3/§3.4 + FFT popup 标杆三方一致)。
沉淀:派发 e2e prompt 前必查"e2e 待测目标的源契约是否真实落地" · §0 真值核查段补 read ADR §3.x + 现有范式标杆 + worker 实际 commit diff 三方一致。
下一步:proposed 2026-06-15 11:30 → 等用户
accept ADR-AIOS-21-R1→ Cline-AIOS 同步 DASHBOARD v5.1.1→v5.1.2(F7 abort + 4 R1 hotfix ready 入 §📋)→ 用户start P1.UA21R1.F1-dock-selector-3-categories-and-data-tap派发 Phase 1(ClaudeA 1.0d)