Skill: 16miku/brightdata-research (version 1.0.0)

--- name: brightdata-research description: > Use when the user asks to batch-search candidates, verify public web evidence, dedupe results, and organize them into Feishu/Lark docs. Use especially for requests like "继续搜更多并追加到飞书", "帮我批量找一批候选并整理到飞书", "搜索+抓取+汇总+落文档/落表", "帮我调研一批XX平台", "扩展候选池", even if the user does not explicitly name this skill. Also use when the user says "检查飞书文档里有没有重复" or "去重" in the context of a research document — this skill covers dedup-and-cleanup as a sub-workflow. Do NOT use for: single-page summaries, one-off Q&A, pure code tasks, or tasks that don't involve batch research + structured output. --- # brightdata-research > GitHub: https://github.com/16Miku/brightdata-research-skill > ClawHub: https://clawhub.ai/16miku/brightdata-research 把"批量搜索 + 网页抓取 + 候选验证 + 结构化整理 + 飞书追加写入"做成一个稳定、可复用的研究流水线。 ## 执行模式 本 skill 有两种执行模式。根据环境状态自动选择。 ### Mode A — 直接执行 前提：搜索、抓取、飞书写入能力均已就绪。 行为：跳过环境准备，直接进入 Step 0 开始研究流程。 ### Mode B — 环境准备 + 执行 前提：首次使用，或 preflight 发现缺少关键能力。 行为：先按 `references/environment-checklist.md` 逐项检查并修复，然后进入 Mode A。 环境准备的自动修复顺序见 `references/lark-cli-install-and-auth.md` 和 `references/brightdata-mcp-setup.md`。 ## 核心原则 1. **搜索和抓取可以并行。** 2. **最终去重、风险分层、飞书写入必须由主代理串行完成。** 3. **先汇总，再写入。** 不要边搜索边直接写飞书。 4. **保留 evidence。** 每条候选都应尽量保留公开证据链接。 5. **环境不齐就降级。** 缺搜索、抓取、飞书、subagent 或 git/worktree 条件时，明确说明并切到 fallback。 6. **不要依赖脆弱的 shell 多行拼接。** 写飞书时优先构造稳定的完整 Markdown。 7. **上下文复用。** 如果当前对话已有历史候选池或目标文档信息，直接复用，不要重复询问用户。 ## 标准工作流 ### Step 0. 明确本轮目标 从用户请求或历史上下文提取： - 研究主题 - 目标数量 - 范围 / 国家 / 语言 / 模型范围 - 已有候选池或目标飞书文档 - 是"继续追加"还是"新建文档" - 是否允许使用 subagent **上下文复用规则：** 如果当前对话里已经出现过目标文档 URL/ID、历史候选列表、或研究主题，直接复用这些信息，不要再问用户"请提供文档 ID"。 ### Step 1. Preflight 环境检查 按 `references/environment-checklist.md` 检查： | 能力 | 检查方式 | 缺失时行为 | |------|----------|------------| | 搜索 | 检查 BrightData MCP 工具或 CLI 是否可用 | 不能扩充候选池，只能验证用户给定名单 | | 抓取 | 检查 BrightData scrape 工具或 CLI 是否可用 | 只输出低置信度线索 | | 飞书写入 | 检查 lark-cli / lark-doc skill 是否可用 | 先输出 Markdown，告知用户未写入飞书 | | 目标文档 | 检查上下文是否有 doc_id / URL | 询问用户：新建还是追加 | | 历史去重 | 尝试读取已有文档内容 | 只做本轮内部去重，声明无法保证历史去重 | | subagent | 检查 git 仓库和 HEAD 是否可解析 | 改为主代理串行执行 | 如果缺失项可自动修复（如 lark-cli 未安装），按 Mode B 修复后继续。 如果缺失项无法自动修复（如用户未提供 API token），明确告知用户并降级。 ### Step 2. 制定搜索批次 把任务拆成多个独立批次： - 不同 query 变体 - 不同语言关键词 - 不同来源入口（官网、文档、pricing、help、faq、terms、privacy） - 不同平台类别关键词（gateway、aggregator、relay、OpenAI-compatible API 等） ### Step 3. 并行搜索与初筛 优先使用 BrightData 搜索和抓取工具： - 搜索候选平台 - 获取官网、文档页、定价页、条款页等公开入口 - 记录标题、URL、摘要、来源 query 初筛时保留高相关候选，剔除明显无关页、镜像页、纯广告页。 ### Step 4. 去重 去重分两阶段： **阶段 A — 本轮内部去重：** 1. 域名规范化：去掉 www/http(s)/尾部斜杠，统一小写 2. 品牌别名识别：同一平台可能有多个域名或品牌名（如 openrouter.ai 和 OpenRouter），应识别为同一候选 3. 保留证据更完整、官网性更强的一条 **阶段 B — 历史去重（如果能读取历史文档）：** 1. 读取已有飞书文档内容 2. 提取历史候选名单（名称 + 域名） 3. 与本轮候选交叉比对 4. 已在历史文档中出现的，不重复写入，但在去重说明中列出 如果无法读取历史文档，只做阶段 A，并明确声明。 ### Step 5. 结构化字段提取 默认推荐字段： - 名称 - 官网 - 文档/API 页 - 定价页或价格线索 - 支持模型证据 - OpenAI-compatible / 统一 API 兼容证据 - 初步风险等级 - 备注 如果用户有自定义字段，优先满足用户字段 schema。 ### Step 6. 风险分层 使用 checklist 式评分： | 维度 | 有=1分 | 无=0分 | |------|--------|--------| | 可访问的官网 | 1 | 0 | | 公开 API 文档 | 1 | 0 | | 定价页或明确价格信息 | 1 | 0 | | Terms of Service / Privacy Policy | 1 | 0 | | 可查证的公司/团队主体 | 1 | 0 | | OpenAI-compatible 或统一 API 兼容证据 | 1 | 0 | 分层规则： - **A / 较低风险**（5-6 分）：公开资料完整，文档与能力证据充足 - **B / 中风险**（3-4 分）：有一定公开证据，但部分维度需补验 - **C / 高风险 / 待验证**（0-2 分）：主要依赖搜索摘要，暂不适合高置信纳入 每条候选附一句风险原因。 ### Step 7. 主代理统一收口 主代理负责： - 汇总所有候选 - 最终去重 - 字段格式统一 - 风险口径统一 - 决定哪些算"新增不重复候选" - 生成最终写入飞书的 Markdown ### Step 8. 串行写入飞书 如果用户要求写入飞书文档： 1. 先遵守 `lark-shared` 与 `lark-doc` 的认证和安全规则 2. 复用现有文档 ID；若无则按用户意图新建或先确认 3. 默认使用 `--as user` 访问用户自己的文档 4. 以统一模板生成一轮完整 Markdown 5. 由主代理一次性或顺序串行追加写入 不要让 subagent 直接写同一个飞书文档。 ## 输出格式 默认按下面结构向用户汇报，并尽量按同结构写入飞书文档： ```md ## 第X轮新增候选（来源说明） ### 1. 平台名称 - 官网： - 文档： - 定价： - 支持模型证据： - OpenAI 兼容证据： - 初步风险：A/B/C（得分 X/6，原因：...） - 备注： ## 本轮待进一步验证候选 ... ## 本轮去重说明 - 本轮内部去重：哪些被合并 - 历史去重：哪些平台已在历史轮次出现，因此不重复写入 ## 本轮阶段性结论 - 本轮新增较高可信候选： - 本轮新增待验证候选： - 下一步建议： ``` 如果用户没有要求写飞书，也建议先按这个模板输出到对话中。 ## 何时调用 subagent 适合调用 subagent 的场景： - 需要扩展多组搜索 query - 需要并行搜索多个类别或多个国家 / 语言 - 需要对多个候选分别做公开网页核验 - 需要快速拉回 5-10 个新候选并形成候选池 ### subagent 可负责 - 搜索 query 扩展 - 搜索结果拉取 - 单个平台公开信息初步核验 - 初步结构化字段整理 ### subagent 不应负责 - 最终历史去重判定 - 最终风险分层定稿 - 飞书文档写入 - 最终面向用户的主结论 如果环境不满足 subagent/worktree 前置条件，改为主代理串行执行。详见 `references/subagent-git-prerequisites.md`。 ## 子工作流：文档去重清理 当用户要求"检查飞书文档有没有重复"或"去重"时，执行以下子流程： 1. 读取目标飞书文档全文 2. 提取所有候选平台的名称和域名 3. 域名规范化 + 品牌别名识别 4. 找出完全重复条目（同一平台在不同轮次被当作新候选重复写入） 5. 区分"重复"与"补充验证"（后续轮次对已有平台补充新证据，不算重复） 6. 向用户报告发现的重复项，由用户确认后删除 ## 边界与禁忌 - 不要把搜索结果摘要当成已核验事实；能补官网或文档页就尽量补。 - 不要把营销话术直接当能力证明；优先找 docs、pricing、terms、privacy、company 等公开页。 - 不要为了追求数量忽略去重；"新增不重复候选"比"看起来很多"更重要。 - 不要在写飞书前跳过统一整理步骤。 - 不要多个 agent 并发写同一文档。 - 不要输出无法回溯来源的结论。 - 不要假装环境齐全；缺前置条件时应明确说明并降级。 ## 成功标准 以下条件大致满足时，可认为本轮执行成功： - 成功找到了本轮新增、不重复的候选 - 候选至少具备核心结构化字段 - 已明确区分"较高可信"与"待进一步验证" - 风险评级基于 checklist 打分，而非纯主观判断 - 最终写入飞书时格式稳定、换行正常、无明显重复 - 在新环境里也能先做 preflight，再决定完整执行还是降级执行 ## 参考文档索引 | 文档 | 用途 | |------|------| | `references/environment-checklist.md` | Preflight 检查清单，区分可自动修复和需用户介入的项 | | `references/brightdata-mcp-setup.md` | BrightData MCP 和 CLI 的安装、认证与验证 | | `references/lark-cli-install-and-auth.md` | lark-cli 安装、配置、认证的完整步骤 | | `references/feishu-setup.md` | 飞书文档写入规则和身份选择 | | `references/known-failures-and-fallbacks.md` | 常见失败场景和降级策略 | | `references/subagent-git-prerequisites.md` | subagent/worktree 的前置条件和降级规则 | | `references/smoke-tests.md` | 每项能力的最小验证命令 |

