coze-low-code-caller-yashu

扣子(Coze)智能体与工作流调用器

功能概述

封装对字节跳动扣子(Coze)平台 API 的调用能力。支持：

• 调用扣子平台上的智能体(Bot)执行特定任务
• 触发扣子平台上的工作流(Workflow)进行自动化处理
• 管理智能体和工作流的执行状态和结果

环境说明

• $SKILL_DIR = 当前 Skill (coze-low-code-caller-yashu) 所在目录，即本文件 SKILL.md 所在的文件夹
• Shell 类型： 本 Skill 的命令示例统一采用 bash 语法。AI 应在 bash 执行环境中运行命令；若当前环境的默认 Shell 不是 bash（如 Windows PowerShell），先切换到 bash（如 Git Bash、WSL）再执行。

• ⚠️ $SKILL_DIR 仅为文档占位符，不是环境变量！ 执行命令时必须替换为当前 Skill 所在目录的绝对路径。直接写 $SKILL_DIR 会被 bash 当作未定义变量解析为空字符串，导致 cd "$SKILL_DIR/scripts" 变成 cd "/scripts" 而报错"找不到路径"。

• 脚本目录： $SKILL_DIR/scripts/
• 命令分隔符： 本 Skill 运行命令时采用 bash && 链式依赖执行（前一条成功才执行下一条）：cmd1 && cmd2
• 模块类型： $SKILL_DIR/scripts/package.json 已设置 "type": "module"，因此所有 .js 脚本均按 ES Module 解析。如需修改或新建脚本文件，必须使用 import 语法，不能使用 CommonJS 的 require。

⚠️ 脚本已混淆，禁止读取源码

$SKILL_DIR/scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理，禁止读取或分析 .js 文件内容。混淆代码可读性极差，读取纯属浪费 token 和时间。

如需了解脚本功能和用法，请查阅「全业务脚本索引清单」和 $SKILL_DIR/references/ 目录下的接口文档。

⚠️ 禁止用 Shell 命令写文件

