# Arkme → Codex 自动派发：本机界面试用与云端增补

日期：2026-09-30，最后补充：2026-10-01。状态：**交互方向已确认；开发原生程序已在专用对话验证输入和排队，独立助手接单及 Arkme 闭环尚未完成，云端下发接口尚未提供。本文不是已上线说明。**

## 1. 用户只需要提交一次

用户在 Arkme 的指定 Codex 对话详情输入下一条需求并点击「加入队列」，之后可以离开页面。不要求用户手动切换到 Codex、复制文字或再次按发送。

```text
远端 Arkme 提交
  → 云端持久保存派发请求
  → 来源电脑自动领取
  → 自动定位对应 Codex 对话、检查输入框、通过原生界面提交
  → 读到真实入队/接受证据
  → Arkme 显示确认结果
```

界面切换发生在运行 Codex 的来源电脑，不是用户提交需求的另一台电脑或手机。本机辅助服务需要持续运行；不能依赖本次开发对话中的电脑使用工具充当产品后台。

最初只支持「本人账号 → 本人明确授权的来源电脑 → 已有且准确绑定的 Codex 对话」。团队成员可以查看动态，不因此获得派发权限；暂不实现指挥其他成员电脑、创建新对话、多选转派或附件。

## 2. 现有接口不能承担下发

同事返回的 `team-codex-integration-guide.md` 只有：

- `/api/v1/team-codex/sync`：上传已发生的任务及事件。
- `/api/v1/team-codex/tasks/list`：读取任务。
- `/api/v1/team-codex/events/list`：读取事件正文。

`kind` 仅有 `UserPromptSubmit / Interrupt / Stop`，没有派发指令。不得把用户需求伪造成已发生的 `UserPromptSubmit`，也不得执行从同步正文中解析出的命令。上传缓冲、Arkme 待派发列表、Codex 原生待执行队列是三种不同状态。

## 3. 最小云端增补能力

复用现有登录、账号、团队、source_id 和 task_id，不建设另一套项目或团队系统。以下是待后端回传的语义，路径只是建议，客户端尚未调用。

| 能力 | 建议接口 | 必须返回/保证 |
| --- | --- | --- |
| 来源控制授权 | 复用现有设备授权；若没有，新增 `sources/control` | 本人在来源电脑显式开启；绑定 owner/team/source，返回可撤销的来源执行凭据或等效认证；其他查看端不能仅凭 source_id 冒领指令 |
| 提交需求 | `commands/create` | 原子持久化、幂等 request_id、状态和版本；不能返回「已入队 Codex」 |
| 来源领取 | `commands/claim` | 仅匹配本人授权来源；原子领取、同一请求只交给一个执行者；返回请求固定归属与正文 |
| 执行回执 | `commands/report` | 有条件推进状态，幂等回执；记录真实接受证据或明确的等待/失败原因 |
| 查看结果 | `commands/list` | 本人按任务查询、分页，返回最新状态；提交页面关闭后仍可查询 |

建议统一前缀 `/api/v1/team-codex/`。轮询即可，不要求 WebSocket。接口可以按后端既有风格合并，但以上行为不能省略。

提交载荷的最小字段：

```json
{
  "expected_owner_ref": "7",
  "team_ref": "101",
  "source_id": "11111111-1111-4111-8111-111111111111",
  "task_id": "22222222-2222-4222-8222-222222222222",
  "request_id": "33333333-3333-4333-8333-333333333333",
  "delivery": "queue",
  "text": "示例：本轮完成后检查输入框布局。"
}
```

以上全部为虚构数据。账号和团队沿用返回契约的数字 ID 字符串；不能发送 `arkme_cn` 作为 team_ref。source/task/request 使用持久 UUID。

