@baimingtao/lbs-agent 1.0.0

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

@@ -0,0 +1,88 @@
+# OpenCorporates — 全球企业注册数据库
+
+## 1. 摘要
+
+OpenCorporates 汇总了来自全球 130 多个司法管辖区（约 2 亿家公司）的企业注册数据。涵盖美国州级备案（NY DOS、Delaware DOC、California SOS 等）、UK Companies House、EU 注册机构以及大多数普通法系司法管辖区。
+
+## 2. 访问方式
+
+- **REST API:** `https://api.opencorporates.com/v0.4/`
+- **HTML fallback:** `https://opencorporates.com/companies?q=...`
+- **Auth:** 需要 API token（免费层级每月 500 次调用，提供付费方案）
+- **Rate limit:** 绑定 token；无 token 的请求返回 401
+
+设置 `OPENCORPORATES_API_TOKEN` 环境变量。可在 https://opencorporates.com/api_accounts/new 获取免费 token。
+
+## 3. Data Schema
+
+由 `fetch_opencorporates.py` 输出的关键字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `name` | str | 公司法定名称 |
+| `company_number` | str | 注册机构分配的编号 |
+| `jurisdiction_code` | str | 例如 `us_ny`, `us_de`, `gb` |
+| `jurisdiction_name` | str | 可读的司法管辖区名称 |
+| `incorporation_date` | str | YYYY-MM-DD |
+| `dissolution_date` | str | YYYY-MM-DD（如为存续状态则为空） |
+| `company_type` | str | Domestic LLC / Foreign Corp 等 |
+| `status` | str | Active / Inactive / Dissolved |
+| `registered_address` | str | 注册办事处地址 |
+| `opencorporates_url` | str | 指向 OpenCorporates 实体页面的链接 |
+| `officers_count` | str | 备案在册的高管总数 |
+| `source` | str | `api`, `html`, 或 `html-fallback` |
+
+## 4. 覆盖范围
+
+- 美国：覆盖所有 50 个州 + DC 的州级层面（LLC、corp、LP）
+- 国际：UK、EU、Canada、Australia、NZ，以及许多 APAC + LATAM 司法管辖区
+- 累计约 2 亿条公司记录
+- 更新频率因司法管辖区而异（UK CH 接近实时；部分州级注册机构会有几个月的延迟）
+
+## 5. 交叉关联潜力
+
+- **NYC ACRIS** ↔ `name`（NYC 房产的 LLC/corp 所有者）
+- **USAspending** ↔ `name`（企业联邦承包商）
+- **SEC EDGAR** ↔ `name`（上市公司及其子公司）
+- **ICIJ Offshore** ↔ `name`（跨国企业架构）
+
+关联键（Join key）：规范化的公司名称。部分条目包含 `previous_names` 数组，但目前的抓取脚本尚未导出此项 —— 若需获取该数据请直接查询 OC。
+
+## 6. 数据质量
+
+- 公司名称的拼写可能会因重新注册或更名而产生差异
+- 高管记录的完整度通常不如公司记录（许多司法管辖区不要求披露高管信息）
+- 实际所有权（Beneficial-ownership）数据通常不包含在此处 —— 大多数司法管辖区不作此要求。UK Companies House 拥有 PSC（拥有重大控制权的人员）数据，但这并不普遍。
+- 跨司法管辖区的关联（母公司/子公司）仅基于注册备案文件；企业架构树通常不完整
+
+## 7. 获取脚本
+
+路径: `scripts/fetch_opencorporates.py`
+
+```bash
+# 按名称进行全局搜索
+python3 SKILL_DIR/scripts/fetch_opencorporates.py --query "Example Corp" \
+    --out data/oc.csv
+
+# 限定至特定司法管辖区
+python3 SKILL_DIR/scripts/fetch_opencorporates.py --query "Example Corp" \
+    --jurisdiction us_ny --out data/oc_ny.csv
+
+# 通过环境变量或标志设置 token
+OPENCORPORATES_API_TOKEN=xxx python3 SKILL_DIR/scripts/fetch_opencorporates.py \
+    --query "Microsoft" --out data/oc.csv
+```
+
+如果没有 token，脚本将回退到抓取 HTML 搜索页面。这种回退机制非常脆弱，且只能填补 `name`、`jurisdiction_code` 和 `opencorporates_url` —— 若用于严谨的工作，请务必设置 token。
+
+## 8. 法律与许可
+
+- OpenCorporates 汇总的是公开记录 —— 其底层事实属于公共领域
+- OpenCorporates 自有的数据库采用 CC-BY-SA-4.0 许可；需注明出处
+- API 服务条款禁止重新分发完整数据集；但允许按单条记录进行引用
+
+## 9. 参考资料
+
+- API 文档: https://api.opencorporates.com/documentation/API-Reference
+- 司法管辖区代码: https://api.opencorporates.com/v0.4/jurisdictions.json
+- Schema: https://opencorporates.com/info/our_data

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

