# Coze-Lovable 函数调用规范

**版本**: 2.0.0  
**更新时间**: 2026-02-03

---

## 🎯 核心要求

**Coze AI 必须返回以下 JSON 格式，前端会自动解析并路由到工作台：**

```json
{
  "answer": "简洁的文字回答（显示在聊天框）",
  "ui_schema": {
    "layout": "vertical",
    "gap": "md",
    "components": [
      { "type": "组件类型", "props": { ... } }
    ]
  },
  "agent_type": "manager|product|marketing|finance|service",
  "suggested_actions": ["建议操作1", "建议操作2"]
}
```

---

## 📋 组件类型速查表

| 组件类型 | 用途 | props 必填字段 |
|---------|------|---------------|
| `stats_row` | 统计指标行 | `items: [{label, value, trend?, icon?}]` |
| `data_table` | 数据表格 | `title, columns: [{key, label}], rows: [{...}]` |
| `chart` | 图表 | `chartType: "pie"|"bar"|"line"|"area", data: [{name, value}]` |
| `alert` | 警告提示 | `type: "info"|"warning"|"error"|"success", message` |
| `insight_card` | 洞察卡片 | `title, description, type?, action?` |
| `progress_bar` | 进度条 | `label, value (0-100), color?` |
| `text` | 文本块 | `content, variant?: "default"|"muted"|"heading"` |
| `approval_list` | 审批列表 | `items: [{id, title, description, status, created_at}]` |

---

## ✅ 正确示例

### 查询客户列表
```json
{
  "answer": "已为您查询到客户信息列表。",
  "agent_type": "manager",
  "ui_schema": {
    "layout": "vertical",
    "gap": "md",
    "components": [
      {
        "type": "stats_row",
        "props": {
          "items": [
            { "label": "总客户数", "value": "156", "trend": "+12%" },
            { "label": "活跃客户", "value": "89", "trend": "+5%" },
            { "label": "新增本月", "value": "23", "trend": "+8%" }
          ]
        }
      },
      {
        "type": "data_table",
        "props": {
          "title": "客户信息列表",
          "columns": [
            { "key": "name", "label": "客户名称" },
            { "key": "email", "label": "邮箱" },
            { "key": "phone", "label": "电话" },
            { "key": "status", "label": "状态" }
          ],
          "rows": [
            { "name": "张三", "email": "zhang@example.com", "phone": "138****1234", "status": "活跃" },
            { "name": "李四", "email": "li@example.com", "phone": "139****5678", "status": "活跃" }
          ]
        }
      }
    ]
  },
  "suggested_actions": ["导出客户列表", "查看客户详情", "添加新客户"]
}
```

---

## ❌ 错误示例

```json
// ❌ 错误 - 缺少 props 包装
{ "type": "stats_row", "items": [...] }

// ❌ 错误 - title 在顶层而非 props 内
{ "type": "data_table", "title": "标题", "props": { "columns": [...] } }

// ❌ 错误 - 将整个 JSON 作为文本返回
"```json\n{\"answer\": \"...\", \"ui_schema\": {...}}\n```"
```

---

## 🔄 意图到 Agent 映射

| 用户意图关键词 | agent_type | 前端自动导航 Tab |
|--------------|------------|-----------------|
| 客户、用户、审批、团队、KPI、全局 | `manager` | home |
| 商品、库存、上架、热销、品牌 | `product` | products |
| 营销、促销、优惠券、秒杀、拼团 | `marketing` | marketing |
| 财务、收入、利润、退款、会员 | `finance` | finance |
| 售后、客服、工单、投诉、物流 | `service` | aftersales |

---

## 📡 API 端点

Coze Agent 可调用以下 Edge Function 获取实时数据：

```
POST https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/coze-langchain
Content-Type: application/json

{
  "text": "用户输入的自然语言",
  "agent_type": "manager",  // 可选，不传则自动识别
  "session_id": "会话ID"    // 可选，用于上下文关联
}
```

**响应处理**:
- `answer` → 显示在聊天框
- `ui_schema` → 推送到工作台渲染
- `agent_type` → 决定导航到哪个 Tab

---

## 🧪 调试方法

访问 `/genui-debug` 页面可直接粘贴 `ui_schema` JSON 测试渲染效果。

---

*此文档供 Coze AI 读取以正确生成 GenUI Schema*
