# FlyHub Agent 接入说明

用户会提供 FlyHub API Key。下文用 KEY 表示这把 Key。先判断当前客户端，再走对应分支做完模型路由和 MCP；不要把一个客户端的配置文件格式套到另一个客户端。确实判断不出客户端时问用户一句，其余不要停下来问。

## 第 0 步：判断客户端

- WorkBuddy → 走下面的「WorkBuddy」分支
- Claude Code、Codex、DeepSeek Harness、Gemini、Kimi → 直接用对应的 flyhub setup 命令（见「其他客户端」）
- Cursor、Cline、Trae → 用环境变量（见「其他客户端」）

## WorkBuddy

模型走 CLI：flyhub setup workbuddy --key KEY。它从 https://flyhub.com.cn/v1/catalog/models 只取 family=chat 的对话模型，按 id 合并进 ~/.workbuddy/models.json，已有的其他模型保留；生图、生视频、音频、向量不会写进来。拉取失败会改用内置清单并打印提示，遇到提示要在汇报里说明。跑完核对：每个 id 的 name 等于 id，url 和 endpoint 都是 https://api.flyhub.com.cn/v1。没有 flyhub 命令就先装：Windows 运行 irm https://flyhub.com.cn/install.ps1 | iex，macOS/Linux 运行 curl -fsSL https://flyhub.com.cn/install.sh | bash。

CLI 装不上或提示 unknown target 时，再手写 models.json（Windows 把 ~/ 换成 %USERPROFILE%\）：GET https://flyhub.com.cn/v1/catalog/models，读取 data.items，只取 family == "chat" 的条目。不要把 family 为 image、video、audio、embedding 的模型写进 models.json——它们不能当主对话模型，WorkBuddy 只会发 /v1/chat/completions，选了必报错。不要用 GET https://api.flyhub.com.cn/v1/models：它会把生图/生视频等媒体模型也列出来，不能直接全抄。也不要按 available 过滤。按 slug 合并进 ~/.workbuddy/models.json。每条：id 和 name 都只用 slug，两者必须相同。不要把 display_name 写进 name，不要加 (FlyHub)，也不要把 slug 再拼到 name 后面。WorkBuddy 会在名字后面再显示一次 id，name 写长了选择器就会变成「长名字:slug」。url 和 endpoint 都只填 https://api.flyhub.com.cn/v1，不要写成 /chat/completions 或其它路径。apiKey 填 KEY，vendor 填 FlyHub，useCustomProtocol 填 false，supportsToolCall 填 true，并把每个 id 放进 availableModels。已有的其他模型保留，不要整份覆盖。不要设置 CODEBUDDY_BASE_URL。

MCP：CLI 不写 mcp.json，这段自己写。GET https://flyhub.com.cn/v1/catalog/mcp。每条的 url 只复制 items[].endpoint，它本身已经以 /invoke 结尾，例如 https://api.flyhub.com.cn/v1/mcp/agentearth/invoke。按 slug 合并进 ~/.workbuddy/mcp.json，保留用户已有服务器。一条的形状：

{"mcpServers":{"SLUG":{"type":"http","url":"ENDPOINT","headers":{"Authorization":"Bearer KEY"}}}}

ENDPOINT 必须是清单里的 endpoint 原文。不要改主机，不要删掉 /invoke。向 https://flyhub.com.cn 请求 /v1/mcp 会 404，那是打错主机。

自检：POST 这个 endpoint，body 为 {"jsonrpc":"2.0","id":1,"method":"tools/list"}。返回 result.tools 即可。

## 其他客户端

- Claude Code：flyhub setup claude-code --key KEY
- Codex：flyhub setup codex --key KEY
- DeepSeek Harness：flyhub setup deepseek-harness --key KEY
- Gemini：flyhub setup gemini --key KEY
- Kimi：flyhub setup kimi --key KEY
- Cursor、Cline、Trae：环境变量 OPENAI_API_KEY=KEY，OPENAI_BASE_URL=https://api.flyhub.com.cn/v1
- 其他 Anthropic 工具：ANTHROPIC_API_KEY=KEY，ANTHROPIC_BASE_URL=https://api.flyhub.com.cn
- 没有 flyhub 命令时：curl -fsSL https://flyhub.com.cn/install.sh | bash

除 WorkBuddy 外，MCP 按客户端自己的配置格式写（Cursor、Cline、Trae 写 .cursor/mcp.json，形状与上面相同，url 用 items[].endpoint）；不要往 ~/.workbuddy/mcp.json 写。所有客户端都只接对话模型；生图、生视频、音频、向量走各自模型详情页的专用端点和示例，不要塞进模型选择器。

## 凭证

- 鉴权：Authorization: Bearer KEY。Anthropic 客户端用 x-api-key: KEY 也可以
- Anthropic Base URL：https://api.flyhub.com.cn（不含 /v1）
- OpenAI Base URL：https://api.flyhub.com.cn/v1
- MCP 清单：GET https://flyhub.com.cn/v1/catalog/mcp

## 完成后

用中文汇报改过的文件、MCP 数量、GET https://api.flyhub.com.cn/v1/models 是否 200。不要把 Key 写入 Git。tools/list 不扣费，tools/call 按次计费。Skill 见 https://flyhub.com.cn/v1/catalog/skills/install.md。