# NanoBananaPro DeepSeek Harness 插件

[![npm](https://img.shields.io/npm/v/dsh-nanobananapro.svg)](https://www.npmjs.com/package/dsh-nanobananapro)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek-Harness-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

`dsh-nanobananapro` 让 DeepSeek Harness 可以直接调用 NanoBananaPro 公开
API 生图和生视频。每位用户使用自己的 NanoBananaPro API Key；上游供应商、
扣费、数据库和存储密钥都留在 NanoBananaPro 服务端，不进入 Harness。

插件提供：

- `nanobananapro_generate_image`：文生图、参考图生图
- `nanobananapro_generate_video`：文生视频、图生视频、多模态参考生视频
- `nanobananapro_get_task`：查询或继续等待任务
- `nanobananapro_get_balance`：查看网页积分和 API 积分
- `nanobananapro_account_help`：返回注册、Key、充值和文档入口

## 注册、充值和 API Key

1. 打开 <https://api.bananapro.site> 登录或注册。
2. 打开 <https://api.bananapro.site/api-pricing> 购买 **API 积分**。
3. 打开 <https://api.bananapro.site/api-keys> 创建 API Key。
4. 只在启动 Harness 的环境中保存 Key，不要写进聊天、代码或
   `cordis.patch.yml`：

   ```bash
   export NANOBANANAPRO_API_KEY='sk-...'
   ```

5. 重启 Harness，先让它调用 `nanobananapro_get_balance` 检查余额。

注意：NanoBananaPro 的网页积分和 API 积分是两个独立钱包。这个插件消耗
**API 积分**，充值时请进入 API Pricing，而不是普通网页套餐。

完整 API 文档：<https://api.bananapro.site/api-docs>

## 安装

```bash
npx -y @deepseek-ai/dsh plugin --profile web add dsh-nanobananapro
npx -y @deepseek-ai/dsh --profile web --dump-config
npx -y @deepseek-ai/dsh web --profile web
```

如果安装克隆到本地的源码：

```bash
npx -y @deepseek-ai/dsh plugin --profile web add .
```

## 对话使用示例

```text
先查询我的 NanoBananaPro API 余额。然后生成一张 16:9、2K 的电影感产品
主视觉：透明跑鞋放在镜面金属台上。等待并返回最终图片。
```

```text
用 NanoBananaPro 的 Veo 3 Fast 生成一段 16:9 电影感视频：黄色纸飞机缓慢
飞过干净的蓝色摄影棚，等待并返回最终视频链接。
```

参考图片、视频和音频必须是外网可访问的 HTTPS URL。插件不会自动把本地文件
上传到网站；需要先上传并取得公开 URL。

## 扣费与安全

- 生图、生视频默认都会先弹出付费确认。
- API Key 由 Harness 凭据服务读取，不作为工具参数交给模型。
- 每个付费请求自动带幂等键；网络重试不会换键，降低重复扣费风险。
- 仅对 `429` 和服务端 `5xx` 做有限次数退避重试。
- 余额不足时错误会给出正确的 API 充值链接。
- 等待超时不代表任务失败。此时用原 `task_id` 调用
  `nanobananapro_get_task`，不要重新提交同一个生成任务。

## 可选配置

默认配置已经可以直接使用。只有需要更改超时、测试地址或确认策略时，才在
`$DSH_HOME/profiles/web/cordis.patch.yml` 覆盖完整配置：

```yaml
- id: nanobananapro
  config:
    apiBaseUrl: https://gateway.bananapro.site
    apiKeyEnv: NANOBANANAPRO_API_KEY
    requestTimeoutMs: 30000
    pollIntervalMs: 3000
    imageWaitTimeoutMs: 300000
    videoWaitTimeoutMs: 900000
    maxRetries: 2
    retryDelayMs: 500
    requireApproval: true
    allowLocalHttp: false
```

Harness 覆盖配置时会替换整行 `config`，不要只保留某一个字段。