用途
document-hunter 是一个自动化文档搜寻工具，使用浏览器自动化（Playwright）在免费公共档案库中系统性地搜索并下载一手文档。当调研需要法院文件、起诉书、笔录、和解协议等原始资料时使用。其定位是替代人工在多档案库间逐个查找文档的繁琐过程。
调用时会依据案件名称、专辑调研需求或明确请求来确定所需文档，然后系统性地检索所有免费来源，下载找到的全部文档，并用元数据整理归档后报告结果。
主要能力
- 系统性检索多个免费来源：DocumentCloud（记者上传的 PACER 文档）、CourtListener（RECAP 众包文档）、Scribd（用户上传的法院文档）、Justia（上诉意见书）、DOJ（起诉书、新闻稿）、SEC（诉状、和解）。
- 下载找到的文档：PDF、笔录、起诉状、起诉书、报告。
- 使用完整 Playwright 能力：点击按钮、等待 JavaScript、从渲染后的 DOM 中提取内容。
- 两阶段方式：先尝试直接下载（快速），再用浏览器自动化（更彻底）。
- 每个站点支持多种策略，一种方法失败则换另一种。
- 生成 manifest.json 元数据清单，记录来源、标题、文件名、URL、大小等，并保留可复现脚本 download-documents.py。
- 结果报告包含：找到的文档清单、已检索来源及各来源命中数量、仍缺失的文档、质量评估。
使用方式
输入通过 $ARGUMENTS 传入。前置要求：
pip install playwright beautifulsoup4 requests
playwright install chromium
工作流程分为三个阶段：
- 准备：检查 Playwright（
pip list | grep playwright），必要时安装；调用resolve_path("documents", album_slug)解析文档存储路径，返回{documents_root}/artists/{artist}/albums/{genre}/{album}/，并创建目录。 - 搜索：生成并运行 Python 脚本，检索所有免费来源、下载找到的文档、生成带元数据的 manifest 并报告结果。站点专属的自动化策略与代码模板参见 site-patterns.md。
- 报告结果：输出形如 DOCUMENT HUNT COMPLETE 的汇总，列出找到的文档及大小与来源、已检索来源及命中数、仍缺失的文档、manifest 路径。
文档存储策略上，原始 PDF 不建议提交到 Git（体积过大），PDF 存放在文档目录下并按专辑结构镜像；Git 中（专辑的 SOURCES.md）只保存带页码的引用摘录、来源 URL 以及对外部 PDF 位置的引用。.gitignore 已配置忽略 *.pdf 与 primary-sources/。
输出结构包含：manifest.json（含元数据的完整目录）、按来源命名的 PDF（如 documentcloud_.pdf、courtlistener_.pdf、doj_*.pdf）以及可复现脚本 download-documents.py。
RECAP 浏览器扩展可众包 PACER 文档：当有人查看 PACER 文档时，RECAP 会将其上传到 CourtListener，随后即可免费下载。安装方式：
cd tools/extensions
curl -L "https://github.com/freelawproject/recap-chrome/releases/download/2.8.6/chrome-release.zip" -o recap.zip
unzip recap.zip -d recap-extension
rm recap.zip
适用场景
- 需要从免费公开档案库获取一手文档的调研（如案件研究、专辑创作资料搜集）。
- 需要跨多个来源系统检索并集中归档文档、保留来源元数据以便引用。
- 需要可复现的下载流程与清单记录。
限制与注意事项
- 需安装 Playwright 及其 Chromium。
- 档案库的可用性会随时间变化。
- 部分来源有反爬保护（文档中给出替代方案）。
- 例如 SEC.gov 有 Akamai WAF，建议改用 DOJ 新闻稿等替代；Scribd 可能需要账号，可选择创建或跳过；CourtListener 若无 RECAP 收录，则需通过 PACER 获取（PACER 按页收费）。
- 始终需核验下载的文档与预期内容一致。
- 若找不到结果，可尝试替代检索词（当事人姓名、案号），检查案件是否过于久远（早于数字化档案），或文档是否被封存。
- 下载失败时可检查是否需要登录、改用直接 URL 下载或检查是否触发限流。
- 应优先穷尽免费来源，保存 URL、日期、来源等元数据用于引用，不要提交 PDF，并报告无法找到的内容以便后续人工跟进。