# cx

**Repository Path**: umb/cx

## Basic Information

- **Project Name**: cx
- **Description**: AgentRunner = LLM + Tools + Memory + Loop + Policy
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cx

`cx` 是一个聚焦**紧凑、模块化、可嵌入**的 Rust Coding Agent 平台。命令行二进制与 Rust 库同名 **`cx`**。它提供同一套 Agent 能力的多种宿主（本地 CLI/REPL、Web、自动化脚本、多进程控制器、第三方 Rust 应用），所有宿主共享同一个 runtime 与 protocol，**不复制** Agent Loop、工具执行、Session 存储或 Compaction。

```
◆ cx v1.0.0 · Qwen3.6-27B · E:\work\demo

⋮ turn 1 · 1.2k chars context
▸ code_run({"code":"ls"})
◂ exit 0 · 24 chars
✓ done · 1.2k tokens · 1 tool call · 3.4s
session saved · temp/sessions/2026-08-13T11-15-38_7aa0
```

- 架构事实源：[docs/architecture/overview.md](docs/architecture/overview.md)
- 模块边界：[docs/architecture/module-boundaries.md](docs/architecture/module-boundaries.md)
- 协议与 Web 接入：[docs/architecture/protocol.md](docs/architecture/protocol.md)
- 当前开发计划：[docs/plans/current.md](docs/plans/current.md)
- 旧兼容迁移说明：[docs/migration-legacy-to-runtime.md](docs/migration-legacy-to-runtime.md)
- 变更日志：[CHANGELOG.md](CHANGELOG.md)

---

## 两种运行模式

cx 的核心是同一套 runtime：

```text
本地模式：cx（CLI/REPL） -> cx-runtime -> cx-core
远程模式：cx --remote / Web -> cx-client -> cx-server -> cx-runtime -> cx-core
```

本地与远程只是装配位置不同，Agent 语义、Session、Compaction、事件流完全一致。

## 快速上手

### 1) 直接下载二进制

从 Releases 取 `cx-<ver>-<platform>.zip`，解压即用。目录里包含：

- `cx.exe` / `cx` —— Agent（本地/远程 CLI、REPL、replay）。
- `cx-server.exe` / `cx-server` —— 长生命周期 server（stdio / TCP / WebSocket）。
- `assets/` —— 系统提示与工具 schema（必须与二进制同目录或可找到）。
- `config.example.toml` —— 复制为 `config.toml` 填入 LLM 端点。

```toml
# config.toml
provider   = "openai"                       # 或 anthropic
api_key    = "sk-..."
base_url   = "http://your-llm-endpoint/v1"
model      = "your-model-name"
cwd        = "."                            # 工作目录/沙箱基准（默认为 exe 目录）
# context_window = 32768                    # tokens；按需提供
# max_turns      = 40
# tool_timeout_secs = 120
```

然后运行 one-shot：

```bash
./cx "List all rust files here and summarize them"
```

### 2) 从源码构建

仓库是一个标准 Cargo workspace，从根目录即可编译/测试/静态检查：

```bash
cd /d E:\ak\cx            # 仓库根

# 仅本地 CLI（默认 debug；--release 出发布位）
cargo build -p cx-cli --offline

# 本地二进制（含 cx 与 cx-server 两个 bin）位于
#   target\debug\cx.exe        以及   target\debug\cx-server.exe
# release 则在 target\release\

# 全 workspace
cargo build --workspace --offline
cargo test  --workspace --offline
cargo clippy --workspace --all-targets --offline -- -D warnings
cargo fmt --all
```

> 发布位（release）由 `scripts/build-release.ps1`（Windows）或
> `scripts/build-release.sh`（*nix）统一产出，见 [发布检查清单](docs/release-checklist.md)。

### 3) 配置优先级

`cx` / `cx-server` 读取同一套 `config.toml`（`./config.toml` 或 `~/cx/config.toml`，可用 `--config <PATH>` 覆盖）。同一字段的来源优先级（高→低）：

```text
CLI flag（--model / --fallback-provider ...）
  > 环境变量（CX_API_KEY / CX_BASE_URL / CX_MODEL / ...）
  > config.toml
  > 内置默认
```

### 4) 三种典型用法

**A. one-shot（单轮执行）**

