coze开发基础

基础概念体系

• 工作流是一系列可执行指令的集合，用于实现业务逻辑或完成特定任务。它为应用/智能体的数据流动和任务处理提供了一个结构化框架。工作流的核心在于将大模型的强大能力与特定的业务逻辑相结合，通过系统化、流程化的方法来实现高效、可扩展的 AI 应用开发。扣子提供了一个可视化画布，你可以通过拖拽节点迅速搭建工作流。同时，支持在画布实时调试工作流。在工作流画布中，你可以清晰地看到数据的流转过程和任务的执行顺序。两种典型工作流：

  • 工作流（Workflow）：用于处理功能类的请求，可通过顺序执行一系列节点实现某个功能。适合数据的自动化处理场景，例如生成行业调研报告、生成一张海报、制作绘本等。

  • 对话流（Chatflow）：是基于对话场景的特殊工作流，更适合处理对话类请求。对话流通过对话的方式和用户交互，并完成复杂的业务逻辑。对话流适用于 Chatbot 等需要在响应请求时进行复杂逻辑处理的对话式应用程序，例如个人助手、智能客服、虚拟伴侣等。

  • 概念	定义	核心特征
    工作流 (Workflow)	一系列可执行指令的集合，实现业务逻辑或特定任务	顺序执行节点、自动化处理、功能类请求处理
    对话流 (Chatflow)	基于对话场景的特殊工作流	交互式对话、复杂逻辑处理、用户意图响应
    智能体 (Agent)	能独立执行任务、决策并学习的自动化程序	自主调用技能（模型 / 知识库 / 插件）、局部任务处理
    空间 (Space)	资源组织的基础单元	资源隔离、多项目管理、共享资源库
    资源库 (Resource)	存储和管理共享资源的容器	支持插件 / 知识库 / 数据库 / 提示词、分空间级和项目级

• 空间包含智能体、AI 应用和资源库；AI 应用包含项目专属资源；工作流由节点组成（开始 / 结束 / 功能节点），智能体可调用工作流作为技能；工作流可引用资源库中的插件 / 知识库；多 Agent 通过跳转条件协同处理复杂任务，工作流（全局流程）> 智能体（局部任务）；空间资源库（全局共享）> 项目资源库（局部私有）。

技术细节与核心参数

• 工作流的核心在于节点，每个节点是一个具有特定功能的独立组件，代表一个独立的步骤或逻辑。这些节点负责处理数据、执行任务和运行算法，并且它们都具备输入和输出。每个工作流都默认包含一个开始节点和一个结束节点。开始节点是工作流的起始节点，定义启动工作流需要的输入参数。结束节点用于返回工作流的运行结果。

  • 组件类型	核心功能	支持变量类型
    开始节点	定义启动工作流的输入参数（如用户输入、文件等）	String/Integer/Number/Boolean/Object/File/Array
    处理节点	包含大模型节点（文本生成）、插件节点（API 调用）、代码节点等	同上
    逻辑控制节点	选择器节点（条件分支）、循环节点、批处理节点等	同上
    结束节点	整合输出结果，支持 JSON 或自然语言格式	同上

• 理解工作流的四个核心组件：开始节点定义输入参数，如用户上传的原始照片或文案主题；处理节点包含大模型节点（文本生成）、插件节点（外部API调用）、图像处理节点等；逻辑控制节点选择器节点实现条件分支；结束节点整合输出结果，支持JSON格式变量返回或自然语言总结

• 通过引用节点输出，你可以将节点连接在一起，形成一个无缝的操作链。例如，你可以在代码节点的输入中引用大模型节点的输出，这样代码节点就可以使用大模型节点的输出。在工作流画布中，你可以看到这两个节点是连接在一起的。

• 工作流的开始节点、结束节点、输出节点、插件节点、子工作流节点、代码节点、SQL 自定义节点、新增数据节点、查询数据节点、更新数据节点、删除数据节点、问答节点、批处理节点、循环节点、变量聚合节点、变量节点、选择器节点均支持多种变量类型，包括 String、Integer、Number、Boolean、Object、File 和 Array等。你可以根据实际需求灵活选择合适的数据类型，而无需额外的数据转换，从而提升工作流编排的灵活性和扩展性。

• 智能体和工作流的区别

  • 智能体（AI Agent），智能体是一个自动化的“助手”，用来执行特定任务。它擅长做一些具体的、重复性的任务，比如客服聊天、推荐商品、处理订单等。
  • 工作流（Workflow），工作流是一系列任务的流程，决定了每个步骤应该做什么，就像一本操作指南，告诉你从头到尾要怎么做。工作流可以处理一个完整的过程，比如从客户下单、付款到发货和售后服务，涵盖了所有步骤和环节。

