lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
## 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 会显示更简洁的内容，详细内容需要进入子目录查看
|