unity-mcp 中find_in_file工具详解用正则精准定位 Unity 项目文件内容【免费下载链接】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-mcp 仓库的官方工具参考文档 find_in_file.md 为主体骨架结合其底层实现 find_in_file.py、技能参考文档 tools-reference.md 与 workflows.md 展开。读完本文你将掌握find_in_file的完整参数语义、URI 寻址规则、返回数据结构、底层实现原理以及如何把它嵌入定位问题代码 → 安全编辑脚本 → 验证编译的 AI 自动化工作流。find_in_file是 unity-mcp 核心工具组coregroup中的一个只读检索工具作用是使用正则表达式在单个文件内搜索并返回匹配的行号与摘录内容。它是 AI 助手在 Unity 项目中做代码定位、问题诊断、脚本编辑前勘验的关键前置工具——在 apply_text_edits.md 的官方建议工作流中就明确要求先用find_in_file定位模式再进行精确坐标编辑。本文将从参数、返回值、URI 规则、实现原理到实战工作流逐层剖析这个工具。工具定位与注册信息在 unity-mcp 的 Python 服务端find_in_file定义于 find_in_file.py并通过mcp_for_unity_tool装饰器注册进 MCP 工具注册表GroupcoreModuleservices.tools.find_in_fileunity_targetmanage_script即该工具在 Unity 端最终路由到manage_script工具的read动作去读取文件内容ToolAnnotationsreadOnlyHintTrue、destructiveHintFalse、idempotentHintTrue、openWorldHintFalse——明确声明这是一个幂等、无副作用、只读的检索型工具AI 客户端可以放心安全地反复调用。在全局能力清单 manifest.json 中它的描述是 Search for content within Unity project files搜索 Unity 项目文件中的内容在测试文件 test_tool_annotations.py 中它也被列为具备 ToolAnnotations 注解的待检工具之一用于验证注解元数据的完整性。参数详解官方文档给出的参数表如下名称类型必填说明uristr是要搜索的资源 URI位于 Assets/ 下或read_resource支持的文件路径形式patternstr是要搜索的正则表达式project_rootstr \| None否可选的项目根路径max_resultsint否限制结果数量避免返回超大 payloadignore_casebool \| str \| None否是否忽略大小写从源码可以进一步确认每个参数的默认值与真实语义uri必填指定要读取并搜索的文件。实现上由_split_uri()负责把它解析成 Unity 端可用的(name, directory)二元组详见下文URI 寻址规则。pattern必填Pythonre语法正则。编译失败时例如括号不匹配、非法转义工具会返回{success: False, message: Invalid regex pattern: 错误详情}而不是抛出异常。project_root可选默认None源码注释明确说明 project_root is currently unused but kept for interface consistency即当前为保持接口一致性而保留尚未参与实际逻辑。调用时传不传都不会改变结果。max_results可选默认200结果上限。实现中当count max_results时立即break停止收集匹配项防止超大文件命中过多导致返回数据膨胀。注意被截断的是返回列表长度total_matches字段仍然统计全文真实命中总数。ignore_case可选默认True注意默认值是开启的。由于不同客户端可能以字符串形式传参实现做了类型兼容当传入字符串时按(true, 1, yes)小写比对转换为布尔值见 find_in_file.py。为True时在正则标志中加入re.IGNORECASE。URI 寻址规则四种输入形式如何归一化find_in_file的第一个参数uri支持多种寻址形式统一由私有函数_split_uri()处理find_in_file.py。理解这套规则才能在不同场景下正确传参mcpforunity://path/...形式去掉mcpforunity://path/前缀后保留 Assets 相对路径。例如mcpforunity://path/Assets/Scripts/MyScript.cs。file://形式做百分号解码unquote规范化路径。若 host 非空且不是localhost会按 UNC 风格补回//host/...前缀兼容网络共享路径。普通路径形式直接使用同样经过百分号解码与分隔符归一化\→/。Assets 段定位归一化后的路径中只要存在大小写不敏感的Assets段就截取从Assets开始的相对部分作为directory否则使用归一化后的完整路径。POSIX 绝对路径的开头/会被去掉转成相对风格如/tmp→tmp。Windows 盘符路径如/C:/...也会在 NT 系统上剥离前导斜杠。最终name 文件名去扩展名directory 剩余目录部分两者再交给 Unity 端的manage_scriptread动作读取文件内容。返回值结构工具返回标准的 Unity 响应字典。成功时结构为{ success: true, data: { matches: [ { line: 42, content: public void Update(), match: void Update, start: 1234, end: 1245 } ], count: 1, total_matches: 3 } }字段语义对应实现 find_in_file.pymatches结果数组最多max_results条。每条含五个字段line匹配起点所在行号1 起始通过统计从文件头到match.start()之间的换行符数量计算得出content匹配所在整行内容经过strip()去除首尾空白match正则实际命中的文本group(0)start/end匹配在整个文件内容中的字符偏移区间便于上层做精确的二次定位。count实际返回的匹配条数受max_results截断。total_matches全文真实命中总数不受截断影响用于让调用方判断是否还有更多结果没被返回。失败时返回形如{success: false, message: ...}的字典典型失败场景包括Unity 端读取文件失败直接透传read响应、文件内容为空、正则编译错误。底层实现原理从 URI 到命中行号find_in_file的执行链路可以拆成四步对应 find_in_file.py解析 URI 并读取文件_split_uri(uri)得到(name, directory)后通过send_with_unity_instance(async_send_command_with_retry, unity_instance, manage_script, {action: read, name: name, path: directory})把读取请求发往对应的 Unity 编辑器实例。其中unity_instance由get_unity_instance_from_context(ctx)从 MCP 上下文解析支持多实例路由未指定时使用默认实例。内容解码兜底正常路径读取data.contents如果内容为空但存在contentsEncoded与encodedContents则对 Base64 编码内容解码utf-8解码失败时用replace策略容错保证特殊编码文件也能被搜索。编译正则以re.MULTILINE为基准标志ignore_case为真时叠加re.IGNORECASE。因为要兼容跨行正则实现直接在整个文件内容上执行regex.finditer(contents)而不是逐行匹配。命中回溯映射对每个匹配用contents.count(\n, 0, start_idx) 1反推行号用rfind(\n, 0, start_idx) 1定位行首、find(\n, start_idx)定位行尾截取整行作为content摘录同时记录match与字符偏移区间。这一全量匹配 回溯映射的设计意味着pattern既可以是单行正则也可以是跨多行的复杂正则行号映射始终准确。实战用法示例技能参考 tools-reference.md 给出了最小可运行示例find_in_file( urimcpforunity://path/Assets/Scripts/MyScript.cs, patternpublic void \\w, # 正则模式 max_results200, ignore_caseTrue ) # 返回行号、内容摘录、匹配位置在此基础上结合参数语义可以衍生出几种典型调用忽略大小写查找方法定义ignore_case默认为True也可显式传入字符串yes或布尔False关闭find_in_file( urimcpforunity://path/Assets/Scripts/PlayerController.cs, patternrprivate\svoid\s\w, ignore_caseFalse )限流大文件搜索避免海量命中撑爆 payloadresult find_in_file( urimcpforunity://path/Assets/Generated/BigFile.cs, patternr//\s*TODO, max_results50, ignore_caseFalse ) if result[success]: print(f返回 {result[data][count]} 条全文共 {result[data][total_matches]} 处命中)URL 形式寻址read_resource同款路径形式同样被支持find_in_file( urifile:///data/UnityProjects/MyGame/Assets/Scripts/GameManager.cs, patternOnApplicationQuit )非法正则的容错处理result find_in_file( urimcpforunity://path/Assets/Scripts/MyScript.cs, pattern(unclosed # 括号未闭合 ) # result {success: False, message: Invalid regex pattern: missing ), unterminated subpattern ...}典型工作流集成工作流一安全编辑现有脚本官方推荐流程在 workflows.md 中find_in_file被嵌入定位 → 结构化编辑 → 校验的安全编辑链# 1. 获取当前脚本 SHA记录基线 sha_info get_sha(urimcpforunity://path/Assets/Scripts/PlayerController.cs) # 2. 用 find_in_file 定位要修改的方法 matches find_in_file( urimcpforunity://path/Assets/Scripts/PlayerController.cs, patternvoid Update\\(\\) ) # 3. 应用结构化编辑anchor 锚点替换比坐标编辑更安全 script_apply_edits( namePlayerController, pathAssets/Scripts, edits[{ op: replace_method, methodName: Update, replacement: void Update() { float h Input.GetAxis(Horizontal); float v Input.GetAxis(Vertical); transform.Translate(new Vector3(h, 0, v) * speed * Time.deltaTime); } }] ) # 4. 校验脚本 validate_script( urimcpforunity://path/Assets/Scripts/PlayerController.cs, levelstandard )同样地apply_text_edits.md 也把find_in_file列为精确坐标编辑apply_text_edits替换的是精确字符位置之前的必经勘验步骤先用read_resource或find_in_file确认目标行的真实内容再计算坐标下笔避免坐标错位导致误改。工作流二编译错误定位与修复workflows.md 给出了完整的调试闭环——先用read_console拉取错误再用find_in_file定位出错的源码位置修复后refresh_unity强制重编译验证# 1. 从控制台读取错误 errors read_console( types[error], count20, include_stacktraceTrue, formatdetailed ) # 2. 解析错误信息中的 file:line用 find_in_file 定位问题代码 for error in errors[messages]: # 用 find_in_file 定位错误对应的源码段 matches find_in_file( urifmcpforunity://path/{error_file}, patternerror_symbol ) # ... # 3. 修复后刷新并复查 refresh_unity(modeforce, scopescripts, compilerequest, wait_for_readyTrue) read_console(types[error], count10)这套控制台报错 → 精准定位 → 修复 → 重编译复查的闭环正是find_in_file在真实开发中的核心价值场景。使用注意与已知边界综合文档与源码使用时有以下几点需要注意默认忽略大小写ignore_case默认True对大小写敏感检索需显式传False。project_root暂未生效参数为接口一致性保留当前实现不消费它不要依赖它来切换搜索根。结果截断语义max_results只截断返回列表total_matches反映真实命中总数发现count total_matches时应考虑收紧pattern或增大上限。读取失败即返回失败若 Unity 端文件不存在或读取失败工具直接透传失败响应不会返回空匹配。内容解码兜底Base64 编码内容会在 UTF-8 解码失败时以replace容错极端编码下可能出现替换字符但不影响行号定位。只读、幂等作为带readOnlyHint与idempotentHint注解的工具它不会修改项目任何文件可安全地由 AI 在推理过程中多次调用、反复勘验。小结find_in_file是 unity-mcp 面向 Unity 项目文件提供的正则 行号 摘录三合一检索工具灵活的 URI 寻址mcpforunity://、file://、普通路径、Assets 相对定位、默认 200 条的结果截断、布尔/字符串双形态的忽略大小写参数以及包含行号、行内容、命中文本与字符偏移的丰富返回结构使它既是独立的问题定位利器也是读取 → 定位 → 编辑 → 校验安全脚本工作流中的关键枢纽。配合 tools-reference.md、workflows.md 以及 manifest.json 中的工具清单AI 助手即可在 Unity 项目中实现可靠的代码级自动化操作。【免费下载链接】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），仅供参考
unity-mcp 中 `find_in_file` 工具详解：用正则精准定位 Unity 项目文件内容
unity-mcp 中find_in_file工具详解用正则精准定位 Unity 项目文件内容【免费下载链接】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-mcp 仓库的官方工具参考文档 find_in_file.md 为主体骨架结合其底层实现 find_in_file.py、技能参考文档 tools-reference.md 与 workflows.md 展开。读完本文你将掌握find_in_file的完整参数语义、URI 寻址规则、返回数据结构、底层实现原理以及如何把它嵌入定位问题代码 → 安全编辑脚本 → 验证编译的 AI 自动化工作流。find_in_file是 unity-mcp 核心工具组coregroup中的一个只读检索工具作用是使用正则表达式在单个文件内搜索并返回匹配的行号与摘录内容。它是 AI 助手在 Unity 项目中做代码定位、问题诊断、脚本编辑前勘验的关键前置工具——在 apply_text_edits.md 的官方建议工作流中就明确要求先用find_in_file定位模式再进行精确坐标编辑。本文将从参数、返回值、URI 规则、实现原理到实战工作流逐层剖析这个工具。工具定位与注册信息在 unity-mcp 的 Python 服务端find_in_file定义于 find_in_file.py并通过mcp_for_unity_tool装饰器注册进 MCP 工具注册表GroupcoreModuleservices.tools.find_in_fileunity_targetmanage_script即该工具在 Unity 端最终路由到manage_script工具的read动作去读取文件内容ToolAnnotationsreadOnlyHintTrue、destructiveHintFalse、idempotentHintTrue、openWorldHintFalse——明确声明这是一个幂等、无副作用、只读的检索型工具AI 客户端可以放心安全地反复调用。在全局能力清单 manifest.json 中它的描述是 Search for content within Unity project files搜索 Unity 项目文件中的内容在测试文件 test_tool_annotations.py 中它也被列为具备 ToolAnnotations 注解的待检工具之一用于验证注解元数据的完整性。参数详解官方文档给出的参数表如下名称类型必填说明uristr是要搜索的资源 URI位于 Assets/ 下或read_resource支持的文件路径形式patternstr是要搜索的正则表达式project_rootstr \| None否可选的项目根路径max_resultsint否限制结果数量避免返回超大 payloadignore_casebool \| str \| None否是否忽略大小写从源码可以进一步确认每个参数的默认值与真实语义uri必填指定要读取并搜索的文件。实现上由_split_uri()负责把它解析成 Unity 端可用的(name, directory)二元组详见下文URI 寻址规则。pattern必填Pythonre语法正则。编译失败时例如括号不匹配、非法转义工具会返回{success: False, message: Invalid regex pattern: 错误详情}而不是抛出异常。project_root可选默认None源码注释明确说明 project_root is currently unused but kept for interface consistency即当前为保持接口一致性而保留尚未参与实际逻辑。调用时传不传都不会改变结果。max_results可选默认200结果上限。实现中当count max_results时立即break停止收集匹配项防止超大文件命中过多导致返回数据膨胀。注意被截断的是返回列表长度total_matches字段仍然统计全文真实命中总数。ignore_case可选默认True注意默认值是开启的。由于不同客户端可能以字符串形式传参实现做了类型兼容当传入字符串时按(true, 1, yes)小写比对转换为布尔值见 find_in_file.py。为True时在正则标志中加入re.IGNORECASE。URI 寻址规则四种输入形式如何归一化find_in_file的第一个参数uri支持多种寻址形式统一由私有函数_split_uri()处理find_in_file.py。理解这套规则才能在不同场景下正确传参mcpforunity://path/...形式去掉mcpforunity://path/前缀后保留 Assets 相对路径。例如mcpforunity://path/Assets/Scripts/MyScript.cs。file://形式做百分号解码unquote规范化路径。若 host 非空且不是localhost会按 UNC 风格补回//host/...前缀兼容网络共享路径。普通路径形式直接使用同样经过百分号解码与分隔符归一化\→/。Assets 段定位归一化后的路径中只要存在大小写不敏感的Assets段就截取从Assets开始的相对部分作为directory否则使用归一化后的完整路径。POSIX 绝对路径的开头/会被去掉转成相对风格如/tmp→tmp。Windows 盘符路径如/C:/...也会在 NT 系统上剥离前导斜杠。最终name 文件名去扩展名directory 剩余目录部分两者再交给 Unity 端的manage_scriptread动作读取文件内容。返回值结构工具返回标准的 Unity 响应字典。成功时结构为{ success: true, data: { matches: [ { line: 42, content: public void Update(), match: void Update, start: 1234, end: 1245 } ], count: 1, total_matches: 3 } }字段语义对应实现 find_in_file.pymatches结果数组最多max_results条。每条含五个字段line匹配起点所在行号1 起始通过统计从文件头到match.start()之间的换行符数量计算得出content匹配所在整行内容经过strip()去除首尾空白match正则实际命中的文本group(0)start/end匹配在整个文件内容中的字符偏移区间便于上层做精确的二次定位。count实际返回的匹配条数受max_results截断。total_matches全文真实命中总数不受截断影响用于让调用方判断是否还有更多结果没被返回。失败时返回形如{success: false, message: ...}的字典典型失败场景包括Unity 端读取文件失败直接透传read响应、文件内容为空、正则编译错误。底层实现原理从 URI 到命中行号find_in_file的执行链路可以拆成四步对应 find_in_file.py解析 URI 并读取文件_split_uri(uri)得到(name, directory)后通过send_with_unity_instance(async_send_command_with_retry, unity_instance, manage_script, {action: read, name: name, path: directory})把读取请求发往对应的 Unity 编辑器实例。其中unity_instance由get_unity_instance_from_context(ctx)从 MCP 上下文解析支持多实例路由未指定时使用默认实例。内容解码兜底正常路径读取data.contents如果内容为空但存在contentsEncoded与encodedContents则对 Base64 编码内容解码utf-8解码失败时用replace策略容错保证特殊编码文件也能被搜索。编译正则以re.MULTILINE为基准标志ignore_case为真时叠加re.IGNORECASE。因为要兼容跨行正则实现直接在整个文件内容上执行regex.finditer(contents)而不是逐行匹配。命中回溯映射对每个匹配用contents.count(\n, 0, start_idx) 1反推行号用rfind(\n, 0, start_idx) 1定位行首、find(\n, start_idx)定位行尾截取整行作为content摘录同时记录match与字符偏移区间。这一全量匹配 回溯映射的设计意味着pattern既可以是单行正则也可以是跨多行的复杂正则行号映射始终准确。实战用法示例技能参考 tools-reference.md 给出了最小可运行示例find_in_file( urimcpforunity://path/Assets/Scripts/MyScript.cs, patternpublic void \\w, # 正则模式 max_results200, ignore_caseTrue ) # 返回行号、内容摘录、匹配位置在此基础上结合参数语义可以衍生出几种典型调用忽略大小写查找方法定义ignore_case默认为True也可显式传入字符串yes或布尔False关闭find_in_file( urimcpforunity://path/Assets/Scripts/PlayerController.cs, patternrprivate\svoid\s\w, ignore_caseFalse )限流大文件搜索避免海量命中撑爆 payloadresult find_in_file( urimcpforunity://path/Assets/Generated/BigFile.cs, patternr//\s*TODO, max_results50, ignore_caseFalse ) if result[success]: print(f返回 {result[data][count]} 条全文共 {result[data][total_matches]} 处命中)URL 形式寻址read_resource同款路径形式同样被支持find_in_file( urifile:///data/UnityProjects/MyGame/Assets/Scripts/GameManager.cs, patternOnApplicationQuit )非法正则的容错处理result find_in_file( urimcpforunity://path/Assets/Scripts/MyScript.cs, pattern(unclosed # 括号未闭合 ) # result {success: False, message: Invalid regex pattern: missing ), unterminated subpattern ...}典型工作流集成工作流一安全编辑现有脚本官方推荐流程在 workflows.md 中find_in_file被嵌入定位 → 结构化编辑 → 校验的安全编辑链# 1. 获取当前脚本 SHA记录基线 sha_info get_sha(urimcpforunity://path/Assets/Scripts/PlayerController.cs) # 2. 用 find_in_file 定位要修改的方法 matches find_in_file( urimcpforunity://path/Assets/Scripts/PlayerController.cs, patternvoid Update\\(\\) ) # 3. 应用结构化编辑anchor 锚点替换比坐标编辑更安全 script_apply_edits( namePlayerController, pathAssets/Scripts, edits[{ op: replace_method, methodName: Update, replacement: void Update() { float h Input.GetAxis(Horizontal); float v Input.GetAxis(Vertical); transform.Translate(new Vector3(h, 0, v) * speed * Time.deltaTime); } }] ) # 4. 校验脚本 validate_script( urimcpforunity://path/Assets/Scripts/PlayerController.cs, levelstandard )同样地apply_text_edits.md 也把find_in_file列为精确坐标编辑apply_text_edits替换的是精确字符位置之前的必经勘验步骤先用read_resource或find_in_file确认目标行的真实内容再计算坐标下笔避免坐标错位导致误改。工作流二编译错误定位与修复workflows.md 给出了完整的调试闭环——先用read_console拉取错误再用find_in_file定位出错的源码位置修复后refresh_unity强制重编译验证# 1. 从控制台读取错误 errors read_console( types[error], count20, include_stacktraceTrue, formatdetailed ) # 2. 解析错误信息中的 file:line用 find_in_file 定位问题代码 for error in errors[messages]: # 用 find_in_file 定位错误对应的源码段 matches find_in_file( urifmcpforunity://path/{error_file}, patternerror_symbol ) # ... # 3. 修复后刷新并复查 refresh_unity(modeforce, scopescripts, compilerequest, wait_for_readyTrue) read_console(types[error], count10)这套控制台报错 → 精准定位 → 修复 → 重编译复查的闭环正是find_in_file在真实开发中的核心价值场景。使用注意与已知边界综合文档与源码使用时有以下几点需要注意默认忽略大小写ignore_case默认True对大小写敏感检索需显式传False。project_root暂未生效参数为接口一致性保留当前实现不消费它不要依赖它来切换搜索根。结果截断语义max_results只截断返回列表total_matches反映真实命中总数发现count total_matches时应考虑收紧pattern或增大上限。读取失败即返回失败若 Unity 端文件不存在或读取失败工具直接透传失败响应不会返回空匹配。内容解码兜底Base64 编码内容会在 UTF-8 解码失败时以replace容错极端编码下可能出现替换字符但不影响行号定位。只读、幂等作为带readOnlyHint与idempotentHint注解的工具它不会修改项目任何文件可安全地由 AI 在推理过程中多次调用、反复勘验。小结find_in_file是 unity-mcp 面向 Unity 项目文件提供的正则 行号 摘录三合一检索工具灵活的 URI 寻址mcpforunity://、file://、普通路径、Assets 相对定位、默认 200 条的结果截断、布尔/字符串双形态的忽略大小写参数以及包含行号、行内容、命中文本与字符偏移的丰富返回结构使它既是独立的问题定位利器也是读取 → 定位 → 编辑 → 校验安全脚本工作流中的关键枢纽。配合 tools-reference.md、workflows.md 以及 manifest.json 中的工具清单AI 助手即可在 Unity 项目中实现可靠的代码级自动化操作。【免费下载链接】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），仅供参考
