内容
代理网关
一个MCP服务器（stdio传输），它将来自[Kimi Code](https://www.kimi.com/code)或其他任何MCP的子任务委托给本地运行的[opencode](httpsencode.ai) CLI。它为你的主代理提供了一个“供应商的模型提供支持的协作者”：opencode使用其配置的模型（DeepSeek、GLM等），而网关处理会话连续性、权限、超时和。
[中文版 README](README.zh-CN.md) · [AI 安装指南（给 Agent 看的）](给K安装指南.md)
## 使用你的 AI 代理安装（）
不想手动安装？将以下内容粘贴到 编程代理（Kimi Code、Claude Code等，它将为你完成所有操作：
```
阅读github.com/SiliconLight/subagent-gateway/blob/mainKimi的安装指南.md 并按照说明在该机器agent-gateway MCP 服务器：克隆仓库到永久依赖，运行烟雾测试，在 MCP 客户端注册它（合并到现有条目中，切勿覆盖整个文件），然后告诉我重启客户端。
```
唯一的前提条件： ≥ 18 和带有配置的 opencode CLI 模型 代理将为您。手动安装文档见 [下方](#install)。
## 日常使用
安装完成后，只需自然地与你的主代理对话：
- **委托工作** — “将此任务交给子代理：…”。注意每次调用都是冷启动，除非你继续使用相同的任务线程（`agent_id`），因此请确保任务是自包含的 **列出可用模型** — “子代理可以使用哪些模型？”（运行 `list_models`更改模型**“更改子代理模型”：代理列出 opencode 的配置模型供你选择，然后询问推理努力 — 选择 **自动根据任务决定需要 [下方](#3-项目-agentsmd-委托策略-可选-帮助主代理) 的 AGENTS.md 代码段。）
- **在一个对话中迭代** —结果；同一个对话在多轮中保持完整的上下文（- **权限门 — 在 YOLO 模式之外，当子代理尝试或运行 shell 命令时，您会收到一个错误，描述；批准它会重试并带有 `: true`，在同一个会话中继续。
-代理** — 删除其在 `<projectDir>/.kimi-code/external-agents.json` 中的条目，以便下次启动新的会话。
## 功能
- **会话继续** — 传递相同的 `agent_id` 以重用相同的 opencode 会具有完整的历史记录；适用于迭代多轮任务。
调用的模型和推理努力** — `model`到 `opencode -m`，`variant`到 `--variant` `deepseek/deepseek-pro` 支持 `high`/`max`）。两者会话的各轮之间更改。
- **权限桥接 `auto_approve: true` 运行 opencode 时`（YOLO 风格）；默认情况下，权限 `ask` 会被无头 opencode 自动拒绝，网到由此产生的停滞（约 60 秒），中止返回被拒绝的工具调用，以便主代理可以询问其用户并重试。
- **鲁棒性** — 自动opencode serve` 并进行身份检查（不仅是“端口打开”），当服务器死亡或会话 404 时，超时实际中止服务端会话（无孤立的令），每个 `agent_id` 互斥锁上的进程树杀死，UTF-8 安全的参数无 cmd.exe 代码页混淆）。
##
- Node.js ≥ 18
- [ophttps://opencode.ai) CLI 已安装并在，至少有一个模型提供配置（`opencode models` 列出模型）。在 Windows 上针对 opencode 1.18.x 开发和测试；其他平台应通过 PATH 回退（参见下文的 `OPENCODE_EXE`）工作。
- 一个 MCP 客户端。 Kimi Code 在下方有文档，但任何通过 stdio 使用 MCP 的客户端都有效。
## 安装bash
gityour-fork-url subagent-gateway install
```
## 测试
1. 协议握手 + 工具列表 opencode）：
```bash
printf '%s \
'{"jsonrpc":"2.0","id,"method":"initialize","params":{"protocolVersion":"2025-26","capabilities":{},"clientInfo":{"nameoke","version":"0.0.1"}}}'jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.id":2,"method":"tools/list"}' \
node server.js
```
您应该看到 `initialize`两个工具定义（`delegate_task`、`list_models。
2. 端到端委托（实际调用配置；第一次运行自动启动 `opencode serve`）：bash
printf '%s\n' \
'{"json2.0","id":1,"method":"initialize":{"protocolVersion":"20203-26","":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' \
'{"jsonrpc.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"tools/call","params":"delegate_task","task":"Reply with exactly characters OK.","modelseek/deepseek-vash","agent_id":"smoke-test"}}}' \
| node server.js
后，`<projectDirkimi-code/external-ag` 应包含一个 `smoke-test` → `…` 会话映射。
## 客户端配置（）
手动段 — 此仓库及您的配置文件。
### 1. `~-code/mcp.json`
```json
{
"": {
"subagent-gateway":command": "node "args": ["-path-to>/subagent/server.js"],
TimeoutMs": 60000,
"toolTimeout600000
}
}
```
服务器默认为其进程（即 Kimi 启动要固定项目目录，请添加 `"env "SUBAGENT_PROJECT_DIR": "/path/to/project" }`。
### 2. `~/.kimi-code/config.toml` — 权限规则（跳过每次调用的批准）
```toml
[[permission.rules]]
decision = "allow"
pattern = "mcp__subagent-g"
```
> 注意：此规则使批准所有委托。子代理随后可能执行的操作opencode 的* 权限配置控制，而不是客户端参阅 [权限模型](#权限模型)。
### 项目 `AG` — 委托策略主代理正确使用工具）
```markdown 子任务委托策略
使用 MCP cp__subateway__delegate_task`encode + 外部模型）而不是内置代理工具委托。
- 首先调用 `mcp__subateway__list_models` 以确认可用模型。
-任务，使用快速模型（例如 deepseek/deep-flash），对于复杂任务，使用更强大的模型（例如 deepseek/deepseek-v4-pro）；为 `variant`。
- 在 YOLO / 全自主模式下，传递 `auto_approve: true`；否则省略它。如果调用因权限被拒绝的错误而失败，请先询问用户，然后重试并带有 `auto_approve: true`（保留相同的 `agent_id` 会话）。
- 当用户说“设置/更改子代理模型类似时：运行 `mcp__subagent-gateway__list_models` 并让用户选择模型，然后让推理努力 — 始终首先提供“自动”（您决定：对于简单任务省略 `variant`，对于复杂任务使用支持的变然后是所选模型实际支持的变体（跳过此步骤如果所有后续 ` 调用记住选择更改它。
行调用相同的 ``（服务器序列化语义更清晰 `agent_id` 进行上下文保留的多轮重启客户端，运行cp` — `-gateway` 为已连接。然后 `mcp__subagent-gateway__list确认链接。
工具
### delegate| 参数 | 类型 | 必需 | 描述 |
| --- | --- |
| `task` | 是 | 自任务描述 |
|` | 字符串 | 转发到 `m`；默认为 `deepseek/deepseek-v4-pro` |
| `agent_id` | 字符串 | 否 | 子代理标识符；传递它启用会话继续 |
| `auto_approve` | 布尔值 | 否 | `true`: 运行 opencode 时带有 `--auto`（自动批准所有未明确拒绝的操作 — YOLO 场景）。默认为 ` opencode 自动拒绝 `ask`；检测到由此产生的停滞（约 60 秒），中止会话，并将拒绝的工具错误返回 |
| `variant` | 字符串 | 否理努力，转发opencode --variant特定于提供者）。`deepseek/deep4-pro` 和seek/deepseek-v4-flash` 支持`/`max`模型的默认值 |
### list_models
运行 `opencode models` 并原样返回列表。
## 权限模型
**在委托实际工作之前请阅读此内容。**
- 子代理在 **opencode 的权限配置**（`~/.config/opencode/opencode.jsonc`）下运行，完全独立于 MCP 客户端的权限系统。
- 在无头 `run` 模式下（网关调用 opencode），`ask` **立即自动拒绝 永远不会存在请求，因此无法交互式它（在 1.x 上观察到）。
- 推荐的 配置与此网使用：
```{
" { "*": " "edit": " "bash": "ask" }
}
```
使用此配置，文件编辑和 shell 命令通过网关的桥接逻辑流动：
- `auto_approve: true` → opencode 获取 `--auto`，永远不会询问任何内容。
- 默认 →被自动拒绝，停滞检测在约 60 秒内返回被拒绝调用的确切信息代理可以询问其用户并重试并带有 `: true`。
- 在 opencode 配置中将工具设置为 `deny` 也有效失败），它只是绕过了网关的检测。
- `approve: true` 危险性 —所有未明确拒绝在您信任的 / 全自主上下文。
## 工作原理
- 在第一次调用时，网关检查 `http://localhost:4096`（`GET /config` 必须返回 JSON，以便不会将占用该端口的随机进程误认为是 opencode）。如果无法访问，它会启动 `opencode serve --port 4096`最多 30 秒调用）。
- 然后 `opencode run --attach http:4096 -m <model> --dir <projectDir> --format json [--auto] [--varianttask>"`
- 针对观察到的 op1.18.x（Windows）的适配 - 在 spawn 时关闭 stdin — `opencode 在 stdin 不是 TT等待 stdin EOF；
- 直接 spawn `opencode.exe`（默认ATA%\npmopencode-aiencode.exe` `OPENCODE_EXE）以避免页混淆 参数；
attach` `--format json` 仅打印一行 `step_start` 然后退出 — 网关从该获取 `sessionID`，然后轮询 `GET /session/{id}/message` 直到本轮助手消息完成（`finish` ≠ `tool-calls`）并部分。
-` → 会话映射存储在 `<project/.kimi-code/external.json`（包含 — 本地材料，由此仓库的 `.` 忽略） - 映射存在追加 `--session < 以继续；
无映射 → 追加 `--title <agent_id>` 以创建命名会话并记录其 `sessionID`（`ses_…`）；
- “会话未找到”错误 → 自动重试而不使用 `--session` 并更新映射。
- 每个 `agent_id`斥锁：并发调用序列化。总超时时间为 10 分钟，通过 `POST/{id}/abort` 中止服务端会话死本地进程树 停滞检测消息以 `tool-calls`，并且在 60 秒内没有出现新回合被视为（典型原因：无头模式下权限自动拒绝）；会话被中止，并返回工具错误。
- 轮询失败（服务端话 404，非 200）立即抛出，而不是等待超时。
## 环境变量
| 变量 | 用 默认值 |
| --- | --- | --- |
| `SUBAGENT_PROJECT_DIR` | 固定项目目录（驱动 `--dir` 和映射文件位置） | 服务器进程 cwd |
| `OPENCODE_EXE` | opencode 可执行文件的路径 | `%APPDATA%\npm\node_modules\opencode-ai\bin\opencode.exe`，从 PATH 备用 |
在 `mcp.json` 中服务器条目的 `"env"` 设置它们。
## 故障排除
- 服务器到 stderr（执行的命令、错误客户端侧检查 `/mcp` 状态。
4096占用：身份检查（`GET /config` 返回 JSON）将拒绝将其视为就绪 — 释放端口或更改 `server.js` 中的 `PORT`。
- 删除 `.-agents.jsonagent_id` 条目，以便下次为其启动新会话。
- 在 opencode 升级重新运行烟雾测试 — 此服务器适配.18.x（`sessionID小写、`--` 输出形状，无头询问自动拒绝）。
## 许可证MIT](LICENSE)
