empiricalwiki

# EmpiricalWiki — Runtime Schema

> 面向经管、会计、金融、管理、经济学实证研究的垂类 LLM Wiki。由 Claude Code 驱动。
> 本文件是 wiki 的运行时入口，定义页面结构、链接规范、workflow 约束。

---

## 仓库布局

需要完整仓库树时，再打开 `docs/runtime-directory-structure.zh.md`。

平时请优先记住这个心智地图：

### `wiki/` 是主要工作面

- `wiki/index.md` 是所有 wiki 页面的目录
- `wiki/log.md` 是 append-only 活动日志
- `wiki/papers/` 存放实证论文结构化卡片
- `wiki/variables/`、`wiki/datasets/`、`wiki/models/`、`wiki/mechanisms/`、`wiki/hypotheses/`、`wiki/identification/`、`wiki/robustness/`、`wiki/heterogeneity/`、`wiki/tables/` 存放实证研究设计层
- `wiki/assumptions/`、`wiki/propositions/` 存放理论建模层（模型原语与形式化结论）；与 `wiki/mechanisms/`、`wiki/hypotheses/` 共同把理论与实证接在同一张 graph 上
- `wiki/concepts/`、`wiki/topics/`、`wiki/foundations/` 存放可复用知识结构
- `wiki/people/`、`wiki/ideas/`、`wiki/experiments/`、`wiki/claims/` 存放研究者、假设、实验和断言
- `wiki/Summary/` 存放领域级综述
- `wiki/outputs/` 存放生成产物
- `wiki/graph/` 是派生状态，禁止手动编辑
- 想把 wiki 看成带图谱/搜索/反链的本地网站：跑 `tools/view.sh`，详见 `docs/view-quartz.zh.md`（基于 Quartz，只读渲染，不改内容）

### 格式护栏

- 在新建或修复 wiki 页面结构、YAML、正文章节前，先打开 `docs/runtime-page-templates.zh.md`
- 需要 graph 派生文件细节或 `index.md` / `log.md` 格式时，打开 `docs/runtime-support-files.zh.md`
- `SKILL.md` 是 skill 的即时入口；较大的 skill 也可以在各自目录下提供按需读取的本地参考文件
- `/init` 是这一模式的第一个具体例子：先读 `.claude/skills/init/SKILL.md`，只有在需要时再打开 `.claude/skills/init/references/*`

### `raw/` 与 `config/`

- `raw/papers/`、`raw/notes/`、`raw/web/` 是用户自有输入
- `raw/discovered/` 存放 `/init` 与 `/daily-arxiv` 抓取的外部论文
- `raw/tmp/` 存放 `/init` 与直接本地 `/ingest` 使用的生成型 prepared sidecar
- `config/` 存放环境与远程服务器模板

---

## 页面类型

实证研究核心类型：`papers`、`variables`、`datasets`、`models`、`mechanisms`、`hypotheses`、`identification`、`robustness`、`heterogeneity`。`/empirical-ingest` 自动产出这九类。

理论建模核心类型：`assumptions`（模型原语：参与人/偏好/信息/时序/约束）、`propositions`（形式化结论：命题/定理/引理）。`papers` 用 `paper_kind: empirical|theory|both` 区分范式，决定 ingest 走 `/empirical-ingest` 还是 `/theory-ingest`。

按需类型（有模板与目录，但只在特定 skill 或用户明确要求时才创建页面，平时为空是正常状态）：

- `tables` — 仅当用户要求逐表复现某篇论文时建页；日常 ingest 把关键表格结论写进论文卡即可。
- `concepts`、`people`、`claims` — 由通用 `/ingest` 与 `/novelty`、`/review` 维护；纯实证流程可能始终为空。
- `ideas`、`experiments` — 由 `/ideate`、`/exp-design`、`/exp-run` 维护；经管实证优先用 `models/` + `identification/` + `robustness/`，`experiments/` 留给计算实验与仿真。
- `topics`、`Summary` — 由 `/prefill`、`/survey` 维护。
- `foundations` — 由 `/prefill` 预填教科书背景，终端节点不写反向链接。

