# tokenforgemore

**Repository Path**: opencode-plugin/tokenforgemore

## Basic Information

- **Project Name**: tokenforgemore
- **Description**: tokenforge-支持多key轮询（不稳定）
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TokenForge More OpenCode Provider Plugin

**提供商 ID**: `tokenforgemore` | **显示名称**: TokenForge More | **Base URL**: `https://tokenforge.ai.studio/v1`

OpenCode 插件，集成 [TokenForge](https://tokenforge.ai.studio) 网关，支持 API Key 多密钥轮询以缓解速率限制。

## 功能

- **多 Key 轮询** — 输入多个 API Key（逗号分隔），自动循环切换，减缓 `429` 速率限制
- **错误容错** — 单个 Key 连续错误 3 次自动跳过，全部不可用时重置计数
- **模型支持** — 内置 `claude-opus-5`（思考模式 / 视觉输入 / 工具调用）
- **思考模型适配** — 对声明 `interleaved` 的模型自动注入 `thinking`，并兜底回传 `reasoning_content`
- **模型别名映射** — OpenCode 上送简写别名，插件改写为上游真实模型 id 后请求
- **请求头注入** — 自动设置 `User-Agent` 和 `Accept` 头
- **未授权兜底** — 未配置 Key 时直接返回 401 并提示授权，不触发无意义重试
- **维护模式识别** — 上游返回 `Site entered in maintainence mode due to massive request.` 时，
  返回 403 与中文提示（`由于请求量过大，网站已进入维护模式。`），不重试、不计入 Key 错误
- **调试日志** — `~/.tokenforgemore/debug.log`，由环境变量控制开关
- **凭证存储** — API Key 持久化到 `~/.tokenforgemore/auth.json`

## 安装

### 前提

- Node.js 22+
- OpenCode

### 步骤

```bash
# 1. 进入项目
cd tokenforgemore

# 2. 安装依赖
npm install

# 3. 构建
npm run build
```

## 配置

### 1. 配置 opencode.json

```json
// opencode.json
{
  "plugins": [
    "/path/to/tokenforgemore"
  ]
}
```

### 2. 添加凭据

在 OpenCode 中执行 `/connect` 命令，选择 **TokenForge More**：

```
┌ 创建 apiKey：https://tokenforge.ai.studio/dashboard/keys
│
│ 邀请链接（注册可额外获得额度）：
│ https://tokenforge.ai.studio/sign-up?aff=kul3
│ https://tokenforge.ai.studio/sign-up?aff=fem9
│
│ 输入 TokenForge API Keys（多key用逗号分隔）
│ ────────────────────────────────
│ sk-key1,sk-key2,sk-key3
└ enter
```

> 多个 Key 用逗号分隔，插件会自动轮询使用。未授权时模型请求会返回
> `未授权：请通过 /connect 命令点击 TokenForge More 进行授权`。

## 可用模型

当前网关仅提供 **1 个模型**：

| Model ID（别名） | 上游模型 ID | 上下文 | 最大输出 | 推理 | 输入模态 |
|------------------|-------------|--------|---------|:---:|----------|
| `claude-opus-5` | `claude-opus-5` | 1,048,576 (1M) | 131,072 (128K) | ✅ | 文本 / 图像 / PDF |

**模型信息（来源：model-advisor）**

- 供应商：Anthropic | 质量档：S 级 | 发布日期：2026-07-24
- 能力：工具调用、推理、视觉、流式输出
- 定价参考（USD / 1M tokens）：输入 `$5.00`、输出 `$25.00`、缓存读取 `$0.50`、缓存写入 `$6.25`
  （以上为 Claude Opus 5 官方定价，实际上游按网关计费为准）
- 推理档位：`max / xhigh / high / medium / low`（默认 `high`，由 OpenCode 的 variants 选择）

### 查询上游模型列表

当前 TokenForge 网关仅支持一个模型；如需确认上游实时模型列表，可执行：

```bash
curl https://tokenforge.ai.studio/v1/models -H "Authorization: Bearer $API_KEY"
```

响应示例：

```json
{
  "object": "list",
  "data": [
    {
      "id": "claude-opus-5",
      "object": "model",
      "created": 0,
      "owned_by": "tokenforge",
      "capabilities": ["reasoning", "coding", "streaming"]
    }
  ]
}
```

> **模型别名映射**：OpenCode 上送的是 `Model ID（别名）` 列，插件通过它匹配
> `src/constants.ts` 中的模型定义，再用「上游模型 ID」列的真实 id 请求上游。

## 多 Key 轮询机制

```
请求 → chat.headers → KeyManager.getNextKey()
                        ↓
                 ┌──────────────┐
                 │  key1  ← 首次 │
                 │  key2  ← 下次 │
                 │  key3  ← 再下次 │
                 └──────────────┘
                        ↓
                 写入 Authorization → 发起 API 请求
```

- 循环轮询：`key1 → key2 → key3 → key1 → ...`
- 错误追踪：每个 Key 连续失败 3 次后跳过
- 自动恢复：所有 Key 都被跳过时重置计数
- 成功自愈：请求成功后清零该 Key 的错误计数

## 错误处理

自定义 `fetch` 统一将上游错误转换为 OpenCode 可解析的标准 JSON 错误流：

| 场景 | 行为 |
|------|------|
| 上游维护模式 | 返回 **403** + `由于请求量过大，网站已进入维护模式。`（立即报错，不重试、不计入 Key 错误） |
| 401 / 403 | 立即报错（不重试），保留上游原始错误消息 |
| 408 / 409 / 429 / 5xx | 触发 OpenCode 重试（自动轮换 Key） |
| 网络异常 | 返回 502 标准错误流，不向 UI 抛异常 |
| 未授权（无 Key） | 返回 401 并提示 `/connect` 授权，不发真实请求 |
| 首 chunk 15s 超时 | 返回 429 触发 OpenCode 重试（防上游挂起） |

> **维护模式识别规则**：命中 `mainten* mode` / `massive request`（兼容上游 `maintenance` /
> `maintainence` 拼写差异），覆盖「错误响应体」与「HTTP 200 + SSE 首块」两种返回形态。
> 该判定仅作用于网关阻断页与错误载荷，模型正常输出中出现同样文字不会被误判。

## 调试日志

通过环境变量开启调试日志：

```bash
# 方式一：全局 DEBUG
DEBUG=1 opencode

# 方式二：仅 TokenForge More
OPENCODE_TOKENFORGEMORE_DEBUG=1 opencode
```

日志位置：`%USERPROFILE%\.tokenforgemore\debug.log`

## 项目结构

```
tokenforgemore/
├── package.json              # 依赖：@ai-sdk/openai-compatible, @opencode-ai/plugin
├── tsconfig.json
├── src/
│   ├── index.ts              # 主入口：auth hook + config hook + chat.headers + 共享 fetch
│   ├── constants.ts          # 提供商配置、模型定义
│   ├── plugin/
│   │   ├── auth.ts           # 凭证读写 ~/.tokenforgemore/auth.json
│   │   └── key-manager.ts    # 多 Key 轮询算法
│   └── utils/
│       └── debug-logger.ts   # 文件日志（无 console.error）
└── dist/                     # 构建产物
```

## 开发

```bash
# 类型检查
npm run typecheck

# 构建
npm run build
```