本 Skill 执行过程中创建或修改任何文件（包括 .env、config/*.json、temp/ 目录下的参数文件等），必须使用 Write 工具，禁止使用任何 Shell 文件写入命令（Set-Content、Out-File、> 重定向、echo >、[System.IO.File]::WriteAllText() 等）。

原因：PowerShell 的文件写入命令会添加 UTF-8 BOM（EF BB BF），导致 JSON 解析失败（Unexpected token）、JS 模块加载报语法错误、Markdown frontmatter 字段读取为 undefined。使用 Write 工具可避免此问题，且在所有平台上安全。

全业务脚本索引清单

智能体脚本（Bot）

工作流脚本（Workflow）

工作流统一使用异步执行（is_async: true）。执行后需轮询 check_workflow_result.js 获取结果。

公共脚本

前置条件

调用扣子 API 前，执行以下检查和准备：

1. 读取配置： 运行 Read 读取 $SKILL_DIR/.env。如 COZE_API_KEY 或 COZE_SPACE_ID 不存在，向用户索要并运行 Write 创建或更新 $SKILL_DIR/.env。获取方式参考 [获取扣子 API Key 指南]($SKILL_DIR/references/获取扣子 API Key.md) 和 获取扣子空间ID指南。

   # 扣子空间 ID
   COZE_SPACE_ID=你的空间ID
   
   # 扣子 API 密钥
   COZE_API_KEY=你的API密钥
   
   # 轮询间隔时间（单位：秒），默认5秒
   POLLING_INTERVAL=5
   

2. 读取配置列表： 运行 Read 读取 $SKILL_DIR/config/bots.json 和 $SKILL_DIR/config/workflows.json。如文件不存在或为空，提示用户先配置智能体/工作流。

   {
     "bots": [
       {
         "id": "你的BOT_ID / 智能体 ID",
         "name": "智能体名称",
         "description": "可选描述",
         "recent_durations": []
       }
     ]
   }
   

   recent_durations 字段由脚本自动维护，记录最近 6 次成功调用的端到端耗时（从创建会话到任务完成，如 "28秒"、"1分15秒"），供 AI 参考预估等待时间。无需手动填写。

   {
     "workflows": [
       {
         "id": "你的WORKFLOW_ID",
         "name": "工作流名称",
         "description": "可选描述",
         "recent_durations": []
       }
     ]
   }
   

   recent_durations 字段由脚本自动维护，记录最近 6 次成功调用的端到端耗时（从执行工作流到执行完成，如 "28秒"、"1分15秒"），供 AI 参考预估等待时间。无需手动填写。

3. 安装依赖（一次性操作）： 运行 cd "$SKILL_DIR/scripts" && npm install 确保依赖已安装。依赖安装后无需重复执行，仅首次使用或 package.json 更新后需要重新安装。

脚本调用方式

所有预置脚本位于 $SKILL_DIR/scripts/ 目录，调用前确保已安装依赖。

⚠️ 【致命重要】执行脚本前必须先 cd 到 scripts 目录

每次运行任何脚本之前，先执行 cd "$SKILL_DIR/scripts"，再运行脚本。否则 Node.js 会在当前工作目录找不到脚本文件，报 Error: Cannot find module '...'。例如：

cd "$SKILL_DIR/scripts" && node create_session.js <bot_id>

执行步骤

1. 确认已在【前置条件】中完成 .env、bots.json 和 workflows.json 的读取
2. 理解用户意图，通过对比 bots.json / workflows.json 中每个对象的 name 和 description 与用户任务的匹配度，选择最合适的智能体或工作流，并向用户说明选择理由

⚠️ 【强制要求】在执行任何脚本之前，必须先读取对应的参考文档！ 这是避免参数错误的关键步骤。

• 调用 send_message.js 前 -> 必须先读取 $SKILL_DIR/references/bot/sendMessage.md
• 调用 run_workflow.js 前 -> 必须先读取 $SKILL_DIR/references/workflow/runWorkflow.md
• 其他脚本同理，否则极容易因为参数格式错误导致调用失败

3. 按对应流程依次执行预置脚本：
   • 智能体：create_session.js -> send_message.js -> check_status.js -> get_messages.js
   • 工作流：get_workflow_info.js -> run_workflow.js -> check_workflow_result.js（需要 workflow_id 和 execute_id 两个参数）
4. 每次执行脚本前，先 cd 到 $SKILL_DIR/scripts，再运行命令。示例：

   cd "$SKILL_DIR/scripts" && node create_session.js <bot_id>
   cd "$SKILL_DIR/scripts" && node send_message.js <conversation_id> <绝对路径>
   cd "$SKILL_DIR/scripts" && node check_status.js <conversation_id> <chat_id>
   cd "$SKILL_DIR/scripts" && node get_messages.js <conversation_id> <chat_id>
   

5. 临时文件必须放在 $SKILL_DIR/temp 目录，且参数文件路径必须使用绝对路径
6. 结果交付后清理临时文件：将执行结果交付给用户后，执行 clear_temp.js 清理 $SKILL_DIR/temp 目录（详细说明见 临时文件清理说明）

上传文件

当需要发送文件（图片、文档、音频、视频等）给智能体或工作流时，先上传文件：

详细说明参考 上传文件详细说明。

调用智能体 (Bot)

智能体调用采用四步流程：create_session.js → send_message.js → check_status.js → get_messages.js

详细调用流程、参数格式、输入输出示例、常见错误处理，参考：

• 完整流程：Bot API 调用索引
• send_message.js 详细参数：发送消息
• create_session.js：创建会话
• check_status.js：查询状态
• get_messages.js：获取回复

调用工作流 (Workflow)

工作流调用采用三步流程：get_workflow_info.js → run_workflow.js → check_workflow_result.js

详细调用流程、参数格式、输入输出示例、常见错误处理，参考：

• 完整流程：Workflow API 调用索引
• get_workflow_info.js：查询工作流信息
• run_workflow.js：执行工作流
• check_workflow_result.js：查询工作流结果

⏳ 轮询等待机制

当调用智能体或工作流时，由于它们是异步执行的，可能需要一段时间才能完成。AI 需要通过轮询来检查任务是否完成。

为什么需要等待？

• 智能体（Bot）：调用 send_message.js 后，智能体正在处理请求，状态可能为 in_progress
• 工作流（Workflow）：执行 run_workflow.js 后，工作流可能正在运行，状态可能为 Running

AI 需要等待多长时间？

首次查询等待时长（取 recent_durations 最小值）： 读取 $SKILL_DIR/config/bots.json（智能体）或 $SKILL_DIR/config/workflows.json（工作流），找到目标智能体/工作流的 recent_durations 数组。该数组记录了最近 6 次成功调用的端到端耗时（如 "28秒"、"1分15秒"）。取数组中的最小值（最短耗时），解析 "X秒"/"X分Y秒" 格式为秒数，作为首次查询的等待时长。调用发起脚本（send_message.js 或 run_workflow.js）后，等待该时长再调用查询脚本进行首次轮询。

边界：recent_durations 为空数组或不存在时（首次执行），从 .env 读取 POLLING_INTERVAL 作为首次查询等待时长；若 .env 不存在，则默认 5 秒。

后续轮询间隔（从 .env 读取 POLLING_INTERVAL）：

# 轮询间隔时间（单位：秒），默认5秒
POLLING_INTERVAL=5

• 默认值：5 秒
• 可自定义：用户可以修改此值来调整后续轮询间隔

不设超时上限：查询日志会体现任务成功或失败，任务最终会结束，无需超时熔断。重复查询直至任务完成或失败即可。

AI 在哪里检查它需要等待多长时间？

1. 智能体（Bot）：

调用 check_status.js 后，检查返回的 status 字段：

2. 工作流（Workflow）：

调用 check_workflow_result.js 后，检查返回的 execute_status 字段：

实现方式

脚本本身不包含自动等待逻辑，需要 AI 自行实现轮询。等待命令必须作为独立的一条命令执行，不能与轮询脚本拼接在同一条命令里。等待命令统一使用 bash 的 sleep N：

# 示例：智能体轮询（bash）
前一次查询: cd "$SKILL_DIR/scripts" && node check_status.js <conversation_id> <chat_id>
# 检查输出，如果 in_progress，先单独执行等待命令，再发起下一次查询
等待: sleep <POLLING_INTERVAL>
后一次查询: cd "$SKILL_DIR/scripts" && node check_status.js <conversation_id> <chat_id>

# 示例：工作流轮询（bash）
前一次查询: cd "$SKILL_DIR/scripts" && node check_workflow_result.js <workflow_id> <execute_id>
# 检查输出，如果 Running，先单独执行等待命令，再发起下一次查询
等待: sleep <POLLING_INTERVAL>
后一次查询: cd "$SKILL_DIR/scripts" && node check_workflow_result.js <workflow_id> <execute_id>

⚠️ 【致命重要】等待命令必须作为独立命令执行，禁止与轮询脚本拼接在同一条命令里！

等待是必须的：两次轮询之间必须等待，避免无意义的密集查询。

等待命令必须单独成一条命令，禁止用 ; 或 && 把等待命令与其他命令拼接。

• ❌ 错误（拼接在一条命令里，bash）：sleep <POLLING_INTERVAL> && cd "$SKILL_DIR/scripts" && node check_workflow_result.js <wf_id> <exec_id>（错误写法）
• ✅ 正确（分两条独立命令执行）：
  • 第 1 条命令（仅等待）：sleep <POLLING_INTERVAL>
  • 第 2 条命令（仅执行脚本）：cd "$SKILL_DIR/scripts" && node check_workflow_result.js <wf_id> <exec_id>

⚠️ 常见错误

⚠️ 重要：所有参数文件路径和用户输入文件路径都必须使用绝对路径，且临时文件必须放在 $SKILL_DIR/temp 目录下！

清理 temp 文件夹

在完成用户请求并将结果交付给用户后，执行 clear_temp.js 清理 $SKILL_DIR/temp 目录下的临时文件，防止文件堆积。

• 清理时机：每次独立请求完成、结果交付给用户之后执行
• 清理规则：由 clear_temp.js 脚本内部逻辑决定，文档不干涉

详细操作说明见 临时文件清理说明。

注意事项

1. 当 API 调用失败时，向用户提供清晰的错误信息
2. scripts 目录下的脚本在运行时如需创建临时文件，必须存放于 $SKILL_DIR/temp 目录中，不得与脚本文件混杂存放
3. 【强制规则】禁止绕过封装脚本直接调用扣子 HTTP API：凡是本技能已经封装过的 API（如创建会话、发送消息、查询状态、获取回复、上传文件、执行工作流等），AI 必须通过 $SKILL_DIR/scripts/ 下对应的封装脚本调用，严禁使用 Invoke-RestMethod、curl、fetch 等方式自行构造 HTTP 请求直接调用扣子平台 API。即使封装脚本因授权、限流等原因调用失败，也不得绕过脚本直接调用 API，应将错误信息如实反馈给用户。
4. 【发布提醒】如果用户的需求没有按照预期产出（如智能体返回无关内容、工作流结果不符合预期等），必须提醒用户检查扣子智能体或工作流是否已发布。 当用户修改了扣子智能体或工作流的配置后，必须重新发布才能使修改生效。只有已发布的智能体和工作流才会通过 API 生效，未发布的修改不会反映在 API 调用结果中。发布渠道选择API