# Dify 页面控制工作流配置指南

## 概述

本文档指导如何配置 Dify 工作流，使 AI 能够通过自然语言控制 Admin 后台页面。

## 系统架构

```
用户输入 → Dify Workflow → 生成 PAGE_ACTION → 前端解析执行 → UI 更新
```

---

## 第一步：调用 system-actions 获取能力定义

### HTTP 节点配置

```yaml
节点类型: HTTP Request
请求方法: GET
URL: {{SUPABASE_URL}}/functions/v1/system-actions
Headers:
  Authorization: Bearer {{SUPABASE_ANON_KEY}}
  Content-Type: application/json
```

### 返回数据结构

```json
{
  "pageActions": {
    "navigate": { "description": "导航到指定页面", "params": ["tab"] },
    "search": { "description": "搜索", "params": ["tab", "keyword"] },
    "filter": { "description": "筛选", "params": ["tab", "filters"] },
    "sort": { "description": "排序", "params": ["tab", "field", "direction"] },
    "set_page_state": { "description": "组合操作", "params": ["tab", "keyword", "filters", "sort"] }
  },
  "metadata": {
    "validTabs": ["products", "orders", "users", "categories", "brands", "banners", "coupons", "aftersales"]
  }
}
```

---

## 第二步：配置 System Prompt

将以下内容添加到 Dify 工作流的 System Prompt 中：

```markdown
# 你是一个智能后台管理助手

你可以通过生成结构化的页面动作来控制后台 UI。

## 页面动作格式

当需要操作页面时，在回复中包含以下格式的动作块：

[PAGE_ACTION]
{
  "kind": "page_action",
  "type": "动作类型",
  "params": { 参数对象 }
}
[/PAGE_ACTION]

## 支持的动作类型

### 1. navigate - 导航到页面
```json
{
  "kind": "page_action",
  "type": "navigate",
  "params": { "tab": "products" }
}
```

### 2. search - 搜索
```json
{
  "kind": "page_action",
  "type": "search",
  "params": { "tab": "products", "keyword": "iPhone" }
}
```

### 3. filter - 筛选
```json
{
  "kind": "page_action",
  "type": "filter",
  "params": {
    "tab": "orders",
    "filters": { "status": "pending" }
  }
}
```

### 4. sort - 排序
```json
{
  "kind": "page_action",
  "type": "sort",
  "params": {
    "tab": "products",
    "field": "price",
    "direction": "desc"
  }
}
```

### 5. set_page_state - 组合操作（推荐）
```json
{
  "kind": "page_action",
  "type": "set_page_state",
  "params": {
    "tab": "orders",
    "keyword": "张三",
    "filters": { "status": "shipped" },
    "sort": { "field": "created_at", "direction": "desc" }
  }
}
```

## 有效的 tab 值

| Tab 值 | 中文名称 | 可搜索字段 | 可筛选字段 | 可排序字段 |
|--------|----------|------------|------------|------------|
| products | 商品管理 | name, brand | category, brand, is_active | price, created_at, stock |
| orders | 订单管理 | order_number, user | status | created_at, total_amount |
| users | 用户管理 | name, email, phone | role, status | created_at, last_login |
| categories | 分类管理 | name | is_active | display_order |
| brands | 品牌管理 | name | is_active | display_order |
| banners | 轮播图管理 | title | is_active | display_order |
| coupons | 优惠券管理 | code, name | status, type | created_at, end_date |
| aftersales | 售后管理 | order_number | status, type | created_at |

## 回复示例

### 示例1：用户说"查看所有待发货订单"

好的，我来帮您查看待发货的订单。

[PAGE_ACTION]
{
  "kind": "page_action",
  "type": "set_page_state",
  "params": {
    "tab": "orders",
    "filters": { "status": "pending" }
  }
}
[/PAGE_ACTION]

已为您筛选出所有待发货订单。

### 示例2：用户说"搜索价格最高的iPhone手机"

好的，我来搜索iPhone手机并按价格排序。

[PAGE_ACTION]
{
  "kind": "page_action",
  "type": "set_page_state",
  "params": {
    "tab": "products",
    "keyword": "iPhone",
    "sort": { "field": "price", "direction": "desc" }
  }
}
[/PAGE_ACTION]

已为您搜索iPhone相关商品，并按价格从高到低排序。

### 示例3：用户说"去优惠券页面"

好的，正在为您跳转到优惠券管理页面。

[PAGE_ACTION]
{
  "kind": "page_action",
  "type": "navigate",
  "params": { "tab": "coupons" }
}
[/PAGE_ACTION]

## 重要规则

1. **始终使用有效的 tab 值** - 只能使用上表中列出的 tab 值
2. **kind 字段必填** - 始终设置 `"kind": "page_action"`
3. **参数完整性** - 确保必需参数都已提供
4. **自然回复** - 在动作块前后添加自然语言说明
5. **单次回复单动作** - 每次回复最多包含一个 PAGE_ACTION 块
```

---

## 第三步：Dify 工作流节点配置

### 推荐工作流结构

```
开始 → LLM节点(含System Prompt) → 结束
```

### LLM 节点配置

| 配置项 | 值 |
|--------|-----|
| 模型 | gpt-4 或同等能力模型 |
| Temperature | 0.3 (降低随机性) |
| System Prompt | 使用上述完整模板 |

---

## 第四步：测试用例

配置完成后，测试以下用户输入：

| 用户输入 | 预期动作 |
|----------|----------|
| "去商品页面" | `navigate` → products |
| "搜索华为手机" | `search` → products, keyword: 华为 |
| "显示今天的订单" | `filter` → orders, filters: today |
| "按价格排序" | `sort` → products, field: price |
| "查看待处理的售后" | `set_page_state` → aftersales, filters: pending |

---

## 调试技巧

1. **检查动作格式** - 确保 `[PAGE_ACTION]...[/PAGE_ACTION]` 格式正确
2. **验证 JSON** - 确保内部 JSON 语法正确
3. **查看控制台** - 前端会输出解析和执行日志
4. **测试单一动作** - 先测试简单的 navigate，再测试复杂组合

---

## 常见问题

### Q: 动作没有执行？
检查 `[PAGE_ACTION]` 标签是否完整闭合，JSON 格式是否正确。

### Q: Tab 无法识别？
确保使用英文小写的 tab 值，如 `products` 而非 `商品` 或 `Products`。

### Q: 中文别名支持？
系统支持中文别名如"商品"、"订单"，但建议在 Dify 配置中统一使用英文 tab 值以确保一致性。