@@ -0,0 +1,80 @@
+# SEC EDGAR — 公司披露文件
+
+## 1. 概要
+
+EDGAR (Electronic Data Gathering, Analysis, and Retrieval) 是 SEC 的系统
+用于公司披露文件：10-K (年度)，10-Q (季度)，8-K (当前事件)，DEF 14A (委托书)，Form 4 (内幕交易)，13F (机构持仓)。
+
+## 2. 访问方式
+
+- **API:** `https://data.sec.gov/submissions/CIK<10-digit-padded>.json` (无需认证)
+- **文件索引:** `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=...`
+- **全文搜索:** `https://efts.sec.gov/LATEST/search-index?q=...`
+- **认证:** 无 — 根据 SEC 政策要求提供包含联系信息的 `User-Agent` header
+- **频率限制:** 每个 IP 10 次请求/秒 (严格执行)
+
+## 3. 数据结构
+
+`fetch_sec_edgar.py` 输出的主要字段 (文件索引):
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `cik` | str | Central Index Key (10 位补零) |
+| `company_name` | str | 注册人名称 |
+| `form_type` | str | 10-K, 10-Q, 8-K 等 |
+| `filing_date` | str | YYYY-MM-DD |
+| `accession_number` | str | 提交 accession (例如 0000320193-24-000123) |
+| `primary_document` | str | 主要文档的文件名 |
+| `filing_url` | str | 指向文件索引的直接 URL |
+| `reporting_period` | str | 报告期 (如适用) |
+
+## 4. 覆盖范围
+
+- 包含自 1993 年至今的所有美国上市注册人
+- 1993-2000 年期间的早期文件覆盖不完整 (纸质到电子化的过渡期)
+- 累计约 1200 万份文件
+- 在文件被受理后几分钟内即更新
+
+## 5. 交叉引用潜力
+
+- **USAspending** ↔ `company_name` (上市公司作为联邦承包商)
+- **Senate LD** ↔ `company_name` (上市公司雇佣游说者)
+- **OFAC SDN** ↔ `company_name` (对上市注册人进行制裁筛查)
+
+关联键：公司名称，或者你有的话也可以用 CIK。CIK 是规范且稳定的标识。
+
+## 6. 数据质量
+
+- 子公司通常挂在母公司 CIK 下提交 — 匹配名称时需小心
+- 名称会随时间变化 (品牌重塑、收购) — CIK 保持不变
+- 10-K Item 1A Risk Factors 是自由格式文本 — 适用于 `web_extract` 风格的解析，不适用于结构化查询
+- 外国私人发行人提交 20-F 而非 10-K
+
+## 7. 获取脚本
+
+路径：`scripts/fetch_sec_edgar.py`
+
+```bash
+# 按 CIK 获取
+python3 SKILL_DIR/scripts/fetch_sec_edgar.py --cik 0000320193 \
+    --types 10-K,10-Q --out data/edgar_filings.csv
+
+# 按公司名称获取 (首先通过名称搜索解析为 CIK)
+python3 SKILL_DIR/scripts/fetch_sec_edgar.py --company "APPLE INC" \
+    --types 8-K --since 2024-01-01 --out data/edgar_filings.csv
+```
+
+设置 `SEC_USER_AGENT` 环境变量并填入你的联系邮箱 (SEC 要求)。
+示例：`SEC_USER_AGENT="Research example@example.com"`。
+
+## 8. 法律与许可
+
+- 属于根据 SEC Rule 24b-2 / 17 CFR § 230.401 规定的公开记录
+- 文件内容无商业使用限制
+- SEC 要求所有批量数据用户在请求中包含带有联系信息的 `User-Agent`，并遵守 10 次/秒的频率限制 — 不遵守可能会导致 IP 被封禁
+
+## 9. 参考资料
+
+- 开发者文档：https://www.sec.gov/edgar/sec-api-documentation
+- EDGAR 全文搜索：https://efts.sec.gov/LATEST/search-index
+- 公平访问政策：https://www.sec.gov/os/accessing-edgar-data

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

