# CX

**Repository Path**: umb/cx

## Basic Information

- **Project Name**: CX
- **Description**: 一个极简的、可自我演化的自主代理框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CX

`cx` 是面向 GenericAgent 运行方式的 Rust 核心实现。

当前仓库目标刻意收敛为首个可对外交付的核心运行时：

- `LLM`：统一模型调用与工具调用协议
- `Tools`：文件、代码执行、用户交互等基础工具
- `Memory`：工作记忆与分层记忆入口
- `Loop`：多轮 Agent 运行闭环
- `Policy`：system prompt、summary、节奏控制、history fold

不在当前首发主线内：

- 多前端适配
- Goal Hive / 多 Agent 编排
- 大型技能生态
- 完整 1:1 迁移 `E:\GA`

## 当前状态

CX 当前版本为 `0.4.2`，已完成首轮 Rust 核心能力对齐，并继续把 browser bridge 协议诊断、会话复用和长期记忆来源守门推进到更稳定的可复用状态。核心 CLI、LLM profile、工具执行、交互式会话、日志与基础运行闭环已经可用，但仍定位为 Rust 核心运行时，而不是 `E:\GA` 的完整可替代版本。

已具备：

- Rust 工程结构与核心模块拆分
- 基础工具注册与执行框架
- Agent runner 多轮循环
- `init` / `doctor` / `run` / 直接启动交互式会话
- GPT / Claude / Ollama profile 与 fallback order
- LLM 请求指数重试，降低上游 429 / overloaded 造成的任务失败
- 文件读写、代码执行、`ask_user`、工作检查点、会话持久化与归档
- browser bridge 第二版边界：`web_scan` 支持最近会话复用、`tabs_only`、`switch_tab_id`、标签页/活动会话返回；`web_execute_js` 支持显式 URL 与会话复用
- browser bridge 会话现在会持续复用最近一次保存的 `bridge_url`，并在 `execute_js` 失败时返回更清晰的非 JSON / 空响应诊断
- `web_scan` 现在也会复用最近会话保存的 `bridge_url`；`scan / switch_tab / snapshot / execute_js` 统一采用带响应摘要的 JSON 诊断
- `start_long_term_update` 已支持 `tool_result`、`user_confirmed`、`derived_summary` 三类来源，并按 L2/L3/L4 层级限制允许写入的证据类型
- 基础测试、CLI smoke test 与真实集成测试骨架
- L3 技能记忆可从磁盘重新加载，并重新注入 system prompt
- Windows PowerShell 新手路径与 release 目录真实运行验证

当前重点：

1. 稳定真实模型运行体验
2. 稳定 browser bridge 与 web 工具行为
3. 完善文档和发布流程
4. 补齐长期记忆、策略节奏和更多真实场景验证

当前已知边界：

- 还没有复刻 `E:\GA\TMWebDriver.py` 那种真实浏览器完整能力
- `start_long_term_update` 已升级为结构化 L2/L3/L4 写入入口，但距离 GA 风格的完整行动验证蒸馏仍有差距
- 插件钩子与多前端仍处于预留位

后续规划见 `docs/roadmap.md`。

## 快速开始

### 环境要求

- Windows 10/11 或 macOS / Linux
- Rust stable（建议通过 `rustup` 安装）
- 可访问的 OpenAI 兼容模型接口

Windows 首次安装可直接执行：

```powershell
winget install Rustlang.Rustup
rustup default stable
```

安装完成后重新打开终端，并验证：

```powershell
cargo --version
```

### 构建

```bash
cargo build --release
```

### 首次初始化

先创建标准数据目录并生成默认配置模板：

```bash
cargo run --release -- init
```

这会在 `cx.exe` 所在目录创建：

- `config.toml`（若尚不存在）
- `data/memory/`
- `data/workspace/`
- `data/logs/`

> 默认与 `cx.exe` 同级；不依赖当前工作目录。可用 `--config` / `--data-dir` 显式覆盖。

### 配置模型

优先使用环境变量注入真实模型参数：

```env
LLM_PROVIDER=openai
LLM_MODEL=gpt-4.1
LLM_API_KEY=your_key_here
LLM_BASE_URL=https://api.openai.com/v1
```

