docs: add n8n integration context

docs/integrations/n8n/workflows/01-topic-discovery.md

@@ -0,0 +1,63 @@
+# Topic项目计划新增
+
+- Registry ID: `topic-discovery`
+- n8n Workflow ID: `iw9vx9ih5Lt0Mobk`
+- Status: `external-upstream`
+- 角色: 从 GitHub Search API 按 topic 和关键词发现候选仓库，经过去重与 AI 筛选后，写入 discovery 任务队列。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：每日约 `01:00` 运行
+
+## 外部输入
+
+- GitHub Search API
+- 预设 topic / keyword watchlist
+- AI 保留或丢弃判断
+
+## 主流程
+
+1. 组合 topic 与关键词查询 GitHub 仓库。
+2. 提取候选仓库 URL、基础描述和来源信息。
+3. 调用 discovery 去重接口判断是否应该继续创建任务。
+4. 使用 LLM 对候选项目做保留或丢弃判断。
+5. 把保留结果写入 discovery 任务队列。
+6. 当召回偏低时发出低召回告警。
+
+## 输出结果
+
+- `tasks[].sourceUrl`
+- `tasks[].sourceType`
+- `dedupe shouldCreate`
+- `task creation result`
+- `low recall alert`
+
+## 与仓库的关系
+
+这条流程不直接写当前仓库的 `projects` 表。它的作用是“发现项目并造任务”，后续由 `项目分析入库（多源）` 消费任务并完成入库。
+
+当前仓库内最终会消费它产出的结果：
+
+- [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)
+
+## 系统边界
+
+当前仓库没有实现以下接口，这部分应视为外部上游系统：
+
+- `POST /api/discovery/check-duplicates`
+- `POST /api/discovery/tasks`
+
+因此，这条流程在仓库侧属于 `external-upstream`，不是应用内路由。
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与职责。
+- 该流程围绕 agent / infra / observability / evaluation / MCP 等方向搜索仓库。
+- 任务入队后，真实入库并不在当前流程内完成。
+
+## 维护要求
+
+- GitHub 搜索 query、topic watchlist、保留规则变更时，同步更新 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)。
+- 若未来 discovery 服务代码并入当前仓库，应把这里的外部边界改成具体路由映射。

docs/integrations/n8n/workflows/02-github-trending-discovery.md

@@ -0,0 +1,62 @@
+# 每日Github Trending项目计划新增
+
+- Registry ID: `github-trending-discovery`
+- n8n Workflow ID: `hughGsWismCpk7jd`
+- Status: `external-upstream`
+- 角色: 抓取 GitHub Trending，筛出值得跟踪的新项目，并写入 discovery 任务队列。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：每日约 `01:00` 运行
+
+## 外部输入
+
+- [GitHub Trending](https://github.com/trending)
+- 页面抓取结果
+- AI 保留或丢弃判断
+
+## 主流程
+
+1. 抓取 GitHub Trending 页面，提取仓库 URL 和基础描述。
+2. 规范化候选项目数据。
+3. 调用 discovery 去重接口，判断当前候选是否已经存在。
+4. 使用 LLM 对候选项目做保留或丢弃判断。
+5. 把保留候选写入 discovery 任务队列。
+
+## 输出结果
+
+- `GitHub trending repository URL`
+- `tasks[].sourceUrl`
+- `tasks[].sourceType`
+- `dedupe shouldCreate`
+- `task creation result`
+
+## 与仓库的关系
+
+这条流程不直接写当前仓库数据库。它只生成“待分析任务”，真正的项目详情写入由 `项目分析入库（多源）` 完成。
+
+最终影响到当前仓库的展示结果：
+
+- [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)
+
+## 系统边界
+
+当前仓库没有实现以下接口：
+
+- `POST /api/discovery/check-duplicates`
+- `POST /api/discovery/tasks`
+
+因此它是当前仓库的外部上游，而不是仓库内闭环的一部分。
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与职责。
+- 该流程从 Trending 抓取候选，再由 AI 过滤，避免把纯噪声仓库直接入库。
+- 当前仓库只能看到最终被入库后的项目，不能独立重放这条发现链路。
+
+## 维护要求
+
+- Trending 抓取逻辑、筛选规则、入队字段变更时，同步更新 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)。
+- 若后续保留了 workflow 导出文件，应在 registry 中补上 `exportFile`。

docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md

@@ -0,0 +1,67 @@
+# 项目分析入库（多源）
+
+- Registry ID: `project-ingestion-multi-source`
+- n8n Workflow ID: `1Ig1CyVMsGJFaHOe`
+- Status: `external-upstream`
+- 角色: 消费 discovery 任务队列，补齐项目事实、外链和标签，再把结果写回 AgentPark 的项目主数据。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：约每 `10` 分钟轮询一次
+
+## 外部输入
+
+- discovery task queue
+- 浏览器抓取与页面解析
+- AI 提取和结构化能力
+- 标签池 / 分类规则
+
+## 主流程
+
+1. 轮询 discovery 任务队列，拉取待处理项目。
+2. 把任务置为 `IN_PROGRESS`。
+3. 基于 `sourceUrl` 和 `sourceType` 打开外部页面，采集项目事实。
+4. 生成标准化项目资料，如标题、描述、正文、分类、外链、标签候选。
+5. 写回任务完成接口，完成项目入库。
+6. 出错时写回失败状态。
+
+## 输出结果
+
+- `project content`
+- `tag assignments`
+- `task completion status`
+
+## 与仓库的关系
+
+这是“项目从发现到落库”的核心桥梁，但它不通过当前仓库中的显式 `/api/discovery/*` 路由实现。当前仓库能确认的消费面主要是项目表结构和展示接口：
+
+- [schema.prisma](D:/Code/AI/agent-park/prisma/schema.prisma)
+- [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)
+
+## 系统边界
+
+当前仓库没有以下接口实现：
+
+- `GET /api/discovery/tasks`
+- `PATCH /api/discovery/tasks/:id`
+- `POST /api/discovery/tasks/:id/complete`
+- 失败回写相关接口
+
+这说明项目入库队列服务是外部系统。当前仓库只能消费最终入库结果，而不能独立运行整条入库工作流。
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与职责。
+- 该流程会先标记 `IN_PROGRESS`，再进行浏览器与 AI 分析。
+- 当前仓库看到的是结果表和查询接口，不是入库执行器本身。
+
+## 对 AI/GSD 的意义
+
+后续如果要梳理“项目数据源头 -> 展示”，必须把这条流程当作核心中间层，而不是假设项目直接从 GitHub 写入 `projects`。
+
+## 维护要求
+
+- 任务字段、回写结构、标签落库策略变化时，同步更新 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)。
+- 若 discovery 服务未来并入仓库，应第一时间把这里改成具体路由与 schema 映射。

docs/integrations/n8n/workflows/04-github-star-refresh.md

@@ -0,0 +1,54 @@
+# GitHub Star 每日刷新
+
+- Registry ID: `github-star-refresh`
+- n8n Workflow ID: `ewx9Gs6cjrTXvwD0`
+- Status: `confirmed`
+- 角色: 每日刷新项目的 GitHub Star 数，保证排序、排行和展示的时效性。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：每日约 `04:00` 运行
+
+## 数据来源
+
+- `projects`
+- `external_links`
+- GitHub Repository API
+
+## 主流程
+
+1. 从数据库读取活跃项目及其 GitHub 外链。
+2. 解析 GitHub 仓库 owner/repo。
+3. 调用 GitHub Repository API 获取最新 star 数。
+4. 直接写回 `projects.githubStars` 与 `projects.githubStarsUpdatedAt`。
+
+## 直接写入字段
+
+- `projects.githubStars`
+- `projects.githubStarsUpdatedAt`
+
+## 与仓库的关系
+
+这条流程不是调用仓库 API，而是直接维护数据库中的展示字段。当前仓库内受其影响的消费面包括：
+
+- [schema.prisma](D:/Code/AI/agent-park/prisma/schema.prisma)
+- [route.ts](D:/Code/AI/agent-park/src/app/api/search/ai/route.ts)
+- [useProjects.ts](D:/Code/AI/agent-park/src/hooks/useProjects.ts)
+
+## 下游影响
+
+- 首页排行
+- 项目列表按 star 排序
+- AI 搜索结果中的 `stars_desc` / `stars_asc`
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与职责。
+- 该流程直接读写 Postgres，而不是走 Next.js API。
+- 所以如果星标不更新，优先排查 n8n 与数据库连接，而不是先看前端排序代码。
+
+## 维护要求
+
+- 如果 `external_links` 的 GitHub 链接筛选规则改变，要同步更新这里和 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)。
+- 如果后续改成走仓库 API 写入，应把“直接 DB 写”改成“仓库 API 触点”。