@@ -0,0 +1,85 @@
+# 参议院 LD — Lobbying Disclosure (LD-1 / LD-2)
+
+## 1. 摘要
+
+参议院公共记录办公室根据《1995年游说披露法》（LDA，经 HLOGA 2007 修订）发布游说披露信息。LD-1 是新客户与说客关系的注册；LD-2 是季度活动报告。
+
+## 2. 访问方式
+
+- **API:** `https://lda.senate.gov/api/v1/`（只读无需认证）
+- **批量下载:** `https://lda.senate.gov/api/v1/filings/?format=csv`（分页获取）
+- **认证:** 超过 120 次请求/小时需要 Token — 在 https://lda.senate.gov/api/auth/register/ 注册
+- **速率限制:** 未认证 120 次请求/小时，认证后 1,200 次请求/小时
+
+## 3. 数据模式
+
+`fetch_senate_ld.py` 输出的主要字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `filing_uuid` | str | 唯一的备案 ID |
+| `filing_type` | str | LD-1, LD-2, LD-203 等 |
+| `filing_year` | int | 年份 |
+| `filing_period` | str | Q1/Q2/Q3/Q4 或年度 |
+| `registrant_name` | str | 游说公司或组织 |
+| `registrant_id` | str | 参议院分配的注册人 ID |
+| `client_name` | str | 被代表的客户 |
+| `client_id` | str | 参议院分配的客户 ID |
+| `client_general_description` | str | 客户行业 / 业务 |
+| `income` | float | 本季度来自客户的 LD-2 收入 (USD) |
+| `expenses` | float | LD-2 支出（内部游说） |
+| `lobbyists` | str | 分号分隔的说客姓名 |
+| `issues` | str | 分号分隔的问题领域 |
+| `government_entities` | str | 联系过的机构/部门 |
+| `filing_date` | str | YYYY-MM-DD |
+
+## 4. 覆盖范围
+
+- 仅限美国联邦游说（州游说由各州道德办公室处理）
+- 1999 年至今（2008 年起实现全面的电子化覆盖）
+- 季度报告周期（LD-2）
+- 累计超过 100 万份备案
+
+## 5. 交叉引用潜力
+
+- **USAspending** ↔ `client_name`（为合同进行游说的客户）
+- **SEC EDGAR** ↔ `client_name`（作为游说客户的上市公司）
+- **OFAC SDN** ↔ `client_name`（对游说客户进行制裁筛查）
+
+关联键：标准化后的 client_name。在关联参议院内部记录时，registrant_id 和 client_id 是标准标识。
+
+## 6. 数据质量
+
+- 许多说客姓名随着时间的推移出现在多个注册人中（由于工作变动）
+- `issues` 和 `government_entities` 是自由文本 — 大小写不一致
+- 外国代理人根据 FARA（司法部）注册，而不是在此处
+- 在一些较早的备案中，收入/支出以 10,000 美元的区间报告
+
+## 7. 获取脚本
+
+路径: `scripts/fetch_senate_ld.py`
+
+```bash
+# By client
+python3 SKILL_DIR/scripts/fetch_senate_ld.py --client "EXAMPLE CORP" \
+    --year 2024 --out data/lobbying.csv
+
+# By registrant (lobbying firm)
+python3 SKILL_DIR/scripts/fetch_senate_ld.py --registrant "BIG K STREET LLP" \
+    --year 2024 --out data/lobbying.csv
+```
+
+如果你有 Token，请设置 `SENATE_LDA_TOKEN` 环境变量（或传递 `--token`）。
+默认为匿名访问（120 次请求/小时）。
+
+## 8. 法律与许可
+
+- 2 U.S.C. § 1604 (LDA) 规定的公共记录
+- 无商业使用限制
+- 无条件重复使用 — 参见参议院公共记录办公室免责声明
+
+## 9. 参考资料
+
+- API 文档: https://lda.senate.gov/api/redoc/v1/
+- LDA 指南: https://lobbyingdisclosure.house.gov/ld_guidance.pdf
+- 参议院公共记录: https://lda.senate.gov/

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

