Coze 完全指南

Coze（扣子）是字节跳动推出的 AI Bot 开发平台，无需编程即可快速构建 AI 应用。通过可视化配置，你可以为 Bot 添加插件、知识库、工作流等能力，并一键发布到飞书、微信、Discord 等多个平台。

本文基于 Coze 国际版（coze.com）和国内版（coze.cn）编写。

平台对比#

根据需求选择版本。国内业务用国内版，海外业务用国际版。

快速入门#

创建第一个 Bot#

1. 访问 coze.com 或 coze.cn
2. 使用字节/Google 账号登录
3. 点击「创建 Bot」
4. 填写基本信息：
   • Bot 名称
   • Bot 描述
   • 选择模型

配置人设与提示词#

Bot 的核心是人设配置（System Prompt）：

# 角色
你是一位专业的前端开发助手，精通 React、Vue、TypeScript。

# 技能
- 解答前端技术问题
- 代码审查和优化建议
- 最佳实践推荐

# 限制
- 只回答前端相关问题
- 不涉及后端或运维内容
- 回复使用中文

Prompt 技巧：

• 明确角色定位
• 列出具体技能
• 设置边界限制
• 提供回复示例

调试与测试#

配置完成后，在右侧预览区直接对话测试：

用户：React 和 Vue 有什么区别？
Bot：React 和 Vue 的主要区别包括：
1. 设计理念：React 偏函数式，Vue 偏声明式...

反复测试和调整 Prompt，直到效果满意。

插件系统#

插件让 Bot 具备「行动能力」，可以调用外部 API、执行操作。

内置插件#

Coze 提供了丰富的内置插件：

添加插件：Bot 配置 → 插件 → 添加插件 → 选择需要的插件。

自定义插件#

当内置插件无法满足需求时，可以创建自定义插件：

1. 创建插件

工作空间 → 插件 → 创建插件

2. 定义 API

{
  "name": "get_stock_price",
  "description": "获取股票实时价格",
  "parameters": {
    "type": "object",
    "properties": {
      "symbol": {
        "type": "string",
        "description": "股票代码，如 AAPL"
      }
    },
    "required": ["symbol"]
  }
}

3. 配置接口

填写 API 地址、请求方式、认证信息。

4. 测试发布

在插件调试页面测试，通过后发布到 Bot。

插件开发最佳实践#

• 功能单一：一个插件只做一件事
• 描述清晰：让 LLM 理解何时调用
• 参数明确：使用 JSON Schema 定义
• 错误处理：返回友好的错误信息

知识库#

知识库让 Bot 具备「记忆能力」，可以基于你的私有数据回答问题。

创建知识库#

1. 工作空间 → 知识库 → 创建知识库
2. 上传数据源：
   • 本地文件（PDF、Word、TXT、Markdown）
   • 网页链接
   • API 接口
   • 飞书文档

数据处理#

上传后系统会自动：

1. 文档解析：提取文本内容
2. 文本切分：按段落/句子切分
3. 向量化：生成 Embedding
4. 存储索引：便于检索

切分策略选择：

关联到 Bot#

Bot 配置 → 知识库 → 选择知识库 → 配置召回策略

召回参数：

• Top K：返回最相关的 K 条结果
• 相似度阈值：低于阈值的不返回
• 召回模式：精确匹配/语义匹配

工作流#

工作流用于编排复杂的多步骤任务，实现高级业务逻辑。

工作流节点#

示例：智能客服工作流#

[开始] → [意图识别 LLM] → [条件分支]
                              ├── 技术问题 → [知识库检索] → [LLM 回复]
                              ├── 投诉建议 → [创建工单插件] → [LLM 回复]
                              └── 其他 → [通用 LLM 回复]
                                                  ↓
                                              [结束]

变量传递#

节点间通过变量传递数据：

// 代码节点示例
async function main({ params }) {
  const { user_query, search_results } = params

  // 处理数据
  const processed = search_results.map((r) => r.content).join('\n')

  return {
    context: processed,
    query: user_query,
  }
}

多平台发布#

Coze Bot 可以发布到多个平台：

国际版支持平台#

• Discord Bot
• Telegram Bot
• Slack App
• Web 网页嵌入
• API 调用

国内版支持平台#

• 飞书机器人
• 微信公众号
• 微信客服
• 网页嵌入
• API 调用

发布流程#

1. Bot 配置 → 发布
2. 选择目标平台
3. 按引导完成授权
4. 配置触发方式
5. 上线发布

Web 嵌入#

将 Bot 嵌入到网站：

<!-- 嵌入代码 -->
<script src="https://lf-cdn.coze.cn/obj/xxx/widget.js"></script>
<script>
  CozeWebSDK.init({
    botId: 'your_bot_id',
    // 其他配置
  })
</script>

API 调用#

通过 API 集成 Bot 到自己的应用：

获取 API Key#

个人设置 → API 密钥 → 创建密钥

对话接口#

curl -X POST https://api.coze.com/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your_bot_id",
    "user_id": "user_123",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

流式响应#

const response = await fetch('https://api.coze.com/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bot_id: 'your_bot_id',
    user_id: 'user_123',
    stream: true,
    messages: [{ role: 'user', content: '你好' }],
  }),
})

const reader = response.body.getReader()
// 处理流式数据...

实战案例#

案例一：技术文档问答 Bot#

需求：基于产品文档回答用户问题

配置：

1. 创建知识库，上传产品文档
2. 配置人设为「产品技术支持」
3. 关联知识库，设置召回策略
4. 添加「无法回答时」的兜底逻辑

案例二：订单查询 Bot#

需求：用户输入订单号，返回订单状态

配置：

1. 创建自定义插件对接订单系统
2. 工作流：提取订单号 → 调用插件 → 格式化回复
3. 发布到微信客服

案例三：AI 写作助手#

需求：辅助创作、润色文章

配置：

1. 人设设定为「资深编辑」
2. 添加写作相关 Prompt 模板
3. 启用多轮对话，支持持续修改
4. 发布为 Web 工具

Coze vs Dify vs GPTs#

选择建议：

• 快速上手、国内业务 → Coze
• 需要自部署、定制化 → Dify
• GPT 生态、海外用户 → GPTs

常见问题#

Bot 回复不准确#

1. 优化 Prompt，更具体
2. 调整模型参数（temperature 降低）
3. 知识库召回策略调整
4. 添加示例对话

插件调用失败#

1. 检查 API 地址是否可访问
2. 确认参数格式正确
3. 查看插件调用日志
4. 测试 API 响应

知识库检索不到内容#

1. 检查文档是否处理完成
2. 调整切分策略
3. 降低相似度阈值
4. 优化查询方式

参考资料#

• Coze 官方文档
• Coze 国内版
• Coze API 文档
• Coze 插件开发