跳转至

80 · 给前端改造智能体的执行手册

📌 本文是手册系列里最重要的一份——直接交给前端改造智能体（如 cline / cursor agent / copilot）作为接手任务的入口。

1. 你是谁？

你（前端智能体）的任务是：把 docs/02-products/P1-xistudio/layout-demo/（vanilla HTML/CSS/JS · 11 commit · 已稳定）按照本手册改造成 Vue 3 + TypeScript + Pinia + Vite 项目，作为 XiStudio IDE 的正式前端代码框架。

你不需要实现 4 个 Stage 的内部业务（XiLink 流图编辑 / XiTune 调音 / XiForge 模块开发 / XiTest 测试）——这些 Stage 继续以 vanilla HTML 形式作为 iframe 加载。你的工作集中在 Shell（操作系统底座） 的 Vue 3 实现。

2. 第一原则（按优先级排序）

1️⃣ 视觉零回归

与 layout-demo 像素级一致。codex.css 1212 行一字不改。详见 60-codex-css-strategy.md。

2️⃣ postMessage 9 类协议是冻结契约

任何变更必须新建 ADR。详见 40-postmessage-protocol.md。

3️⃣ localStorage key 兼容 xistudio-layout-v1

用户从 demo 切换到 Vue 项目，布局必须自动还原。

4️⃣ Stage iframe 不重写

stage-*.html 作为静态资源放 public/stages/。详见 30-stage-iframe-strategy.md。

5️⃣ TS 严格模式 + 类型契约统一

所有协议、store state 都在 src/types/ 集中定义。

6️⃣ 严格按 Phase 推进

每完成一个 Phase 跑一次验收脚本。详见 70-migration-checklist.md。

3. 启动顺序（强制）

Step 0 · 阅读架构文档（5 min）
  └ docs/02-products/P1-xistudio/v1.2-ide-architecture.md
    重点：§0 一图概览 / §11 一句话总览 / §12 实现成果沉淀

Step 1 · 阅读本手册导引（10 min）
  └ docs/08-implementation/30-frontend-vue3/layout/00-overview.md
    重点：§1 现状 vs 目标 / §6 验收标准

Step 2 · 阅读架构映射（15 min）
  └ docs/08-implementation/30-frontend-vue3/layout/10-architecture-mapping.md
    重点：§1 目录结构 / §2 demo→Vue 映射 / §7 反模式

Step 3 · 跑通 demo 本机预览（5 min）
  └ 在 docs/02-products/P1-xistudio/layout-demo/ 下用浏览器打开 index.html
  └ 4 个 Pill 各点一遍，感受交互

Step 4 · 按 Phase 1 启动改造（0.5 d）
  └ 70-migration-checklist.md Phase 1
  └ 跑验收脚本

Step 5 · 按 Phase 2-7 推进（持续 6.5 d）

Step 6 · 终极验收
  └ 00-overview.md §6 全部 9 项 ✅
  └ 提交交付

严禁跳过 Step 0-3 直接动手。

4. 决策树（遇到不确定时怎么办）

4.1 找不到映射怎么办？

1. 在 10-architecture-mapping.md 中 grep 关键词
2. 在 v1.2-ide-architecture.md §12 中查规约
3. 看 layout-demo/index.html 真实实现
4. 仍不确定 → 用 ask_followup_question 提问，不要猜

4.2 codex.css 不够用怎么办？

1. 99% 的情况：仔细读 codex.css 1212 行，你需要的样式已经在了
2. 真的没有 → 用 <style scoped> 加局部样式，但**不要**重新定义颜色变量
3. 涉及全局的（新主题/新 z-index 层）→ 提 ADR

4.3 postMessage 协议不够用怎么办？

1. 99% 的情况：现有 9 类协议覆盖所有场景
2. 真的需要扩展（如主题同步 'theme' 消息）→ 按 40-postmessage-protocol.md §6 ADR 流程
3. 不要散落式 addEventListener('message', ...)，必须走 useStageBridge

4.4 store 拆分粒度怎么定？

1. 默认按 50-state-management.md 的 6 个 store
2. 不要新增 store（除非业务确实独立且无重叠）
3. 不要把 4 个 Stage 的业务状态放进任何 store（那些归 Stage iframe 内部管理）

4.5 测试覆盖率如何？

1. 单元测试覆盖 stores + composables（重点：useStageBridge 与 useLayoutStore）
2. E2E 测试覆盖 11 个核心场景（70-migration-checklist.md §7.2）
3. 不强求 100% 覆盖率，关键路径 100% 即可

5. 协作规则

5.1 与 demo 团队的同步

  • demo 改了 stage HTML → 你跑 scripts/sync-stages-from-demo.sh 同步到 public/stages/
  • demo 改了 codex.css → 你跑 diff 验证，确认字节级 1:1
  • demo 改了 postMessage 协议 → 必须先有 ADR，再同步 TS 类型 + Stage HTML
  • demo 改了 localStorage 字段 → 必须 ADR 决定迁移方案（向后兼容 / break）

5.2 与架构团队的同步

  • 遇到架构层不明确 → 回看 v1.2-ide-architecture.md §0–§11
  • 需要扩展架构能力（如新增 Stage、新增 license 类型）→ 提 ADR 给架构团队 review

