DRAFT

XiStudio IDE 整体架构设计 · V1.2

⚠️ 架构断代声明：本文档基于 Xisound 产品矩阵 V1.2 七层架构。

废弃：./layout-demo/old/v3-implementation-spec.md 与 ./layout-demo/old/v3-style-skeleton-summary.md（已归档）中"XiStudio = 4 主 tab 之一（XiStudio/XiForge/XiTune/XiProbe）"的旧描述。

新事实： - XiStudio 是 IDE 容器外壳（不是某个 tab） - L4 Stage 子产品四件套（容器内中央主舞台）= XiLink / XiForge / XiTune / XiTest - XiCal / XiProbe / XiResBox / XiMic 角色变更为 L1 测试硬件辅助（驱动配置 / 通道控制悬浮窗），不占主舞台 - License 三元体系：IDE 容器 license + Stage license + Add-on license（XiMind 二元混合）

视觉/CSS 法典（brand-color v1.2 + macOS 9 关键点 + 骨架尺寸）继续沿用 xistudio-codex.css。本文档只重定义"产品架构层"和"模块挂载层"，不动视觉法典。

---

0. 一图概览（v1.2.2 顶栏 3 行 · 总顶部 104px）

┌──────────────────────────────────────────────────────────────────────────────┐
│ ① MenuBar       (28px)  traffic-lights · Logo · 9 菜单 · 主题 · License       │ ← VSCode 风第一行
├──────────────────────────────────────────────────────────────────────────────┤
│ ② StageBar      (44px)  ┃ 🔗 XiLink  🔨 XiForge  🎚 XiTune  🧪 XiTest  ┃ 工具组 · ⌘K ┃ ← Stage Pill + ToolBar 合一
├──────────────────────────────────────────────────────────────────────────────┤
│ ③ SubTabs       (32px)  随当前 Stage 联动（多文档 tab / 子视图 tab）           │ ← 子 tab
├──────────┬──────────────────────────────────────────────┬────────────────────┤
│          │                                              │                    │
│ ④ 左 Dock │           ⑤ Stage 中央主舞台                │     ⑥ 右 Dock      │
│  240 px  │           （4 主 DAW 的画布）                │     320 px         │
│          │                                              │                    │
│ 10 面板  │                                              │      9 面板        │
│ (按场景)  │                                              │     (按场景)       │
│          │ ⑦ BottomPanel  220 px                                              │
├──────────┴──────────────────────────────────────────────┴────────────────────┤
│ ⑧ StatusBar     (24px)  License 等级 · 引擎 LED · 设备状态 · 编译进度          │
└──────────────────────────────────────────────────────────────────────────────┘
       ↑ 辅助悬浮窗（XiCal / XiProbe / XiResBox / XiMic）独立于 IDE，可在屏幕任意位置

顶栏高度演进：

版本	MenuBar	StageTabs	ToolBar	SubTabs	总顶栏	节省
v1.2.1（4 行）	28	44	38	32	142px	—
v1.2.2（3 行）	28	44（合并 Pill+ToolBar）	—	32	104px	-38px

StageBar 内部分区（44px 单行）：

┌────────────────────────────────────────────────────────────────────────┐
│ [🔗 XiLink][🔨 XiForge][🎚 XiTune][🧪 XiTest] │ 文件 构建 编辑 视图 │ ⌘K │
│  ←——— 左侧 4 个 Stage Pill ———→            │  ← Stage 联动工具组 → │   │
└────────────────────────────────────────────────────────────────────────┘

• 左半：4 个 Stage Pill 胶囊（按 license 显示/灰显），激活态填充 --accent 实色
• 中间：1px 竖直分隔线 --line-soft + 8px padding
• 右半：当前 Stage 联动的工具组（文件 / 构建 / 编辑 / 视图，每组 3-4 按钮）+ 最右 ⌘K 命令面板触发器
• 响应式收缩：窗口宽度 < 1280px 时，工具组按钮 label 自动隐藏，仅留图标

容器与 Stage 的关系：

• XiStudio IDE Shell = 顶栏 + 双 Dock + 底栏 + StatusBar（永远存在）
• Stage 主舞台 = 中央画布区域，按当前激活的 DAW 切换内容
• license 启动重定向：用户 license 仅含 forge-pro → 启动直接进入 XiForge Stage，其他 Stage 灰显加锁

---

1. 与 V1.1 旧架构的对照表

维度	V1.1（旧 spec.md）	V1.2（本文档 · v1.2.2）	演进原因
XiStudio 角色	4 主 tab 之一（含 flow 子视图）	IDE 容器外壳	容器与 Stage 解耦，分别计费
主 tab/Stage 数量	4（XiStudio/XiForge/XiTune/XiProbe）	4（XiLink/XiForge/XiTune/XiTest）	XiLink 析出 + XiTest 替代 XiProbe
XiLink	不存在（是 XiStudio.flow）	L4 独立产品 P13	流图编辑职责独立 + 可独立采购
XiTest	不存在	L4 独立产品（替代 XiProbe 主 tab 角色）	"测试"职责需要独立 DAW 而非 Probe
XiProbe	L4 主 tab（含 freq/thd/snr/batch）	L1 输出声卡驱动（辅助悬浮窗）	角色降级为驱动配置工具
XiCal	spec 未涉及	L1 输入声卡驱动（辅助悬浮窗）	与 XiProbe 对偶
XiCore	L0 芯片落盘	L3 运行时框架（上移）	与 XiAlgo/XiVST 并列底层三件套
Dock 面板数	左 5 / 右 4	左 10 / 右 9（A 选项收敛后）	场景化大幅扩展，Minimap 内嵌 XiLink Stage
顶栏行数 / 高度	4 行 / 142px	3 行 / 104px（v1.2.2 压缩）	StageTabs+ToolBar 合并为 StageBar 单行
视觉法典	brand-color + macOS 9 点	沿用不变	✅ 法典不动
骨架宽度	240/1fr/320	沿用不变	✅ 双 Dock 宽度不动

结论：V1.2 是产品架构断代，但视觉法典兼容——xistudio-codex.css 继续有效，新 demo 只需替换顶栏布局（4→3 行）+ 重排 Dock 面板挂载。

---

2. 顶栏设计（① MenuBar + ② StageBar 合并行 + ③ SubTabs）

v1.2.2 顶栏重构（A 选项 · 2026-05-17）

原 v1.2.1 设计的 ② StageTabs（44px） + ③ ToolBar（38px）合并为单行 ② StageBar（44px），节省垂直空间 38px。SubTabs 编号从 ④ 调整为 ③。

2.1 ① MenuBar（28px · VSCode 风菜单）

区位	元素	备注
左	macOS traffic-lights（红/黄/绿）	12px × 3，沿用 macOS 法典
左中	Logo ◆ XiStudio	--accent 色
中	9 菜单项	文件 / 编辑 / 视图 / 项目 / 构建 / 调试 / 工具 / 窗口 / 帮助
右	License 等级 tag	Community / Pro / Enterprise 玫瑰金/曦紫/极光青三色区分
右	AI 状态 tag	XiMind 在线 / 离线
右	主题切换按钮 🎨	6 主题 popover

license 联动：MenuBar 上 License tag 点击 → 弹出 LicenseDialog 显示当前授权矩阵（容器 + 各 Stage + Add-on）。

2.2 ② StageBar（44px · Stage Pill 左 + ToolBar 右 · 合并行）

左半区 · 4 个 Stage Pill 胶囊：

顺序	图标	名称	关联产品	License key	默认
1	🔗	XiLink	P13-xilink (L4)	xilink-pro（Community 含 xilink-view-only）	✅
2	🔨	XiForge	P9-xiforge (L4)	xiforge-pro	❌ 独立购买
3	🎚	XiTune	P6-xitune (L4)	xitune-pro（含 xitune-reverse add-on）	❌ 独立购买
4	🧪	XiTest	P7-xitest (L4)	xitest-pro（4 子 tab 共享 license）	❌ 独立购买

Pill 胶囊样式：border-radius: 999px 激活态填充 --accent 实色（沿用 macOS 法典关键点 #9）；高度 32px，垂直居中于 44px 行。

未授权 Stage：灰显 + 🔒 图标，点击触发 Toast 提示 "License 未授权，无法进入 XiForge"。

右半区 · ToolBar 工具组（随当前 Stage 联动）：

Stage	工具组 1	工具组 2	工具组 3	工具组 4
XiLink	文件（新建/打开/保存）	构建（编译/运行/停止/烧录）	编辑（撤销/重做）	视图（链路/调音/测试/部署）
XiForge	文件	构建（生成 VST/VST3/AU）	编辑	视图（设计/源码/仿真）
XiTune	文件	调音（正向/反向）	A/B（保存/对比）	视图（链路/曲线/ABx）
XiTest	文件	测试（启动/停止/批量）	报告（导出 PDF/CSV）	视图（单测/集成/硬件）

最右侧 ⌘K = 命令面板触发器（全 Stage 通用），按钮宽度固定 36×32，hover 显示快捷键提示。