- owner 从登录主体取得；expected_owner_ref 只用于防切号。服务端核对 task 的 owner/team/source 对应关系与当前权限。
- request_id 在点击提交时生成并保存。网络重试复用；同 ID 同载荷返回已有结果，同 ID 不同载荷返回冲突。两次主动提交相同文字是两个请求，不能按正文去重。
- 首版仅接受纯文本、`delivery=queue`；建议限制 16 KiB UTF-8，超限明确拒绝，不能截断后执行。不接收任意 shell、文件路径、URL 导航或快捷键指令。
- 来源执行认证独立于 source_id，凭据不放进复制给 Codex 的说明、页面或普通日志。开启上传不等于开启远程输入。
- 来源退出 Arkme、切账号、切团队、暂停授权或失去团队权限时，停止领取和提交；旧请求保留原归属，不能自动发到另一账号、电脑或同名任务。
- 同一来源只能有一个界面执行器，避免多个对话同时抢前台、串输入框。来源授权/独占机制由后端回传明确方案。
- 未开始界面提交的离线请求建议 24 小时到期；最终时限由后端确认。已经开始提交但结果不明的请求必须保留待核对状态，不因到期重新执行。

## 4. 状态与“不重复发送”规则

```text
pending（云端已保存）
  → claimed（来源已领取）
  → waiting（锁屏、草稿、用户正在输入等；尚未提交）
  → submitting（已记录提交意图，开始可能产生副作用的步骤）
  → queued_confirmed / accepted_confirmed / unknown / failed
```

- `pending / claimed / waiting` 不能显示为「Codex 已入队」。
- 忙碌时必须明确采用下一轮排队，不误用 steer。空闲时 Codex 可能直接接受并开始执行，此时显示「Codex 已接受」，不伪造一个不存在的队列位置。
- `queued_confirmed` 需匹配目标对话及本次新出现的原生队列条目；`accepted_confirmed` 需可靠的本轮接受证据。不能只看输入框清空、正文相同或本地 HTTP 200。
- 在可能触发提交前，本地先持久记录 submitting；云端也要完成对应状态确认。回执丢失只重传回执，不能重按发送。
- 一旦可能已经提交却拿不到结果，转 `unknown`（送达结果待确认），禁止自动重发；来源崩溃或领取租约到期也不能把 submitting/unknown 直接变回可重派发。
- 来源重启后先核对原提交记录与原生证据。无法确认时保留 unknown，允许用户看到原因；不得宣称 GUI 路径具备严格 exactly-once。
- 未开始副作用的 claimed/waiting 才能在确认旧执行者失效后重新领取；租约、执行器标识和状态版本必须共同防止旧执行者继续发送。
- 派发成功不代表任务完成。未取得 request_id → turn_id 的可靠关联时，不根据最后一条 Stop 将该派发标为已完成。

## 5. 本机原生界面适配边界

1. 用户在来源电脑一次性开启此功能，并在系统要求时亲自授权辅助功能。不得自动关闭审批或绕过系统权限、锁屏。
2. 确认来源电脑醒着、桌面已解锁、Codex 可用。界面控制不可用时保留请求并说明原因，不能盲按坐标。
3. 由既有本地任务映射解析准确的 Codex 对话 ID；不用相同标题或路径猜目标，不允许云端任意指定打开 URL。
4. 打开后再次核对对话身份和原生输入框。若对话身份无法可靠验证，停止发送。不得误用当前前台对话。
5. 发现已有草稿、附件或用户正在输入时等待，不覆盖、清空或发送用户草稿。输入和提交之间再次检查焦点/目标；失去控制时停止。
6. 保持用户的默认 follow-up 设置，只使用经当前版本实测的单次排队操作。不能把 CLI 的快捷键直接套给桌面端。
7. 使用原生输入框提交，不直接修改 Codex 的队列数据库或全局状态文件。不启动第二个 app-server 并假称控制到了当前桌面队列。
8. 尽量在成功后恢复原前台窗口；若用户已主动操作，不再次抢焦点。此模式会短暂占用前台，不宣传为无感后台接口。

