@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/research/osint-investigation/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: osint-investigation
+description: 公共记录 OSINT 调查框架 — SEC EDGAR 文件、USAspending 合同、参议院游说记录、OFAC 制裁名单、ICIJ 离岸泄密、纽约市房产记录 (ACRIS)、OpenCorporates 企业注册信息、CourtListener 法庭记录、Wayback Machine 存档、Wikipedia + Wikidata、GDELT 新闻监控。支持跨来源实体解析、交叉链接分析、时间相关性与证据链构建。仅使用 Python 标准库。
+version: 0.1.0
+platforms: [linux, macos, windows]
+author: Hermes Agent (adapted from ShinMegamiBoson/OpenPlanter, MIT)
+metadata:
+  hermes:
+    tags: [osint, investigation, public-records, sec, sanctions, corporate-registry, property, courts, due-diligence, journalism]
+    category: research
+    related_skills: [domain-intel, arxiv]
+---
+
+# OSINT Investigation — 公共记录交叉比对
+
+用于公共记录 OSINT 的调查框架：政府合同、企业申报文件、游说记录、制裁名单、离岸泄密、房产记录、法庭记录、网络存档、知识库以及全球新闻。解析异构来源中的实体，构建带有明确置信度的交叉链接，运行统计时间测试，并生成结构化的证据链。
+
+**仅使用 Python 标准库。** 零安装。支持 Linux、macOS 和 Windows。大多数数据源无需 API key 即可使用（OpenCorporates 提供可选的免费 token 以提升速率限制）。
+
+基于 MIT 许可的 ShinMegamiBoson/OpenPlanter 项目改编；扩展涵盖了原项目未涉及的实体身份、房产、诉讼、存档及新闻数据源。
+
+## 何时使用此技能
+
+适用于用户要求以下场景：
+
+- “跟踪资金流向”—— 政府合同、游说立法化、制裁情况
+- 企业尽职调查—— 谁控制着公司 X，他们在哪里注册成立，谁在他们的董事会任职，他们提交了哪些文件
+- 制裁筛查—— 实体 X 是否在 OFAC SDN 名单中，ICIJ 离岸泄密库中是否有记录
+- 权钱交易调查—— 具有离岸关系的承包商，游说客户中标情况
+- 房产所有权—— 按姓名或地址查找记录在案的地契/抵押贷款（纽约市；对于其他县，请引导用户前往相关的登记处）
+- 诉讼历史—— 查找联邦和州法院的判决书以及 PACER 案卷
+- 命名规则不一致的多源实体解析（例如 LLC 后缀、缩写差异）
+- 构建带有明确置信度级别的证据链
+- “关于 X 说了什么”—— 国际新闻 (GDELT) + Wikipedia 报道 + 使用 Wayback Machine 恢复死链 URL
+
+请勿将此技能用于：
+
+- 常规网络研究 → `web_search` / `web_extract`
+- 域名/基础设施 OSINT → `domain-intel` 技能
+- 学术文献 → `arxiv` 技能
+- 社交媒体资料发现 → `sherlock` 技能（可选）
+- 美国**联邦**竞选财务—— 此处有意不涵盖 FEC（在免费的 DEMO_KEY 层级上，该 API 对于临时贡献者姓名查询非常不稳定）。如需联邦捐款信息，请引导用户直接访问 https://www.fec.gov/data/。
+
+## 工作流程
+
+Agent 通过 `terminal` 工具运行脚本。`SKILL_DIR` 是存放本 SKILL.md 的目录。
+
+### 1. 确定适用的数据源
+
+阅读数据源 wiki 条目以规划调查方案：
+
+```
+ls SKILL_DIR/references/sources/
+
+# 联邦金融 / 监管
+cat SKILL_DIR/references/sources/sec-edgar.md       # 企业申报文件
+cat SKILL_DIR/references/sources/usaspending.md     # 联邦合同
+cat SKILL_DIR/references/sources/senate-ld.md       # 游说记录
+cat SKILL_DIR/references/sources/ofac-sdn.md        # 制裁名单
+cat SKILL_DIR/references/sources/icij-offshore.md   # 离岸泄密
+
+# 身份 / 房产 / 诉讼 / 存档 / 新闻
+cat SKILL_DIR/references/sources/nyc-acris.md       # 纽约市房产记录
+cat SKILL_DIR/references/sources/opencorporates.md  # 全球企业注册库
+cat SKILL_DIR/references/sources/courtlistener.md   # 法庭记录（联邦 + 州）
+cat SKILL_DIR/references/sources/wayback.md         # Wayback Machine 存档
+cat SKILL_DIR/references/sources/wikipedia.md       # Wikipedia + Wikidata
+cat SKILL_DIR/references/sources/gdelt.md           # 全球新闻监控
+```
+
+每个条目遵循 9 部分模板：摘要、访问方式、数据模式、覆盖范围、交叉比对键、数据质量、数据获取、法律声明、参考资料。
+
+**交叉比对潜力** 部分映射了各数据源之间的关联键——请优先阅读该部分以选择正确的比对组合。
+
+### 2. 获取数据
+
+每个数据源在 `SKILL_DIR/scripts/` 目录下都有一个仅依赖标准库的获取脚本：
+
+**联邦金融 / 监管**
+
+```bash
+# SEC EDGAR 文件（企业披露）
+python3 SKILL_DIR/scripts/fetch_sec_edgar.py --cik 0000320193 \
+    --types 10-K,10-Q --out data/edgar_filings.csv
+
+# USAspending 联邦合同
+python3 SKILL_DIR/scripts/fetch_usaspending.py --recipient "EXAMPLE CORP" \
+    --fy 2024 --out data/contracts.csv
+
+# 参议院 LD-1 / LD-2 游说披露
+python3 SKILL_DIR/scripts/fetch_senate_ld.py --client "EXAMPLE CORP" \
+    --year 2024 --out data/lobbying.csv
+
+# OFAC SDN 制裁名单（完整快照）
+python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --out data/ofac_sdn.csv
+
+# ICIJ Offshore Leaks — 首次使用时会下载约 70 MB 的批量 CSV 数据，
+# 然后在本地进行搜索。缓存保留 30 天，存放于
+# $HERMES_OSINT_CACHE/icij/ (默认路径: ~/.cache/hermes-osint/icij/).
+python3 SKILL_DIR/scripts/fetch_icij_offshore.py --entity "EXAMPLE CORP" \
+    --out data/icij.csv
+```
+
+**身份 / 房产 / 诉讼 / 存档 / 新闻**
+
+```bash
+# 纽约市房产记录（地契、抵押贷款、留置权）— 通过 Socrata 访问 ACRIS
+python3 SKILL_DIR/scripts/fetch_nyc_acris.py --name "SMITH, JOHN" \
+    --out data/acris.csv
+python3 SKILL_DIR/scripts/fetch_nyc_acris.py --address "571 HUDSON" \
+    --out data/acris_addr.csv
+
+# OpenCorporates — 涵盖 130 多个司法管辖区的企业注册库
+# (需要免费 token；请设置 OPENCORPORATES_API_TOKEN 或传递 --token 参数)
+python3 SKILL_DIR/scripts/fetch_opencorporates.py --query "Example Corp" \
+    --jurisdiction us_ny --out data/opencorporates.csv
+
+# CourtListener — 联邦及州法院判决书，PACER 案卷
+python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Smith v. Example Corp" \
+    --type opinions --out data/courts.csv
+
+# Wayback Machine — 历史网页快照
+python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
+    --match host --collapse digest --out data/wayback.csv
+
+# Wikipedia + Wikidata — 人物传记叙述 + 结构化事实
+# 请设置 HERMES_OSINT_UA=your-app/1.0 (your@email) 以标识您的身份
+python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Bill Gates" \
+    --out data/wp.csv
+
+# GDELT — 涵盖 100 多种语言的全球新闻，约 2015年至今
+python3 SKILL_DIR/scripts/fetch_gdelt.py --query '"Example Corp"' \
+    --timespan 1y --out data/gdelt.csv
+```
+
+所有输出均为包含标题行的标准化 CSV 文件。脚本支持幂等重跑。
+
+当普通个人不可能出现在某数据源中时（例如：非上市公司人员查询 SEC EDGAR，非联邦承包商查询 USAspending，非游说客户查询参议院 LDA），脚本将返回 0 行数据并给出明确的警告，而不是静默写入一个空的 CSV 文件。特别是，当公司名称解析器匹配到填写 Form 3/4/5 的个人申报者而非企业注册者时，EDGAR 会进行标记提示。
+
+速率限制相关的说明位于各数据源的 wiki 条目中。默认情况下，获取脚本会在分页请求之间进行礼貌的休眠。**API key 可以提升支持速率限制的数据源的访问上限**（`SEC_USER_AGENT`、`SENATE_LDA_TOKEN`、`OPENCORPORATES_API_TOKEN`、`COURTLISTENER_TOKEN`）。所有脚本在遇到 429 响应时会立即抛出并显示上游的配额限制提示消息，以便用户知道需要放缓请求频率或提供相应的 key。
+
+### 3. 跨来源解析实体
+
+规范化名称并在两个 CSV 文件之间查找匹配项：
+
+```bash
+# 将游说客户 (参议院 LDA) 与合同接收方 (USAspending) 进行匹配
+python3 SKILL_DIR/scripts/entity_resolution.py \
+    --left  data/lobbying.csv   --left-name-col  client_name \
+    --right data/contracts.csv  --right-name-col recipient_name \
+    --out data/cross_links.csv
+```
+
+具有明确置信度的三个匹配层级：
+
+| 层级 | 方法 | 置信度 |
+|------|--------|------------|
+| `exact` | 去除后缀/标点符号后字符串完全一致 | high |
+| `fuzzy` | 排序后的 token 完全一致（词袋匹配） | medium |
+| `token_overlap` | token 重叠率 ≥60%，共享 token ≥2 个，且 token 长度 ≥4 个字符 | low |
+
+输出 `cross_links.csv` 的列包含：`match_type, confidence, left_name,
+right_name, left_normalized, right_normalized, left_row, right_row`。
+
+### 4. 统计时间相关性分析（可选）
+
+使用置换检验，测试两个时间序列是否在时间上存在可疑的紧密聚集（例如：游说申报记录密集出现于合同授予前后）：
+
+```bash
+python3 SKILL_DIR/scripts/timing_analysis.py \
+    --donations data/lobbying.csv --donation-date-col filing_date \
+        --donation-amount-col income --donation-donor-col client_name \
+        --donation-recipient-col registrant_name \
+    --contracts data/contracts.csv --contract-date-col award_date \
+        --contract-vendor-col recipient_name \
+    --cross-links data/cross_links.csv \
+    --permutations 1000 \
+    --out data/timing.json
+```
+
+脚本的列参数被刻意设计为通用的——最初的工具是为“捐款 vs 获奖”编写的，但它适用于任何通过交叉链接关联的（事件，收款人）时间序列。零假设：事件发生时间与授予日期相互独立。单侧 p 值 = 观察到的最近授予距离均值小于或等于实际观察值的置换检验比例。每次（付款方，供应商）配对测试至少需要 3 个事件才能运行。
+
+### 5. 生成结论 JSON（证据链）
+
+```bash
+python3 SKILL_DIR/scripts/build_findings.py \
+    --cross-links data/cross_links.csv \
+    --timing data/timing.json \
+    --out data/findings.json
+```
+
+每条结论都包含 `id, title, severity, confidence, summary, evidence[], sources[]`。每项证据都会指回原始 CSV 数据源中的特定行。用户（或后续执行的 agent）可以对照数据来源验证每一条声明。
+
+## 置信度与证据规范
+
+这是本技能的核心支撑原则。请告知用户：
+
+- 每一项声明都必须能追溯到具体记录。不接受无根据的断言。
+- 置信度级别伴随声明存在。`match_type=fuzzy` 意味着“有可能”，而绝非“已确认”。
+- 实体解析提供的是调查线索，而非最终结论。例如，“ACME LLC”和“Acme Holdings Group”之间的 `fuzzy` 匹配是一条线索，而不是既定事实。
+- 统计显著性 ≠ 违规行为。p < 0.05 只意味着在零假设前提下，这种时间模式发生的概率极低。它不能作为认定腐败的证据。
+- 此处的所有数据源皆为公共记录。但它们仍可能包含不准确、过时的信息或经过脱敏处理的内容（如 GDPR 限制、密封记录）。
+
+## 添加新的数据源
+
+请使用以下模板：
+
+```bash
+cp SKILL_DIR/templates/source-template.md \
+    SKILL_DIR/references/sources/<your-source>.md
+```
+
+填妥全部 9 个部分。在 `scripts/` 目录下编写一个仅使用标准库且输出标准化 CSV 的 `fetch_<source>.py` 脚本。 更新上述“何时使用”章节中的数据源列表。
+
+## 工具及其局限性
+
+- `entity_resolution.py` 并未使用外部模糊匹配库（没有使用 rapidfuzz，也没有使用 jellyfish）。词袋匹配是当前可用的最高匹配标准。如果需要 Levenshtein 距离、音译或语音匹配功能，请单独使用 pip 安装相关库。
+- `timing_analysis.py` 使用 Python 的 `random` 进行置换检验。若需保证结果可复现，请传递 `--seed N` 参数。
+- `fetch_*.py` 脚本使用 `urllib.request` 并遵循 `Retry-After` 响应头。大量高频的抓取行为仍可能违反服务条款（ToS）——请务必先阅读各数据源的法律声明部分。
+
+## 法律声明
+
+所有 Phase-1 数据源均为公共记录。根据各自的获取条款（如 FOIA、《公共记录法》、ICIJ 明确发布、OFAC 公共数据），允许进行批量获取。然而：
+
+- 部分数据源存在严格的速率限制。请尊重并遵循其响应头要求。
+- 部分数据会对注册者信息进行脱敏处理（如 GDPR 对 WHOIS 的限制、密封卷宗）。
+- 通过交叉比对公共记录来识别普通个人身份可能涉及伦理问题。本技能产出的为证据链，而非指控。

