1 files changed, 41 insertions, 0 deletions
diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md
new file mode 100644
index 0000000..26db279
--- /dev/null
+++ b/docs/api-reference/README.md
@@ -0,0 +1,41 @@
+# 中文 API / 模块说明（api-reference）
+
+本目录为《活着的村庄》玩家可见代码模块的系统性中文说明，面向维护者与验收者。
+每条口径以**当前源码**为准（F# 8 / .NET 8）；文档只描述既有实现，不发明接口。
+
+## 阅读约定
+
+- **单位**：模拟时间以 `tick` 为基本单位，`1 tick = 1/60 秒`；`1 模拟日 = 86,400 秒 = 5,184,000 tick`。
+  位置以**像素**为单位（`Sim.tilePixels = 32` 像素/瓦片）；地图以**瓦片**为单位。
+- **确定性**：世界推进只由 `World.Rng`（splitmix64 同源）与 `seed` 派生，禁止墙钟与 `System.Random`。
+- **性能**：只引用**实测**基准（`docs/evidence/p70-*.txt`），不外推、不宣称未测数字。
+- **交叉引用**：`docs/维护说明.md`（模块职责 / 状态不变量 / 已验证命令）、
+  `docs/chinese-village-art-direction.md`（中文与美术方向）。
+
+## 模块索引
+
+| 文件 | 覆盖模块 | 关键接口 |
+| --- | --- | --- |
+| `sim-kernel.md` | `LivingVillage.Kernel/Sim.fs` | `Sim.step`、`World`、`chat`、`trade`、`chooseDialogueWith` |
+| `map-and-mapgen.md` | `MapGen.fs`、`ProceduralMap.fs`、`MapSnapshot.fs` | `MapGen.generateWithSize`、`MapGen.serialize`、`MapSnapshot.renderPng` |
+| `rendering-desktop.md` | `Game.fs`、`VillageArt.fs`、`CjkGlyphAtlas.fs` | `LivingVillageGame` 主循环、`VillageArt.drawWorld`、`CjkGlyphAtlas.sourceRectangle` |
+| `interaction-and-trade.md` | `Interaction.fs`、`PlayerTrade.fs` | `M5Interaction.apply`、`M5View`、`PlayerTrade.buy/sell` |
+| `occupation.md` | `Occupation.fs` | `Occupation.saveToken`、`Occupation.dailyTaskOfWith`、`Occupation.applySignal` |
+| `world-save.md` | `WorldSave.fs` | `WorldSave.save/saveWith`、`WorldSave.loadFromFileWith` |
+
+## 统一小节口径
+
+每个模块文件固定包含六节：
+
+1. **职责**：一句话说明该模块负责什么、不负责什么。
+2. **对外 API 概览**：公开类型与函数的真实签名/语义。
+3. **单位与量纲**：输入/输出的单位、取值范围。
+4. **不变量**：可验收的硬约束。
+5. **失败分支**：错误/拒绝/异常路径与处理方式。
+6. **算法与性能取舍**：算法要点与**实测**性能引用。
+
+## 相关证据与基准
+
+- Kernel 吞吐 / GC：`docs/evidence/p70-kernel-baseline.txt`（`--performance-baseline`）。
+- Desktop 帧率 / 每帧分配：`docs/evidence/p70-analysis.txt`、`docs/evidence/p70-frames-sample.txt`。
+- 复跑：`bash scripts/bench-p70.sh /tmp/opencode/lv-p70`。