unity_docs 详解：Unity MCP 官方文档检索工具的使用与源码原理-港品优选

unity_docs 详解：Unity MCP 官方文档检索工具的使用与源码原理

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp

unity_docs是 Unity MCP 的docs工具组中负责检索官方文档的核心工具，它从 docs.unity3d.com 拉取 ScriptReference、Manual 与包文档，并返回描述、参数详情、代码示例与注意事项。本文以 unity_docs 工具参考文档为主体，结合服务端实现、单元测试与技能手册，讲解其四种 Action、全部参数、返回结构、底层抓取与解析原理，并给出与unity_reflect配合的 API 验证工作流，帮助你准确、高效地为 AI 生成可靠的 Unity 代码。

工具定位与适用场景

unity_docs归属于docs工具组（group=docs），模块路径为services.tools.unity_docs，通过 Server/src/services/tools/unity_docs.py 中的@mcp_for_unity_tool装饰器注册到 MCP 服务（可在 manifest.json 中查看到它的注册声明）。

它的核心能力是：

从 docs.unity3d.com 获取 Unity 官方文档，返回描述（description）、参数详情（parameters）、代码示例（examples）与注意事项（caveats）。推荐在unity_reflect确认某个类型确实存在之后使用，用于在编写实现代码前获取用法模式、坑点与示例代码。

这里体现了两个关键定位：

与unity_reflect互补：unity_reflect通过运行时反射检查"编辑器里实际存在什么 API"（需要 Unity 连接），而unity_docs拉取"官方文档怎么说"（不需要 Unity 连接），两者构成"反射 > 项目资产 > 官方文档"的信任层级；
面向写码前验证：避免 AI 在写 C# 时臆造或使用过时的 API 签名。

docs工具组是可选（opt-in）的，首次使用前需要通过manage_tools(action="activate", group="docs")激活，详见 workflows.md。

四种 Action 一览

unity_docs通过action参数区分四种操作，常量ALL_ACTIONS = ["get_doc", "get_manual", "get_package_doc", "lookup"]在源码中定义（见 unity_docs.py）：

Action	用途	必填参数	可选参数
`get_doc`	获取某个类或成员的 ScriptReference 文档	`class_name`	`member_name`、`version`
`get_manual`	获取 Unity Manual 页面	`slug`（如`execution-order`、`urp/urp-introduction`）	`version`
`get_package_doc`	获取包文档	`package`、`page`、`pkg_version`	—
`lookup`	并行检索所有文档源（ScriptReference + Manual + 包文档），并支持批量查询	`query`或`queries`	`package`、`pkg_version`、`version`

传入未知的action时，工具会返回success: false及提示信息Unknown action 'xxx'. Valid actions: ...，这一点有对应的单元测试覆盖（test_unknown_action_returns_error）。

get_doc：类与成员的 ScriptReference 文档

用于获取类（如Physics、Transform）或类成员（如Physics.Raycast、Transform.position）的脚本参考文档。内部会抓取对应 HTML 页面，并通过 HTML 解析器抽取结构化内容：description（描述）、signatures（方法签名列表）、parameters（参数表）、returns（返回值说明）、examples（C# 代码示例）。

get_manual：Manual 页面

通过页面 slug 获取 Unity 手册文章，例如脚本执行顺序execution-order、URP 介绍urp/urp-introduction。返回内容为文章标题（title）、按标题切分的章节（sections，每个章节含heading与content）以及代码示例（code_examples）。

get_package_doc：包文档

获取某个安装包的 manual 文档，需要同时提供包名、页面与版本，例如：

unity_docs(action="get_package_doc", package="com.unity.render-pipelines.universal", page="2d-index", pkg_version="17.0")

缺少package、page、pkg_version三者中的任何一个都会直接返回错误（get_package_doc requires package, page, and pkg_version.）。

lookup：多源并行检索与批量查询

lookup是覆盖面最广的入口：一次调用同时搜索 ScriptReference、Manual，若提供了package与pkg_version还会搜索对应包文档。支持两种传参方式：

query：单个查询；
queries：逗号分隔的批量查询，例如queries='Physics.Raycast,NavMeshAgent,Light2D'一次调用即可全部检索。

一个值得注意的增强行为是：当查询涉及资源关键词（shader、material、texture、sprite、prefab、mesh、model、font 以及 lit/unlit/urp/hdrp/2d/3d 等）时，lookup还会自动检索当前 Unity 项目的资产（通过manage_asset的searchaction，需要 Unity 连接）。例如lookup(query="Lit shader")会同时返回官方文档命中和项目中匹配的 Shader/Material 资产。

参数参考

