# Data-governance 工作流添加 Tools 指南

**目标**: 为 Data-governance 工作流添加检查和创建元数据的工具  
**日期**: 2025-11-04

---

## ✅ 已完成的准备工作

### 1. 后端 API 接口已创建

#### 检查元数据接口
```http
GET http://192.168.3.143:5000/api/meta/check?name_zh=元数据中文名

Response:
{
  "code": 200,
  "data": {
    "exists": true/false,
    "name_zh": "元数据中文名"
  },
  "msg": "查询成功"
}
```

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

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

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

### 2. AI Agent 系统消息已更新

AI Agent 现在已配置为：
- 引导用户提供元数据信息
- 使用 check_metadata 工具检查
- 使用 create_metadata 工具创建

---

## 🛠️ 在 n8n 界面中添加 Tools

### 步骤 1: 登录 n8n

```
访问: https://n8n.citupro.com
登录账号
```

### 步骤 2: 打开 Data-governance 工作流

```
1. 进入 Workflows 页面
2. 找到 "Data-governance" 工作流
3. 点击打开编辑器
```

### 步骤 3: 添加检查元数据工具

#### 3.1 添加节点

```
1. 点击 "+" 添加节点
2. 搜索 "HTTP Request Tool"
3. 选择 "HTTP Request Tool" (LangChain类别)
```

#### 3.2 配置节点参数

**基本配置**:
- **Name**: `check_metadata`
- **Description**: 
  ```
  检查元数据中文名是否已经存在。需要参数：name_zh（元数据中文名）。返回exists字段表示是否存在（true/false）
  ```

**HTTP Request 配置**:
- **Method**: `GET`
- **URL**: `http://192.168.3.143:5000/api/meta/check?name_zh={{ $parameter.name_zh }}`
- **Authentication**: `None`

**Placeholder Definitions** (参数定义):
点击 "Add Placeholder" 添加：
- **Name**: `name_zh`
- **Description**: `元数据中文名`

#### 3.3 连接到 AI Agent

```
1. 将 "HTTP Request Tool" 节点拖动到 AI Agent 旁边
2. 从 "HTTP Request Tool" 的输出点拖线到 "AI Agent"
3. 在弹出的连接类型选择中，选择 "ai_tool" 连接类型
```

### 步骤 4: 添加创建元数据工具

#### 4.1 添加节点

```
1. 再次点击 "+" 添加节点
2. 搜索 "HTTP Request Tool"
3. 选择 "HTTP Request Tool" (LangChain类别)
```

#### 4.2 配置节点参数

**基本配置**:
- **Name**: `create_metadata`
- **Description**:
  ```
  创建新的元数据。需要参数：name_zh（中文名，必填）, data_type（数据类型，默认string）, description（描述信息，选填）。返回创建结果
  ```

**HTTP Request 配置**:
- **Method**: `POST`
- **URL**: `http://192.168.3.143:5000/api/meta/node/add`
- **Authentication**: `None`
- **Send Body**: ✅ 启用
- **Body Content Type**: `JSON`
- **JSON Body**:
  ```json
  {
    "name_zh": "={{ $parameter.name_zh }}",
    "data_type": "={{ $parameter.data_type || 'string' }}",
    "describe": "={{ $parameter.description || '' }}",
    "source": "data-governance-workflow",
    "status": true
  }
  ```

**Placeholder Definitions** (参数定义):
点击 "Add Placeholder" 三次添加：
1. **Name**: `name_zh`, **Description**: `元数据中文名（必填）`
2. **Name**: `data_type`, **Description**: `数据类型（string/int/float等，默认string）`
3. **Name**: `description`, **Description**: `描述信息（选填）`

#### 4.3 连接到 AI Agent

```
1. 从 "HTTP Request Tool" 的输出点拖线到 "AI Agent"
2. 选择 "ai_tool" 连接类型
```

### 步骤 5: 清理旧节点（可选）

如果工作流中还有这些节点，可以删除它们（它们已经不需要了）：
- "判断用户意图" (IF节点)
- "调用元数据新增API" (HTTP Request节点)
- "设置确认消息" (Set节点)
- "设置拒绝消息" (Set节点)

**注意**: 只保留以下核心节点：
- Chat Trigger
- AI Agent
- DeepSeek Chat Model
- check_metadata (HTTP Request Tool)
- create_metadata (HTTP Request Tool)

### 步骤 6: 保存并激活

```
1. 点击右上角 "Save" 保存工作流
2. 如果工作流未激活，点击 "Active" 开关激活
```

---

## 🧪 测试工作流

### 测试场景 1: 完整流程