docs/integrations/n8n/workflows/05-project-description-vectorization.md

@@ -0,0 +1,55 @@
+# 项目描述向量化
+
+- Registry ID: `project-description-vectorization`
+- n8n Workflow ID: `1AvejnM5n-WPApU1vFt9C`
+- Status: `confirmed`
+- 角色: 为项目生成 embedding，供语义检索工作流使用。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：约每 `30` 分钟运行一次
+
+## 数据来源
+
+- `projects` 表中的活跃项目
+- SiliconFlow Embeddings API
+- 模型：`BAAI/bge-m3`
+
+## 主流程
+
+1. 选出 `embedding IS NULL` 或需要补算的活跃项目。
+2. 读取项目的中英文名称、描述和正文。
+3. 拼接向量化输入文本。
+4. 调用 SiliconFlow Embeddings API 生成向量。
+5. 直接写回 `projects.embedding` 和 `embeddingUpdatedAt`。
+
+## 直接写入字段
+
+- `projects.embedding`
+- `projects.embeddingUpdatedAt`
+
+## 与仓库的关系
+
+这条流程直接维护数据库向量列，而不是通过仓库 API 写入。仓库侧主要消费点：
+
+- [schema.prisma](D:/Code/AI/agent-park/prisma/schema.prisma)
+- [migration.sql](D:/Code/AI/agent-park/prisma/migrations/20260126000000_add_project_embedding/migration.sql)
+- [route.ts](D:/Code/AI/agent-park/src/app/api/search/ai/route.ts)
+
+## 下游影响
+
+- `RAG项目搜索`
+- 语义搜索命中质量
+- 以自然语言搜索项目的相关性
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与职责。
+- 当前实现是直连数据库维护向量列。
+- 所以如果 AI 搜索结果变差，既要查 webhook 搜索流程，也要查这条补向量流程是否落后或失败。
+
+## 维护要求
+
+- 向量输入字段、模型、补算规则变化时，同步更新 [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)。
+- 如果后续 embedding 改成异步队列或应用内任务，需要把这里的数据库直写描述同步改掉。

docs/integrations/n8n/workflows/06-rag-project-search.md

@@ -0,0 +1,66 @@
+# RAG项目搜索
+
+- Registry ID: `ai-search`
+- n8n Workflow ID: `F5cQ06DykBfpeyfqL-pd7`
+- Status: `confirmed`
+- 角色: 把用户查询转成向量相似度检索结果，再把候选项目 ID 返回给仓库 API 做二次补全。
+
+## 触发方式
+
+- webhook 触发
+- 已核查 webhook path: `ai-search`
+
+## 输入契约
+
+- `desc`
+- `limit`
+- `page`
+- `offset`
+- `tags`
+- `domains`
+- `productForms`
+
+## 主流程
+
+1. 仓库 API 接收搜索请求。
+2. API 把请求转发给 n8n webhook `ai-search`。
+3. n8n 为查询文本生成 embedding。
+4. n8n 在 Postgres 中执行向量相似度搜索。
+5. n8n 返回候选项目 ID 和相似度。
+6. 仓库 API 再按 ID 回库查询完整项目数据并返回前端。
+
+## 输出契约
+
+- `results[].id`
+- `results[].similarity`
+- `pagination.total`
+- `pagination.totalPages`
+- `pagination.hasMore`
+
+## 与仓库的关系
+
+这是当前仓库里最直接可见的 n8n 搜索接点：
+
+- [route.ts](D:/Code/AI/agent-park/src/app/api/search/ai/route.ts)
+- [useProjects.ts](D:/Code/AI/agent-park/src/hooks/useProjects.ts)
+
+## 关键实现边界
+
+- n8n 负责“召回候选 ID”
+- 仓库 API 负责“按 ID 补全项目字段”
+- 前端不直接信任 n8n 返回完整项目对象，而是以仓库数据库为准
+
+这个分层是正确的，因为它避免把页面展示完全绑死到 n8n 返回结构。
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据、webhook path 和返回字段。
+- 当前搜索依赖 `projects.embedding`，因此和 `项目描述向量化` 强耦合。
+- 如果 `N8N_AI_SEARCH_WEBHOOK` 缺失或返回结构变化，搜索 API 会直接受影响。
+
+## 维护要求
+
+- 搜索输入字段、分页规则、n8n 返回结构变化时，必须同步更新：
+  - [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)
+  - [route.ts](D:/Code/AI/agent-park/src/app/api/search/ai/route.ts)
+- 如未来增加 rerank 或 hybrid search，也应先更新这里，再调整 API 契约。

