一、插件简介

扣子工作流接口插件将迅睿CMS与扣子（Coze）AI工作流平台无缝集成，实现网站数据的自动化AI处理。插件负责接口对接与数据流转，具体的AI处理逻辑需在扣子平台自行编写工作流实现。

核心能力：

• 多套API配置管理，支持不同工作流独立对接
• 可视化参数映射，迅睿字段与扣子参数灵活对应
• 依托系统异步队列执行，不阻塞后台操作
• 完整的执行记录与日志追踪
• 超时自动检测、失败自动重试机制
• 支持所有迅睿CMS字段类型

二、安装与卸载

安装

1. 将插件目录 Cozeall 上传至 dayrui/App/ 目录
2. 登录迅睿CMS后台，进入「应用」→「应用管理」
3. 找到「扣子工作流接口」，点击「安装」
4. 安装完成后，后台左侧菜单出现「扣子工作流接口」菜单组

卸载

1. 进入「应用」→「应用管理」，找到「扣子工作流接口」
2. 点击「卸载」，系统将自动清理插件数据表和定时任务
3. 注意：卸载操作不可逆，所有API配置、工作流配置和执行记录将被永久删除

三、功能架构总览

扣子工作流接口
├── API配置管理        管理扣子平台的API连接凭据
│   ├── 配置名称       标识不同API配置
│   ├── API Token      扣子平台的认证令牌
│   ├── API地址        扣子API服务地址（默认 https://api.coze.cn）
│   ├── 工作流ID       扣子平台的工作流唯一标识
│   └── 数据来源       选择读取草稿表/待审表/正式表
│
├── 工作流配置管理     配置数据映射与执行参数
│   ├── 关联API配置    绑定上一步创建的API配置
│   ├── 绑定模块       选择要处理的迅睿CMS内容模块
│   ├── 发送参数       迅睿字段 → 扣子工作流输入参数
│   ├── 接收参数       扣子工作流输出 → 迅睿字段
│   └── 筛选条件       过滤需要处理的数据
│
├── 数据管理与入队     选择数据并提交到执行队列
│   ├── 数据列表浏览   查看模块中的数据及入队状态
│   ├── 单条入队       将单条数据加入执行队列
│   └── 批量入队       将多条数据批量加入执行队列
│
└── 执行记录管理       查看任务执行状态与结果
    ├── 统计概览       总记录/成功/失败/待执行/执行中
    ├── 状态筛选       按工作流、状态筛选记录
    ├── 移出队列       取消待执行的任务
    └── 清空记录       批量清理历史记录

四、快速上手

使用流程

第1步：注册扣子账号 → 创建工作流 → 获取API Token和工作流ID
         ↓
第2步：在插件中添加API配置（填入Token、工作流ID等）
         ↓
第3步：创建工作流配置（绑定模块、配置发送/接收参数映射）
         ↓
第4步：进入数据列表，选择数据入队
         ↓
第5步：系统自动执行，在执行记录中查看结果

最简配置示例

假设你想实现：将草稿文章的标题和内容发送给扣子，让AI优化后写回。

1. 添加API配置：填写扣子API Token和工作流ID，数据来源选"草稿表"
2. 添加工作流配置：
   • 关联上一步的API配置
   • 绑定模块选择你的内容模块（如"news"）
   • 发送参数：title（迅睿标题字段）→ title（扣子输入参数名），content → content
   • 接收参数：title（扣子输出参数名）→ title（迅睿标题字段），content → content
3. 入队执行：进入数据列表，勾选草稿数据，点击批量入队

五、API配置管理

进入后台「扣子工作流接口」→「API配置」，可管理所有扣子平台的API连接配置。

六、工作流配置管理

进入后台「扣子工作流接口」→「工作流管理」，可管理所有工作流配置。每个工作流配置绑定一个API配置和一个内容模块，定义了数据的发送和接收映射关系。

6.1 添加工作流

点击「添加工作流」按钮，填写以下信息：

