Initial CST-Agent: portable Linux/Termux/Windows coding agent.
Vendored sashidown, OpenAI-compatible env (OPENAI_*), and bootstrap scripts. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
WHC
@@ -0,0 +1,198 @@
|
||||
# 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 实验）。
|
||||
Reference in New Issue
Block a user