# Codex 常驻会话桥接说明

创建人员：Codex  
文件职责：说明如何把管理系统消息发送到常驻 Codex 会话。  
管理规范/模板：../../全局规范.md；../ai-workplace/AI工作空间创建指南.md。  
引用文件：agents.example.json；send-codex-message.ps1。  
记录方式：工具说明文档；桥接协议或使用方式变化时追加更新。

## 1. 目标

本目录用于验证和沉淀一种桥接方式：

```text
管理系统 / 脚本
-> Codex app-server WebSocket / JSON-RPC
-> 指定 thread
-> 常驻 Codex TUI 或后台会话
```

目标不是每次调用 `codex exec` 新起一个会话，而是向已经登记的 `thread_id` 发消息。

## 2. 当前前置条件

必须先有一个可连接的 Codex app-server：

```powershell
codex.cmd app-server --listen ws://127.0.0.1:4567
```

并且目标观察员窗口应连接到同一个 app-server，或至少目标 `thread_id` 已经在该 app-server 可恢复。

如果 app-server 没有监听，`send-codex-message.ps1` 会 fail-fast，不会假装发送成功。

## 3. Agent 注册表

参考 `agents.example.json` 创建项目自己的注册表，建议放在：

```text
D:/manage_system/data/codex-bridge/agents.json
```

关键字段：

| 字段 | 说明 |
|---|---|
| `server_url` | Codex app-server WebSocket 地址 |
| `thread_id` | 目标 Codex thread id；为空时脚本可创建新 thread |
| `cwd` | 该 agent 默认工作目录 |
| `model` | 可选；发 turn 时覆盖模型 |
| `approval_policy` | 可选；默认建议 `never` |
| `sandbox` | 可选；默认按 thread 原设置 |

## 4. 发送消息

```powershell
.\send-codex-message.ps1 `
  -Agent observer `
  -Message "你按 ag 检查最近实验，有问题全部报给我"
```

指定注册表：

```powershell
.\send-codex-message.ps1 `
  -RegistryPath D:/manage_system/data/codex-bridge/agents.json `
  -Agent observer `
  -Message "桥接测试：回复 OK"
```

如果没有 `thread_id`，允许创建新 thread：

```powershell
.\send-codex-message.ps1 -Agent observer -Message "初始化观察员" -CreateThreadIfMissing
```

## 5. 已知限制

1. 本工具依赖 Codex app-server 的实验协议，协议可能随 Codex CLI 版本变化。
2. 当前脚本只实现 WebSocket JSON-RPC 路径，不使用键盘模拟。
3. `codex.cmd app-server --listen ws://...` 在部分环境下可能进程存在但端口未监听，遇到这种情况应先解决 app-server 启动问题。
4. 不建议把消息发到没有队列锁的同一个 thread；同一时间同一 thread 最好只跑一个 turn。