首个COZE应用开发实战篇

背景

由于coze等智能体兴起，将脚本性项目（非复杂业务）平移到coze是一个不错的选择，由平台为你封装了流程与大模型相关，不仅可以实现组件化，获取到数据后，可以借助大模型进行一定的分析，也可轻松发布应用或者智能体。

初识coze

过去一年是大模型兴起的一年，Agent+项目也同时兴起，字节coze 也是同时兴起，字节变态的执行力，很快在Agent市场占有一席之地；

由于coze官网文档写的比较清晰，包括《使用指南》和《API 》再加上层出不穷的学习笔记，例如前字节AI产品经理，COZE深度开发者写了一篇《4万字教程-COZE/扣子与智能体入门》，所以笔者不在写全面教程，而是从一个新手入门实战项目中，重点攻克的问题出发，写今天这篇《首个COZE插件、workflow、应用开发》

准备工作

由于是个人学习使用，暂时使用基础版本，后期如果需要项目上线或者其他限制，再升级为专业版。

coze版本区别

功能模块	扣子基础版	扣子专业版
团队	每个基础版账号最多可创建 5 个团队。每个基础版团队人数上限为 50 人。	每个专业版账号最多可创建 10 个团队。每个专业版团队人数上限为 100 人。
知识库空间	1 GB，不支持扩容。	默认 10 GB，可购买额外的知识库空间。费用说明可参考知识库空间。
多人协作	基础版团队空间中，最多 3 个智能体、3 个应用和 3 个工作流可开启多人协作模式，每个智能体、工作流或应用最多可添加 5 位协作者。	专业版团队空间中，支持开启多人协作的智能体、应用和工作流的数量无限制，每个智能体、应用和工作流最多可添加 100 位协作者。
工作流	基础版每个工作流每天最多试运行 500 次，否则会报错。试运行工作流指在扣子平台工作流编排页面试运行工作流。	专业版不限制试运行工作流的次数，无免费试运行额度，按照每次试运行消耗的模型 token 计费。
API 流控	发起对话 API 的流控限制为 10 QPS。执行工作流、执行工作流（流式响应）、执行对话流 API 的流控限制为 100 QPS。 2024年8月15日之后，扣子 API 的免费额度为每个账号 100 次 API 调用。一旦累计调用次数超过免费额度，此账号将无法继续使用任何扣子 API。API 免费额度不适用于通过扣子平台、其他发布渠道或 SDK 产生的请求。	发起对话 API 的流控限制为 50 QPS。执行工作流、执行工作流（流式响应）、执行对话流 API 的流控限制为 100 QPS。
模型流控	基础版用户调用发起对话、执行工作流、执行工作流（流式响应）、执行对话流等涉及模型处理的 API 时，每个用户使用模型的频率受限。模型的流控限制为： QPS：2 QPM：60 QPD：3000	专业版模型的流控限制取决于火山方舟平台中设置的 RPM，最大可设置为 12000。设置方式可参考为扣子专业版接入模型。如需提高频控，可通过工单平台沟通需求。
SDK	Web SDK 的免费额度为每个账号 100 次对话。一旦累计对话次数超过免费额度，此账号将无法继续使用扣子 SDK。免费额度不适用于通过扣子平台、其他发布渠道或直接通过 API 发起的请求。	频控：不限制通过 SDK 和智能体对话的次数，但每个账号限制调用频率 RPM 12000。如需提高频控，可通过工单平台沟通需求。费用：使用 SDK 时，根据对话次数统计智能体调用次数，根据每次对话的 Token 统计方舟模型 Token费用。
方舟模型资源	不支持接入火山方舟模型资源。	模型列表：支持通过火山方舟接入模型资源，支持的模型可参考火山方舟文档。根据扣子专业版计费方式收费。频控：智能体调用频率限制 RPM 12000。如需提高频控，可通过工单平台沟通需求。费用：不限制智能体调用次数。在豆包中使用智能体不收取智能体调用费用，其他渠道根据扣子专业版计费方式收费。根据 Token 收取火山引擎方舟模型费用。
免费豆包模型	模型列表：支持豆包 Function call 等豆包免费模型版本。模型列表可参考大语言模型。免费额度：对于使用豆包模型的智能体，扣子基础版提供智能体调用次数免费额度 500次/天，用量超出免费额度之后不可调用智能体。 2024年8月15日之后，免费额度调整，使用豆包模型的智能体在豆包渠道不限制请求次数，在其他渠道限制请求次数 100次/天。	暂不支持豆包 Function call 等豆包免费模型版本，但可以付费使用方舟提供的豆包模型版本。
其他免费模型	模型列表：支持 Kimi、通义千问等模型，模型列表可参考大语言模型。不收取模型费用，但每日调用数量有一定限制。免费额度：对于使用Kimi、通义千问等免费模型的智能体，扣子提供智能体调用次数免费额度 100次/天，用量超出免费额度之后不可调用智能体。 2024年8月15日之后，免费额度调整为：通过扣子智能体商店、豆包、掘金调试或调用智能体时，限制调用 50次/天。通过抖音、微信、飞书渠道调用智能体调用次数限制调整为免费体验累计 100 次智能体调用，包括使用扣子支持范围内所有模型的智能体。	模型列表：支持 Kimi、通义千问等模型，模型列表可参考大语言模型。不收取模型费用，但每日调用数量有一定限制。免费额度：对于使用Kimi、通义千问等免费模型的智能体，扣子提供智能体调用次数免费额度 100次/天，用量超出免费额度之后不可调用智能体。