```
访问: https://n8n.citupro.com/chat/tWfjLZE1FmMfQAIn

用户: "是，我要创建元数据"
预期: AI 询问元数据信息

用户: "中文名：测试字段001，类型：string，描述：这是一个测试字段"
预期: 
1. AI 使用 check_metadata 检查是否存在
2. 如果不存在，使用 create_metadata 创建
3. 返回成功消息
```

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

```
用户: "是，我要创建元数据"
AI: "好的！请提供元数据信息..."

用户: "中文名：测试字段001，类型：string"
预期: AI 提示该元数据已存在
```

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

```
用户: "是，我要创建元数据"
AI: "好的！请提供元数据信息..."

用户: "类型是string"
预期: AI 提示需要提供中文名
```

---

## 📊 工作流最终结构

```
┌────────────────┐
│  Chat Trigger  │
└───────┬────────┘
        │
        ↓
┌────────────────┐      ┌─────────────────────┐
│   AI Agent     │◄─────│ DeepSeek Chat Model │
└───────┬────────┘      └─────────────────────┘
        │
        │ (ai_tool连接)
        ├──────────────────────┐
        │                      │
        ↓                      ↓
┌────────────────┐    ┌─────────────────┐
│ check_metadata │    │ create_metadata │
│ (HTTP Tool)    │    │ (HTTP Tool)     │
└────────────────┘    └─────────────────┘
```

**关键连接**:
- `Chat Trigger` → `AI Agent` (main 连接)
- `DeepSeek Chat Model` → `AI Agent` (ai_languageModel 连接)
- `check_metadata` → `AI Agent` (ai_tool 连接)
- `create_metadata` → `AI Agent` (ai_tool 连接)

---

## ⚠️ 重要注意事项

### 1. 连接类型

**ai_tool 连接** 是特殊的连接类型：
- 不是普通的 main 连接
- 表示该节点是 AI Agent 可以使用的工具
- AI Agent 会根据用户输入自动决定何时调用哪个工具

### 2. Tool Description 很重要

Tool 的 Description 会告诉 AI：
- 这个工具的功能是什么
- 需要什么参数
- 返回什么结果

**AI 根据 Description 来决定是否调用该工具**。

### 3. 参数传递

Tool 的参数 (placeholders) 由 AI Agent 从对话中提取：
- 用户说："中文名是用户姓名"
- AI 提取: `name_zh = "用户姓名"`
- 调用: `check_metadata(name_zh="用户姓名")`

### 4. JSON Body 中的表达式

使用 n8n 表达式语法：
- `={{ $parameter.name_zh }}` - 获取参数值
- `={{ $parameter.data_type || 'string' }}` - 默认值
- 需要用双花括号 `={{ }}`

---

## 🔧 调试技巧

### 查看工具调用日志

```
1. 在 n8n 界面打开 "Executions"
2. 找到最近的执行记录
3. 展开查看每个节点的输入输出
4. 检查 Tool 是否被正确调用
```

### 测试单个工具

```
1. 在编辑器中点击 Tool 节点
2. 点击 "Test node"
3. 手动输入参数值
4. 查看返回结果
```

### 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| AI 不调用工具 | Description 不清晰 | 优化 Description，明确说明功能和参数 |
| 工具调用失败 | API 不可达 | 检查 192.168.3.143 的网络连接 |
| 参数未传递 | Placeholder 未定义 | 检查 Placeholder Definitions |
| 返回格式错误 | API 返回不符合预期 | 检查后端 API 返回格式 |

---

## ✅ 完成验收

工作流配置完成后，应该满足：

- [ ] 两个 HTTP Request Tool 节点已添加
- [ ] 工具通过 ai_tool 连接到 AI Agent
- [ ] check_metadata 工具配置正确
- [ ] create_metadata 工具配置正确
- [ ] AI Agent 系统消息已更新
- [ ] 工作流已保存并激活
- [ ] 测试场景 1 通过
- [ ] 测试场景 2 通过
- [ ] 测试场景 3 通过

---

## 📚 相关资源

### n8n 官方文档
- [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/)
- [LangChain Tools](https://docs.n8n.io/integrations/langchain/tools/)

### 项目文档
- [工作流改进方案](./n8n_improved_workflow_design.md)
- [Chat Trigger 错误诊断](./n8n_chat_trigger_error_diagnosis.md)

---

## 🎯 下一步

1. **立即执行**: 按照本指南在 n8n 界面中添加 Tools
2. **测试验证**: 使用测试场景验证功能
3. **优化提示词**: 根据测试结果优化 AI 系统消息
4. **监控运行**: 观察工作流执行日志，持续优化

**预计配置时间**: 15-20 分钟  
**难度**: ⭐⭐⭐ (中等)

祝您配置顺利！🚀