# Coze C端消费者聊天 Agent 开发规范

## 🔴🔴🔴 最高原则：数据库是唯一真相源 🔴🔴🔴

**DATABASE IS THE SINGLE SOURCE OF TRUTH**

所有业务数据（产品、价格、库存）必须来自系统提供的数据库数据。**AI 不得编造、猜测或生成任何数据。**

### 必须遵守
- ✅ 产品 ID 必须 100% 来自系统注入的产品目录 `[ID:xxx]`
- ✅ 产品价格必须以目录中的价格为准
- ✅ 如果目录中没有匹配的产品，返回 `picks: []`
- ✅ 宁可不推荐，也不推荐假数据

### 严格禁止
- ❌ 禁止生成/编造任何 UUID
- ❌ 禁止猜测产品 ID 格式
- ❌ 禁止使用示例中的占位符 ID
- ❌ 禁止截断或简化 UUID

### 快速获取此原则 API
```bash
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec?format=ssot
```

---

## 1. 获取规范 API

Coze Agent 可以通过以下 API 自动读取最新规范：

### 基础 URL
```
https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec
```

### 请求参数

| 参数 | 说明 | 可选值 |
|------|------|--------|
| `format` | 返回格式 | `full`（默认）、`ssot`（唯一真相源原则）、`prompt`、`intents`、`formats`、`examples`、`issues`、`last_test` |

### 示例请求

```bash
# 🔴 获取唯一真相源原则（最重要！）
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec?format=ssot

# 获取完整规范
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec

# 仅获取系统提示词（含核心原则）
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec?format=prompt

# 获取当前问题通报
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec?format=issues

# 获取最近测试反馈
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/consumer-agent-spec?format=last_test
```

---

## 2. Coze 插件配置

在 Coze 平台创建一个 **API 插件**，配置如下：

### 插件信息
- **名称**: 获取开发规范
- **描述**: 获取 C端消费者聊天 Agent 的最新开发规范

### API 配置
```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Consumer Agent Spec API",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://tlsofopqzrzuduinsicm.supabase.co/functions/v1"
    }
  ],
  "paths": {
    "/consumer-agent-spec": {
      "get": {
        "operationId": "getAgentSpec",
        "summary": "获取 C端消费者 Agent 开发规范",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["full", "prompt", "intents", "formats", "examples"],
              "default": "full"
            },
            "description": "返回格式: full=完整规范, prompt=系统提示词, intents=意图识别, formats=响应格式, examples=示例对话"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回规范"
          }
        }
      }
    }
  }
}
```

---

## 3. API 响应格式

### 完整规范 (`format=full`)

```json
{
  "version": "1.1.0",
  "updated_at": "2026-02-04",
  "agent_info": {
    "name": "小智",
    "role": "手机销售顾问助手",
    "target_users": "C端消费者",
    "language": "中文",
    "personality": ["热情", "专业", "耐心"],
    "speaking_style": "简洁友好，避免冗长"
  },
  "core_responsibilities": [...],
  "response_formats": {...},
  "intent_recognition": {...},
  "product_matching_rules": {...},
  "constraints": {...},
  "context_injection": {...},
  "example_dialogues": [...],
  "system_prompt_template": "..."
}
```

### 系统提示词 (`format=prompt`)

```json
{
  "system_prompt": "你是一个专业的手机销售顾问助手...",
  "version": "1.1.0"
}
```

---

## 4. Coze Bot 使用方式

### 方式 A：启动时读取（推荐）
在 Coze Bot 的 **开场白** 或 **初始化流程** 中调用此 API，获取最新规范后注入到对话上下文。

### 方式 B：作为工具调用
将此 API 配置为 Coze 插件，Agent 可以在需要时主动调用获取规范。

### 方式 C：定时同步
Coze 工作流中设置定时任务，定期同步规范到知识库。

---

## 5. 环境变量配置

在 Supabase Secrets 中配置：

| 变量名 | 说明 | 必填 |
|--------|------|------|
| `COZE_API_KEY` | Coze API 密钥（Bearer Token） | ✅ |
| `COZE_CONSUMER_BOT_ID` | C端消费者 Bot ID | ✅ |
| `COZE_BASE_URL` | API 地址（默认 `https://api.coze.cn`） | ❌ |

---

## 6. 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-02-03 | 初始规范 |
| 1.1.0 | 2026-02-04 | 改为 API 自动读取模式 |

---

**维护者**: Lovable AI  
**最后更新**: 2026-02-04