package/extensions/skills/optional/research/osint-investigation/references/sources/courtlistener.md

@@ -0,0 +1,92 @@
+# CourtListener — Free Law Project
+
+## 1. 概述
+
+CourtListener（Free Law Project）汇集了法院判决意见、案件卷宗、口头辩论和法官数据。涵盖了可追溯至殖民地时期美国的约 1000 万份联邦和州法院判决意见，以及来自 RECAP 提交的 PACER 卷宗数据。
+
+## 2. 访问方式
+
+- **REST API v4:** `https://www.courtlistener.com/api/rest/v4/`
+- **认证：** 大多数 endpoint 允许匿名读取；使用 token 可提高速率限制并解锁批量导出功能
+- **速率限制：** 未认证情况下搜索请求约为每小时 5,000 次；使用 token 后更高
+
+设置 `COURTLISTENER_TOKEN` 环境变量。请在 https://www.courtlistener.com/sign-in/ 注册并创建一个 API key 以获取免费 token。
+
+## 3. 数据模式
+
+`fetch_courtlistener.py` 输出的主要字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `case_name` | str | 案件名称 |
+| `court` | str | 法院名称 |
+| `court_id` | str | 法院 ID（例如 `nysd`, `scotus`, `ca9`） |
+| `date_filed` | str | YYYY-MM-DD |
+| `docket_number` | str | 法院卷宗号 |
+| `judge` | str | 法官姓名 |
+| `citation` | str | 判例汇编引注 |
+| `result_type` | str | opinions / dockets / oral / people |
+| `snippet` | str | 搜索匹配摘要（最多 500 个字符） |
+| `absolute_url` | str | CourtListener 直接 URL |
+
+## 4. 覆盖范围
+
+- 联邦：所有巡回法院和地区法院，SCOTUS
+- 州：全部 50 个州的最高/上诉法院，以及许多初审法院
+- 判决意见：约 1000 万份，可追溯至 17 世纪（殖民地时期），1950 年至今覆盖完整
+- 通过 RECAP 获取的卷宗：来自用户提交的 PACER PDF 的超过 300 万份
+- 持续更新中
+
+## 5. 交叉引用潜力
+
+- **OpenCorporates** ↔ `case_name`（公司诉讼）
+- **SEC EDGAR** ↔ `case_name`（证券集体诉讼）
+- **OFAC SDN** ↔ `case_name`（制裁相关的民事/刑事案件）
+
+关联键（Join key）：来自 `case_name` 的当事人名称。注意：`case_name` 经常使用缩写（例如使用 "Smith v. Jones" 而不是完整的当事人名称）——请使用完整的案件 URL 以获取所有当事人信息。
+
+## 6. 数据质量
+
+- 较早的判决意见（1990 年以前）通常缺少卷宗号和法官信息
+- 州级覆盖的均匀度不如联邦
+- PACER 卷宗覆盖范围取决于 RECAP 用户的提交——并不全面
+- 已密封的文件已被排除
+| 案件标题中的当事人名称并不总是与备案名称完全一致
+
+## 7. 获取脚本
+
+路径：`scripts/fetch_courtlistener.py`
+
+```bash
+# 根据当事人 / 关键词搜索判决意见
+python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Example Corp" \
+    --out data/cl.csv
+
+# PACER 卷宗（最适合近期诉讼）
+python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Example Corp" \
+    --type dockets --out data/cl_dockets.csv
+
+# 限定特定法院
+python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Microsoft" \
+    --court ca9 --out data/cl_9th.csv
+
+# 日期范围
+python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Example Corp" \
+    --date-from 2020-01-01 --date-to 2024-12-31 --out data/cl.csv
+```
+
+请传入 `--token` 或设置 `COURTLISTENER_TOKEN`。
+
+## 8. 法律与许可
+
+- 法院判决意见属于公共领域
+- Free Law Project 在 CC0 / 公共领域贡献协议下提供数据
+- 对判决意见文本或元数据没有商业使用限制
+- 部分 PACER PDF 的排版受版权保护（文本不受保护）——适用于合理使用原则
+
+## 9. 参考资料
+
+- API 文档: https://www.courtlistener.com/help/api/rest/
+- 法院 ID: https://www.courtlistener.com/api/jurisdictions/
+- RECAP 归档: https://www.courtlistener.com/recap/
+- 批量数据: https://www.courtlistener.com/help/api/bulk-data/