| 字段 | 说明 | 是否必填 | |------|------|---------| | 工作流名称 | 标识此工作流配置，如"标题优化" | 是 | | 关联API配置 | 选择已创建的API配置，决定调用哪个扣子工作流 | 是 | | 绑定模块 | 选择要处理的迅睿CMS内容模块 | 是 | | 最大内容长度 | 发送内容字段的最大字符数，超出部分将被截断，默认3000 | 否 | | 状态 | 启用/禁用此工作流 | 否（默认启用） | | 排序 | 数字越小越靠前 | 否 |

选择模块后，系统会自动加载该模块的所有字段，供后续参数映射使用。

6.2 配置发送参数

发送参数定义了哪些迅睿CMS字段的数据发送给扣子工作流。

每行配置包含：

| 项目 | 说明 | |------|------| | 迅睿字段名 | 从下拉列表中选择模块字段（如 title、content） | | 迅睿字段类型 | 自动识别，如 Text、Textarea、Selects 等 | | 扣子参数名 | 对应扣子工作流的输入参数名称 | | 扣子参数类型 | 扣子工作流的参数类型，通常为 String |

配置要点：

• 扣子参数名必须与工作流中定义的输入参数名完全一致
• 至少需要配置一个发送参数
• 数组类型字段（如 Checkbox、Selects）会自动序列化为JSON字符串发送
• 内容字段超过最大长度限制时会被自动截断

6.3 配置接收参数

接收参数定义了扣子工作流返回的数据如何写入迅睿CMS字段。

每行配置包含：

| 项目 | 说明 | |------|------| | 扣子响应字段 | 扣子工作流输出中的字段名 | | 扣子字段类型 | 扣子输出的字段类型 | | 迅睿字段名 | 要写入的迅睿CMS模块字段 | | 迅睿字段类型 | 目标字段的类型，影响数据格式转换 |

配置要点：

• 至少需要配置一个接收参数
• 支持嵌套字段提取，使用点号分隔，如 output.title 可提取 {"output":{"title":"xxx"}} 中的值
• 系统会自动识别字段属于主表还是附表，分别更新
• 字段类型会自动适配（详见9.5 字段类型自动适配）

6.4 配置筛选条件

筛选条件用于过滤数据列表中显示的数据，帮助快速定位需要处理的内容。

支持的筛选类型：

| 类型 | 说明 | 示例 | |------|------|------| | 为空 | 字段值为空或NULL | 筛选标题为空的数据 | | 包含 | 字段值包含指定文本 | 标题包含"待优化" | | 长度小于 | 字段值字符长度小于指定值 | 内容长度<100（可能需要补充） |

注意： 筛选条件仅影响数据列表的显示过滤，不影响入队操作本身。

6.5 编辑与删除工作流

• 编辑：在工作流列表中点击「编辑」按钮，可修改所有配置项
• 删除：若工作流下还有执行记录，需先清空记录才能删除

七、数据管理与任务入队

工作流配置完成后，需要选择具体的数据提交到执行队列。

7.1 进入数据列表

在工作流列表中，点击对应工作流的「数据」按钮，进入该工作流的数据管理页面。

数据列表展示的是该工作流绑定模块中、对应数据来源表（草稿表/待审表/正式表）的数据。

7.2 单条入队

在数据列表中，每行数据右侧有「入队」按钮，点击即可将该条数据加入执行队列。

入队时系统会进行以下校验：

• 检查是否已在队列中（防止重复入队）
• 检查工作流配置是否启用
• 检查API配置Token是否有效
• 检查源数据是否真实存在
• 若数据来源为草稿表/待审表，还会检查正式表是否已存在相同标题的数据

7.3 批量入队

1. 勾选需要处理的数据（支持全选）
2. 点击列表上方的「批量入队」按钮
3. 系统会逐条校验并入队，最终显示成功和失败的数量

批量入队同样会进行重复检查和各项校验，已在队列中的数据会自动跳过。

7.4 数据列表状态说明

数据列表中每条数据会显示其入队状态：

