mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
804fd756e7be11e90f417e81c6ef18032b45eee4
agent-park/.planning/codebase/N8N-CONTEXT.md
T

13 KiB
Raw Blame History

N8N Context

Generated at: 2026-04-20T11:04:30.112Z

This file is generated from docs/integrations/n8n/registry.json plus repository scanning. It exists so external n8n workflows become committed, reviewable context for AI agents and GSD.

Workflow Inventory

AI Search

  • Status: confirmed
  • ID: ai-search
  • Purpose: Resolve semantic search candidates from n8n and hydrate them into project results.
  • n8n workflow id: F5cQ06DykBfpeyfqL-pd7
  • Export file: not recorded

Entrypoints

  • webhook: GET ai-search

Repository Touchpoints

  • src/app/api/search/ai/route.ts

Environment

  • N8N_AI_SEARCH_WEBHOOK

Contracts

  • Request fields: desc, limit, page, offset, tags, domains, productForms
  • Response fields: results[].id, results[].similarity, pagination.total, pagination.totalPages, pagination.hasMore

Schemas

  • N8NSearchResponseSchema

Related Systems

  • Upstreams: RAG项目搜索, pgvector similarity search, SiliconFlow embeddings
  • Downstreams: src/hooks/useProjects.ts#getProjectsByIds, POST /api/search/ai response

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: webhook path is ai-search and the workflow returns results[].id plus similarity.

Signals Aggregation

  • Status: confirmed
  • ID: signals-aggregation
  • Purpose: Aggregate multi-source discussion signals, filter them with AI, and ingest them into the repository signal store.
  • n8n workflow id: bAxNZKGq2ApUUiw9
  • Export file: not recorded

Entrypoints

  • schedule: multi-source discussion crawl

Repository Touchpoints

  • src/lib/auth.ts
  • src/app/api/webhook/signals/route.ts
  • src/app/api/signals/route.ts
  • src/lib/validations.ts
  • prisma/schema.prisma

Environment

  • WEBHOOK_API_KEY

Contracts

  • Request fields: 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
  • Response fields: success, processed, created, updated, failed, errors[].index, errors[].field, errors[].message

Schemas

  • SignalWebhookPayloadSchema
  • SignalIngestionInputSchema
  • SignalQuerySchema

Related Systems

  • Upstreams: Hacker News, GitHub, arXiv, Reddit, Product Hunt, Hugging Face
  • Downstreams: GET /api/signals, signals page feed, signal hotness computation

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow posts to /api/webhook/signals and also triggers external discovery dedupe/task creation. Workflow currently embeds a shared secret in HTTP body and should move to credentials/env.

Project Tag Reset

  • Status: confirmed
  • ID: tag-reset
  • Purpose: Reset selected project tags in bulk from n8n classification results.
  • n8n workflow id: 8tIgBqLyWrBewJPs
  • Export file: not recorded

Entrypoints

  • manual: bulk tag reset

Repository Touchpoints

  • src/lib/auth.ts
  • src/app/api/tags/reset-projects/route.ts
  • src/lib/validations.ts
  • prisma/schema.prisma

Environment

  • WEBHOOK_API_KEY

Contracts

  • Request fields: apiKey, dryRun, replaceAllCategories, categories, projects[].projectSlug, projects[].selectedTagSlugsByCategory
  • Response fields: success, result.dryRun, result.categories, result.updatedCount, result.failedCount, result.results[].projectSlug, result.results[].status, result.results[].details

Schemas

  • ProjectTagResetRequestSchema

Related Systems

  • Upstreams: n8n tag classification
  • Downstreams: project tag relations, project detail page revalidation, project list revalidation

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow reads /api/tags and /api/projects, then posts bulk updates into /api/tags/reset-projects. Workflow currently embeds a shared secret in HTTP body and should move to credentials/env.

Project Ingestion (Multi-source)

  • Status: external-upstream
  • ID: project-ingestion-multi-source
  • Purpose: Consume queued discovery tasks, enrich project metadata with AI/browser steps, and write final ingestion results back to Agent Park.
  • n8n workflow id: 1Ig1CyVMsGJFaHOe
  • Export file: not recorded

Entrypoints

  • schedule: every 10 minutes

Repository Touchpoints

  • prisma/schema.prisma
  • src/app/api/projects/route.ts
  • src/app/api/projects/[slug]/route.ts