docs/integrations/n8n/workflows/07-signals-aggregation.md

@@ -0,0 +1,89 @@
+# 前沿信号聚合（多源+AI Agent过滤）
+
+- Registry ID: `signals-aggregation`
+- n8n Workflow ID: `bAxNZKGq2ApUUiw9`
+- Status: `confirmed`
+- 角色: 聚合多源讨论与发布内容，筛出 AI Agent 相关信号，结构化后写入 AgentPark 的 `signals` 数据流。
+
+## 触发方式
+
+- 定时触发
+- 当前已核查行为：多源周期抓取
+
+## 数据来源
+
+- Hacker News
+- GitHub
+- arXiv
+- Reddit
+- Product Hunt
+- Hugging Face
+
+## 主流程
+
+1. 从 6 类外部源抓取候选讨论或发布内容。
+2. 做基础规则过滤与去重。
+3. 使用 LLM 判断是否属于 AI Agent 相关前沿信号。
+4. 生成中英双语标题、摘要、主题、标签、sections 和热度字段。
+5. 调用仓库 webhook 写入 `signals`。
+6. 从保留结果中抽取 GitHub 仓库链接，回流 discovery 系统继续发现项目。
+
+## 输入契约
+
+- `apiKey`
+- `signals[].source`
+- `signals[].sourceUrl`
+- `signals[].title`
+- `signals[].titleEn`
+- `signals[].summary`
+- `signals[].summaryEn`
+- `signals[].topic`
+- `signals[].topicEn`
+- `signals[].tags`
+- `signals[].sections`
+- `signals[].engagement`
+- `signals[].hotScore`
+- `signals[].isHot`
+- `signals[].publishedAt`
+- `signals[].isActive`
+
+## 输出契约
+
+- `success`
+- `processed`
+- `created`
+- `updated`
+- `failed`
+- `errors[].index`
+- `errors[].field`
+- `errors[].message`
+
+## 与仓库的关系
+
+仓库内直接接点：
+
+- [auth.ts](D:/Code/AI/agent-park/src/lib/auth.ts)
+- [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)
+- [schema.prisma](D:/Code/AI/agent-park/prisma/schema.prisma)
+
+## 下游影响
+
+- Signals 页面内容
+- 热门信号排序与过滤
+- 从信号反向发现 GitHub 项目的回流链路
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与 webhook 写入方向。
+- 该流程会向 `/api/webhook/signals` 写入结构化 signals。
+- 它还会触发外部 discovery 去重与任务创建，因此不只是“信号展示流”，也是项目发现的旁路入口。
+- workflow 当前在 HTTP body 中携带共享密钥，仓库侧应视为待治理项，后续改为 n8n credential 或环境变量注入。
+
+## 维护要求
+
+- 字段结构、验证 schema、热度算法变更时，同步更新：
+  - [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)
+  - [validations.ts](D:/Code/AI/agent-park/src/lib/validations.ts)
+  - [route.ts](D:/Code/AI/agent-park/src/app/api/webhook/signals/route.ts)

docs/integrations/n8n/workflows/08-project-tag-reset.md