响应式策略（窗口宽度从 1920 → 1280 → 960）：

宽度区间	Stage Pill	工具组	⌘K
≥ 1280px	完整图标+文字	图标+文字	完整
960–1280px	完整图标+文字	仅图标（label tooltip）	完整
< 960px	仅图标 + popover 列表	折叠为「⋯」溢出菜单	完整

license 启动重定向：

启动时调用 useLicense.fetch()
  → 获取 tiers[]
  → 计算 enabledStages
  → if (enabledStages.length === 1) router.replace('/' + enabledStages[0])
  → else 默认进入 XiLink（最常用）

2.3 ③ SubTabs（32px · 子视图切换）

随当前 Stage 渲染 children 路由表：

Stage	SubTabs	路由
XiLink	主图 / 子图 / 多图（多文档 tab）	/xilink/main / /sub/{id} / /multi
XiForge	模块设计 / VST 创建 / 调音界面 / 源码生成	/xiforge/module / /vst / /tune-ui / /source
XiTune	正向调音 / 反向调音	/xitune/forward / /reverse
XiTest	单体冒烟 / 链路 e2e / 算力 / 硬件指标	/xitest/unit / /e2e / /perf / /hw

---

3. 中央主舞台 · 4 Stage 详细设计（⑤ Stage 区）

3.1 🔗 XiLink Stage（链路搭建 · L4）

核心职责：可视化流图画布，搭建算法链路。

视图模式：

• 主图模式：单一 .xilink 文件，全屏画布
• 子图模式：进入某个 module 内部查看子链路（双击节点钻入）
• 多图模式：多个 .xilink 文件 tab 并列（如 main_chain.xilink + subwoofer.xilink）

画布要素：

• 节点拖拽 / 端口连线 / Bezier 曲线 / Multi-select
• Minimap 缩略图（右下角）
• 自动布局（Dagre / Force-directed）
• 多文档 tab 顶部
• 撤销栈 ≥ 50 步

节点来源：

• XiAlgo IP 库（自研算法 modules）
• XiVST Marketplace（第三方 VST/VST3）
• XiForge 自定义模块（用户在 XiForge 里创建的）

编译目标：

• XiDSP-D1/D2/D3/D4/A1（自研芯片，5 档算力）
• WASM（桌面仿真，开发期实时听）

文件格式：.xilink（JSON-based，可包含多链路、多版本快照）。

双击节点交互：

• 双击 → 打开对应 Tuning 浮窗（GEQ/PEQ/Mixer/Limiter ...）
• 浮窗跨 Stage 持续存在，最小化进 BottomPanel 托盘

3.2 🔨 XiForge Stage（模块/VST/UI 设计器 · L4）

核心职责：自定义算法模块开发 + VST 插件生成 + 调音 UI 设计。

4 子视图（SubTabs）：

SubTab	功能	输出
模块设计	DSP 算法模块 IP 创建（拖拽 DSP 原语：滤波/FFT/卷积/动态）	.ximodule 模块文件
VST 创建	把模块封装为 VST/VST3/AU 插件	.vst3 / .dll / .component
调音 UI	控件库拖拽（旋钮/滑块/示波器）→ 生成调音对话框	.xiui UI 描述文件
源码生成	从模块图生成 C/C++/Rust 源码 + 编译	.c/.cpp/.h + 编译产物

关键控件库（左 Dock L7 通用界面控件库）：

• TT 系列：TTButton / TTLabel / TTSlider / TTToggle / TTKnob / TTMeter / TTScope
• 数据绑定控件：TTLabelComboBox / TTProgressBar / TTChartTable
• 高阶控件：TTMixerWidget / TTGGEQWidget / TTSpectrumWidget

3.3 🎚 XiTune Stage（专业调音 · L4）

核心职责：声音调音专用工具，正向/反向双模式。

2 子视图（SubTabs）：

SubTab	模式	工作流
正向调音	算法 → 参数	选择算法链路 → 手动/自动调参 → 实时听 → A/B 对比 → 保存档案
反向调音	目标声 → 算法+参数	上传目标车内声音 / 录音 → AI 分析（XiMind 驱动）→ 反推链路结构 + 参数 → 一键应用

反向调音的革命性：传统调音工程师靠耳朵 + 经验调上千参数；反向调音让用户只需提供"想要什么样"，AI 推算出"怎么实现"。

A/B 对比：所有调音操作支持 A/B 双状态切换，秒级回滚。

3.4 🧪 XiTest Stage（自动化测试 · L4 · D1 不拆分）

核心职责：从算法理论验证到硬件指标测试的全链路自动化测试平台。

4 子视图（SubTabs · D1 不拆分方案）：

SubTab	测试方向	典型场景	Add-on license
单体冒烟	算法单元测试	给定输入波 → 验证算法输出符合理论模型（Pass/Fail）	xitest.unit-only
链路 e2e	链路集成测试	验证整条 .xilink 链路在 XiCore 运行时的正确性	xitest.e2e-only
算力测试	性能基准测试	测算 MIPS / 内存 / 时延，对比 XiDSP-D1~D4 算力档位	xitest.perf-only
硬件指标	XiAmp/XiBox 硬件	频响 / THD / SNR / 串扰 / 通道平衡（接 XiResBox 校准夹具）	xitest.hw-only

测试流水线：

算法理论验证（单体冒烟）
    ↓
模块集成测试（链路 e2e）
    ↓
音响系统整体集成测试（链路 e2e + 算力测试）
    ↓
调音测试（XiTune A/B 持续记录）
    ↓
硬件指标终检（硬件测试 + XiResBox 夹具）

XiTest D1 决策回顾（已锁定）

3 方案对比（详见 §10 决策点 1）：

方案	描述	推荐度
D1 不拆分 ✅	单一 XiTest 内 4 子 tab + 4 个 add-on license（细粒度商业化）	⭐⭐⭐⭐
D2 拆 2 件套	XiTest（链路+算法+算力）+ XiHwTest（硬件）	⭐⭐⭐
D3 拆 3 独立	XiTest-Algo / XiTest-Chain / XiTest-Hw	⭐⭐

采用 D1 的核心理由：测试是连贯流水线（单测→e2e→硬件，工程师一天跨多 tab）；数据共享需求强；license 简化（一个 xitest-pro 一票通行 + add-on 细分商业化）；UI 一致性高（4 子 tab 共享同一 Stage 外壳，开发成本低 75%）。

---

4. 双 Dock 系统（④ 左 + ⑥ 右）

4.1 设计原则

• Dock 面板按场景挂载：每个 Stage 激活时，自动显示该 Stage 相关的 Dock 面板，无关面板隐藏（节省视觉空间）
• Dock 面板可拖动重排：用户可调整 Dock 面板顺序（保存到 localStorage）
• Dock 面板可折叠：每个面板有 ▼/▶ 折叠按钮
• Dock 面板可外置浮窗：右键 → "弹出为悬浮窗"

4.2 ④ 左 Dock（10 面板，宽 240px · A 选项收敛后）

#	面板	关联 Stage	用途
L1	Workspace 链路工程管理	XiLink / XiTune / XiTest	多个 .xilink 项目树
L2	IP 插件管理	XiLink / XiForge	XiAlgo + XiVST + 自定义 IP 索引
L3	通信连接路由管理	全 Stage	串口/USB/网络/蓝牙设备路由（含 XiDSP-Link 烧录通道）
L4	声音引擎管理	全 Stage	XiCore Runtime 实例（启停、采样率、buffer size）
L5	音效模式管理	XiTune	预设模式（夜晚/会议/影院/驾驶）切换
L6	Workspace IPVSP 工程管理	XiForge	XiForge 项目树（模块/VST/UI 设计器）
L7	通用界面控件库	XiForge	TT 系列控件 + 自定义控件，拖拽到画布
L8	XiForge 素材版本管理	XiForge	素材 git 版本（图标/字体/示意图）
L9	调音工程管理	XiTune	调音项目树（每个项目含算法链 + 参数集）
L10	调音用户档案	XiTune	用户偏好档案（喜欢哪种声音、A/B 历史）

左 Dock 收敛说明（A 选项 · 2026-05-17）： 原 v1.2.0 草案的 L10 "链路流图 Dock 版"被移除——它与 XiLink Stage 主舞台职能重复。链路缩略图改为 XiLink Stage 内部覆盖层（Minimap），由 Stage 自身渲染（参见 §3.1）。 XiTune Stage 需要查看链路时，可右键 L1 Workspace 中的 .xilink 文件 → "弹出为悬浮缩略图"，达成同等效果而不占 Dock 槽位。 总左 Dock 槽位 11 → 10。

4.3 ⑥ 右 Dock（9 面板，宽 320px）

