agent-park/docs/integrations/n8n/DATAFLOW.md

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 的旁路流程：

• 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
  • 项目向量，供语义检索工作流使用

总流图

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
  • route.ts
  • useProjects.ts

3. 项目检索链路

核心流程：

• 项目描述向量化
• RAG项目搜索

职责分工：

• 项目描述向量化
  • 扫描 embedding IS NULL 的活跃项目
  • 用 BAAI/bge-m3 生成向量
  • 写回 projects.embedding 和 embeddingUpdatedAt
• RAG项目搜索
  • 接收 ai-search webhook
  • 对用户输入生成向量
  • 直接在 Postgres 中做向量相似度搜索
  • 返回 results[].id 和 similarity

仓库接点：

• route.ts
  • 转发到 n8n webhook
  • 再根据 ID 批量回库拿完整项目
• useProjects.ts
  • getProjectsByIds() 负责补全项目详情

最终展示：

• 项目搜索页
• 项目列表筛选结果

4. Signals 展示链路

核心流程：

• 前沿信号聚合（多源+AI Agent过滤）

职责：

• 从 6 类外部源抓取讨论或发布内容
• 先做规则过滤和去重
• 再用 LLM 判断是否属于 AI Agent 相关信号
• 输出中英双语结构化字段
• 计算热度字段
• 通过 webhook 写入 signals

仓库接点：

• route.ts
• route.ts
• validations.ts

最终展示：

• Signals 页数据流
• 讨论聚合展示卡片

副作用：

• 该流程还会从已保留信号中提取 GitHub 仓库链接，回流到 discovery 任务系统

5. 标签治理链路

核心流程：

• 项目标签重置

职责：

• 拉取标签池与项目列表
• 逐项目调用 LLM 做 5 类标签归类
• 调用仓库内的标签重置接口

仓库接点：

• route.ts
• auth.ts
• 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
  • 对应 workflows/*.md
• 更新后执行：
  • pnpm n8n:context
• 如果 discovery 服务代码后续被并入仓库，优先补齐 /api/discovery/* 的实现文档与路由映射