Environment

  • none

Contracts

  • Request fields: task.status, task.sourceUrl, task.sourceType
  • Response fields: project content, tag assignments, task completion status

Related Systems

  • Upstreams: discovery task queue, browser/AI extraction, tag catalog
  • Downstreams: project records visible in repository APIs, task completion callbacks, task failure callbacks

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow polls /api/discovery/tasks, marks tasks IN_PROGRESS, enriches candidates, then completes or fails tasks. The current repo does not contain /api/discovery/* handlers, so this is an upstream system dependency rather than a route implemented here.

GitHub Star Refresh

  • Status: confirmed
  • ID: github-star-refresh
  • Purpose: Refresh projects.githubStars and projects.githubStarsUpdatedAt directly from GitHub repository metadata.
  • n8n workflow id: ewx9Gs6cjrTXvwD0
  • Export file: not recorded

Entrypoints

  • schedule: daily at 04:00

Repository Touchpoints

  • prisma/schema.prisma
  • src/app/api/search/ai/route.ts
  • src/hooks/useProjects.ts

Environment

  • none

Contracts

  • Request fields: projects.id, projects.slug, external_links.url(type=GITHUB)
  • Response fields: projects.githubStars, projects.githubStarsUpdatedAt

Related Systems

  • Upstreams: GitHub repository API, projects table, external_links table
  • Downstreams: project ranking, star sorting, home ranking display

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow reads active project GitHub links from Postgres, fetches repository metadata from GitHub, then writes star counts directly back to Postgres. This bypasses repository API routes.

Project Description Vectorization

  • Status: confirmed
  • ID: project-description-vectorization
  • Purpose: Generate and persist project embeddings used by semantic search.
  • n8n workflow id: 1AvejnM5n-WPApU1vFt9C
  • Export file: not recorded

Entrypoints

  • schedule: every 30 minutes

Repository Touchpoints

  • prisma/schema.prisma
  • prisma/migrations/20260126000000_add_project_embedding/migration.sql
  • src/app/api/search/ai/route.ts

Environment

  • none

Contracts

  • Request fields: projects.id, projects.name, projects.nameEn, projects.description, projects.descriptionEn, projects.content, projects.contentEn
  • Response fields: projects.embedding, projects.embeddingUpdatedAt

Related Systems

  • Upstreams: SiliconFlow embeddings API, projects table
  • Downstreams: RAG项目搜索, semantic search quality

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow selects active projects with null embeddings, generates BAAI/bge-m3 vectors, and writes them directly into the vector column. This is a direct DB maintenance job, not a repository API route.

GitHub Trending Discovery

  • Status: external-upstream
  • ID: github-trending-discovery
  • Purpose: Scrape GitHub Trending, dedupe candidates, filter them with AI, and enqueue project discovery tasks.
  • n8n workflow id: hughGsWismCpk7jd
  • Export file: not recorded

Entrypoints

  • schedule: daily at 01:00

Repository Touchpoints

  • src/app/api/projects/route.ts
  • src/app/api/projects/[slug]/route.ts

Environment

  • none

Contracts

  • Request fields: GitHub trending repository URL, apiKey, tasks[].sourceUrl, tasks[].sourceType
  • Response fields: dedupe shouldCreate, task creation result

Related Systems

  • Upstreams: https://github.com/trending, AI keep/discard filter
  • Downstreams: /api/discovery/check-duplicates, /api/discovery/tasks, project ingestion queue

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow scrapes GitHub Trending, filters candidates with an LLM, then posts queued tasks into discovery webhook endpoints. The current repo does not implement /api/discovery/*, so treat this as upstream data intake.

Topic Discovery

  • Status: external-upstream
  • ID: topic-discovery
  • Purpose: Search GitHub topics and keywords for agent/LLM engineering repos, dedupe them, and enqueue discovery tasks.
  • n8n workflow id: iw9vx9ih5Lt0Mobk
  • Export file: not recorded

Entrypoints

  • schedule: daily at 01:00

Repository Touchpoints

  • src/app/api/projects/route.ts
  • src/app/api/projects/[slug]/route.ts

Environment

  • none

Contracts

  • Request fields: GitHub search query, apiKey, tasks[].sourceUrl, tasks[].sourceType
  • Response fields: dedupe shouldCreate, task creation result, low recall alert

Related Systems

  • Upstreams: GitHub Search API, AI keep/discard filter, topic watchlist
  • Downstreams: /api/discovery/check-duplicates, /api/discovery/tasks, project ingestion queue

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: workflow searches agent, infra, observability, evaluation, and MCP-related repositories, then posts accepted candidates into discovery webhooks. The current repo does not implement /api/discovery/*, so this is upstream context rather than in-repo routing.

AI Chat Gateway

  • Status: adjacent
  • ID: ai-chat-gateway
  • Purpose: Expose a chat-oriented webhook wrapper around RAG项目搜索 and package search hits into chat blocks/citations.
  • n8n workflow id: Rncc22jmHEaYOG58
  • Export file: not recorded

Entrypoints

  • webhook: POST agent-park-chat

Repository Touchpoints

  • none

Environment

  • none

Contracts

  • Request fields: requestId, sessionId, clientId, locale, mode, message
  • Response fields: message.blocks, message.citations, message.meta.source, progress.stage

Related Systems

  • Upstreams: RAG项目搜索, n8n webhook ai-search
  • Downstreams: external chat clients, project detail URLs

Ownership

  • none

Notes

  • Confirmed against live n8n MCP: this workflow is related to Agent Park but does not call a repository route directly. It wraps the RAG webhook and formats citations pointing at project pages.

Exported Workflow Files

  • none

Detected Repository Touchpoints

  • src/app/api/search/ai/route.ts (39 matches)

    • L6: const N8N_WEBHOOK_URL = process.env.N8N_AI_SEARCH_WEBHOOK!
    • L8: if (!N8N_WEBHOOK_URL) {
    • L9: throw new Error('N8N_AI_SEARCH_WEBHOOK environment variable is not set')
    • L12: // n8n 返回的搜索结果 Schema（统一格式）
    • L13: const N8NSearchResponseSchema = z.object({

  • src/app/api/tags/maintenance/route.test.ts (1 matches)

    • L65: process.env.WEBHOOK_API_KEY = validApiKey;

  • src/app/api/tags/reset-projects/route.test.ts (1 matches)

    • L78: process.env.WEBHOOK_API_KEY = validApiKey;

  • src/app/api/webhook/signals/route.ts (7 matches)

    • L13: SignalWebhookPayloadSchema,
    • L15: type SignalWebhookPayload,
    • L39: const validationResult = SignalWebhookPayloadSchema.safeParse(body)
    • L51: const payload = validationResult.data as SignalWebhookPayload
    • L184: console.error(\[Webhook Signals] Error at index ${i}:`, error)`

  • src/hooks/useProjects.ts (2 matches)

    • L563: // n8n 返回的简化搜索结果类型
    • L564: export type N8NSearchResult = {

  • src/lib/auth.ts (1 matches)

    • L9: expectedApiKey: string | undefined = process.env.WEBHOOK_API_KEY

  • src/lib/validations.ts (5 matches)

    • L60: export const WebhookAuthSchema = z.object({
    • L106: export const SignalWebhookPayloadSchema = WebhookAuthSchema.extend({
    • L147: export type SignalWebhookPayload = z.infer<typeof SignalWebhookPayloadSchema>;

  • src/messages/en.json (2 matches)

    • L220: "contractTitle": "n8n Field Contract",
    • L221: "contractDescription": "Every visual element maps to fields that can be produced from n8n workflow outputs.",

  • src/messages/zh.json (2 matches)

    • L220: "contractTitle": "n8n 字段契约",
    • L221: "contractDescription": "页面元素都对应可由 n8n 输出的字段，避免出现无法供数的设计组件。",

Environment Variables

  • N8N_AI_SEARCH_WEBHOOK
  • WEBHOOK_API_KEY

Gaps To Fill

  • All detected repo touchpoints are mapped to documented workflows.

Maintenance Rules

  • When an n8n workflow changes, update docs/integrations/n8n/registry.json in the same PR.
  • If possible, export the workflow JSON into docs/integrations/n8n/exports/ and reference it from the registry.
  • Re-run pnpm n8n:context after every workflow, contract, or route change.
  • Treat this file as generated output; edit the registry instead of editing this file directly.
Reference in New Issue View Git Blame Copy Permalink