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/eval_tool_cst.md。

能不能用来工作？

可以：有监督的本地小改动 / 探索本仓库（TUI + 工具 + 权限确认）。
不宜：无人值守长任务或当 CI 主力（网关偶发空答、无完整 diff UI）。

5 分钟试用

# Linux 一键：克隆并编译
git clone https://git.whcself.xyz/WHC/CST-agent.git && ./CST-agent/scripts/bootstrap_linux.sh ./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。

平台	一键脚本
Linux	scripts/bootstrap_linux.sh
Termux	scripts/bootstrap_termux.sh
Windows 交叉构建（在 Linux 上）	scripts/bootstrap_windows.sh → dist/windows-x86_64/
Windows 运行	拷贝 dist 后 scripts/run_windows.bat

迷你验收工程（论文案例）

故意带 bug 的小计算器：fixtures/mini_calc/（任务书 TASK.md）。

./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。

Build

Make（Linux 默认）

cd agent
make
make check

CMake（推荐跨编译器 / 交叉）

# 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

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。交叉构建：

./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。

项	默认（未设 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

# 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

call <id> <name>
arg <key> <nbytes>
<raw bytes exactly nbytes>
end

Execution happens only on confirmed end (CTL_EV_CALL_READY).

Starvation experiment

make check
./scripts/replay_starvation.sh

CTL vs JSON-buffer 截断数字写入 docs/eval_tool_cst.md 实验 A；与 mini_calc e2e 一起作为 Tool-loop CST 附录素材（不替代 SD 主论文 Markdown→HTML 实验）。