docs: add comprehensive planning for unimplemented features
- Add roadmap for 4 phases of feature implementation - Phase 1: AI Gateway enhancements (P0, 1-2 weeks) - Phase 2: OpenClaw task scheduling (P1, 2-3 weeks) - Phase 3: OpenClaw long-term memory (P1, 2-3 weeks) - Phase 4: Codex FFI Rust embedded mode (P2, 4-6 weeks) - Include task breakdown, acceptance criteria, and success metrics - Add dependencies, milestones, and resource requirements - Document risks and mitigation strategies
This commit is contained in:
Haitao Pan
parent
32b7aac1a7
commit
9e797eab40
332
docs/planning/xworkmate-unfinished-features-roadmap.md
Normal file
332
docs/planning/xworkmate-unfinished-features-roadmap.md
Normal file
@ -0,0 +1,332 @@
|
||||
# XWorkmate 待实现功能详细规划
|
||||
|
||||
**文档版本:** v1.0
|
||||
**规划日期:** 2026-03-14
|
||||
**负责人:** TBD
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
基于当前 Codex 集成状态分析，本文档规划三个未实现核心功能的详细实现路径：
|
||||
|
||||
1. **Phase 1: AI Gateway 增强功能** (短期 - 1-2 周)
|
||||
2. **Phase 2: OpenClaw 任务调度集成** (中期 - 2-3 周)
|
||||
3. **Phase 3: OpenClaw 远期记忆集成** (中期 - 2-3 周)
|
||||
4. **Phase 4: Codex FFI Rust 嵌入模式** (长期 - 4-6 周)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: AI Gateway 增强功能 (P0 - 高优先级)
|
||||
|
||||
### 目标
|
||||
增强现有 AI Gateway 集成，提升用户体验和稳定性。
|
||||
|
||||
### 任务列表
|
||||
|
||||
#### 任务 1.1: 模型缓存机制
|
||||
- **工作量:** 2-3 天
|
||||
- **子任务:**
|
||||
- [ ] 在 `RuntimeModelsController` 中添加模型缓存
|
||||
- [ ] 实现 LRU 缓存策略
|
||||
- [ ] 缓存 TTL 设置 (24小时)
|
||||
- [ ] 缓存失效机制 (配置变更时)
|
||||
- **验收标准:**
|
||||
- 模型列表从本地缓存加载速度 < 100ms
|
||||
- 缓存命中率 > 90%
|
||||
|
||||
#### 任务 1.2: 多模型并发支持
|
||||
- **工作量:** 2-3 天
|
||||
- **子任务:**
|
||||
- [ ] 支持多 Provider 配置
|
||||
- [ ] 实现模型优先级机制
|
||||
- [ ] 实现 fallback 逻辑
|
||||
- [ ] 添加模型健康检查
|
||||
- **验收标准:**
|
||||
- 主模型失败后自动切换 < 3s
|
||||
- 支持最多 5 个备用模型
|
||||
|
||||
#### 任务 1.3: 流式响应支持
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 扩展 `CodexEvent` 支持流式事件
|
||||
- [ ] 实现 SSE 解析
|
||||
- [ ] UI 流式显示
|
||||
- **验收标准:**
|
||||
- 流式响应延迟 < 1s
|
||||
- 支持 1000 token/s 输出
|
||||
|
||||
#### 任务 1.4: 错误重试机制
|
||||
- **工作量:** 2 天
|
||||
- **子任务:**
|
||||
- [ ] 指数退避重试策略
|
||||
- [ ] 区分可重试和不可重试错误
|
||||
- [ ] 重试次数配置
|
||||
- **验收标准:**
|
||||
- 网络错误自动重试最多 3 次
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: OpenClaw 任务调度集成 (P1 - 中优先级)
|
||||
|
||||
### 目标
|
||||
实现与 OpenClaw Gateway 的任务调度集成，支持定时任务和后台执行。
|
||||
|
||||
### 任务列表
|
||||
|
||||
#### 任务 2.1: 任务调度 API 实现
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 实现 `scheduleTask()`
|
||||
- [ ] 实现 `listScheduledTasks()`
|
||||
- [ ] 实现 `deleteScheduledTask()`
|
||||
- [ ] 实现 `getTaskStatus()`
|
||||
- **验收标准:**
|
||||
- 支持标准 cron 表达式
|
||||
- 任务执行延迟 < 5s
|
||||
|
||||
#### 任务 2.2: 任务管理 UI
|
||||
- **工作量:** 4-5 天
|
||||
- **子任务:**
|
||||
- [ ] 创建任务列表页面
|
||||
- [ ] 任务创建对话框
|
||||
- [ ] 任务详情页面
|
||||
- [ ] Cron 表达式编辑器
|
||||
- **验收标准:**
|
||||
- UI 响应时间 < 200ms
|
||||
- Cron 实时验证
|
||||
|
||||
#### 任务 2.3: 任务执行监控
|
||||
- **工作量:** 2-3 天
|
||||
- **子任务:**
|
||||
- [ ] 实时执行状态更新
|
||||
- [ ] 执行日志流
|
||||
- [ ] 失败任务告警
|
||||
- **验收标准:**
|
||||
- 执行状态延迟 < 1s
|
||||
- 失败告警 < 5s
|
||||
|
||||
#### 任务 2.4: 后端集成
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 与 OpenClaw Gateway 团队协调 API
|
||||
- [ ] 定义任务 payload 规范
|
||||
- [ ] 测试任务创建和执行
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: OpenClaw 远期记忆集成 (P1 - 中优先级)
|
||||
|
||||
### 目标
|
||||
实现跨设备的长期记忆功能，支持记忆存储和检索。
|
||||
|
||||
### 任务列表
|
||||
|
||||
#### 任务 3.1: 记忆 API 实现
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 实现 `storeMemory()`
|
||||
- [ ] 实现 `retrieveMemory()`
|
||||
- [ ] 实现 `listMemoryKeys()`
|
||||
- [ ] 实现 `deleteMemory()`
|
||||
- [ ] 批量操作支持
|
||||
- **验收标准:**
|
||||
- 单条记忆存储 < 100ms
|
||||
- 支持 TTL 过期
|
||||
|
||||
#### 任务 3.2: 记忆管理 UI
|
||||
- **工作量:** 4-5 天
|
||||
- **子任务:**
|
||||
- [ ] 记忆列表页面
|
||||
- [ ] 记忆创建/编辑对话框
|
||||
- [ ] 记忆搜索功能
|
||||
- [ ] 记忆导出/导入
|
||||
- **验收标准:**
|
||||
- 搜索响应时间 < 500ms
|
||||
- 导出 < 1GB 数据 < 5s
|
||||
|
||||
#### 任务 3.3: 自动记忆管理
|
||||
- **工作量:** 2-3 天
|
||||
- **子任务:**
|
||||
- [ ] 重要对话自动保存
|
||||
- [ ] 记忆过期清理
|
||||
- [ ] 记忆使用统计
|
||||
- **验收标准:**
|
||||
- 自动保存成功率 > 90%
|
||||
|
||||
#### 任务 3.4: 后端集成
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 与 OpenClaw Gateway 团队协调 API
|
||||
- [ ] 定义记忆数据结构
|
||||
- [ ] 测试存储和检索
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Codex FFI Rust 嵌入模式 (P2 - 低优先级)
|
||||
|
||||
### 目标
|
||||
实现真正的嵌入式 Codex Rust FFI，替代外部 CLI 模式。
|
||||
|
||||
### 任务列表
|
||||
|
||||
#### 任务 4.1: Rust 进程管理
|
||||
- **工作量:** 7-10 天
|
||||
- **子任务:**
|
||||
- [ ] 实现 `ProcessManager`
|
||||
- [ ] 实现 `StdioHandler`
|
||||
- [ ] 信号处理
|
||||
- **验收标准:**
|
||||
- 进程启动 < 100ms
|
||||
- 崩溃恢复 < 10s
|
||||
|
||||
#### 任务 4.2: 异步消息队列
|
||||
- **工作量:** 5-7 天
|
||||
- **子任务:**
|
||||
- [ ] 实现 `MessageQueue`
|
||||
- [ ] 实现 `EventStream`
|
||||
- [ ] FFI 接口
|
||||
- **验收标准:**
|
||||
- 消息吞吐 > 1000 msg/s
|
||||
- 事件延迟 < 10ms
|
||||
|
||||
#### 任务 4.3: 文件系统操作
|
||||
- **工作量:** 5-7 天
|
||||
- **子任务:**
|
||||
- [ ] 实现 `CodexFileSystem`
|
||||
- [ ] 沙箱实现
|
||||
- [ ] FFI 接口
|
||||
- **验收标准:**
|
||||
- 文件操作延迟 < 50ms
|
||||
- 沙箱规则 100% 有效
|
||||
|
||||
#### 任务 4.4: Codex CLI 集成
|
||||
- **工作量:** 7-10 天
|
||||
- **子任务:**
|
||||
- [ ] 集成 Codex CLI 作为 Rust crate
|
||||
- [ ] 实现 JSON-RPC 服务器
|
||||
- [ ] 对话管理和执行引擎
|
||||
|
||||
#### 任务 4.5: Dart FFI 绑定
|
||||
- **工作量:** 3-4 天
|
||||
- **子任务:**
|
||||
- [ ] 更新 `codex_ffi_bindings.dart`
|
||||
- [ ] 重构 `CodexRuntime`
|
||||
- [ ] 测试
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
Phase 1 (AI Gateway 增强)
|
||||
├── 独立实施，无依赖
|
||||
└── 可立即开始
|
||||
|
||||
Phase 2 (任务调度)
|
||||
├── 依赖 OpenClaw Gateway 后端 API
|
||||
└── 依赖 Phase 1 的错误重试机制
|
||||
|
||||
Phase 3 (远期记忆)
|
||||
├── 依赖 OpenClaw Gateway 后端 API
|
||||
└── 可与 Phase 2 并行实施
|
||||
|
||||
Phase 4 (FFI 嵌入)
|
||||
├── 最长期目标
|
||||
└── 需要大量测试
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 里程碑和时间线
|
||||
|
||||
### Sprint 1 (Week 1-2): Phase 1 完成
|
||||
- [x] 模型缓存机制
|
||||
- [x] 多模型并发支持
|
||||
- [x] 流式响应支持
|
||||
- [x] 错误重试机制
|
||||
|
||||
### Sprint 2 (Week 3-5): Phase 2 完成
|
||||
- [ ] 任务调度 API 实现
|
||||
- [ ] 任务管理 UI
|
||||
- [ ] 任务执行监控
|
||||
- [ ] 后端集成测试
|
||||
|
||||
### Sprint 3 (Week 6-8): Phase 3 完成
|
||||
- [ ] 记忆 API 实现
|
||||
- [ ] 记忆管理 UI
|
||||
- [ ] 自动记忆管理
|
||||
- [ ] 后端集成测试
|
||||
|
||||
### Sprint 4 (Week 9-14): Phase 4 完成
|
||||
- [ ] Rust 进程管理
|
||||
- [ ] 异步消息队列
|
||||
- [ ] 文件系统操作
|
||||
- [ ] Codex CLI 集成
|
||||
- [ ] Dart FFI 绑定
|
||||
|
||||
---
|
||||
|
||||
## 资源需求
|
||||
|
||||
### 开发资源
|
||||
- **前端开发 (Dart/Flutter):** 2-3 人
|
||||
- **后端开发 (Rust):** 1-2 人 (Phase 4)
|
||||
- **后端协调:** 0.5 FTE
|
||||
|
||||
### 基础设施
|
||||
- **测试环境:** OpenClaw Gateway 实例
|
||||
- **CI/CD:** 自动化测试和部署
|
||||
- **监控:** 错误跟踪和性能监控
|
||||
|
||||
---
|
||||
|
||||
## 风险和缓解
|
||||
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|----------|
|
||||
| OpenClaw Gateway API 延迟 | 高 | 中 | 与 Gateway 团队紧密协作 |
|
||||
| FFI Rust 复杂度超预期 | 中 | 高 | 阶段性验证，降级到 CLI 模式 |
|
||||
| 资源不足 | 高 | 中 | 优先级排序，分阶段交付 |
|
||||
|
||||
---
|
||||
|
||||
## 成功指标
|
||||
|
||||
### Phase 1
|
||||
- 模型缓存命中率 > 90%
|
||||
- 流式响应延迟 < 1s
|
||||
- 错误自动恢复率 > 95%
|
||||
|
||||
### Phase 2
|
||||
- 任务执行成功率 > 95%
|
||||
- 任务调度延迟 < 5s
|
||||
- 用户满意度 > 4.5/5
|
||||
|
||||
### Phase 3
|
||||
- 记忆存储可靠性 > 99.9%
|
||||
- 记忆检索延迟 < 100ms
|
||||
- 自动保存覆盖率 > 80%
|
||||
|
||||
### Phase 4
|
||||
- FFI 模式性能提升 > 50%
|
||||
- 嵌入模式稳定性 > 99%
|
||||
- 内存占用减少 > 30%
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [XWorkmate 集成架构说明](../architecture/xworkmate-integrations.md)
|
||||
- [Codex FFI 集成状态报告](../reports/codex-ffi-status-report.md)
|
||||
- [Codex 集成 actual 状态](../reports/codex-integration-status-actual.md)
|
||||
|
||||
---
|
||||
|
||||
## 术语表
|
||||
|
||||
- **FFI:** Foreign Function Interface
|
||||
- **JSON-RPC:** JSON Remote Procedure Call
|
||||
- **Cron:** 时间任务调度表达式
|
||||
- **SSE:** Server-Sent Events
|
||||
- **TTL:** Time To Live
|
||||
190
docs/reports/codex-ffi-status-report.md
Normal file
190
docs/reports/codex-ffi-status-report.md
Normal file
@ -0,0 +1,190 @@
|
||||
# Codex Agent FFI 集成状态报告
|
||||
|
||||
## 测试执行时间
|
||||
2026-03-14 10:20
|
||||
|
||||
## FFI 库状态
|
||||
**文件路径:** `/Applications/XWorkmate.app/Contents/Frameworks/libcodex_ffi.dylib`
|
||||
**大小:** 302 KB (ARM64)
|
||||
**架构:** Mach-O 64-bit dynamically linked shared library arm64
|
||||
|
||||
## FFI 函数可用性测试
|
||||
|
||||
### ✅ 可用的 FFI 函数（已导出）
|
||||
|
||||
| 函数名 | 状态 | 说明 |
|
||||
|--------|------|------|
|
||||
| `codex_init()` | ✅ 可用 | 初始化库，返回 0 表示成功 |
|
||||
| `codex_runtime_create()` | ✅ 可用 | 创建运行时实例，返回有效指针 |
|
||||
| `codex_runtime_destroy()` | ✅ 可用 | 销毁运行时实例，清理内存 |
|
||||
| `codex_start_thread()` | ✅ 可用 | 启动线程，返回 ThreadHandle (id=0 表示空句柄) |
|
||||
| `codex_send_message()` | ✅ 可用 | 发送消息，返回 0 表示成功 |
|
||||
| `codex_poll_events()` | ✅ 可用 | 轮询事件，返回 0 (未实现) |
|
||||
| `codex_shutdown()` | ✅ 可用 | 关闭运行时，返回 0 表示成功 |
|
||||
| `codex_last_error()` | ✅ 可用 | 获取最后错误信息 |
|
||||
|
||||
### ❌ 核心功能实现状态
|
||||
|
||||
根据 Rust 源码分析 (`rust/src/lib.rs` 和 `rust/src/runtime.rs`)：
|
||||
|
||||
| 功能 | 实现状态 | 代码位置 |
|
||||
|------|----------|----------|
|
||||
| Codex CLI 进程启动 | ❌ **未实现** | `runtime.rs:235` - `// TODO: Start process` |
|
||||
| 异步消息发送 | ❌ **未实现** | `lib.rs:87` - `// TODO: Implement async message sending` |
|
||||
| 事件轮询机制 | ❌ **未实现** | `lib.rs:108` - `// TODO: Implement event polling` |
|
||||
| 响应流处理 | ❌ **未实现** | 无相关代码 |
|
||||
| 进程停止管理 | ❌ **未实现** | `runtime.rs:247` - `// TODO: Stop process` |
|
||||
| Codex 二进制查找 | ✅ **已实现** | `runtime.rs:202-221` |
|
||||
|
||||
## 对话功能测试结果
|
||||
|
||||
### 测试尝试
|
||||
尝试通过 FFI 发送消息并轮询响应：
|
||||
|
||||
```dart
|
||||
// 1. 创建运行时 ✅
|
||||
runtime = codex_runtime_create(config);
|
||||
// 结果: 成功，返回有效指针
|
||||
|
||||
// 2. 启动线程 ✅
|
||||
thread = codex_start_thread(runtime, cwd);
|
||||
// 结果: 返回 ThreadHandle，但 id=0 (空句柄)
|
||||
|
||||
// 3. 发送消息 ✅
|
||||
result = codex_send_message(runtime, thread, message);
|
||||
// 结果: 返回 0 (成功)，但消息实际上未发送
|
||||
|
||||
// 4. 轮询响应 ❌
|
||||
events = codex_poll_events(runtime, buffer, bufferSize);
|
||||
// 结果: 返回 0 (无事件)
|
||||
// 原因: 未实现事件队列和处理逻辑
|
||||
```
|
||||
|
||||
### 结论
|
||||
**❌ 无法进行真正的 Codex agent 对话**
|
||||
|
||||
原因：
|
||||
1. Codex CLI 进程从未启动
|
||||
2. FFI 函数只是桩代码（stubs），返回预定义值
|
||||
3. 没有实际的消息处理和响应机制
|
||||
4. 事件轮询返回 0，因为没有事件队列
|
||||
|
||||
## 执行功能测试结果
|
||||
|
||||
### 虽拟执行测试
|
||||
尝试通过 FFI 执行类似 "创建文件" 的操作：
|
||||
|
||||
```dart
|
||||
// 发送执行指令
|
||||
codex_send_message(runtime, thread, "Create a file named test.txt");
|
||||
// 结果: 返回 0 (成功)，但:
|
||||
// 1. Codex 进程未启动，无法接收指令
|
||||
// 2. 没有执行管道和输出捕获
|
||||
// 3. 没有文件系统操作的实际代码
|
||||
```
|
||||
|
||||
### 结论
|
||||
**❌ 无法执行任何 Codex agent 操作**
|
||||
|
||||
原因：
|
||||
- 没有进程管理代码
|
||||
- 没有 stdio 管道建立
|
||||
- 没有输出流处理
|
||||
- 没有文件系统操作接口
|
||||
|
||||
## 当前架构评估
|
||||
|
||||
### ✅ 已完成的部分
|
||||
1. **FFI 接口定义** - 所有必要的函数签名已定义
|
||||
2. **内存管理** - Box 智能指针正确用于 FFI 边界
|
||||
3. **类型安全** - Rust Struct 和 Dart FFI 类型对应正确
|
||||
4. **编译构建** - dylib 成功编译并可加载
|
||||
5. **基础测试** - 简单的 FFI 调用可以成功执行
|
||||
|
||||
### ❌ 缺失的关键部分
|
||||
1. **进程管理** - 无子进程启动、监控、停止机制
|
||||
2. **IPC 通信** - 无消息队列、事件通知机制
|
||||
3. **异步处理** - Rust 端无异步代码，Dart 端无回调接口
|
||||
4. **Codex 集成** - 无实际调用 Codex CLI 的代码
|
||||
5. **错误处理** - 所有错误都被忽略，返回固定值
|
||||
|
||||
## 离线模式实际工作原理
|
||||
|
||||
由于 Codex FFI 未完全实现，当前应用在"离线模式"下：
|
||||
|
||||
### 实际使用的是
|
||||
- **Stdio 桥接模式** - 通过 `CodexRuntime` Dart 类直接调用外部 Codex CLI
|
||||
- **外部 CLI 模式** - 启动独立的 `codex` 可执行文件进程，通过 stdin/stdout 通信
|
||||
|
||||
### 不是使用
|
||||
- ❌ 内置 FFI Rust 库 (`libcodex_ffi.dylib`)
|
||||
- ❌ 内存内的 Codex 实现
|
||||
- ❌ Rust 嵌入式 Codex
|
||||
|
||||
## 完整对话和执行的实现路径
|
||||
|
||||
要使 libcodex_ffi.dylib 能够进行真正的对话和执行，需要：
|
||||
|
||||
### 1. Rust 端实现
|
||||
```rust
|
||||
// 需要实现的核心组件：
|
||||
- ProcessManager: 启动/停止 Codex CLI 进程
|
||||
- MessageQueue: 异步消息队列
|
||||
- EventStream: 事件流输出 (响应、日志、错误)
|
||||
- StdioHandler: stdin/stdout/stderr 处理
|
||||
- TaskScheduler: 任务执行调度
|
||||
```
|
||||
|
||||
### 2. FFI 接口扩展
|
||||
```rust
|
||||
// 新增需要的函数：
|
||||
- codex_execute_command() - 执行 shell 命令
|
||||
- codex_read_file() - 读取文件内容
|
||||
- codex_write_file() - 写入文件
|
||||
- codex_list_directory() - 列出目录
|
||||
- codex_get_response() - 获取 AI 响应流
|
||||
```
|
||||
|
||||
### 3. Dart 端实现
|
||||
```dart
|
||||
// 需要实现：
|
||||
- StreamController: 处理响应流
|
||||
- CallbackHandler: Rust 回调转 Dart
|
||||
- ErrorHandler: 错误传播
|
||||
- TimeoutManager: 超时管理
|
||||
```
|
||||
|
||||
## 建议
|
||||
|
||||
### 短期（当前可行）
|
||||
继续使用**外部 CLI 模式**：
|
||||
- 通过 `CodexRuntime.dart` 直接启动 `codex` 可执行文件
|
||||
- 使用 Stdio 进行通信
|
||||
- 不依赖 FFI Rust 库
|
||||
|
||||
### 中期（需要开发）
|
||||
实现基本 FFI 功能：
|
||||
1. 进程管理（启动/停止 Codex）
|
||||
2. 基础消息传递
|
||||
3. 简单响应接收
|
||||
|
||||
### 长期（完整功能）
|
||||
完整 Rust FFI 实现：
|
||||
1. 嵌入式 Codex（无需外部 CLI）
|
||||
2. 异步事件流
|
||||
3. 文件系统操作
|
||||
4. 任务执行和监控
|
||||
|
||||
## 总结
|
||||
|
||||
| 测试项 | 结果 | 说明 |
|
||||
|--------|------|------|
|
||||
| FFI 库加载 | ✅ 通过 | dylib 可正常加载 |
|
||||
| FFI 函数调用 | ✅ 通过 | 所有函数可调用 |
|
||||
| 对话功能 | ❌ 失败 | 未实现，Codex 进程未启动 |
|
||||
| 执行功能 | ❌ 失败 | 未实现，无 IPC 机制 |
|
||||
| 响应接收 | ❌ 失败 | 未实现，无事件流 |
|
||||
|
||||
**当前状态：** libcodex_ffi.dylib 提供了 FFI 接口的**骨架**，但缺乏实现对话和执行所需的**核心逻辑**。
|
||||
|
||||
**实际可用方案：** 应用当前通过外部 Codex CLI（Stdio 模式）在离线模式下运行，不依赖 Rust FFI 库。
|
||||
328
docs/reports/codex-integration-status-actual.md
Normal file
328
docs/reports/codex-integration-status-actual.md
Normal file
@ -0,0 +1,328 @@
|
||||
# XWorkmate Codex 集成实际运行状态分析
|
||||
|
||||
## 分析时间
|
||||
2026-03-14 10:30
|
||||
|
||||
## 1. Codex FFI 调用能力验证
|
||||
|
||||
### ❌ **结论：无法通过 FFI 调用 Codex 进行对话和执行**
|
||||
|
||||
### 实际实现方式
|
||||
|
||||
**CodexRuntime 类使用外部 CLI 模式：**
|
||||
|
||||
```dart
|
||||
lib/runtime/codex_runtime.dart:382
|
||||
_process = await Process.start(
|
||||
codexPath,
|
||||
args, // ['app-server', '--listen', 'stdio://', ...]
|
||||
workingDirectory: cwd,
|
||||
);
|
||||
```
|
||||
|
||||
**工作流程：**
|
||||
|
||||
```
|
||||
XWorkmate (Flutter/Dart)
|
||||
↓
|
||||
CodexRuntime.startStdio()
|
||||
↓
|
||||
Process.start() → 启动外部 'codex' 可执行文件
|
||||
↓
|
||||
Stdio (stdin/stdout/stderr)
|
||||
↓
|
||||
JSON-RPC 通信
|
||||
↓
|
||||
Codex CLI (外部进程)
|
||||
```
|
||||
|
||||
### FFI 库状态
|
||||
|
||||
**libcodex_ffi.dylib 当前状态 - 仅桩代码：**
|
||||
|
||||
| FFI 函数 | 实现 | 说明 |
|
||||
|----------|------|------|
|
||||
| `codex_init()` | ✅ 桩代码 | 返回 0，无实际初始化 |
|
||||
| `codex_runtime_create()` | ✅ 桩代码 | 创建 Box 并返回指针，无进程 |
|
||||
| `codex_start_thread()` | ✅ 桩代码 | 返回 id=0 空句柄 |
|
||||
| `codex_send_message()` | ✅ 桩代码 | 返回 0，未发送消息 |
|
||||
| `codex_poll_events()` | ✅ 桩代码 | 返回 0，无事件队列 |
|
||||
|
||||
**Rust 源码确认：**
|
||||
|
||||
```rust
|
||||
rust/src/lib.rs:87 // TODO: Implement async message sending
|
||||
rust/src/lib.rs:108 // TODO: Implement event polling
|
||||
rust/src/runtime.rs:235 // TODO: Start process
|
||||
rust/src/runtime.rs:247 // TODO: Stop process
|
||||
```
|
||||
|
||||
所有核心功能都有 TODO 标记，未实现。
|
||||
|
||||
## 2. AI Gateway 桥接能力验证
|
||||
|
||||
### ✅ **结论：可以桥接到 AI Gateway 提供的模型**
|
||||
|
||||
### 实现路径
|
||||
|
||||
```
|
||||
XWorkmate 设置
|
||||
↓
|
||||
AI Gateway 配置 (URL、API Key、模型)
|
||||
↓
|
||||
CodexConfigBridge.configureForGateway()
|
||||
↓
|
||||
生成 ~/.codex/config.toml
|
||||
↓
|
||||
[model_providers.xworkmate]
|
||||
base_url = "https://ai.example.com"
|
||||
experimental_bearer_token = "xxx"
|
||||
```
|
||||
|
||||
### 配置代码
|
||||
|
||||
```dart
|
||||
lib/runtime/codex_config_bridge.dart:16
|
||||
Future<void> configureForGateway({
|
||||
required String gatewayUrl,
|
||||
required String apiKey,
|
||||
String providerName = 'xworkmate',
|
||||
String defaultModel = 'gpt-4.1',
|
||||
...
|
||||
})
|
||||
```
|
||||
|
||||
### 实际工作流程
|
||||
|
||||
```
|
||||
1. 用户在设置中配置 AI Gateway
|
||||
- Gateway URL: https://ai.example.com
|
||||
- API Key: sk-xxx
|
||||
- 选择模型: gpt-4.1, gpt-4-mini, ...
|
||||
|
||||
2. 调用配置桥接
|
||||
await _runtimeCoordinator.configureCodexForGateway(
|
||||
gatewayUrl: gatewayUrl,
|
||||
apiKey: apiKey,
|
||||
);
|
||||
|
||||
3. 生成 Codex 配置文件
|
||||
~/.codex/config.toml 包含：
|
||||
- [model_providers.xworkmate]
|
||||
- base_url
|
||||
- experimental_bearer_token
|
||||
|
||||
4. 启动 Codex 外部 CLI
|
||||
Codex CLI 读取配置文件
|
||||
使用 AI Gateway 作为模型提供方
|
||||
所有 AI 调用通过 AI Gateway 代理
|
||||
```
|
||||
|
||||
### 支持的 AI Gateway 功能
|
||||
|
||||
| 功能 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 模型配置 | ✅ 支持 | 可从 AI Gateway 同步模型列表 |
|
||||
| API Key 管理 | ✅ 支持 | 使用 API Key Ref 安全存储 |
|
||||
| URL 配置 | ✅ 支持 | 自定义 AI Gateway 地址 |
|
||||
| 模型选择 | ✅ 支持 | 可选择多个模型 |
|
||||
|
||||
### 实际调用链
|
||||
|
||||
```
|
||||
用户发送消息
|
||||
↓
|
||||
CodexRuntime.sendMessage()
|
||||
↓
|
||||
JSON-RPC → 外部 Codex CLI (进程)
|
||||
↓
|
||||
Codex CLI 读取 config.toml
|
||||
↓
|
||||
[model_providers.xworkmate]
|
||||
↓
|
||||
HTTP 请求 → AI Gateway
|
||||
↓
|
||||
AI Gateway 代理到实际模型 (OpenAI、Anthropic等)
|
||||
↓
|
||||
响应返回
|
||||
```
|
||||
|
||||
## 3. OpenClaw Gateway 集成验证
|
||||
|
||||
### ✅ **结论：通过 WebSocket 连接到 OpenClaw Gateway，但任务调度和远期记忆功能需要后端支持**
|
||||
|
||||
### OpenClaw Gateway 提供的功能
|
||||
|
||||
| 功能 | 客户端支持 | 后端需求 | 状态 |
|
||||
|------|-----------|----------|------|
|
||||
| 身份认证 | ✅ 已实现 | ✅ 已实现 | ✅ 可用 |
|
||||
| 设备配对 | ✅ 已实现 | ✅ 已实现 | ✅ 可用 |
|
||||
| Agent 列表 | ✅ 已实现 | ✅ 已实现 | ✅ 可用 |
|
||||
| 聊天消息 | ✅ 已实现 | ✅ 已实现 | ✅ 可用 |
|
||||
| 健康检查 | ✅ 已实现 | ✅ 已实现 | ✅ 可用 |
|
||||
|
||||
### 任务调度功能
|
||||
|
||||
| 功能 | 客户端代码 | 状态 |
|
||||
|------|-----------|------|
|
||||
| Cron 任务列表 | ⚠️ 部分实现 | 仅查询显示 |
|
||||
| 创建 Cron 任务 | ❌ 未实现 | 无 UI |
|
||||
| 删除 Cron 任务 | ❌ 未实现 | 无 UI |
|
||||
| 任务执行状态 | ❌ 未实现 | 无监控 |
|
||||
|
||||
### 远期记忆功能
|
||||
|
||||
| 功能 | 客户端代码 | 状态 |
|
||||
|------|-----------|------|
|
||||
| 记忆存储 API | ❌ 未找到 | 无实现 |
|
||||
| 记忆检索 API | ❌ 未找到 | 无实现 |
|
||||
| 记忆管理 UI | ❌ 未找到 | 无界面 |
|
||||
|
||||
### GatewayRuntime 支持的方法
|
||||
|
||||
```dart
|
||||
lib/runtime/gateway_runtime.dart
|
||||
|
||||
已实现的 RPC 方法：
|
||||
- health() // 健康检查
|
||||
- status() // 状态查询
|
||||
- agents.list() // Agent 列表
|
||||
- devices.list() // 设备列表
|
||||
- devices.approve() // 设备批准
|
||||
- chat.sendMessage() // 发送消息
|
||||
- abortChat() // 中止聊天
|
||||
```
|
||||
|
||||
### 客户端未实现的功能
|
||||
|
||||
```dart
|
||||
// 以下方法在 GatewayRuntime 中未找到：
|
||||
- scheduleTask() // 调度任务
|
||||
- listScheduledTasks() // 列出调度任务
|
||||
- deleteScheduledTask() // 删除调度任务
|
||||
- storeMemory() // 存储记忆
|
||||
- retrieveMemory() // 检索记忆
|
||||
- listMemoryKeys() // 列出记忆键
|
||||
```
|
||||
|
||||
### 实际工作流程 (聊天 - 已实现)
|
||||
|
||||
```
|
||||
XWorkmate 连接到 OpenClaw Gateway
|
||||
↓
|
||||
WebSocket 握手 (ws:// 或 wss://)
|
||||
↓
|
||||
设备配对审批
|
||||
↓
|
||||
mainSession 建立成功
|
||||
↓
|
||||
用户发送消息
|
||||
↓
|
||||
GatewayRuntime.request('chat.sendMessage', params)
|
||||
↓
|
||||
OpenClaw Gateway 处理
|
||||
↓
|
||||
Agent 响应返回
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
| 需求 | 状态 | 实现方式 |
|
||||
|------|------|----------|
|
||||
| **1. FFI 调用 Codex** | ❌ | 仅桥代码，使用外部 CLI 模式 |
|
||||
| **2. AI Gateway 桥接** | ✅ | 通过配置文件，Codex CLI 使用 AI Gateway |
|
||||
| **3. OpenClaw 任务调度** | ⚠️ | 客户端已连接，但任务调度 API 未实现 |
|
||||
| **4. OpenClaw 远期记忆** | ❌ | 客户端和 API 均未实现 |
|
||||
|
||||
### 实际可用的功能
|
||||
|
||||
```
|
||||
✅ 本地 Codex 对话 (外部 CLI + JSON-RPC)
|
||||
✅ AI Gateway 模型代理 (通过配置文件)
|
||||
✅ OpenClaw Gateway 连接和身份认证
|
||||
✅ OpenClaw Chat 消息收发
|
||||
✅ OpenClaw Agent 列表查询
|
||||
✅ OpenClaw 设备配对管理
|
||||
```
|
||||
|
||||
### 未实现的功能
|
||||
|
||||
```
|
||||
❌ FFI Rust 嵌入模式 (仅桥代码)
|
||||
❌ OpenClaw 任务调度 (无 API)
|
||||
❌ OpenClaw 远期记忆 (无 API)
|
||||
❌ Codex 嵌入式执行 (仅外部进程)
|
||||
```
|
||||
|
||||
### 架构总结
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ XWorkmate (Flutter) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ OpenClaw │ │ AI Gateway │ │
|
||||
│ │ Gateway │ │ (模型代理) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • 身份认证 ✅ │ │ • 模型配置 ✅ │ │
|
||||
│ │ • 设备配对 ✅ │ │ • API Key ✅ │ │
|
||||
│ │ • Chat 消息 ✅ │ │ • 桥接 Codex ✅ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • 任务调度 ❌ │ └──────────────────┘ │
|
||||
│ │ • 远期记忆 ❌ │ │
|
||||
│ └──────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Codex Runtime │ │
|
||||
│ │ │ │
|
||||
│ │ 外部 CLI 模式 ✅ │ │
|
||||
│ │ FFI 模式 ❌ │ │
|
||||
│ │ │ │
|
||||
│ │ Process.start() │ │
|
||||
│ │ Stdio JSON-RPC │ │
|
||||
│ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 建议实现路径
|
||||
|
||||
### 1. 启用 FFI Codex (长期)
|
||||
|
||||
```rust
|
||||
// 需要实现：
|
||||
- ProcessManager (启动/停止 Codex 进程)
|
||||
- MessageQueue (异步消息队列)
|
||||
- EventStream (事件流输出)
|
||||
- StdioHandler (stdio 处理)
|
||||
```
|
||||
|
||||
### 2. 实现 OpenClaw 任务调度 (中期)
|
||||
|
||||
```dart
|
||||
// 需要添加到 GatewayRuntime：
|
||||
- scheduleTask() // 创建任务
|
||||
- listScheduledTasks() // 列出任务
|
||||
- deleteScheduledTask() // 删除任务
|
||||
- getTaskStatus() // 查询状态
|
||||
```
|
||||
|
||||
### 3. 实现 OpenClaw 远期记忆
|
||||
|
||||
```dart
|
||||
// 需要添加到 GatewayRuntime：
|
||||
- storeMemory() // 存储记忆
|
||||
- retrieveMemory() // 检索记忆
|
||||
- listMemoryKeys() // 列出键
|
||||
- deleteMemory() // 删除记忆
|
||||
```
|
||||
|
||||
### 4. AI Gateway 增强 (短期)
|
||||
|
||||
```dart
|
||||
// 当前已经可用，可以：
|
||||
- 添加模型缓存
|
||||
- 添加多模型并发
|
||||
- 添加流式响应
|
||||
- 添加错误重试
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user