From 0a5146117bca62f7dbabec03976831db5ef36a05 Mon Sep 17 00:00:00 2001 From: mzaxd Date: Tue, 27 Jan 2026 21:49:18 +0800 Subject: [PATCH] docs: add n8n workflow designs for AI timeline --- docs/n8n/historical-workflow-design.md | 177 ++++++++++++++++++++++++ docs/n8n/incremental-workflow-design.md | 135 ++++++++++++++++++ 2 files changed, 312 insertions(+) create mode 100644 docs/n8n/historical-workflow-design.md create mode 100644 docs/n8n/incremental-workflow-design.md diff --git a/docs/n8n/historical-workflow-design.md b/docs/n8n/historical-workflow-design.md new file mode 100644 index 0000000..0080338 --- /dev/null +++ b/docs/n8n/historical-workflow-design.md @@ -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 会验证所有字段，不符合标准的数据会被拒绝 diff --git a/docs/n8n/incremental-workflow-design.md b/docs/n8n/incremental-workflow-design.md new file mode 100644 index 0000000..55d581b --- /dev/null +++ b/docs/n8n/incremental-workflow-design.md @@ -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）