术语表
本文档定义了 Dora Pocket 文档系统中使用的核心术语、命名规范和分类标准。所有文档编写者和贡献者都应遵循这些定义，以确保项目文档的一致性和专业性。
AI 模型
本项目使用三种 AI 模型来辅助文档生成和代码开发，每种模型都有其特定的用途和优势。
Codex
- 模型标识:
gpt-5.1-codex - 用途: 代码实现、自动化开发、代码生成
- 特点: 擅长理解代码上下文并生成高质量的实现代码
- 典型场景: 功能实现、组件开发、测试用例生成
Gemini
- 模型标识:
gemini-2.5-pro - 用途: 代码分析、文档生成、代码审查
- 特点: 拥有强大的分析能力和大型上下文窗口
- 典型场景: 架构分析、文档撰写、模式识别
Qwen
- 模型标识:
qwen-coder - 用途: Gemini 的备选方案，分析和文档生成
- 特点: 提供可靠的备份能力，确保服务连续性
- 典型场景: 当 Gemini 不可用时的替代选择
文档类型
Dora Pocket 文档按照内容性质和目标受众分为五个主要类型，每种类型都有其特定的写作风格和结构要求。
API 文档
- 定义: 详细描述函数、类、接口等编程接口的技术文档
- 特征: 包含签名、参数、返回值、示例代码和边界情况
- 目标受众: 使用该 API 的开发者
- 典型文件:
@esdora/kit函数文档、@esdora/color函数文档 - 模板: API 文档模板
架构文档
- 定义: 阐述系统设计、技术选型和架构决策的文档
- 特征: 包含架构图、组件关系、数据流和设计原则
- 目标受众: 系统维护者、架构师、高级开发者
- 典型文件:
ARCHITECTURE.md、模块设计文档
用户指南
- 定义: 面向最终用户的使用说明和操作手册
- 特征: 侧重于"如何做"，包含步骤说明和实用示例
- 目标受众: 项目使用者、初学者
- 典型文件: 快速上手、安装指南、常见问题解答
最佳实践
- 定义: 总结经验教训和推荐做法的深度文章
- 特征: 采用"问题-原则-方案"结构，侧重思想和模式传递
- 目标受众: 追求代码质量和工程效率的开发者
- 典型文件: 设计模式、代码规范、性能优化指南
贡献指南
- 定义: 指导外部贡献者参与项目的规范文档
- 特征: 包含工作流程、规范要求和协作指南
- 目标受众: 项目贡献者、开源社区成员
- 典型文件:
CONTRIBUTING.md、提交规范、文档编写指南
核心术语
Frontmatter
- 定义: Markdown 文件开头的 YAML 格式元数据区块
- 格式: 使用
---包裹，包含title、description等字段 - 示例:yaml
--- title: 快速上手 description: Dora Pocket 的入门指南 ---
VitePress
- 定义: 本项目使用的静态文档网站生成器
- 技术栈: 基于 Vite 和 Vue 3
- 配置文件:
docs/.vitepress/config.ts - 特点: 支持 Markdown、Vue 组件和自定义主题
Kit
- 定义:
@esdora/kit包的简称，提供通用工具函数 - 全称:
@esdora/kit - 特点: 零依赖、类型安全、纯函数式
- 文档位置:
docs/packages/kit/
Module (模块)
- 定义: 项目中的独立功能包
- 命名规范: 使用
@esdora/[name]格式 - 示例:
@esdora/kit,@esdora/color,@esdora/date - 组织方式: Monorepo 结构，使用 pnpm workspace
Package (包)
- 定义: 可独立发布和安装的 npm 包
- 关系: 与 Module 同义，在本项目中可互换使用
- 管理工具: pnpm (workspace)
Monorepo
- 定义: 单一代码仓库管理多个包的项目结构
- 工具: pnpm workspace + Turbo
- 优势: 代码共享、统一版本管理、简化开发流程
TypeScript
- 定义: JavaScript 的超集，提供静态类型系统
- 版本: 使用 ESNext 目标
- 配置:
tsconfig.json - 构建工具: tsdown
Vitest
- 定义: 本项目使用的单元测试框架
- 特点: 基于 Vite，与 Jest 兼容的 API
- 用途: 编写和运行函数测试，测试代码用于文档生成
示例驱动 (Example-Driven)
- 定义: 文档编写哲学，强调使用丰富的代码示例来阐述功能
- 原则: "一个好的示例胜过千言万语"
- 实践: 每个函数文档都包含多个实际使用场景的示例
用户中心 (User-Centric)
- 定义: 文档编写的核心原则，始终站在使用者角度思考
- 目标: 解决用户的实际问题，而非展示技术实现
- 体现: 清晰的描述、实用的示例、完善的边界情况说明
文档元数据字段
title (必需)
- 定义: 文档页面的标题
- 类型: 字符串
- 规范: 应简短明确，准确反映页面内容
- 示例:
"快速上手","isCircular","toHex" - 使用位置: Frontmatter 的
title字段
description (必需)
- 定义: 文档页面的详细描述
- 类型: 字符串
- 规范: 应包含完整的功能说明，包括来源和用途
- 格式: 对于函数文档，使用
"[函数名] - 来自 Dora Pocket 的[类别]"道具"，用于[功能描述]。" - 示例:
"toHex - 来自 Dora Pocket 的颜色"道具"，用于将任意颜色格式转换为十六进制 (HEX) 字符串。" - 使用位置: Frontmatter 的
description字段
category (可选)
- 定义: 文档的分类标签
- 类型: 枚举值
- 可选值:
API|架构|指南|实践|贡献 - 用途: 用于文档分类和导航生成
- 示例:
category: "API" - 使用位置: Frontmatter 的
category字段（扩展字段）
ai_model (可选)
- 定义: 生成该文档时使用的 AI 模型
- 类型: 枚举值
- 可选值:
Codex|Gemini|Qwen - 用途: 标记文档生成方式，便于质量追踪和优化
- 示例:
ai_model: "Gemini" - 使用位置: Frontmatter 的
ai_model字段（扩展字段）