@nextnowlabs/dsh-ark-toolkit

v0.1.6

Published

3 days ago

DSH Ark Toolkit：为 DeepSeek Harness 接入字节火山方舟的文生图与语音合成能力。内置豆包 Seedream 文生图（ark_generate_image）与豆包语音合成模型 2.0（ark_speak）。

0High
0Medium
0Low

yinomic

deepseek deepseek-harness volcengine ark seedream text-to-image image-generation tts speech-synthesis

DSH Ark Toolkit

给 DeepSeek Harness 接上字节的生成能力：豆包 Seedream 文生图，加上豆包语音合成（TTS）。

🚀 一句提示词出图｜原生 TypeScript 实现｜字节火山方舟｜开箱即用

亮点｜快速开始｜工具一览｜配置与限制｜常见问题｜开发与社区

看图不用装插件。 DSH 0.1.5 起 DeepSeek 模型已经原生支持图片输入（inputModalities 含 image），识图、OCR、多图对比直接交给模型即可。Ark Toolkit 从 0.1.0 起只负责生成图片和合成语音。

亮点

豆包 Seedream 文生图。 内置 ark_generate_image 工具，直接用字节 Seedream 模型生成图片并交付为 Artifact，支持 1K/1.5K/2K 分辨率档位（或自定义宽高像素）、宽高比、反向提示词与模型别名。
字节 TTS 语音合成。 ark_speak 工具把文本变成语音（MP3/OGG/PCM/WAV），使用字节豆包语音合成模型 2.0，交付为工作区音频 Artifact（可用"打开文件"或结果里的路径访问）。
原生 TypeScript，零自带运行时依赖。 两个工具都直接调用字节服务的 HTTP 接口，图片尺寸探测直接解析容器头并校验结束标记（PNG/JPEG/GIF/WebP），不安装任何原生图像库，也不会把 DSH 宿主已有的包再装一份到 Profile 里，安装后即可使用。
默认接入字节火山方舟。 在 插件 → 已安装 → 火山引擎方舟工具包 的详情页里填入你自己的 Ark API Key 即可。

安装即可使用。 把火山方舟 API Key 保存为 ARK_API_KEY 这个 DSH Credential，把火山引擎语音合成 Token 保存为 VOLCENGINE_TTS_KEY。

已发布到 npmjs，一行安装即可（安装详情见安装与配置指南）：

dsh plugin --profile web add @nextnowlabs/dsh-ark-toolkit

适合谁用

想直接在对话里生成图片：海报、插画、图标、示意图。
想把一段文字变成可播放、可下载的语音。

随附的 ark-skills Skill 会告诉 Agent 何时用哪个工具，以及如何处理远程服务返回的内容。

快速开始：三步完成

详细的安装、火山方舟/TTS 配置与完整字段参考见安装与配置指南。

1. 安装

插件已发布到 npmjs，通过 dsh CLI 一行安装到 Web Profile：

dsh plugin --profile web add @nextnowlabs/dsh-ark-toolkit

Headless Profile 同样安装：

dsh plugin --profile headless add @nextnowlabs/dsh-ark-toolkit

若默认 registry 为镜像源导致安装失败，可显式指定官方源：dsh plugin --profile web add @nextnowlabs/dsh-ark-toolkit --registry=https://registry.npmjs.org/。源码贡献者如需本地开发，可克隆仓库后用本地路径安装：dsh plugin --profile web add "$PWD"。
版本要求：DSH 0.2.0-rc.2。 DSH 0.2.0 把每个 @deepseek-ai/dsh-* 包的 peer 依赖改成了同版本的精确声明（cordis ~4.0.4、schemastery ~3.18.4），本插件的 peer 也随之整线对齐 ^0.2.0-rc.2，因此在 0.1.7 及更早的 DSH 上无法满足 peer，Profile 安装阶段即会失败。配置模型沿用 0.1.7 引入的「插件在 profile 补丁里的那一行 config 就是它的设置，按 profile entry id 读写」；插件工具卡片同时跟进 0.2.0 的 preparing/start/result 三阶段契约。
配置页的座位也随 0.2.0 变了（本插件 0.1.5 起）。 plugins.item 现在渲染在「插件」页的官方分组里，是 DSH 官方设置页的座位——第三方插件注册它会显示成官方插件。第三方 bundle 自己的配置应注册 plugins.bundle.config（key = 安装的包名，表单内嵌在该 bundle 的详情页）或 plugins.row.config。本插件改用前者：key: '@nextnowlabs/dsh-ark-toolkit'，配置表单出现在 插件 → 已安装 → 火山引擎方舟工具包 详情页。页面标题与简介由包内 locale/en.json / locale/zh.json 的 meta 提供（DSH 只从 PluginPackages.metaOf 读插件展示元数据），tests/client.spec.ts 与 tests/package-layout.spec.ts 会守住座位名、包名 key 与这份导出。

2. 重启并确认