参数	类型	必填	说明
`action`	`str`	是	要执行的文档操作：`get_doc`/`get_manual`/`get_package_doc`/`lookup`
`class_name`	`str \\| None`	get_doc 必填	Unity 类名（如`Physics`、`Transform`）
`member_name`	`str \\| None`	否	要查询的方法或属性名
`version`	`str \\| None`	否	Unity 版本（如`6000.0.38f1`），会自动提取 major.minor
`slug`	`str \\| None`	get_manual 必填	Manual 页面 slug（如`execution-order`）
`package`	`str \\| None`	get_package_doc 必填；lookup 可选	包名（如`com.unity.render-pipelines.universal`）
`page`	`str \\| None`	get_package_doc 必填	包文档页面（如`index`、`2d-index`）
`pkg_version`	`str \\| None`	get_package_doc 必填；lookup 可选	包版本 major.minor（如`17.0`）
`query`	`str \\| None`	lookup 单查询	单个检索词（类名、主题或 slug）
`queries`	`str \\| None`	lookup 批量	逗号分隔的批量检索词（如`Physics.Raycast,NavMeshAgent,Light2D`）

返回结构

所有操作统一返回一个包含 Unity 响应的dict，具体形状随 action 变化：

成功找到文档时：{"success": true, "data": {"found": true, ...}}；
404 未找到时：success仍为true，但data.found = false，并附带suggestion提示下一步（如"用unity_reflect的 search 确认类型名后重试"）；
网络不可达时：{"success": false, "message": "Could not reach docs.unity3d.com: ..."}。

get_doc的data包含：url、class、member、description、signatures、parameters、returns、examples、see_also。get_manual/get_package_doc的data包含：found、url、title、sections、code_examples。lookup的data则提供聚合视图：found、queries、results（每条查询一个结果对象，含query、hits、sources_checked）以及summary（total/found/missed统计）。

调用示例

以下示例来自 tools-reference.md：

# 获取类的 ScriptReference 文档 unity_docs(action="get_doc", class_name="Physics") unity_docs(action="get_doc", class_name="Physics", member_name="Raycast") unity_docs(action="get_doc", class_name="Transform", version="6000.0.38f1") # 获取 Manual 页面 unity_docs(action="get_manual", slug="execution-order") unity_docs(action="get_manual", slug="urp/urp-introduction") # 获取包文档 unity_docs(action="get_package_doc", package="com.unity.render-pipelines.universal", page="2d-index", pkg_version="17.0") # 单查询并行 lookup unity_docs(action="lookup", query="Physics.Raycast") # 批量 lookup（一次检索多个 API） unity_docs(action="lookup", queries="Physics.Raycast,NavMeshAgent,Light2D") # 带包文档的 lookup unity_docs(action="lookup", query="VolumeProfile", package="com.unity.render-pipelines.universal", pkg_version="17.0")

底层实现原理

版本号自动提取

传入的version（如6000.0.38f1、2022.3.45f1、6000.1.0b2）会先经过_extract_version归一化为major.minor（6000.0、2022.3、6000.1），再拼接到文档 URL 中；空值或缺失则使用无版本号的 URL（见 unity_docs.py）。

URL 构造规则

类文档：https://docs.unity3d.com/{version}/Documentation/ScriptReference/{Class}.html；
成员文档使用点分隔：{Class}.{member}.html（如Physics.Raycast.html）；
属性文档使用短横线分隔（property 风格）：{Class}-{member}.html（如Transform-position.html）；
Manual：https://docs.unity3d.com/{version}/Documentation/Manual/{slug}.html；
包文档：https://docs.unity3d.com/Packages/{package}@{pkg_version}/manual/{page}.html。

相关构造函数为_build_doc_url与_build_property_url，均有单元测试验证 URL 形态（test_build_url_class_only、test_build_property_url等）。

抓取与容错回退

抓取基于标准库urllib（请求头User-Agent: MCPForUnity/1.0，超时 10 秒），并通过asyncio.get_running_loop().run_in_executor放入线程池执行，避免阻塞事件循环（unity_docs.py）。抓取包含两级智能回退：

成员回退：成员用点分隔 URL 返回 404 时，自动改用属性风格的短横线 URL 重试（如Transform.position走Transform-position.html）；
版本回退：带版本号的 URL 404 时，自动退回无版本 URL；get_manual同样支持该回退。

测试用例test_get_doc_property_fallback、test_get_doc_version_fallback、test_get_manual_version_fallback分别验证了这些路径。

HTML 解析器

针对两类页面使用了两套基于HTMLParser的自研解析器：

_UnityDocParser（ScriptReference）：抽取 description、signatures、parameters、returns、examples。它同时兼容新旧两代 Unity 文档 HTML 结构——旧版类名name-collumn/desc-collumn和新版name lbl/desc都能正确解析参数表；方法签名既支持<pre>包裹的旧格式，也支持新版signature-CS内联文本（并会剥离 "Declaration" 前缀）（unity_docs.py）；
_ManualPageParser（Manual / 包文档）：按h1标题 +h2/h3章节 +p段落 +pre代码块切分为sections与code_examples（unity_docs.py）。

两个解析器在 test_unity_docs.py 中都有基于真实 HTML 样本（含新旧格式）的断言测试。

lookup 的并发检索与项目资产联动

lookup的内部流程值得单独说明（unity_docs.py）：