• 在业务中，通常需要的是工作流而非单个智能体，因为整个业务流程设计至关重要。工作流是全局的，智能体是局部的。

• 扣子是新一代 AI 应用开发平台。借助扣子提供的可视化设计与编排工具，你可以通过零代码或低代码的方式，快速搭建出基于大模型的各类 AI 项目，满足个性化需求、实现商业价值。

• 空间是资源组织的基础单元，不同空间内的资源和数据相互隔离。一个空间内可创建多个智能体和 AI 应用，并包含一个资源库。在资源库中创建的资源可以被相同空间内的智能体和 AI 应用使用。项目分为智能体和 AI 应用两种类型，AI 应用内可以创建多种应用专属资源，也可以和智能体共享空间资源库中的资源。

  • 智能体（Agent）通常指的是一个能够独立执行任务、做出决策并进行学习的一种自动化程序。智能体可以根据用户输入的指令，自主调用模型、知识库、插件等技能并完成编排，最终完成用户的指令。
  • AI 应用是指利用大模型技术开发的应用程序，这些应用程序能够使用大模型，执行复杂任务，分析数据，并作出决策。

• 在资源库内创建、发布、管理共享资源，例如插件、知识库、数据库、提示词等。这些资源可以被同一空间内的智能体和应用使用。资源可以存在于两个实体内，一个是空间的资源库，一个是 AI 应用项目中的项目资源库。

  • 空间资源库内创建的资源可以被空间内的 AI 应用项目和智能体项目使用，属于空间内的共享资源。
  • AI 应用项目中也可以创建资源，但这些资源是项目自有的资源，默认不可以被其他项目使用也不会展示在空间资源库内。当需要将 AI 应用项目中的资源转换成公共资源给其他 AI 应用或智能体使用时，可以将这些资源转移或复制到空间资源库内。

• 工作流是一种以低代码方式开发插件的方法。你可以将各种节点添加到工作流中，并像为智能体添加插件一样，添加并使用工作流。多 Agent 模式允许您通过将不同的人物设定分配给不同的 Agent 来扩展智能体的功能。用户与一个 Agent 交谈时，当用户输入的内容满足跳转条件时，对话将移交给另一个 Agent 进行处理。多 Agent 模式更适合处理复杂的任务。

• 用于从多个维度调整不同模型在生成内容时的随机性。扣子提供以下预置的模式供你选择，每个模式的模型参数取值不同。精确模式：模型的输出内容严格遵循指令要求，可能会反复讨论某个主题，或频繁出现相同词汇。平衡模式：模型的输出内容更具随机性和准确性。创意模式：模型的输出内容更具多样性和创新性，某些场景下可能会偏离主旨。也可以根据需求，展开高级设置，修改每个模式下的具体参数值。建议不要同时调整生成随机性和 Top P，以免在多参数的影响下难以判断每个参数的调整效果。避免同时调整 temperature 和 Top P，优先通过单一参数控制多样性；根据任务类型选择预置模式（精确 / 平衡 / 创意）后再微调。

  • 参数名称	作用机制	调优影响	典型场景建议值
    生成随机性 (temperature)	控制输出多样性，值越高随机性越强	高值：创新但可能偏离主题；低值：严谨但可能重复	创作类（0.7-0.9）；事实问答（0.1-0.3）
    Top P	累计概率阈值，限制模型选择高概率词汇组合	高值（0.9）：多样性高；低值（0.5）：输出更集中	通用场景（0.7-0.8）；精准任务（0.5-0.6）
    重复语句惩罚 (frequency penalty)	阻止频繁使用相同词汇短语	正值越高：重复内容越少，可能影响连贯性	长文本生成（0.2-0.5）；短问答（0-0.1）
    重复主题惩罚 (presence penalty)	阻止频繁讨论相同主题	正值越高：主题切换越频繁，可能分散重点	多主题创作（0.3-0.6）；单主题深入（0-0.2）

