chore: 清理历史辅助文件
This commit is contained in:
@@ -1,66 +0,0 @@
|
||||
# docs/ - Project Documentation
|
||||
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Technical documentation, design plans, and implementation guides for the agent_park project.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
docs/
|
||||
├── api-reference.md # API endpoint documentation
|
||||
├── api-testing-guide.md # API testing instructions
|
||||
├── discovery-workflow.md # Project discovery system docs
|
||||
├── e2e-testing-guide.md # Playwright E2E guide
|
||||
├── verification-report.md # Feature verification reports
|
||||
├── analyst.md # Product analysis notes
|
||||
├── n8n/ # n8n workflow documentation
|
||||
│ ├── historical-workflow-design.md
|
||||
│ ├── incremental-workflow-design.md
|
||||
│ ├── frontier-signals-workflow.md
|
||||
│ ├── tag-janitor-workflow.json
|
||||
│ ├── project-tag-reset-workflow.json
|
||||
│ ├── project-tag-reset-workflow.md
|
||||
│ ├── github-link-janitor-workflow.json
|
||||
│ ├── github-link-janitor-workflow.md
|
||||
│ ├── github-link-repair-workflow.json
|
||||
│ ├── github-link-repair-workflow.md
|
||||
│ ├── github-stars-refresh-workflow.json
|
||||
│ └── github-stars-refresh-workflow.md
|
||||
└── plans/ # Design & implementation plans
|
||||
├── 2026-01-25-ai-search-system-design.md
|
||||
├── 2026-01-25-ai-search-implementation.md
|
||||
├── 2025-01-25-ai-timeline-feature-design.md
|
||||
├── 2025-01-25-ai-timeline-implementation.md
|
||||
├── 2026-01-25-keyword-cloud-system-design.md
|
||||
└── 2026-01-25-keyword-cloud-implementation.md
|
||||
```
|
||||
|
||||
## KEY DOCUMENTS
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| `api-reference.md` | Complete API documentation |
|
||||
| `discovery-workflow.md` | Project discovery architecture |
|
||||
| `plans/*.md` | Feature design & implementation specs |
|
||||
| `n8n/*.md` | n8n workflow design docs |
|
||||
| `n8n/frontier-signals-workflow.md` | Multi-source frontier signals ingestion workflow (AI Agent filter) |
|
||||
| `n8n/project-tag-reset-workflow.json` | Project tag reset workflow (multi-AI category classification) |
|
||||
|
||||
## FOR AI AGENTS
|
||||
|
||||
### When Adding Documentation
|
||||
|
||||
1. Place design docs in `plans/` with date prefix
|
||||
2. Update this AGENTS.md with new file entries
|
||||
3. Follow existing markdown formatting
|
||||
|
||||
### Related Files
|
||||
|
||||
- `CLAUDE.md` - Main project context (root)
|
||||
- `AGENTS.md` - Project knowledge base (root)
|
||||
- `.claude/` - Custom agents & commands
|
||||
|
||||
<!-- MANUAL: Additional notes can be added below -->
|
||||
-158
@@ -1,158 +0,0 @@
|
||||
---
|
||||
|
||||
## 🎯 现状问题诊断
|
||||
|
||||
### 1. 信息架构问题
|
||||
- **标签体系混乱**：有的项目标了"本地部署/macOS/iOS/Android"（4个标签），有的只有"✨"，标准不统一
|
||||
- **缺乏分类维度**：用户无法快速筛选"开源/闭源"、"可商用/个人项目"、"多智能体/单智能体"
|
||||
- **没有时间维度**：看不出项目是新发布还是经典项目，对 Agent 这个快速迭代的领域很关键
|
||||
|
||||
### 2. 用户体验断层
|
||||
- **卡片信息过载/不足并存**：描述长短不一，但缺少关键决策信息（GitHub stars？是否开源？演示链接？）
|
||||
- **无快速筛选**：当项目超过20个时，浏览成本会指数级上升
|
||||
- **缺乏"为什么值得关注"**：单纯罗列不如策展（Curation），需要策展人视角的推荐理由
|
||||
|
||||
### 3. 技术呈现问题
|
||||
- **移动端适配**：从代码结构看是响应式，但卡片在手机上可能过于拥挤
|
||||
- **无暗色模式**：开发者群体对暗色模式有强需求，实现成本低（CSS media query）
|
||||
- **加载性能**：如果 n8n 工作流生成的是静态 Markdown，建议预渲染为 HTML 提升首屏速度
|
||||
|
||||
---
|
||||
|
||||
## 💡 轻量级但高价值的功能设计
|
||||
|
||||
基于"不做重，但要做巧"的原则，推荐以下功能：
|
||||
|
||||
### 阶段一：核心体验完善（2周内）
|
||||
|
||||
**1. 极简标签系统（三层维度）**
|
||||
```
|
||||
类型标签：🤖 Chatbot | 🔄 Multi-Agent | 🧠 Memory | 👁️ Vision | 🛠️ Tool Use
|
||||
形态标签：📦 开源 | ☁️ SaaS | 💻 本地部署 | 📱 App
|
||||
热度标签：🔥 Trending | ⭐ Classic | 🆕 New
|
||||
```
|
||||
*实现：纯 CSS 过滤，无需后端，前端 JS 筛选即可*
|
||||
|
||||
**2. "30秒决策"信息卡片**
|
||||
每个项目卡片补充3个关键字段（n8n工作流抓取时补充）：
|
||||
- **GitHub Stars**（如果是开源）
|
||||
- **体验方式**：Live Demo / 下载 / 仅代码
|
||||
- **适用场景**：一句话场景（如"适合搭建个人知识库"）
|
||||
|
||||
**3. 每日/每周精选（Newsletter 化）**
|
||||
不增加功能，而是**内容运营策略**：
|
||||
- 首页顶部固定"本周编辑推荐"（3个项目+一句话推荐理由）
|
||||
- 底部增加邮件订阅框（用 Buttondown 或 Revue，零成本）
|
||||
- 归档页面按周聚合（`/week-04-2025`）
|
||||
|
||||
### 阶段二：社区感与互动（1个月内）
|
||||
|
||||
**4. "使用报告"轻互动**
|
||||
不同于评论系统（太重），采用**投票+标签**：
|
||||
- "你在用吗？" 👍 / 👎（匿名）
|
||||
- "适用场景"多选标签（用户可添加，类似 StackOverflow 的标签系统）
|
||||
- 数据存储：Airtable 或 Notion API（轻量级数据库）
|
||||
|
||||
**5. Agent 项目 Twitter 趋势墙**
|
||||
无需自己生成内容，聚合展示：
|
||||
- 嵌入 Twitter List（创建一个"Agent Builders"列表）
|
||||
- 或展示特定 hashtag（如 `#AIAgent`）的最新热门推文
|
||||
- 实现：Twitter 嵌入式时间线，零维护成本
|
||||
|
||||
**6. 极简提交表单优化**
|
||||
当前"立即提交"大概率跳转到表单，优化为：
|
||||
- 预填项目模板（GitHub URL 自动抓取信息）
|
||||
- 支持提交者写"推荐语"（策展人视角）
|
||||
- 审核流：GitHub Issues 或 Airtable 表单（不用开发后台）
|
||||
|
||||
### 阶段三：开发者工具化（2个月内）
|
||||
|
||||
**7. Agent 项目 RSS 聚合**
|
||||
开发者刚需：一站式追踪所有 Agent 项目更新
|
||||
- 为每个项目生成 RSS 源监控（GitHub releases）
|
||||
- 提供聚合 RSS（用户订阅一个即可看全站更新）
|
||||
- 技术：RSSHub 或 n8n 自动生成
|
||||
|
||||
**8. "Agent 构建模式"分类**
|
||||
垂直领域细分（这是你的差异化）：
|
||||
- **ReAct 模式**项目集合
|
||||
- **Plan-and-Execute**项目
|
||||
- **Multi-Agent 协作框架**
|
||||
- **Function Calling 工具库**
|
||||
帮助开发者按技术方案选型，而非只看功能。
|
||||
|
||||
---
|
||||
|
||||
## 📋 分阶段实施计划（ Roadmap ）
|
||||
|
||||
### Week 1-2：基础优化
|
||||
- [ ] 统一标签体系（3层9个标签以内）
|
||||
- [ ] 修改项目卡片模板（增加 Stars/Demo 链接字段）
|
||||
- [ ] 增加暗色模式（`prefers-color-scheme` 媒体查询）
|
||||
- [ ] 优化移动端卡片布局（单列+横向滚动标签）
|
||||
|
||||
### Week 3-4：内容运营
|
||||
- [ ] 建立编辑推荐机制（每周手动精选3个）
|
||||
- [ ] 上线邮件订阅（嵌入 Buttondown）
|
||||
- [ ] 优化提交表单（GitHub URL 自动拉取）
|
||||
- [ ] 创建 Twitter/X 账号同步发布精选
|
||||
|
||||
### Month 2：互动功能
|
||||
- [ ] 增加轻量级投票系统（用 Upstash Redis 或 Airtable）
|
||||
- [ ] 上线 RSS 订阅功能
|
||||
- [ ] 增加"技术模式"分类维度
|
||||
- [ ] 发布首份《Agent Landscape 月报》（PDF 轻量报告）
|
||||
|
||||
### Month 3：生态扩展
|
||||
- [ ] 推出"Agent Builder 访谈"（轻量级文字访谈，每月2期）
|
||||
- [ ] 建立 Discord/Telegram 群组（社区沉淀）
|
||||
- [ ] 尝试"项目雷达"功能（预测下周可能火的项目）
|
||||
|
||||
---
|
||||
|
||||
## 💰 变现可能性分析（从轻到重）
|
||||
|
||||
基于"保持轻量"的前提，按可行性排序：
|
||||
|
||||
### 1. **策展付费（轻量，推荐优先尝试）**
|
||||
- **模式**：每周付费 Newsletter（$5/月或$50/年），提供更深度的项目分析、代码解读、创始人访谈
|
||||
- **可行性**：⭐⭐⭐⭐⭐ 你已经用 n8n 做内容聚合，增加深度分析即可，无需改技术架构
|
||||
- **受众**：Agent 开发者愿意为高质量信息付费，参考 Lenny's Newsletter（产品经理领域）
|
||||
|
||||
### 2. **精准职位板（轻量）**
|
||||
- **模式**："Agent 相关岗位"板块，公司付费发帖（$100/月）
|
||||
- **可行性**：⭐⭐⭐⭐ 当下 Agent 工程师需求旺盛，但供给分散，你的受众正是招聘方想要的
|
||||
- **优势**：比大型招聘站更精准，比 LinkedIn 更垂直
|
||||
|
||||
### 3. **开源项目赞助分成（超轻量）**
|
||||
- **模式**：项目卡片增加"赞助该项目"按钮，跳转 GitHub Sponsors，你收取 5-10% 导流费或获得 affiliate 返点
|
||||
- **可行性**：⭐⭐⭐ 需要与项目方谈合作，但初期可以作为增值服务免费提供，建立信任后变现
|
||||
|
||||
### 4. **轻量级广告/赞助（需谨慎）**
|
||||
- **模式**：接受 Agent 框架、云服务（如 LangSmith、Langfuse）的广告位
|
||||
- **可行性**：⭐⭐⭐ 需要流量基础（月UV 1万+），且要保持克制避免破坏体验
|
||||
- **建议**：以"赞助商推荐"形式融入内容，而非 banner 广告
|
||||
|
||||
### 5. **数据/洞察服务（未来方向）**
|
||||
- **模式**：出售 Agent 趋势数据报告（GitHub 增长趋势、技术栈迁移方向）
|
||||
- **可行性**：⭐⭐ 需要积累 6-12 个月数据，且需要品牌背书
|
||||
- **风险**：会变重，建议保持轻量，只出季度免费报告建立权威性
|
||||
|
||||
### ❌ 不建议的变现方式
|
||||
- **付费墙阻断访问**：违背导航站开放属性
|
||||
- **复杂的会员系统**：开发与维护成本高
|
||||
- **交易佣金**：涉及支付、合规，太重
|
||||
|
||||
---
|
||||
|
||||
## 🚀 立即可做的3个改动（本周）
|
||||
|
||||
如果你只想快速优化，先做这三件：
|
||||
|
||||
1. **标签标准化**：删除所有重复/冗长标签，只用 类型+形态 二维（如 `🤖Chatbot` `📦开源`）
|
||||
2. **增加"一键体验"按钮**：在卡片上直接放 🔗Demo 或 💻GitHub 图标，减少用户点击成本
|
||||
3. **顶部增加时间线**：小字标注"本周新增 X 个项目，共收录 Y 个"，营造更新感
|
||||
|
||||
**核心建议**：Agent Park 现在的定位应该是 **"Agent 爱好者的 Hacker News + Product Hunt 混合体"**，保持策展人（Curator）视角比做全量数据库更有价值。你的 n8n 工作流是护城河，但**人工精选的品味**才是核心竞争力。
|
||||
|
||||
需要我针对某个具体功能（比如 n8n 工作流优化方案、暗色模式 CSS、或者邮件订阅文案）展开详细方案吗？
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,502 +0,0 @@
|
||||
# AI 智能搜索系统设计文档
|
||||
|
||||
**日期**: 2026-01-25
|
||||
**作者**: Claude Code
|
||||
**状态**: 设计阶段
|
||||
|
||||
## 概述
|
||||
|
||||
为项目列表添加 AI 语义搜索功能，用户可通过自然语言描述需求，系统通过向量相似度匹配返回相关项目，而非传统的关键词模糊搜索。
|
||||
|
||||
### 核心目标
|
||||
|
||||
- ✅ 支持自然语言查询（如"帮我找做图像生成的项目"）
|
||||
- ✅ 基于向量相似度的语义匹配
|
||||
- ✅ 完全在 n8n 中实现 AI 逻辑，Next.js 应用保持纯净
|
||||
- ✅ 利用现有 Neon 数据库的 pgvector 扩展
|
||||
|
||||
---
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 整体架构
|
||||
|
||||
```
|
||||
前端（Next.js）
|
||||
↓
|
||||
API 代理（/api/search/ai）
|
||||
↓
|
||||
n8n 工作流（AI 逻辑）
|
||||
↓
|
||||
Neon 数据库（pgvector）
|
||||
```
|
||||
|
||||
### 核心组件
|
||||
|
||||
**数据层（Neon + pgvector）**
|
||||
- `Project` 表添加 `embedding` 字段存储向量
|
||||
- HNSW 索引加速相似度搜索
|
||||
- 向量维度：1536（OpenAI text-embedding-3-small）
|
||||
|
||||
**服务层（n8n 工作流）**
|
||||
- **向量化工作流**：定时扫描未向量化项目，调用 OpenAI API 生成向量
|
||||
- **AI 搜索工作流**：接收查询 → 生成向量 → 相似度搜索 → 返回结果
|
||||
|
||||
**前端层（Next.js）**
|
||||
- 搜索框增加 AI 模式切换按钮
|
||||
- 显示相似度评分和匹配原因
|
||||
|
||||
---
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### Schema 修改
|
||||
|
||||
```prisma
|
||||
model Project {
|
||||
// ... 现有字段
|
||||
|
||||
// 新增：向量嵌入字段
|
||||
embedding vector(1536)? // pgvector 类型
|
||||
embeddingUpdatedAt DateTime? // 向量化更新时间
|
||||
}
|
||||
```
|
||||
|
||||
### 迁移 SQL
|
||||
|
||||
```sql
|
||||
-- 启用 pgvector 扩展
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
|
||||
-- 添加向量列
|
||||
ALTER TABLE "Project" ADD COLUMN "embedding" vector(1536);
|
||||
ALTER TABLE "Project" ADD COLUMN "embeddingUpdatedAt" TIMESTAMP;
|
||||
|
||||
-- 创建 HNSW 索引（余弦距离）
|
||||
CREATE INDEX idx_project_embedding_cosine
|
||||
ON "Project" USING hnsw ("embedding" vector_cosine_ops)
|
||||
WITH (m = 16, ef_construction = 64);
|
||||
|
||||
-- 复合索引（查找未向量化项目）
|
||||
CREATE INDEX idx_project_embedding_null
|
||||
ON "Project" ("id")
|
||||
WHERE "embedding" IS NULL;
|
||||
```
|
||||
|
||||
### 向量化内容策略
|
||||
|
||||
**字段权重分配：**
|
||||
- 名称（40%）：`name` + `nameEn`
|
||||
- 描述（40%）：`description` + `descriptionEn`
|
||||
- 标签（15%）：`tags`（逗号连接）
|
||||
- 详细内容（5%）：`content` + `contentEn`（截取前 500 字）
|
||||
|
||||
**示例输入文本：**
|
||||
```
|
||||
AI Video Generator
|
||||
一个基于人工智能的视频生成工具，可以自动从文本生成高质量视频...
|
||||
人工智能, 视频生成, AIGC
|
||||
详细功能介绍...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## n8n 工作流设计
|
||||
|
||||
### 工作流 1：定时向量化
|
||||
|
||||
**触发器**：Cron 表达式（每 5 分钟）
|
||||
|
||||
```
|
||||
*/5 * * * *
|
||||
```
|
||||
|
||||
**流程**：
|
||||
```
|
||||
触发器
|
||||
↓
|
||||
查询未向量化项目（LIMIT 20）
|
||||
↓
|
||||
批量处理（每批 5 个）
|
||||
↓
|
||||
构造文本内容（合并字段）
|
||||
↓
|
||||
调用 OpenAI Embeddings API
|
||||
↓
|
||||
更新数据库 embedding 字段
|
||||
↓
|
||||
等待 1 秒（控制速率）
|
||||
↓
|
||||
下一批
|
||||
```
|
||||
|
||||
**PostgreSQL 查询**：
|
||||
```sql
|
||||
SELECT id, name, "nameEn", description, "descriptionEn",
|
||||
content, "contentEn"
|
||||
FROM "Project"
|
||||
WHERE "embedding" IS NULL
|
||||
AND "status" = 'ACTIVE'
|
||||
LIMIT 20
|
||||
```
|
||||
|
||||
**错误处理**：
|
||||
- API 限流：指数退避重试（1s → 2s → 4s）
|
||||
- 最多重试 3 次
|
||||
- 失败记录日志
|
||||
|
||||
### 工作流 2：AI 搜索
|
||||
|
||||
**触发器**：Webhook（`/webhook/ai-search`）
|
||||
|
||||
**流程**：
|
||||
```
|
||||
Webhook 接收查询
|
||||
↓
|
||||
接收参数：{ query, locale, limit, filters }
|
||||
↓
|
||||
调用 OpenAI Embeddings API（生成查询向量）
|
||||
↓
|
||||
PostgreSQL 向量相似度搜索
|
||||
↓
|
||||
应用过滤条件（tags, status）
|
||||
↓
|
||||
格式化结果（添加相似度评分）
|
||||
↓
|
||||
返回 JSON 响应
|
||||
```
|
||||
|
||||
**PostgreSQL 查询**：
|
||||
```sql
|
||||
SELECT
|
||||
id, name, "nameEn", slug, description, "descriptionEn",
|
||||
1 - (embedding <=> '{{ query_vector }}'::vector) as similarity
|
||||
FROM "Project"
|
||||
WHERE "embedding" IS NOT NULL
|
||||
AND "status" = 'ACTIVE'
|
||||
ORDER BY embedding <=> '{{ query_vector }}'::vector
|
||||
LIMIT {{ limit || 20 }}
|
||||
```
|
||||
|
||||
**响应格式**：
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"project": { /* 项目数据 */ },
|
||||
"similarity": 0.89,
|
||||
"matchReason": "项目名称和描述与图像生成高度相关"
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"searchTime": 156
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next.js API 设计
|
||||
|
||||
### 路由配置
|
||||
|
||||
**文件**：`src/app/api/search/ai/route.ts`
|
||||
|
||||
```typescript
|
||||
import { NextResponse } from 'next/server'
|
||||
|
||||
const N8N_WEBHOOK_URL = process.env.N8N_AI_SEARCH_WEBHOOK
|
||||
|
||||
export async function POST(request: Request) {
|
||||
try {
|
||||
const body = await request.json()
|
||||
|
||||
// 转发到 n8n 工作流
|
||||
const n8nResponse = await fetch(N8N_WEBHOOK_URL, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(body)
|
||||
})
|
||||
|
||||
const results = await n8nResponse.json()
|
||||
|
||||
return NextResponse.json(results)
|
||||
|
||||
} catch (error) {
|
||||
return NextResponse.json(
|
||||
{ error: 'Search failed' },
|
||||
{ status: 500 }
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**请求格式**：
|
||||
```json
|
||||
{
|
||||
"query": "帮我找做图像生成的AI工具",
|
||||
"locale": "zh",
|
||||
"limit": 20,
|
||||
"filters": {
|
||||
"tags": ["AIGC"],
|
||||
"status": "ACTIVE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前端交互设计
|
||||
|
||||
### UI 组件修改
|
||||
|
||||
**文件**：`src/components/search/SearchBar.tsx`
|
||||
|
||||
**功能**：
|
||||
- 添加 AI 模式切换按钮（Sparkles 图标）
|
||||
- AI 模式时按钮高亮（金色背景）
|
||||
- 不同模式的占位符提示
|
||||
- 加载状态优化
|
||||
|
||||
**关键代码**：
|
||||
```tsx
|
||||
<button
|
||||
onClick={() => setAiMode(!aiMode)}
|
||||
className={`
|
||||
px-3 py-2 border-2 transition-all
|
||||
${aiMode
|
||||
? 'bg-yellow-400 border-yellow-500 text-black'
|
||||
: 'bg-white border-gray-300 text-gray-600'
|
||||
}
|
||||
`}
|
||||
title="AI 语义搜索"
|
||||
>
|
||||
<Sparkles className="w-5 h-5" />
|
||||
</button>
|
||||
```
|
||||
|
||||
### AI 搜索结果展示
|
||||
|
||||
**文件**：`src/components/search/AISearchResults.tsx`
|
||||
|
||||
**功能**：
|
||||
- 显示相似度指示条（左侧彩色条）
|
||||
- 相似度评分（0-100%）
|
||||
- 匹配原因说明（可选）
|
||||
- 颜色编码：绿色（>0.8）、黄色（>0.6）、红色（<0.6）
|
||||
|
||||
### 搜索模式对比
|
||||
|
||||
| 特性 | 传统搜索 | AI 搜索 |
|
||||
|------|---------|---------|
|
||||
| 占位符 | "搜索项目名称..." | "描述你想要的项目..." |
|
||||
| 匹配方式 | 关键词模糊匹配 | 向量语义相似度 |
|
||||
| 返回速度 | 极快（<100ms） | 较快（1-3s） |
|
||||
| 结果增强 | 无 | 相似度评分 + 匹配原因 |
|
||||
| 提示信息 | 无 | "💡 试试：'帮我找能生成视频的 AI 工具'" |
|
||||
|
||||
---
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
### Next.js 应用（`.env.local`）
|
||||
|
||||
```bash
|
||||
# Neon 数据库（已有）
|
||||
DATABASE_URL=postgres://...
|
||||
|
||||
# n8n Webhook
|
||||
N8N_AI_SEARCH_WEBHOOK=https://your-n8n-instance.com/webhook/ai-search
|
||||
N8N_WEBHOOK_API_KEY=your-webhook-key # 可选，用于安全验证
|
||||
```
|
||||
|
||||
### n8n 工作流
|
||||
|
||||
```bash
|
||||
# OpenAI API（用于 Embeddings）
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# Neon 数据库（与 Next.js 共享）
|
||||
NEON_DATABASE_URL=postgres://...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理与优化
|
||||
|
||||
### 错误处理策略
|
||||
|
||||
**n8n 工作流**：
|
||||
- API 限流：指数退避重试
|
||||
- API Key 无效：发送告警
|
||||
- 数据库查询失败：返回友好错误信息
|
||||
- 向量未就绪：提示用户稍后重试
|
||||
|
||||
**前端**：
|
||||
- 10 秒超时限制
|
||||
- 超时或错误时自动降级到传统搜索
|
||||
- Toast 消息提示用户
|
||||
|
||||
### 性能优化
|
||||
|
||||
**数据库查询**：
|
||||
- 只返回必要字段（不返回 content）
|
||||
- 使用 HNSW 索引
|
||||
- 设置查询超时（5s）
|
||||
|
||||
**缓存策略（可选）**：
|
||||
- Redis 缓存常见查询结果（5 分钟 TTL）
|
||||
- 内存缓存热门查询
|
||||
|
||||
### 监控指标
|
||||
|
||||
- 平均搜索响应时间
|
||||
- API 调用次数/成本
|
||||
- 向量化完成率
|
||||
- 错误率
|
||||
|
||||
---
|
||||
|
||||
## 成本估算
|
||||
|
||||
### OpenAI Embeddings API
|
||||
|
||||
**定价**：
|
||||
- text-embedding-3-small：$0.00002 / 1K tokens
|
||||
|
||||
**估算**：
|
||||
- 单个项目（500 tokens）：$0.00001
|
||||
- 1000 个项目：$0.01
|
||||
- 单次搜索（10 tokens）：$0.0000002
|
||||
- 1000 次搜索：$0.0002
|
||||
|
||||
**月度预算**：$5 可处理 50 万个项目或 2500 万次搜索
|
||||
|
||||
### Neon 免费套餐
|
||||
|
||||
**限制**：
|
||||
- 存储：0.5GB
|
||||
- 计算：300 小时/月
|
||||
|
||||
**向量存储**：
|
||||
- 单个项目（1536 维）：3KB（半精度）
|
||||
- 1000 个项目：3MB
|
||||
- 10,000 个项目：30MB ✅
|
||||
|
||||
**结论**：免费套餐完全够用（可支持 5,000-10,000 个项目）
|
||||
|
||||
---
|
||||
|
||||
## 测试计划
|
||||
|
||||
### 单元测试
|
||||
|
||||
```typescript
|
||||
// src/__tests__/search.test.ts
|
||||
describe('AI Search', () => {
|
||||
it('should handle empty query', async () => {
|
||||
const response = await fetch('/api/search/ai', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ query: '' })
|
||||
})
|
||||
expect(response.status).toBe(400)
|
||||
})
|
||||
|
||||
it('should fallback to traditional search on error', async () => {
|
||||
// 测试错误降级逻辑
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### E2E 测试
|
||||
|
||||
```typescript
|
||||
// tests/e2e/ai-search.spec.ts
|
||||
test('AI 搜索功能', async ({ page }) => {
|
||||
await page.goto('/zh/projects')
|
||||
await page.click('[data-testid="ai-mode-toggle"]')
|
||||
await page.fill('input[name="search"]', '视频生成工具')
|
||||
await page.press('input[name="search"]', 'Enter')
|
||||
await expect(page.locator('.ai-search-results')).toBeVisible()
|
||||
})
|
||||
```
|
||||
|
||||
### 集成测试
|
||||
|
||||
- 测试 n8n 工作流端到端
|
||||
- 验证向量搜索结果准确性
|
||||
- 测试错误场景（API 限流、数据库连接失败）
|
||||
|
||||
---
|
||||
|
||||
## 部署清单
|
||||
|
||||
### 数据库准备
|
||||
|
||||
- [x] 运行数据库迁移
|
||||
- [x] 验证 pgvector 扩展已启用
|
||||
- [x] 检查 HNSW 索引创建成功
|
||||
|
||||
### n8n 配置
|
||||
|
||||
- [ ] 创建向量化工作流
|
||||
- [ ] 配置 Cron 触发器（每 5 分钟）
|
||||
- [ ] 配置 PostgreSQL 节点
|
||||
- [ ] 配置 OpenAI Embeddings 节点
|
||||
- [ ] 添加错误处理和重试逻辑
|
||||
|
||||
- [ ] 创建 AI 搜索工作流
|
||||
- [ ] 配置 Webhook 触发器
|
||||
- [ ] 配置 OpenAI Embeddings 节点
|
||||
- [ ] 配置 PostgreSQL 向量查询
|
||||
- [ ] 配置结果格式化
|
||||
|
||||
- [ ] 测试工作流
|
||||
- [ ] 手动触发向量化流程
|
||||
- [ ] 测试 Webhook 搜索
|
||||
- [ ] 验证错误处理
|
||||
|
||||
### Next.js 部署
|
||||
|
||||
- [ ] 添加环境变量（N8N_WEBHOOK_URL）
|
||||
- [ ] 创建 API 路由（`/api/search/ai`）
|
||||
- [ ] 更新 SearchBar 组件
|
||||
- [ ] 创建 AISearchResults 组件
|
||||
- [ ] 本地测试完整流程
|
||||
- [ ] 部署到 Vercel
|
||||
|
||||
### 验证步骤
|
||||
|
||||
1. **向量化测试**：
|
||||
```sql
|
||||
-- 检查已向量化项目数
|
||||
SELECT COUNT(*) FROM "Project" WHERE embedding IS NOT NULL;
|
||||
```
|
||||
|
||||
2. **搜索测试**：
|
||||
- 输入自然语言查询
|
||||
- 验证返回结果相关性
|
||||
- 检查相似度评分
|
||||
|
||||
3. **性能测试**：
|
||||
- 测量平均响应时间
|
||||
- 验证并发处理能力
|
||||
|
||||
---
|
||||
|
||||
## 后续优化方向
|
||||
|
||||
1. **混合搜索**：结合关键词搜索和向量搜索，提升准确率
|
||||
2. **查询缓存**：Redis 缓存热门查询结果
|
||||
3. **A/B 测试**：对比传统搜索和 AI 搜索的用户体验
|
||||
4. **多模态搜索**：支持图片、语音输入
|
||||
5. **个性化排序**：基于用户历史行为优化结果
|
||||
6. **自动标签建议**：AI 分析项目内容推荐标签
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Neon pgvector 文档](https://neon.com/docs/extensions/pgvector)
|
||||
- [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings)
|
||||
- [pgvector GitHub](https://github.com/pgvector/pgvector)
|
||||
- [HNSW 算法论文](https://arxiv.org/abs/1603.09320)
|
||||
@@ -1,88 +0,0 @@
|
||||
# Timeline 页面修复验证报告
|
||||
|
||||
## 验证时间
|
||||
2025-01-27
|
||||
|
||||
## 验证方法
|
||||
使用 chrome-devtools-mcp 自动化测试工具
|
||||
|
||||
## 验证结果
|
||||
|
||||
### ✅ 页面结构
|
||||
- 标题: "THE STORY OF A.I."
|
||||
- 副标题: "Pinned. Stacked. Zigzagged."
|
||||
- 7个年份分组 (2023 → 2017)
|
||||
- 12个事件卡片正确渲染
|
||||
- Newsletter 订阅区域正常
|
||||
- Back to top 按钮存在
|
||||
|
||||
### ✅ 动画效果验证
|
||||
**CSS Transition 配置:**
|
||||
```css
|
||||
transition: all 0.4s cubic-bezier(0.25, 0.8, 0.25, 1)
|
||||
```
|
||||
|
||||
**Hover 效果实测:**
|
||||
- z-index: 50 (从40提升到50) ✅
|
||||
- transform: scale(1.05) translateY(-20px) ✅
|
||||
- marginRight: 20px (从-224px增加) ✅
|
||||
- rotation: 0deg (从旋转角度变正) ✅
|
||||
|
||||
### ✅ 视觉元素
|
||||
- 背景网格 (40px 网格，10% 透明度) ✅
|
||||
- 装饰性 SVG 形状 (脉动动画) ✅
|
||||
- Tape 装饰 (12个，半透明 + 模糊) ✅
|
||||
- 年份标签 (交替左右布局，±2度旋转) ✅
|
||||
- 时间线连接线 (垂直渐变线) ✅
|
||||
- 时间线圆点 (每个年份一个) ✅
|
||||
|
||||
### ✅ 数据完整性
|
||||
- 2017年: Transformer 论文
|
||||
- 2018年: GPT-1, BERT (共3个，含测试数据)
|
||||
- 2019年: GPT-2
|
||||
- 2020年: GPT-3
|
||||
- 2021年: GitHub Copilot
|
||||
- 2022年: ChatGPT
|
||||
- 2023年: GPT-4, Claude
|
||||
|
||||
### ✅ 控制台检查
|
||||
- 无错误
|
||||
- 仅1个资源预加载警告（可忽略）
|
||||
|
||||
## 与原始设计对比
|
||||
|
||||
### 已实现
|
||||
- ✅ 标题风格: "THE STORY OF A.I."
|
||||
- ✅ 单一年份标签（您要求的）
|
||||
- ✅ 卡片堆叠效果
|
||||
- ✅ Hover 动画（上浮 + 缩放 + 旋转归零）
|
||||
- ✅ Tape 装饰（半透明 + 模糊）
|
||||
- ✅ 背景网格
|
||||
- ✅ 装饰性 SVG 形状
|
||||
- ✅ Newsletter 区域
|
||||
- ✅ Back to top 按钮
|
||||
|
||||
### 设计差异（已修复）
|
||||
- ✅ 动画过渡曲线：cubic-bezier(0.25, 0.8, 0.25, 1)
|
||||
- ✅ Hover z-index 提升：50
|
||||
- ✅ Transform 包含 translateY(-20px) 和 scale(1.05)
|
||||
- ✅ Margin 调整实现展开效果
|
||||
|
||||
## 性能指标
|
||||
- 页面加载时间: ~6s (首次编译)
|
||||
- 后续导航: <1s
|
||||
- 动画帧率: 60fps (smooth)
|
||||
- 总卡片区: 12
|
||||
- 总年份: 7
|
||||
|
||||
## 结论
|
||||
✅ **所有核心功能已实现并与原始设计对齐**
|
||||
- 动画效果流畅
|
||||
- 视觉风格匹配
|
||||
- 数据完整准确
|
||||
- 用户体验良好
|
||||
|
||||
## 建议
|
||||
1. CSS 已正确加载到 globals.css
|
||||
2. 动画效果已验证工作正常
|
||||
3. 可以部署到生产环境
|
||||
Reference in New Issue
Block a user