@@ -0,0 +1,73 @@
+# 项目标签重置
+
+- Registry ID: `tag-reset`
+- n8n Workflow ID: `8tIgBqLyWrBewJPs`
+- Status: `confirmed`
+- 角色: 基于 n8n 分类结果批量重置项目标签，保证项目标签体系的一致性。
+
+## 触发方式
+
+- 手动触发
+- 当前已核查行为：面向批量标签治理任务
+
+## 数据来源
+
+- `GET /api/tags`
+- `GET /api/projects`
+- n8n 内的 LLM 标签分类
+
+## 主流程
+
+1. 从仓库读取标签池和项目列表。
+2. 在 n8n 内对项目做多分类标签判断。
+3. 组装批量标签重置请求。
+4. 调用仓库 API `/api/tags/reset-projects`。
+5. 返回更新结果、失败信息和 dry-run 结果。
+
+## 输入契约
+
+- `apiKey`
+- `dryRun`
+- `replaceAllCategories`
+- `categories`
+- `projects[].projectSlug`
+- `projects[].selectedTagSlugsByCategory`
+
+## 输出契约
+
+- `success`
+- `result.dryRun`
+- `result.categories`
+- `result.updatedCount`
+- `result.failedCount`
+- `result.results[].projectSlug`
+- `result.results[].status`
+- `result.results[].details`
+
+## 与仓库的关系
+
+仓库内直接接点：
+
+- [auth.ts](D:/Code/AI/agent-park/src/lib/auth.ts)
+- [route.ts](D:/Code/AI/agent-park/src/app/api/tags/reset-projects/route.ts)
+- [validations.ts](D:/Code/AI/agent-park/src/lib/validations.ts)
+- [schema.prisma](D:/Code/AI/agent-park/prisma/schema.prisma)
+
+## 下游影响
+
+- 项目列表筛选
+- 项目详情标签展示
+- 标签一致性与后续搜索效果
+
+## 已确认要点
+
+- 已通过 live n8n MCP 核查 workflow 元数据与请求方向。
+- 该流程会先读取仓库标签和项目，再把批量结果回写到仓库 API。
+- workflow 当前在请求体中携带共享密钥，仓库侧应视为待治理项，后续改为 n8n credential 或环境变量注入。
+
+## 维护要求
+
+- 标签分类规则、分类维度、批量请求结构变更时，同步更新：
+  - [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)
+  - [route.ts](D:/Code/AI/agent-park/src/app/api/tags/reset-projects/route.ts)
+  - [validations.ts](D:/Code/AI/agent-park/src/lib/validations.ts)

docs/integrations/n8n/workflows/README.md

@@ -0,0 +1,32 @@
+# Workflow Specs
+
+这里存放 8 条已核查生产流程的仓库内说明文件。
+
+作用：
+
+- 给 AI 和工程协作者提供“单流程级别”的说明，而不是只看总表
+- 固定每条流程的触发方式、数据源、关键节点、写入位置、仓库触点和边界
+- 当 n8n 流程有变更时，可以快速定位应该更新哪一份说明
+
+## 索引
+
+1. [1 Topic项目计划新增](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/01-topic-discovery.md)
+2. [2 每日Github Trending项目计划新增](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/02-github-trending-discovery.md)
+3. [3 项目分析入库（多源）](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md)
+4. [4 GitHub Star 每日刷新](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/04-github-star-refresh.md)
+5. [5 项目描述向量化](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/05-project-description-vectorization.md)
+6. [6 RAG项目搜索](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/06-rag-project-search.md)
+7. [7 前沿信号聚合（多源+AI Agent过滤）](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/07-signals-aggregation.md)
+8. [8 项目标签重置](D:/Code/AI/agent-park/docs/integrations/n8n/workflows/08-project-tag-reset.md)
+
+## 使用规则
+
+- `registry.json` 记录的是映射和契约
+- `workflows/*.md` 记录的是流程结构和职责
+- [DATAFLOW.md](D:/Code/AI/agent-park/docs/integrations/n8n/DATAFLOW.md) 记录的是全链路视图
+
+建议在每次生产流程改动后同时更新：
+
+1. 对应 `workflows/*.md`
+2. [registry.json](D:/Code/AI/agent-park/docs/integrations/n8n/registry.json)
+3. `pnpm n8n:context`