Usability pass: tool registry, TUI polish, saved keys and settings

Tools
- Table-driven tool registry with permission classes and default/minimal
  profiles; new tools: edit_file, list_dir, glob, grep, delete_file,
  move_file, todo_write, web_fetch, ask_user (plus read_file paging).
- Built-in Myers diff; write tools return unified diffs.
- Persistent permission rules (.agent/permissions.json), per-turn undo
  snapshots (.agent/undo), AGENTS.md project notes, auto-compact at 80%
  of the model context, cancellable run_shell with process-group kill.

TUI
- Table-driven slash commands: /provider /key /effort /status /tools
  /permissions /yolo /undo /retry /diff /export /copy /rename /delete
  /init /max-steps /todo, with / and @ completion.
- Permission modal with diff and prefix rules, ask_user modal, todo
  panel, header with model/effort/context, bracketed paste, line editing,
  wide-char cursor, NO_COLOR and ASCII fallback; Esc never quits.

Startup and configuration
- API keys are entered in the TUI (hidden) and saved per provider in
  <config>/credentials (0600); env variables are only a fallback.
- Last provider, per-provider model and reasoning effort are remembered
  in <config>/settings.json; --effort/-e and /effort send
  reasoning_effort (low|medium|high|max) to models that accept it.
- DeepSeek preset uses deepseek-flash / deepseek-v4-pro.
- Session flags --new/--continue/--resume/--list-sessions, --yolo,
  --confirm.

Compatibility and tests
- ncurses detection, macOS/Homebrew support, make install, XDG config
  dir, POSIX cleanups; Gitea CI (gcc/clang/asan/musl/macOS).
- Unit tests for diff, fs tools, registry, undo/perms and config;
  e2e fixtures multi_file_refactor and ask_or_todo; vendored cJSON.

README.md

@@ -7,8 +7,8 @@ See [docs/theory_tool_cst.md](docs/theory_tool_cst.md).
 
 ## 能不能用来工作？
 
-**可以**：有监督的本地小改动 / 探索本仓库（TUI + 工具 + 权限确认）。  
-**不宜**：无人值守长任务或当 CI 主力（网关偶发空答、无完整 diff UI）。
+**可以**：有监督的本地改动 / 探索仓库（TUI + 13 个内置工具 + 带 diff 的权限确认 + `/undo`）。  
+**不宜**：无人值守长任务或当 CI 主力（网关偶发空答；headless 模式默认自动批准）。
 
 ### 5 分钟试用
 
@@ -19,13 +19,16 @@ git clone https://git.whcself.xyz/WHC/CST-agent.git && ./CST-agent/scripts/boots
 # 已有仓库目录内：
 ./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 .
+# 装到 PATH（或 sudo make install）
+make install PREFIX=$HOME/.local
+
+# 在项目目录里直接启动：首次会让你选 provider 并输入 API key（遮罩输入，按 provider 保存）
+cd ~/my-project && cst-agent
 ```
 
+之后再启动会沿用上次的 provider、模型和推理强度（low / medium / high / max），不需要任何参数或环境变量。
+界面里用 `/provider` 切换（没保存过 key 的会当场询问），`/model`、`/effort` 切换模型和推理强度，`/key` 更换 key。
+
 完整环境变量说明：[docs/env_openai.md](docs/env_openai.md)。
 
 | 平台 | 一键脚本 |
@@ -41,21 +44,41 @@ export OPENAI_MODEL='gpt-4.1-mini'
 
 ```bash
 ./scripts/e2e_mini_calc.sh --baseline-only   # 无 API：证明初始测试 RED
-./scripts/e2e_mini_calc.sh                 # 有 key：agent 修复后 make test
+./scripts/e2e_mini_calc.sh --provider deepseek --protocol ctl   # 有 key
 ```
 
-口径：`pass` / `partial` / `fail` — 见 [docs/eval_tool_cst.md](docs/eval_tool_cst.md)。
+更多夹具（每个都有 `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 agent
-make
-make check
+cd CST-agent
+make            # 依赖 pkg-config 找 libcurl / ncursesw（找不到时退回 ncurses）
+make check      # 单元测试 + 截断实验（含真实录制流）
+make asan       # AddressSanitizer + UBSan 构建并跑全部测试
+make install PREFIX=$HOME/.local   # 或 sudo make install（默认 /usr/local）
 ```
 
+NixOS：`nix-shell`（仓库自带 [`shell.nix`](shell.nix)）后再 `make`。
+macOS：`brew install curl ncurses pkg-config` 后直接 `make`（Makefile 会找 Homebrew 的 keg-only 库）。
+各平台细节与验收清单见 [docs/compat.md](docs/compat.md)。
+
 ### CMake（推荐跨编译器 / 交叉）
 
 ```bash
