Migration Plan · 2026Q2 · v1.0.2

文档体系迁移计划 2026Q2 v1.0.2

4 阶段(P0 基础设施 / P1 高优 / P2 业务架构 / P3 全量收尾)· 12 周完成 332 篇 .md 重构

适用范围:AlgoDepartment/06_docs/site-build/docs/** · 受众:文档管理员智能体(执行主体)+ 各部门作者(配合方)

文档体系迁移计划 2026Q2 v1.0.2

本文档定位

角色:4 阶段可执行迁移蓝图 —— 从当前 D 系列 + 旧目录(332 篇 .md)迁移到 IA v3 数字前缀目标态
执行主体:文档管理员智能体(由其按本计划批量执行 mv / 改 frontmatter / 修链接)
配合方:各部门作者(P1-P3 阶段中负责本部门文档的内容审阅)
不管辖:具体技术实现细节(详见 folder-structure-spec.md / nav-display-spec.md / md-writing-spec.md)

v1.0.2 版本要点(2026-05-11 · 含 v1.0.1 nav 总入口补丁 + Stripe 三栏补丁)

4 阶段:P0(2 周)→ P1(3 周)→ P2(4 周)→ P3(3 周),共 12 周
总规模:332 篇 .md + CSS/JS 主题文件升级 + mkdocs.yml 重写(含 nav 字段从 D 系列切换到 IA v3 数字前缀)
P0 必须先于其他阶段完成(因为它建立基础设施),P1/P2/P3 可适度并行
每个阶段都有明确的「前置条件 / 工作清单 / 验收标准 / 风险」
⚠️ nav 字段改造贯穿 P0~P3 四个阶段:P0 切换一级骨架(§3.2 P0.3)/ P1 填充各目录二级条目(§4.2 P1.1 step 4)/ P2 每个产品迁移 PR 同步切换路径(§5.2 P2.0)/ P3 验收 nav 完整性(§6.3 关键验收 3)。禁止散落在各产品迁移子任务中

1. 总览图

gantt
    title Xisound 文档体系迁移 2026Q2(12 周)
    dateFormat YYYY-MM-DD
    section P0 基础设施
    规范 6 份归档定稿 :done, p0a, 2026-05-11, 1w
    主题 CSS/JS 升级 :active, p0b, after p0a, 1w
    section P1 高优文档
    创建 9 个一级目录 + index.md :p1a, after p0b, 0.5w
    01-strategy 迁移(原 D0)        :p1b, after p1a, 1.5w
    07-engineering 迁移            :p1c, after p1b, 0.5w
    06-customer 迁移(原 external) :p1d, after p1b, 0.5w
    section P2 业务架构
    02-products 迁移(原 D2 + D4) :p2a, after p1d, 2.5w
    03-platform 抽离(原 D3)      :p2b, after p2a, 1w
    04-departments 迁移(原 D1)   :p2c, after p2b, 0.5w
    section P3 全量收尾
    旧目录归档(00-spec/10-/20-) :p3a, after p2c, 1w
    Broken link 批量修复            :p3b, after p3a, 1w
    mkdocs build --strict 验证       :p3c, after p3b, 1w

2. 阶段总表

阶段	名称	工期	范围	文档量	验收
P0	基础设施	2 周	6 份规范定稿 + CSS/JS 升级 + mkdocs.yml 重构 + 9 个空目录	6 + 配置	nav-demo 4 份 HTML 在 mkdocs 体系下 1:1 复刻
P1	高优文档	3 周	01-strategy / 06-customer / 07-engineering	100+	PR checklist 全过 + 0 新增 broken link
P2	业务架构	4 周	02-products / 03-platform / 04-departments	200+	`legacy_doc_id` 全保留 + 各产品 13 稳态结构齐全
P3	全量收尾	3 周	99-archive 整理 + broken link 修复 + 验证	30+	`mkdocs build --strict` 通过

总工期:12 周(2026-05-11 ~ 2026-08-03)

3. P0 · 基础设施(2 周 · 2026-05-11 ~ 2026-05-25)

3.1 目标

把"未来全站迁移所需的全部基础设施"一次性就位: - 6 份规范文档归档完成(本计划之 D1-D6) - 主题 CSS/JS 升级(应用 10 条视觉决议) - mkdocs.yml 主配置升级(features / extra_css/js / palette) - 9 个一级目录的物理空壳 + index.md 占位

3.2 工作清单

任务 P0.1 · 6 份规范定稿归档(✅ 本计划完成时已就绪)

文件	路径	状态
`format-spec-changelog.md` v1.0.1	`docs/D0-company/05-standards/`	✅
`brand-color-system.md` v1.2	同上	✅
`md-writing-spec.md` v2.0	同上	✅
`nav-display-spec.md` v1.0.1	同上	✅
`folder-structure-spec.md` v1.0	同上	✅
`migration-plan-2026Q2.md` v1.0.2(本文)	同上	✅

注:这 6 份现位于 D0-company/05-standards/,P1 阶段会随 01-strategy → 05-standards 拆分时整体移到 docs/05-standards/。

任务 P0.2 · 主题 CSS/JS 升级(应用 10 条视觉决议)

按 format-spec-changelog.md §3 工程落地依赖矩阵执行:

#	文件动作	内容
1	`xiyin-extra.css` 末尾追加	9 个 §块的 CSS(总 ~250 行):xy-quote / xy-glossary / xy-gantt / xy-stack / xy-frac / xy-mermaid-zoom / status-badge / tabbed-active / xy-status-banner
2	`xiyin-brand.css` 检查并补齐	18 个产品 6 色变量(`--L0-bg ~ --L5-text`)— 详见 brand-color-system.md §6
3	`xiyin-patch.css` 替换	Admonition 由「全部统一极光青」改为「6 组语义配色」— 详见 brand-color-system.md §4.2
4	新建 `docs/assets/javascripts/xiyin-mermaid-zoom.js`	完整代码见 format-spec-changelog.md §决议 7
5	新建 `docs/assets/javascripts/xiyin-katex.js`	完整代码见 format-spec-changelog.md §决议 8
6	`xiyin-mermaid.js` 检查	`themeVariables` 是否含 `gantt*` 系列(决议 6a),缺则补
7 ⭐	Stripe 三栏布局接管 Material(v1.0.1 新增)	落地决议 10:① `xiyin-brand.css` 加 11 个 `--xy-sidebar-* / --xy-main-* / --xy-stripe-*` 变量;② `xiyin-extra.css` 加 nav-display-spec §3.7 完整接管 CSS(`.md-sidebar--primary 260px 深色` / `.md-sidebar--secondary 220px 边框` / `.md-content max-width 720px` / 当前项 2px 玫瑰金色条);③ 验收等同于 `nav-demo/demo-1-stripe-style.html`

任务 P0.3 · `mkdocs.yml` 主配置升级

按 nav-display-spec.md 执行:

§	修改点	备注
§1	`theme.features` 完整列表(17 项)	必选导航 / 搜索 / 内容 / TOC 类
§3.1	`extra_css` / `extra_javascript` 加载顺序固化	7 个 JS 顺序敏感
§6	`theme.palette` 改为 `primary: custom` `accent: custom`	让 xiyin-brand.css 接管
§7	`plugins` 加 `mkdocs-redirects`	为 P3 阶段重定向旧 URL 做准备
-	`nav` 切换为 IA v3 一级骨架(00/01/02/03/04/05/06/07/99)	P0 完成站点入口切换;P1/P2 再迁移各目录下具体内容树

任务 P0.4 · `overrides/main.html` Jinja2 模板升级

§	添加内容
`nav-display-spec.md §3.2`	KaTeX 按 `katex: true` frontmatter 动态加载
`nav-display-spec.md §5.2`	status 徽章 + deprecated 横幅渲染逻辑

任务 P0.5 · 创建 9 个一级目录的物理空壳

# 在 docs/ 下创建空目录 + 占位 index.md(用 nav-display-spec.md §4.3 模板)
mkdir -p docs/00-home docs/01-strategy docs/02-products docs/03-platform \
         docs/04-departments docs/05-standards docs/06-customer \
         docs/07-engineering docs/99-archive

# 为每个目录创建占位 index.md(P1-P3 阶段填充)
for dir in 00-home 01-strategy 02-products 03-platform 04-departments \
           05-standards 06-customer 07-engineering 99-archive; do
  if [ ! -f "docs/$dir/index.md" ]; then
    cp docs/D0-company/05-standards/templates/index-template.md docs/$dir/index.md
  fi
done

3.3 P0 验收标准

6 份规范文档全部 status: published
xiyin-extra.css 含 9 个 §块,xiyin-brand.css 含产品 6 色变量
xiyin-mermaid-zoom.js / xiyin-katex.js 都创建并加载
mkdocs.yml: nav 已切换为 IA v3 一级骨架(00/01/02/03/04/05/06/07/99)
关键验收 1:在 mkdocs 体系下打开任一 .md 测试页,9 条视觉组件全部正确渲染(等同于 nav-demo 4 份 HTML)
关键验收 2 ⭐:Stripe 三栏布局已落地 — 视觉等同于 nav-demo/demo-1-stripe-style.html:
三栏宽度严格 260px / 1fr(主区 max 720px)/ 220px
左侧栏深海军蓝 #0a2540 + 字号 13/12.5/11px(L1/L2/L3-或group)
当前项有 2px 玫瑰金色条(var(--yin) 接管 Stripe 紫)
右 TOC 有 1px 浅灰左边线 + 当前项玫瑰金边线
移动端(<900px)单栏退化正常
0 残留 Stripe 紫 #635bff / 蓝 #00d4ff(全文 grep 验证)
mkdocs build --strict 通过(只允许 103 个 P0 阶段已知 warning,不增不减)
9 个一级目录物理空壳 + index.md 占位创建完成

3.4 P0 风险登记

风险	影响	缓解
Admonition 6 组配色 CSS 选择器与 Material 主题冲突	视觉错乱	在 staging 分支测 + 完整 grep `.admonition` 现有样式
KaTeX 按 frontmatter 动态加载在某些 mkdocs 版本不工作	公式不渲染	实测 mkdocs material 9.x;若失败 fallback 到全站加载
旧 `xiyin-patch.css` 的 `!important` 影响新决议	决议不生效	用浏览器 devtools 逐个组件验证;必要时清理 patch.css
Stripe 三栏布局 Material 默认 `.md-sidebar--secondary` 不显示完整 TOC 边线	三栏视觉不到位	必须用 `!important` 覆盖 width / border-left;或 `overrides/main.html` 改 sidebar 模板
Stripe 主区 max-width 720px 与现有 Hero 全宽冲突	L1A/L1B 首页样式断	用 `body.level-l1a / body.level-l1b` 选择器例外,只对 L2/L3 文档生效 720px 限制

4. P1 · 高优文档(3 周 · 2026-05-25 ~ 2026-06-15)

4.1 目标

把最重要、最稳定、最少冲突的目录优先迁移到 IA v3: - 01-strategy(原 D0-company / 36 篇) - 06-customer(原 external / 33 篇) - 07-engineering(原 D3-execution + 部分 D6-testing-ops / 3 篇) - 04-departments 部分(D6-testing-ops → 04-departments/test/)

4.2 工作清单

任务 P1.1 · 01-strategy 迁移(原 D0-company)

当前路径:                     →  目标路径:
docs/D0-company/00-vision/     →  docs/01-strategy/00-vision/
docs/D0-company/01-brand/      →  docs/01-strategy/01-brand/
docs/D0-company/02-policies/   →  docs/01-strategy/02-policies/
docs/D0-company/03-finance/    →  docs/01-strategy/03-finance/
docs/D0-company/04-roadmap/    →  docs/01-strategy/04-roadmap/
docs/D0-company/05-standards/  →  docs/05-standards/  (拆出独立一级目录)

操作步骤:

批量 git mv(保留 git 历史):

git mv docs/D0-company/00-vision docs/01-strategy/00-vision
# ... 重复
git mv docs/D0-company/05-standards docs/05-standards   # 拆出
rmdir docs/D0-company   # 空目录删除

每个 .md 加 legacy_doc_id:

---
doc_id: SPEC-VISION-001
legacy_doc_id: D0-company/00-vision/strategy-whitepaper.md   # ← 加这行
---

批量更新内部链接:用脚本搜索 D0-company/ 替换为 01-strategy/(注意 05-standards 单独处理)。
更新 mkdocs.yml: nav 的 01-strategy / 05-standards 二级条目(P0 阶段一级骨架已切换
```
                # 
```
,本任务只填二级路径): href="#__codelineno-4-1">- 01 战略: - 概览: 01-strategy/index.md # P0 已激活骨架 - 00 愿景与战略: 01-strategy/00-vision/index.md - 01 品牌与 VI: 01-strategy/01-brand/index.md - 02 公司制度: 01-strategy/02-policies/index.md - 03 融资与法务: 01-strategy/03-finance/index.md - 04 公司 Roadmap: 01-strategy/04-roadmap/index.md p-Indicator">- 05 标准: - 规范总览: 05-standards/index.md # 升为独立一级目录 - 格式变更日志(底座): 05-standards/format-spec-changelog.md - MD 写作规范 v2.0: 05-standards/md-writing-spec.md - 品牌色彩系统 v1.2: 05-standards/brand-color-system.md - 目录显示规范: 05-standards/nav-display-spec.md - 目录结构规范: 05-standards/folder-structure-spec.md - 文档编号规范: 05-standards/doc-numbering.md - PR 检查清单: 05-standards/checklist.md - 跨部门交付索引: 05-standards/release-to-other-depts.md - 迁移计划 2026Q2: 05-standards/migration-plan-2026Q2.md P0 阶段已删除原 - 📘 D0 公司级一级条目,本任务只填充新结构二级

任务 P1.2 · 06-customer 迁移(原 external)

docs/external/  →  docs/06-customer/

操作类同 P1.1。external 有 33 个文件,但结构相对简单(主要 4 个二级子目录:overview / case-studies / partner / support)。

任务 P1.3 · 07-engineering 迁移

docs/D3-execution/    →  docs/07-engineering/  (2 文件)

注:D3-execution 命名歧义已确认应该归 07(全局工程过程,见 folder-structure-spec.md §9)。

任务 P1.4 · 04-departments 部分迁移

docs/D6-testing-ops/  →  docs/04-departments/test/  (1 文件)

完整 D1-divisions(49 文件)→ 04-departments 在 P2 进行,本阶段只搬测试运维这 1 篇。

4.3 P1 验收标准

01-strategy / 05-standards / 06-customer / 07-engineering 物理结构完整
所有迁移文件 frontmatter 含 legacy_doc_id
新文档全部应用 v2.0 frontmatter 字段(doc_id 等)
mkdocs build --strict 不引入新 warning(原 103 个保留)
9 条视觉组件在试点文档中实际使用(每个一级目录至少 1 个示例)
mkdocs.yml: nav 更新到位

4.4 P1 风险登记

风险	影响	缓解
`git mv` 后 git 历史断裂	失去文件演化追溯	用 `git mv -k`,验证 `git log --follow` 仍能跟踪
内部链接破坏(其他文档引用 D0-company/)	broken link 暴增	批量脚本 + `mkdocs build --strict` 双向验证
05-standards 拆出独立一级目录后,nav 顺序混乱	UX 问题	严格按 nav-display-spec.md §2.2 顺序

5. P2 · 业务架构(4 周 · 2026-06-15 ~ 2026-07-13)

5.1 目标

迁移最大体量、最复杂的目录: - 02-products(原 D2-products + 部分 D4-implementation / 152 篇) - 03-platform(原 D3-architecture / 37 篇) - 04-departments(原 D1-divisions / 49 篇)

5.2 工作清单

任务 P2.0 · mkdocs.yml nav 同步规则 ⭐(P2 阶段强制约束)

关键约束:P2 阶段每完成一个产品 / 一个目录的物理迁移,当次 PR 必须同步更新 mkdocs.yml: nav 中对应条目的二级路径。一级骨架在 P0 已切换,P2 阶段只动二级及以下条目。

操作模板(每个产品迁移完后,在同一个 PR 内执行):

# 迁移前(P0 一级骨架 + P1 临时双轨,二级仍指向 D 系列)
- 02 产品:
    - 概览: 02-products/index.md           # P0 已激活
    - P1 XiStudio: D2-products/P1-xistudio/index.md   # ← P2 待切换

# 迁移后(P2 切换为 IA v3 完整路径 + 13 稳态子目录)
- 02 产品:
    - 概览: 02-products/index.md
    - P1 XiStudio:
        - 概览: 02-products/P1-xistudio/index.md
        - 业务: 02-products/P1-xistudio/01-business/index.md
        - 架构: 02-products/P1-xistudio/02-architecture/index.md
        - 模块: 02-products/P1-xistudio/03-modules/index.md
        # ... 11 个稳态子目录

禁止: - ❌ P2 阶段任何 PR 中,迁移了文件但未更新 mkdocs.yml: nav — 会造成 nav 死链 - ❌ 在不同 PR 中拆分「文件迁移」和「nav 更新」— 必须原子提交(一个 PR 同时改这两件事) - ❌ 跳过临时双轨直接重写整个 nav — 会导致中间态 broken

自动化检查脚本(P0.5 创建 verify-nav.py):

python scripts/verify-nav.py mkdocs.yml docs/
# 验证 nav 中所有路径都指向实际存在的 .md 文件
# 任何死链 → exit 1

任务 P2.1 · 02-products 迁移(2.5 周 · 132 篇)

这是 P2 的主战场。每个产品(P1-xistudio ~ P11-ximind)都要按 folder-structure-spec.md §3.3 的 13 稳态结构重组:

当前 docs/D2-products/P1-xistudio/                  →  目标 docs/02-products/P1-xistudio/
├── tech-arch.md                                   →  ├── 02-architecture/tech-arch.md
├── modules/source/00-architecture.md              →  ├── 03-modules/source/00-architecture.md
├── _dev/phases/PHASE-008-implementation.md        →  ├── _dev/phases/PHASE-008-implementation.md (路径不变,父目录改)
└── ...                                                ...

# D4-implementation/ 各产品的 phases 文档并入对应产品的 _dev/phases/
docs/D4-implementation/P1-xistudio/PHASE-XX.md     →  docs/02-products/P1-xistudio/_dev/phases/PHASE-XX.md

逐产品迁移顺序(从已试点的开始): 1. P1-XiStudio(已试点 6 commits) 2. P3-XiAlgo / P4-XiDSP / P5-XiCore(芯片 + 算法核心) 3. P2-XiForge(工具) 4. P6-XiAmp / P7-XiBox(硬件) 5. P8-XiTune / P9-XiMic / P10-XiCalProbe(测试调音) 6. P11-XiMind(云端)

每个产品的内部步骤: 1. 创建 02-products/PN-product/ 下 11 个稳态子目录 2. 把当前文件按 folder-structure-spec.md §7.2 命名重命名 + 移到对应稳态子目录 3. 更新 frontmatter doc_id + legacy_doc_id 4. 更新 index.md 列出本产品所有稳态文档 5. 修内部链接

任务 P2.2 · 03-platform 抽离(1 周 · 37 篇)

D3-architecture/ 内容双向分流: - 跨产品稳态部分(协议 / 数据模型 / DSP 通用规范)→ 03-platform/ - 特定产品的架构部分 → 对应 02-products/PN/02-architecture/

需要逐文件人工判断,典型分流: | D3-architecture 文件 | 目标 | |:---|:---| | protocols/websocket-spec.md | 03-platform/01-protocols/ | | data-models/patch.md | 03-platform/02-data-models/ | | dsp-spec/sample-tick-model.md | 03-platform/04-dsp-spec/ | | xistudio-engine-arch.md | 02-products/P1-xistudio/02-architecture/ |

任务 P2.3 · 04-departments 迁移(0.5 周 · 49 篇)

docs/D1-divisions/algo/         →  docs/04-departments/algo/
docs/D1-divisions/product/      →  docs/04-departments/product/
docs/D1-divisions/hardware/     →  docs/04-departments/hardware/
... (6 个部门子目录)

操作相对简单(目录命名一一对应)。

5.3 P2 验收标准

11 个产品全部完成 13 稳态结构重组
03-platform 5 个子目录完整(协议 / 数据模型 / 部署 / DSP / UI Kit)
04-departments 6 个子目录完整
每个产品的 index.md 列出全部稳态文档清单
关键验收:试点产品 P1-XiStudio 用 v2.0 规范重写至少 5 篇核心稳态文档(展示 9 条视觉组件实战效果)
broken link 数量不超过 P0/P1 阶段基线(103 + 新增 ≤ 30)

5.4 P2 风险登记

风险	影响	缓解
132 篇 D2-products 文件迁移路径错误	大规模 broken link	每个产品迁移完单独 PR + mkdocs build 验证
D3-architecture 分流判断不准确	架构文档分类混乱	人工分流 + 各产品 owner 复核
历史 `_dev/` 文件 ADR/PHASE 编号冲突	命名重复	用脚本扫描所有 `<TYPE>-NNN-` 编号去重
试点 6 commits 已用旧路径	需二次迁移	试点文件优先 P2 第一批迁移,frontmatter 加双 `legacy_doc_id`

6. P3 · 全量收尾(3 周 · 2026-07-13 ~ 2026-08-03)

6.1 目标

清理所有遗留 + 修复全部 broken link + 通过最严格的 mkdocs build 验证: - 旧目录归档(00-spec / 10-product-matrix / 20-doc-system / _audit) - 99-archive 目录整理 - 全站 broken link 修复 - mkdocs build --strict 全通过

6.2 工作清单

任务 P3.1 · 旧目录归档(1 周)

docs/00-spec/             →  docs/99-archive/2026-04-pre-ia-v3/old-spec/  (6 文件)
docs/10-product-matrix/   →  内容并入 docs/02-products/index.md  (2 文件)
docs/20-doc-system/       →  内容并入 docs/05-standards/  (2 文件)
docs/_audit/              →  docs/99-archive/audit/  (1 文件)

归档原则(详见 folder-structure-spec.md §5.3): - ✅ mv 不 rm - ✅ frontmatter 加 status: deprecated + legacy_doc_id - ✅ 用 mkdocs-redirects 配置旧 URL 重定向到新位置

任务 P3.2 · Broken link 批量修复(1 周)

来源	处理
103 个 P0 阶段已知 warning	全量修复
P1-P2 阶段新增 warning	全量修复
`legacy_doc_id` 引用的旧路径	配 `mkdocs-redirects` 而非修改源文档

修复脚本(可由智能体执行):

python scripts/fix-broken-links.py \
  --docs-root docs/ \
  --redirect-config mkdocs.yml \
  --output-report _audit/broken-links-fixed-2026-08.md

任务 P3.3 · 最终验证(1 周)

# 1. 严格构建验证
cd AlgoDepartment/06_docs/site-build
python -m mkdocs build --clean --strict

# 2. nav 完整性验证(每个 nav 入口必须存在对应文件)
python scripts/verify-nav.py mkdocs.yml docs/

# 3. frontmatter 合规验证(发布级文档必须有 doc_id 等)
python scripts/verify-frontmatter.py docs/

# 4. 9 条视觉组件渲染验证(在浏览器实际打开 mkdocs serve)
python -m mkdocs serve
# 然后人工抽样检查关键页面

6.3 P3 验收标准

关键验收 1:mkdocs build --strict 0 warning + 0 error
关键验收 2:旧目录(00-spec / 10- / 20- / _audit / D0-D6 全部前缀)在 docs/ 下不存在
关键验收 3 ⭐ nav 完整切换:
mkdocs.yml: nav 字段顶层 9 项严格按 IA v3 顺序(00-home / 01-strategy / 02-products / 03-platform / 04-departments / 05-standards / 06-customer / 07-engineering;99-archive 在 footer 小入口)
0 残留 D 系列前缀(📘 D0 / 📦 D2 / 🏛️ D3 等一级条目)
0 残留 旧入口(旧目录 / 产品矩阵(旧入口) / 文档体系(旧入口) / 🎨 格式 Demo 等)
0 死链:python scripts/verify-nav.py mkdocs.yml docs/ 退出码 0
所有二级路径都指向 IA v3 数字前缀目录(没有任何二级路径残留指向 D2-products / D3-architecture 等)
关键验收 4 ⭐ Stripe 布局视觉合规(v1.0.1 新增):
全站任一文档页打开后,视觉 100% 等同于 nav-demo/demo-1-stripe-style.html
三栏宽度严格 260 / 1fr(主区 720) / 220 像素 — 用浏览器 devtools 测量
侧栏字号 L1=13px / L2=12.5px / L3=12.5px / group-title=11px uppercase(全部对齐)
当前项 2px 玫瑰金色条 在所有页面正常显示(无遗漏 / 无错位)
0 残留 Stripe 原色:grep -rn "#635bff\|#00d4ff" docs/assets/ 无输出
移动端(< 900px)单栏退化 + 侧栏可抽屉切换
99-archive 含完整时间分组(2026-01 / 2026-04 / audit)
mkdocs-redirects 配置至少 50 条旧→新 URL 重定向
frontmatter 合规率 ≥ 95%(发布级文档有 doc_id)
站点首页 + 9 个一级目录 index.md 全部 L1B 渲染正常(Hero + 视觉组件展示)
PR 全部合并到 main,试点分支 feat/docs-migration-source-sink-pilot 关闭

6.4 P3 风险登记

风险	影响	缓解
`--strict` 模式因为 P2 遗漏的 warning 失败	无法验收	P3.2 阶段反复迭代直到 0 warning
旧 URL 用户书签全部失效	客户/合作方流失	`mkdocs-redirects` 必须覆盖至少 P0/P1/P2 重要文档
试点 commits 与 P2 迁移冲突	git 合并困难	P2 阶段先 rebase 试点分支到 main

7. 跨阶段约束

7.1 必须遵守的红线

❌ 不允许直接 rm:任何文件删除前必须先 mv 到 99-archive/(详见 folder-structure-spec.md §5.3)
❌ 不允许动 xiyin-brand.css 三色法典 hex(P0 只允许追加,不允许改既有变量)
❌ 不允许跳过 frontmatter 升级(每个迁移文件必须加 legacy_doc_id)
❌ 不允许提交 mkdocs build 有新增 error 的 PR

7.2 提交工作流

每个阶段都按以下子流程:

flowchart LR
    A[创建阶段分支<br>feat/migration-PN] --> B[批量 git mv<br>+ frontmatter 升级]
    B --> C[mkdocs build 验证]
    C --> D{warning 数量}
    D -- 不超基线 --> E[创建 PR + 文档管理员审]
    D -- 超基线 --> B
    E --> F[各部门 owner 内容复核]
    F --> G[merge to main]

    class A,B,E xyL3
    class C,D xyWarn
    class F,G xyL5

7.3 PowerShell 注意

执行命令含 $ 时(如 git log --pretty=$format),用 .ps1 脚本 + pwsh -File 规避吞噬:

# bad
pwsh -c "git log --pretty=$format"   # $format 会被 PowerShell 当作变量吃掉

# good
pwsh -File scripts/git-log-export.ps1

8. 工具与脚本依赖

文档管理员智能体需要这些脚本(P0 阶段创建):

脚本	路径	用途
`migrate-d-to-ia-v3.ps1`	`scripts/migrate-d-to-ia-v3.ps1`	批量 git mv + frontmatter 升级
`fix-broken-links.py`	`scripts/fix-broken-links.py`	扫描 + 修复 broken link
`verify-nav.py`	`scripts/verify-nav.py`	验证 mkdocs.yml nav 与文件系统一致性
`verify-frontmatter.py`	`scripts/verify-frontmatter.py`	验证 frontmatter 合规率
`bump-doc-id.py`	`scripts/bump-doc-id.py`	批量分配 doc_id

9. 与下游的关系

flowchart TD
    A["migration-plan-2026Q2.md<br>(本文档 · 4 阶段执行蓝图)"] -->|目标态依据| B["folder-structure-spec.md<br>(IA v3 物理结构)"]
    A -->|配置目标| C["nav-display-spec.md<br>(站点级配置)"]
    A -->|frontmatter 升级模板| D["md-writing-spec.md v2.0"]
    A -->|9 条决议落地清单| E["format-spec-changelog.md<br>(视觉决议来源)"]
    A -->|color 变量补齐| F["brand-color-system.md v1.2"]

    G[文档管理员智能体] -->|执行主体| A
    H[各部门作者] -->|配合方| A

    class A xyL5
    class B,C,D xyL1
    class E,F xyL2
    class G,H xyL3

10. 修订历史

版本	日期	修订人	关键变更
v1.0.2	2026-05-11	AlgoDepartment	Stripe 三栏布局补丁:① P0.2 主题升级表新增任务 #7「Stripe 三栏布局接管 Material」(11 个 CSS 变量 + 完整接管 CSS);② P0.3 验收新增「关键验收 2 Stripe 布局已落地」6 项硬性检查;③ P0.4 风险登记新增 Stripe 与 Material 默认双栏 / 与 Hero 全宽冲突 2 类风险;④ P3 验收新增「关键验收 4 Stripe 布局视觉合规」6 项硬性检查 — 落地第一组导航方案决议(Demo 1 Stripe 风格,此前在 plan 中漏记录)
v1.0.1	2026-05-11	AlgoDepartment	nav 总入口补丁:nav 字段改造贯穿 P0~P3 / P2.0 nav 同步规则 / P3 验收 nav 完整切换
v1.0	2026-05-11	AlgoDepartment	首版发布 · 4 阶段(P0/P1/P2/P3)12 周计划 · 332 篇 .md 全量迁移到 IA v3

致文档管理员智能体

本计划完成后,你应: 1. 严格按 §3-§6 顺序执行 4 阶段,P0 必须最先完成 2. 每个阶段验收标准必须 100% 满足才进入下一阶段 3. 每次迁移失败时优先回滚到上次 PR,不允许在错误状态上叠加 4. 所有红线(§7.1)是硬约束,违反必须立即停止并向用户汇报 5. 完成后提交最终交付报告(可仿照 nav-demo/docs-migration-pilot-report.md 站外历史草案格式 · P3 阶段归档到 99-archive/)

文档体系迁移计划 2026Q2 v1.0.2

文档体系迁移计划 2026Q2 v1.0.2

1. 总览图

2. 阶段总表

3. P0 · 基础设施(2 周 · 2026-05-11 ~ 2026-05-25)

3.1 目标

3.2 工作清单

任务 P0.1 · 6 份规范定稿归档(✅ 本计划完成时已就绪)

任务 P0.2 · 主题 CSS/JS 升级(应用 10 条视觉决议)

任务 P0.3 · mkdocs.yml 主配置升级

任务 P0.4 · overrides/main.html Jinja2 模板升级

任务 P0.5 · 创建 9 个一级目录的物理空壳

3.3 P0 验收标准

3.4 P0 风险登记

4. P1 · 高优文档(3 周 · 2026-05-25 ~ 2026-06-15)

4.1 目标

4.2 工作清单

任务 P1.1 · 01-strategy 迁移(原 D0-company)

任务 P1.2 · 06-customer 迁移(原 external)

任务 P1.3 · 07-engineering 迁移

任务 P1.4 · 04-departments 部分迁移

4.3 P1 验收标准

4.4 P1 风险登记

5. P2 · 业务架构(4 周 · 2026-06-15 ~ 2026-07-13)

5.1 目标

5.2 工作清单

任务 P2.0 · mkdocs.yml nav 同步规则 ⭐(P2 阶段强制约束)

任务 P2.1 · 02-products 迁移(2.5 周 · 132 篇)

任务 P2.2 · 03-platform 抽离(1 周 · 37 篇)

任务 P2.3 · 04-departments 迁移(0.5 周 · 49 篇)

5.3 P2 验收标准

5.4 P2 风险登记

6. P3 · 全量收尾(3 周 · 2026-07-13 ~ 2026-08-03)

6.1 目标

6.2 工作清单

任务 P3.1 · 旧目录归档(1 周)

任务 P3.2 · Broken link 批量修复(1 周)

任务 P3.3 · 最终验证(1 周)

6.3 P3 验收标准

6.4 P3 风险登记

7. 跨阶段约束

7.1 必须遵守的红线

7.2 提交工作流

7.3 PowerShell 注意

8. 工具与脚本依赖

9. 与下游的关系

10. 修订历史

任务 P0.3 · `mkdocs.yml` 主配置升级

任务 P0.4 · `overrides/main.html` Jinja2 模板升级