# 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 实验）。