@@ -77,17 +100,20 @@ 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）**。
+依赖：`gcc` 或 `clang`、`libcurl`、Linux TUI 需 `ncursesw`；Windows TUI 需 **PDCurses**。
+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 | x86_64 / aarch64 | GCC, Clang | yes | ncursesw | `/bin/sh` 或旁路 `busybox` |
+| Linux（glibc / musl） | x86_64 / aarch64 | GCC, Clang | 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 | x86_64 / aarch64 | MinGW GCC/Clang | yes | PDCurses | **捆绑 busybox-w32** |
-| macOS | — | — | **不做** | — | — |
 
 ### Termux
 
@@ -118,65 +144,159 @@ cmake -B build-win-tui -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
 
 ## Defaults (API)
 
-默认 MiniMax：`https://api.minimax.cn/v1` / `MiniMax-M2.7`。  
-对接 **OpenAI 官方或其它兼容网关** 时设置：
+`--provider`（或 `CST_PROVIDER`）选择预设；显式的 `--api-base` / `--model` / 环境变量优先。
 
-| 用途 | 推荐变量 | 等价别名 |
-|---|---|---|
-| 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` |
+| 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` |
+| `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_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` |
+
+“上次使用”记在配置目录的 `settings.json`（TUI 里切换时更新；headless 运行不改它）。
+推理强度以 `reasoning_effort` 发送给 DeepSeek 和 OpenAI 推理模型（o 系列、gpt-5，`max` 映射为 `high`），其他模型不发送。
 
 详见 [docs/env_openai.md](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`。
+| `CST_PROTOCOL` / `--protocol` | 工具调用协议（`native-eos`） |
+| `CST_TOOLS` / `--tools` | 工具集：`default`（全部）/ `minimal`（论文 4 件套） |
+| `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` | 覆盖模型上下文窗口大小 / 关闭自动压缩（用到 80% 时自动 `/compact`） |
+| `CST_NO_PROJECT_NOTES=1` | 不把工作区的 `AGENTS.md` 注入 system prompt |
+| `NO_COLOR` / `CST_ASCII=1` | 关闭颜色 / 强制 ASCII 图形（非 UTF-8 终端自动退化） |
+| `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 |
 
 ## Run
 
 ```bash
+# TUI（工作目录 = 当前目录；Assistant Markdown 经 Sashidown CST 渲染）
+cst-agent
+
 # Local CTL demo (no API)
-./cst-agent --demo-ctl --workspace .
+cst-agent --demo-ctl
 
-# TUI（OpenCode 风格；Assistant Markdown 经 Sashidown CST 渲染）
-./cst-agent --workspace ..
-
-# 强制重新弹窗保存 Key
-./cst-agent --ask-key --workspace .
+# 在命令行输入并保存当前 provider 的 key（不回显）
+cst-agent --ask-key --provider deepseek
 
 # Headless（默认 auto-approve shell/写文件）
-./cst-agent --headless --prompt 'List files' --workspace .
+cst-agent --headless --prompt 'List files'
 ```
 
-### 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` | 帮助 |
+| `-c` / `--continue` | 打开上次的会话（默认行为） |
+| `-N` / `--new` | 开新会话 |
+| `-R ID` / `--resume ID` | 打开指定会话（完整 id 或唯一前缀） |
+| `-L` / `--list-sessions` | 列出会话（时间、条数、标题）后退出 |
+| `-y` / `--yolo` | 本次运行不再确认（等同 `--confirm none`） |
+| `-C LIST` / `--confirm LIST` | 需要确认的类别：`shell,write,net` 的任意组合或 `none` |
+| `-T PROFILE` / `--tools PROFILE` | `default` 或 `minimal` |
+| `-P NAME` / `-m NAME` / `-e LEVEL` | 本次使用的 provider / 模型 / 推理强度（不传则用上次的） |
+| `-a` / `--ask-key` | 在命令行输入并保存当前 provider 的 key |
 
-会话落盘：`<workspace>/.agent/sessions/<id>.jsonl` + `CURRENT`。
+工作目录默认就是当前目录（`-w DIR` 可指定别的目录）。
+
+会话落盘：`<workspace>/.agent/sessions/<id>.jsonl` + `CURRENT`；`.agent/` 自带 `.gitignore`，不会被误提交。
+
+### 内置工具
+
+| 工具 | 类别 | 说明 |
+|---|---|---|
+| `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 转纯文本 |
+| `todo_write` | 元 | 维护任务清单（TUI 右侧面板，Ctrl+T 开关） |
+| `ask_user` | 询问 | 向用户提问（可给选项）；headless 下返回错误让模型自行决定 |
+
+`--tools minimal` 只保留 `read_file` / `run_shell` / `write_file` / `apply_patch`（论文实验口径）。
+TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
+
+### 权限、撤销与项目说明
+
+- **确认**：默认 shell、写文件、联网三类工具需要确认。弹窗会显示命令或写入的 diff：
+  `y` 允许一次 · `a` 本工具总是允许 · `p` 总是允许这个命令前缀（如 `make`、`git status`）· `n` / Esc 拒绝。
+  `a` / `p` 写入 `<workspace>/.agent/permissions.json`，`/permissions` 查看，`/permissions reset` 清空。
+  `sudo`、`rm`、解释器（`python3 -c …`）等危险前缀不会被建议成规则。
+- **撤销**：每轮写文件前自动快照到 `.agent/undo/`，`/undo` 恢复上一轮改动的全部文件（新建的文件会被删除）。
+- **AGENTS.md**：工作区根目录的 `AGENTS.md` 会注入 system prompt；`/init` 让 agent 自己生成一份。
+- **自动压缩**：上一轮 prompt 用到模型上下文 80% 时，下一轮开始前自动总结历史（`CST_AUTO_COMPACT=0` 关闭）。
+
+### TUI 快捷键
+
+| 按键 | 说明 |
+|---|---|
+| Enter | 发送；busy 时入队 |
+| Ctrl+N / Alt+Enter | 换行（粘贴的多行文本保持原样，不会被当成发送） |
+| ← → Home End Ctrl+A/E Ctrl+B/F Alt+B/F | 移动光标（按字 / 按词，支持中文宽字符） |
+| Ctrl+W / Ctrl+U / Ctrl+K / Alt+Backspace / Delete | 删词 / 删到行首 / 删到行尾 |
+| ↑ / ↓ | 提示历史（多行输入时先在行间移动） |
+| Tab | 补全 `/命令` 和 `@文件`；空输入时展开/折叠 Thought |
+| Ctrl+O / Ctrl+T | 展开最近 tool 输出 / 开关任务面板 |
+| PgUp / PgDn / 鼠标滚轮 | 滚动对话 |
+| Esc | 取消当前 turn（不会退出） |
+| Ctrl+C 两次 / 空输入 Ctrl+D | 退出 |
+
+### 斜杠命令
+
+输入 `/` 弹出补全；唯一前缀即可（如 `/st` → `/status`）。标 * 的命令在模型运行中也能用。
+
+| 命令 | 说明 |
+|---|---|
+| `/help` * | 命令与按键 |
+| `/new`、`/session [id]`、`/rename <标题>` *、`/delete [id]` | 新建 / 选择切换 / 命名 / 删除会话 |
+| `/provider [name]`、`/model [name]`、`/effort [level]` | 切换 provider（缺 key 时当场输入）、模型、推理强度；都会记住 |
+| `/key` | 输入或更换当前 provider 的 API key（遮罩输入并保存） |
+| `/protocol [name]` | 切换工具调用协议 |
+| `/tools [on\|off NAME\|minimal\|default]` | 查看或开关工具 |
+| `/permissions [reset]` *、`/yolo` *、`/max-steps [N]` * | 权限规则、本次免确认、每轮步数 |
+| `/status` *、`/todo` * | 会话 / 模型 / 上下文占比 / 设置；任务清单 |
+| `/undo`、`/retry` | 撤销上一轮文件改动；丢弃上一条回复重问 |
+| `/diff [path]` * | `git status` + `git diff` |
+| `/compact` | 手动压缩上下文 |
+| `/export [file]` *、`/copy` * | 导出 Markdown 记录；复制上一条回复（OSC 52，需终端支持） |
+| `/init` | 让 agent 写 `AGENTS.md` |
+| `/details` *、`/quit` * | 展开全部 tool 输出；退出 |
 
 ### 协议
 
-- 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）
+请求统一走 OpenAI 兼容 `POST …/chat/completions`（SSE）。工具调用的承载方式由 `--protocol` 决定：
+
+| 协议 | 承载 | 何时执行 |
+|---|---|---|
+| `native-eos`（默认） | 原生 `tools[]` / SSE `tool_calls` | 整个流结束后（基线） |
+| `native-inc` | 同上 | 某个 index 的参数完整（下一个 index 开始或 finish）即执行 |
+| `ctl` | 正文中的 CTL 帧，长度前缀参数 | `end` 行一被确认即执行，流仍在继续 |
+| `ctl-heredoc` | 正文中的 CTL 帧，`<<TAG` 定界参数 | 同上 |
+| `xml` | MiniMax `<minimax:tool_call>` 文本 | 流结束后 |
+
+文本协议（ctl / ctl-heredoc / xml）不发送 `tools[]`，工具结果以
+`result <id> exit=<n> <nbytes>` … `end` 帧放在下一条 user 消息里。
+同一会话可以随时切换协议：历史中的调用会按当前协议重新渲染。
 
 ## CTL tool language
 
@@ -184,16 +304,22 @@ cmake -B build-win-tui -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
 call <id> <name>
 arg <key> <nbytes>
 <raw bytes exactly nbytes>
+arg <key> <<TAG
+<lines, verbatim>
+TAG
+arg <key> short inline value
 end
 ```
 
-Execution happens only on confirmed `end` (`CTL_EV_CALL_READY`).
+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）
 ```
 
-CTL vs JSON-buffer 截断数字写入 [docs/eval_tool_cst.md](docs/eval_tool_cst.md) 实验 A；与 mini_calc e2e 一起作为 Tool-loop CST 附录素材（**不**替代 SD 主论文 Markdown→HTML 实验）。
+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 实验）。