把各模块说明从 README 拆到 Doc，并用索引替代 Doc/README。

Co-authored-by: Cursor <cursoragent@cursor.com>

Doc/README.md

@@ -1,9 +0,0 @@
-# Doc
-
-设计文档，不是编译目标。
-
-| 文件 | 内容 |
-|---|---|
-| [`初步计划.md`](初步计划.md) | 定案：子集 ST、toml 工程、寄存器 VM、执行模型、ST 子集；第 12 节为分阶段实现顺序 |
-
-仓库根目录 [`README.md`](../README.md) 只说明目录和模块边界；语言规则、映像与扫描周期的细节以本目录为准。

Doc/compiler/编译管线.md

@@ -0,0 +1,26 @@
+# 编译管线
+
+compiler 模块：ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 [`指令与映像.md`](../isa/指令与映像.md)。
+
+读齐工程后走直通 pass，产出单一映像，不上 LLVM。词法、语法、符号表、检查、codegen、链接都留在本库，不再拆 CMake 子库。
+
+语言规则、toml 字段、链接与第 12 节阶段见 [`初步计划.md`](../初步计划.md)。指令和映像只认 [`指令与映像.md`](../isa/指令与映像.md)。
+
+## 管线
+
+```text
+读 toml、收齐 .st
+  → 词法 / 递归下降语法
+  → 收集导出符号
+  → 解析 VAR_EXTERNAL、链接、定地址
+  → 类型检查
+  → 按 PROGRAM / FUNCTION / FB 编寄存器码
+  → 回填跳转、写映像头与工程哈希
+```
+
+## 边界
+
+- toml **不声明变量**；`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`
+- `[[io.*]]` 的 `var` 必须已在 GVL 中；同名全局链接失败
+- 第三方 toml 解析放 `third_party/`，本库私有链接
+- 不写扫描周期，不链 `vm`

Doc/host/宿主入口.md

@@ -0,0 +1,18 @@
+# 宿主入口
+
+host 模块：可执行入口。CMake 目标：`host`（`EXECUTABLE`），链接 `compiler` 和 `vm`。
+
+第一版一条命令：读工程 → 编译映像 → 按扫描周期跑。不拆独立的编译器可执行文件。总顺序见 [`初步计划.md`](../初步计划.md) 第 12.10 节。
+
+## 职责
+
+- 读 `project.toml` 和其中的 `.st`，交给 `compiler`
+- 按 `[[io.input]]` / `[[io.output]]` 采样 I、写回 Q（不创造变量）
+- 把 `dt_ms` 交给 VM，推进 `TON` / `TOF` / `CTU`
+- 单步、看寄存器和映像、按录制的 `I` 回放
+
+## 边界
+
+- 指令编码见 [`指令与映像.md`](../isa/指令与映像.md)
+- ST 解析与链接见 [`编译管线.md`](../compiler/编译管线.md)
+- 寄存器执行循环见 [`扫描周期.md`](../vm/扫描周期.md)

Doc/vm/扫描周期.md

@@ -0,0 +1,22 @@
+# 扫描周期
+
+vm 模块：寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 [`指令与映像.md`](../isa/指令与映像.md)。
+
+运行时是 **一台 VM、一个入口、一份映像**。不链接 `compiler`。扫描周期与确定性见 [`初步计划.md`](../初步计划.md) 第 2、8 节。
+
+## 扫描周期
+
+```text
+1. 按 toml 的 io 绑定，采样 → I / 输入全局
+2. 从 PROGRAM MAIN 的 pc=0 执行到 RET
+3. 写回 Q / 输出全局
+4. 用本周期 Δt 推进 TON / TOF / CTU（不用 wall clock）
+```
+
+## 边界
+
+- 只认 `isa` 映像；类型与溢出按 [`指令与映像.md`](../isa/指令与映像.md)（`INT` 饱和）
+- 局部 / `VAR` = 固定寄存器；`nregs` 在函数头
+- `CALL` 目标是立即数 `fn_id`，有界调用栈
+- 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制
+- I/O 从哪来、Δt 谁给、回放怎么喂，属于 `host`

Doc/索引.md

