@realsee/five/docs/documents/ai-doc-guidelines.html

Realsee Renderer SDK

<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>ai-doc-guidelines | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">ai-doc-guidelines</a></li></ul></div><div class="tsd-panel tsd-typography"><!-- AI-friendly guide template for `ai_guides/` -->
<h1 id="ai-文档与维护指南-ai-documentation-maintenance-guide" class="tsd-anchor-link">AI 文档与维护指南 (AI Documentation &amp; Maintenance Guide)<a href="#ai-文档与维护指南-ai-documentation-maintenance-guide" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<h2 id="summary" class="tsd-anchor-link">Summary<a href="#summary" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>本文档包含两部分内容：</p>
<ol>
<li><strong>Writing Guide</strong>: 供 AI 和人类编写新文档时的标准模板与风格规范。</li>
<li><strong>Maintenance Guide</strong>: 供 AI 维护者进行文档更新、同步与体检的操作指南。</li>
</ol>
<hr>
<h1 id="part-1-writing-guide-编写指南" class="tsd-anchor-link">Part 1: Writing Guide (编写指南)<a href="#part-1-writing-guide-编写指南" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<h2 id="目的" class="tsd-anchor-link">目的<a href="#目的" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>提供统一、结构化的 Markdown 模板，便于 AI 自动解析、索引与生成功能性示例。</p>
<h2 id="建议风格" class="tsd-anchor-link">建议风格<a href="#建议风格" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li>使用中文为主，代码示例使用 TypeScript。</li>
<li><strong>受众意识</strong>: 文档面向 SDK 的<strong>外部使用者</strong>。避免暴露无用的内部实现细节（如私有属性、临时状态），除非对调试有帮助。</li>
<li><strong>结构规范</strong>: 严格使用二级标题 (<code>##</code>) 作为主要段落分割（如 <code>## Schema</code>, <code>## Concepts</code>），避免使用中文标题（如 <code>## 格式说明</code>）。</li>
<li><strong>代码缩进</strong>: 强制使用 <strong>两个空格</strong> 缩进。</li>
<li><strong>相对路径</strong>: 内部文档链接必须使用 <strong>相对路径</strong>（如 <code>./state.md</code>）。</li>
<li><strong>Schema</strong>: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
<ul>
<li><strong>精简原则</strong>: 仅展示核心与常用字段，避免列出所有内部或废弃字段。</li>
</ul>
</li>
<li><strong>Configuration</strong>: 对于参数较多的配置项，建议按 <strong>“常用 (Common)”</strong>、<strong>“进阶 (Advanced)”</strong>、<strong>“内部 (Internal)”</strong> 进行分类表格展示，并在内部参数处添加“不建议修改”的警告。</li>
<li><strong>Source Link</strong>: 引用源码文件时，请在 <code>## Schema</code> 章节中使用 <code>&gt; **Definition**: [InterfaceName](../../path/to/source.ts)</code> 的格式。<strong>支持多个链接</strong>（如 <code>[Five](...), [EventTypes](...)</code>），以便完整覆盖相关类型。<strong>必须</strong> 指向 <code>lib/</code> 目录下的 <code>.ts</code> 文件。构建脚本会自动将其转换为发布包中的 <code>.d.ts</code> 链接。</li>
<li><strong>Related</strong>: 文档末尾建议包含 <code>## Related</code> 章节，提供相关文档的<strong>相对路径链接</strong>。
<ul>
<li><strong>语义化</strong>: 链接文字应准确反映目标文档的主题（如 <code>[Coordinate System](./coordinate.md)</code>）。</li>
</ul>
</li>
<li><strong>Metadata</strong>: 结尾必须包含 YAML 格式的 <code>tags</code>。</li>
<li><strong>文档拆分与审查</strong>: 单个文档应保持精简。若内容过多需拆分为新专题，<strong>必须</strong>在创建新文件前向用户确认并获得批准，严禁擅自创建新文件。</li>
</ul>
<h2 id="最佳实践-best-practices" class="tsd-anchor-link">最佳实践 (Best Practices)<a href="#最佳实践-best-practices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="1-变量命名语义化-semantic-variable-naming" class="tsd-anchor-link">1. 变量命名语义化 (Semantic Variable Naming)<a href="#1-变量命名语义化-semantic-variable-naming" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>在示例代码中，变量名应准确反映其通用性或特定上下文。</p>
<ul>
<li><strong>Good</strong>: <code>parentParameter</code> (暗示可用于 Model, ViewLayer 等多种父级)</li>
<li><strong>Bad</strong>: <code>modelParam</code> (若该逻辑同样适用于 ViewLayer，则会误导用户)</li>
</ul>
<h3 id="2-区分属性与方法-property-vs-method" class="tsd-anchor-link">2. 区分属性与方法 (Property vs Method)<a href="#2-区分属性与方法-property-vs-method" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>明确区分“直接访问属性”与“调用方法计算”。</p>
<ul>
<li>若 API 设计为 Getter (如 <code>parameter.opacity</code>)，文档应引导用户直接访问属性，避免混淆使用 <code>get()</code> 方法。</li>
<li>对于涉及计算或继承的逻辑 (如 <code>resolveValue()</code>)，应显式说明其与直接访问的区别。</li>
</ul>
<h3 id="3-显式说明默认行为-explicit-default-behavior" class="tsd-anchor-link">3. 显式说明默认行为 (Explicit Default Behavior)<a href="#3-显式说明默认行为-explicit-default-behavior" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>对于有默认值或继承逻辑的方法，务必说明“不传参”时的行为。</p>
<ul>
<li>例如：<code>resolveValue()</code> 不传参时仅计算默认值；传入 <code>upstream</code> 时会包含继承逻辑。</li>
</ul>
<h2 id="标准模板结构-standard-template-structure" class="tsd-anchor-link">标准模板结构 (Standard Template Structure)<a href="#标准模板结构-standard-template-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>无论是<strong>新建文档</strong>还是<strong>维护现有文档</strong>，都请参考独立模板文件：<a href="template.html">template.md</a>。</p>
<ul>
<li><strong>新建文档</strong>: 直接复制模板内容开始编写。</li>
<li><strong>维护文档</strong>: 在修改现有文档时，请检查其结构是否符合模板要求（如 Schema 的 Definition 引用、Configuration 的分类等）。如果发现结构过时，请顺手将其标准化。</li>
<li><strong>特殊说明 (Special Notes)</strong>:
<ul>
<li><strong>模板链接格式 (Template Link Format)</strong>:
<ul>
<li>模板(<code>template.md</code>)中所有的占位符链接（如 <code>Definition</code> 处的 <code>[InterfaceName](...)</code> 或 <code>Related</code> 处的 <code>[RelatedConcept](...)</code>）均使用了<strong>代码块</strong>包裹，以避免构建时因路径不存在而报错。</li>
<li><strong>AI 操作</strong>: 在编写正式文档时，<strong>必须将其还原为可点击的标准 Markdown 链接</strong>（即去掉反引号），并确保路径指向真实存在的文件。</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>请严格遵循该模板的结构，以保证文档风格一致性。</p>
<hr>
<h1 id="part-2-maintenance-guide-维护指南" class="tsd-anchor-link">Part 2: Maintenance Guide (维护指南)<a href="#part-2-maintenance-guide-维护指南" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<h2 id="核心原则-core-principles" class="tsd-anchor-link">核心原则 (Core Principles)<a href="#核心原则-core-principles" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>为了防止文档与代码脱节，我们遵循 <strong>“代码变更驱动文档更新”</strong> 的原则。</p>
<h2 id="1-语义化检索-semantic-retrieval" class="tsd-anchor-link">1. 语义化检索 (Semantic Retrieval)<a href="#1-语义化检索-semantic-retrieval" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>不再维护硬编码的“源码-文档”映射表。AI 维护者在修改代码后，应利用自身的语义搜索能力（如 <code>SearchCodebase</code> 或 <code>Grep</code>）来定位需要更新的文档。</p>
<p><strong>推荐策略</strong>:</p>
<ul>
<li>搜索<strong>类名/方法名</strong>: 如修改了 <code>five.load</code>，搜索 <code>five.load</code> 或 <code>load</code>。</li>
<li>搜索<strong>概念关键词</strong>: 如修改了射线检测逻辑，搜索 <code>Raycast</code> 或 <code>project2d</code>。</li>
</ul>
<h2 id="2-单一事实来源-single-source-of-truth" class="tsd-anchor-link">2. 单一事实来源 (Single Source of Truth)<a href="#2-单一事实来源-single-source-of-truth" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><strong>API 签名</strong>: 以 <code>package/five/index.d.ts</code> 和代码中的 TSDoc 为准。</li>
<li><strong>ai_guides/api.md</strong>: 仅作为 <strong>索引 (Index)</strong> 和 <strong>摘要 (Summary)</strong>。不要试图复制所有参数细节，除非是核心参数。</li>
<li><strong>ai_guides/features/*.md</strong>: 重点解释 <strong>“为什么”</strong> 和 <strong>“怎么用”</strong>，避免机械复制类型定义。</li>
</ul>
<h2 id="3-维护工作流-maintenance-workflow" class="tsd-anchor-link">3. 维护工作流 (Maintenance Workflow)<a href="#3-维护工作流-maintenance-workflow" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="场景-a：代码功能迭代后-post-coding" class="tsd-anchor-link">场景 A：代码功能迭代后 (Post-Coding)<a href="#场景-a：代码功能迭代后-post-coding" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>当修改了 SDK 源码后，请执行以下检查：</p>
<ol>
<li><strong>反向查找</strong>: 利用工具搜索关键词（API 名称、Feature 名称），找到 <code>ai_guides/</code> 下相关的文档。</li>
<li><strong>更新文档</strong>:
<ul>
<li>如果修改了 API 签名 -&gt; 更新对应的 <code>Schema</code> 和 <code>Examples</code>。</li>
<li>如果废弃了功能 -&gt; 在文档中添加 <code>&gt; [!WARNING] Deprecated</code> 提示。</li>
</ul>
</li>
<li><strong>更新索引</strong>: 如果是新功能，确保将其添加到 <code>ai_guides/README.md</code> 的合适章节中。</li>
<li><strong>同步 llms.txt</strong>: 若新增了文档或修改了文档路径，<strong>必须</strong>同步更新项目根目录下的 <code>llms.txt</code>，确保外部索引与 <code>ai_guides/</code> 保持一致。</li>
</ol>
<h3 id="场景-b：api-文档同步-sync-api-doc" class="tsd-anchor-link">场景 B：API 文档同步 (Sync API Doc)<a href="#场景-b：api-文档同步-sync-api-doc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>定期检查 <code>ai_guides/api.md</code> 的完整性：</p>
<ol>
<li>读取 <code>package/five/index.d.ts</code> 获取最新公开 API。</li>
<li>对比 <code>ai_guides/api.md</code>，找出缺失的高频 API 或已删除的 API。</li>
<li><strong>注意</strong>: 只收录高频/核心 API，低频 API 应引导用户查看源码或专门的 Feature 文档。</li>
</ol>
<h2 id="目录结构说明" class="tsd-anchor-link">目录结构说明<a href="#目录结构说明" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><code>ai_guides/</code>: 文档根目录。</li>
<li><code>ai_guides/features/</code>: 功能性文档 (Features)。</li>
<li><code>ai_guides/release_notes/</code>: 版本更新记录。</li>
<li><code>ai_guides/api.md</code>: 核心 API 索引。</li>
<li><code>ai_guides/README.md</code>: 文档总索引。</li>
<li><code>package/five/index.d.ts</code>: <strong>API 签名的真理来源</strong>。</li>
</ul>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#ai-文档与维护指南-ai-documentation-maintenance-guide"><span>AI 文档与维护指南 (<wbr/>AI <wbr/>Documentation &amp; <wbr/>Maintenance <wbr/>Guide)</span></a><ul><li><a href="#summary"><span>Summary</span></a></li></ul><a href="#part-1-writing-guide-编写指南"><span>Part 1: <wbr/>Writing <wbr/>Guide (编写指南)</span></a><ul><li><a href="#目的"><span>目的</span></a></li><li><a href="#建议风格"><span>建议风格</span></a></li><li><a href="#最佳实践-best-practices"><span>最佳实践 (<wbr/>Best <wbr/>Practices)</span></a></li><li><ul><li><a href="#1-变量命名语义化-semantic-variable-naming"><span>1. 变量命名语义化 (<wbr/>Semantic <wbr/>Variable <wbr/>Naming)</span></a></li><li><a href="#2-区分属性与方法-property-vs-method"><span>2. 区分属性与方法 (<wbr/>Property vs <wbr/>Method)</span></a></li><li><a href="#3-显式说明默认行为-explicit-default-behavior"><span>3. 显式说明默认行为 (<wbr/>Explicit <wbr/>Default <wbr/>Behavior)</span></a></li></ul></li><li><a href="#标准模板结构-standard-template-structure"><span>标准模板结构 (<wbr/>Standard <wbr/>Template <wbr/>Structure)</span></a></li></ul><a href="#part-2-maintenance-guide-维护指南"><span>Part 2: <wbr/>Maintenance <wbr/>Guide (维护指南)</span></a><ul><li><a href="#核心原则-core-principles"><span>核心原则 (<wbr/>Core <wbr/>Principles)</span></a></li><li><a href="#1-语义化检索-semantic-retrieval"><span>1. 语义化检索 (<wbr/>Semantic <wbr/>Retrieval)</span></a></li><li><a href="#2-单一事实来源-single-source-of-truth"><span>2. 单一事实来源 (<wbr/>Single <wbr/>Source of <wbr/>Truth)</span></a></li><li><a href="#3-维护工作流-maintenance-workflow"><span>3. 维护工作流 (<wbr/>Maintenance <wbr/>Workflow)</span></a></li><li><ul><li><a href="#场景-a：代码功能迭代后-post-coding"><span>场景 <wbr/>A：代码功能迭代后 (<wbr/>Post-<wbr/>Coding)</span></a></li><li><a href="#场景-b：api-文档同步-sync-api-doc"><span>场景 <wbr/>B：<wbr/>API 文档同步 (<wbr/>Sync <wbr/>API <wbr/>Doc)</span></a></li></ul></li><li><a href="#目录结构说明"><span>目录结构说明</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>