页面模板看 `docs/runtime-page-templates.zh.md`；理论建模 6 槽位骨架看 `docs/runtime-theory-skeleton.zh.md`；graph/index/log 参考看 `docs/runtime-support-files.zh.md`。

---

## 链接语法

所有内部链接使用 Obsidian wikilink：

```markdown
[[slug]]                    ← 链接到本 wiki 内任意页面
[[patient-capital]] ← 链接到 variables/patient-capital.md 或 concepts/patient-capital.md
[[耐心资本]]        ← 中文实证论文允许使用 CJK slug
```

**命名规范**：英文全小写、连字符分隔、无空格；中文标题允许保留 CJK 字符。

---

## Cross Reference 规则

写正向链接时**必须同步写反向链接**：

| 正向操作 | 必须同步的反向操作 |
|----------|-------------------|
| papers/A 写 `Related: [[concept-B]]` | concepts/B 的 `key_papers` 追加 `A` |
| papers/A 写 `[[researcher-C]]` | people/C 的 `Key papers` 追加 `A` |
| papers/A 写 `supports: [[claim-D]]` | claims/D 的 `evidence` 追加 `{source: A, type: supports}` |
| papers/A 写 `operationalizes: [[variable-V]]` | variables/V 的 `source_papers` 追加 A |
| papers/A 写 `uses_dataset: [[dataset-D]]` | datasets/D 的 `source_papers` 追加 A |
| papers/A 写 `estimates_model: [[model-M]]` | models/M 的 `source_papers` 追加 A |
| papers/A 写 `tests_mechanism: [[mechanism-M]]` | mechanisms/M 的 `source_papers` 或 `evidence` 追加 A |
| papers/A 写 `tests_hypothesis: [[hypothesis-H]]` | hypotheses/H 的 `source_papers` 追加 A |
| papers/A 写 `addresses_endogeneity_with: [[identification-I]]` | identification/I 的 `source_papers` 追加 A |
| papers/A 写 `uses_robustness_check: [[robustness-R]]` | robustness/R 的 `source_papers` 追加 A |
| papers/A 写 `uses_heterogeneity_split: [[heterogeneity-H]]` | heterogeneity/H 的 `source_papers` 追加 A |
| papers/A 写 `assumes: [[assumption-X]]` | assumptions/X 的 `source_papers` 追加 A |
| papers/A 写 `proves: [[proposition-P]]` | propositions/P 的 `source_papers` 追加 A |
| papers/A 写 `formalizes_mechanism: [[mechanism-M]]` | mechanisms/M 的 `source_papers` 或 `evidence` 追加 A（理论侧），并在 `## Theoretical Logic` 补理论来源 |
| propositions/P 写 `predicts: [[hypothesis-H]]` | hypotheses/H 的 `source_papers` 追加 P，并在 `## Literature Basis` 标注理论来源 |
| topics/T 写 `key_people: [[person-D]]` | people/D 的 `Research areas` 追加 T |
| concepts/K 写 `key_papers: [[paper-E]]` | papers/E 的 `Related` 追加 `K` |
| concepts/K 写 part_of `[[topic-F]]` | topics/F 的概述段落追加 `K` |
| ideas/I 写 `origin_gaps: [[claim-C]]` | claims/C 的 `## Linked ideas` 追加 I |
| experiments/E 写 `target_claim: [[claim-C]]` | claims/C 的 `evidence` 追加 `{source: E, type: tested_by}` |
| claims/C 写 `source_papers: [[paper-P]]` | papers/P 的 `## Related` 追加 C |
| 任意页面链接到 `[[foundation-X]]` | **不写反向链接** — foundations 是终端节点：接收来自 papers/concepts 等页面的入链，但不写 `key_papers` 或任何反向引用字段 |

---

## Graph 规则

