chongming-plugins/doubao/README.md

# Doubao Worker 插件

火山引擎豆包（Doubao）视觉理解模型集成，支持图像分析与描述生成。

---

## 功能

- 接收 **base64 编码**的图片和**提示词**（prompt）
- 调用火山引擎豆包视觉模型 API
- 支持**思考模式**（thinking mode），模型会先推理再输出结果
- 返回模型生成的图像描述文本

---

## 配置

在 `config/workers/doubao/config.toml` 中设置：

```toml
[workers.config]
type = "doubao"
api_key = "<your-api-key>"                                  # 火山引擎 API Key（也可通过环境变量 VOLC_ACCESSKEY 提供）
base_url = "https://ark.cn-beijing.volces.com/api/v3"       # API 端点
model = "doubao-seed-evolving"                              # 模型名称
```

---

## API 端点

### `POST /doubao/analyze` — 图像分析

```json
// 请求
{
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "prompt": "描述这张图片的内容"
}

// 响应
{
  "result": "图片中是一只橘猫坐在米色沙发上，阳光从窗户照进来...",
  "error": ""
}
```

| 参数           | 类型  | 必填 | 说明                                                        |
| -------------- | ----- | ---- | ----------------------------------------------------------- |
| `image_base64` | `str` | ✅   | Base64 编码的图片数据（可含 `data:image/...;base64,` 前缀） |
| `prompt`       | `str` | ✅   | 给模型的提示词，描述期望的分析内容                          |

---

## 支持的模型

| 模型                   | 说明                         |
| ---------------------- | ---------------------------- |
| `doubao-seed-evolving` | 豆包视觉理解旗舰模型（默认） |

可根据火山引擎最新文档更换 `model` 配置项。

---

## 实现细节

- 生命周期基于 `Plugin` 基类：`on_init` 按 `is_aicc` 分支创建 Ark（`AsyncArk`）或
  AICC（`AsyncOpenAI` + `AsyncSecureHttpClient`）客户端并写入 `global_var`；
  `on_cleanup` 释放客户端引用（无数据库）
- API Key 优先取配置 `api_key`，其次环境变量 `VOLC_ACCESSKEY`（缺失时插件初始化报错）
- 支持 AICC 安全通信模式（懒加载 SDK，避免非 AICC 环境导入失败）
- 超时时间默认 30 秒，在 `config.toml` 的 `defaults.timeout` 中配置

---

## 依赖

| 工具包             | 用途                                 |
| ------------------ | ------------------------------------ |
| `httpx`            | 异步 HTTP 客户端                     |
| `chongming-worker` | `@rpc_method` 装饰器 + Worker 运行时 |