KIE 图像视频生成 MarceloSenai/dsh-plugin-kie-ai

dsh-plugin-kie-ai

为 DeepSeek Harness 智能体提供图像和视频生成能力，基于 KIE AI REST API。

这是一个社区插件，并非官方插件。它在 ctx.tools 上注册了三个工具，除此之外不消费任何其他内容——没有新增能力接缝，也没有对智能体循环做任何改动。

| 工具 | 功能 |
| kie_generate_image | 创建图像任务，每 5 秒轮询一次直到完成（默认 5 分钟），并返回最终的图像 URL。 |
| kie_generate_video | 创建视频任务，每 5 秒轮询一次直到完成（默认 5 分钟），并返回最终的视频 URL。 |
| kie_task_status | 获取某个任务的当前状态快照以及目前产出的任何资源 URL——不等待。 |

Bearer token 在每次操作时从环境变量读取（通过 apiKeyEnv，默认为 KIE_API_KEY）。它从不硬编码、从不记录日志，也从不写入配置文件。

安装

npm install dsh-plugin-kie-ai

然后在你的 profile 的 cordis.patch.yml 中添加一行：

- insert:
- id: tool-kie-ai
name: 'dsh-plugin-kie-ai'

在调用工具之前设置密钥：

export KIE_API_KEY=
dsh web

该插件将 @deepseek-ai/cordis、@deepseek-ai/dsh-tools 和 @deepseek-ai/dsh-llm 声明为 peer 依赖；harness 安装本身已经提供了它们。

配置

- id: tool-kie-ai
config:
baseUrl: https://api.kie.ai/api/v1
apiKeyEnv: KIE_API_KEY
pollIntervalMs: 5000
pollTimeoutMs: 300000

| 选项 | 默认值 | 含义 |
| baseUrl | https://api.kie.ai/api/v1 | API 基础地址；会追加 /jobs/...。 |
| apiKeyEnv | KIE_API_KEY | 存放 bearer token 的环境变量。 |
| pollIntervalMs | 5000 | 状态检查之间的延迟。 |
| pollTimeoutMs | 300000 | 总轮询预算（5 分钟）。 |

工作原理

两个生成工具都会调用 POST /jobs/createTask，然后轮询 GET /jobs/recordInfo?taskId=...，直到任务完成、失败、耗尽预算，或者智能体回合被取消。

失败会被分类，这样模型拿到的是可以据以行动的信息，而不是一个需要猜测的状态码：

| 条件 | 错误类型 |
| HTTP 402/429，或响应体提到余额或配额 | insufficient-balance |
| KIE 状态为 failed/error/cancelled/…… | task-failed |
| 在预算内未达到终态 | timeout |
| 调用被智能体中止 | cancelled |
| 响应中没有任务 id，或成功但没有 URL | protocol |

响应会被防御性地解析：任务 id 从 task_id、taskId、id 或嵌套在 data 中的这些字段读取，结果 URL 则通过递归查找 http(s) 字符串来发现，深度限制为 6，命中数限制为 64。

无法识别的状态会被视为待处理，而绝不会被视为失败。提供商会新增状态字符串，而将未知状态视为终态会放弃一个仍在运行的任务。

模型读回的内容

使用 nano-banana-pro 生成的图像（任务 T-9，成功）：
- https://cdn.example/asset.png

任务 T-9：状态 pending，状态渲染中

已知限制

- 一次生成会占用整个回合。 两个生成工具都在单次调用内轮询，因此一个五分钟的视频会占用工具槽位五分钟。将等待交给后台任务接缝可以解决这个问题，而这不是本插件所做的。
- 结果是 URL，而非附件。 资产留在提供商处，并按其时间表过期。没有任何内容被纳入 harness 附件存储，因此后续回合无法查看生成的图像——只能查看其链接。
- 模型 id 直接透传。 未知的 id 会表现为提供商错误，而不是在调用处被拒绝。
- 没有成本报告。 一次生成由提供商计费，这里没有任何东西为其定价，因此它不会出现在会话的支出报告中。

测试

npm test

globalThis.fetch 被桩替换；没有任何内容会到达真实端点。测试所固定的是对提供商格式的读取、令牌绝不会出现在调用方所见内容中，以及工具会随插件 fiber 注册和注销。实时检查需要密钥，是一个手动步骤。

许可证

MIT