- `graph/` 是自动生成目录，不要手动编辑
- 核心派生文件是 `edges.jsonl`、`citations.jsonl`、`context_brief.md`、`open_questions.md`
- semantic edge type 包括 paper-paper（`same_problem_as`、`similar_method_to`、`complementary_to`、`builds_on`、`compares_against`、`improves_on`、`challenges`、`surveys`）、paper-concept（`introduces_concept`、`uses_concept`、`extends_concept`、`critiques_concept`）、实证抽取（`operationalizes`、`uses_dataset`、`estimates_model`、`tests_mechanism`、`tests_hypothesis`、`addresses_endogeneity_with`、`uses_robustness_check`、`uses_heterogeneity_split`、`reports_table`）、理论抽取（`assumes`、`proves`、`formalizes_mechanism`、`predicts`），以及既有 claim/experiment/provenance 类型（`supports`、`contradicts`、`tested_by`、`invalidates`、`addresses_gap`、`derived_from`、`inspired_by`）
- `/ingest` 产生的 paper-paper 与 paper-concept semantic edge 必须带 `confidence: high|medium|low`
- `/theory-ingest` 的 `assumes`、`proves` 是结构事实，不带 confidence；`formalizes_mechanism`、`predicts` 是判断，必须带 `confidence: high|medium|low`
- 对称 paper-paper edge 只存一行，endpoint 按顺序排序，并写 `symmetric: true`
- bibliographic citation 存在 `citations.jsonl`，`type: cites`
- 用 `tools/research_wiki.py add-edge`、`add-citation`、`rebuild-context-brief`、`rebuild-open-questions` 维护

## log.md 格式

标准日志行：

```markdown
## [YYYY-MM-DD] skill | details
```

## Python 环境

- 有 `.venv/` 时优先用 `.venv/bin/python`（Unix/macOS）或 `.venv/Scripts/python.exe`（Windows）
- 否则使用当前激活的 conda 环境
- 再否则回退到 `python3`（Unix/macOS）或 `python`（Windows）
- Python 工具会通过 `tools/_env.py` 自动加载 `~/.env` 与项目根目录 `.env`

---

## 约束

- **`raw/papers/`、`raw/notes/`、`raw/web/` 归用户所有**：把它们当作权威输入。`/init` 与 `/daily-arxiv` 只能把外部抓取论文追加到 `raw/discovered/`。`/init` 与直接本地 `/ingest` 可以把生成的本地预处理 sidecar 写到 `raw/tmp/`（只增不改，绝不覆盖用户自有文件）。`/edit` 仅在用户明确要求时才允许新增 raw 来源。`/init` 在 INIT MODE 下 fan-out 的 `/ingest` 子代理仍必须把 `raw/` 视为严格只读，并直接消费交接的 canonical path。
- **skill 的用户可见参数归用户所有**：skill 的 `argument-hint` 中列出的 flag 与取值属于用户命令，而不是 agent 可自行决定的策略开关。不得仅根据仓库状态擅自补出、切换或删除这些参数。若用户未提供某个参数，只有在该 skill 明确写出省略时的默认或推导规则时，才可使用该默认或推导值；否则应保持未设置，必要时询问用户。不是用户可见参数的内部派生设置，skill 仍可自行推断。
- **INIT MODE 交接由 manifest 驱动**：当 `/init` 写出 `.checkpoints/init-sources.json` 后，该 manifest 就是 ingest 顺序与规范来源路径的唯一真相来源。预处理后的本地输入应指向 `raw/tmp/`；外部引入论文应指向 `raw/discovered/`。
- **graph/ 自动生成**：不得手动编辑 `graph/` 下的文件，仅通过 `tools/research_wiki.py` 维护。
- **严禁在工作仓库切换到 demo 分支**：wiki 内容在 main 上是被忽略的工作区文件、在 demo 上是被跟踪文件，`git switch demo` 再切回会让 git 删光工作区 wiki。更新 demo 一律用 `tools/update_demo.sh`（plumbing 实现，不动 checkout）。
- **实证抽取优先**：阅读实证论文时，先抽取变量、数据来源、模型设定、理论机制、异质性、稳健性和识别策略，再写通用概念或 idea。
- **理论抽取优先**：阅读理论建模论文（`paper_kind: theory`）时，对着 `docs/runtime-theory-skeleton.zh.md` 的 6 槽位先抽取假设/原语、命题/定理、解概念、可检验推论，再写通用概念或 idea。形式化陈述逐字引用，禁止释义改写成立条件。
- **双向链接**：写正向链接时同步写反向链接。
- **tex 优先**：.tex > .pdf，fallback 链：tex 失败 → PDF 解析，PDF 失败 → vision API。
- **index.md 每次 ingest 立即更新**，log.md append-only。
- **lint 默认只报告**：`--fix` 自动修复确定性问题（xref 反向链接、缺失字段默认值）；`--suggest` 输出非确定性问题的建议供用户批准；`--fix --dry-run` 预览修复。
- **slug 生成规则**：论文标题关键词，连字符连接；英文全小写，中文标题允许保留 CJK 字符。
- **importance 评分**：1 = niche, 2 = useful, 3 = field-standard, 4 = influential, 5 = seminal。
- **idea 失败必须记录原因**：`failure_reason` 字段是反重复记忆，防止重复探索已知死路。
- **claim confidence 区间**：0.0-1.0，evidence 每次变动时重新评估。
- **实验模块对经管实证是可选项**：Stata 式实证流程优先使用 `models/`、`tables/`、`identification/` 和 `robustness/`。`experiments/` 仅保留给计算实验、仿真或机器学习任务。
- **DeepXiv token**：`DEEPXIV_TOKEN` 环境变量。未设置时 SDK 自动注册（写入 `~/.env`）。免费额度 10,000 请求/天。DeepXiv 不可用时所有 skill 自动回退到 S2+RSS 模式。

