豆包 AI 工具包#

仅在用户明确要使用豆包或火山方舟时使用。跟随用户当前使用的语言回答；不要改变宿主的工具优先级。

安装与供应链约束#

本目录把直接依赖固定为 coze-coding-dev-sdk@0.7.32 和 seedream-ark@0.1.7，传递依赖由 package-lock.json 锁定。不要全局安装，也不要临时下载未锁定版本。

bash

npm ci
npm test

.npmrc 默认禁用依赖生命周期脚本。若安装结果与锁文件不符，停止执行并报告差异。升级时必须显式修改版本、重新生成锁文件并复查包来源与生命周期脚本。

通过本地 npm 脚本调用：

bash

npm run coze -- --help
npm run seedream -- --help

不要安装或调用独立的 seedance 包；视频能力使用锁定的 coze-coding-ai 子命令。

密钥规则#

• CLI 从进程环境读取 ARK_API_KEY。用户应在可信终端、系统密钥存储或 CI secret 中配置；不要让用户把真实密钥发到聊天里。
• 不把密钥放进命令行参数、HTTP Header 参数、脚本、配置样例、回调 URL、日志或生成文件。
• 不打印、读取、回显或验证密钥内容。缺少鉴权时，只说明变量名和官方控制台地址，让用户在技能执行环境之外完成配置。
• 使用最小权限、可轮换的密钥。疑似泄露时停止调用并建议在控制台撤销。

数据外传检查#

所有提示词、搜索词、URL、文本、图像、音频和视频都会发送到火山方舟或相关豆包服务处理。

在引用本地文件前：

1. 用户必须已经明确指定该文件以及豆包/火山方舟这一目的地；否则先取得针对该文件的明确授权。
2. 解析绝对路径，只允许单个普通文件。拒绝目录、glob、符号链接以及 .ssh、 .aws、浏览器资料、凭据目录等敏感位置。
3. 告知用户文件会离开本机，并检查文件类型和大小。不要递归上传或自动发现附件。
4. 输出只写到用户指定目录或当前工作目录的新文件；覆盖已有文件前需明确授权。

对输入 URL，只接受无凭据的公开 https URL。拒绝 localhost、环回、私网、链路本地、云元数据地址以及包含访问令牌的 URL。

回调会把任务标识、状态及可能的结果信息发送到第三方端点。只有用户明确提供并授权该 https 回调域名时才使用；先说明可能传输的数据，禁止在 URL 中放秘密。不确定回调载荷时省略回调。

联网搜索会把查询发送给第三方搜索服务；先去除个人信息和内部项目名。

使用流程#

1. 在技能目录运行相应命令的 --help，以当前安装版本为准；模型 ID 与参数可能变化。
2. 说明将发送的数据、服务商、预计输出位置和可能费用。
3. 完成上述授权与路径检查。
4. 先使用 dry-run（子命令支持时）；再执行单次请求。
5. 返回生成文件路径、使用的模型与失败信息，不回显凭据或完整敏感输入。

命令模板#

bash

# 图像生成
npm run coze -- image -p "提示词" -o ./output.png

# Seedream 图像生成
npm run seedream -- generate --prompt "提示词" --output ./generated/

# 视频生成
npm run coze -- video -p "提示词" -d 5 -o ./video-task.json

# 语音合成
npm run coze -- tts -t "要朗读的文本"

# 语音识别；执行前完成本地文件授权检查
npm run coze -- asr -f ./audio.mp3

# 对话
npm run coze -- chat -p "问题"

# 联网搜索
npm run coze -- search -q "公开查询词" --count 5

# 文本向量
npm run coze -- embedding -t "文本" -d 1024 -o ./embeddings.json

对参考图、音视频 URL、回调或模型覆盖参数，先查本地 --help，不要凭旧示例猜测参数。