diff --git a/README.md b/README.md index d76091c..f3ba88e 100644 --- a/README.md +++ b/README.md @@ -1,548 +1,195 @@ # CST-Agent -C11 OpenCode-like carrier that extends paper **CST** (confirmation frontier / irreversible emission) from Markdown→HTML to the **agent tool loop**. +本地 coding agent：终端 TUI、可选 WebUI / 桌面 GUI，在工作区里读改文件、跑命令、管会话。 +C11 实现，OpenAI 兼容网关（DeepSeek / Kimi / MiniMax / OpenAI 等）。 -See [docs/theory_tool_cst.md](docs/theory_tool_cst.md). -评测/反哺论文素材：[docs/eval_tool_cst.md](docs/eval_tool_cst.md)。 +**适合**：有监督的本地改动与仓库探索（权限确认、diff、`/undo`、沙箱）。 +**慎用**：完全无人值守的长任务；headless 默认自动批准。 -## 能不能用来工作？ +文档索引：[docs/README.md](docs/README.md)。 -**可以**：有监督的本地改动 / 探索仓库（TUI + 13 个内置工具 + 带 diff 的权限确认 + `/undo`）。 -**不宜**：无人值守长任务或当 CI 主力（网关偶发空答；headless 模式默认自动批准）。 +--- -### 5 分钟试用 +## 安装 + +### Linux / WSL / macOS（推荐） ```bash -# Linux / WSL / macOS 一键：克隆到 ~/CST-agent、编译、装到 ~/.local/bin +# 预编译包（快；失败则自动回退源码编译） +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 - -# 已有仓库目录内（装到别处：CST_AGENT_PREFIX=/usr/local） -./scripts/bootstrap_linux.sh . - -# 以后升级：拉取最新代码、重新编译并安装（本地有未提交改动时跳过 pull） -cst-agent-update -cst-agent --version - -# 在项目目录里直接启动：首次会让你选 provider 并输入 API key（遮罩输入，按 provider 保存） -cd ~/my-project && cst-agent ``` -不想编译：[Release](https://git.whcself.xyz/WHC/CST-agent/releases) 里有静态链接的 Linux 单文件 -（`cst-agent-VERSION-linux-{x86_64,x86,aarch64}.tar.gz`，musl，任何发行版都能直接跑），解压后把 `cst-agent` -放进 `PATH` 即可；每个文件旁边有 `.sha256`。 +已有仓库目录： -Windows 10 1903+（PowerShell，不需要管理员）： +```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 -# 新开终端后：cd 到项目目录运行 cst-agent；升级用 cst-agent-update ``` -也可以下载 Release 里的安装包 `cst-agent-VERSION-windows-x86_64-setup.exe`（按用户安装、自动加 PATH、 -开始菜单有 WebUI 入口），或便携版 zip。详见 [docs/README-windows.md](docs/README-windows.md)。 - -一键脚本可以重复运行：已有仓库会 `git pull --ff-only`，**增量编译**后重新安装（`CST_AGENT_CLEAN=1` 才强制 clean）； -同时装 `cst-agent-update` 与 `cst-agent-service`（议会席位服务辅助）。NixOS 上会自动进 `nix-shell` 编译。 - -之后再启动会沿用上次的 provider、模型和推理强度（low / medium / high / max），不需要任何参数或环境变量。 -界面里用 `/provider` 切换（没保存过 key 的会当场询问），`/model`、`/effort` 切换模型和推理强度，`/key` 更换 key。 - -完整环境变量说明：[docs/env_openai.md](docs/env_openai.md)。 -多设备议会（密码 Realm / 主席 / 常驻同步）：[docs/parliament.md](docs/parliament.md)。 - -| 平台 | 一键脚本 | -|---|---| -| Linux | [`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)（从 Release 安装），之后 `cst-agent-update` | -| Linux 静态发行包（musl 交叉） | [`scripts/package_linux.sh`](scripts/package_linux.sh) `x86_64\|x86\|aarch64` → `dist/*.tar.gz` | -| Windows 交叉构建（在 Linux 上） | [`scripts/bootstrap_windows.sh`](scripts/bootstrap_windows.sh) → `dist/windows-x86_64/`、zip 和安装包 | -| Windows 原生构建（MSYS2 UCRT64） | [`scripts/bootstrap_msys2.sh`](scripts/bootstrap_msys2.sh) → `dist/windows-x86_64/` | - -### 迷你验收工程（论文案例） - -故意带 bug 的小计算器：[`fixtures/mini_calc/`](fixtures/mini_calc/)（任务书 `TASK.md`）。 - -```bash -./scripts/e2e_mini_calc.sh --baseline-only # 无 API：证明初始测试 RED -./scripts/e2e_mini_calc.sh --provider deepseek --protocol ctl # 有 key -``` - -更多夹具（每个都有 `TASK.md` + `check.sh`）：`makefile_tab`（写含 TAB 的 Makefile）、 -`big_file`（写 5000 字节文件）、`test_fix_test`（先跑测试→修→再跑测试）、 -`multi_file_refactor`（跨文件改名 + 修 bug，适合 `edit_file` / `grep`）、 -`ask_or_todo`（必须用 `todo_write` 规划并全部完成；无人回答 `ask_user`）。 -后两个需要 `--tools default`（脚本默认 `minimal`，即论文用的 4 个工具）。 - -```bash -scripts/e2e_fixture.sh makefile_tab --provider deepseek --protocol native-inc -scripts/e2e_fixture.sh multi_file_refactor --provider deepseek --tools default -# 批量实验：协议 x 模型 x 夹具 x N 次 → results.csv + summary.md -scripts/run_matrix.sh -p "native-eos native-inc ctl ctl-heredoc xml" \ - -m "deepseek:deepseek-flash deepseek:deepseek-v4-pro" -n 3 -r -``` - -口径：`pass` / `fail` / `agent_error` / `timeout` — 见 [docs/eval_tool_cst.md](docs/eval_tool_cst.md)。 - -## Build - -### Make（Linux 默认） - -```bash -cd CST-agent -make -j$(nproc) # 增量编译；头文件依赖走 -MMD，测试复用 libcstcore.a -make -j$(nproc) check # 并行编测试二进制，再串行跑 -make asan # AddressSanitizer + UBSan 构建并跑全部测试 -make CC=tcc AR=ar check # TinyCC：整套构建 + 测试十几秒（CI 的校验就是这条） -make install PREFIX=$HOME/.local # 或 sudo make install（默认 /usr/local） -make install-service PREFIX=$HOME/.local # 可选：systemd --user 议会服务单元 -``` - -NixOS：`nix-shell --run 'make -j$(nproc) && make install PREFIX=$HOME/.local'`（CLI）；Qt 桌面用 `nix-build` / `cst-agent-app`。 -macOS：`brew install curl ncurses pkg-config` 后直接 `make`（Makefile 会找 Homebrew 的 keg-only 库）。 -各平台细节与验收清单见 [docs/compat.md](docs/compat.md)。 - -### 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：用一键脚本（见下方“Windows 发行包”），会先编译静态依赖 -./scripts/bootstrap_windows.sh -``` - -依赖：`gcc`、`clang` 或 `tcc`（0.9.27 mob 以上）、`libcurl`、TUI 需 `ncursesw`（Windows 版用打过补丁的 ncurses 6.6，脚本自动编译）。 -### 桌面 GUI（Qt/QML，可选） - -把引擎放进同一个进程的窗口前端（无端口、无第二个进程）：`app/`，细节见 [app/README.md](app/README.md)。 - -```bash -# NixOS / nix：装进用户 profile（PATH + 菜单项 + 图标），卸载 nix profile remove cst-agent -nix profile add --file . - -# 其他发行版（需要 Qt 6 的 Quick/Qml/QuickControls2 与 libcurl） -cmake -B build-app -DCST_BUILD_APP=ON -DCMAKE_BUILD_TYPE=Release -cmake --build build-app -j && cmake --install build-app --component app --prefix ~/.local -``` - -菜单里启动时工作区=启动目录（即 `$HOME`）；在项目目录里 `cst-agent-app` 启动则工作区就是那个目录。 - -Sashidown（`vendor/sashidown`）与 cJSON（`vendor/cjson`，MIT）已随仓库提供。 -API Key：TUI 里输入并按 provider 保存到配置目录的 `credentials`（权限 0600）；`/key` 更换，`--ask-key` 在命令行输入。 -`--api-key` 只用于本次进程、不落盘；`DEEPSEEK_API_KEY` 等环境变量和 `CST_API_KEY` 仅作为没有保存 key 时的兜底（方便 CI）。 - -## 平台支持矩阵 - -| OS | Arch | 编译器 | Headless | TUI | Shell | -|---|---|---|---|---|---| -| Linux（glibc / musl） | x86_64 / x86 / aarch64 | GCC, Clang, TinyCC | yes | ncursesw | `/bin/sh` 或旁路 `busybox` | -| WSL2 | x86_64 | 同 Linux | yes | ncursesw | `/bin/sh`（工作区建议放在 Linux 文件系统内） | -| macOS | arm64 / x86_64 | Apple Clang | yes | ncurses（Homebrew） | `/bin/sh` | -| Android Termux | aarch64 / … | Clang (Termux) | yes | ncurses（Termux 包） | `$PREFIX/bin/sh`；可旁路 busybox | -| Windows 10 1903+ | x86_64 | MinGW-w64 GCC（UCRT） | yes | ncurses 6.6（Windows 控制台） | **捆绑 busybox-w32** | - -### WebUI（`--web`） - -同一个二进制内置一个 HTTP + SSE 前端：`cst-agent --web`（默认 `http://127.0.0.1:8787/`）。 -它和 TUI 是同一引擎的两个前端，浏览器里能流式看回答、点审批、切会话、贴图。 -协议是一份稳定的 JSON + SSE 接口，供以后的专用客户端复用。详见 [docs/webui.md](docs/webui.md)。 - -```bash -cst-agent --web # 本机浏览器打开 http://127.0.0.1:8787/ -cst-agent --web --web-port 0 # 端口交给系统，启动日志里给 URL -cst-agent --web --web-dev ./web # 开发前端：直接读目录，改完刷新 -cst-agent --web --web-host 0.0.0.0 --web-token 口令 # 手机/局域网访问 -sh scripts/e2e_webui.sh # 用录制流跑完整轮次，不需要 API key -``` - -不带 TUI 的构建也可以开 WebUI（`cmake -DCST_BUILD_WEBUI=ON -DCST_BUILD_TUI=OFF`）； -`-DCST_BUILD_WEBUI=OFF` 时 `--web` 只打印一条提示。 +或下载 `cst-agent-VERSION-windows-x86_64-setup.exe` / 便携 zip。详见 [docs/README-windows.md](docs/README-windows.md)。 ### Termux ```bash -# 一键：装依赖、克隆到 ~/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 -make && make install # 装到 Termux 的 $PREFIX/bin，之后任意目录运行 cst-agent -# 可选：旁路 Unix busybox -# ./scripts/build_third_party_mingw.sh busybox-unix ``` -环境：`PREFIX` 自动用于找 `sh`；`CST_EXE_DIR` / `argv[0]` 用于定位旁路 busybox（`/proc/self/exe` 受限时）。 -临时目录：依次试 `$TMPDIR`、`$PREFIX/tmp`、`/tmp`、`/var/tmp`、`~/.cache/cst-agent/tmp`，用第一个真能建文件的， -并写回 `TMPDIR` 给 shell 子进程和沙箱用（Termux 的 `/tmp` 常常不存在或被 SELinux 拒绝）。 - -### Linux 静态发行包 +### 第一次用 ```bash -scripts/package_linux.sh x86_64 # 或 x86 / aarch64；CST_LINUX_CHECK=1 顺便跑 make check +cd ~/my-project && cst-agent ``` -用 Bootlin 的 musl 交叉 gcc（固定版本、校验 sha256）静态编译 mbedTLS、curl 8.22（只开 HTTP/HTTPS）和宽字符 ncurses， -再以 `STATIC=1` 和 `-Werror` 编出 `cst-agent`，产物是 `dist/cst-agent-VERSION-linux-ARCH.tar.gz`（+ `.sha256`）。 -宿主需要 `cmake ninja make perl` 以及 `tic`/`infocmp` 和终端条目（Debian：`ncurses-bin ncurses-term`）。 -ncurses 会去常见目录找 terminfo，找不到时用编进去的 `xterm-256color`、`xterm`、`screen-256color`、`tmux-256color`、`linux`、`vt100`。 -CA 证书：`CST_CA_BUNDLE` → `SSL_CERT_FILE` → 各发行版的常见位置（Debian/Ubuntu、Fedora/RHEL、openSUSE、Alpine）。 +首次选择 provider 并输入 API key（遮罩输入，按 provider 存到配置目录 `credentials`，权限 0600）。 +之后用 `/provider`、`/model`、`/effort`、`/key` 切换；选择会记在 `settings.json`。 -### Windows 发行包 +完整环境变量：[docs/env_openai.md](docs/env_openai.md)。 +多设备议会：[docs/parliament.md](docs/parliament.md)。 -见 [docs/README-windows.md](docs/README-windows.md)（安装、编码、沙箱、构建、已知限制）。 - -```bash -./scripts/bootstrap_windows.sh # Linux 交叉编译；Windows 上在 MSYS2 UCRT64 里用 scripts/bootstrap_msys2.sh -``` - -产物：`dist/windows-x86_64/`（静态链接的 `cst-agent.exe` + `busybox.exe`，无其他 DLL）、 -`dist/cst-agent-VERSION-windows-x86_64.zip`，以及装了 `makensis` 时的安装包 `dist/cst-agent-VERSION-windows-x86_64-setup.exe`。 - -### CI 与 Release - -`.gitea/workflows/ci.yml`：TinyCC 校验（构建、`make check`、WebUI 端到端）通过后，用 gcc（`-Werror`）打发行包—— -Linux x86_64 / x86 / aarch64 静态包（前两者跑 `make check`，aarch64 用 qemu 冒烟）， -Windows x86_64 的 zip 和安装包（Debian mingw-w64 UCRT + NSIS）。 -推送到 `main` 或 `v*` tag 时各任务经 `scripts/ci_publish.sh` 上传到 Gitea Release `vVERSION`（同名资源会被替换）； -仓库可设 `RELEASE_TOKEN`（`write:repository`），否则用任务自带 token。 -共用逻辑在 `scripts/lib_release.sh`（版本号、sha256、打包、下载镜像）。 -本地：`GITEA_TOKEN=... scripts/release.sh dist/cst-agent-*.tar.gz dist/cst-agent-*.zip dist/cst-agent-*-setup.exe`。 -快速安装预编译包：`scripts/bootstrap_linux.sh --release`（失败则回退源码编译）。 - -环境变量：`CST_SHELL`、`CST_EXE_DIR`、`CST_AUTO_APPROVE` 等。 - -## Defaults (API) - -`--provider`（或 `CST_PROVIDER`）选择预设；显式的 `--api-base` / `--model` / 环境变量优先。 - -| 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-v4-pro`） | `DEEPSEEK_API_KEY` | -| `kimi` | `https://api.moonshot.ai/v1` | `kimi-k3`（另有 `kimi-k2.6`、`kimi-k2.7-code`） | `MOONSHOT_API_KEY` | -| `kimi-code` | `https://api.kimi.ai/coding/v1` | `k3`（另有 `k3-256k`、`kimi-for-coding`、`kimi-for-coding-highspeed`） | `KIMI_API_KEY` | -| `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_API_KEY` | -| `teamorouter` | `https://api.teamorouter.com/v1` | 登录后自动取 `/models` 第一个（`/model` 可换） | `TEAMOROUTER_API_KEY` | - -| 用途 | 来源（优先级从高到低） | +| 平台 | 脚本 | |---|---| -| Provider | `--provider` → `CST_PROVIDER` → 上次使用 → `minimax` | -| Key | `--api-key` → 已保存的 key（`credentials`）→ provider 的 Key 变量 → `CST_API_KEY` → TUI 询问 | -| Base（含 `/v1`） | `--api-base` → `CST_API_BASE` → `OPENAI_BASE_URL` → `OPENAI_API_BASE` → 预设 | -| Model | `--model` → `CST_MODEL` → `OPENAI_MODEL` → 该 provider 上次使用的模型 → 预设 | -| 推理强度 | `--effort` → `CST_EFFORT` → 上次使用 → `medium` | +| 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) | -“上次使用”记在配置目录的 `settings.json`（TUI 里切换时更新；headless 运行不改它）。 -推理强度会按 provider 适配：DeepSeek/OpenAI 使用 `reasoning_effort`，Kimi K3 使用同名字段，Kimi K2 使用 `thinking` 并保留 `reasoning_content`。Kimi 默认开启 1 小时隐式 prompt cache，可用 `CST_KIMI_CACHE_TTL=5m|1h` 调整，或用 `CST_NO_CACHE_HINTS=1` 关闭提示。 +--- -Kimi 与 DeepSeek 还提供官方联网工具：`web_search` 调用 provider 的 Search API，`web_fetch` 调用 provider 的 Fetch API；其它 provider 继续使用通用 HTTP 抓取。 - -`kimi` 是按量计费的 Kimi 开放平台，`kimi-code` 是会员订阅的 Kimi Code API；两者的 Base URL 和 API Key 不通用。 - -详见 [docs/env_openai.md](docs/env_openai.md)。 - -| 变量 | 作用（默认） | -|---|---| -| `CST_PROTOCOL` / `--protocol` | 工具调用协议（`native-eos`） | -| `CST_TOOLS` / `--tools` | 工具集：`default`（全部）/ `minimal`（论文 4 件套） | -| `CST_MODE` / `--mode` | 工作模式：`coding`（默认，代码口径）/ `general`（通用助手口径） | -| `CST_EFFORT` / `--effort` | 推理强度 `low` / `medium` / `high` / `max` | -| `CST_CONFIRM` / `--confirm` | 哪些类别要确认：`shell,write,net`（默认）或 `none` | -| `CST_MAX_STEPS` / `--max-steps` | 每个用户回合最多调用模型几次（30） | -| `CST_TOOL_OUT_CAP` | 单个工具输出发给模型的字节上限（16384，保留头 60% + 尾 40%） | -| `CST_CTX_WINDOW` | 发给模型的最近非 system 消息条数（80） | -| `CST_CTX_TOKENS` / `CST_AUTO_COMPACT=0` | 覆盖模型上下文窗口大小 / 关闭自动压缩（用到 75% 时自动 `/compact`） | -| `CST_NO_PROJECT_NOTES=1` | 不把工作区的 `AGENTS.md` 注入 system prompt | -| `NO_COLOR` / `CST_ASCII=1` | 关闭颜色 / 强制 ASCII 图形（非 UTF-8 终端自动退化） | -| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（默认不限），设了才在超时后整组杀进程，exit=124 | -| `CST_METRICS=0` / `CST_METRICS_PATH` | 关闭 / 指定计时埋点 JSONL（默认 `.agent/metrics/.jsonl`） | -| `CST_RECORD_SSE=DIR` / `CST_REPLAY_SSE=DIR` | 录制 / 回放原始 SSE 流（`NNNN.sse` + `NNNN.req.json`） | -| `CST_APPROVAL=ask\|auto\|yolo` / `CST_SANDBOX=off\|landlock\|seccomp` | 审批模式 / 关闭沙箱（回落到只读白名单规则）或只用指定沙箱 | -| `CST_CA_BUNDLE` | HTTPS 用的 CA 证书文件（默认：`SSL_CERT_FILE`、libcurl 自带路径、常见发行版位置；Windows 用系统证书库） | -| `CST_MODELS`、`CST_AUTO_APPROVE=1`、`CST_SHELL`、`CST_EXE_DIR` | 模型列表、自动批准（= yolo）、shell、旁路 busybox | - -## Run +## 构建 ```bash -# TUI（工作目录 = 当前目录；Assistant Markdown 经 Sashidown CST 渲染） -cst-agent +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 议会单元 +``` -# Local CTL demo (no API) -cst-agent --demo-ctl +NixOS：`nix-shell --run 'make -j$(nproc)'`。macOS：`brew install curl ncurses pkg-config` 后直接 `make`。 +平台细节：[docs/compat.md](docs/compat.md)。 -# 在命令行输入并保存当前 provider 的 key（不回显） +```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 - -# Headless（默认 auto-approve shell/写文件） -cst-agent --headless --prompt 'List files' ``` -会话相关命令行参数： - | 参数 | 作用 | |---|---| -| `-c` / `--continue` | 打开上次的会话（默认行为） | -| `-N` / `--new` | 开新会话 | -| `-R ID` / `--resume ID` | 打开指定会话（完整 id 或唯一前缀） | -| `-L` / `--list-sessions` | 列出会话（时间、条数、标题）后退出 | -| `--migrate-store` | 把旧版本的会话（扁平 `.jsonl`）搬进新布局后退出 | -| `-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` | -| `-M MODE` / `--mode MODE` | 工作模式 `coding`（默认）/ `general`，也读 `CST_MODE`，并记进 `settings.json` | -| `-P NAME` / `-m NAME` / `-e LEVEL` | 本次使用的 provider / 模型 / 推理强度（不传则用上次的） | -| `-a` / `--ask-key` | 在命令行输入并保存当前 provider 的 key | +| `-c` / `-N` / `-R ID` / `-L` | 继续上次 / 新会话 / 恢复 / 列表 | +| `-A ask\|auto\|yolo` / `-y` | 审批模式 | +| `-T default\|minimal` | 工具集（`minimal` = 读写 shell 四件套） | +| `-M coding\|general` | 工作模式 | +| `-P` / `-m` / `-e` | provider / 模型 / 推理强度 | +| `-w DIR` | 工作区 | -工作目录默认就是当前目录（`-w DIR` 可指定别的目录）。 +会话目录：`/.agent/sessions//`（自带 `.gitignore`）。WebUI 协议：[docs/webui.md](docs/webui.md)。 -会话落盘：一个会话一个目录 `/.agent/sessions//`（`session.jsonl` 转录、`title`、`attachments/`、子 agent 的 `sub-N.jsonl`）+ `CURRENT` 指向下次打开的会话；id 是 uuid，两台机器共用一份工作目录也不会撞。旧版本写的扁平会话仍然可读，`--migrate-store` 一次搬进新布局（幂等）。`.agent/` 自带 `.gitignore`，不会被误提交。 +### 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` | -| 工具 | 类别 | 说明 | -|---|---|---| -| `read_file` | 读 | 支持 `offset` / `limit` 分段读和行号 | -| `list_dir` | 读 | 目录树（`depth`），遵守 `.gitignore`，跳过 `.git` / `node_modules` 等 | -| `glob` | 读 | 按通配符找文件（支持 `**`） | -| `grep` | 读 | 正则搜索内容，可限定路径 / glob、忽略大小写、带上下文 | -| `write_file` | 写 | 整文件写入（自动建父目录） | -| `edit_file` | 写 | 精确片段替换（必须唯一，或 `replace_all`） | -| `apply_patch` | 写 | 应用 unified diff，多文件原子生效 | -| `delete_file` / `move_file` | 写 | 删除 / 移动（重命名）文件 | -| `run_shell` | shell | 非交互命令，超时整组进程被杀，Esc 可中断 | -| `web_fetch` | 网络 | 抓取 URL，HTML 转纯文本 | -| `web_search` | 网络 | 使用 Kimi 或 DeepSeek 的官方 Search API 搜索实时网页 | -| `download` | 网络 | 把 URL 抓成工作区里的文件（≤128 MB，超限删掉残file）；字节落在磁盘上，不进模型上下文 | -| `read_pdf` | 读 | 读 PDF 的文本层（`read_file` 因二进制拒收的缺口），带页数，文本默认截到 256 KiB | -| `clipboard_read` | 读 | 读系统剪贴板里的文本（`max_bytes` 默认 64 KiB，超出截断并说明） | -| `clipboard_write` | 写 | 把文本放进系统剪贴板（按写类权限确认；本机走 pbcopy / wl-copy / xclip / Win32 API） | -| `todo_write` | 元 | 维护任务清单（TUI 右侧面板，Ctrl+T 开关） | -| `ask_user` | 询问 | 向用户提问（可给选项）；headless 下返回错误让模型自行决定 | -| `skill` | 元 | 加载一个 skill 的说明（`SKILL.md`）或其中的文件；有 skill 时才出现 | -| `task` | 子 agent | 把独立任务交给子 agent（`general` / `explore` / `plan` / 自定义角色），只返回最终报告 | -| `deliver_file` | 交付 | 把工作区里的成品文件复制进会话库并交给用户（任意字节，≤64 MB）：前端画成文件卡，可打开 / 分享；带 `for_user` 标记，永不进模型上下文 | -| `md_to_html` | 文档 | 把 markdown（文本或工作区 `.md`）渲染成一份自包含 HTML 文档写进工作区并交付成文件卡：utf-8、标题、内联样式，无脚本无外链 | -| `md_to_pdf` | 文档 | 图形前端（桌面 / APK）自带：把 markdown 或工作区 `.md` / `.html` 排成 A4 PDF（15 mm 边距，自动分页）写进工作区并交付成文件卡；不需要 Qt PrintSupport，手机上也能出 | -| `session_search` | 读 | 在过去和当前的所有会话转录里搜子串，给会话 id、条数、标题和匹配行（行号 + 角色 + 上下文）；有预算：`max_bytes`（默认 32 MB）、`max_seconds`（默认 5 s），超 64 KiB 的单行跳过，被预算截断时结果里写清楚 | -| `device_info` | 读 | 报告运行环境：系统 / 架构 / CPU 数、工作区、沙箱、模型与审批模式、config / temp / 程序目录、pid（审批策略名 `device`） | +优先级：CLI → 已保存 credentials → 环境变量 → TUI 询问。详见 [docs/env_openai.md](docs/env_openai.md)。 -插件工具和 MCP 工具（`mcp____`）在运行时注册，和内置工具走同一套审批与 `/tools` 开关。 -同一步里的多个只读调用（读文件、搜索、只读子 agent）会并行执行（最多 4 个）。 +### 内置能力（摘要） -`--tools minimal` 只保留 `read_file` / `run_shell` / `write_file` / `apply_patch`（论文实验口径）。 -TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。 +- **文件**：`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)） -### 工作模式（coding / general） +同一步里连续只读调用会自动并行（默认最多 8，`CST_PAR_MAX` 可调）。截断结果带 `[truncated … evidence=ID]`，用 `evidence_read` 续读。 -`--mode general`（或 TUI 里 `/mode general`、WebUI 运行设置里的「工作模式」、`CST_MODE=general`）把默认口径 -从"代码助手"换成"通用助手"：工作流从改代码/跑测试换成"先弄清要什么、再动手、给出处和不确定的地方"， -工具说明从"仓库"改成"文件与数据"，并说明 `web_fetch` 可以拿外部资料；`/status` 第一行显示当前模式， -切换后 history 里会留一条系统提示。默认仍是 `coding`，选择记在 `settings.json`； -`--tools minimal`（论文口径）的提示词按字节冻结，不受模式影响。 +### 审批与沙箱 -### 剪贴板与文档附件 +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` 会注入系统提示。 -- **剪贴板**：`clipboard_read` / `clipboard_write` 两个工具（写剪贴板是不可逆发射，要确认）； - TUI 里 `/attach paste` 在剪贴板里没有图片时，把剪贴板的**文本**放进输入框（丢掉 CR 与控制字节，尊重输入长度上限）。 -- **附件**（`/attach `、拖入终端、剪贴板图片都算）：图片按原样存进会话目录，发给模型时是 image part； - **PDF 在摄取时就抽出文本层**（零依赖解析器：Flate / ASCIIHex / ASCII85、对象流、CID 字体 ToUnicode、 - 内联图像跳过），存的是文本、`mime` 仍是 `application/pdf`；其余文件必须是 UTF-8 文本。 - 文档以 **text part 内联**发出，所以不受 `CST_NO_IMAGES` 或非视觉模型影响；图片照旧会被换成一行"未发送"说明。 - 上限：单个附件 ≤16 MB（文档文本 ≤4 MiB），每条消息最多 8 个。 - 加密 PDF、扫描件（无文本层）会被明确拒绝并说明原因； - `view_image` 仍只收图片，文本/PDF 走 `/attach`。 +### TUI 常用 -### 权限、撤销与项目说明 - -- **审批模式**（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`； - 读、执行和联网不受限。 - - Linux 没有 Landlock 时（Android / Termux、WSL、老发行版；内核 5.5+，x86_64 / aarch64）：seccomp user-notify - （界面显示 `auto · seccomp`）。子进程的写类系统调用（带写标志的 open、创建 / 删除 / 改名 / 链接 / chmod 等）先交给 - agent 里的监督线程，按真实路径判断是否在工作区、临时目录或 `/dev/null` 等之内，不在就返回 `EACCES`。联网不受限。 - 读、执行和已打开文件的写入不检查。它防的是误操作而不是恶意程序：检查之后内核会再读一次路径，多线程程序可以趁机换掉。 - 探测还会确认能读直接子进程的内存；`ptrace_scope=2` 且无 `CAP_SYS_PTRACE` 时 seccomp 不会启用。 - 比 shell 活得久的后台进程：桌面发行版开着 Yama（`ptrace_scope` ≥ 1）时它们的受检写入会被拒；命令结束后一律失败。 - - macOS：`sandbox_init` profile，同样只放行工作区和临时目录写入，不限制联网。 - - Windows 10 1903+：Low 完整性级别的受限令牌 + Job Object（界面显示 `auto · lowil`）。第一次在工作区运行时 - 给它打上 Low 标签，之后子进程只能写工作区和沙箱临时目录，读不到凭据文件；不限制联网。 - `/sandbox` 查看、`/sandbox reset-labels` 撤销标签，详见 [docs/README-windows.md](docs/README-windows.md)。 - - 更老的内核：没有沙箱，自动回落到规则判断（界面显示 `auto · rules`）。 - - `CST_SANDBOX=off` 强制关闭沙箱；`CST_SANDBOX=landlock` / `seccomp` / `lowil` 只用指定的那种。 - - 沙箱里的命令如果像是被拦了（`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` 写入 `/.agent/permissions.json`，`/permissions` 查看，`/permissions reset` 清空。 - `sudo`、`rm`、解释器（`python3 -c …`）等危险前缀不会被建议成规则。 -- **撤销**：每轮写文件前自动快照到 `.agent/undo/`，`/undo` 恢复上一轮改动的全部文件（新建的文件会被删除）。 -- **AGENTS.md**：工作区根目录的 `AGENTS.md` 会注入 system prompt；`/init` 让 agent 自己生成一份。 -- **自动压缩**：上一轮 prompt 用到模型上下文 75% 时，下一轮开始前自动总结历史（`CST_AUTO_COMPACT=0` 关闭）。 - -### 扩展：Skills、插件、MCP、子 agent - -多模型角色绑定、可续接 worker、共享执行预算与编排模式见 [worker 配置指南](docs/workers.md)。 - -`--tools minimal` 下这些都不加载（论文口径保持不变）。配置写法与示例见 [docs/plugins.md](docs/plugins.md)。 - -- **Skills**：`/SKILL.md`（frontmatter `name` + `description`），放在工作区 `.agent/skills/`、`.claude/skills/` - 或配置目录 `skills/`。system prompt 只放名字和一句描述，模型需要时调用 `skill(name)` 读全文； - `/skills` 浏览，`/skill NAME 任务` 直接带着某个 skill 开始一轮。 -- **插件**：`plugins//plugin.json` 声明外部命令工具（参数以 JSON 写到 stdin，stdout 即结果，`perm` 决定审批， - 默认 60 s 超时），也可以附带 skills 目录和 MCP 服务器。 -- **MCP**：`mcp.json`（`{"mcpServers": {...}}`，与 Claude/Cursor 格式相同）里的 stdio 服务器在后台启动， - 工具注册为 `mcp____`，默认按网络工具审批（`autoApprove` 可放行）。`/mcp` 看状态，侧栏显示连接数。 -- **工作区信任**：工作区里的 `.agent/plugins/` 和 `.agent/mcp.json` 会执行命令，默认不加载； - `/plugins trust` 后才生效（记在 `settings.json`）。配置目录（`~/.config/cst-agent/`）下的始终加载。 -- **子 agent**：`task(description, prompt, agent?)` 新开一个独立上下文跑完一轮，把最终报告交回主 agent。 - 内置 `general`（除 task 外全部工具）、`explore`（只读，可并行）、`plan`（只读，输出计划）； - `.agent/agents/*.md` 或配置目录 `agents/*.md` 可自定义角色（frontmatter `name / description / model / tools / - max_steps / readonly`，正文是角色说明）。子 agent 不能再开子 agent；Esc 会一并取消；它的审批弹窗标 `[角色名]`； - 文件改动并入当前轮，`/undo` 一起撤销。转录在 `.agent/sessions/<会话>/sub-N.jsonl`，`/agents` 查看。 - -### TUI 快捷键 - -默认 leader 是 **Ctrl+X**：先按 Ctrl+X，再按后面的字母。`/keys`（或 F1、Ctrl+X h）列出当前全部绑定。 - -| 按键 | 说明 | +| 按键 / 命令 | 说明 | |---|---| -| Enter | 发送；busy 时入队 | -| Ctrl+N / Alt+Enter | 换行（粘贴的多行文本保持原样，不会被当成发送） | -| Shift+Enter / Ctrl+Enter | 换行；需要支持 kitty 键盘协议的终端（kitty、WezTerm、foot、Ghostty、WHC Shell 等），启动时自动探测 | -| ← → Home End Ctrl+A/E Ctrl+B/F Alt+B/F Ctrl/Alt+← → | 移动光标（按字 / 按词，支持中文宽字符） | -| Ctrl+W / Alt+Backspace / Ctrl+Backspace / Ctrl+Delete | 向前删词 / 向后删词（Ctrl+Backspace 需要 kitty 键盘协议） | -| Ctrl+U / Ctrl+K / Delete | 删到行首 / 删到行尾 / 删后一个字符 | -| ↑ / ↓ | 提示历史（多行输入时先在行间移动） | -| Tab | 补全 `/命令` 和 `@文件`；没有可补全时切换 Build / Plan（Plan 只开放只读工具） | -| Shift+Tab | 循环切换审批模式 ask → auto → yolo | -| Ctrl+P | 命令面板（输入过滤，↑↓ / 鼠标选择） | -| Ctrl+O / Ctrl+R | 展开/折叠最近的 tool 输出 / 最近的 Thought | -| Ctrl+T / Ctrl+L | 开关任务面板 / 重绘 | -| PgUp / PgDn、Alt+↑ / Alt+↓、Ctrl+Home / Ctrl+End | 半页滚动、单行滚动、跳到开头 / 最新 | -| Ctrl+X n / l | 新会话 / 会话列表 | -| Ctrl+X m / p / e | 模型 / provider / 推理强度 | -| Ctrl+X u / r / c | 撤销上一轮改动 / 重问 / 压缩上下文 | -| Ctrl+X y / x | 复制上一条回复 / 导出记录 | -| Ctrl+X t / d / s | 全部 Thought 默认展开或折叠 / 全部 tool 输出 / 侧栏 | -| Ctrl+X a / k / g | 子 agent 面板 / skills / 插件 | -| Ctrl+X h、F1 / Ctrl+X q | 快捷键列表 / 退出 | -| 鼠标点击 | 展开/折叠 tool 卡片和 Thought、在输入框里定位光标、点模式行切换 Build/Plan、在选择框里选中 | -| 鼠标拖动 / 双击 / 三击 | 在对话区选中文字（按字符 / 词 / 行），松开即通过 OSC 52 复制到剪贴板；拖到上下边缘会自动滚动。Shift+拖动或 `/mouse` 关闭后用终端原生选择 | -| Esc | 取消当前 turn（不会退出） | -| Ctrl+C 两次 / 空输入 Ctrl+D | 退出 | +| 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 / 退出 | -Thought（推理过程）默认折叠成一行“Thought · 3.2s”，生成中显示实时计时；`/thinking on` 改为默认展开。 +完整快捷键与斜杠命令仍以 TUI 内 `/help`、`/keys` 为准。 -**自定义按键**：`~/.config/cst-agent/keybinds.json`，键是动作名（`/keys` 里能看到），值是一个或多个按键， -`"none"` 解除绑定： +### 工具协议（可选） -```json -{ - "leader": "ctrl+x", - "new_session": [" n", "f2"], - "toggle_thought": "ctrl+g", - "todo": "none" -} -``` +默认 `native-eos`（OpenAI `tools[]`，流结束后执行）。也可 `native-inc`、文本帧 `ctl` / `ctl-heredoc`、`xml`（`CST_PROTOCOL` / `/protocol`）。日常使用保持默认即可。 -按键写法：`ctrl+x`、`alt+b`、`shift+tab`、`f1`…`f12`、`pgup`、`home`、` n`。 -写错的条目会被跳过并在 `/keys` 里提示，其余照常生效。 +--- -### 斜杠命令 +## 平台 -输入 `/` 弹出补全；唯一前缀即可（如 `/st` → `/status`）。标 * 的命令在模型运行中也能用。 +| 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 | -| 命令 | 说明 | -|---|---| -| `/help` * | 命令与按键 | -| `/new`、`/session [id]`、`/rename <标题>` *、`/delete [id]` | 新建 / 选择切换 / 命名 / 删除会话 | -| `/provider [name]`、`/model [name]`、`/effort [level]` | 切换 provider（缺 key 时当场输入并用 `/models` 校验）、模型（列表优先显示 API 实际返回的模型，标 `(api)`）、推理强度；都会记住 | -| `/key` | 输入或更换当前 provider 的 API key（遮罩输入并保存） | -| `/protocol [name]` | 切换工具调用协议 | -| `/mode [coding\|general]` | 工作模式（通用助手 / 代码助手口径） | -| `/tools [on\|off NAME\|minimal\|default]` | 查看或开关工具 | -| `/approval [ask\|auto\|yolo]` *、`/yolo` * | 审批模式；本次开关 yolo | -| `/permissions [reset]` *、`/max-steps [N]` * | 权限规则、每轮步数 | -| `/sidebar` *、`/mouse` * | 开关右侧边栏（≥120 列时显示）、开关鼠标 | -| `/status` *、`/todo` * | 会话 / 模型 / 上下文占比 / 设置；任务清单 | -| `/undo`、`/retry` | 撤销上一轮文件改动；丢弃上一条回复重问 | -| `/diff [path]` * | `git status` + `git diff` | -| `/compact` | 手动压缩上下文 | -| `/export [file]` *、`/copy` * | 导出 Markdown 记录；复制上一条回复（OSC 52，需终端支持） | -| `/attach [path\|paste\|list\|clear]` | 给下一条消息带附件：图片、PDF（自动取文本层）、文本文件；`paste` 优先取剪贴板图片，没有就把剪贴板文本放进输入框 | -| `/web` * | 后台起一个 WebUI 进程（同 workspace、新会话，日志写到 `.agent/webui.log`） | -| `/init` | 让 agent 写 `AGENTS.md` | -| `/details` *、`/thinking [on\|off]`、`/keys` * | 展开全部 tool 输出；Thought 默认展开/折叠；快捷键列表 | -| `/skills [reload\|list]`、`/skill [任务]` | 浏览 skills；带着某个 skill 开始一轮 | -| `/plugins [trust\|untrust\|reload]`、`/mcp [reload]` | 插件与工作区信任；MCP 服务器状态 | -| `/agents` | 子 agent 角色与本会话的子 agent 记录（可查看转录） | -| `/quit` * | 退出 | +--- -### 协议 - -请求统一走 OpenAI 兼容 `POST …/chat/completions`（SSE）。工具调用的承载方式由 `--protocol` 决定： - -| 协议 | 承载 | 何时执行 | -|---|---|---| -| `native-eos`（默认） | 原生 `tools[]` / SSE `tool_calls` | 整个流结束后（基线） | -| `native-inc` | 同上 | 某个 index 的参数完整（下一个 index 开始或 finish）即执行 | -| `ctl` | 正文中的 CTL 帧，长度前缀参数 | `end` 行一被确认即执行，流仍在继续 | -| `ctl-heredoc` | 正文中的 CTL 帧，`<` 文本 | 流结束后 | - -文本协议（ctl / ctl-heredoc / xml）不发送 `tools[]`，工具结果以 -`result exit= ` … `end` 帧放在下一条 user 消息里。 -同一会话可以随时切换协议：历史中的调用会按当前协议重新渲染。 - -## CTL tool language - -```text -call -arg - -arg < -TAG -arg short inline value -end -``` - -Execution happens only on confirmed `end` (`CTL_EV_CALL_READY`); no prefix of -a call is ever executable. See [docs/theory_tool_cst.md](docs/theory_tool_cst.md). - -## Starvation experiment +## 开发者备忘 ```bash make check -./scripts/replay_starvation.sh -./tests/test_replay_real # 真实 DeepSeek 录制流上的逐字节截断（实验 C） +scripts/prompt_smoke.sh # 系统提示契约（无 API） +scripts/e2e_webui.sh # WebUI 录制流（无 API） +scripts/e2e_fixture.sh mini_calc --provider deepseek # 可选：带 key 的夹具 ``` -CTL vs JSON-buffer 截断数字写入 [docs/eval_tool_cst.md](docs/eval_tool_cst.md) 实验 A / C；与 mini_calc e2e 一起作为 Tool-loop CST 附录素材（**不**替代 SD 主论文 Markdown→HTML 实验）。 +`fixtures/` 下是可重复的本地任务夹具（`TASK.md` + `check.sh`），用于手工或脚本验收，不是产品依赖。 + +许可证与第三方：`vendor/sashidown`、`vendor/cjson`（MIT）、`vendor/monocypher` 随仓库提供。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6bd4f3b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +# 文档索引 + +面向日常使用的说明。二进制名仍是 `cst-agent`，配置目录默认 `~/.config/cst-agent/`。 + +| 文档 | 内容 | +|---|---| +| [env_openai.md](env_openai.md) | Provider、模型、API Key、环境变量 | +| [parliament.md](parliament.md) | 多设备议会（Realm / 席位 / 同步） | +| [workers.md](workers.md) | 后台任务、worker、job 完成报告 | +| [webui.md](webui.md) | 内置 HTTP + SSE WebUI | +| [plugins.md](plugins.md) | Skills、插件、MCP | +| [compat.md](compat.md) | 平台兼容与验收清单 | +| [README-windows.md](README-windows.md) | Windows 安装、沙箱、构建 | +| [android.md](android.md) | Android / APK | +| [windows_selftest.md](windows_selftest.md) | Windows 自测步骤 | +| [archive/](archive/) | 历史设计笔记（非产品文档） | diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..4e84888 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,10 @@ +# 归档 + +历史设计笔记与评测草稿，**不是**面向用户的产品文档，也不再作为论文素材维护。 + +| 文件 | 说明 | +|---|---| +| `theory_tool_cst.md` | 早期工具调用确认流设计笔记 | +| `eval_tool_cst.md` | 早期协议/夹具评测草稿 | + +日常使用请看仓库根目录 [README.md](../../README.md) 与同级其它 `docs/*.md`。 diff --git a/docs/eval_tool_cst.md b/docs/archive/eval_tool_cst.md similarity index 96% rename from docs/eval_tool_cst.md rename to docs/archive/eval_tool_cst.md index 72a258a..1daebb2 100644 --- a/docs/eval_tool_cst.md +++ b/docs/archive/eval_tool_cst.md @@ -1,9 +1,8 @@ # Tool-loop CST 评测笔记（反哺论文素材） -> 本文是 **CST-Agent** 侧的评测/案例记录，供写入 SD 主论文附录或独立 TR 时粘贴。 -> **不**替代 [`SD/paper/sections/eval_zh.tex`](../../SD/paper/sections/eval_zh.tex) 中 Markdown→HTML 主实验。 +> **归档。** 早期评测草稿，已停止维护；请勿当作当前产品说明。 -理论锚点见 [theory_tool_cst.md](theory_tool_cst.md)。 +理论锚点见同目录 [theory_tool_cst.md](theory_tool_cst.md)。 ## 命题分工 diff --git a/docs/theory_tool_cst.md b/docs/archive/theory_tool_cst.md similarity index 98% rename from docs/theory_tool_cst.md rename to docs/archive/theory_tool_cst.md index 4be190e..9666635 100644 --- a/docs/theory_tool_cst.md +++ b/docs/archive/theory_tool_cst.md @@ -1,5 +1,7 @@ # Tool-loop CST：确认前沿推广到工具调用 +> **归档。** 早期设计笔记，已停止维护；请勿当作当前产品说明。见 [README.md](README.md)。 + ## 命题 在 agent 工具环中，对模型输出做**确认流式转导**：只在 \(O_{\mathrm{conf}}\) 内不可逆地发射「可执行工具调用 / 可应用补丁 / 可提交会话状态」。相对「拼到合法 JSON 再执行」的缓冲基线，这能降低注意力饥渴导致的残缺工具帧（未闭合括号、半截 arguments）被过早执行或整轮失败的问题。 diff --git a/docs/compat.md b/docs/compat.md index 769291f..d11576f 100644 --- a/docs/compat.md +++ b/docs/compat.md @@ -22,7 +22,7 @@ adds Homebrew's keg-only `ncurses`/`curl` to `PKG_CONFIG_PATH`; without Homebrew it falls back to the system `-lncurses` (wide-character capable). Verified so far: NixOS x86_64 with gcc, clang and TinyCC (`-Werror` except -tcc, `make check`, `make asan`, ctest). CI (`.gitea/workflows/ci.yml`, restored) +tcc, `make check`, `make asan`, ctest). CI (`.gitea/workflows/ci.yml`) checks with TinyCC and builds the static musl releases for x86_64, x86 and aarch64 with gcc `-Werror` (`make check` on both x86 targets, a qemu smoke test on aarch64). macOS and WSL are checked by hand with the list below. diff --git a/include/cst_version.h b/include/cst_version.h index 56a35a0..6c54555 100644 --- a/include/cst_version.h +++ b/include/cst_version.h @@ -3,7 +3,7 @@ #define CST_VERSION_MAJOR 0 #define CST_VERSION_MINOR 9 -#define CST_VERSION_PATCH 33 +#define CST_VERSION_PATCH 34 #define CST_VERSION_STR_(x) #x #define CST_VERSION_STR(x) CST_VERSION_STR_(x) diff --git a/scripts/e2e_fixture.sh b/scripts/e2e_fixture.sh index 00c504a..5a649c1 100755 --- a/scripts/e2e_fixture.sh +++ b/scripts/e2e_fixture.sh @@ -7,7 +7,7 @@ # [--model M] [--max-steps N] [--tools minimal|default] [--out DIR] # [--record] [--baseline-only] # -# --tools defaults to minimal (the four tools the paper experiments used). +# --tools defaults to minimal (read_file / run_shell / write_file / apply_patch). # # Artifacts go to /______/: # result.json agent.log session.jsonl metrics.jsonl check.log [sse/] diff --git a/scripts/replay_starvation.sh b/scripts/replay_starvation.sh index 37f7684..2263860 100755 --- a/scripts/replay_starvation.sh +++ b/scripts/replay_starvation.sh @@ -5,4 +5,4 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" make check echo -echo "See docs/theory_tool_cst.md for the claim under test." +echo "Historical note: docs/archive/theory_tool_cst.md (not product docs)." diff --git a/scripts/run_matrix.sh b/scripts/run_matrix.sh index 9d40e18..6768800 100755 --- a/scripts/run_matrix.sh +++ b/scripts/run_matrix.sh @@ -9,7 +9,7 @@ # # -m provider:model pairs (model may be empty: "deepseek:") # -r also record raw SSE streams per run (for replay experiments) -# -t tool profile (default minimal, as in the paper runs) +# -t tool profile (default minimal) # # Each run is scripts/e2e_fixture.sh; results land in // and the # summary in /results.csv and /summary.md.