---

## Skills

| Skill | 文件 | 触发 |
|-------|------|------|
| `/setup` | `.claude/skills/setup/SKILL.md` | 手动（首次配置） |
| `/reset` | `.claude/skills/reset/SKILL.md` | 手动（`--scope wiki\|raw\|log\|checkpoints\|all`） |
| `/init` | `.claude/skills/init/SKILL.md` | 手动 |
| `/prefill` | `.claude/skills/prefill/SKILL.md` | 手动（`[domain] [--add concept]`） |
| `/ingest` | `.claude/skills/ingest/SKILL.md` | 手动 |
| `/empirical-ingest` | `.claude/skills/empirical-ingest/SKILL.md` | 手动 |
| `/theory-ingest` | `.claude/skills/theory-ingest/SKILL.md` | 手动 |
| `/variable-map` | `.claude/skills/variable-map/SKILL.md` | 手动 |
| `/empirical-design` | `.claude/skills/empirical-design/SKILL.md` | 手动 |
| `/stata-plan` | `.claude/skills/stata-plan/SKILL.md` | 手动 |
| `/discover` | `.claude/skills/discover/SKILL.md` | 手动 / 内部（`/ingest --discover` 时调用） |
| `/ask` | `.claude/skills/ask/SKILL.md` | 手动 |
| `/edit` | `.claude/skills/edit/SKILL.md` | 手动 |
| `/check` | `.claude/skills/check/SKILL.md` | 每两周/手动 |
| `/daily-arxiv` | `.claude/skills/daily-arxiv/SKILL.md` | 手动（可自行配置 cron） |
| `/novelty` | `.claude/skills/novelty/SKILL.md` | 手动 |
| `/review` | `.claude/skills/review/SKILL.md` | 手动 |
| `/ideate` | `.claude/skills/ideate/SKILL.md` | 手动 |
| `/exp-design` | `.claude/skills/exp-design/SKILL.md` | 手动 |
| `/exp-run` | `.claude/skills/exp-run/SKILL.md` | 手动（`<slug> [--collect] [--full] [--env local\|remote]`） |
| `/exp-status` | `.claude/skills/exp-status/SKILL.md` | 手动（`[--pipeline <slug>] [--collect-ready] [--auto-advance]`） |
| `/exp-eval` | `.claude/skills/exp-eval/SKILL.md` | 手动 |
| `/refine` | `.claude/skills/refine/SKILL.md` | 手动 |
| `/paper-plan` | `.claude/skills/paper-plan/SKILL.md` | 手动 |
| `/paper-draft` | `.claude/skills/paper-draft/SKILL.md` | 手动 |
| `/paper-compile` | `.claude/skills/paper-compile/SKILL.md` | 手动 |
| `/survey` | `.claude/skills/survey/SKILL.md` | 手动 |
| `/research` | `.claude/skills/research/SKILL.md` | 手动 |
| `/rebuttal` | `.claude/skills/rebuttal/SKILL.md` | 手动 |