WHCandCursor
2602806aea
Rewrite the homepage for day-to-day use, move paper/eval drafts under docs/archive, and add a docs index so theory no longer leads the project. Co-authored-by: Cursor <cursoragent@cursor.com>
196 lines
7.8 KiB
Markdown
196 lines
7.8 KiB
Markdown
# CST-Agent
|
||
|
||
本地 coding agent：终端 TUI、可选 WebUI / 桌面 GUI，在工作区里读改文件、跑命令、管会话。
|
||
C11 实现，OpenAI 兼容网关（DeepSeek / Kimi / MiniMax / OpenAI 等）。
|
||
|
||
**适合**：有监督的本地改动与仓库探索（权限确认、diff、`/undo`、沙箱）。
|
||
**慎用**：完全无人值守的长任务；headless 默认自动批准。
|
||
|
||
文档索引：[docs/README.md](docs/README.md)。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
### Linux / WSL / macOS（推荐）
|
||
|
||
```bash
|
||
# 预编译包（快；失败则自动回退源码编译）
|
||
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_linux.sh | bash -s -- --release
|
||
|
||
# 或始终从源码增量编译安装到 ~/.local/bin
|
||
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_linux.sh | bash
|
||
```
|
||
|
||
已有仓库目录：
|
||
|
||
```bash
|
||
./scripts/bootstrap_linux.sh . # 源码
|
||
./scripts/bootstrap_linux.sh . --release # 只装 Release 二进制
|
||
cst-agent-update # 之后升级
|
||
cst-agent --version
|
||
```
|
||
|
||
[Release](https://git.whcself.xyz/WHC/CST-agent/releases) 也提供静态 musl 包
|
||
`cst-agent-VERSION-linux-{x86_64,x86,aarch64}.tar.gz`（旁有 `.sha256`），解压后把 `cst-agent` 放进 `PATH` 即可。
|
||
|
||
### Windows 10 1903+
|
||
|
||
```powershell
|
||
irm https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/install_windows.ps1 | iex
|
||
```
|
||
|
||
或下载 `cst-agent-VERSION-windows-x86_64-setup.exe` / 便携 zip。详见 [docs/README-windows.md](docs/README-windows.md)。
|
||
|
||
### Termux
|
||
|
||
```bash
|
||
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_termux.sh | bash
|
||
```
|
||
|
||
### 第一次用
|
||
|
||
```bash
|
||
cd ~/my-project && cst-agent
|
||
```
|
||
|
||
首次选择 provider 并输入 API key（遮罩输入，按 provider 存到配置目录 `credentials`，权限 0600）。
|
||
之后用 `/provider`、`/model`、`/effort`、`/key` 切换；选择会记在 `settings.json`。
|
||
|
||
完整环境变量：[docs/env_openai.md](docs/env_openai.md)。
|
||
多设备议会：[docs/parliament.md](docs/parliament.md)。
|
||
|
||
| 平台 | 脚本 |
|
||
|---|---|
|
||
| Linux / macOS | [`scripts/bootstrap_linux.sh`](scripts/bootstrap_linux.sh) |
|
||
| Termux | [`scripts/bootstrap_termux.sh`](scripts/bootstrap_termux.sh) |
|
||
| Windows 安装 | [`scripts/install_windows.ps1`](scripts/install_windows.ps1) |
|
||
| Linux 静态包 | [`scripts/package_linux.sh`](scripts/package_linux.sh) `x86_64\|x86\|aarch64` |
|
||
| Windows 交叉构建 | [`scripts/bootstrap_windows.sh`](scripts/bootstrap_windows.sh) |
|
||
| Windows 原生（MSYS2） | [`scripts/bootstrap_msys2.sh`](scripts/bootstrap_msys2.sh) |
|
||
|
||
---
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
make -j$(nproc) # 增量；有 ccache 会自动用；make help 看目标
|
||
make -j$(nproc) check # 单元测试
|
||
make asan # ASan + UBSan
|
||
make CC=tcc AR=ar check # TinyCC 快校验（CI 同款）
|
||
make install PREFIX=$HOME/.local
|
||
make install-service PREFIX=$HOME/.local # 可选：systemd --user 议会单元
|
||
```
|
||
|
||
NixOS：`nix-shell --run 'make -j$(nproc)'`。macOS：`brew install curl ncurses pkg-config` 后直接 `make`。
|
||
平台细节：[docs/compat.md](docs/compat.md)。
|
||
|
||
```bash
|
||
# CMake（多编译器 / 无 TUI）
|
||
cmake -B build -DCMAKE_C_COMPILER=gcc -DCST_BUILD_TUI=ON
|
||
cmake --build build -j && ctest --test-dir build --output-on-failure
|
||
```
|
||
|
||
可选 Qt 桌面前端：[app/README.md](app/README.md)。
|
||
Android APK：[docs/android.md](docs/android.md)。
|
||
|
||
### CI 与发布
|
||
|
||
推送 `main` / `v*` 时 [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) 会：TinyCC `check` → 打 Linux/Windows 发行包 → `scripts/ci_publish.sh` 上传 Gitea Release。
|
||
共用逻辑：[`scripts/lib_release.sh`](scripts/lib_release.sh)。本地上传：`GITEA_TOKEN=... scripts/release.sh dist/cst-agent-*`。
|
||
|
||
---
|
||
|
||
## 用法速览
|
||
|
||
```bash
|
||
cst-agent # TUI，工作区=当前目录
|
||
cst-agent --web # 浏览器 http://127.0.0.1:8787/
|
||
cst-agent --headless --prompt '…' # 无人值守（默认自动批准）
|
||
cst-agent --ask-key --provider deepseek
|
||
```
|
||
|
||
| 参数 | 作用 |
|
||
|---|---|
|
||
| `-c` / `-N` / `-R ID` / `-L` | 继续上次 / 新会话 / 恢复 / 列表 |
|
||
| `-A ask\|auto\|yolo` / `-y` | 审批模式 |
|
||
| `-T default\|minimal` | 工具集（`minimal` = 读写 shell 四件套） |
|
||
| `-M coding\|general` | 工作模式 |
|
||
| `-P` / `-m` / `-e` | provider / 模型 / 推理强度 |
|
||
| `-w DIR` | 工作区 |
|
||
|
||
会话目录：`<workspace>/.agent/sessions/<uuid>/`（自带 `.gitignore`）。WebUI 协议：[docs/webui.md](docs/webui.md)。
|
||
|
||
### Provider 默认
|
||
|
||
| provider | API Base | 默认模型 | Key |
|
||
|---|---|---|---|
|
||
| `minimax`（默认） | `https://api.minimax.cn/v1` | `MiniMax-M2.7` | `MINIMAX_API_KEY` |
|
||
| `deepseek` | `https://api.deepseek.com/v1` | `deepseek-flash` | `DEEPSEEK_API_KEY` |
|
||
| `kimi` | `https://api.moonshot.ai/v1` | `kimi-k3` | `MOONSHOT_API_KEY` |
|
||
| `kimi-code` | `https://api.kimi.ai/coding/v1` | `k3` | `KIMI_API_KEY` |
|
||
| `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_API_KEY` |
|
||
| `teamorouter` | `https://api.teamorouter.com/v1` | `/models` 首个 | `TEAMOROUTER_API_KEY` |
|
||
|
||
优先级：CLI → 已保存 credentials → 环境变量 → TUI 询问。详见 [docs/env_openai.md](docs/env_openai.md)。
|
||
|
||
### 内置能力（摘要）
|
||
|
||
- **文件**：`read_file` / `list_dir` / `glob` / `grep` / `edit_file` / `apply_patch` / `write_file` / `delete_file` / `move_file`
|
||
- **命令**：`run_shell`（沙箱 + 可中断；超时 `CST_SHELL_TIMEOUT`）
|
||
- **网络**：`web_fetch`；Kimi/DeepSeek 另有官方 `web_search`
|
||
- **任务**：`todo_write`、`ask_user`、`task` 子 agent、后台 `job_*`（完成会推 TUI / 下一回合笔记）
|
||
- **扩展**：Skills、插件、MCP（[docs/plugins.md](docs/plugins.md)）；worker 编排（[docs/workers.md](docs/workers.md)）
|
||
|
||
同一步里连续只读调用会自动并行（默认最多 8，`CST_PAR_MAX` 可调）。截断结果带 `[truncated … evidence=ID]`，用 `evidence_read` 续读。
|
||
|
||
### 审批与沙箱
|
||
|
||
Shift+Tab / `/approval` 在 `ask` → `auto` → `yolo` 间切换。`auto` 下 Linux 优先 Landlock（否则 seccomp），macOS `sandbox_init`，Windows Low IL；详见源码与 [docs/compat.md](docs/compat.md)。
|
||
写文件前自动快照，`/undo` 可回滚；工作区 `AGENTS.md` 会注入系统提示。
|
||
|
||
### TUI 常用
|
||
|
||
| 按键 / 命令 | 说明 |
|
||
|---|---|
|
||
| Enter / Esc | 发送（busy 时入队）/ 取消当前回合 |
|
||
| Tab / Shift+Tab | 补全或 Build↔Plan / 审批模式 |
|
||
| Ctrl+P / Ctrl+T | 命令面板 / 任务面板 |
|
||
| Ctrl+X 再按字母 | Leader 快捷键（`/keys` 或 F1 查看） |
|
||
| `/provider` `/model` `/effort` `/key` | 切换后端 |
|
||
| `/realm` `/motion` | 议会登录提示、Seat Deck 动效 |
|
||
| `/web` `/quit` | 起 WebUI / 退出 |
|
||
|
||
完整快捷键与斜杠命令仍以 TUI 内 `/help`、`/keys` 为准。
|
||
|
||
### 工具协议（可选）
|
||
|
||
默认 `native-eos`（OpenAI `tools[]`，流结束后执行）。也可 `native-inc`、文本帧 `ctl` / `ctl-heredoc`、`xml`（`CST_PROTOCOL` / `/protocol`）。日常使用保持默认即可。
|
||
|
||
---
|
||
|
||
## 平台
|
||
|
||
| OS | Arch | TUI | 备注 |
|
||
|---|---|---|---|
|
||
| Linux glibc/musl | x86_64 / x86 / aarch64 | ncursesw | 静态 Release 为 musl |
|
||
| WSL2 | x86_64 | ncursesw | 工作区放在 Linux 文件系统 |
|
||
| macOS | arm64 / x86_64 | Homebrew ncurses | |
|
||
| Termux | aarch64 等 | Termux ncurses | |
|
||
| Windows 10 1903+ | x86_64 | 捆绑 ncurses | shell 为 busybox-w32 |
|
||
|
||
---
|
||
|
||
## 开发者备忘
|
||
|
||
```bash
|
||
make check
|
||
scripts/prompt_smoke.sh # 系统提示契约（无 API）
|
||
scripts/e2e_webui.sh # WebUI 录制流（无 API）
|
||
scripts/e2e_fixture.sh mini_calc --provider deepseek # 可选：带 key 的夹具
|
||
```
|
||
|
||
`fixtures/` 下是可重复的本地任务夹具（`TASK.md` + `check.sh`），用于手工或脚本验收，不是产品依赖。
|
||
|
||
许可证与第三方：`vendor/sashidown`、`vendor/cjson`（MIT）、`vendor/monocypher` 随仓库提供。
|