@realsee/five/ai_guides/ai-doc-guidelines.md

Realsee Renderer SDK

<!-- AI-friendly guide template for `ai_guides/` -->
# 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](./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 签名的真理来源**。