DRAFT

文件命名规则 · 实施计划（待决策）

本文档定位

本文档不是规范，而是为下一次"文件命名规则讨论"任务准备的输入备份。收纳：现状观察、各种命名风格的并存证据、待决策问题清单、可选方案、建议步骤。一旦讨论完成并产出决议，本文档将升级为正式规范（参考 doc-numbering.md 体例），或合并进 folder-structure-spec.md。

触发上下文

P3.1a Step 2（auto-index hook + 19 个 L2 index.md v2.0 改写，commit 99580cc）完成后，用户原话："将命名规则作为一个 plan 实施计划，作为文档备份，下次任务处理"。完成 auto-index 自动化后，文件命名规则的确定性变得更重要——hook 按"数字前缀 → 字母序"自然排序，若文件命名风格不统一，卡片排序会出现非预期顺序。

1. 现状观察（事实核查 · 2026-05-13）

1.1 现存的三种命名风格并存

风格	示例	存在位置
A · 数字前缀（NN-）+ 短主题	`00-overview.md` / `10-xi-ide-architecture.md` / `90-preset-lifecycle.md`	`03-platform/30-frontend/`、`02-products/P*/`（最常见）
B · 纯主题名	`vision-mission.md` / `module-customization.md` / `awe.md`	`01-strategy/00-vision/`、`08-implementation/10-dsp-algo/modules/`
C · 含字母前缀	`D3-FE-ARCH-007-...md`（已迁旧名）、`P11-xiprobe/30-architecture.md`	部分历史迁移文件、部分二级目录名

1.2 目录命名风格也分两类

有数字前缀：01-strategy/ / 10-architecture/ / 30-frontend/ / 10-dsp-algo/
无数字前缀：xialgo/ / xiamp/（06-customer/30-products/ 下产品目录）

1.3 frontmatter `doc_id` 格式

当前已有两种： - 三段数字：01.00.001 / 03.30.001 / 08.10.001（IA-v3 主流） - 保留旧码：legacy_doc_id: D0-company/00-vision/index.md / D3-ARCH-FE-000

1.4 影响 auto-index hook 排序的具体场景

hook 当前排序规则（见 overrides/hooks/auto_index.py: _sort_key）： 1. 优先：有数字前缀的文件（00- < 10- < 20- < ...，自然数字序） 2. 其次：无数字前缀的文件（按字母序，CJK 按 Unicode 码点）

实际后果： - 01-strategy/00-vision/ 的 5 个子文档全部为风格 B（无数字前缀），渲染顺序为： product-matrix → roadmap-3y → strategy-3y → strategy-whitepaper → vision-mission （字母序），与人脑预期"vision → strategy → roadmap → matrix → whitepaper"不一致。 - 03-platform/30-frontend/ 的 10 个子文档全部为风格 A（数字前缀），渲染顺序与目录名自然一致。

2. 待决策问题清单

Q1 · 是否强制全站文件名采用"数字前缀 + 短主题"风格？

选项 1a：强制所有非 index 子文档采用 NN-topic.md 格式（NN 为 00/10/20/...）
选项 1b：仅强制有 ≥3 个子文档的目录采用数字前缀
选项 1c：不强制，允许并存（继续依赖 hook 自然排序兜底）

Q2 · 数字前缀的步长是多少？

选项 2a：步长 5（00 / 05 / 10 / 15 / ...）便于中间插入
选项 2b：步长 10（00 / 10 / 20 / ...）当前主流，简洁
选项 2c：步长 1 + 三位数（001 / 002 / 003 / ...）极致严格

Q3 · 是否对 frontmatter 强制要求 title/description？

选项 3a：强制（hook 不再需要 H1 兜底，元数据更整齐）
选项 3b：仅强制 title，description 可空
选项 3c：不强制（继续依赖 hook 容错链：frontmatter → H1 → 文件名）

Q4 · 目录命名是否统一加数字前缀？

