内容
# 伞状工具
[](https://jahala.github.io/umbel/)
[](LICENSE)
[](https://github.com/jahala/umbel/actions)
🌱 **[什么是伞状工具？ →](https://jahala.github.io/umbel/)** · 视觉概览
**在代理会话中启动其他提供商的代理工作程序。** 在 CLI、MCP 服务器或 YAML 工作流中以交互方式驱动 `claude`、`codex`、`gemini` 或 `opencode`。一个二进制文件，一个提供商抽象 — 对 `claude`/`codex`/`gemini` 订阅计费，`opencode` 任意模型。
## 克劳德代码编排 Codex（和 Gemini，平行）
您的 `claude` 会话无法直接启动 `codex` 会话。配置 `umbel mcp` 后，它可以：
```jsonc
// .mcp.json
{ "mcpServers": { "umbel": { "command": "umbel", "args": ["mcp"] } } }
```
您的克劳德代码代理现在拥有 `umbel_spawn`、`umbel_send`、`umbel_wait`、`umbel_read`、`umbel_kill` 和 `umbel_help` 等工具。告诉它：
> 在 `./worktrees/a` 中启动一个 Codex 审查器，在 `./worktrees/b` 中启动一个 Gemini 测试器。让它们并行工作，然后综合他们的发现。
它将建立两个工作程序，调度提示，等待完成，并读取他们的输出。三个订阅，三个角色，一个编排。主机的上下文保持干净 — 它花费代币在规划和综合上，而不是在做工作本身。
服务器提供一个服务器级别的 `instructions` 块和一个按需的 `umbel_help` 工具（主题：`lifecycle`、`workflow`、`providers`），因此您的代理学习何时调用 umbel 以及如何使用它，而不会被淹没在前置上下文中。
## 监督模式（CLI）
从您的 shell 中使用相同的动词 — 在脚本、cron 或驱动 umbel 时无需 MCP 主机：
```bash
umbel spawn --name reviewer --provider claude --cwd ./worktrees/review --model sonnet
umbel spawn --name fixer --provider codex --cwd ./worktrees/fix --model o4-mini
umbel send reviewer "review the diff and write findings to review.md"
umbel wait reviewer
umbel read reviewer
```
单个监督者可以在提供商之间并发驱动工作程序。提供商记录在每个会话的 `meta.json` 中，因此 `send`/`wait`/`read`/`kill` 自动路由 — 无需 `--provider`。
完整动词列表：`spawn`、`send`、`wait`、`status`、`ls`、`kill`、`attach`、`read`、`capture`、`logs`、`run`、`mcp`。
## 工作流模式
声明式多步骤管道，混合提供商每个步骤：
```yaml
workers:
reviewer:
provider: claude
model: sonnet
cwd: ./worktrees/review
fixer:
provider: codex
model: o4-mini
cwd: ./worktrees/fix
steps:
- run: reviewer
prompt: "Review PR #{{ env.PR }}. Write findings to review.md."
wait: { stop: $session, timeout: 10m }
outputs:
review: file:./worktrees/review/review.md
- run: fixer
needs: [reviewer]
prompt: "Apply these fixes:\n{{ steps.reviewer.outputs.review }}"
wait:
all:
- { stop: $session }
- { file: ./worktrees/fix/tests-passed }
```
```bash
umbel run review-then-fix.yaml
```
步骤在 `needs` 允许的情况下并行运行。模板设计故意简单：`{{ env.X }}`、`{{ steps.NAME.outputs.X }}`、`{{ $session }}`。
## `umbel -p` — `claude -p` / `codex -p` / `gemini -p` 的替代品
与供应商 `-p` 模式相同的标志，提供商作为参数：
```bash
umbel -p "summarise $FILE" --provider claude --model sonnet --allowedTools Read
umbel -p "summarise $FILE" --provider codex --model o4-mini
umbel -p "summarise $FILE" --provider gemini --model gemini-2.5-pro
umbel -p "summarise $FILE" --provider opencode --model opencode/big-pickle # 免费，无需密钥
umbel -p "summarise $FILE" --provider opencode --model ollama/qwen2.5-coder # 本地
```
`--provider` 默认值为 `claude`（因此 `umbel -p` 镜像 `claude -p`）。首次调用冷启动约 3–5 秒；使用 `--name` / `--resume` 保持会话热度：
```bash
umbel -p --name analyst --provider claude "first question"
umbel -p --resume analyst "follow-up" # 重用热会话，相同提供商
```
## 安装
```bash
bun install && bun run build
```
Homebrew 软件仓库即将推出。目前，请从源代码构建。
## 需求
- `tmux` >= 3.0
- macOS 或 Linux
- 至少安装一个提供商 CLI：
- `claude`（Claude Pro / Max — 订阅计费）
- `codex`（ChatGPT Plus / Pro / Team / Enterprise — 订阅计费）
- `gemini`（Google AI Pro / Ultra — 订阅计费）
- `opencode`（无需订阅 — 本地通过 `ollama/…`，免费层通过 `opencode/big-pickle`，或通过 `anthropic/…` / `openrouter/…` 使用您自己的密钥进行 API 计费）
如果没有安装提供商的二进制文件，则无法选择该提供商。`umbel spawn --provider gemini` 在 tmux 无法执行 `gemini` 时会大声失败。
## 架构
无守护进程。`tmux` 是守护进程；`~/.umbel/` 是状态存储。每个 `umbel` 调用都是短暂的。完成检测使用每个提供商的原生生命周期事件（Claude `Stop`，Codex `Stop`，Gemini `AfterAgent`，OpenCode `session.status` 空闲）— 而不是终端刮擦。代理输出从每个提供商的转录中读取（`claude`/`codex`/`gemini` 的 JSONL；`opencode` 的 `opencode export` JSON）— 永远不会从 `capture-pane` 读取。提供商通过小型接口 (`src/core/providers/types.ts`) 可插件 — 添加新的 CLI 是约 150 LOC 实现，而不是重写。请参阅 [`docs/architecture-v3.md`](docs/architecture-v3.md) 以获取完整设计。
**是什么，它的发展方向：** umbel 是 *一个单元的工作* 的可靠、中立执行边界 — 工作程序由编排者（代理、工作流或人类）命令并读取结构化结果。论文、合同和信任层路线图（类型化 + 验证结果）位于 [`docs/positioning.md`](docs/positioning.md)。
## 为什么存在
Anthropic、OpenAI 和 Google 都将其 `-p` / `--print` 模式按 API 费率定价，同时将交互式 TUI 留在订阅中。`umbel` 为您提供了一个编程接口，适用于您正在支付的任意供应商的交互式二进制文件 — 因此您通常在 TUI 中手动完成的工作针对您已经支付的订阅运行，而不是额外的按令牌计费的 API。
OpenCode 没有订阅。它添加了一个不同的通道：**本地**（您的硬件，免费，`ollama/…`），**免费层**（OpenCode Zen，无密钥，限制），或 **API 计费**（您的 `anthropic/…`，`openrouter/…` 密钥）。OpenCode 使 umbel 成为 **统一的编排层，适用于任何代理 CLI** — 非常适合在没有成本权衡的情况下运行免费的本地工作程序以及您的订阅 `claude`/`codex`/`gemini`。
`claude` 提供商也可以指向任何与 Anthropic 兼容的端点 — DeepSeek、OpenRouter、本地代理 — 通过 `--env` (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_MODEL`）：Claude Code 的工具包，不同模型，按令牌计费。请参阅 [自定义模型端点](docs/cli-reference.md#custom-model-endpoints-claude-provider)。
旨在为单独的开发者自动化自己的工作。 不适用于商业转售或大规模逃避。 有关所有三个供应商的防御性光谱，请参见 [`docs/tos.md`](docs/tos.md)。
## 姊妹项目
[**walkie-clawkie**](https://github.com/jahala/walkie-clawkie) — 在代理会话运行期间的 push-to-talk 消息传递。 互补，不重叠：umbel 调度和等待；walkie-clawkie 让会话在回合中相互交谈。
## 贡献
欢迎 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。测试首先 — 每个修复和功能都从一个失败的测试开始。
## 支持
[](https://buymeacoffee.com/jahala)
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
