# Seedance 2 DeepSeek Harness 插件

[![npm](https://img.shields.io/npm/v/dsh-seedance2.svg)](https://www.npmjs.com/package/dsh-seedance2)
[![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-seedance2` 通过 Seedance 2 AI 自己的公开 API，让 DeepSeek Harness 同时
具备生图和生视频能力：

- 图片：Nano Banana Pro、Nano Banana 2 Lite、GPT Image 2
- 视频：Seedance 2、Seedance 2.5
- 查询：统一通过任务 ID 继续查询或等待

插件工具：

- `seedance2_generate_image`
- `seedance2_generate_video`
- `seedance2_get_task`
- `seedance2_account_help`

## 注册、充值和 API Key

1. 打开 <https://seedance2ai.io/sign-up> 注册或登录。
2. 打开 <https://seedance2ai.io/pricing> 购买积分。
3. 打开 <https://seedance2ai.io/app/api> 创建和管理 API Key。
4. 只在启动 Harness 的环境里保存 Key：

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

5. 重启 Harness。

这里必须使用 API 页面创建的公开 API Key。项目内部的上游供应商变量（例如
`SEEDANCE_API_KEY`）不能用于公开 API。

当前模型参数和完整 API 文档：<https://seedance2ai.io/developers>

## 安装

```bash
npx -y @deepseek-ai/dsh plugin --profile web add dsh-seedance2
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
用 Seedance 2 AI 的 Nano Banana Pro 生成一张 1:1、2K 的高端产品包装图，
背景是干净的摄影棚。等待并返回最终图片。
```

```text
用 Seedance 2 Pro 把这个公开 HTTPS 首帧图片做成 5 秒、720p、16:9 的
慢速推镜视频，生成声音，并等待最终视频链接。
```

```text
使用 Seedance 2.5 的 media-to-video，把这些公开 HTTPS 图片和视频作为
参考素材。提示词中明确每个素材的用途，等待最终结果。
```

参考素材必须是外网可访问的 HTTPS URL。视频提示词最好同时写明主体、动作、
场景、镜头运动、视觉风格、限制条件，以及每个素材扮演的角色。

## 扣费与安全

- 生图和生视频默认先弹出付费确认。
- API Key 由 Harness 凭据服务读取，不作为工具参数交给模型。
- 每次付费提交都带幂等键；自动重试沿用原键，降低重复扣费风险。
- 只对 `429` 和服务端 `5xx` 做有限次数退避重试。
- 失败任务会展示 API 返回的 `credits_refunded`。
- 等待超时不等于失败。继续使用原 `task_id` 调用
  `seedance2_get_task`，不要重新付费提交。
- Key 无效或余额不足时，会返回官方 Key 管理页或充值页。

## 可选配置

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

```yaml
- id: seedance2
  config:
    apiBaseUrl: https://www.seedance2ai.io
    apiKeyEnv: SEEDANCE2_PUBLIC_API_KEY
    requestTimeoutMs: 30000
    pollIntervalMs: 3000
    imageWaitTimeoutMs: 300000
    videoWaitTimeoutMs: 900000
    maxRetries: 2
    retryDelayMs: 500
    requireApproval: true
    allowLocalHttp: false
```

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