AGN 平行方案：UI Relay 协调体系

0. 目标与边界

目标

  1. Coordinator 不再接触仓库、文件、终端、编辑器。只负责生成任务文本与调度顺序。
  2. 所有跨模型协作通过各自官方客户端完成，例如 Codex 客户端、Claude Code 客户端、Gemini 客户端等。
  3. 通过本机执行器完成图形界面交互，把任务文本投递到指定客户端输入框，并发送。
  4. 全流程可审计、可回放、可验证，出现偏差可快速止损。

边界

  1. UI Relay 只做三类动作：激活应用、聚焦输入、粘贴文本并发送。
  2. UI Relay 不允许任意点击导航、拖拽、文件操作、打开链接、执行终端命令。
  3. Coordinator 无任何本机权限，它只是生产指令与文本。

1. 总体架构

三层分离

  1. 决策层 Coordinator 模型。负责把你的自然语言需求变成可执行的投递计划与任务文本。

  2. 执行层 UI Relay 本机执行器。唯一拥有无障碍权限的组件，按协议执行投递动作。

  3. 验收层 证据收集与评估模块。负责收集投递成功证据与对端回复证据，并以可量化标准判定阶段完成。

关键思想

把 AGN 原本的“多代理对文件与工具的直接操作”替换为“多客户端之间的文本回合制协作”。系统复杂度从工具编排与权限治理，转移为投递可靠性与证据链治理。

2. 核心组件清单

2.1 Coordinator

职责

  1. 把需求拆成若干回合，定义每回合要找哪个客户端，说什么话，要拿回什么证据。
  2. 为每个回合生成结构化投递指令与任务文本。
  3. 读取对端回复，判断是否进入下一回合，或触发止损。

强约束

  1. Coordinator 输出必须满足严格格式，禁止自由发挥式的多选项建议。
  2. Coordinator 每回合只允许生成一条要投递的任务文本，避免分叉。

2.2 UI Relay 本机执行器

职责

  1. 校验指令合法性，应用白名单与窗口校验规则。
  2. 执行投递：激活目标应用，聚焦输入区域，粘贴整段文本，发送。
  3. 产出证据：投递前后窗口标题，时间戳，截图，错误码。

强约束

  1. 只允许操作白名单应用。
  2. 只允许有限动作集合。
  3. 严格的超时与重试策略，重试必须可控且可回溯。

2.3 Evidence Vault 证据仓库

职责

  1. 存储每次投递与每次对端回复的证据。
  2. 可回放，便于审计与复盘。
  3. 支持按任务、回合、时间检索。

建议存储内容

  1. 指令原文与哈希
  2. 投递目标与校验信息
  3. 投递截图与对端回复截图
  4. 错误日志与恢复动作记录

2.4 Session Router 会话路由

职责

  1. 维护每个客户端当前对应哪个任务，防止投递到错误对话。
  2. 支持多任务并行时的强隔离，例如每个任务独立窗口或独立对话标签。

3. 指令协议

为了让执行器与 Coordinator 解耦，必须定义一套最小但足够严谨的协议。建议采用 JSON 结构，但这里不写任何代码形式，仅描述字段含义。

3.1 基本字段

  1. task_id 全局唯一任务编号，用于证据链索引。

  2. turn_id 回合编号，从 1 开始递增。

  3. target_app 目标应用标识，必须命中白名单。

  4. target_context 目标上下文校验规则，例如窗口标题必须包含指定关键字，或必须处于指定 workspace。

  5. input_focus_strategy 聚焦策略，只允许两类 第一类：固定快捷键聚焦输入 第二类：只允许点击固定的输入区域坐标块，这一类风险更高，能不用就不用

  6. payload_text 要发送的完整任务文本。

  7. send_action 发送方式，通常是回车。可选支持组合键发送。

  8. evidence_policy 必须产出的证据类型与粒度，例如必须截图，必须回传窗口标题。

  9. timeouts_and_retries 超时阈值与重试次数上限，重试必须记录原因与证据。

