Mosimann-adv/tarrafa_scraper

# Tarrafa [](LICENSE) [](SECURITY.md) [](pyproject.toml) [](https://github.com/Mosimann-adv/tarrafa_scraper/actions/workflows/ci.yml) [](https://github.com/Mosimann-adv/tarrafa_scraper/actions/workflows/codeql.yml) [](https://github.com/Mosimann-adv/tarrafa_scraper/releases)  用于**实验性法律用途**的**源码可见**多源 CLI：用于开放式材料和书证（网页、feeds、截图、视频、Instagram、CNPJ、官方公报/DJEN、Datajud 和 PDFs）的盘点整理。 它适用于在法律语境下构建原型并支持材料收集/整理 —— 它**不是** SaaS，**不是**法律服务，也**不能**替代人工分析。 不依赖于任何 IDE、vault 或 AI 助手。 | | | |--|--| | CLI | `tarrafa` | | 版本 | 0.4.0 (实验性) | | Python | ≥ 3.10 | | 状态 | 研究 / 原型 —— **非产品** | | 分发方式 | 在非商业许可证下公开源代码 | | 许可证 | [PolyForm Noncommercial 1.0.0](LICENSE) —— 必须署名 · **禁止商业用途** | ## 30 秒简介 ``` tarrafa page --url https://example.com --out ./out/page.json ``` ``` page: · ok · count=1 · -> out/page.json · text_len=76 ``` 结果是一个 JSON envelope，包含来源、抓取时间、方法、内容、错误和备注。截图和视频还会记录 SHA-256。查看一个[示例 artifact](examples/page_capture.example.json)。 ## 如何使用 典型的案件流程： 1. **安装**（一次）—— 参见下方的[安装说明](#instalação)。 2. **检查环境：** `tarrafa doctor` 3. **（可选）创建案件文件夹：** tarrafa init ./meu-caso --name "Meu caso" 这会创建 `tarrafa.toml` 以及 `raw/`、`shots/`、`html/`、`logs/`、`meta/runs/` 文件夹。 workspace 是**可选的**：你可以将其保存在任何 `--out` / `--out-dir` 中。 4. 使用正确的工具进行**抓取**（务必指定**保存位置**）： | 我想要… | 基础命令 | |--------|----------------| | 获取 URL 的文本 + facts | `tarrafa page --url URL --out ./raw/page.json` | | 一次性处理多个 URL | `tarrafa page --urls-file urls.txt --out ./raw/pages/` | | 屏幕截图（视觉证据） | `tarrafa shot --url URL --out-dir ./shots --id DOC01` | | Instagram 帖子的评论 | `tarrafa ig --url POST_URL --out ./raw/ig.json --storage-state ./storage_state.json --headed` | | CNPJ | `tarrafa cnpj --cnpj 00.000.000/0001-91 --out ./raw/cnpj.json` | | 官方公报（律师） | `tarrafa djen --oab 12345 --uf SP --out ./raw/djen.json` | | 官方公报（当事人 / 内容中的姓名） | `tarrafa djen --papel parte --texto "Nome Completo" --out ./raw/djen.json` | | 通过 CNJ 查询案件 | `tarrafa datajud --cnj … --out ./raw/datajud.json` | | 案件 PDF 中的文本提取 | `tarrafa pdf-extract --dir ./pdfs --recursive --out ./raw/pdf.json` | | 用于打印的相册/档案卡 | `tarrafa album …` / `tarrafa dossier …` | 5. **各工具的帮助文档：** `tarrafa --help` · 列表：`tarrafa list` 6. **全局 flags**（在工具名称之前）： ``` tarrafa --workspace ./meu-caso -v page --url https://example.com --out raw/page.json tarrafa --no-clobber page --url … --out raw/page.json # recusa sobrescrever tarrafa --force page --url … --out raw/page.json # permite com no_clobber ``` 激活 workspace 后，每次执行都会将历史记录保存在 `meta/runs/.json` 中（经过脱敏的参数、artifacts + sha256、exit code）。 分层配置：flags → env (`TARRAFA_TIMEOUT`, …) → `./tarrafa.toml` → `~/.tarrafa/config.toml`。 ### 各项资源由谁配置 | 资源 | 提供方 | |---------|----------------| | Python 3.10+、依赖项、Chromium | 用户的机器 (`pip` + `playwright install`) | | Instagram 会话 (`storage_state.json`) | **每个用户自身的原生登录**（切勿共享该文件） | | `DATAJUD_API_KEY` | 可选（配额）；如果使用，放在本地的 `.env` 中 | | Playwright MCP Token | 可选（真实 Chrome / 扩展） | **不要**在 CLI 中输入密码。**不要**自动化 Facebook OIDC。输出仅发送到你指定的路径。 ## 工具 | 命令 | 功能 | |---------|--------| | `tarrafa init` | 创建可选的 workspace (`tarrafa.toml` + 文件夹) | | `tarrafa ig` | Instagram 评论 → 生成带有 permalink `/c/{id}/` 的 JSON | | `tarrafa page` | 一个公开的 URL → 文本 + facts (meta / JSON-LD) | | `tarrafa site` | 同域名的 BFS 爬虫（限制最大页面数 / 深度） | | `tarrafa feed` | RSS/Atom → 条目 envelope | | `tarrafa shot` | 高质量截图 (PNG + JSON) | | `tarrafa video` | 视频 meta + 帧（+ 可通过 yt-dlp 可选下载） | | `tarrafa album` | 将截图/帧编译为易于打印的 HTML | | `tarrafa dossier` | HTML 档案卡：头像 + 发现结果 + 来源 + 精选截图 | | `tarrafa cnpj` | 通过开放 API CNPJá 查询 CNPJ（无需 API key） | | `tarrafa djen` | DJEN 公告 —— 律师 (`--oab`) 或当事人 (`--papel parte --texto`) | | `tarrafa datajud` | 通过 CNJ 获取 Datajud 的封面/案件进程 | | `tarrafa pdf-extract` | PDF 文件的文本 + identity hints | | `tarrafa doctor` | 检查依赖项、Chromium、ffmpeg、yt-dlp、会话和 env | | `tarrafa list` / `version` | 列出工具 / 版本 | ## 安装说明 ### 使用 从源码安装： ``` git clone https://github.com/Mosimann-adv/tarrafa_scraper.git cd tarrafa_scraper python -m venv .venv # Windows .\.venv\Scripts\Activate.ps1 # macOS / Linux # source .venv/bin/activate python -m pip install . python -m playwright install chromium tarrafa doctor ``` 直接从 release 安装： ``` python -m pip install \ https://github.com/Mosimann-adv/tarrafa_scraper/releases/download/v0.4.0/tarrafa_scraper-0.4.0-py3-none-any.whl python -m playwright install chromium tarrafa doctor ``` 可选附加项： ``` python -m pip install ".[av]" # yt-dlp (download de vídeo) python -m pip install ".[site]" # scrapy (opcional; site usa BFS httpx por padrão) # ffmpeg no PATH → frames a partir do arquivo baixado ``` ### 开发 ``` python -m pip install -e ".[dev]" python -m playwright install chromium ruff check src tests pytest -q -m "not integration" pytest -q -m integration # rede e Chromium ``` ## 示例 ### 网页 ``` tarrafa page --url https://example.com --out ./out/page.json # batch（每行一个 URL；# 注释 ok） tarrafa page --urls-file ./urls.txt --out ./out/pages/ --mode http ``` 除了文章正文，还会收集 **meta/OG**、**JSON-LD** 和内嵌计数器（`structured_facts`，`text_main` = 纯正文）。 ### 截图 + 相册 ``` # 主要内容裁剪 tarrafa shot --url https://example.com --out-dir ./out/shots --id EX01 --clip main --dpr 2 # batch tarrafa shot --urls-file ./urls.txt --out-dir ./out/shots --clip main --dpr 1 # 整页 tarrafa shot --url https://example.com --out-dir ./out/shots --id EX01b --clip page --full-page # CSS selector tarrafa shot --url https://example.com --out-dir ./out/shots --id EX01c --selector "article" tarrafa album --dir ./out/shots --out ./out/shots/album.html \ --title "Álbum de capturas" \ --kicker "Inventário visual" \ --meta "Assunto: …" \ --meta "Data: …" ``` 盘点样式的 HTML（A4 页面，打印/PDF 按钮）。 **默认内嵌**（base64） → 生成单个便携的 `.html`。相对路径模式：`--no-embed`。 ### 档案卡 / 卷宗 基于**已抓取**的 facts 和文件渲染总览（不会去网上抓取）。 ``` tarrafa dossier \ --title "Nome Completo" \ --subtitle "Âncora · cidade" \ --out ./perfil/ficha.html \ --avatar ./perfil/foto.png \ --meta "Nome: …" --meta "Cidade: …" \ --fact "Achado factual (fonte citada)" \ --source "Fonte | https://… | nota" \ --timeline "2022 | Vínculo em …" \ --shot "print1=./shots/print.png::Legenda" \ --gap "O que não foi validado" \ --chip "âncora curta" ``` - **`--fact` / `--source` / `--timeline`**：内容和来源清单；截图为可选且经过精选。 - **`--manifest dossier.json`**：丰富多样的版块（`sections[]`、cards、表格）。 ### CNPJ / DJEN / Datajud / PDF ``` tarrafa cnpj --cnpj 00.000.000/0001-91 --out ./out/cnpj.json # Advogado: 按州 OAB 查询日报 tarrafa djen --oab 12345 --uf SP --max-items 100 --out ./out/djen.json # Parte: 在正文中搜索（姓名和/或 handle） tarrafa djen --papel parte --texto "Nome Completo" --max-items 50 --out ./out/djen_parte.json # Parte + Datajud 链式调用（找到的 CNJs） tarrafa djen --papel parte --texto "Nome Completo" --follow-datajud \ --datajud-out ./out/datajud.json --max-cnj 15 --out ./out/djen.json tarrafa datajud --cnj 0000000-00.0000.0.00.0000 --out ./out/datajud.json # 可选：--tribunal trf4 | env DATAJUD_API_KEY tarrafa pdf-extract --dir ./out/pdfs --recursive --out ./out/pdf_extract.json ``` - **cnpj：** 开放的 CNPJá，无需 API key；不支持按合伙人姓名搜索。 - **djen advogado：** 抽样 + OAB 后置过滤。 - **djen parte：** 在内容中搜索 `--texto`；summary 中包含 `identity_hints`；切勿仅凭短名将同名者合并。 - **datajud：** 典型的索引**不包含**当事人信息 —— 请使用已知的 CNJs。 - **pdf-extract：** 提取内嵌文本（使用 pypdf）；纯图像 PDF 需要外部 OCR。 - **个人档案（编排）：** `docs/PROFILE_PIPELINE.md` —— djen parte、案件卷宗、IG 截图、同名者/CPF、V1 HTML 与司法附件的对比。 ### 视频 ``` tarrafa video --url https://example.com/video --out-dir ./out/vid --id VID01 --frames 5 tarrafa video --url "URL" --out-dir ./out/vid --id VID01 --download --frames 5 tarrafa album --dir ./out/vid --out ./out/vid/album.html --title "Frames de vídeo" ``` ### 网站 / feed / Instagram ``` tarrafa site --url https://example.com --out ./out/site.json --max-pages 15 --max-depth 2 tarrafa feed --url https://example.com/feed.xml --out ./out/feed.json --max-entries 20 # IG: 原生登录一次（绝不要使用 Facebook OIDC / 自动化密码） tarrafa ig --url https://www.instagram.com/accounts/login/ --headed --max-comments 0 \ --save-storage ./storage_state.json --out ./_login_dummy.json tarrafa ig --url https://www.instagram.com/p/SHORTCODE/ --out ./comments.json \ --storage-state ./storage_state.json --expand-replies --headed ``` ## 通用 envelope 字段：`tool`、`version`、`collected_at`、`source`、`meta`、`count`、`items[]`、`errors[]`、`notes[]`。 Shot/video 会将媒体文件保存在 `--out-dir` 中，并在 JSON 中记录 `sha256`。 ## AI Agents **`AGENTS.md`** 中的契约：优先使用 CLI；不要输入密码；输出至用户指定的目录；仅限材料处理（仅抓取，不作分类）。 ## 结构 ``` tarrafa_scraper/ src/tarrafa/ cli.py core/ # envelope, writers, http, extract, crawl, media, doctor templates/ # HTML album / dossier tools/ # ig, page, site, feed, shot, video, album, … tests/ docs/ ``` ## 配置与安全 - `storage_state.json` 和 `.env` 已包含在 `.gitignore` 中 —— 请勿提交。 - 启动时加载 env（不会覆盖进程中已存在的变量）： 1. `~/.tarrafa/.env` (用户全局) 2. `/.env` (项目) - Playwright MCP 扩展的可选 Token： ``` PLAYWRIGHT_MCP_EXTENSION_TOKEN=seu_token_aqui ``` 模板：`.env.example`。使用 `tarrafa doctor` 进行检查（显示掩码状态）。 仅限合法用途与证据保全；请遵守服务条款（ToS）及当地法律。Tarrafa **不**提供法律服务，也**不能**替代人工的法律分析。 另请参阅 **[SECURITY.md](SECURITY.md)**（在 issues 中不应泄露的信息；tokens；漏洞报告）。 ## 许可证 基于 **[PolyForm Noncommercial License 1.0.0](LICENSE)** 分发。 由于该许可证限制了商业用途，因此 Tarrafa 是**源码可见（source-available）**的软件，而不是 OSI 意义上的开源软件。该包的 SPDX 表达式为 `PolyForm-Noncommercial-1.0.0`。 简要说明（不替代完整文本）： | | | |--|--| | **允许** | 出于**非商业**目的使用、学习、修改和重新分发，并保留许可证声明 | | **必须** | 保留 **署名** / `Required Notice` 以及随附的许可证 | | **禁止** | **商业**用途（包括未经单独授权的软件付费运营） | | **担保** | 无 —— 软件“现状”（as is），实验性质 | 在经济活动/事务所中将其作为产品或服务使用，在本许可证下通常被视为**商业**用途。如需商业许可证或特定授权，请联系维护者。 这**并不**代表 Tarrafa 变成了受支持的产品：即使获得许可，本代码仍处于实验阶段。 ## 支持项目 如果 Tarrafa 在你的工作流（学习、研究、非商业原型设计）中有所帮助，欢迎通过 **Pix** 进行自愿捐款以支持项目的维护。 | | | |--|--| | Pix Key | `mosimannadv@gmail.com` | | 类型 | 电子邮件 |  纯属自愿捐款；**不**包含任何法律服务对价。

标签：Python, 命令控制, 安全规则引擎, 数字取证, 数据采集, 无后门, 法律科技, 特征检测, 自动化脚本, 逆向工具