跳到主要内容
AI教程

Jev GUI Delegate 教程：让 Codex 委派 Windows 与 Chrome GUI 操作

本教程介绍如何在 Windows 上安装 Jev GUI Delegate、运行离线测试、接入 Codex，并理解任务契约、确定性匹配、Jev 语义选择、结果核验与故障恢复机制。

AI我搜编辑部阅读约 10 分钟
Jev GUI Delegate 教程：让 Codex 委派 Windows 与 Chrome GUI 操作

项目概览

Jev GUI Delegate 是一个面向 Codex 的 Windows 与 Chrome GUI 委派原型。主模型负责给出任务目标和验收条件，本地控制器负责观察界面、匹配控件、执行动作，并在每一步检查实际结果。只有遇到无法通过确定性规则处理的语义选择时，控制器才会调用 TypeSafe Jev。

它要解决的核心问题是：如果主模型逐步操作网页或桌面应用，就需要反复读取界面、选择控件并处理工具返回，形成成本较高的操作循环。Jev GUI Delegate 将一段能够明确验收的操作交给本地控制器连续执行，同时保留状态检查、异常恢复和用户接管能力。

该项目是个人设计、借助 AI 实现并持续验收的原型。任务契约、工具编排、恢复机制、权限检查、测试和反馈迭代属于项目贡献；Jev 模型、TypeSafe SDK、Codex 与浏览器插件属于上游产品。

工作流程

  1. Codex 主模型提交目标与验收条件。

  2. 任务被整理为可检查的本地任务契约。

  3. 控制器观察当前界面并尝试确定性控件匹配。

  4. 无法直接判断时，控制器调用 Jev 进行语义选择。

  5. Chrome 操作通过宿主提供的官方浏览器会话执行，Windows 操作通过 UI Automation 执行。

  6. 控制器验证实际结果、保存进度，并决定继续、恢复、暂停，或要求主模型补充信息。

这个流程不会复制个人浏览器配置，也不会提取 Cookie。Chrome 路径依赖 Codex 宿主提供的兼容官方浏览器会话 API，仓库本身不能创建或替代该会话。

关键功能

两条 GUI 执行路径

  • Chrome：复用宿主提供的官方浏览器会话。

  • Windows：使用 Windows UI Automation 操作可访问的桌面控件。

显式任务契约

任务契约会明确描述目标、允许动作、操作范围、所需输入、执行步骤和成功条件。控制器因此可以在执行前检查权限与范围，在执行后依据成功条件判断任务是否真正完成。

按需调用 Jev

能够通过本地规则确定的控件由代码直接匹配；需要理解文本含义或候选项语义时才调用 Jev。项目会按实际情况记录零模型调用，不会将其错误计为一次成功的 Jev 推理。

连续执行与恢复

控制器可以保存执行进度，并处理缺少输入、局部选择错误、暂停、取消与用户接管等情况。如果提交动作是否成功无法确认，它不会自动重放提交，以降低重复提交带来的风险。

结果与安全检查

系统会在操作前核对身份、授权和范围，在操作后检查实际值或页面状态。模型使用量与失败原因会分别记录，便于区分成本问题和执行问题。

运行环境与前置条件

项目面向以下环境：

  • Windows x64

  • Python 3.12

  • Node.js

  • 用于原生 GUI 操作的交互式桌面

  • 如需使用 Chrome 路径，还要有 Codex 宿主提供的兼容官方浏览器会话 API

建议将项目安装到 C:\jev\jev-bridge。部分历史命令和 Codex skill 示例默认使用该位置。如果选择其他目录，需要同步修改相关示例和配置。

安装项目

第一步：克隆仓库并创建虚拟环境

git clone https://github.com/YUTA-fywoo/jev-gui-delegate.git C:\jev\jev-bridge
cd C:\jev\jev-bridge
py -3.12 -m venv .venv

第二步：安装锁定依赖

.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements.lock

--require-hashes 会依据锁定文件中的哈希安装依赖，有助于确保安装内容与项目记录一致。第三方依赖目录不会随仓库公开，应从原始发行渠道安装。

第三步：准备运行时

.\.venv\Scripts\python.exe scripts/setup-runtime.py

第四步：运行离线测试

.\.venv\Scripts\python.exe -m unittest discover -s gui_delegate/tests -p "test_*.py"

这些测试覆盖控制器、恢复流程和边界条件。离线回归使用合成数据与受控替身，不等同于现场 GUI 操作，也不会冒充实时 Jev 请求。更完整的结果应参考仓库中的 发布验证文档。

配置 Jev 密钥

密钥可以由本机环境变量 TYPESAFE_API_KEY 或 Windows 凭据管理器提供。项目建议使用 set-key.cmd 打开的本地输入窗口进行设置。

set-key.cmd

不要把密钥写入 Git 仓库、任务契约或聊天内容。安装者本机生成的 chrome-runtime.json 已被忽略，仓库不会携带原作者机器上的环境路径。

注册到 Codex

需要将项目接入 Codex 时，在项目目录运行以下安装脚本：

install.cmd
gui-install.cmd

安装器会修改用户级 MCP、skill 和路由配置，同时保留备份并检查冲突。如果机器上已经存在同名目录，应先检查其用途；安装器不会直接覆盖本机正在使用的项目。