path: evals/evals.json
content: {
  "skill_name": "brightdata-research",
  "evals": [
    {
      "id": 0,
      "prompt": "帮我继续找新的大模型 API 中转站，重点支持 Claude、GPT、Gemini。用搜索和网页抓取补官网、文档、定价页，去重后按高可信和待验证分组，再追加到我现有的飞书文档里。",
      "expected_output": "识别这是批量研究+飞书追加场景；先做 preflight 检查环境能力，再搜索与抓取，去重（含历史去重）、结构化输出、风险分层，并明确只由主代理统一写飞书。",
      "files": [],
      "assertions": [
        {
          "text": "执行 preflight 环境检查，确认搜索、抓取、飞书写入能力",
          "type": "text_contains"
        },
        {
          "text": "明确提到先读取或对照现有飞书文档/历史候选进行历史去重",
          "type": "text_contains"
        },
        {
          "text": "明确区分高可信与待验证两组输出",
          "type": "text_contains"
        },
        {
          "text": "明确说明最终飞书写入由主代理串行完成",
          "type": "text_contains"
        },
        {
          "text": "明确要求保留官网、docs、pricing 或兼容性 evidence",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 1,
      "prompt": "做一轮 API 聚合平台 research。允许你用 subagent 并行搜，但最终要由你统一去重、定风险、整理结构化 Markdown，并串行写入飞书文档，不要重复写已经记录过的平台。",
      "expected_output": "识别 subagent 可用于搜索和初筛，但最终去重、定风险和飞书写入必须串行收口；避免重复写入历史已有平台。",
      "files": [],
      "assertions": [
        {
          "text": "明确把搜索/抓取/初筛列为可并行阶段",
          "type": "text_contains"
        },
        {
          "text": "明确把最终去重、风险分层、Markdown 定稿、飞书写入列为必须串行阶段",
          "type": "text_contains"
        },
        {
          "text": "明确要求不重复写已经记录过的平台",
          "type": "text_contains"
        },
        {
          "text": "明确由主代理统一收口，而不是让 subagent 各自落飞书",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "继续扩展我们的候选池：找 5 到 8 个新的 OpenAI-compatible LLM gateway 或 relay 平台，优先给出官网、docs、pricing、兼容性证据和风险等级。整理完先给我结论，再追加进飞书。",
      "expected_output": "先完成候选检索、证据提取、风险分层和结果汇报，再在确认新增不重复后追加进飞书。",
      "files": [],
      "assertions": [
        {
          "text": "明确遵守先给结论、后追加飞书的顺序",
          "type": "text_contains"
        },
        {
          "text": "明确本轮只追加新的、不重复的候选",
          "type": "text_contains"
        },
        {
          "text": "输出结构包含官网、docs、pricing、兼容性证据和风险等级这些结构化字段",
          "type": "text_contains"
        },
        {
          "text": "不会边搜索边直接写飞书，而是先汇总后写入",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 3,
      "prompt": "我第一次使用这个环境，没有安装过 lark-cli，也没有配置 BrightData。帮我批量搜一些 AI API 聚合平台并整理到飞书。",
      "expected_output": "识别为新环境首次使用（Mode B），先做 preflight 检查，发现 lark-cli 未安装和 BrightData 未配置，按顺序指导安装和配置，可自动修复的项自动修复，需用户介入的项明确提示。",
      "files": [],
      "assertions": [
        {
          "text": "检测到 lark-cli 未安装，尝试自动安装或提供安装命令",
          "type": "text_contains"
        },
        {
          "text": "检测到 BrightData MCP 未配置，提供配置命令并提示用户提供 API token",
          "type": "text_contains"
        },
        {
          "text": "明确区分可自动修复项和需要用户手动操作的项",
          "type": "text_contains"
        },
        {
          "text": "不假装环境已就绪，而是明确告知当前状态和所需步骤",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 4,
      "prompt": "帮我搜一些新的大模型中转站，但我目前没有飞书写入权限。",
      "expected_output": "识别飞书写入不可用的降级场景。正常执行搜索和抓取，完成结构化整理后以 Markdown 输出到对话中，明确说明未写入飞书，告知用户完成飞书授权后可继续写入。",
      "files": [],
      "assertions": [
        {
          "text": "正常执行搜索和抓取，不因飞书不可写就放弃所有步骤",
          "type": "text_contains"
        },
        {
          "text": "输出完整结构化 Markdown 到对话中",
          "type": "text_contains"
        },
        {
          "text": "明确说明未写入飞书",
          "type": "text_contains"
        },
        {
          "text": "告知用户如何修复飞书权限以便后续写入",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 5,
      "prompt": "检查一下我的飞书文档里有没有重复的中转站，有的话告诉我。文档地址：https://my.feishu.cn/docx/ScIldFXJHoeSSyxveS9cObInnFw",
      "expected_output": "识别为去重清理子工作流。读取飞书文档全文，提取所有候选名称和域名，做域名规范化和品牌别名识别，区分真正重复和补充验证，向用户报告发现。",
      "files": [],
      "assertions": [
        {
          "text": "读取目标飞书文档内容",
          "type": "text_contains"
        },
        {
          "text": "提取候选平台名称和域名进行比对",
          "type": "text_contains"
        },
        {
          "text": "区分完全重复与补充验证条目",
          "type": "text_contains"
        },
        {
          "text": "向用户报告发现的重复项，不直接删除",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 6,
      "prompt": "帮我找一些 OpenAI-compatible 的 API 中转站。我之前的飞书文档里已经记录了 OpenRouter、APIYI、one-api 这些，不要重复。",
      "expected_output": "识别用户已提供历史候选名单作为去重基线。搜索新候选时，将 OpenRouter、APIYI、one-api 排除在新增候选之外，同时做域名和品牌别名去重。",
      "files": [],
      "assertions": [
        {
          "text": "将用户提供的 OpenRouter、APIYI、one-api 作为历史去重基线",
          "type": "text_contains"
        },
        {
          "text": "域名规范化去重，识别可能的别名或多域名情况",
          "type": "text_contains"
        },
        {
          "text": "在去重说明中列出哪些候选因与历史重复而被排除",
          "type": "text_contains"
        },
        {
          "text": "使用 checklist 式风险评分而非纯主观判断",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 7,
      "prompt": "我上次对话让你搜了一批中转站，文档地址是 https://my.feishu.cn/docx/ScIldFXJHoeSSyxveS9cObInnFw，继续追加新的一轮。",
      "expected_output": "识别为续写场景，复用上下文中的文档地址，不重复询问。先读取已有文档内容进行历史去重，再执行新一轮搜索。",
      "files": [],
      "assertions": [
        {
          "text": "直接复用用户提供的文档 URL，不重复询问目标文档",
          "type": "text_contains"
        },
        {
          "text": "先读取已有文档做历史去重",
          "type": "text_contains"
        },
        {
          "text": "执行新一轮搜索扩充候选池",
          "type": "text_contains"
        },
        {
          "text": "新增候选以追加模式写入，不覆盖已有内容",
          "type": "text_contains"
        }
      ]
    },
    {
      "id": 8,
      "prompt": "帮我搜几个便宜的 Claude API 代理。",
      "expected_output": "虽然用户措辞简短，仍应识别为 brightdata-research 适用场景。执行标准流程但规模较小，聚焦 Claude API 支持和价格证据。",
      "files": [],
      "assertions": [
        {
          "text": "识别为批量搜索候选场景，触发本 skill 流程",
          "type": "text_contains"
        },
        {
          "text": "聚焦 Claude API 支持证据和价格/定价信息",
          "type": "text_contains"
        },
        {
          "text": "输出包含结构化字段的候选列表",
          "type": "text_contains"
        },
        {
          "text": "包含风险分层评估",
          "type": "text_contains"
        }
      ]
    }
  ]
}


path: README.md
content: # brightdata-research

基于 BrightData + 飞书 lark-cli 的批量调研 skill，为 Claude Code 提供"搜索 → 抓取 → 验证 → 去重 → 风险分层 → 飞书写入"一站式研究流水线。

## 链接

- GitHub：https://github.com/16Miku/brightdata-research-skill
- ClawHub：https://clawhub.ai/16miku/brightdata-research

## 功能概览

- **批量搜索**：通过 BrightData MCP 或 CLI 并行搜索多组关键词，发现候选平台
- **网页抓取**：自动抓取官网、文档、定价、条款等公开页面，提取结构化字段
- **智能去重**：域名规范化 + 品牌别名识别 + 历史文档交叉比对，避免重复写入
- **风险分层**：6 维度 checklist 打分（A/B/C 三级），替代纯主观判断
- **飞书写入**：通过 lark-cli 串行追加到飞书文档，格式稳定
- **环境自适应**：自动检测环境能力，缺失项可自动修复或明确降级

## 快速安装

### 1. 安装 skill

```bash
npx skills add https://github.com/16Miku/brightdata-research-skill -y -g
```

### 2. 配置 BrightData（搜索和抓取能力）

**方式一：MCP 服务器（推荐）**
```bash
claude mcp add --transport sse brightdata "https://mcp.brightdata.com/sse?[REDACTED_SECRET]"
```

**方式二：BrightData CLI**
```bash
npm install -g @brightdata/cli
brightdata login
```

### 3. 配置 lark-cli（飞书写入能力）

```bash
npm install -g @larksuite/cli
npx skills add https://github.com/larksuite/cli -y -g
lark-cli config init
lark-cli auth login --recommend
```

### 4. 验证

```bash
claude mcp list                    # 检查 BrightData MCP
lark-cli auth status               # 检查飞书认证
```

## 使用方式

安装完成后，在 Claude Code 中直接用自然语言触发：

```
帮我批量找一批大模型 API 中转站，搜索+抓取+整理后追加到飞书文档
```

```
继续扩展候选池，找 5-8 个新的 OpenAI-compatible API gateway
```

```
检查飞书文档里有没有重复的中转站
```

Skill 会自动识别意图并执行完整流程。

## 执行模式

| 模式 | 条件 | 行为 |
|------|------|------|
| **Mode A** | 搜索、抓取、飞书写入均就绪 | 直接执行研究流程 |
| **Mode B** | 首次使用或缺少关键能力 | 先检查环境并自动修复，再执行 |
| **降级模式** | 缺少无法自动修复的能力 | 执行可用步骤，明确告知缺失项 |

## 标准工作流

```
Step 0. 明确目标 → Step 1. Preflight 检查 → Step 2. 制定搜索批次
    → Step 3. 并行搜索 → Step 4. 去重 → Step 5. 结构化提取
    → Step 6. 风险分层 → Step 7. 主代理收口 → Step 8. 写入飞书
```

## 风险评分体系

| 维度 | 有=1分 | 无=0分 |
|------|--------|--------|
| 可访问的官网 | 1 | 0 |
| 公开 API 文档 | 1 | 0 |
| 定价页或价格信息 | 1 | 0 |
| Terms / Privacy | 1 | 0 |
| 可查证的公司主体 | 1 | 0 |
| OpenAI-compatible 兼容证据 | 1 | 0 |

- **A 级**（5-6 分）：较低风险，资料完整
- **B 级**（3-4 分）：中风险，部分需补验
- **C 级**（0-2 分）：高风险，证据不足

## 项目结构

```
brightdata-research/
├── SKILL.md                                    # 主 skill 文件（agent 读取）
├── README.md                                   # 项目说明（人类阅读）
├── evals/
│   └── evals.json                              # 9 个场景评测用例
└── references/
    ├── brightdata-mcp-setup.md                 # BrightData MCP + CLI 配置
    ├── lark-cli-install-and-auth.md            # lark-cli 安装与认证
    ├── environment-checklist.md                # 环境 Preflight 检查清单
    ├── feishu-setup.md                         # 飞书写入规则
    ├── known-failures-and-fallbacks.md         # 失败场景与降级策略
    ├── subagent-git-prerequisites.md           # subagent 前置条件
    └── smoke-tests.md                          # 能力验证命令
```

## 前置依赖

| 组件 | 必需 | 用途 |
|------|------|------|
| Claude Code | 是 | 执行环境 |
| BrightData 账户 + API Key | 是 | 搜索和网页抓取 |
| lark-cli | 是（写飞书时） | 飞书文档读写 |
| Node.js / npm | 是 | 安装 CLI 工具 |
| git | 否 | subagent worktree 隔离（可选） |

## 评测

包含 9 个场景评测用例，覆盖：

| ID | 场景 |
|----|------|
| 0 | 标准批量搜索 + 飞书追加 |
| 1 | subagent 并行搜索 + 串行收口 |
| 2 | 指定数量候选 + 先结论后写入 |
| 3 | 新环境首次使用（Mode B） |
| 4 | 飞书不可写的降级场景 |
| 5 | 文档去重清理 |
| 6 | 用户提供历史名单去重 |
| 7 | 上下文复用续写 |
| 8 | 简短请求触发识别 |

## 许可证

MIT


path: references/brightdata-mcp-setup.md
content: # BrightData 搜索与抓取能力配置

本文档说明如何为当前环境配置 BrightData 的搜索和网页抓取能力。有两种方式可用：MCP 服务器集成（推荐用于 Claude Code）和独立 CLI 工具。

## 方式一：MCP 服务器集成（推荐）

将 BrightData 作为 MCP 服务器接入 Claude Code，使 agent 可直接调用搜索和抓取工具。

### 前置条件

1. 已安装并配置 Claude Code
2. 拥有 BrightData 账户（新用户可获得免费测试额度）
3. 从 BrightData 用户设置页面获取 API 密钥

### 安装步骤

**1. 添加 MCP 服务器**

```bash
claude mcp add --transport sse brightdata "https://mcp.brightdata.com/sse?[REDACTED_SECRET]"
```

将 `<your-api-token>` 替换为实际 API 令牌。

**2. 验证连接**

```bash
claude mcp list
```

预期输出：
```
brightdata: https://mcp.brightdata.com/sse?[REDACTED_SECRET]) - ✓ Connected
```

### MCP 提供的工具

| 工具类别 | 用途 | 示例工具名 |
|----------|------|-----------|
| 搜索引擎 | 发现候选平台 | `search_engine`, `search_engine_batch`, `discover` |
| 网页抓取 | 抓取官网、docs、pricing 等页面正文 | `scrape_as_markdown`, `scrape_batch` |
| 结构化数据 | 快速读取 GitHub 等平台结构化数据 | `web_data_github_repository_file` |
| 远程浏览器 | 导航、点击、截图、读取需 JS 渲染的页面 | `scraping_browser_navigate`, `scraping_browser_snapshot` |

### 检测 MCP 是否可用

在 skill 的 preflight 阶段：
- 检查当前环境是否有以 `mcp__brightdata__` 为前缀的工具可用
- 如果有 `search_engine` 工具 → 搜索能力可用
- 如果有 `scrape_as_markdown` 工具 → 抓取能力可用

## 方式二：BrightData CLI（独立命令行工具）

BrightData 也提供独立的 CLI 工具，可在终端中直接使用搜索、抓取、结构化数据提取等功能。适用于不依赖 MCP 的场景，或作为 MCP 的补充。

### 安装

```bash
npm install -g @brightdata/cli
```

验证安装：
```bash
brightdata --version
```

安装后也可使用简写别名 `bdata`。

### 认证

**方式 A：浏览器 OAuth（推荐）**
```bash
brightdata login
```
自动打开浏览器完成认证。登录一次后所有后续命令自动认证。

**方式 B：无浏览器环境（SSH/服务器）**
```bash
brightdata login --device
```
打印一个 URL 和验证码，在任意设备上打开 URL 输入验证码即可。

**方式 C：直接 API Key（CI/CD 场景）**
```bash
brightdata login --api-key YOUR_API_KEY
```

**方式 D：环境变量**
```bash
export BRIGHTDATA_API_KEY=YOUR_API_KEY
```

### 验证配置

```bash
brightdata config   # 查看配置
brightdata budget   # 查看额度
brightdata scrape https://example.com   # 测试抓取
```

### 常用命令

| 命令 | 用途 | 示例 |
|------|------|------|
| `brightdata scrape <url>` | 抓取网页为 Markdown | `brightdata scrape https://example.com` |
| `brightdata search "<query>"` | 搜索引擎查询 | `brightdata search "OpenAI compatible API gateway"` |
| `brightdata discover "<query>"` | AI 驱动的意图搜索 | `brightdata discover "AI API relay" --intent "找中转平台"` |
| `brightdata pipelines <type> <url>` | 结构化数据提取 | `brightdata pipelines github_repo "<url>"` |
| `brightdata browser open <url>` | 远程浏览器控制 | `brightdata browser open https://example.com` |
| `brightdata add mcp` | 将 BrightData MCP 添加到 coding agent | `brightdata add mcp` |

### 交互式初始化向导

首次使用也可运行引导式设置：
```bash
brightdata init
```

### 配置文件位置

| 系统 | 路径 |
|------|------|
| macOS | `~/Library/Application Support/brightdata-cli/` |
| Linux | `~/.config/brightdata-cli/` |
| Windows | `%APPDATA%\brightdata-cli\` |

## MCP vs CLI 选择建议

| 场景 | 推荐方式 |
|------|----------|
| Claude Code 中使用本 skill | MCP（agent 可直接调用工具） |
| 终端中手动搜索/抓取 | CLI |
| CI/CD 自动化流水线 | CLI |
| 两者都已安装 | 优先用 MCP（agent 调用更直接），CLI 作补充 |

## 自动修复

如果 BrightData 能力未配置：

**MCP 未配置时：**
1. 告知用户需要配置 BrightData MCP
2. 提供安装命令：`claude mcp add --transport sse brightdata "https://mcp.brightdata.com/sse?[REDACTED_SECRET]"`
3. 提醒用户需要自行替换 API token
4. 安装完成后需要重启 Claude Code 会话才能生效

**CLI 未安装时：**
1. 可自动尝试安装：`npm install -g @brightdata/cli`
2. 安装后提示用户运行 `brightdata login` 完成认证

**注意：** API token / 账户认证属于用户私密操作，skill 不应尝试自动获取或存储。必须由用户手动完成。

## 完整文档索引

BrightData 完整文档索引：`https://docs.brightdata.com/llms.txt`
可用于查找所有可用功能页面。


path: references/environment-checklist.md
content: # Environment Checklist

在执行 `brightdata-research` 之前，先做这份环境自检。每项分为三类：可自动修复、需用户介入、不可修复（需降级）。

## 一、必需能力

### 1. 搜索能力

**检测：**
- MCP 方式：检查 `mcp__brightdata__search_engine` 工具是否可用
- CLI 方式：`which brightdata 2>/dev/null && brightdata --version`

**可自动修复：**
- BrightData CLI 未安装 → 可自动执行 `npm install -g @brightdata/cli`

**需用户介入：**
- MCP 方式：需要用户配置 MCP 服务器并提供 API token
- CLI 方式：需要用户运行 `brightdata login` 完成认证

**修复指引：** 见 `references/brightdata-mcp-setup.md`

MCP 和 CLI 任一可用即满足搜索能力要求。

缺失时降级：
- 不能执行"扩充候选池"模式
- 只能对用户给定名单做验证与整理

### 2. 网页抓取能力

**检测：**
- MCP 方式：检查 `mcp__brightdata__scrape_as_markdown` 工具是否可用
- CLI 方式：`brightdata scrape https://example.com`

**可自动修复：** 同搜索能力
**需用户介入：** 同搜索能力（MCP 和 CLI 共用 BrightData 账户/认证）
**修复指引：** 见 `references/brightdata-mcp-setup.md`

缺失时降级：
- 不要把搜索摘要直接当事实
- 只能给出低置信度线索，并明确说明证据不足

### 3. 飞书写入能力

**检测：**
```bash
which lark-cli 2>/dev/null && lark-cli auth status
```

**可自动修复：**
- lark-cli 未安装 → 可自动执行 `npm install -g @larksuite/cli`
- lark-cli skills 未安装 → 可自动执行 `npx skills add https://github.com/larksuite/cli -y -g`

**需用户介入：**
- 首次配置需要扫码 → `lark-cli config init`
- 首次登录需要浏览器确认 → `lark-cli auth login --recommend`
- 权限不足需要用户在飞书后台授权

**修复指引：** 见 `references/lark-cli-install-and-auth.md`

缺失时降级：
- 先输出结构化 Markdown
- 不要假装已写入飞书

### 4. 本地文件与命令执行能力

为了读写 skill、保存评测结果、执行 lark-cli 等命令，需要基础文件系统与命令执行能力。

## 二、推荐能力

### 1. subagent / Agent 能力

**检测：**
```bash
git rev-parse --is-inside-work-tree 2>/dev/null && git rev-parse HEAD 2>/dev/null
```

**可自动修复：**
- 不在 git 仓库 → 可自动 `git init`
- 没有 commit → 可自动 `git add -A && git commit -m "init"`

**需用户介入：** 无（如果允许自动初始化 git）

缺失时降级：
- 改为主代理串行执行
- 保留同样的去重与汇总纪律

## 三、执行前必查项

每次开始前按以下清单检查：

1. [ ] 搜索能力是否可用
2. [ ] 网页抓取能力是否可用
3. [ ] lark-cli 是否已安装
4. [ ] lark-cli 是否已认证
5. [ ] 若要写飞书，是否已知道目标 doc_id 或目标文档 URL
6. [ ] 若要历史去重，是否能读取已有飞书文档内容
7. [ ] 若要用 subagent/worktree，git 仓库和 HEAD 是否正常
8. [ ] 当前任务是"继续追加"还是"新建文档"

## 四、快速判断

### 可以完整执行标准流程
满足：
- 搜索 + 抓取 + 飞书写入都可用
- 已知目标文档或能创建目标文档
- 需要时可读取历史文档做去重
→ 进入 **Mode A**

### 需要先修复再执行
任一情况成立：
- lark-cli 未安装（可自动修复）
- git 仓库不存在（可自动修复）
→ 进入 **Mode B**，修复后转 Mode A

### 只能执行降级流程
任一情况成立：
- BrightData MCP 未配置（需用户 API token）
- lark-cli 已安装但用户未完成扫码授权
- 没有历史文档内容且任务要求历史去重
→ 明确告知用户哪一步能做、哪一步做不了


path: references/feishu-setup.md
content: # Feishu Setup and Write Rules

本文档覆盖飞书文档写入时的规则和注意事项。安装和认证步骤见 `lark-cli-install-and-auth.md`。

## 一、写飞书前先遵守共享规则

优先读取并遵守：
- `lark-shared`
- `lark-doc`

核心原因：
- `--as user` 和 `--as bot` 行为差异很大
- 用户资源通常需要 `--as user`
- 写入操作前必须确认用户意图

## 二、默认身份

| 场景 | 推荐身份 |
|------|----------|
| 访问用户已有飞书文档 | `--as user` |
| 追加到用户自己的飞书文档 | `--as user` |
| 上传到用户云空间 | `--as user` |
| 企业级自动化 / bot 资源 | `--as bot`（需用户明确要求）|

不要默认使用 `--as bot` 去写用户自己的文档。

## 三、飞书写入前的最小确认项

在新环境中，写飞书前至少确认：

1. 是否已经有目标文档 ID / URL
2. 如果没有，是新建文档还是先让用户指定文档
3. 当前身份是否有权限访问该文档
4. 当前任务是 append、replace 还是 create
5. 写入对象是 doc/docx 还是 wiki 节点映射出的真实对象

**上下文复用：** 如果当前对话中已出现过目标文档的 URL 或 ID，直接复用，不必重复询问。

## 四、历史去重依赖

如果任务要求"继续追加""不要重复写已经记录过的平台"，必须先：
- 读取已有飞书文档内容
- 抽取历史候选名单（名称 + 规范化域名）
- 以历史文档为第一去重基线

如果拿不到已有文档内容：
- 不要声称已完成历史去重
- 最多只能完成"本轮内部去重"

## 五、写入格式纪律

### 1. 先汇总，再写入
不要边搜索边直接写飞书。标准顺序应为：
- 搜索
- 抓取与验证
- 去重
- 风险分层
- 生成完整 Markdown
- 再由主代理串行写入

### 2. 主代理串行写入
如果使用 subagent：
- subagent 只负责搜索、抓取、初步核验
- 最终飞书写入只能由主代理执行

### 3. 保持真实换行
写入 Markdown 时：
- 使用真实换行
- 不要依赖脆弱的 `\n` 拼接作为主要手段

### 4. 避免 shell 引号与反引号坑
在命令行拼接长 Markdown 时：
- 避免反引号包裹 URL
- 避免多层引号嵌套导致 shell 解释错误
- 优先构造稳定的单次写入内容

### 5. 写入命令参考
```bash
# 追加到文档末尾
lark-cli docs +update --doc "<doc_url>" --mode append --body "<markdown>" --as user

# 替换整个文档
lark-cli docs +update --doc "<doc_url>" --mode replace --body "<markdown>" --as user
```

## 六、无飞书能力时的降级方式

如果新环境没有飞书写入能力或认证未完成：
- 先输出完整结构化 Markdown
- 明确告诉用户"尚未写入飞书"
- 将结果保留为后续可直接粘贴或再调用飞书工具写入的版本


path: references/known-failures-and-fallbacks.md
content: # Known Failures and Fallbacks

这份文档记录最可能遇到的失败场景，以及该 skill 应该如何降级，而不是中途悄悄改变目标。

## 一、BrightData MCP 未配置

### 症状
- 无法调用 `mcp__brightdata__*` 系列工具
- 工具不存在或连接失败

### 正确处理
1. 检查是否已安装 BrightData CLI 作为备选：`which brightdata`
2. 如果 CLI 也不可用，告知用户需要配置 BrightData（MCP 或 CLI 二选一）
3. MCP 安装命令：`claude mcp add --transport sse brightdata "https://mcp.brightdata.com/sse?[REDACTED_SECRET]"`
4. CLI 安装命令：`npm install -g @brightdata/cli` → `brightdata login`
5. MCP 配置完成后需要重启 Claude Code 会话
6. 降级：如果用户能提供候选名单，改做"验证与整理"模式

## 二、BrightData 已配置但搜索/抓取失败

### 症状
- MCP 工具可调用但返回错误
- CLI 命令执行失败
- API token 过期或额度用尽
- 网络连接问题

### 正确处理
- 重试一次，确认是否为临时问题
- 如果 MCP 失败但 CLI 可用（或反之），切换到另一种方式
- 如果持续失败，告知用户可能的原因（token、额度、网络）
- 已获取的部分结果仍然保留并输出

## 二.5、BrightData CLI 未安装

### 症状
- `which brightdata` 返回空
- `brightdata: command not found`

### 正确处理
1. 自动尝试安装：`npm install -g @brightdata/cli`
2. 安装后提示用户运行 `brightdata login` 完成认证
3. 如果同时 MCP 也不可用，搜索和抓取能力均不可用，需降级

## 三、lark-cli 未安装

### 症状
- `which lark-cli` 返回空
- `lark-cli: command not found`

### 正确处理
1. 自动尝试安装：
   ```bash
   npm install -g @larksuite/cli
   npx skills add https://github.com/larksuite/cli -y -g
   ```
2. 安装后提示用户运行 `lark-cli config init` 完成配置
3. 如果 npm 也不可用，告知用户需要先安装 Node.js

## 四、lark-cli 已安装但未认证

### 症状
- `lark-cli auth status` 显示未登录
- 执行文档操作时返回认证错误

### 正确处理
1. 提示用户运行 `lark-cli auth login --recommend`
2. 说明此步骤需要在浏览器中确认授权
3. 等待用户完成后重新检查状态
4. 降级：先输出完整 Markdown，标注"尚未写入飞书"

## 五、lark-cli 已认证但缺少特定权限

### 症状
- 执行操作时返回 `Permission denied` 或 `缺少权限 "xxx"`
- lark-cli 的错误信息通常会包含修复命令

### 正确处理
1. 读取错误信息中的修复命令
2. 提示用户执行该命令（如 `lark-cli auth login --scope "docs:doc:readonly"`）
3. 如果需要在飞书后台授权，告知用户操作步骤

## 六、没有目标文档 ID

### 症状
- 用户要求"整理到飞书"，但没有给 doc_id / URL
- 当前上下文里也没有目标文档

### 正确处理
- 明确区分：
  - 是要新建文档
  - 还是要追加到已有文档
- 在未确认前，不要假设目标文档
- 如果上下文对话中之前出现过文档 URL，可以直接复用

## 七、无法读取历史文档内容

### 症状
- 用户要求"不重复写"
- 但当前环境无法读取历史飞书文档

### 正确处理
- 只能完成"本轮内部去重"
- 必须明确告诉用户：无法保证已与历史文档完全去重

## 八、subagent/worktree 失败

### 症状
- 当前目录不是 git 仓库
- git 没有 commit
- `HEAD` 无法解析
- 无法创建 worktree

### 正确处理
- 如果用户允许，自动补 git 初始化与初始 commit
- 否则退化为主代理串行执行

## 九、Markdown 写入格式崩坏

### 症状
- 飞书文档里换行失效
- 内容挤成一团
- URL 被 shell 误解释

### 正确处理
- 使用真实换行
- 不要在 URL 外面包反引号
- 避免脆弱的多行 shell 拼接
- 先构造完整 Markdown，再一次性写入

## 十、npm / Node.js 不可用

### 症状
- 无法安装 lark-cli
- `npm: command not found`

### 正确处理
- 告知用户需要先安装 Node.js 环境
- 提供 Node.js 官方下载地址或推荐使用 nvm
- 降级：先输出完整 Markdown，等环境准备好后再写入飞书

## 降级原则

遇到环境问题时，不要假装任务已经完整执行。应明确说明：
- 哪一步能做
- 哪一步做不了
- 当前输出是什么
- 用户若想完整执行，还缺什么前置条件

**优先级：** 尽量多做能做的步骤，而不是因为一个环节缺失就完全放弃。例如：搜索和抓取已完成但飞书不可写，仍应输出完整的结构化结果。


path: references/lark-cli-install-and-auth.md
content: # lark-cli 安装与认证

本文档说明如何安装和配置 lark-cli，使 skill 获得飞书文档读写能力。

## 前置条件

- Node.js 环境（用于 npm/npx）
- 飞书账号

## 安装步骤

### 1. 安装 CLI

```bash
npm install -g @larksuite/cli
```

### 2. 安装 Skills

```bash
npx skills add https://github.com/larksuite/cli -y -g
```

这会安装 19 个飞书 Agent Skills，覆盖日历、消息、文档、表格等 11 个业务域。

### 3. 初始化配置

```bash
lark-cli config init
```

这是一个交互式引导流程：
- 选择语言（中文/英文）
- 选择一键配置应用
- 选择飞书版本（国内版飞书 / 国际版 Lark）
- 扫码授权

### 4. 登录授权

```bash
lark-cli auth login --recommend
```

`--recommend` 会自动选择常用权限范围。

### 5. 验证状态

```bash
lark-cli auth status
```

成功输出应显示已登录的身份和权限列表。

## 检测 lark-cli 是否可用

在 skill 的 preflight 阶段：

```bash
# 检查 lark-cli 是否已安装
which lark-cli 2>/dev/null && echo "installed" || echo "not_installed"

# 检查认证状态
lark-cli auth status 2>&1
```

## 自动修复流程

如果 lark-cli 未安装或未认证，按以下顺序尝试修复：

### 情况 1：lark-cli 未安装
```bash
npm install -g @larksuite/cli
npx skills add https://github.com/larksuite/cli -y -g
```
安装后提示用户运行 `lark-cli config init` 完成交互式配置。

### 情况 2：已安装但未配置
提示用户运行：
```bash
lark-cli config init
```
此步骤需要用户扫码，无法自动完成。

### 情况 3：已配置但未登录
```bash
lark-cli auth login --recommend
```
此步骤可能需要用户在浏览器中确认授权。

### 情况 4：已登录但缺少特定权限
lark-cli 的错误信息会指导下一步，例如：
```
Error: 缺少权限 "docs:doc:readonly"
修复命令：lark-cli auth login --scope "docs:doc:readonly"
```
按错误提示的命令补充权限即可。

## 身份选择

| 场景 | 推荐身份 |
|------|----------|
| 访问用户自己的飞书文档 | `--as user` |
| 追加到用户自己的飞书文档 | `--as user` |
| 企业级自动化工作流 | `--as bot` |

本 skill 默认使用 `--as user`，除非用户明确要求使用 bot。

## 本 skill 常用命令

| 操作 | 命令 |
|------|------|
| 读取文档内容 | `lark-cli docs +fetch --doc "<doc_url>" --as user` |
| 搜索文档 | `lark-cli docs +search --keyword "<keyword>" --as user` |
| 追加内容到文档 | `lark-cli docs +update --doc "<doc_url>" --mode append --body "<markdown>" --as user` |
| 覆盖文档内容 | `lark-cli docs +update --doc "<doc_url>" --mode replace --body "<markdown>" --as user` |


path: references/smoke-tests.md
content: # Smoke Tests

每项能力的最小验证命令。在 preflight 阶段使用，快速判断能力是否可用。

## 1. BrightData 搜索能力

**验证方式 A（MCP）：** 执行一次最小搜索
```
使用 mcp__brightdata__search_engine 工具搜索 "test"
```

**验证方式 B（CLI）：**
```bash
brightdata search "test" 2>&1 | head -5
```

**成功标志：** 返回搜索结果列表
**失败标志：** 工具不存在、连接失败、command not found、或返回错误

## 2. BrightData 抓取能力

**验证方式 A（MCP）：** 抓取一个简单页面
```
使用 mcp__brightdata__scrape_as_markdown 抓取 "https://example.com"
```

**验证方式 B（CLI）：**
```bash
brightdata scrape https://example.com 2>&1 | head -10
```

**成功标志：** 返回页面 Markdown 内容
**失败标志：** 工具不存在、连接失败、command not found、或返回错误

## 2.5. BrightData CLI 安装与认证状态

**验证命令：**
```bash
which brightdata 2>/dev/null && brightdata --version
```

**认证检查：**
```bash
brightdata config 2>&1
```

**成功标志：** 输出版本号和配置信息
**失败标志：** command not found 或未认证提示

## 3. lark-cli 安装状态

**验证命令：**
```bash
which lark-cli 2>/dev/null && lark-cli --version
```

**成功标志：** 输出版本号
**失败标志：** command not found

## 4. lark-cli 认证状态

**验证命令：**
```bash
lark-cli auth status
```

**成功标志：** 显示已登录的身份信息
**失败标志：** 未登录提示、或权限不足提示

## 5. 飞书文档读取

**验证方式：** 尝试读取目标文档
```bash
lark-cli docs +fetch --doc "<target_doc_url>" --as user
```

**成功标志：** 返回文档内容（JSON 包含 markdown 字段）
**失败标志：** Permission denied、文档不存在、或认证过期

## 6. 飞书文档写入

**验证方式：** 对目标文档做一次 dry-run 或最小追加测试
建议先读取文档确认权限，不要在 smoke test 阶段实际写入内容。

## 7. subagent/worktree 前置条件

**验证命令：**
```bash
git rev-parse --is-inside-work-tree 2>/dev/null && git rev-parse HEAD 2>/dev/null
```

**成功标志：** 第一行输出 `true`，第二行输出 commit hash
**失败标志：** 不在 git 仓库、或 HEAD 无法解析

## Preflight 判定矩阵

| 能力 | 通过 | 可自动修复 | 需用户介入 |
|------|------|-----------|-----------|
| BrightData 搜索（MCP） | smoke test 1A 通过 | - | 需用户配置 MCP + API token |
| BrightData 搜索（CLI） | smoke test 1B 通过 | 可自动 `npm install -g @brightdata/cli` | 需用户 `brightdata login` |
| BrightData 抓取（MCP） | smoke test 2A 通过 | - | 同上 |
| BrightData 抓取（CLI） | smoke test 2B 通过 | 同上 | 同上 |
| lark-cli 安装 | smoke test 3 通过 | 可自动 `npm install -g @larksuite/cli` | - |
| lark-cli 认证 | smoke test 4 通过 | 可提示命令 | 需用户扫码/确认 |
| 文档读取 | smoke test 5 通过 | - | 权限问题需用户处理 |
| subagent | smoke test 7 通过 | 可自动 `git init && git commit` | - |

**注意：** MCP 和 CLI 两种 BrightData 接入方式任一可用即满足搜索/抓取能力要求。MCP 对 agent 更友好（直接工具调用），CLI 对终端操作和管道组合更灵活。


path: references/subagent-git-prerequisites.md
content: # Subagent and Git Prerequisites

这个 skill 支持把“搜索与抓取”阶段并行化，但不应假设所有环境都天然支持 subagent/worktree。

## 一、何时适合用 subagent

适合：
- 需要扩展多组 query
- 需要并行搜索不同来源或不同语言关键词
- 需要并行核验多个候选平台

不适合：
- 任务量很小
- 当前环境不稳定
- 当前没有 git/worktree 前置条件
- 最终写入飞书阶段

## 二、subagent 的职责边界

subagent 可以做：
- query 扩展
- 搜索候选
- 抓取官网、docs、pricing、terms 等公开页
- 提取初步结构化字段
- 返回候选摘要和证据链接

subagent 不应做：
- 最终历史去重
- 风险等级定稿
- 飞书写入
- 最终面向用户的主结论

## 三、如果要用 worktree 隔离

某些 agent/worktree 运行依赖 git 仓库环境。开始前检查：

1. 当前目录是否在 git 仓库里
2. 仓库是否至少有一个 commit
3. `HEAD` 是否可解析

检测命令见 `smoke-tests.md` 第 7 项。

## 四、已知常见问题

### 1. 不在 git 仓库
可能出现：
- 无法创建 agent worktree

处理：
- 初始化 git 仓库，或不要使用依赖 worktree 的 subagent 模式

### 2. git 仓库存在，但没有 commit
可能出现：
- `Failed to resolve base branch \"HEAD\"`
- `git rev-parse failed`

处理：
- 创建至少一个初始 commit，再尝试使用 worktree/subagent

### 3. 多个 subagent 同时修改同一目标
风险：
- 冲突
- 重复写入
- 汇总格式漂移

处理：
- 搜索与抓取可并行
- 汇总与飞书写入必须由主代理串行完成

## 五、无 subagent 时的降级规则

如果环境没有 subagent，或 worktree 前置条件不满足：
- 改为主代理串行执行所有步骤
- 仍然保留相同纪律：
  - 先搜索和抓取
  - 再汇总去重
  - 再统一分层
  - 最后串行写飞书

没有 subagent 只会影响效率，不应该影响流程正确性。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)