package/extensions/skills/optional/research/osint-investigation/references/sources/gdelt.md

@@ -0,0 +1,94 @@
+# GDELT — 全球新闻监控
+
+## 1. 概述
+
+GDELT (Global Database of Events, Language, and Tone) 监控以 100 多种语言发布的世界新闻，并提供全文索引。每 15 分钟更新一次。
+覆盖范围约为 2015 年至今，已索引超过 10 亿篇文章。提供免费的匿名访问。
+
+GDELT 的覆盖范围比 Google News 更广（包含更多国际来源和更多长尾来源），并按语调/情感、主题（CAMEO 码）、人物和组织进行索引。
+
+## 2. 访问方式
+
+- **DOC 2.0 API:** `https://api.gdeltproject.org/api/v2/doc/doc`
+- **Events / GKG 2.0:** `https://api.gdeltproject.org/api/v2/events/events`
+- **Auth:** 无
+- **Rate limit:** DOC API 限制为 **每 5 秒 1 次请求** — 非常严格
+
+获取脚本在收到 429 错误时会自动休眠 6 秒后重试。
+
+## 3. 数据模式
+
+`fetch_gdelt.py` 输出的主要字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `title` | str | 文章标题 |
+| `url` | str | 文章 URL |
+| `seen_date` | str | GDELT 首次发现该文章的时间 (UTC) |
+| `domain` | str | 发布者域名 |
+| `language` | str | 源语言 |
+| `source_country` | str | 2 个字母的国家代码 |
+| `tone` | str | GDELT 计算的语调得分（负数 = 负面报道） |
+| `social_image` | str | 可用时的 Open Graph 图像 URL |
+
+## 4. 覆盖范围
+
+- 100 多种语言的全球新闻
+- 约 2015 年至今（Events 可通过单独的数据流追溯至 1979 年）
+- 更新频率：15 分钟
+- 偏见：在数量上严重偏向英语，但总体来源列表非常广泛
+
+## 5. 交叉引用潜力
+
+- **所有来源** ↔ `title` / `url`（提供任何主题的新闻背景）
+- **Wikipedia** ↔ 知名实体的事件时间线
+- **Wayback Machine** ↔ 恢复链接已失效的文章
+- **OFAC SDN** ↔ 制裁指定的新闻背景
+- **SEC EDGAR** ↔ 8-K 重大事件的新闻背景
+
+关联键（Join key）：出现在文章标题或全文中的实体名称。GDELT 还会将命名实体提取到单独的数据流（GKG）中，但此获取器并未暴露该功能 —— 如需实体级别的过滤，请直接查询 GDELT。
+
+## 6. 数据质量
+
+- 标题提取是自动化的，可能会出错（有时会抓取成站点名称 + 分隔符 + 文章标题；有时是通用的页面标题）
+- 情感/语调由 GDELT 计算得出，并非由来源提供
+- 部分域名被过度采样（如新闻专线、新闻聚合器）
+- 来源国家是根据域名注册/TLD 推断的 —— 对于使用中性国家域名的国际新闻网站，推断结果可能会有误
+- 文章 URL 可能会失效（链接失效） —— 请与 Wayback Machine 配合使用以保存内容
+
+## 7. 获取脚本
+
+路径：`scripts/fetch_gdelt.py`
+
+```bash
+# Recent news mentioning an entity
+python3 SKILL_DIR/scripts/fetch_gdelt.py --query "Nous Research" \
+    --timespan 6m --out data/gdelt.csv
+
+# Phrase-exact (use double quotes inside single quotes for the shell)
+python3 SKILL_DIR/scripts/fetch_gdelt.py --query '"Dillon Rolnick"' \
+    --timespan 1y --out data/gdelt.csv
+
+# Filter to a country / language
+python3 SKILL_DIR/scripts/fetch_gdelt.py --query "Microsoft" \
+    --source-country US --source-lang English --out data/gdelt.csv
+
+# Date range
+python3 SKILL_DIR/scripts/fetch_gdelt.py --query "Microsoft" \
+    --start 2024-01-01 --end 2024-12-31 --out data/gdelt.csv
+```
+
+GDELT 支持其专有的查询运算符：短语引用、AND/OR/NOT、`sourcecountry:US`、`theme:ECON_BANKRUPTCY`、`tone<-5` 等。
+有关语法详情，请参见 https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/ 。
+
+## 8. 法律与许可
+
+- GDELT 数据免费提供给学术和新闻界使用
+- 文章 URL 会直接链接到原始发布者 —— 版权仍归发布者所有
+- GDELT 不是内容存档；它是一个元数据索引
+
+## 9. 参考资料
+
+- DOC 2.0 API: https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/
+- Themes & query syntax: https://blog.gdeltproject.org/gkg-2-0-our-global-knowledge-graph-2-0-amazing-data-at-your-fingertips/
+- Project home: https://www.gdeltproject.org/