可安装的个人 Codex skill 位于 gui_delegate/skill/SKILL.md。如果项目没有安装在默认目录，还应检查其中涉及路径的示例。

基本使用与验证

检查本地就绪状态

安装后可以运行：

health.cmd

health.cmd 只检查组件是否就绪，不代表已执行实时 Jev 验证，也不代表当前机器已经通过真实 GUI 场景验收。

执行实时验证

项目提供的 verify.cmd 等实时验证流程会调用 Jev 服务：

verify.cmd

运行前应确认密钥已经正确配置，并区分离线回归结果与实时服务结果。README 没有将历史开发环境中的“本机已验证”视为所有安装者都能直接继承的结论。

设计一个适合委派的任务

这个原型适合边界清楚、步骤可限定、结果可检查的 GUI 操作。向控制器交付任务时，应至少明确以下内容：

  • 目标：最终需要达到什么状态。

  • 范围：允许在哪些页面、窗口或对象内操作。

  • 允许动作：控制器可以执行哪些类型的交互。

  • 输入：执行任务必需且允许使用的数据。

  • 步骤：可以连续执行的操作阶段。

  • 成功条件：完成后应观察到的实际值或页面状态。

例如，一个任务可以要求控制器在指定页面范围内查找目标控件、填写已授权的输入，并通过页面状态确认结果。具体契约字段和结果模型应以 gui_delegate/schema.py 中的实现为准，不应自行假设 README 未定义的格式。

源码阅读路线

如果需要理解执行机制或进行二次开发，可以按以下顺序阅读：

  1. gui_delegate/schema.py：理解任务契约、状态和结果模型。

  2. gui_delegate/controller.py：查看控制器如何组织执行循环。

  3. gui_delegate/drivers.py：了解驱动和结构化界面观察。

  4. gui_delegate/security.py：查看范围、授权和输入检查。

  5. gui_delegate/chrome_gateway.mjs：理解官方浏览器会话入口。

  6. jev_client.py：查看 Jev SDK 封装、版本检查和使用量记录。

  7. gui_delegate/tests：通过测试理解恢复逻辑与边界行为。

进阶使用建议

优先使用确定性匹配

如果控件能够通过稳定属性或结构化信息识别，应优先交给本地代码匹配。只有需要语义判断时才调用 Jev，这既符合项目设计，也便于准确记录模型使用量。

为每一步设置可观察结果

不要只定义“点击按钮”这类动作，还应定义点击后预期出现的值、控件状态或页面变化。项目强调核对实际结果，而不是把工具调用成功直接当作任务成功。

谨慎处理提交类动作

如果提交后结果不明确，不要假定失败并自动重复操作。该项目明确避免在结果不明时自动重放提交。遇到此类状态，更适合暂停、保存进度并交由用户或主模型确认。

将缺少输入与选择错误分开处理

缺少必要输入时，应补充输入后继续；只有局部语义选择错误时，才针对该选择进行修复。这样可以避免从头重跑任务，也能保留已经验证过的进度。

升级 Jev 版本后重新验证

当前 settings.json 固定的是历史测试所用的 jev-1.13.0。服务端版本变化后，应重新进行核验并更新配置，不能把旧版本的测试结果当作新版本的质量保证。示例策略也不表示当前机器已经完成校准。

正确理解基准测试

README 记录了 2026 年 9 月 23 日的两轮合成任务测试。每轮包含相同的 4 项任务和 24 个动作，两组任务均完成 4/4。

  • 第一轮中，Astra token 从 2,266,693 降至 236,295，减少 89.6%，端到端任务速率为基线的 3.05 倍。

  • 第二轮中，Astra token 从 2,256,091 降至 192,752，减少 91.5%，端到端任务速率为基线的 3.53 倍。

这里的 Astra token 包含缓存输入，Jev 的额外用量另行统计。两轮重复的是相同四项任务，并不代表八种独立场景；这些数字也不是账单节省比例，更不能证明所有应用、任意任务或部署环境都会获得相同结果。早期三任务版本的非缓存 token 结果并未改善，详细范围应查看 测试说明。

已知限制

  • 原型依赖可读取的 DOM 或辅助功能信息。

  • Canvas、图像理解、安全桌面和部分跨框架控件可能无法直接处理。

  • 宿主没有开放的功能可能需要主模型补充处理。

  • Chrome 路径不能脱离兼容的宿主官方会话独立运行。

  • 历史机器验证记录不等于新安装环境已经通过验收。

  • 运行日志、浏览器配置、密钥、个人任务材料、机器安装状态和回滚包没有公开。

总结

Jev GUI Delegate 将可验收的 GUI 操作从主模型的逐步循环中分离出来，由本地控制器完成确定性匹配、按需语义选择、状态验证和故障恢复。安装时应先完成锁定依赖、运行时设置与离线测试，再配置密钥并接入 Codex。实际使用中，清晰的任务范围、可观察的成功条件、谨慎的提交恢复策略和版本变更后的重新验证，是获得可靠结果的关键。

进一步了解上游组件，可访问 TypeSafe 文档、MCP Python SDK 和 pywinauto。