@@ -0,0 +1,90 @@
+# USAspending — 联邦政府合同与拨款
+
+## 1. 摘要
+
+USAspending.gov 是联邦支出数据的官方来源。覆盖范围：合同、拨款、贷款、直接付款、子奖项。根据 2014 年的 DATA Act 要求——所有联邦机构必须按照统一的 schema 进行报告。
+
+## 2. 访问方式
+
+- **API v2:** `https://api.usaspending.gov/api/v2/` (无需 auth，无需 key)
+- **Bulk:** `https://files.usaspending.gov/` (按 award 类型提供 CSV / Parquet)
+- **Auth:** 无
+- **Rate limit:** 未严格限制，但请保持礼貌 — 保持在 <10 req/s
+
+## 3. 数据 Schema
+
+由 `fetch_usaspending.py` 输出的关键字段 (prime awards):
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `award_id` | str | 联邦 award ID (合同为 PIID，拨款为 FAIN) |
+| `recipient_name` | str | 获奖者法定名称 |
+| `recipient_uei` | str | Unique Entity Identifier (2022 年替代了 DUNS) |
+| `recipient_duns` | str | 旧版 DUNS 编号 (仅限历史数据) |
+| `recipient_parent_name` | str | 最终母公司组织 |
+| `recipient_state` | str | 获奖者所在州 |
+| `awarding_agency` | str | 部门 / 机构名称 |
+| `awarding_sub_agency` | str | 子级机构 (例如 DoD → 陆军) |
+| `award_type` | str | 合同 / 拨款 / 贷款 / 直接付款 |
+| `award_amount` | float | 当前总承担金额 (美元) |
+| `award_date` | str | 行动 / 签署日期 YYYY-MM-DD |
+| `period_of_performance_start` | str | YYYY-MM-DD |
+| `period_of_performance_end` | str | YYYY-MM-DD |
+| `naics_code` | str | 行业分类 |
+| `psc_code` | str | 产品 / 服务代码 |
+| `competition_extent` | str | 完全竞标 / 限制竞标 / 独家来源 |
+| `description` | str | award 描述 (自由文本) |
+
+## 4. 覆盖范围
+
+- 仅限美国联邦奖项 (不包括州/地方数据)
+- 财年 2008 → 至今 (从财年 2017 起完全覆盖)
+- 根据机构报告每两周更新一次
+- 累计超过 1 亿条交易记录
+
+## 5. 交叉引用潜力
+
+- **SEC EDGAR** ↔ `recipient_name` (作为承包商的上市公司)
+- **Senate LD** ↔ `recipient_name` (获得合同的游说客户)
+- **OFAC SDN** ↔ `recipient_name` (承包商的制裁筛查 — 虽然应该已经被 SAM.gov 过滤，但请进行验证)
+- **ICIJ Offshore** ↔ `recipient_name` (与离岸相关的承包商)
+
+Join key：标准化的获奖者名称。如果存在，UEI 为权威标识。
+
+## 6. 数据质量
+
+- DUNS → UEI 过渡 (2022 年 4 月) — 旧记录包含 DUNS，新记录包含 UEI
+- 部分子奖项未报告 (FFATA 阈值为 $30k)
+- Award 金额随时间变化 (mod actions) — 抓取脚本报告的是当前总额
+- `competition_extent` 字段在旧记录中是自由文本 — `fetch_usaspending.py` 会将其标准化为规范值
+- 获奖者名称的变体非常多 — "ACME LLC", "Acme L.L.C.", "ACME, INC" 都可能出现。请使用 `entity_resolution.py`。
+
+## 7. 采集脚本
+
+路径：`scripts/fetch_usaspending.py`
+
+```bash
+# By recipient name
+python3 SKILL_DIR/scripts/fetch_usaspending.py --recipient "EXAMPLE CORP" \
+    --fy 2024 --out data/contracts.csv
+
+# By awarding agency
+python3 SKILL_DIR/scripts/fetch_usaspending.py --agency "Department of Defense" \
+    --fy 2024 --out data/contracts.csv
+
+# Filter to sole-source only
+python3 SKILL_DIR/scripts/fetch_usaspending.py --recipient "EXAMPLE CORP" \
+    --fy 2024 --sole-source-only --out data/contracts.csv
+```
+
+## 8. 法律与许可
+
+- 根据《联邦资金问责与透明度法案》(FFATA, 2006) 和 DATA Act (2014) 属于公共记录
+- 数据无商业使用限制
+- 奖项接收者的个人身份信息 (例如某些拨款中小企业主的地址) 应根据来源机构的隐私声明进行处理
+
+## 9. 参考
+
+- API 文档: https://api.usaspending.gov/
+- 数据字典: https://www.usaspending.gov/data-dictionary
+- Award schema: https://files.usaspending.gov/docs/Data_Dictionary_Crosswalk.xlsx

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

