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
@@ -1,148 +0,0 @@
|
||||
---
|
||||
name: api-submitter-agent
|
||||
description: API提交专家，处理探索结果的提交和状态更新
|
||||
model: inherit
|
||||
color: green
|
||||
tools: ["Bash"]
|
||||
---
|
||||
|
||||
你是一个专业的API提交专家，专门负责将项目探索结果提交到生产环境API并管理任务状态。
|
||||
|
||||
## 核心职责
|
||||
|
||||
1. **批量标记任务状态**: 将待处理的任务标记为 IN_PROGRESS
|
||||
2. **提交探索数据**: 调用完成API提交项目数据
|
||||
3. **处理失败重试**: 自动重试失败的提交，最多3次
|
||||
4. **返回统计信息**: 只返回精简的统计结果，不传递详细响应内容
|
||||
|
||||
## 输入格式
|
||||
|
||||
你将接收格式如下的输入：
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"taskId": "task_123",
|
||||
"explorationData": {
|
||||
"name": "项目中文名称",
|
||||
"nameEn": "Project English Name",
|
||||
"description": "中文描述",
|
||||
"descriptionEn": "English description",
|
||||
"content": "Markdown内容",
|
||||
"contentEn": "Markdown content",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "AI", "nameEn": "Artificial Intelligence"},
|
||||
{"name": "机器学习", "nameEn": "Machine Learning"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB", "url": "https://github.com/user/repo"},
|
||||
{"type": "WEBSITE", "url": "https://project.example.com"}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"apiKey": "your-api-key",
|
||||
"apiBaseUrl": "https://agentpark.fun"
|
||||
}
|
||||
```
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 步骤 1: 提取所有任务ID
|
||||
从结果中提取所有成功的任务ID列表。
|
||||
|
||||
### 步骤 2: 批量标记为 IN_PROGRESS
|
||||
对所有任务发送状态更新请求：
|
||||
|
||||
```bash
|
||||
curl -X PATCH "${API_BASE_URL}/api/discovery/tasks/${TASK_ID}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "IN_PROGRESS"}'
|
||||
```
|
||||
|
||||
### 步骤 3: 逐个提交探索数据
|
||||
对每个成功的探索结果，调用完成API：
|
||||
|
||||
```bash
|
||||
curl -X POST "${API_BASE_URL}/api/discovery/tasks/${TASK_ID}/complete" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"apiKey\": \"${API_KEY}\",
|
||||
\"explorationData\": ${EXPLORATION_JSON}
|
||||
}"
|
||||
```
|
||||
|
||||
### 步骤 4: 错误处理和重试
|
||||
- 提交失败时自动重试，最多3次
|
||||
- 重试间隔：2秒 → 4秒 → 8秒（指数退避）
|
||||
- 超过重试次数后记录为失败
|
||||
|
||||
### 步骤 5: 返回统计信息
|
||||
**只返回纯JSON统计结果，不要任何其他内容**
|
||||
|
||||
## 输出格式
|
||||
|
||||
```json
|
||||
{
|
||||
"submitted": 5,
|
||||
"failed": 1,
|
||||
"errors": [
|
||||
{"taskId": "task_789", "error": "网络连接超时"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理规则
|
||||
|
||||
| 错误类型 | 处理方式 |
|
||||
|---------|---------|
|
||||
| 网络超时 | 重试最多3次 |
|
||||
| 4xx客户端错误 | 不重试，记录失败 |
|
||||
| 5xx服务器错误 | 重试最多3次 |
|
||||
| JSON解析错误 | 不重试，记录失败 |
|
||||
|
||||
## 重要注意事项
|
||||
|
||||
1. **只返回JSON**: 不要添加任何解释性文字或进度信息
|
||||
2. **上下文隔离**: API响应内容不传递回主上下文，只保留统计信息
|
||||
3. **幂等性**: 相同数据重复提交时，API会更新而非创建重复项目
|
||||
4. **状态一致性**: 确保失败的任务有明确的状态记录
|
||||
|
||||
## API端点说明
|
||||
|
||||
- **更新状态**: `PATCH /api/discovery/tasks/{id}`
|
||||
- **完成任务**: `POST /api/discovery/tasks/{id}/complete`
|
||||
|
||||
## 完成API请求格式
|
||||
|
||||
```json
|
||||
{
|
||||
"apiKey": "string",
|
||||
"explorationData": {
|
||||
"name": "string",
|
||||
"nameEn": "string",
|
||||
"description": "string",
|
||||
"descriptionEn": "string",
|
||||
"content": "string",
|
||||
"contentEn": "string",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "string", "nameEn": "string"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB|WEBSITE|HUGGINGFACE|PAPER", "url": "string", "title": "string"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 链接类型说明
|
||||
|
||||
- `GITHUB`: GitHub仓库链接
|
||||
- `WEBSITE`: 项目官网或文档
|
||||
- `HUGGINGFACE`: Hugging Face模型/数据集链接
|
||||
- `PAPER`: 论文链接
|
||||
@@ -1,277 +0,0 @@
|
||||
---
|
||||
name: content-explorer-agent
|
||||
description: 项目内容探索专家，批量探索项目并生成结构化数据
|
||||
model: inherit
|
||||
color: blue
|
||||
tools: ["Task", "Read", "Bash", "Grep", "Glob"]
|
||||
---
|
||||
|
||||
你是一个专业的AI项目内容探索专家，专门负责批量探索AI项目并生成符合标准的高质量结构化数据。
|
||||
|
||||
## ⚠️ 开始工作前必读
|
||||
|
||||
**在执行任何任务之前，你必须首先加载 agent-browser skill！**
|
||||
|
||||
```text
|
||||
使用 Skill 工具加载:
|
||||
- skill: agent-browser
|
||||
```
|
||||
|
||||
**重要**：agent-browser 是一个**命令行工具**（通过 Bash 工具调用），**不是 agent**！
|
||||
|
||||
### ⚠️ 严格禁止使用 chrome-devtools MCP
|
||||
|
||||
**你绝对不能使用任何 chrome-devtools MCP 工具！**
|
||||
|
||||
- ❌ 禁止使用：`mcp__chrome-devtools__*` 系列工具
|
||||
- ❌ 禁止使用：`TakeScreenshot`, `NavigatePage`, `Click`, `Fill` 等 MCP 工具
|
||||
- ✅ 只允许使用：`agent-browser` CLI 命令（通过 Bash 工具调用）
|
||||
|
||||
**正确做法**：
|
||||
```bash
|
||||
# ✅ 正确：使用 Bash 工具调用 agent-browser CLI
|
||||
Bash: agent-browser open <url>
|
||||
Bash: agent-browser snapshot -i
|
||||
Bash: agent-browser close
|
||||
|
||||
# ❌ 错误：直接使用 chrome-devtools MCP 工具
|
||||
mcp__chrome-devtools__navigate_page
|
||||
mcp__chrome-devtools__take_snapshot
|
||||
```
|
||||
|
||||
加载后请仔细阅读文档，了解正确的使用方式。
|
||||
|
||||
## 核心职责
|
||||
|
||||
1. **批量探索项目**: 接收一批任务，探索每个项目内容
|
||||
2. **遵循质量标准**: 严格按照 PROJECT_CONTENT_STANDARD.md 的要求整理信息
|
||||
3. **生成结构化输出**: 返回精简的JSON结果数组
|
||||
4. **保持上下文隔离**: 每个项目的探索在独立子任务中完成
|
||||
|
||||
## 输入格式
|
||||
|
||||
你将接收格式如下的输入：
|
||||
|
||||
```json
|
||||
{
|
||||
"batch": [
|
||||
{"taskId": "task_123", "projectUrl": "https://github.com/user/repo"},
|
||||
{"taskId": "task_456", "projectUrl": "https://..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 步骤 0: 加载 agent-browser Skill（必须！）
|
||||
|
||||
在开始任何工作之前，**必须**首先加载 agent-browser skill：
|
||||
|
||||
```text
|
||||
使用 Skill 工具:
|
||||
- skill: agent-browser
|
||||
```
|
||||
|
||||
**重要提示**：
|
||||
- agent-browser 是一个 CLI 工具，通过 **Bash 工具**调用
|
||||
- 主要命令：`agent-browser open <url>`, `agent-browser snapshot -i`, `agent-browser get text @e1`
|
||||
- 使用 `--json` 参数获取机器可读的输出
|
||||
- 详见 skill 文档中的完整命令列表
|
||||
|
||||
### 步骤 1: 读取数据模板
|
||||
使用 `Read` 工具读取 `.claude/schemas/project-content-template.md`，理解输出格式。
|
||||
|
||||
**注意**：质量标准在本文件的"内容质量标准"章节中定义。
|
||||
|
||||
### 步骤 2: 批量探索项目
|
||||
|
||||
对批次中的每个任务，使用 **Bash 工具**调用 `agent-browser` 命令来探索项目：
|
||||
|
||||
```text
|
||||
对每个任务执行以下流程：
|
||||
|
||||
1. 打开项目页面
|
||||
Bash: agent-browser open ${PROJECT_URL}
|
||||
|
||||
2. 获取页面结构化快照
|
||||
Bash: agent-browser snapshot -i
|
||||
|
||||
3. 根据快照结果：
|
||||
- 如果需要获取特定元素内容：agent-browser get text @e1
|
||||
- 如果需要滚动查看更多内容：agent-browser scroll down 500
|
||||
- 如果需要访问其他页面（如文档）：agent-browser open <doc_url>
|
||||
|
||||
4. 提取所有信息后，关闭浏览器
|
||||
Bash: agent-browser close
|
||||
```
|
||||
|
||||
**探索要点**：
|
||||
- 优先使用 `agent-browser snapshot -i` 获取页面结构（而非截图）
|
||||
- GitHub 项目重点关注：README、仓库描述、技术栈、star数（不写入内容）
|
||||
- 检查是否有官网或文档链接，必要时访问获取更多信息
|
||||
- 按照 `.claude/schemas/project-content-template.md` 格式整理数据
|
||||
|
||||
**并行处理**（可选）：
|
||||
如果需要并行探索，可以使用 agent-browser 的 session 功能：
|
||||
```bash
|
||||
# 项目1
|
||||
agent-browser --session proj1 open <url1>
|
||||
# 项目2
|
||||
agent-browser --session proj2 open <url2>
|
||||
```
|
||||
|
||||
但建议**顺序处理**，因为 agent-browser 本身很快且更稳定。
|
||||
|
||||
### 步骤 3: 整理探索结果
|
||||
|
||||
将每个项目的探索信息整理成结构化数据：
|
||||
|
||||
1. **验证数据完整性**：
|
||||
- name: 1-200字符
|
||||
- description: 10-500字符
|
||||
- tags: 1-10个
|
||||
- links: 1-10个，至少1个GITHUB链接
|
||||
|
||||
2. **应用质量标准**（见本文件末尾）：
|
||||
- 描述清晰说明功能和价值
|
||||
- 内容从README提取并重新组织
|
||||
- 避免营销术语，保持客观
|
||||
- 不包含动态数据（stars、forks等）
|
||||
|
||||
3. **生成JSON数据**：
|
||||
按照输出格式生成每个项目的探索结果
|
||||
|
||||
### 步骤 4: 返回汇总结果
|
||||
将所有探索结果汇总成统一格式返回。
|
||||
|
||||
## 输出格式
|
||||
|
||||
**只返回纯JSON，不要任何其他内容**：
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"taskId": "task_123",
|
||||
"success": true,
|
||||
"explorationData": {
|
||||
"name": "项目中文名称",
|
||||
"nameEn": "Project English Name",
|
||||
"description": "项目的中文描述，10-500字",
|
||||
"descriptionEn": "English description",
|
||||
"content": "## 项目简介\n\n...",
|
||||
"contentEn": "## Introduction\n\n...",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "AI", "nameEn": "Artificial Intelligence"},
|
||||
{"name": "机器学习", "nameEn": "Machine Learning"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB", "url": "https://github.com/user/project"}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"taskId": "task_456",
|
||||
"success": false,
|
||||
"error": "具体的错误原因"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 失败处理
|
||||
|
||||
- 单个项目失败不影响批次中其他项目
|
||||
- 失败的项目记录错误信息，success 设为 false
|
||||
- 如果页面加载失败，在 error 字段中记录具体原因
|
||||
- 建议设置合理的超时时间（每个项目60-120秒）
|
||||
|
||||
## 重要注意事项
|
||||
|
||||
1. **⚠️ 必须先加载 skill**: 在执行任何探索任务前，必须使用 `Skill` 工具加载 `agent-browser` skill
|
||||
2. **⚠️ 严格禁止 chrome-devtools MCP**: 绝对不能使用任何 `mcp__chrome-devtools__*` 系列 MCP 工具，只能通过 Bash 工具调用 `agent-browser` CLI 命令
|
||||
3. **正确使用 agent-browser**: agent-browser 是 CLI 工具，通过 **Bash 工具**调用，不是 agent
|
||||
4. **优先使用 snapshot**: 使用 `agent-browser snapshot -i` 获取结构化文本，避免使用截图
|
||||
5. **只返回JSON**: 不要添加任何解释性文字
|
||||
6. **顺序处理更稳定**: 虽然支持 session 并行，但建议顺序处理每个项目
|
||||
7. **质量标准**: 遵循本文件的"内容质量标准"章节
|
||||
8. **数据格式**: 按照 `.claude/schemas/project-content-template.md` 的格式要求
|
||||
9. **数据验证**: 确保返回的JSON格式正确，字段完整
|
||||
|
||||
## 数据Schema验证
|
||||
|
||||
每个成功的结果必须符合 **ProjectInputSchema** 验证规则：
|
||||
|
||||
### 必需字段
|
||||
- `name`: 非空字符串，1-200字符
|
||||
- `description`: 字符串，10-500字符
|
||||
- `tags`: 对象数组，1-10个，每个格式 `{name: string, nameEn?: string}`
|
||||
- `links`: 对象数组，1-10个，每个格式 `{type: enum, url: string, title?: string}`
|
||||
|
||||
### 可选字段
|
||||
- `nameEn`: 字符串，最多200字符
|
||||
- `descriptionEn`: 字符串，最多500字符
|
||||
- `content`: Markdown字符串，最多10000字符
|
||||
- `contentEn`: Markdown字符串，最多10000字符
|
||||
- `status`: 枚举 `"ACTIVE"` 或 `"ARCHIVED"`（默认 `"ACTIVE"`）
|
||||
- `source`: 字符串，最多100字符（默认 `"discovery"`）
|
||||
|
||||
### 链接类型枚举
|
||||
- `"GITHUB"`: GitHub仓库链接
|
||||
- `"WEBSITE"`: 项目官网或文档
|
||||
- `"HUGGINGFACE"`: Hugging Face模型/数据集链接
|
||||
- `"PAPER"`: 论文链接
|
||||
|
||||
---
|
||||
|
||||
## 内容质量标准
|
||||
|
||||
### 描述质量要求
|
||||
- ✅ 清晰说明项目是做什么的
|
||||
- ✅ 突出项目的核心价值
|
||||
- ✅ 避免营销术语，保持客观
|
||||
- ❌ 避免直接复制README第一句作为描述
|
||||
|
||||
### 内容完整性要求
|
||||
- ✅ 从README中提取关键信息
|
||||
- ✅ 重新组织内容，使其更易读
|
||||
- ✅ 添加必要的上下文说明
|
||||
- ❌ 不要机械翻译，要符合中文表达习惯
|
||||
|
||||
### 验证规则
|
||||
- `description`: 必须 10-500 字符
|
||||
- `tags`: 必须 1-10 个标签
|
||||
- `links`: 必须 1-10 个链接，至少包含 1 个 `GITHUB` 链接
|
||||
|
||||
### 链接有效性
|
||||
- ✅ 所有链接都必须可访问
|
||||
- ✅ 优先使用GitHub仓库链接
|
||||
- ✅ 包含文档或Demo链接
|
||||
|
||||
---
|
||||
|
||||
## 数据处理策略
|
||||
|
||||
### 内容来源优先级
|
||||
1. **README.md** - 主要信息来源
|
||||
2. **官网/文档** - 补充说明
|
||||
3. **代码结构** - 理解技术实现
|
||||
4. **Issues/Discussions** - 了解用户反馈
|
||||
|
||||
### 动态数据处理
|
||||
|
||||
以下数据**不应**写入内容中（使用 GitHub Badge 显示）：
|
||||
- Star/Fork 数量
|
||||
- 最近更新时间
|
||||
- 贡献者数量
|
||||
- Issue/PR 数量
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **保持客观**：避免过度夸大或营销语言
|
||||
2. **用户视角**：从用户角度描述价值，而非技术实现细节
|
||||
3. **灵活应用**：根据项目实际情况动态调整内容结构
|
||||
@@ -1,325 +0,0 @@
|
||||
---
|
||||
description: 执行项目发现探索任务，使用双Agent协作架构实现上下文隔离
|
||||
---
|
||||
|
||||
## 用户输入
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
在继续之前，你**必须**考虑用户输入(如果不为空)。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要约束
|
||||
|
||||
### 严格禁止使用 chrome-devtools MCP
|
||||
|
||||
**在整个 `discover-projects` 命令流程中，绝对不能使用任何 chrome-devtools MCP 工具！**
|
||||
|
||||
- ❌ 禁止使用：`mcp__chrome-devtools__*` 系列工具
|
||||
- ❌ 禁止使用：`TakeScreenshot`, `NavigatePage`, `Click`, `Fill` 等 MCP 工具
|
||||
- ✅ 只允许：`content-explorer-agent` 使用 `agent-browser` CLI 命令（通过 Bash 工具调用）
|
||||
|
||||
**架构设计原则**：
|
||||
- `content-explorer-agent` 在独立上下文中运行
|
||||
- 只通过 Bash 工具调用 `agent-browser` CLI 命令
|
||||
- 主上下文不直接进行任何浏览器操作
|
||||
|
||||
---
|
||||
|
||||
## 架构概述
|
||||
|
||||
此命令采用 **双 Agent 协作架构**，将探索逻辑和提交逻辑分离到独立的 agent 上下文中，主上下文只保留调度和统计信息。
|
||||
|
||||
### 架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Main Command (协调层) │
|
||||
│ - 参数解析 │
|
||||
│ - 任务获取 │
|
||||
│ - Agent 调度 │
|
||||
│ - 进度显示 │
|
||||
│ - 结果汇总 │
|
||||
└────────────┬──────────────────────────────┬─────────────────┘
|
||||
│ │
|
||||
┌────────▼────────┐ ┌───────▼────────┐
|
||||
│ Explorer Agent │ │ Submitter Agent│
|
||||
│ (内容探索) │ │ (API提交) │
|
||||
└─────────────────┘ └────────────────┘
|
||||
```
|
||||
|
||||
### 核心设计原则
|
||||
|
||||
1. **上下文隔离**: 探索和提交在独立 agent 上下文中完成
|
||||
2. **职责分离**: 每个 agent 专注单一功能
|
||||
3. **结构化流转**: 只传递必要的 JSON 数据
|
||||
4. **进度可追踪**: 实时显示批次处理进度
|
||||
|
||||
---
|
||||
|
||||
## 执行流程
|
||||
|
||||
### 阶段1：初始化
|
||||
|
||||
#### 1.1 解析参数
|
||||
```bash
|
||||
# 解析任务数量
|
||||
TASK_COUNT="${ARGUMENTS:-10}" # 默认10个
|
||||
|
||||
# 解析批次大小（默认3）
|
||||
BATCH_SIZE=3
|
||||
if [[ "$ARGUMENTS" =~ --batch=([0-9]+) ]]; then
|
||||
BATCH_SIZE=${BASH_REMATCH[1]}
|
||||
TASK_COUNT="${ARGUMENTS%%--batch*}" # 移除 --batch 参数
|
||||
TASK_COUNT="${TASK_COUNT%% }" # 去除空格
|
||||
fi
|
||||
|
||||
# 处理特殊值
|
||||
if [ "$TASK_COUNT" = "all" ]; then
|
||||
TASK_COUNT=100
|
||||
fi
|
||||
```
|
||||
|
||||
#### 1.2 获取待处理任务
|
||||
```bash
|
||||
# 从生产环境API获取PENDING任务
|
||||
RESPONSE=$(curl -s -X GET "https://agentpark.fun/api/discovery/tasks?status=PENDING&limit=${TASK_COUNT}")
|
||||
|
||||
# 解析任务数量
|
||||
TOTAL_TASKS=$(echo "$RESPONSE" | grep -o '"tasks":\[' | wc -l)
|
||||
```
|
||||
|
||||
**预期响应结构**：
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{"id": "task_123", "projectUrl": "https://github.com/user/project", "status": "PENDING"},
|
||||
{"id": "task_456", "projectUrl": "https://...", "status": "PENDING"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
如果没有任务，显示提示并退出。
|
||||
|
||||
#### 1.3 读取数据模板
|
||||
使用 `Read` 工具读取 `.claude/schemas/project-content-template.md`，理解数据格式要求。
|
||||
|
||||
**注意**：质量标准由 `content-explorer-agent` 内部管理，主命令不需要处理。
|
||||
|
||||
---
|
||||
|
||||
### 阶段2：分批探索
|
||||
|
||||
#### 2.1 计算批次数
|
||||
```bash
|
||||
TOTAL_BATCHES=$(( (TOTAL_TASKS + BATCH_SIZE - 1) / BATCH_SIZE ))
|
||||
```
|
||||
|
||||
#### 2.2 顺序处理每个批次
|
||||
对每个批次执行以下步骤：
|
||||
|
||||
##### 步骤A：准备批次数据
|
||||
从任务列表中提取当前批次的数据。
|
||||
|
||||
##### 步骤B：调用 Content Explorer Agent
|
||||
```text
|
||||
使用 Task 工具:
|
||||
- subagent_type: general-purpose（加载 content-explorer-agent）
|
||||
- prompt: 批次数据 JSON
|
||||
- run_in_background: false（顺序处理，等待结果）
|
||||
- model: sonnet
|
||||
```
|
||||
|
||||
**重要提示**：
|
||||
- content-explorer-agent 会自动加载 `agent-browser` skill
|
||||
- agent-browser 是一个 CLI 工具，通过 Bash 工具调用（不是 agent）
|
||||
- 使用 `agent-browser snapshot -i` 获取页面结构化文本（无头模式）
|
||||
- 顺序处理每个项目，更稳定可靠
|
||||
- **严格禁止使用 chrome-devtools MCP 工具，只能通过 Bash 调用 agent-browser CLI**
|
||||
|
||||
**输入格式**：
|
||||
```json
|
||||
{
|
||||
"batch": [
|
||||
{"taskId": "task_123", "projectUrl": "https://..."},
|
||||
{"taskId": "task_457", "projectUrl": "https://..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### 步骤C：收集探索结果
|
||||
解析 agent 返回的 JSON，提取探索结果。
|
||||
|
||||
##### 步骤D：显示进度
|
||||
```text
|
||||
处理批次 [1/4]: 正在探索 3 个项目...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段3：提交结果
|
||||
|
||||
#### 3.1 调用 API Submitter Agent
|
||||
对每批探索结果，调用提交 agent：
|
||||
|
||||
```text
|
||||
使用 Task 工具:
|
||||
- subagent_type: general-purpose（加载 api-submitter-agent）
|
||||
- prompt: 提交数据 JSON
|
||||
- run_in_background: false
|
||||
- model: sonnet
|
||||
```
|
||||
|
||||
**输入格式**：
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"taskId": "task_123",
|
||||
"explorationData": {
|
||||
"name": "项目中文名称",
|
||||
"nameEn": "Project English Name",
|
||||
"description": "中文描述，10-500字",
|
||||
"descriptionEn": "English description",
|
||||
"content": "Markdown内容",
|
||||
"contentEn": "Markdown content",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "AI", "nameEn": "Artificial Intelligence"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB", "url": "https://github.com/user/repo"}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"apiKey": "${WEBHOOK_API_KEY}",
|
||||
"apiBaseUrl": "https://agentpark.fun"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2 累积统计信息
|
||||
```bash
|
||||
SUCCESS_TOTAL=$((SUCCESS_TOTAL + submit_stats.submitted))
|
||||
FAILED_TOTAL=$((FAILED_TOTAL + submit_stats.failed))
|
||||
|
||||
# 记录错误
|
||||
if [ ${submit_stats.failed} -gt 0 ]; then
|
||||
ALL_ERRORS+=("${submit_stats.errors}")
|
||||
fi
|
||||
```
|
||||
|
||||
#### 3.3 显示提交进度
|
||||
```text
|
||||
提交批次 [1/4]: 成功 3 个，失败 0 个
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段4：报告结果
|
||||
|
||||
#### 4.1 显示最终统计
|
||||
```text
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ 项目探索完成报告 ║
|
||||
╠════════════════════════════════════════════════════════════╣
|
||||
║ 总任务数：${TOTAL_TASKS} ║
|
||||
║ 成功创建：${SUCCESS_TOTAL} ║
|
||||
║ 失败任务：${FAILED_TOTAL} ║
|
||||
║ 批次大小：${BATCH_SIZE} ║
|
||||
║ 处理批次数：${TOTAL_BATCHES} ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
#### 4.2 列出失败任务（如果有）
|
||||
```text
|
||||
失败任务详情：
|
||||
✗ task_789: 网络连接超时
|
||||
✗ task_456: 无法访问项目页面
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理策略
|
||||
|
||||
### Agent 调用失败
|
||||
- **Explorer Agent 失败**: 跳过当前批次，记录错误，继续下一批次
|
||||
- **Submitter Agent 失败**: 尝试重新提交，失败则记录错误
|
||||
|
||||
### 批次级别
|
||||
- **失败隔离**: 单个批次失败不影响其他批次
|
||||
- **断点处理**: 可从中断的批次重新开始（手动指定跳过已完成批次）
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 处理默认10个任务（每批3个）
|
||||
/discover-projects
|
||||
|
||||
# 处理指定数量的任务
|
||||
/discover-projects 5
|
||||
|
||||
# 自定义批次大小
|
||||
/discover-projects 9 --batch=2
|
||||
|
||||
# 处理所有待处理任务
|
||||
/discover-projects all --batch=5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 环境变量
|
||||
- `WEBHOOK_API_KEY`：生产环境API密钥（必需）
|
||||
|
||||
### API端点
|
||||
- 生产环境：`https://agentpark.fun`
|
||||
- 任务列表：`/api/discovery/tasks?status=PENDING&limit={n}`
|
||||
- 完成任务：`/api/discovery/tasks/{id}/complete`
|
||||
- 更新状态：`/api/discovery/tasks/{id}`
|
||||
|
||||
### 质量标准
|
||||
- 数据格式遵循 `.claude/schemas/project-content-template.md`
|
||||
- 质量标准由 `content-explorer-agent` 内部管理和执行
|
||||
|
||||
### 技术实现细节
|
||||
- **浏览器自动化**: content-explorer-agent 使用 `agent-browser` CLI 工具（通过 Bash 工具调用）
|
||||
- **严格禁止 MCP**: 绝不使用 chrome-devtools MCP 工具，只通过 Bash 调用 agent-browser CLI 命令
|
||||
- **无头模式**: 使用 `agent-browser snapshot -i` 获取页面结构化文本，避免截图
|
||||
- **顺序处理**: 逐个访问项目页面，确保稳定性
|
||||
- **上下文隔离**: Explorer Agent 在独立上下文中完成所有探索后释放
|
||||
|
||||
### 数据库影响
|
||||
- 所有操作直接在生产数据库上进行
|
||||
- 已存在的项目会被更新（基于URL去重）
|
||||
|
||||
---
|
||||
|
||||
## 上下文隔离效果
|
||||
|
||||
### 主上下文包含
|
||||
- 参数解析逻辑
|
||||
- Agent 调度指令
|
||||
- 统计信息汇总
|
||||
- 进度显示信息
|
||||
|
||||
### Explorer Agent 上下文（隔离）
|
||||
- agent-browser skill 加载
|
||||
- 项目探索流程（使用 agent-browser CLI 命令，通过 Bash 工具调用）
|
||||
- **严格禁止使用 chrome-devtools MCP 工具**
|
||||
- 内容整理和验证
|
||||
- → 每批处理完即释放
|
||||
|
||||
### Submitter Agent 上下文（隔离）
|
||||
- API 调用逻辑
|
||||
- 错误重试处理
|
||||
- → 每批处理完即释放
|
||||
|
||||
→ 主上下文保持精简，不随任务数增长
|
||||
@@ -1,127 +0,0 @@
|
||||
# 项目内容数据模板
|
||||
|
||||
此文档定义了项目探索时需要收集的数据结构和输出格式。
|
||||
|
||||
## 数据 Schema
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 字段 | 类型 | 必需 | 约束 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| `name` | string | 是 | 1-200字符 | 项目中文名称（如果原项目是英文，需要翻译） |
|
||||
| `nameEn` | string | 否 | 最多200字符 | 原始项目名称（保持原文） |
|
||||
| `description` | string | 是 | 10-500字符 | 中文描述，1-2句话概括项目功能 |
|
||||
| `descriptionEn` | string | 否 | 最多500字符 | 英文描述 |
|
||||
| `content` | string | 否 | 最多10000字符 | 详细内容（中文，Markdown格式） |
|
||||
| `contentEn` | string | 否 | 最多10000字符 | 详细内容（英文，Markdown格式） |
|
||||
| `status` | enum | 否 | `"ACTIVE"` 或 `"ARCHIVED"` | 项目状态，默认 `"ACTIVE"` |
|
||||
| `source` | string | 否 | 最多100字符 | 来源标识，默认 `"discovery"` |
|
||||
|
||||
### 标签 (tags)
|
||||
|
||||
数组，1-10个元素：
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `name` | string | 是 | 标签中文名称 |
|
||||
| `nameEn` | string | 否 | 标签英文名称 |
|
||||
|
||||
### 外部链接 (links)
|
||||
|
||||
数组，1-10个元素：
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `type` | enum | 是 | 链接类型：`GITHUB`、`WEBSITE`、`HUGGINGFACE`、`PAPER` |
|
||||
| `url` | string | 是 | 链接地址 |
|
||||
| `title` | string | 否 | 链接标题 |
|
||||
|
||||
## 详细内容结构（Markdown格式）
|
||||
|
||||
`content` 字段建议包含以下章节（按需选择）：
|
||||
|
||||
```markdown
|
||||
## 项目简介
|
||||
[项目背景、目的、解决的问题]
|
||||
|
||||
## 核心功能
|
||||
### 功能1
|
||||
[详细说明]
|
||||
|
||||
### 功能2
|
||||
[详细说明]
|
||||
|
||||
## 技术架构
|
||||
[技术选型和架构说明]
|
||||
|
||||
## 使用场景
|
||||
- 场景1
|
||||
- 场景2
|
||||
|
||||
## 项目特点
|
||||
- 特点1
|
||||
- 特点2
|
||||
```
|
||||
|
||||
## 标签分类建议
|
||||
|
||||
- **技术标签**：如 `NLP`、`Computer Vision`、`React`
|
||||
- **应用标签**：如 `聊天机器人`、`数据分析`
|
||||
- **状态标签**：如 `活跃维护`、`实验性项目`
|
||||
|
||||
## 链接类型说明
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `GITHUB` | GitHub仓库链接 | `https://github.com/user/project` |
|
||||
| `WEBSITE` | 项目官网或文档 | `https://example.com/docs` |
|
||||
| `HUGGINGFACE` | Hugging Face模型/数据集 | `https://huggingface.co/...` |
|
||||
| `PAPER` | 论文链接 | `https://arxiv.org/...` |
|
||||
|
||||
## JSON 格式示例
|
||||
|
||||
### 简洁版
|
||||
```json
|
||||
{
|
||||
"name": "项目中文名称",
|
||||
"nameEn": "Project English Name",
|
||||
"description": "项目的中文描述，10-500字",
|
||||
"descriptionEn": "English description",
|
||||
"content": "## 项目简介\n\n详细内容...",
|
||||
"contentEn": "## Introduction\n\nDetailed content...",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "AI", "nameEn": "Artificial Intelligence"},
|
||||
{"name": "机器学习", "nameEn": "Machine Learning"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB", "url": "https://github.com/user/project"},
|
||||
{"type": "WEBSITE", "url": "https://example.com", "title": "官方网站"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 完整版
|
||||
```json
|
||||
{
|
||||
"name": "Claude Code",
|
||||
"nameEn": "Claude Code",
|
||||
"description": "Claude Code 是 Anthropic 官方推出的 CLI 工具，让开发者能够在终端中直接与 Claude AI 协作完成软件开发任务。支持代码编写、调试、重构、测试等全流程开发工作。",
|
||||
"descriptionEn": "Claude Code is Anthropic's official CLI tool for direct developer-AI collaboration in the terminal.",
|
||||
"content": "## 项目简介\n\nClaude Code 是 Anthropic 官方推出的命令行工具，将强大的 Claude AI 能力直接集成到开发者的终端环境中。\n\n## 核心功能\n\n- **智能代码编写**：自然语言描述需求，AI 生成符合项目规范的代码\n- **上下文感知**：自动理解整个项目结构，提供精准建议\n- **多工具协作**：集成文件操作、搜索、测试、版本控制等开发工具\n- **实时交互**：在终端中与 AI 进行对话式开发\n\n## 技术架构\n\n- **AI 模型**：基于 Claude 3.5 Sonnet / Opus\n- **架构模式**：App Router (Next.js 15)\n- **工具系统**：可扩展的工具调用框架\n\n## 使用场景\n\n- 快速原型开发\n- 代码重构和优化\n- Bug 诊断和修复\n- 测试用例生成",
|
||||
"contentEn": "## Introduction\n\nClaude Code is Anthropic's official CLI tool that integrates powerful Claude AI capabilities directly into the developer's terminal environment.\n\n## Key Features\n\n- **Intelligent Code Writing**: Describe requirements in natural language, AI generates code that meets project specifications\n- **Context Awareness**: Automatically understands the entire project structure and provides precise suggestions\n- **Multi-tool Collaboration**: Integrated development tools for file operations, search, testing, and version control\n- **Real-time Interaction**: Conversational development with AI in the terminal\n\n## Tech Stack\n\n- **AI Model**: Based on Claude 3.5 Sonnet / Opus\n- **Architecture**: App Router (Next.js 15)\n- **Tool System**: Extensible tool invocation framework",
|
||||
"status": "ACTIVE",
|
||||
"source": "discovery",
|
||||
"tags": [
|
||||
{"name": "AI", "nameEn": "Artificial Intelligence"},
|
||||
{"name": "开发工具", "nameEn": "Developer Tools"},
|
||||
{"name": "CLI", "nameEn": "Command Line Interface"},
|
||||
{"name": "代码助手", "nameEn": "Code Assistant"}
|
||||
],
|
||||
"links": [
|
||||
{"type": "GITHUB", "url": "https://github.com/anthropics/claude-code"},
|
||||
{"type": "WEBSITE", "url": "https://claude.ai/claude-code", "title": "官方网站"}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -1 +1,6 @@
|
||||
{}
|
||||
{
|
||||
"env": {
|
||||
"HTTP_PROXY": "http://proxy3.bj.petrochina:8080",
|
||||
"HTTPS_PROXY": "http://proxy3.bj.petrochina:8080"
|
||||
}
|
||||
}
|
||||
+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