00 · 前端改造手册 · 总览
📌 手册定位：本手册是给前端改造智能体看的执行级文档，配套 XiStudio IDE 架构 v1.2.2-impl，把
layout-demo/（vanilla HTML/CSS/JS）的 11 个 commit 实现成果1:1 映射到 Vue 3 + Pinia + Vite 项目。
1. 改造背景
1.1 现状（layout-demo · 11 commit · 已稳定）
已落地： - Shell 操作系统底座：MenuBar / StageBar 4 Pill / 左右 Activity Bar / Drawer 框 / Bottom 框 / StatusBar - VSCode 式窗口管理：locked/float + resize + split + dock 位置 + ½/⅓/¼ 比例 + localStorage 持久化 - 4 个 L4 Stage：XiLink / XiTune / XiForge / XiTest（独立 iframe HTML） - 跨 Stage 共享浮窗：Tuning Dialog - postMessage 9 类协议（Stage ↔ Shell IPC） - 视觉法典 codex.css（1212 行，严禁修改）
技术栈：
- 纯 vanilla：HTML + CSS + JavaScript（IIFE 模式）
- 单文件 index.html（~2400 行）+ 4 个 stage iframe
- 持久化：localStorage 手写 key xistudio-layout-v1
- 通信：window.postMessage + addEventListener('message', ...)
1.2 目标（Vue 3 项目 · 改造后）
技术栈：
- Vue 3.4+（Composition API · <script setup>）
- TypeScript 5.x（严格模式）
- Vite 5.x（构建工具）
- Pinia 2.x（状态管理）+ pinia-plugin-persistedstate（持久化）
- Vue Router 4.x（路由 + license 守卫）
- VueUse（composable 工具集）
- Tailwind CSS 或 原生 codex.css（保持视觉法典）
输出形态：
- XiStudioShell.vue 根组件 + 6 个子组件（MenuBar / StageBar / DrawerLeft / DrawerRight / Bottom / StatusBar）
- Stage 仍以 iframe 形式接入（不重写 Stage 内部业务，保持 demo 与 Vue 项目并行迭代）
- Pinia stores：useLayoutStore / useStageStore / useLicenseStore / useThemeStore
- composables：useStageBridge() / useDrawerDock() / useWindowResize() / useTuningDialog()
1.3 现状 vs 目标 对照表
| 维度 | 现状（layout-demo） | 目标（Vue 3 项目） |
|---|---|---|
| 框架 | vanilla JS IIFE | Vue 3 + Composition API |
| 类型 | 无 | TypeScript 严格模式 |
| Shell 入口 | index.html 单文件 ~2400 行 |
XiStudioShell.vue 根组件 + 6 子组件 |
| 状态管理 | window 全局变量 + localStorage | Pinia store + persistedstate plugin |
| 路由 | 无（单页内 switchStage） | Vue Router 4 + license 路由守卫 |
| Stage 接入 | iframe 动态 src | iframe（保持） + Vue Router lazy chunk（混合） |
| postMessage 协议 | addEventListener 散落 | useStageBridge() composable + TS 类型 |
| 持久化 | 手写 localStorage debounce | Pinia plugin 自动 |
| codex.css | 全局 link | 全局 import（不拆模块） |
| 主题切换 | data-theme 属性 + CSS 变量 | useThemeStore + provide/inject |
| 浮窗（Tuning） | DOM 操作 | <Teleport> + Pinia 状态驱动 |
| 测试 | 无 | Vitest（单元）+ Playwright（E2E） |
2. 改造原则
原则 1 · 视觉零回归（codex.css 不动）
- ❌ 不重写 codex.css
- ❌ 不拆为 SCSS module / CSS-in-JS
- ✅ 1:1 字节兼容 import 为全局 CSS
- ✅ 所有组件类名严格匹配 codex.css 选择器（
.dock-icon不能用.activity-icon等）
原则 2 · Stage 不重写（iframe 沿用）
- 4 个 Stage HTML（stage-xilink/xitune/xiforge/xitest.html）保持原样，作为静态资源放在
public/stages/ - Vue 项目通过
<iframe :src>加载，不把 Stage 业务逻辑迁移到 Vue 组件 - 好处：demo 与 Vue 项目可并行迭代，Stage 更新不需要触动 Vue Shell
- 未来某个 Stage 业务稳定后，可单独把它重写为 Vue Stage 组件（渐进式）
原则 3 · postMessage 协议是契约边界
- 9 类消息（8 类 Stage→Shell + 2 类 Shell→Stage）作为冻结契约
- TS 类型定义放在
src/types/stage-bridge.ts，Stage 与 Vue Shell 共享 - 所有协议变更必须新增 ADR
原则 4 · localStorage key 兼容（xistudio-layout-v1）
- Pinia 持久化 key 沿用现有
xistudio-layout-v1 - 字段结构兼容：用户从 demo 切换到 Vue 项目，布局自动还原
原则 5 · 改造分阶段（Phase 1 → Phase 5）
3. 时间线（建议节奏）
| Phase | 内容 | 工作量估计 |
|---|---|---|
| Phase 1 · 项目初始化 | Vite + Vue 3 + TS + Pinia + Router 脚手架；codex.css 接入；目录结构建立 | 0.5 d |
| Phase 2 · Shell 组件树 | XiStudioShell.vue + 6 子组件骨架；CSS grid-template-areas 还原 |
1.5 d |
| Phase 3 · Pinia stores | useLayoutStore / useStageStore / useLicenseStore / useThemeStore |
1 d |
| Phase 4 · postMessage bridge | useStageBridge() + TS 类型 + Stage iframe 接入 |
1 d |
| Phase 5 · 窗口管理 | Drawer Dock 4 位置切换 + resize + split + 持久化还原 | 1.5 d |
| Phase 6 · 跨 Stage 浮窗 | Tuning Dialog <Teleport> + Pinia 状态驱动 |
0.5 d |
| Phase 7 · 验收 + E2E | Playwright 跑 11 个 commit 对应的关键场景 | 1 d |
| 总计 | ~7 d |
4. 角色与文档边界
| 文档 | 给谁看 | 内容 |
|---|---|---|
| 本手册（layout/） | 前端改造智能体 / 前端工程师 | Vue 3 改造的实现级规约（组件树/store/composable/checklist） |
| v1.2-ide-architecture.md §12 | 架构师 / 团队对齐 | 实现成果沉淀（IPC 协议、ADR、commit 索引） |
| layout-demo/index.html | 视觉/交互参考 | vanilla 实现，作为字节级参考 |
xistudio-codex.css |
视觉法典 | 严禁修改，1:1 复用 |
5. 手册文件索引
| # | 文件 | 内容 | 给智能体的提示 |
|---|---|---|---|
| 00 | 00-overview.md（本文） | 总览 + 现状 vs 目标 + 时间线 | 先读这个 |
| 10 | 10-architecture-mapping.md | demo HTML/CSS/JS → Vue3 组件/Pinia/composable 映射 | 第二读 |
| 20 | 20-shell-component-tree.md | Shell 组件拆分树 + Props/Emits/Slots | 写组件骨架时读 |
| 30 | 30-stage-iframe-strategy.md | iframe 接入策略 + Stage 静态资源放置 | 接 Stage 时读 |
| 40 | 40-postmessage-protocol.md | 9 类 postMessage 协议 TS 类型定义 | 写 useStageBridge 时读 |
| 50 | 50-state-management.md | 4 个 Pinia store 设计 | 写 store 时读 |
| 60 | 60-codex-css-strategy.md | codex.css 复用策略 + 类名匹配规则 | 全程参考 |
| 70 | 70-migration-checklist.md | Phase 1-7 改造 checklist + 风险点 | 推进时打勾 |
| 80 | 80-handoff-to-agent.md | 给前端智能体的执行手册（最重要） | 智能体接手后从这个开始 |
6. 验收标准（改造完成的判定）
改造完成后，Vue 3 项目必须满足：
- 视觉零回归：与 layout-demo 像素级一致（同分辨率截图 diff < 1%）
- VSCode 式窗口管理 5 项全功能：locked / float / resize / split / dock 位置切换 / 比例 ½/⅓/¼
- Drawer 持久化：刷新页面后布局恢复（localStorage
xistudio-layout-v1兼容） - 4 Pill 切换：点击切换 Stage iframe，无残留 toolbar/inspector/properties
- postMessage 9 类协议：Stage iframe 注入 toolbar/status/hint/inspector/module-properties 全部生效
- Tuning Dialog 跨 Stage 持续：Stage 切换浮窗保留，最小化进 Bottom 托盘
- codex.css 字节兼容：与 demo 中的
xistudio-codex.css完全一致（diff 为空） - TS 严格模式无错误：
tsc --noEmit通过 - Vitest + Playwright 关键路径覆盖：至少 11 个核心场景测试通过
7. 启动顺序（智能体执行建议）
1. 读 00-overview.md（本文） ← 全局认知
2. 读 80-handoff-to-agent.md ← 知道从哪开始
3. 按 70-migration-checklist Phase 推进
├── Phase 1: 读 10-architecture-mapping → 60-codex-css-strategy
├── Phase 2: 读 20-shell-component-tree
├── Phase 3: 读 50-state-management
├── Phase 4: 读 30-stage-iframe + 40-postmessage-protocol
└── Phase 5-7: 按 80-handoff 收尾
4. 每完成一个 Phase 跑一次验收脚本
5. 全部通过后交付
8. 联系点
- 架构问题 → 回看 v1.2-ide-architecture.md §0–§11（决策层）
- 实现细节 → 回看 v1.2-ide-architecture.md §12（实现层）
- 视觉对照 → 跑
layout-demo/index.html本机预览 - 协议契约 → 40-postmessage-protocol.md
- 歧义 → 通过 ask_followup_question 提问，不要猜
v1.0 · 2026-05-17 · D4 前端改造手册总览 · 配套架构 v1.2.2-impl