agent-park/.planning/codebase/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 条内，但已登记在仓库上下文中的旁路流程：

• 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

核心实体

• projects
• external_links
• tags
• project_tags
• 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 任务队列

2. 项目入库链路

• 项目分析入库（多源）

职责：

• 轮询 discovery 任务队列
• 任务置为 IN_PROGRESS
• 浏览器/AI 收集事实
• 生成标准化项目内容、外链、标签候选
• 调用 completion 接口完成入库
• 失败时置为 FAILED

3. 项目检索链路

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

职责：

• 生成并更新 projects.embedding
• 通过 webhook 对用户查询生成向量
• 在 Postgres 中进行向量相似度搜索
• 返回项目 ID 与相似度

4. Signals 展示链路

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

职责：

• 从 6 类外部源抓取内容
• 规则过滤、去重、AI 结构化
• 写入 signals
• 从保留信号中提取 GitHub 仓库，回流 discovery

5. 标签治理链路

• 项目标签重置

职责：

• 拉取标签池和项目列表
• 按 5 类标签做归类
• 调用标签重置接口更新项目标签

6. Star 刷新链路

• GitHub Star 每日刷新

职责：

• 读取项目 GitHub 链接
• 调 GitHub API 获取仓库信息
• 更新 githubStars 与 githubStarsUpdatedAt

当前“就绪状态”定义

现在仓库已经具备：

• 8 条生产流程的仓库内登记
• 代码触点与 workflow 的映射关系
• 从“源头 -> n8n -> DB/API -> 页面”的主链路图

仍然不在当前仓库闭环的内容：

• discovery task service
• n8n credentials / secrets / runtime env