# Data-governance 工作流改进方案

**需求**: 完善元数据管理流程  
**日期**: 2025-11-04

---

## 📋 新需求分析

### 功能需求

1. **用户确认后收集信息** ✅
   - 当用户回答"是"时
   - 提示用户输入元数据信息
   - 需要收集：元数据中文名、数据类型、描述等

2. **检查元数据是否存在** ✅
   - 调用API检查元数据中文名是否已存在
   - API地址：`http://192.168.3.143:5000/api/meta/check`

3. **创建新元数据** ✅
   - 如果不存在，调用API创建
   - API地址：`http://192.168.3.143:5000/api/meta/add`

---

## 🎯 推荐方案：使用 AI Agent Tools

### 方案概述

由于 Chat Trigger + AI Agent 的架构限制（AI Agent 必须是终点），最佳方案是：

**让 AI Agent 使用 Tools（工具）来执行操作**

### 工作流结构

```
Chat Trigger
    ↓
AI Agent (带多个工具)
    ├─ Tool 1: 收集元数据信息
    ├─ Tool 2: 检查元数据是否存在
    └─ Tool 3: 创建元数据
    ↓
DeepSeek Chat Model (语言模型)
```

### AI Agent 的对话流程

```
用户: "是，我需要创建元数据"
  ↓
AI: "好的！请提供以下元数据信息：
     1. 元数据中文名（必填）
     2. 数据类型（string/int/float等）
     3. 描述信息"
  ↓
用户: "中文名：用户姓名，类型：string，描述：用户的真实姓名"
  ↓
AI 使用 Tool 1: 检查"用户姓名"是否存在
  ↓
如果不存在 → 使用 Tool 2: 创建元数据
  ↓
AI: "✅ 元数据创建成功！
     - 中文名：用户姓名
     - 类型：string
     - 描述：用户的真实姓名"
```

---

## 🛠️ 实现方案

### 方案 A: 使用 HTTP Request Tools（推荐）⭐⭐⭐

#### 节点配置

##### 1. Chat Trigger
```json
{
  "type": "@n8n/n8n-nodes-langchain.chatTrigger",
  "parameters": {
    "public": true,
    "initialMessages": "您好！我是数据治理助手。\n\n我可以帮助您创建和管理元数据。\n\n请问您需要创建新的元数据吗？",
    "options": {
      "title": "数据治理助手 🤖",
      "subtitle": "元数据管理专家"
    }
  }
}
```

##### 2. AI Agent
```json
{
  "type": "@n8n/n8n-nodes-langchain.agent",
  "parameters": {
    "promptType": "auto",
    "options": {
      "systemMessage": `你是一个专业的数据治理助手，负责帮助用户创建元数据。

工作流程：
1. 当用户表示需要创建元数据时，询问用户提供以下信息：
   - 元数据中文名（必填）
   - 数据类型（string/int/float/date等，默认string）
   - 描述信息（选填）

2. 收集完信息后：
   - 使用 check_metadata 工具检查元数据是否已存在
   - 如果不存在，使用 create_metadata 工具创建

3. 返回创建结果给用户

注意：
- 友好地引导用户提供信息
- 元数据中文名是必需的
- 如果元数据已存在，告诉用户并询问是否需要其他帮助`
    }
  }
}
```

##### 3. HTTP Request Tool - 检查元数据
```json
{
  "name": "check_metadata",
  "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
  "parameters": {
    "name": "check_metadata",
    "description": "检查元数据中文名是否已经存在。输入：元数据中文名。返回：存在返回true，不存在返回false",
    "method": "GET",
    "url": "=http://192.168.3.143:5000/api/meta/check?name_zh={{$parameter.name_zh}}",
    "authentication": "none"
  }
}
```