#	面板	关联 Stage	用途
R1	通道频响曲线	XiTune / XiTest	实时频响（per channel）
R2	通道相位曲线	XiTune / XiTest	相位响应（per channel）
R3	通道 RMS 电平表	XiTune / XiTest	LUFS / Peak / RMS 三表
R4	Transfer 对比曲线	XiTune	类比 SMAART：选 2 个通道 → 频响差 / 时延 / 相位差 / 一致性
R5	部署	XiLink	编译产物 → 烧录到 XiDSP / 推送到云
R6	辅助产品参数设置	全 Stage	XiCal / XiProbe / XiResBox / XiMic 等辅助硬件配置入口
R7	XiForge 控件数据属性	XiForge	选中控件的 props/绑定/事件
R8	链路 Module 属性	XiLink	选中节点的参数 inspector
R9	XiForge Module 属性	XiForge	选中模块的 IO/算法参数

4.4 Stage × Dock 联动矩阵（核心）

┌─────────┬──────────────────────────────┬──────────────────────────┐
│ Stage   │ 左 Dock 显示                 │ 右 Dock 显示             │
├─────────┼──────────────────────────────┼──────────────────────────┤
│ XiLink  │ L1 L2 L3 L4                  │ R5 R6 R8                 │
│ XiForge │ L2 L6 L7 L8                  │ R6 R7 R9                 │
│ XiTune  │ L1 L3 L4 L5 L9 L10           │ R1 R2 R3 R4 R6 R8        │
│ XiTest  │ L1 L3 L4                     │ R1 R2 R3 R6              │
└─────────┴──────────────────────────────┴──────────────────────────┘

A 选项联动差异说明： - XiLink 不再挂"链路流图 Dock 版"（已收敛进 Stage Minimap） - XiTune 联动从 7 个 dock 降到 6 个（同样移除"链路流图 Dock 版"）

切 Stage 时 Dock 面板淡入淡出（200ms ease）。用户可手动取消联动锁，让所有 Dock 面板永远显示（但默认是联动模式）。

---

5. 底栏（⑦ BottomPanel · 220px · 跨 Stage 共享）

#	Tab	用途
B1	构建	编译进度 / 错误列表 / 编译产物路径
B2	问题	链路问题 / 模块警告 / Lint 错误
B3	终端	集成 PowerShell / bash 终端
B4	日志	XiCore 运行时日志 / API 调用日志
B5	🤖 XiMind	AI 助手对话窗口（自然语言 → 链路操作 / 调音建议）
B6	🪟 Tuning 托盘	当前所有 Tuning 浮窗的最小化列表（计数）

XiMind 对话窗口示例：

• 用户："给我加一段 PEQ，重点压制 200-500Hz 的浑浊"
• XiMind：解析意图 → 在当前 XiLink 链路插入 GEQ 节点 → 设置 200-500Hz 增益 -3dB → 弹出 Tuning 让用户微调

---

6. 辅助悬浮窗（L1 测试硬件四件套 · 独立于 IDE 主窗口）

L1 测试硬件四件套（XiCal / XiProbe / XiResBox / XiMic）不在主舞台，而是独立可拖拽悬浮窗，可放在屏幕任意位置（甚至跨显示器）。

为什么 XiBox / XiAmp 不在此列（A 选项 · 2026-05-17）

XiBox / XiAmp 是 L2 量产硬件（车规功放 / 算法盒），它们是 XiStudio 的烧录目标设备，不是测试工具。

其在 IDE 内的呈现入口是 左 Dock L3「通信连接路由管理」+ 右 Dock R5「部署」，不需要独立悬浮窗。

悬浮窗专门给 L1 测试硬件用——这些设备需要参数化配置面板（声卡驱动 / 通道映射 / 负载阻值 / 麦克风阵列），且常常与主舞台并行操作（边调音边监看采集），独立悬浮窗形态最贴合工作流。

工具	角色	触发位置	配置内容
XiCal	多路数字麦采集系统驱动配置	StatusBar 右侧设备图标 → 选 XiCal	通道数（8/16/32）/ 采样率 / 时间同步 / 通道映射
XiProbe	音响系统下行电信号收录驱动配置	StatusBar 右侧设备图标 → 选 XiProbe	采样率 / 触发模式 / 通道阻抗匹配 / 量程
XiResBox	可编程多通道电阻负载控制台	XiTest Stage 右 Dock R6 辅助产品	24 通道阻值矩阵 / 预设场景 / 远程切换
XiMic	高精度数字麦克风阵列配置	XiCal 悬浮窗内嵌 + XiTune Stage R6	麦克风序列号 / 校准曲线 / 灵敏度 / I²S/TDM 通道

悬浮窗规范：沿用 tuning-dialog 外壳（traffic-lights + 拖拽 + 圆角 14px + shadow-lg），但：

• 默认位置在屏幕右下角而不是中央
• 不进入 BottomPanel Tuning 托盘（独立管理）
• 关闭即销毁实例（不像 Tuning 那样持久化）
• 多设备并存时使用「设备图标 → popover 列表」收纳，避免屏幕挤占

与产品矩阵 V1.2 §3.5 对齐：本节四件套清单 = 产品矩阵 V1.2 L1 测试硬件辅助生态 完全一致。

---

7. License 联动矩阵（核心商业模型 · 三元体系）

7.1 三元 License 体系（含 XiMind 二元混合）

IDE 容器 License（必需）      Stage 子产品 License（可选叠加）       Add-on License（细粒度）
┌────────────────────┐         ┌─────────────────────────┐         ┌───────────────────────┐
│  Community  (免费) │         │  xilink-view-only (赠送)│         │  xitune-reverse        │
│   含 xilink-view-  │   +     │  xilink-pro             │   +     │  xilink-multi-doc      │
│   only 默认赠送    │         │  xiforge-pro            │         │  xitest.unit-only      │
│  Pro        (¥XXX) │         │  xitune-pro             │         │  xitest.e2e-only       │
│  Enterprise (¥YYY) │         │  xitest-pro             │         │  xitest.perf-only      │
└────────────────────┘         └─────────────────────────┘         │  xitest.hw-only        │
                                                                   │  ximind-pro (高级 AI) │
                                                                   └───────────────────────┘

关键规则：

• 容器 license 必有，决定整个 IDE 能否启动
• Stage license 决定能进入哪些 Stage（未授权灰显加 🔒）
• Add-on license 决定 Stage 内某些子功能是否解锁
• XiMind 二元混合（决策 4 锁定）：基础对话能力嵌入式内置（Pro 起免费送）；高级能力（自动链路生成、车端数据回传分析、Token 重度场景）独立 ximind-pro

7.2 4 个典型客户场景

客户类型	License 组合	启动后默认 Stage
车企调音工程师	Pro + xitune-pro + xitune-reverse	XiTune（反向调音解锁）
VST 插件开发者	Pro + xiforge-pro	XiForge
算法研究员	Pro + xilink-pro + xitest-pro + ximind-pro	XiLink ↔ XiTest 来回切，AI 全开
完整集成商	Enterprise（含全部 Stage + 全 Add-on）	XiLink（默认）

7.3 路由守卫实现

router.beforeEach((to, from, next) => {
  const lic = useLicenseStore()
  const required = to.meta.license as string | undefined
  if (required && !lic.has(required)) {
    showToast(`License "${required}" 未授权`)
    return next(false)
  }
  next()
})

每个 Stage 路由 = () => import(...) 异步 chunk，未授权用户根本不下载该 Stage 的 JS（代码层隔离 + 防破解）。

---

8. ⑧ StatusBar（24px · 全局状态）

区位	元素	联动
左 1	License 等级 + 过期天数	容器 license tag
左 2	XiCore 引擎 LED（绿/黄/红）	引擎运行状态
左 3	当前采样率 / 缓冲区大小	引擎参数
左 4	设备列表（XiCal/XiProbe/XiResBox/XiMic 微图标）	已连接设备数（点击呼起对应悬浮窗）
中	编译进度条	仅编译期间显示
右 1	XiMind 在线状态	AI 服务连接
右 2	当前 Stage 名	与 ② StageBar 同步
右 3	当前用户 + 头像	登录状态

---

9. 与 V1.1 demo 的演进/迁移路径

V1.1 已有 11 个 v3-full-* HTML demo（已全部归档到 ./layout-demo/old/）。V1.2 新 demo 重构计划：

V1.1 demo（已归档 old/）	V1.2 处置	动作
v3-full-xistudio-graph.html	改名为 stages/stage-xilink.html	XiLink 主图视图（Stage 片段，不带 shell）
v3-full-xistudio-tuning-view.html	拆分到 stages/stage-xitune.html	XiTune Stage 主视图
v3-full-xistudio-simulation.html	改名为 stages/stage-xitest-perf.html	XiTest.算力测试子 tab
v3-full-xistudio-deploy.html	拆分到 docks/dock-deploy.html（R5）	部署移到右 Dock
v3-full-xiforge-*.html (3)	整合到 stages/stage-xiforge.html	XiForge Stage 4 子 tab 单文件
v3-full-xitune-*.html (3)	整合到 stages/stage-xitune.html	重构为正向/反向 2 SubTab
v3-unified-macos.html	升级为 index.html（新 shell 容器）	顶栏 4→3 行，挂载 stages + docks

