Theory Ingest

/theory-ingest

把一篇理论建模论文拆成可复用的研究资产。对着「理论建模通用骨架」的 6 个固定槽位抽取：环境/原语、解概念、结果、论证、比较静态、可检验推论。形式化陈述逐字引用，禁止释义。

Inputs

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

Outputs

• wiki/papers/{slug}.md（paper_kind: theory）
• 按需新建或更新：
  • wiki/assumptions/*.md
  • wiki/propositions/*.md
  • wiki/hypotheses/*.md（模型导出的可检验推论）
  • wiki/mechanisms/*.md（填 ## Theoretical Logic，与实证层共享）
  • wiki/foundations/*.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

理论论文公式密集，.tex 优先：有 .tex 源码就用源码，公式不会被 PDF 解析毁掉。只有 PDF 时先人工读第一页标题：

"$PYTHON_BIN" - "<source>" <<'PY'
import sys, fitz
doc = fitz.open(sys.argv[1])
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 作为正文读取入口。

Step 2: Extract Along the 6-Slot Skeleton

先打开 docs/runtime-theory-skeleton.zh.md，对着 6 个固定槽位抽取。没有明确证据写“未报告”，不猜：

1. 环境 / 原语：参与人、行动/策略空间、偏好/支付函数、信息结构、时序、技术/约束
2. 解概念：均衡概念（Nash / 子博弈精炼 / 贝叶斯精炼 / 竞争均衡 …）
3. 结果：每个命题/定理/引理的形式化陈述 + 成立条件
4. 论证：每个结果的证明技术
5. 比较静态：内生量随参数怎么动
6. 可检验推论：模型导出的、可拿去实证的符号关系

理论论文没有 variables/datasets/identification/robustness——这些不是填“未报告”，而是整块不存在。这是与 /empirical-ingest 的根本分流。

Step 3: Write Pages

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

papers/{slug}.md 设 paper_kind: theory，填 theory block，正文用理论段落：

## 研究问题
## 模型环境
## 核心假设
## 解概念
## 命题与证明
## 比较静态
## 可检验推论
## 对实证的启发
## Related

• 每条核心假设 → assumptions/，formal_statement 逐字引用原文
• 每个命题/定理 → propositions/，formal_statement 逐字引用，conditions 写清成立条件，proof_technique 查不到写“未报告”
• 每条可检验推论 → hypotheses/（status: literature_supported）
• 模型形式化的经济机制 → 查重后更新 mechanisms/ 的 ## Theoretical Logic 段；不要新造与实证侧重复的机制页
• 解概念、证明框架等可复用规范知识 → foundations/（终端节点，不写反向链接）

每次新建前先查重：

"$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 assumptions/<a> --type assumes --evidence "<原文位置>"
"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from papers/<paper> --to propositions/<p> --type proves --evidence "<命题编号>"
"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from papers/<paper> --to mechanisms/<m> --type formalizes_mechanism --confidence high --evidence "<evidence>"
"$PYTHON_BIN" tools/research_wiki.py add-edge wiki --from propositions/<p> --to hypotheses/<h> --type predicts --confidence high --evidence "<evidence>"

• assumes、proves：结构事实，不带 --confidence
• formalizes_mechanism、predicts：判断，必须带 --confidence high|medium|low
• derived_from（论文 → foundation）按需使用
• 实证论文检验本理论的推论时，实证侧的 tests_hypothesis / tests_mechanism 反向边由 /empirical-ingest 写；本 skill 只负责理论侧的正向边与双向链接同步

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

最后报告：

• 新增/更新了哪些页面（按 6 槽位分组）
• 抽出的可检验推论是否已与既有实证论文/机制接上桥
• 哪些命题或机制可服务当前选题

Constraints

• 形式化陈述逐字引用，禁止释义：命题、假设的成立条件不得改写（把“对所有凹效用函数”写成“对效用函数”是灾难）。
• 不编造证明技术、参数符号、均衡结果；查不到写“未报告”。
• propositions/ 装被证明的形式化结果，不与 claims/（带置信度的实证断言）混用。
• mechanisms/、hypotheses/ 与实证层共享：先查重，优先更新既有页面的理论侧，不另造近义页。
• 纯计算/仿真（agent-based）模型偏实验性质，落 experiments/，不进 propositions/。
• .tex 优先。raw/papers/ 是用户输入，不覆盖、不移动。
• 中文/英文理论论文没有 arXiv/S2 元数据时不视为失败，以正文为准。