chivgent 1.0.1 → 1.1.1

package/README.zh-CN.md

@@ -1,887 +1,173 @@
-# chivgent
+<p align="center">
+  <img src="docs/assets/chivgent-leaf-mark.png" width="88" alt="">
+</p>
 
-[English](README.md) | [简体中文](README.zh-CN.md)
-
-> ⚠️ **本中文版已过时，请以 [英文 README](README.md) 为准。** 尤其是安全说明：`--allow-shell` 现在在离线 Docker 容器中运行命令，每条命令需逐条确认，且不向容器传入 API key（详见 [shell sandbox](docs/shell-sandbox.md)）。下文中与此冲突的说法均已失效。
-
-> 一款易读的终端 Coding Agent，提供流式 TUI 与可切换的 AI 供应商。
-
-![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
-![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?logo=typescript&logoColor=white)
-[![CI](https://github.com/chivopic/chivgent/actions/workflows/ci.yml/badge.svg)](https://github.com/chivopic/chivgent/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-![Version](https://img.shields.io/badge/version-1.0.0-blue)
-
-`chivgent` 将 Provider 无关的 Agent Loop 与 LLM API、工具和工作区边界连接起来。
-它可以发现文件、搜索源码、分段读取内容，并可按需编辑文件或运行命令；
-支持 OpenAI、DeepSeek 和兼容 Chat Completions 的 API。
-
-这个项目刻意保持精简：先让 Tool Calling、Conversation State、Provider Adapter
-和循环终止条件容易理解，再逐步加入成熟 Agent Harness 所需的工程复杂度。
-
-## 功能
-
-- 完整的多轮 Agent Loop：模型 -> Tool Call -> Tool Result -> 模型。
-- Provider 无关的运行时消息和工具契约。
-- Provider 注册表：新增 Provider 只是一条声明，不需要改 CLI。
-- API Key 依次从 `--api-key`、环境变量、可选文件解析。
-- 通过 Responses API 支持 OpenAI。
-- 通过通用 OpenAI-compatible Chat Completions 客户端支持 DeepSeek。
-- 可通过 TUI、CLI 参数或环境变量配置自定义 OpenAI-compatible API。
-- 滚动式 TUI：输入斜杠显示命令建议，可在菜单中选择供应商。
-- 既可以进入带斜杠命令的交互式会话，也可以单次提问后退出。
-- Session 以 JSON Lines 持久化，可以在之后的进程中恢复。
-- 提供 `--json` 事件流，便于脚本和其他前端消费。
-- 基于类型化运行时事件流的流式输出。
-- 上下文管理器：压缩较早的轮次以待在窗口内。
-- 可中断的运行：Ctrl+C 停止当前回答；空闲时退出，不丢失会话记录。
-- Provider 调用具备单次超时和有上限的指数退避重试。
-- 通过 `list_files` 和字面量 `search_text` 确定性地发现项目内容。
-- 支持带续读提示的分段 `read_file`，所有工具结果都有容量上限。
-- 默认只读；`--allow-writes` 才会启用 `write_file` 和 `edit_file`。
-- 通过 `--allow-shell` 选择性开启的 `bash` 工具，输出边跑边显示。
-- 采集 Provider 报告的 token 用量：按轮、按次运行、按 eval 任务分别统计。
-- Eval 套件：衡量 Agent 能不能把活干成，而不只是能不能跑起来。
-- 远程会话：一个进程持有会话，其他进程通过本地 socket 接上来。
-- 多个客户端可以同时观察同一个会话，其中任何一个都能中断当前运行。
-- 扩展系统：可以添加工具、斜杠命令、事件订阅和 system prompt 片段。
-- 项目扩展受按目录记录的信任决定门控；判定发生在任何模块被 import 之前，
-  没有终端可问时一律拒绝。
-- 命令运行在独立进程组中，取消一次运行会杀掉整棵进程树。
-- 命令输出从尾部截断，完整内容写入临时文件供按需读取。
-- 精确匹配的 `edit_file`，命中缺失或不唯一时拒绝执行。
-- 编辑会保留文件原有的 BOM 和 CRLF 换行符。
-- 原子写入：写入中途崩溃不会损坏原文件。
-- 安全的工作区访问，阻止路径穿越和符号链接逃逸。
-- 支持根 `.gitignore`、生成目录和敏感路径过滤。
-- 工具参数验证、明确的工具错误和有上限的轮次限制。
-- 可打包安装的 Node.js CLI，不依赖 Agent 框架。
-- 默认测试不调用真实 API，不消耗模型额度。
+<div align="center">
 
-## 快速开始
+# chivgent
 
-### 环境要求
+### 终端里的 coding agent。
 
-- Node.js 22 或更高版本
-- npm
-- OpenAI、DeepSeek 或其他兼容供应商的 API Key
+和 Claude Code、Codex 同一类。模型你自己带。
 
-### 从 npm 安装
+[![npm](https://img.shields.io/npm/v/chivgent?color=111111)](https://www.npmjs.com/package/chivgent)
+[![CI](https://img.shields.io/github/actions/workflow/status/chivopic/chivgent/ci.yml?label=CI&color=111111)](https://github.com/chivopic/chivgent/actions/workflows/ci.yml)
+![Node.js >=22](https://img.shields.io/badge/Node.js-%3E%3D22-111111)
+[![License](https://img.shields.io/badge/license-MIT-111111)](LICENSE)
 
-```bash
-npm install -g chivgent
-chivgent --version
-```
+**[官网 ↗](https://chivgent-web.vercel.app/)** · [架构](docs/architecture.md) · [Shell](docs/shell-sandbox.md) · [登录](docs/subscription-oauth.md) · [English](README.md) · **简体中文**
 
-通过 npm 全局安装后，可以直接更新：
+</div>
 
-```bash
-chivgent update --check  # 只检查版本
-chivgent update         # 安装更新，完成后重新启动 chivgent
-```
-
-旧版本若还没有这个命令，先执行一次 `npm install -g chivgent@latest`。
-仅在主动运行命令时检查更新；源码、本地项目依赖和临时 `npx` 运行会显示对应的更新指引。
-详见[更新说明](docs/updating.zh-CN.md)。
-
-如果希望安装当前源码版本：
-
-```bash
-git clone https://github.com/chivopic/chivgent.git
-cd chivgent
-npm install
-npm run build
-npm install -g .
-```
+chivgent 是跑在你打开的目录里的本地 agent。它要做的，是 [Claude Code](https://code.claude.com) 和 [Codex](https://github.com/openai/codex) 那一类事：读这个项目，改它，跑它，会话还能回来。模型是你的。一把 API key，或者 ChatGPT、xAI 订阅。
 
-### 分析一个项目
+这一类现在的默认是 auto mode。工作区内的读取、编辑，以及沙箱里的命令，直接进行。动作离开工作区，或者命令要用宿主机，就停。这里这个策略叫 `workspace`。它不是另一个模型在逐条审查，也不是跳过所有边界。本地交互式 rich TUI 在没有指定权限模式或旧权限开关时默认使用 Ask for me：文件修改和命令都要确认；在空闲输入框按 Shift+Tab 可在 Plan、Auto mode 和 Ask for me 之间循环。headless、simple 和远程启动保留原有默认值。
 
-进入你希望 Agent 分析的项目目录，然后运行 `chivgent`。
+## 快速开始
 
-使用 OpenAI：
+需要 Node.js 22 或更高版本。
 
 ```bash
-export OPENAI_API_KEY="your-api-key"
-chivgent "src/agent.ts 是做什么的？"
+npm install -g chivgent
 ```
 
-使用 DeepSeek：
+macOS/Linux 用户也可以通过[官网一键安装脚本](https://chivgent-web.vercel.app/install.sh)安装。仍需提前装好 Node.js 22+ 和 npm；脚本安装的是同一个 npm 包，不会自动调用 `sudo` 或修改 Shell 配置。
 
 ```bash
-export DEEPSEEK_API_KEY="your-api-key"
-chivgent --provider deepseek "解释 src/ 目录的架构"
+curl -fsSL https://chivgent-web.vercel.app/install.sh | bash
 ```
 
-使用任意 OpenAI-compatible Chat Completions API：
+这会直接执行从网上下载的脚本。更稳妥的做法是先运行 `curl -fsSLo install.sh https://chivgent-web.vercel.app/install.sh`，阅读内容后再运行 `bash install.sh`。如果 npm 全局命令目录不在 PATH 里，脚本会提示需要添加的目录。
 
-```bash
-export OPENAI_API_KEY="your-provider-api-key"
-export OPENAI_BASE_URL="https://api.vendor.example/v1"
-export OPENAI_MODEL="vendor-model"
 
-chivgent --provider openai-compatible "解释 src/ 目录的架构"
-```
+已经安装过？先 `chivgent update --check`，再 `chivgent update`。
 
-不带问题直接运行 `chivgent` 会进入交互式会话：
+在项目目录里启动。
 
 ```bash
+cd /path/to/project
 chivgent
-› src/agent.ts 在做什么？
-› 这个循环在哪里测试？
-› /exit
-```
-
-会话会跨多轮保留上下文，因此追问不需要重复之前的信息。之后可以用
-`chivgent --continue`（或 `chivgent --resume <id>`）恢复；`chivgent --sessions`
-可以列出已记录的会话。
-
-答案会随模型生成实时写入 stdout，因此 stdout 仍然可以直接管道使用。工具活动、
-重试和运行状态写入 stderr；Provider 错误会返回非零退出码。使用 `--no-stream`
-可改为一次性输出完整答案，`--quiet` 可隐藏工具活动。
-
-## CLI 参考
-
-```text
-chivgent [选项] "问题"            回答一次后退出
-chivgent [选项]                   进入交互式会话
-
-选项：
-  --provider NAME  openai、deepseek、openai-compatible、openrouter、groq、xai、
-                   moonshot（默认：openai）
-  --model MODEL    覆盖 Provider 模型
-  --max-turns N    工具调用轮次上限（默认：8，加 --allow-writes 或 --allow-shell
-                   时为 16）
-  --no-stream      关闭流式输出，等待完整答案
-  -q, --quiet      不在 stderr 打印工具活动
-  --json           以 JSON Lines 输出整次运行，而不是渲染文本
-  -c, --continue   恢复当前工作区最近的一次 Session
-  --resume ID      恢复指定 Session
-  --api-key KEY    本次运行使用的 API Key；更推荐用环境变量
-  --sessions       列出已记录的 Session 并退出
-  --allow-writes   允许 Agent 创建和修改文件（默认只读）
-  --allow-shell    允许 Agent 执行 Shell 命令。它蕴含写权限：Shell 不受工作区
-                   边界约束。仅支持 Unix。
-  --serve          把当前会话暴露在本地 socket 上并常驻
-  --connect TARGET 接上一个已服务的会话，可用 id 或 socket 路径
-  --servers        列出仍在响应的服务端后退出
-  --no-extensions  不加载任何扩展，也不询问信任
-  --extensions     列出已加载的扩展及其注册内容后退出
-  --forget-trust   忘记覆盖当前工作区的信任决定后退出
-  --context-window N  上下文的 Token 预算（默认：128000）
-  --no-compaction  发送完整 transcript，不压缩较早的轮次
-  --no-session     不记录本次运行
-  -h, --help       显示帮助
-  -v, --version    显示版本
-```
-
-交互式会话中 `/help` 会列出全部斜杠命令，包括 `/provider`、`/model`、`/endpoint`、`/login`、
-`/session`、`/tools`、`/clear` 和 `/exit`。TUI 输入 `/` 会在当前输入行下方打开命令菜单；
-输入 `/provider` 会打开供应商菜单，可用上下键选择并按 Enter 切换。
-选中没有 Key 的供应商后会直接进入隐藏的 Key 输入；已有 Key 时直接可用。
-`/login` 保留用于更换 Key。
-运行中按 Ctrl+C 中断当前回答，不会退出会话；空闲时按 Ctrl+C 则退出（退出码 130）。
-Ctrl+D 在空行时也可离开。当前为单行输入，一个输入批次只提交首行，
-后续内容被丢弃；请等提示符重新出现后再输入下一条问题。
-
-退出码：`0` 正常回答，`1` 配置或 Provider 失败，`2` 达到轮次上限，`130` 被
-Ctrl+C 中断。
-
-### 登录
-
-最省事的方式是直接启动 chivgent，让它来问：
-
-```text
-$ chivgent --tui
-  v1.0.0
-  openai / gpt-5.6
-  Start with /provider → choose a Provider
-› /provider deepseek
-Selected deepseek / deepseek-v4-flash. API key needed for deepseek.
-API key for deepseek (hidden, saved locally; Enter skips):
-Stored the key for deepseek. Ready for your next prompt.
-› 
-```
-
-**没有 Key 时交互式会话照样能启动**。打开 `/provider`、选中供应商后，
-TUI 会直接询问它的 Key；已有 Key 就跳过。Key 保存后立即生效，
-无需再输入 `/login`。需要替换 Key 时仍可运行 `/login`。
-
-输入的 Key 不会回显，`auth.json` 以仅所有者可读的权限写入。存的时候**不会**去
-Provider 那里验证；你之后的第一次提问才是真正的检验。
-
-非交互式运行在没有 Key 时依然立刻失败——管道里没有人可问。
-
-在会话中换供应商或模型：
-
-```text
-› /provider                          # 打开供应商菜单，上下键选择
-› /provider deepseek                 # 选用默认模型；缺 Key 时直接输入
-› /model deepseek-v4-pro             # 改用另一模型
-› /provider openrouter               # 先切换供应商
-› /model anthropic/claude-sonnet-4   # 再设置该供应商的模型
-› /provider openai-compatible
-› /model vendor-model
-› /endpoint https://api.vendor.example/v1
-```
-
-切换后保留会话历史。`--api-key` 仅用于启动时选择的供应商，不会被带到另一家。
-从 OpenAI 在会话内切换到自定义兼容端点时，也不会复用 `OPENAI_API_KEY`；
-TUI 会单独询问这个端点的 Key。
-
-### Provider 配置
-
-| Provider | API Key | 模型环境变量 | 默认模型 | API 形式 |
-| --- | --- | --- | --- | --- |
-| OpenAI | `OPENAI_API_KEY` | `OPENAI_MODEL` | `gpt-5.6` | Responses API |
-| DeepSeek | `DEEPSEEK_API_KEY` | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | OpenAI-compatible Chat Completions |
-| 自定义兼容供应商 | `OPENAI_API_KEY` | `OPENAI_MODEL` | 必填 | OpenAI-compatible Chat Completions |
-| OpenRouter | `OPENROUTER_API_KEY` | `OPENROUTER_MODEL` | 必填 | OpenAI-compatible Chat Completions |
-| Groq | `GROQ_API_KEY` | `GROQ_MODEL` | 必填 | OpenAI-compatible Chat Completions |
-| xAI | `XAI_API_KEY` | `XAI_MODEL` | 必填 | OpenAI-compatible Chat Completions |
-| Moonshot | `MOONSHOT_API_KEY` | `MOONSHOT_MODEL` | 必填 | OpenAI-compatible Chat Completions |
-
-显式传入的 `--model` 优先于 Provider 对应的模型环境变量。自定义兼容供应商还必须
-配置 `OPENAI_BASE_URL`。Session 记录在 `CHIVGENT_HOME`（默认 `~/.chivgent`）下。
-
-Provider 通过注册表声明，而不是在 CLI 里分支判断，因此 `--help` 的内容、
-`--provider` 的校验和实际创建 Client 用的是同一份清单。
-
-#### API Key 解析顺序
-
-按以下顺序解析，命中即停：
-
-1. `--api-key`（仅本次运行）
-2. Provider 对应的环境变量
-3. `<CHIVGENT_HOME>/auth.json`
-
-环境变量刻意排在文件之前，与其他 CLI 的惯例一致，这样已存储的 Key 可以被
-一次性的环境变量临时覆盖，而不必改文件。
-
-`auth.json` 是可选的，只接受字面量 Key：
-
-```json
-{
-  "openai": { "type": "api_key", "key": "sk-..." },
-  "deepseek": "sk-..."
-}
-```
-
-不支持 `$VAR` 展开，也不支持 `!command` 替换：让配置文件能够启动进程，
-是用很小的便利换很大的攻击面。当该文件可被其他用户读取时 chivgent 会告警，
-请保持 `chmod 600`。
-
-```bash
-chivgent --provider openai --model gpt-5.6 "解释 package.json"
-chivgent --provider deepseek --model deepseek-v4-pro "解释 package.json"
-chivgent --provider openai-compatible --model vendor-model "解释 package.json"
-```
-
-## 架构
-
-```text
-                                  +-> OpenAI Responses API
-用户 -> CLI -> Agent -> LLMClient |
-                 |                +-> OpenAI-compatible Chat -> DeepSeek / 自定义
-                 |
-                 +-> Tool Registry -> list_files / search_text / read_file -> Workspace
-                                      write_file / edit_file（--allow-writes）
-                 |                    bash（--allow-shell）-> ShellOperations
-```
-
-Agent Runtime 拥有自己的消息模型。Provider 特有的数据结构只在 `LLMClient` 边界
-进行转换：
-
-```text
-Agent Message[] -> Provider Adapter -> Provider Request
-                                      <- Provider Response
-AssistantMessage <- Normalized Result
-```
-
-因此 Agent、工具和 CLI 不会依赖任何单一供应商的消息格式。
-
-### 上下文管理
-
-Session 记录发生过的一切；Context Manager 决定这一次请求值得发送什么。把两者
-分开，才能让长会话待在固定的上下文窗口内。
-
-```text
-完整 transcript ──────────────→ Session Store（发生了什么）
-       │
-       ↓
-ContextManager
-       │  token 估算 vs. contextWindow - reserveTokens
-       ↓
-摘要 + 最近消息 ──────────────→ Provider（模型看到什么）
-```
-
-当估算超出预算时，较早的消息会被压缩成一条摘要消息，最近若干轮原样保留。
-有三个细节值得注意：
-
-- **文件清单从工具调用推导，而不是从摘要里提取。** 摘要可能遗漏或者编造路径。
-  对 Coding Agent 来说，「我读过和改过哪些文件」是最需要完整存活的信息，因此
-  它直接从 `read_file`、`write_file`、`edit_file` 的调用参数收集。
-- **工具调用永远不会和它的结果被切开。** 会把 tool result 孤立的切点会向前
-  移动，越过整组消息。
-- **压缩会丢弃 Provider continuation。** 在服务端串联历史的 Provider 会重放
-  它自己那份历史、忽略请求里带的消息，保留 continuation 等于把刚压缩掉的历史
-  又送了回去。
-
-Token 数量按字符长度估算，而不是用真正的 tokenizer：后者与模型强相关，为一个
-只用来决定「何时压缩」的数字引入大依赖并不划算，估算误差由 reserve 预算吸收。
-
-单条超过整个预算的工具结果无法被压缩掉，这种情况应该去限制工具输出本身。
-用 `--no-compaction` 可以关闭压缩。
-
-### 运行时事件
-
-Agent Loop 自己不打印任何内容，而是通过类型化的事件流对外汇报。一次运行会产生：
-
-```text
-agent_start
-  turn_start -> message_start -> message_update* -> message_end
-    tool_execution_start -> tool_execution_end   (每个 Tool Call 一次)
-  turn_end
-  ...
-agent_end (completed | max_turns | aborted | error)
 ```
 
-`message_update` 只携带增量，不携带累计快照，因此事件流的体积与答案长度保持线性
-关系。事件都是可结构化克隆的，且每个监听者拿到的是副本，渲染层无法修改
-transcript。`src/render.ts` 中的 CLI 渲染器只是其中一个消费者，日志、JSON 流或
-TUI 同样可以消费。
-
-`LLMClient.stream` 是可选的。Provider 未实现时，Agent 会退回 `complete`，事件序列
-不变，只是没有增量事件。
-
-### OpenAI-compatible 供应商
-
-兼容供应商可以通过修改 `baseURL`、凭据和模型名称，复用官方 `openai` npm 包。
-CLI 用户无需修改代码：
+没有 key 也能打开会话。输入 `/provider`，按提示填入，或先导出一把。key 只给当前用户读，保存在 `~/.chivgent/auth.json`。
 
 ```bash
-export OPENAI_API_KEY="your-provider-api-key"
-export OPENAI_BASE_URL="https://api.vendor.example/v1"
-export OPENAI_MODEL="vendor-model"
-
-chivgent --provider openai-compatible "src/agent.ts 是做什么的？"
-```
-
-`OPENAI_BASE_URL` 必须指向供应商的 OpenAI-compatible API 根地址。供应商至少需要
-实现 `POST /chat/completions` 和 Function Tool Calling。
-
-如果要在源码中增加一个具名 Provider，可以复用相同的 Adapter：
-
-```ts
-const client = new OpenAICompatibleChatClient({
-  apiKey: process.env.VENDOR_API_KEY!,
-  baseURL: "https://api.vendor.example/v1",
-  model: "vendor-model",
-  continuationTag: "vendor-chat",
-});
-```
-
-`DeepSeekChatClient` 就是共享客户端之上的轻量配置包装器。兼容层还会把 DeepSeek
-的 `reasoning_content` 等 Provider 私有字段保存在不透明的 continuation state 中。
-
-修改 `baseURL` 不代表所有能力都能完全兼容。不同供应商的模型名称、鉴权方式、
-工具 Schema、Strict Mode、推理字段、流式事件和错误结构都可能不同。供应商差异
-应保留在轻量 Provider Adapter 内，而不是泄漏到 Agent Loop。
-
-## 项目结构
-
-```text
-src/
-  cli.ts                         CLI 入口与进程边界
-  cli-options.ts                 参数和 Provider 配置
-  auth/
-    credentials.ts               凭据契约与解析顺序
-    runtime-credentials.ts       --api-key 覆盖层
-    env-credentials.ts           环境变量查找
-    file-credentials.ts          auth.json 存储的读与写
-  agent.ts                       Agent Loop 与运行状态
-  events.ts                      运行时事件模型
-  render.ts                      运行时事件的终端渲染
-  llm.ts                         Provider 无关的 LLM 契约
-  retry.ts                       Provider 超时与重试装饰器
-  messages.ts                    运行时消息模型
-  session.ts                     会话状态与事件分发
-  session-store.ts               JSONL 会话日志与恢复
-  repl.ts                        交互式输入与斜杠命令
-  context/
-    context-manager.ts           构造单次请求的消息
-    compaction.ts                压缩历史并跟踪文件
-    token-estimator.ts           基于字符的 Token 估算
-  workspace.ts                   工作区配置与只读默认值
-  workspace/
-    types.ts                     上限、错误类型与 Workspace 契约
-    paths.ts                     路径归一化与逃逸防护
-    ignore.ts                    .gitignore 与生成目录过滤
-    text.ts                      UTF-8 解码、行切分与预览
-    read.ts                      分段读取
-    list.ts                      目录遍历
-    search.ts                    字面量文本搜索
-    write.ts                     原子整文件写入与精确编辑
-  providers/
-    registry.ts                  Provider 注册表
-    usage.ts                     Provider token 用量的解析与累加
-    deferred-client.ts           Provider 可以稍后到位的客户端
-    definitions.ts               内置 Provider 声明
-    client.ts                    凭据解析并构造 LLM Client
-    openai.ts                    OpenAI Responses Adapter
-    openai-compatible-chat.ts    通用 Chat Completions Adapter
-    deepseek.ts                  DeepSeek 配置包装器
-  tools/
-    tool.ts                      Tool 契约
-    output.ts                    共享的 64 KiB 工具输出边界
-    list-files.ts                确定性的项目树发现工具
-    search-text.ts               有界的源码字面量搜索工具
-    read-file.ts                 分段文本读取工具
-    write-file.ts                整文件创建与替换
-    edit-file.ts                 精确唯一匹配编辑
-    bash.ts                      Shell 命令执行
-  prompts.ts                     Agent 运行时使用的提示词
-  evals/
-    task.ts                      任务定义与校验
-    fixture.ts                   每次尝试一份全新的工作区副本
-    graders.ts                   确定性判定器
-    runner.ts                    跑 N 次并聚合
-    report.ts                    表格与 JSON 输出
-    parse-args.ts                Eval CLI 参数
-    cli.ts                       npm run eval
-  remote/
-    protocol.ts                  消息形状与版本协商
-    framing.ts                   有界缓冲的 JSON Lines 分帧
-    server.ts                    在 Unix socket 上服务一个会话
-    client.ts                    接入一个已服务的会话
-    repl.ts                      接入端的交互循环
-    socket-path.ts               socket 路径、陈旧检测与发现
-  extensions/
-    trust.ts                     按目录记录的信任存储
-    decide-trust.ts              询问流程，以及无人可问时的拒绝
-    discover.ts                  扩展的位置与文件识别规则
-    api.ts                       扩展可以注册什么
-    registry.ts                  收集注册项并拒绝冲突
-    loader.ts                    import 模块并隔离其失败
-  shell/
-    types.ts                     执行契约与 Shell 错误类型
-    config.ts                    Shell 解析与 Windows 拦截
-    local.ts                     本地 spawn 后端
-    process.ts                   进程组终止与退出处理
-    output.ts                    有界的流式输出累积器
-    truncate.ts                  命令输出的尾部截断
-    sanitize.ts                  控制字符过滤
-tests/                           Provider、Agent Loop 和 Workspace 测试
-evals/                           Eval 任务与其 fixture
-docs/                            架构与学习文档
+export OPENAI_API_KEY="your-api-key"
 ```
 
-## 开发
+在交互会话里，`/login oauth openai` 或 `/login oauth xai` 用订阅登录。平常启动时，key 仍然优先。[订阅登录](docs/subscription-oauth.md)。
 
 ```bash
-npm install
-npm run check
-npm test
-npm run build
+chivgent "入口在哪？"                                # 读完再答
+chivgent --permission-mode workspace "跑测试并修掉"
+chivgent --permission-mode ask-first "审这个项目"
+chivgent --allow-writes "把 sayHi 改成 greet"        # 旧开关，不能和模式一起用
+chivgent --allow-shell "跑测试"                      # 先确认，再进 Seatbelt 或 Docker
+chivgent --provider deepseek "讲讲 src/"
+chivgent                                             # 本地交互终端默认使用 rich TUI
+chivgent --simple                                    # 使用追加式界面
+chivgent --tui                                       # 显式请求 rich TUI
+chivgent --continue                                  # 这个目录里的上一次会话
 ```
 
-运行完整的发布检查（包含 npm tarball dry run）：
+## 模式
 
-```bash
-npm run release:check
-```
+| 模式 | 能直接进行的 | 这一版 |
+| --- | --- | --- |
+| `workspace` | 工作区内的修改和沙箱命令。网络关着。命令要用宿主机时，只为这一条问一次。 | TUI 循环中的 Auto mode，或 `--permission-mode workspace`。 |
+| `ask-first` | 读取。每次改文件、每条命令都要确认。没有答复就没有动作。 | 普通本地 rich TUI 启动，或 `--permission-mode ask-first`。 |
+| `unrestricted` | shell 命令带着宽宿主机文件访问和网络运行，仍在操作系统沙箱里。文件工具不出工作区。 | 显式选择。 |
+| 无 | 读取。写入和 shell 等开关。需要交互式确认或显式全批准。 | `--simple`、headless 和远程启动，除非指定模式或旧权限开关。 |
 
-构建一个可以在本地安装的 tarball：
+`--permission-mode` 在这个进程里代替那些开关。不能和 `--allow-writes`、`--allow-shell`、`--approve-all-shell`、`--shell-network` 一起用，也不能和 `--serve`、`--connect` 一起用。`/permissions` 查看或更改模式，但只有启动时选了模式的会话才行。这个选择不写进会话记录。恢复会话时用的是启动时选的模式，不是上次更宽的那个。
 
-```bash
-npm install -g "$(npm pack --silent)"
-```
+`/plan` 是另一件事。它让 agent 停在只读工具和一份计划上。即使模型要求，写入、shell 和扩展工具也会被挡住。
 
-测试使用脚本化或 Mock LLM Client。真实 API Smoke Test 需要手工执行，因此默认
-测试不会消耗 API 额度。
+## 它怎么接在一起
 
-## Evals
+你在终端里打字。chivgent 调用你选的模型。文件工具不出当前目录。shell 在沙箱里运行，拿不到你的模型 key。默认启动时，shell 要打开才出现。
 
-**Agent 任务计划：** 复杂任务可通过参考 Codex 的 `update_plan` 更新结构化任务清单，TUI 显示进度，且不会授予额外文件或 Shell 权限。详见 [Agent 计划与进度](docs/agent-plan-progress.md)。
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/fit-zh-dark.svg">
+  <img src="docs/assets/fit-zh-light.svg" width="920" alt="默认启动：你、chivgent、你选的模型、当前目录，以及只有打开 shell 才出现的沙箱。">
+</picture>
 
-**TUI V5：** 默认输入框现支持斜杠命令补全、鼠标定位与拖选，以及需逐次确认的只读 `/gitdiff [--staged]` 工作区审查。详见 [TUI V5 指南](docs/tui-v5.md)。
+## 它能碰到什么
 
-**TUI V4：** `--tui` 默认使用可自由编辑的多行输入框：Enter 发送、Ctrl+O 换行、Ctrl+Z/Y 撤销重做、Ctrl+R 搜索历史。详见 [TUI V4 指南](docs/tui-v4.md)。
+下面是这一版，不是上面那个 auto 式默认。
 
-**TUI V3：** `/editor` 支持光标移动的真正多行输入（Ctrl+S 发送），`/review` 支持交互式翻页审查补丁，代码块具备基础语法高亮。详见 [TUI V3 指南](docs/tui-v3.md)。
+| | 怎么开 | 能碰到什么 |
+| --- | --- | --- |
+| 读这个项目 | 开着 | 当前目录。被忽略的、生成的和凭据路径会跳过。 |
+| 改文件 | `--allow-writes` | 工作区内的文件。修改必须精确匹配，写入是原子的。 |
+| 跑命令 | `--allow-shell` | macOS 用 Seatbelt，其他系统用 Docker。默认没有网络。每条命令都要确认。 |
+| 选一种策略 | `--permission-mode` | `ask-first`、`workspace` 或 `unrestricted`。在这个进程里代替上面的开关。 |
 
-**TUI V2：** 支持 `/compose` 多行输入、`/diff [页码]` 查看完整补丁、Markdown/代码块显示以及单键 Shell 审批。详见 [TUI V2 指南](docs/tui-v2.md)。
+费用付给你选的供应商，按他们的价格。chivgent 显示 token 数，不折算成费用。
 
-**并行只读工具：** 内置文件读取、目录列举与搜索最多同时执行 4 个；写入、Shell 与第三方扩展保持独占，模型接收的工具结果顺序不变。详见 [工具调度说明](docs/parallel-read-tools.md)。
+## 模型
 
-**项目规则：** 支持分目录加载 `AGENTS.md` 与 `AGENTS.override.md`，详细作用域与上下文压缩说明见 [项目指令文档](docs/scoped-agents-md.md)。
+| 供应商 | `--provider` | Key | 模型 |
+| --- | --- | --- | --- |
+| OpenAI，Responses API | `openai`（默认） | `OPENAI_API_KEY` | `gpt-5.6` |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-v4-flash` |
+| 任何兼容端点 | `openai-compatible` | `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` | 设置 `OPENAI_MODEL` |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | 设置 `OPENROUTER_MODEL` |
+| Groq | `groq` | `GROQ_API_KEY` | 设置 `GROQ_MODEL` |
+| xAI | `xai` | `XAI_API_KEY` | 设置 `XAI_MODEL` |
+| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | 设置 `MOONSHOT_MODEL` |
 
-**批量补丁：** `--allow-writes` 现在可以使用 `apply_patch` 一次修改多个文件，采用严格上下文校验；参见 [补丁格式和限制](docs/apply-patch.md)。
+`--model` 覆盖模型变量。key 按这个顺序找：`--api-key`，然后环境变量，然后 `~/.chivgent/auth.json`。自定义的 base URL 会收到你的 key 和提示词。只把它指向你信任的端点。
 
-**Shell 安全提示：** `--allow-shell` 现在通过无网络的 Docker 容器执行命令，交互模式会逐条请求确认；非交互模式默认拒绝，除非显式使用 `--approve-all-shell`。限制与风险详见 [Shell 沙箱说明](docs/shell-sandbox.md)。
+兼容端点必须实现支持工具调用的 `POST /chat/completions`。只换 base URL，并不保证完全兼容。[架构](docs/architecture.md#openai-compatible-providers)。
 
+## 会话还在
 
-评测前请先运行 `npm run eval -- --dry-run --allow-writes --allow-shell`，在不调用模型的情况下校验任务和生成题目指纹。具体方法见 [基线评测指南](docs/eval-baseline-guide.md)。Token 用量缺失会标为未知，而不是 0。
+不带问题运行 `chivgent`，就是一次交互会话。会话保存在 `~/.chivgent/sessions`。`--continue` 恢复这个目录里最近的一次。`/resume` 列出其余的，并且只打开这里的会话。
 
+`/compact` 压缩较早的轮次，完整记录仍留着，方便恢复。`/status` 显示模型、权限和 token 用量。其余的，`/help`。
 
-三百多个单元测试验证的是"代码是否按我写的那样运行"，它们对"这是不是一个好用的 Agent"
-一无所知。`npm run eval` 回答后一个问题：
+本地交互终端默认使用 rich TUI。`--simple` 选择追加式界面；`--tui` 仍可显式请求 rich TUI，包括将 stdout 重定向时。管道输入或输出、JSON、单次提问、`--serve` 和 `--connect` 保持原有简单输出。`TERM=dumb` 自动选择简单界面；设置 `NO_COLOR` 时仍使用 rich TUI，但不输出颜色。没有旧权限开关或显式权限模式时，rich TUI 默认使用 Ask for me。空闲输入框中的 Shift+Tab 可循环切换 Plan → Auto mode → Ask for me，页脚显示当前模式。简洁欢迎信息不显示 session ID；用 `/session` 或 `/status` 查看完整信息，`/help` 查看命令和快捷键。显式 `--permission-mode` 和旧权限开关继续按原有方式工作。[TUI](docs/tui.md)。长会话会压缩较早的轮次，并留下读过和改过的文件列表，从而留在上下文窗口里。[上下文](docs/architecture.md#context-management)。
 
-```bash
-npm run eval                              # 跑 evals/ 下全部任务
-npm run eval -- --task rename-symbol --attempts 10
-npm run eval -- --allow-writes --allow-shell --json report.json
-DEEPSEEK_API_KEY=sk-... npm run eval -- --provider deepseek
-```
+在内联编辑器中输入 `/` 可浏览已注册命令，继续输入可筛选命令。用 ↑/↓ 选择命令，再按 Tab 或 Enter 将其补全到草稿；之后按 Enter 提交。鼠标单击可补全可见命令，滚轮可浏览菜单。Esc 关闭菜单并保留草稿。完整输入的命令仍可直接按一次 Enter 执行。
 
-`--api-key` 也能用，但这里更推荐环境变量：npm 会在执行前把展开后的完整命令回显出来，
-写在命令行上的 key 会明文出现在任何被采集的日志里。
+## 边界
 
-```text
-task                  pass  turns  tokens  tools                       p50
-find-auth-logic       4/5   2.0    3.4k    list_files,search_text,...  6.1s
-rename-symbol         3/5   5.4    12.1k   read_file,edit_file         9.8s
+- 工作区以外的路径会被拒绝，包括 `..` 和符号链接逃逸。常见凭据路径会被拒绝。工具输出有上限。
+- 没有选模式或旧权限开关时，`--simple`、headless 和远程启动仍为只读。本地 rich TUI 启动会为当前进程选择 `ask-first`，除非指定了旧权限开关。`--allow-shell` 需要交互式确认；非交互式命令除非指定 `--approve-all-shell`，否则会被拒绝。`--serve` 会话除非同时加上 `--approve-all-shell`，否则拒绝命令。沙箱起不来，命令不会改到无沙箱运行。
+- `workspace` 自动执行工作区内的修改和沙箱命令，命令要访问宿主机文件和网络时问一次。`unrestricted` 是显式选择的宽宿主机访问和网络。这些都不随会话保存。[Shell 安全](docs/shell-sandbox.md)。
+- macOS 沙箱仍然能读当前用户能读的文件。它限制的是写入和网络，不是机密隔离。
+- 还没有按命令的允许列表，也没有原生 Windows shell。`workspace` 不是这一版的启动模式。
+- 扩展是跑在 chivgent 进程里的 JavaScript。信任一个项目，就是允许它的作者以你的身份执行代码。每个目录问一次；没有终端可问时，不加载。
+- key、订阅凭据和会话日志只对文件所有者可读，而且是明文。日志里有提示词、回答和文件摘录。
+- `--serve` 把会话放在仅所有者可进的目录里的 Unix socket 上。谁能打开这个 socket，谁就拿到服务器启动时的全部能力。没有 TCP 监听。
 
-overall  7/10 (70%)  58.3k tokens
+在已提交的代码上工作。不信任的仓库，用一份副本。
 
-rename-symbol attempt 2,5: not-used-tool name="write_file" — called write_file 1 time(s)
-```
-
-`tokens` 那一列是 Provider 自己报的数字，于是一次改动可以同时看两个维度：
-一个把通过率从 70% 提到 75%、token 却翻三倍的 prompt 改动通常是笔坏买卖，
-而少了第二个数字它看起来是纯赚。
-
-**Eval 不是测试。** 模型是不确定的，所以一个任务跑一次就是抛硬币：通过与失败不是这次
-运行的属性，而是"模型 + harness"这个组合的属性。因此 eval 的基本单位是 **N 次尝试的
-通过率**；也因此 **evals 绝不进 CI 门禁**——让 CI 花钱、并且以六成概率变红，两周内就会
-训练所有人忽略 CI。`npm test` 依然免费、离线、确定。
-
-一个任务就是 `evals/` 下的一个目录：一份 `task.json` 加一棵 `fixture/` 文件树，
-每次尝试都复制到一个全新的临时工作区。
-
-```jsonc
-{
-  "prompt": "把 sayHi 重命名成 greet，包括所有调用处。",
-  "capabilities": ["writes"],
-  "attempts": 5,
-  "graders": [
-    { "type": "file-contains", "path": "src/greet.ts", "text": "export function greet(" },
-    { "type": "file-excludes", "path": "src/greet.ts", "text": "sayHi" },
-    { "type": "used-tool", "name": "edit_file" },
-    { "type": "not-used-tool", "name": "write_file" }
-  ]
-}
-```
+这个仓库还包含 Electron 桌面应用。它通过原生目录选择器打开项目，并用同一 Agent 和只读项目工具运行已配置的 Provider。桌面端仅从环境变量或 CLI `auth.json` 读取 API Key，不保存凭证；它不会读取 `oauth.json` 或刷新订阅 OAuth 凭证。仅通过 `/login oauth` 登录的用户，使用桌面端前还需配置 API Key。选择兼容 Provider 时，请先核对界面显示的请求端点，再发送项目内容。目前仅有一个内存会话，不提供历史列表或重启恢复。设置 `CHIVGENT_DESKTOP_DEMO=1` 可显式启用离线演示。使用 `npm run desktop:dev` 开发；离线真实 adapter 验收运行 `npm run desktop:build && node apps/desktop/scripts/verify-readonly.mjs`。[桌面行为与限制](docs/desktop-architecture.md)。
 
-判定器全部是确定性的——文件内容、工具调用、回答匹配、轮数。**没有 LLM judge**：
-判官本身就是一个不确定的测量仪器，用它去测量不确定的对象，两个误差会叠加，
-最后你无法分辨"Agent 变差了"和"判官今天心情不同"。
-
-最后两条判定才是重点。整文件重写同样能得到正确的内容，一个只看结果的 eval 会给它满分。
-对编码 Agent 来说，**工具误用是比答错更常见、也更值得测的失败**，所以任务不仅判定
-"做对了没有"，还判定"是怎么做的"。
-
-**一条判定如果点名了这个任务拿不到的工具，加载任务时就会报错。** 只读任务上的
-`not-used-tool: write_file` 永远不可能失败——它断言模型没调用一个它从没拿到过的工具；
-反过来 `used-tool` 一个拿不到的工具则永远不可能通过。两者都是任务定义写错了，都在花第一
-分钱之前拦下来。这类判定曾经在仓库里躺了两个版本。
-
-有三条判定的存在，是因为"用过哪些工具"这个集合回答不了它们回答的问题。
-`tool-never-failed` 抓瞎猜路径——猜错的读必然报错，而去重后的名字集合看不见这件事。
-它只在"失败即出错"的工具上成立：`read_file` 成立，`bash` 不成立——后者对任何非零退出码
-都报错，而在"先跑一次让它挂"的任务上，失败正是对的。`max-tool-calls` 卡的是调用次数
-而不是轮数，因为一轮里可以发起任意多次调用："到底是顺着 import 找过去，还是把整个项目
-读了一遍"，这是个次数问题；
-`file-unchanged` 拿 fixture 原件做字节比较，把"别动没让你动的东西"从愿望变成判定，
-而且不需要在 `task.json` 里再抄一份文件内容（抄一份就会有忘记同步的那天）。
-JSON 报告里多了 `toolCalls`：按调用顺序记录每一次调用和它成功与否，和表格用的
-`toolsUsed` 集合并存。
-
-九个任务分成"找到了什么"和"改了什么"两类。其中四个的存在理由是：第一次真实基线
-30 次里过了 29 次，也就是什么都没测出来——`needle-in-many-files`（40 个文件名毫无
-信息量，`list_files` 给不出线索）、`trace-the-default`（一个值被覆盖两次，停在第一跳
-会得到一个看起来很合理的错数字）、`decoy-config`（两个几乎一样的模块，其中一个是死代码）、
-`wrong-test`（挂掉的测试，其期望与源码里写明的契约矛盾，改源码去迎合它就是陷阱）。
-
-**一个任务如果在不同模型上都是 0/N 或都是 N/N，它就没在测东西**，应该改难、改对，
-或者删掉。全都过不是质量的证据。
-
-## Token 用量
-
-Provider 每次调用都会报告代价，chivgent 现在会把它留下来：每轮在 `message_end` 上、
-整次运行在 `agent_end` 和运行结果上、每次 eval 尝试在报告里、以及 `/session` 的累计。
-
-```text
-› /session
-id:        2026-09-07T...
-workspace: /home/me/project
-prompts:   4
-messages:  18
-tokens:    38.2k total, 35.9k in, 2.3k out, 12.0k cached
-```
-
-**只报 token，不报钱。** 换算成金额需要一张"模型 → 单价"的表，而那张表会在 Provider
-调价时**悄悄过期**，产出一个看起来精确、实际错误的金额——那比没有数字更糟，因为没人
-会去质疑一个带小数点的数。token 数是 Provider 自己报的事实，不会过期。
-
-某次调用没报用量时，合计会被**标记为不完整**，而不是当成零：缺失的数字要看得见地
-缺着，而不是悄悄把合计压小。压缩自己那次摘要调用**计入**合计——它拿"现在多花一次
-调用"换"后续输入更小"，少算一半就没法判断这笔交易划不划算。
-
-流式的 Chat Completions 默认不报用量，必须显式索取，所以 chivgent 会发送
-`stream_options: { include_usage: true }`。某些较早的自建 OpenAI 兼容端点可能不认识
-这个字段而拒绝请求，此时 `--no-stream` 是退路。
-
-## 活的区域
-
-`--tui` 会在提示行上方画一块状态区域：第几轮、模型在想还是在跑工具、哪几个工具在跑、
-各自针对什么、最新一行输出、已经跑了多久、累计花了多少 token。
-
-```text
-Let me look at how sessions are stored.
-  read_file src/session.ts (2s)
-  search_text (1s)  src/store.ts:41: export class SessionStore
-running tools  ·  turn 2/8  ·  11s  ·  4.2k tokens  ·  ctrl+c to stop
-```
-
-它是事件流的第一个**反向**消费者。其他所有消费者——流式输出、会话日志、扩展、远程
-客户端——都是追加式的：事件来了就打印，打印完就忘掉。这一个必须从同一条流里**重建出
-"现在是什么状态"**，并随着新事件到达保持它正确。这件事拆成三段：
-
-```text
-reduce(state, event, now)  ->  ViewState     纯函数
-view(state, {width, now})  ->  string[]      纯函数
-paint(previous, next)                        唯一碰终端的地方
-```
-
-两个纯函数不需要终端就能测，真正的保证在那里。让状态模型成为承重结构的，是事件词汇表
-里的一处不对称：`message_update` 带的是**增量**，`tool_execution_update` 带的是被截断过
-的**快照**。对快照做追加，会堆出从未产生过的输出——那个窗口的头部早就被丢掉了；对增量
-做替换，则只剩最后一个 token，整个回答就没了。追加式渲染器**永远不需要知道这个区别**，
-因为它只管把收到的东西打出去。有两条测试，写反哪一边红哪一边。
-
-它**不接管备用屏**。切过去滚动历史就没了，要补回来就得重新实现滚动、搜索和选中——
-几千行，而且教的是终端图形，不是 Agent 架构。已完成的一轮会被刷进终端自己的滚动历史
-并从状态里丢掉，所以再长的会话也不会把状态撑大。输入继续交给 readline 也是同一个理由：
-行编辑器不是这里值得解决的问题。
-
-绘制只重写内容变了的行，所以一个跳动的计时器只花一行，而不是重画整块。改变窗口大小会
-让这个基准失效——终端已经把屏幕上的内容重新折行了——那是唯一一个"整块重画才是对的"
-时刻。
-
-`--tui` 需要 stdin 和 stderr 都是终端，且是交互式会话；不满足时**直接报错而不是静默
-退回**，因为一个安静地什么都不做的开关，会让打错的命令看起来像成功了。目前**不是默认**。
-简短的启动提示显示供应商、模型、工作目录和下一步操作；用 `/session` 查看会话 ID。
-输入 `/` 即在当前输入行下方显示斜杠命令（包括扩展命令），可用上下键选择、Tab 补全；
-上下键浏览输入历史。运行中普通输入会被忽略，Ctrl+C 仍可立即取消；取消后恢复提示符，
-已收到的部分回答保留在滚动历史中。运行结束会显示结果、耗时和已报告的 token 用量。
-
-中文、组合字符和 Emoji 按终端列宽截断；长的单行回答保留最新文字，长路径保留文件名和
-工具进度，窄窗口优先显示状态与停止快捷键。较矮的窗口优先保留状态行，缩放会重绘当前
-区域。提示符及界面走 stderr，最终回答走 stdout，可用 `chivgent --tui > answers.txt`
-保存回答，同时继续在终端交互。
-
-```sh
-npm run build
-node dist/cli.js --tui
-npm run demo:tui  # 离线交互演示，无需 API Key 或网络
-```
-
-演示使用模拟供应商与工具进度，不修改工作区。操作说明和验证方式见 [TUI 指南](docs/tui.md)。
-
-## 远程会话
-
-会话通常和启动它的那个终端同生共死。`--serve` 让它留在一个进程里，其他进程可以接上来：
-
-```bash
-# 终端 A
-chivgent --serve --allow-writes
-# chivgent 0.12.0 serving session 2026-09-06T...
-# socket:       ~/.chivgent/sockets/2026-09-06T....sock
-# capabilities: --allow-writes
-
-# 终端 B
-chivgent --servers                 # 列出正在运行的服务端
-chivgent --connect <id>            # 交互式接入
-chivgent --connect <id> "问题"      # 问一次就走
-```
-
-客户端不持有任何状态：它只负责发 prompt、渲染服务端广播的事件流。可以同时接入多个
-客户端——多出来的那些实时观察同一次运行，并且**任何一个都能中断它**，因为运行属于会话，
-不属于"谁发起的"。运行期间再来一个 prompt 会被拒绝而不是排队；客户端中途断开也不会
-取消正在跑的运行。
-
-接入时**不重放历史**——那是会话日志的职责。协议是 Unix socket 上的 JSON Lines，
-一行一个对象，和 `--json` 输出同一种形状。
-
-**能连上这个 socket 的人，拥有服务端启动时的全部能力。** 如果它是带 `--allow-shell`
-起来的，那么任何能连上的人都能让模型执行命令——这正是服务端启动时会打印本次能力的原因：
-接入的人看不到你敲了什么参数。边界是文件系统权限（socket 位于 `CHIVGENT_HOME` 下仅
-所有者可访问的目录），并且**不监听 TCP**。要跨机器访问请用 SSH 转发，让认证由 SSH 负责。
-
-## 扩展系统
-
-一个扩展就是默认导出一个函数的 ES 模块。启动时它会被调用一次，拿到的 API 可以注册
-工具、注册斜杠命令、订阅运行时事件、追加 system prompt。
-
-```js
-// .chivgent/extensions/word-count.js
-export default function (api) {
-  api.registerTool({
-    name: "word_count",
-    description: "统计工作区某个文件的词数。",
-    inputSchema: {
-      type: "object",
-      properties: { path: { type: "string" } },
-      required: ["path"],
-      additionalProperties: false,
-    },
-    async execute(args, context) {
-      const file = await context.workspace.readTextFile(args.path);
-      return {
-        content: `${file.content.split(/\s+/).filter(Boolean).length} words`,
-        isError: false,
-      };
-    },
-  });
-
-  api.contributeSystemPrompt("需要数词数时用 word_count，不要整篇读文件。");
-}
-```
-
-扩展从两个位置加载：
+## 文档
 
-| 位置 | 何时加载 |
+| | |
 | --- | --- |
-| `<CHIVGENT_HOME>/extensions/` | 始终加载——那是你自己机器上的配置 |
-| `<工作区>/.chivgent/extensions/` | 只有在你信任该项目之后 |
-
-两处都接受 `name.js` 和 `name/index.js`，不再往下递归。**只支持纯 JavaScript**：
-用 TypeScript 写的话自己编译成 `.js` 即可，为此让 chivgent 背上一个 TS 运行时加载器
-不划算。与内置工具或命令重名的注册会被拒绝，所以扩展无法顶替 `read_file` 或
-`/clear`；某个扩展坏掉只会被报告并跳过，不会把 chivgent 一起带走。
-
-`chivgent --extensions` 可以列出加载了哪些扩展、各自注册了什么。
-
-### Project Trust
-
-第一次在带扩展的项目里运行 chivgent 时，它会说明这些扩展是什么并询问一次。答案记在
-`<CHIVGENT_HOME>/trust.json` 里，键是解析后的目录路径，**按最近祖先匹配**——信任
-`~/work` 就覆盖它下面所有仓库。`--forget-trust` 可以删掉覆盖当前工作区的那条决定。
-
-**信任一个项目，等于允许这个仓库的作者以你的身份执行代码。** 扩展在 chivgent 进程内
-运行：不受工作区边界约束，不需要 `--allow-shell` 就能执行命令，也能读到你环境变量里的
-API Key。这正是询问必须发生在 import 之前的原因，也是"没人可问时一律拒绝"的原因——
-CI 任务或管道运行永远不会自作主张去执行一个 clone 里的代码。
-
-## 安全模型
-
-- API Key 依次从 `--api-key`、环境变量、可选的 `auth.json` 解析，绝不能提交到仓库。
-- `auth.json` 以明文保存 Key，因此它是可选的；当文件权限允许其他用户读取时会告警。
-- `/login` 会以仅所有者可读的权限写入，输入也不回显，但 Key 依然是明文存储的——
-  它是一个便利设施，不是密钥管理器。
-- 该文件只接受字面量 Key，无法展开环境变量或执行 Shell 命令。
-- 自定义 `OPENAI_BASE_URL` 会收到配置的 API Key 和提示词，只能使用可信端点。
-- 不传 `--allow-writes` 时工作区工具全部只读，`write_file` 和 `edit_file` 根本
-  不会被注册。
-- `bash` 工具需要 `--allow-shell`，它与 `--allow-writes` 相互独立，永远不会被后者
-  顺带打开。授予它意味着授予大得多的权限：Shell 能改动或删除运行 chivgent 的用户
-  能碰的任何东西，无论是否在工作区内，下面这些工作区限制对它一律不适用。
-- 命令运行在独立进程组中并按组杀死，取消一次运行不会留下孤儿后代进程。
-- 命令会继承 chivgent 的环境变量，其中包含它正在使用的 API Key。开了
-  `--allow-shell` 的模型可以读到这个 Key 以及环境里的其他内容。请只带上这次任务
-  真正需要的环境变量。
-- 被截断的命令输出会写入临时文件供模型按需读取。该文件仅所有者可读，但运行结束后
-  **不会自动删除**，其中可能包含命令打印的任何内容。处理敏感数据后请清理临时目录。
-- 开启 `--allow-shell` 后，会话日志除文件片段外还会记录命令输出。
-- 项目扩展只有在存在明确的、已记录的信任决定之后才会加载，且没有终端可问时绝不加载。
-  扩展以你的权限在进程内运行，上面那些工作区限制对它一概不适用——因此"信任一个项目"
-  与 `--allow-shell` 是同一量级的授权，区别只在于前者由 clone 一个仓库触发，
-  后者要你亲手敲一个参数。
-- `<CHIVGENT_HOME>/extensions/` 下的用户级扩展始终加载，那是你自己的配置。
-- 扩展无法占用内置工具或内置命令的名字。
-- `trust.json` 与会话日志、认证文件一样，以仅所有者可读的权限写入。
-- 被服务的会话对任何能打开其 socket 的人可达，且他们获得服务端启动时的全部能力。
-  socket 位于仅所有者可访问的目录中；**真正起作用的是目录权限**，因为 socket 文件在
-  能被收紧权限之前会短暂地以默认权限存在。
-- chivgent 从不监听 TCP。跨机器访问请使用 SSH 转发。
-- 写入会解析到最深层已存在的祖先目录，路径上任何一段是符号链接都会被拒绝，
-  因此预先植入的链接无法把写入重定向到工作区之外。
-- 写入先落到同目录的临时文件再 rename 就位，中断的写入不会截断已有文件。
-- `edit_file` 在 `old_text` 找不到或命中多处时拒绝执行，宁可失败也不改错行。
-- 文件路径必须位于当前工作区内。
-- Real Path 检查会阻止 `..` 路径穿越和符号链接逃逸。
-- 文件大小和二进制内容检查会限制不安全的读取。
-- 自动发现遵循根 `.gitignore` 和固定的生成目录忽略规则。
-- 所有工具统一禁止常见凭据、私钥和敏感配置路径。
-- 工具结果限制为 64 KiB，读取、扫描、深度和结果数量都有硬上限。
-- 工具输入是不可信数据，执行前必须验证。
-- Agent 会在有限的模型轮数后终止。
-- `~/.chivgent/sessions` 下的会话日志包含提问、回答和工具结果（含文件片段）。
-  在敏感项目中请使用 `--no-session`，并像对待项目本身一样对待该目录。
-- Session id 在拼接成文件路径前会先做校验。
-
-这是一个用于学习的 MVP，并不是经过加固的 Sandbox。它**没有权限系统**：能力开关
-都是会话级的粗粒度开关，`--allow-writes` 和 `--allow-shell` 都不会对每次操作逐一
-确认。这是有意为之：有了 Shell 之后，命令白名单能被一行 `sh -c` 绕开，而逐次弹确认
-只会训练用户无脑确认，所以 chivgent 选择把边界说清楚，而不是假装能拦住什么。
-
-请在已提交的代码上使用这些开关。如果需要真正的边界，请把整个进程放进容器，并只给
-容器这次任务真正需要的东西。在允许它访问敏感项目之前，请先审查代码和威胁模型。
-
-## 路线图
-
-- [x] 最小 Tool Calling Agent Loop
-- [x] 安全的 `read_file` 工具
-- [x] OpenAI 和 DeepSeek Provider
-- [x] 通用 OpenAI-compatible Chat Completions Adapter
-- [x] 自定义 OpenAI-compatible CLI Provider
-- [x] 项目发现工具：`list_files`、`search_text` 和分段 `read_file`
-- [x] 流式输出和运行时事件
-- [x] 持久化多轮 Session
-- [x] Context Window 管理和压缩
-- [x] 通过 `--allow-writes` 选择性开启的 `write_file` 和 `edit_file`
-- [x] Provider Registry 与凭据解析链
-- [x] 通过 `--allow-shell` 开启的 `bash` 工具，带流式输出
-- [x] 扩展系统与 Project Trust
-- [x] 基于本地 socket 的远程会话
-- [x] 带确定性判定器和通过率的 Eval 套件
-- [x] Provider Token 用量采集与聚合
-- [x] 由事件流驱动的活状态区域（`--tui`）
-
-逐条命令确认和命令白名单是**主动放弃**的方向。有了 Shell 工具之后，`bash` 能做的
-事是 `write_file` 的超集，任何白名单都能被一行 `sh -c` 绕开，而逐条弹确认只会训练
-用户无脑确认。能力开关一律是会话级的粗粒度开关，真正的边界是容器。
-
-## 文档
+| [架构](docs/architecture.md) | 循环、供应商、上下文，以及源码在哪 |
+| [Shell 安全](docs/shell-sandbox.md) | Seatbelt、Docker，以及一条命令仍能读到什么 |
+| [订阅登录](docs/subscription-oauth.md) | ChatGPT 和 xAI：存了什么，key 仍然做什么 |
+| [TUI](docs/tui.md) | 实时状态区、编辑器、diff 审阅 |
+| [Evals](docs/evals.md) | agent 能不能把活干完，和单元测试分开 |
+| [扩展与远程会话](docs/extensions-and-remote.md) | 你加的工具，以及另一个终端怎么接上来 |
 
-- [Stage 1：Minimal Agent 设计](docs/stage-1-minimal-agent.md)
-- [DeepSeek Provider 设计](docs/deepseek-provider.md)
-- [Stage 2：Project Discovery 实现设计](docs/stage-2-project-discovery.md)
-- [Stage 3：Runtime Events 与流式输出设计](docs/stage-3-runtime-events.md)
-- [Stage 4：Session 与交互模式设计](docs/stage-4-sessions.md)
-- [Stage 5：写入工具与 Workspace 拆分](docs/stage-5-write-tools.md)
-- [Stage 6：Provider Registry 与凭证解析链](docs/stage-6-provider-registry.md)
-- [Stage 7：上下文预算与压缩](docs/stage-7-context-management.md)
-- [Stage 8：Shell 工具与流式子进程](docs/stage-8-shell-tool.md)
-- [Stage 9：扩展系统与 Project Trust](docs/stage-9-extensions.md)
-- [Stage 10：远程会话](docs/stage-10-remote-sessions.md)
-- [Stage 11：Evals](docs/stage-11-evals.md)
-- [Stage 12：Token 用量](docs/stage-12-usage.md)
-- [发布流程](docs/releasing.md)
-
-## 参与贡献
-
-欢迎提交 Issue 和范围明确的 Pull Request。提交修改前请运行：
+## 开发
 
 ```bash
-npm run check
+git clone https://github.com/chivopic/chivgent.git
+cd chivgent
+npm install
 npm test
-npm run build
 ```
 
-请将 Provider 特有的类型保留在 `src/providers/` 中，并确保核心 Agent Runtime
-不依赖供应商 SDK 的数据结构。
+测试用脚本化的模型客户端，不花 API 额度。欢迎 issue，也欢迎范围清楚的 pull request。供应商专有的类型留在 `src/providers/`，这样 agent 不依赖某一家的 SDK。
 
 ## 许可证
 
-本项目使用 [MIT License](LICENSE)。
+[MIT](LICENSE)