@@ -0,0 +1,23 @@
+# 文档索引
+
+设计文档，不是编译目标。全工程定案在根下；各 CMake 模块一个文件夹，文件名标明用途。
+
+```text
+doc/
+  索引.md
+  初步计划.md
+  isa/指令与映像.md
+  compiler/编译管线.md
+  vm/扫描周期.md
+  host/宿主入口.md
+```
+
+| 路径 | 内容 |
+|---|---|
+| [`初步计划.md`](初步计划.md) | 全工程定案：子集 ST、toml、执行模型、第 12 节阶段 |
+| [`isa/指令与映像.md`](isa/指令与映像.md) | 指令、映像、定宽类型、饱和；**规范以此为准** |
+| [`compiler/编译管线.md`](compiler/编译管线.md) | 编译器边界与管线 |
+| [`vm/扫描周期.md`](vm/扫描周期.md) | 扫描周期与 VM 边界 |
+| [`host/宿主入口.md`](host/宿主入口.md) | 可执行入口：编译 + 跑周期 |
+
+代码目录里的 README 只作入口；类型、指令、映像以 `isa/指令与映像.md` 为准。

README.md

@@ -2,7 +2,7 @@
 
 子集 ST + 扫描周期虚拟机。IEC 风格的子集 ST：用 `project.toml` 组织多个 `.st`，编译成单一映像，由寄存器虚拟机按扫描周期执行。
 
-方案见 [`Doc/初步计划.md`](Doc/初步计划.md)。
+方案见 [`Doc/初步计划.md`](Doc/初步计划.md)，模块文档见 [`Doc/索引.md`](Doc/索引.md)。
 
 ```text
 多个 .st

compiler/README.md

@@ -2,27 +2,4 @@
 
 ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 `isa`。
 
-读齐工程后走直通 pass，产出单一映像，不上 LLVM。词法、语法、符号表、检查、codegen、链接都留在本库，不再拆 CMake 子库。
+边界与管线见 [`doc/compiler/编译管线.md`](../doc/compiler/编译管线.md)。语言规则见 [`doc/初步计划.md`](../doc/初步计划.md)。
-
-## 管线
-
-```text
-读 toml、收齐 .st
-  → 词法 / 递归下降语法
-  → 收集导出符号
-  → 解析 VAR_EXTERNAL、链接、定地址
-  → 类型检查
-  → 按 PROGRAM / FUNCTION / FB 编寄存器码
-  → 回填跳转、写映像头与工程哈希
-```
-
-## 工程文件
-
-toml **不声明变量**，只做三件事：列出源文件、指定唯一 GVL、（可选）把已声明的全局接到硬件。
-
-- 字段：`files` / `entry` / `cycle_limit` / `dt_ms` / `gvl.file` / 可选 `io.*`
-- 第一版只有 `gvl.file` 允许出现 `VAR_GLOBAL`
-- `[[io.*]]` 的 `var` 必须已在 GVL 中声明，否则编译错误
-- 同名 `VAR_GLOBAL` 链接失败，禁止覆盖
-
-第三方 toml 解析放在 `third_party/`，本库私有链接。

host/README.md

@@ -2,15 +2,4 @@
 
 可执行入口。CMake 目标：`host`（`EXECUTABLE`），链接 `compiler` 和 `vm`。
 
-第一版一条命令：读工程 → 编译映像 → 按扫描周期跑。不拆独立的编译器可执行文件。
+职责与边界见 [`doc/host/宿主入口.md`](../doc/host/宿主入口.md)。
-
-## 职责
-
-- 读 `project.toml` 和其中的 `.st`，交给 `compiler`
-- 按 `[[io.input]]` / `[[io.output]]` 采样 I、写回 Q
-- 把 `dt_ms` 交给 VM，推进 `TON` / `TOF` / `CTU`
-- 单步、看寄存器和映像、按录制的 `I` 回放
-
-## 不放什么
-
-指令编码（`isa`）、ST 解析与链接（`compiler`）、寄存器执行循环（`vm`）。

vm/README.md

@@ -2,23 +2,4 @@
 
 寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 `isa`。
 
-运行时是 **一台 VM、一个入口、一份映像**。不链接 `compiler`。
+扫描周期与边界见 [`doc/vm/扫描周期.md`](../doc/vm/扫描周期.md)。
-
-## 扫描周期
-
-```text
-1. 按 toml 的 io 绑定，采样 → I / 输入全局
-2. 从 PROGRAM MAIN 的 pc=0 执行到 RET
-3. 写回 Q / 输出全局
-4. 用本周期 Δt 推进 TON / TOF / CTU（不用 wall clock）
-```
-
-## 约束
-
-- 局部 / `VAR` = 固定寄存器；`nregs` 写在函数头
-- `I` / `Q` / `M` 走映像指令，不是通用寄存器
-- FB 实例固定布局，字段偏移编译期算死
-- `CALL` 目标是立即数 `fn_id`，有界调用栈
-- 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制
-
-I/O 从哪来、Δt 谁给、回放怎么喂，属于 `host`。