refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions
--- a/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-06
--- a/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/design.md
+++ b/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/design.md
@@ -0,0 +1,229 @@
+## Context
+
+**当前状态**:
+
+项目目前有两个主要文档文件：
+- `README.md` (1102 行) - 面向终端用户，包含安装、使用、API 文档等
+- `README_DEV.md` (1249 行) - 面向开发者，包含架构、开发规范、测试等
+
+这种"巨型单文件"结构导致：
+- 新用户需要滚动大量内容才能找到快速开始指南
+- 开发者难以在 1249 行中定位特定的模块说明
+- AI 处理长文档时容易丢失上下文
+- 违反渐进式披露设计原则
+
+**约束条件**:
+- 不引入文档生成工具（MkDocs、Docusaurus 等），保持纯 Markdown
+- 不修改代码功能
+- 保持用户文档和开发文档的明确划分
+- 项目尚未上线，无现有用户需要迁移
+
+## Goals / Non-Goals
+
+**Goals:**
+- README.md 精简到约 300 行，聚焦快速开始和核心概念
+- 建立清晰的文档导航结构，用户能在 3 次点击内找到所需信息
+- 按主题模块化拆分文档，每个文件控制在 100-300 行
+- 保持文档内容的完整性和准确性，只重组不删除
+
+**Non-Goals:**
+- 不改变代码行为或 API
+- 不引入新的文档工具链
+- 不创建多语言版本
+- 不改变项目现有的开发规范
+
+## Decisions
+
+### 1. 文档目录结构
+
+**决策**: 采用两层目录结构 `docs/` 和 `docs/development/`
+
+**理由**:
+- 用户文档和开发文档读者群体不同，分离后避免相互干扰
+- 两层结构比单层更清晰，比三层更简洁
+- 与 GitHub/GitLab 的文档展示方式兼容
+
+**替代方案考虑**:
+- 单层 `docs/` 目录：会导致用户和开发文档混在一起，增加认知负担
+- 三层结构（如 `docs/user/guide/`）：对于纯 Markdown 项目过于复杂，导航困难
+
+### 2. README.md 内容策略
+
+**决策**: 保留"概览 + 快速开始 + 导航链接"结构
+
+**理由**:
+- 项目首页需要给用户最核心的信息：这是什么、怎么快速开始、去哪里深入了解
+- 300 行限制确保在 GitHub 首页可以完整浏览而不需要大量滚动
+
+**README.md 保留内容**:
+1. 项目标题和一句话描述
+2. 功能特性列表（精简）
+3. 快速开始（安装、5 分钟上手、实时预览）
+4. 核心概念概述（YAML 语法、元素类型、模板系统，各控制在 50 行内）
+5. 文档导航（分类链接到 docs/）
+6. 常见用例（3-5 个示例）
+7. 项目信息（依赖、许可证）
+
+### 3. 拆分粒度
+
+**决策**: 按主题拆分，每个文件 100-300 行
+
+**理由**:
+- 按主题拆分符合用户的思维模型（"我需要了解模板系统" → 打开 templates/）
+- 100-300 行确保每个文件专注单一主题，易于维护
+- 过细的拆分（如 50 行一个文件）会导致文件碎片化，增加导航负担
+
+**具体拆分方案**:
+
+```
+docs/
+├── user-guide.md           (200-300行) - 用户完整指南
+├── elements/               - 按元素类型拆分
+│   ├── text.md             (100-150行)
+│   ├── image.md            (100-150行)
+│   ├── shape.md            (100-150行)
+│   └── table.md            (100-150行)
+├── templates/              - 按模板功能拆分
+│   ├── inline.md           (150-200行)
+│   ├── external-library.md (150-200行)
+│   ├── mixing-mode.md      (150-200行)
+│   └── condition-rendering.md (150-200行)
+├── fonts.md                (200行) - 字体主题系统
+├── reference/              - API 参考文档
+│   ├── commands.md         (50-100行)
+│   ├── coordinates.md      (50-100行)
+│   ├── colors.md           (50-100行)
+│   └── validation.md       (50-100行)
+├── examples.md             (200行) - 示例集合
+└── troubleshooting.md      (100行) - 故障排查
+
+docs/development/
+├── architecture.md         (300行) - 架构设计
+├── modules/                - 按代码模块拆分
+│   ├── elements.md         (100-200行)
+│   ├── template.md         (100-200行)
+│   ├── validators.md       (100-200行)
+│   ├── renderers.md        (100-200行)
+│   └── loaders.md          (100-200行)
+├── font-system.md          (150行) - 字体系统实现
+├── scope-system.md         (200行) - 作用域系统
+├── development-guide.md    (150行) - 开发规范
+├── extending.md            (200行) - 扩展指南
+├── testing.md              (200行) - 测试规范
+└── maintenance.md          (100行) - 维护指南
+```
+
+### 4. 文档间链接策略
+
+**决策**: 使用相对路径链接，创建导航辅助文件
+
+**理由**:
+- 相对路径在 Git clone 后仍然有效
+- 每个目录下的 `index.md` 或 `_nav.md` 提供该目录的导航
+
+**实现**:
+- 在每个子目录创建索引文件（如 `docs/elements/_index.md`）列出该目录下的所有文档
+- README.md 中的链接使用 `./docs/...` 相对路径
+- 文档间的交叉引用也使用相对路径
+
+### 5. 内容迁移策略
+
+**决策**: 先创建新结构，再移动内容，最后清理原文件
+
+**理由**:
+- 降低操作风险，随时可以回滚
+- 确保没有内容遗漏
+
+**迁移顺序**:
+1. 创建完整的目录结构
+2. 创建空的目标文件（带模板头部）
+3. 按主题从源文件复制内容到目标文件
+4. 更新所有交叉引用链接
+5. 精简 README.md 到 300 行
+6. 删除 README_DEV.md（内容已迁移）
+7. 验证所有链接有效性
+
+## Risks / Trade-offs
+
+### 风险 1: 外部链接失效
+
+**风险**: 项目外部的博客、教程引用了原 README.md 的特定章节，迁移后这些链接会失效。
+
+**缓解措施**:
+- 项目尚未上线，无外部引用
+- 在 README.md 顶部添加迁移说明（如果未来有外部引用）
+- 考虑保留原文件的 Git 历史供追溯
+
+### 风险 2: 用户找不到信息
+
+**风险**: 用户习惯了在 README.md 中查找所有信息，迁移后可能不知道去哪里找详细内容。
+
+**缓解措施**:
+- README.md 保留清晰的文档导航区块，分类列出所有子文档
+- 每个子文档顶部有"返回导航"链接
+- 在 `docs/README.md` 创建完整文档索引
+
+### 风险 3: 维护负担增加
+
+**风险**: 文件数量从 2 个增加到约 25 个，可能增加维护成本。
+
+**缓解措施**:
+- 每个文件职责明确，单一主题，降低修改时的认知负担
+- 使用相对路径链接，重命名时工具可自动更新
+- 定期审计文档结构，合并过于碎片化的文件
+
+### 权衡: 简洁 vs 完整
+
+**权衡**: README.md 精简后可能让部分用户感觉"信息不完整"。
+
+**缓解措施**:
+- 在 README.md 中明确说明这是"快速入门"，完整文档在 docs/
+- 保持 docs/ 文档的完整性和详细程度
+- 提供"常见用例"覆盖 80% 用户的需求
+
+## Migration Plan
+
+### 阶段 1: 准备 (1-2 小时)
+
+- [ ] 创建 `docs/` 和 `docs/development/` 目录结构
+- [ ] 创建所有目标文件的空模板（带标题和简要说明）
+- [ ] 在 `docs/README.md` 创建完整文档索引
+
+### 阶段 2: 内容迁移 (3-4 小时)
+
+- [ ] 按拆分方案从 README.md 复制内容到各子文档
+- [ ] 按拆分方案从 README_DEV.md 复制内容到各开发文档
+- [ ] 更新所有文档内部的交叉引用链接
+- [ ] 添加每个文档的导航链接（返回上级、相关文档）
+
+### 阶段 3: 精简主文件 (1 小时)
+
+- [ ] 精简 README.md 到约 300 行
+- [ ] 删除 README_DEV.md（内容已迁移）
+- [ ] 更新 README.md 中的文档导航链接
+
+### 阶段 4: 验证 (30 分钟)
+
+- [ ] 检查所有相对路径链接是否有效
+- [ ] 验证没有内容遗漏
+- [ ] 在 GitHub 上预览文档显示效果
+
+### 回滚策略
+
+- 保留 Git 历史，随时可以 `git checkout` 回原来的文档结构
+- 建议在新分支进行迁移，验证通过后再合并到主分支
+
+## Open Questions
+
+1. **是否需要文档搜索功能？**
+   - 纯 Markdown 项目无法提供搜索，依赖 GitHub 的代码搜索
+   - 用户反馈后可考虑引入文档生成工具
+
+2. **示例文档策略？**
+   - 目前未设计专门的示例文件
+   - `docs/examples.md` 作为占位文档，未来可根据用户需求添加
+   - 各主题文档中已内嵌代码示例供参考
+
+3. **文档版本策略？**
+   - 当前项目尚未发布，暂不考虑多版本文档
+   - 未来发布后，可能需要为不同主版本维护独立文档分支
--- a/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/proposal.md
+++ b/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/proposal.md
@@ -0,0 +1,39 @@
+## Why
+
+当前项目的两个主要文档 README.md (1102 行) 和 README_DEV.md (1249 行) 体积过于庞大，包含了大量细节内容。这种"信息过载"的结构不便于人类和 AI 阅读与导航，违背了渐进式披露（Progressive Disclosure）的设计原则。用户无法快速获取核心信息，开发者也难以定位具体的开发指南。
+
+## What Changes
+
+- **精简 README.md 到约 300 行**：保留项目概览、功能特性、快速开始、核心概念，移除详细内容到子文档
+- **创建 docs/ 目录结构**：建立层次化的用户文档目录，按主题拆分内容
+- **模块化拆分**：
+  - 元素类型文档到 docs/elements/ (text.md, image.md, shape.md, table.md)
+  - 模板系统文档到 docs/templates/ (inline.md, external-library.md, mixing-mode.md, condition-rendering.md)
+  - 字体主题系统到 docs/fonts.md
+  - API 参考文档到 docs/reference/ (commands.md, coordinates.md, colors.md, validation.md)
+  - 示例和故障排查到 docs/examples.md 和 docs/troubleshooting.md
+- **重构 README_DEV.md 到 docs/development/**：
+  - 架构设计到 docs/development/architecture.md
+  - 模块详解到 docs/development/modules/ (elements.md, template.md, validators.md, renderers.md, loaders.md)
+  - 字体系统和作用域系统到独立文件
+  - 开发指南、扩展指南、测试规范、维护指南分别到独立文件
+- **保持明确划分**：用户文档 (docs/) 和开发文档 (docs/development/) 完全分离，面向不同的读者群体
+- **使用纯 Markdown**：不引入文档生成工具，保持简单
+
+## Capabilities
+
+### New Capabilities
+
+(无 - 本变更仅涉及文档结构重组，不引入新的功能规范)
+
+### Modified Capabilities
+
+(无 - 本变更不改变任何现有功能的需求规范)
+
+## Impact
+
+- **文档结构**：从 2 个巨型文件变为约 25 个模块化文档文件
+- **导航体验**：用户和开发者可以更快地定位所需信息
+- **代码功能**：无任何影响，不涉及代码修改
+- **CI/CD**：可能需要更新任何硬编码文档路径的自动化脚本
+- **外部链接**：项目主页的 README 会显示更简洁的内容，详细内容需要进入子目录查看
--- a/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/specs/README.md
+++ b/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/specs/README.md
@@ -0,0 +1,14 @@
+# Specs 说明
+
+本变更仅涉及文档结构重组，不引入新的功能规范或修改现有功能规范。
+
+根据 proposal.md 的 "Capabilities" 部分：
+- **New Capabilities**: 无
+- **Modified Capabilities**: 无
+
+因此无需创建任何 spec.md 文件。
+
+文档重构的内容请参考：
+- proposal.md - 变更概述和影响
+- design.md - 详细的设计决策和实施计划
+- tasks.md - 具体的实施任务清单
--- a/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/tasks.md
+++ b/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/tasks.md
@@ -0,0 +1,69 @@
+## 1. 准备阶段
+
+- [x] 1.1 创建 `docs/` 主目录
+- [x] 1.2 创建 `docs/development/` 开发文档目录
+- [x] 1.3 创建 `docs/elements/` 子目录（元素类型文档）
+- [x] 1.4 创建 `docs/templates/` 子目录（模板系统文档）
+- [x] 1.5 创建 `docs/reference/` 子目录（API 参考文档）
+- [x] 1.6 创建 `docs/development/modules/` 子目录（模块详解文档）
+- [x] 1.7 创建所有目标文件的空模板文件（约 25 个）
+- [x] 1.8 在 `docs/README.md` 创建完整文档索引
+
+## 2. 用户文档内容迁移
+
+- [x] 2.1 从 README.md 提取用户指南内容到 `docs/user-guide.md`
+- [x] 2.2 从 README.md 提取文本元素内容到 `docs/elements/text.md`
+- [x] 2.3 从 README.md 提取图片元素内容到 `docs/elements/image.md`
+- [x] 2.4 从 README.md 提取形状元素内容到 `docs/elements/shape.md`
+- [x] 2.5 从 README.md 提取表格元素内容到 `docs/elements/table.md`
+- [x] 2.6 从 README.md 提取内联模板内容到 `docs/templates/inline.md`
+- [x] 2.7 从 README.md 提取外部模板库内容到 `docs/templates/external-library.md`
+- [x] 2.8 从 README.md 提取混合模式内容到 `docs/templates/mixing-mode.md`
+- [x] 2.9 从 README.md 提取条件渲染内容到 `docs/templates/condition-rendering.md`
+- [x] 2.10 从 README.md 提取字体主题系统内容到 `docs/fonts.md`
+- [x] 2.11 从 README.md 提取命令行选项到 `docs/reference/commands.md`
+- [x] 2.12 从 README.md 提取坐标系统到 `docs/reference/coordinates.md`
+- [x] 2.13 从 README.md 提取颜色格式到 `docs/reference/colors.md`
+- [x] 2.14 从 README.md 提取验证功能到 `docs/reference/validation.md`
+- [x] 2.15 从 README.md 提取常见错误到 `docs/troubleshooting.md`
+- [x] 2.16 创建 `docs/examples.md`（暂无示例文件，创建占位文档说明未来将添加示例）
+
+## 3. 开发文档内容迁移
+
+- [x] 3.1 从 README_DEV.md 提取架构设计内容到 `docs/development/architecture.md`
+- [x] 3.2 从 README_DEV.md 提取 elements 模块内容到 `docs/development/modules/elements.md`
+- [x] 3.3 从 README_DEV.md 提取 template 模块内容到 `docs/development/modules/template.md`
+- [x] 3.4 从 README_DEV.md 提取 validators 模块内容到 `docs/development/modules/validators.md`
+- [x] 3.5 从 README_DEV.md 提取 renderers 模块内容到 `docs/development/modules/renderers.md`
+- [x] 3.6 从 README_DEV.md 提取 loaders 模块内容到 `docs/development/modules/loaders.md`
+- [x] 3.7 从 README_DEV.md 提取字体系统实现到 `docs/development/font-system.md`
+- [x] 3.8 从 README_DEV.md 提取作用域系统到 `docs/development/scope-system.md`
+- [x] 3.9 从 README_DEV.md 提取开发规范到 `docs/development/development-guide.md`
+- [x] 3.10 从 README_DEV.md 提取扩展指南到 `docs/development/extending.md`
+- [x] 3.11 从 README_DEV.md 提取测试规范到 `docs/development/testing.md`
+- [x] 3.12 从 README_DEV.md 提取维护指南到 `docs/development/maintenance.md`
+
+## 4. 链接和导航更新
+
+- [x] 4.1 更新所有子文档内部的交叉引用链接（使用相对路径）
+- [x] 4.2 在每个子文档顶部添加"返回导航"链接
+- [x] 4.3 在 `docs/elements/` 创建 `_index.md` 索引文件
+- [x] 4.4 在 `docs/templates/` 创建 `_index.md` 索引文件
+- [x] 4.5 在 `docs/reference/` 创建 `_index.md` 索引文件
+- [x] 4.6 在 `docs/development/modules/` 创建 `_index.md` 索引文件
+
+## 5. 主文件精简
+
+- [x] 5.1 备份当前 README.md（创建分支或复制）
+- [x] 5.2 精简 README.md 到约 300 行（保留概览、快速开始、导航）
+- [x] 5.3 删除 README_DEV.md（内容已全部迁移）
+- [x] 5.4 更新 README.md 中的文档导航链接（指向新路径）
+
+## 6. 验证和收尾
+
+- [x] 6.1 检查所有相对路径链接是否有效
+- [x] 6.2 验证 README.md 行数在 300 行左右（实际：290 行）
+- [x] 6.3 验证所有子文档行数符合预期（100-300 行）
+- [x] 6.4 验证没有内容遗漏（对比源文件和目标文件）
+- [x] 6.5 在 GitHub 上预览文档显示效果
+- [x] 6.6 提交变更到 Git