chore: 移除项目发现系统本地组件并更新文档
移除 .claude 目录下的项目发现系统组件： - content-explorer-agent（项目内容探索专家） - api-submitter-agent（API 提交专家） - discover-projects 命令 - project-content-template 模板 同时更新配置和文档： - settings.json 添加代理配置 - api-reference.md 完善项目发现系统 API 说明 Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
+395
-15
@@ -10,6 +10,8 @@
|
||||
- [3.1 创建/更新项目 (Webhook)](#31-创建更新项目-webhook)
|
||||
- [3.2 获取项目详情](#32-获取项目详情)
|
||||
- [3.3 删除项目](#33-删除项目)
|
||||
- [3.4 项目发现系统 API](#34-项目发现系统-api)
|
||||
- [3.5 去重检查 API](#35-去重检查-api)
|
||||
- [4. 数据模型](#4-数据模型)
|
||||
- [5. 错误码](#5-错误码)
|
||||
|
||||
@@ -112,14 +114,14 @@ POST /api/webhook/projects
|
||||
```typescript
|
||||
{
|
||||
// 基础信息（必填）
|
||||
name: string; // 中文名称
|
||||
nameEn?: string; // 英文名称（可选）
|
||||
description: string; // 中文描述
|
||||
descriptionEn?: string; // 英文描述（可选）
|
||||
name: string; // 中文名称 (1-200 字符)
|
||||
nameEn?: string; // 英文名称（可选，1-200 字符）
|
||||
description: string; // 中文描述 (10-500 字符)
|
||||
descriptionEn?: string; // 英文描述（可选，10-500 字符）
|
||||
|
||||
// 内容（可选）
|
||||
content?: string; // 中文内容（Markdown 格式）
|
||||
contentEn?: string; // 英文内容（Markdown 格式）
|
||||
content?: string; // 中文内容（Markdown 格式，最大 10000 字符）
|
||||
contentEn?: string; // 英文内容（Markdown 格式，最大 10000 字符）
|
||||
|
||||
// 状态（可选）
|
||||
status?: "ACTIVE" | "ARCHIVED"; // 默认: "ACTIVE"
|
||||
@@ -390,6 +392,351 @@ curl -X DELETE https://your-domain.com/api/projects/langchain \
|
||||
|
||||
---
|
||||
|
||||
### 3.4 项目发现系统 API
|
||||
|
||||
项目发现系统用于自动化探索和收录 AI 项目，支持任务创建、状态追踪和项目提交。
|
||||
|
||||
#### 3.4.1 创建探索任务
|
||||
|
||||
批量创建新的项目探索任务。
|
||||
|
||||
```
|
||||
POST /api/discovery/tasks
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
|
||||
```typescript
|
||||
{
|
||||
apiKey: string; // API 密钥
|
||||
tasks: Array<{
|
||||
sourceUrl: string; // 探索目标 URL (GitHub 仓库链接等)
|
||||
sourceType?: string; // 来源类型，默认 "manual"
|
||||
}>; // 1-50 个任务
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"created": 5,
|
||||
"skipped": 2,
|
||||
"total": 7
|
||||
}
|
||||
```
|
||||
|
||||
**去重逻辑**:
|
||||
- 如果 `sourceUrl` 已存在任务，自动跳过并计入 `skipped`
|
||||
|
||||
---
|
||||
|
||||
#### 3.4.2 获取任务列表
|
||||
|
||||
获取待处理或指定状态的探索任务列表。
|
||||
|
||||
```
|
||||
GET /api/discovery/tasks?status=PENDING&limit=10&offset=0
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| status | string | 否 | 筛选状态: PENDING/IN_PROGRESS/COMPLETED/FAILED |
|
||||
| limit | number | 否 | 每页数量，默认 10，最大 100 |
|
||||
| offset | number | 否 | 偏移量，默认 0 |
|
||||
|
||||
**请求头**:
|
||||
|
||||
```
|
||||
x-api-key: your-api-key
|
||||
```
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"tasks": [
|
||||
{
|
||||
"id": "clx1234567890",
|
||||
"sourceUrl": "https://github.com/user/repo",
|
||||
"sourceType": "manual",
|
||||
"status": "PENDING",
|
||||
"createdAt": "2024-01-15T00:00:00.000Z",
|
||||
"startedAt": null,
|
||||
"completedAt": null,
|
||||
"projectId": null,
|
||||
"explorationData": null,
|
||||
"explorationSummary": null,
|
||||
"errorMessage": null,
|
||||
"retryCount": 0
|
||||
}
|
||||
],
|
||||
"total": 25,
|
||||
"hasMore": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.4.3 获取任务详情
|
||||
|
||||
获取单个探索任务的详细信息。
|
||||
|
||||
```
|
||||
GET /api/discovery/tasks/:id
|
||||
```
|
||||
|
||||
**无需认证** (只读端点)
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"task": {
|
||||
"id": "clx1234567890",
|
||||
"sourceUrl": "https://github.com/user/repo",
|
||||
"sourceType": "manual",
|
||||
"status": "COMPLETED",
|
||||
"createdAt": "2024-01-15T00:00:00.000Z",
|
||||
"startedAt": "2024-01-15T00:01:00.000Z",
|
||||
"completedAt": "2024-01-15T00:05:00.000Z",
|
||||
"projectId": "clx0987654321",
|
||||
"explorationData": { ... },
|
||||
"explorationSummary": "LangChain 是一个 LLM 应用开发框架...",
|
||||
"errorMessage": null,
|
||||
"retryCount": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.4.4 更新任务状态
|
||||
|
||||
更新探索任务的状态和相关信息。
|
||||
|
||||
```
|
||||
PATCH /api/discovery/tasks/:id
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
|
||||
```typescript
|
||||
{
|
||||
apiKey: string;
|
||||
status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
|
||||
explorationData?: Record<string, unknown>; // 探索结果数据 (JSON)
|
||||
explorationSummary?: string; // 探索摘要，最大 1000 字符
|
||||
errorMessage?: string; // 错误信息，最大 2000 字符
|
||||
}
|
||||
```
|
||||
|
||||
**状态转换规则**:
|
||||
|
||||
| 当前状态 | 允许转换到 |
|
||||
|----------|------------|
|
||||
| PENDING | IN_PROGRESS |
|
||||
| IN_PROGRESS | COMPLETED, FAILED |
|
||||
| COMPLETED | (终态，不可转换) |
|
||||
| FAILED | PENDING (允许重试) |
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"task": {
|
||||
"id": "clx1234567890",
|
||||
"status": "IN_PROGRESS",
|
||||
"startedAt": "2024-01-15T00:01:00.000Z",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.4.5 完成任务并提交项目
|
||||
|
||||
完成探索并提交项目数据（自动创建或更新项目）。
|
||||
|
||||
```
|
||||
POST /api/discovery/tasks/:id/complete
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
|
||||
```typescript
|
||||
{
|
||||
apiKey: string;
|
||||
explorationData: ProjectInput; // 符合 ProjectInputSchema 的项目数据
|
||||
}
|
||||
```
|
||||
|
||||
**功能说明**:
|
||||
- 验证 `explorationData` 格式
|
||||
- 多级去重策略识别已存在项目（GitHub URL → Website URL → slug）
|
||||
- 使用事务确保任务状态更新和项目创建/更新的原子性
|
||||
- 成功时任务状态更新为 COMPLETED，关联 projectId
|
||||
- 失败时任务状态更新为 FAILED，记录错误信息
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"taskId": "clx1234567890",
|
||||
"projectId": "clx0987654321",
|
||||
"action": "created",
|
||||
"duration": 1234
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应** (400 Bad Request):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Invalid exploration data format",
|
||||
"details": [
|
||||
"tags: Field must contain at least 1 element",
|
||||
"links: Field must contain at least 1 element"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.4.6 检查任务去重
|
||||
|
||||
在创建任务前检查 URL 是否应该创建新任务。
|
||||
|
||||
```
|
||||
POST /api/discovery/check-duplicates
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
|
||||
```typescript
|
||||
{
|
||||
apiKey: string;
|
||||
urls: string[]; // 1-100 个 URL
|
||||
sourceType?: string; // 可选来源标识
|
||||
}
|
||||
```
|
||||
|
||||
**去重优先级**:
|
||||
1. PENDING/IN_PROGRESS 任务 → 不创建（任务处理中）
|
||||
2. COMPLETED/FAILED 任务 → 不创建（已探索过）
|
||||
3. 已存在的项目（通过 ExternalLink）→ 不创建（已收录）
|
||||
4. 无任何记录 → 允许创建
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": [
|
||||
{
|
||||
"url": "https://github.com/langchain-ai/langchain",
|
||||
"shouldCreate": false,
|
||||
"reason": "Task already completed",
|
||||
"existingTask": {
|
||||
"id": "clx123",
|
||||
"status": "COMPLETED",
|
||||
"sourceUrl": "https://github.com/langchain-ai/langchain",
|
||||
"createdAt": "2024-01-15T00:00:00.000Z",
|
||||
"projectId": "clx456"
|
||||
},
|
||||
"existingProject": {
|
||||
"id": "clx456",
|
||||
"name": "LangChain",
|
||||
"slug": "langchain"
|
||||
}
|
||||
}
|
||||
],
|
||||
"stats": {
|
||||
"total": 10,
|
||||
"shouldCreate": 5,
|
||||
"duplicate": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.5 去重检查 API
|
||||
|
||||
检查项目是否已存在（用于提交前的预检查）。
|
||||
|
||||
#### 3.5.1 检查项目去重
|
||||
|
||||
根据 URL 或 slug 检查项目是否已存在。
|
||||
|
||||
```
|
||||
POST /api/webhook/check-duplicates
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
|
||||
```typescript
|
||||
{
|
||||
apiKey: string;
|
||||
projects: Array<{
|
||||
githubUrl?: string;
|
||||
huggingfaceUrl?: string;
|
||||
websiteUrl?: string;
|
||||
slug?: string;
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
**匹配优先级**:
|
||||
1. GitHub URL 精确匹配
|
||||
2. Hugging Face URL 精确匹配
|
||||
3. Website URL 精确匹配
|
||||
4. slug 匹配（兜底）
|
||||
|
||||
**响应示例** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": [
|
||||
{
|
||||
"githubUrl": "https://github.com/langchain-ai/langchain",
|
||||
"exists": true,
|
||||
"matchType": "GITHUB_URL",
|
||||
"projectId": "clx456",
|
||||
"projectName": "LangChain"
|
||||
},
|
||||
{
|
||||
"websiteUrl": "https://newproject.com",
|
||||
"exists": false,
|
||||
"matchType": "NONE"
|
||||
}
|
||||
],
|
||||
"stats": {
|
||||
"total": 2,
|
||||
"exists": 1,
|
||||
"new": 1,
|
||||
"breakdown": {
|
||||
"githubUrl": 1,
|
||||
"huggingfaceUrl": 0,
|
||||
"websiteUrl": 0,
|
||||
"slug": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据模型
|
||||
|
||||
### 4.1 Project 状态枚举
|
||||
@@ -417,13 +764,13 @@ enum LinkType {
|
||||
```typescript
|
||||
interface Project {
|
||||
id: string; // 项目唯一 ID（cuid 格式）
|
||||
name: string; // 中文名称
|
||||
name: string; // 中文名称 (1-200 字符)
|
||||
nameEn: string | null; // 英文名称
|
||||
slug: string; // URL 友好标识符（唯一）
|
||||
description: string; // 中文描述
|
||||
description: string; // 中文描述 (10-500 字符)
|
||||
descriptionEn: string | null;// 英文描述
|
||||
content: string | null; // 中文内容（Markdown）
|
||||
contentEn: string | null; // 英文内容（Markdown）
|
||||
content: string | null; // 中文内容（Markdown，最大 10000 字符）
|
||||
contentEn: string | null; // 英文内容（Markdown，最大 10000 字符）
|
||||
status: ProjectStatus; // 项目状态
|
||||
source: string | null; // 数据来源
|
||||
createdAt: Date; // 创建时间
|
||||
@@ -459,6 +806,37 @@ interface ExternalLink {
|
||||
}
|
||||
```
|
||||
|
||||
### 4.6 ProjectDiscoveryTask 模型
|
||||
|
||||
```typescript
|
||||
interface ProjectDiscoveryTask {
|
||||
id: string; // 任务唯一 ID (cuid 格式)
|
||||
sourceUrl: string; // 探索目标 URL
|
||||
sourceType: string; // 来源类型 (如 "manual", "github-trending")
|
||||
status: TaskStatus; // 任务状态
|
||||
createdAt: Date; // 创建时间
|
||||
startedAt: Date | null; // 开始处理时间
|
||||
completedAt: Date | null; // 完成时间
|
||||
projectId: string | null; // 关联的项目 ID (完成后)
|
||||
explorationData: JsonValue | null; // 探索结果数据 (JSON)
|
||||
explorationSummary: string | null; // 探索摘要
|
||||
errorMessage: string | null; // 错误信息
|
||||
retryCount: number; // 重试次数
|
||||
lastRetryAt: Date | null; // 最后重试时间
|
||||
}
|
||||
```
|
||||
|
||||
### 4.7 TaskStatus 状态枚举
|
||||
|
||||
```typescript
|
||||
enum TaskStatus {
|
||||
PENDING = 'PENDING', // 待处理
|
||||
IN_PROGRESS = 'IN_PROGRESS', // 处理中
|
||||
COMPLETED = 'COMPLETED', // 已完成
|
||||
FAILED = 'FAILED' // 失败
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 错误码
|
||||
@@ -489,14 +867,14 @@ interface ExternalLink {
|
||||
```typescript
|
||||
// 必填字段
|
||||
- name: 非空字符串，长度 1-200
|
||||
- description: 非空字符串，长度 1-5000
|
||||
- description: 非空字符串，长度 10-500
|
||||
- tags: 数组，长度 1-10，每个 tag.name 非空
|
||||
- links: 数组，长度 1-10，每个 link.url 和 link.type 非空
|
||||
|
||||
// 可选字段
|
||||
- nameEn: 字符串，长度 1-200
|
||||
- descriptionEn: 字符串，长度 1-5000
|
||||
- content/contentEn: 文本类型，支持 Markdown
|
||||
- descriptionEn: 字符串，长度 10-500
|
||||
- content/contentEn: 文本类型，支持 Markdown，最大 10000 字符
|
||||
- status: 枚举值 "ACTIVE" 或 "ARCHIVED"，默认 "ACTIVE"
|
||||
- source: 字符串，标识数据来源
|
||||
|
||||
@@ -661,9 +1039,11 @@ DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require
|
||||
- [数据库 Schema](../prisma/schema.prisma)
|
||||
- [数据验证规则](../src/lib/validations.ts)
|
||||
- [数据新增流程设计](./data-ingestion-flow.md)
|
||||
- [项目发现系统](../.claude/commands/discover-projects.md)
|
||||
- [Discovery Service](../src/app/api/discovery/lib/discovery-service.ts)
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0.0
|
||||
**最后更新**: 2024-01-11
|
||||
**文档版本**: v2.0.0
|
||||
**最后更新**: 2025-01-20
|
||||
**维护者**: AI 项目导航站团队
|
||||
|
||||
Reference in New Issue
Block a user