新 demo 文件结构（v1.2.2 起）：

layout-demo/
├── index.html                  ← 新 shell 容器（顶栏 3 行 + 双 Dock + Bottom + Status）
├── shell.js                    ← Stage 路由 + Dock 注册 + license mock
├── xistudio-codex.css          ← 视觉法典（沿用，1212 行）
├── stages/
│   ├── stage-xilink.html       ← XiLink 主舞台（Stage 片段）
│   ├── stage-xiforge.html
│   ├── stage-xitune.html
│   └── stage-xitest.html
├── docks/
│   ├── dock-project.html       ← L1 项目树
│   ├── dock-xialgo-library.html ← L2 IP 库
│   ├── dock-link-inspector.html ← R8 链路属性
│   └── ... (其余 Dock 按需补)
├── dialogs/                    ← 二级浮窗（PEQ/Mixer Tuning）
├── README.md                   ← 新 demo 说明 + 与 old/ 的关系
└── old/                        ← 18 个 v1.1 demo 归档
    ├── v3-full-*.html (11)
    ├── v3-unified-macos.html
    ├── product-entry-map.html / themes*.html / index.html
    └── v3-*.md (3)

新增 demo 优先级（W4-W5）：

优先级	文件	内容
🔴 P0	index.html + shell.js + stages/stage-xilink.html	最小可演示集（验证 shell-stage-dock 三层组合调用）
🔴 P0	docks/dock-project.html + dock-xialgo-library.html + dock-link-inspector.html	XiLink Stage 联动 dock
🟡 P1	stages/stage-xitest.html（4 子 tab）	XiTest 全套（D1 不拆分方案验证）
🟡 P1	stages/stage-xitune.html（正向+反向 2 子 tab）	XiTune 反向调音
🟢 P2	dialogs/aux-xical.html + aux-xiprobe.html + aux-xiresbox.html + aux-ximic.html	L1 测试硬件四件套悬浮窗
🟢 P2	stages/stage-xiforge.html（4 子 tab）	XiForge 完整设计器

---

10. 关键决策记录（已锁定 · 2026-05-17）

用户已确认所有 4 个决策点（A 选项）

本节原为待决策清单，2026-05-17 用户审阅后全部锁定为如下结论。后续若需变更，请新建 ADR 而非修改本节。

#	决策点	锁定结论	影响章节
1	XiTest 拆分	✅ D1 不拆分：单一 XiTest Stage + 4 子 tab（单体冒烟 / e2e 集成 / 算力 / 硬件指标）。子 tab 可配 add-on license（如 xitest.unit-only）实现细粒度商业化，但代码库不分仓	§3.4 / §7.1
2	L1 测试硬件四件套	✅ XiCal / XiProbe / XiResBox / XiMic（与 product-matrix V1.2 §3.5 一致）。XiBox / XiAmp 是 L2 量产硬件，不属于测试工具，不进 IDE 悬浮窗	§6 / §1 对照表
3	XiLink Community 查看权	✅ 默认含 xilink-view-only：Community 容器 license 自动赠送只读权限（仅可查看 1 个 chain，不可编辑/编译）。Pro 起解锁 xilink-pro 完整编辑能力	§2.2 / §7.1
4	XiMind license 归属	✅ 二元混合：基础对话能力嵌入式内置（Pro 起免费送）；高级能力（自动链路生成、车端数据回传分析、Token 重度场景）独立 ximind-pro 三元 license。商业模式上仍归 V1.2 矩阵 §5.1 云服务收入项	§7.1

决策追溯链

• 用户原始反馈：2026-05-17 14:13（产品矩阵 V1.2 落地后的 IDE 整体设计审阅）
• 主智能体修订建议：2026-05-17 16:13（4 处大纲修订 + 4 决策点表态）
• 用户最终确认：2026-05-17 16:18（A 选项 · 全采纳）
• 顶栏压缩追加（v1.2.2）：2026-05-17 16:53（StageTabs+ToolBar 合并 → StageBar）

---

11. 一句话总览

V1.2.2 = XiStudio 是 IDE 容器，里面装 4 个独立的 L4 Stage（XiLink / XiForge / XiTune / XiTest），每个 Stage 单独计费。 顶栏 3 行（MenuBar 28 + StageBar 44 含 Pill+ToolBar 合并 + SubTabs 32）= 104px 总顶部 + 状态栏 24px = 128px（v1.2.2 较 v1.2.1 节省 38px）。 双 Dock 19 面板（左 10 + 右 9 · A 选项收敛后）按 Stage 智能联动显隐。 底栏 6 tab（构建 / 问题 / 终端 / 日志 / XiMind AI / Tuning 托盘）跨 Stage 共享。 L1 测试硬件四件套（XiCal / XiProbe / XiResBox / XiMic）= 独立悬浮窗，不占舞台；XiBox / XiAmp 是 L2 烧录目标，由左 Dock L3 通信路由 + 右 Dock R5 部署接管。 License 体系：容器 + Stage + Add-on 三元结构（XiMind 二元混合：基础内置 / 高级独立 ximind-pro）。

接下来按 §9 demo 优先级清单逐个落地，先 P0（shell + XiLink Stage + 3 dock）验证组合调用机制。

v1.2.3-impl 增补（2026-05-19 · §13 完整描述）：顶栏 StageBar 演进为五段动态注入架构——Stage Pills | mode-switcher | stageToolbar | Shell 通用按钮组（🤖/🪟/🔒/🎨）| (sub-tabs-bar 行 2 仅 XL/XT)，其中 mode-switcher 由 stage 按子主界面动态注入（XF 3 / XT 4 / XL 0）、stageToolbar 按 stage + mode 双维度动态注入（XF.layout 4 / XF.simulation 0 / XL 5 / XT 3）。新增 Shell 全局单例引擎（_engineRunning，XL/XT 共享 ▶/■ toggle 状态）。Drawer 双 dock 边界进一步明确：内容由 stage 注入（dock-inject 协议 7+3+3+0）· 操作（dock 位置切换 / 1-2-3-4 比例 / 横纵分屏 / resize / locked-float 模式 / 持久化）由 Shell 统一接管。详见 §13。

---

XiStudio IDE 架构 v1.2.3-impl · 2026-05-19 · 基于产品矩阵 V1.2 七层架构 · 4 决策点已锁定 · 顶栏 4→3→五段注入演进 · v4.3 stageToolbar 机制落地（layout-demo 12 commit）

---

12. 实现成果沉淀（v1.2.2-impl · 2026-05-17 layout-demo 11 commit）

本章为 §0–§11 架构决策的实现层补充

§0–§11 锁定的是架构决策与边界；本章沉淀 layout-demo/ 11 个 commit 落地的具体机制、协议、IPC、持久化、ADR——是"骨架（vanilla HTML/CSS/JS demo）→ 框架（Vue 3 改造）"之间的实现规约。

12.1 Shell 与 Stage 的运行时边界（操作系统 vs 应用程序）

层	角色	持有内容	实现位置
Shell	操作系统底座（容器框架）	MenuBar / 4 Pill StageBar / 左右 Activity Bar / Drawer 框 / Bottom 框 / StatusBar / Lock / 主题 / 浮窗管理器 / 基础设施连接监控 / 窗口管理器（locked/float/resize/split/dock 位置/持久化）/ 跨 Stage 共享浮窗（Tuning Dialog）	layout-demo/index.html（~2400 行）
Stage	应用程序（业务内容）	XiLink / XiTune / XiForge / XiTest 各自的画布、列表、SVG、KPI、调音曲线	layout-demo/stages/stage-{xilink,xitune,xiforge,xitest}.html

关键约束： - Shell 不知道 Stage 内部业务，只提供"槽位"（toolbar / status / hint / inspector / module-properties / drawer title） - Stage 不直接操作 Shell DOM，全部通过 postMessage 协议注入内容 - 每个 Stage 是独立 iframe HTML，通过 STAGE_SRC 映射动态加载到中央 Stage 区 - 架构中性证明：3 个新 Stage（XiTune/XiForge/XiTest）依次接入，无需改 Shell 一行代码——证明 plug-in 边界正确

12.2 4 Pill plug-in 架构（iframe 动态加载）

┌─ STAGE_SRC 映射表（Shell 内置） ───────────────────────┐
│ const STAGE_SRC = {                                    │
│   xilink:  './stages/stage-xilink.html',               │
│   xitune:  './stages/stage-xitune.html',               │
│   xiforge: './stages/stage-xiforge.html',              │
│   xitest:  './stages/stage-xitest.html'                │
│ }                                                       │
└────────────────────────────────────────────────────────┘
              │
              ▼ switchStage(key)
┌─ Pill 点击 ──────────────────────────────────────────┐
│ 1. 高亮目标 Pill / 取消其他 Pill 激活态              │
│ 2. 设置 #stageFrame.src = STAGE_SRC[key]             │
│ 3. iframe 加载完毕 → Stage 自动 postMessage          │
│    'stage-ready' 通知 Shell                          │
│ 4. Shell 清空所有"上一个 Stage 注入"的槽位内容        │
│ 5. Stage 按需重新注入 toolbar/hint/status/inspector  │
└──────────────────────────────────────────────────────┘