• 基础概念： 触发器（Trigger）、节点（Node）、分支（Branch）、变量（Variable）、意图识别、插件使用等。设计思路： 如何构建特定场景的工作流？（例如：信息查询、多步骤交互、外部 API 调用、数据库操作、异常处理等）。节点详解： 特定节点的功能、配置参数说明（LLM 节点、函数节点、代码节点、API 调用节点、数据库节点、条件分支节点、消息节点等）。变量操作： 如何定义、赋值、修改、传递变量？作用域问题？数据类型处理？流程控制： 如何实现条件判断（if/else）、循环？如何使用分支和汇聚？集成与插件： 如何使用插件（如搜索、天气、知识库）？如何调用外部 API？如何操作数据库？调试与排错： 工作流运行报错怎么办？如何查看执行日志？如何定位变量问题或逻辑错误？性能优化： 如何提高工作流的响应速度？减少不必要的 LLM 调用？优化复杂逻辑？最佳实践： 模块化设计、错误处理规范、日志记录规范、安全注意事项等。与 Bot 结合： 如何在工作流中调用 Bot 技能？如何将工作流结果返回给用户？高级技巧： 异步操作、流式输出、使用临时存储、复杂的业务逻辑实现等。

同类平台对比分析

• 工作流 (Workflows)学习设计任务逻辑。知识库 (Knowledge Base)学习如何让 Agent 拥有专业知识。插件 (Plugins)学习如何连接外部世界。

• 平台	定位差异	核心优势	劣势	适用场景
  Coze	大模型原生 AI 应用开发平台	可视化工作流编排、多 Agent 协作、资源库管理一体化、与字节生态集成	生态相对较新，第三方插件数量有限	企业级 AI 应用、对话机器人、复杂业务流程自动化
  Dify	LLM 应用快速开发平台	极简界面、Prompt 工程优化、模型集成丰富（支持开源模型）	复杂流程编排能力较弱	快速验证 LLM 应用想法、简单对话机器人
  N8N	通用工作流自动化平台	海量第三方服务集成、强大的流程逻辑控制、开源可自部署	大模型原生支持较弱，需额外集成	跨系统数据同步、传统业务流程自动化
  LangFlow	基于 LangChain 的可视化工具	开源免费、深度集成 LangChain 生态、灵活的自定义组件	需一定技术背景，企业级支持较弱	开发者实验性项目、LangChain 生态应用

工作流创建与发布步骤

• 工作流是一系列可执行指令的集合，用于实现业务逻辑或完成特定任务。你可以在智能体和应用搭建中通过工作流实现特定的任务或指令。无论是在智能体还是应用中使用工作流，都需要先创建一个可运行的工作流。

  • 创建工作流，在页面顶部选择目标工作空间，然后在左侧导航栏中单击资源库。在资源库页面右上角，选择 +资源 > 工作流。设置工作流的名称与描述，并单击确认。开始节点用于启动工作流。结束节点用于返回工作流的运行结果。

  • 编排工作流，创建工作流后，你在画布中添加节点，并按照任务执行顺序连接节点。工作流内置了多种基础节点供你使用，同时你还可以添加插件节点来执行特定任务。如果你在插件商店中收藏了某些插件，则添加节点面板中将自动展示你所收藏的插件，便于你直接调用。

  • 测试并发布工作流，要想在智能体内使用该工作流，则需要发布工作流。如果输入参数包含图片、视频等文件类型，试运行时可以上传文件或输入文件 URL。运行成功的节点边框会显示绿色，在各节点的右上角可查看节点的输入和输出。

• 资源管理策略，空间资源库：创建公共资源（插件 / 知识库），供所有项目使用，项目资源库：创建应用专属资源，需转移到空间库才能共享，插件使用：收藏常用插件→自动显示在节点面板→直接拖拽调用。

书籍解读视频生成工作流

• 需求定义：输入书籍名称，输出3-5 分钟读书解读视频（包含语音旁白、文字摘要、相关配图）

• 作流节点设计：

  • 节点类型	功能描述	调用资源 / 工具	参数配置
    开始节点	接收用户输入的书名	-	输入参数：book_name（String 类型）
    插件节点	获取书籍基本信息（作者、简介、核心观点）	图书信息 API 插件	输入：book_name；输出：book_info（Object 类型）
    大模型节点	生成 3-5 分钟解读文案（结构：引言→核心观点→案例→总结）	大模型（如 GPT-4）	模式：平衡模式；temperature=0.6；Top P=0.7；提示词：“基于 {book_info} 生成口语化解读文案，控制在 500 字左右”
    插件节点	将文案转换为语音旁白	文本转语音插件	输入：文案内容；输出：audio_file（File 类型）；参数：语速 = 1.0，音色 = 中性
    插件节点	根据书籍主题生成配图（3-5 张）	图像生成插件（如 Midjourney）	输入：book_info. 主题 + 文案片段；输出：images（Array）；风格 = 简约插画
    插件节点	合成视频（语音 + 配图 + 文字字幕）	视频编辑插件	输入：audio_file+images + 文案；输出：final_video（File 类型）；时长 = 3-5 分钟
    结束节点	返回最终视频文件	-	输出：final_video（File 类型）

