118 lines
3.8 KiB
Markdown
118 lines
3.8 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`
|
||
|
||
### 功能
|
||
|
||
每日自动拉取标签，按分桶分块交给 AI Agent 处理，并通过结构化输出解析器强制 JSON 格式，最终调用维护 API 执行合并与 `nameEn` 补全。
|
||
|
||
### 执行流程
|
||
|
||
1. **Schedule Trigger**: 每日 UTC 03:00 触发
|
||
2. **Fetch Tags**: 调用 `GET /api/tags` 获取标签和项目计数
|
||
3. **Prepare Chunk Batches**: 预处理并按 bucket + chunk 拆分（默认每块 80）
|
||
4. **Tag Merge Agent + Structured Output Parser**: Agent 生成计划，Parser 强制输出 schema
|
||
5. **Validate Plan**: 校验覆盖率（`reviewedTagIds` 必须覆盖整块）、ID 合法性、自合并
|
||
6. **Retry Loop**: 校验失败会自动重试（默认 2 次，可配置）
|
||
7. **Execute Maintenance**: 仅对校验通过的块调用 `POST /api/tags/maintenance`
|
||
8. **Summarize Results**: 汇总 executed/noop/failed_validation/failed_execute
|
||
|
||
### API 端点
|
||
|
||
- `GET {API_URL}/api/tags` - 拉取标签列表（含 `_count.projects`）
|
||
- `POST {API_URL}/api/tags/maintenance` - 执行批量 updates/merges
|
||
|
||
### 环境变量
|
||
|
||
在 n8n 进程环境中配置：
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
| --- | --- | --- |
|
||
| `SITE_BASE_URL` | 站点地址 | 无 |
|
||
| `WEBHOOK_API_KEY` | 维护 API 鉴权密钥 | 无 |
|
||
| `TAG_JANITOR_CHUNK_SIZE` | 每块标签数量 | `80` |
|
||
| `TAG_JANITOR_MAX_RETRIES` | 校验失败自动重试次数 | `2` |
|
||
|
||
### 注意事项
|
||
|
||
1. **不要全量一次喂模型**：
|
||
- 900+ 标签必须分块，否则大概率返回不完整。
|
||
|
||
2. **结构化输出是硬约束**：
|
||
- 由 `Structured Output Parser` 保证格式。
|
||
- `Validate Plan` 仍会做二次校验，防止“格式正确但内容不完整”。
|
||
|
||
3. **失败块不会误执行**：
|
||
- 校验不通过的块不会调用维护 API，会在 summary 中归类为失败并给出原因。
|
||
|
||
### 扩展建议
|
||
|
||
- 将 `failed_*` 摘要接入 Slack/Telegram 告警
|
||
- 对 `failed_validation` 块做二次人工审核队列
|
||
- 在预处理阶段先做字符串近似聚类，进一步减少 LLM token 消耗
|