Unity MCP `delete_script` 工具详解：URI 解析、安全校验与脚本删除实现原理

Unity MCPdelete_script工具详解URI 解析、安全校验与脚本删除实现原理【免费下载链接】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-mcpdelete_script是 Unity MCP 中core工具组内负责删除 C# 脚本的核心工具它接受一条 URI 或 Assets 相对路径作为入参将对应.cs脚本移入 Unity 资源回收站。本文以该工具为准绳从参数契约、URI 解析规则、服务端调用链到 Unity 编辑器端的安全删除实现逐一展开帮助你理解在 AI 助手与 Unity 编辑器之间删除脚本的完整链路并能在自己的自动化工作流中正确使用这一破坏性工具。工具定位与基本信息delete_script属于core工具组后端模块为services.tools.manage_script。该工具的官方文档由 Python 工具注册表自动生成见 delete_script.md其中明确其功能为Delete a C# script by URI or Assets-relative path.在仓库的工具清单manifest中delete_script与create_script、validate_script、get_sha、apply_text_edits等同属于脚本生命周期管理工具族全部由 manage_script.py 这一模块对外暴露。参数契约delete_script的参数十分精简仅有一个必填项名称类型必填说明uristr是待删除脚本的 URI位于 Assets/ 目录下支持mcpforunity://path/Assets/...、file://...或直接Assets/...三种形式返回结构工具返回一个dict包含 Unity 侧的响应结果具体形状取决于操作是否成功成功时形如{success: true, message: Script deleted (verified after domain reload)., data: ...}失败时携带错误码例如目标不在Assets/下时返回{success: false, code: path_outside_assets, message: URI must resolve under Assets/.}。调用示例# mcpforunity:// 协议形式 delete_script(urimcpforunity://path/Assets/Scripts/MyScript.cs) # file:// 形式支持百分号编码如文件名含空格 delete_script(urifile:///Users/alex/Project/Assets/Scripts/Foo%20Bar.cs) # 直接 Assets 相对路径形式 delete_script(uriAssets/Scripts/Obsolete.cs)URI 解析从各种入参形式到 (name, directory)delete_script之所以能同时接受三种 URI 形式是因为服务端先调用了_split_uri辅助函数见 manage_script.py将入参统一规约为(name, directory)二元组再下发给 Unity。其解析规则如下mcpforunity://path/前缀直接剥离前缀剩余部分作为路径file://前缀用urlparse解析保留 UNC 主机file://server/share/...→//server/share/...对路径做百分号解码unquote再剥离主机与前导斜杠普通路径按原样处理。无论哪种形式后续都会统一执行再次unquote并规范化分隔符\→/仅对 Windows 盘符形态如/C:/...剥离前导斜杠os.path.normpath折叠../、./大小写不敏感地查找Assets段一旦命中就返回以该Assets为根目录的资产相对路径未命中则退回规范化后的原始路径并去掉 POSIX 前导/如/tmp→tmp最终用os.path.splitext取文件名主体作为name剩余部分作为directory。这一逻辑在 test_manage_script_uri.py 中有完整覆盖例如入参 uri解析出的 name解析出的 pathmcpforunity://path/Assets/Scripts/MyScript.csMyScriptAssets/Scriptsfile:///Users/alex/Project/Assets/Scripts/Foo%20Bar.csFoo BarAssets/Scriptsfile://localhost/Users/alex/Project/Assets/Hello.csHelloAssetsfile:///C:/Users/Alex/Proj/Assets/Scripts/Hello.csHelloAssets/Scriptsfile:///tmp/Other.cs在 Assets 之外Othertmp可以看到URI 中是否携带Assets段直接决定了路径是保留 Assets 相对语义还是退化为普通路径这也是理解delete_script行为边界的关键。服务端调用链与边界防护在 delete_script 的实现 中删除动作遵循如下流程通过get_unity_instance_from_context(ctx)解析当前目标 Unity 实例支持多实例路由调用_split_uri得到(name, directory)边界校验若directory为空或其首段不是assets不区分大小写直接返回path_outside_assets错误拒绝执行删除从源头杜绝删除 Assets 之外的任意文件构造{action: delete, name: name, path: directory}参数通过send_mutation下发到 Unity删除后的验证_verify_delete回调会在写入后含域重载场景再次以read动作确认目标脚本已不存在若确认成功则返回Script deleted (verified after domain reload).的最终结果。这与create_script的_verify_create验证逻辑互为镜像体现了写操作必验证的设计模式。值得说明的是send_mutation同时承担了 Unity 域重载Domain Reload后的恢复处理因此即便删除脚本触发了编辑器重新编译AI 助手仍能拿到准确的执行结果。Unity 编辑器端安全的资源回收站删除delete_script在 Unity 侧由 ManageScript.cs 承载通过HandleCommand将action delete路由到DeleteScript见 ManageScript.cs#L1212-L1243。其实现要点如下文件不存在保护目标.cs不存在时返回Script not found at .... Cannot delete.走回收站而非物理删除调用AssetDatabase.MoveAssetToTrash(relativePath)将脚本移入 Unity 的回收机制支持撤销undo避免误删后无法恢复同步刷新资源库成功后执行AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport)确保资源数据库与磁盘状态一致失败兜底若文件被锁定或占用导致移入回收站失败返回明确错误提示而不会静默失败。路径加固只允许删除 Assets 之下的脚本在执行删除动作前HandleCommand会调用TryResolveUnderAssets见 ManageScript.cs#L61-L120对目录做双重防护规范化并解析出磁盘全路径校验其必须以Application.dataPath即 Assets 根为前缀防止路径穿越逃逸到 Assets 之外符号链接ReparsePoint防护自目标目录向上逐级检查一旦发现任意祖先目录是符号链接/重解析点即拒绝操作防止通过 symlink 间接删除 Assets 外部文件。这两层防护与服务端 Python 的path_outside_assets校验形成前后端双保险是delete_script作为一个破坏性工具最重要的安全设计。工具声明中也通过ToolAnnotations(titleDelete Script, destructiveHintTrue)明确标记了破坏性语义让下游 AI 客户端在调用前能够感知风险。与同族脚本工具的协同delete_script并非孤立存在理解它在脚本管理工具族中的位置有助于设计自动化流程create_script在同一目录下创建脚本创建后同样有_verify_create域重载验证apply_text_edits按行列坐标精确修改脚本内容配合get_sha的 SHA256 前置条件防并发覆盖get_sha获取脚本 SHA256 与字节数用于编辑前校验validate_script对脚本做语法校验并返回诊断信息manage_script兼容路由create/read/delete的旧式路由器delete_script是其delete动作的推荐替代入口。一个典型的脚本替换工作流可以是read确认当前内容 →get_sha记录基线 →apply_text_edits精准修改或create_script新建→ 需要清理时用delete_script删除废弃文件全程都可被 AI 助手通过 MCP 协议自动驱动。使用建议与注意事项优先使用三种标准 URI 形式其中mcpforunity://path/Assets/...是官方推荐格式与 Unity 端get_sha等工具返回的uri字段保持一致可直接复用目标必须位于Assets/之下服务端与编辑器端各有独立校验任何绕过 Assets 的路径都会在两端之一被拒绝删除是移入回收站而非物理销毁误删可通过 Unity 的撤销/回收机制恢复但仍建议在批量删除前先read或get_sha留档注意域重载删除脚本可能触发编辑器重新编译服务端的send_mutation与_verify_delete已处理该场景响应中的验证消息可以视为删除已生效的可靠信号破坏性标注由于destructiveHintTrue调用前应充分确认目标脚本不再被其他组件引用避免留下悬挂引用导致编译错误。从 工具文档 到 Python 服务端实现再到 Unity 编辑器实现 与 URI 解析测试delete_script的完整链路体现了 Unity MCP 在AI 可控地操作 Unity 工程上的设计取舍对外提供简洁的单一参数接口对内则以资产相对路径解析、Assets 边界校验、符号链接防护和删除后验证为破坏性操作兜底。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考