3.2 合法性规则

  1. 未命中白名单应用直接拒绝执行。
  2. 窗口标题校验失败直接拒绝执行。
  3. payload_text 超过长度阈值必须拆分回合，而不是强行一次粘贴。
  4. 任何不在动作集合内的请求直接拒绝。

4. 任务文本规范

你要的效果是 Coordinator 只用嘴描述任务，但要让对端客户端稳定执行，文本必须工程化。

4.1 统一结构

  1. 任务目标 一句话定义可验收结果。

  2. 约束与边界 明确不允许做什么，例如禁止改主分支，禁止删除文件，禁止引入新依赖。

  3. 输入材料 仓库路径、分支策略、文件范围、已有接口约定。这里仍然是文字描述，不要求 Coordinator 访问文件。

  4. 交付物清单 必须给出哪些输出，例如补丁摘要、变更文件列表、测试结果摘要、风险点列表。

  5. 验收标准 必须可量化，例如通过哪些测试，或输出哪些命令的结果。你可以要求对端把命令输出粘贴回来。

  6. 止损条件 如果遇到不确定性或需要大改，必须停下并提出问题，而不是继续自由发挥。

4.2 关键策略

  1. 所有任务默认要求在新分支进行，除非你明确允许直改。
  2. 对端执行后必须回报一个最小可验证证据，例如测试通过摘要或变更摘要。
  3. 同一回合只做一类动作，例如只做实现，或只做 review，不要混在一个回合里。

5. 可靠性机制

GUI 自动化的失败常见于焦点、窗口错位、输入法干扰、应用卡顿。方案必须系统性处理。

5.1 聚焦与投递可靠性

  1. 统一采用剪贴板粘贴，不逐字输入，减少输入法与自动替换风险。
  2. 投递前做窗口标题校验，确保落点正确。
  3. 投递后强制截图，证明内容已进入正确的对话窗口。

5.2 超时与重试

  1. 每次投递有明确超时，例如 5 秒内必须完成焦点与发送。
  2. 重试次数严格上限，例如最多 1 次。
  3. 重试前必须再次校验窗口标题，且必须产出失败证据。

5.3 失败分级

  1. 可恢复失败 焦点丢失、窗口标题不匹配、目标应用未前台。

  2. 不可恢复失败 无障碍权限失效、目标应用崩溃、系统弹窗拦截导致不确定输入。

对不可恢复失败，系统必须立即停止并向你报告，不得继续尝试。

6. 安全与权限治理

这套方案的最大风险是无障碍权限过强。必须把“强权限”封装在一个极小的执行面里。

6.1 权限最小化

  1. 只有 UI Relay 拥有无障碍权限。
  2. Coordinator 无任何本机权限。
  3. UI Relay 运行身份固定，避免权限漂移。

6.2 行为白名单

  1. 应用白名单 只允许你指定的客户端与通讯工具。

  2. 动作白名单 只允许激活、聚焦、粘贴、发送、截图与读窗口标题。

  3. 内容审计 每次投递内容与哈希落盘，防止静默修改。

6.3 防误投递隔离

  1. 每个任务固定绑定一个对话窗口或一个 workspace。
  2. 当窗口标题不符合规则时禁止投递。
  3. 建议对每个客户端建立专用会话，不与日常聊天混用。

7. 与现有 AGN 的并行关系

7.1 你当前 AGN 的优势

  1. 能直接改仓库，能跑测试，能读文件，能形成闭环。
  2. 自动化程度高，适合长期无人监管运行。

7.2 UI Relay 方案的优势

  1. 极低的工具集成成本，不需要让模型接触终端与文件系统。
  2. 权限面更可控，执行器行为非常有限。
  3. 适合你现在“只想把协作跑起来”的阶段。

