Folder Structure Spec · v1.0

目录文件夹结构规范 v1.0

IA v3 权威定稿 · 9 个一级目录 + 二级约定 + 特殊目录规则

适用范围:AlgoDepartment/06_docs/site-build/docs/** · 受众:文档管理员智能体 + 所有作者

目录文件夹结构规范 v1.0

本文档定位

角色:目录物理结构的权威(对应 IA v3 定稿)
管辖范围:docs/ 下所有目录的命名 / 层级 / 内容职责
不管辖:目录在站点 nav 上怎么显示(见 nav-display-spec.md);MD 文件内格式(见 md-writing-spec.md v2.0)
下游受众:文档管理员智能体在 P1 阶段执行「D 系列 → 数字前缀」批量重命名时,以本文档为目标态

v1.0 版本要点(2026-05-11)

首版发布 · 把 nav-demo/docs-system-redesign-plan.md(站外历史草案,P3 阶段归档到 99-archive/)IA v3 定稿落地为可执行规范
与当前 D 系列结构(D0-company / D1-divisions / D2-products / ...)的映射在 migration-plan-2026Q2.md §3 给出

1. 目录总图(IA v3)

docs/
├── index.md                          ← 站点首页(L1A · Hero + 8 张大卡片)
│
├── 00-home/                          ← 首页支撑文档(快速导览、新人入门)
│   └── index.md
│
├── 01-strategy/                      ← 战略层(原 D0-company)
│   ├── index.md
│   ├── 00-vision/                    ← 公司愿景与战略
│   ├── 01-brand/                     ← 品牌与 VI
│   ├── 02-policies/                  ← 公司制度
│   ├── 03-finance/                   ← 融资与财务
│   └── 04-roadmap/                   ← 公司级 Roadmap
│
├── 02-products/                      ⭐ 主战场 · 11 个产品
│   ├── index.md                      ← 产品矩阵 V2.0(L1B · Mermaid 6 层架构)
│   ├── P1-xistudio/                  ← XiStudio(L4 工具)
│   │   ├── index.md
│   │   ├── 01-business/              ← 13 稳态文档之 1:业务定义
│   │   ├── 02-architecture/          ← 13 稳态文档之 2-3:技术架构
│   │   ├── 03-modules/               ← 13 稳态文档之 4-5:模块设计
│   │   │   ├── source/
│   │   │   ├── sink/
│   │   │   ├── mixer/
│   │   │   └── ...
│   │   ├── 04-api/                   ← 13 稳态文档之 6:API 规约
│   │   ├── 05-data/                  ← 13 稳态文档之 7:数据模型
│   │   ├── 06-deployment/            ← 13 稳态文档之 8:部署
│   │   ├── 07-operations/            ← 13 稳态文档之 9:运维
│   │   ├── 08-roadmap/               ← 13 稳态文档之 10:产品 Roadmap
│   │   ├── 09-release/               ← 13 稳态文档之 11:发布说明
│   │   ├── 10-changelog/             ← 13 稳态文档之 12:变更日志
│   │   ├── 11-faq/                   ← 13 稳态文档之 13:FAQ
│   │   ├── _dev/                     ← 过程文档(详见 §4)
│   │   │   ├── adr/                  ← 架构决策记录(ADR-NNN)
│   │   │   ├── phases/               ← 阶段交付(PHASE-NNN)
│   │   │   ├── runbooks/             ← 运维手册(RUNBOOK-NNN)
│   │   │   ├── handoffs/             ← 跨团队交接
│   │   │   └── README.md             ← _dev 目录说明
│   │   └── images/                   ← 该产品所有截图
│   ├── P2-xiforge/                   ← XiForge(L4 工具)
│   ├── P3-xialgo/                    ← XiAlgo(L3 算法)
│   ├── P4-xidsp/                     ← XiDSP(L0 芯片)
│   ├── P5-xicore/                    ← XiCore(L0 芯片)
│   ├── P6-xiamp/                     ← XiAmp(L1 硬件)
│   ├── P7-xibox/                     ← XiBox(L1 硬件)
│   ├── P8-xitune/                    ← XiTune(L2 测试调音)
│   ├── P9-ximic/                     ← XiMic(L2 测试调音)
│   ├── P10-xicalprobe/               ← XiCal + XiProbe(L2 测试调音)
│   └── P11-ximind/                   ← XiMind(L5 云端)
│
├── 03-platform/                      ← 跨产品平台稳态(原 D3-architecture 部分)
│   ├── index.md
│   ├── 01-protocols/                 ← 通信协议(WebSocket / gRPC / SignalR / SSE / JSON-RPC)
│   ├── 02-data-models/               ← 跨产品数据模型(Patch / Project / Device 等)
│   ├── 03-deployment/                ← 通用部署方案
│   ├── 04-dsp-spec/                  ← DSP 通用规范(模块接口 / Sample-Tick 模型 / 调度)
│   └── 05-shared-ui-kit/             ← 跨产品 UI Kit
│
├── 04-departments/                   ← 部门规范(原 D1-divisions)
│   ├── index.md
│   ├── algo/                         ← 算法部章程 + 工作流
│   ├── product/                      ← 产品中心章程
│   ├── hardware/                     ← 硬件部章程
│   ├── test/                         ← 测试部章程
│   ├── business/                     ← 商务部章程
│   └── delivery/                     ← 交付部章程
│
├── 05-standards/                     ← 跨部门标准(本目录)
│   ├── index.md
│   ├── md-writing-spec.md            ← MD 写作规范 v2.0
│   ├── brand-color-system.md         ← 3+1 品牌色系统 v1.2
│   ├── nav-display-spec.md           ← 目录显示规范 v1.0
│   ├── folder-structure-spec.md      ← 目录结构规范 v1.0(本文)
│   ├── format-spec-changelog.md      ← 格式变更日志 v1.0(9 条决议沉淀)
│   ├── doc-numbering.md              ← 文档编号 / 命名规范方案 4
│   ├── checklist.md                  ← PR 检查清单
│   ├── release-to-other-depts.md     ← 跨部门交付索引
│   ├── migration-plan-2026Q2.md      ← 阶段迁移计划
│   ├── tech-docs-framework.md        ← 技术文档体系总览
│   └── tags.md                       ← Tags 索引页
│
├── 06-customer/                      ← 客户专区(原 external)
│   ├── index.md                      ← 客户欢迎页(L1B)
│   ├── overview/                     ← 公司/产品总览(对外版)
│   ├── case-studies/                 ← 客户案例
│   ├── partner/                      ← 合作伙伴专区
│   └── support/                      ← 支持与联系
│
├── 07-engineering/                   ← 全局工程过程
│   ├── index.md
│   ├── adr-global/                   ← 全站级 ADR(跨产品架构决策)
│   ├── handoffs/                     ← 跨产品交接
│   ├── runbooks-global/              ← 全局运维手册
│   └── postmortems/                  ← 复盘报告
│
└── 99-archive/                       ← 归档(底部小入口,不在主 nav)
    ├── index.md
    ├── 2026-01-old-spec/              ← 按归档时间分组
    ├── 2026-04-pre-ia-v3/             ← v3 前的旧目录
    └── deprecated-docs/               ← 已废弃文档

2. 9 个一级目录 · 权威定义

目录	中文名	英文别称	收纳类型	level 默认	文档量级(估)
`00-home/`	首页	Home	站点入口、新人导览、文档地图	L1A/L3	~3
`01-strategy/`	战略	Strategy	公司愿景 / 品牌 / 制度 / 融资 / 公司级 Roadmap	L1B/L2	30-40
`02-products/` ⭐	产品	Products	11 个产品全维度自包含(13 稳态 + modules + _dev)	L1B/L2	130-150
`03-platform/`	平台	Platform	跨产品稳态:协议 / 数据模型 / 部署 / DSP 规范 / UI Kit	L1B/L2	30-50
`04-departments/`	部门	Departments	各部门章程、工作流、内部规范	L2	40-60
`05-standards/`	标准	Standards	跨部门元规范(命名 / MD / PR / 模板)	L1B/L2	10-15
`06-customer/`	客户	Customer	客户面向内容(对外公开)	L1B/L2	30-40
`07-engineering/`	工程	Engineering	全局过程文档(全站 ADR / 跨产品 handoff / 复盘)	L2/L3	10-20
`99-archive/`	归档	Archive	已废弃 / 历史快照 / 不再维护的文档	L3	不限

目标总量:约 300-400 篇 .md(当前 332 篇 + 部分新增 - 部分归档去重)

3. 二级目录命名约定

3.1 数字前缀 vs 语义前缀

一级目录	二级目录命名	示例
`01-strategy/`	数字前缀(`NN-name/`)	`00-vision/` `01-brand/` `02-policies/`
`02-products/`	产品代号(`PN-name/`)	`P1-xistudio/` `P2-xiforge/` `P11-ximind/`
`03-platform/`	数字前缀	`01-protocols/` `02-data-models/`
`04-departments/`	部门英文名	`algo/` `product/` `hardware/`
`05-standards/`	直接放 .md(无二级目录)	`md-writing-spec.md` 等
`06-customer/`	语义名	`overview/` `case-studies/` `partner/`
`07-engineering/`	语义名	`adr-global/` `handoffs/` `postmortems/`
`99-archive/`	时间分组	`2026-01-old-spec/` `2026-04-pre-ia-v3/`

3.2 数字前缀规则

用 2 位数字:00- 01- ... 99-(避免 1- / 2- 排序问题)
起始数字按重要性 / 时序选择,不强制从 00- 开始
同级目录间允许跳号(为未来插入新目录预留位置,如 00- 01- 02- 05- 99-)

3.3 产品目录(`02-products/PN-xxx/`)的 13 稳态文档子目录

每个产品目录下统一用以下 11 个数字前缀子目录(原计划 13 个,合并部分稳态文档到同一子目录):

PN-product-name/
├── index.md                  ← 产品门面页(L1B · 含产品 Hero)
├── 01-business/              ← 业务定义(原稳态 1)
├── 02-architecture/          ← 技术架构(原稳态 2-3 合并)
├── 03-modules/               ← 模块设计(原稳态 4-5 合并 · 含 source/ sink/ mixer/ 等子模块)
├── 04-api/                   ← API 规约(原稳态 6)
├── 05-data/                  ← 数据模型(原稳态 7)
├── 06-deployment/            ← 部署(原稳态 8)
├── 07-operations/            ← 运维(原稳态 9)
├── 08-roadmap/               ← 产品 Roadmap(原稳态 10)
├── 09-release/               ← 发布说明(原稳态 11)
├── 10-changelog/             ← 变更日志(原稳态 12)
├── 11-faq/                   ← FAQ(原稳态 13)
├── _dev/                     ← 过程文档(详见 §4)
└── images/                   ← 该产品所有截图

例外:小型产品(P5-xicore 等)允许只用前 4-5 个子目录,但目录命名必须保持一致(便于跨产品对比)。

4. 特殊目录:`_dev/` 过程文档

4.1 角色与职责

_dev/ 目录存放过程文档(类型前缀 + 数字编号,详见 doc-numbering.md 命名规范方案 4),与 13 稳态文档(数字段稳态)分离:

PN-product/_dev/
├── README.md                 ← _dev 目录的说明 + 索引(注:这里允许用 README,因为不进 nav)
├── adr/                      ← 架构决策记录
│   ├── ADR-001-tech-stack-choice.md
│   ├── ADR-002-mixer-multi-tone.md
│   └── ...
├── phases/                   ← 阶段交付报告
│   ├── PHASE-001-mvp.md
│   ├── PHASE-008-implementation.md
│   ├── PHASE-009-roadmap.md
│   └── ...
├── runbooks/                 ← 运维手册
│   ├── RUNBOOK-001-deploy-prod.md
│   ├── RUNBOOK-003-upgrade-engine.md
│   └── ...
├── handoffs/                 ← 跨团队交接
│   ├── HANDOFF-001-algo-to-test.md
│   └── ...
└── postmortems/              ← 复盘报告(产品级 · 全站级在 07-engineering/)
    ├── PM-001-engine-crash-2026-03.md
    └── ...

4.2 `_dev/` 与稳态文档的边界

项	稳态文档(`01-business/` 等)	过程文档(`_dev/`)
命名	数字段稳态(`tech-arch.md`)	类型前缀过程(`ADR-NNN-xxx.md`)
doc_id	`SPEC-XXX` / `ARCH-XXX` 等	`ADR-NNN` / `PHASE-NNN` 等
寿命	长期维护,版本号迭代	一次性输出,完成后冻结
进 nav	✅ 进	❌ 不进 nav(隐藏)
status	`draft` → `review` → `published` → `deprecated`	`published` → `frozen`(冻结)
修订频率	高(每月)	低(完成后基本不动)

4.3 `_dev/` 不进 nav 的实现方式

mkdocs.yml: nav 字段不列出 _dev/ 下的任何文件,但物理上保留(可通过 URL 直接访问)。

5. 特殊目录:`99-archive/` 归档

5.1 归档时机

触发条件	处理动作
文档已被新版本取代,但作为历史参考保留	`mv` 到 `99-archive/YYYY-MM-原因/` + 在新文档 frontmatter 加 `legacy_doc_id`
旧目录(00-spec/ 等)整体迁移完成	整个目录归档到 `99-archive/YYYY-MM-pre-ia-v3/old-dir-name/`
文档作者离职 + 内容已无人维护	`status: deprecated`,后续再批量归档

5.2 归档目录结构

99-archive/
├── index.md                                ← 归档目录索引(L3 · 极简列表)
├── 2026-01-old-spec/                       ← 按归档时间 + 来源分组
│   └── (从 docs/00-spec/ 整体搬迁过来的内容)
├── 2026-04-pre-ia-v3/
│   ├── D0-company-snapshot/
│   ├── D2-products-old/
│   └── ...
└── deprecated-docs/                        ← 单独废弃的文档(无法按时间归类)

5.3 归档不删原则

✅ 必须先归档,再删除(P3 阶段验收前不允许 hard delete)
✅ frontmatter 必须保留 legacy_doc_id
✅ 旧 URL 必须配置 mkdocs 重定向(mkdocs-redirects plugin,P0 阶段引入)
❌ 不允许直接 rm 文档而不归档

6. README.md vs index.md 选择规则

场景	用 `index.md`	用 `README.md`
一级目录入口(00 ~ 07 / 99)	✅ 必须	❌
二级目录入口(01-vision / P1-xistudio 等)	✅ 必须	❌
产品 13 稳态子目录(01-business / 02-architecture 等)	✅ 推荐	❌
`_dev/` 目录及其子目录	❌	✅ 允许(不进 nav)
`images/` 目录	❌	❌ 不需要(无文档)
`docs/` 站点根	✅ `docs/index.md` 是站点首页	❌

统一原则:进 nav 的目录用 index.md,不进 nav 的目录可用 README.md(详见 nav-display-spec.md §4.2)。

7. 文件命名约定

7.1 通用规则

小写 + 连字符:tech-arch.md / mixer-multi-tone.md(不用下划线 _,不用驼峰)
不超过 60 字符(URL 友好)
避免中文 / 空格 / 特殊字符(英文小写字母 + 数字 + 连字符)
不允许同名:同一目录下不允许 tech-arch.md + Tech-Arch.md

7.2 稳态文档命名(13 类)

01-business/
├── definition.md             ← 业务定义
├── target-users.md           ← 目标用户
└── value-proposition.md      ← 价值主张

02-architecture/
├── tech-arch.md              ← 技术架构总览(必须)
├── component-design.md       ← 组件设计
└── data-flow.md              ← 数据流图

03-modules/
├── source/
│   ├── 00-architecture.md    ← 模块架构(必须)
│   ├── 10-business.md        ← 模块业务
│   ├── 20-frontend.md        ← 前端实现
│   ├── 30-backend.md         ← 后端实现
│   └── 40-tests.md           ← 测试用例
├── sink/
│   └── (同 source)
└── mixer/
    └── (同 source)

7.3 过程文档命名(类型前缀 + 数字)

详见 doc-numbering.md 命名规范方案 4

ADR-NNN-{kebab-case-summary}.md 如 ADR-014-multi-tone-injection.md
PHASE-NNN-{kebab-case-summary}.md 如 PHASE-008-implementation.md
RUNBOOK-NNN-{kebab-case-summary}.md 如 RUNBOOK-003-upgrade-engine.md
PM-NNN-{kebab-case-summary}-{YYYY-MM}.md 如 PM-001-engine-crash-2026-03.md

8. images/ 目录规则

8.1 路径

每个产品独立:02-products/PN-xxx/images/
跨产品共用资源:docs/assets/images-shared/(标志、图标等)
不允许散落:不允许在 docs/images/ 根目录乱放

8.2 文件命名

详见 md-writing-spec.md §10.1

格式:{product-or-domain}-{scene}-{version}.{ext}
示例:xistudio-main-ui-v1.png / xiamp-pro12-front.jpg
后缀:优先 .png / .svg(矢量),次选 .jpg(照片);禁止 .gif(用 mermaid / .mp4 替代)

9. 当前现状 → 目标态映射

注:本节是给文档管理员智能体看的「目标差异表」,详见 migration-plan-2026Q2.md §3

当前现状	目标态(IA v3)	迁移阶段
`D0-company/` (36 文件)	`01-strategy/`	P1
`D1-divisions/` (49 文件)	`04-departments/`	P2
`D2-products/` (132 文件)	`02-products/` (子目录命名也改)	P2
`D3-architecture/` (37 文件)	`03-platform/` + 部分进 `02-products/PN/02-architecture/`	P2
`D3-execution/` (2 文件)	大部分进 `07-engineering/`	P1
`D4-implementation/` (20 文件)	进 `02-products/PN/_dev/phases/` 各产品	P2
`D6-testing-ops/` (1 文件)	进 `04-departments/test/`	P1
`external/` (33 文件)	`06-customer/`	P1
`00-spec/` (6 文件)	`99-archive/2026-04-pre-ia-v3/`	P0
`10-product-matrix/` (2 文件)	内容并入 `02-products/index.md`,目录归档	P0
`20-doc-system/` (2 文件)	内容并入 `05-standards/`,目录归档	P0
`_audit/` (1 文件)	`99-archive/audit/`	P0

10. 与下游规范的引用关系

flowchart TD
    A["folder-structure-spec.md<br>(本文档 · 目录物理结构)"] -->|目录列表 + index.md 入口| B["nav-display-spec.md<br>(站点级配置)"]
    A -->|稳态 vs 过程文档边界| C["doc-numbering.md<br>(命名规范方案 4)"]
    A -->|路径变更映射| D["migration-plan-2026Q2.md<br>(阶段计划)"]
    E["md-writing-spec.md v2.0"] -->|frontmatter doc_id| C
    E -->|图片路径规则 §10.1| A

    class A xyL3
    class B,C xyL1
    class D xyL5
    class E xyL2

11. 修订历史

版本	日期	修订人	关键变更
v1.0	2026-05-11	AlgoDepartment	首版发布 · IA v3 9 个一级目录权威定稿 + 二级命名约定 + `_dev/` `99-archive/` 特殊目录规则

下一步

本规范完成后,文档管理员智能体应: 1. 在 P0 阶段创建 9 个一级目录的物理结构(空目录 + index.md 占位) 2. 在 P1-P3 阶段按 §9 表格分批迁移文件 3. 每次迁移必须在新文件 frontmatter 保留 legacy_doc_id 4. 每次归档前必须先 mv 到 99-archive/,禁止直接 rm

目录文件夹结构规范 v1.0

目录文件夹结构规范 v1.0

1. 目录总图(IA v3)

2. 9 个一级目录 · 权威定义

3. 二级目录命名约定

3.1 数字前缀 vs 语义前缀

3.2 数字前缀规则

3.3 产品目录(02-products/PN-xxx/)的 13 稳态文档子目录

4. 特殊目录:_dev/ 过程文档

4.1 角色与职责

4.2 _dev/ 与稳态文档的边界

4.3 _dev/ 不进 nav 的实现方式

5. 特殊目录:99-archive/ 归档

5.1 归档时机

5.2 归档目录结构

5.3 归档不删原则

6. README.md vs index.md 选择规则

7. 文件命名约定

7.1 通用规则

7.2 稳态文档命名(13 类)

7.3 过程文档命名(类型前缀 + 数字)

8. images/ 目录规则

8.1 路径

8.2 文件命名

9. 当前现状 → 目标态映射

10. 与下游规范的引用关系

11. 修订历史

3.3 产品目录(`02-products/PN-xxx/`)的 13 稳态文档子目录

4. 特殊目录:`_dev/` 过程文档

4.2 `_dev/` 与稳态文档的边界

4.3 `_dev/` 不进 nav 的实现方式

5. 特殊目录:`99-archive/` 归档