From d9bbdfb06f0f4fae608db6809321389fe682987c Mon Sep 17 00:00:00 2001
From: Caihaohan <caihaohan0712@foxmail.com>
Date: Tue, 27 Jan 2026 20:26:35 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0=20n8n=20=E7=8E=AF?=
 =?UTF-8?q?=E5=A2=83=E5=8F=98=E9=87=8F=E9=85=8D=E7=BD=AE=E5=92=8C=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example            |  5 +++
 n8n-workflows/README.md | 86 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 n8n-workflows/README.md

diff --git a/.env.example b/.env.example
index 490b0f0..058e52b 100644
--- a/.env.example
+++ b/.env.example
@@ -7,6 +7,11 @@ WEBHOOK_API_KEY="sk_live_your_secure_api_key_min_32_chars"
 # n8n AI Search Webhook
 N8N_AI_SEARCH_WEBHOOK="https://n8n.mzaxd.fun/webhook/ai-search"
 
+# n8n Keyword Cloud Workflow Environment Variables
+# These variables should be set in your n8n environment
+# N8N_API_URL: Your API endpoint URL (e.g., http://localhost:3000 for local, or your production URL)
+# N8N_API_KEY: Use the same value as WEBHOOK_API_KEY above
+
 # Internationalization
 NEXT_INTL_DEFAULT_LOCALE="zh"
 NEXT_INTL_SUPPORTED_LOCALES="zh,en"
diff --git a/n8n-workflows/README.md b/n8n-workflows/README.md
new file mode 100644
index 0000000..fbf2b45
--- /dev/null
+++ b/n8n-workflows/README.md
@@ -0,0 +1,86 @@
+# n8n 工作流文档
+
+本目录包含 Agent Park 的 n8n 工作流配置。
+
+## 关键词词云工作流
+
+**文件**: `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` - 批量写入关键词
+
+### 调试
+
+检查每个节点的输出，确保数据格式正确：
+
+- **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）