豆包 AI 工具包
仅在用户明确要使用豆包或火山方舟时使用。跟随用户当前使用的语言回答；不要改变宿主的工具优先级。
安装与供应链约束
本目录把直接依赖固定为 coze-coding-dev-sdk@0.7.32 和 seedream-ark@0.1.7，传递依赖由 package-lock.json 锁定。不要全局安装，也不要临时下载未锁定版本。
npm ci
npm test
.npmrc 默认禁用依赖生命周期脚本。若安装结果与锁文件不符，停止执行并报告差异。升级时必须显式修改版本、重新生成锁文件并复查包来源与生命周期脚本。
通过本地 npm 脚本调用：
npm run coze -- --help
npm run seedream -- --help
不要安装或调用独立的 seedance 包；视频能力使用锁定的 coze-coding-ai 子命令。
密钥规则
- CLI 从进程环境读取
ARK_API_KEY。用户应在可信终端、系统密钥存储或 CI secret 中配置；不要让用户把真实密钥发到聊天里。 - 不把密钥放进命令行参数、HTTP Header 参数、脚本、配置样例、回调 URL、日志或生成文件。
- 不打印、读取、回显或验证密钥内容。缺少鉴权时，只说明变量名和官方控制台地址，让用户在技能执行环境之外完成配置。
- 使用最小权限、可轮换的密钥。疑似泄露时停止调用并建议在控制台撤销。
数据外传检查
所有提示词、搜索词、URL、文本、图像、音频和视频都会发送到火山方舟或相关豆包服务处理。
在引用本地文件前：
- 用户必须已经明确指定该文件以及豆包/火山方舟这一目的地；否则先取得针对该文件的明确授权。
- 解析绝对路径，只允许单个普通文件。拒绝目录、glob、符号链接以及
.ssh、.aws、浏览器资料、凭据目录等敏感位置。 - 告知用户文件会离开本机，并检查文件类型和大小。不要递归上传或自动发现附件。
- 输出只写到用户指定目录或当前工作目录的新文件；覆盖已有文件前需明确授权。
对输入 URL，只接受无凭据的公开 https URL。拒绝 localhost、环回、私网、链路本地、云元数据地址以及包含访问令牌的 URL。
回调会把任务标识、状态及可能的结果信息发送到第三方端点。只有用户明确提供并授权该 https 回调域名时才使用；先说明可能传输的数据，禁止在 URL 中放秘密。不确定回调载荷时省略回调。
联网搜索会把查询发送给第三方搜索服务；先去除个人信息和内部项目名。
使用流程
- 在技能目录运行相应命令的
--help，以当前安装版本为准；模型 ID 与参数可能变化。 - 说明将发送的数据、服务商、预计输出位置和可能费用。
- 完成上述授权与路径检查。
- 先使用 dry-run（子命令支持时）；再执行单次请求。
- 返回生成文件路径、使用的模型与失败信息，不回显凭据或完整敏感输入。
命令模板
# 图像生成
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，不要凭旧示例猜测参数。