如果使用兼容 OpenAI 协议的网关，也可仅设置：

```env
OPENAI_API_KEY=your_key_here
```

也可以直接编辑与 `cx.exe` 同级的 `config.toml`。

### 环境诊断

```bash
cargo run --release -- doctor
```

`doctor` 会检查：

- 配置文件是否可加载
- provider / model 是否已解析
- API key 是否缺失
- `data/memory`、`data/workspace`、`data/logs` 是否存在
- browser bridge 未作为 `doctor` 的必检项；如需 web JS 能力，请额外配置 `CX_BROWSER_BRIDGE_URL`

日志默认写入 `data/logs/`，同时继续输出到当前终端。

### 运行

执行一次性任务：

```bash
cargo run --release -- run "读取 workspace 下文件并总结"
```

进入交互式会话（不带子命令即进入 REPL）：

```bash
cargo run --release
```

## 测试

### 本地基线（不访问外部网络/凭据）

```bash
cargo test --tests
```

或一键脚本：

```bash
bash scripts/ci-test.sh   # 等价于 fmt + clippy + cargo test --tests
```

CLI smoke + 工具执行 + 库单测共约 33 个测试，全部不需要 API key 即可通过。

### 真实集成测试（需 LLM 凭据，已 `#[ignore]`）

`tests/real_integration_test.rs` 中 6 个 `#[tokio::test]` 已默认 `#[ignore]`，
避免 `cargo test` 静默通过假绿。需要显式运行：

```bash
# 至少 1 个 profile 可用
export LLM_API_KEY=sk-...
# 可选
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-4
export LLM_BASE_URL=https://api.openai.com/v1
# browser bridge smoke 额外需要
export CX_BROWSER_BRIDGE_URL=http://127.0.0.1:3847

cargo test -- --ignored --test-threads=1
```

缺凭据时 `require_real_test_config` / `require_browser_bridge_client` 会 panic 并提示如何修复。

### 当前真实集成测试覆盖 6 类任务

- 文件读取与总结
- 代码执行与结果核对
- 多工具组合读写
- 多轮跟进文件编辑
- 缺失文件后的失败恢复
- browser bridge smoke（需 `CX_BROWSER_BRIDGE_URL`）

当前单元/集成验证还覆盖：

- CLI smoke 路径（`init` / `doctor` / 参数校验）
- `ask_user` 最小闭环
- 工作检查点刷新与会话归档
- browser bridge 第一版的 HTTP 回退与 sidecar 执行路径
- L3 技能记忆加载与 system prompt 注入

## 文档

- 新手入门：`QUICKSTART.md`
- 设计方案：`docs/rust-core-design.md`
- 后续规划：`docs/roadmap.md`
- 迭代记录：`docs/changelog.md`
- 发布检查：`docs/release-checklist.md`

## 发布说明

当前版本为 `0.4.2`，定位为首个完成 browser bridge v2 诊断收敛、SOP 持续注入与长期记忆来源分级守门的 Rust 核心 release candidate。

推荐发布流程：

1. 运行 `cargo test --test cli_smoke_test -- --nocapture`
2. 运行 `cargo test --test tool_execution_test -- --nocapture`
3. 运行 `cargo test --test real_integration_test -- --nocapture`
4. 在干净环境按 `docs/release-checklist.md` 完成安装演练
5. 再生成发布构建：`cargo build --release`

已知限制：

- 真实集成测试依赖外部 LLM API 凭据
- browser bridge 已完成第二版 client 边界稳定化，但距离 `E:\GA` 的真实浏览器桥还有明显差距
- 当前首发文档优先覆盖 Windows，macOS / Linux 仅提供基础兼容说明
- 外部灰度反馈流程已定义，但仍需实际执行一轮

## 版本目标

首个对外交付版本的定义是：

- CLI 可运行
- 核心工具链可用
- 多轮任务闭环稳定
- 基础策略行为可复现
- 配置与文档对外可用

在此之前，仓库中的扩展方向都视为后续演进，不作为首发完成标准。

## License

MIT