内容
# 开放路由器子代理
一个MCP服务器**和命令行界面**，它提供了一个与模型无关的“子代理”工具，由 **[开放路由器](https://openrouter.ai)** 支持 — 只需一个API密钥，即可使用所有模型。它默认使用 **开放路由器融合** (`openrouter/fusion`)，该模型并行运行一个模型面板，并由一个裁判模型将它们综合成一个答案。 与 [`gpt-subagents-api`](https://github.com/Wally-Ahmed/gpt-subagents-api) （OpenAI API密钥）和 [`gpt-subagents-subscription`](https://github.com/Wally-Ahmed/gpt-subagents-subscription) （ChatGPT订阅）是 sibling 项目，它们都提供了相同的 **编排模式** 系统。
> **注意：** 使用 **开放路由器API密钥** (`Authorization: Bearer …`) 对兼容OpenAI的聊天完成端点。 与开放路由器无关联或背书。
---
## 工具
| 工具 | 功能 |
|------|--------------|
| `ask_openrouter` | 调用任何开放路由器模型。 **`model` 默认值为 `openrouter/fusion`** （多模型综合）；传递任何开放路由器ID以覆盖（例如 `anthropic/claude-opus-latest`、`openai/gpt-latest` 或快速廉价模型）。每次调用都需编写 `instructions` （系统提示）。推理能力完全可控（见下文）。仅适用于Fusion - `analysis_models` （面板，1-8个ID）和 `judge_model` （综合器）。 |
| `list_patterns` / `get_pattern` | 用于驱动模型的编排模式（见下文）。 |
**融合成本：** Fusion调用计费 **每个面板模型加上裁判模型**。 当多个视角值得投入时使用（研究、批评、出错成本高）；对于快速战术提示，传递单个模型ID。
### 推理和采样控制
任何模型的推理级别都可以设置 - 服务器公开开放路由器的完整统一 `reasoning` 对象，开放路由器将其转换为目标模型原生支持的内容（OpenAI/Grok努力级别、Anthropic思考预算、Gemini `thinkingLevel`、Qwen思考预算、DeepSeek/GLM模型的开启/关闭标志）。不支持的级别映射到模型提供的最近级别。
| 参数 | 含义 |
|-------|---------|
| `reasoning_effort` | 命名级别，最低到最高：`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。 (`none` 禁用推理。 在Anthropic上，这些变为预算比率 ≈ 0.1/0.2/0.5/0.8/0.95 of `max_tokens`，限制在 [1024, 128000]； 在Gemini上，它们映射到 `thinkingLevel`。) |
| `reasoning_max_tokens` | 精确的推理代币预算（Anthropic/Gemini/Qwen风格）用于精细控制。 **与 `reasoning_effort` 互斥**。 |
| `reasoning_enabled` | 在不选择级别或预算的情况下开启/关闭默认强度的推理。 |
| `reasoning_exclude` | 模型仍然推理，但推理代币不返回在响应中。 |
| `temperature` | 采样温度，0-2（越低越确定）。 适用于支持它的模型；开放路由器为不支持的模型删除它。 |
> **代理注意（MCP或CLI）：** 如果调用失败或发生任何错误 - 超时、速率限制、模型拒绝、提供商停机 - **首先重试相同的调用** （短暂等待瞬时错误）。 如果它仍然失败，请报告错误并 **询问**； 不要 **降级** 或在用户未直接同意的情况下更改用户设置的配置（模型、推理级别/预算、温度、融合面板/裁判）。 此规则也内置到服务器的MCP `instructions` 和CLI `--help` 中。
---
## 命令行界面
MCP服务器提供的所有功能都可以通过简单的shell命令获得 - 相同的客户端，相同的模式库，但答案以 **stdout上的原始文本** 返回，没有JSON-RPC框架。 对于可以运行shell命令的代理，这是一种经济高效的方式来委托： 两个方向都没有MCP信封，大输入（差异、日志、文件）永远不必通过模型的上下文回声。
```bash
npm run build # 编译 dist/cli.js
npm link # 可选：将 `openrouter-subagents` 放入您的PATH
# 调用（子命令是可选的）；stdout上的原始答案
openrouter-subagents "为什么天空是蓝色的？"
openrouter-subagents ask -m anthropic/claude-haiku-4.5 -e xhigh "证明sqrt(2)是无理数"
# 管道输入成为提示 - 或当给出提示时的上下文
git diff | openrouter-subagents ask -p "检查此差异是否有错误" -e high
openrouter-subagents ask -p "总结" --context-file big-report.md -m openai/gpt-5-mini
# 模式
openrouter-subagents patterns
openrouter-subagents pattern two-layer-cross-model-expert
```
标志镜像MCP工具： `-m/--model`、 `-i/--instructions` （默认为简洁的通用提示）、 `-p/--prompt`、 `-c/--context` （每个都有 `--*-file` 变体）、 `-e/--effort` （`none`...`max`）、 `--reasoning-tokens <n>`、 `--reasoning on|off`、 `--hide-reasoning`、 `-t/--temperature` 和Fusion的 `--analysis-models` / `--judge`。 `--help` 显示完整参考。 退出代码： `0` 成功， `2` 使用错误， `1` API/网络错误。
---
## 编排模式
模式是可重用的剧本（Markdown格式，位于 [`patterns/`](./patterns)），描述了 **如何** 驱动专家工具 - 分割工作、捆绑上下文、调用专家、 **验证其输出是否符合基本事实** ，并聚合。 它们通过 `list_patterns` （目录）和 `get_pattern("<name>")` （全文）公开，在调用时从磁盘读取 **（无需重建即可添加）** ，服务器的 `instructions` 提示代理在非琐碎的专家工作中查阅它们。
| 名称 | 功能 |
|------|--------------|
| [`two-layer-cross-model-expert`](./patterns/two-layer-cross-model-expert.md) | 将开放路由器专家包装在验证Claude子代理中，以便编排器仅看到并行、上下文便宜、基本事实检查的结论。 （融合使“跨模型”前提更加有力 - 专家是整个模型家族的面板。） |
| [`worker-orchestrator`](./patterns/worker-orchestrator.md) | 通过廉价的Sonnet包装器子代理将具体工作分发到开放路由器工作器（使用快速模型） - 通过执行验证，而不是验证门。 |
两种模式都附带一个渲染的图表，位于 [`patterns/html/`](./patterns/html)。 请参阅 [`patterns/README.md`](./patterns/README.md) 以添加您自己的模式。
---
## 设置
需要Node 18+（使用全局 `fetch`）和开放路由器API密钥。
```bash
npm install
npm run build
cp .env.example .env # 然后将您的密钥放入.env
```
在 <https://openrouter.ai/keys> 获取密钥，并在 `.env` 中设置 `OPENROUTER_API_KEY`。 `.env` 被git忽略，绝不能提交 - 只有 `.env.example` 被跟踪。
### 配置默认融合面板 + 裁判（可选）
默认情况下， `openrouter/fusion` 使用开放路由器的内置“质量”预设。 您可以从 `.env` 重写此 **每次** 调用：
```bash
# 1-8个面板模型并行回答：
OPENROUTER_FUSION_ANALYSIS_MODELS=anthropic/claude-opus-latest,openai/gpt-latest,google/gemini-pro-latest
# 综合它们的裁判模型：
OPENROUTER_FUSION_JUDGE_MODEL=anthropic/claude-opus-latest
```
优先级为 **每次调用的参数 > `.env` 默认值 > 开放路由器预设** ，独立解析面板和裁判： `ask_openrouter` 上的每次调用参数覆盖匹配的 `.env` 默认值，这些默认值仅适用于 `openrouter/fusion` （对于其他模型，它们被忽略）。
### 注册到Claude Code
```bash
claude mcp add -s user openrouter-subagents -- node /absolute/path/to/openrouter-subagents/dist/server.js
```
(Claude Code在启动时读取MCP注册，因此新添加的服务器在完全重启后出现。)
---
## 工作原理
1. `ask_openrouter` 构建一个OpenAI风格的聊天完成请求（`system` + `user` 消息）。
2. 对于 `openrouter/fusion`，面板 (`analysis_models`) 和裁判 (`judge_model`) 在 **每次调用的参数 > `.env` 默认值 > 开放路由器预设** 的优先级下解析，然后作为 `plugins: [{ id: "fusion", … }]` 条目发送。 如果两者都没有设置，则使用开放路由器的内置质量预设。
3. 请求以 `Authorization: Bearer $OPENROUTER_API_KEY` 发送到 `https://openrouter.ai/api/v1/chat/completions`；答案是 `choices[0].message.content`。
4. Fusion较慢（并行面板 + 综合），因此客户端使用慷慨的请求超时（~280s）。
---
## 安全
- API密钥存储在 `.env` （在所有地方都被git忽略）；只有 `.env.example` （占位符）被跟踪。
- 输出 `instructions` / `prompt` / `context` 在离开您的机器之前会经过尽力而为的秘密清理（API密钥、令牌、私钥） - **不是** 保证；请勿粘贴高度敏感的数据。
- **数据边界：** 默认情况下， `openrouter/fusion` 将您的输入一次性发送到多个第三方提供商（例如Anthropic、OpenAI、Google）通过开放路由器。
- 本地代理/编辑器状态（ `.mempalace/`、 `.claude/`、 `CLAUDE.local.md`、IDE文件夹）被git忽略。
---
## 许可证
MIT