• 数据流转：书名→书籍信息→解读文案→语音 / 图像→视频合成；逻辑控制：若图书信息 API 调用失败，通过选择器节点跳转至 “提示用户确认书名” 分支。参数优化：大模型节点采用平衡模式保证解读准确性与流畅度；图像生成插件通过增加 “教育类” 标签约束风格

• 触发启动：用户输入书名（触发器：用户输入触发工作流启动）；数据承载：书名存储为变量book_name（变量：在节点间传递）；任务执行：插件节点调用 “图书信息 API”，输入book_name，输出book_info（节点 + 变量 + 插件联动），LLM 节点基于book_info生成解读文案（节点 + 变量联动）；逻辑分支：若 API 调用失败（book_info为空），选择器节点跳转至 “提示用户确认书名” 分支（分支 + 节点联动）；结果输出：最终视频文件通过结束节点返回（节点 + 变量联动）

• 核心功能元素（工作流的 “原子组件”），是构建工作流的基础单元，决定了流程的启动、执行、数据流转和结果输出。

  • 概念	定义	核心作用	关键特性
    触发器（Trigger）	工作流的 “启动开关”，定义工作流何时 / 如何被触发执行	决定工作流的启动条件（如用户输入、定时任务、外部事件）	支持手动触发（测试）、自动触发（用户输入匹配、API 调用）、定时触发（ cron 表达式）
    节点（Node）	工作流中具有独立功能的最小单元，是任务执行的具体载体	执行具体操作（如文本生成、API 调用、数据处理、逻辑判断）	每个节点有明确输入（接收数据）和输出（产生数据），通过连接线传递数据
    变量（Variable）	存储和传递数据的 “容器”，用于在节点间共享信息	实现数据在工作流中的流转和复用（如用户输入、中间结果、最终输出）	支持多类型（String/File/Array 等），有明确作用域（局部 / 全局）
    分支（Branch）	工作流中基于条件拆分的不同执行路径	处理复杂逻辑中的多场景（如 “成功 / 失败” 分支、“不同用户类型” 分支）	由逻辑控制节点（如选择器）创建，可独立执行后汇聚到同一节点

• 变量是工作流中数据的 “载体”，其操作直接影响流程正确性。全局变量：在开始节点定义（如book_name），全工作流可见；局部变量：在节点内临时定义（如代码节点中计算的word_count），仅节点内有效；动态变量：节点输出自动生成（如 API 节点返回的book_info）

• 变量赋值与修改，直接赋值：通过 “变量节点” 手动设置（如status = "processing"）；动态赋值：节点输出自动覆盖变量（如 LLM 节点输出script，直接赋值给video_script）；计算赋值：代码节点中通过逻辑计算修改（如total_time = 3 * len(images)）

• 作用域规则：子工作流变量默认不共享，需通过 “变量聚合节点” 传递到父流程。类型约束输入变量类型必须与节点要求匹配（如 API 节点需String类型的书名，不可传入Number）

• 流程控制：实现复杂逻辑的关键，通过分支、循环等控制节点，使工作流能处理多场景、多步骤任务。

  • 控制类型	实现方式	应用场景	注意事项
    条件判断	选择器节点配置多组条件（如if A then 分支1 else 分支2）	错误处理（API 成功 / 失败）、场景区分（新用户 / 老用户）	需覆盖所有可能情况，建议设置 “默认分支” 避免流程中断
    循环执行	循环节点绑定数组变量，遍历执行子流程（如for book in books）	批量处理（生成多本书籍解读）、重试机制（API 调用失败后重试 3 次）	限制循环次数（如最多 5 次），避免死循环
    分支汇聚	多分支流程最终连接到同一节点（如 “成功分支” 和 “失败分支” 均连接到 “日志记录” 节点）	统一处理结果（无论成功 / 失败均记录日志）	汇聚前需确保变量格式一致（如均输出result变量）

• 工作流与 Bot 的协同，Bot 调用工作流：将工作流设为 Bot 的 “技能”，Bot 接收用户指令后自动触发工作流（如用户说 “解读《三体》”，Bot 调用 “书籍解读工作流”），工作流通过 “消息节点” 将结果返回给 Bot，再由 Bot 呈现给用户（支持文本、文件、图片）

  • 基础层：触发器（启动）→ 节点（执行）→ 变量（数据）→ 分支（逻辑）
  • 扩展层：意图识别（理解）→ 插件/API（扩展）→ 数据库（存储）
  • 控制层：条件判断 → 循环 → 分支汇聚
  • 优化层：调试排错 → 性能优化 → 最佳实践
  • 应用层：与Bot结合 → 高级技巧（异步/流式）