@@ -0,0 +1,87 @@
+# Wayback Machine — Internet Archive CDX
+
+## 1. Summary
+
+Internet Archive 的 Wayback Machine 自 1996 年以来已抓取约 9000 亿以上的网页。CDX server API 通过 URL、时间戳和内容哈希对这些抓取记录进行索引。免费、匿名、无需身份验证。
+
+## 2. Access Methods
+
+- **CDX server:** `https://web.archive.org/cdx/search/cdx`
+- **Wayback URL:** `https://web.archive.org/web/<timestamp>/<url>`
+- **Save Page Now (write):** `https://web.archive.org/save/<url>` (不同的 API)
+- **Auth:** 无
+- **Rate limit:** 宽松；请保持礼貌（约 1 req/s）
+
+## 3. Data Schema
+
+`fetch_wayback.py` 输出的关键字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `url` | str | 抓取的原始 URL |
+| `timestamp` | str | YYYYMMDDHHMMSS (CDX 格式) |
+| `wayback_url` | str | 直接回放 URL |
+| `mimetype` | str | 抓取时的 Content-type |
+| `status` | str | HTTP 状态码 (通常为 200) |
+| `digest` | str | 抓取内容的 SHA1 (支持折叠去重) |
+| `length` | str | 抓取内容的字节长度 |
+
+## 4. Coverage
+
+- 1996 年至今
+- 跨越约 7 亿个域名的 9000 亿以上的抓取记录
+- 通过自动爬虫和手动保存持续更新
+- 部分域名覆盖密集（如新闻），其他则较稀疏（如私人网站）
+
+## 5. Cross-Reference Potential
+
+- **Wikipedia** ↔ 反向查找被引用为参考来源但现已失效的页面
+- **News URLs** ↔ 在当前 URL 返回 404 时获取原始文章内容
+- **Corporate websites** ↔ 被删除的历史“关于”页面和高管简介
+
+当其他来源指向已不存在的 URL 时，Wayback CDX 作为**内容恢复**层最为实用。
+
+## 6. Data Quality
+
+- 被 robots.txt 屏蔽的域名可能覆盖不完整或无覆盖
+- 抓取内容的完整性参差不齐（可能只保存了 HTML 而没有 CSS/JS）
+- 部分内容因域名所有者要求（DMCA 等）被排除
+- 对“深层链接”（带查询字符串的 URL）的覆盖不均
+- 时间分辨率为每次抓取的时间点，而非连续——存在空白期很常见
+
+## 7. Acquisition Script
+
+路径：`scripts/fetch_wayback.py`
+
+```bash
+# All captures of a specific URL
+python3 SKILL_DIR/scripts/fetch_wayback.py --url "https://example.com/page" \
+    --out data/wb.csv
+
+# All captures of a host
+python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
+    --match host --out data/wb.csv
+
+# All captures of a domain + subdomains
+python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
+    --match domain --out data/wb.csv
+
+# Only unique-content captures within a date window
+python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
+    --match host --collapse digest \
+    --from-date 2020-01-01 --to-date 2023-12-31 \
+    --out data/wb.csv
+```
+
+## 8. Legal & Licensing
+
+- Internet Archive 的抓取基于合理使用研究条款
+- 回放 URL 是稳定的参考来源——鼓励引用
+- Internet Archive 的非营利性使用条款管辖内容
+- 部分内容受权利限制；即使 CDX 条目显示已抓取，回放仍可能被阻止
+
+## 9. References
+
+- CDX server docs: https://github.com/internetarchive/wayback/blob/master/wayback-cdx-server/README.md
+- Wayback API: https://archive.org/help/wayback_api.php
+- Internet Archive: https://archive.org/

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

