安装 · 快速开始 · 什么是 Smooth · 架构 · CLI · 平台
## 安装
### Homebrew（推荐，macOS + Linux）
```
brew install SmooAI/tools/th
```
这会拉取 [SmooAI/homebrew-tools](https://github.com/SmooAI/homebrew-tools) 并在首次使用时安装 `th` 二进制文件；`brew upgrade th` 会自动获取未来的发布版本。
支持平台：Apple Silicon macOS、Linux x86_64、Linux arm64。Windows 支持正在开发中（pearl `th-a165b4` —— 需要 Cargo feature 门控，以便二进制文件在 Windows 上排除 microsandbox + TUI；在此期间，请通过 WSL 安装）。
### `curl | sh`
```
curl -fsSL https://raw.githubusercontent.com/SmooAI/smooth/main/install.sh | sh
```
### 从源码构建
```
git clone https://github.com/SmooAI/smooth.git
cd smooth
cargo install --path crates/smooth-cli
```
## 快速开始
```
# 通过 Smoo AI 的 gateway 进行认证（解析每个 smooth-* slot）
th model login smooai-gateway
# 启动 Smooth — 默认在 microsandbox microVM 内启动
th up
# 打开交互式编程助手
th code
```
或者带上你自己的 provider —— 参阅 [认证](#authentication)
获取完整列表。
无需 Docker。无需 Node.js。无运行时依赖。单个 10MB 的二进制文件。
### 两种模式，同一阵容
Smooth 恰好有两种运行方式，它们共享相同的 agents、
tools 和监控 —— 唯一不同的是影响范围：
| 命令 | 它的作用 | 使用时机 |
|---|---|---|
| `th up`（默认） | 在硬件隔离的 [Microsandbox](https://github.com/microsandbox/microsandbox) microVM 内启动整个阵容（Linux 上使用 libkrun，macOS 上使用 HVF）。`:4400` 被转发出来以供 TUI / web UI 使用。 | 你的笔记本电脑，任何 host 可以运行 microsandbox 的地方。 |
| `th up direct` | 作为 host 进程运行相同的阵容，前方没有任何 sandbox。 | CI runner、专用开发机、嵌套虚拟化 VM —— 已经是 *受 sandbox 保护* 的环境。 |
Docker 绝不是 sandbox 运行时。`docker` CLI 仍然被打包
*在* microVM *内部*，以便 agent 可以访问 host 上的 Docker / OrbStack /
Colima / Rancher / Podman daemon 来处理无嵌套虚拟化的工作负载，
但 Smooth 本身运行在 microsandbox 上或直接运行在 host 上 —— 仅此
而已。
参阅 [ADR-001](docs/Decisions/ADR-001-Consolidate-into-one-microVM.md)
了解整合理由，以及 [ADR-002](docs/Decisions/ADR-002-microsandbox-0.4.6-and-remove-docker-backend.md)
了解最近的 microsandbox 版本更新 + 移除 Docker 后端。
## 什么是 Smooth？
Smooth 是 [Smoo AI](https://smoo.ai) 的核心 CLI 和编排平台。它做两件事：
1. **Agent 编排** —— 派遣 Smooth operatives（受 sandbox 保护的 AI agents）在硬件隔离的 Microsandbox microVM 内处理真实项目，并配备对抗性监控和基于策略门控的访问控制。
2. **Smoo AI 平台 CLI** —— 管理配置 schema，与 Smoo AI API 交互，与 Jira 同步，并通过一个命令控制你的基础设施。
### Agent 循环的工作原理
在每个 operative VM 内部，**单个 agent** 通过 `smooth-operator` 的 agent 循环处理自己的内部迭代
（LLM → tool → LLM → …）。一个轻量级的外部
governor 通过三个任务来包装它：将上一次运行的测试输出反馈进去，
在失败的测试减少时对工作区进行快照，并在出现第一个令人信服的信号时停止。
```
%%{init: {'theme':'base','themeVariables':{
'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart LR
START["Task prompt"] --> TURN
TURN["Coding turn
agent runs tools"] --> GREEN{"Tests green?"}
GREEN -- yes --> DONE["Done"]
GREEN -- no --> SNAP["Snapshot
if failures dropped"]
SNAP --> STOP{"Stop signal?
close-to-green · budget · cap"}
STOP -- no --> TURN
STOP -- yes --> RESTORE["Restore best state"] --> DONE
classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
class TURN warm
class DONE teal
```
在 [`smooth-operator::coding_workflow`](crates/smooth-operator/src/coding_workflow.rs) 中实现。
早期版本将运行分解为七个阶段（ASSESS / PLAN /
EXECUTE / VERIFY / REVIEW / TEST / FINALIZE）。阶段流水线
总是在某个检测器处悄悄短路；单 agent
循环更小、更易于推理，并且符合
经过基准测试调优的编码 agent 的形态。我们保留了系统提示词中的自我验证要求、
最佳状态快照以及编译错误
短路 —— 并放弃了按阶段分发。
**停止条件** 是预算 + 停滞期，而不是固定的迭代上限：
- **Green** —— agent 报告所有测试通过。
- **Close-to-green** —— 前一回合达到了 ≤3 个失败测试；本
回合没有改善。继续迭代更有可能导致倒退。
- **Budget** —— 下一回合将突破 `--budget-usd` 上限。
- **Iteration cap** —— 安全上限（默认为 5），而不是主要制动器。
### 模型路由
每次 LLM 调用都通过一个 **语义路由 slot** 进行分发。网关
（通常是 `llm.smoo.ai`）将每个 slot 解析为具体的模型，因此
升级后端不会搅乱代码。
六个语义 slots（外加一个 `smooth-default` 线上兼容别名，网关
将其路由到 `smooth-coding`）：
| Slot | 使用方 | 形态 |
|---|---|---|
| `smooth-coding` | 编码循环（主力）—— 同时服务于遗留的 `smooth-default` 别名 | 强大的 tool 使用 + 多轮交互 |
| `smooth-reasoning` | `th code` Plan/Think 模式 —— 从旧的 `thinking` + `planning` slots 合并而来 | 扩展的思维链、任务分解 |
| `smooth-reviewing` | `th code` Review 模式、代码审查流程 | 对抗性批判 |
| `smooth-judge` | Narc 的 LLM-as-a-judge、基准测试评分 | 是/否判定，低延迟 |
| `smooth-summarize` | 长时间运行期间的上下文压缩 | 摘要总结 |
| `smooth-fast` | 会话自动命名、短标题、自动补全 | Haiku/Flash 级别，亚秒级 TTFT |
路由位于 [`smooth-operator::providers`](crates/smooth-operator/src/providers.rs)。
CLI 的 `th code` 预设通过模型选择器将 slots 重新映射到任意模型 ——
例如，在某次运行中将 Coding 指向 Kimi Code，将 Reasoning 指向
GLM 等等。
**实时状态。** TUI 在每个
编码回合流式传输 `AgentEvent::PhaseStart`，并在状态栏显示迭代次数 + 路由别名 + 已解析的 upstream +
花费：
```
CODING · smooth-coding → minimax-m2.7 | iter 3/5 | failed: 4 → 1 | spend: $0.012
```
所有状态通过 Smooth 内置的 pearl tracker（以 Dolt 为后端，
基于项目，可通过 git 同步）实现持久化。
## 架构
```
%%{init: {'theme':'base','themeVariables':{
'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart TB
TH["th binary
+ host credential broker"]
subgraph VM["The microVM · microsandbox"]
BS["Big Smooth
orchestrator · READ-ONLY"]
W["Wonk · access control"]
G["Goalie · net + fs proxy"]
N["Narc · surveillance"]
SC["Scribe → Archivist · logging"]
OPS["Smooth operatives
the workers"]
end
TH -->|spawns| VM
BS -->|orchestrates| OPS
OPS -->|HTTP_PROXY| G
G -->|"allowed?"| W
N -->|intercepts| OPS
OPS --> SC
classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
class OPS warm
class W teal
```
`th up direct` 作为 host 进程运行完全相同的阵容 —— 相同的 gRPC
socket，相同的监控，相同的 credential broker —— 只是前方没有
microsandbox 边界。同一张图，只是 microVM 盒子不在那里。
**网络传输。** 系列服务在启动时绑定四个基于 Unix-domain socket 的 tonic-gRPC 服务器
（位于 `$SMOOTH_SINGLE_PROCESS_SOCKET_DIR` 下的 `narc.sock`、`wonk.sock`、`scribe.sock`、
`bigsmooth.sock`）。每个
operative 子进程在每次 tool 检查、
策略决策和日志记录时都会拨号连接这些 socket —— 参见 `proto/{narc,wonk,scribe,bigsmooth}.proto`
和 `crates/smooth-bigsmooth/src/single_process.rs::bootstrap_from_app_state`。
在 Big Smooth 自己的进程内部，通过
`Arc
` 直接访问相同的服务（无需网络）。外部 TUI/web UI/bench harness
通过 HTTP+WebSocket 与端口 `:4400` 上的 Big Smooth 通信。完整拓扑结构位于
[`docs/Architecture/Transport.md`](docs/Architecture/Transport.md)。
### 阵容
Big Smooth、Archivist、Wonk、Goalie、Narc、Scribe 和 Groove 都位于
同一个 microVM（sandbox 模式）或同一个进程树（direct
模式）。Smooth operatives 是在该
边界内生成的子进程，每个分发的 pearl 对应一个。
| 服务 | 角色 |
|---|---|
| **Big Smooth** | Orchestrator。调度工作，生成策略，处理访问请求。**只读** —— 无法写入文件系统。 |
| **Archivist** | 中央日志 + trace 聚合器。接收来自每个 Scribe 的 events 和 OTLP traces。将 traces 存储在 SQLite 中，可选择转发到外部 OTel 后端（Jaeger、Tempo、Honeycomb）。可以写入，但只能写入日志路径。 |
| **Wonk** | 访问控制权威。读取策略 TOML，为每个网络请求、tool 调用、pearl 访问和 CLI 命令回答“这是否被允许？”。无 LLM。 |
| **Goalie** | 网络 + 文件系统代理。哑管道 —— 根据 Wonk 的回答进行转发或阻断。iptables + FUSE 在 VM 内部的内核级别强制执行。 |
| **Narc** | Tool 监控 + 提示词注入防护。两级检测：快速 regex 预过滤器 + 针对模糊情况的 LLM-as-a-judge。 |
| **Scribe** | 结构化日志服务。所有服务都通过 Scribe 记录日志，Scribe 写入内存中的 SQLite 并提供给 Archivist。 |
| **Groove** | LLM 检查点 + 会话恢复。在 tool 调用后捕获对话状态，以便被中断的 operative 能从上一个检查点继续。 |
**The Board** = Big Smooth + Archivist（领导层）。**The Safehouse**
是 microVM（或者在 direct 模式下，host 进程树），The
Board 在那里与其余阵容一起运作。
**Smooth operatives** = AI agents（受 sandbox 保护的 workers）。唯一写代码的角色。（它们运行 `smooth-operator` 引擎；不要将 worker 与引擎混淆。）
### 每个 MicroVM 内部
```
%%{init: {'theme':'base','themeVariables':{
'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart LR
subgraph VM["MicroVM · --scope none"]
Operator["Operative / Big Smooth"]
Wonk["Wonk · :8400"]
Goalie["Goalie · :8480"]
Narc["Narc"]
Scribe["Scribe · :8401"]
end
Operator -->|HTTP_PROXY| Goalie
Goalie -->|"allowed?"| Wonk
Narc -->|"intercepts · checks tool"| Operator
Operator --> Scribe
Wonk --> Scribe
Goalie --> Scribe
Narc --> Scribe
classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
class Operator warm
class Scribe teal
```
- **Wonk** 读取 `/etc/smooth/policy.toml`，监听 `127.0.0.1:8400`，并在文件更改时热重载
- **Goalie** 监听 `127.0.0.1:8480` 作为 HTTP 代理。iptables 拒绝除 Goalie UID 之外的所有出站 TCP。`/workspace` 处的 FUSE 挂载用于文件系统访问控制。
- **Narc** 拦截 tool 调用和传入的 prompts。Regex 快速路径能捕捉明显的秘密和写入违规。模糊情况会交给一个小巧/快速的 LLM（Haiku、Flash、GPT-4o-mini）进行是/否判定。
- **Scribe** 监听 `127.0.0.1:8401`，写入 pod 内的 SQLite 和 JSON-lines，并将 events 提供给 Archivist。通过 `tracing-opentelemetry` 将 `tracing` span 桥接到 OpenTelemetry，为 operative 生命周期、prompts、tool 调用和网络请求生成 trace 层次结构。使用跨 VM 边界的 W3C traceparent 传播将 OTLP traces 导出到 Archivist。
### 安全模型
```
%%{init: {'theme':'base','themeVariables':{
'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart TD
subgraph Enforcement["Kernel-level enforcement"]
IPT["iptables · only Goalie UID egress"]
FUSE["FUSE mount · all file I/O via Goalie"]
end
subgraph Policy["Policy-driven access control"]
TOML["policy.toml
generated per operative"]
NET["Network allowlist"]
FS["Filesystem deny
*.env · *.pem · .ssh/*"]
REST["Tools · pearls · MCP allowlists"]
end
subgraph Detection["Narc · two-tier detection"]
REGEX["Regex fast path"]
LLM["LLM judge · ambiguous cases"]
end
TOML --> NET & FS & REST
IPT --> NET
FUSE --> FS
classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
class TOML warm
class LLM teal
```
**关键不变量：**
- Big Smooth **从不写入**。Narc 在 VM 内部强制执行此操作 —— 任何写入尝试都会被立即阻断。
- Archivist **可以写入**，但只能写入日志路径。对任何其他路径的写入都会被阻断。
- Operatives 只能看到分配给它们的 pearls 和依赖项（由 auth token 限定范围）。
- 所有出站流量都经过 Goalie。没有进程可以绕过代理 —— 在内核级别强制执行。
### 持续访问协商
Operatives 可以在运行时请求扩展访问权限。流程如下：
```
%%{init: {'theme':'base','themeVariables':{
'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
'lineColor':'#7c8aa0','actorBkg':'#0b1426','actorBorder':'#2b3a52','actorTextColor':'#e6edf6',
'signalColor':'#7c8aa0','signalTextColor':'#e6edf6','noteBkgColor':'#f49f0a','noteTextColor':'#1a0f00','noteBorderColor':'#ff6b6c',
'fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
sequenceDiagram
participant Op as Operative
participant G as Goalie
participant W as Wonk
participant BS as Big Smooth
Op->>G: GET api.stripe.com/v1/charges
G->>W: is this allowed?
W-->>G: BLOCKED (not in allowlist)
G-->>Op: 403 Blocked
G->>W: request access
W->>BS: POST /api/access/request
BS->>BS: auto-approve? check pearl labels?
alt auto-approved
BS-->>W: approved + updated policy
W-->>W: hot-reload policy
Note over Op,G: retry succeeds
else needs human
BS->>BS: send to inbox
Note over BS: th access approve <pearl> <domain>
end
```
### 默认访问信封
每个 operative VM 启动时都带有一个最小的信封：
- **网络**：配置的 LLM 网关（默认为 `llm.smoo.ai`），
相关的包注册中心（crates.io、npm、PyPI）和 GitHub。任何
其他域名都需要明确批准 —— 参见上面的持续访问协商。
- **文件系统**：对 `/workspace`（用户 repo 的 bind-mount）有读写权限。
其他一切都是只读或被拒绝的。`.env`、`*.pem`、
`.ssh/*` 和其他类似秘密的路径始终被拒绝。
- **Pearls**：分配的 pearl + 其深度为 2 的依赖闭包。
任务无法访问该闭包之外的 pearls。
- **Tools**：已注册的 tool 白名单（文件读/写、通过
Goalie 的 bash、已批准的 MCP tools、CLI-wrapper 插件）。每次
调用都会通过 Narc 的 regex 预过滤器 + 模糊情况 LLM 判定。
## `th` CLI
### 核心
```
th up # Start everything
th down # Stop
th status # System health
th code # Interactive coding assistant (ratatui)
```
### 认证
Smooth 可以与任何兼容 OpenAI 的端点通信。推荐的默认选项
是 **[llmoo.ai](https://llm.smoo.ai)** —— 我们基于 LiteLLM 的网关
，它将每个 `smooth-*` 路由 slot 映射到经过生产调优的 upstream
（Claude、GPT、Gemini、Kimi、MiniMax、GLM、Qwen 等），并配备 Stripe
计量的账单、组织/团队密钥和管理仪表板。一把密钥，所有
模型，无需按 provider 进行管道铺设。
```
# Smoo AI 的 gateway（推荐 — 每个 slot 通过一个密钥解析）
th model login smooai-gateway
# 或者自带 upstream — 任何 OpenAI 兼容的 provider：
th model login kimi-code # Moonshot Kimi Code (coding workhorse)
th model login kimi # Moonshot Kimi chat endpoint
th model login openrouter # OpenRouter (aggregator over many providers)
th model login openai # OpenAI direct
th model login anthropic # Anthropic direct
th model login google # Google (Gemini)
th model login ollama # Local Ollama models
th model status # Show all provider status
th model providers # List configured providers
th model default # Which provider backs smooth-default
```
Provider 和 slot 是独立的：你可以通过 `th code` 的模型选择器或通过编辑 `~/.smooth/providers.json` 将每个路由 slot
（`smooth-coding`、`smooth-thinking`、…）固定到不同的 provider/model。
### 工作
```
th run # Trigger work on a pearl
th operatives # List active Smooth operatives
th pause/resume/steer/cancel # Control operatives mid-task
th approve # Approve a review
th inbox # Messages needing attention
```
### 访问控制
```
th access pending # List pending access requests
th access approve # Approve domain access
th access deny # Deny domain access
th access policy # Show current policy
```
### Tools 和插件
```
# MCP servers（Playwright、GitHub、filesystem 等）
th mcp add playwright npx @playwright/mcp@latest
th mcp add --project repo-fs npx @modelcontextprotocol/server-filesystem /workspace
th mcp list # Global + project scopes
th mcp defaults # Show shipped defaults (budget-aware-mcp, …)
th mcp install # Register all shipped defaults (idempotent)
th mcp install budget-aware-mcp # Register a single shipped default
th mcp test playwright # Health check
th mcp remove playwright
# CLI-wrapper 插件 — 将 shell 命令暴露为 agent tools
th plugin init jq --command 'jq {{filter}} <<< {{json}}'
th plugin init --project deploy --command 'scripts/deploy.sh {{env}}'
th plugin list
th plugin remove deploy --project
```
全局配置位于 `~/.smooth/`；项目配置位于
`/.smooth/`。发生名称冲突时，项目条目会覆盖全局条目。
完整指南请参阅 [`docs/extending.md`](docs/extending.md)。
### 在 sandbox 中运行 pearl (`th run`)
将一个 pearl（或临时 prompt）派发给运行在
microVM 中的 Smooth operative。该 agent 对你的工作区有 bind-mount 访问权限，
在 `/opt/smooth/cache` 处有项目范围的缓存，并且（使用 `--keep-alive` 时）
有转发的端口，以便你可以实时查看 dev server。
```
# 首个就绪的 pearl，默认 image
th run --keep-alive
# 显式 pearl，显式 memory
th run th-abcdef --keep-alive --memory-mb 6144
# 针对当前目录的 ad-hoc prompt
th run "add a /health route that returns {\"ok\":true}" --keep-alive
# 检查并销毁
th operatives list
th operatives kill
```
**每个技术栈一个镜像。** `smooai/smooth-operative` 附带了
内置的 alpine + `mise`。该 agent 读取工作区
（`package.json`、`Cargo.toml`、`pyproject.toml`、`go.mod`）并
在运行时安装它需要的任何 toolchain —— node + pnpm、
python + uv、rust、go、bun、deno，或 mise 支持的约 140 种工具中的任何一种。
安装会存放在 `/opt/smooth/cache/mise` 中，绑定到
host 项目缓存，因此第二次运行的启动具有离线般的快速。
本地构建：
```
scripts/build-smooth-operative-image.sh
```
如果你想要一个自定义变体（例如为了 CI 的可重复性而固定版本），可以通过 `--image` 或 `SMOOTH_OPERATIVE_IMAGE` 环境变量进行覆盖。
**Microsandbox 镜像解析。** 本地构建的镜像位于
你的 Docker Desktop 镜像存储中；默认情况下，`microsandbox` 从注册中心
拉取，因此如果它的拉取操作看不到你的本地构建，请先
推送它（`docker push smooai/smooth-operative:0.2.0`），或者将
`SMOOTH_OPERATIVE_IMAGE` 设置为 microsandbox 可以访问的地址。
**项目缓存。** 每个工作区路径都会哈希到它自己的缓存，
挂载在 VM 内部的 `/opt/smooth/cache`。在同一 repo 上的后续运行共享 mise 安装 + 语言存储（pnpm-store、cargo
registry、uv cache 等）。默认情况下由一流的 microsandbox
Volume 支持（`~/.microsandbox/volumes/smooth-cache-/`）；
设置 `SMOOTH_USE_VOLUMES=0` 以回退到遗留的 bind-mount
（`~/.smooth/project-cache//`）。通过以下方式管理：
```
th cache list # shows entries from both backends, tagged
th cache prune --older-than 30 # evict caches idle > N days
th cache clear /path/to/project # remove entry for a specific workspace
```
### 后台服务
通过原生服务管理器使 `th up` 在重启后保持运行
（用户级；无需 sudo，无需系统 daemon）。
```
th service install # LaunchAgent (macOS) / systemd --user (Linux) / logon task (Windows)
th service start / stop / restart
th service status
th service logs -f # Tail ~/.smooth/service.log
th service uninstall
th service install --system # Print the system-level artifact + install instructions
```
### 系统
```
th db status # Database info
th db backup # Backup SQLite
th audit tail leader # View audit logs
th tailscale status # Tailscale info
th worktree create/list/merge # Git worktrees
```
## 扩展 Smooth
两个扩展点可以添加 tools 而无需重新构建二进制文件：
- **MCP servers** —— 生成 [Model Context
Protocol](https://modelcontextprotocol.io) server，例如 Playwright
MCP 或 GitHub MCP；它们的 tools 作为
`.` 进入 agent 的注册中心。Smooth 开箱即用附带一个默认配置：
[`budget-aware-mcp`](https://github.com/Doorman11991/budget-aware-mcp)
—— 基于 token 预算的代码图查询（`graph_walk`、`search_graph`、
`check_scope`、`explain_symbol`、`find_dead_code`、…），以便
operative 可以只提取结构相关的代码，而不是采用 ripgrep 读取文件转储整个文件的方式。在首次
`th up` 时注册；使用 `SMOOTH_SKIP_DEFAULT_MCP=1` 退出或通过
`th mcp remove budget-aware-mcp` 移除。
- **CLI-wrapper 插件** —— 在
`.smooth/plugins//plugin.toml` 放置一个 TOML manifest，runner 会将其注册为
`plugin.`，将 `{{placeholder}}` 参数渲染为 shell
命令模板。
两者都可以进行全局配置（`~/.smooth/`）和按项目
配置（`/.smooth/`）。项目条目会覆盖全局条目。在
加载这些内容时**没有信任门控** —— 这与 `npm install`、
`.zshrc` 或克隆任何 repo 并运行 `pnpm dev` 一致。纵深防御
发生在 *调用时*：Narc 的 CliGuard / 注入 / 秘密
检测器为每次 tool 调用设置门控，Wonk 策略为每个
网络 + 文件系统访问设置门控，并且整个 agent 循环运行在
硬件隔离的 microVM 内。参阅 [`docs/extending.md`](docs/extending.md)
和 [`SECURITY.md`](SECURITY.md)。
## 技术栈
| | |
|---|---|
| **语言** | Rust 2021 edition |
| **HTTP** | axum + tower |
| **数据库** | rusqlite (bundled SQLite) |
| **TUI** | ratatui + crossterm |
| **Web** | React 19 + Vite + Tailwind CSS 4 (embedded) |
| **Markdown** | pulldown-cmark (TUI), react-markdown (web) |
| **Sandboxes** | Microsandbox (hardware-isolated microVMs) |
| **Agent 框架** | smooth-operator (Rust-native, built-in checkpointing) |
| **LLM** | 默认通过 `llm.smoo.ai` 网关兼容 OpenAI (Kimi, MiniMax, GLM, Qwen, Anthropic, OpenAI, Google) |
| **工作追踪** | Pearls (Dolt-backed, git-syncable) |
| **策略** | 基于 TOML，可通过 notify + ArcSwap 热重载 |
| **日志记录** | smooai-logger (structured, context-aware) |
| **链路追踪** | OpenTelemetry (tracing-opentelemetry bridge, OTLP export) |
| **Linting** | clippy (pedantic + nursery) |
| **格式化** | rustfmt (160 max width) |
## Workspace
```
smooth/
├── crates/
│ ├── smooth-cli/ # Binary — clap CLI, the `th` entry point
│ ├── smooth-bigsmooth/ # Library — orchestrator, policy gen, session mgmt
│ ├── smooth-bootstrap-bill/ # Library + binary — host-side microsandbox broker ("Bill")
│ ├── smooth-operator/ # Library — Rust-native AI agent framework
│ ├── smooth-operative/ # Binary — agent loop inside each operative VM
│ ├── smooth-policy/ # Library — shared policy types, TOML parsing
│ ├── smooth-wonk/ # Binary — in-VM access control authority
│ ├── smooth-goalie/ # Binary — in-VM network + filesystem proxy
│ ├── smooth-narc/ # Library — tool surveillance + secret detection
│ ├── smooth-scribe/ # Library — per-VM structured logging
│ ├── smooth-archivist/ # Library — central log aggregator
│ ├── smooth-pearls/ # Library — Dolt-backed pearl tracker
│ ├── smooth-plugin/ # Library — CLI-wrapper plugin manifests
│ ├── smooth-diver/ # Library — deep research / exploratory agent
│ ├── smooth-tunnel/ # Library — th.smoo.ai reverse-tunnel client
│ ├── smooth-bench/ # Binary — coding-benchmark harness (aider-polyglot, SWE-bench, …)
│ ├── smooth-code/ # Library — ratatui terminal dashboard
│ └── smooth-web/ # Library — embedded Vite SPA
│ └── web/ # React + Vite source
├── Cargo.toml # Workspace root
├── rustfmt.toml # Format config
└── install.sh # Curl installer
```
## 开发
```
# 构建
cargo build
# 测试（涵盖所有 crates 的完整 suite）
cargo test
# 格式化
cargo fmt
# Lint
cargo clippy
# 运行 dev（带自动重载）
cargo watch -x 'run -p smooth-cli -- up'
# Release build（~10MB）
cargo build --release -p smooth-cli
ls -lh target/release/th
```
## 🧩 Smoo AI 的一部分 {#part-of-smoo-ai}
Smooth 由 **[Smoo AI](https://smoo.ai)** 构建并开源 —— 这是一个由 AI 驱动的业务平台，在每个产品中都内置了 AI：CRM、客户支持、营销活动、现场服务、可观测性和开发者工具。
- 🚀 **平台上的 Smooth** — [smoo.ai/th](https://smoo.ai/th)
- 🧰 **更多来自 Smoo AI 的开源项目** — [smoo.ai/open-source](https://smoo.ai/open-source)
- 🧩 **兄弟包** — [smooth-operator](https://github.com/SmooAI/smooth-operator)（Smooth 运行的 agent 引擎），[@smooai/deploy](https://github.com/SmooAI/deploy)，[@smooai/logger](https://github.com/SmooAI/logger)，[@smooai/config](https://github.com/SmooAI/config)
## 🤝 贡献
欢迎提交 Issues 和 PR。所有功能开发都在 git worktree（`th worktree create`）中进行 —— 有关构建、测试和工作流约定，请参阅 [CLAUDE.md](CLAUDE.md)；有关安全模型，请参阅 [SECURITY.md](SECURITY.md)。
## 📄 许可证
MIT © [Smoo AI](https://smoo.ai)。请参阅 [LICENSE](LICENSE)。
由 Smoo AI 构建 —— AI 内置于每一个产品中。