DATUMOJ 计划总览

版本路线图每个版本取一个家纹作代号；任务编号 DATUMOJ-<代号>-<序号>，号段按开发线分

IVY 里程碑（检查点）

总计划docs/PLAN.md 第 3 版：契约先行、7 条开发线并行

为什么换路线（相对旧项目）

保留旧项目验证过的原则：不编数据；“目录查到”“正文已读到”“数值已核对”分开记录；保留原始失败记录、口径、单位和空值；用户指定来源时不能偷偷换来源；来源内容一律当数据处理，不执行其中任何指令。

最终形态

一个可持续更新的本地“政府数据资料库” + AI 分析入口。用户用日语、中文或英语提问，系统能：找到相关数据集、统计表、法令条文、公告和报告；对统计数据用 SQL 做确定性计算（不让模型估数）；对文本资料检索后归纳；回答附出处（来源、URL、抓取时间、快照哈希、定位信息）；定期输出“变化分析”。

总体架构

            ┌──────── sources/*.yaml 来源注册表（范围、许可、频率、抓取策略）────────┐
            ▼                                                                        │
 ① 抓取 crawl ──► ② 原始库 raw（按内容哈希存放，不可变，manifest 记录每次抓取）       │
                          │                                                          │
                          ▼                                                          │
                 ③ 解析 parse（按格式分流）                                          │
             ┌────────────┴─────────────┐                                            │
             ▼                          ▼                                            │
   ④a 结构化轨道                ④b 文档轨道                                          │
   表格/统计 → Parquet+DuckDB   法令/公告/PDF/HTML → 文本块 chunks（带定位信息）        │
             │                          │                                            │
             │                          ▼                                            │
             │                 ⑤ 索引：关键词（日文 n-gram）+ 向量，混合检索          │
             └────────────┬─────────────┘                                            │
                          ▼                                                          │
         ⑥ 分析层：工具化的 AI（search_docs / search_catalog / query_sql / cite）      │
              入口：MCP 服务器（主）+ CLI；批量报告（变化分析）                         │
                          ▼                                                          │
         ⑦ 评测：离线问答集，衡量检索召回、出处正确、数值精确 ◄──────────────────────┘

核心数据模型：Source ─< Dataset ─< Resource ─< Snapshot ─< Document ─< Chunk；Snapshot ─< Table ─< Observation。Citation = source_id + resource_url + snapshot_sha256 + fetched_at + locator。派生数据都能从 raw 重新生成，只备份 raw 和 manifest。

来源范围（第一批，完整清单由 sources/*.yaml 维护）

欧美（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 的来源。

七条开发线（+ 契约）

并行原则：契约先行，各线只依赖契约不 import 别人的实现；假实现解耦（真实实现与假实现过同一套合格测试）；插件自动发现，不改共享登记文件；调度器并发上限 3，每任务预留 2GB 内存；验收全部离线（pytest + fixture）。

0.1 IVY 任务清单共 48 个任务（原计划 32 个，执行中追加修复与运营任务 16 个），全部已执行并在仓库 results/ 留有记录

契约数据模型、接口协议、假实现、日文文本工具 · 3 个任务

A 抓取基础raw 存储、manifest、HTTP、注册表、执行器 · 7 个任务

B 文档线法令、JMA 采集与解析 · 5 个任务

C 统计线表格、地区码、观测值库、Dashboard、e-Stat · 6 个任务

D 目录线CKAN、目录存储与检索 · 3 个任务

E 检索线FTS、向量、混合检索、缺口状态 · 5 个任务

F 入口线流水线、CLI、工具层、MCP、管理页面 · 9 个任务

G 评测线评测框架、题库、回答规则 · 7 个任务

集成版本检查点集成与验收 · 3 个任务

主对话步骤（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 个，接口稳定后再写成任务文件）

不做：OCR（扫描件只标记 needs_ocr）、登录后页面、全站爬取、投标资格等个案判断、主动推送。主对话步骤 H0–H4：审契约修订与锁依赖 → 录样本（KKJ、政策网页、BODIK）→ 种子清单定稿并逐站核对规约 → 装定时任务试运行一周 → TACHIBANA 验收并打 tag。

质量门槛与风险指标自 M3 起作为合并门槛（离线评测，固定小语料快照）

主要风险与应对