| 状态 | 含义 | |------|------| | 待执行 | 已入队，等待系统自动执行 | | 执行中 | 正在调用扣子API处理 | | 成功 | 扣子工作流执行完成，数据已写回 | | 失败 | 执行失败，可查看错误信息 | | 未入队 | 尚未加入执行队列 |

八、执行记录管理

进入后台「扣子工作流接口」→「执行记录」，可查看所有任务的执行状态和详细日志。

8.1 记录列表与筛选

记录列表展示以下信息：

| 列 | 说明 | |----|------| | 记录ID | 系统自增ID | | 工作流名称 | 关联的工作流配置名称 | | 文章ID | 源数据的文章ID | | 标题 | 源数据的标题 | | 原始数据 | 发送给扣子前的数据快照 | | 保存数据 | 扣子处理完成后写回的数据 | | 状态 | 待执行/执行中/成功/失败 | | 完成时间 | 执行完成的时间 |

筛选功能：

• 按工作流筛选：选择特定工作流查看其执行记录
• 按状态筛选：选择待执行/执行中/成功/失败

8.2 统计概览

执行记录页面顶部显示统计卡片：

| 统计项 | 说明 | |--------|------| | 总记录 | 所有执行记录总数 | | 成功 | 状态为"成功"的记录数 | | 失败 | 状态为"失败"的记录数 |

8.3 移出队列

对于状态为「待执行」的记录，可以执行「移出队列」操作：

• 单条移出：点击记录的「移出队列」按钮
• 批量移出：勾选多条待执行记录，点击「批量移出队列」

移出队列后，记录状态变为「失败」，错误信息为"手动移出队列"，同时系统会删除对应的定时任务。

注意： 执行中的任务无法移出队列。

8.4 删除记录

• 单条删除：点击记录的「删除」按钮
• 批量删除：勾选多条记录，点击「批量删除」

限制： 执行中的任务无法删除，需等待执行完成后再操作。

8.5 清空记录

点击「清空记录」下拉按钮，支持以下选项：

| 选项 | 说明 | |------|------| | 清空成功记录 | 删除所有状态为"成功"的记录 | | 清空失败记录 | 删除所有状态为"失败"的记录 | | 清空所有记录 | 清空全部执行记录（执行中的任务需先等待完成） |

九、任务执行机制详解

9.1 队列执行流程

用户入队操作
    │
    ▼
创建执行记录（状态：待执行）
    │
    ▼
注册系统定时任务（cron）
    │
    ▼
系统定时触发 Cron\Execute.php
    │
    ▼
校验记录状态 → 更新为"执行中"
    │
    ▼
读取源数据 → 构建请求参数
    │
    ▼
调用扣子API（POST /v1/workflow/run）
    │
    ▼
解析响应数据 → 按接收参数映射写回
    │
    ▼
若来源为草稿/待审表 → 移动到正式表
    │
    ▼
更新记录状态为"成功"

9.2 数据流向说明

根据API配置中选择的「数据来源」不同，数据处理流向有所区别：

草稿表 → 正式表：

1. 从草稿表读取数据
2. 发送给扣子工作流处理
3. 将AI处理结果更新到草稿数据中
4. 将更新后的草稿数据移动到正式表（通过迅睿CMS内容模型保存）
5. 删除原草稿记录

待审表 → 正式表：

1. 从待审表读取数据
2. 发送给扣子工作流处理
3. 将AI处理结果更新到待审数据中
4. 将更新后的待审数据移动到正式表
5. 删除原待审记录

正式表 → 正式表（原地更新）：

1. 从正式表读取数据
2. 发送给扣子工作流处理
3. 将AI处理结果直接更新到正式表对应字段
4. 数据不移动，仅更新字段值

9.3 超时恢复与自动重试

插件内置了完善的超时检测和重试机制

恢复流程：

1. 系统定时任务（Cron.php）每次执行时，会扫描所有"执行中"且超过15分钟的记录
2. 若重试次数未达上限，将状态重置为"待执行"，自动重新入队
3. 若重试次数已达上限（3次），标记为"失败"，错误信息为"执行超时，已超过最大重试次数"

9.4 API调用与响应解析

