brightdata-research

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 re...

Security Scan

The skill's instructions, required tools, and expected credentials match its stated purpose (BrightData search/scrape + Feishu/Lark doc writing); it is internally coherent though it will perform system actions (installs, git ops) and requires user credentials at runtime.

Purpose & Capability

The skill name/description describe batch web search, scraping, dedupe, risk-scoring, and writing to Feishu/Lark; the SKILL.md and reference docs consistently require BrightData for search/scrape and lark-cli for Feishu writes. No unrelated services or secrets are requested. Note: the manifest lists no declared required env vars, yet the runtime instructions require the user to provide BrightData API keys and Feishu auth (this is expected for an instruction-only skill but is a documentation gap in metadata rather than a mismatch of purpose).

Instruction Scope

The instructions legitimately instruct the agent to check environment state, call MCP tools or CLI, read Feishu docs, and optionally run subagents. These actions are within the skill's stated remit (preflight checks, reading/writing target Feishu docs, git/worktree checks). Important: the skill tells the agent to run system commands (npm installs, git init/commit, lark-cli calls, brightdata CLI calls) and to read remote/local document contents — all of which are powerful actions but consistent with the purpose.

Install Mechanism

There is no install spec in the manifest (instruction-only), but the docs explicitly instruct installing packages via npm (e.g., @brightdata/cli, @larksuite/cli) and adding skills via npx. These are standard package sources (npm, GitHub). No untrusted direct-download URLs or obfuscated installers are present; automatic global installs and npx commands require elevated privileges and network access, so the user should expect those side effects.

Credentials

The skill requires sensitive credentials at runtime (BrightData API token / MCP config and Feishu/Lark authentication) and requires Node/npm and possibly git. Those credentials are proportionate to the skill's functionality. However, the manifest does not explicitly declare required env vars or a primary credential — the references and SKILL.md do instruct how to provide them (including BRIGHTDATA_API_KEY examples). This is a documentation gap: the skill will need those secrets to operate but they are not enumerated in the registry metadata.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It does instruct commands that modify the system (npm global installs, git init/commit, adding MCP entries) and will read/write user Feishu documents when authorized. Those are expected for the workflow but have real side effects and require user consent/credentials.

Assessment

This skill appears to do what it claims: it uses BrightData for parallel search/scraping, dedupes and risk-scores results, and can append structured Markdown to Feishu/Lark docs via lark-cli. Before installing or running it, consider: (1) It will ask you to provide BrightData API tokens and to authorize lark-cli (Feishu) — only provide credentials you trust and prefer least-privilege tokens. (2) The skill's instructions include running system commands (npm install -g, npx skills add, git init/commit, claude mcp add) which will modify the environment; review/approve these commands before allowing execution. (3) If you need to avoid global installs or git changes, run the skill in an isolated environment or a disposable container/session. (4) Because the manifest is instruction-only, the skill does not itself store credentials in code, but the agent executing these instructions will need your tokens to read/write Feishu documents — confirm how your agent handles secrets. (5) If you are concerned, test on a non-sensitive Feishu doc or use read-only trials first. Overall the skill is internally coherent with its purpose, but exercise normal caution around credentials and system-level installs.

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 直接写同一个飞书文档。

输出格式

默认按下面结构向用户汇报，并尽量按同结构写入飞书文档：

## 第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	每项能力的最小验证命令