解析查询：若查询含.且不以com.开头（避免与包名混淆），自动拆分为class_name.member_name，例如Physics.Raycast拆为Physics+Raycast；
构造并行任务：同时发起 ScriptReference 查询、原大小写 Manual 查询（如UIE-USS-Properties-Reference会保留原始大小写，同时尝试小写版本）、以及（可选）包文档查询；
asyncio.gather并行执行，收集命中的hits（标注来源script_ref/manual/manual_lc/package/package_lc）与非致命errors；
资源类查询联动项目资产：命中_ASSET_KEYWORDS时调用_search_assets，从查询中提取非停用词（如in/the/a/for/unity/using等会被过滤）构造*term*搜索模式，并依据关键词推断filter_type（如shader→Shader、material→Material、texture→Texture2D、sprite→Sprite、prefab→Prefab、mesh→Mesh、font→Font），通过manage_asset的searchaction 并行检索Assets目录（每项pageSize=10，结果上限 15 条去重）；
汇总统计：返回summary.total / found / missed，当存在未命中时会附上suggestion（建议改用get_doc精确类名、get_manual正确 slug，或manage_asset(action='search')检索 shader/material/prefab 等资源）。

_should_search_assets的判定在测试中也有覆盖："Mesh2D shader"、"Lit material"、"URP 2D lighting"、"default sprite"触发资产搜索，而"Physics.Raycast"、"NavMeshAgent"、"execution-order"不触发。

与 unity_reflect 配合的标准工作流

Unity MCP 的技能手册给出了推荐的 API 验证四步流程（workflows.md），核心是"反射（运行时真实 API）> 项目资产 > 官方文档"的信任层级：

# Step 1: 检索所需类型 unity_reflect(action="search", query="NavMesh") # → 返回匹配类型：NavMeshAgent、NavMeshPath、NavMeshHit ... # Step 2: 获取类型成员摘要 unity_reflect(action="get_type", class_name="UnityEngine.AI.NavMeshAgent") # Step 3: 获取具体成员的完整签名 unity_reflect(action="get_member", class_name="NavMeshAgent", member_name="SetDestination") # → 返回参数类型、返回类型、全部重载 # Step 4: 用 unity_docs 获取官方文档与示例 unity_docs(action="get_doc", class_name="NavMeshAgent", member_name="SetDestination") # → 返回描述、签名、参数、代码示例

跨版本校验场景可以显式指定版本：

unity_docs(action="get_doc", class_name="Camera", member_name="main", version="6000.0.38f1")

CLI 方式调用

除 MCP 调用外，服务端 CLI 也提供了文档查询入口 Server/src/cli/commands/docs.py：

unity-mcp docs get Physics unity-mcp docs get Physics Raycast unity-mcp docs get NavMeshAgent SetDestination --version 6000.0

其中class_name为必填位置参数，member_name可选，--version/-v指定 Unity 版本，输出格式跟随全局配置（--format）。

测试验证与可靠性

Server/tests/test_unity_docs.py 对工具做了系统性验证，可作为理解行为的依据：

纯函数测试：版本提取（完整版本、LTS、beta、空值、短版本）、URL 构造（类 / 成员点分隔 / 属性短横线 / 无版本）；
解析器测试：新旧两代 HTML 格式的 description、signatures、parameters、returns、examples 抽取，以及空 HTML 的健壮性；
动作层测试：未知 action 报错、必填参数校验、成功路径、404 未找到（含 suggestion）、属性回退、版本回退、网络错误（Could not reach）；
lookup 测试：单查询、批量查询（Physics,Camera,zzz-nonexistent得到found=2 / missed=1）、无结果建议、资产关键词检测与搜索词构造。

常见问题与排查建议

返回found: false：优先确认类名/成员名/slug 拼写。get_doc的 suggestion 会提示先用unity_reflect的search核实类型名；get_manual的 suggestion 会提示常见 slug 如execution-order、urp/urp-introduction、UIE-USS-Properties-Reference；get_package_doc的 suggestion 会提示核对包名、版本与页面（常见页面index、installation、whats-new）。
返回success: false且提示无法连接：说明网络无法访问 docs.unity3d.com，此时lookup中依赖 Unity 连接的资源搜索部分也会降级跳过（_search_assets内部捕获ImportError与异常并返回None）。
lookup部分查询未命中：查看summary中的missed与每条results的hits/sources_checked，再按 suggestion 改用精确的get_doc/get_manual或项目资产搜索。
想查属性而非方法：get_doc的成员回退会自动处理点/短横线两种 URL；直接写member_name="position"即可。
资源类查询想同时看项目资产：使用lookup并让查询包含shader、material、texture等关键词，但注意该联动需要当前会话具备 Unity 连接。

总而言之，unity_docs是 Unity MCP 文档验证链路的"官方依据"环节：它不依赖 Unity 编辑器即可使用，覆盖面横跨 ScriptReference、Manual 与包文档，并通过并行 lookup、自动回退、资产联动等机制，把"查文档"这件事从一次笨拙的单页抓取变成了面向 LLM 的结构化检索能力，是写码前校验 API 事实的关键一环。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析