PVF XMate (TypeSquirrel)

PVF XMate 是一个面向 Squirrel 脚本与 PVF 编辑工作流的 VS Code 扩展。它同时提供两类 AI 集成能力：

VS Code language model tools：供 GitHub Copilot 在编辑器内直接调用。
独立 MCP server：供支持 stdio MCP 的其他 AI 客户端调用。这两类入口共享同一批核心能力，但不是扩展里的所有功能都会自动暴露给外部 AI。当前对外暴露的是 8 个 AI 工具，覆盖内置符号检索、工程符号检索、当前上下文解析、角色名映射、技能导出、PVF 文件读写等场景。

核心能力

Squirrel 语言能力

IntelliSense：自动补全、成员补全、参数提示、内联类型提示。
Navigation：跳转定义、符号大纲、引用计数（CodeLens）。
Diagnostics：语法 / 结构 / DocBlock 缺失等增量分析。
Formatting：内置 Prettier 规则，可自定义括号风格、间距和宽度。
DocBlocks：生成、解析与嵌入提示，支持 @param / @return / 自定义标记。
Hover：显示函数签名、常量值，以及图片 / 视频等资源预览。
Snippets：常用 Squirrel 模式与 DocBlock 模板快速插入。

工程与内置符号能力

内置函数 / 类 / 成员 / 属性定义查询。
基于自然语言的内置函数候选检索。
工作区符号索引查询，可按符号名或自然语言检索工程内函数、类和成员。
当前文件上下文符号解析，可追踪局部变量、参数、初始化来源与推断类型。
角色名称映射查询，支持职业枚举、数值 ID、英文别名互转。

PVF 工作流能力

PVF Explorer 与虚拟文档编辑。
PVF 文件直接读取 / 写回，不要求文件已在编辑器中打开。
依赖当前 PVF 会话的脚本读取、写入、编译 / 反编译辅助。
技能导出 / 提取清单生成，可直接从脚本工程或当前打开的 PVF 会话导出。

Copilot 与 MCP 的关系

如果你使用的是 GitHub Copilot Chat：

扩展通过 package.json 中的 languageModelTools 直接向 Copilot 暴露工具。
这种模式不需要你手动配置 MCP。

如果你使用的是 Copilot 之外的 AI：

只要该客户端支持 stdio MCP，就可以调用本扩展提供的独立 MCP server。
当前仓库已经为 MarsCode 和 Trae CN 提供自动写入配置的逻辑。
其他 MCP 客户端需要手动配置，但底层仍然调用同一个 dist/mcp-server.js。

边界说明：

外部 AI 能调用的是独立 MCP server 中注册的 8 个工具，不等于扩展中的全部 UI 功能、命令或侧边栏能力。
某些工具依赖当前工作区索引或当前 PVF 会话。若没有活动编辑器，可通过 filePath、sourceText、pvfSessionId、pvfPath 等参数显式提供上下文。

当前 MCP 工具列表

semantic_search_functions：根据自然语言检索内置函数候选。
typesquirrel-get-builtin-function-definition：查询内置类、全局函数、成员方法、静态方法、属性定义。
typesquirrel-resolve-symbol-context：解析当前上下文中的局部变量、参数和来源表达式。
typesquirrel-query-workspace-symbol-index：查询工作区符号索引。
typesquirrel-query-character-names：查询角色名称映射。
typesquirrelBuildingCharacterScript：生成或执行技能导出 / 提取清单。
typesquirrel-pvf-read-file：读取当前 PVF 会话中的文件内容。
typesquirrel-pvf-write-file：写入当前 PVF 会话中的文件内容。

MCP 前置条件

1. 外部 MCP 客户端需要本机 Node

当前扩展为外部 MCP 客户端生成的配置是：

{
	"command": "node",
	"args": ["<extension-install-path>/dist/mcp-server.js"]
}

这意味着：

GitHub Copilot 直接使用扩展内建工具时，不需要你额外手动配置 Node。
任何通过独立 MCP server 调用本扩展能力的外部 AI，都需要本机可以执行 node。
建议使用 Node 18 或更高版本，当前 MCP 构建目标也是 Node 18。

