CST-Agent

本地 coding agent：终端 TUI、可选 WebUI / 桌面 GUI，在工作区里读改文件、跑命令、管会话。 C11 实现，OpenAI 兼容网关（DeepSeek / Kimi / MiniMax / OpenAI 等）。

适合：有监督的本地改动与仓库探索（权限确认、diff、/undo、沙箱）。
慎用：完全无人值守的长任务；headless 默认自动批准。

文档索引：docs/README.md。

---

安装

Linux / WSL / macOS（推荐）

# 预编译包（快；失败则自动回退源码编译）
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

已有仓库目录：

./scripts/bootstrap_linux.sh .              # 源码
./scripts/bootstrap_linux.sh . --release    # 只装 Release 二进制
cst-agent-update                            # 之后升级
cst-agent --version

Release 也提供静态 musl 包 cst-agent-VERSION-linux-{x86_64,x86,aarch64}.tar.gz（旁有 .sha256），解压后把 cst-agent 放进 PATH 即可。

Windows 10 1903+

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。

Termux

curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_termux.sh | bash

第一次用

cd ~/my-project && cst-agent

首次选择 provider 并输入 API key（遮罩输入，按 provider 存到配置目录 credentials，权限 0600）。 之后用 /provider、/model、/effort、/key 切换；选择会记在 settings.json。

完整环境变量：docs/env_openai.md。
多设备议会：docs/parliament.md。

平台	脚本
Linux / macOS	scripts/bootstrap_linux.sh
Termux	scripts/bootstrap_termux.sh
Windows 安装	scripts/install_windows.ps1
Linux 静态包	scripts/package_linux.sh x86_64|x86|aarch64
Windows 交叉构建	scripts/bootstrap_windows.sh
Windows 原生（MSYS2）	scripts/bootstrap_msys2.sh

---

构建

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。

# 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。
Android APK：docs/android.md。

CI 与发布

推送 main / v* 时 .gitea/workflows/ci.yml 会：TinyCC check → 打 Linux/Windows 发行包 → scripts/ci_publish.sh 上传 Gitea Release。
共用逻辑：scripts/lib_release.sh。本地上传：GITEA_TOKEN=... scripts/release.sh dist/cst-agent-*。

---

用法速览

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。

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。

内置能力（摘要）

• 文件：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）；worker 编排（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。
写文件前自动快照，/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

---

开发者备忘

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 随仓库提供。