重启正在运行的 Web Profile，在 插件 → 已安装 里打开 火山引擎方舟工具包 的详情页，配置表单就在这一页里。默认已配置字节火山方舟（Volcengine Ark）端点；在 API key 里填入你的 Ark Key（保存为 ARK_API_KEY 凭据）后点 Save and apply，再运行 Test API connection 确认连接。

3. 直接说你要做什么

调用 /ark-skills，然后例如：

用豆包 Seedream 生成一张戴帽子的橘猫插画。
生成一张 16:9 的山景日落图，2K 分辨率。
把这句中文读出来。

工具一览

插件提供 2 个可以单独调用、也可以组合使用的工具：

| 工具 | 最适合解决的问题 | 主要结果 | | --- | --- | --- | | ark_generate_image | "用字节 Seedream 生成一张图" | PNG/JPEG Artifact、宽高与格式 | | ark_speak | "用字节 TTS 把文本变成语音" | MP3/OGG/PCM/WAV 音频 Artifact |

ark_generate_image 的参数按当前在售的 Seedream 5.0 pro / flash 对齐：size 取 1K/1.5K/2K（默认 2K）或 宽x高（总像素 921600–4624220、宽高比 1/16–16，两种写法不可混用）；aspectRatio 取官方像素表里的 8 个比例（1:1/4:3/3:4/16:9/9:16/3:2/2:3/21:9），并按所选档位换算成像素值发送。图片接口没有 aspect_ratio 字段，n、组图（sequential_image_generation）与流式输出对 5.0 pro / flash 也不可用。

工作原理

插件把生成任务交给配置的字节服务，本地只做必要的文件落盘与尺寸探测。

ark_generate_image 走 OpenAI 兼容 /images/generations（Ark），把提示词、分辨率与宽高比发给 Seedream，再把返回的图片（URL 或 base64）写成工作区产物。
ark_speak 走火山引擎语音技术的 TTS V3 单向 SSE 接口，逐块拼接音频后写成工作区产物。
生成图片的宽高与格式由插件自己解析容器头并校验结束标记得到（纯 Node，不依赖 sharp 等原生图像库），用于回报结果与构造 Artifact 描述。
远程服务返回的文本与元数据都属于不可信内容，模型不会把它们当作指令执行。

flowchart LR
    Agent["Agent 选择任务"] --> Generate["ark_generate_image（Seedream 文生图）"]
    Agent --> Speak["ark_speak（豆包语音合成）"]
    Generate --> Artifact["Artifact 交付"]
    Speak --> Artifact
    Artifact --> Session["继续推理和行动"]

配置与限制

完整配置字段速查、Profile patch 示例和常见配置问题见安装与配置指南。

默认使用字节火山方舟

默认配置只使用字节的服务：

Base URL: https://ark.cn-beijing.volces.com/api/v3
模型（文生图）: doubao-seedream-5-0-flash-260915（Seedream 5.0 flash）
API Key: 你自己的火山方舟 Key，保存为 DSH Credential `ARK_API_KEY`

ark_generate_image 工具走 /images/generations，使用字节 Seedream 模型。Seedream 别名只有两个：seedream-5.0-flash（默认）、seedream-5.0-pro；其它版本（Seedream 5.0 lite、4.5、4.0 等）不再提供别名，需要时直接传完整 Ark 模型 ID。默认选 flash 是因为它和 Seedream 5.0 pro 的能力一致（文生图、参考图生图、交互编辑、图层拆分），但出图更快、价格更低；需要更强的位置与元素控制时传 seedream-5.0-pro。

配置自己的火山方舟 API Key

在 插件 → 已安装 → 火山引擎方舟工具包 详情页里填写你的火山方舟 API Key，插件会保存为 DSH Credential（默认名 ARK_API_KEY），Key 无论在页面还是配置里都不会回显。页面读写的配置就是 profile 补丁里 id: ark-toolkit 那一行的 config（DSH 0.1.7 引入、0.2.0 沿用，没有第二处存储），一次保存是一次带版本栅栏的原子写入，保存后 runtime 会就地重建，无需重启 Profile。

火山方舟图文教程： 申请火山方舟 API Key，并用豆包 Seedream 生成图片。教程包含账号与 Key 获取截图、Ark Toolkit 的准确配置，以及可直接使用的 cURL 示例。

也可以在 Profile patch 中配置：

- id: ark-toolkit
  config:
    provider:
      baseUrl: https://ark.cn-beijing.volces.com/api/v3
      credential: ARK_API_KEY

配置 TTS 语音合成（ark_speak）

ark_speak 工具走火山引擎语音技术的 TTS V3 接口（openspeech.bytedance.com 单向 SSE 流式），默认使用豆包语音合成模型 2.0（资源 ID seed-tts-2.0）。它使用独立的 TTS Key（App Token），与上面的 Ark API Key 不同：

