Godot 离线文档 TheoiNabiy/godot-docs-dsh-plugin

godot-docs —— 面向 DSH 的离线 Godot 文档工具插件

这是一个 DSH（DeepSeek Harness）插件，把本地的 Godot 官方文档（godot-docs 仓库或其 .rst.txt 导出）变成 Agent 可用的工具。
Agent 不再凭记忆回答 Godot 问题（记忆通常是 Godot 3.x 或更老的 4.x），而是从与当前项目引擎版本一致的文档里查证，并给出所引用的文件与行号。

仓库：<https://github.com/TheoiNabiy/godot-docs-dsh-plugin> · English: README.md

文档目录 ──▶ 索引（类、成员、正文词元）──▶ godot_docs_ 工具 ──▶ Agent

为什么

* 版本正确：索引中的文档就是本项目的权威依据；插件会自动识别文档版本（例如 4.7）。
* 签名精确：godot_docs_member("CharacterBody2D","move_and_slide") 返回真实签名、默认值、修饰符与说明，并附带文件行号。
* 查询很快：1600 页 / 32 MiB 文档，单次搜索约 25–90 ms。
* 完全离线：不访问网络，索引全部来自本地磁盘。

工具一览

| 工具 | 作用 |
| godot_docs_search | 全文检索（all / classes / tutorials），返回摘录与 相对路径#L行号；命中规范页时带 convention_topic 标记 |
| godot_docs_class | 类参考：继承链（祖先与直接子类双向）、描述、教程链接、枚举成员及取值、完整成员表（属性/方法/信号/常量/枚举/注解）及精确行号，并列出可继承到的成员 |
| godot_docs_member | 单个成员的完整信息：签名、参数、默认值、说明、所在行（可用 kind:name 指定类型）；继承成员会沿继承链解析并给出 declared_on；枚举会列出全部取值，常量会给出数值 |
| godot_docs_find_member | 反向查找：哪些类声明了同名的成员（如 signal:body_entered 查出所有拥有该信号的类） |
| godot_docs_project_settings | 查询某个设置项或整棵分支（debug/gdscript/warnings/ 会列出全部 GDScript 警告名），或校验真实的 project.godot 并报出文档中不存在的键 |
| godot_docs_get | 读取整页或某一节，返回清理过 RST 标记的带行号文本（path#L120-L180、path#Method Descriptions） |
| godot_docs_code | 抽取官方示例代码（gdscript、csharp、glsl、cpp 等），供改写而不是凭空编 API |
| godot_docs_conventions | 查官方开发规范：GDScript 风格、项目/场景组织、静态类型、@export、文档注释、警告系统、单例取舍、信号、C# 风格与 API 差异、着色器风格、文件路径、i18n、性能、线程安全、编辑器插件等，并给出对应页面路径 |
| godot_docs_project_search | 在本项目自己的源码里做字面/正则检索：看某 API 既有用法、找全部调用点、检查推荐写法是否已遵守 |
| godot_docs_api_check | 校验标识符（Class、Class.member）、整段 GDScript/C#，或整个项目目录——脚本以及 .tscn/.tres 场景与资源：对文档中不存在的名字给出 文件:行号 的调用点 |
| godot_docs_status | 当前索引了哪些文档树、识别到的版本、页数/类数、缓存状态、探测路径与解析错误 |
| godot_set_docs_path | 把文档目录写入插件配置（立即生效） |

插件还会注入三段系统提示（system prompt）：先查文档、没有文档时如何配置路径，以及（重要）按引擎自己的规范写代码，而不是照搬其他引擎的习惯或记忆中的做法。

不只是 API，还有规范

这份文档树本身就包含本项目的编码规范。godot_docs_conventions 把主题或别名映射到权威页面（并告诉你该页面是否存在于当前文档树），godot_docs_search 会在结果里标出规范页，而 godot-docs:conventions 提示段会列出文档确立的要点：GDScript 风格指南的命名与代码顺序、静态类型、用 @export 暴露可调参数、用信号代替轮询、保持节点树扁平并拆进场景、用 %UniqueName 代替长节点路径、不要滥用 autoload、运行时写 user:// 而不是 res://、可翻译文本用 tr() 且不要拼接、耗时工作交回主线程而不是在线程里随意调引擎 API、不要无视引擎警告。

共收录 40 个规范主题，每一个都由自检脚本验证确实存在于该文档树中：GDScript 风格/静态类型/ @export/文档注释/警告系统/格式化字符串、C# 风格、C# 与 GDScript 的 API 差异、C# 语言特性、项目与场景组织、场景与脚本取舍、autoload、信号、分组、资源、节点与对象取舍、逻辑与数据、数据存储取舍、接口、通知、idle 与物理帧、可重写回调、暂停、输入、多分辨率、文件路径、国际化、性能、线程安全、着色器风格、编辑器插件、单元测试等。

校验真实代码

godot_docs_api_check(paths=[...]) 会遍历项目自己的脚本与场景，报告本文档版本里不存在的
引用，并给出每处 文件:行号。它刻意保守——误报的代价高于漏报——只断言可证的部分：

脚本部分：

* 文档中存在的类的 Class.member，成员沿继承链解析（Node.get_property_list 在 Object 上； TCPServer.new 是语言层构造而非缺失方法）；
* 类型可证的变量的成员访问：is 判断、as 转换、构造调用，或有文档的返回类型；
* 绝不报告：字符串字面量（"res://levels/Node2D.tscn"）、容器键（Dictionary/Array 属性包）、被 := 遮蔽的变量、self./super. 成员、GDScript 语言内置成员。