5.3 Git 工作流

  • 每个 Phase 一个 feature branch（feature/phase-1-init / feature/phase-2-shell...）
  • 每个 Phase 完成后跑验收脚本，通过后 PR 合并到 main
  • commit message 用 conventional commits 规范

5.4 沟通习惯

  • 不确定 → 用 ask_followup_question 问
  • 不要为了演示进度而虚报完成项
  • 改完一项 → 在 70-migration-checklist.md 进度表打勾
  • 卡住 > 30 分钟 → 不要硬扛，提问

6. 交付定义（DoD · Definition of Done）

每个 Phase 的 DoD：

  • 70-migration-checklist.md 该 Phase 所有 checkbox 已打勾
  • 验收脚本通过
  • commit + push
  • 进度表更新

终极交付的 DoD：

  • 00-overview.md §6 验收标准 9 项全部 ✅
  • 与 demo 1920×1080 截图 diff < 1%
  • codex.css diff 为空
  • localStorage 兼容性测试通过（demo↔Vue 互相还原）
  • TS 严格模式 0 错误
  • 11 个 E2E 场景全部通过

7. 不可越过的红线

  • ❌ 修改 codex.css（任何一个字节都不行）
  • ❌ 改 localStorage key（必须沿用 xistudio-layout-v1）
  • ❌ 散落 addEventListener('message', ...)（全部走 useStageBridge）
  • ❌ 重写 Stage 业务（保持 iframe + vanilla）
  • ❌ 用 SCSS module / CSS-in-JS 包装 codex.css
  • ❌ 使用 .activity-icon 等错误类名（必须用 codex.css 法典类）
  • ❌ 手写 localStorage debounce（用 Pinia plugin）
  • ❌ 跳过 Phase 验收脚本直接进入下一个 Phase
  • ❌ 没有 ADR 就修改 postMessage 协议
  • ❌ 大段虚构 demo 现状再改造——必须先 read_file 看真实实现

8. 工具与脚本清单

脚本 用途
scripts/sync-stages-from-demo.sh 从 demo 同步 stage HTML + codex.css 到 Vue 项目
scripts/verify-codex-css.sh 字节兼容 diff 验证
scripts/phase-verify.sh Phase 收尾通用验收
npm run dev Vite dev server
npm run build 生产构建
npx vitest run 单元测试
npx playwright test E2E 测试
npx tsc --noEmit TS 严格检查
npx eslint src/ Lint

9. 常见错误与排查

9.1 主题切换 iframe 不响应

→ 检查是否走了 postMessage theme 协议（需要 ADR 登记）。Stage HTML 内是否有 message handler。

9.2 4 Pill 切换有内容残留

→ 检查 watch(stage.current) 是否调了所有 5 个 clear 方法（stageBar / stageStatus / stageHint / inspector / moduleProperties）。

9.3 Drawer dockPos 切换 grid 错乱

→ 检查 useLayoutStore.gridColumns / gridRows getter，按 dockPos + visible + ratio 三维度计算 fr 值。写单元测试覆盖所有组合。

9.4 dock-icon 需要点两次才切换

→ 这是 v3.4 修复的 bug。检查 ActivityBarLeft/Right 的 onDockIconClick 是否实现了"单击同一个 toggle off / 单击新的切换"逻辑。

9.5 localStorage 数据丢失

→ 检查 Pinia persistedstate plugin 的 key/paths 配置，必须严格对齐 50-state-management.md §2.1。清空 localStorage 后重新触发布局操作，看是否生成 xistudio-layout-v1 key。

9.6 iframe 加载后 stage-ready 没收到

→ 检查： 1. iframe src 是否正确（DevTools Network 看是否 200） 2. Stage HTML 内是否真的发了 stage-ready postMessage 3. useStageBridge 来源校验是否过严（生产环境同 origin 应该过）

10. 文档索引（快查）

任务 看哪份
入门 00-overview.md
整体映射 10-architecture-mapping.md
写组件骨架 20-shell-component-tree.md
接 Stage iframe 30-stage-iframe-strategy.md
写 useStageBridge / 协议类型 40-postmessage-protocol.md
写 Pinia store 50-state-management.md
用 codex.css 60-codex-css-strategy.md
推进任务 / 验收 70-migration-checklist.md
遇到困惑回到这里 80-handoff-to-agent.md（本文）
架构权威源 docs/02-products/P1-xistudio/v1.2-ide-architecture.md

11. 给智能体的最后嘱咐

你接手的是一个 11 个 commit 已稳定的 vanilla 实现，要把它升级为 Vue 3 框架。

不要： - 不要"按理解"自由发挥 - 不要简化协议、压缩组件、合并 store - 不要为追求"现代化"重写 codex.css - 不要把 Stage 业务也重写到 Vue

要： - 严格按手册推进 - 不确定就读源码、读架构、提问 - 每个 Phase 验收过了再下一个 - 视觉零回归 / 协议契约 / localStorage 兼容是三大铁律

改造完成后，你交付的是 XiStudio IDE 的正式前端代码框架——后续所有业务功能（XiLink/XiTune/XiForge/XiTest）都在这个框架上长出来。质量决定了 IDE 未来 5 年的演进速度。

加油，按规矩来，每一步都验收。

v1.0 · 2026-05-17 · D4 前端改造手册 · 智能体执行手册 · 配套 v1.2.2-impl 全套规约