tool-rename-deprecation

工具重命名弃用

更改工具或工具集引用名称时，必须始终将旧名称添加到弃用/旧名称数组中，以确保现有提示词文件、工具配置和已保存的引用仍能正确解析。

适用时机

对任何内置工具或工具集注册代码的更改运行此技能，以发现回归问题：

• 重命名工具的 toolReferenceName
• 重命名工具集的 referenceName
• 将工具从一个工具集移到另一个工具集（旧的 toolSet/toolName 路径将成为旧名称）
• 审查修改工具注册的 PR — 确认没有删除旧名称

操作步骤

步骤 1 — 确定更改内容

判断你重命名的是工具还是工具集，以及它的注册位置：

实体	注册位置	要重命名的名称字段	旧名称数组	稳定 ID（绝不可更改）
工具（IToolData）	TypeScript	toolReferenceName	legacyToolReferenceFullNames	id
工具（扩展）	package.json languageModelTools	toolReferenceName	legacyToolReferenceFullNames	name（会成为 id）
工具集（IToolSet）	TypeScript	referenceName	legacyFullNames	id
工具集（扩展）	package.json languageModelToolSets	name 或 referenceName	legacyFullNames	—

关键提示： 对于扩展提供的工具，package.json 中的 name 字段会映射到 IToolData 上的 id（参见 languageModelToolsContribution.ts 第 id: rawTool.name 行）。它还用于激活事件（onLanguageModelTool:<name>）。绝不要重命名 name 字段 — 只重命名 toolReferenceName。

步骤 2 — 将旧名称添加到旧名称数组

确认旧的 toolReferenceName 值出现在 legacyToolReferenceFullNames 中。 不要假设它已经存在 — 请检查数组的实际内容。如果旧名称已在列表中（例如，之前重命名时添加的），请确认它未被删除。如果不存在，请将其添加进去。

对于内部/内置工具（TypeScript IToolData）：

// Before rename
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'oldName',
	// ...
};

// After rename — old name preserved
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'newName',
	legacyToolReferenceFullNames: ['oldName'],
	// ...
};

如果该工具之前位于某个工具集中，请使用完整的 toolSet/toolName 格式：

legacyToolReferenceFullNames: ['oldToolSet/oldToolName'],

如果重命名多次，请累积保留所有先前名称 — 不要删除现有条目：

legacyToolReferenceFullNames: ['firstOldName', 'secondOldName'],

对于工具集，调用 createToolSet 时，将旧名称添加到 legacyFullNames 选项中：

toolsService.createToolSet(source, id, 'newSetName', {
	legacyFullNames: ['oldSetName'],
});

对于扩展提供的工具（package.json），只重命名 toolReferenceName，并将旧值添加到 legacyToolReferenceFullNames。不要重命名 name 字段：

// CORRECT — only toolReferenceName changes, name stays stable
{
	"name": "copilot_myTool",           // ← KEEP this unchanged
	"toolReferenceName": "newName",     // ← renamed
	"legacyToolReferenceFullNames": [
		"oldName"                       // ← old toolReferenceName preserved
	]
}

步骤 3 — 检查所有工具名称使用方

凡是通过引用名称查找工具的地方，都必须支持旧名称，而不仅仅是在提示词解析中。主要使用方包括：

• 提示词文件 — getDeprecatedFullReferenceNames() 会将旧名称映射到当前名称，用于 .prompt.md 验证和代码操作
• 工具启用 — getToolAliases() / getToolSetAliases() 会返回旧名称，以便工具选择器和启用映射正确解析
• 自动批准配置 — isToolEligibleForAutoApproval() 会检查 legacyToolReferenceFullNames（包括带命名空间旧名称中 / 后的部分），并与 chat.tools.eligibleForAutoApproval 设置进行匹配
• RunInTerminalTool — 有自己的本地自动批准检查，也会遍历 LEGACY_TOOL_REFERENCE_FULL_NAMES

重命名后，请确认：

1. .prompt.md 文件中的 #oldName 仍能解析（不会显示验证错误）
2. 引用了旧名称的工具配置仍能激活该工具
3. 曾设置 "chat.tools.eligibleForAutoApproval": { "oldName": false } 的用户，其限制仍然有效

步骤 4 — 更新引用（可选）

虽然旧名称可确保向后兼容，但请更新第一方引用，改用新名称：

• 系统提示词和内置的 .prompt.md 文件
• 通过引用名称提及该工具的文档和模型描述
• 直接引用旧名称的测试文件

关键文件