package/extensions/skills/optional/research/osint-investigation/references/sources/icij-offshore.md

@@ -0,0 +1,79 @@
+# ICIJ 离岸泄密数据库
+1.摘要
+国际调查记者同盟（ICIJ）发布了一份
+来自巴拿马，
+潘多拉文件、巴哈马群岛泄密事件和离岸泄密事件。约800,000+个离岸实体
+以及他们的官员、中介机构和地址。
+2. 访问方法
+- **批量下载（主要）：**`https://offshoreleaks-data.icij.org/offshoreleaks/csv/full-oldb.LATEST.zip`（约70 MB ZIP文件，会定期刷新）
+- **搜索用户界面（人工）：**`https://offshoreleaks.icij.org/`
+- **认证**：无
+- **注意**：之前的Open Refine对账端点位于
+ `/reconcile` 现在返回 404。ICIJ 已将其删除。批量 ZIP 文件是
+ 剩余的稳定访问路径。该技能的`fetch_icij_offshore.py`缓存
+ 在本地解压（默认路径为`~/.cache/hermes-osint/icij/`，刷新后）
+ （30天）并离线搜索。
+3.数据模式
+`fetch_icij_offshore.py` 输出的关键字段：
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `node_id` | int | ICIJ规范节点ID |
+| `name` | str | 实体/官员/中介名称 |
+| `node_type` | str | 实体 / 官员 / 中介 / 地址 |
+| `country_codes` | str | 以分号分隔的ISO代码 |
+| `countries` | str | 国家名称 |
+| `jurisdiction` | str | 离岸司法管辖区（英属维尔京群岛、巴拿马等） |
+| `incorporation_date` | str | YYYY-MM-DD |
+| `inactivation_date` | str | YYYY-MM-DD（如已失效） |
+| `source` | str | 巴拿马文件 / 天堂。 |
+| `entity_url` | str | 指向ICIJ页面的链接 |
+| `connections` | str | 以分号分隔的相关实体的节点ID |
+4.覆盖
+- 全球离岸实体记录
+- 最早记录：20世纪70年代（巴哈马泄密事件）。大部分数据来自1990年至2018年。
+- 未实时更新——当国际调查记者同盟（ICIJ）发布新泄密文件时，会添加进去
+- 约810,000个离岸实体 + 约750,000名管理人员 + 约150,000个中介机构
+5. 交叉引用潜力
+- **SEC EDGAR** ↔ `名称`（拥有离岸分支机构的上市公司）
+- **USAspending** ↔ `name`（具有离岸结构的联邦承包商）
+- **OFAC SDN** ↔ `name`（使用离岸工具的受制裁实体）
+连接键：规范化实体/官员名称。`node_id`是跨数据库的规范标识符
+在ICIJ内部引用。连接图遍历是在脚本中进行的（基于广度优先搜索（BFS））
+“connections”）。
+6. 数据质量
+离岸实体的名称有时会在多次泄露中以微小的差异出现
+- 官员可能是名义持有人（挂名负责人），而非实益拥有人
+- 有些条目信息极少（仅包含名称和管辖地）
+- 连接图不完整——部分关系已记录在
+ 原始材料，但不在结构化数据库中
+- 已停用/已注销的实体仍会包含在`inactivation_date`中
+7. 采集脚本
+路径：`scripts/fetch_icij_offshore.py`
+```bash
+# 按实体名称搜索（在批量数据库中不区分大小写的子字符串）
+python3 SKILL_DIR/scripts/fetch_icij_offshore.py --entity "EXAMPLE CORP" \
+ --输出数据至 data/icij.csv
+# 按官员（个人）搜索
+python3 SKILL_DIR/scripts/fetch_icij_offshore.py --officer "SMITH JOHN" \
+ --输出文件 data/icij.csv
+# 按司法管辖区搜索（基于缓存结果进行筛选）
+python3 SKILL_DIR/scripts/fetch_icij_offshore.py --officer "SMITH" \
+ --管辖区 "英属维尔京群岛" --输出 data/icij_bvi.csv
+# 强制重新下载（默认刷新窗口为30天）
+python3 SKILL_DIR/scripts/fetch_icij_offshore.py --entity "EXAMPLE CORP" \
+ --强制刷新 --输出数据/icij.csv
+```
+首次调用会在`~/.cache/hermes-osint/icij/`目录下下载约70MB的ZIP文件
+（或`$HERMES_OSINT_CACHE/icij/`）。后续调用将重用该缓存，有效期为30天。
+8. 法律与许可
+- 国际调查记者同盟（ICIJ）以明确出版方式发布的公开记录
+- 基本事实（实体名称、司法管辖区）无版权
+- 若在衍生品报告中引用，ICIJ要求注明出处
+- **道德说明**：出现在此数据库中并不意味着存在不当行为。许多
+ 离岸结构是合法的。该数据库是一个研究工具，而非一份清单
+ 罪犯。
+## 9.参考文献
+- 数据库：https://offshoreleaks.icij.org/
+- 关于数据：https://offshoreleaks.icij.org/pages/about
+- 方法论：https://www.icij.org/investigations/panama-papers/
+- API提示：Open Refine对账端点位于`https://offshoreleaks.icij.org/reconcile`