基本概念

了解COZE 中的插件、workflow、应用、Agent/Bot 等概念：

首先 COZE 存在形式有两种，一是应用、二是智能体，Agent/Bot都是智能体不同叫法。由于笔者需要做的是应用，所以本篇侧重应用实战。
插件概念：插件可以理解为单一功能的工具，需要注意的是，单一插件执行有超时限制。（支持python语音和nodejs）
注意：如果工作流或节点运行超时，智能体可能无法提供符合预期的回复。各场景的超时时间说明如下：
- 未开启工作流异步运行时，工作流整体超时时间为 3 分钟，模型节点 3 分钟，IDE 插件节点 1 分钟，其他类型的插件节点 3 分钟，其他节点 1 分钟。
- 开启工作流异步运行后，工作流整体超时时间为 24 小时，模型节点 5 分钟，IDE 插件节点 1 分钟，插件节点 3 分钟，其他节点 1 分钟。
- 一次对话中，智能体连续两次回复的时间间隔限制为 2 分钟。
- 由于插件超时问题，在爬虫项目中必须攻破，解决方案有几种：
  - 不用COZE插件（不可行，那就没必要迁移了）
  - 使用《流式插件配置教程》
  - 使用将插件原子化后使用循环插件（根据实现难易程度，笔者选择这种方式实现项目迁移）

实战

迁移插件

创建插件（由于原项目使用python，为减少不必要的迁移麻烦，依然选用python）
插件初始化代码

python 复制代码

import { Args } from '@/runtime';
import { Input, Output } from "@/typings/first/first";

/**
  * Each file needs to export a function named `handler`. This function is the entrance to the Tool.
  * @param {Object} args.input - input parameters, you can get test input value by input.xxx.
  * @param {Object} args.logger - logger instance used to print logs, injected by runtime
  * @returns {*} The return data of the function, which should match the declared output parameters.
  * 
  * Remember to fill in input/output in Metadata, it helps LLM to recognize and use tool.
  */
export async function handler({ input, logger }: Args<Input>): Promise<Output> {
  return {
    "message": "123",
    "data":"a_"+input.before
  };
};

初始方法handler 为插件入口和出口（Input, Output）
定义入参和出参字段（String、Integer、Number、Object、Array、Boolean）

代码迁移涉及的问题

避免使用本地文件写入，coze 对本地文件权限限制比较严格，只能读不能写，如必须使用本地文件，可以查/tmp/文件夹，且文件格式有一定要求，
创建 IDE 插件时，只支持在/tmp目录下读写临时文件，文件最大为 512MB。TMP_DIR = "/tmp"----参考
如果期望插件返回文件流，根据元数据支持的类型：String、Integer、Number、Object、Array、Boolean，暂时无法实现，可能需要通过base64或者其他手段曲折实现。

日志可以使用：args.logger输入到在线IDE中，可自测插件，插件测试通过后，可以选择发布到COZE商城。

创建workflow

循环节点的使用（有限循环，如果超出，参考超时限制）
循环中数据的传递（可以使用变量或者中间变量）
- 应用变量：用于配置应用中多处开发场景需要访问的数据，每次新请求均会初始化为默认值。
- 用户变量：用于存储每个用户使用项目过程中，需要持久化存储和读取的数据，如用户的语言偏好、个性化设置等。
- 系统变量：可选择开启你需要获取的，系统在用户在请求自动产生的数据，仅可读不可修改。如用于通过ID识别用户或处理某些渠道特有的功能。
- 中间变量：（循环组件特有）
循环体内可插入插件或其他
输入对象的格式化（简单逻辑可以用代码节点（比插件更方便））
最后是输出格式化后的数据到结束节点

创建应用

新增列表，数据绑定
新增事件（加载时，自动调用工作流）

Item点击事件：

成品参考1：预览&发布应用

优化：循环+变量传递数据，如果在数据量特别大的时候，可能有问题，笔者没试极限，为了防止这种情况发生，笔者还是将变量传递数据修改为本地文件（存+取）

其他功能：由于本项目循环执行，需要及时通知失败信息，需要接入微信、飞书、钉钉等在线及时推送

发布

参考

其他玩法

对话流使用（大模型）

简单插件实现大模型初始promt