XiStudio v3 前端实施路线图
文档定位：本文档承接
v3-unified-macos.html v0.3+（已验收的框架级 demo），回答用户提出的核心问题： "demo 是要做到框架级就交付，还是把每个页面所有功能都演示出来再交付？"本文档不替代
v3-implementation-spec.md（实施规格），而是规格的"上游路线图"——决定做到什么粒度、何时切到代码、前端智能体怎么接力。
§0 快速导航
| 章节 | 内容 | 适合谁读 |
|---|---|---|
| §1 当前阶段诊断 | v0.3+ demo 现状/缺口 | 全员 |
| §2 行业最佳实践 | B 端复杂 IDE 类产品的设计→实施分期 | 设计负责人 / TL |
| §3 三方案对比 | A 浅完整 / B 深完整 / C 分层混合（推荐⭐） | 决策者 |
| §4 每个 tab 功能清单 | XiStudio / XiForge / XiTune / XiProbe 的子 tab 与功能点 | 设计师 / 前端 |
| §5 协作工作流（按方案 C） | 5 个阶段的具体交付 + 工时 + 责任人 | TL / PM |
| §6 阶段验收标准 | 每个阶段"完成"的判定条件 | PM / QA |
| §7 风险与权衡 | 跳过/简化某阶段的代价 | 决策者 |
§1 当前阶段诊断
1.1 v0.3+ demo 已经完成什么
| 维度 | 完成度 | 证据 |
|---|---|---|
| 整体布局骨架 | ✅ 100% | 3 行 4 列 grid（顶 44 / 主体 1fr / 底 32 / 状态 24，列 = 左 48 / 主 / 右 48）已稳定 |
| 品牌色法典 / 6 主题 | ✅ 100% | A 玫瑰金 / B 极光青 / C 米纸 / D 极简白 / E 赛博紫黑 / F 毛玻璃，全部可一键切换 |
| macOS 视觉语言 | ✅ 100% | 红绿灯装饰 + 毛玻璃 backdrop-filter + SF Pro + 圆角体系 + 焦点环 |
| 4 主 tab 切换 | ✅ 100% | XiStudio / XiForge / XiTune / XiProbe 的 Pill Tab 可切，XiCloud 灰显（License 隔离） |
| Activity Bar 双侧 | ✅ 100% | 左 5 icon + 右 4 icon 互斥切换，单击唤起悬浮抽屉 |
| 悬浮抽屉 + 锁定模式 | ✅ 100% | 默认悬浮智能避让 inset，Ctrl+\ 切锁定挤压主画布 |
| 底部 6 tab 常驻 | ✅ 100% | Module 属性 / 编译 / 日志 / 问题 / 终端 / XiMind |
| Tuning 多开浮窗管理器 | ✅ 100% | 9 函数管理 API + 顶栏 🪟 浮窗 N 入口 + 浮窗 traffic-lights |
| ☰ 菜单 + 5 文件图标 | ✅ 100% | 折中菜单方案落地 |
结论：v0.3+ 已经是一份合格的"设计法典级"框架 demo，足以让前端智能体理解全局视觉/交互规范。
1.2 v0.3+ demo 缺什么
| 缺口 | 描述 | 对前端的影响 |
|---|---|---|
| 每个 tab 主画布的真实功能视图 | 当前 4 主 tab 主画布只有 1-2 个示意元素（如 XiStudio 只有几个示意节点；XiForge 只有控件库雏形） | 🟡 中等：前端能看出"这块画布是流图/UI 设计器"，但不知道节点详细形态、连线交互细节、属性面板如何联动 |
| 每个 sidebar 抽屉的真实内容 | 抽屉只有 mock 列表（📁 工程/项目1/项目2），缺真实业务字段 |
🟡 中等：前端会照 mock 实现，业务侧后续返工 |
| 子 tab 切换后的二级页面 | XiStudio 内部有"流图/调音视图/仿真/部署"4 子 tab，但 demo 只演示了流图，其他子 tab 占位 | 🔴 高：前端会"猜"，每人猜一个版本 |
| Tuning 浮窗内部 UI | 12 个 *TuningDialog 在 frontend_vue3 里已存在，但 demo 浮窗只是空壳 | 🟢 低：可直接复用现有 .vue 文件 |
| 空状态 / 加载态 / 错误态 | demo 没演示"无项目时""加载中""License 失效""设备掉线" | 🟡 中等：前端容易遗漏 |
| 响应式断点 | demo 仅在 1440×900 视口验证，未演示窄屏（笔记本 1366）和宽屏（4K） | 🟡 中等：前端需自行设计断点 |
1.3 给前端智能体看 v0.3+ 够不够？
不够。 原因：
- 视觉风格够了（智能体能照搬色板/字号/圆角/动效）；
- 交互框架够了（智能体能照搬抽屉模式/Tuning 多开/主题切换）；
- 但 4 主 tab 内部各自的"代表性页面长什么样"没有定， 4 个智能体（或同一智能体分 4 次）会各自发挥，导致 4 个 tab 内部风格不一致——这是 B 端 IDE 类产品最大的体验杀手。
所以必须补 4 个"招牌页面" demo，把每个 tab 的"灵魂功能视图"用同一支笔画出来，建立 tab 内部的风格基准。
§2 行业最佳实践：B 端复杂 IDE 产品的设计→实施分期
参考 VSCode / Figma / Logic Pro / Ableton Live / DaVinci Resolve / Blender 等成熟产品的公开设计访谈与文档，B 端复杂 IDE 类产品的标准流程通常是 5 阶段：
| 阶段 | 名称 | 产物 | 决策粒度 | 典型工时占比 |
|---|---|---|---|---|
| P-1 | 设计原型（Wireframe） | 黑白线框图 | 信息架构 / 主导航 | 5–10% |
| P-2 | 视觉法典（Design Tokens + 风格） | 色板 / 字号 / 圆角 / 动效 / 6 主题 | 视觉语言 | 10–15% |
| P-3 | 框架级高保真（Layout Skeleton） | 可点击的 HTML/Figma 原型，演示整体布局 + 跨页交互 | 顶栏/侧栏/底栏/主区如何拼接 | 15–20% |
| P-4 | 招牌页面高保真（Hero Pages） | 每个一级 tab 选 1 个最有代表性的"灵魂页面"做完整 demo | 每个 tab 内部的设计语言 | 15–25% |
| P-5 | 实施规格（Spec）+ 编码 | 组件清单 / 状态机 / 路由 / API 契约 / 工程化 | 落地工程 | 35–50% |
2.1 我们当前的位置
P-1 ✅ 已完成（5 个 v2 demo + v3 框架）
P-2 ✅ 已完成（brand-color-system v1.2 + 6 主题）
P-3 ✅ 已完成（v3-unified-macos.html v0.3+ 验收）
P-4 ⏳ 进行中（待启动 4 个招牌页面） ← 我们在这里
P-5 ⏳ 待启动（spec v1.0 + 前端智能体编码）
2.2 不同公司在 P-3 和 P-4 之间的取舍
- Figma / Notion：P-3 后直接进 P-5（设计师同时是工程师），但他们前端团队规模小、迭代快；
- VSCode / Logic Pro：P-3 + P-4 都做，P-4 至少做 3-5 个核心场景，因为团队大、风格统一难；
- 国内 ToB SaaS（蓝湖/Worktile/腾讯文档）：P-3 后直接做"全量 mockup"（即方案 B），但代价是设计周期 +50%。
我们的情况：用户是单人产品负责人 + 待派的前端智能体团队 → 接近 VSCode 模式，P-4 必须做但不需要做 12-15 个全量 mockup，挑 4 个招牌页面即可。
§3 三方案对比
3.1 方案 A · 浅完整型
思路：当前框架级 demo + 4 主 tab 每个加 1 个"代表性子页面"完整 demo（与方案 C 相似），其他子 tab 占位即可，不写 spec v1.0，直接交付前端智能体边写边补。
| 维度 | 评估 |
|---|---|
| 设计阶段工时 | 1 周（4 个招牌页面 demo） |
| 前端实施工时 | 10–12 周（前端要边猜边问） |
| 风格一致性风险 | 🟡 中等（有招牌页面兜底） |
| 适用场景 | 时间极紧、团队磨合度高、前端工程师懂设计 |
| 不推荐原因 | 缺 spec v1.0 → 状态机/路由/API 契约靠口口相传 → 联调地狱 |
3.2 方案 B · 深完整型
思路：每个 tab 的所有子 tab、所有功能都 demo 完整（XiStudio 4 子 tab × 各功能 + XiForge 3 视图各完整 + XiTune 3 视图 + XiProbe 4 视图），约 12-15 个完整页面 demo + spec v1.0，再交付前端智能体。
| 维度 | 评估 |
|---|---|
| 设计阶段工时 | 4–6 周（12-15 个 demo 页面 + 各种空/错/加载态） |
| 前端实施工时 | 6–8 周（"翻译"式实施，不需要做设计判断） |
| 风格一致性风险 | 🟢 低（所有页面都画过） |
| 适用场景 | 设计师团队充足、前端工程师不懂设计、产品已稳定不会大改 |
| 不推荐原因 | 工时拖到 4-6 周，期间产品需求可能变更 → demo 返工成本高；且 IDE 类产品很多细节本就该在编码阶段迭代（如节点右键菜单的最终 17 项 vs 初版 8 项） |
3.3 方案 C · 分层混合 ⭐ 推荐
思路： 1. 冻结 v0.3+ 大框架作为"设计法典"（即 P-3 完成，不再改大结构）； 2. 重点完善 4 个"招牌页面"——每 tab 1 个最有代表性的（即 P-4 收口）； 3. 同步沉淀 spec v1.0（基于 v0.3+ 框架 + 4 招牌页面）； 4. 其他子 tab + 功能细节留给前端智能体在实施阶段"边写边补"，参照设计法典 + 招牌页面的视觉风格 + spec 的工程契约； 5. 每个迭代节点设计师 review 一次前端实施成果，不偏航。
| 维度 | 评估 |
|---|---|
| 设计阶段工时 | 2 周（4 招牌页面 + spec v1.0 重写） |
| 前端实施工时 | 8–10 周（有 spec 兜底 + 4 招牌页面参考） |
| 风格一致性风险 | 🟢 低（招牌页面+spec 双保险） |
| 总工时 | 10–12 周（vs B 的 10-14 周，节省 0-2 周） |
| 灵活性 | 🟢 高（边写边迭代细节，需求变更可吸收） |
| 适用场景 | 就是我们当前的场景 |
方案 C 的核心论据
- 80/20 原则：4 个招牌页面承载 80% 的视觉/交互决策，剩下 20% 的页面靠"复用法典 + 招牌页面延伸"即可；
- B 端 IDE 的高频操作集中：用户 80% 时间在流图、UI 设计器、调音链、测试报告 4 个核心视图，这 4 个就是招牌页面，做透它们就能保证主流程无瑕疵；
- 降低需求变更损失：方案 B 提前 4-6 周画完所有页面，期间需求变更必然导致 demo 返工；方案 C 让"次要页面"在编码期再细化，反而能吸收变更；
- 匹配前端智能体能力：智能体擅长"在已定的模式上批量产出相似页面"，不擅长"无设计指引下做创造性发挥"——招牌页面正好提供"模式"。
3.4 三方案速查表
| A 浅完整 | B 深完整 | C 分层混合 ⭐ | |
|---|---|---|---|
| 设计周期 | 1 周 | 4-6 周 | 2 周 |
| 实施周期 | 10-12 周 | 6-8 周 | 8-10 周 |
| 总周期 | 11-13 周 | 10-14 周 | 10-12 周 |
| 风格一致性 | 🟡 中 | 🟢 高 | 🟢 高 |
| 需求变更吸收力 | 🟢 高 | 🔴 低 | 🟢 高 |
| spec v1.0 | ❌ 无 | ✅ 有 | ✅ 有 |
| 招牌页面 | ✅ 4 个 | ✅ 12-15 个 | ✅ 4 个 |
| 推荐度 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
§4 每个 tab 的功能清单（用于后续 demo 完善 + spec 撰写）
以下清单不是让你立即把每个功能都画 demo，而是给你全景地图——决定哪些进招牌页面 demo（方案 C 4 个）、哪些进 spec 文字描述、哪些留给前端实施时迭代。
4.1 XiStudio（L4 流图链路 IDE · 工程师向）
| 子 tab | 功能点（粗→细） | 招牌候选 |
|---|---|---|
| ① 流图编辑 | 节点拖拽 / 连线 / 缩放 0.25-4× / 多文档 tab / Minimap / 自动布局 / 节点右键菜单 / 双击打开 Tuning / 框选/对齐/分组 / 撤销重做 / 复制粘贴 / 搜索定位 | ⭐ 强烈推荐为 XiStudio 招牌页 |
| ② 调音视图 | Tuning Stack 多卡片并排 / 8 通道 RTA / 单通道高亮 / 全局 bypass / 旁路对比 | |
| ③ 仿真 | 实时频响 / 频谱 / 波形 / RTA 4 联屏 / ABx 切换 / 截屏对比 | |
| ④ 部署 | 4 步流程：编译→烧录→自检→FOTA / 进度条 / 错误诊断 |
4.2 XiForge（L4 算法 IP 工坊 / VST 开发场景 · 算法工程师向）
| 子 tab | 功能点 | 招牌候选 |
|---|---|---|
| ① UI 设计 | 左控件库（XiForge 方块网格风格）/ 中央 UI 画布 / 右属性面板 / 底部代码生成预览 / 控件对齐网格 / 多控件组合 / 模板库 | ⭐ 强烈推荐为 XiForge 招牌页 |
| ② 算法源码 | 左文件树 / 中央代码编辑器（Monaco-like）/ 右编译输出 / 错误跳转 / 符号搜索 | |
| ③ 仿真测试 | 左用例树 / 中央 PASS/FAIL 摘要卡 / 右测试报告 / 回归对比 |
4.3 XiTune（L2 调音套装 · 调音师向）
| 子 tab | 功能点 | 招牌候选 |
|---|---|---|
| ① 调音链 | 链路图（简化流图）/ 多个 Tuning 卡片并排 / 8 通道独立调节 / 实时频响曲线 / preset 库 / 历史版本对比 | ⭐ 强烈推荐为 XiTune 招牌页 |
| ② 曲线对比 | 多曲线叠加 / 目标曲线 / 偏差色块 / 频段标尺 / 截图导出 | |
| ③ ABX 盲测 | A/B/X 3 按钮 / 统计胜率 / 自动随机切换 / 报告导出 |
4.4 XiProbe（L2 测试设备 · QA 向）
| 子 tab | 功能点 | 招牌候选 |
|---|---|---|
| ① 频响测试 | 频响曲线 / 标准曲线 / 容差判定 / 多通道并排 | |
| ② THD+N | THD 曲线 / 目标线 / 多频点测量 | |
| ③ SNR | SNR 数值 / 频谱图 / 噪声基底 | |
| ④ 批量测试 | 测试用例树 / 报告对比 / PASS/FAIL 一览 / 历史趋势 / 自动化脚本入口 / 报告 PDF 导出 | ⭐ 强烈推荐为 XiProbe 招牌页 |
4.5 4 个招牌页面汇总
| # | 招牌页面 | 文件名（建议） | 复杂度 | 工时 |
|---|---|---|---|---|
| 1 | XiStudio · 流图编辑完整页 | v3-hero-xistudio-graph.html |
🔴 高 | 2-3 天 |
| 2 | XiForge · UI 设计器 + 源码生成完整页 | v3-hero-xiforge-ui.html |
🔴 高 | 2-3 天 |
| 3 | XiTune · 调音链 + Tuning 多开完整页 | v3-hero-xitune-chain.html |
🟡 中 | 1-2 天 |
| 4 | XiProbe · 批量测试报告完整页 | v3-hero-xiprobe-batch.html |
🟡 中 | 1-2 天 |
| 合计 | 6-10 天（约 1.5 周） |
加上 spec v1.0 重写（约 0.5 周），P-4 阶段总工时 = 2 周，与 §3.3 方案 C 估算一致。
§5 前端智能体协作工作流（按方案 C 展开）
5.1 全流程时间线（10-12 周）
周次 阶段 主要交付 责任方
─────────────────────────────────────────────────────────────────────
W0 ✅ P-3 已完成 v3-unified-macos.html v0.3+ 设计（已交付）
W1-2 ⏳ P-4 招牌页面+spec 4 个 hero demo + spec v1.0 设计 ← 立即启动
─────────────────────────────────────────────────────────────────────
W3 🔵 阶段 1 视觉法典落地 tokens.css / themes.css / macos.css 前端智能体
W4 🔵 阶段 2 应用骨架 MenuBar / ToolBar / MainTabs / 路由 前端智能体
W5-6 🔵 阶段 3 侧栏与抽屉 Activity Bar + 悬浮抽屉 + 锁定模式 前端智能体
W7-8 🔵 阶段 4 4 主 tab 招牌页 对照 4 hero demo 实现首屏 前端智能体
W9-10 🔵 阶段 5 Tuning + 浮窗 复用 12 *TuningDialog + 浮窗管理器 前端智能体
W11-12 🔵 阶段 6 联调 + 打磨 真实后端/License/设备/批量回归 前端+后端
5.2 P-4 阶段（W1-W2）· 设计交付清单
| 周 | 交付物 | 文件路径 | 验收人 |
|---|---|---|---|
| W1 | hero-1: XiStudio 流图招牌页 | layout-demo/v3-hero-xistudio-graph.html |
用户 |
| W1 | hero-2: XiForge UI 设计器招牌页 | layout-demo/v3-hero-xiforge-ui.html |
用户 |
| W2 | hero-3: XiTune 调音链招牌页 | layout-demo/v3-hero-xitune-chain.html |
用户 |
| W2 | hero-4: XiProbe 批量测试招牌页 | layout-demo/v3-hero-xiprobe-batch.html |
用户 |
| W2 | spec v1.0 | layout-demo/v3-implementation-spec.md（重写） |
用户 + 前端 TL |
5.3 实施阶段（W3-W12）· 6 个子阶段详解
阶段 1（W3）· 视觉法典落地 · 1 周
目标：让任意 Vue 组件挂上 class="xy-button-primary" 就能拿到设计法典外观。
交付：
- frontend_vue3/src/styles/tokens.css：CSS 变量（色板 / 字号 / 圆角 / 间距 / 动效时长）
- frontend_vue3/src/styles/themes.css：6 主题 [data-theme="A"] 级联
- frontend_vue3/src/styles/macos.css：traffic-lights / 毛玻璃 / SF Pro
- frontend_vue3/src/composables/useTheme.ts：ThemeEngine + localStorage 持久化
- frontend_vue3/src/components/_design-system-preview.vue：法典自检页（可视化所有 tokens）
验收：自检页 6 主题切换无视觉错位，所有 tokens 在 Vue DevTools 可见。
阶段 2（W4）· 应用骨架 · 1 周
目标：搭起 v0.3+ 的"3 行 4 列 grid"和顶栏/底部条/状态栏。
交付：
- App.vue 重构为 grid 容器
- components/shell/AppMenuBar.vue（☰ 菜单 + 5 文件图标 + 红绿灯）
- components/shell/AppToolBar.vue（工具栏区）
- components/shell/MainTabs.vue（4 主 tab + XiCloud 灰显）
- components/shell/AppFooter.vue（底部 6 tab）
- components/shell/AppStatusBar.vue
- router/index.ts：4 主 tab 对应 4 路由
- stores/license.ts：Pinia store 控 XiCloud 灰显
验收：路由切换流畅，4 主 tab 切换不闪烁，6 主题在所有壳层组件生效。
阶段 3（W5-W6）· 侧栏与抽屉 · 2 周
目标：左右 Activity Bar + 悬浮抽屉 + 智能避让 + 锁定模式（Ctrl+\）。
交付：
- components/shell/ActivityBarLeft.vue（5 icon）
- components/shell/ActivityBarRight.vue（4 icon）
- components/shell/SideDrawer.vue（通用抽屉容器，支持 left/right）
- composables/useDrawer.ts（抽屉状态机：closed / floating / locked）
- composables/useSmartInset.ts（智能避让算法）
- 9 个抽屉内容组件（左 5 + 右 4，先用 mock 数据填充）
验收：单击 icon 互斥切换、Ctrl+\ 切锁定、抽屉拖拽改宽度、布局不溢出。
阶段 4（W7-W8）· 4 主 tab 招牌页对照实现 · 2 周
目标：照 P-4 交付的 4 个 hero demo，把每个 tab 的"灵魂首屏"实现到位。
交付：
- views/xistudio/GraphEditor.vue（对照 hero-1）
- views/xiforge/UIDesigner.vue（对照 hero-2）
- views/xitune/TuningChain.vue（对照 hero-3）
- views/xiprobe/BatchReport.vue（对照 hero-4）
- 各 tab 的"次要子 tab"先用占位页（带 <TODO /> 标识）
验收：4 主 tab 切到首屏即看到 hero demo 同款界面，像素级偏差 < 5%。
阶段 5（W9-W10）· Tuning + 浮窗管理器 · 2 周
目标：复用现有 12 个 *TuningDialog.vue，套上浮窗管理器。
交付：
- composables/useFloatingWindows.ts（9 函数 API：open/close/minimize/show/closeAll/bringToFront/makeDraggable/refreshTray/toggleTray）
- components/shell/FloatingWindowHost.vue（浮窗宿主 + traffic-lights）
- components/shell/FloatingWindowTray.vue（顶栏 🪟 浮窗 N 入口）
- 适配 12 *TuningDialog 到浮窗容器（不改原 .vue 内容，只加 wrapper）
验收：从流图节点双击能开 Tuning 浮窗，多开不冲突，最小化/恢复/关闭都正常。
阶段 6（W11-W12）· 联调 + 打磨 · 2 周
目标：接真实后端、License、设备，跑通端到端。
交付： - 后端 API 对接（替换所有 mock） - License 真实校验（替换 store mock） - 设备连接真实 WebSocket - 空状态 / 加载态 / 错误态 / 网络异常态全覆盖 - 性能优化（首屏 < 2s，路由切换 < 200ms） - 设计师 review + 像素级修正
验收：跑通"新建工程→拖节点→连线→开 Tuning→部署"完整流程，6 主题在真实场景下无翻车。
§6 阶段验收标准
6.1 P-4 阶段（设计交付）
| 项 | 验收标准 |
|---|---|
| 4 个 hero demo | 离线双击可运行 / 6 主题切换正常 / 关键交互可点击演示 |
| spec v1.0 | 章节齐备（§1 视觉法典 / §2 路由 / §3 状态机 / §4 组件清单 / §5 API 契约 / §6 工程化 / §7 验收）/ 每个组件标注对应现有 .vue 文件 |
| 用户拍板 | 用户在最后一次 attempt_completion 后回复 "OK / 通过" |
6.2 实施阶段（前端智能体交付）
每个子阶段（1-6）独立验收：
| 子阶段 | 关键验收点 |
|---|---|
| 1 视觉法典 | 自检页通过 / 6 主题切换正常 / Lighthouse 视觉一致性 ≥ 95% |
| 2 应用骨架 | 4 主 tab 路由通 / 6 主题在壳层全覆盖 / 无 console error |
| 3 侧栏与抽屉 | 9 个抽屉互斥切换 / Ctrl+\ 锁定切换 / 拖拽改宽度持久化 |
| 4 招牌页 | 4 hero demo 视觉一致性 ≥ 95% / 关键交互可用 |
| 5 Tuning + 浮窗 | 12 Tuning 全部能从流图开出 / 浮窗管理器 9 函数全可用 |
| 6 联调 + 打磨 | E2E 测试用例 ≥ 20 条全过 / 首屏 < 2s / 0 console error |
§7 风险与权衡
7.1 跳过 P-4 招牌页面（直接 P-3 → P-5）的代价
症状：前端智能体看 v0.3+ 框架 demo 写 4 主 tab 内部，每个 tab 风格不一致——XiStudio 用大圆角，XiForge 用小圆角；XiStudio 节点用阴影，XiForge 控件用边框；用户切 tab 时"像换了个产品"。
修复成本：联调期返工 2-3 周 → 总周期反而 +2 周，不如老实做 P-4。
7.2 选方案 B 深完整型的代价
症状：4-6 周设计期内产品需求变更（如新增 XiCloud tab、Tuning 浮窗形态调整、License 灰显规则修改），demo 全部返工。
修复成本：每次需求变更追加 0.5-1 周 → 高概率总周期 +2-3 周。
触发条件：仅在"产品需求已 100% 冻结、12 个月内不会改"时方案 B 才划算——我们显然不在此场景。
7.3 方案 C 的潜在风险与缓解
| 风险 | 缓解措施 |
|---|---|
| 前端智能体在"次要子 tab"自由发挥导致风格漂移 | 每个迭代节点（W4 / W6 / W8 / W10）设计师 review 一次，发现问题立即在 spec v1.0 增补条款 |
| spec v1.0 写得不够细 → 智能体询问轮次过多 | spec 必须包含"组件状态机图"和"API 契约 mock JSON"，把灰色地带提前消除 |
| 招牌页面 demo 选错（不是真正的"灵魂页"） | §4 已论证招牌选择，且 hero demo 本身只用 1.5 周——即使选错重做成本可控 |
| 现有 12 *TuningDialog 与新框架不兼容 | 在阶段 5 用 wrapper 适配，原 .vue 内容不动（已在 §5.3 阶段 5 明确） |
7.4 决策矩阵
| 你的情况 | 推荐方案 |
|---|---|
| 需求 100% 冻结、设计团队充足 | B |
| 时间极紧（< 8 周）、风格不那么重要 | A |
| 当前实际情况（用户单人主导 + 前端智能体团队 + 需求会迭代） | C ⭐ |
§8 立即行动清单（如果用户拍板方案 C）
8.1 本任务范围内（路线图文档完成）
- 创建
v3-frontend-implementation-roadmap.md（本文档） - 用
ask_followup_question让用户拍板方案 A / B / C - 用户拍板后，结束本 task，启动新 task 做 P-4 阶段
8.2 P-4 阶段新 task（用户拍板 C 后启动，不在本任务范围）
- W1 D1-D2：写
v3-hero-xistudio-graph.html（流图招牌页） - W1 D3-D4：写
v3-hero-xiforge-ui.html（UI 设计器招牌页） - W1 D5：用户 review 前 2 个 hero demo
- W2 D1-D2：写
v3-hero-xitune-chain.html（调音链招牌页） - W2 D3：写
v3-hero-xiprobe-batch.html（批量测试招牌页） - W2 D4-D5：重写
v3-implementation-spec.md为 v1.0 - W2 末：用户最终验收 P-4 整体交付
8.3 实施阶段（W3 起，前端智能体接手，不在本任务范围）
按 §5.3 的 6 个子阶段顺序执行，每个子阶段结束做一次设计师 review。
§9 附录
9.1 文档版本
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.0 | 2026-05-14 | 首版发布，承接 v0.3+ 框架 demo |
9.2 关联文档
v3-unified-macos.htmlv0.3+：当前框架级 demo（设计法典源头）v3-implementation-spec.mdv0.1：当前 spec 草稿（待 P-4 完成后重写为 v1.0）00-overview.md§4.1：产品概述中的 v3 综合方案入口brand-color-system v1.2：色板法典（不可修改）frontend_vue3/：现有 Vue 3 工程（42 个 .vue 组件，实施阶段复用）
9.3 术语表
| 术语 | 含义 |
|---|---|
| 设计法典 | 由 v0.3+ + brand-color-system 构成的"全局视觉/交互规范"，所有页面必须遵守 |
| 招牌页面（Hero Page） | 每个一级 tab 的"灵魂首屏"，承担"建立 tab 内部风格基准"的职责 |
| 悬浮抽屉模式 | 默认模式，抽屉浮在主画布上方但通过 inset 智能避让 |
| 锁定模式 | Ctrl+\ 切换，抽屉挤压主画布（VSCode 风） |
| 浮窗管理器 | 统一调度 Tuning 多开 + 辅助产品浮窗的 9 函数 API |
§10 用户决议（2026-05-14）：方案 B 深完整型 ✅
10.1 拍板结果
用户最终拍板：方案 B 深完整型（非 §3 推荐的方案 C）。
决策语境：用户作为单人产品负责人 + 待派的前端智能体团队，倾向于"先把所有页面 demo 做透，让前端智能体进入'翻译式实施'而非'创造性发挥'"——即用 4-6 周设计期换取更可控的实施期。
10.2 方案 B 完整 demo 清单（14 个页面）
按 §4 功能清单全展开，每个子 tab 都做完整 demo：
| # | 产品 | 子 tab | demo 文件名（建议） | 复杂度 | 工时 |
|---|---|---|---|---|---|
| 1 | XiStudio | ① 流图编辑 | v3-full-xistudio-graph.html |
🔴 高 | 2-3 天 |
| 2 | XiStudio | ② 调音视图 | v3-full-xistudio-tuning-view.html |
🟡 中 | 1-2 天 |
| 3 | XiStudio | ③ 仿真 | v3-full-xistudio-simulation.html |
🟡 中 | 1-2 天 |
| 4 | XiStudio | ④ 部署 | v3-full-xistudio-deploy.html |
🟢 低 | 1 天 |
| 5 | XiForge | ① UI 设计 | v3-full-xiforge-ui.html |
🔴 高 | 2-3 天 |
| 6 | XiForge | ② 算法源码 | v3-full-xiforge-source.html |
🔴 高 | 2-3 天 |
| 7 | XiForge | ③ 仿真测试 | v3-full-xiforge-test.html |
🟡 中 | 1-2 天 |
| 8 | XiTune | ① 调音链 | v3-full-xitune-chain.html |
🟡 中 | 1-2 天 |
| 9 | XiTune | ② 曲线对比 | v3-full-xitune-curves.html |
🟡 中 | 1-2 天 |
| 10 | XiTune | ③ ABX 盲测 | v3-full-xitune-abx.html |
🟢 低 | 1 天 |
| 11 | XiProbe | ① 频响测试 | v3-full-xiprobe-freq.html |
🟡 中 | 1-2 天 |
| 12 | XiProbe | ② THD+N | v3-full-xiprobe-thd.html |
🟡 中 | 1 天 |
| 13 | XiProbe | ③ SNR | v3-full-xiprobe-snr.html |
🟢 低 | 1 天 |
| 14 | XiProbe | ④ 批量测试 | v3-full-xiprobe-batch.html |
🟡 中 | 1-2 天 |
| 15 | — | spec v1.0 重写 | v3-implementation-spec.md（v1.0） |
🔴 高 | 3-5 天 |
| 16 | — | 空/错/加载态附录 demo | v3-states-empty-loading-error.html |
🟡 中 | 2 天 |
| 合计 | 22-32 天（约 4.5-6.5 周） |
10.3 方案 B 排期（按 5 周压缩 + 1 周缓冲 = 6 周）
| 周次 | 工作内容 | 交付物 | 中期 review |
|---|---|---|---|
| W1 | XiStudio 4 子 tab demo（高复杂度优先） | demo #1-4 | 周末用户 review |
| W2 | XiForge 3 子 tab demo（高复杂度密集） | demo #5-7 | 周末用户 review |
| W3 | XiTune 3 子 tab demo + XiProbe 前 2 个 | demo #8-12 | 周末用户 review |
| W4 | XiProbe 后 2 个 demo + 空/错/加载态附录 | demo #13-14 + #16 | 周末用户 review |
| W5 | spec v1.0 重写（覆盖所有 14 个 demo） | spec v1.0 | 用户 + 前端 TL 联审 |
| W6 | 缓冲：用户反馈整改 + 主题切换全量回归测试 | 全量交付 | 最终验收 |
关键里程碑： - W1 末：XiStudio 4 子 tab 全部 demo 完成（高频核心场景定调） - W2 末：XiForge 3 子 tab 全部 demo 完成（算法工程师场景定调） - W4 末：14 个 demo 全部完成 - W5 末：spec v1.0 完成 - W6 末：用户最终验收 P-4 整体交付，可启动前端智能体编码
10.4 方案 B 的红线约束（必须遵守）
- 冻结 v0.3+ 大框架：14 个 demo 共用同一份"3 行 4 列 grid + Activity Bar + 悬浮抽屉 + 6 主题"，禁止在 demo 里改大结构（避免 14 份不同骨架）
- 复用同一份 CSS 法典：所有 demo 内联引用同一份
<style>法典或抽取为共用xistudio-codex.css（避免 14 份 CSS 漂移） - 每个 demo 必须包含：
- 6 主题切换按钮（顶栏右侧）
- 与 v0.3+ 一致的红绿灯 + ☰ 菜单 + 4 主 tab + Activity Bar
- 子 tab 切换时高亮当前 demo 对应的子 tab
- 至少 1 个空状态 + 1 个加载态示意（在该 demo 内部）
- 风格一致性 review 节点：W1/W2/W3/W4/W5 周末必须 review，发现风格漂移立即修正
- 需求变更应对：W1-W5 期间若产品需求变更，由用户判断是"立即整改已完成 demo"还是"在剩余 demo 里直接采用新需求"
10.5 方案 B 落地风险提示（用户已知情）
| 风险 | 概率 | 影响 | 应对 |
|---|---|---|---|
| 需求在 5-6 周设计期内变更 | 🟡 中 | 高（demo 返工） | W3 末做一次需求冻结确认；变更只允许进未完成 demo |
| 14 个 demo 风格漂移 | 🟡 中 | 高（违背 demo 初衷） | 共用 CSS 法典 + 每周 review |
| spec v1.0 在 W5 才动笔，时间紧 | 🟢 低 | 中 | W1-W4 期间同步累计 spec 草稿，W5 收口而非从零写 |
| 用户疲劳（5 周连续 review） | 🟡 中 | 中 | 周末 review 形式简化为"截图 + 30 分钟语音" |
10.6 下一步行动（决议生效）
- 本 task 完成：路线图文档 v1.0 + §10 用户决议章节落盘
- 启动新 task：P-4 阶段 W1（XiStudio 4 子 tab demo）
- 第一步：用 v0.3+ 的 CSS 法典抽取为
xistudio-codex.css（共用样式表） - 第二步：写
v3-full-xistudio-graph.html（最复杂招牌页，定调 demo） - 第三步：依次完成 XiStudio 调音视图 / 仿真 / 部署 3 个 demo
- W1 末：用户 review 4 个 XiStudio demo
注：§3 / §5 / §6 / §8 章节中关于"方案 C"的描述保留为历史参考，不删除——便于未来追溯决策路径。最终执行以本 §10 章节为准。
文档结束。决议已固化为方案 B，下一步启动新 task 执行 W1。