package/extensions/skills/optional/research/osint-investigation/references/sources/nyc-acris.md

@@ -0,0 +1,85 @@
+# NYC ACRIS — 纽约市房地产记录
+
+## 1. 摘要
+
+Automated City Register Information System (ACRIS) 是纽约市已记录房地产文件（契约、抵押、清偿、留置权、UCC 申请）的索引系统。覆盖曼哈顿、布朗克斯、布鲁克林、皇后区和斯塔滕岛。在 NYC Open Data 门户上以 4 个相互关联的 Socrata 数据集形式发布。
+
+## 2. 访问方式
+
+- **Socrata API:** `https://data.cityofnewyork.us/resource/636b-3b5g.json` (当事方)
+- **其他数据集:** `bnx9-e6tj` (主表), `8h5j-fqxa` (法律), `uqqa-hym2` (引用)
+- **认证:** 读取访问无需认证（如有需要，Socrata `$app_token` 可提高速率限制）
+- **速率限制:** 宽松（未认证情况下约 1000 次请求/小时）
+
+## 3. 数据模式
+
+`fetch_nyc_acris.py` 输出的关键字段（当事方已关联至主表）：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `document_id` | str | ACRIS 文档 ID |
+| `name` | str | 记录在案的当事方名称（通常为 "LAST, FIRST"，但会有变化） |
+| `party_type` | str | 1=grantor, 2=grantee, 3=other |
+| `party_role` | str | 人类可读的角色标签 |
+| `address_1` | str | 房产或当事方地址第 1 行 |
+| `city`, `state`, `zip`, `country` | str | 地址组成部分 |
+| `doc_type` | str | DEED, MTGE (mortgage), SAT (satisfaction), AGMT 等 |
+| `doc_date`, `recorded_date` | str | YYYY-MM-DD |
+| `borough` | str | Manhattan / Bronx / Brooklyn / Queens / Staten Island |
+| `amount` | str | 文档金额（USD，适用时） |
+| `filing_url` | str | 直接的 ACRIS DocumentImageView 链接 |
+
+## 4. 覆盖范围
+
+- 仅限纽约市 5 个行政区 —— 其他县有各自的记录机构
+- 1966 年至今（更早的申请文件可在 County Clerk 的微缩胶片中找到）
+- 每晚更新
+- 累计超过 7000 万条当事方记录
+
+## 5. 交叉比对潜力
+
+- **SEC EDGAR** ↔ `name`（在纽约市拥有房产的内部交易申报人）
+- **USAspending** ↔ `name`（在纽约市拥有房产的联邦承包商）
+- **Senate LDA** ↔ `name`（在纽约市拥有房产的说客/客户）
+- **ICIJ Offshore** ↔ `name`（通过离岸工具拥有的纽约市房产）
+
+关联键：规范化的当事方名称。纽约市房产记录通常将名称存储为 "LAST, FIRST" 或完整的 LLC 名称 —— 请使用 `entity_resolution.py`。
+
+## 6. 数据质量
+
+- 同一个人随时间推移会以多种名称格式出现
+- LLC 和信托所有权掩盖了实际受益人
+- 记录延迟可能在交易完成后的 2-4 周
+- 较旧的文档地址数据不够完整
+- 封存记录（例如家庭暴力收容所）依法被排除在外
+
+## 7. 获取脚本
+
+路径：`scripts/fetch_nyc_acris.py`
+
+```bash
+# 按当事方名称
+python3 SKILL_DIR/scripts/fetch_nyc_acris.py --name "ROLNICK" --out data/acris.csv
+
+# 按地址（当您知道房产但不知道名称时很有用）
+python3 SKILL_DIR/scripts/fetch_nyc_acris.py --address "571 HUDSON" --out data/acris.csv
+
+# 限制为受让人（买家/贷款人）
+python3 SKILL_DIR/scripts/fetch_nyc_acris.py --name "ROLNICK" --party-type 2 \
+    --out data/acris_buyers.csv
+```
+
+该脚本会将当事方关联至主表，以填充 doc_type、日期、行政区和金额。传入 `--no-enrich` 可跳过关联步骤（速度更快，但列数较少）。
+
+## 8. 法律与许可
+
+- 根据 NYS Real Property Law 和 NYC Charter 属于公共记录
+- 数据无商业使用限制
+- 所有 ACRIS 数据依法属于公共信息
+
+## 9. 参考
+
+- ACRIS 门户: https://a836-acris.nyc.gov/CP/
+- NYC Open Data: https://data.cityofnewyork.us/
+- 当事方数据集: https://data.cityofnewyork.us/City-Government/ACRIS-Real-Property-Parties/636b-3b5g
+- 文档类型代码: https://www1.nyc.gov/site/finance/taxes/acris.page