请求格式：

POST {base_url}/v1/workflow/run
Headers:
  Authorization: Bearer {token}
  Content-Type: application/json
Body:
  {
    "workflow_id": "xxx",
    "parameters": {
      "参数名1": "值1",
      "参数名2": "值2"
    }
  }

响应解析策略： 插件会智能解析扣子API的响应数据，按以下优先级提取结果：

1. 直接字段匹配：在响应顶层查找接收参数中定义的字段名
2. 点号路径匹配：如 output.title 会逐层深入查找
3. 常见容器路径：自动在 output、data、result 等常见容器中查找
4. 深度JSON解码：自动解码响应中嵌套的JSON字符串

API调用容错：

• 连接失败自动重试（最多3次）
• HTTP 500/429错误自动重试
• 超时重试间隔递增（5秒、10秒、15秒）
• 单次请求超时240秒，连接超时30秒

9.5 字段类型自动适配

插件会根据迅睿CMS字段类型自动进行数据格式转换

十、典型应用场景

重要提示： 本插件只提供接口和数据处理逻辑，具体的应用功能需要自行在扣子平台编写工作流实现。

内容生产类

• 标题智能生成：根据产品参数、游戏参数自动生成吸引人的标题
• 内容摘要自动生成：长文章自动提取核心内容生成摘要
• SEO优化：文章发布前自动优化SEO关键词、描述

内容结构化

• 标签自动生成：文章自动打上分类标签、话题标签
• 智能分类推荐：新内容自动推荐最合适的栏目/分类

内容质量提升

• 内容纠错润色：草稿内容自动检查错别字、语法错误并修正
• 内容风格统一：不同编辑写的内容风格不统一，AI统一调性

多模态内容处理

• 图片描述生成：给上传的图片自动生成ALT标签、图片说明
• 视频内容提取：视频上传后，自动提取视频内容生成文字介绍

内容运营类

• 热门话题生成：根据近期热门话题自动生成话题文章
• 用户评论智能回复：热门评论自动生成回复模板

数据迁移与整合

• 外部内容聚合：从RSS订阅、API获取的外部内容，自动清洗整合
• 历史内容翻新：旧文章翻新重发，更新内容、优化标题
• 多平台内容适配：同一内容生成不同平台版本

电商/产品类

• 产品卖点提炼：产品参数自动生成吸引人的产品描述
• 用户评价智能汇总：用户评论自动生成好评汇总

基础应用

• 内容优化：草稿内容发送给扣子进行标题润色、摘要生成、SEO关键词提取，处理完成后自动写入正式表
• 多语言翻译：中文内容发布后，自动翻译并同步到多语言栏目
• 数据标准化：从第三方导入的数据经扣子清洗、补全、格式统一后，自动进入正式库
• 智能审核：对用户投稿进行敏感词检测、内容合规性检查，自动判断通过或退回

十一、注意事项

1. 本插件仅提供接口对接：具体的AI处理逻辑需在扣子平台自行编写工作流（也可找我们定制工作流），插件负责数据的读取、发送、接收和写回
2. API Token安全：Token是访问扣子平台的唯一凭据，请勿泄露给他人
3. 数据备份：批量操作前建议备份数据库，防止意外数据丢失
4. 执行频率：扣子平台有API调用频率限制，请合理控制入队数量，避免触发限流
5. 草稿/待审数据移动：从草稿表或待审表入队的数据，执行成功后会自动移动到正式表，原草稿/待审记录会被删除
6. 执行中任务不可操作：正在执行中的任务无法删除或移出队列，需等待执行完成或超时
7. 系统定时任务依赖：插件的异步执行依赖迅睿CMS的系统定时任务机制，请确保系统定时任务正常运行
8. 服务器网络：服务器需能正常访问 api.coze.cn，如使用国内服务器一般无问题，海外服务器可能需要确认网络连通性
9. PHP执行时间：单次工作流执行最长900秒（15分钟），超时将自动重试，超过3次标记为失败
10. 零核心修改：本插件完全基于迅睿CMS插件机制开发，不修