# 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 消耗