TimSimpsonJr/magpie

# Magpie      Magpie 是一个 Claude Code 插件，用于处理记录到达后进行的调查环节。你只需将 FOIA 披露的文件或数据转储（如电子表格、审计日志、一堆 PDF）交给它，它就能帮你把这堆数据转化为站得住脚的调查结果：进行统计，将引用精确溯源到具体页面，排查不应被公开的 PII（个人身份信息），并作为相互关联的笔记归档保存。就像它名字来源的喜鹊一样，它把散落的闪光物品收集到一个你可以真正开展工作的巢穴中。 每一个作为标题的数字在成为正式发现之前都要经过核查，任何降级的分析都不会被冒充为事实。你的记录永远不会离开你的机器：分析在本地你自己的 Claude Code 会话中运行，而那些接触敏感资料的工具（PII 排查、脱敏检查）的作用就是确保名字不会出现在你发布的任何内容中。 ## 工作原理 **FOIA 披露或数据转储** → `archive-evidence`（哈希、RFC 3161 时间戳、保管日志） → 针对电子表格运行 `dataset-analyze`，或针对文档运行 `ingest` → `analysis-recipe` / `pii-sweep` / `redaction-check` / `investigate` → `redact-output` → **Librarian** 将关联的调查结果笔记归档。 *可选的第 2 层（操作员层级）：* `entity-extract` → `entity-graph` → `entity-crossref` 用于网络分析。 ## 你可以用它做什么 - **在文件到达的瞬间记录其来源。** `archive-evidence` 在收到文件时对其进行哈希处理，获取一个 RFC 3161 可信时间戳以证明该哈希在特定时间点存在，并在对任何字节进行操作之前，编写一个只能追加、哈希链式的保管日志。你可以让它“为此证据添加时间戳”或“记录这份 FOIA 回执的监管链”。 - **将杂乱的电子表格转化为可查询的数据。** `dataset-analyze` 会加载混乱的 CSV/XLSX 文件（进行编码嗅探，保留带前导零的 ID），检查那些在分析前就可能毁掉报道的静默截断问题，推导出调查所需的列，并将结果公开供只读 SQL 查询。你可以让它“分析这个 FOIA 数据集”或“检查此导出文件是否存在截断”。 - **对每个来源运行相同的调查清单。** `analysis-recipe` 对单一来源执行固定的 13 点检查（跨州访问、移民关键词、借口拦截、超级用户、同行者、集中度统计等），然后跨来源汇总结果，以测试是否存在同一行为者反复出现的情况。你可以让它“运行 13 点清单”或“跨这些机构汇总调查结果”。 - **量化记录暴露的 PII。** `pii-sweep` 在自由文本字段上运行 spaCy 姓名检测以及结构化标识符匹配，按行数加权，并将为了问责而指出的官员姓名与本应被脱敏的第三方 PII 区分开来。你可以让它“在这个原因列中排查 PII 暴露情况”。 - **在你发布之前，抓住你和他们那些糟糕的脱敏处理。** `redaction-check` 扫描 PDF，查找黑框下仍可提取的文本、泄露的元数据、未应用的脱敏注释以及嵌入的文件，并将每一项作为线索报告给人类处理。你可以让它“检查这个 PDF 是否有错误的脱敏”或“这个 FOIA 回复是否在黑框下泄露了文本”。 - **提取可溯源到页面的声明。** `ingest` 转换 PDF 的同时保留页面和边界框来源信息，而 `investigate` 将其转换为锚定在精确引用上的声明，通过两种独立方式进行复核，并在任何内容发布前将其置于强制的人工审核关卡。你可以让它“从这份文档中提取带引用的调查结果”。 - **在发布前对相关人员进行脱敏。** `redact-output` 将无关的第三方姓名掩码为首字母缩写，将结构化 PII 掩码为类型化占位符，同时保留官员和调查员指定的对象姓名，并将完整的未脱敏展示文件写入到本地的非库路径中。你可以让它“在此调查结果笔记进入库之前对其进行脱敏”。 - **映射网络（可选，第 2 层）。** `entity-extract`、`entity-graph` 和 `entity-crossref` 从文档中提取人员、组织及其关系，在人工审核关卡后解析整个语料库中谁是谁，并根据你自己的语料库或自愿加入的监视名单对他们进行筛查。你可以让它“从这些文档中构建实体图”。 所有这些操作的结果都会通过 **Librarian** 进行归档，因此调查结果会作为相互关联的 Markdown 笔记存入你的库中，而不是散乱的草稿文件。 ## 为什么它很有用 调查往往在悄无声息且代价高昂的失误中失败：被静默截断到一百万行的电子表格、因为包含“ice”而标记了“police”的关键词过滤器、留在已发布笔记中本绝不该出现的名字、以及一个后来发现根本不在文件中的笃定声明。Magpie 的构建初衷就是默认拒绝所有这些失败。遇到被截断的导出文件它会停止分析，而不是去分析残缺的片段。关键词在单词边界上进行匹配，因此“police”绝不会因为包含“ice”而被标记。脱敏标记被计为“存在但被保留”，绝不计为一个具体值。并且声明不能在缺乏支撑的文本段落上发布。 另一半则是你希望严谨的同事能强制执行的那种纪律。在人类签字确认之前，调查结果都只是线索。在展示 AI 的声明之前会先展示证据，让你优先判断来源的可靠性。降级的引用会被大声警告，而不是被轻易放行。而且由于繁重的机器学习组件是可选的，只有在需要时才安装，因此日常工作保持轻量，可以在一台没有任何复杂配置的笔记本电脑上运行。 ## 快速开始 从 Fieldwork 市场安装它： ``` /plugin marketplace add TimSimpsonJr/fieldwork-plugins /plugin install magpie@fieldwork ``` Magpie 有两个入口，分别针对接触它的不同人员。如果你是负责设置机器的**操作员**，请运行一次 setup 来安装依赖项并下载模型： ``` /setup ``` 如果你是日常使用它的**调查员**，请先检查哪些功能已准备就绪（这是严格的只读操作，不会进行任何安装）： ``` /doctor ``` 然后将其指向一条记录并开始工作。对于数据集： ``` Analyze this FOIA dataset: ./exports/audit-log.csv ``` 对于文档： ``` Archive this PDF as evidence, then ingest it: ./releases/response.pdf ``` `doctor` 会告诉你目前哪些工作流已准备就绪，对于任何缺失的内容，还会提示你需要让操作员安装的下一个具体步骤。在底层，它运行 `detect_tier` 来评估你的机器能做什么。 两份指南提供了更深入的信息：操作员请参考 [OPERATOR_GUIDE.md](docs/OPERATOR_GUIDE.md)，记者请参考 [JOURNALIST_START.md](docs/JOURNALIST_START.md)。 ## 底层机制 Magpie 分层运行，大多数记者从不离开第一层。 **第 0–1 层（笔记本电脑本地环境，旗舰核心）。** 纯本地 Python：pandas、DuckDB 和 `sqlite-utils`，清理后的数据集通过固定的 `mcp-sqlite` 服务器以只读方式提供，以便分析代理可以使用 SQL 查询它，但绝不能写入数据。较重的组件（用于 PII 排查的 spaCy，用于 PDF 提取的 Docling，用于脱敏检查的 Free Law `x-ray`）仅限 CPU 运行并位于边缘位置，仅在运行该特定工作流时才导入。没有容器，也没有需要管理的基础设施。 **第 2 层（实体网络，操作员层级）。** 可选的网络分析轨道：`entity-extract`（GLiNER + GLiREL）、`entity-graph`（在强制的人工审核关卡之后，将跨文档解析集成到 Neo4j 中），以及 `entity-crossref`（通过本地 yente + OpenSearch 堆栈，根据你自己的语料库或自愿加入的制裁/政治公众人物监视名单进行筛查）。这部分绝不会影响记者入口，记者入口将始终保持无容器化。 能力图表（运行 `doctor` 查看你的配置）： | 工作流 | 需求 | 层级 | |----------|---------------|------| | 分析数据集 | pandas / DuckDB / 用于查询界面的 `uvx` | 第 0–1 层 | | PII 排查 | spaCy + `en_core_web_lg` | 第 0–1 层 | | 提取 PDF | Docling + RapidOCR（仅 Tesseract/Ghostscript 用于扫描预处理） | 第 0–1 层 | | 脱敏 QA | Free Law `x-ray` / pikepdf / pdfminer | 第 0–1 层 | | 引用验证 | 纯标准库（引用引擎） | 第 0–1 层 | | 证据时间戳 | `rfc3161-client` + TSA（默认为 freeTSA） | 第 0–1 层 | | 提取实体 | GLiNER + GLiREL（首次运行时下载权重） | 第 2 层依赖 | | 构建实体图 | Neo4j（由操作员运行） | 第 2 层 | | 交叉引用实体 | yente + OpenSearch（由操作员运行） | 第 2 层 | 贯穿所有的两条设计原则。**是线索，而非定论：** 无法运行的检查绝不会证明其检查的内容不存在，缺失的必填列会产生一个被记录的“已跳过”，绝不会产生伪造的零。**本地与已发布：** 原始 PII、恢复的黑框下文本以及验证器推理仅存在于本地文件中；已发布的笔记仅包含汇总计数和非原始锚点。完整的目录树结构及各部分耦合方式详见 [MANIFEST.md](MANIFEST.md)。 ## 面向开发者 开发环境由 [mise](https://mise.jdx.dev) 管理，它固定了 Python 3.12.10 版本并绑定了项目的 virtualenv。 ``` mise run bootstrap # install pinned deps into .venv mise run test # run the full pytest suite ``` 测试套件默认处于离线状态（无 API 密钥，无网络）：繁重的集成测试通过标记进行控制（`spacy`、`docling`、`xray`、`tsa`、`gliner`、`ftm`、`neo4j`、`compose`、`yente`）并从默认运行中排除，同时 Track B 容器/Linux 路径已在 CI 中验证。依赖项被拆分在 `requirements-dev.txt`（完整）、`requirements-offline.txt`（精简的 CI 子集）以及第 2 层边缘模块（`requirements-ftm.txt`、`requirements-graph.txt`、`requirements-crossref.txt`）中。 ## Fieldwork 套件的一部分 - [Researcher](https://github.com/TimSimpsonJr/researcher)：将来源收集为带引用的笔记 - [Magpie](https://github.com/TimSimpsonJr/magpie)：分析 FOIA/数据以得出调查结果 - [Librarian](https://github.com/TimSimpsonJr/librarian)：将调查结果整理为相互关联的库笔记（共享层） - [Copydesk](https://github.com/TimSimpsonJr/copydesk)：用你的语气撰写调查报告 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。默认的工具栈基于宽松许可证授权；Copyleft 或非免费的工具（PyMuPDF、GLiREL 权重、Neo4j 社区版镜像、CC-BY-NC 监视名单）仅作为明确标记的自愿加入配置文件提供。

标签：Claude Code 插件, Python, 代码示例, 信息审计, 安全规则引擎, 数据分析, 数据脱敏, 无后门, 网络安全, 证据保全, 隐私保护