未授权 Pill：保持 🔒 图标 + 灰显 + click → toast，不触发 switchStage。

v1.2.2-impl 全 4 Pill 解锁（commit 808531d）：四个 Pill 全部可点击切换，不再只有 XiLink 一个解锁——为后续 license 守卫接管做好"开关位"。

12.3 postMessage 协议（Stage ↔ Shell · 9 类 IPC 完整规范）

12.3.1 Stage → Shell 8 类消息

消息类型	数据契约	Shell 处理
stage-ready	{ stage, version }	标记 Stage 启动就绪，可发后续消息
toolbar-inject	{ stage, buttons:[{id,icon,label,tip}] }	渲染 StageBar 右半区工具组（按 id 反查响应回调）
stage-status	{ stage, html }	注入 StatusBar #stageStatusSlot（Stage 附加状态）
stage-hint	{ stage, html }	注入 BottomBar 右侧 #stageHintSlot（快捷键提示）
select-node	{ stage, node, label }	节点选中事件 → Shell 更新右 Drawer 标题为 label
tuning-dialog	{ stage, module, label }	拉起跨 Stage 共享的 Tuning Dialog 浮窗（PEQ 调参）
show-toast	{ stage, message }	Stage 请求 Shell 显示 toast（统一 UI）
inspector-inject	{ html, module }	注入右 Drawer Inspector 子内容（v3.4 边界修正）
module-properties-inject	{ html, module }	注入 Bottom 属性 tab 子内容（v3.4 边界修正）

注：inspector-inject / module-properties-inject 是 v3.4 新增——之前 Shell 直接渲染 Inspector / 属性，导致 Stage 切换时残留旧 Stage 的内容。修正为"Shell 提供空槽 + 协议提示"，全部由 Stage 注入。

12.3.2 Shell → Stage 反向消息

消息类型	数据契约	Stage 处理
subtab	{ subtab }	Shell 切 SubTab 通知 Stage（Stage 切换内部子视图）
toolbar-click	{ stage, id }	顶栏工具按钮被点击的回调（按 id 派发到 Stage 内部 handler）

12.3.3 安全与可演进性

• 来源校验：Shell 校验 event.source === stageFrame.contentWindow，防止跨 iframe 注入
• stage 字段：所有消息携带 stage: 'xilink'|'xitune'|'xiforge'|'xitest'，Shell 可丢弃非当前 Stage 的消息
• 版本号：stage-ready 必带 version，未来协议升级时 Shell 可按版本路由

12.4 VSCode 式窗口管理（locked / float / resize / split / dock 位置 / 持久化）

12.4.1 模式

模式	行为	切换
locked	Drawer/Bottom 占据 grid 槽位，挤压中央 Stage 区域（VSCode 默认）	.ide.locked 类
float	Drawer/Bottom 浮在 Stage 之上，Stage 区域不变（macOS 风）	移除 .ide.locked 类

12.4.2 Drawer Dock 位置切换（4 位置 · 3 比例）

Dock 位置	槽位映射	默认比例	可选比例
left	grid actL/body	¼	½ · ⅓ · ¼
right	grid body/actR	¼	½ · ⅓ · ¼
top	grid topbar/body	⅓	½ · ⅓ · ¼
bottom	grid body/bottom	⅓	½ · ⅓ · ¼

dock-icon 单击切换 bug 修复（v3.4 / commit a6babfb）： - 旧逻辑：第二次点击同一 dock-icon 才切换内容（首次只激活） - 修正：drawer.dataset.activeKey 跟踪当前激活面板，单击即切换 + toggle off

12.4.3 Bottom Tab 互斥显示（VSCode terminal/output 风）

• 同一时刻只显示一个 Bottom tab 的内容（构建/问题/终端/日志/属性）
• 切 tab 时旧内容隐藏，新内容显示——通过 .bottom-pane.active 类切换
• 对应 v3.2 commit 71d9e8c

12.4.4 持久化

• localStorage key：xistudio-layout-v1
• 持久字段：
• stage（当前激活 Stage key）
• drawerLeft.{visible, dockPos, ratio, activeKey}
• drawerRight.{visible, dockPos, ratio, activeKey}
• bottom.{visible, ratio, activeKey}
• locked（boolean）
• theme（主题 key）
• 启动时 Shell 读取该 key 还原布局；用户每次操作即时写回（debounce 300ms）

12.5 Drawer / Bottom 内容注入边界（v3.4 修正后）

