MIGRATED
Xisound 前端 IDE 文档规划与实现 Roadmap v1.0
文档定位
- 上游：D3-FE-ARCH-001 顶层架构说明书
- 本文回答：为了完整描述并落地 7 产品前端 IDE，总共需要哪些文档 + 每份文档的目的/位置/优先级/受众/产出状态
- 不回答：文档内部细节（由各子文档自身负责）
- 目标读者：架构师 / 产品负责人 / 其他智能体（按本规划消费阶段 C/D 产出）
1. 文档体系总览
1.1 三层结构
graph TB
subgraph L0["🎯 D3 架构级（本次产出 4 份）"]
A1["D3-FE-ARCH-001<br/>顶层架构说明书"]
A2["D3-FE-ARCH-002<br/>文档规划 Roadmap<br/>（本文）"]
A3["D3-FE-ARCH-003<br/>共享 UI kit 架构"]
A4["D3-FE-ARCH-004<br/>实现 plan 总纲"]
end
subgraph L1["📦 D2 产品级（7 产品 × 3 核心文档）"]
B1["各产品 tech-arch<br/>（7 份）"]
B2["各产品 prd<br/>（7 份 · 下批）"]
B3["各产品 spec<br/>（7 份 · 下批）"]
end
subgraph L2["🔨 D3-FE 实现 plan（每功能独立）"]
C1["Phase 实现 plan<br/>（每产品 1-3 份）"]
end
A1 --> A2 --> A3 --> A4
A1 --> B1 --> C1
A4 --> C1
class A1,A2,A3,A4 xyL3
class B1,B2,B3 xyL2
class C1 xyL4
class L0,L2 xySgL4; class L1 xySgL2;
1.2 分层职责与 Docs-First 约束
| 层 |
归属目录 |
Docs/Code 关系 |
本次动作 |
| D3 架构级 |
D3-architecture/frontend/ |
Docs-First 初稿（漂移容忍） |
本轮产出 4 份 |
| D2 产品级 |
D2-products/P{n}-{name}/ |
Docs-First（产品决策先行） |
本轮更新 3 份 tech-arch |
| D3-FE 实现 plan |
D3-architecture/frontend/implementation-plans/（本文提议新建） |
Docs-First 初稿 + 智能体消费 |
本轮产出 1 份总纲 |
| D4 实现级 |
D4-implementation/frontend-monorepo/ |
Code-First · CI 强制 |
不在本次范围（Monorepo 落地后自动生成） |
2. 完整文档清单（D3 架构级 + D2 产品级）
2.1 D3 架构级（前端）— 共 6 份
| 编号 |
文件名 |
目的 |
受众 |
优先级 |
状态 |
| D3-FE-ARCH-001 |
D3-FE-ARCH-001-xi-ide-architecture.md |
7 产品统一前端架构宪章；Monorepo 结构；技术栈决策 |
架构师 / 所有开发 |
P0 |
✅ 本轮完成 |
| D3-FE-ARCH-002 |
D3-FE-ARCH-002-documentation-plan.md |
本文：文档清单与路线图 |
规划执行者 / 其他智能体 |
P0 |
✅ 本轮完成 |
| D3-FE-ARCH-003 |
D3-FE-ARCH-003-shared-ui-kit-architecture.md |
@xi/ui-kit / @xi/protocol / @xi/store-core / @xi/dsp-utils / @xi/ai-sdk 5 个共享 package 详细架构 |
前端基建工程师 |
P0 |
🚧 本轮完成 |
| D3-FE-ARCH-004 |
D3-FE-ARCH-004-implementation-plan-master.md |
实现 plan 总纲 · 各产品 plan 的索引与阶段划分 · 智能体消费入口 |
智能体 / 工程 leader |
P0 |
🚧 本轮完成 |
| D3-FE-ARCH-005 |
D3-FE-ARCH-005-routing-and-deep-link.md |
vue-router 路由规范 + xi:// deep-link URL Scheme 完整定义 |
各 app 前端 |
P1 |
⏳ 下批 |
| D3-FE-ARCH-006 |
D3-FE-ARCH-006-build-and-deploy-topology.md |
Monorepo 构建流 / CI / 发布拓扑 / CDN / 域名规划 |
DevOps / 部署工程师 |
P1 |
⏳ 下批 |
2.2 D2 产品级 · tech-arch（每产品 1 份，共 7 份）
| 编号 |
产品 |
文件路径 |
核心内容 |
优先级 |
状态 |
| D2-P1-TECH-002 |
XiStudio |
D2-products/P1-xistudio/tech-arch.md |
Shell 架构 · 内嵌机制 · Link Editor · Project Manager · Copilot 集成 |
P0 |
🚧 本轮更新（覆写现有 v1.0） |
| D2-P9-TECH-001 |
XiForge |
D2-products/P9-xiforge/tech-arch.md |
MC→XiForge 升级路径 · Module Designer · Algo Code Gen · Tuning UI Designer |
P0 |
🚧 本轮完成 |
| D2-P6-TECH-001 |
XiTune |
D2-products/P6-xitune/tech-arch.md |
Session · Measurement · Auto-Tune · Manual Tuner · A/B · Report |
P0 |
🚧 本轮完成 |
| D2-P7-TECH-001 |
XiTest |
D2-products/P7-xitest/tech-arch.md |
Test Suite · Module Unit Test · Integration Test · Regression · Report |
P1 |
⏳ 下批 |
| D2-P10-TECH-001 |
XiVST |
D2-products/P10-xivst/tech-arch.md |
双形态架构 · XVST 协议 · Plugin 生命周期 · Marketplace 站点 |
P1 |
⏳ 下批 |
| D2-P8-TECH-001 |
XiMind |
D2-products/P8-ximind/tech-arch.md |
ai-sdk 架构 · Function Calling · RAG · 多模态 · 后端契约 |
P1 |
⏳ 下批 |
| D2-P11-TECH-001 |
XiProbe |
D2-products/P11-xiprobe/tech-arch.md（DQ-01 确认 P11 编号后创建） |
Device Mgr · Signal Gen · Acquisition · Analysis · Tauri 桌面化 |
P2 |
⏳ 下批 |
2.3 D2 产品级 · prd / spec（各 7 份，下批产出）
| 类型 |
数量 |
优先级 |
说明 |
| prd.md |
7 |
P1 |
产品需求文档（用户故事 / 功能列表 / 版本矩阵 / 竞品对比） |
| spec.md |
7 |
P2 |
详细规格（UI 交互细节 / 数据字段 / 错误处理） |
注：prd / spec 的 7 份不在本轮产出范围。本轮聚焦 tech-arch 3 份（XiStudio/XiForge/XiTune）。其余 prd/spec 的模板在 D2-products/P{n}-{name}/ 已由前期占位，待本轮 tech-arch 敲定后按需填充。
2.4 D3-FE 实现 plan（每功能独立，共约 11 份）
| 编号 |
文件名（建议） |
覆盖功能 |
优先级 |
状态 |
| D3-FE-PLAN-000 |
implementation-plans/00-master.md |
实现 plan 总纲（即 D3-FE-ARCH-004） |
P0 |
🚧 本轮完成 |
| D3-FE-PLAN-001 |
implementation-plans/01-monorepo-bootstrap.md |
Monorepo 初始化 / packages 骨架 / CI 流 |
P0 |
⏳ 下批 |
| D3-FE-PLAN-002 |
implementation-plans/02-ui-kit.md |
@xi/ui-kit 开发（原子+分子+产品专用） |
P0 |
⏳ 下批 |
| D3-FE-PLAN-003 |
implementation-plans/03-protocol-and-store-core.md |
@xi/protocol + @xi/store-core |
P0 |
⏳ 下批 |
| D3-FE-PLAN-004 |
implementation-plans/04-xi-studio-shell.md |
XiStudio Shell + Link Editor 迁移（批次 1） |
P0 |
⏳ 下批 |
| D3-FE-PLAN-005 |
implementation-plans/05-xi-forge-alpha.md |
XiForge Alpha（module_creator 迁移 + AI 代码生成） |
P1 |
⏳ 下批 |
| D3-FE-PLAN-006 |
implementation-plans/06-xi-test-v05.md |
XiTest v0.5（module_test/test_runner/tuning_test 迁移） |
P1 |
⏳ 下批 |
| D3-FE-PLAN-007 |
implementation-plans/07-xi-tune-v09.md |
XiTune v0.9（auto_tune 迁移 + Measurement 新建） |
P1 |
⏳ 下批 |
| D3-FE-PLAN-008 |
implementation-plans/08-xi-vst-marketplace.md |
XiVST Marketplace Beta + 内嵌商店 |
P2 |
⏳ 下批 |
| D3-FE-PLAN-009 |
implementation-plans/09-xi-probe-y1.md |
XiProbe Y1 web + Y2 Tauri 化规划 |
P2 |
⏳ 下批 |
| D3-FE-PLAN-010 |
implementation-plans/10-ai-sdk-integration.md |
@xi/ai-sdk 集成 + Copilot 落地 |
P2 |
⏳ 下批 |
3. 本轮产出清单（阶段 C · Z 粒度）
用户确认的 Z 粒度 = 阶段 A (2 份) + 阶段 B + 前 5 份核心子文档。本轮交付映射：
| # |
文档 |
编号 |
路径 |
状态 |
| 1 |
顶层架构说明书 |
D3-FE-ARCH-001 |
D3-architecture/frontend/D3-FE-ARCH-001-xi-ide-architecture.md |
✅ 已完成 |
| 2 |
文档规划 Roadmap |
D3-FE-ARCH-002 |
D3-architecture/frontend/D3-FE-ARCH-002-documentation-plan.md |
🚧 本文 |
| 3 |
共享 UI kit 架构 |
D3-FE-ARCH-003 |
D3-architecture/frontend/D3-FE-ARCH-003-shared-ui-kit-architecture.md |
⏭ 下一份 |
| 4 |
实现 plan 总纲 |
D3-FE-ARCH-004 |
D3-architecture/frontend/D3-FE-ARCH-004-implementation-plan-master.md |
⏭ 之后 |
| 5 |
XiStudio tech-arch |
D2-P1-TECH-002 |
D2-products/P1-xistudio/tech-arch.md |
⏭ 之后 |
| 6 |
XiForge tech-arch |
D2-P9-TECH-001 |
D2-products/P9-xiforge/tech-arch.md |
⏭ 之后 |
| 7 |
XiTune tech-arch |
D2-P6-TECH-001 |
D2-products/P6-xitune/tech-arch.md |
⏭ 之后 |
4. 下批产出规划（人类拍板后启动）
4.1 下批 P1 优先级（建议一次性打包）
- D3-FE-ARCH-005 · routing-and-deep-link
- D3-FE-ARCH-006 · build-and-deploy-topology
- D2-P7/P10/P8-TECH-001 · XiTest / XiVST / XiMind tech-arch
- D3-FE-PLAN-001 ~ 004 · Monorepo Bootstrap + UI kit + Protocol + XiStudio Shell plans
4.2 下批 P2 优先级
- D2-P11-TECH-001 · XiProbe tech-arch（DQ-01 确认 P11 编号后）
- D3-FE-PLAN-005 ~ 010 · 其他产品 plan
- 各产品 prd / spec（如产品部有具体需求节奏）
4.3 产出节奏建议
| 阶段 |
覆盖 |
预估会话数 |
适合时点 |
| 本轮（Z 粒度） |
D3-FE-ARCH-001/002/003/004 + 3 份 tech-arch |
1 |
现在 |
| 下批 P1 |
ARCH-005/006 + 3 份 tech-arch + 4 份 plan |
1-2 |
本轮 review 通过后 |
| 下批 P2 |
P11 tech-arch + 6 份 plan + prd/spec 按需 |
1-2 |
P1 落地 code 后 |
5. 文档规范遵循
所有本规划下的文档必须遵守：
| 规范 |
具体要求 |
| MD 写作规范 v1.1 |
frontmatter 必填 title/description/level/category/status/author/date；L2 级 hero_show=false；禁 ASCII 框图 + emoji 标题；Mermaid 替代图形 |
| 文档编号 v1.0 |
doc_id 格式 D3-FE-{类型}-{序号} 或 D2-P{n}-{类型}-{序号}；路径 kebab-case |
| Docs-Code 同步 v1.0 |
D2-products 业务级 = Docs-First；D3-architecture/frontend = Docs-First 初稿+漂移容忍；实现 plan 执行后产物归 D4-implementation（Code-First CI） |
| mkdocs.yml nav |
每份新文档必须加入 nav；D3-architecture/frontend 子组 + D2-products/P{n} 子组 |
6. mkdocs.yml nav 更新计划
6.1 D3-architecture/frontend 子组插入点
现有 nav 结构（L431-464 附近）：
- D3 架构级:
- D3-architecture/index.md
- 系统架构:
- D3-architecture/system/...
- 前端架构:
- D3-architecture/frontend/index.md
- D3-architecture/frontend/architecture.md # ← 现有（待决定是否保留）
# ← 本轮新增插入点
本轮新增：
- 前端架构:
- D3-architecture/frontend/index.md
- 顶层架构:
- Xisound IDE 架构说明书: D3-architecture/frontend/D3-FE-ARCH-001-xi-ide-architecture.md
- 文档规划 Roadmap: D3-architecture/frontend/D3-FE-ARCH-002-documentation-plan.md
- 共享 UI kit 架构: D3-architecture/frontend/D3-FE-ARCH-003-shared-ui-kit-architecture.md
- 实现 plan 总纲: D3-architecture/frontend/D3-FE-ARCH-004-implementation-plan-master.md
- 既往文档:
- architecture（旧稿）: D3-architecture/frontend/architecture.md
6.2 D2-products 各产品 tech-arch 无需改 nav
（tech-arch.md 在各产品组已有条目，本轮仅覆写内容）
6.3 updating 策略
nav 更新在所有本轮文档写入完成最后一步统一修改，降低 mkdocs 解析失败风险。
7. 对其他智能体的消费指南
本规划的 D3-FE-PLAN- 系列（实现 plan）是交付给其他智能体执行*的入口。每份 plan 必须满足：
| 要素 |
要求 |
目的 |
| 前置依赖 |
列出依赖的 package / app / 其他 plan |
让智能体知道什么时候可以开工 |
| 具体文件清单 |
新建 / 修改 / 删除文件的完整路径 |
避免智能体判断失误 |
| 阶段划分 |
2-5 个阶段，每阶段有交付物 |
分步验证 |
| 人天预算 |
每阶段估时 |
进度可控 |
| 验收标准 |
自动化测试 / 手动检查清单 |
明确完成定义 |
| DQ 点 |
需要人类拍板的决策 |
避免智能体自行决策错方向 |
格式范本：参考前一任务产出的 D3-architecture/system/phase8-implementation-plan.md（Core Loop + 阶段预算 + 三端改动清单 + 测试矩阵）。
8. 版本与变更记录
| 版本 |
日期 |
作者 |
说明 |
| v1.0 |
2026-05-08 |
work-cline |
初稿；锚定本轮 Z 粒度 7 份产出 + 下批规划 |
附录 A · 文档索引矩阵（一页速查）
| 产品/组件 |
overview |
prd |
spec |
tech-arch |
实现 plan |
| XiStudio (P1) |
已有 published |
已有 published |
⏳ |
🚧 本轮 |
D3-FE-PLAN-004 |
| XiTune (P6) |
⏳ |
⏳ |
⏳ |
🚧 本轮 |
D3-FE-PLAN-007 |
| XiTest (P7) |
⏳ |
⏳ |
⏳ |
⏳ 下批 |
D3-FE-PLAN-006 |
| XiMind (P8) |
⏳ |
⏳ |
⏳ |
⏳ 下批 |
D3-FE-PLAN-010 |
| XiForge (P9) |
⏳ |
⏳ |
⏳ |
🚧 本轮 |
D3-FE-PLAN-005 |
| XiVST (P10) |
⏳ |
⏳ |
⏳ |
⏳ 下批 |
D3-FE-PLAN-008 |
| XiProbe (P11) |
⏳（DQ-01） |
⏳ |
⏳ |
⏳ 下批 |
D3-FE-PLAN-009 |
| 架构级 |
D3-FE-ARCH-001 ✅ |
D3-FE-ARCH-003 🚧 |
D3-FE-ARCH-005 ⏳ |
— |
D3-FE-ARCH-004 / PLAN-000 🚧 |