完善通用开发 Agent Runtime V1.1
新增仓库上下文指纹复核与 durable action 漂移保护 拆分 App CLI 与独立 Runner 的投递执行边界并补齐恢复诊断 加入桌面和移动端浏览器验证及跨源网络阻断 实现隔离子 Agent 私有记忆与终止状态传播 补齐 Provider 协议确认副作用重放与 join 真实端到端验证 同步共享契约实施计划决策记录与开发流程文档
This commit is contained in:
AIGameCreator App
@@ -4167,3 +4167,24 @@
|
||||
- 决策：`agent.delegate` 子任务必须 durable 保存 `parentAgentId / parentRunId / delegationId`，其中 `delegationId` 从已持久化工具动作的 `actionId` 派生，不能使用执行时随机值；终态任务记录必须保存经过统一凭据清洗和安全截断的 `terminalDetail`，不能依赖可能被后续 run 覆盖的 Agent 全局 state。子任务进入 `completed / failed / cancelled / budget-exhausted` 任一终态后，Runtime 必须在 delegation 级 OS 文件锁内按固定 receipt runId 幂等生成且至多生成一次 `agent.delegate.result` 回执；不同委派并发写同一目标 Agent 时，runId 分配与 pending 追加还必须在目标 Agent 任务账本 OS 锁内原子完成。失败、排队或活跃取消、预算耗尽与成功同等需要回执，`needs-reconciliation` 只有最终取消后才回执。父 Agent 通过既有队列接收 `source=agent-delegate-receipt` 的续跑任务，回执 prompt 禁止重复同一委派，并携带完整的已清洗 `terminalDetail`，不能只保留 UI 摘要；排队期间不提前写入父会话，真正执行时才幂等落盘，用户消息或回执消息落盘失败时不得进入 LLM。回执任务必须保留父 run 关联，真正开始或恢复前再次核验父 run，关联缺失或父 run 不存在时失败关闭；父 run 已取消或普通失败时只保留 suppressed receipt 审计，不自动复活。父 Session 存在未结束委派时禁止切换或归档，极端竞态下回执回落到父 Agent 当前可写 Session。续跑继续遵守同 Agent FIFO、per-Agent OS 锁、权限确认、取消、恢复和 `needs-reconciliation` 屏障，不允许直接重入、插队或重复投递；恢复必须先恢复 pending action / reconciliation 屏障，再补齐“子终态已落盘、回执未入队”的崩溃窗口。
|
||||
- 决策：Agent loop 的语义事件类型固定为 `thinking_summary / plan / action / observation / response / error`。普通失败和预算耗尽必须先追加统一 `error` 事件，同时保留 `turn.failed / turn.budget_exhausted` 生命周期事件供旧读取方兼容；状态、phase 和清洗后的错误详情必须在两类事件中一致。Runtime 状态面板默认展示最新 4 条事件，但在当前后端最近事件窗口大于 4 条时必须允许展开全部返回记录，不能让 `plan`、早期 observation 或 thinking summary 永久不可见。
|
||||
- 验证：Rust 覆盖首轮上下文不泄露、工具后 observation 可见、六类语义事件、确认前后内容边界、前后台同 Agent 串行、前台结束后队列 drain、恢复确认 gate、预算耗尽失败、默认工具白名单一致性，以及 delegate 成功 / 失败 / 取消 / 预算耗尽终态回执、`delegationId` 幂等去重和父 Agent receipt 续跑仍受 FIFO / 锁 / 确认 / 恢复门禁；revision / verification gate 还要覆盖修改前推进、失败不回退、`requiresVerification` 单向持久化、验证只绑定当前 revision、v1 context bundle / pending action 恢复失败关闭、修改 run 与只读 run 的 stale 回复不落盘、跨 Agent 漂移在同 run 自愈、stale context 重启恢复、动态验证输出不能绕过 stall、stall 跨 revision / restart 保持，以及最终 assistant / completed 在项目写锁内复核后才落盘；finalization 还要覆盖三个阶段边界的崩溃窗口恢复、`prepared` 后取消或 revision / gate 漂移丢弃、journal 损坏或身份冲突阻断并显示 `finalizing`、conversation `messageId` / audit 自愈与并发不重复，以及终态投影 / receipt 不重放；前端覆盖统一事件展示、主工作区和独立开发 Agent 聊天窗口的默认恢复确认条与显式恢复 command。
|
||||
|
||||
## 2026-07-12 AI 游戏创作 Agent Runtime V1.1 通用开发能力
|
||||
|
||||
- 决策：Runtime 首轮从“完全不预加载项目内容”调整为注入固定预算的 repository startup context。自动内容仅限有界目录/manifest/验证脚本摘要、适用 `AGENTS.md`、根 `CONTEXT.md`/README 来源和安全 Git 摘要；任意源码、对话、资产和私有记忆正文仍经工具读取。仓库文本是不可信输入，不能提升权限或覆盖 Runtime 安全规则。
|
||||
- 决策：后台执行所有权迁入同一发布二进制的 `--agent-runner` 模式。Runner 从显式 AppData 配置目录读取密钥，通过带协议版本、requestId 和私有 token 的 loopback 本地协议接收唤醒；`.agent/runtime/**` 继续是事实源。App 退出后 Runner 可继续任务，整机重启后仍需按 `agent.resume` 策略显式恢复。
|
||||
- 决策：跨进程运行前先把 Agent DB、conversation、events/tasks、activity/output 和 Session catalog 的临界区升级为进程内锁加 OS 文件锁；配置写入使用同目录原子替换。事件只作为刷新提示，断线后重读 snapshot。
|
||||
- 决策：新增 `preview.validate`，只验证当前授权项目的精确 loopback 预览，不接受任意 URL/JavaScript/Profile。工具用隔离 Chrome/Edge CDP 采集桌面/移动截图、DOM/console/network 和 canvas 非空证据，证据只落 `.agent/runtime/browser-validations`；它不替代 `project.verify` 或 `game.static_smoke`。
|
||||
- 决策：保留静态 `agent.delegate`，新增批量 `agent.spawn_isolated`。角色/Provider/策略按 `templateAgentId`，队列/锁/session/run/private memory 按 Runtime 生成的 `instanceId`；单次最多 3 个、深度 1、writeScopes 不得重叠，全部 child 终态后只产生一个幂等 join continuation。
|
||||
- 决策：新增仓库外配置的真实 Provider opt-in 验收。通过依据固定为 task/event/agent.db、文件、revision、verification、finalization、conversation、结构化 join 和浏览器证据；模型最终文本不作为通过证据，缺关键外部配置时报告 `BLOCKED`，不得 skip 后记为通过。
|
||||
- 2026-07-12 安全修正：所有 Runtime 写 CLI 必须显式使用项目外 AppData 并交给独立 Runner，`--runner-status` 保持只读。AppData、endpoint 和锁文件必须校验 owner/权限；Runner、Agent lane 和项目 execution-owner 安全打开时拒绝符号链接、硬链接和 Windows reparse point。同一项目的 execution-owner 跨 AppData 唯一并绑定 `bootId / protocolVersion`，不同 Runner 不能同时接管同一项目。
|
||||
- 2026-07-12 安全修正：项目索引和 checkpoint 统一排除敏感配置、`.agent`、VCS、依赖及构建目录；checkpoint manifest 路径必须是唯一规范相对路径，create/diff/restore 均复用项目安全路径解析。通用文件工具不得访问 `.agent/checkpoints/**`，restore 不得覆盖或删除本地敏感配置。
|
||||
- 2026-07-12 修正：动态隔离 all-join 使用独立持久交付记录。固定 `joinRunId` 至多入队一次；原父 run 通过 `agent.run_status` 认领 ready join 时，必须持久标记并取消未执行 continuation；只有父 run 未认领时才在 lane 释放后执行唯一 continuation，恢复不得生成 `-dup-*` join run 或重复调用父 LLM。
|
||||
- 2026-07-12 安全修正：Windows AppData、Runner endpoint、AppData lock 和 execution-owner 诊断文件使用禁止继承且只允许当前用户 SID 的 protected DACL；只读状态入口只校验，不创建目录、不收紧权限。项目 execution-owner 的 OS 锁文件与 JSON 诊断投影分离，Runtime 通过稳定目录句柄先取得系统锁，再原子修复缺失、截断或损坏的诊断，诊断内容不得作为接管依据。
|
||||
- 2026-07-12 安全修正：通用文件、项目索引和 checkpoint 使用同一可移植相对路径语法，拒绝 Windows 盘符 / UNC / ADS、尾随点或空格、保留设备名和大小写碰撞；快照额外排除私钥、数据库和 dump。进入 prompt 的绝对路径脱敏同时覆盖 Unix、Windows 盘符和 UNC 路径。
|
||||
- 2026-07-12 安全修正：`preview.validate` 只使用系统固定安装位置的 Chrome / Chromium / Edge，并在导航前通过 CDP Fetch request-stage 拦截覆盖全部资源。除精确预览 HTTP origin 及同 host / port WebSocket 外，跨 origin HTTP、redirect target、WebSocket 和其他端口必须在连接前阻断。
|
||||
- 2026-07-12 修正：父 run 认领 ready all-join 必须绑定当前持久化 `agent.run_status` 的 `actionId`；同一 action 重试幂等返回，其他 action 不得重复消费，已开始的 continuation 不得被迟到认领覆盖。
|
||||
- 2026-07-12 修正：所有 durable 工具动作执行前复核 repository fingerprint；规范漂移会作废旧动作并回到同 run planning，整个 `.agent` 控制面不参与 fingerprint，避免 checkpoint、日志和 Runtime 状态制造伪漂移。
|
||||
- 2026-07-12 修正：动态隔离 instance 使用自己的 Runtime 私有临时 memory lane，只允许 `scope=agent` 读写本人，拒绝 sibling 和项目 / Session / 黑板共享写入；父任务进入 failed、budget-exhausted 或 cancelled 时必须幂等取消全部非终态 children。
|
||||
- 2026-07-12 修正：`preview.validate` 必须固定同时生成 desktop / mobile 证据，每个视口都要有可见且至少两种 RGBA 状态的 canvas；单视口、无 canvas、透明或均匀纯色画布不能通过。
|
||||
- 验证：真实 `gpt-5.5` 的 `llm-runtime` 套件已通过 Runner 强杀恢复、11 条合法工具协议、4 套完整确认生命周期、5 个零重放副作用动作、9 次结构化成功工具执行、checkpoint/修改、项目验证、Chrome 桌面与移动取证、3 个隔离实例和唯一 join；终态投影与 assistant audit 唯一，action/message/receipt 重复为 0，密钥与诱饵泄露为 0。未配置 External Editor API 时 `full` 套件按契约返回 `BLOCKED(editorApi)`。
|
||||
- 详细契约与验收矩阵见 `docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。
|
||||
|
||||
@@ -60,10 +60,10 @@ npm run agc
|
||||
开发侧需要无 UI 验收某个单 Agent 的完整 Runtime 时使用：
|
||||
|
||||
```bash
|
||||
npm run ai-game-creator-shell:agent-task -- --init /absolute/project code-prototype "修复失败测试并完成验证"
|
||||
npm run ai-game-creator-shell:agent-task -- --config-dir /absolute/app-data --init /absolute/project code-prototype "修复失败测试并完成验证"
|
||||
```
|
||||
|
||||
省略 `--init` 时项目必须已经由客户端初始化；遇到权限确认会返回非零并保留待确认动作，继续操作应回到开发窗口，不能用 CLI 静默绕过。
|
||||
省略 `--init` 时项目必须已经由客户端初始化。所有 Runtime 写命令都必须显式传入项目外 `--config-dir` 并投递给独立 Runner；`--runner-status` 和 Agent 状态查询只读取已有配置与 endpoint，不得创建 AppData、修改权限或为了查询启动 Runner。遇到权限确认会返回非零并保留待确认动作，继续操作应回到开发窗口，不能用 CLI 静默绕过。
|
||||
|
||||
`npm run agc` 会启动 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@
|
||||
| 创作入口、草稿架和玩法链路 | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` |
|
||||
| 创作流程统一阶段计划 | `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` |
|
||||
| 宿主壳、移动 App、桌面 App 与 AI H5 沙箱边界 | `docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`、`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md` |
|
||||
| AI 游戏创作独立 App、Agent Runtime、Runner、浏览器验证与动态隔离子 Agent | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md` |
|
||||
| 本地启动、验证、部署、埋点和运营查询 | `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` |
|
||||
| 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
|
||||
| UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
|
||||
|
||||
Reference in New Issue
Block a user