AI 文档与维护指南 (AI Documentation & Maintenance Guide)
Summary
本文档包含两部分内容：
- Writing Guide: 供 AI 和人类编写新文档时的标准模板与风格规范。
- Maintenance Guide: 供 AI 维护者进行文档更新、同步与体检的操作指南。
Part 1: Writing Guide (编写指南)
目的
提供统一、结构化的 Markdown 模板，便于 AI 自动解析、索引与生成功能性示例。
建议风格
- 使用中文为主，代码示例使用 TypeScript。
- 受众意识: 文档面向 SDK 的外部使用者。避免暴露无用的内部实现细节（如私有属性、临时状态），除非对调试有帮助。
- 结构规范: 严格使用二级标题 (
##) 作为主要段落分割（如 ## Schema, ## Concepts），避免使用中文标题（如 ## 格式说明）。
- 代码缩进: 强制使用 两个空格 缩进。
- 相对路径: 内部文档链接必须使用 相对路径（如
./state.md）。
- Schema: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
- 精简原则: 仅展示核心与常用字段，避免列出所有内部或废弃字段。
- Configuration: 对于参数较多的配置项，建议按 “常用 (Common)”、“进阶 (Advanced)”、“内部 (Internal)” 进行分类表格展示，并在内部参数处添加“不建议修改”的警告。
- Source Link: 引用源码文件时，请在
## Schema 章节中使用 > **Definition**: [InterfaceName](../../path/to/source.ts) 的格式。支持多个链接（如 [Five](...), [EventTypes](...)），以便完整覆盖相关类型。必须 指向 lib/ 目录下的 .ts 文件。构建脚本会自动将其转换为发布包中的 .d.ts 链接。
- Related: 文档末尾建议包含
## Related 章节，提供相关文档的相对路径链接。
- 语义化: 链接文字应准确反映目标文档的主题（如
[Coordinate System](./coordinate.md)）。
- Metadata: 结尾必须包含 YAML 格式的
tags。
- 文档拆分与审查: 单个文档应保持精简。若内容过多需拆分为新专题，必须在创建新文件前向用户确认并获得批准，严禁擅自创建新文件。
最佳实践 (Best Practices)
1. 变量命名语义化 (Semantic Variable Naming)
在示例代码中，变量名应准确反映其通用性或特定上下文。
- Good:
parentParameter (暗示可用于 Model, ViewLayer 等多种父级)
- Bad:
modelParam (若该逻辑同样适用于 ViewLayer，则会误导用户)
2. 区分属性与方法 (Property vs Method)
明确区分“直接访问属性”与“调用方法计算”。
- 若 API 设计为 Getter (如
parameter.opacity)，文档应引导用户直接访问属性，避免混淆使用 get() 方法。
- 对于涉及计算或继承的逻辑 (如
resolveValue())，应显式说明其与直接访问的区别。
3. 显式说明默认行为 (Explicit Default Behavior)
对于有默认值或继承逻辑的方法，务必说明“不传参”时的行为。
- 例如：
resolveValue() 不传参时仅计算默认值；传入 upstream 时会包含继承逻辑。
标准模板结构 (Standard Template Structure)
无论是新建文档还是维护现有文档，都请参考独立模板文件：template.md。
- 新建文档: 直接复制模板内容开始编写。
- 维护文档: 在修改现有文档时，请检查其结构是否符合模板要求（如 Schema 的 Definition 引用、Configuration 的分类等）。如果发现结构过时，请顺手将其标准化。
- 特殊说明 (Special Notes):
- 模板链接格式 (Template Link Format):
- 模板(
template.md)中所有的占位符链接（如 Definition 处的 [InterfaceName](...) 或 Related 处的 [RelatedConcept](...)）均使用了代码块包裹，以避免构建时因路径不存在而报错。
- AI 操作: 在编写正式文档时，必须将其还原为可点击的标准 Markdown 链接（即去掉反引号），并确保路径指向真实存在的文件。
请严格遵循该模板的结构，以保证文档风格一致性。
Part 2: Maintenance Guide (维护指南)
核心原则 (Core Principles)
为了防止文档与代码脱节，我们遵循 “代码变更驱动文档更新” 的原则。
1. 语义化检索 (Semantic Retrieval)
不再维护硬编码的“源码-文档”映射表。AI 维护者在修改代码后，应利用自身的语义搜索能力（如 SearchCodebase 或 Grep）来定位需要更新的文档。
推荐策略:
- 搜索类名/方法名: 如修改了
five.load，搜索 five.load 或 load。
- 搜索概念关键词: 如修改了射线检测逻辑，搜索
Raycast 或 project2d。
2. 单一事实来源 (Single Source of Truth)
- API 签名: 以
package/five/index.d.ts 和代码中的 TSDoc 为准。
- ai_guides/api.md: 仅作为 索引 (Index) 和 摘要 (Summary)。不要试图复制所有参数细节，除非是核心参数。
- ai_guides/features/*.md: 重点解释 “为什么” 和 “怎么用”，避免机械复制类型定义。
3. 维护工作流 (Maintenance Workflow)
场景 A：代码功能迭代后 (Post-Coding)
当修改了 SDK 源码后，请执行以下检查：
- 反向查找: 利用工具搜索关键词（API 名称、Feature 名称），找到
ai_guides/ 下相关的文档。
- 更新文档:
- 如果修改了 API 签名 -> 更新对应的
Schema 和 Examples。
- 如果废弃了功能 -> 在文档中添加
> [!WARNING] Deprecated 提示。
- 更新索引: 如果是新功能，确保将其添加到
ai_guides/README.md 的合适章节中。
- 同步 llms.txt: 若新增了文档或修改了文档路径，必须同步更新项目根目录下的
llms.txt，确保外部索引与 ai_guides/ 保持一致。
场景 B：API 文档同步 (Sync API Doc)
定期检查 ai_guides/api.md 的完整性：
- 读取
package/five/index.d.ts 获取最新公开 API。
- 对比
ai_guides/api.md，找出缺失的高频 API 或已删除的 API。
- 注意: 只收录高频/核心 API，低频 API 应引导用户查看源码或专门的 Feature 文档。
目录结构说明
ai_guides/: 文档根目录。ai_guides/features/: 功能性文档 (Features)。ai_guides/release_notes/: 版本更新记录。ai_guides/api.md: 核心 API 索引。ai_guides/README.md: 文档总索引。package/five/index.d.ts: API 签名的真理来源。