diff --git a/.claude/agents/api-submitter-agent.md b/.claude/agents/api-submitter-agent.md deleted file mode 100644 index 8e637d3..0000000 --- a/.claude/agents/api-submitter-agent.md +++ /dev/null @@ -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`: 论文链接 diff --git a/.claude/agents/content-explorer-agent.md b/.claude/agents/content-explorer-agent.md deleted file mode 100644 index 22f6774..0000000 --- a/.claude/agents/content-explorer-agent.md +++ /dev/null @@ -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 -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 `, `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 - -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 -# 项目2 -agent-browser --session proj2 open -``` - -但建议**顺序处理**，因为 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. **灵活应用**：根据项目实际情况动态调整内容结构 diff --git a/.claude/commands/discover-projects.md b/.claude/commands/discover-projects.md deleted file mode 100644 index 7d935ab..0000000 --- a/.claude/commands/discover-projects.md +++ /dev/null @@ -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 调用逻辑 -- 错误重试处理 -- → 每批处理完即释放 - -→ 主上下文保持精简，不随任务数增长 diff --git a/.claude/schemas/project-content-template.md b/.claude/schemas/project-content-template.md deleted file mode 100644 index 0d335de..0000000 --- a/.claude/schemas/project-content-template.md +++ /dev/null @@ -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": "官方网站"} - ] -} -``` diff --git a/.claude/settings.json b/.claude/settings.json index 9e26dfe..2565d34 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1 +1,6 @@ -{} \ No newline at end of file +{ + "env": { + "HTTP_PROXY": "http://proxy3.bj.petrochina:8080", + "HTTPS_PROXY": "http://proxy3.bj.petrochina:8080" + } +} \ No newline at end of file diff --git a/docs/api-reference.md b/docs/api-reference.md index a48cf03..88aeb1a 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -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; // 探索结果数据 (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 项目导航站团队