From d150f77301a3328873d21bb9a22fcbc50825cbbc Mon Sep 17 00:00:00 2001 From: AIGameCreator App Date: Fri, 10 Jul 2026 08:33:05 +0800 Subject: [PATCH] =?UTF-8?q?=E5=85=81=E8=AE=B8Agent=E6=81=A2=E5=A4=8D?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=BF=AB=E7=85=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 后台 Runtime 工具箱新增 project.restore Agent 可按权限策略请求恢复到指定 checkpoint 补充恢复成功和确认阻断测试 同步 Runtime V1 文档和项目记忆 --- .../src-tauri/src/agent.rs | 52 ++++- .../src-tauri/src/tests.rs | 184 ++++++++++++++++++ .../shared-memory/decision-log.md | 1 + ...案】AI游戏创作智能体App实施计划-2026-06-24.md | 6 +- 4 files changed, 239 insertions(+), 4 deletions(-) diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent.rs b/apps/ai-game-creator-shell/src-tauri/src/agent.rs index 62d081ab3..7f7a72e14 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent.rs @@ -1627,7 +1627,7 @@ fn build_game_creator_agent_background_tool_plan_request( let tool_policy_json = serde_json::to_string_pretty(&tool_policy) .map_err(|error| format!("序列化 Agent 工具策略失败：{error}"))?; let prompt = format!( - "当前工具策略：\n{tool_policy_json}\n\n项目上下文如下。你正在执行后台 Agent loop 第 {loop_index} 轮。请基于目标、已有工具观察和当前上下文修正计划，再决定是否调用最多 {AGENT_RUNTIME_BACKGROUND_TOOL_ACTION_LIMIT} 个白名单工具。只输出 JSON 对象，不要 markdown。\n\n{context}\n\n后台任务：\n{task}\n\n已有工具观察：\n{observations_json}\n\nJSON schema：{{\"thinkingSummary\":\"一句话理解\",\"plan\":[\"步骤\"],\"actions\":[{{\"tool\":\"memory.read|memory.write|conversation.read|asset.list|project.index|project.checkpoint|project.diff|file.list|file.read|file.write|task.list|task.create|task.update|command.run_limited|preview.start|canvas.asset_generate|blackboard.write|agent.message|agent.delegate|agent.schedule_ready|agent.run_status\",\"reason\":\"为什么需要\",\"input\":{{}}}}],\"response\":\"如果无需继续调用工具，可直接给最终回复\"}}\n\n工具输入约定：memory.read 使用 {{\"scope\":\"session|project|blackboard|agent\"}}；memory.write 使用 {{\"scope\":\"agent|project|session|blackboard\",\"title\":\"标题\",\"content\":\"要沉淀的稳定结论\",\"mode\":\"append|overwrite\"}}，其中 agent scope 只能写当前 Agent 自己的私有记忆，跨 Agent 共享请用 blackboard.write 或 agent.message；project.checkpoint input 可为空，用于在写文件或批量修改前创建本地 checkpoint；project.diff 使用 {{\"checkpointId\":\"checkpoint id\"}}，用于读取当前项目相对路径 diff 摘要；file.list 使用 {{\"path\":\"可选项目内相对目录或文件\"}}，path 为空时列出项目摘要；file.read 使用 {{\"path\":\"项目内相对路径\"}}；file.write 使用 {{\"path\":\"项目内相对路径\",\"content\":\"文件内容\"}}；task.list input 可为空，用于读取 manifest 任务图、状态和 readyTaskIds；task.create 使用 {{\"taskId\":\"可选自定义 taskId\",\"title\":\"任务标题\",\"group\":\"design|art|code|balance|audio|publishing\",\"role\":\"角色名\",\"dependencies\":[\"已有 taskId\"],\"artifacts\":[\"预期产物\"],\"acceptanceCriteria\":[\"验收标准\"],\"status\":\"pending|running|waiting-for-confirmation|completed|failed\"}}，用于把 Agent 拆出的新任务追加到 manifest；task.update 使用 {{\"taskId\":\"manifest taskId\",\"status\":\"pending|running|waiting-for-confirmation|completed|failed\"}}；command.run_limited 使用 {{\"commandId\":\"game.static_smoke\"}}，只支持本地静态自检；preview.start input 可为空，用于启动当前项目的 127.0.0.1 本地 HTTP 预览；canvas.asset_generate 使用 {{\"prompt\":\"要生成的美术素材描述\"}}，通过配置的 External Editor API 生成首版素材并登记到 assets；blackboard.write 使用 {{\"title\":\"标题\",\"content\":\"要共享给所有 Agent 的稳定结论\"}}；agent.message 使用 {{\"agentId\":\"目标 taskId\",\"content\":\"给目标 Agent 的定向消息\"}}；agent.delegate 使用 {{\"agentId\":\"目标 taskId\",\"task\":\"要委派的后台任务\",\"runId\":\"可选 run id\"}}，用于把任务投递到另一个 Agent 的独立队列；agent.schedule_ready input 可为空或 {{\"limit\":1}}，用于把 manifest 中依赖已完成的 ready task 投递到对应 Agent 后台队列；agent.run_status 使用 {{\"agentId\":\"可选目标 taskId\",\"scope\":\"self|all\"}}，用于读取自己或其他 Agent 的 Runtime 状态摘要；如果已有观察足够，请返回空 actions 并填写 response。其他工具 input 可为空。" + "当前工具策略：\n{tool_policy_json}\n\n项目上下文如下。你正在执行后台 Agent loop 第 {loop_index} 轮。请基于目标、已有工具观察和当前上下文修正计划，再决定是否调用最多 {AGENT_RUNTIME_BACKGROUND_TOOL_ACTION_LIMIT} 个白名单工具。只输出 JSON 对象，不要 markdown。\n\n{context}\n\n后台任务：\n{task}\n\n已有工具观察：\n{observations_json}\n\nJSON schema：{{\"thinkingSummary\":\"一句话理解\",\"plan\":[\"步骤\"],\"actions\":[{{\"tool\":\"memory.read|memory.write|conversation.read|asset.list|project.index|project.checkpoint|project.restore|project.diff|file.list|file.read|file.write|task.list|task.create|task.update|command.run_limited|preview.start|canvas.asset_generate|blackboard.write|agent.message|agent.delegate|agent.schedule_ready|agent.run_status\",\"reason\":\"为什么需要\",\"input\":{{}}}}],\"response\":\"如果无需继续调用工具，可直接给最终回复\"}}\n\n工具输入约定：memory.read 使用 {{\"scope\":\"session|project|blackboard|agent\"}}；memory.write 使用 {{\"scope\":\"agent|project|session|blackboard\",\"title\":\"标题\",\"content\":\"要沉淀的稳定结论\",\"mode\":\"append|overwrite\"}}，其中 agent scope 只能写当前 Agent 自己的私有记忆，跨 Agent 共享请用 blackboard.write 或 agent.message；project.checkpoint input 可为空，用于在写文件或批量修改前创建本地 checkpoint；project.restore 使用 {{\"checkpointId\":\"checkpoint id\"}}，用于在确认后把当前项目恢复到指定 checkpoint；project.diff 使用 {{\"checkpointId\":\"checkpoint id\"}}，用于读取当前项目相对路径 diff 摘要；file.list 使用 {{\"path\":\"可选项目内相对目录或文件\"}}，path 为空时列出项目摘要；file.read 使用 {{\"path\":\"项目内相对路径\"}}；file.write 使用 {{\"path\":\"项目内相对路径\",\"content\":\"文件内容\"}}；task.list input 可为空，用于读取 manifest 任务图、状态和 readyTaskIds；task.create 使用 {{\"taskId\":\"可选自定义 taskId\",\"title\":\"任务标题\",\"group\":\"design|art|code|balance|audio|publishing\",\"role\":\"角色名\",\"dependencies\":[\"已有 taskId\"],\"artifacts\":[\"预期产物\"],\"acceptanceCriteria\":[\"验收标准\"],\"status\":\"pending|running|waiting-for-confirmation|completed|failed\"}}，用于把 Agent 拆出的新任务追加到 manifest；task.update 使用 {{\"taskId\":\"manifest taskId\",\"status\":\"pending|running|waiting-for-confirmation|completed|failed\"}}；command.run_limited 使用 {{\"commandId\":\"game.static_smoke\"}}，只支持本地静态自检；preview.start input 可为空，用于启动当前项目的 127.0.0.1 本地 HTTP 预览；canvas.asset_generate 使用 {{\"prompt\":\"要生成的美术素材描述\"}}，通过配置的 External Editor API 生成首版素材并登记到 assets；blackboard.write 使用 {{\"title\":\"标题\",\"content\":\"要共享给所有 Agent 的稳定结论\"}}；agent.message 使用 {{\"agentId\":\"目标 taskId\",\"content\":\"给目标 Agent 的定向消息\"}}；agent.delegate 使用 {{\"agentId\":\"目标 taskId\",\"task\":\"要委派的后台任务\",\"runId\":\"可选 run id\"}}，用于把任务投递到另一个 Agent 的独立队列；agent.schedule_ready input 可为空或 {{\"limit\":1}}，用于把 manifest 中依赖已完成的 ready task 投递到对应 Agent 后台队列；agent.run_status 使用 {{\"agentId\":\"可选目标 taskId\",\"scope\":\"self|all\"}}，用于读取自己或其他 Agent 的 Runtime 状态摘要；如果已有观察足够，请返回空 actions 并填写 response。其他工具 input 可为空。" ); let request = LlmRunRequest::new(vec![ LlmMessage::system(game_creator_agent_runtime_tool_plan_system_prompt()), @@ -1734,6 +1734,7 @@ pub(crate) async fn execute_game_creator_agent_runtime_tool_action( "asset.list" => observe_agent_runtime_assets(root), "project.index" => observe_agent_runtime_project_index(root), "project.checkpoint" => observe_agent_runtime_project_checkpoint(root), + "project.restore" => observe_agent_runtime_project_restore(root, &action.input), "project.diff" => observe_agent_runtime_project_diff(root, &action.input), "file.list" => observe_agent_runtime_file_list(root, &action.input), "file.read" => observe_agent_runtime_file(root, &action.input), @@ -1771,6 +1772,7 @@ fn game_creator_agent_runtime_tool_command_id(tool: &str) -> Option<&'static str "asset.list" => Some("asset.list"), "project.index" => Some("project.index"), "project.checkpoint" => Some("project.checkpoint"), + "project.restore" => Some("project.restore"), "project.diff" => Some("project.diff"), "file.list" => Some("file.list"), "file.read" => Some("file.read"), @@ -1893,6 +1895,7 @@ fn agent_runtime_executable_tools() -> Vec<&'static str> { "asset.list", "project.index", "project.checkpoint", + "project.restore", "project.diff", "file.list", "file.read", @@ -2299,6 +2302,50 @@ fn observe_agent_runtime_project_checkpoint(root: &Path) -> AgentRuntimeToolObse } } +fn observe_agent_runtime_project_restore( + root: &Path, + input: &serde_json::Value, +) -> AgentRuntimeToolObservation { + let checkpoint_id = + agent_runtime_tool_input_text(input, &["checkpointId", "checkpoint_id", "id"]); + if checkpoint_id.trim().is_empty() { + return AgentRuntimeToolObservation { + tool: "project.restore".to_string(), + status: "failed".to_string(), + summary: "缺少 checkpointId".to_string(), + detail: None, + }; + } + let _lock = match acquire_project_write_lock(root, "project.restore") { + Ok(lock) => lock, + Err(error) => { + return AgentRuntimeToolObservation { + tool: "project.restore".to_string(), + status: "failed".to_string(), + summary: redact_agent_runtime_project_paths(root, &error, 240), + detail: None, + }; + } + }; + match restore_local_project_checkpoint_at(root, &checkpoint_id) { + Ok(result) => AgentRuntimeToolObservation { + tool: "project.restore".to_string(), + status: "ok".to_string(), + summary: format!("已恢复 checkpoint {}", result.checkpoint_id), + detail: Some(format!( + "checkpointId={} · restoredCount={} · deletedCount={}", + result.checkpoint_id, result.restored_count, result.deleted_count + )), + }, + Err(error) => AgentRuntimeToolObservation { + tool: "project.restore".to_string(), + status: "failed".to_string(), + summary: redact_agent_runtime_project_paths(root, &error, 240), + detail: None, + }, + } +} + fn observe_agent_runtime_project_diff( root: &Path, input: &serde_json::Value, @@ -3891,6 +3938,7 @@ fn default_game_creator_agent_runtime_allowed_tools() -> Vec { "agent.schedule_ready", "asset.list", "project.checkpoint", + "project.restore", "project.diff", "file.list", "file.read", @@ -5123,7 +5171,7 @@ pub(crate) fn game_creator_role_agent_chat_system_prompt() -> &'static str { } pub(crate) fn game_creator_agent_runtime_tool_plan_system_prompt() -> &'static str { - "你是 Genarrative AI 游戏创作多智能体 Runtime 中的专业 Agent。你必须在白名单工具内规划行动：先给一句 thinkingSummary，再给短计划，再决定是否请求工具。只能请求 memory.read、memory.write、conversation.read、asset.list、project.index、project.checkpoint、project.diff、file.list、file.read、file.write、task.list、task.create、task.update、command.run_limited、preview.start、canvas.asset_generate、blackboard.write、agent.message、agent.delegate、agent.schedule_ready、agent.run_status。Agent 私有记忆只能由本人写入，跨 Agent 共享稳定结论用 blackboard.write，给单个 Agent 留上下文用 agent.message。不要假装工具已执行；工具结果会由 Runtime 作为 observation 返回。只输出 JSON 对象，不要 markdown，不要泄露密钥。" + "你是 Genarrative AI 游戏创作多智能体 Runtime 中的专业 Agent。你必须在白名单工具内规划行动：先给一句 thinkingSummary，再给短计划，再决定是否请求工具。只能请求 memory.read、memory.write、conversation.read、asset.list、project.index、project.checkpoint、project.restore、project.diff、file.list、file.read、file.write、task.list、task.create、task.update、command.run_limited、preview.start、canvas.asset_generate、blackboard.write、agent.message、agent.delegate、agent.schedule_ready、agent.run_status。Agent 私有记忆只能由本人写入，跨 Agent 共享稳定结论用 blackboard.write，给单个 Agent 留上下文用 agent.message。不要假装工具已执行；工具结果会由 Runtime 作为 observation 返回。只输出 JSON 对象，不要 markdown，不要泄露密钥。" } pub(crate) fn game_creator_agent_role_definition( diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests.rs b/apps/ai-game-creator-shell/src-tauri/src/tests.rs index 69900bc94..4d17ad882 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests.rs @@ -5543,6 +5543,190 @@ async fn background_agent_runtime_project_diff_respects_project_policy() { fs::remove_dir_all(root).ok(); } +#[tokio::test] +async fn background_agent_runtime_can_restore_checkpoint() { + let root = unique_project_path(); + init_local_game_project_at(&root, "project-1", "月光厨房").expect("project init"); + write_local_project_file_at(&root, "game/notes.txt", "v1").expect("write notes"); + let checkpoint = create_local_project_checkpoint_at(&root).expect("create checkpoint"); + write_local_project_file_at(&root, "game/notes.txt", "v2").expect("change notes"); + write_local_project_file_at(&root, "game/temp.txt", "temp").expect("add temp file"); + write_project_permission_policy_at( + &root, + ProjectPermissionPolicy { + denied_commands: Vec::new(), + confirm_commands: Vec::new(), + agent_policies: BTreeMap::new(), + }, + ) + .expect("allow project restore"); + + let (sender, receiver) = mpsc::channel(); + let plan_json = serde_json::json!({ + "thinkingSummary": "本轮修改需要回滚到 checkpoint", + "plan": ["恢复 checkpoint", "确认恢复结果"], + "actions": [ + { + "tool": "project.restore", + "reason": "撤销本轮偏离目标的文件修改", + "input": { "checkpointId": checkpoint.checkpoint_id } + } + ], + "response": "" + }) + .to_string(); + let base_url = spawn_mock_llm_server_responses_with_capture( + vec![plan_json, "checkpoint 已恢复。".to_string()], + Some(sender), + ); + let _config_guard = write_test_local_config(format!( + r#"{{ + "agentLlm": {{ + "design-director": {{ + "apiKey": "design-key", + "baseUrl": {base_url:?}, + "model": "design-runtime-model", + "apiKind": "openai_responses" + }} + }} +}}"# + )); + + start_game_creator_agent_background_task_at( + &root, + "design-director", + "后台恢复到安全 checkpoint", + "design-project-restore-run", + ) + .expect("start background task"); + + let plan_request = receiver + .recv_timeout(Duration::from_secs(2)) + .expect("plan llm request"); + assert!(plan_request.contains("project.restore")); + assert!(plan_request.contains("checkpointId")); + let final_request = receiver + .recv_timeout(Duration::from_secs(2)) + .expect("final reply llm request"); + assert!(final_request.contains("project.restore")); + assert!(final_request.contains("已恢复 checkpoint")); + assert!(final_request.contains("restoredCount=")); + assert!(final_request.contains("deletedCount=1")); + + let runtime = wait_for_agent_runtime_idle(&root, "design-director"); + assert_eq!(runtime.status, "idle"); + assert!(runtime + .tool_policy + .auto_tools + .contains(&"project.restore".to_string())); + assert!(runtime + .observations + .iter() + .any(|item| item.contains("project.restore：ok · 已恢复 checkpoint"))); + assert!(runtime.recent_tool_calls.iter().any(|call| { + call.tool == "project.restore" + && call.status == "ok" + && call + .detail + .as_deref() + .is_some_and(|detail| detail.contains("deletedCount=1")) + })); + assert_eq!( + fs::read_to_string(root.join("game/notes.txt")).expect("restored notes"), + "v1" + ); + assert!(!root.join("game/temp.txt").exists()); + let agent_db = fs::read_to_string(root.join(".agent/agent.db")).expect("agent db"); + assert!(agent_db.contains("\"recordType\":\"project.restore\"")); + assert!(agent_db.contains("\"tool\":\"project.restore\"")); + + fs::remove_dir_all(root).ok(); +} + +#[tokio::test] +async fn background_agent_runtime_project_restore_respects_project_policy() { + let root = unique_project_path(); + init_local_game_project_at(&root, "project-1", "月光厨房").expect("project init"); + write_local_project_file_at(&root, "game/blocked-notes.txt", "v1").expect("write notes"); + let checkpoint = create_local_project_checkpoint_at(&root).expect("create checkpoint"); + write_local_project_file_at(&root, "game/blocked-notes.txt", "v2").expect("change notes"); + write_project_permission_policy_at( + &root, + ProjectPermissionPolicy { + denied_commands: Vec::new(), + confirm_commands: vec!["project.restore".to_string()], + agent_policies: BTreeMap::new(), + }, + ) + .expect("write policy"); + + let (sender, receiver) = mpsc::channel(); + let plan_json = serde_json::json!({ + "thinkingSummary": "尝试恢复 checkpoint", + "plan": ["恢复 checkpoint", "等待权限结果"], + "actions": [ + { + "tool": "project.restore", + "reason": "恢复项目到安全状态", + "input": { "checkpointId": checkpoint.checkpoint_id } + } + ], + "response": "" + }) + .to_string(); + let base_url = spawn_mock_llm_server_responses_with_capture(vec![plan_json], Some(sender)); + let _config_guard = write_test_local_config(format!( + r#"{{ + "agentLlm": {{ + "design-director": {{ + "apiKey": "design-key", + "baseUrl": {base_url:?}, + "model": "design-runtime-model", + "apiKind": "openai_responses" + }} + }} +}}"# + )); + + start_game_creator_agent_background_task_at( + &root, + "design-director", + "后台尝试恢复 checkpoint", + "design-project-restore-policy-run", + ) + .expect("start background task"); + + let plan_request = receiver + .recv_timeout(Duration::from_secs(2)) + .expect("plan llm request"); + assert!(plan_request.contains("confirmTools")); + assert!(plan_request.contains("project.restore")); + assert!(receiver.recv_timeout(Duration::from_millis(200)).is_err()); + + let runtime = wait_for_agent_runtime_confirmation(&root, "design-director"); + assert_eq!(runtime.status, "waiting-for-confirmation"); + assert_eq!(runtime.task_queue.waiting_for_confirmation, 1); + assert!(runtime + .tool_policy + .confirm_tools + .contains(&"project.restore".to_string())); + assert!(runtime.observations.iter().any(|item| item.contains( + "project.restore：waiting-for-confirmation · 项目权限策略要求用户确认：project.restore" + ))); + assert!(!runtime + .observations + .iter() + .any(|item| item.contains("project.restore：ok"))); + assert_eq!( + fs::read_to_string(root.join("game/blocked-notes.txt")).expect("blocked notes"), + "v2" + ); + let agent_db = fs::read_to_string(root.join(".agent/agent.db")).expect("agent db"); + assert!(!agent_db.contains("\"recordType\":\"project.restore\"")); + + fs::remove_dir_all(root).ok(); +} + #[tokio::test] async fn background_agent_runtime_can_read_other_agent_status() { let root = unique_project_path(); diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 9b1aa47ef..75c2f8b03 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -32,6 +32,7 @@ - 2026-07-10 补充：主窗口 Agent 状态栏在开发模式新增“调度 Ready”控制，用来显式调用 `schedule_game_creator_agent_ready_tasks`。该控制先读取项目策略，命中 `agent.schedule_ready` confirm 时走现有确认弹窗，确认后才把 manifest ready task 投递到对应 Agent Runtime；普通用户窗口不展示这个开发控制。 - 2026-07-10 补充：后台 Agent Runtime 的白名单工具继续扩到 `agent.schedule_ready`，让 Agent 在完成或更新 manifest task 后可按项目权限策略自行调度新 ready task。该工具复用同一个 scheduler：扫描依赖已完成且仍为 pending 的 manifest task，先标为 running，再按 taskId 投递到对应 Agent 的既有后台队列；策略要求确认时当前 Agent 停在 `waiting-for-confirmation`，不会静默启动下游 Agent。 - 2026-07-10 补充：后台 Agent Runtime 的白名单工具继续扩到 `project.checkpoint`，让 Agent 在 `file.write`、`task.update` 或批量修改前自行创建本地 checkpoint。该工具复用 `project.checkpoint` 策略和项目写锁，observation 只返回 checkpoint id、文件数和总字节数，不返回本机绝对路径；策略要求确认时不创建 checkpoint。 +- 2026-07-10 补充：后台 Agent Runtime 的白名单工具继续扩到 `project.restore`，让 Agent 在 diff 或自检发现走偏后可请求恢复到指定 checkpoint。该工具复用 `project.restore` 确认策略和项目写锁，observation 只返回 checkpoint id、恢复文件数和删除文件数；默认确认策略下不会静默回滚用户项目。 - 影响范围：`apps/ai-game-creator-shell` 的 Tauri command、Agent Runtime state/event、开发窗口单 Agent 聊天、项目内 Agent 对话弹窗、`appSurface.test.ts` 和 AI 游戏创作 App 实施计划。 - 验证方式：运行 Tauri Rust 后台 Agent 并行测试、壳前端 appSurface 测试、壳 typecheck、编码检查和 `git diff --check`。 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 85b6971ad..2c600e56a 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -32,7 +32,7 @@ Agent Runtime 负责： - 开发窗口能力：debug 构建额外打开 `developer` 窗口，走 `index.html?agent-chat`；开发者可选择 Agent、授权本地项目路径，并通过 `read_local_conversation` / `append_local_conversation_message` 读写 `.agent/conversations/agents/.jsonl`，通过 `agentLlm.` 调用该 Agent 的独立 LLM 路由做真实对话，用于单独调试某个 Agent 的长期对话上下文。这里的 `` 以 manifest taskId 为规范值，旧 `group-role` 别名只作为兼容输入映射到 taskId。 - 命令能力：内置命令调用、权限 gate、执行日志；v1 只允许白名单受限命令，不执行任意 shell。 - 编排能力：任务拆分、任务图依赖、专业组调度、多智能体协作；Runtime V1 会为单 Agent 对话和生成 loop 中的角色 brief 写入独立 runtime state / event，先解决“每个 Agent 正在做什么、跑到哪一步、最近一次 task/run 是什么”的可观测性。 -- 后台任务能力：开发窗口单 Agent 聊天和项目内 Agent 对话弹窗可把当前输入投递为单 Agent 后台任务，Tauri 命令 `start_game_creator_agent_runtime_task` 会立即写入该 Agent 的 `.agent/runtime/agents/.json`、`.agent/runtime/events/.jsonl`、`.agent/runtime/tasks/.jsonl` 和 `.agent/conversations/agents/.jsonl`，随后在 App 进程内启动 tokio task 执行最小 Agent loop：每轮让该 Agent 输出 `thinkingSummary / plan / actions / response`，Runtime 按白名单和项目权限策略执行工具动作，写入 `thinking_summary / plan / action / observation / response / error` 事件，再把 observation 放入下一轮 prompt 让 Agent 修正计划、继续行动或用空 actions + response 收束；后台任务最多执行 3 轮 loop，仍未收束时再按最后计划和全部观察生成最终回复并追加回对话。工具箱包含只读工具 `memory.read`、`conversation.read`、`asset.list`、`project.index`、`project.diff`、`file.list`、`file.read`、`task.list`、`agent.run_status`，以及受策略保护的写/运行工具 `memory.write`、`project.checkpoint`、`file.write`、`task.create`、`task.update`、`command.run_limited`、`blackboard.write`、`agent.message` 和 `agent.delegate`；`memory.write` 可追加或覆盖本 Agent 私有记忆、项目长期/短期记忆或黑板，`project.checkpoint` 可在写入或批量修改前创建本地 checkpoint，`file.write` 只能写项目内相对路径并记录审计，`task.create` 只能追加经过校验的新 manifest 任务，`task.update` 只能更新已有 manifest 任务状态，`command.run_limited` 只接受 `game.static_smoke` 并复用本地静态自检安全边界，`blackboard.write` 追加 `memory/blackboard.md`，`agent.message` 给目标 `.agent/conversations/agents/.jsonl` 写入 tool 留言，`agent.delegate` 把任务投递到目标 Agent 的独立后台队列，策略要求确认或拒绝时不执行写入、运行或委派，只把策略结果作为 observation 回给 Agent。`read_game_creator_agent_runtime` 会按 `runId` 去重返回最近任务和最近事件，`read_game_creator_agent_runtimes` 批量读取所有规范 taskId 的 runtime；开发窗口和项目内 Agent 对话弹窗的 Runtime 状态面板展示最近事件、最近任务、当前目标、当前任务、当前动作、等待对象、下一步和运行阶段，主窗口 Agent 状态列表展示当前目标、任务、动作、等待对象和运行阶段摘要。不同 Agent 使用各自 runtime 锁，可以并行运行；同一 Agent 已有运行任务时，新任务会先写成 `pending / queued`，由当前后台 drain 在完成后串行继续执行。该能力仍属于 Runtime V1 的进程内任务，不是独立 OS 进程或跨重启离线常驻 worker。 +- 后台任务能力：开发窗口单 Agent 聊天和项目内 Agent 对话弹窗可把当前输入投递为单 Agent 后台任务，Tauri 命令 `start_game_creator_agent_runtime_task` 会立即写入该 Agent 的 `.agent/runtime/agents/.json`、`.agent/runtime/events/.jsonl`、`.agent/runtime/tasks/.jsonl` 和 `.agent/conversations/agents/.jsonl`，随后在 App 进程内启动 tokio task 执行最小 Agent loop：每轮让该 Agent 输出 `thinkingSummary / plan / actions / response`，Runtime 按白名单和项目权限策略执行工具动作，写入 `thinking_summary / plan / action / observation / response / error` 事件，再把 observation 放入下一轮 prompt 让 Agent 修正计划、继续行动或用空 actions + response 收束；后台任务最多执行 3 轮 loop，仍未收束时再按最后计划和全部观察生成最终回复并追加回对话。工具箱包含只读工具 `memory.read`、`conversation.read`、`asset.list`、`project.index`、`project.diff`、`file.list`、`file.read`、`task.list`、`agent.run_status`，以及受策略保护的写/运行工具 `memory.write`、`project.checkpoint`、`project.restore`、`file.write`、`task.create`、`task.update`、`command.run_limited`、`blackboard.write`、`agent.message` 和 `agent.delegate`；`memory.write` 可追加或覆盖本 Agent 私有记忆、项目长期/短期记忆或黑板，`project.checkpoint` 可在写入或批量修改前创建本地 checkpoint，`project.restore` 可在确认后把项目恢复到指定 checkpoint，`file.write` 只能写项目内相对路径并记录审计，`task.create` 只能追加经过校验的新 manifest 任务，`task.update` 只能更新已有 manifest 任务状态，`command.run_limited` 只接受 `game.static_smoke` 并复用本地静态自检安全边界，`blackboard.write` 追加 `memory/blackboard.md`，`agent.message` 给目标 `.agent/conversations/agents/.jsonl` 写入 tool 留言，`agent.delegate` 把任务投递到目标 Agent 的独立后台队列，策略要求确认或拒绝时不执行写入、运行、恢复或委派，只把策略结果作为 observation 回给 Agent。`read_game_creator_agent_runtime` 会按 `runId` 去重返回最近任务和最近事件，`read_game_creator_agent_runtimes` 批量读取所有规范 taskId 的 runtime；开发窗口和项目内 Agent 对话弹窗的 Runtime 状态面板展示最近事件、最近任务、当前目标、当前任务、当前动作、等待对象、下一步和运行阶段，主窗口 Agent 状态列表展示当前目标、任务、动作、等待对象和运行阶段摘要。不同 Agent 使用各自 runtime 锁，可以并行运行；同一 Agent 已有运行任务时，新任务会先写成 `pending / queued`，由当前后台 drain 在完成后串行继续执行。该能力仍属于 Runtime V1 的进程内任务，不是独立 OS 进程或跨重启离线常驻 worker。 - 2026-07-10 补充：Agent Runtime state 新增 `toolPolicy`，按当前项目 `.agent/policy.json` 派生工具级 `allowedTools / autoTools / confirmTools / deniedTools` 快照；后台 planning prompt 会带入该快照，让 Agent 在规划时知道哪些工具会自动执行、需要确认或被拒绝。`blackboard.write` 继承 `memory.write` 策略，`agent.message` 继承 `conversation.write` 策略，`agent.delegate` 使用独立 `agent.delegate` 策略；实际执行仍以 Runtime 的白名单和项目权限 gate 为准。 - 2026-07-10 补充：`.agent/policy.json` 新增 `agentPolicies`，可按规范 Agent id 分别配置 `deniedCommands / confirmCommands`。有效策略为“项目级策略 + Agent 级策略”的保守叠加：项目级拒绝 / 确认仍对所有 Agent 生效，Agent 级策略只能进一步限制该 Agent，不能放宽项目级策略，拒绝优先于确认。主聊天新增 `/agent-policy-deny Agent 命令`、`/agent-policy-allow Agent 命令`、`/agent-policy-confirm Agent 命令` 和 `/agent-policy-auto Agent 命令`，写入前仍走 `project.policy_write` 确认卡。 - 2026-07-10 补充：后台 Agent 工具命中 `confirmCommands` 时不再继续整理最终回复，而是把本轮 Runtime 停在 `status/phase = waiting-for-confirmation`，`waitingOn` 指向“开发者确认 Agent 工具动作”，`recentToolCalls`、事件流、任务记录和 `taskQueue.waitingForConfirmation` 都保留该待确认事实；同一 Agent 的 drain 会暂停，不继续消费后续 pending 任务。命中拒绝策略仍作为 `blocked` observation 交回 Agent 继续修正计划。 @@ -53,6 +53,7 @@ Agent Runtime 负责： - 2026-07-10 补充：主窗口 Agent 状态栏的“调度 Ready”只在开发模式显示。点击后复用项目策略确认弹窗，确认通过才调用 `schedule_game_creator_agent_ready_tasks`，并把返回的 Runtime 合并回 Agent 状态卡；普通用户窗口继续只展示状态和单 Agent 对话入口，不直接暴露 ready-task 调度按钮。 - 2026-07-10 补充：`agent.schedule_ready` 同时接入后台 Agent loop 白名单工具。Agent 可在 `task.update` 或 `task.create` 后自行请求调度新 ready task；执行仍走 `agent.schedule_ready` 项目权限策略，确认策略命中时当前 run 停在 `waiting-for-confirmation`，不会继续消费队列或启动下游 Agent。确认通过后复用同一 scheduler，把 ready task 投递到对应 Agent 的既有后台队列。 - 2026-07-10 补充：后台任务工具箱已加入 `project.checkpoint`。Agent 可在写入文件、更新任务或批量修改前自行创建本地 checkpoint；Runtime 复用 `project.checkpoint` 权限策略和项目写锁，observation 只返回 checkpoint id、文件数和总字节数，不返回本机绝对路径。策略要求确认或拒绝时不会创建 checkpoint。 +- 2026-07-10 补充：后台任务工具箱已加入 `project.restore`。Agent 可在 diff 或自检发现本轮修改走偏后请求恢复到指定 checkpoint；Runtime 复用 `project.restore` 权限策略和项目写锁，observation 只返回 checkpoint id、恢复文件数和删除文件数，不返回本机绝对路径。默认确认策略下不会静默回滚用户项目。 - 2026-07-10 补充：单 Agent 聊天和后台 planning prompt 会读取同一个 Agent 的 Runtime 连续上下文，把本 Agent 最近 status / phase / runId / 当前任务 / 下一步、最近回复、计划、观察、最近 3 条工具动作、最近事件、最近 3 条任务记录和工具策略摘要带入下一轮推理；上下文按规范 taskId 隔离，不读取其他 Agent 的 runtime 文件，并在进入 prompt 前过滤密钥和本机绝对路径。新后台 run 启动时会继承本 Agent 上次 `recentToolCalls` 和 `lastResponse`，让多轮任务不丢失结构化行动证据。 - 2026-07-10 补充：后台任务工具箱已加入 `preview.start`。Agent 可在 loop 中自行请求启动当前项目的本地 HTTP 预览；Runtime 会复用 `preview.start` 策略、项目写锁、共享 `PreviewRegistry`、manifest 预览状态、`.agent/logs/preview.log` 和 run trace 追加逻辑，并把 `agent.runtime.preview.start` 写入 `.agent/agent.db`。该 observation 只向 LLM 返回 localhost URL 与端口，不返回用户项目绝对路径。 - 2026-07-10 补充：后台任务工具箱已加入 `canvas.asset_generate`。Agent 可在 loop 中自行给出素材 prompt，通过 AppData / Tauri 配置里的 `editorApi` 调用 External Editor API 生成首版美术素材、下载到 `assets/canvas-generated/` 并登记 manifest；Runtime 复用 `canvas.asset_generate` 策略和项目写锁，并写入 `agent.runtime.canvas.asset_generate` 审计记录。API Key 不进入 observation、manifest、agent.db 或日志；策略要求确认或拒绝时不会调用外部 API。 @@ -284,7 +285,7 @@ game-project/ - Tauri Rust 入口保持薄壳：`src-tauri/src/main.rs` 只保留共享类型 / 常量、模块声明、CLI preflight、`tauri::Builder`、运行时配置初始化和 `invoke_handler` 清单；命令行入口放在 `cli.rs`，Tauri command 包装放在 `commands.rs`，运行时配置与 LLM 配置检查放在 `config.rs`，Agent loop 与生成编排放在 `agent.rs`，上传 / 画板 / 平台美术生成接入放在 `assets.rs`，本地项目文件、记忆、对话、权限、checkpoint、manifest 和通用路径工具放在 `project.rs`，本地 HTTP 预览与 preview 命令放在 `preview.rs`，旧窗口兼容命令放在 `windows.rs`，Rust 单测放在 `tests.rs`。后续继续拆分时保持 Tauri command 名、JSON 字段、`.agent/*` 路径和错误语义不变。 - 本地项目初始化会创建 `game/`、`assets/`、`memory/`、`memory/agents/`、`exports/`、`.agent/logs/`，写入 `.agent/manifest.json`，生成 append-only JSONL 本地项目索引 `.agent/agent.db`，并生成默认 `game/index.html`。 - v1 conversation 记录使用 append-only JSONL，每行带 `schemaVersion`、`role`、`content`、`agentId` 和 `updatedAt`，作为聊天历史和单 agent 对话历史的事实源；目录在首次写入时创建。 -- 开发窗口和项目内 Agent 对话弹窗的“后台运行”只启动或排队单 Agent 后台任务，不阻塞等待回复；用户可刷新同一 Agent 对话或 runtime 状态查看进度和结果，也可对当前 run 执行取消 / 重试，待确认 run 还可执行“确认继续”。后台任务会向 `.agent/runtime/tasks/.jsonl` 追加任务视角记录，任务状态使用 `pending / running / waiting-for-confirmation / cancelled / completed / failed`，读取时按 `runId` 去重返回最近任务；`runId` 在同一 Agent 内是单个 run 的身份，后台入队会自动把重复 runId 改写为唯一实际 runId，防止不同任务互相覆盖；runtime state 自身仍可在完成后显示 `idle / completed`，二者语义分开。同一 Agent 的 pending 任务由持有 `.agent/runtime/locks/.lock` 的后台 drain 串行执行，避免同一 Agent 并发抢上下文；不同 Agent 仍可并行；若某个工具动作命中确认策略，该 Agent 会停在 `waiting-for-confirmation` 并暂停继续消费队列，等待后续确认或策略调整；确认继续会为新 run 写入一次性 `.agent/runtime/confirmations///.json` 票据，权限 gate 在 deny 之后、confirm 阶段消费票据并只放行对应工具一次，原 run 追加 `completed/confirmed` 任务记录；若用户取消 pending 任务，drain 不再消费该 run，若取消 running 任务，则在当前 LLM 或工具调用返回后的检查点停止，不继续执行工具或保存最终 assistant 回复。客户端重开项目时会对当前项目路径自动尝试一次 Runtime 恢复；恢复命令必须通过 `agent.resume` 自动权限，默认确认策略下不会静默启动；同一 Agent 同时存在上一进程遗留 `running` 和 `pending` 时，先重接 `running`，再由 drain 继续 `pending`。开发构建和后台 Agent 工具箱都可通过 `agent.schedule_ready` 权限确认入口把 manifest ready task 投递进同一后台队列，命令会先把 ready task 标成 `running`，再用 taskId 作为 Agent id 入队，source 为 `agent-ready-task-scheduler`；该入口不新增独立 worker。后台任务的核心 loop 最多 3 轮：每轮把已有 observation 带回 LLM 让 Agent 重新规划，只有 actions 为空且 response 非空时提前收束，否则继续执行白名单工具，跑满后再进入最终回复整理。后台任务完成后会把 assistant 回复追加到对应 `.agent/conversations/agents/.jsonl`，并向 `.agent/agent.db` 写入 `agent.runtime.background_task.queued` / `agent.runtime.background_task` / `agent.runtime.background_task.recovered` / `agent.runtime.ready_task.scheduled` / `agent.runtime.tool_observation` / `agent.runtime.tool_confirmation_required` / `agent.runtime.tool_confirmation.approved` / `agent.runtime.memory.write` / `agent.runtime.file.write` / `agent.runtime.task.create` / `agent.runtime.task.update` / `agent.runtime.command.run_limited` / `agent.runtime.blackboard.write` / `agent.runtime.agent.message` / `agent.runtime.agent.delegate` / `agent.runtime.background_task.cancelled` / `agent.runtime.background_task.retry` / `agent.runtime.background_task.completed` / `agent.runtime.background_task.failed` 审计记录。当前工具箱开放只读工具 `memory.read`、`conversation.read`、`asset.list`、`project.index`、`project.diff`、`file.list`、`file.read`、`task.list`、`agent.run_status`，以及受策略保护的写/运行工具 `memory.write`、`project.checkpoint`、`file.write`、`task.create`、`task.update`、`command.run_limited`、`blackboard.write`、`agent.message`、`agent.delegate` 和 `agent.schedule_ready`；`memory.write scope=agent` 只允许写当前 Agent 自己的私有记忆，跨 Agent 共享必须改用 `blackboard.write` 或 `agent.message`；`project.checkpoint` 只创建本地 checkpoint，不返回本机绝对路径；`task.create` 只追加新 manifest 任务，`task.update` 只更新已有任务状态；`agent.schedule_ready` 只调度 manifest ready task，不创建平行 runtime；若项目策略拒绝，对应工具不会执行，Runtime 会把策略结果作为 observation 回给 Agent 修正计划；若项目策略要求确认且没有一次性确认票据，Runtime 会保留待确认状态而不执行该工具。`toolPolicy` 保存当前工具级权限快照，供 planning prompt 和状态面板展示；`recentToolCalls` 保存最近 20 条结构化工具动作，供状态面板展示最近动作；append-only JSONL 写入按目标文件路径在当前进程内串行追加完整行，覆盖 `.agent/agent.db`、对话、Runtime events/tasks、activity 和 output，减少多个 Agent 同时完成时的行交错风险。 +- 开发窗口和项目内 Agent 对话弹窗的“后台运行”只启动或排队单 Agent 后台任务，不阻塞等待回复；用户可刷新同一 Agent 对话或 runtime 状态查看进度和结果，也可对当前 run 执行取消 / 重试，待确认 run 还可执行“确认继续”。后台任务会向 `.agent/runtime/tasks/.jsonl` 追加任务视角记录，任务状态使用 `pending / running / waiting-for-confirmation / cancelled / completed / failed`，读取时按 `runId` 去重返回最近任务；`runId` 在同一 Agent 内是单个 run 的身份，后台入队会自动把重复 runId 改写为唯一实际 runId，防止不同任务互相覆盖；runtime state 自身仍可在完成后显示 `idle / completed`，二者语义分开。同一 Agent 的 pending 任务由持有 `.agent/runtime/locks/.lock` 的后台 drain 串行执行，避免同一 Agent 并发抢上下文；不同 Agent 仍可并行；若某个工具动作命中确认策略，该 Agent 会停在 `waiting-for-confirmation` 并暂停继续消费队列，等待后续确认或策略调整；确认继续会为新 run 写入一次性 `.agent/runtime/confirmations///.json` 票据，权限 gate 在 deny 之后、confirm 阶段消费票据并只放行对应工具一次，原 run 追加 `completed/confirmed` 任务记录；若用户取消 pending 任务，drain 不再消费该 run，若取消 running 任务，则在当前 LLM 或工具调用返回后的检查点停止，不继续执行工具或保存最终 assistant 回复。客户端重开项目时会对当前项目路径自动尝试一次 Runtime 恢复；恢复命令必须通过 `agent.resume` 自动权限，默认确认策略下不会静默启动；同一 Agent 同时存在上一进程遗留 `running` 和 `pending` 时，先重接 `running`，再由 drain 继续 `pending`。开发构建和后台 Agent 工具箱都可通过 `agent.schedule_ready` 权限确认入口把 manifest ready task 投递进同一后台队列，命令会先把 ready task 标成 `running`，再用 taskId 作为 Agent id 入队，source 为 `agent-ready-task-scheduler`；该入口不新增独立 worker。后台任务的核心 loop 最多 3 轮：每轮把已有 observation 带回 LLM 让 Agent 重新规划，只有 actions 为空且 response 非空时提前收束，否则继续执行白名单工具，跑满后再进入最终回复整理。后台任务完成后会把 assistant 回复追加到对应 `.agent/conversations/agents/.jsonl`，并向 `.agent/agent.db` 写入 `agent.runtime.background_task.queued` / `agent.runtime.background_task` / `agent.runtime.background_task.recovered` / `agent.runtime.ready_task.scheduled` / `agent.runtime.tool_observation` / `agent.runtime.tool_confirmation_required` / `agent.runtime.tool_confirmation.approved` / `agent.runtime.memory.write` / `agent.runtime.file.write` / `agent.runtime.task.create` / `agent.runtime.task.update` / `agent.runtime.command.run_limited` / `agent.runtime.blackboard.write` / `agent.runtime.agent.message` / `agent.runtime.agent.delegate` / `agent.runtime.background_task.cancelled` / `agent.runtime.background_task.retry` / `agent.runtime.background_task.completed` / `agent.runtime.background_task.failed` 审计记录。当前工具箱开放只读工具 `memory.read`、`conversation.read`、`asset.list`、`project.index`、`project.diff`、`file.list`、`file.read`、`task.list`、`agent.run_status`，以及受策略保护的写/运行工具 `memory.write`、`project.checkpoint`、`project.restore`、`file.write`、`task.create`、`task.update`、`command.run_limited`、`blackboard.write`、`agent.message`、`agent.delegate` 和 `agent.schedule_ready`；`memory.write scope=agent` 只允许写当前 Agent 自己的私有记忆，跨 Agent 共享必须改用 `blackboard.write` 或 `agent.message`；`project.checkpoint` 只创建本地 checkpoint，不返回本机绝对路径；`project.restore` 只按 checkpoint id 恢复当前项目，不返回本机绝对路径，默认确认策略下不会静默回滚；`task.create` 只追加新 manifest 任务，`task.update` 只更新已有任务状态；`agent.schedule_ready` 只调度 manifest ready task，不创建平行 runtime；若项目策略拒绝，对应工具不会执行，Runtime 会把策略结果作为 observation 回给 Agent 修正计划；若项目策略要求确认且没有一次性确认票据，Runtime 会保留待确认状态而不执行该工具。`toolPolicy` 保存当前工具级权限快照，供 planning prompt 和状态面板展示；`recentToolCalls` 保存最近 20 条结构化工具动作，供状态面板展示最近动作；append-only JSONL 写入按目标文件路径在当前进程内串行追加完整行，覆盖 `.agent/agent.db`、对话、Runtime events/tasks、activity 和 output，减少多个 Agent 同时完成时的行交错风险。 - 2026-07-10 补充：当前工具箱还开放 `preview.start`，审计记录类型为 `agent.runtime.preview.start`；该工具不会打开任意 URL，只启动当前授权项目的 `127.0.0.1` 本地预览，并和 Tauri 用户命令共用同一个 `PreviewRegistry`。 - 2026-07-10 补充：当前工具箱还开放 `canvas.asset_generate`，审计记录类型为 `agent.runtime.canvas.asset_generate`；该工具只通过配置好的 External Editor API 生成并回流素材，不暴露任意上传 / 任意网络请求能力。 - 2026-07-10 补充：当前工具箱还开放 `task.list`；该工具只读取 manifest 任务图、状态、依赖、产物和 `readyTaskIds`，并受 `task.list` 项目权限策略保护。 @@ -292,6 +293,7 @@ game-project/ - 2026-07-10 补充：当前工具箱还开放 `task.update`，审计记录类型为 `agent.runtime.task.update`；该工具只允许更新 manifest 中已有任务的状态，并受 `task.update` 项目权限策略保护。 - 2026-07-10 补充：当前工具箱还开放 `file.list`；该工具只读列出项目文件摘要，可按相对路径过滤，并受 `file.list` 项目权限策略保护。 - 2026-07-10 补充：当前工具箱还开放 `project.diff`；该工具只读返回 checkpoint 对比后的新增、修改、删除计数和相对路径摘要，并受 `project.diff` 项目权限策略保护。 +- 2026-07-10 补充：当前工具箱还开放 `project.restore`；该工具按 checkpoint id 恢复当前项目并删除 checkpoint 外新增文件，受 `project.restore` 项目权限策略和项目写锁保护，默认确认策略下不会静默执行。 - 2026-07-10 补充：当前工具箱还开放 `agent.run_status`；该工具只读返回自己、目标 Agent 或一组 Agent 的 Runtime 状态摘要，并受 `agent.run_status` 项目权限策略保护。 - 2026-07-10 补充：当前工具箱还开放 `agent.delegate`，审计记录类型为 `agent.runtime.agent.delegate`；该工具只把任务投递到目标 Agent 既有后台队列，不创建平行 runtime，不绕过目标 Agent 的锁和队列，也受 `agent.delegate` 项目权限策略保护。 - 2026-07-10 补充：当前 Runtime 命令和后台工具箱都开放 `agent.schedule_ready`，审计记录类型为 `agent.runtime.ready_task.scheduled`；该命令把 manifest ready task 批量投递到对应 Agent 的既有后台队列，默认需要确认，确认前不会启动下游 Agent。