```bash
./cx "explain main.rs"
./cx --no-cache "explain main.rs"   # 绕过工具结果缓存
./cx --log-level verbose "..."     # 展开完整工具输出
./cx --prompt-file long.md "..."   # 长提示从文件读
./cx --replay <session.jsonl>      # 回放一个已保存的旧 session
```

**B. 交互式 REPL（`cx` 在 stdin 为 TTY 且无 prompt 时自动进入）**

```bash
./cx --repl
```

REPL 跨轮次保持会话。普通每行是一个新 prompt；以 `:` 开头的是 REPL 命令。常用：

| 命令 | 作用 |
|---|---|
| `:help` | 列出所有命令 |
| `:exit` / `:quit` / `:q` | 退出 |
| `:reset` / `:clear` | 清空当前对话历史（保留 session） |
| `:sessions` | 列出历史 session（`--all` 显示更多列） |
| `:continue <id>` / `:resume <id>` | 继续/恢复某个 session |
| `:compact` | 当前本地 REPL 暂不支持；protocol method 仍保留但当前 server 不声明该能力 |
| `:abort` | 中止当前运行中的 operation |
| `:steer <text>` / `:follow-up <text>` | runtime steering / follow-up 控制 |
| `:info` / `:memory` / `:tokens` | 查看运行信息 / 长期记忆 / token 用量 |
| `:log <level>` | 运行时切换输出粒度（别名 `:log-level` / `:l`） |
| `:history` | 查看当前对话历史 |
| `:skill run <id> [args]` | 触发一条已注册 skill |
| `:profile <id>` / `:profile validate` | 切换 / 校验 profile |
| `:desc [filter]` / `:inspect <subject> <name>` | 查看注册的工具/扩展与内省 |
| `:tokens` / `:tk` | token 统计 |

完整命令以 `:help` 为准。

**C. 远程 server / client**

server（stdio / TCP / WebSocket 三种 transport，任一进程只占一个端口）：

```bash
# stdio JSONL（stdin 每行一 request；stdout 出 response/event；stderr 诊断）
cx-server --cwd . --config config.toml

# TCP 监听（多连接共享同一 Server；协议与 stdio 同构；断开不销毁 session）
cx-server --cwd . --config config.toml --listen 127.0.0.1:7000

# WebSocket（浏览器等价通道）；--web 在同端口挂静态页 GET /
cx-server --cwd . --config config.toml --listen-ws 127.0.0.1:7001 [--web]
```

client（CLI 远程模式）：

```bash
cx --remote 127.0.0.1:7000 "问一个问题"        # TCP 远程 one-shot
cx --remote ws://127.0.0.1:7001 --repl          # WebSocket 远程交互
cx --remote 127.0.0.1:7000 --continue <sid> ... # resume 远程 session
```

`cx --remote` 的 REPL 命令集收敛为 `:exit` / `:abort` / `:new` / `:session`，与本地 REPL 不同。

### 5) cx-server 关键参数

| 参数 | 作用 |
|---|---|
| `--cwd <dir>` | 工作目录/会话基准 |
| `--config <path>` | 指定 config |
| `--listen host:port` | TCP 监听（多连接共享 Server） |
| `--listen-ws host:port` | WebSocket 监听 |
| `--web` | ws 监听上挂静态页（必须配 `--listen-ws`） |
| `--workspace <path>`（可重复） | workspace allowlist（默认 `[cwd]`） |
| `--redact-secret <s>`（可重复） | 出流脱敏串（生产 API key 自动并入，`sk-` 常开） |
| `--token <t>` | ws 升级凭据（`?token=` 或 `X-Cx-Token`） |
| `--extension-deny-tool <name>`（可重复） | P7.2 远程扩展权限：拒绝工具名 |
| `--extension-require-sandbox` | P7.2 要求工具调用必须在 sandbox 内 |
| `--dummy-reply / --dummy-error / --dummy-ask` | 诊断模式（不触 LLM） |
| `--approval-tool / --approval-prompt / --approval-timeout-ms` | P7.3 诊断审批模式 |

> 本地 CLI 对应 P7.1 扩展策略参数：`--extension-deny-tool <name>`（可重复）、
> `--extension-require-sandbox`。本地/远程共用同一 `ExtensionPolicy` 语义。

---

## 架构

源码划分为标准 Cargo workspace：