.tscn/.tres 场景与资源部分：

* 节点类型必须是文档中的类（type="Sprite2Dxx" 会被报出）；
* 节点属性与子资源属性按该节点的类校验，因此拼错或改名的属性无需打开编辑器就能发现；
* 由节点自身脚本声明的属性——@export var max_health——会从项目脚本解析出来，包含继承来的 （extends Entity），并包含被实例化场景根脚本的导出变量；
* 信号连接按 from 节点解析出的类校验；
* 属于格式/编辑器而非类 API 的键会被识别并计入统计，而不是报错：layout_mode、 anchors_preset、theme_override_、metadata/、各种块头；
* .tres 的根 [resource] 块按 gd_resource type 校验。

godot_docs_project_settings(path=<项目目录>) 对 project.godot 做同样的事：报出所有本文档版本
未收录的键及其行号与相近候选。config_version 与 application/config/features（引擎写入）以及用户自定义的 [input]、[autoload]、[layer_names]、[editor_plugins] 段被视为结构而非 API。

在作者本机的 7 个真实 Godot 项目上，脚本检查约 6000 处 API 用法只报出 2 处，且都是真错误
（Camera3D.get_environment() 实际只存在于 World3D；ThemeDB.get_fallback_font() 是属性不是方法）。

这类调用到底搜的是哪个项目

读取项目文件的工具以会话工作区为基准：省略 path/paths 时从工作区开始，相对路径按工作区解析，工作区自身或其上级目录里存在 project.godot 才是"这个项目"。宿主进程自己的目录永远不作为基准——在桌面版里那就是 DSH profile 目录，而一次静默扫描 ~/.dsh/profiles/<profile> 却把它当成项目的搜索，会以 "0 条匹配"的形式回答。

当被搜索目录及其上级都没有 project.godot 时，返回值会明说而不是猜：godot_docs_project_search 返回 found_project_godot: false、resolved_by: "start"，并在 hint 里指出该根目录只是回退；godot_docs_api_check 也会在汇总里标注该路径。对文档树或散放的脚本目录来说这是正常情况；要搜真实项目请显式传 path=。

索引了哪些数据

所有工具的回答都来自首次调用时从文档树构建的索引（1600 页约 2.5 秒），并缓存为 JSON （~/.dsh/godot-docs-cache/index-<hash>.json，约 30 MiB，约 170 ms 重新载入）：

* 每页元数据：标题、继承链、描述、章节标题、正文长度；
* 1078 个类上的 25340 条成员锚点（属性/方法/信号/常量/构造/运算符/注解/私有回调/主题项）及精确行号；
* 788 个枚举、5601 个取值（含 Variant.Type 这类带点号的枚举名）；
* 可继承成员表，因此类只继承来的成员也能解析；
* 941 个有文档的项目设置及其键名与行号；
* 用于检索的正文词元倒排索引。

两个查询不落盘、按需派生（各约 20 ms，避免让缓存继续膨胀）：成员反查索引 （godot_docs_find_member）与子类表（godot_docs_class）。

安装

插件是标准 DSH bundle（ESM 插件 + cordis.patch.yml）。在本 package.json 所在目录执行：

dsh plugin --profile <profile> add <本地路径或 git 地址>

本仓库的 git 地址为：

dsh plugin --profile <profile> add git+https://github.com/TheoiNabiy/godot-docs-dsh-plugin.git

也可以手动写入 profile 的 package.json 依赖与 dsh.profile.bundles，再启动 profile。
bundle 层会注册组合行：

- insert:
- id: tool-godot-docs
name: godot-docs

文档路径也可直接写进 profile 的 cordis.patch.yml（或用 godot_set_docs_path、或插件卡片上的 docsPath 字段）：

- id: tool-godot-docs
name: godot-docs
config:
docsPath: D:\Godot\godot-docs-master

文档来源与优先级

以下来源按顺序使用，先解析到文档树的那一层生效：

1. 工具参数 docs_path；
2. 插件配置 docsPath（可写多个目录，用 ; 或换行分隔）；
3. 会话工作区及其上层目录（因此把文档检出直接作为工作区打开时无需任何配置）；
4. 约定位置（~/godot-docs、~/Documents/godot-docs、C:/godot/godot-docs、 /usr/local/share/godot-docs、/opt/godot-docs）。

判定标准：目录下存在 classes/class_node.rst.txt。显式传入的 docs_path 具有权威性——若它不是一个文档树，工具会直接说明原因，而不会悄悄改用手头其他文档。

索引与缓存

首次调用会构建索引（1600 页约 2.5 秒）：每页元数据（标题、继承链、描述、章节标题、正文长度）、全部 .. _class_X_method_y: 成员锚点，以及正文词元倒排索引。随后会持久化为 JSON （~/.dsh/godot-docs-cache/index-<hash>.json，约 18 MiB），并以「页数 + 最新 mtime」校验，之后每个会话加载仅需约 70 ms。若所有缓存位置都不可写，则每个进程重新构建索引，功能不受影响。

配置项

| 字段 | 类型 | 说明 |
| docsPath | string | 需要索引的文档目录。DSH ≥ 0.2 上为 volatile 字段，GUI 表单可原位编辑。 |

开发

node test/run.mjs [文档目录] # 39 项自检：注册工具并逐一调用验证
node test/bench.mjs [文档目录] # 索引构建 / 缓存 / 搜索耗时

test/node_modules 内是 @deepseek-ai/dsh-tools 与 @deepseek-ai/schemastery 的最小桩实现，test/hooks.mjs 负责把这两个导入重定向过去，使插件能脱离 harness 单独启动。

许可

MIT。