agent-park/n8n-workflows/README.md

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