```text
packages/
├── core/        cx-core      Agent 内核、消息、事件、context、基础 contract
├── llm/         cx-llm       统一模型流 / Provider 抽象 / retry / fallback
├── tools/       cx-tools     工具注册 + 唯一执行 pipeline + 输出策略/缓存
├── session/     cx-session   Session DAG、Entry/Record、存储、Compaction
├── protocol/    cx-protocol  跨进程版本化 request/response/event/error 契约
├── runtime/     cx-runtime   产品级 AgentSession 与宿主运行时（Operation/订阅/控制）
├── server/      cx-server    长生命周期 server、transport、连接/session/operation 路由
├── client/      cx-client    client SDK、request correlation、订阅、重连
├── ws/          cx-ws        WebSocket 传输原语（供 server/client 复用）
├── tui/         cx-tui       终端展示（Diamond 风格 + RuntimeEvent 渲染）
└── cli/         cx-cli       `cx` + `cx-server` 两个 bin、REPL、装配入口

adapters/web/      浏览器静态适配（adapter.js + index.html）
assets/            系统提示、工具 schema
scripts/           发布构建脚本（release.ps1 / release.sh）
docs/              架构/ADR/计划/指南（事实源分层）
```

依赖单向，底层不反向依赖产品层：

```text
cx-cli   -> cx-runtime / cx-client / cx-tui / cx-protocol
cx-client-> cx-protocol（+ 自有 transport 抽象）
cx-server-> cx-runtime + cx-protocol + cx-ws
cx-runtime-> cx-core + cx-llm + cx-tools + cx-session
cx-tui   -> cx-runtime 的展示事件 contract
cx-tools / cx-session / cx-llm -> cx-core
```

模块职责、允许/禁止依赖见 [模块边界](docs/architecture/module-boundaries.md)。

## 质量门禁（P8）

开发期对每个阶段强制执行，并在 [plans/current.md](docs/plans/current.md) 留证：

```bash
cargo build  --workspace --offline
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --offline -- -D warnings
cargo test   --workspace --offline
```

要求：编译零错误、格式零 diff、clippy 零 warning、测试全绿。

## 设计要点

- **对外同步迭代器、对内 tokio 异步**：宿主拿到的事件流是同步可遍历的，内部走 async，镜像 GA 的生成器模型。
- **工具只走一条 pipeline**：`prepare -> validate -> approval -> sandbox -> timeout/abort -> execute -> output -> finalize -> cache`（[ADR-0001](docs/adr/0001-tool-pipeline-unification.md)）。
- **Session 是 DAG**：上下文 Entry 与运行审计 Record 分离；支持恢复、分支、Compaction（[ADR-0002](docs/adr/0002-session-dag-and-compaction.md)）。
- **HostRuntime/AgentSession 收敛在 cx-runtime**：core 不反向依赖产品层（[ADR-0003](docs/adr/0003-host-runtime-egress-from-core.md)）。
- **协议四件套 + 三 transport**：protocol/server/client/web 拆分（[ADR-0004](docs/adr/0004-protocol-server-client-split.md)）、stdio 先行（[ADR-0005](docs/adr/0005-stdio-first-transport.md)）。
- **流事件与运行时渲染统一**：CLI/REPL/TUI 共用同一 RuntimeEvent 渲染主链（[ADR-0006](docs/adr/0006-stream-events-and-runtime-renderer.md)）。
- **Diamond 风格输出**：列 0 事件标记（`▸` 工具始 / `◂` 终 / `⋮` turn / `✓ done` / `✗ error`）、plan/reflect 框、无 spinner。
- **版本化落盘**：会话元数据与事件流均带版本（`META_VERSION = 1` / `EVENT_VERSION = 1`），为未来迁移留缝；旧 `LoopEvent` / replay 只走兼容边界，不进生产主链。

## 文档与决策

- 文档入口：[docs/README.md](docs/README.md)
- 架构：[overview](docs/architecture/overview.md) · [module-boundaries](docs/architecture/module-boundaries.md) · [protocol](docs/architecture/protocol.md) · [runtime-model](docs/architecture/runtime-model.md)
- ADR：[索引](docs/adr/README.md)
- 开发指南：[guides/development.md](docs/guides/development.md)
- 历史归档：[docs/archive/](docs/archive/README.md)
- 旧兼容迁移（`LoopEvent`/`AgentEventStream`/旧 events.jsonl）：[migration-legacy-to-runtime.md](docs/migration-legacy-to-runtime.md)
- 发布：[release-checklist.md](docs/release-checklist.md) · [CHANGELOG.md](CHANGELOG.md)

## License

MIT