package/extensions/skills/optional/research/osint-investigation/references/sources/ofac-sdn.md

@@ -0,0 +1,84 @@
+# OFAC SDN — Specially Designated Nationals List
+
+## 1. 摘要
+
+Foreign Assets Control (OFAC) 发布 Specially Designated Nationals and Blocked Persons List (SDN)。通常禁止美国人员与该名单上的个人和实体进行交易。此外还发布了：非 SDN 综合名单（BIS Denied Persons、FSE 等）。
+
+## 2. 访问方式
+
+- **完整 XML:** `https://www.treasury.gov/ofac/downloads/sdn.xml`
+- **分隔符格式:** `https://www.treasury.gov/ofac/downloads/sdn.csv`
+- **综合列表:** `https://www.treasury.gov/ofac/downloads/consolidated/consolidated.xml`
+- **认证:** 无
+- **速率限制:** 无（静态文件下载）。持续更新。
+
+## 3. Data Schema
+
+`fetch_ofac_sdn.py` 输出的主要字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `entity_id` | int | OFAC 唯一 ID |
+| `name` | str | 主要名称 |
+| `entity_type` | str | 个人 / 实体 / 船只 / 航空器 |
+| `program_list` | str | 以分号分隔的制裁项目（例如 SDGT;IRAN） |
+| `title` | str | 针对个人：头衔/角色 |
+| `nationalities` | str | 以分号分隔的国家代码 |
+| `aka_list` | str | 以分号分隔的“亦称(also known as)”名称 |
+| `addresses` | str | 以分号分隔的已知地址 |
+| `dob` | str | 出生日期（针对个人） |
+| `pob` | str | 出生地（针对个人） |
+| `remarks` | str | OFAC 的自由文本备注 |
+| `last_updated` | str | YYYY-MM-DD（发布日期） |
+
+## 4. 覆盖范围
+
+- 全球范围 —— 受美国财政部制裁的所有实体
+- SDN 名单约有 10,000 条记录，综合名单约有 15,000 条记录
+- 持续更新（在积极执法期间有时会每日更新）
+- 包含 AKA（非常普遍，每个实体可能有 10 个以上）
+
+## 5. 交叉比对潜力
+
+- **SEC EDGAR** ↔ `name`（受制裁的上市公司）
+- **USAspending** ↔ `name`（受制裁实体作为联邦承包商——理应不可能，但需核实）
+- **ICIJ Offshore** ↔ `name`（同样受制裁的离岸实体）
+
+关联键：标准化名称。**关键**：还必须与 `aka_list` 进行匹配。许多受制裁实体只能通过别名被发现。
+
+## 6. 数据质量
+
+- 名称由多种文字音译而来 —— 可能有多种罗马化拼写
+- AKA 通常与主名称大相径庭
+- 部分个人记录信息极少（无 DOB，无地址）
+- 自由文本 `remarks` 包含关键背景信息 —— 请务必阅读
+- "Specially Designated Global Terrorists" (SDGT) 和 "Cyber-related" (CYBER2) 项目频繁增删条目
+
+## 7. 采集脚本
+
+路径：`scripts/fetch_ofac_sdn.py`
+
+```bash
+# 完整快照
+python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --out data/ofac_sdn.csv
+
+# 筛选特定项目
+python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --program SDGT --out data/sdn_sdgt.csv
+
+# 仅实体（跳过个人、船只、航空器）
+python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --entity-type entity --out data/sdn_entities.csv
+```
+
+## 8. 法律与许可
+
+- 基于 Executive Order 授权和法定制裁项目的公开记录
+- 美国人员必须针对此名单进行筛查 —— 该名单具有强制执行力
+- 数据本身没有使用限制；限制在于与名单所列实体的交易行为
+- 对“过度匹配（over-matching）”零处罚 —— 误报（false positives）必须被澄清，但不会被禁止
+
+## 9. 参考资料
+
+- OFAC 主页：https://ofac.treasury.gov/
+- SDN 列表：https://ofac.treasury.gov/specially-designated-nationals-and-blocked-persons-list-sdn-human-readable-lists
+- 数据格式：https://ofac.treasury.gov/sdn-list/sanctions-list-search-tool
+- 合规指南：https://ofac.treasury.gov/recent-actions