##### 4. HTTP Request Tool - 创建元数据
```json
{
  "name": "create_metadata",
  "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
  "parameters": {
    "name": "create_metadata",
    "description": "创建新的元数据。输入参数：name_zh(中文名), data_type(数据类型), description(描述)。返回创建结果",
    "method": "POST",
    "url": "http://192.168.3.143:5000/api/meta/add",
    "authentication": "none",
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": {
      "name_zh": "={{$parameter.name_zh}}",
      "data_type": "={{$parameter.data_type || 'string'}}",
      "description": "={{$parameter.description || ''}}",
      "source": "data-governance-workflow"
    }
  }
}
```

##### 5. DeepSeek Chat Model
```json
{
  "type": "@n8n/n8n-nodes-langchain.lmChatDeepSeek",
  "parameters": {
    "model": "deepseek-chat",
    "options": {
      "temperature": 0.7,
      "maxTokens": 1000
    }
  },
  "credentials": {
    "deepSeekApi": "LSdatLFCoTSCGXmn"
  }
}
```

#### 连接关系

```
Chat Trigger → AI Agent (main)
DeepSeek → AI Agent (ai_languageModel)
check_metadata Tool → AI Agent (ai_tool)
create_metadata Tool → AI Agent (ai_tool)
```

---

### 方案 B: 简化版（如果 Tools 不可用）⭐⭐

如果 HTTP Request Tools 配置复杂，可以使用简化方案：

#### AI Agent 系统消息

```
你是数据治理助手。

当用户表示需要创建元数据时，请按以下格式收集信息：

📝 请提供元数据信息：
1. 中文名称（必填）
2. 数据类型（string/int/float，默认string）
3. 描述信息（选填）

示例格式：
中文名：用户姓名
类型：string
描述：用户的真实姓名

收集完信息后，我会为您创建元数据。

注意：由于当前系统限制，请确保元数据名称不重复。
```

然后通过后端API的逻辑来处理检查和创建。

---

## 📊 对比分析

| 特性 | 方案A (Tools) | 方案B (简化) |
|------|--------------|-------------|
| 功能完整性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 实现复杂度 | 中等 | 简单 |
| 用户体验 | 很好 | 一般 |
| 可维护性 | 高 | 中 |
| 实时反馈 | ✅ | ❌ |
| 重复检查 | ✅ 自动 | ❌ 需后端处理 |

---

## 🚀 实施步骤

### 步骤 1: 准备 API 接口

确保以下API在 192.168.3.143 上可用：

#### 检查元数据接口
```http
GET /api/meta/check?name_zh=元数据中文名
Response: {
  "code": 200,
  "data": {
    "exists": true/false
  }
}
```

#### 创建元数据接口
```http
POST /api/meta/add
Content-Type: application/json

{
  "name_zh": "元数据中文名",
  "data_type": "string",
  "description": "描述信息",
  "source": "data-governance-workflow"
}

Response: {
  "code": 200,
  "data": {...},
  "msg": "success"
}
```

### 步骤 2: 在 n8n 中配置

#### 方案 A 配置步骤：

1. **添加 HTTP Request Tool 节点** (检查)
   ```
   - 节点类型：HTTP Request Tool
   - Name: check_metadata
   - Description: 检查元数据是否存在
   - Method: GET
   - URL: http://192.168.3.143:5000/api/meta/check
   ```

2. **添加 HTTP Request Tool 节点** (创建)
   ```
   - 节点类型: HTTP Request Tool
   - Name: create_metadata
   - Description: 创建新元数据
   - Method: POST
   - URL: http://192.168.3.143:5000/api/meta/add
   ```

3. **连接 Tools 到 AI Agent**
   ```
   - check_metadata → AI Agent (ai_tool端口)
   - create_metadata → AI Agent (ai_tool端口)
   ```

4. **更新 AI Agent 系统消息**
   ```
   使用上面提供的系统消息内容
   ```

5. **测试工作流**
   ```
   输入: "是，我要创建元数据"
   AI应该: 询问元数据信息
   输入: "中文名：测试字段，类型：string"
   AI应该: 检查并创建
   ```

