# agent-hub

**让一个"主导智能体"通过 MCP 调度其他模型和智能体协同干活。**

主导者可以是 Claude Code，也可以是 Codex，或任何支持 MCP 的客户端。agent-hub 把 DeepSeek、智谱 GLM 这类大模型，以及 Codex、Claude Code 这类命令行智能体统一包装成 MCP 工具。你想让谁来主导，就在谁那里接上 agent-hub，其他人就成了它可以调度的帮手。

```
        主导者（随时可换）
   Claude Code    Codex    其他 MCP 客户端
        └────────────┼────────────┘
                     ▼
          agent-hub（MCP 服务，stdio）
       ┌─────────────┴──────────────┐
  模型类：直接调用接口           命令行类：后台子进程
  DeepSeek / 智谱 GLM …         Codex / Claude Code …
```

[English summary](#english)

## 为什么做这个

直接用 shell 调用其他智能体，会踩到这些坑：

- 在 Windows 上，`claude` 等命令是 `.cmd` 包装器，**带换行的提示词会被截断**，表现为莫名其妙的"模型不存在"报错
- 报错被掩盖，主导者看不出真实原因，于是盲目重试，白白消耗额度
- 每调用一次就启动一个完整的智能体，**固定开销往往高达数万 token**
- 看不到进度，长任务也没办法取消

agent-hub 的应对方式：

- 提示词一律通过 stdin 传入
- 报错原样返回，并且绝不自动重试
- 纯文本任务直接调用模型接口，没有额外开销
- 长任务在后台异步运行，可以查询进度、读取结果、随时取消

## 提供的 MCP 工具

| 工具 | 作用 |
|---|---|
| `list_workers` | 列出可调度的模型和智能体 |
| `ask_model` | 让大模型同步完成一次文本任务，比如写稿、翻译、审稿 |
| `start_task` | 把任务派给命令行智能体在后台执行，立即返回任务编号 |
| `task_status` | 查看任务状态和已用时间 |
| `task_result` | 读取智能体的最终回复，没有回复时返回日志末尾 |
| `cancel_task` | 取消任务，连同它启动的所有子进程一起结束 |

## 安装

需要 Python 3.11 及以上版本，以及 [uv](https://docs.astral.sh/uv/)。

```bash
git clone https://github.com/LJUN0308/agent-hub.git
cd agent-hub
uv sync
```

## 配置

把 [config.example.toml](config.example.toml) 复制到 `~/.agent-hub/config.toml`，然后按需修改：

- `allowed_roots`：`start_task` 的工作目录必须位于这些目录之下
- `[workers.xxx]`：每个工人一节，`kind = "model"` 表示大模型，`kind = "cli"` 表示命令行智能体
- `command`：命令行智能体的启动参数，可以使用 `{workdir}` 和 `{output_file}` 两个占位符。提示词总是通过 stdin 传入，所以命令里要包含让对方从 stdin 读取的参数，比如 Codex 的 `-`
- `command_glob`：可选。如果可执行文件的路径会变，比如 Codex 桌面版带哈希的目录，可以用通配符匹配，自动选最新的那个；匹配不到时回退到 PATH 查找。`%VAR%` 和 `~` 会被展开

**API Key 不要写进配置文件。** 支持两种方式：
- `api_key_env`：从环境变量读取
- `api_key_ccswitch`：从 [cc-switch](https://github.com/farion1231/cc-switch) 的数据库中，**只读**取出同名供应商的 Key

## 接入主导智能体

```bash
# Claude Code
claude mcp add agent-hub -- uv --directory /path/to/agent-hub run agent-hub

# Codex
codex mcp add agent-hub -- uv --directory /path/to/agent-hub run agent-hub
```

接入以后，直接用自然语言让主导者分派任务就行，比如："用 DeepSeek 写第一章初稿，同时让 Codex 画 6 张插图"。

调用记录保存在 `~/.agent-hub/usage.jsonl`，每个后台任务的日志保存在 `~/.agent-hub/jobs/`。

## 安全说明

- **`allowed_roots` 只约束工作目录，它不是沙箱。** 智能体实际能访问什么，取决于它自己的权限设置，比如 Codex 的 `-s workspace-write`。请在 `command` 里按最小权限原则配置
- 命令行智能体会**继承 agent-hub 进程的环境变量**。如果你通过 `api_key_env` 提供了 Key，被调度的智能体也能读取到
- 模型的 API Key 不写入日志和用量记录。接口报错信息里如果回显了 Key，会先替换成 `***` 再返回
- 在 Windows 上，如果命令行智能体是 `.cmd`/`.bat` 包装器，含有 `&|<>^%!"` 的参数会被拒绝，以防 cmd.exe 把它们当成命令语法解析
- 后台任务只保存在内存里，**不跨重启保留**。agent-hub 退出时会结束所有仍在运行的任务，避免它们在无人管理的情况下继续消耗额度

## 路线图

- [x] 第一阶段：模型调用、后台任务、stdin 传参、失败即停
- [ ] 预算限额：为每个工人设置单次和每日的 token 上限
- [ ] 并发上限、任务记录清理，以及子进程的环境变量白名单
- [ ] MCP 类工人：转接其他 MCP 服务，比如 WorkBuddy 本地的连接器代理，用来接入企业微信等国内生态
- [ ] 任务看板：在网页上实时查看所有任务
- [ ] 更多模型预设：智谱、Kimi、通义等

## 开发

```bash
uv run pytest --cov=agent_hub
uv run ruff check .
```

## English

agent-hub is a small MCP server that lets a *lead* agent (Claude Code, Codex, or any MCP client) delegate work to other LLMs (any OpenAI-compatible API such as DeepSeek or GLM) and CLI agents (Codex, Claude Code). Text tasks go straight to the model API, so there is no agent start-up overhead. CLI tasks run in the background and expose status, result and cancel tools. Prompts are always passed via stdin, which avoids Windows `.cmd` argument truncation. Errors come back verbatim and are never retried automatically. Configure workers in `~/.agent-hub/config.toml` (see `config.example.toml`).

## License

[MIT](LICENSE)