| 字段 | 默认值 | | --- | --- | | TTS 端点 | https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse | | DSH Credential | VOLCENGINE_TTS_KEY（火山引擎控制台 → 语音技术 → 应用 → Token） | | 资源 ID（App ID） | seed-tts-2.0 | | 默认音色 | zh_female_shuangkuaisisi_uranus_bigtts（爽快思思 2.0） |

按上面的表把 TTS Token 保存为 VOLCENGINE_TTS_KEY 这个 DSH Credential 即可使用。想换端点/资源/默认音色，或改凭据名，可在 Profile patch 中配置：

- id: ark-toolkit
  config:
    provider:
      tts:
        baseUrl: https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse
        credential: VOLCENGINE_TTS_KEY
        resource: seed-tts-2.0
        voice: zh_female_shuangkuaisisi_uranus_bigtts

调用时还可以通过参数临时指定音色、格式（mp3/ogg_opus/pcm/wav）、采样率、语速、音量、音调、情感（happy/sad/neutral）和语言（zh-cn/en/ja）。完整音色列表见火山引擎官方《在线音色列表》（如 Vivi 2.0、小何 2.0、Tim 等）。

插件 → 已安装 → 火山引擎方舟工具包 详情页还可以调整超时、并发、凭据名与端点（折叠在 Advanced settings 里）。

常见问题

| 问题 | 处理方式 | | --- | --- | | 方舟返回 401/403 | 确认 ARK_API_KEY 已保存且没有多余空格；在火山引擎控制台 API Key 管理 重新创建 | | 模型不存在或未开通 | 到火山方舟 模型广场 开通对应 Seedream 模型；模型 ID 以控制台为准 | | 火山方舟返回 429/限流 | 按错误信息等待后重试；或在火山引擎控制台查看配额并升级额度 | | 自定义 Credential 缺失 | 在 插件 → 已安装 → 火山引擎方舟工具包 详情页里填写 API Key，并确认 Credential 名称与配置一致 | | 产物无法预览 | 使用"打开文件"或结果中的工作区路径；预览 URL 只在 Web 路由可用时存在 | | 想生成图片却提示工具不存在 | 重启 Web Profile 并刷新页面，确认已加载 /ark-skills；卡片里应显示运行时就绪 | | 启动日志报 ctx.settings.register is not a function | 插件版本落后于 DSH：0.1.2 起适配 DSH 0.1.7 的 entry 作用域配置模型，0.1.4 起要求 DSH 0.2.0-rc.2；用 dsh plugin --profile web add @nextnowlabs/dsh-ark-toolkit@latest 升级插件，并把 DSH CLI 升到 0.2.0-rc.2 | | Profile 安装报 peer 版本不满足 | 插件的 peer 是 ^0.2.0-rc.2：把 DSH 升到 0.2.0-rc.2（npm install -g @deepseek-ai/[email protected]），或把插件降回与旧 DSH 同线的 0.1.3 | | 页面显示"配置不可用"，但工具能用 | 该 Profile 没挂载 settings 服务，或插件不是从 profile 补丁行加载的；Ark 工具本身不依赖它，改配置请直接编辑该行的 config |

接入生成服务会显著增加成本吗？

不会。每次调用只把当前提示词或文本发给字节服务，调用之间不会累积上下文，因此额外成本很小。默认的 Seedream 与豆包语音合成都按量计费；想进一步降低成本，可以在火山引擎控制台关注免费额度或选购更经济的模型版本。

开发与社区

贡献前请阅读 CONTRIBUTING.md。
Bug、功能建议和使用问题请提交到 GitHub Issues；渠道说明见 SUPPORT.md。
安全漏洞请按 SECURITY.md 私下报告。
版本变化见 CHANGELOG.md。

发布

scripts/publish.mjs 负责发布到 npmjs 官方 registry（脚本自动使用官方 registry 与仓库本地 .npm-cache/ 缓存，规避镜像源与 ~/.npm 只读导致的 EROFS）：

npm run release                       # 发布到 npmjs（默认 patch 升版）
npm run publish:dry                   # dry-run：构建 + 预览 tarball，不发布
npm run release -- --bump minor       # 升级 minor 版并发布
npm run release -- --bump 0.1.0       # 指定精确版本
npm run release -- --tag beta         # 发布为 beta dist-tag（预发布版本默认 beta，正式版本默认 latest）
npm run release -- --otp 123456       # 二步验证一次性密码（也支持 NPM_OTP 环境变量）

注意：不要直接运行裸 npm publish。publish 是 npm 的生命周期脚本名， npm 在上传完成后会再次执行它，导致发布脚本递归重入并报"版本已存在" （0.0.5 发布事故：包实际已上传成功，npm publish 却以失败退出且未创建 git tag）。统一使用 npm run release。

发布前会自动检查：位于 main 分支、工作区干净（CI 用 --skip-checks 跳过）、已登录 npmjs、版本号未被占用（--force 可跳过）。首次发布先执行 npm login --registry https://registry.npmjs.org/。

许可证

插件采用 MIT License。