---

## 🧪 测试场景

### 场景 1: 完整流程 - 成功创建

```
用户: "是，我需要创建元数据"
AI: "好的！请提供元数据信息..."
用户: "中文名：用户年龄，类型：int，描述：用户的年龄"
AI: [使用check_metadata检查]
AI: [不存在，使用create_metadata创建]
AI: "✅ 元数据创建成功！"
```

### 场景 2: 元数据已存在

```
用户: "是，我需要创建元数据"
AI: "好的！请提供元数据信息..."
用户: "中文名：用户姓名，类型：string"
AI: [使用check_metadata检查]
AI: "❌ 元数据"用户姓名"已经存在，无需重复创建。需要其他帮助吗？"
```

### 场景 3: 信息不完整

```
用户: "是，我需要创建元数据"
AI: "好的！请提供元数据信息..."
用户: "类型是string"
AI: "还需要提供元数据的中文名称哦，这是必填项。"
```

---

## 📄 API 实现示例

### 后端 API 代码（参考）

#### 检查元数据接口
```python
@app.route('/api/meta/check', methods=['GET'])
def check_metadata():
    name_zh = request.args.get('name_zh')
    
    if not name_zh:
        return jsonify({"code": 400, "message": "缺少name_zh参数"})
    
    # 查询数据库
    exists = check_metadata_exists(name_zh)
    
    return jsonify({
        "code": 200,
        "data": {"exists": exists},
        "msg": "success"
    })
```

#### 创建元数据接口（已存在）
```python
@app.route('/api/meta/add', methods=['POST'])
def add_metadata():
    data = request.get_json()
    name_zh = data.get('name_zh')
    
    # 检查是否存在
    if check_metadata_exists(name_zh):
        return jsonify({
            "code": 409,
            "message": "元数据已存在"
        })
    
    # 创建元数据
    result = create_metadata(data)
    
    return jsonify({
        "code": 200,
        "data": result,
        "msg": "success"
    })
```

---

## ⚠️ 注意事项

### Chat Trigger 限制

1. **AI Agent 必须是终点节点**
   - 不能在 AI Agent 后面添加普通节点
   - 只能通过 Tools 来执行操作

2. **Tools 的参数传递**
   - AI Agent 会自动从对话中提取参数
   - 需要在 Tool 的 description 中明确说明参数

3. **错误处理**
   - Tool 执行失败时，AI Agent 会告诉用户
   - 需要在系统消息中定义如何处理错误

### API 设计建议

1. **检查接口应该轻量**
   - 只返回存在性，不返回详细信息
   - 响应时间 < 100ms

2. **创建接口应该原子性**
   - 要么成功创建，要么失败
   - 返回明确的错误信息

3. **统一错误格式**
   ```json
   {
     "code": 错误码,
     "message": "错误描述",
     "data": null
   }
   ```

---

## ✅ 验收标准

工作流完成后应满足：

- [ ] 用户确认创建元数据后，AI 询问详细信息
- [ ] AI 能正确收集：中文名、类型、描述
- [ ] AI 自动检查元数据是否已存在
- [ ] 如果不存在，自动创建
- [ ] 如果已存在，友好提示用户
- [ ] 创建成功后给出明确反馈
- [ ] 整个流程顺畅，无需人工干预

---

## 📚 相关文档

- n8n LangChain Tools: https://docs.n8n.io/integrations/langchain/tools/
- HTTP Request Tool: https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolhttprequest/
- AI Agent: https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/

---

## 🎯 下一步

1. **确认 API 接口** - 在 192.168.3.143 上实现检查接口
2. **在 n8n 中配置** - 按照方案 A 添加 Tools
3. **测试工作流** - 使用上述测试场景验证
4. **优化体验** - 根据测试结果调整 AI 提示词

**推荐从方案 A 开始实施，因为它提供了最完整的功能和最好的用户体验！** 🚀