forked from WHC/Hermit
WHCandCursor
1f1fcba7ad
Vendored sashidown, OpenAI-compatible env (OPENAI_*), and bootstrap scripts. Co-authored-by: Cursor <cursoragent@cursor.com>
199 lines
6.6 KiB
Markdown
199 lines
6.6 KiB
Markdown
# CST-Agent
|
||
|
||
C11 OpenCode-like carrier that extends paper **CST** (confirmation frontier / irreversible emission) from Markdown→HTML to the **agent tool loop**.
|
||
|
||
See [docs/theory_tool_cst.md](docs/theory_tool_cst.md).
|
||
评测/反哺论文素材：[docs/eval_tool_cst.md](docs/eval_tool_cst.md)。
|
||
|
||
## 能不能用来工作？
|
||
|
||
**可以**：有监督的本地小改动 / 探索本仓库（TUI + 工具 + 权限确认）。
|
||
**不宜**：无人值守长任务或当 CI 主力（网关偶发空答、无完整 diff UI）。
|
||
|
||
### 5 分钟试用
|
||
|
||
```bash
|
||
# 一键拉取编译（Linux）
|
||
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_linux.sh | bash
|
||
# 或已有仓库：
|
||
cd CST-agent && ./scripts/bootstrap_linux.sh .
|
||
|
||
# OpenAI 官方
|
||
export OPENAI_API_KEY='sk-...'
|
||
export OPENAI_BASE_URL='https://api.openai.com/v1'
|
||
export OPENAI_MODEL='gpt-4.1-mini'
|
||
./cst-agent --workspace .
|
||
```
|
||
|
||
完整环境变量说明：[docs/env_openai.md](docs/env_openai.md)。
|
||
|
||
| 平台 | 一键脚本 |
|
||
|---|---|
|
||
| Linux | [`scripts/bootstrap_linux.sh`](scripts/bootstrap_linux.sh) |
|
||
| Termux | [`scripts/bootstrap_termux.sh`](scripts/bootstrap_termux.sh) |
|
||
| Windows 交叉构建（在 Linux 上） | [`scripts/bootstrap_windows.sh`](scripts/bootstrap_windows.sh) → `dist/windows-x86_64/` |
|
||
| Windows 运行 | 拷贝 dist 后 [`scripts/run_windows.bat`](scripts/run_windows.bat) |
|
||
|
||
### 迷你验收工程（论文案例）
|
||
|
||
故意带 bug 的小计算器：[`fixtures/mini_calc/`](fixtures/mini_calc/)（任务书 `TASK.md`）。
|
||
|
||
```bash
|
||
./scripts/e2e_mini_calc.sh --baseline-only # 无 API：证明初始测试 RED
|
||
./scripts/e2e_mini_calc.sh # 有 key：agent 修复后 make test
|
||
```
|
||
|
||
口径：`pass` / `partial` / `fail` — 见 [docs/eval_tool_cst.md](docs/eval_tool_cst.md)。
|
||
|
||
## Build
|
||
|
||
### Make（Linux 默认）
|
||
|
||
```bash
|
||
cd agent
|
||
make
|
||
make check
|
||
```
|
||
|
||
### CMake（推荐跨编译器 / 交叉）
|
||
|
||
```bash
|
||
# GCC
|
||
cmake -B build-gcc -DCMAKE_C_COMPILER=gcc -DCST_BUILD_TUI=ON
|
||
cmake --build build-gcc && ctest --test-dir build-gcc
|
||
|
||
# Clang
|
||
cmake -B build-clang -DCMAKE_C_COMPILER=clang -DCST_BUILD_TUI=ON
|
||
cmake --build build-clang
|
||
|
||
# Headless only（无 ncurses）
|
||
cmake -B build-hd -DCST_BUILD_TUI=OFF && cmake --build build-hd
|
||
|
||
# Windows MinGW 交叉（需安装 mingw-w64）
|
||
cmake -B build-win -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
|
||
-DCST_BUILD_TUI=OFF
|
||
cmake --build build-win
|
||
# TUI：安装 PDCurses 后 -DCST_BUILD_TUI=ON -DPDCurses_ROOT=...
|
||
```
|
||
|
||
依赖：`gcc` 或 `clang`、`libcurl`、Linux TUI 需 `ncursesw`；Windows TUI 需 **PDCurses**；sibling `../SD`（`libsashidown.a`）。
|
||
API Key：env / 配置文件 / **zenity（Linux）或控制台输入（Windows / 无 zenity）**。
|
||
|
||
## 平台支持矩阵
|
||
|
||
| OS | Arch | 编译器 | Headless | TUI | Shell |
|
||
|---|---|---|---|---|---|
|
||
| Linux | x86_64 / aarch64 | GCC, Clang | yes | ncursesw | `/bin/sh` 或旁路 `busybox` |
|
||
| Android Termux | aarch64 / … | Clang (Termux) | yes | ncurses（Termux 包） | `$PREFIX/bin/sh`；可旁路 busybox |
|
||
| Windows | x86_64 / aarch64 | MinGW GCC/Clang | yes | PDCurses | **捆绑 busybox-w32** |
|
||
| macOS | — | — | **不做** | — | — |
|
||
|
||
### Termux
|
||
|
||
```bash
|
||
pkg install clang make cmake libcurl ncurses-ui-libs
|
||
cmake -B build -DCST_BUILD_TUI=ON && cmake --build build
|
||
# 可选：旁路 Unix busybox
|
||
# ./scripts/build_third_party_mingw.sh busybox-unix
|
||
```
|
||
|
||
环境：`PREFIX` 自动用于找 `sh`；`CST_EXE_DIR` / `argv[0]` 用于定位旁路 busybox（`/proc/self/exe` 受限时）。
|
||
|
||
### Windows 发行包
|
||
|
||
见 [docs/README-windows.md](docs/README-windows.md)。交叉构建：
|
||
|
||
```bash
|
||
./scripts/build_third_party_mingw.sh all # curl+PDCurses+busybox-w32
|
||
# 源码：https://github.com/rmyorston/busybox-w32.git
|
||
# https://github.com/mirror/busybox.git （Unix）
|
||
cmake -B build-win-tui -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
|
||
-DCST_BUILD_TUI=ON -DCMAKE_PREFIX_PATH=$PWD/third_party/prefix-mingw
|
||
```
|
||
|
||
产物示例：`dist/windows-x86_64/`（含 `cst-agent.exe` + `busybox.exe` + `libwinpthread-1.dll`）。
|
||
|
||
环境变量：`CST_SHELL`、`CST_EXE_DIR`、`CST_AUTO_APPROVE` 等。
|
||
|
||
## Defaults (API)
|
||
|
||
默认 MiniMax：`https://api.minimax.cn/v1` / `MiniMax-M2.7`。
|
||
对接 **OpenAI 官方或其它兼容网关** 时设置：
|
||
|
||
| 用途 | 推荐变量 | 等价别名 |
|
||
|---|---|---|
|
||
| Key | `OPENAI_API_KEY` | `CST_API_KEY`、`MINIMAX_API_KEY` |
|
||
| Base（含 `/v1`） | `OPENAI_BASE_URL` | `CST_API_BASE`、`OPENAI_API_BASE` |
|
||
| Model | `OPENAI_MODEL` | `CST_MODEL` |
|
||
|
||
详见 [docs/env_openai.md](docs/env_openai.md)。
|
||
|
||
| 项 | 默认（未设 OPENAI_* 时） |
|
||
|---|---|
|
||
| API Base | `https://api.minimax.cn/v1` |
|
||
| Model | `MiniMax-M2.7` |
|
||
| API Key | env → 配置目录 credentials → zenity/控制台 |
|
||
|
||
环境变量：`CST_MODELS`、`CST_AUTO_APPROVE=1`、`CST_SHELL`、`CST_EXE_DIR`。
|
||
|
||
## Run
|
||
|
||
```bash
|
||
# Local CTL demo (no API)
|
||
./cst-agent --demo-ctl --workspace .
|
||
|
||
# TUI（OpenCode 风格；Assistant Markdown 经 Sashidown CST 渲染）
|
||
./cst-agent --workspace ..
|
||
|
||
# 强制重新弹窗保存 Key
|
||
./cst-agent --ask-key --workspace .
|
||
|
||
# Headless（默认 auto-approve shell/写文件）
|
||
./cst-agent --headless --prompt 'List files' --workspace .
|
||
```
|
||
|
||
### TUI 快捷键与斜杠命令
|
||
|
||
| 操作 | 说明 |
|
||
|---|---|
|
||
| Enter | 发送；空输入展开最近 tool 卡；busy 时入队（最多 3） |
|
||
| Ctrl+N | 输入换行（多行 composer） |
|
||
| ↑ / ↓ | 提示历史 |
|
||
| Esc / Ctrl+C | busy 时取消当前 turn |
|
||
| Tab / `t`（空输入） | 展开/折叠 Thought |
|
||
| 权限 | shell/写文件：`y` 允许 · `n` 拒绝 · `a` 本进程对该工具 Always |
|
||
| `/new` | 新会话 |
|
||
| `/session` | **可点选**会话列表（↑↓ Enter）；`/session <id>` 手打切换 |
|
||
| `/model` | **可点选**模型；`/model NAME` 直接设置（进程内） |
|
||
| `/compact` | 压缩上下文 |
|
||
| `/details` | 展开/折叠全部 tool 输出 |
|
||
| `/help` | 帮助 |
|
||
|
||
会话落盘：`<workspace>/.agent/sessions/<id>.jsonl` + `CURRENT`。
|
||
|
||
### 协议
|
||
|
||
- OpenAI 兼容 `POST …/chat/completions`：原生 `tools` / SSE `tool_calls`，answer 轮 `tool_choice:none`
|
||
- MiniMax XML `<minimax:tool_call>` 作 fallback
|
||
- Assistant 仅工具时 `content: null` + `tool_calls`（对齐 OpenCode/OpenAI Chat）
|
||
|
||
## CTL tool language
|
||
|
||
```text
|
||
call <id> <name>
|
||
arg <key> <nbytes>
|
||
<raw bytes exactly nbytes>
|
||
end
|
||
```
|
||
|
||
Execution happens only on confirmed `end` (`CTL_EV_CALL_READY`).
|
||
|
||
## Starvation experiment
|
||
|
||
```bash
|
||
make check
|
||
./scripts/replay_starvation.sh
|
||
```
|
||
|
||
CTL vs JSON-buffer 截断数字写入 [docs/eval_tool_cst.md](docs/eval_tool_cst.md) 实验 A；与 mini_calc e2e 一起作为 Tool-loop CST 附录素材（**不**替代 SD 主论文 Markdown→HTML 实验）。
|