# CST-Agent 本地 coding agent：终端 TUI、可选 WebUI / 桌面 GUI，在工作区里读改文件、跑命令、管会话。 C11 实现，OpenAI 兼容网关（DeepSeek / Kimi / MiniMax / OpenAI 等）。 **适合**：有监督的本地改动与仓库探索（权限确认、diff、`/undo`、沙箱）。 **慎用**：完全无人值守的长任务；headless 默认自动批准。 文档索引：[docs/README.md](docs/README.md)。 --- ## 安装 ### Linux / WSL / macOS（推荐） ```bash # 预编译包（快；失败则自动回退源码编译） 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 ``` 已有仓库目录： ```bash ./scripts/bootstrap_linux.sh . # 源码 ./scripts/bootstrap_linux.sh . --release # 只装 Release 二进制 cst-agent-update # 之后升级 cst-agent --version ``` [Release](https://git.whcself.xyz/WHC/CST-agent/releases) 也提供静态 musl 包 `cst-agent-VERSION-linux-{x86_64,x86,aarch64}.tar.gz`（旁有 `.sha256`），解压后把 `cst-agent` 放进 `PATH` 即可。 ### Windows 10 1903+ ```powershell 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](docs/README-windows.md)。 ### Termux ```bash curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_termux.sh | bash ``` ### 第一次用 ```bash cd ~/my-project && cst-agent ``` 首次选择 provider 并输入 API key（遮罩输入，按 provider 存到配置目录 `credentials`，权限 0600）。 之后用 `/provider`、`/model`、`/effort`、`/key` 切换；选择会记在 `settings.json`。 完整环境变量：[docs/env_openai.md](docs/env_openai.md)。 多设备议会：[docs/parliament.md](docs/parliament.md)。 | 平台 | 脚本 | |---|---| | Linux / macOS | [`scripts/bootstrap_linux.sh`](scripts/bootstrap_linux.sh) | | Termux | [`scripts/bootstrap_termux.sh`](scripts/bootstrap_termux.sh) | | Windows 安装 | [`scripts/install_windows.ps1`](scripts/install_windows.ps1) | | Linux 静态包 | [`scripts/package_linux.sh`](scripts/package_linux.sh) `x86_64\|x86\|aarch64` | | Windows 交叉构建 | [`scripts/bootstrap_windows.sh`](scripts/bootstrap_windows.sh) | | Windows 原生（MSYS2） | [`scripts/bootstrap_msys2.sh`](scripts/bootstrap_msys2.sh) | --- ## 构建 ```bash 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](docs/compat.md)。 ```bash # 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](app/README.md)。 Android APK：[docs/android.md](docs/android.md)。 ### CI 与发布 推送 `main` / `v*` 时 [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) 会：TinyCC `check` → 打 Linux/Windows 发行包 → `scripts/ci_publish.sh` 上传 Gitea Release。 共用逻辑：[`scripts/lib_release.sh`](scripts/lib_release.sh)。本地上传：`GITEA_TOKEN=... scripts/release.sh dist/cst-agent-*`。 --- ## 用法速览 ```bash 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` | 工作区 | 会话目录：`/.agent/sessions//`（自带 `.gitignore`）。WebUI 协议：[docs/webui.md](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](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](docs/plugins.md)）；worker 编排（[docs/workers.md](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](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 | --- ## 开发者备忘 ```bash 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` 随仓库提供。