DATUMOJ 计划总览
把日本政府（其次是欧美）的公开数据先抓下来、存成带出处的本地资料库，再让 AI 在这个资料库上做检索、问答和分析。每个结论都要能追溯到某一次抓取的原始文件。
附：数据源目录 —— orbisdata.org 收录的 471 个官方数据资源地址，已按 50 个预设数据分析场景组织，支持关键字逐步筛选：orbisdata 资源目录 · 按数据场景分类 →
新：100 个多源数据融合分析案例 —— 每个案例至少引用 3 个官方数据源，把统计、贸易、遥感、金融等数据拼起来做知识发现，专为 aha moment 而写：100 个多源数据融合分析案例 →
新：30 个单源数据失真验证案例 —— 假设一个国家的某项数据可能作假，再用 3 个以上独立数据源交叉打假（镜像法／实物量锚点／卫星复核／统计指纹）；13 例有公开实证记录，17 例是假设设计：30 个单源数据失真验证案例 →
新：Hugging Face「government」数据集全量调查 —— 把 HF 上 389 个 government 关键词数据集全部盘点一遍：谁在做、都是什么、热度在哪，以及有没有人已经做过 datumoj 想做的事（结论：注册表与垂直登记库两个方向都是空白）：389 个数据集全量调查报告 →
版本路线图每个版本取一个家纹作代号；任务编号 DATUMOJ-<代号>-<序号>，号段按开发线分
0.1 · 当前已完成
IVY（蔦）
契约 → 法令链路 → 目录与统计 → AI 分析入口（第一阶段）。48 个任务全部执行并留有结果记录，里程碑 M1 / M2 / M3 与版本 tag 均已发布。
✓ 已完成 tag: v0.1.0-ivy
0.2 · 下一版本
TACHIBANA（橘）
日本扩面与持续运营：KKJ 采购公告与 PDF、省厅和自治体政策网页、BODIK、定时增量、抓取监控、每周变化报告。计划已定稿（草案 v0.1），任务待 IVY 契约二与执行器接口稳定后拆分。
计划阶段 计划: docs/plans/0.2-tachibana.md
0.3 · 远景
待定（候选：楓 Maple）
欧美扩面：data.europa.eu、Eurostat、英德法荷门户、Federal Register 等。IVY、TACHIBANA 完成后再细拆。
方向已定
IVY 里程碑（检查点）
M0 契约与地基 集成任务 IVY-105
契约审查通过；make test 全部通过；用回放样本完整走一遍“计划→抓取→存 raw→写 manifest”，失败和超上限都有记录。
M1 法令链路 ✓ tag v0.1.0-ivy-m1
真实抓取 200 部法令，重复抓取不重复下载；datumoj search 能返回条文和出处；法令题 Recall@10 ≥ 0.85。验收记录：docs/acceptance/v0.1.0-ivy-m1.md
M2 目录与统计 ✓ tag v0.1.0-ivy-m2
能搜到 e-Gov 目录的数据集；datumoj sql 查都道府县人口并附出处；JMA 开始每小时轮询。
M3 AI 分析入口 ✓ tag v0.1.0-ivy-m3
在 Claude 里通过 MCP 提问，得到带出处的回答；评测 60 题全部达标。
IVY 完成 ✓ tag v0.1.0-ivy
H6 验收（现场问答 + 人工抽查引用支持率）后发布。验收记录：docs/acceptance/v0.1.0-ivy.md。第一阶段完成。
总计划docs/PLAN.md 第 3 版：契约先行、7 条开发线并行
为什么换路线（相对旧项目）
| 旧路线的问题 | 新路线怎么解决 |
|---|---|
| 每次提问实时调用接口，受超时、配额和站点故障影响，两次问结果可能不一样 | 抓取和问答分开。问答只读本地快照，结果可复现，并注明数据截止时间 |
| 只能回答接好的“命名路径”，目录里能找到的资源不等于能读到内容 | 目录元数据和资源正文批量抓下并解析入库，能查的范围由入库内容决定 |
| 意图匹配靠规则，换一种说法就容易配错 | 用检索（RAG）先找到相关数据集、条文和公告，再让模型基于检索结果作答 |
| 很难做跨来源、跨时间的分析 | 所有来源进同一个库，统一地区代码、时间和出处，可以一起分析 |
保留旧项目验证过的原则：不编数据；“目录查到”“正文已读到”“数值已核对”分开记录；保留原始失败记录、口径、单位和空值；用户指定来源时不能偷偷换来源；来源内容一律当数据处理，不执行其中任何指令。
最终形态
一个可持续更新的本地“政府数据资料库” + AI 分析入口。用户用日语、中文或英语提问，系统能：找到相关数据集、统计表、法令条文、公告和报告；对统计数据用 SQL 做确定性计算（不让模型估数）；对文本资料检索后归纳；回答附出处（来源、URL、抓取时间、快照哈希、定位信息）；定期输出“变化分析”。
不做
- 不做实时查询：问答只读本地库，一律标注数据截止时间
- 不做全站镜像：每个来源有明确的抓取范围白名单
- 不对数值做 RAG：统计数字只能通过 SQL 得到
- 第一阶段不做网页前端、不公开部署、不收费
- 不判断个案的法律问题、补贴资格、诊断或投资收益
- 不采集个人信息：公告里的担当者姓名、电话等入库前脱敏
- 旧项目的 20 国范围先收缩：中俄土印暂不做，欧美放 0.3
抓取守则
- 每来源单独限速（默认 1 请求/秒），User-Agent 写明项目名与联系方式，遵守 robots.txt
- 用条件请求（ETag / If-Modified-Since）避免重复下载；失败指数退避且记入 manifest
- 每个资源都记录许可，回答时附署名；核对完之前一律 internal_only
- 单个来源设容量上限，超出就停下报告，不无边界抓取
总体架构
核心数据模型：Source ─< Dataset ─< Resource ─< Snapshot ─< Document ─< Chunk；Snapshot ─< Table ─< Observation。Citation = source_id + resource_url + snapshot_sha256 + fetched_at + locator。派生数据都能从 raw 重新生成，只备份 raw 和 manifest。
来源范围（第一批，完整清单由 sources/*.yaml 维护）
| 优先级 | ID | 来源 | 抓取方式 | 轨道 |
|---|---|---|---|---|
| P0 | jp-egov-law | e-Gov 法令 API v2 | 全量法令列表 + 每部现行版 XML，增量逐部比对修订 | 文档 |
| P0 | jp-egov-data | e-Gov 数据门户（CKAN） | 全量目录元数据，增量用活动接口，资源按白名单下载 | 目录 + 两轨 |
| P0 | jp-stat-dashboard | 统计 Dashboard API | 指标目录 + 精选指标全地区时间序列 | 结构化 |
| P1 | jp-estat-files | e-Stat 统计表文件（CSV / XLSX） | 精选表清单按 statInfId 下载 | 结构化 |
| P1 | jp-jma | 气象厅 XML（Atom feed） | 轮询长期 feed（每小时，只保留约 7 天） | 文档 + 结构化 |
| P1 | jp-kkj | 官公需情报门户 KKJ | 按发注日分日期段采集 + 关联 PDF（→ 0.2 TACHIBANA） | 文档 |
| P1 | jp-gov-web | 省厅和自治体政策网页（定向） | 种子 URL 清单，限定深度与域名（→ 0.2） | 文档 |
| P1 | jp-bodik | BODIK ODCS（CKAN） | 复用 CKAN 采集器 + DataStore（→ 0.2） | 目录 + 两轨 |
| P2 | jp-estat-api | e-Stat API v3 | 需 appId，先核实可用再排任务 | 结构化 |
| P2 | jp-ksj / jp-census / jp-mhlw / jp-abr | 国土数值信息、经济普查、医疗开放数据、ABR 地址 | 命名文件下载 | 结构化 |
欧美（0.3）：data.europa.eu、Eurostat SDMX、data.gov.uk、GovData、data.gouv.fr、data.overheid.nl、Federal Register、GovInfo / Data.gov、世界银行 WDI。优先顺序：EU 整体 → 美国 Federal Register → 英德法荷门户 → 需 Key 的来源。
七条开发线（+ 契约）
| 线 | 内容 | 拥有的目录 |
|---|---|---|
| 契约 | 数据模型、接口协议、假实现、日文文本工具 | core/models.py、core/contracts.py、testing/、text/ |
| A 抓取基础 | raw 存储、manifest、HTTP、注册表、执行器 | core/ 其余文件 |
| B 文档线 | 法令、JMA（0.2 起加 KKJ、PDF、网页） | crawlers/、parsers/ 对应文件 |
| C 统计线 | 表格、地区码、观测值库、Dashboard、e-Stat | tabular/、reference/、store/observations.py |
| D 目录线 | CKAN、目录存储与检索 | crawlers/ckan.py、store/catalog.py |
| E 检索线 | FTS、向量、混合检索、缺口状态 | index/、store/chunks.py |
| F 入口线 | 流水线、CLI、工具层、MCP | pipeline.py、cli.py、analysis/、mcp_server.py |
| G 评测线 | 评测框架、题库、回答规则 skill | eval/、skills/ |
并行原则：契约先行，各线只依赖契约不 import 别人的实现；假实现解耦（真实实现与假实现过同一套合格测试）；插件自动发现，不改共享登记文件；调度器并发上限 3，每任务预留 2GB 内存；验收全部离线（pytest + fixture）。
协作模式：Human × Agent人定方向与契约、守验收关；Agent 按七条线并行实现、自证合规；系统门禁让每一步留痕
泳道图按项目的实际流程绘制：契约定版 → 并行实现 → 交叉审查（异家族审）→ 检查点真实验收 → 打 tag 发布。SVG 原图：总体架构图 · 协作泳道图
0.1 IVY 任务清单共 48 个任务（原计划 32 个，执行中追加修复与运营任务 16 个），全部已执行并在仓库 results/ 留有记录
契约数据模型、接口协议、假实现、日文文本工具 · 3 个任务
| IVY-001 | 契约一：数据模型、locator、工具输出格式 | ✓ 结果已记录 |
| IVY-002 | 契约二：接口协议、插件自动发现、假实现与契约测试 | ✓ 结果已记录 |
| IVY-003 | 日文文本工具：解码、归一化、和历、数字注记 | ✓ 结果已记录 |
A 抓取基础raw 存储、manifest、HTTP、注册表、执行器 · 7 个任务
| IVY-101 | raw 存储：按内容寻址 | ✓ 结果已记录 |
| IVY-102 | manifest：抓取记录库（SQLite） | ✓ 结果已记录 |
| IVY-103 | 礼貌 HTTP 客户端：限速、条件请求、重试、上限、回放 | ✓ 结果已记录 |
| IVY-104 | 来源注册表 schema 与校验 | ✓ 结果已记录 |
| IVY-105 | 采集执行器：计划→抓取→落库→记录，带上限 | ✓ 结果已记录 |
| IVY-106 | 修复：单个文件超过单文件上限时只记失败、继续抓取，不再停掉整次采集 | ✓ 结果已记录 |
| IVY-107 | 抓取开关与调度：control.json、schedule tick/status/enable/disable、运行锁、launchd 安装 | ✓ 结果已记录 |
B 文档线法令、JMA 采集与解析 · 5 个任务
| IVY-201 | e-Gov 法令采集器 | ✓ 结果已记录 |
| IVY-202 | 法令 XML 解析器：按条切分，带层级和 locator | ✓ 结果已记录 |
| IVY-203 | JMA 长期 feed 采集器与解析器 | ✓ 结果已记录 |
| IVY-204 | 修复：法令解析器只处理现行版全文快照，列表和修订历史跳过 | ✓ 结果已记录 |
| IVY-205 | 修复：没有“条”、正文直接是“项”的法令也能解析 | ✓ 结果已记录 |
C 统计线表格、地区码、观测值库、Dashboard、e-Stat · 6 个任务
| IVY-301 | 表格读取：CSV / XLSX / ZIP，cp932，表头与注记 | ✓ 结果已记录 |
| IVY-302 | 地区码表：全国地方公共団体コード | ✓ 结果已记录 |
| IVY-303 | 观测值库：DuckDB + Parquet，只读 SQL 与出处回溯 | ✓ 结果已记录 |
| IVY-304 | 统计 Dashboard 采集器、分批规划与观测值转换 | ✓ 结果已记录 |
| IVY-305 | e-Stat 统计表文件采集器与两类版式转换 | ✓ 结果已记录 |
| IVY-306 | 修复观测值库只读查询的日文字面量错误（字节偏移误当字符下标） | ✓ 结果已记录 |
D 目录线CKAN、目录存储与检索 · 3 个任务
| IVY-401 | 通用 CKAN 采集器（e-Gov データポータル） | ✓ 结果已记录 |
| IVY-402 | 目录解析、目录存储与目录检索 | ✓ 结果已记录 |
| IVY-403 | 修复：CKAN 增量只以完整走完的全量为基准，上次没走完就退回全量 | ✓ 结果已记录 |
E 检索线FTS、向量、混合检索、缺口状态 · 5 个任务
| IVY-501 | chunk 存储与 FTS5 trigram 关键词索引 | ✓ 结果已记录 |
| IVY-502 | 向量索引：嵌入接口与 LanceDB | ✓ 结果已记录 |
| IVY-503 | 混合检索（RRF、多查询）与四种缺口状态 | ✓ 结果已记录 |
| IVY-504 | 修复：关键词检索按词拆分，不再把整条查询当一个短语 | ✓ 结果已记录 |
| IVY-505 | 修复：只有低相似度向量结果时判为零命中 | ✓ 结果已记录 |
F 入口线流水线、CLI、工具层、MCP、管理页面 · 9 个任务
| IVY-601 | 解析与索引流水线（增量，基于插件发现） | ✓ 结果已记录 |
| IVY-602 | 命令行：crawl / parse / index / search / sql / status | ✓ 结果已记录 |
| IVY-603 | 分析工具层：search / catalog / sql / chunk / cite / version / coverage | ✓ 结果已记录 |
| IVY-604 | MCP 服务器（stdio） | ✓ 结果已记录 |
| IVY-605 | 修复：解析失败的快照下次要重试，不再当作已处理 | ✓ 结果已记录 |
| IVY-607 | 修复：向量嵌入失败不能让解析失败；可用环境变量关闭向量 | ✓ 结果已记录 |
| IVY-608 | 修复：MCP 服务器的工具调用固定在同一个线程，SQLite 不再跨线程报错 | ✓ 结果已记录 |
| IVY-609 | 修复：已成功下载的目录资源要标为“已抓取正文” | ✓ 结果已记录 |
| IVY-610 | 抓取管理页面：datumoj admin（仅本机），总开关、各来源开关、状态与立即运行 | ✓ 结果已记录 |
G 评测线评测框架、题库、回答规则 · 7 个任务
| IVY-701 | 评测框架：题库格式、全部指标、门槛 | ✓ 结果已记录 |
| IVY-702 | 法令评测题 20 道 | ✓ 结果已记录 |
| IVY-703 | 目录与统计评测题 20 道 | ✓ 结果已记录 |
| IVY-704 | 缺口、时间、跨语言、注入评测题 + 回答规则 skill | ✓ 结果已记录 |
| IVY-705 | 修复：统计题 tokyo-ict 的 SQL 补上经营组织维度 | ✓ 结果已记录 |
| IVY-706 | 修复：数值出现率同时认 SQL 结果的出处行 | ✓ 结果已记录 |
| IVY-707 | 修复：评测框架按题型取证（目录题认目录检索、数值题取 SQL 出处、时间题认施行日） | ✓ 结果已记录 |
集成版本检查点集成与验收 · 3 个任务
| IVY-901 | 检查点 M1 集成：法令链路端到端，法令题达标 | ✓ 结果已记录 |
| IVY-902 | 检查点 M2 集成：目录、统计、JMA 接入，统计题达标 | ✓ 结果已记录 |
| IVY-903 | 检查点 M3 集成：工具层接真实实现、MCP、60 题全部门槛（IVY 完成线） | ✓ 结果已记录 |
主对话步骤（H，人来做）
- H0 骨架与依赖：pyproject、依赖一次锁定、Makefile、空包目录，uv lock 后离线可装
- H1 录制测试样本：各线负责人按来源录制真实响应小样本进 tests/fixtures/（公开仓库只提交许可允许再分发的样本，个人信息先脱敏）
- H2 契约审查与 M0 检查点：全体审契约；A 线完成后回放走通全链路
- H3 M1 验收：真实抓取 200 部法令、现场检索、验收记录、打 tag
- H4 M2 验收：目录/Dashboard/e-Stat 真实抓取，SQL 查人口核对数值，JMA 定时轮询开始
- H5 嵌入模型选型：Ollama + bge-m3 与纯关键词对比 Recall@10，结论写 ADR-0001
- H6 M3 与 IVY 版本验收：MCP 注册、现场 10 问、人工抽查 20 条引用支持率（目标 ≥ 0.95）、打 tag v0.1.0-ivy
0.2 TACHIBANA 计划草案 v0.1（2026-10-20）· 把资料库扩到采购公告和政策网页，并让它每天自动增量更新、每周告诉人有什么变化
完成标准
- KKJ 采购公告入库：按日期增量采集；附件 PDF 按页切块、能引用到页码；担当者个人信息入库前脱敏
- 政策网页入库：种子清单内页面及链接 PDF 按节切块；SPA 外壳和空页面能识别，不当作成功
- BODIK 入库：复用 CKAN 采集器 + DataStore 读取
- 定时增量：按来源频率自动运行，休眠唤醒补跑，防重入锁；失败率异常时 datumoj status 提醒
- 每周变化报告：data/reports/ 生成 Markdown，按来源列新增/修改/删除/失败，每条带出处
- 评测：新增 KKJ、政策网页、变化、脱敏四类题 25 题以上，与 IVY 的 60 题一起全部达标
- 真实问答验收：能回答“大阪市 AI 创业支援策”“近期大阪有哪些 IT 采购”——旧项目答不出的两个问题，回答带出处
先行的契约修订（由人审查）
- ChangeEvent：变化事件（新增/修改/删除/抓取失败/解析失败），能引用到快照
- Redaction：脱敏记录（类别、locator、占位符），原文不入库
- Document.kind：law / notice / html_page / pdf / dataset / bulletin，检索可按类型过滤
- 快照父子关系：公告或网页 → 附件 PDF
任务草稿（约 18 个，接口稳定后再写成任务文件）
| 号 | 线 | 内容 | 依赖（IVY） | 审查 |
|---|---|---|---|---|
| 001 | 契约 | 契约修订：ChangeEvent、Redaction、Document.kind、快照父子关系 | 002 | human |
| 101 | A | 定时：schedule 命令（launchd / cron）、防重入锁、运行记录 | 105 | other_family |
| 102 | A | 抓取监控与 status 提醒 | 101 | other_family |
| 201 | B | PDF 解析器（按页切块、needs_ocr、加密和损坏处理） | 002、003 | other_family |
| 202 | B | HTML 正文抽取与分节切块、日期抽取、SPA 外壳识别 | 002、003 | other_family |
| 203 | B | KKJ 采集器（日期分段、满 1000 条自动二分、附件任务） | 105 | other_family |
| 204 | B | KKJ 公告解析与脱敏 | 001、003 | human |
| 205 | B | 政策网页定向采集器（种子、深度、域名、robots、URL 规范化） | 105 | other_family |
| 401 | D | BODIK：CKAN 复用 + DataStore 读取 | 401 | other_family |
| 601 | F | 变化检测（ChangeEvent 生成） | 001、601 | other_family |
| 602 | F | 每周变化报告与 report 命令 | 601 | other_family |
| 603 | F | 工具层与 MCP：list_changes、search_notices | 001、603/604 | other_family |
| 701 | G | 评测题：KKJ 10、政策网页 10、变化 5、脱敏与注入 3 | 701 | human |
| 702 | G | 回答规则更新：采购和政策问答（不判断资格和中标） | 704 | human |
| 901 | 集成 | 检查点 m1：KKJ + PDF 端到端 | 201、203、204 | human |
| 902 | 集成 | 检查点 m2：政策网页 + BODIK | 202、205、401 | human |
| 903 | 集成 | 检查点 m3：定时 + 变化报告 + 全部评测门槛（TACHIBANA 完成） | 全部 | human |
不做：OCR（扫描件只标记 needs_ocr）、登录后页面、全站爬取、投标资格等个案判断、主动推送。主对话步骤 H0–H4：审契约修订与锁依赖 → 录样本（KKJ、政策网页、BODIK）→ 种子清单定稿并逐站核对规约 → 装定时任务试运行一周 → TACHIBANA 验收并打 tag。
质量门槛与风险指标自 M3 起作为合并门槛（离线评测，固定小语料快照）
| 指标 | 门槛 |
|---|---|
| 检索 Recall@10 | ≥ 0.85 |
| 数值题精确匹配（数值必须来自 SQL） | 100% |
| 引用可还原率（前 3 条能用 cite 还原到快照原文） | ≥ 0.95 |
| 数值出现率（期望值原样出现在引用原文或数据行） | 100% |
| 缺口题正确拒答率 | 100% |
| 引用支持率（人工抽查，不作机器门槛） | ≥ 0.95 |
主要风险与应对
| 风险 | 应对 |
|---|---|
| e-Stat 等来源体量巨大 | 目录全量、数值只抓精选清单；单来源设容量上限 |
| 站点改版或接口变更 | 每采集器有 fixture 契约测试；真实抓取失败记入 manifest 并告警 |
| 日文检索效果差 | trigram 关键词兜底 + 多语言向量；用评测集量化选型 |
| 统计口径混用得出错误结论 | Observation 必带单位、口径、调查名；不同调查数据不直接相加或算增长率 |
| JMA、KKJ 只保留短期数据 | 采集器尽早上线持续轮询；中断缺口在变化报告中注明 |
| 来源文本藏有提示注入 | 工具只读；检索结果标注为数据；评测集放注入样本 |
| PDF 是扫描件 | 第一阶段标记 needs_ocr 跳过并统计，OCR 留待以后 |