# 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-06-23

## 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.2.0`，已完成首轮 Rust 核心能力对齐。核心 CLI、LLM profile、工具执行、交互式会话、日志与基础运行闭环已经可用，但仍定位为 Rust 核心运行时，而不是 `E:\GA` 的完整可替代版本。

已具备：

- Rust 工程结构与核心模块拆分
- 基础工具注册与执行框架
- Agent runner 多轮循环
- `init` / `doctor` / `run` / `repl` / 直接启动交互式会话
- GPT / Claude / Ollama profile 与 fallback order
- LLM 请求指数重试，降低上游 429 / overloaded 造成的任务失败
- 文件读写、代码执行、`ask_user`、工作检查点、会话持久化与归档
- browser bridge 第二版边界：`web_scan` 支持最近会话复用、`tabs_only`、`switch_tab_id`、标签页/活动会话返回；`web_execute_js` 支持显式 URL 与会话复用
- 基础测试、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
```

这会创建：

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

### 配置模型

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

```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
```

也可以直接编辑 `config/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 下文件并总结"
```

进入交互式会话：

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

## 测试

运行核心测试：

```bash
cargo test --test tool_execution_test -- --nocapture
```

先执行环境诊断：

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

运行真实集成测试前，必须先设置 API 环境变量：

```bash
cargo test --test real_integration_test -- --nocapture --test-threads=1
```

当前真实集成测试覆盖 5 类任务：

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

额外可选验证：

- 设置 `CX_BROWSER_BRIDGE_URL` 后运行 browser sidecar smoke test
- 验证 `data/memory/L3/*.md` 写入后可在后续会话重新注入

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

- 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.2.0`，定位为首个完成 browser bridge v2 边界和结构化长期记忆入口的 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 仍是第一版协议，距离 `E:\GA` 的真实浏览器桥还有明显差距
- 当前首发文档优先覆盖 Windows，macOS / Linux 仅提供基础兼容说明
- 外部灰度反馈流程已定义，但仍需实际执行一轮

## 版本目标

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

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

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

## License

MIT