[Tracking] Game Agent Runtime 交互边界重构 #167

New Issue

2026-08-13T15:13:43+08:00

suzmii commented

2026-08-13 15:13:43 +08:00

问题

当前 GUI、CLI、swarm_cli、Tauri wrapper 和自动化测试分别承担了一部分 Game Agent Runtime 的生命周期判断、状态解释和写入逻辑。

同一个用户操作可能因 Consumer 不同而产生不同处理方式，例如：

是否启动新 Run；
是否 steer、retry、resume 或 cancel；
如何解释 Runtime state、event、response stream 和 sidecar；
如何把 Runtime 输出保存到 Conversation；
在刷新、重连、崩溃和恢复时采用什么行为。

这会造成 GUI、CLI、测试与 Runner 之间的行为漂移；同时，公开状态、命令、幂等、错误、身份、权限和恢复边界尚未形成统一合同。

目标

将正式 Runtime 交互收敛为同一条边界：

Consumer：只读取公开状态、展示界面并提交用户意图；
Supervisor Shell：统一负责交互决策、命令校验、幂等受理、结果读回和错误映射；
Runtime：继续维护 task、state、action、provider、finalization、conversation 等执行事实；
Runner：在持有现有 execution owner lock 时执行正式 Shell 写入、wake 和恢复；
Public / Developer read model：保持明确隔离；
Conversation：从既有 source 回读，不复制第二份正文；
迁移过程：不新增第二套 Runtime authority，不允许 Consumer fallback 回旧写路径。

非目标

本次重构不包括：

Runtime main_loop、task queue 或 Agent 执行状态机重写；
Provider、LLM 或提示词体系调整；
Runner 开机自启或无人值守常驻；
Session rotation、Session handoff、ActiveSessionIndex 或 session control lease；
全局 owner generation / lease；
资源上传、资源 lineage、Preview Registry 或 Session 管理面的重新设计。

现有 OS execution-owner.lock 继续是项目执行写入权威；现有 .agent/project.lock 不作为 Shell protocol lock。

追踪状态

设计并评审 Runtime 统一交互边界方案 #168
确认候选 Contract 可冻结，并明确 P0–P6 的阶段边界和验收门禁
P0：建立迁移前行为基线、协议 fixture 和 crash test harness
P1：建立 Shell 持久协调、幂等读回和 owner 保护
P2：建立 Public / Developer Snapshot、Interaction 只读投影和事件订阅
P3：实现统一写协议，并收口所有正式 Runtime 写入口
P4：实现 Runner 自驱、重启发现和安全恢复
P5：迁移 GUI、CLI 和自动化测试
P6：删除旧公开面并完成最终验收

当前候选方案正在 PR #168 中评审。P0–P6 的具体实现范围、验收证据和后续 PR 拆分，以通过评审后的设计文档及各实施 PR 为准；本 Issue 不重复维护字段级协议或实现细节。

## 问题当前 GUI、CLI、`swarm_cli`、Tauri wrapper 和自动化测试分别承担了一部分 Game Agent Runtime 的生命周期判断、状态解释和写入逻辑。同一个用户操作可能因 Consumer 不同而产生不同处理方式，例如： - 是否启动新 Run； - 是否 steer、retry、resume 或 cancel； - 如何解释 Runtime state、event、response stream 和 sidecar； - 如何把 Runtime 输出保存到 Conversation； - 在刷新、重连、崩溃和恢复时采用什么行为。这会造成 GUI、CLI、测试与 Runner 之间的行为漂移；同时，公开状态、命令、幂等、错误、身份、权限和恢复边界尚未形成统一合同。 ## 目标将正式 Runtime 交互收敛为同一条边界： - **Consumer**：只读取公开状态、展示界面并提交用户意图； - **Supervisor Shell**：统一负责交互决策、命令校验、幂等受理、结果读回和错误映射； - **Runtime**：继续维护 task、state、action、provider、finalization、conversation 等执行事实； - **Runner**：在持有现有 execution owner lock 时执行正式 Shell 写入、wake 和恢复； - **Public / Developer read model**：保持明确隔离； - **Conversation**：从既有 source 回读，不复制第二份正文； - **迁移过程**：不新增第二套 Runtime authority，不允许 Consumer fallback 回旧写路径。 ## 非目标本次重构不包括： - Runtime `main_loop`、task queue 或 Agent 执行状态机重写； - Provider、LLM 或提示词体系调整； - Runner 开机自启或无人值守常驻； - Session rotation、Session handoff、ActiveSessionIndex 或 session control lease； - 全局 owner generation / lease； - 资源上传、资源 lineage、Preview Registry 或 Session 管理面的重新设计。现有 OS `execution-owner.lock` 继续是项目执行写入权威；现有 `.agent/project.lock` 不作为 Shell protocol lock。 ## 追踪状态 - [ ] 设计并评审 Runtime 统一交互边界方案 #168 - [ ] 确认候选 Contract 可冻结，并明确 P0–P6 的阶段边界和验收门禁 - [ ] P0：建立迁移前行为基线、协议 fixture 和 crash test harness - [ ] P1：建立 Shell 持久协调、幂等读回和 owner 保护 - [ ] P2：建立 Public / Developer Snapshot、Interaction 只读投影和事件订阅 - [ ] P3：实现统一写协议，并收口所有正式 Runtime 写入口 - [ ] P4：实现 Runner 自驱、重启发现和安全恢复 - [ ] P5：迁移 GUI、CLI 和自动化测试 - [ ] P6：删除旧公开面并完成最终验收 > 当前候选方案正在 PR #168 中评审。P0–P6 的具体实现范围、验收证据和后续 PR 拆分，以通过评审后的设计文档及各实施 PR 为准；本 Issue 不重复维护字段级协议或实现细节。

suzmii referenced this issue

2026-08-13 15:28:26 +08:00

技术方案：Game Agent Runtime 交互边界重构 #168

suzmii closed this issue

2026-08-22 11:04:50 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#167