1
0

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

将 README.md 拆分为多个专题文档,减少认知负荷:
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行,仅保留概览和导航
- 删除 README_DEV.md,内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions

View File

@@ -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 会显示更简洁的内容,详细内容需要进入子目录查看