XYZ/CST-agent
1
0
Fork 0
forked from WHC/Hermit
Code Pull Requests Activity

OpenCode-style TUI, model probing, sandboxed auto approval

Browse Source 
- TUI: centered home screen with logo, boxed input with mode line, sidebar
  (>=120 cols), Ctrl+P palette, Tab Build/Plan, Shift+Tab approval cycle,
  mouse (cards, cursor, pickers, wheel), /sidebar /mouse /approval
- /models probing: key check on entry (401 re-asks), API models in /model
- Shell sandbox in C: Linux Landlock (writes limited to workspace/tmp,
  ABI>=4 blocks TCP), macOS sandbox_init, rules fallback elsewhere
- Approval modes ask/auto/yolo (default auto); read-only command whitelist;
  ask to rerun outside the sandbox when a command looks blocked
- Upgradable bootstrap scripts (git pull --ff-only, rebuild, reinstall) and
  cst-agent-update; cst-agent --version
- tests: test_sandbox, test_models
This commit is contained in:
WHC
2026-10-05 12:34:46 +08:00
parent a77f27ed59
commit ef63f6d612
25 changed files with 3021 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -12
View File
@@ -13,19 +13,23 @@ See [docs/theory_tool_cst.md](docs/theory_tool_cst.md).
### 5 分钟试用
```bash
# Linux 一键：克隆并编译
git clone https://git.whcself.xyz/WHC/CST-agent.git && ./CST-agent/scripts/bootstrap_linux.sh ./CST-agent
# Linux / WSL / macOS 一键：克隆到 ~/CST-agent、编译、装到 ~/.local/bin
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_linux.sh | bash
# 已有仓库目录内：
# 已有仓库目录内（装到别处：CST_AGENT_PREFIX=/usr/local）
./scripts/bootstrap_linux.sh .
# 装到 PATH（或 sudo make install）
make install PREFIX=$HOME/.local
# 以后升级：拉取最新代码、重新编译并安装（本地有未提交改动时跳过 pull）
cst-agent-update
cst-agent --version
# 在项目目录里直接启动：首次会让你选 provider 并输入 API key（遮罩输入，按 provider 保存）
cd ~/my-project && cst-agent
```
一键脚本可以重复运行：已有仓库会 `git pull --ff-only`，代码有更新时干净重编，然后重新安装；
同时装一个 `cst-agent-update` 命令（等同重跑脚本）。NixOS 上会自动进 `nix-shell` 编译。
之后再启动会沿用上次的 provider、模型和推理强度（low / medium / high / max），不需要任何参数或环境变量。
界面里用 `/provider` 切换（没保存过 key 的会当场询问），`/model`、`/effort` 切换模型和推理强度，`/key` 更换 key。
@@ -118,9 +122,12 @@ API Key：TUI 里输入并按 provider 保存到配置目录的 `credentials`（
### Termux
```bash
# 一键：装依赖、克隆、编译、安装到 $PREFIX/bin
# 一键：装依赖、克隆到 ~/CST-agent、编译、安装到 $PREFIX/bin
curl -fsSL https://git.whcself.xyz/WHC/CST-agent/raw/branch/main/scripts/bootstrap_termux.sh | bash
# 以后升级（重跑上面那条也一样）
cst-agent-update
# 或手动
pkg install git clang make pkg-config binutils libcurl ncurses
git clone https://git.whcself.xyz/WHC/CST-agent.git && cd CST-agent
@@ -185,7 +192,8 @@ cmake -B build-win-tui -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（120），超时整组进程被杀，exit=124 |
| `CST_METRICS=0` / `CST_METRICS_PATH` | 关闭 / 指定计时埋点 JSONL（默认 `.agent/metrics/<session>.jsonl`） |
| `CST_RECORD_SSE=DIR` / `CST_REPLAY_SSE=DIR` | 录制 / 回放原始 SSE 流（`NNNN.sse` + `NNNN.req.json`） |
| `CST_MODELS`、`CST_AUTO_APPROVE=1`、`CST_SHELL`、`CST_EXE_DIR` | 模型列表、自动批准、shell、旁路 busybox |
| `CST_APPROVAL=ask\|auto\|yolo` / `CST_SANDBOX=off` | 审批模式 / 关闭沙箱（回落到只读白名单规则） |
| `CST_MODELS`、`CST_AUTO_APPROVE=1`、`CST_SHELL`、`CST_EXE_DIR` | 模型列表、自动批准（= yolo）、shell、旁路 busybox |
## Run
@@ -211,7 +219,8 @@ cst-agent --headless --prompt 'List files'
| `-N` / `--new` | 开新会话 |
| `-R ID` / `--resume ID` | 打开指定会话（完整 id 或唯一前缀） |
| `-L` / `--list-sessions` | 列出会话（时间、条数、标题）后退出 |
| `-y` / `--yolo` | 本次运行不再确认（等同 `--confirm none`） |
| `-A MODE` / `--approval MODE` | 审批模式 `ask` / `auto`（默认）/ `yolo`，见下文 |
| `-y` / `--yolo` | 等同 `--approval yolo`，只对本次运行有效 |
| `-C LIST` / `--confirm LIST` | 需要确认的类别：`shell,write,net` 的任意组合或 `none` |
| `-T PROFILE` / `--tools PROFILE` | `default` 或 `minimal` |
| `-P NAME` / `-m NAME` / `-e LEVEL` | 本次使用的 provider / 模型 / 推理强度（不传则用上次的） |
@@ -243,7 +252,28 @@ TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
### 权限、撤销与项目说明
- **确认**：默认 shell、写文件、联网三类工具需要确认。弹窗会显示命令或写入的 diff：
- **审批模式**（Shift+Tab 循环切换，`/approval`，`--approval`，`CST_APPROVAL`）：
| 模式 | 写文件 | run_shell | web_fetch |
|---|---|---|---|
| `ask` | 询问 | 询问 | 询问 |
| `auto`（默认） | 直接执行 | 有沙箱 → 在沙箱里直接执行；没有沙箱 → 只读白名单命令直接执行，其余询问 | 询问 |
| `yolo` | 直接执行 | 直接执行（不进沙箱） | 直接执行 |
已保存的规则（`a` / `p`）优先：匹配的命令不进沙箱直接运行。
`ask` / `auto` 的选择会记在 `settings.json`；`yolo` 只在本次运行有效。headless 行为不变（全部自动）。
- **沙箱**（C 实现，`src/sandbox_exec.c`）：
- Linux：Landlock（内核 5.13+，直接 syscall，无需 libseccomp）。子进程只能写工作区、临时目录、`/dev/null`、`/dev/tty`；
读和执行不受限。Landlock ABI ≥ 4（内核 6.7+）时同时禁止 TCP 连接和监听。
- macOS：`sandbox_init` profile，同样只放行工作区和临时目录写入，禁网。
- Android / Termux、Windows、老内核：没有沙箱，自动回落到规则判断（界面显示 `auto · rules`）。
- `CST_SANDBOX=off` 强制关闭沙箱。
- 沙箱里的命令如果像是被拦了（`Permission denied` / `权限不够` / `Read-only file system` 等），会弹窗问
“Rerun outside the sandbox?”：`y` 在沙箱外重跑一次 · `p` 保存命令前缀规则并重跑 · `n` 保留沙箱结果（模型会收到说明）。
- **只读白名单**（无沙箱时 `auto` 用）：`ls cat head tail wc grep rg find pwd echo which file stat du tree`
和 `git status/diff/log/show/branch`；可以用 `|` `&&` `||` `;` 串联，但每段都必须在白名单里。
`find -exec/-delete`、`rg --pre`、`git branch NAME`、`>` 重定向（`2>&1`、`>/dev/null` 除外）、`$(…)`、反引号、
`<(…)`、`sudo`、`rm` 一律不算安全。
- **确认弹窗**会显示命令或写入的 diff：
`y` 允许一次 · `a` 本工具总是允许 · `p` 总是允许这个命令前缀（如 `make`、`git status`）· `n` / Esc 拒绝。
`a` / `p` 写入 `<workspace>/.agent/permissions.json`，`/permissions` 查看，`/permissions reset` 清空。
`sudo`、`rm`、解释器（`python3 -c …`）等危险前缀不会被建议成规则。
@@ -260,9 +290,12 @@ TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
| ← → Home End Ctrl+A/E Ctrl+B/F Alt+B/F | 移动光标（按字 / 按词，支持中文宽字符） |
| Ctrl+W / Ctrl+U / Ctrl+K / Alt+Backspace / Delete | 删词 / 删到行首 / 删到行尾 |
| ↑ / ↓ | 提示历史（多行输入时先在行间移动） |
| Tab | 补全 `/命令` 和 `@文件`；空输入时展开/折叠 Thought |
| Tab | 补全 `/命令` 和 `@文件`；没有可补全时切换 Build / Plan（Plan 只开放只读工具） |
| Shift+Tab | 循环切换审批模式 ask → auto → yolo |
| Ctrl+P | 命令面板（输入过滤，↑↓ / 鼠标选择） |
| Ctrl+O / Ctrl+T | 展开最近 tool 输出 / 开关任务面板 |
| PgUp / PgDn / 鼠标滚轮 | 滚动对话 |
| 鼠标点击 | 展开/折叠 tool 卡片和 Thought、在输入框里定位光标、点模式行切换 Build/Plan、在选择框里选中（`/mouse` 关闭后可用终端原生选择复制） |
| Esc | 取消当前 turn（不会退出） |
| Ctrl+C 两次 / 空输入 Ctrl+D | 退出 |
@@ -274,11 +307,13 @@ TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
|---|---|
| `/help` * | 命令与按键 |
| `/new`、`/session [id]`、`/rename <标题>` *、`/delete [id]` | 新建 / 选择切换 / 命名 / 删除会话 |
| `/provider [name]`、`/model [name]`、`/effort [level]` | 切换 provider（缺 key 时当场输入）、模型、推理强度；都会记住 |
| `/provider [name]`、`/model [name]`、`/effort [level]` | 切换 provider（缺 key 时当场输入并用 `/models` 校验）、模型（列表优先显示 API 实际返回的模型，标 `(api)`）、推理强度；都会记住 |
| `/key` | 输入或更换当前 provider 的 API key（遮罩输入并保存） |
| `/protocol [name]` | 切换工具调用协议 |
| `/tools [on\|off NAME\|minimal\|default]` | 查看或开关工具 |
| `/permissions [reset]` *、`/yolo` *、`/max-steps [N]` * | 权限规则、本次免确认、每轮步数 |
| `/approval [ask\|auto\|yolo]` *、`/yolo` * | 审批模式；本次开关 yolo |
| `/permissions [reset]` *、`/max-steps [N]` * | 权限规则、每轮步数 |
| `/sidebar` *、`/mouse` * | 开关右侧边栏（≥120 列时显示）、开关鼠标 |
| `/status` *、`/todo` * | 会话 / 模型 / 上下文占比 / 设置；任务清单 |
| `/undo`、`/retry` | 撤销上一轮文件改动；丢弃上一条回复重问 |
| `/diff [path]` * | `git status` + `git diff` |