┌─ Drawer Header ─────────────────────────────────────┐
│ Title（grid 两行 · row1 主标题 / row2 副标题截断）   │ ← Shell 渲染
│ Pin / Float / Dock 切换按钮                          │ ← Shell 渲染
├─ Drawer Body ───────────────────────────────────────┤
│  ┌─ Tab Bar ────────────────────────────────────┐   │ ← Shell 渲染
│  │ 项目树 / Inspector / 库 / ...                │   │
│  ├─ Tab Pane: 项目树 ──────────────────────────┤   │ ← Shell 渲染（静态）
│  ├─ Tab Pane: Inspector ──────────────────────┤   │
│  │  [空槽 #inspectorSlot · 等待 Stage 注入]    │   │ ← Stage 通过 inspector-inject
│  └────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

┌─ Bottom Tab Bar ────────────────────────────────────┐
│ 构建 / 问题 / 终端 / 日志 / 属性                     │ ← Shell 渲染
├─ Bottom Pane: 构建 ────────────────────────────────┤
│ Shell 自渲染（编译进度/错误列表）                    │
├─ Bottom Pane: 属性 ────────────────────────────────┤
│ [空槽 #modulePropertiesSlot · 等待 Stage 注入]     │ ← Stage 通过 module-properties-inject
└─────────────────────────────────────────────────────┘

边界总结： - Shell 渲染：Drawer 外壳/Header/Tab Bar；Bottom Tab Bar；构建/问题/终端/日志四个通用 tab 的容器（内容仍由 Shell 自渲染） - Stage 注入：Inspector 子内容；属性 tab 子内容 - 空槽 + 协议提示：Stage 切换时槽位先清空，避免旧 Stage 残留

12.6 Drawer Header Title v3.1 修复（grid 两行 + ellipsis）

问题	修复
Title 在 Drawer 窄宽度时被按钮挤丢	grid-template-columns: 1fr auto（title 弹性 + 按钮组固定）
Title 多行换行破坏 Header 高度	grid-template-rows: auto auto（主/副两行固定）
Title 文本溢出无截断	white-space: nowrap; overflow: hidden; text-overflow: ellipsis

对应 commit 886dacc。

12.7 跨 Stage 共享浮窗（Tuning Dialog）

• 由 Shell 全局管理（不归属任何 Stage）
• 任何 Stage 可通过 tuning-dialog 消息拉起
• 浮窗内容：PEQ 调参 + 实时频响曲线 + A/B 切换
• Stage 切换时浮窗继续存在（最小化进 BottomPanel Tuning 托盘 B6）
• 实现位置：layout-demo/index.html 的 #tuningDialog 与 openTuningDialog(module, label) 函数

12.8 codex.css 边界（视觉法典 · 1212 行 · 严禁修改）

.ide                       § 4   grid-template-areas
.ide.locked                § 15  挤压布局开关
.dock-icon                 § 6   38×38 Activity Bar 图标
.view-pane                 § 7   position:absolute; inset:0; display:none
.view-pane.active          § 7   display:block
.drawer                    § 8   position:absolute; opacity:0
.drawer.show               § 8   opacity:1
颜色变量                    § 2   --accent / --xi-light / --ok / --warn / --err / --L1~L5

实现规范： - 所有 Shell HTML 结构必须严格匹配 codex.css 选择器 - ❌ 不能用 .activity-icon（必须 .dock-icon） - ❌ 不能直接 display:block 切换 view-pane（必须用 .active 类） - ❌ 不能修改 codex.css 任何一行

12.9 ADR 决策记录（5 次迭代修正）

ADR	Commit	标题	决策
ADR-01 v3.1	886dacc	Drawer Header Title 截断修复	grid 两行 + nowrap + ellipsis（不改 codex.css，仅 Shell 内部布局调整）
ADR-02 v3.2	71d9e8c	Header 两行 + Bottom Tab 互斥 + Stage Hint 槽	Bottom 同一时刻只显示一个 tab 内容；新增 #stageHintSlot 由 Stage 注入快捷键提示
ADR-03 v3.3	8b2e76a	阶段 2 通用骨架示意	PEQ + Bottom 5 tab + Drawer 项目树/Inspector 三大通用骨架先于 Stage 业务内容验证
ADR-04 v3.4	a6babfb	Dock-icon bug 修复 + Inspector/Bottom-Module 边界修正	用 dataset.activeKey 修复单击切换；Inspector/属性改为空槽 + Stage 注入
ADR-05 v3.5	808531d	4 主 Pill 全解锁 + iframe 动态加载 + STAGE_SRC 映射	4 个 Pill 全可切换，Stage iframe 动态加载，证明 plug-in 边界

12.10 layout-demo 11 commit 全量索引

#	Commit	标题	关键文件
1	28e7ac3	XiLink Stage iframe 联动 + Tuning Dialog 浮层骨架	index.html / stages/stage-xilink.html
2	d0ee8ab	VSCode 式窗口管理（locked + resize + split + 持久化）	index.html
3	1efed72	Drawer Dock 位置切换（4 位置 + ½/⅓/¼ 比例）	index.html
4	886dacc	Drawer Header Title 截断修复 v3.1	index.html
5	71d9e8c	Header 两行 + Bottom Tab 互斥 + Stage Hint 槽 v3.2	index.html
6	8b2e76a	阶段 2 通用骨架示意（PEQ + Bottom 5 tab + Drawer 项目树/Inspector）v3.3	index.html / stages/stage-xilink.html
7	a6babfb	Dock-icon bug 修复 + Inspector/Bottom-Module 边界修正 v3.4	index.html / stages/stage-xilink.html
8	8d99d1a	stage-xitune.html · 调音 Stage 骨架（3 列）	stages/stage-xitune.html
9	ad11aa0	stage-xiforge.html · 模块开发 Stage 骨架（2 列 + 伪代码源码示意）	stages/stage-xiforge.html
10	a0ca76a	stage-xitest.html · 测试 Stage 骨架（2 列 + 4 KPI + 失败回归 + SVG 趋势）	stages/stage-xitest.html
11	808531d	4 主 Pill 全解锁 + iframe 动态加载 + STAGE_SRC 映射 v3.5	index.html

12.11 实现层 TODO（留给 v1.2.3 / v1.3）

• License 系统对接：当前 4 Pill 全解锁是"开发期开关位"，正式版需接入 useLicenseStore 路由守卫（详见 §7.3）
• 左右 Activity Bar 7 个未做的 dock-icon 子界面：当前只接入了 XiLink/XiTune/XiForge/XiTest 主舞台，左 Dock L1/L2/L3/L4/L5/L6/L7/L8/L9/L10 与右 Dock R1/R2/R3/R4/R5/R6/R7/R8/R9 中尚有 7 个未做（XiLink Stage 关联那几个已做）
• Tuning Dialog 完整 PEQ 引擎：当前是浮窗骨架 + mock 频响曲线，需接入真实 DSP 计算
• MenuBar 9 菜单项功能落地：当前只是占位（文件/编辑/视图/项目/构建/调试/工具/窗口/帮助）
• ⌘K 命令面板：仅有按钮，未接入命令注册中心
• 跨 Stage Tuning 浮窗持久化：Stage 切换时浮窗状态保留，但 reload 后未恢复

12.12 Vue 3 改造提示（详见 D4 前端实现手册）

本节仅给出改造方向，详细分组件/Pinia store/composable 的迁移方案请见
👉 docs/08-implementation/30-frontend-vue3/layout/（前端改造指导手册）

• Shell → XiStudioShell.vue（根布局组件）+ 子组件 MenuBar / StageBar / DrawerLeft / DrawerRight / Bottom / StatusBar
• Stage → 路由懒加载 + <iframe> 或 <component :is> 渐进式（手册推荐 iframe，便于沿用本期 demo）
• postMessage 9 类协议 → useStageBridge() composable + TS 类型定义
• localStorage 持久化 → Pinia plugin（pinia-plugin-persistedstate）替代手写 localStorage
• codex.css → 直接复用为全局 CSS（不拆 SCSS module，保持 1:1 字节兼容）

---

XiStudio IDE 架构 v1.2.2-impl · 2026-05-17 · §0–§11 锁定决策 · §12 沉淀 layout-demo 11 commit 实现成果 · 下一步衔接 D4 前端改造手册

---

13. 顶栏五段动态注入架构（v1.2.3-impl · 2026-05-19 · v4.0–v4.3 演进）

本章为 §0–§12 架构基线之上的 v4.x 演进沉淀

§2 描述的 v1.2.2 顶栏（3 行 / StageBar 44px Pill+ToolBar 合并）是架构基线；本章沉淀 2026-05-18 至 2026-05-19 经过 v4.0 → v4.1 → v4.2 → v4.3 共 4 次迭代后的最终顶栏五段架构。

核心变化：StageBar 从"Pill 左 + ToolBar 右（按 stage 静态分配）"演进为"Stage Pills | mode-switcher | stageToolbar | Shell 通用按钮组"四段动态注入 + 行 2（仅 XL/XT 显示的 doc-tabs sub-tabs-bar）。

其中 mode-switcher 与 stageToolbar 都按 stage 动态注入；stageToolbar 进一步按 mode 双维度切换（XF 在 simulation 模式下 stageToolbar 自动清空）。

13.1 五段架构图（行 1 单行 44px · 行 2 仅 XL/XT 26px）

┌──────────────────── 行 1 · StageBar (44px) ───────────────────────────────────────────┐
│ [🚦] XiStudio [☰]                                                                       │
│                                                                                          │
│ ┌─────────── ① Stage Pills ─────────┐ ┌── ② mode-switcher ─┐ ┌── ③ stageToolbar ───┐    │
│ │ [🔗 XL][🔨 XF][🎚 XT][🧪 XS]      │ │ chip · stage 注入  │ │ button · stage+mode│    │
│ │ ↑ license 决定 · 灰显加锁         │ │ XL=0/XF=3/XT=4/XS=*│ │ 注入（动态）       │    │
│ └────────────────────────────────────┘ └─────────────────────┘ └─────────────────────┘    │
│                                                                                          │
│ ┌──────── ④ Shell 通用按钮组（永远固定 · 全 stage 通用）────────────────────┐           │
│ │ 🤖 XiMind  🪟 浮窗管理  🔒 锁定/悬浮 toggle  🎨 主题                     │           │
│ └────────────────────────────────────────────────────────────────────────────┘           │
└──────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────── 行 2 · sub-tabs-bar (26px · 仅 XL/XT) ────────────────────────────┐
│ ⑤ 📑 文档：[main_chain.xilink ●][subgraph_eq.xilink][multi_band_dyn.xilink] [＋]        │
│   ↑ doc-tabs（多文档 / 子图切换） · stage 通过 doc-tabs-inject 注入                     │
│   · XF/XS 不显示行 2，IDE 自动移除 .with-subtabs-bar class                              │
└──────────────────────────────────────────────────────────────────────────────────────────┘

设计原则（一句话）：

"license 决定能进哪个 Stage · stage 决定中段有几个 mode · stage+mode 共同决定右段有哪些 stageToolbar 按钮 · Shell 通用按钮组永远固定。"

13.2 五段职责矩阵（核心契约）

段位	DOM 槽位	谁决定显示什么	动态性	协议
① Stage Pills	#stagePills .main-tabs	license 决定哪几个 Pill 可点（未授权灰显加 🔒）	启动时一次性渲染（除非用户切 license）	无（Shell 内置）
② mode-switcher	#modeSwitcher	当前 stage 的子主界面数量 决定 chip 数量	stage 切换时整段重渲；mode 切换时仅高亮变	mode-switcher-inject ↓ + mode-switch-click ↑
③ stageToolbar	#stageToolbar .toolbar-group	当前 stage + 当前 mode 共同决定按钮组（同 stage 不同 mode 可不同）	stage 切换 + mode 切换都触发重渲	toolbar-inject ↓ + toolbar-click ↑
④ Shell 通用按钮组	4 个 .topbar-ico-btn	Shell 自身（与 stage 无关）	永远固定 4 个：🤖/🪟/🔒/🎨	无（Shell 内置）
⑤ sub-tabs-bar	#docTabsBar + .ide.with-subtabs-bar	当前 stage 是否有多文档需求（仅 XL/XT 用）	stage 切换时整段重渲 + IDE class 同步切换	doc-tabs-inject ↓ + doc-tab-click/close/new ↑

13.3 各 Stage × Mode × stageToolbar 配置矩阵（v4.3 落地清单）

Stage	Pill 显示条件	mode-switcher	stageToolbar（按 mode 区分）
🔗 XiLink	xilink-view-only 或 xilink-pro	无（不注入 mode-switcher）	5 按钮 · 💾 保存 / 📄 新建 / 🔄 链路更新 / ⌘ 节点对齐 / ▶/■ 引擎 toggle
🔨 XiForge	xiforge-pro	3 chips · 🎨 工具布局 / 💻 源码设计 / 🧪 仿真验证	layout & code 模式：4 按钮 🆕 新建画布 / 💾 保存 / 🧹 清空 / ⚙ 编译运行 ｜ simulation 模式：0 按钮（buttons:[] 清空）
🎚 XiTune	xitune-pro	4 chips · 🎚 link 手动 / 🤖 link 自动 / 🔄 兼容 / ↩ 反向（默认 link-manual · 主区暂不切换 · 仅 chip 高亮 + toast）	3 按钮 · 💾 保存 / 📄 新建 / ▶/■ 引擎 toggle
🧪 XiTest	xitest-pro（4 子 add-on）	（v4.0 原方案曾设 5 chips · 当前保持 stage 现状 · 后续按 SMOKE/INTEG/ELEC/ACOU/LIVE 注入）	当前保持 stage 现状（运行/停止/重跑/捕获/导出）

说明：上述矩阵直接映射到 layout-demo/stages/stage-{xilink,xiforge,xitune,xitest}.html 的 mode-switcher-inject / toolbar-inject 启动注入代码，是 v4.3 实现的"事实标准"。XiTest 保持现状是用户在 v4.3 评审时明确决定。

13.4 mode-switcher-inject 协议（Stage → Shell · 数据契约）

window.parent.postMessage({
  type: 'mode-switcher-inject',
  stage: 'xiforge',                     // 必填 · 用于 Shell 校验来源
  chips: [                              // 必填 · 数组 · 空数组 = 清空中段（隐藏）
    { key: 'layout',     icon: '🎨', label: '工具布局', tip: '可视化布局画布' },
    { key: 'code',       icon: '💻', label: '源码设计', tip: '源码编辑器（C/C++）' },
    { key: 'simulation', icon: '🧪', label: '仿真验证', tip: '在仿真环境运行 IP' }
  ],
  activeKey: 'layout'                   // 可选 · 默认 chips[0].key
}, '*');

反向消息（Shell → Stage · 用户点击 chip 时）：

{ type: 'mode-switch-click', stage: 'xiforge', key: 'simulation' }

Stage 接收 mode-switch-click 后的典型处理：

1. 切换 stage 内主区显示（XF：layout/code/simulation 三 pane 切换 · XT：仅 toast 提示，主区不动）
2. 调用 injectToolbarFor(key)：根据新 mode 重新发 toolbar-inject 给 Shell（XF 在切到 simulation 时发空数组清空 stageToolbar）

13.5 toolbar-inject 协议（v4.3 增强 · 支持 toggle 引擎按钮）

window.parent.postMessage({
  type: 'toolbar-inject',
  stage: 'xilink',
  buttons: [                                       // 必填 · 数组 · 空数组 = 清空 stageToolbar
    { id: 'xl-save',   icon: '💾', label: '保存',     tip: '保存当前工程 (⌘S)' },
    { id: 'xl-new',    icon: '📄', label: '新建',     tip: '新建工程' },
    { id: 'xl-update', icon: '🔄', label: '链路更新', tip: '重新拉取 DSP 链路' },
    { id: 'xl-align',  icon: '⌘',  label: '节点对齐', tip: '栅格对齐选中节点' },
    { id: 'xl-engine', toggle: true, tip: '启动 / 停止音频引擎（全局单例）' }
    //                  ↑ v4.3 新增 · toggle:true 表示该按钮是开关状态
    //                    Shell 自动渲染为 ▶（停止时）或 ■（运行时）
    //                    点击不转发 toolbar-click，而是切换 Shell 全局 _engineRunning
  ]
}, '*');

普通按钮的反向消息（用户点击非 toggle 按钮时）：

{ type: 'toolbar-click', stage: 'xilink', id: 'xl-save' }

toggle 按钮的特殊处理（详见 §13.6 全局引擎单例）。

13.6 全局引擎单例机制（v4.3 核心 · XL/XT 共享）

用户决策：v4.3 评审 Q6 = b（Shell 全局共享引擎状态 · "只有一个引擎，不能启动两个"）。

实现路径：

┌─ Shell 全局变量 ──────────────────────────────────────────────────────┐
│ let _engineRunning = false;  // Shell index.html 顶部 · 单例状态       │
└───────────────────────────────────────────────────────────────────────┘
                  │
                  ▼
┌─ injectStageToolbar(stage, buttons) · 渲染按钮 ─────────────────────┐
│ buttons.forEach((b) => {                                              │
│   const isEngineBtn = b.toggle === true || /engine/i.test(b.id);     │
│   if (isEngineBtn) {                                                  │
│     btn.dataset.role = 'engine';                                      │
│     btn.textContent = _engineRunning ? '■' : '▶';                    │
│     btn.classList.toggle('active', _engineRunning);                   │
│     // 点击时 · 直接切 Shell 状态 · 不转发给 stage                    │
│     btn.onclick = () => {                                             │
│       _engineRunning = !_engineRunning;                               │
│       btn.textContent = _engineRunning ? '■' : '▶';                  │
│       showToast(_engineRunning ? '🔊 已启动' : '⏹ 已停止');          │
│     };                                                                │
│   } else {                                                            │
│     // 普通按钮 · 转发 toolbar-click 给 stage                         │
│   }                                                                   │
│ });                                                                   │
└───────────────────────────────────────────────────────────────────────┘
                  │
                  ▼
┌─ stage-ready 时同步引擎按钮（跨 stage 切换状态续接）────────────────┐
│ function _syncEngineButtonsToActiveStage() {                          │
│   document.querySelectorAll('#stageToolbar [data-role="engine"]')     │
│     .forEach((btn) => {                                               │
│       btn.textContent = _engineRunning ? '■' : '▶';                  │
│       btn.classList.toggle('active', _engineRunning);                 │
│     });                                                               │
│ }                                                                     │
│ // 在 message handler 的 'stage-ready' case 中调用                     │
└───────────────────────────────────────────────────────────────────────┘

典型时序（XL 启动 → 切到 XT → XT 显示 ■）：

1. 用户在 XiLink 点击 ▶
   → Shell: _engineRunning = false → true
   → 按钮 ▶ → ■ + active class
   → toast "🔊 音频引擎 · 已启动"

2. 用户切到 XiTune（点击 🎚 XT Pill）
   → switchStage() 清空 #stageToolbar
   → 加载 stage-xitune.html

3. XiTune 启动后 postMessage 'stage-ready'
   → Shell 调 injectStageToolbar 渲染 3 按钮
     · 此时 _engineRunning === true
     · xt-engine 按钮渲染为 ■ + active class（与 XL 一致）
   → Shell 调 _syncEngineButtonsToActiveStage()（双重保险）

4. 用户在 XiTune 点击 ■
   → Shell: _engineRunning = true → false
   → 按钮 ■ → ▶
   → 切回 XiLink 时，xl-engine 也是 ▶（共享状态）

为什么不转发给 stage 而是 Shell 内部直接切：避免 stage 自维护状态导致 XL 和 XT 不一致；Shell 是唯一真实数据源。

辅助协议（stage 主动控制引擎 · 可选）：

{ type: 'engine-control', stage: 'xilink', action: 'start' | 'stop' | 'toggle' }

Shell 收到后调 handleEngineControl() 切 _engineRunning + 同步所有可见引擎按钮。

13.7 Drawer 双 dock 边界（内容 stage 注入 · 操作 Shell 接管）

用户原话："左右 dock 的组件根据不同的 stage 注入，但是 dock 的操作是一致的横向纵向，比例分屏等操作"。

边界划分：

维度	谁负责	实现位置
Drawer 外壳（边框 / 圆角 / 阴影 / open/close 动画）	Shell	codex.css §8 + index.html .drawer.left/right
Drawer Header（traffic-lights / title / pin / dock-tools / ratio-tools / split-tools）	Shell	index.html .drawer-head（grid 两行布局 · v3.1 修复）
Drawer body 内 dock-pane 列表（每个 dock-icon 对应的内容）	stage 注入	dock-inject 协议 · 数组结构 [{key, icon, tip, html}]
Activity Bar dock-icon 列表（左/右侧 48px 竖列 · 切换 dock-pane）	stage 注入（与 dock-pane 一一对应）	dock-inject 同协议 · 渲染时同时重建 #actLeft / #actRight
Dock 位置切换（left/right/top/bottom 4 位置）	Shell	setDock(side, pos) 函数
Dock 比例切换（½ · ⅓ · ¼）	Shell	setStripRatio(side, ratio) 函数
横/纵 split 分屏（pane1/pane2 切换）	Shell	toggleSplit(target, dir) 函数
Resize 拖拽（drawer 边缘 / split handle 内部）	Shell	attachOuterResize / attachSplitHandleDrag
locked / float 模式切换	Shell	toggleLock() 函数（v4.3 仅切图标 🔒↔🔓）
持久化（localStorage xistudio-layout-v1）	Shell	saveLayout / loadLayout 函数

dock-inject 协议（详见 §12.3.1，v3.7.3 起规范化为数组格式）：

window.parent.postMessage({
  type: 'dock-inject',
  stage: 'xitune',
  left:  [                                  // 左 Drawer 注入 N 个 dock-pane（与 N 个 activity-bar dock-icon 一一对应）
    { key: 'xt-proj',    icon: '📁', tip: '调音工程管理',     html: '...' },
    { key: 'xt-flow',    icon: '🔗', tip: '链路流图（只读）', html: '...' },
    { key: 'xt-profile', icon: '⭐', tip: '音效 Profile',     html: '...' }
  ],
  right: [                                  // 右 Drawer 注入
    { key: 'xt-freq',  icon: '📈', tip: '频响（出口）', html: '...' },
    /* ... 7 个 ... */
  ]
}, '*');

Shell 端 injectStageDock 行为：

1. 备份 Shell 默认 dock（仅首次 · backupDefaultDock()）
2. 切 stage 时还原默认 dock（resetStageDock()）
3. 收到 stage 的 dock-inject 后重建 splitLeft .pane-body 内的 dock-pane HTML + actLeft 内的 dock-icon HTML
4. 默认激活首项 + 同步 drawer 标题

当前各 stage 的 dock 配置：

Stage	left dock 数	right dock 数
XiLink	默认（Shell 自带 5 个 · proj/lib/conn/engine/aux）	默认（Shell 自带 4 个 · inspect/scope/deploy/ai）
XiForge	3 · proj/iplib/ctllib	3 · mod-prop/ctl-data/publish
XiTune	3 · proj/flow/profile	7 · freq/phase/rms/xical/ref/hist/aux
XiTest	当前保持现状	当前保持现状

13.8 与 §12 实现成果沉淀的衔接（commit 索引）

子章节	对应 commit	主要工作
13.1 五段架构	多 commit 累积	累计 v4.0–v4.3 逐步演进
13.2 mode-switcher	v4.0 引入 + v4.1 emoji 紧凑化	mode-switcher-inject + mode-chip CSS（emoji + label · 删 chip-tag）
13.3 stageToolbar 矩阵	0e5d450（本次 v4.3 commit）	XL 5 按钮 / XF 3 chips + 动态 toolbar / XT 3 按钮 + 4 chips
13.4 mode-switcher 协议	v4.0 起	协议定义 + 反向 mode-switch-click
13.5 toolbar-inject toggle:true	v4.3 新增	引擎按钮渲染为 ▶/■ + active class · 不转发 toolbar-click
13.6 全局引擎单例	v4.3 新增	_engineRunning + _syncEngineButtonsToActiveStage() + handleEngineControl()
13.7 Drawer 边界	v3.7.2 起 + v4.x 沉淀	dock-inject 协议数组化 + Shell 通用操作（dock-tools / ratio-tools / split-tools）

13.9 v4.0 → v4.3 演进史（一句话回顾）

版本	核心变化	决策动因
v4.0（2026-05-19 PLAN）	提出顶栏三段式：Pill / mode-switcher / stageToolbar；引入 audio-engine 全局组（▶/■/🔄+状态灯）；引入 doc-tabs-inject + mode-switcher-inject + engine-state-changed 三协议	把 stage 内分散的 doc-tabs / mode-bar / 通用按钮按职责归位 Shell
v4.1	mode-chip 改 emoji icon + 紧凑 label（删 chip-tag）；删除 audio-engine 全局组（与 stage 内部 test-ctrl-bar 重复 · 改由 stage 内部接管）；新增 XiMind 顶栏右上角按钮	视觉紧凑化 + 避免双重控制源
v4.2	顶栏右侧统一为 .topbar-ico-btn 4 图标按钮（🤖/🪟/🔒/🎨）；删除 .float-mgr / .lock-toggle / .lic-tag 旧式样式；showLicense 函数删除	Shell 通用按钮组样式统一
v4.3（2026-05-19 当前）	toggleLock 仅切图标（🔒↔🔓 · 删中文标签）；stageToolbar 单行恢复（位于 mode-switcher 之后、🤖 之前）；toolbar-inject 支持 toggle:true；Shell 全局单例 _engineRunning（XL/XT 共享）；4 stage 改造完成（XL 5 / XT 3+4chips / XF 3chips+动态 toolbar / XS 保持）	把 v4.1 删掉的引擎控制重新引入，但改为单例共享避免双引擎

13.10 v1.2.3-impl 之后的 TODO（留给 v1.2.4 / v1.3）

• License 系统接入 Stage Pills：当前 4 Pill 全解锁是开发期开关位，正式版需接入 useLicenseStore 路由守卫（详见 §7.3）
• mode-switcher 与 license add-on 联动：例如 xitune-reverse add-on 未授权时 · XT 的"反向"chip 应灰显加锁（当前所有 chip 都可点）
• stageToolbar 按钮也接入 license：例如 XL 的"链路更新"在 view-only 模式下应灰显（仅 xilink-pro 可用）
• XiTest 接入 mode-switcher：按 v4.0 PLAN 设计的 5 chips（SMOKE/INTEG/ELEC/ACOU/LIVE）注入
• engine-state-changed 广播：当前 Shell 仅本地维护 _engineRunning · 后续可向所有 stage 广播 sampleRate / bufferSize / latency 状态供 stage 联动 UI（如 XT io-bar LIVE 灯）
• localStorage 持久化扩展：当前未持久 mode-switcher 当前 activeKey · 切回 stage 后恢复到 chips[0]；后续可持久化每个 stage 的 lastActiveMode

13.11 v1.2.4-impl 预告 · AIOS 多智能体协作落地（2026-05-19 新增 · v3 修订）

§13 顶栏五段架构契约的实施层调度已转交 AIOS(AI Operating System)5 角色协作框架(v3 · 跨栈职能解耦),详见 docs/08-implementation/40-aios/。

• 本节(§13)定位:架构契约源头 · 描述五段架构应该是什么
• D4 master-plan 定位:实施路线图 · 描述做什么 + 顺序(17 phase · 详见 30-frontend-vue3/00-master-plan.md)
• 40-aios/ 定位:5 角色协作框架 · 描述谁来做 + 怎么协作(Cline=AIOS 调度内核 + 双 Claude Code CLI + Continue + Copilot)

5 角色架构(v3 · 2026-05-19 傍晚晚 · 跨栈职能解耦):

• AIOS / Cline(10%) · Cline 插件作为调度内核的化身 · 不写业务代码
• ClaudeA(50%) · Claude Code CLI 终端 #1 · frontend_vue3/ 全程独占 · 17 phase 全部前端
• ClaudeB(30%) · Claude Code CLI 终端 #2 · backend_csharp/ + dsp_algo/ + contracts/ 全程独占 · 写本节相关契约 + 后端 + DSP + XiForge MC 融合
• Continue(5%) · 异步文档同步 + 备份
• Copilot(5%) · IDE 内联补全(被动)

协议契约层落地(v1.2.4-impl 预期产出):

• ClaudeB 编写 40-aios/contracts/protocol-v1.md · 把 §13.5 mode-switcher / §13.6 stageToolbar / §13.7 engine-control 的契约语义全部协议化
• 12 类原 postMessage 协议 → store action 命名空间 + EventBus 信号集(见 30-frontend-vue3/00-master-plan.md §3)
• contract 在 Day 5 freeze + 打 tag contract-v1.0 · 之后所有实施 commit 必须 ack: contract-vX.Y
• ⚠️ contract freeze 是 ClaudeA(phase 6-7 mode-switcher / engine-toggle) 的硬阻塞依赖

跨栈职能解耦(v3 修正 v2 时间窗串行错误):

• frontend_vue3/ = ClaudeA 全程独占 · 17 phase 由 ClaudeA 一人跑完
• backend_csharp/ + dsp_algo/ + contracts/ = ClaudeB 全程独占 · 提前为 ClaudeA 铺路
• Day 1 起即并行 · 双 CLI 同时启动 · 目录天然隔离 · 零 commit 冲突
• phase 16-17(Week 6-7) = ClaudeA(前端 e2e) + ClaudeB(后端联调) 同时在线 · 仍在各自目录内协作

调度机制:

• 实时看板:40-aios/KANBAN.md(17 phase 全部 owner=ClaudeA + ClaudeB 13 项后端横切主线)
• 5 角色名册:40-aios/agents/Roster.md(v3)
• 仓库分区铁律(跨栈职能解耦):40-aios/agents/Repository-Partition.md
• 决策升级链:40-aios/agents/Conflict-Resolution.md
• 全框架决议 ADR(v3 已修订):40-aios/ADR/ADR-AIOS-01-multi-agent-collaboration.md

当 AIOS 调度机制运行 ≥ 1 周后,本节将正式 promote 到 v1.2.4-impl 版本号 · 同步更新 frontmatter version 字段。

---

XiStudio IDE 架构 v1.2.3-impl · 2026-05-19 · §0–§11 决策层(v1.2.2 锁定)+ §12 v3.x 实现沉淀(11 commit)+ §13 v4.x 顶栏五段动态注入(v4.0–v4.3 共 4 次迭代 · 落地于 commit 0e5d450)+ §13.11 AIOS 5 角色协作框架预告 v3(Cline=AIOS 化身 + 双 Claude Code CLI · 跨栈职能解耦 · Day 1 真正并行 · v1.2.4-impl 即将激活)