# 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 契约。