# Godot Local Docs Ref > 当用户要求以文档为依据提供指导，或回答与操作实质上依赖可能因版本而异、可能已变化、尚不确定、存在争议或需要精确核实的引擎事实时，使用本地生成且版本匹配的 Godot 文档。 - Skill: `cloudreverie/godot-local-docs-ref` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add cloudreverie/godot-local-docs-ref` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudreverie/godot-local-docs-ref/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Cloudreverie (https://skillmd.com/u/cloudreverie) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cloudreverie/godot-local-docs-ref --- # Godot 本地文档参考 通过本地生成的文档确认可靠、版本匹配的 Godot 引擎知识，并保持检索范围集中。 ## 判断是否需要检索 当可靠的结果实质上依赖某项 Godot 特有事实，且满足以下任一条件时，检索文档： - 该事实可能因 Godot 版本而异，或可能已经变化。 - 精确的 API 契约、默认值、生命周期规则、工作流程、警告或错误含义会影响结果。 - 现有上下文无法确定引擎行为，或存在相互冲突的信息。 - 用户要求以文档为依据或针对特定版本进行核实。 用户文件和运行状态方面的事实应通过项目检查确认。如果观察到的状态也依赖引擎契约，应结合项目证据与文档判断。 复用当前任务中已经确认的事实。先进行一次聚焦查询，仅在结果不足时扩大范围。 ## 选择文档版本 - 根据用户请求或可靠的项目证据确定目标版本，再通过 `--version ` 使用 `references/godot-docs/`。 - 版本未知且仅安装了一套语料时，使用该语料，并在回答中注明版本。 - 安装了多套语料且版本会影响结论时，应先指出版本不明确，再决定采用哪套语料。 - 如果缺少匹配的 `manifest.json`，报告所需语料不可用。语料准备由部署者负责；运行时 Agent 不得自动运行 `scripts/build_godot_docs.py`。 ## 检索文档 使用对语料只读的搜索工具获取范围受限、按相关性排序的证据。 ```bash python3 /scripts/search_godot_docs.py "Node.queue_free" --version --show-best python3 /scripts/search_godot_docs.py "Creating your first script" --version --mode title python3 /scripts/search_godot_docs.py "Indented block expected" --version --mode content ``` - 查询类、`Class.member`、构造或实例化表达式（如 `Vector2()` 或 `JSON.new()`），或进行初步探索时，使用默认的 `auto` 模式。继承成员会回溯到定义它的类。 - 已知页面名称时使用 `--mode title`，已知章节标题时使用 `--mode section`，查询精确短语或错误时使用 `--mode content`。 - 查询精确时使用 `--show-best`；探索合适来源时使用默认排序列表。列表为前三项结果提供摘要，其余结果仅提供简要索引。 - 构造调用仅按参数数量筛选，不推断参数类型。`--show-best` 提示存在多个构造重载时（JSON 中见 `warnings`），首项不代表已经消歧；应移除该选项查看候选，并按来源路径核实适用签名。 - 如果结果仅有索引、摘要被截断，或结论需要相邻上下文，使用结果中的 `path:line` 定位 `references/godot-docs//`，读取足以确认事实的最小本地范围。 - 整页结果最多预览正文前 24 行，省略后文时也会标记 `truncated`；增大 `--max-chars` 不会扩大该行数范围，应按路径补读原文。 - 使用文档中的官方英文术语构造查询。先将非英文概念译为英文再检索；结果不足或相关条目排名较低时，使用不带限定的成员名、精确措辞或排序结果中的词项细化查询。 使用类参考页面核实签名、默认值、继承、信号、警告和弃用信息；使用手册页面了解概念、工作流程和示例。如果可靠的指导同时依赖 API 契约及其预期用法，应查阅两类页面。 ## 应用证据 - 应用证据前，确认来源版本与目标版本匹配。 - 对不显然的结论，引用结果报告的本地路径和标题。 - 区分文档事实、推断和项目观察，并说明已安装语料仍无法消除的不确定性。 ## 可选反馈 日志和评价默认关闭，沿用用户已有配置。仅在启用 `GODOT_DOCS_FEEDBACK_FILE` 或用户指定反馈文件后，遇到明显障碍或特别有用的发现时，可顺手记录一条：哪条查询遇到了什么、怎样解决或帮助了任务。无需每次调用都评价，也不为评价追加检索或测试。 提供实际查询、文档版本和一句中文观察即可；以下仅为格式示例： ```bash python3 /scripts/record_godot_docs_feedback.py --version 4.7 --query "Node.queue_free" --reason "摘要不足以判断调用时机，补读同页上下文后解决。" ``` 来源、评价等级和任务标识均可选；自定义语料需附带 `--docs-root`。不把主观评价当作验证结果，不粘贴源码或完整对话。脚本缺失或记录失败时跳过，继续原任务。需要额外参数时查看脚本 `--help`；配置说明在仓库 `README.md` 的“日志与反馈”一节，日常检索无需阅读。