mrinaalr/CaseLinker
GitHub: mrinaalr/CaseLinker
一个针对儿童危害犯罪（CSEA）案件的开源数据聚合、特征提取与可视化分析系统，旨在解决跨案件数据分散和模式识别困难的问题。
Stars: 3 | Forks: 0
# CaseLinker
**CaseLinker** 是一个旨在对涉及危害儿童犯罪以及儿童性剥削与性虐待（CSEA）案件中的**统计**和**上下文**信息进行分组和可视化的项目。
## 在线演示
**在线体验最新版本：** [https://caselinker.up.railway.app/](https://caselinker.up.railway.app/)
在线发布版本包含所有功能，以及来自公开 ICAC / NCMEC / DOJ / 各州总检察长新闻资料的已处理案件语料库。该语料库涵盖了来自 **56** 个数据接入源的 **7,426** 起案件。实时数据统计和各数据源的覆盖率可在应用内的 **Sources**（数据源）页面查看。这些报告概述了调查、逮捕和起诉情况，并对公众发布的内容进行了脱敏处理。本项目未处理任何 PII（个人身份信息）；所有数据均已在公开领域。无需安装——只需在浏览器中打开链接即可。
## 技术报告
- **报告 #1：[CaseLinker：一个针对网络危害儿童报告的跨案件分析开源系统](https://arxiv.org/abs/2603.18020)** - 初始技术报告，记录了原型架构、确定性提取流水线以及 47 起案件的评估基准。
- **报告 #2：[分析网络危害儿童报告的可解释 ML 方法](https://mrinaalr.github.io/website/CaseLinker-%20Interpretable%20ML%20Approaches%20for%20Analyzing%20Internet%20Crimes%20Against%20Children%20Reports.pdf)** - 第二份报告，涵盖了 NER 整合、数据集扩展至 207 起案件，以及从扩展数据集中得出的新趋势，包括由 215 个执法机构组成的分布式网络。
- **报告 #3：[5 个数据源、500 起案件及扩展性考量](https://mrinaalr.github.io/website/Scaling.pdf)** - 第三份报告，涵盖了新增 3 个数据源、facet-tree 搜索以及数据效用。
- **报告 #4：[美国各特遣部队针对网络危害儿童犯罪的回顾性分析与案例研究框架](https://mrinaalr.github.io/website/Framework.pdf)** - 第四份报告，建立了一套可复制且可扩展的案例研究方法论：四阶段框架（2010-2026）、跨阶段分层抽样、五维度案例研究结构，以及该分析的法律和伦理基础。
- **报告 #5：[使用解释性工具描绘网络危害儿童犯罪的态势](https://mrinaalr.github.io/website/PaintingTheLandscapeOfInternetCrimesAgainstChildrenWithInterpretiveTooling.html)** - 第五份也是最后一份报告：一份长达十页的简报，以可视化方式展示了长达十六年的美国 ICAC 执法情况，介绍了提取与分析框架、跨越四个阶段的 20 个案例研究，以及涵盖 5,000 多起案件的综合发现。
## 动机
本项目的动机源于我在理解儿童剥削案件时遇到的一些挑战，包括：
- **碎片化的数据源**：案件散布在众多组织、州和机构中
- **跨案件分析**：如果没有统一的系统，即使案件在滥用模式、平台或犯罪者人口统计等方面具有共同特征，要识别它们之间的模式、相似之处和联系也变得极具挑战性
- **趋势分析的局限性**：分析儿童剥削行为的演变、其发生的媒介以及反复出现的案件主题
- **情感影响**：反复阅读和处理极度令人不安的案件材料所带来的挑战
CaseLinker 旨在通过作为案件分析工具来解决这些挑战，使研究人员、执法部门和维权组织能够更好地了解儿童剥削的全貌。
## 重点
- **特征提取**：从案件中稳健地提取信息，并为聚类和分析提供可解释性
- **聚类与链接**：基于共同特征（如受害者背景、使用的平台和执法行动）对案件进行关联
- **可视化**：特别注重案件内容的得体展示，以及跨调查的模式分析
## 系统架构
CaseLinker 遵循模块化、分层式的架构：
1. **接入层**：处理 PDF 数据源，包括文本提取和验证
2. **处理层**：提取特征、分配比较值并填充案件 schema
3. **存储层**：PostgreSQL（生产环境）/ SQLite（本地开发环境）- 实现与具体数据库无关
4. **聚类与分析层**：案件比对、相似度检测、自动分组、分诊以及生成洞察
5. **可视化层**：交互式 Web 仪表板（平台危害仪表板、生命周期状态机、facet 树搜索、分析视图）
## 安装说明
### 选项 1：使用在线演示（推荐用于快速测试）
**无需安装。** 访问在线部署版本：
- **在线应用**：[https://caselinker.up.railway.app](https://caselinker.up.railway.app)
在线版本包含所有功能以及一个已处理的案件语料库，专为快速测试和演示而创建。
### 选项 2：本地设置（即装即用）
```
# Clone 仓库
git clone https://github.com/mrinaalr/CaseLinker.git
cd CaseLinker
# 运行 setup 脚本（创建 venv 并安装依赖）
./setup.sh
# 激活虚拟环境
source .venv/bin/activate
# 启动主应用程序
python3 run/main.py
```
然后在浏览器中打开：
- **主页**：http://localhost:8000/
- **可视化**：http://localhost:8000/visualization
- **高级分析**：http://localhost:8000/analysis
- **集群**：http://localhost:8000/clusters
- **统计**：http://localhost:8000/stats
- **搜索**：http://localhost:8000/search
- **查询**：http://localhost:8000/query
- **生命周期**：http://localhost:8000/lifecycle
- **分诊**：http://localhost:8000/triage
- **模式 (Phase 2)**：http://localhost:8000/patterns
- **技术全景**：http://localhost:8000/tech-landscape
- **LLM**：http://localhost:8000/llm
- **数据源**：http://localhost:8000/sources
- **数据审计**：http://localhost:8000/audit
- **查看内部原理**：http://localhost:8000/under-the-hood
- **案例研究**：http://localhost:8000/case-studies
- **API 文档**：http://localhost:8000/docs
**数据库：**
- **生产环境**：PostgreSQL，配备加密连接和托管备份
- **本地开发**：SQLite (`caselinker.db`) - 在
本地运行时自动创建，初始状态为空
**全新克隆包含的内容**（适用于空数据库）：
| 包含内容 | 路径 | 本地使用 |
|-------|------|-----------|
| 本体案例图谱（各池中约 2k+ 个案例） | `ontology/graph_output/` | `/patterns/graph`, `/api/ontology/*` |
| PACER 生命周期状态机（30 个案例） | `state_machines/graphs/`, `ontology/PACER/` | `/lifecycle` |
| L* 轨迹 / 转移矩阵 | `state_machines/data/lstar_all_cases.json` | `/api/lifecycle/lstar` |
| 案例研究（跨越 4 个阶段的 21 个案例） | `data/case_studies.json` | `/case-studies` |
| 分诊模型包 | `models/triage_bundle.joblib` | `/triage`, `/api/triage-live` |
**重现本地语料库数据库**（两种选项）：
1. **受信任的 API 导出**（一次性获取完整的生产级语料库）— 请通过 **mramachandra@umass.edu** 申请 `CaseLinker-Key`，然后：
```
source .venv/bin/activate
export CASELINKER_KEY='your-trusted-key'
python3 scripts/run/import_corpus_from_api.py
python3 run/main.py
```
2. **PDF 导入**（根据您收集的公开数据构建；请参阅下方的 **处理您自己的 PDF 文件**）：
```
source .venv/bin/activate
python3 src/main.py "path/to/your/file.pdf"
# 或者，在将多个 PDF 放入仓库根目录后：
./scripts/run/ingest_all_pdfs.sh
python3 run/main.py
```
您可以处理额外的 PDF 文件，从而向数据库中添加更多案例。
## 使用说明
### ⚠️ 重要提示：数据内容与警告
**CaseLinker 处理公开可用的案件报告及相关记录，仅用于研究、分析和调查工作流程目的。**
**虽然所有源材料均取自公开报告，但其内容涉及对儿童剥削、虐待或其他令人不安的刑事案件细节的描述，阅读起来可能令人不适。**
**请在了解材料敏感性质的前提下继续操作，并负责任地将本项目用于研究、学术或授权的分析目的。**
## 入口点
1. **`src/main.py`** - **用于处理 PDF 的 CLI 工具**
- 处理 PDF 文件以提取案件并将其存储在数据库中
- 当您想从 PDF 文件中添加新案件时运行此工具
- 提取文本、识别数据源、拆分案件、提取特征并进行存储
- 在存储新案件后预计算集群
2. **`run/main.py`** - **主应用程序**
- 启动 Web 服务器，提供可视化界面和 API 服务
- 运行此程序以访问 Web 界面和可视化功能
- 在启动时使用预计算的集群，以实现出色的性能
- 为案件数据、分析和统计信息提供 REST API 端点
3. **`caselinker_mcp/server.py`** — **用于 agent 和 LLM 分析的 MCP server**
- 暴露了 **37 个工具**：语料库搜索、分诊、Q1 平台证据、按需生成的 `case2cac` 队列图谱、Turtle 导出 (`export_case_graph_ttl`) 以及图遍历
- 只读模式；封装现有的 REST API；不改变数据库状态
- 如需私有的 mcp.json 密钥，请联系项目负责人，并查看 `caselinker_mcp/README.md` 和 `caselinker_mcp/tool_registry.md` 以获取设置、授权及完整的工具目录信息
**典型用例：**
1. 首先，使用处理后的 PDF 填充数据库或申请受信任的 API key
2. 然后，使用 `run/main.py` 启动 Web 服务器以查看和分析案件
3. 可选：通过 **stdio**、**SSE** 或 **Streamable HTTP** 连接 MCP 客户端（Cursor、Claude Desktop 或任何兼容 MCP 的宿主程序）
## 处理您自己的 PDF 文件
**本地数据库初始状态为空。** 要将案件填充到其中，您需要处理想要导入的 PDF 文件。
### 查找 PDF 来源
访问 **Sources** 页面以查看用于收集数据源的链接：
- **在线演示数据源页面**：[https://caselinker.up.railway.app/sources](https://caselinker.up.railway.app/sources)
- 或者在本地运行时访问 `/sources`：http://localhost:8000/sources
已处理的数据源包括：
- **Arizona ICAC (AZICAC)**：年度案件报告和逮捕情况 (AZICAC)
- **National Center for Missing & Exploited Children (NCMEC)**：案件
摘要和与 CyberTipline 相关的出版物
- **Georgia Bureau of Investigation (GBI)**：CEACC / 佐治亚州 ICAC 新闻稿
- **Idaho Office of Attorney General (Idaho ICAC)**：ICAC 新闻室发布的新闻稿
- **Texas Office of the Attorney General (Texas AG)**：网络犯罪 / ICAC 相关新闻稿
- **Michigan State Police (Michigan ICAC)**：MSP 新闻室发布的 ICAC 消息
- **Silicon Valley ICAC (SVICAC)**：地区性的“In The News”新闻文章
- **Tennessee Bureau of Investigation (TBI ICAC)**：TBI 新闻室 ICAC 搜索结果
- **South Carolina Attorney General (SCAG ICAC)**：带有 ICAC 标签的新闻稿
- **New York State Police (NEWYORK SP)**：NYSP 新闻室 ICAC 关键字搜索
- **Illinois Attorney General (ILLINOIS AG)**：ICAC 新闻稿搜索
- **Pennsylvania Office of the Attorney General (PA AG)**：Child Predator / ICAC 相关发布
- **New Jersey Office of the Attorney General (NJ AG)**：ICAC 站内搜索
- **Washoe County Sheriff's Office (WCSO)**：内华达州 ICAC 新闻室搜索
- **Fresno County Sheriff's Office (FRESNO SO)**：ICAC 站内搜索
- **Osceola County Sheriff's Office (OSCEOLA SO)**：ICAC 站内搜索
- **Las Vegas Metropolitan Police Department (LVMPD)**：ICAC 站内搜索
- **San Jose Police Department (SJPD)**：ICAC / 儿童剥削新闻搜索
- **Los Angeles Police Department (LAPD)**：ICAC 新闻搜索
- **Seattle Police Department (SPD)**：SPD Blotter ICAC 搜索
- **San Diego Police Department (SDPD)**：圣地亚哥市 ICAC 站内搜索
- **Colorado Springs Police Department (CSPD)**：ICAC 站内搜索
- **Hawaii Department of the Attorney General (HI AG)**：HICAC 媒体与新闻
- **Cook County State's Attorney (CCSAO)**：ICAC 单元新闻发布
- **South Florida ICAC (SOUTH FLORIDA ICAC)**：地区特遣部队新闻索引
- **Florida Office of the Attorney General (FL AG)**：ICAC 站内搜索
- **Vermont Office of the Attorney General (VT AG)**：与儿童相关 / ICAC 发布
- **Rhode Island Office of the Attorney General (RI AG)**：ICAC 站内搜索
- **Ohio Attorney General (OHIO AG)**：ICAC / 与儿童相关的新闻搜索
- **Delaware Department of Justice (DE AG)**：Child Predator Task Force / ICAC 发布
- **Sedgwick County Sheriff's Office (SEDGW SO)**：儿童剥削新闻搜索
- **Anchorage Police Department (ANCHORAGE PD)**：阿拉斯加 ICAC 相关发布
- **Mississippi Attorney General (MS AG)**：ICAC 媒体发布
- **Montana Department of Justice (MT DOJ)**：与儿童相关的新闻稿
- **New Mexico Attorney General's Office (NM AG)**：ICAC 站内搜索
- **North Carolina State Bureau of Investigation (NC SBI)**：ICAC 新闻搜索
- **Louisiana Office of the Attorney General (LA AG)**：ICAC 新闻稿
- **Utah Attorney General (UT AG)**：ICAC 站内搜索
- **Washington State Office of the Attorney General (WA AG)**：与儿童相关的新闻搜索
- **Oregon Department of Justice (OREGON DOJ)**：ICAC 站内搜索
- **Wyoming Division of Criminal Investigation (WY DCI)**：ICAC / 计算机犯罪新闻
- **Iowa Division of Criminal Investigation (IA DCI)**：ICAC 站内搜索
- **Arkansas Department of Public Safety (ARKANSAS DPS)**：ICAC / ASP 新闻搜索
- **Alabama Law Enforcement Agency (ALEA)**：SBI / ICAC 新闻搜索
- **South Dakota Office of the Attorney General (SD AG)**：ICAC 新闻稿
- **Kentucky State Police (KY SP)**：新闻档案 ICAC 搜索
- **Nebraska State Patrol (NE SP)**：儿童剥削新闻搜索
- **U.S. Army Criminal Investigation Division (ARMY CID)**：ICAC 相关发布
- **U.S. Air Force Office of Special Investigations (AF OSI)**：儿童性虐待材料和剥削相关新闻稿
- **U.S. Customs and Border Protection (CBP)**：关于儿童性剥削及相关边境执法的新闻室发布（站内搜索）
- **U.S. Immigration and Customs Enforcement (ICE)**：HSI 儿童剥削新闻稿
- **Naval Criminal Investigative Service (NCIS)**：儿童剥削及相关调查的新闻稿
- **U.S. DOJ CEOS (DOJ CEOS)**：儿童剥削与淫秽部门新闻稿
- **U.S. DOJ CEOS Archives (DOJ ARCHIVES)**：存档的 CEOS 刑事案件新闻稿 (2002-2008)
- **U.S. Secret Service (USSS)**：与 ICAC 相关的新闻室新闻稿（ICAC 特遣部队、CSAM 及儿童剥削搜索结果）
- **U.S. Marshals Service (US MARSHALS)**：关于侵害儿童的罪犯、性侵逃犯以及被解救未成年人的新闻稿
### 通过处理 PDF 填充数据库
获取 PDF 文件后，请使用 CLI 工具进行处理：
**单个 PDF：**
```
source .venv/bin/activate
python3 src/main.py "path/to/your/file.pdf"
```
**多个 PDF：**
```
python3 src/main.py "2011 Cases and Arrests – AZICAC.ORG.pdf" "2020 Reports" "2024-media-coverage-cybertipline-success-stories.pdf"
```
**代码库下的所有 PDF**（例如在清空数据库后）：
```
./scripts/run/ingest_all_pdfs.sh
# 如果你想要优先获取 state feeds，则在第一次扫描时跳过 NCMEC/DOJ：
./scripts/run/ingest_all_pdfs.sh --no-aggregate
```
系统将会：
1. 从每个 PDF 中提取文本
2. 通过文件名识别组织名称（如 AZICAC、NCMEC 等）
3. 批量处理案件、提取特征、分配案件 ID
4. 将所有案件存储在本地 SQLite 数据库中
5. 预计算集群以实现快速可视化
## 使用可视化功能
通过[在线演示](https://caselinker.up.railway.app/visualization)或在本地访问 http://localhost:8000/visualization 即可使用**平台危害仪表板**。
**仪表板功能**：
- **生命周期图谱**：将平台分布在六条剥削通道上（分发、存储、社区、发现、消息传递、制作）
- **详情面板**：针对每个平台的分析，包含四个标签页：
- **Affordances（可供性）** → 媒介赋予了什么能力
- **Misuse Surface（滥用面）** → 犯罪分子是如何滥用这些特性的
- **Harm Vectors（危害向量）** → 针对受害者的伤害路径
- **Case Evidence（案件证据）** → 来自 `q1_evidence.json` 的可展开引用；提供链接至 Audit 页面以查看完整的案件审查
- **过滤器**：按平台名称搜索；按证据级别缩小范围
## 使用搜索功能
通过[在线演示](https://caselinker.up.railway.app/search)或在本地访问 http://localhost:8000/search 即可使用搜索功能。
搜索功能在已存储的案件语料库之上提供了一个 **facet 决策树**：服务器根据结构化的 facet 构建确定性的分区树（而不是磁盘上的预计算文件）。该视图使用 **D3.js** (SVG) 来渲染群组节点和边。您可以限制树的深度、**修剪**应用哪些分区维度，并可选择过滤每个 facet（提取的特征）允许的值，然后**点击任何节点**（分支或叶子）以列出该群组中的**案件 ID**，供其他地方使用（例如：单案件可视化、人工跨案件分析）。小规模群组（少于三起案件）的 ID 需通过演示访问密钥解锁。有关分区的顺序和语义，请参见 `src/Storage Layer/facet_tree.py` 和 `/api/facet-tree`。
## 使用高级案件分析与分诊功能
导航至[在线演示](https://caselinker.up.railway.app/analysis)或在本地运行服务器并导航至 http://localhost:8000/analysis。
1. **基于标签的分析（运行高级分析）**：
- 从以下类别中选择一个或多个标签：案件主题、严重程度指标、平台与环境、调查类型、犯罪者关系、犯罪者状态
- 点击“Run Advanced Analysis”（运行高级分析）以查找匹配所有选中标签的案件（交集逻辑）
- 查看匹配的案件，文本中会高亮显示在原始案件数据中发现标签的位置
- 查看每个选中标签的案件计数
2. **自动化分析（运行自动化分析）**：
- 点击“Run Automated Analysis”（运行自动化分析）以运行完整的自动化分析流水线
- **案件分组**：查看按相似度（平台、人口统计、主题、严重程度、调查）分组的案件
- **最高优先级案件**：查看按优先级评分（标准化为 5-10 分制）排序的案件，评分基于：
- 严重程度指标 (35%)：婴儿、强奸、极其年幼、身体虐待
- 受害者人数 (30%)：多名受害者得分更高
- 案件类型 (25%)：制作、动手实施、持有、仅限线上
- 严重性短语 (15%)：危险的、声称的、告诉的、持续的、攻击的、失控的、被吸引的
- 证据数量 (10%)：图像、视频、存储大小
- 登记在册的性犯罪者 (10%)：惯犯状态
- **自动化洞察**：查看有关最常见平台、严重程度分布和案件主题的洞察
- **检测到的模式**：查看诸如惯犯、关系模式和调查重点等模式
- **热门关键字**：查看从案件文本中提取的最常见关键字
- **可展开的详细信息**：点击任意框以查看原始案件数据，其中包含高亮显示的优先级指标以及关于分析为何对该案件优先处理/分组的详细解释
通过[在线演示](https://caselinker.up.railway.app/triage)或在本地访问 http://localhost:8000/triage 即可使用分诊功能。目前的实现使用了**基于规则的**优先级分层、**用于分诊的 ML 分类**（利用数据库中的特征并基于确定性规则得出的标签进行训练的随机森林或决策树），可选择性地受到与搜索中相同的 facet 维度过滤的限制，并支持**粘贴即时分诊**，该功能在内存中对文本进行评分，而无需写入数据库。如需完整的分诊文档（规则、bundle 路径、API、实时粘贴），请查阅代码库根目录下的 **`triage.md`**。
## 阶段 2：模式（[本地](http://localhost:8000/patterns) · [在线](https://caselinker.up.railway.app/patterns)）是语料库跨案件模式分析的一个持续研究阶段。
### A 部分 — 研究问题
有三个问题驱动着阶段 2；每一个都建立在前一个的基础之上。发现页面：[`/patterns/questions/q01`](https://caselinker.up.railway.app/patterns/questions/q01) (Q1), [`q02`](https://caselinker.up.railway.app/patterns/questions/q02) (Q2), [`q03`](https://caselinker.up.railway.app/patterns/questions/q03) (Q3)。
| 问题 | 关注点 | 为什么重要 |
|----------|--------|----------------|
| **Q1 — 平台危害** | 什么是平台？它具有哪些功能？在实践中它是如何被滥用的？它暴露了哪些供人利用的界面、向量和途径？这种媒介中究竟是什么具体因素使其能被用于剥削？这些特性是否能被归纳为一个用于对未来平台进行压力测试的框架？ | 新闻稿和在线危害研究经常提到平台，但很少解释是*媒介的什么特性*促使了犯罪的发生。可供性级别的分析将平台提及和记录在案的犯罪转化为一个可迁移的框架。证据：`ontology/q1/` ([`q1_evidence.json`](ontology/q1/q1_evidence.json)) |
| **Q2 — 剥削生命周期** | 在大规模的不同犯罪子集（如家庭虐待、诱导、性勒索、制作、持有等）中，犯罪和执法情况是怎样的？在每个子集中，哪些平台、方法和模式会反复出现？ | 大多数 ICAC 研究依赖于哈希、总计数或单一案件的叙述。按子集分层的生命周期视图展示了成千上万的案件中犯罪和执法是如何展开的。证据：`ontology/q2/` ([`q2_lifecycle.json`](ontology/q2/q2_lifecycle.json), [`q2_evidence.py`](ontology/q2/q2_evidence.py))。 |
| **Q3 — Kill-chain（阻断链）干预** | 根据 Q1 和 Q2，技术、调查或执法能在哪里以最大的杠杆效应进行干预？ | 平台映射和生命周期分析的存在是为了回答一个操作性问题：在哪里进行阻断最为合理（检测、报告、执行搜查令、预防）。证据：`ontology/q3/` ([`q3_interventions.json`](ontology/q3/q3_interventions.json), [`q3_evidence.py`](ontology/q3/q3_evidence.py))。 |
在本地重建证据表：
```
python3 ontology/q1/build_candidates.py && python3 ontology/q1/q1_evidence.py
python3 ontology/q2/build_candidates.py && python3 ontology/q2/q2_evidence.py
python3 ontology/q3/build_candidates.py && python3 ontology/q3/q3_evidence.py
```
### B 部分 — 方法：本体流水线
为了在语料库规模上回答 Q1–Q3，执法部门的案件叙述不能仅仅停留在关系表和通过 regex 推导出的标签上。它们必须以一种**结构化、支持图查询**的形式表达，以便可以对模式进行跨案件的查询、验证和比较。CaseLinker 已经从每个叙述中提取了一致的特征；**本体流水线**将这些特征映射到标准的调查词汇表中，并构建一个经过验证的知识图谱，作为跨案件分析的机制。
**什么是本体：** [CAC Ontology](https://github.com/Project-VIC-International/CAC-Ontology)（ Crimes Against Children Ontology ，危害儿童犯罪本体）是一个形式化的词汇表，旨在将儿童剥削调查中的实体建模为有类型、有关系的对象：平台、受害者、罪犯、调查和结果。CAC 由 [Project VIC International](https://www.projectvic.org/) 管理，并建立在 Linux 基金会的 [Cyber Domain Ontology](https://cyberdomainontology.org/) 技术栈（[UCO](https://unifiedcyberontology.org/) 和 [CASE](https://caseontology.org/)）之上。CaseLinker 的案件数据正在与该词汇表进行对齐，以便能够使用取证和情报工作流程中相同的工具来共享、验证和查询图谱。
**CaseLinker 如何使用本体：** 一个确定性的映射层将每个案件提取出的特征转化为 CAC 实体和关系，输出每个案件的 RDF 图谱，对其进行验证，然后将符合标准的图谱合并到一个可查询的知识图谱中。
**流水线流程**：
1. **CaseLinker 案件特征** — 已完成提取（平台、主题、调查信号、起诉结果）。
2. **映射层** — 确定性地转化为 CAC 实体和关系 (`ontology/graph_generate.py`)。
3. **RDF 输出** — 每个案件的图谱以 Turtle 和 JSON-LD 格式输出至 `ontology/graph_output/` 目录下。
4. **SHACL 验证** — 只有符合标准的图谱才会进入合并后的语料库。
5. **支持 SPARQL 查询的语料库** — 合并并验证过的图谱成为了 Q1–Q3 分析的基础数据结构。
Agents 还可以通过 MCP 按需构建群组图谱（`case2cac` → `graph_summarize` → `export_case_graph_ttl`）。
**参考资源**
- [CAC Ontology 代码库](https://github.com/Project-VIC-International/CAC-Ontology)
- [带有 CAC 绑定的 CASE/UCO SDK](https://github.com/vulnmaster/CASE-UCO-SDK)
- [CASE](https://github.com/casework/CASE)
- [UCO](https://github.com/ucoProject/UCO)
- [Project VIC International](https://projectvic.org/)
## 其他功能
- **数据源选项卡**：查看数据源并访问原始案件报告
- **集群选项卡**：查看预计算的集群并分析案件报告
- **统计选项卡**：数据集的覆盖范围和案件分布
- **技术全景**：按时代划分的技术轮盘（平台、调查技术、匿名化、P2P）
- **生命周期**：PACER 剥削生命周期。以 CAC 本体状态机展示的五种犯罪类型
- **查询**：自定义分析实验室（公开 API）
- **LLM**：基于案件统计数据的自然语言（SQL 支持；生产环境有速率限制）
- **案例研究选项卡**：按时代组织的叙述性案例研究 (`data/case_studies.json`)
- **审计选项卡**：通过交互式高亮显示逐案审查提取的特征，以验证提取的准确性
## 项目结构
```
CaseLinker/
├── src/
│ ├── Ingestion Layer/ # PDF extraction, source detection, ingest_file
│ ├── Processing Layer/ # batching.py, processing.py, merge_processing.py
│ │ ├── Pattern Processing Layer/ # Regex / rule-based feature extraction
│ │ └── ML Processing Layer/ # NER, semantic concepts, content sanitization
│ ├── Storage Layer/ # SQLite + PostgreSQL storage, facet_tree.py
│ ├── Clustering & Analysis Layer/ # analysis.py, triage.py
│ ├── Visualization Layer/ # Server-side viz helpers
│ └── main.py # CLI: ingest PDFs → process → store
├── run/
│ ├── main.py # FastAPI app: pages + REST API
│ ├── redis_cache.py # Optional Redis caching (production)
│ └── auth.py # Access gates / keys for sensitive views
├── scripts/
│ ├── stats/ # Corpus statistics scripts
│ ├── verify/ # Claims, uniqueness, ICAC TF alignment, triage tests
│ ├── run/ # ingest_all_pdfs.sh, import_corpus_from_api.py, clear_postgres.py, train_triage_model.py
│ └── scraper/ # fetch_source_urls.py, scrape_pdf.py
├── visualization/ # Static HTML (served by run/main.py)
│ ├── assets/ # caselinker-api.js, cover.png
│ ├── home.html # /
│ ├── visualization.html # /visualization
│ ├── search.html # /search (facet tree)
│ ├── analysis.html # /analysis
│ ├── clusters.html # /clusters
│ ├── stats.html # /stats
│ ├── query.html # /query
│ ├── lifecycle.html # /lifecycle
│ ├── triage.html # /triage
│ ├── patterns.html # /patterns
│ ├── patterns-graph.html # /patterns/graph
│ ├── questions/ # /patterns/questions/q01–q03
│ ├── tech-landscape.html # /tech-landscape
│ ├── LLM.html # /llm
│ ├── sources.html # /sources
│ ├── case-studies.html # /case-studies
│ ├── audit.html # /audit
│ └── under-the-hood.html # /under-the-hood
├── ontology/
│ ├── q1/ # Q1 affordance candidates + evidence
│ ├── q2/ # Q2 lifecycle subsets + evidence
│ ├── graph_output/ # staging (new graphs; not in Patterns viz)
│ │ ├── universe/ # full corpus — compare + Universe mode
│ │ └── big_bang/ # half-sample — Big Bang button
│ ├── big_bang.py # ~1k bridge-dense subset for /patterns/graph
│ └── merge_graph_cache.py # merged compare / all pools (API)
├── caselinker_mcp/ # MCP server (37 tools; SSE + Streamable HTTP on Railway)
│ ├── server.py # FastMCP entry point
│ ├── README.md # Hosted auth, Cursor config, graph workflow
│ └── tool_registry.md # Full tool catalog
├── models/ # triage_bundle.joblib (optional; see /triage)
├── data/ # case_studies.json for /case-studies
├── setup.sh
├── requirements.txt # Core deps
├── requirements-ml.txt # Optional ML / NER stack
├── config.py
├── caselinker.db # SQLite (local; created on first ingest)
├── triage.md # Triage rules and model docs
├── Procfile # Railway / Heroku start command
└── Architecture design.md
```
## 案件 Schema 与特征提取
每个案件都包含从案件叙述中提取的结构化特征：
### **Regex 提取**
- **犯罪者**：年龄、性犯罪者登记状态、声明时的性别；多被告操作的标记
- **受害者**：年龄、年龄段、当受害者条款措辞明确指出时的计数、验证后的性别
- **关系**：亲属和角色标签（父亲、母亲、父母、兄弟姐妹、老师、教练、陌生人等）；未声明时为未知
- **平台**：指定的应用程序和界面——社交、消息传递、游戏、文件托管、直播、早期聊天时代、被引用时的 Gen AI 工具——以及在找不到匹配产品时的通用在线、聊天或社交媒体标记
- **技术信号**（与平台列表分开存储）：调查工具（PhotoDNA、哈希匹配、CyberTipline 语言）、匿名化（Tor、暗网、加密货币）、P2P 客户端
- **起诉**：带计数的指控短语、立案阶段（从逮捕到判刑）、提及监禁、刑期
- **证据数量**：当文本中量化时的图像、视频、存储和消息计数
- **调查**：非排他性类型——主动、被动、在线、卧底、CyberTipline 来源或未知；结合模式匹配和 NER 补充得出的机构信息
- **前科记录**：登记状态和声明时的先前逮捕年龄
### **基于模式的分类**
- **案件主题**：制作、持有、分发、贩卖、csam、ai_csam、性勒索、动手实施 vs 仅限线上、家庭成员 vs 陌生人、跨国、跨州
- **严重程度指标**：婴儿、极其年幼、12 岁以下、性虐待；当提取出多个罪犯年龄时标记为多名犯罪者
- **严重性短语**：危险的、声称的、告诉的、持续的、攻击的、失控的、被吸引的 —— 用于优先级评分
### **ML 增强**
当启用 ML 技术栈时，NER 会添加组织、地点、日期和年龄，并与 regex 输出合并。受害者年龄门控机制会过滤掉诱饵年龄和新闻标题年龄。语义句子评分会在每个案件上存储概念得分；诱导（grooming）可能会增加严重性标签，而强烈的持有或 AI 生成语言可能会强化案件主题。大多数概念得分会被保留用于分析；只有被选中的得分才会合并到主要字段中。
### **聚类与存储**
- **比较值**：归一化向量（平台、人口统计、调查、证据、主题、严重程度、日期），用于相似度计算和预计算集群
- **机构路径**：根据叙述上下文可推断出的联邦与州/地方分支
- **保留的数据**：原始叙述、来源组织、存在时的来源 URL、从格式化 PDF 提取的来源发布日期、时间戳
## API 端点
- `GET /` - 主页
- `GET /api/cases` - 完整的批量案件导出（需 localhost 或在 `CASELINKER_TRUSTED_KEYS` 中配置的 `CaseLinker-Key`）
- `GET /api/cases-summaries-chunk` - 公开的分页摘要（`offset`，`limit` ≤ 500）；UI 通过许多小的响应加载完整的时间线，而不是一个批量的 JSON
- `POST /api/cases-summaries-by-ids` - 公开的批量摘要（每次请求最多 500 个 ID），用于集群成员身份和类似流程
- `GET /api/cases/{case_id}` - 单个案件（公开响应省略 `raw_data`；叙述以 `case_text` 形式提供供 UI 深入查看）
- `GET /api/case-count` - 案件总数（公开，有速率限制）
- `GET /api/case-ids-by-filter` - 匹配过滤查询参数的案件 ID（公开，有速率限制）
- `GET /api/tags` - 整个语料库中不同的标签值（公开，有速率限制）
- `POST /api/tag-threader` - 标签共现线程分析（公开，有速率限制）
- `GET /visualization` - 平台危害仪表板（Q1 可供性-滥用-危害分析、分级证据、手动平台分析）
- `GET /api/q1/platform-evidence` - Q1 平台证据索引或特定平台的队列信息（`platform`，可选的 `tier`）
- `GET /search` - 已存储案件的 Facet 决策树 (D3)；修剪过滤器；通过 API 获取队列案件 ID
- `GET /query` - 自定义分析实验室（仅限浏览器端 JavaScript 调用公开 API；示例见页面）
- `GET /lifecycle` - 剥削生命周期可视化（公开 HTML；payload 在服务器端嵌入）
- `GET /api/lifecycle/cases` - 生命周期 JSON（受信任的 `CaseLinker-Key` 或 localhost；与 `GET /api/cases` 门控相同）
- `GET /api/lifecycle/lstar` - 完整的 L* 输出（`state_machines/data/lstar_all_cases.json`；受信任的 key 或 localhost）
- `GET /api/lifecycle/canonical` - 面向 5 个典型 PACER 状态机案件的公开 JSON（无需 key；有速率限制；专为外部嵌入设计）
- `GET /analysis` - 具有基于标签的过滤和自动化分析的高级案件分析页面
- `GET /api/facet-tree` - 构建 facet 树 JSON（`max_depth`，可选的修剪查询参数）
- `GET /api/facet-distinct` - 每个 facet 不同的主桶值（用于搜索修剪 UI）
- `POST /api/facet-cohort-members` - 某个 facet 路径的案件 ID（与树具有相同的修剪语义；小规模队列受限）
- `GET /triage` - 分诊页面（规则、模型评估、语料库模型分层、粘贴即时分诊）
- `GET /patterns` - 阶段 2：模式研究文档页面
- `GET /patterns/graph` - 合并后的 CAC 本体图谱浏览器（compare / Big Bang 池）
- `GET /patterns/questions/{question_id}` - Q01–Q03 叙述性问题页面
- `GET /mcp/sse` - MCP SSE 传输（需要 `Authorization: Bearer `）
- `GET|POST /mcp-http/` - MCP Streamable HTTP 传输（相同的授权要求）
- `GET /api/ontology/merged` - 合并的图谱 JSON（`pool=compare|all|universe|analysis`；公开，带缓存）
- `GET /api/ontology/cases` - 单个案件的图谱目录（`pool=compare|all|universe|analysis`；公开元数据：`case_id`、`path`、`ttl_path`）
- `GET /ontology/graph_output/{pool}/{case_id}.jsonld|.ttl` - 静态的单个案件 CAC 图谱文件（公开）
- `GET /ontology/q1/*`, `/ontology/q2/*`, `/ontology/q3/*`, `/ontology/question_data/*` - 静态的 Q1–Q3 证据 JSON（公开）
- `GET /ontology/q_results.json` - 存在时的汇总问题结果 JSON（公开）
- `POST /api/ontology/cache/warm` - 重建/预热合并图谱的缓存（`pool=compare|all|universe|analysis|both`）
- `GET /api/triage-eval` - 基于实时案件的分层训练/测试指标（与 `scripts/verify/test_triage.py` 使用相同的流水线）
- `GET /api/triage-model-corpus` - 在实时数据库上保存的 bundle 预测；可选的 `facet_constraints` JSON 查询参数（有速率限制）
- `POST /api/triage-live` - 仅在内存中对粘贴的批量文本进行分类；需要 bundle；不进行持久化存储
- `GET /sources` - 数据源页面
- `GET /case-studies` - 案例研究阅览室（时代 + 来自 `data/case_studies.json` 的研究）
- `GET /api/case-studies` - 案例研究内容文档（时代、研究、默认表单 URL）
- `GET /api/case-studies/notes/{case_id}` - 针对某个研究 ID 的社区笔记
- `POST /api/case-studies/notes/{case_id}` - 添加社区笔记（有速率限制）
- `GET /audit` - 数据审计页面，用于逐案审查提取的特征
- `GET /api/automated-analysis` - 运行自动化分析（案件分组、分诊、洞察）
- `POST /api/return-tagged-cases` - 获取匹配选中标签的案件（交集逻辑）
- `GET /api/stats` - 获取案件统计信息（案件总数、提取的特征计数、数据源）
- `GET /api/stats-detailed` - 详细的语料库统计信息（公开，有速率限制）
- `GET /api/location-stats` - 地点/地理汇总信息（公开，有速率限制）
- `GET /api/technology-revolver` - 按时代桶划分的各时代技术数据（公开，有速率限制）
- `GET /api/cluster-groups` - 预计算的相似度集群组（公开，有速率限制）
- `GET /stats` - 统计仪表板页面
- `GET /clusters` - 集群浏览器页面
- `GET /tech-landscape` - 技术全景页面
- `GET /under-the-hood` - 架构/方法论页面
- `GET /llm` - LLM 聊天页面
- `POST /api/llm/chat` - LLM 聊天端点（公开；按 IP 每日限额，localhost/受信任的 key 豁免）
- `POST /api/cache/clear` - 清除服务器缓存（速率限制：10次/小时）
- `GET /api` - API 信息根目录；`GET /healthz` - 健康检查
- `GET /docs` - 交互式 API 文档
## 技术栈
- **后端**：Python 3, FastAPI, Uvicorn
- **数据处理**：Pandas, NumPy
- **PDF 处理**：pdfplumber
- **数据库**：PostgreSQL（生产环境）/ SQLite（本地开发环境）
- 生产环境：Railway PostgreSQL，配备加密连接
- 本地环境：首次运行时自动创建 SQLite 数据库
- **可视化**：D3.js, HTML/CSS/JavaScript
- **ML/NER**：
- Stanza 主要 NER 模型；代码中包含可选的 Transformers/spaCy 路径
- 语义概念评分（诱导、持有、AI 生成的 CSAM 语言及相关主题），在满足阈值时合并到案件主题和严重程度字段中
- **有监督的分诊（实验性）**：scikit-learn 随机森林或决策树；标签来源于基于规则的优先级评分；在推理时加载 `joblib` bundle
- **架构**：模块化的 5 层设计
## 部署
CaseLinker 可以部署到云平台以供公开访问。该应用程序包含一个 `Procfile`，可用于部署到 Railway、Heroku 及类似平台。
## 数据源与伦理
- **无敏感数据**：本系统包含的案件均来自公开可用的数据源（ICAC Task Forces 案件与逮捕信息、NCMEC CyberTipline 成功故事、DOJ CEOS 新闻稿以及各州总检察长办公室新闻稿）。这些报告是公开的，概述了调查、逮捕和案件细节，并为公开发布进行了脱敏处理。所有数据均已在公开领域。本项目已获得马萨诸塞大学阿默斯特分校人类研究保护办公室的裁定（HRPO Determination #7668）；根据联邦法规 [45 CFR 46.102(f)(1), (2)]，本研究不包含私人或可识别的个人信息。
- **有关数据使用的完整免责声明，请参见 `/sources` 页面**
## 贡献
贡献者可以通过以下方式提供帮助：
- 为 README 添加想法
- 参与架构设计
- 代码实现
标签：Apex, 代码示例, 信息提取, 数据分析, 机器学习, 案件分析, 测试用例, 逆向工具