官方行为依据：[Queue 与 Steer](https://learn.chatgpt.com/docs/prompting#steering-and-queuing)。官方说明证明两种行为存在，不证明 Arkme 已能自动控制当前安装版本。

## 6. 实现与验收顺序

### A. 本机可行性门槛（先做）

在用户指定的测试对话中，用无业务副作用的测试内容验证：准确定位、保留草稿、忙碌时排队、空闲时接受、前台恢复、读取确认。不能把开发者在聊天工具中手动代发一次视为 Arkme 独立运行成功。

2026-09-30 本轮检查结果：当前开发会话的电脑使用通道在 `getState`、选择 Codex 时反复初始化超时；最后返回等待 Codex app-server initialize 超时。未读到原生输入框，未发送测试请求，未变更系统权限、Codex 配置或队列。**只能确认开发验证通道不可用，不能断言是辅助功能未授权，也不能断言独立本机辅助程序不可行。**

门槛通过前不开放会产生真实输入的正式入口。先恢复验证通道并完成此项，再连接 Arkme UI。

2026-09-30 22:56 增补：已开发独立 Swift/macOS 只读验证助手，源码和构建说明位于 `tools/codex-companion/`。开发进程下可通过原生辅助功能 API 读取窗口与输入区域，不再依赖前述超时的开发工具；但通过 macOS Launch Services 独立启动后，助手自身的辅助功能权限为未授权。当前对话 ID 也尚未从窗口结构可靠取得。**原生只读探测有进展，不代表独立自动入队已经跑通。** 下一步需用户为助手授权，并明确允许专用测试对话；现有业务对话未输入或发送任何测试消息，未安装常驻服务。

2026-10-01 00:24 增补：授权引导已按确认方案更新，macOS 27 使用本机实测名称「设备控制和数据访问」，旧版本保留「辅助功能」；直达按钮已实际跳转到正确页面，另提供精确路径与访达定位兜底。返回应用时自动检查真实权限，不把跳转成功或授权成功混同为原生入队就绪。只验证了界面、跳转与状态逻辑，没有替用户切换系统权限或发送测试需求。

### B. 本机 Arkme 闭环

2026-10-01 本机可行性增补：固定位置的独立只读助手已经由用户重新授权，系统检查与弹窗状态一致。另在用户明确授权创建的专用对话中，开发原生测试程序完成了 UUID 深链核对、原生输入、空闲发送、忙碌排队、读取真实队列条目和后续回复；已有草稿、错误 UUID、重复提交意图均被拒绝。此证据证明原生 UI 路径可行，**不代表当前独立助手已经能够自动接单，也不代表本机 Arkme 或跨电脑链路完成**。详见 `tools/codex-companion/README.md`；已授权助手未被新构建覆盖。

沿用独立 3100 预览，输入框下明确「仅本机验证」。请求与回执本地持久化，刷新/退出页面不丢请求；重启后不重复发送。未接云端前，另一电脑不能靠这个版本远程派发。

2026-10-01 01:12 开发进度：本机请求日志、执行协调接口、简约输入框组件与候选原生输入适配器已编写，尚未把它们装配到 3100 或真实 Host。新助手 0.0.3 集成了仅面向用户已批准专用对话的固定文字测试入口，构建通过；独立 `doctor` 确认为未授权，因此未进行新包真实发送，原来已授权的助手也未覆盖。下一步须完成新助手独立授权和输入回归，再接入本机派发。测试夹具/纯策略通过不能写成「Arkme 本机闭环已完成」。

2026-10-01 后续交互确认：不修改已安装的 Arkme 客户端，采用单独安装并授权的原生助手。插件先展示底部输入入口，点击打开「连接 Codex 助手」说明。当前固定为 `integration_pending`，没有提交回调，不创建请求、不探测或修改系统权限；不把「记录已同步」当作「可控制」。本人其他电脑的任务提示云端派发未接通，同事任务仅可阅读。说明弹窗不提供尚不存在的下载链接、虚假连接检查或自动输入开关。正式本机接单能力完成后，才能替换为真实安装、授权、绑定及启用流程。旧的 01:12 检查点仅为历史记录，不能作为后续输入框是否可见的判断依据。

### C. 后端接口到位后的跨电脑验收

- 电脑 B 提交给电脑 A 的已有任务，关闭 B 页面，A 自动处理，B 重开可看到真实确认。
- A 忙碌时进入正确对话的后续队列；A 空闲时确认已接受。两种行为分别验收。
- 锁屏/离线等待、恢复后处理未过期请求；有草稿不覆盖，用户输入时不抢键盘。
- 双击、HTTP 超时、进程重启、多个执行器、ACK 丢失、同文多请求，不重复、不串任务。
- 换账号、切团队、撤销来源控制、退组、其他成员尝试派发均被正确隔离。
- 提交临界点断线/崩溃时显示 unknown，不静默重复；原生已执行但队列中消失不当作失败重发。

本机单元测试、模拟界面成功、开发工具代操作、真实本机端到端、真实跨电脑端到端分别记录，不相互替代。