# AI 文档与维护指南 (AI Documentation & Maintenance Guide)

## Summary

本文档包含两部分内容：

1. Writing Guide: 供 AI 和人类编写新文档时的标准模板与风格规范。
2. 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 源码后，请执行以下检查：

1. 反向查找: 利用工具搜索关键词（API 名称、Feature 名称），找到 `ai_guides/` 下相关的文档。
2. 更新文档:
   - 如果修改了 API 签名 -> 更新对应的 `Schema` 和 `Examples`。
   - 如果废弃了功能 -> 在文档中添加 `> [!WARNING] Deprecated` 提示。
3. 更新索引: 如果是新功能，确保将其添加到 `ai_guides/README.md` 的合适章节中。
4. 同步 llms.txt: 若新增了文档或修改了文档路径，必须同步更新项目根目录下的 `llms.txt`，确保外部索引与 `ai_guides/` 保持一致。

### 场景 B：API 文档同步 (Sync API Doc)

定期检查 `ai_guides/api.md` 的完整性：

1. 读取 `package/five/index.d.ts` 获取最新公开 API。
2. 对比 `ai_guides/api.md`，找出缺失的高频 API 或已删除的 API。
3. 注意: 只收录高频/核心 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 签名的真理来源。