From 18d96911b3865225db64e46562e928f82f83a8a1 Mon Sep 17 00:00:00 2001 From: mzaxd Date: Sun, 18 Jan 2026 17:44:18 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E6=AD=A3=20content-explorer-ag?= =?UTF-8?q?ent=20=E4=B8=AD=20agent-browser=20=E7=9A=84=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修复了将 agent-browser 误认为 agent 的严重架构错误： - 明确 agent-browser 是 CLI 工具，通过 Bash 工具调用（不是 agent） - 修改工作流程：从"并行子任务"改为"顺序使用 Bash 调用" - 添加必须先加载 agent-browser skill 的明确提示 - 更新命令使用说明：snapshot -i、get text 等 - 优化上下文隔离说明，去除错误的"子任务"概念 相关文件： - .claude/agents/content-explorer-agent.md: 重构工作流程 - .claude/commands/discover-projects.md: 更新技术实现细节 --- .claude/agents/content-explorer-agent.md | 146 +++++++++++++---------- .claude/commands/discover-projects.md | 17 ++- 2 files changed, 99 insertions(+), 64 deletions(-) diff --git a/.claude/agents/content-explorer-agent.md b/.claude/agents/content-explorer-agent.md index c01292c..ef22b57 100644 --- a/.claude/agents/content-explorer-agent.md +++ b/.claude/agents/content-explorer-agent.md @@ -8,6 +8,19 @@ tools: ["Task", "Read", "Bash", "Grep", "Glob"] 你是一个专业的AI项目内容探索专家，专门负责批量探索AI项目并生成符合标准的高质量结构化数据。 +## ⚠️ 开始工作前必读 + +**在执行任何任务之前，你必须首先加载 agent-browser skill！** + +```text +使用 Skill 工具加载: +- skill: agent-browser +``` + +**重要**：agent-browser 是一个**命令行工具**（通过 Bash 工具调用），**不是 agent**！ + +加载后请仔细阅读文档，了解正确的使用方式。 + ## 核心职责 1. **批量探索项目**: 接收一批任务，探索每个项目内容 @@ -30,78 +43,84 @@ tools: ["Task", "Read", "Bash", "Grep", "Glob"] ## 工作流程 +### 步骤 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: 批量探索项目 -对批次中的每个任务，**并行**启动 `agent-browser` 子任务： + +对批次中的每个任务，使用 **Bash 工具**调用 `agent-browser` 命令来探索项目： ```text -使用 Task 工具: -- subagent_type: agent-browser -- prompt: " - 你是一个项目探索专家。请探索以下项目并返回结构化数据。 +对每个任务执行以下流程： - 项目URL：\${PROJECT_URL} +1. 打开项目页面 + Bash: agent-browser open ${PROJECT_URL} - 任务要求： - 1. 导航到项目页面，提取 README 内容 - 2. 如果是 GitHub 项目，获取仓库信息（stars、forks、描述等） - 3. 按照 .claude/schemas/project-content-template.md 的格式整理信息 - 4. 应用以下质量标准： - - 描述必须清晰说明项目功能和核心价值 - - 从README提取并重新组织内容，不要机械翻译 - - 避免营销术语，保持客观 - - 不将动态数据（stars、forks等）写入内容 - 5. 生成符合以下 Schema 的 JSON 数据 +2. 获取页面结构化快照 + Bash: agent-browser snapshot -i - **重要：只返回纯JSON，不要任何其他内容** +3. 根据快照结果： + - 如果需要获取特定元素内容：agent-browser get text @e1 + - 如果需要滚动查看更多内容：agent-browser scroll down 500 + - 如果需要访问其他页面（如文档）：agent-browser open - 返回格式： - { - \"taskId\": \"${TASK_ID}\", - \"success\": true, - \"explorationData\": { - \"name\": \"项目中文名称\", - \"nameEn\": \"Project English Name\", - \"description\": \"中文描述（10-500字）\", - \"descriptionEn\": \"English description\", - \"content\": \"详细的Markdown内容（中文）\", - \"contentEn\": \"Detailed Markdown content (English)\", - \"status\": \"ACTIVE\", - \"source\": \"discovery\", - \"tags\": [ - {\"name\": \"AI\", \"nameEn\": \"Artificial Intelligence\"} - ], - \"links\": [ - {\"type\": \"GITHUB\", \"url\": \"https://...\"} - ] - } - } - - 如果探索失败，返回： - { - \"taskId\": \"${TASK_ID}\", - \"success\": false, - \"error\": \"具体错误原因\" - } -" -- run_in_background: true -- model: sonnet +4. 提取所有信息后，关闭浏览器 + Bash: agent-browser close ``` -### 步骤 3: 收集探索结果 -使用 `TaskOutput` 工具等待所有子任务完成： +**探索要点**： +- 优先使用 `agent-browser snapshot -i` 获取页面结构（而非截图） +- GitHub 项目重点关注：README、仓库描述、技术栈、star数（不写入内容） +- 检查是否有官网或文档链接，必要时访问获取更多信息 +- 按照 `.claude/schemas/project-content-template.md` 格式整理数据 -```text -对每个子任务: -- 使用 TaskOutput 工具获取探索结果 -- 解析返回的 JSON 数据 -- 验证数据完整性 +**并行处理**（可选）： +如果需要并行探索，可以使用 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: 返回汇总结果 将所有探索结果汇总成统一格式返回。 @@ -146,16 +165,19 @@ tools: ["Task", "Read", "Bash", "Grep", "Glob"] - 单个项目失败不影响批次中其他项目 - 失败的项目记录错误信息，success 设为 false -- 超时时间：每个子任务 120 秒 +- 如果页面加载失败，在 error 字段中记录具体原因 +- 建议设置合理的超时时间（每个项目60-120秒） ## 重要注意事项 -1. **只返回JSON**: 不要添加任何解释性文字 -2. **上下文隔离**: 每个子任务完成后即释放，结果只保留JSON -3. **并行处理**: 批次内的任务并行启动 -4. **质量标准**: 遵循本文件的"内容质量标准"章节 -5. **数据格式**: 按照 `.claude/schemas/project-content-template.md` 的格式要求 -6. **数据验证**: 确保返回的JSON格式正确，字段完整 +1. **⚠️ 必须先加载 skill**: 在执行任何探索任务前，必须使用 `Skill` 工具加载 `agent-browser` skill +2. **正确使用 agent-browser**: agent-browser 是 CLI 工具，通过 **Bash 工具**调用，不是 agent +3. **优先使用 snapshot**: 使用 `agent-browser snapshot -i` 获取结构化文本，避免使用截图 +4. **只返回JSON**: 不要添加任何解释性文字 +5. **顺序处理更稳定**: 虽然支持 session 并行，但建议顺序处理每个项目 +6. **质量标准**: 遵循本文件的"内容质量标准"章节 +7. **数据格式**: 按照 `.claude/schemas/project-content-template.md` 的格式要求 +8. **数据验证**: 确保返回的JSON格式正确，字段完整 ## 数据Schema验证 diff --git a/.claude/commands/discover-projects.md b/.claude/commands/discover-projects.md index 0d3af8c..b3d71d8 100644 --- a/.claude/commands/discover-projects.md +++ b/.claude/commands/discover-projects.md @@ -116,6 +116,12 @@ TOTAL_BATCHES=$(( (TOTAL_TASKS + BATCH_SIZE - 1) / BATCH_SIZE )) - model: sonnet ``` +**重要提示**： +- content-explorer-agent 会自动加载 `agent-browser` skill +- agent-browser 是一个 CLI 工具，通过 Bash 工具调用（不是 agent） +- 使用 `agent-browser snapshot -i` 获取页面结构化文本（无头模式） +- 顺序处理每个项目，更稳定可靠 + **输入格式**： ```json { @@ -265,6 +271,12 @@ fi - 数据格式遵循 `.claude/schemas/project-content-template.md` - 质量标准由 `content-explorer-agent` 内部管理和执行 +### 技术实现细节 +- **浏览器自动化**: content-explorer-agent 使用 `agent-browser` CLI 工具（通过 Bash 工具调用） +- **无头模式**: 使用 `agent-browser snapshot -i` 获取页面结构化文本，避免截图 +- **顺序处理**: 逐个访问项目页面，确保稳定性 +- **上下文隔离**: Explorer Agent 在独立上下文中完成所有探索后释放 + ### 数据库影响 - 所有操作直接在生产数据库上进行 - 已存在的项目会被更新（基于URL去重） @@ -280,8 +292,9 @@ fi - 进度显示信息 ### Explorer Agent 上下文（隔离） -- 项目探索内容 -- 内容整理逻辑 +- agent-browser skill 加载 +- 项目探索流程（使用 agent-browser CLI 命令） +- 内容整理和验证 - → 每批处理完即释放 ### Submitter Agent 上下文（隔离）