文件	内容
src/vs/workbench/contrib/chat/common/tools/languageModelToolsService.ts	带有旧名称字段的 IToolData 和 IToolSet 接口
src/vs/workbench/contrib/chat/browser/tools/languageModelToolsService.ts	解析逻辑：getToolAliases、getToolSetAliases、getDeprecatedFullReferenceNames、isToolEligibleForAutoApproval
src/vs/workbench/contrib/chat/common/tools/languageModelToolsContribution.ts	扩展点架构、验证，以及关键的 id: rawTool.name 映射（第 ~274 行）
src/vs/workbench/contrib/terminalContrib/chatAgentTools/browser/tools/runInTerminalTool.ts	工具的示例：它针对旧名称自行执行本地自动批准检查

实例

• runInTerminal 工具：从 runCommands/runInTerminal 重命名而来 → legacyToolReferenceFullNames: ['runCommands/runInTerminal']
• todo 工具：从 todos 重命名而来 → legacyToolReferenceFullNames: ['todos']
• getTaskOutput 工具：从 runTasks/getTaskOutput 重命名而来 → legacyToolReferenceFullNames: ['runTasks/getTaskOutput']

参考 PR

• #277047 — 设计 PR：引入了 legacyToolReferenceFullNames 和 legacyFullNames，构建了解析基础设施，并完成了第一批工具重命名。请将其作为正确使用旧名称进行重命名的模板。
• #278506 — 消费者端修复：在 #277047 中重命名后，eligibleForAutoApproval 设置未检查旧名称，导致限制了旧名称的用户失去了该限制。此 PR 说明了为什么所有使用工具引用名称的消费者都必须处理旧名称。
• vscode-copilot-chat#3810 — 遗漏示例：将 openSimpleBrowser 重命名为 openIntegratedBrowser，但也更改了 name 字段（稳定 ID），从 copilot_openSimpleBrowser 改为 copilot_openIntegratedBrowser。toolReferenceName 的向后兼容性只是碰巧生效（旧名称此前已因其他更改存在于旧名称数组中，并非作为此次重命名的一部分有意添加）。

回归检查

对任何涉及工具注册的 PR 执行此检查（TypeScript IToolData、createToolSet，或 package.json 中的 languageModelTools/languageModelToolSets）：

1. 搜索差异中变更的 toolReferenceName 或 referenceName 值。 对每处变更，确认之前的值现在出现在 legacyToolReferenceFullNames 或 legacyFullNames 中。不要假设它已经存在——请检查实际数组。
2. 搜索扩展贡献工具中变更的 name 字段。 name 字段是工具稳定的 id，绝不能更改。如果它变了，请将其标记为错误。（这会破坏激活事件、按 ID 调用工具，以及任何通过工具的 name 引用该工具的代码。）
3. 确认现有旧名称数组中没有条目被移除。
4. 如果工具在工具集之间移动，请确认旧的 toolSet/toolName 完整路径位于旧名称数组中。
5. 检查工具集成员列表（languageModelToolSets 贡献中的 tools 数组）。如果工具的 toolReferenceName 发生变化，任何引用旧名称的工具集 tools 数组都应更新——不过旧名称解析系统会处理此情况，因此旧名称仍可使用。

反面模式

• 更改扩展贡献的工具的 name 字段 — package.json 中的 name 会成为 IToolData 上的 id（通过 languageModelToolsContribution.ts 中的 id: rawTool.name）。更改它会破坏激活事件（onLanguageModelTool:<name>）、任何通过 id 引用该工具的代码，以及工具调用。只重命名 toolReferenceName，不要更改 name。（参见 vscode-copilot-chat#3810，其中 name 和 toolReferenceName 都被更改了。）
• 更改 TypeScript 注册工具的 id 字段 — 原则与上文相同。id 是稳定的内部标识符，绝不能更改。
• 假设旧名称已在 legacy 数组中 — 务必读取 legacyToolReferenceFullNames 的实际内容进行确认，而不只是检查该字段是否存在。legacy 数组可能列出了更早一次重命名的名称，却没有当前正在更改的名称。
• 从 legacy 数组中移除旧名称 — 这会导致现有的已保存提示词和用户配置无法正常工作。
• 完全忘记添加 legacy 名称 — 提示词文件和工具配置会悄无声息地无法解析。
• 只更新提示词解析，却不更新其他使用方 — 自动批准设置、工具启用映射以及单个工具检查（如 RunInTerminalTool）都需要支持 legacy 名称（参见 #278506）。