内容
# Hyperagent MCP 和本地 OpenCode 提供者
本地桥接 **Fable 5** 和 **GPT-5.6 Sol** 模型，使用 `hyperagent.com` 的活动浏览器会话 cookie。
该项目提供两种独立模式：
1. **stdio MCP 服务器**，带有 `hyperagent_models` 和 `hyperagent_chat` 工具；
2. **兼容 OpenAI 的本地提供者**，将两种模型添加到 OpenCode 并传递本地 OpenCode 工具（`bash`、`read`、`write`、`edit` 等）。
> [!WARNING]
> 该项目访问 Hyperagent 的内部、非官方文档的 Web API。Hyperagent 可能会在没有通知的情况下更改模型、端点或响应格式。
## 功能
- 仅支持两种明确允许的模型；
- 通过现有的 Hyperagent 会话使用，无需在 OpenCode 配置文件中复制 cookie；
- 在每个请求之前重新读取 cookie 文件；
- 通过 MCP 创建新的和继续的 Hyperagent 线程；
- OpenAI Chat Completions API，作为 OpenCode 的单独提供者；
- 流式和非流式响应；
- 将模型的工具调用转换为实际的本地 OpenCode 工具；
- 防止关于创建或修改本地文件的虚假声明；
- 将 HTTP 提供者绑定到 `127.0.0.1`；
- 自动删除提供者的临时 Hyperagent 线程。
## 支持的模型
| 别名 | 名称 | Hyperagent 模型 ID | 运行环境 | 上下文 | 最大响应 |
| --- | --- | --- | --- | ---: | ---: |
| `fable-5` | Fable 5 | `claude-fable-5` | `claude-agents-sdk` | 1,000,000 | 128,000 |
| `gpt-5.6-sol` | GPT-5.6 Sol | `openai/gpt-5.6-sol` | `langchain-deepagents` | 950,000 | 128,000 |
对于 Fable 5，使用 `effort=max` 和 `maxThinkingTokens=32000`。对于 GPT-5.6 Sol，使用 `effort=max`。
## 项目结构
```text
OpenCode
├── MCP 客户端 ──stdio──> dist/src/index.js
│ └── Hyperagent 会话 API
└── AI 提供者 ──HTTP──> 127.0.0.1:18457/v1
└── 提供者服务器.js
├── OpenAI 消息/工具转换
├── Hyperagent 会话 API
└── 将工具调用返回给 OpenCode
```
远程 Hyperagent 沙盒（`/agent/workspace`）**不是用户计算机**。在提供者模式下，任何对当前目录、文件、shell 和进程的操作都必须由 OpenCode 工具在本地计算机上执行。服务器使用单独的工具传输名称，以免与远程沙盒的内置工具冲突。
## 要求
- Node.js 18 或更高版本；
- npm；
- 活跃的 `https://hyperagent.com` 账户和浏览器会话；
- OpenCode - 仅当需要将模型作为提供者或 MCP 连接到 OpenCode 时。
## 安装
```bash
git clone <您的存储库 URL>
cd hyperagent-mcp
npm ci
npm run build
```
主要命令：
| 命令 | 用途 |
| --- | --- |
| `npm run check` | 在不创建 `dist` 的情况下检查 TypeScript |
| `npm run build` | 在 `dist/src` 中编译 JavaScript |
| `npm start` | 手动启动 stdio MCP 服务器 |
| `npm run provider` | 在前台启动 HTTP 提供者 |
| `npm run provider:start` | 在后台启动提供者 |
| `npm run provider:status` | 检查提供者和 `/health` |
| `npm run provider:stop` | 正确停止提供者 |
## Cookie：位置和格式
### 文件位置
默认情况下，服务器在当前工作目录中查找 `cookies.md` 文件。
- 在此安装中：`/root/test/cookies.md`；
- 在通常的克隆中：`<存储库根目录>/cookies.md`；
- 推荐路径：与 `package.json` 相邻。
可以通过环境变量覆盖路径：
```bash
export HYPERAGENT_COOKIES_FILE=/absolute/path/to/cookies.md
```
后台服务脚本默认始终使用 `<存储库根目录>/cookies.md`，而与运行 `npm` 命令的目录无关。
`cookies.md` 文件包含在 `.gitignore` 中，不应进入 GitHub、npm 包、日志或错误消息中。安全的模板位于 `cookies.example.md` 中。
### 准备 cookies.md
1. 在浏览器中登录 `https://hyperagent.com`。
2. 打开 Chrome DevTools 和 `hyperagent.com` 的 Cookie 表。
3. 将 Cookie 行复制为带有 TAB 分隔符的表格数据。
4. 将数据保存到 `<存储库根目录>/cookies.md`。
5. 不要将表格转换为带有 `|` 字符的 Markdown。
预期的前几列顺序：
```text
名称<TAB>值<TAB>域<TAB>路径<TAB>...
```
标头 `名称<TAB>值...` 是允许的，将被跳过。服务器使用名称、值和域，但需要至少具有四列的表格格式。仅允许以下域：
- `hyperagent.com`；
- `.hyperagent.com`。
每次向 Hyperagent 发送请求前都会重新读取 Cookie。在替换 `cookies.md` 后，通常不需要重启。
### Cookie 安全
Cookie 等同于 bearer 凭证，提供对您会话的访问权限。
- 不要提交 `cookies.md`；
- 不要将值粘贴到 `opencode.jsonc` 中；
- 不要将文件发送到问题、gist 或 CI 制品中；
- 不要将 Cookie 发送到除固定 `https://hyperagent.com` 之外的任何域；
- 在意外发布后，结束 Hyperagent 会话并获取新 Cookie。
客户端禁止跨源重定向，检查字符串域并拒绝允许注入额外 HTTP 头的字符。
## 模式 1：stdio MCP 服务器
构建后，入口点位于此处：
```text
dist/src/index.js
```
### 连接到 OpenCode
在 `~/.config/opencode/opencode.jsonc` 中添加以下内容，将路径替换为绝对路径：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hyperagent": {
"type": "local",
"command": ["node", "/absolute/path/to/hyperagent-mcp/dist/src/index.js"],
"environment": {
"HYPERAGENT_COOKIES_FILE": "/absolute/path/to/hyperagent-mcp/cookies.md"
},
"enabled": true
}
}
}
```
检查：
```bash
opencode mcp list
```
### 工具 hyperagent_models
不接受参数。返回支持的模型的别名、API ID、运行时、限制和设置。
### 工具 hyperagent_chat
| 字段 | 类型 | 必需 | 描述 |
| --- | --- | ---: | --- |
| `model` | `fable-5` 或 `gpt-5.6-sol` | 是 | 模型别名 |
| `prompt` | 字符串 | 是 | 模型的消息 |
| `thread_id` | 字符串 | 否 | 现有 Hyperagent 线程的 ID，用于继续 |
| `system` | 字符串 | 否 | 新线程的系统提示或现有线程的显式更新 |
| `timeout_seconds` | 整数 10–1800 | 否 | 超时，默认为 600 秒 |
新对话:
```json
{
"model": "fable-5",
"prompt": "用一个词回答：OK"
}
```
继续:
```json
{
"model": "fable-5",
"thread_id": "ID_来自_前一个_响应",
"prompt": "继续前一个回答"
}
```
响应包含 `thread_id`、`created_thread`、模型别名/ID 和 `response` 文本。继续线程时应使用原始模型和运行时。
MCP 模式管理远程 Hyperagent 线程。MCP 本身不允许模型访问 OpenCode 的本地文件。
## 模式 2：模型作为单独的 OpenCode 提供者
此模式适用于 Fable 5 和 GPT-5.6 Sol 必须显示在 `/models` 中并作为具有 OpenCode 本地工具的编码模型工作。
### 启动提供者
```bash
npm run build
npm run provider:start
npm run provider:status
```
提供者仅监听：
```text
http://127.0.0.1:18457/v1
```
停止：
```bash
npm run provider:stop
```
运行时文件在项目根目录中创建并被 Git 忽略：
- `.hyperagent-provider.pid` - 后台进程的 PID；
- `.hyperagent-provider.log` - 提供者的 stdout/stderr。
### OpenCode 配置
在 `~/.config/opencode/opencode.jsonc` 中添加提供者：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"hyperagent": {
"npm": "@ai-sdk/openai-compatible",
"name": "Hyperagent 会话",
"options": {
"baseURL": "http://127.0.0.1:18457/v1",
"apiKey": "local"
},
"models": {
"fable-5": {
"name": "Fable 5",
"limit": { "context": 1000000, "output": 128000 }
},
"gpt-5.6-sol": {
"name": "GPT-5.6 Sol",
"limit": { "context": 950000, "output": 128000 }
}
}
}
}
}
```
检查模型：
```bash
opencode models hyperagent
```
模型标识符：
```text
hyperagent/fable-5
hyperagent/gpt-5.6-sol
```
### 提供者如何与本地工具配合
1. OpenCode 将历史记录、工具的 JSON 模式和 `tool_choice` 发送到本地提供者。
2. 提供者将工具名称替换为唯一的传输别名。
3. 模型收到明确的指示，即 Hyperagent 沙盒不是用户计算机。
4. 模型返回 JSON 工具调用请求。
5. 提供者恢复实际的工具名称并将调用返回给 OpenCode。
6. OpenCode 在本地执行工具并将结果发送到下一个消息。
7. 只有本地工具结果被视为文件读取、修改或创建的确认。
对于明显的创建/编辑/读取文件和工作目录请求，提供者需要相应的本地工具调用。如果模型甚至在修复尝试后仍未返回必要的调用，请求将以错误结束，而不是假阳性成功消息。
每个 OpenAI 补全都创建一个临时的 Hyperagent 线程。在完成或错误后，提供者尝试删除该线程，因为 OpenCode 在每一步都发送整个历史记录。
## 提供者的 HTTP API
| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/health` | 进程检查 |
| `GET` | `/v1/models` | 两个模型的列表 |
| `POST` | `/v1/chat/completions` | OpenAI 兼容的聊天补全 |
支持常规和 SSE 流式响应、OpenAI 样式的工具调用和 `tool_choice`。
## 环境变量
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `HYPERAGENT_COOKIES_FILE` | `<cwd>/cookies.md` | Cookie 文件的绝对或相对路径 |
| `HYPERAGENT_PROVIDER_PORT` | `18457` | 提供者的本地端口 |
| `HYPERAGENT_PROVIDER_DEBUG` | 禁用 | 值 `1` 启用安全的 shape 日志记录 |
调试模式记录角色、工具数量/名称和结果形状，但不应记录提示文本或 Cookie 值。
## 仓库结构
```text
.
├── src/
│ ├── index.ts # stdio MCP 入口点
│ ├── provider-server.ts # OpenAI 兼容的 HTTP 提供者
│ ├── openai-compat.ts # 消息、工具别名和工具调用解析
│ ├── hyperagent.ts # Hyperagent 会话 API 客户端
│ ├── cookies.ts # 安全的 Cookie 表解析
│ └── models.ts # 允许的模型和运行时
├── scripts/
│ └── provider-service.mjs # 后台提供者的启动/停止/状态
├── cookies.example.md # 安全的格式模板
├── cookies.md # 实际的 Cookie；被 Git 忽略
├── package.json
└── tsconfig.json
```
`dist/`、`node_modules/`、日志、PID 和 Cookie 不发布到 Git。
## 安装后检查
```bash
npm ci
npm run check
npm run build
npm run provider:start
curl --fail http://127.0.0.1:18457/health
curl --fail http://127.0.0.1:18457/v1/models
opencode models hyperagent
npm run provider:stop
```
实时查询需要更新的 `cookies.md`。
## 故障排除
### 401 或 403
浏览器会话已过期或 Cookie 未完全复制。请从活跃的 Hyperagent 会话更新 `cookies.md`。值将在下一次请求时重新读取。
### 无效的 cookie 表/域/值
确保文件由 TAB 隔开，包含至少四列，并且仅包含 `hyperagent.com`/.`hyperagent.com`。不要粘贴普通的 HTTP `Cookie:` 头部代替表格。
### 提供者无法启动
```bash
npm run build
npm run provider:status
cat .hyperagent-provider.log
```
还请检查 `127.0.0.1:18457` 是否空闲，或者设置另一个 `HYPERAGENT_PROVIDER_PORT` 并更新 OpenCode 的 `baseURL`。
### 模型写入文件，但文件不存在
确保通过本地提供者选择了 `hyperagent/fable-5` 或 `hyperagent/gpt-5.6-sol` 模型，而不是远程 Hyperagent MCP/代理。本地提供者应返回工具调用，然后 OpenCode 显示 `write`、`edit` 或 `bash` 的实际执行。
### Hyperagent 更改了内部 API
检查 `/api/threads`、`/api/threads/:id/messages` 和聊天 SSE 的响应。该项目故意不使用第三方域的 Cookie，因此无法自动切换到未知端点。
## 发布到 GitHub 的准备
首次提交前：
```bash
git init
git check-ignore cookies.md
git status --short
npm ci
npm run check
npm run build
```
确保暂存文件中没有：
- `cookies.md` 和任何实际的 Cookie 值；
- `.hyperagent-provider.log` 和 `.hyperagent-provider.pid`；
- `node_modules/`、`dist/`、`.env`；
- 不属于 MCP/提供者的用户文件。
然后：
```bash
git add .
git status --short
git commit -m "初始 Hyperagent MCP 桥接"
git branch -M main
git remote add origin <您的存储库 URL>
git push -u origin main
```
## 限制
- Hyperagent 的内部 API 可能会更改。
- Cookie 会过期，需要手动更新。
- 图像输入转换为文本通知，不作为图像传输。
- OpenAI 兼容响应中的令牌使用量根据字符数近似评估。
- 官方远程 MCP Hyperagent 管理远程沙盒中的代理，不直接访问 OpenCode 的本地文件系统。
- 此项目不是官方的 Hyperagent SDK 或产品。
