# Dify 系统功能查询指南

## 概述

为了让 Dify 智能体能够动态了解系统的功能清单和当前状态，我们提供了一个专用的 API 端点：`system-info`。

## API 端点

```
GET https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info
```

**特点：**
- 无需身份验证（公开端点）
- 返回完整的系统架构和功能清单
- 包含实时统计数据和示例数据

## 返回数据结构

```json
{
  "version": "1.0.0",
  "description": "智能电商管理系统 - AI助手可以帮助管理产品、订单、用户、售后等各项业务",
  
  "statistics": {
    "products": { "total": 150, "active": 120 },
    "orders": { "total": 500 },
    "users": { "total": 1000 },
    "afterSales": { "total": 50 }
  },
  
  "database": {
    "tables": [
      {
        "name": "products",
        "description": "商品信息表",
        "columns": ["id", "name", "price", "stock_quantity", ...]
      }
    ]
  },
  
  "operations": {
    "product": {
      "query": {
        "name": "查询产品",
        "description": "根据条件查询产品列表",
        "params": ["keyword", "category", "brand", ...]
      },
      "create": { ... },
      "update": { ... }
    },
    "order": { ... },
    "user": { ... },
    "afterSales": { ... },
    "category": { ... },
    "brand": { ... },
    "banner": { ... },
    "analytics": { ... }
  },
  
  "sampleData": {
    "products": [...],
    "orders": [...],
    "categories": [...],
    "brands": [...]
  },
  
  "apiInfo": {
    "endpoint": "https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/admin-operations",
    "method": "POST",
    "authentication": "Bearer Token (JWT)",
    "requestFormat": {
      "operation": "string",
      "params": "object"
    }
  },
  
  "businessRules": {
    "orderWorkflow": [...],
    "productManagement": [...],
    "afterSales": [...]
  }
}
```

## 在 Dify 中配置

### 方法 1: 工作流启动时获取（推荐）

在 Dify 工作流的开始节点添加 HTTP 请求：

1. **添加 HTTP 请求节点**
   - 节点名称: `获取系统信息`
   - URL: `https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info`
   - Method: `GET`
   - 无需认证

2. **将返回结果传递给 LLM**
   - 在 LLM 节点的上下文中引用 `{{获取系统信息.body}}`
   - 或者提取特定字段如 `{{获取系统信息.body.operations}}`

### 方法 2: 配置为 Dify 工具

1. **创建自定义工具**
   ```yaml
   name: get_system_info
   description: 获取系统完整的功能清单和架构信息
   parameters: []
   api:
     url: https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info
     method: GET
   ```

2. **在 Agent 中启用此工具**
   - Agent 可以在需要时调用此工具获取最新系统信息

### 方法 3: 系统提示词中包含

如果系统功能相对稳定，也可以在系统提示词中直接包含：

```
你是一个智能电商管理助手。系统功能包括：

产品管理：
- product.query: 查询产品
- product.create: 创建产品
- product.update: 更新产品
- product.updateStock: 更新库存
...

订单管理：
- order.query: 查询订单
- order.update: 更新订单
...

当用户询问系统能做什么时，基于以上功能列表回答。
当需要执行具体操作时，使用 admin-operations 工具。
```

## 使用场景

### 场景 1: 用户询问系统能力

**用户:** "这个系统能做什么？"

**Dify 流程:**
1. 调用 `system-info` 获取功能清单
2. 基于 `operations` 字段生成易懂的功能说明
3. 回复用户系统的主要功能模块

### 场景 2: 智能推荐操作

**用户:** "帮我看看现在有什么问题"

**Dify 流程:**
1. 调用 `system-info` 获取统计数据
2. 分析 `statistics` 发现异常（如库存低、待处理售后多）
3. 推荐相应的管理操作

### 场景 3: 动态参数提示

**用户:** "我想更新产品"

**Dify 流程:**
1. 从 `operations.product.update` 获取参数列表
2. 提示用户需要提供哪些信息
3. 收集完参数后调用 `admin-operations` 执行

## 测试命令

```bash
# 获取系统信息
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info

# 格式化输出
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info | jq .

# 只看操作列表
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info | jq .operations

# 只看统计数据
curl https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info | jq .statistics
```

## 与 admin-operations 的配合

```mermaid
graph LR
    A[Dify Agent] -->|1. 获取功能清单| B[system-info]
    B -->|2. 返回系统信息| A
    A -->|3. 理解用户意图| A
    A -->|4. 执行管理操作| C[admin-operations]
    C -->|5. 返回操作结果| A
    A -->|6. 反馈给用户| D[用户]
```

**工作流程：**
1. Dify 启动时或定期调用 `system-info` 了解系统能力
2. 用户提出需求时，基于功能清单理解意图
3. 确定需要执行的操作后，调用 `admin-operations` 执行
4. 将执行结果以自然语言反馈给用户

## 最佳实践

1. **首次对话时获取系统信息**
   - 在会话开始时调用一次 `system-info`
   - 缓存结果避免重复调用

2. **动态更新统计数据**
   - 每次执行操作后可以重新获取 `statistics`
   - 保持 Agent 对系统状态的感知

3. **构建操作映射**
   - 将自然语言需求映射到具体的 operation type
   - 使用 `operations` 中的 `description` 帮助理解

4. **参数验证**
   - 参考 `operations.[category].[action].params` 验证用户输入
   - 提前提示缺失的必填参数

5. **示例数据辅助理解**
   - 使用 `sampleData` 让 Agent 理解数据结构
   - 在回答时可以引用真实数据作为示例

## 注意事项

- `system-info` 是公开端点，任何人都可以访问
- 不包含敏感数据，只返回系统架构和功能描述
- 示例数据只返回前5条，不会泄露完整数据
- 执行实际操作仍需要通过 `admin-operations` 进行身份验证

## 故障排查

**问题: 无法访问 system-info**
- 检查 URL 是否正确
- 确认网络连接正常
- 查看 Edge Function 部署状态

**问题: 返回数据不完整**
- 检查数据库连接
- 查看 Edge Function 日志
- 确认表权限配置正确

**问题: 统计数据不准确**
- 检查 RLS 策略是否影响了查询
- 确认 ANON_KEY 权限足够读取统计

## 扩展建议

1. **添加版本控制**
   - 在 `version` ���段标记 API 版本
   - 支持多版本兼容

2. **缓存优化**
   - 使用 Redis 缓存系统信息
   - 设置合理的过期时间

3. **监控告警**
   - 统计 API 调用频率
   - 监控响应时间和错误率

4. **权限细分**
   - 考虑为不同角色返回不同的功能列表
   - 添加可选的认证支持
