docs: add n8n integration context
This commit is contained in:
@@ -0,0 +1,321 @@
|
||||
# AgentPark n8n Dataflow
|
||||
|
||||
这份文档回答两个问题：
|
||||
|
||||
1. 这 8 条生产流程分别负责什么。
|
||||
2. 数据怎样从外部源头进入 AgentPark，再进入数据库、API 和页面展示。
|
||||
|
||||
## 范围
|
||||
|
||||
当前纳入范围的 8 条生产流程：
|
||||
|
||||
1. `Topic项目计划新增`
|
||||
2. `每日Github Trending项目计划新增`
|
||||
3. `项目分析入库（多源）`
|
||||
4. `GitHub Star 每日刷新`
|
||||
5. `项目描述向量化`
|
||||
6. `RAG项目搜索`
|
||||
7. `前沿信号聚合（多源+AI Agent过滤）`
|
||||
8. `项目标签重置`
|
||||
|
||||
不在这 8 条内，但已登记在 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json) 的旁路流程：
|
||||
|
||||
- `AI对话网关（Agent Park）`
|
||||
|
||||
## 系统边界
|
||||
|
||||
当前体系不是“单仓库闭环”，而是三层：
|
||||
|
||||
- 外部数据源层：GitHub Search API、GitHub Trending、Hacker News、Reddit、arXiv、Product Hunt、Hugging Face
|
||||
- n8n 编排层：抓取、去重、AI 过滤、标签重置、向量化、信号结构化
|
||||
- AgentPark 应用层：Postgres/Prisma、Next.js API、页面组件
|
||||
|
||||
还有一个明确存在但当前仓库里没有实现代码的外部服务边界：
|
||||
|
||||
- `Discovery Task Service`
|
||||
- `GET/POST/PATCH /api/discovery/tasks`
|
||||
- `POST /api/discovery/check-duplicates`
|
||||
|
||||
也就是说，项目发现与入库链路的“队列与去重接口”不在当前 Next.js 仓库中实现，但其输出最终进入当前仓库使用的数据库与项目展示链路。
|
||||
|
||||
## 核心实体
|
||||
|
||||
- `projects`
|
||||
- 项目主体记录，供 `/api/projects`、详情页、搜索页、首页排行使用
|
||||
- `external_links`
|
||||
- 项目外链，尤其是 GitHub 链接，供 Star 刷新流程使用
|
||||
- `tags`
|
||||
- 标签池，供项目筛选、标签重置、入库分类使用
|
||||
- `project_tags`
|
||||
- 项目与标签的关系表
|
||||
- `signals`
|
||||
- 前沿讨论信号，供 `/api/signals` 和 Signals 页面使用
|
||||
- `projects.embedding`
|
||||
- 项目向量，供语义检索工作流使用
|
||||
|
||||
## 总流图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Sources["External Sources"]
|
||||
GHSearch["GitHub Search API"]
|
||||
GHTrend["GitHub Trending"]
|
||||
GHRepo["GitHub Repository API"]
|
||||
HN["Hacker News"]
|
||||
Reddit["Reddit"]
|
||||
Arxiv["arXiv"]
|
||||
PH["Product Hunt"]
|
||||
HF["Hugging Face"]
|
||||
Silicon["SiliconFlow Embeddings"]
|
||||
end
|
||||
|
||||
subgraph N8N["n8n Workflows"]
|
||||
W1["1 Topic项目计划新增"]
|
||||
W2["2 每日Github Trending项目计划新增"]
|
||||
W3["3 项目分析入库（多源）"]
|
||||
W4["4 GitHub Star 每日刷新"]
|
||||
W5["5 项目描述向量化"]
|
||||
W6["6 RAG项目搜索"]
|
||||
W7["7 前沿信号聚合"]
|
||||
W8["8 项目标签重置"]
|
||||
end
|
||||
|
||||
subgraph Discovery["External Discovery Service"]
|
||||
Dedupe["/api/discovery/check-duplicates"]
|
||||
Tasks["/api/discovery/tasks"]
|
||||
Complete["/api/discovery/tasks/:id/complete"]
|
||||
end
|
||||
|
||||
subgraph App["AgentPark App + DB"]
|
||||
DBProjects["projects"]
|
||||
DBLinks["external_links"]
|
||||
DBTags["tags / project_tags"]
|
||||
DBSignals["signals"]
|
||||
APIProjects["/api/projects"]
|
||||
APISearch["/api/search/ai"]
|
||||
APISignals["/api/signals"]
|
||||
APITagReset["/api/tags/reset-projects"]
|
||||
UIProjects["Projects pages"]
|
||||
UISignals["Signals page"]
|
||||
UIHome["Home rankings"]
|
||||
end
|
||||
|
||||
GHSearch --> W1
|
||||
GHTrend --> W2
|
||||
W1 --> Dedupe
|
||||
W2 --> Dedupe
|
||||
Dedupe --> Tasks
|
||||
Tasks --> W3
|
||||
W3 --> Complete
|
||||
Complete --> DBProjects
|
||||
Complete --> DBLinks
|
||||
Complete --> DBTags
|
||||
|
||||
DBProjects --> W5
|
||||
Silicon --> W5
|
||||
W5 --> DBProjects
|
||||
|
||||
DBProjects --> W6
|
||||
Silicon --> W6
|
||||
W6 --> APISearch
|
||||
APISearch --> UIProjects
|
||||
|
||||
DBProjects --> W4
|
||||
DBLinks --> W4
|
||||
GHRepo --> W4
|
||||
W4 --> DBProjects
|
||||
DBProjects --> UIHome
|
||||
DBProjects --> UIProjects
|
||||
|
||||
HN --> W7
|
||||
Reddit --> W7
|
||||
Arxiv --> W7
|
||||
PH --> W7
|
||||
HF --> W7
|
||||
W7 --> DBSignals
|
||||
W7 --> Dedupe
|
||||
DBSignals --> APISignals
|
||||
APISignals --> UISignals
|
||||
|
||||
DBTags --> W8
|
||||
DBProjects --> W8
|
||||
W8 --> APITagReset
|
||||
APITagReset --> DBTags
|
||||
APITagReset --> UIProjects
|
||||
```
|
||||
|
||||
## 主链路拆解
|
||||
|
||||
### 1. 项目发现链路
|
||||
|
||||
入口流程：
|
||||
|
||||
- `Topic项目计划新增`
|
||||
- `每日Github Trending项目计划新增`
|
||||
|
||||
职责：
|
||||
|
||||
- 从 GitHub 搜索结果和 Trending 列表中找候选项目
|
||||
- 先走 discovery 去重
|
||||
- 再用 LLM 做保留/丢弃判断
|
||||
- 最后把可入库项目写进 discovery 任务队列
|
||||
|
||||
注意：
|
||||
|
||||
- 这两条流程不会直接写 `projects` 表
|
||||
- 它们只负责“造任务”
|
||||
|
||||
### 2. 项目入库链路
|
||||
|
||||
核心流程：
|
||||
|
||||
- `项目分析入库（多源）`
|
||||
|
||||
职责：
|
||||
|
||||
- 轮询 discovery 任务队列
|
||||
- 把任务置为 `IN_PROGRESS`
|
||||
- 用浏览器/AI 工具从入口 URL 收集事实
|
||||
- 生成标准化项目内容、外链、标签候选
|
||||
- 调用 completion 接口完成入库
|
||||
- 失败时把任务置为 `FAILED`
|
||||
|
||||
当前仓库边界：
|
||||
|
||||
- 当前仓库没有 `/api/discovery/*` 的实现
|
||||
- 但入库后的结果最终会出现在：
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/projects/route.ts)
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/projects/[slug]/route.ts)
|
||||
- [useProjects.ts](D:/Code/AI/agent-park/src/hooks/useProjects.ts)
|
||||
|
||||
### 3. 项目检索链路
|
||||
|
||||
核心流程：
|
||||
|
||||
- `项目描述向量化`
|
||||
- `RAG项目搜索`
|
||||
|
||||
职责分工：
|
||||
|
||||
- `项目描述向量化`
|
||||
- 扫描 `embedding IS NULL` 的活跃项目
|
||||
- 用 `BAAI/bge-m3` 生成向量
|
||||
- 写回 `projects.embedding` 和 `embeddingUpdatedAt`
|
||||
- `RAG项目搜索`
|
||||
- 接收 `ai-search` webhook
|
||||
- 对用户输入生成向量
|
||||
- 直接在 Postgres 中做向量相似度搜索
|
||||
- 返回 `results[].id` 和 `similarity`
|
||||
|
||||
仓库接点：
|
||||
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/search/ai/route.ts)
|
||||
- 转发到 n8n webhook
|
||||
- 再根据 ID 批量回库拿完整项目
|
||||
- [useProjects.ts](D:/Code/AI/agent-park/src/hooks/useProjects.ts)
|
||||
- `getProjectsByIds()` 负责补全项目详情
|
||||
|
||||
最终展示：
|
||||
|
||||
- 项目搜索页
|
||||
- 项目列表筛选结果
|
||||
|
||||
### 4. Signals 展示链路
|
||||
|
||||
核心流程：
|
||||
|
||||
- `前沿信号聚合（多源+AI Agent过滤）`
|
||||
|
||||
职责：
|
||||
|
||||
- 从 6 类外部源抓取讨论或发布内容
|
||||
- 先做规则过滤和去重
|
||||
- 再用 LLM 判断是否属于 AI Agent 相关信号
|
||||
- 输出中英双语结构化字段
|
||||
- 计算热度字段
|
||||
- 通过 webhook 写入 `signals`
|
||||
|
||||
仓库接点：
|
||||
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/webhook/signals/route.ts)
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/signals/route.ts)
|
||||
- [validations.ts](D:/Code/AI/agent-park/src/lib/validations.ts)
|
||||
|
||||
最终展示：
|
||||
|
||||
- Signals 页数据流
|
||||
- 讨论聚合展示卡片
|
||||
|
||||
副作用：
|
||||
|
||||
- 该流程还会从已保留信号中提取 GitHub 仓库链接，回流到 discovery 任务系统
|
||||
|
||||
### 5. 标签治理链路
|
||||
|
||||
核心流程：
|
||||
|
||||
- `项目标签重置`
|
||||
|
||||
职责：
|
||||
|
||||
- 拉取标签池与项目列表
|
||||
- 逐项目调用 LLM 做 5 类标签归类
|
||||
- 调用仓库内的标签重置接口
|
||||
|
||||
仓库接点：
|
||||
|
||||
- [route.ts](D:/Code/AI/agent-park/src/app/api/tags/reset-projects/route.ts)
|
||||
- [auth.ts](D:/Code/AI/agent-park/src/lib/auth.ts)
|
||||
- [validations.ts](D:/Code/AI/agent-park/src/lib/validations.ts)
|
||||
|
||||
最终影响：
|
||||
|
||||
- 项目筛选
|
||||
- 详情页标签
|
||||
- 入库后标签整洁度
|
||||
|
||||
### 6. Star 刷新链路
|
||||
|
||||
核心流程：
|
||||
|
||||
- `GitHub Star 每日刷新`
|
||||
|
||||
职责：
|
||||
|
||||
- 从 `projects` + `external_links` 找出 GitHub 仓库
|
||||
- 调 GitHub API 拉仓库详情
|
||||
- 更新 `githubStars` 与 `githubStarsUpdatedAt`
|
||||
|
||||
最终影响：
|
||||
|
||||
- 首页排行
|
||||
- 项目列表星标排序
|
||||
- AI 搜索结果里的 `stars_desc` / `stars_asc`
|
||||
|
||||
## 当前“就绪状态”定义
|
||||
|
||||
现在仓库已经具备：
|
||||
|
||||
- 8 条生产流程的仓库内登记
|
||||
- 代码触点与 workflow 的映射关系
|
||||
- 从“源头 -> n8n -> DB/API -> 页面”的主链路图
|
||||
- `.planning/codebase` 中可供 GSD 读取的 n8n 总览
|
||||
|
||||
但仍有 2 个外部依赖不在当前仓库闭环：
|
||||
|
||||
- discovery task service
|
||||
- n8n credentials / secrets / runtime env
|
||||
|
||||
因此，“代码库就绪”应理解为：
|
||||
|
||||
- AI 和 GSD 已经能正确理解全局结构与边界
|
||||
- 但不能假设当前仓库单独包含所有后端实现
|
||||
|
||||
## 建议维护规则
|
||||
|
||||
- 任何一条生产 workflow 变更时，优先更新：
|
||||
- [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)
|
||||
- 对应 `workflows/*.md`
|
||||
- 更新后执行：
|
||||
- `pnpm n8n:context`
|
||||
- 如果 discovery 服务代码后续被并入仓库，优先补齐 `/api/discovery/*` 的实现文档与路由映射
|
||||
Reference in New Issue
Block a user