---
name: theory-ingest
description: 将一篇理论建模论文摄取为理论研究 wiki：论文卡片 + 假设/原语 + 命题/定理 + 解概念 + 可检验推论，并与实证层在同一张 graph 上接桥
argument-hint: "<local-pdf-or-tex-path> [--topic <research-topic>]"
---

# /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`：

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

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

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

然后运行：

```bash
"$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，正文用理论段落：

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

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

每次新建前先查重：

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

### Step 4: Add Graph Edges

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

```bash
"$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

```bash
"$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 元数据时不视为失败，以正文为准。


---
Source attribution: Lambenthan
Original project: https://github.com/Lambenthan/empiricalwiki/blob/7b9bcbb92049b9e0a23d43f86a455537ce042560/.claude/skills/theory-ingest/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 OmegaWiki Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: Lambenthan
Original project: https://github.com/Lambenthan/empiricalwiki/blob/7b9bcbb92049b9e0a23d43f86a455537ce042560/.claude/skills/theory-ingest/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Education & Research
Roles: Academic Writer, Data Scientist, Researcher
Specialties: API
Tools: Python
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 0cb384d78c390883c3c451236536da774a8fa6568e624984452fd3c2891bd21f