@@ -0,0 +1,96 @@
+# Wikipedia + Wikidata
+
+## 1. Summary
+
+对于知名人物、地点和组织，Wikipedia 是权威的叙事与生平信息来源。Wikidata 则是其对应的结构化数据版本：包含约 1.1 亿个条目，每个条目均带有声明、日期、标识符，以及指向外部机构（VIAF、ISNI、ORCID、GRID 等）的交叉引用。
+
+它们共同构成了一个高精度的 entity-resolution 层 —— 收录门槛非常高，但只要越过该门槛，都有详尽的引用参考。
+
+## 2. Access Methods
+
+- **Wikipedia OpenSearch:** `https://en.wikipedia.org/w/api.php?action=opensearch`
+- **Wikipedia REST summary:** `https://en.wikipedia.org/api/rest_v1/page/summary/<title>`
+- **Wikidata Action API:** `https://www.wikidata.org/w/api.php?action=wbgetentities`
+- **Wikidata SPARQL:** `https://query.wikidata.org/sparql` （功能更强大，但有严格的 rate-limited）
+- **Auth:** 无，但**必须提供有意义的 User-Agent**
+
+将 `HERMES_OSINT_UA` 设置为具有标识性的内容（例如 `your-app/1.0 (you@example.com)`）。Wikimedia 会针对通用的 UA 返回 HTTP 429 错误。
+
+## 3. Data Schema
+
+由 `fetch_wikipedia.py` 输出的关键字段：
+
+| 列 | 类型 | 说明 |
+| -------- | ------ | ------------- |
+| `source` | str | `wikipedia` 或 `wikipedia+wikidata` |
+| `label` | str | Wikipedia 条目标题 |
+| `description` | str | 简短的 Wikidata 描述 |
+| `qid` | str | Wikidata QID（例如 Microsoft 的 Q2283） |
+| `wikipedia_title`, `wikipedia_url` | str | 条目标识符 + URL |
+| `wikidata_url` | str | Wikidata entity URL |
+| `instance_of` | str | 实体类型（P31） |
+| `country` | str | 国家（机构/地点为 P17，人物为 P27） |
+| `occupation` | str | P106 |
+| `employer` | str | P108 |
+| `date_of_birth` | str | P569, YYYY-MM-DD |
+| `place_of_birth` | str | P19 |
+| `summary` | str | Wikipedia REST 提取文本（约 1000 字符） |
+
+抓取脚本使用 Wikidata 的 Action API（而非 SPARQL）来获取结构化事实 —— 它对 rate limits 宽容得多。
+
+## 4. Coverage
+
+- Wikipedia EN：约 700 万篇条目
+- Wikidata：约 1.1 亿个条目，约 15 亿条声明
+- 持续更新；滥用过滤器和机器人会持续运行
+- 高 notability 门槛 —— 绝大多数普通个人不会出现在 Wikipedia 中
+
+## 5. Cross-Reference Potential
+
+- **所有来源** ↔ `label`（entity identity resolution）
+- **SEC EDGAR** ↔ `label`（上市公司）
+- **CourtListener** ↔ `label`（重大诉讼的当事人）
+- **Wikidata 外部标识符**（目前未包含在此抓取器的输出中）链接至 VIAF、ISNI、ORCID、GRID、GitHub、Twitter、IMDb 等...
+
+Join key：Wikidata QID 是规范标识。大多数 Wikipedia 条目标题是稳定的，但可能会被重命名。
+
+## 6. Data Quality
+
+- Notability 过滤器 —— 仅包含具有 notability 的实体（标准因主题而异）
+- 时效性滞后 —— 时事需要数天到数周时间才能反映出来
+- POV（观点争议）/ 蓄意破坏 —— 受到监管，但在巡查之间的编辑内容可能会存在问题
+- 在世人物传记具有更严格的来源要求
+- Wikidata 声明包含限定符和参考资料 —— 抓取脚本目前暂不导出它们
+
+## 7. Acquisition Script
+
+Path: `scripts/fetch_wikipedia.py`
+
+```bash
+# Look up a notable entity
+python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Microsoft" --out data/wp.csv
+
+# A specific person
+python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Bill Gates" --out data/wp_bg.csv
+
+# Skip the Wikidata enrichment for speed
+python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Microsoft" --no-wikidata \
+    --limit 5 --out data/wp.csv
+```
+
+OpenSearch 支持模糊查询 —— `--limit 5` 会返回前 5 个匹配的 Wikipedia 条目。除非传入 `--no-wikidata` 参数，否则每个结果都会通过 QID + 结构化事实进行补充。
+
+## 8. Legal & Licensing
+
+- Wikipedia 文本：CC-BY-SA-3.0 / GFDL
+- Wikidata 声明：CC0（公共领域）
+- API ToS：遵守 rate limits，标识您的 agent
+- 允许在署名的前提下进行商业使用
+
+## 9. References
+
+- Wikipedia OpenSearch: https://www.mediawiki.org/wiki/API:Opensearch
+- Wikipedia REST: https://en.wikipedia.org/api/rest_v1/
+- Wikidata Action API: https://www.wikidata.org/wiki/Wikidata:Data_access
+- Wikidata SPARQL: https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service
+- User-Agent policy: https://meta.wikimedia.org/wiki/User-Agent_policy

