From a69e0bc68f59fa867415dd1581c9644842f2f4ef Mon Sep 17 00:00:00 2001 From: Linghong Date: Thu, 27 Aug 2026 10:32:50 +0000 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20Provider=20=E4=BA=A4?= =?UTF-8?q?=E6=8E=A5=E5=A4=B1=E8=B4=A5=E6=9C=AC=E5=9C=B0=E8=AF=8A=E6=96=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 成功 handoff 失败时保存应用私有 Provider 响应诊断 在项目状态和 Agent DB 中记录本地诊断相对引用 补充 Runtime 技术方案与排障记录 增加私有诊断落盘和引用校验测试 --- .../runtime_protocol/provider_control.rs | 223 ++++++++++++++++++ .../agent/runtime_protocol/provider_retry.rs | 24 +- docs/project-memory/shared-memory/pitfalls.md | 6 + ...案】AI游戏创作Agent Runtime V1.1-2026-07-12.md | 2 + 4 files changed, 252 insertions(+), 3 deletions(-) diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_control.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_control.rs index 1e061353a..7d7ebc0f0 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_control.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_control.rs @@ -460,6 +460,148 @@ pub(in crate::agent) fn mark_game_creator_agent_runtime_provider_success_handoff ) } +const PROVIDER_RECONCILIATION_DIAGNOSTIC_RELATIVE_ROOT: &str = + "diagnostics/provider-reconciliation"; +const PROVIDER_RECONCILIATION_DIAGNOSTIC_MAX_BYTES: usize = 1024 * 1024; + +/// Persist the raw successful Provider response only in the application +/// private data directory. Project state keeps the safe summary below; this +/// sidecar is diagnostic-only and is never consulted by recovery/retry logic. +pub(in crate::agent) fn write_provider_reconciliation_diagnostic_at( + snapshot: &AgentRuntimeProviderRequestSnapshot, + request_id: &str, + response: &platform_llm::LlmRunResponse, + error: &str, +) -> Result { + let config_dir = game_creator_runtime_config_dir() + .ok_or_else(|| "Runtime config dir 未初始化，无法写入本地 Provider 诊断".to_string())?; + write_provider_reconciliation_diagnostic_in_dir( + &config_dir, + snapshot, + request_id, + response, + error, + ) +} + +fn write_provider_reconciliation_diagnostic_in_dir( + config_dir: &Path, + snapshot: &AgentRuntimeProviderRequestSnapshot, + request_id: &str, + response: &platform_llm::LlmRunResponse, + error: &str, +) -> Result { + let project_key = format!("{:x}", Sha256::digest(snapshot.project_id.as_bytes())); + let request_key = format!("{:x}", Sha256::digest(request_id.as_bytes())); + let directory = config_dir + .join(PROVIDER_RECONCILIATION_DIAGNOSTIC_RELATIVE_ROOT) + .join(&project_key); + fs::create_dir_all(&directory) + .map_err(|error| format!("创建本地 Provider 诊断目录失败：{error}"))?; + let relative_path = format!( + "{PROVIDER_RECONCILIATION_DIAGNOSTIC_RELATIVE_ROOT}/{project_key}/{request_key}.json" + ); + let path = directory.join(format!("{request_key}.json")); + if let Ok(metadata) = fs::symlink_metadata(&path) { + if metadata.file_type().is_symlink() || !metadata.is_file() { + return Err("本地 Provider 诊断目标必须是普通文件".to_string()); + } + return Ok(relative_path); + } + let diagnostic = serde_json::json!({ + "schemaVersion": "provider-reconciliation-diagnostic.v1", + "identity": { + "projectId": snapshot.project_id.clone(), + "agentId": snapshot.agent_id.clone(), + "taskId": snapshot.task_id.clone(), + "sessionId": snapshot.session_id.clone(), + "runId": snapshot.run_id.clone(), + "source": snapshot.source.clone(), + "requestKind": snapshot.request_kind.clone(), + "requestSlot": snapshot.request_slot.clone(), + "requestId": request_id, + "appliedSteerCursor": snapshot.applied_steer_cursor, + }, + "provider": { + "provider": format!("{:?}", response.provider), + "model": response.model.clone(), + "responseId": response.response_id.clone(), + "finishReason": response.finish_reason.clone(), + "usage": response.usage.clone(), + }, + "failure": { + "error": error, + }, + "response": { + "text": response.text.clone(), + "toolCalls": response.tool_calls.iter().map(|call| serde_json::json!({ + "id": call.id.clone(), + "name": call.name.clone(), + "arguments": call.arguments.clone(), + })).collect::>(), + }, + }); + let mut content = serde_json::to_string_pretty(&diagnostic) + .map_err(|error| format!("序列化本地 Provider 诊断失败：{error}"))?; + content.push('\n'); + if content.len() > PROVIDER_RECONCILIATION_DIAGNOSTIC_MAX_BYTES { + return Err(format!( + "本地 Provider 诊断超过 {PROVIDER_RECONCILIATION_DIAGNOSTIC_MAX_BYTES} 字节" + )); + } + let temporary = path.with_file_name(format!(".{request_key}.tmp.{}", unix_timestamp_nanos())); + let mut options = fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + let mut file = options + .open(&temporary) + .map_err(|error| format!("创建本地 Provider 诊断临时文件失败：{error}"))?; + if let Err(error) = file + .write_all(content.as_bytes()) + .and_then(|_| file.sync_data()) + { + let _ = fs::remove_file(&temporary); + return Err(format!("写入本地 Provider 诊断失败：{error}")); + } + drop(file); + if let Err(error) = fs::rename(&temporary, &path) { + let _ = fs::remove_file(&temporary); + return Err(format!("安装本地 Provider 诊断失败：{error}")); + } + Ok(relative_path) +} + +fn private_diagnostic_reference(error: &str) -> Option<&str> { + let reference = error.split_once("；localDiagnostic=")?.1.trim(); + let reference = reference.split('；').next()?.trim(); + if reference.starts_with(PROVIDER_RECONCILIATION_DIAGNOSTIC_RELATIVE_ROOT) + && reference + .chars() + .all(|character| character.is_ascii_alphanumeric() || "/.-_".contains(character)) + { + Some(reference) + } else { + None + } +} + +fn attach_private_diagnostic_reference( + mut audit: serde_json::Value, + reference: Option, +) -> serde_json::Value { + if let (Some(reference), Some(audit)) = (reference, audit.as_object_mut()) { + audit.insert( + "localDiagnostic".to_string(), + serde_json::Value::String(reference), + ); + } + audit +} + #[cfg(test)] pub(crate) fn mark_game_creator_agent_runtime_provider_success_handoff_needs_reconciliation_for_test( root: &Path, @@ -505,6 +647,8 @@ fn mark_game_creator_agent_runtime_provider_request_needs_reconciliation_with_di { return Err("孤立 Provider 请求与当前 Runtime 身份冲突".to_string()); } + let private_reference = + diagnostic.and_then(|(_, error)| private_diagnostic_reference(error).map(str::to_string)); let diagnostic = diagnostic.map(|(failure_kind, error)| { ( failure_kind, @@ -544,6 +688,11 @@ fn mark_game_creator_agent_runtime_provider_request_needs_reconciliation_with_di detail }) .unwrap_or_else(|| format!("requestId={request_id}")); + let public_detail = if let Some(reference) = private_reference.as_deref() { + format!("{public_detail} · localDiagnostic={reference}") + } else { + public_detail + }; let event_detail = diagnostic .is_some() .then_some(public_detail.as_str()) @@ -625,6 +774,7 @@ fn mark_game_creator_agent_runtime_provider_request_needs_reconciliation_with_di "requestSlot": snapshot.request_slot, }) }; + let audit = attach_private_diagnostic_reference(audit, private_reference); let _ = append_agent_db_record(root, audit); emit_game_creator_agent_runtime_update(root, &snapshot.agent_id); Ok(()) @@ -676,3 +826,76 @@ where ) .await } + +#[cfg(test)] +mod provider_reconciliation_diagnostic_tests { + use super::*; + + #[test] + fn private_diagnostic_keeps_raw_response_outside_project_state() { + let directory = tempfile::tempdir().expect("diagnostic directory"); + let snapshot = AgentRuntimeProviderRequestSnapshot { + project_id: "project-1".to_string(), + agent_id: "project-planning".to_string(), + task_id: "task-1".to_string(), + session_id: "session-1".to_string(), + run_id: "run-1".to_string(), + source: "agent-delegate".to_string(), + goal_id: None, + goal_revision: 0, + goal_snapshot_fingerprint: String::new(), + applied_steer_cursor: 0, + request_kind: "tool-plan".to_string(), + request_slot: "loop-1-repair-0".to_string(), + web_search_enabled: false, + allow_idle_context_compaction: false, + planning_session_binding: None, + }; + let response = platform_llm::LlmRunResponse { + provider: platform_llm::LlmProvider::OpenAiCompatible, + model: "test-model".to_string(), + text: "C:\\private\\response".to_string(), + finish_reason: Some("completed".to_string()), + response_id: Some("response-1".to_string()), + usage: None, + tool_calls: vec![platform_llm::LlmToolCall { + id: "call-1".to_string(), + name: "runtime_tool_plan_submit_gdd".to_string(), + arguments: "{\"path\":\"C:\\\\private\\\\argument\"}".to_string(), + }], + }; + let relative = write_provider_reconciliation_diagnostic_in_dir( + directory.path(), + &snapshot, + "provider-request-1", + &response, + "绝对路径 C:\\private\\error", + ) + .expect("write diagnostic"); + assert!(relative.starts_with("diagnostics/provider-reconciliation/")); + let persisted = + fs::read_to_string(directory.path().join(&relative)).expect("read diagnostic"); + let persisted: serde_json::Value = + serde_json::from_str(&persisted).expect("parse diagnostic"); + assert_eq!(persisted["response"]["text"], "C:\\private\\response"); + assert_eq!( + persisted["response"]["toolCalls"][0]["arguments"], + "{\"path\":\"C:\\\\private\\\\argument\"}" + ); + assert_eq!(persisted["failure"]["error"], "绝对路径 C:\\private\\error"); + } + + #[test] + fn private_diagnostic_reference_accepts_only_relative_reference() { + assert_eq!( + private_diagnostic_reference( + "失败；localDiagnostic=diagnostics/provider-reconciliation/p/r.json" + ), + Some("diagnostics/provider-reconciliation/p/r.json") + ); + assert_eq!( + private_diagnostic_reference("失败；localDiagnostic=C:\\secret.json"), + None + ); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_retry.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_retry.rs index 92a6d3926..d33035874 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_retry.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_retry.rs @@ -1409,7 +1409,7 @@ where attempt_snapshot.clone(), provider_request, |provider_request_id, response| { - if persist_handoff { + let handoff_result = if persist_handoff { let response = canonicalize_handoff_response(response); provider_handoff::write_at( root, @@ -1418,7 +1418,8 @@ where attempt, provider_request_id, &response, - )?; + ) + .map(|_| ()) } else if persist_tool_plan_handoff { tool_plan_handoff::write_at( root, @@ -1427,7 +1428,24 @@ where attempt, provider_request_id, response, - )?; + ) + .map(|_| ()) + } else { + Ok(()) + }; + if let Err(error) = handoff_result { + let error = match write_provider_reconciliation_diagnostic_at( + &attempt_snapshot, + provider_request_id, + response, + &error, + ) { + Ok(path) => format!("{error}；localDiagnostic={path}"), + Err(diagnostic_error) => { + format!("{error}；localDiagnosticWriteFailed={diagnostic_error}") + } + }; + return Err(error); } Ok(()) }, diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 1a56fe8e1..07eb4b5c1 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -1,5 +1,11 @@ # 踩坑与排障记录 +## 2026-08-27 Provider 成功 handoff 失败时需要保留本地私有原始响应 + +- **现象**：Provider 已返回响应，但 tool-plan handoff 因绝对路径或其它内容安全校验失败，Runtime 只留下 `failureKind`、哈希和被压平的 JSON pointer；排障时无法确认实际工具名和完整 arguments。 +- **处理**：项目 `.agent`、Agent DB 和公共 event 继续只写安全摘要；额外在应用私有配置目录的 `diagnostics/provider-reconciliation//.json` 保存本次响应、tool calls 和校验错误，供本机人工排障。该文件不参与恢复/重试、不复制到项目、不进入 Git，单文件限制 1 MiB，写入失败不改变 reconciliation 语义。 +- **排查顺序**：先读 Runtime 状态里的 `localDiagnostic` 相对引用，再在应用私有目录读取诊断，核对 requestId、requestSlot、tool name 和失败 pointer；不要为了取得原文而放宽 handoff 的安全门。 + ## 2026-08-27 阶段判定不能在持锁的 Provider builder 中再次获取项目锁 - **现象**：GDD 修订取证阶段新增后，重新启动策划时前两步表面成功，但父 Supervisor 在收到 `project-planning` 回执、生成下一轮工具计划时失败：`项目正在被其他写操作占用：$PROJECT_ROOT\\.agent\\project.lock`。 diff --git a/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md b/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md index d8d1bd9fd..6f1cd2e10 100644 --- a/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md +++ b/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md @@ -1480,6 +1480,8 @@ npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-final-reply-transie V1.43 不放宽 V1.41 的文本型 `game-creator-provider-handoff.v1`，而是为 `requestKind=tool-plan` 增加独立私有账本 `.agent/runtime/tool-plan-handoffs//.json`，schema 固定为 `game-creator-tool-plan-handoff.v1`。同一 Agent/run 账本按 `(loopIteration, repairAttempt)` 单调保存已成功的 `repair-0..N` Provider 响应，每条绑定完整 retry identity、实际物理 `providerRequestId`、真实 request slot/attempt、Provider/model、去除 thinking 后的响应、thinking 归一化哈希/计数、完整 function call envelope、usage、响应指纹和创建时间。账本使用既有 `0600`、原子替换、父目录同步、`.previous` 恢复和写后完整回读；未知字段、乱序/缺口、重复 slot 冲突、超限、危险可执行路径、密钥或配置痕迹一律失败关闭。 +当成功响应因 handoff 校验失败而进入 `needs-reconciliation` 时，Runtime 额外在应用私有数据目录的 `diagnostics/provider-reconciliation//.json` 写入一次本地诊断。该诊断只服务人工排障，不参与恢复、重试或业务状态判断，可保留本次 Provider 响应、tool call arguments 和原始校验错误；项目 `.agent`、Agent DB、公共 event、CLI 与报告只保留安全摘要及该私有诊断的相对引用。诊断文件限制为 1 MiB，使用原子写入；应用配置目录不可用或诊断写入失败时，不改变既有 fail-closed reconciliation 语义。 + ### 提交、重放与所有权 - 每个 tool-plan 物理请求的顺序固定为：Provider 成功 -> tool-plan handoff 追加并回读 -> 同一实际 requestId lifecycle `completed` -> 解析/格式修复或动作预检。function arguments 只存在于私有 handoff 与后续 pending/action batch。protocol/repair 公共审计共同保存 `agentId/taskId/sessionId/runId/source/loopIteration/repairAttempt/requestSlot/responseFingerprint/providerRequestIdSha256/protocol`；protocol 只额外保存 `functionCallCount/callIdSha256s/functionNames/responseIdSha256/responseIdChars` 和既有 normalization 字段，其中 function names 必须由 catalog 绑定；repair 只额外保存 attempt/maxAttempts、协议错误/preview 哈希与字符数及 `callIdSha256/functionNameSha256`。公共 task、event、Agent DB、CLI 和报告不得保存原始 callId/callIds/responseId/providerRequestId。两类审计都在 Agent DB append 锁内按完整 Agent/task/Session/run/source/slot 身份做全历史 compare-and-append，不能以受限尾部读取替代幂等。