--provider --model
-y/--yes --no-history --classic --ui
clai set [key] # --from-env | --stdin | --url | --skip-ping
clai unset # remove all keys for a provider
clai keys # list providers with masked keys
clai use # set active provider
clai provider [provider] # switch provider or open picker
clai model # set model for the active provider
clai mode # set default mode
clai search-provider
clai config [key] [value] # print / get / set config
clai doctor # check installed tools + provider config
clai history [--show ] # list sessions / print one
clai update # check for updates
clai authorize-pentest AGREE # enable scan/attack tools (one-time ack)
clai scope # engagement scope (new: --targets --exclude --phases
# --name --note --expires --max-rate --max-concurrency)
clai privacy
```
## 内置工具
| 组别 | 工具 |
|-------|-------|
| **文件** | `fs.read` · `fs.list` · `fs.search` · `fs.write` · `fs.writeMany` · `fs.edit` · `fs.replaceLines` · `fs.append` · `fs.delete` |
| **Shell 与作业** | `shell.exec` · `shell.start` · `shell.jobs` · `shell.tail` · `shell.stop` · `pkg.install` |
| **网络** | `net.scan` (nmap) · `net.context` · `net.pingSweep` · `dns.lookup` · `whois.lookup` |
| **HTTP / 网络** | `http.fetch` (原始证据) · `web.search` · `web.fetch` (可读内容) |
| **渗透测试** | `pentest.recon` · `pentest.webDiscover` · `pentest.apiEnumerate` · `pentest.authCompare` · `pentest.scanStatus` |
| **编排** | `tool.batch` (最多 20 次调用，`on_fail` 策略) · `tool.check` · `wordlist.find` |
| **计划** | `plan.create` · `task.update` · `agent.handoff` |
| **上下文** | `sysinfo` · `image.ocr` · `pdf.read` |
### tool.batch 失败策略
默认为 **continue** —— 一次失败的查询绝不会影响其他查询（非常适合侦察）。当后续工作依赖于早期工作的成功时，可选择启用快速失败或选择性取消：
```
{"name":"tool.batch","args":{
"on_fail":"cancel_pending",
"calls":[
{"name":"net.scan","args":{"target":"lab.example"}},
{"name":"http.fetch","args":{"url":"https://lab.example/"}}
]
}}
```
包含多个独立工具块的顶层消息不会取消同级任务——当你需要特定的失败策略时，请使用 `tool.batch`。
## 网络搜索 / OSINT
| 提供商 | 密钥 | 环境变量 |
|----------|-----|---------|
| DuckDuckGo | 无（默认） | — |
| Brave | 必需 | `BRAVE_SEARCH_API_KEY` |
| Tavily | 必需 | `TAVILY_API_KEY` |
```
clai set brave bsx-...
clai set tavily tvly-...
clai search-provider tavily
```
搜索提供商的密钥同样支持多密钥，并像模型提供商一样进行轮换。
## 特定项目的上下文
在仓库中放置一个 `.clai/context.md` 文件，其内容会在每一轮对话中被注入——实验室拓扑结构、范围内的主机、技术栈假设、编码规范，或者任何 agent 在该项目中应始终知晓的信息。
## 配置与隐私
```
clai config # view config
clai mode agent # default mode
clai model # default model for the active provider
/privacy on # private mode: don't persist this session
/privacy clear-all # wipe history, logs, and artifacts
```
配置文件存放在操作系统的用户配置目录下（例如 `~/.config/clai/`）。密钥在本地存储，并且仅以掩码形式显示。
## 开发
```
npm install
npm run dev # run from source
npm run typecheck
npm run build
npm test # full vitest suite
npm run compile # native binaries (Bun)
```
## 发布
基于 Tag 驱动的 CI（`.github/workflows/release.yml`）：验证（类型检查 + 测试 + prompt 预算 + 发布检查） → 多平台二进制文件 → GitHub Release → npm `@pentoshi/clai` → Homebrew tap。
```
# package.json 中的 "version" 是唯一的真相来源。
npm version 3.8.0 --no-git-tag-version
npm run sync-version # refreshes version.generated.ts + install manifests + lockfile
git commit -am "v3.8.0" && git push origin main
git tag -a v3.8.0 -m "clai v3.8.0" && git push origin v3.8.0
```
机密信息：`NPM_TOKEN`，`TAP_GITHUB_TOKEN`。可选：`NPM_PROVENANCE=true`。
## 架构
```
clai/
├─ src/
│ ├─ index.ts # CLI entry + subcommands
│ ├─ agent/ # loop, plans, compaction, resume orientation, tool parsing
│ ├─ llm/ # 12 providers, streaming, native tools, key rotation + fallback
│ ├─ tools/ # fs, shell, net, http, web, pentest, batch, plan
│ ├─ safety/ # risk classifier + engagement (scope) policy
│ ├─ store/ # config, history, keys, plans, scope
│ ├─ tui-v2/ # full-screen OpenTUI console (primary)
│ ├─ app/ # session controllers, commands, events
│ └─ prompts/ # agent methodology (embedded for the compiled binary)
├─ install/ · manifests/
└─ package.json
```
## License
MIT.
**仅在你被授权测试的系统上使用。** clai 是操作员的工具：授权、范围和影响由你自行承担。agent 仅在你配置的门控和确认下执行操作——仅此而已。