7.3 并行策略

  1. 把 UI Relay 作为 AGN 的旁路模式 当你不希望任何 agent 触碰本机文件时启用。

  2. 把 UI Relay 作为故障回退 当 AGN 的工具链不稳定，例如 CLI 掉线、授权抖动时，改走客户端文字协作。

  3. 把 UI Relay 作为高价值环节的人工化接口 例如最终 review 必须经过 Claude Code 客户端的固定流程。

8. 运行流程

8.1 单任务标准回合

  1. 你发需求给 Coordinator
  2. Coordinator 生成回合 1 给 Codex 客户端的实现任务
  3. UI Relay 投递并产出证据
  4. 等待对端回复，收集证据
  5. Coordinator 基于回复生成回合 2 给 Claude Code 客户端的 review 任务
  6. UI Relay 投递并产出证据
  7. 等待对端回复，收集证据
  8. Coordinator 汇总并给出下一步，或交付完成报告

8.2 可选回合

  1. 澄清回合 当需求不确定时，先让某一客户端提出问题，避免盲改。

  2. 风险回合 让 review 客户端明确列出风险与回滚策略。

  3. 验证回合 要求实现客户端粘贴测试结果或运行摘要，作为完成证据。

9. 验收指标与可量化输出

为了避免“看起来做了”，必须定义硬指标。

9.1 投递侧指标

  1. 每回合投递成功率
  2. 窗口校验失败率
  3. 平均投递耗时
  4. 重试次数分布

9.2 协作侧指标

  1. 每回合平均返回时长

  2. 每回合有效信息密度 是否包含交付物清单、测试摘要、变更摘要

  3. 返工率 实现回合后 review 指出需重做的比例

9.3 终局指标

  1. 任务一次通过率
  2. 从需求到可验收交付的总时长
  3. 人工介入次数

10. 风险清单与对策

10.1 最大风险：误投递

对策

  1. 严格窗口标题校验
  2. 每任务固定窗口与固定对话
  3. 投递后截图回传

10.2 权限风险：无障碍滥用

对策

  1. 执行器最小行为集合
  2. 全量审计日志
  3. 失败即停，不做探索性点击

10.3 客户端不可控行为

例如客户端自带快捷键变化、输入框焦点策略不稳定 对策

  1. 为每个客户端建立独立的聚焦策略配置
  2. 配置必须版本化，变更需记录
  3. 每次升级客户端后跑一次投递自检

10.4 系统弹窗拦截

对策

  1. 一旦检测到弹窗存在，立即停止并要求你处理
  2. 不允许执行器尝试点弹窗按钮

11. 分阶段落地计划

阶段 A 最小闭环

  1. 白名单只含一个客户端
  2. 单回合投递与截图证据
  3. 你人工读取回复

验收

  1. 连续 20 次投递无误投
  2. 截图证据完整

阶段 B 双客户端回合制

  1. Codex 实现回合
  2. Claude review 回合
  3. Coordinator 汇总回合

验收

  1. 连续 10 个任务完成
  2. 返工率与误投为零或可接受

阶段 C 会话路由与多任务隔离

  1. 支持多个 task_id 并行
  2. 强制任务与窗口绑定
  3. 证据仓库可检索回放

验收

  1. 多任务并行无串线
  2. 证据链可回放复盘

阶段 D 与 AGN 主方案并行治理

  1. 明确何时走 UI Relay，何时走 AGN 工具链
  2. 定义自动回退条件 例如 CLI 掉线或授权失败时走 UI Relay

验收

  1. 复杂任务仍可用主方案完成
  2. 主方案故障时能平滑切换

12. 结论

  1. 一个可控的“文字协作总线”，把多模型协作从系统集成问题降级为投递可靠性问题。
  2. Coordinator 角色极度简化，只做调度与写任务。
  3. 执行器权限集中且可审计，降低“模型越界”的系统性风险。
  4. 可与 AGN 现有方案并行，既能快速跑起来，也保留长期自动化演进空间。

如果你认可这套规划，下一步我会把它收敛成一份可直接放进 AGN 文档体系的规范稿，包含：术语表、协议字段定义表、失败码定义、验收清单与阶段门禁规则。