改进策划Agent局部修改失败诊断

批量 patch_file 校验不再在首个失败处短路，逐项汇总未找到、多处匹配、重叠和无修改原因。

原文未找到时返回候选行号和可见化缩进，多处匹配时返回首次匹配行号，并控制错误详情规模。

明确报告本次未写入文件及可唯一匹配的其余 edit 数量，保留全部通过才原子写入的语义。

同步更新策划 Agent 工具描述与生产迁移权威文档，并补充批量失败诊断回归断言。

apps/ai-game-creator-shell/src-tauri/design-agent/tools.json

@@ -2,7 +2,7 @@
   {"type":"function","function":{"name":"get_workflow_status","description":"读取当前策划工作流状态，只返回阶段列表、当前阶段、已批准阶段和待审批阶段；不推进阶段、不提交审批、不修改文件。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
   {"type":"function","function":{"name":"list_resources","description":"列出固定资源的逻辑目录、资源 ID、标题和简介。资源是只读的随包文档；不要猜测物理路径。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
   {"type":"function","function":{"name":"read_resource","description":"读取一份固定资源文档全文。每次读取一个 resource_id；资源只读。读到未实现占位文档时由你自行判断和处理。","parameters":{"type":"object","properties":{"resource_id":{"type":"string"}},"required":["resource_id"],"additionalProperties":false}}},
-  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一，匹配失败、重复或范围重叠时不修改文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
+  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一。所有 edit 会一次性校验；任何失败都不修改文件，错误会列出各失败项及可唯一匹配的其余项。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"delete_path","description":"谨慎使用；永久删除工作区内的文件或目录；目录会连同全部内容递归删除，不备份。先确认目标及删除范围。path 使用相对路径，不能删除工作区根目录，也不能经过链接。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"list_dir","description":"列出工作目录内的文件和目录。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"read_file","description":"读取工作目录内的 UTF-8 文本文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},

apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs

@@ -321,15 +321,31 @@ pub(crate) fn execute_design_file_tool(
                 })
                 .collect::<Vec<_>>();
             let mut matches = Vec::new();
+            let mut edit_errors = Vec::new();
+            let mut valid_edits = 0;
             for (index, (old, new)) in normalized.iter().enumerate() {
+                if old == new {
+                    edit_errors.push(format!(
+                        "edits[{index}] new_text 与 old_text 相同，不会产生修改"
+                    ));
+                    continue;
+                }
                 let count = content.matches(old).count();
                 if count == 0 {
-                    return Err(format!("edits[{index}] 原文未找到：{display}"));
+                    edit_errors.push(format!(
+                        "edits[{index}] 原文未找到：{}{}",
+                        display,
+                        design_patch_location_hint(&content, old)
+                    ));
+                    continue;
                 }
                 if count != 1 {
-                    return Err(format!(
-                        "edits[{index}] 原文匹配 {count} 处，必须唯一：{display}"
+                    let start = content.find(old).expect("count checked");
+                    let line = design_patch_line_number(&content, start);
+                    edit_errors.push(format!(
+                        "edits[{index}] 原文匹配 {count} 处，必须唯一；首次位于第 {line} 行"
                     ));
+                    continue;
                 }
                 let start = content.find(old).expect("count checked");
                 let end = start + old.len();
@@ -337,13 +353,33 @@ pub(crate) fn execute_design_file_tool(
                     .iter()
                     .find(|(_, other_start, other_end)| start < *other_end && *other_start < end)
                 {
-                    return Err(format!(
-                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠：{display}"
+                    edit_errors.push(format!(
+                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠；请合并为一个 edit 或缩短 old_text"
                     ));
+                    continue;
                 }
                 matches.push((index, start, end));
+                valid_edits += 1;
                 let _ = new;
             }
+            if !edit_errors.is_empty() {
+                let shown = edit_errors.len().min(4);
+                let mut details = edit_errors[..shown].to_vec();
+                if shown < edit_errors.len() {
+                    details.push(format!(
+                        "另有 {} 个 edit 校验失败（详情省略）",
+                        edit_errors.len() - shown
+                    ));
+                }
+                if valid_edits > 0 {
+                    details.push(format!(
+                        "其余 {valid_edits} 个 edit 当前可唯一匹配；本次未写入文件"
+                    ));
+                } else {
+                    details.push("本次未写入文件".to_string());
+                }
+                return Err(details.join("\n"));
+            }
             let mut updated = content.clone();
             for (index, start, end) in matches.into_iter().rev() {
                 let (_, new) = &normalized[index];
@@ -396,6 +432,60 @@ pub(crate) fn execute_design_file_tool(
     }
 }
 
+fn design_patch_line_number(content: &str, start: usize) -> usize {
+    1 + content[..start]
+        .bytes()
+        .filter(|byte| *byte == b'\n')
+        .count()
+}
+
+fn design_patch_visible_line(line: &str) -> String {
+    line.replace('\t', "\\t").chars().take(180).collect()
+}
+
+fn design_patch_location_hint(content: &str, old: &str) -> String {
+    let Some(anchor) = old.lines().map(str::trim).find(|line| !line.is_empty()) else {
+        return String::new();
+    };
+
+    let mut candidates = content
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| line.trim() == anchor)
+        .map(|(index, line)| (index + 1, line))
+        .collect::<Vec<_>>();
+    if candidates.is_empty() {
+        let token = anchor.split_whitespace().find(|token| token.len() >= 3);
+        if let Some(token) = token {
+            candidates = content
+                .lines()
+                .enumerate()
+                .filter(|(_, line)| line.trim().contains(token))
+                .map(|(index, line)| (index + 1, line))
+                .collect();
+        }
+    }
+    if candidates.is_empty() {
+        return format!(
+            "；未找到与 old_text 首个非空行相似的行（当前文件约 {} 行）",
+            content.lines().count()
+        );
+    }
+
+    let details = candidates
+        .iter()
+        .take(2)
+        .map(|(line, text)| format!("第 {line} 行：{}", design_patch_visible_line(text)))
+        .collect::<Vec<_>>()
+        .join("；");
+    let suffix = if candidates.len() > 2 {
+        format!("等 {} 处", candidates.len())
+    } else {
+        String::new()
+    };
+    format!("；old_text 首个非空行可能对应 {details}{suffix}（tab 显示为 \\t）")
+}
+
 pub(crate) fn list_design_workspace_files(
     root: &Path,
 ) -> Result<Vec<DesignWorkspaceEntry>, String> {
@@ -693,6 +783,22 @@ mod tests {
         )
         .expect_err("escape");
         assert!(escaped.contains("路径"));
+        let mismatch = execute_design_file_tool(
+            root,
+            "patch_file",
+            &json!({
+                "path":"notes/design.md",
+                "edits":[
+                    {"old_text":"  游戏设计","new_text":"游戏概念"},
+                    {"old_text":"设计","new_text":"方案"}
+                ]
+            }),
+        )
+        .expect_err("report all patch failures");
+        assert!(mismatch.contains("edits[0] 原文未找到"));
+        assert!(mismatch.contains("第 1 行：游戏设计"));
+        assert!(mismatch.contains("其余 1 个 edit 当前可唯一匹配"));
+        assert!(mismatch.contains("本次未写入文件"));
         let patched = execute_design_file_tool(
             root,
             "patch_file",

docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md

@@ -152,7 +152,7 @@ get_workflow_status
 
 工具使用相对工作区路径。工具执行结果继续通过 Runtime 统一记录和展示，但不向 Agent 暴露宿主绝对路径。
 
-`patch_file` 保留原型按唯一原文匹配修改的语义、换行归一化和缺文件错误。正常工作区写入与删除不逐次请求用户审批；阶段审批不能被复用为文件操作许可。
+`patch_file` 保留原型按唯一原文匹配、范围不重叠、全部通过才原子写入的语义、换行归一化和缺文件错误。批量 edits 会一次性完成全部校验，并把未找到、多处匹配、重叠等失败项汇总返回；未找到时同时给出候选行号和可见化缩进提示，帮助 Provider 基于当前文件修正锚点。正常工作区写入与删除不逐次请求用户审批；阶段审批不能被复用为文件操作许可。
 
 `list_resources` 一次返回完整逻辑分类、资源 ID、标题和简介；`read_resource` 按一个资源 ID 读取一个文件。资源描述不增加 `required=true/false` 分类，也不增加引导同轮多次调用的说明。