基于扣子（Coze）工作流 API 的微信小程序开发实践总结

在 AI 应用逐渐产品化的背景下，如何将大模型能力安全、稳定地接入小程序端，成为一个非常典型的工程问题。本文以我近期完成的一个示例微信小程序项目 「祝福暖语铺」 为例，分享一次 基于扣子（Coze）工作流 API 的完整落地实践，涵盖整体架构、工作流调用方式、SSE 流式处理、云函数安全设计等关键点。

---

一、项目概述

祝福暖语铺 是一个基于 微信小程序 + 云开发 的智能祝福语生成器。

项目通过 扣子（Coze）工作流 API（也可替换为扣子智能体工作流 API），根据用户选择的节日类型和情感类型，动态生成个性化祝福语，适用于春节、情人节、母亲节等多种场景。

核心能力

• 🎉 多节日、多情感组合生成祝福语
• 🤖 基于 Coze 工作流的 AI 内容生成
• 🔐 云函数调用，前端不暴露任何 API Token
• 🌊 支持 SSE 流式返回，提升用户体验

项目预览

---

二、项目整体结构

项目采用标准的小程序 + 云开发结构，逻辑清晰、便于扩展：

BestWishes_workflow/
├── app.js                 # 小程序入口
├── app.json               # 全局配置
├── pages/                 # 页面目录
│   ├── index/             # 首页：参数选择 & 生成入口
│   ├── preview/           # 预览页：展示生成的祝福语
│   ├── myrecords/         # 我的记录：历史祝福语
│   └── ...
├── utils/                 # 工具函数
├── images/                # 静态资源
├── cloudfunctions/        # 云函数
│   └── generateWorkflow/  # 调用 Coze 工作流的核心云函数
└── ...

---

三、扣子（Coze）工作流调用机制

1. 前端调用流程

整体调用链路如下：

1. 用户交互
   用户在首页选择节日、情感类型等参数

2. 参数构建
   前端将选择项转换为结构化参数

3. 云函数调用
   使用 wx.cloud.callFunction 调用云函数

4. 工作流请求
   云函数向 Coze 工作流 API 发起请求

5. 结果返回
   云函数解析结果并返回给小程序端

---

2. 参数映射设计

为了让工作流 Prompt 更友好，前端将选项值映射为自然语言描述：

// 节日映射
const festivalNames = {
  spring_festival: '春节',
  new_year: '元旦',
  valentine: '情人节',
  mothers_day: '母亲节',
  fathers_day: '父亲节',
  christmas: '圣诞节'
};

// 情感映射
const emotionNames = {
  blessing: '祝福',
  gratitude: '感谢',
  commemorate: '纪念',
  care: '关怀',
  encouragement: '鼓励'
};

这样可以避免在工作流中出现大量业务判断，让 Prompt 更聚焦内容生成本身。

---

四、SSE 流式返回处理与页面展示

1. 为什么选择 SSE？

扣子工作流 API 支持 流式返回（Server-Sent Events），相比一次性返回：

• 响应更快
• 用户等待感更低
• 适合长文本生成场景

---

2. 云函数中的 SSE 处理流程

在云函数中主要做了以下处理：

1. 监听流事件

   • data
   • end
   • error

2. 解析 SSE 格式

   • 按行解析 id:、event:、data:

3. 事件过滤

   • 只处理 Message 类型事件

4. 双层 JSON 解包

   • SSE 数据本身是 JSON
   • 内部 content 仍是 JSON 字符串

---

3. 页面展示逻辑

前端接收到最终文本后：

• 📄 在预览页展示祝福语内容
• 💾 自动保存到本地历史记录
• ⏳ 显示加载状态 & 错误提示

整体体验接近「AI 实时生成」。

---

五、核心云函数：generateWorkflow

generateWorkflow 是整个项目的核心，专门负责与 Coze 工作流交互。

1. 环境变量配置

所有敏感信息均通过云函数环境变量注入：

• COZE_TOKEN：Coze API Token
• WORKFLOW_ID：工作流 ID

const token = process.env.COZE_TOKEN;
const workflowId = process.env.WORKFLOW_ID;

---

2. 工作流 API 调用示例

const response = await axios.post(
  '替换为你的真实的扣子工作流访问路径',
  {
    workflow_id: workflowId,
    parameters: {
      input: workflowInput
    }
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    responseType: 'stream',
    timeout: 30000
  }
);

• 使用 responseType: 'stream' 接收 SSE
• 避免前端直接调用第三方 API

---

3. 安全设计要点

• 🔐 Token 只存在于云函数
• 🚫 前端不直连 Coze API
• 🧱 参数校验 + 错误兜底
• 📛 出错时不返回敏感信息

---

六、云开发与部署配置

云开发配置

• 使用 wx.cloud.callFunction 调用
• 云函数环境变量统一在控制台管理

部署注意事项

• cloudfunctionRoot: cloudfunctions/
• 云函数超时时间需适配流式响应
• 确保 Node 版本支持 stream 处理

---

七、项目特色与实践总结

项目亮点

1. 安全性高
   完全符合「前端无密钥」原则

2. 体验友好
   SSE 流式返回，生成过程可感知

3. 可扩展性强
   新节日 / 新情感只需配置映射

4. 工程化落地
   AI 能力真正进入业务，而非 Demo

---

八、注意事项

• 提前配置云函数环境变量
• 注意 Coze API 的调用频率限制
• 流式解析需做好异常处理

---

结语

这次项目实践让我对 「AI 工作流 + 小程序 + 云函数」 的组合有了更清晰的认知。
如果你也在考虑 将 Coze 工作流能力落地到真实产品中，希望这篇总结能对你有所帮助。

👉 有任何问题或想法，欢迎在评论区交流讨论。