117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# n8n 工作流文档
|
||
|
||
本目录包含 Agent Park 的 n8n 工作流配置。
|
||
|
||
## 工作流清单
|
||
|
||
| 文件 | 功能 |
|
||
| --- | --- |
|
||
| `keyword-cloud-workflow.json` | Google Trends → 关键词词云入库 |
|
||
| `tag-janitor-workflow.json` | 每日 AI 标签合并与 `nameEn` 补全 |
|
||
|
||
## 关键词词云工作流
|
||
|
||
**文件**: `keyword-cloud-workflow.json`
|
||
|
||
### 功能
|
||
|
||
自动采集 Google Trends 数据，生成 AI 热点词汇词云。
|
||
|
||
### 执行流程
|
||
|
||
1. **Schedule Trigger**: 每季度末最后一天的 23:00 自动触发
|
||
2. **Calculate Quarter**: 计算当前季度标识和时间范围
|
||
3. **Google Trends**: 采集热门搜索词
|
||
4. **Extract Keywords**: 提取关键词和热度分数
|
||
5. **Get Visual Rules**: 获取视觉样式规则
|
||
6. **Match Visual Rules**: 为关键词匹配视觉样式
|
||
7. **Send to API**: 写入数据库
|
||
|
||
### 环境变量
|
||
|
||
在 n8n 中设置以下环境变量：
|
||
|
||
| 变量名 | 说明 | 示例值 |
|
||
|--------|------|--------|
|
||
| `API_URL` | API 端点 URL | `http://localhost:3000` (本地) 或生产环境 URL |
|
||
| `API_KEY` | Webhook API Key | 与项目的 `WEBHOOK_API_KEY` 相同 |
|
||
|
||
### 配置步骤
|
||
|
||
1. **导入工作流**：
|
||
- 打开 n8n 界面
|
||
- 点击 "Import from File"
|
||
- 选择 `keyword-cloud-workflow.json`
|
||
|
||
2. **配置 Google Trends 节点**：
|
||
- 确保已安装 `@gamal.dev/n8n-nodes-google-trends` 包
|
||
- 根据需要调整搜索关键词列表
|
||
|
||
3. **配置环境变量**：
|
||
- 在 n8n 设置中添加环境变量
|
||
- 或在每个节点的表达式字段中使用具体值
|
||
|
||
4. **手动执行测试**：
|
||
- 点击 "Execute Workflow" 按钮
|
||
- 检查每个节点的输出
|
||
- 验证数据库中的数据
|
||
|
||
### API 端点
|
||
|
||
工作流调用以下 API 端点：
|
||
|
||
- `GET {API_URL}/api/keyword-cloud/rules` - 获取视觉规则
|
||
- `POST {API_URL}/api/keyword-cloud/keywords` - 批量写入关键词
|
||
|
||
## Tag Janitor 工作流
|
||
|
||
**文件**: `tag-janitor-workflow.json`
|
||
|
||
### 功能
|
||
|
||
每日自动拉取标签，利用 LLM 生成 `merges + updates` 计划，并调用维护 API 执行标签合并。
|
||
|
||
### 执行流程
|
||
|
||
1. **Schedule Trigger**: 每日 UTC 03:00 触发
|
||
2. **Fetch Tags**: 调用 `GET /api/tags` 获取标签和项目计数
|
||
3. **Preprocess Tags**: 预处理排序（按 projectCount）
|
||
4. **AI Analyze Tags**: 生成严格 JSON 计划（`merges`、`updates`）
|
||
5. **Validate JSON**: 校验输出结构和自合并风险
|
||
6. **Execute Maintenance**: 调用 `POST /api/tags/maintenance` 执行
|
||
7. **Summarize Results**: 输出日报（merged/deleted/updated）
|
||
|
||
### API 端点
|
||
|
||
- `GET {API_URL}/api/tags` - 拉取标签列表（含 `_count.projects`）
|
||
- `POST {API_URL}/api/tags/maintenance` - 执行批量 updates/merges
|
||
|
||
### 调试
|
||
|
||
检查每个节点的输出，确保数据格式正确：
|
||
|
||
- **Calculate Quarter**: 应输出 `quarter`, `startDate`, `endDate`
|
||
- **Extract Keywords**: 应输出 `word`, `trendScore`, `quarter`
|
||
- **Match Visual Rules**: 应添加 `visualConfig` 字段
|
||
- **Send to API**: 应返回 `success: true`
|
||
|
||
### 注意事项
|
||
|
||
1. **Google Trends API 限制**：
|
||
- Google Trends 有请求频率限制
|
||
- 建议在非高峰期执行工作流
|
||
|
||
2. **数据质量**：
|
||
- 当前工作流中的 `description` 和 `detailPoints` 是占位符
|
||
- 需要添加 AI 节点（如 OpenAI）来生成真实内容
|
||
|
||
3. **时区处理**：
|
||
- 确保时区设置正确，以便准确计算季度末日期
|
||
|
||
### 扩展建议
|
||
|
||
- **AI 内容生成**：在 "Match Visual Rules" 后添加 OpenAI 节点，生成描述和要点
|
||
- **数据验证**：添加验证节点检查数据完整性
|
||
- **错误处理**：添加错误分支，记录失败的关键词
|
||
- **通知**：工作流完成后发送通知（如 Slack、Email）
|