2. 需要可访问的扩展安装目录

外部 MCP 配置最终会指向扩展安装目录下的脚本，例如：

VS Code: C:/Users//.vscode/extensions/dof.type-squirrel-/dist/mcp-server.js
Trae CN: C:/Users//.trae-cn/extensions/dof.type-squirrel-/dist/mcp-server.js

3. 某些工具依赖工作区或 PVF 会话状态

以下工具在没有上下文时能力会受限：

typesquirrel-query-workspace-symbol-index：依赖当前工作区索引。
typesquirrel-resolve-symbol-context：最好提供 filePath 或 sourceText。
typesquirrel-pvf-read-file / typesquirrel-pvf-write-file：依赖当前打开的 PVF 会话，或显式传入 pvfSessionId。
typesquirrelBuildingCharacterScript：可使用外部脚本工程，也可复用当前 PVF 会话。

自动写入的 MCP 配置

扩展激活时会自动尝试写入以下配置文件：

MarsCode: %USERPROFILE%/.marscode/vscode.mcp.config.json
Trae CN: %APPDATA%/Trae CN/User/mcp.json

自动写入策略：

如果 typesquirrel 配置不存在，则追加。
如果检测到扩展旧版本写入的错误路径，会自动修正。
如果用户已经自定义了同名配置且不是受管旧配置，则不会强制覆盖。

手动 MCP 配置示例

通用 stdio MCP 客户端

如果你的 AI 客户端支持 command + args 形式的 stdio MCP，可以按下面配置：

{
	"mcpServers": {
		"typesquirrel": {
			"command": "node",
			"args": [
				"C:/Users/<you>/.vscode/extensions/dof.type-squirrel-<version>/dist/mcp-server.js"
			]
		}
	}
}

MarsCode

MarsCode 默认配置文件：%USERPROFILE%/.marscode/vscode.mcp.config.json

{
	"mcpServers": {
		"typesquirrel": {
			"id": "typesquirrel",
			"command": "node",
			"args": [
				"C:/Users/<you>/.vscode/extensions/dof.type-squirrel-<version>/dist/mcp-server.js"
			]
		}
	}
}

Trae CN

Trae CN 默认配置文件：%APPDATA%/Trae CN/User/mcp.json

{
	"mcpServers": {
		"typesquirrel": {
			"id": "typesquirrel",
			"command": "node",
			"args": [
				"C:/Users/<you>/.trae-cn/extensions/dof.type-squirrel-<version>/dist/mcp-server.js"
			]
		}
	}
}

说明：

如果你的客户端配置格式与上面不同，只需要把 command 设为 node，并把参数指向 dist/mcp-server.js。
如果 node 不在 PATH 中，也可以把 command 改成 Node 的绝对路径。

Copilot 内置工具

GitHub Copilot 在 VS Code 中可直接使用扩展注册的 language model tools，无需单独配置 MCP。当前暴露的能力与上面的 MCP 工具基本对齐，适合在聊天中直接查询：

内置函数 / 类定义。
工程符号索引。
当前上下文符号。
角色名称映射。
技能提取清单。
PVF 文件读写。

扩展也会自动同步用户级技能文件，当前默认写入两个目录：

Copilot: %USERPROFILE%/.copilot/skills
Trae CN: %USERPROFILE%/.trae-cn/skills

其他说明

JSDoc / DocBlock

基于文档注释中的类型信息提供更精准的补全与诊断。
自动模板：基于函数签名生成参数与返回类型注释。
作用域控制：可标记可见性以调节补全曝光，例如 @public / @protected / @private。
Getter / Setter：文档化后在补全中呈现属性访问形式。
类型覆盖：在缺失或推断不完整时手动指定类型。
期望值：参数可附带固定候选值，触发补全列表。
片段扩展：DocBlock 也能作为片段复用。

索引与缓存

首次打开文件夹时会全量索引。
后续有增改时使用增量缓存。
工作区缓存文件位于 .typesquirrel-workspace-index.json。

Credits

Kudos to the Attract-Mode developers, contributors, and community.

Attract-Mode-Plus-Squirrel - by Chadnaut

PVF XMate

DOF