Skip to content

Latest commit

 

History

History
74 lines (49 loc) · 6.9 KB

AGENTS.md

File metadata and controls

74 lines (49 loc) · 6.9 KB

供在此仓库中工作的编码智能体阅读

更改任何内容前,请先阅读本文。以下每一行均已于 2026-09-18 对照实时 API 或已安装的 SDK brightdata-sdk 2.5.2 进行验证。其中多处内容与 SDK 自身的行为或文档字符串相矛盾。

此仓库可以演示的内容

LinkedIn 个人资料数据属于个人数据。API 本身也明确说明了这一点:个人资料数据集的 46 个字段中,有 8 个被标记为 pii: true,即 id、name、about、url、input_url、linkedin_id、first_name 和 last_name。

  • 示例使用职业信息已经公开的公众人物以及公司页面。请勿添加抓取普通个人信息的示例。
  • 请勿添加基于 search.linkedin.profiles 的示例。它按名字和姓氏搜索,属于人员搜索。
  • 客户需自行负责确保用途合规,README 会链接到 Bright Data 的合规材料,而不会在此重复说明。

身份验证

  • SDK 会从环境变量、通过从其自身安装文件夹向上搜索找到的 .env 文件(因此,当虚拟环境位于项目内时,就是项目根目录),或 Bright Data CLI 登录信息中读取 BRIGHTDATA_API_TOKEN。对应的 JavaScript 版本完全不会读取 .env;请勿将其措辞复制到这里。
  • 始终以 SyncBrightDataClient(auto_create_zones=False) 的方式构造客户端。如果保持开启,SDK 会在启动时创建此仓库从不使用的网络解锁器和 SERP 区域,而在没有付款方式的情况下,区域创建会失败。

API 的行为方式

  • 每次调用都是一个异步作业:触发、轮询、获取。2026-09-18,个人资料作业耗时 13 秒至 64 秒。
  • timeout 的单位是秒,默认为 180。对应 JavaScript 版本的 pollTimeout 单位是毫秒。直接复制数字会相差一千倍。
  • 对于 URL,LinkedIn 功能位于 client.scrape.linkedin;对于姓名、关键词和日期搜索,则位于 client.search.linkedin。JavaScript SDK 没有 search.linkedin;在其中,这两类功能都是 scrape.linkedin 上的 discover* 方法。
  • 个人资料数据集是 gd_l1viktl72bvl7bjuj0,这也是控制面板显示的 ID。
  • 一组 URL 属于一个作业。API 按记录计费,而不是按作业计费。

SDK 错误标记列表结果

这是最需要记住的一点。对于 URL 列表,_scrape_urls 按位置将结果行与输入配对:

for url_item, data_item in zip(url_list, result.data):
    ScrapeResult(success=True, data=data_item, url=url_item, ...)

API 每次运行都会以不同顺序返回结果行。2026-09-18 使用三个输入进行测试时,标记为 reidhoffman 的结果包含已失效个人资料的错误,而标记为已失效 slug 的结果却包含 Reid Hoffman 的个人资料。

  • 对于列表输入,绝不要读取 ScrapeResult.url。请根据结果行自身的 input_url 将其与输入匹配;对于没有 input_url 的错误行,则使用 input["url"]。src/linkedin_scraper/scrape.py 中的 attribute() 实现了这一点。
  • 在列表结果中,success 始终为 True,错误行也不例外。请读取结果行本身。
  • 如果返回的结果行少于输入数量,zip 会静默丢弃其余输入。
  • 发生失败或超时时,即使输入是列表,该方法也只会返回一个 ScrapeResult,而不是列表。
  • amazon、facebook、instagram、pinterest 和 tiktok 爬虫工具中也存在相同的 zip。相关问题在 sdk-python#60 中跟踪。

错误行

  • 之所以会返回错误行,是因为执行器发送了 include_errors=True。API 默认关闭此选项。
  • 已失效的个人资料:The profile is hidden or private.
  • 受限流的账户:Crawler error: Your system is sending too many of this type of request. If you need to send more, contact your Account Manager。有效的个人资料也会因此失败。2026-09-18,在短时间内多次调用个人资料接口后观察到此情况。请等待一段时间再重新运行。
  • 请根据消息进行匹配,而不是 error_code。

会产生费用的操作

  • search.linkedin.jobs 没有限制返回行数的参数,也从不发送 limit_per_input。每条职位信息收取一个额度,而宽泛的关键词可能匹配数千条结果。因此 README 不会运行它,因为 README 中的每个代码块都会每周重新运行。测试固定检查缺少该参数,因此一旦加入限制参数,测试就会失败。
  • 它接受不带地点的关键词。对应的 JavaScript 版本要求提供 location。
  • 绝不要在 README 中固定职位 URL。职位可能关闭,届时每周检查会在代码本身没有任何问题的情况下变红。

数据结构

  • 绝不要硬编码字段列表。API 还会返回数据结构中未列出的 timestamp 和 input。
  • client.datasets.linkedin_profiles.get_metadata() 以字典形式返回 fields,但会丢弃 pii:每个 DatasetField 仅保留 type、active、required 和 description。请从原始端点 https://api.brightdata.com/datasets/gd_l1viktl72bvl7bjuj0/metadata 读取该标记,live.yml 中的字段表步骤正是这样做的。相关问题在 sdk-python#61 中跟踪。
  • 完整文档索引,每个条目对应一个 .md 页面:https://docs.brightdata.com/llms.txt

Bright Data CLI

CLI 0.4.0(2026 年 10 月 12 日)移除了 linkedin_person_profile 等流水线类型名称:bdata pipelines <type> 现在会以状态码 1 退出。请通过数据集 ID 和方法运行爬虫工具,即 bdata pipelines run gd_l1viktl72bvl7bjuj0 collect_by_url <url>。请运行 bdata pipelines search linkedin,不要猜测 ID。README 代码块使用未固定版本的 npx,因此无论 live.yml 固定了什么版本,它始终会获取最新的 CLI。

API 会间歇性停滞

2026-09-16,API 出现了多轮持续约一小时的停滞,在此期间大多数作业会一直等待到轮询截止时间,随后返回 status: "timeout",且不包含任何结果行。在这些时段之间,相同调用可在约一分钟内完成。负载无法解释这一现象。如果实时检查变红且唯一症状是超时,很可能只是遇到了异常时段:在查找代码变更前,请先重新运行。

在此仓库中工作

  • pytest 可离线运行,不需要令牌。ruff check . 必须通过。
  • CI 会在空白机器上使用 README 自身的命令进行安装。每周工作流会针对真实 API 执行 README 中的每个围栏代码块,每日工作流则会运行规模较小的实时检查。
  • 字段表位于 <!-- fields:start --> 和 <!-- fields:end --> 之间,每天重新生成。请勿手动编辑。
  • “last verified”徽章所在行由每日运行自动重写。请勿编辑。
  • 保持精简:15 个文件,约 300 行 Python 代码。请勿添加重试、去重、调度、数据库、异步示例或并发功能。