# agnesmore

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

## Basic Information

- **Project Name**: agnesmore
- **Description**: agnes-支持多key轮询
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agnes OpenCode Provider Plugin

**提供商 ID**: `agnesmore` | **显示名称**: Agnes | **Base URL**: `https://apihub.agnes-ai.com/v1`

OpenCode 插件，集成 [Agnes AI](https://agnes-ai.com)（Sapiens AI 旗下）免费多模态 AI API，支持 API Key 多密钥轮询以缓解速率限制。

## 功能

- **多 Key 轮询** — 输入多个 API Key（逗号分隔），自动循环切换，减缓 `429` 速率限制
- **错误容错** — 单个 Key 连续错误 3 次自动跳过，全部不可用时重置计数
- **模型支持** — 内置 3 个免费模型：文本对话、图像生成、视频生成
- **请求头注入** — 自动设置 `User-Agent` 和 `Accept` 头
- **调试日志** — `~/.agnesmore/debug.log`，由环境变量控制开关
- **凭证存储** — API Key 持久化到 `~/.agnesmore/auth.json`

## 安装

### 前提

- Node.js 22+
- OpenCode

### 步骤

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

# 2. 安装依赖
npm install

# 3. 构建
npm run build
```

## 配置

### 1. 添加凭据

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

```
┌ apiKey创建：https://platform.agnes-ai.com/settings/apiKeys
│
│ 当前3个模型均免费使用，详见文档：https://agnes-ai.com/doc
│
│ 输入 API Keys（多 key 用逗号分隔）
│ ────────────────────────────────
│ sk-key1,sk-key2,sk-key3
└ enter
```

> 多个 Key 用逗号分隔，插件会自动轮询使用。
> Agnes 的 API Key 以 `sk-` 开头。

### 2. 配置 opencode.json

```json
{
  "provider": {
    "agnesmore": {
      "name": "Agnes",
      "options": {
        "baseURL": "https://apihub.agnes-ai.com/v1"
      }
    }
  }
}
```

### 3. 选择模型

执行 `/models` 命令，选择可用模型：

| Model ID | 描述 | 上下文 | 类型 |
|----------|------|--------|------|
| `agnes-2.0-flash` | 快速高效多模态语言模型，支持工具调用、图片理解 | 256K | 文本+图像→文本 |
| `agnes-image-2.1-flash` | 高性能图像生成与编辑，支持文生图、图生图 | - | 文本→图像 |
| `agnes-video-v2.0` | 视频生成，支持文生视频、图生视频、关键帧动画 | - | 文本→视频（异步） |

## 图像/视频参数请求头

其他 OpenCode 插件（如智能体编排插件）可通过 `chat.headers` 钩子注入自定义请求头，
控制图像/视频生成的输出参数。插件在 `auth.loader` 的自定义 `fetch` 中自动读取并应用。

### 图像模型请求头

| 请求头 | 类型 | 默认值 | 说明 | 适用模型 |
|--------|------|--------|------|----------|
| `X-Image-Size` | string | API 默认 | 输出尺寸，如 `1024x1024`、`1792x1024` | 全部 |
| `X-Image-N` / `X-Image-Count` | number | `1` | 生成图片数量 | 全部 |

### 视频模型请求头

| 请求头 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `X-Video-Width` | number | API 默认（`1152`） | 视频宽度 |
| `X-Video-Height` | number | API 默认（`768`） | 视频高度 |
| `X-Video-Num-Frames` | number | API 默认（`121`） | 视频帧数（≤441，且为 8n+1） |
| `X-Video-Frame-Rate` | number | API 默认（`24`） | 视频帧率（1–60） |
| `X-Video-Seed` | number | 随机 | 随机种子，可复现结果 |
| `X-Video-Mode` | string | - | 生成模式，`ti2vid` 或 `keyframes` |
| `X-Video-Negative-Prompt` | string | - | 反向提示词 |

### 注入示例

外部插件的 `chat.headers` 钩子：

```typescript
'chat.headers': async (input, output) => {
  if (input.model.modelID === 'agnes-image-2.1-flash') {
    output.headers['X-Image-Size'] = '1792x1024'
  }
  if (input.model.modelID === 'agnes-video-v2.0') {
    output.headers['X-Video-Width'] = '1920'
    output.headers['X-Video-Height'] = '1080'
    output.headers['X-Video-Num-Frames'] = '241'
    output.headers['X-Video-Frame-Rate'] = '24'
  }
}
```

### 模型差异说明

| 模型 | 图像输入 | 多图合成 | 输出方式 |
|------|----------|----------|----------|
| `agnes-image-2.1-flash` | 支持单张图生图 | ❌ | URL 下载到本地 |
| `agnes-image-2.0-flash` | 支持多张图生图 | ✅ 多图合成 | URL 下载到本地 |
| `agnes-video-v2.0` | 支持图生视频 | ❌ | 异步轮询 → URL 下载到本地 |

## 多 Key 轮询机制

```
请求 → loader → KeyManager.getNextKey()
                ↓
         ┌──────────────┐
         │  key1  ← 首次 │
         │  key2  ← 下次 │
         │  key3  ← 再下次 │
         └──────────────┘
                ↓
         返回 apiKey → 发起 API 请求
```

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

## 调试日志

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

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

# 方式二：仅 Agnes
OPENCODE_AGNESMORE_DEBUG=1 opencode
```

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

## 项目结构

```
agnesmore/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # 主入口：auth hook + config hook + chat.headers
│   ├── constants.ts          # 提供商配置、3 个免费模型定义
│   ├── plugin/
│   │   ├── auth.ts           # 凭证读写 ~/.agnesmore/auth.json
│   │   └── key-manager.ts    # 多 Key 轮询算法
│   └── utils/
│       └── debug-logger.ts   # 文件日志（无 console.error）
└── dist/                     # 构建产物
```

## 开发

```bash
# 构建
npm run build

# 类型检查
npm run typecheck
```

## 许可

Apache 2.0