package/extensions/skills/optional/research/osint-investigation/scripts/_http.py

@@ -0,0 +1,82 @@
+"""Tiny stdlib HTTP helper used by fetch_*.py scripts.
+
+Provides polite retry + JSON convenience + User-Agent enforcement.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_UA = (
+    "hermes-osint-investigation/0.2 "
+    "(+https://github.com/NousResearch/hermes-agent; "
+    "set HERMES_OSINT_UA env var to identify yourself per "
+    "Wikimedia / SEC fair-use guidance)"
+)
+
+
+def get(
+    url: str,
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    user_agent: str | None = None,
+    max_retries: int = 3,
+    backoff: float = 1.5,
+    timeout: float = 30.0,
+) -> bytes:
+    """GET with retry on 5xx and Retry-After honoring.
+
+    429 (rate-limit) is raised IMMEDIATELY with a clear message — retrying
+    when the upstream says "you're over quota" just wastes time. The caller
+    should slow down or supply real credentials.
+    """
+    if params:
+        sep = "&" if "?" in url else "?"
+        url = f"{url}{sep}{urllib.parse.urlencode(params)}"
+    h = {"User-Agent": user_agent or os.environ.get("HERMES_OSINT_UA", DEFAULT_UA)}
+    if headers:
+        h.update(headers)
+
+    last_err: Exception | None = None
+    for attempt in range(max_retries + 1):
+        req = urllib.request.Request(url, headers=h)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                # 立即抛出。读取响应体以便调用者能看到
+                # provider 的实际消息（"OVER_RATE_LIMIT" 等）。
+                try:
+                    body = e.read(2048).decode("utf-8", errors="replace")
+                except Exception:  # noqa: BLE001
+                    body = ""
+                raise RuntimeError(
+                    f"HTTP 429 rate-limited by {urllib.parse.urlsplit(url).netloc}. "
+                    f"Slow down or supply a real API key. Body: {body[:300]}"
+                ) from e
+            if e.code in {500, 502, 503, 504} and attempt < max_retries:
+                retry_after = e.headers.get("Retry-After") if e.headers else None
+                wait = float(retry_after) if (retry_after and retry_after.isdigit()) else backoff ** (attempt + 1)
+                time.sleep(wait)
+                last_err = e
+                continue
+            raise
+        except urllib.error.URLError as e:
+            if attempt < max_retries:
+                time.sleep(backoff ** (attempt + 1))
+                last_err = e
+                continue
+            raise
+    if last_err:
+        raise last_err
+    raise RuntimeError("unreachable")
+
+
+def get_json(url: str, **kwargs) -> dict | list:
+    return json.loads(get(url, **kwargs).decode("utf-8"))

package/extensions/skills/optional/research/osint-investigation/scripts/_normalize.py

@@ -0,0 +1,67 @@
+"""Shared entity-name normalization helpers (stdlib-only).
+
+Used by entity_resolution.py and timing_analysis.py.
+"""
+from __future__ import annotations
+
+import re
+
+# 规范化处理时需要去除的合法后缀 / 公司样板文本。
+_SUFFIX_TOKENS = {
+    "INC", "INCORPORATED", "LLC", "LLP", "LP", "LTD", "LIMITED",
+    "CORP", "CORPORATION", "CO", "COMPANY",
+    "GROUP", "GRP", "HOLDINGS", "HOLDING",
+    "PARTNERS", "ASSOCIATES",
+    "INTERNATIONAL", "INTL",
+    "ENTERPRISES", "ENTERPRISE",
+    "SERVICES", "SERVICE", "SVCS",
+    "SOLUTIONS", "MANAGEMENT", "MGMT", "CONSULTING",
+    "TECHNOLOGY", "TECHNOLOGIES", "TECH",
+    "INDUSTRIES", "INDUSTRY",
+    "AMERICA", "AMERICAN",
+    "USA", "US",
+    "PLLC", "PC",
+    "TRUST", "FOUNDATION",
+}
+
+_PUNCT_RE = re.compile(r"[^\w\s]")
+_WS_RE = re.compile(r"\s+")
+
+
+def normalize_name(name: str | None) -> str:
+    """Standard normalization: uppercase, strip suffixes, drop punctuation."""
+    if not name:
+        return ""
+    s = _PUNCT_RE.sub(" ", name.upper())
+    s = _WS_RE.sub(" ", s).strip()
+    tokens = [t for t in s.split() if t and t not in _SUFFIX_TOKENS]
+    return " ".join(tokens)
+
+
+def normalize_aggressive(name: str | None) -> str:
+    """Aggressive normalization: sorted unique tokens (word-bag)."""
+    base = normalize_name(name)
+    if not base:
+        return ""
+    return " ".join(sorted(set(base.split())))
+
+
+def name_tokens(name: str | None, min_len: int = 4) -> set[str]:
+    """Token set used for overlap matching."""
+    base = normalize_name(name)
+    if not base:
+        return set()
+    return {t for t in base.split() if len(t) >= min_len}
+
+
+def token_overlap_ratio(left: str | None, right: str | None) -> tuple[float, int]:
+    """Return (jaccard-like ratio, shared token count) over min-len tokens."""
+    a = name_tokens(left)
+    b = name_tokens(right)
+    if not a or not b:
+        return 0.0, 0
+    shared = a & b
+    if not shared:
+        return 0.0, 0
+    union = a | b
+    return len(shared) / len(union), len(shared)