选项 4a：所有 ≥L2 目录强制 NN-name/（含 06-customer/30-products/xialgo/ → xx-xialgo/）
选项 4b：仅 L2 目录强制（已基本做到），L3+ 自由
选项 4c：现状为准（06-customer/30-products/ 下产品目录无前缀，保留语义可读性）

Q5 · 是否引入文件命名 lint 工具？

选项 5a：写 scripts/lint-filenames.ps1 在 mkdocs build 前/CI 跑一次
选项 5b：依赖人工 review + 命名规范文档约束
选项 5c：在 auto-index hook 内置警告（构建时打印不规范的文件名 INFO 日志）

Q6 · 历史 `legacy_doc_id` 字段是否最终清理？

当前所有迁移文件保留了 legacy_doc_id: D0-company/...、D3-ARCH-FE-000 等
选项 6a：永久保留（历史可追溯、redirect_maps 可读）
选项 6b：N 个月后批量清理（mkdocs.yml 的 redirect_maps 仍生效，因此 frontmatter 字段冗余）
选项 6c：迁出 frontmatter 到 _audit/ 下的迁移日志

3. 参考方案（如果决定立规则）

3.1 提议命名规范 v1（草案，供讨论起点）

[NN]-[kebab-case-topic].md

NN：00 / 10 / 20 / 30 / ... / 90（步长 10，为中间插入预留空间）
kebab-case-topic：小写 + 连字符分隔，无空格、无大写、无下划线
index.md：保留为目录入口名，不加数字前缀

示例： - ✅ 00-overview.md - ✅ 10-xi-ide-architecture.md - ❌ vision_mission.md（下划线） - ❌ Module-Customization.md（大写） - ❌ module customization.md（空格）

3.2 frontmatter 必填字段建议

---
title: ...           # 必填，用于卡片标题、nav、搜索
description: ...     # 必填（可为空字符串），用于卡片描述、SEO meta
status: published|draft|migrated|archived  # 必填
owner: ...           # 必填
last_review: YYYY-MM-DD  # 必填
version: X.Y.Z       # 必填
---

3.3 与 auto-index hook 的协作

hook 已支持 icon: material-xxx 字段从 frontmatter 读取卡片图标
后续可扩展支持 auto_index_skip: true 让某文件不进卡片
若全站统一数字前缀，hook 排序天然稳定，无需特殊配置

4. 下次任务建议步骤

共识达成：先讨论 Q1~Q4 的方向（建议 Q1=1a / Q2=2b / Q3=3a / Q4=4c），15~30 分钟
影响面评估：跑脚本统计当前不符合提议规范的文件数量（写一个 scripts/audit-filenames.ps1），10 分钟
批量重命名脚本：参照 scripts/p2-fix-internal-links.ps1 模式写 scripts/p32-rename-to-spec.ps1，含 dry-run + git mv + redirect_maps 联动更新，30~60 分钟
正式规范化：把本 plan 文档升级为 file-naming-spec.md（与 doc-numbering.md 同级体例），15 分钟
CI/lint 集成：可选 · 在 GitHub Actions deploy.yml 增加文件名校验步骤，15 分钟

预计总工时：1.5~2.5 小时（取决于决策严格度与历史文件数量）

5. 风险与提醒

重命名会破坏链接：若 Q1 选 1a 全站强制，会涉及 redirect_maps 的大规模新增（参照 P2.x 历史经验，约 100~200 条新规则）
hero 字段非命名问题：18 个 L2 index.md 的 hero_* 字段差异（部分有 hero_stats，部分仅 hero_label）属于 frontmatter 规范化范畴，建议与文件命名一同讨论
mkdocs.yml nav 段联动：当前 nav 由 scripts/p29-build-nav.ps1 自动生成，文件名变更后必须重跑该脚本

6. 相关文档

doc-numbering.md：D0/D1/D2/D3 旧编号规则（IA-v3 时代已弱化）
folder-structure-spec.md：目录结构规范
md-writing-spec.md：Markdown 写作规范
todo-list.md：未完成文档总清单

v0.1.0 · 计划版（待讨论后升级）· 2026-05-13 · Xisound AlgoDepartment