Steviewonders99/ultimatescrape

# UltimateScrape [](https://github.com/Steviewonders99/ultimatescrape/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) [](#install) **一个会自我检查作业的开源深度研究 agent。** 它会围绕一个研究问题 分派出数百个小型 LLM agent，然后完成大多数研究 agent 会跳过的工作： 对 agent 引用的每个 URL 进行存活检查，每项发现都会遭到独立的对抗性 验证者的攻击，并且最终报告中的每个数字都是在 Python 中计算出来的， 而不是由模型回忆出来的。 大多数深度研究工具会交给你一份自信满满的报告，里面的引用却无人 检查。而这个工具会告诉你哪些发现通过了检查，哪些被反驳，有多少个 独立 agent 对此予以证实，以及哪些引用的来源已经失效。 ``` flowchart LR A[targets x dimensions] --> B[N parallel agents] B --> C[merge + corroboration count] C --> D[liveness-check every cited URL] D --> E[adversarial verifiers
distinct lenses, majority vote] E --> F[synthesis] F --> G[markdown / csv / xlsx / json] ``` ## 为什么 - **引用被视为声明，而非证据。** 对每个引用的 URL 执行一次真实的 GET 请求， 失效的 URL 会压倒任何程度的模型共识。 - **验证者试图反驳，而非证实。** 每个验证者都有不同的视角——事实 准确性、时效性、具体性。三个完全相同的怀疑论者会互相认同； 三个不同的怀疑论者则不会。 - **模型做判断，代码做计算。** 每个数字、去重和 URL 检查都在 Python 中发生并被断言。 - **它会自动停止。** 一旦某次运行突破你的支出上限，一个共享账本会立刻抛出异常， 因此失控的代价只是一次调用的开销，而不是你的全部预算。约为 $0.066/agent。 - **安全地中断。** 每个 agent 都会将检查点存入磁盘；`resume` 只会重新分发 那些未完成的任务。你永远不需要付两次钱。 - **为真实研究提供全套装备** —— 收录了 61 个政府统计和公司注册 API，并详细记录了它们各自的怪癖（41 个不需要密钥），提供带有 公开薪酬标准的竞争对手招聘信息流，以及一个在多次运行间不断积累 且具备完整溯源的本地知识图谱。 ## 快速开始 ``` git clone https://github.com/Steviewonders99/ultimatescrape.git cd ultimatescrape uv venv --python 3.13 && uv pip install -e ".[dev,export]" ``` 有两个命令**完全不需要任何凭证** —— 可以从这里开始： ``` uscrape platforms # 18 competitor platforms, and how each is reached uscrape jobs -p imerit -p appen --pay-only # live listings with published pay rates ``` 只需添加一个密钥（`OPENROUTER_API_KEY`），研究引擎就会启动： ``` uscrape doctor # what's live before you spend anything uscrape company "Toast" "Square" "Lightspeed" # 3 companies x 8 dimensions = 24 agents uscrape market "United States" "Canada" -t "restaurant POS software" uscrape vendor -c Brazil -c Vietnam -p "small video data collection studios" uscrape resume latest # finish an interrupted run, paying only for gaps uscrape ga4 run geo --days 28 # engagement by country and city uscrape graph show "Scale AI" --provenance # what we know, and who said it ``` Windows 用户：运行 `.\setup.ps1` 并查看 [`ONBOARDING.md`](ONBOARDING.md)。 所有配置都在 [`uscrape.toml`](uscrape.toml) 中 —— 包括输出格式、 要监控哪些竞争对手、以及是否开启图谱。环境变量会覆盖其中的配置， 因此 CI 永远不需要修改该文件。 ## 为什么这样构建 在三个同类的代码库中，已经有五个 swarm 研究系统存在。 它们各自拥有必要组件中的一两个，但没有一个拥有全部：重试和退避机制 只存在于普查 swarm 中，模型回退链也仅存于此，密钥池只存在于一个 worker 中， 额度预检存在于另一个中，带有失败门控写入的 TTL 缓存 只存在于文化研究引擎中，可恢复的任务队列 只存在于 supervisor 中，而共识投票又只在普查 swarm 中。 以前的所有系统都没有积累以美元计算的成本或执行 token 预算，因此 一旦扇出崩溃，一切都会付诸东流。 UltimateScrape 将这些组件聚集在一处，并添加了它们都没有的功能： 针对主机的礼貌策略、robots 协议处理、真正的请求重试策略、HTML 转 Markdown 提取，以及增量检查点。 ### 发挥作用的目标分解 一次运行就是 **targets × dimensions**。target 是指被研究的对象（一个国家、 一家公司、一个市场）。dimension 是应用于 targets 的一个角度（竞争对手、 招聘信号、法规、定价）。40 个 targets 乘以 8 个 dimensions 就是 320 个 独立的 agent。 这比这里任何其他的设计选择都重要。一个关于 40 个国家的大型 prompt 会返回浅薄、处处留有余地的套话。300 个小 prompt，每个针对一个国家 提出一个问题，则会返回具体的细节——并且每个都可以 单独缓存、重试、跳过，而且成本极低。 ### 模型与代码之间的劳动分工 模型提供 **映射、判断和文本描述**。Python 计算 **每一个数字、 每一次去重、以及每一次 URL 检查**，并对结果进行断言。这种分工正是 让一次 300-agent 的运行值得信赖（而不仅仅是规模庞大）的原因，它 直接借鉴自 census 语言 swarm，后者之所以是前身中最可靠的，恰恰是因为 它从不让 LLM 做算术。 ## 安装详情 ``` uv venv --python 3.13 uv pip install -e ".[dev,export]" cp .env.example .env # then set OPENROUTER_API_KEY ``` `config.py` 会先读取 `./.env`，然后是 `USCRAPE_ENV_FALLBACKS` 中列出的任何文件， 这让你可以指向位于其他位置的现有 `.env`，而无需将密钥 复制到第二个文件中。使用平台对应的分隔符（Windows 上为 `;`， 其他平台上为 `:`）分隔多个路径。 两个可选层级。两者都比较重，而且都不会自动激活——浏览器 层级仅在 HTTP 获取返回的内容单薄时才会被使用，而 LinkedIn 解析器 层级在接管之前会保持休眠状态，直到你为其提供一个 session。 ``` uv pip install -e ".[crawl]" && crawl4ai-setup # headless browser uv pip install -e ".[linkedin]" && patchright install chromium # LinkedIn parsers ``` 在启用第二个层级之前，请阅读 [`docs/LINKEDIN.md`](docs/LINKEDIN.md)。 ## 层级架构 ``` sources/ official APIs — 61 catalogued, 41 usable with no key at all jobboards/ competitor and worker-gig feeds, with published pay rates ga4/ analytics reporting, no Google SDK required fetch/ polite HTTP with retries and robots, plus a Crawl4AI browser tier channels/ URL → access path, with tiered fallback and health checks swarm/ fan-out, merge, URL validation, adversarial verification, synthesis graph/ local knowledge graph accumulating entities and provenance output/ one row model → markdown, json, csv, xlsx, html, mermaid publish/ SharePoint upload via Microsoft Graph store/ run directories, per-unit checkpoints ``` ### `sources/` —— 官方统计和注册机构 61 个来源被记录为数据而非代码，因为六十个统计机构共享大约五种协议。 实现这些协议（PxWeb 1.x 和 2.0、SDMX、OData、Census 矩阵格式）并将机构 描述为数据，是保持其可维护性的唯一方法。 每个条目都记录了那些如果不注意就会让你耗费一个下午的怪异之处。以下是一些 已经编码进去的示例： - **US Census** 现在*每次*查询都需要密钥；被广泛引用的每日 500 次的 无密钥层级已不复存在，且被隐藏的单元格会显示为 `-666666666`。 - **Companies House** 使用 HTTP Basic 认证，将密钥作为*用户名*并使用空 密码，而不是 Bearer token。 - **World Bank** 通过 **502 HTML 页面或读取超时来发出限流信号，从来不会返回 429** —— 在突发请求下，有效的 URL 会以看起来像格式错误请求的 方式开始失败。（我曾怀疑过 `date=2022:2023` 中的冒号和 `USA;BRA` 分隔符， 后来才确认这两者都没问题，请求频率控制才是问题所在。） - **ISTAT** 在每分钟 5 次请求以上时会将你的 IP 封禁一到两天。 - **OECD** 允许每小时下载 60 次，并会完全屏蔽 VPN 流量。 - **IMF** 的旧版 API 已于 2025 年 11 月退役；**FAOSTAT** 在 2026 年 4 月全面 要求使用 JWT；`odata4.cbs.nl` 和 `api.data.abs.gov.au` 已经完全无法解析。 ``` uscrape sources --ready # what works right now uscrape sources --protocol pxweb # everything sharing one adapter uscrape census --var B01003_001E --var B19013_001E --for "state:*" ``` ### `channels/` —— 带有健康检查的分层访问 借鉴自 Agent-Reach，这是该项目中唯一一个真正出色的想法。 一个 channel 会声明它处理哪些 URL 以及一个有序的后端列表； 调度器负责路由，channel 则遍历其层级直到有一个成功。访问权限控制 因此变成了一项配置决策，而不是代码修改，并且 `uscrape doctor` 会在运行*之前*告诉你哪些层级是存活的，而不是在运行了四十分钟之后。 ### `jobboards/` —— 竞争对手情报 促成这一点的发现是：几乎每一家 AI 数据领域的竞争对手都在标准的 ATS 上运行企业招聘，并带有公开的 JSON API，因此 **一个适配器就能覆盖九家 公司** —— 无需抓取、无需浏览器、也没有实质性的速率限制。少数几家运行着 自定义 endpoint，而这些才是有价值的，因为它们发布了公司董事会 所没有的 **工人薪酬标准**。 ``` uscrape platforms # 18 competitors and how each is reached uscrape jobs --pay-only # only listings with a published rate uscrape jobs --gigs # worker gigs, not corporate roles ``` 截至最后一次运行时的实时数据：iMerit 22/23 个列表带有薪酬标准，Appen 49/49， Handshake 121/130，TELUS 54/121。iMerit 是观察地域薪酬套利最清晰的窗口 —— 相同的英文转录工作在不同国家的定价大相径庭。 招聘平台的 token 也被记录了下来，因为大多数是无法猜到的：Invisible 是 `agency`， Sama 是 `samainc`，Appen 是 `appen`，而不是它自己网站上宣传的 `appen-2`。 ### `ga4/` —— 面向市场研究团队的分析 特意构建为**不依赖 Google SDK**。Google 认证的两部分都是普通的 HTTP，所以这不需要 `gcloud`，不需要密钥文件，也不需要原生构建——它可以在 Windows 笔记本电脑上保持原样运行。包含 14 个命名报告，每个报告都解答一个 问题，而不需要你去了解 API 字段名。 ``` uscrape ga4 reports # the catalogue uscrape ga4 run devices -f xlsx # device and OS mix as a spreadsheet uscrape ga4 run device-by-country # does device preference differ by market? uscrape ga4 fields -s engagement # valid field names, so nobody guesses ``` 针对三种 API 行为进行了专门处理，而不是放任不管：九维度上限、 将 `(not set)` 作为字面字符串而非 null 处理，以及针对任何宽泛数据的 offset 分页。 ### `graph/` —— 本地知识图谱 基于 SQLite，单文件，无服务器。其核心在于积累：关于一家公司的 第二个问题应该比第一个更便宜。两次提取过程 —— 首先进行确定性提取（来自发现字段，无需模型调用，不产生幻觉 的可能），然后是可选的 LLM 提取，用于处理仅在文本中陈述的关系。 这种排序意味着模型的失败只会损失丰富度，永远不会损失正确性。 ``` uscrape graph stats uscrape graph search "Scale" uscrape graph show "Scale AI" --depth 2 --provenance uscrape graph export -f mermaid ``` Observation 采用追加模式，并且每一条边都携带了生成它的运行 ID、 agent 和 URL —— 因此知识图谱始终能回答“是谁说的？”，并且 在发现来源有误时可以进行纠正。重新观察到同一条边会增加其权重 而不是产生重复，因此权重可以直接作为佐证计数来解读。 ### `output/` —— 一种行模型，七种格式 发现、职位列表、GA4 数据行和知识图谱的边都会变成相同的 `Dataset`， 因此一份 GA4 地理数据的 CSV 和一份研究发现的 CSV 具有相同的结构和 溯源列。如果一个研究团队从每个命令那里得到结构不同的电子表格， 他们最终只能全部手动重新构建。 CSV 在写入时使用了 UTF-8 BOM，以便 Windows 上的 Excel 能正确 渲染重音符号，而 xlsx 则会根据判定结果进行拆分，并带有 冻结的表头和自动筛选。 ### `swarm/` —— 运行 pipeline 1. **预检** —— 额度检查、后端健康状态、工作矩阵扩展、恢复扫描 2. **研究** —— 在信号量控制下进行扇出，每个结果在落地的瞬间即刻存入检查点 3. **合并** —— 进行带有佐证计数和字段回填的去重 4. **验证** —— 对 agent 声称的每一个 URL 进行存活检查 *（确定性的，免费）* 5. **检验** —— 对每项发现分配 N 个对抗性验证者，每个验证者都有独特的视角 6. **综合** —— 对已验证的集合进行一次判断 7. **报告** —— Markdown 加上机器可读的 JSON 第 4 步是整个系统中价值最高的步骤，且成本为零。先前的 供应商 swarm 系统已经证明，LLM 报告的 URL 经常出错，以至于一份未经验证的 列表会毒害整个数据集。 第 5 步对每个验证者使用*不同的*视角，而不是 N 个相同的怀疑论者 —— 三个相同的怀疑论者会互相认同；三个不同的怀疑论者则不会。 ## 从 Python 中使用它 ``` import asyncio from ultimatescrape import Swarm from ultimatescrape.swarm.spec import SwarmSpec, Target, Dimension from ultimatescrape.swarm.prompts import RESEARCH_SYSTEM spec = SwarmSpec( topic="EU AI Act compliance vendors", targets=[Target.of(c) for c in ("Germany", "France", "Ireland")], dimensions=[ Dimension("vendors", "Who sells AI Act compliance tooling in {label}?"), Dimension("pricing", "What does AI Act compliance tooling cost in {label}?"), ], system_prompt=RESEARCH_SYSTEM, output_contract='{"findings":[{"name":"","summary":"","url":"","confidence":""}]}', verifier_votes=3, ) async def main(): async with Swarm() as swarm: result = await swarm.run(spec) print(result.stats, result.ledger["cost_usd"]) asyncio.run(main()) ``` ## 成本与安全 在一个每个 agent 都会向其写入数据的共享账本中，强制执行着一项硬性 上限（`USCRAPE_MAX_RUN_COST_USD`，默认为 $25）。一旦突破上限，它就会抛出异常， 因此失控的代价仅仅是一次调用的超额，而不是整个预算。在最近一次实际 运行中观察到的费率：**每个落地的 agent 约为 $0.066**，因此一次包含 24 个 agent 的 公司扫描最终花费约 $1.60。 中断的运行可以通过 `uscrape resume ` 恢复。每个工作单元在完成时都会 原子地写入磁盘，只有缺失或出错的工作单元才会被重新分发 —— 一项耗时三小时的 200-agent 任务变得可中断，而不是要么全部成功要么彻底失败。 ## 发布到 SharePoint 使用具有 Microsoft Graph 应用程序权限的 Azure AD 应用注册。 如果你的组织已经有一个用于 SharePoint 自动化的应用注册，请直接复用它 —— 只需 三个环境变量，无需提出新的 IT 请求。 ``` uscrape publish latest --dry-run # verify auth, site and folder access uscrape publish latest # confirms before uploading ``` 默认处于禁用状态，且始终是一个显式执行的命令：上传是面向外部的操作，因此完成一次运行绝不会将其作为副作用发布任何内容。请注意，该应用持有 **Sites.Selected** 权限，因此只有管理员明确授权的站点是可访问的。 ## API 密钥 [`docs/API_KEYS.md`](docs/API_KEYS.md) 涵盖了每一个密钥——去哪里注册、需要 多长时间，以及如果没有它会出什么问题。简短版：你**只需一个**密钥 即可使用本系统，如果你需要 US Census 数据，则需要 `CENSUS_API_KEY`，因为截至 2026 年，这已经是每次查询的强制要求，而不再是可选项。 ## LinkedIn 在启用默认层级之外的任何功能之前，请阅读 [`docs/LINKEDIN.md`](docs/LINKEDIN.md)。 自动化访问违反了 LinkedIn 的用户协议，并且自托管的层级带有真实的 账号限制风险。层级链条使得这成为一个明确的、经过配置的决策。比 库的选择更重要的操作细节是：**为每个账号使用一个专用的静态 ISP 地址，并在创建 session 之前设置好代理** —— 将已登录的 session 移动到新 IP 上 本身就是一种触发检查点的行为，因此使用轮换的住宅 IP 池比不用代理更糟糕。 ## 测试 ``` .venv/bin/python -m pytest tests/ -q # 51 passing, no network required ```

标签：Linux安全, LLM代理, Python, 人工智能, 数据采集与验证, 无后门, 深度研究智能体, 用户模式Hook绕过, 逆向工具