docs: add n8n workflow designs for AI timeline

2026-01-27 21:49:18 +08:00
parent 8cfcebc515
commit 0a5146117b
2 changed files with 312 additions and 0 deletions
@@ -0,0 +1,177 @@
+# n8n 历史数据初始化 Workflow
+
+## 概述
+
+此 workflow 用于一次性收集和初始化 2017-2025 年的 AI 重大事件数据。
+
+## Workflow 结构
+
+### Node 1: Cron 触发器(手动触发)
+
+- 节点类型: `Manual Trigger`
+- 用途: 开发测试时手动运行
+
+### Node 2: 设置年份列表
+
+- 节点类型: `Code`
+- 用途: 定义要处理的年份列表
+
+```javascript
+// 返回年份数组
+return [
+  { year: 2017 },
+  { year: 2018 },
+  { year: 2019 },
+  { year: 2020 },
+  { year: 2021 },
+  { year: 2022 },
+  { year: 2023 },
+  { year: 2024 },
+  { year: 2025 },
+];
+```
+
+### Node 3: 搜索 Agent(循环每年)
+
+- 节点类型: `Loop Over Items`
+- 用途: 遍历每个年份
+
+### Node 4: Web Search - Agent 1
+
+- 节点类型: `HTTP Request`
+- 方法: POST
+- URL: `http://localhost:3000/api/web-search` (或 MCP 端点)
+- Headers:
+  ```json
+  {
+    "Content-Type": "application/json"
+  }
+  ```
+- Body:
+  ```json
+  {
+    "search_query": "AI breakthrough {{ $json.year }} LLM release transformer model",
+    "search_recency_filter": "noLimit",
+    "content_size": "high"
+  }
+  ```
+
+### Node 5: 筛选 Agent - Agent 2
+
+- 节点类型: `Code`
+- 用途: 根据权威来源筛选
+
+```javascript
+const trustedDomains = [
+  'arxiv.org',
+  'openai.com',
+  'anthropic.com',
+  'google.ai',
+  'meta.ai',
+  'deepmind.com',
+  'research.google',
+];
+
+const items = $input.all();
+
+const filtered = items.filter(item => {
+  const url = item.json.url || '';
+  return trustedDomains.some(domain => url.includes(domain));
+});
+
+return filtered;
+```
+
+### Node 6: 格式化 Agent - Agent 3
+
+- 节点类型: `Code`
+- 用途: 转换为 API 格式
+
+```javascript
+const items = $input.all();
+
+const formatted = items.map(item => {
+  const publishedDate = item.json.published_date || new Date().toISOString();
+
+  return {
+    json: {
+      title: item.json.title || 'Untitled',
+      eventDate: new Date(publishedDate).toISOString(),
+      description: (item.json.description || item.json.snippet || '').substring(0, 500),
+      imageUrl: item.json.image_url || 'https://images.unsplash.com/photo-1677442136019-21780ecad995?w=800',
+      sourceUrl: item.json.url,
+    },
+  };
+});
+
+return formatted;
+```
+
+### Node 7: 提交到 API
+
+- 节点类型: `HTTP Request`
+- 方法: POST
+- URL: `http://localhost:3000/api/events`
+- Headers:
+  ```json
+  {
+    "Content-Type": "application/json",
+    "X-API-Key": "={{ $env.WEBHOOK_API_KEY }}"
+  }
+  ```
+- Body: `={{ $json }}` (发送整个数组)
+
+### Node 8: 错误处理
+
+- 节点类型: `IF`
+- 条件: 检查上一个节点的 status code
+- On True: 记录成功
+- On False: 发送错误邮件
+
+## 环境变量
+
+在 n8n 中设置:
+- `WEBHOOK_API_KEY`: 你的 API 密钥(从 .env.local 获取)
+- `API_ENDPOINT`: `http://localhost:3000/api/events` (开发) 或生产 URL
+
+## 测试步骤
+
+1. 在 n8n UI 中创建此 workflow
+2. 手动触发运行
+3. 检查数据库: `pnpm prisma studio`
+4. 验证事件已正确创建
+
+## 数据质量标准
+
+### 标题要求
+- 清晰描述事件
+- 1-200 字符
+- 避免营销术语
+
+### 描述要求
+- 客观描述功能和价值
+- 10-500 字符
+- 突出技术亮点
+
+### 日期要求
+- ISO 8601 格式
+- 准确的发布日期
+
+### 链接要求
+- 必须包含 sourceUrl（权威来源）
+- 链接可访问
+- 优先 arxiv.org、openai.com 等
+
+## 权威来源列表
+
+- 学术论文: arxiv.org
+- 官方博客: openai.com, anthropic.com, google.ai, meta.ai
+- 研究机构: deepmind.com, research.google
+- 新闻媒体: techcrunch.com, theverge.com (需人工审核)
+
+## 注意事项
+
+1. **去重**: workflow 会自动跳过重复的事件（基于 sourceUrl）
+2. **图片**: 如果没有图片，使用默认占位图
+3. **错误处理**: 失败的事件会被记录，不会中断整个流程
+4. **数据验证**: API 会验证所有字段，不符合标准的数据会被拒绝
@@ -0,0 +1,135 @@
+# n8n 增量更新 Workflow
+
+## 概述
+
+此 workflow 每周一自动运行，收集最近 7 天的新 AI 事件。
+
+## Workflow 结构
+
+### Node 1: Cron 触发器
+
+- 节点类型: `Cron`
+- 表达式: `0 9 * * 1` (每周一早上 9:00)
+- 时区: Asia/Shanghai
+
+### Node 2: Web Search - Agent 1
+
+- 节点类型: `HTTP Request`
+- URL: `http://localhost:3000/api/web-search` (或 MCP 端点)
+- Body:
+  ```json
+  {
+    "search_query": "AI news LLM release model launch this week",
+    "search_recency_filter": "oneWeek"
+  }
+  ```
+
+### Node 3: 筛选 Agent - Agent 2
+
+- 节点类型: `Code`
+- 用途: 筛选 + 去重(查询数据库避免重复)
+
+```javascript
+const trustedDomains = [
+  'arxiv.org',
+  'openai.com',
+  'anthropic.com',
+  'google.ai',
+  'meta.ai',
+  'deepmind.com',
+];
+
+// 过滤权威来源
+const items = $input.all();
+const filtered = items.filter(item => {
+  const url = item.json.url || '';
+  return trustedDomains.some(domain => url.includes(domain));
+});
+
+// TODO: 添加数据库查询去重
+// 这里可以调用 GET /api/events 检查 sourceUrl 是否已存在
+
+return filtered;
+```
+
+### Node 4: 格式化 Agent - Agent 3
+
+- 节点类型: `Code`
+- 代码: 同历史 workflow
+
+### Node 5: 提交到 API
+
+- 节点类型: `HTTP Request`
+- 配置: 同历史 workflow
+
+### Node 6: 发送通知邮件
+
+- 节点类型: `Send Email`
+- 条件: 仅在创建新事件时发送
+- 内容:
+  ```
+  主题: AI Timeline - 新事件已添加
+
+  本次更新添加了 {{ $json.created }} 个新事件。
+
+  查看: https://your-domain.com/timeline
+  ```
+
+### Node 7: 错误处理
+
+- 节点类型: `Error Trigger`
+- 动作: 发送错误邮件到管理员
+
+## 测试
+
+1. 修改 Cron 为手动触发进行测试
+2. 验证只有新事件被添加
+3. 检查邮件通知是否正常发送
+4. 确认错误处理工作正常
+
+## 数据质量保证
+
+### 自动筛选规则
+
+1. **来源可信**: 仅来自权威域名
+2. **时效性**: 仅最近 7 天的内容
+3. **去重**: 基于 sourceUrl 自动去重
+
+### 人工审核流程
+
+建议在自动导入后进行人工审核：
+1. 检查标题是否准确
+2. 验证描述是否客观
+3. 确认图片是否合适
+4. 测试链接是否可访问
+
+## 邮件通知配置
+
+### 成功通知
+
+当有新事件添加时发送：
+- 收件人: 内容团队
+- 主题: "AI Timeline - {{ count }} 个新事件已添加"
+- 内容: 包含事件列表和链接
+
+### 错误通知
+
+当 workflow 失败时发送：
+- 收件人: 技术团队
+- 主题: "⚠️ AI Timeline Workflow 失败"
+- 内容: 错误详情和日志
+
+## 监控指标
+
+建议监控以下指标：
+- 每周添加的事件数量
+- workflow 执行时间
+- 失败率和错误类型
+- 去重率
+
+## 优化建议
+
+1. **AI 辅助筛选**: 使用 AI 模型评估新闻相关性
+2. **多源聚合**: 整合多个搜索 API
+3. **智能去重**: 基于标题相似度去重
+4. **自动翻译**: 自动生成英文翻译（titleEn, descriptionEn）