Empirical Ingest

/empirical-ingest

把一篇实证论文拆成可复用的研究设计资产。它不是普通摘要工具；优先抽取变量、数据、模型、机制、识别和稳健性，再写通用概念。

Inputs

• source: 本地 .pdf、.tex，或 /init 预处理后的 raw/tmp/... 路径。
• --topic 可选：当前项目主题，如“耐心资本与 ESG”。

Outputs

• wiki/papers/{slug}.md
• 按需新建或更新：
  • wiki/variables/*.md
  • wiki/datasets/*.md
  • wiki/models/*.md
  • wiki/mechanisms/*.md
  • wiki/hypotheses/*.md
  • wiki/identification/*.md
  • wiki/robustness/*.md
  • wiki/heterogeneity/*.md
  • wiki/tables/*.md（仅当用户明确要求逐表复现时创建；默认把关键表格及结论写进论文卡，不单独建页）
• wiki/index.md、wiki/log.md
• wiki/graph/edges.jsonl

Workflow

Step 1: Resolve Source

确认工作目录是项目根目录，包含 wiki/、raw/、tools/。

优先使用 .venv：

if [ -x .venv/bin/python ]; then PYTHON_BIN=.venv/bin/python; else PYTHON_BIN=python3; fi

如果输入是 PDF，先人工读取第一页标题。中文 PDF 可以用 PyMuPDF 快速抽取：

"$PYTHON_BIN" - "<source>" <<'PY'
import sys, fitz
path = sys.argv[1]
doc = fitz.open(path)
print(doc[0].get_text("text")[:2000])
PY

然后运行：

"$PYTHON_BIN" tools/prepare_paper_source.py --raw-root raw --source <source> --title "<confident-title>"

把返回的 prepared_path 作为正文读取入口。若标题不确定，不传 --title。

Step 2: Extract Empirical Facts

从论文中抽取以下字段。没有明确证据时写“未报告”，不要猜：

• 研究问题
• 理论机制
• 研究假设
• 样本区间、样本范围、样本筛选规则
• 数据来源和数据库表
• 被解释变量、核心解释变量、中介变量、调节变量、控制变量、工具变量
• 变量测算公式、分组规则、缩尾规则
• 主模型、固定效应、标准误聚类方式
• 内生性处理
• 机制检验、异质性检验、稳健性检验
• 关键表格及结论
• 可复现线索：变量名、数据库、Stata 处理步骤

Step 3: Write Pages

打开 docs/runtime-page-templates.zh.md，按模板写页面。

写 papers/{slug}.md 时，正文必须包含：

## 研究问题
## 理论机制
## 研究假设
## 数据与样本
## 变量设定
## 模型设定
## 主要结果
## 机制检验
## 异质性检验
## 稳健性检验
## 内生性处理
## 可复现线索
## 对我当前选题的启发
## Related

对每个核心变量、数据源、模型、机制和检验方法，先查重再创建新页面：

"$PYTHON_BIN" tools/research_wiki.py slug "<title>"

已有等价页面时更新，不重复造近义页面。

Step 4: Add Graph Edges

用工具写图谱关系，不手动编辑 wiki/graph/edges.jsonl：

"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from papers/<paper> --to variables/<variable> --type operationalizes --confidence high --evidence "<evidence>"
"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from papers/<paper> --to datasets/<dataset> --type uses_dataset --confidence high --evidence "<evidence>"
"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from papers/<paper> --to models/<model> --type estimates_model --confidence high --evidence "<evidence>"

其他边按需使用：tests_mechanism、tests_hypothesis、addresses_endogeneity_with、uses_robustness_check、uses_heterogeneity_split、reports_table。

Step 5: Rebuild and Report

"$PYTHON_BIN" tools/research_wiki.py rebuild-index wiki
"$PYTHON_BIN" tools/research_wiki.py rebuild-context-brief wiki
"$PYTHON_BIN" tools/research_wiki.py rebuild-open-questions wiki
"$PYTHON_BIN" tools/lint.py --wiki-dir wiki

最后报告：

• 新增/更新了哪些页面
• 还缺哪些信息
• 哪些变量或模型可以直接服务当前项目

Constraints

• 不要编造变量口径、模型公式、数据库表名。
• 中文论文没有 arXiv/Semantic Scholar 元数据时，不把这视为失败；以 PDF 正文和项目内文献为准。
• 实证论文优先抽取 variables/、datasets/、models/，不要只写通用 concepts/。
• raw/papers/ 是用户输入，不覆盖、不移动。