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

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

CMakeLists.txt

@@ -2,7 +2,7 @@
 cmake_minimum_required(VERSION 3.21)
 
 # 工程名、版本号、工程描述
-project(StScan
+project(Stator
         VERSION 0.1
         DESCRIPTION "子集 ST 编译为寄存器 VM，按扫描周期执行"
         LANGUAGES C CXX)

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/isa/指令与映像.md

@@ -0,0 +1,160 @@
+# 指令与映像
+
+isa 模块规范：指令集 + 映像 + 定宽类型。不是编译器，不把 `.st` 编成映像。
+
+`compiler` 按本文件写出字节，`vm` 只认这些字节。两边不互链。
+
+全工程定案见 [`初步计划.md`](../初步计划.md)。**类型、指令编码、映像布局以本文为准**，不要另写一份互相打架的表。头文件实现本文，不另当规范。
+
+```text
+host → compiler → isa
+host → vm       → isa
+```
+
+CMake 目标：`isa`（`STATIC`），无依赖。公开头：`isa/include/isa/`。
+
+---
+
+## 做 / 不做
+
+**做**
+
+- 操作码与 32 位指令布局
+- 映像头与段（函数字节码、全局 / FB 槽、工程哈希）
+- `BOOL` / `INT` / `TIME` 宽度与溢出规则
+- 编解码、工程哈希、一条指令的文本转储（给 host 打印）
+
+**不做**
+
+- toml 字段、关键字表、符号表、AST
+- 扫描周期循环、I/O 采样
+- 短路语义（`AND`/`OR` 指令只组合已算好的值；短路由 `compiler` 编成跳转）
+
+指令表可作为内部 IR 的文本形态，不必当主语言。
+
+---
+
+## 特性
+
+| 项 | 第一版 |
+|---|---|
+| `BOOL` | `uint8_t`，只允许 0/1 |
+| `INT` | `int16_t`（IEC `INT`） |
+| `TIME` | `int32_t` 毫秒；与 `INT` 不混用 |
+| 整数溢出 | **饱和**（夹到 `INT` 最小/最大） |
+| 字节序 | 小端 |
+| 指令宽度 | 32 bit，一种主布局 |
+| 寄存器 | 下标 0..255；每函数实际个数写在函数头 `nregs` |
+| 跳转 | 相对 offset，单位是**指令条数**，不是字节 |
+| `CALL` | 立即数 `fn_id`（u16），无函数指针 |
+| 映像魔数 | `STSC`，版本 `1` |
+| 工程哈希 | 源文件路径排序后对内容做 FNV-1a 64（非密码学） |
+| I/O 绑定 | **不进映像**；编译期把 `var` 收成槽号，channel/bit 留在 host 读 toml |
+| 不做 | `REAL`、隐式宽化、独立 `stc.exe` |
+
+---
+
+## 类型
+
+C++11 定宽：
+
+- `BOOL`：`uint8_t`，0/1
+- `INT`：`int16_t`；加减乘除溢出饱和
+- `TIME`：`int32_t` 毫秒
+
+`compiler` 与 `vm` 都按同一规则，不再另选溢出策略。
+
+---
+
+## 指令
+
+定宽 32 bit：
+
+```text
+[ op:8 | rd:8 | a:8 | b:8 ]
+```
+
+- 三寄存器：`a`/`b` 为 `ra`/`rb`（`MOVE`/`NOT` 只用 `rd`+`a`）
+- `LOADK`：`a|b` 为 `const_id`（u16）
+- `JMP` / `JT` / `JF`：`a|b` 为有符号相对 offset（指令条数）
+- `CALL`：`a|b` 为 `fn_id`（u16）
+
+操作码一次列全（`CMP_xx` 冻下面六种）：
+
+```text
+MOVE rd, rs
+LOADK rd, const_id
+NOT rd, rs
+AND/OR rd, ra, rb          (* 已算好的值；短路用跳转 *)
+ADD/SUB/MUL/DIV rd, ra, rb
+CMP_EQ/NE/LT/LE/GT/GE rd, ra, rb
+JMP  offset
+JT/JF r, offset
+LOAD_I / STORE_Q / LOAD_M / STORE_M
+LOAD_GLOBAL / STORE_GLOBAL
+CAL_TON / CAL_TOF / CAL_CTU
+CALL fn_id
+RET
+```
+
+局部 / `VAR` = 固定寄存器；表达式临时值往后编号；`nregs` 写进函数头。  
+`I`/`Q`/`M` 走映像指令，不是通用寄存器。  
+FB 实例固定布局，字段偏移编译期算死。
+
+---
+
+## 映像
+
+魔数 `STSC`，版本 `1`。
+
+头：
+
+- `cycle_limit`、`dt_ms`
+- 工程哈希
+- 全局槽数、I/Q/M 槽数
+- 常量表 / 函数表 / 字节码 / FB 布局的偏移
+- 入口 `MAIN` 的 `fn_id`
+
+函数表一行：`fn_id`、`nregs`、字节码偏移与长度。
+
+工程哈希：收录源文件路径排序后对内容做 **FNV-1a 64**，只保证回放槽位一致，不是密码学哈希。
+
+`[[io.input]]` / `[[io.output]]` 不进映像。
+
+---
+
+## 目录与 CMake
+
+```text
+isa/
+  CMakeLists.txt
+  README.md                 # 代码目录入口，指向本文
+  include/isa/
+    Types.hpp               # 宽度、饱和、槽值表示
+    Op.hpp                  # 操作码枚举 + 助记符
+    Instr.hpp               # 32-bit 打包/拆字段（inline）
+    Image.hpp               # 头、段、函数表/常量表/FB 布局
+    Encode.hpp              # 编解码、哈希、反汇编一行
+  src/
+    Encode.cpp
+    Image.cpp
+```
+
+```cmake
+add_library(isa STATIC src/Encode.cpp src/Image.cpp)
+target_include_directories(isa PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+```
+
+`compiler` / `vm`：`target_link_libraries(... PUBLIC isa)`。
+
+---
+
+## 实现顺序（对齐初步计划 12.0～12.1）
+
+1. `Types.hpp`：三类型 + `sat_add` 等饱和函数（inline 即可）
+2. `Op.hpp` + `Instr.hpp`：枚举与 32-bit 编解码
+3. `Encode.cpp`：`encode` / `decode` / `disasm` 一条指令
+4. `Image.hpp` + `Image.cpp`：头布局、FNV-1a、读写缓冲（先能写空映像 + 一条 `RET`）
+5. 测试随后在 `tests/` 加编解码往返；本阶段以头文件和库能链为准
+
+不在本模块做：VM `switch`、toml、关键字、符号表。

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

@@ -202,6 +202,8 @@ motor.st / main.st
 
 ## 7. 寄存器机与指令
 
+编码宽度、操作码取值、映像头与定宽类型以 [`isa/指令与映像.md`](isa/指令与映像.md) 为准。本节只列助记符。
+
 - 局部 / `VAR` = 固定寄存器；表达式临时值往后编号；`nregs` 写进函数头。
 - `I/Q/M` 走映像指令，不是通用寄存器。
 - 每个 FB 实例一块固定布局，字段偏移编译期算死。
@@ -378,11 +380,9 @@ CMake 四个目标能空编译：`isa`、`compiler`、`vm`、`host`。`host` 先
 
 **指令（进 `isa`，约 20 条）**
 
-第 7 节那张表：编码宽度、立即数格式、`fn_id` 是立即数、跳转是相对 offset。  
+布局、操作码、映像、哈希、饱和以 [`isa/指令与映像.md`](isa/指令与映像.md) 为准。第 7 节只列助记符。
-映像头：函数表、常量表、全局槽数、FB 槽布局、`cycle_limit`、`dt_ms`、工程哈希。  
-工程哈希：收录的源文件排序后算，写入映像，回放时槽位必须一致。
 
-完成：`isa` 能编解码一条指令；头文件即规范，不再另写一份互相打架的文档。
+完成：`isa` 能编解码一条指令；实现头文件，不另写第三份规范。
 
 ---
 

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`）。

isa/README.md

@@ -1,17 +1,7 @@
 # isa
 
-共享契约库。CMake 目标：`isa`（`STATIC` 或 `INTERFACE`），无依赖。
+指令集 + 映像 + 定宽类型。CMake 目标：`isa`（`STATIC`）。
 
-`compiler` 写映像、`vm` 读映像，两边只依赖本目录，彼此不链接。
+`compiler` 写映像、`vm` 读映像，两边只依赖本目录。
 
-## 职责
+规范、特性与实现顺序见 [`doc/isa/指令与映像.md`](../doc/isa/指令与映像.md)。
-
-- 约 20 条寄存器指令的编码（`MOVE`、`LOADK`、跳转、`LOAD_I` / `STORE_Q`、`CALL` / `RET`、`CAL_TON` 等）
-- 映像头：函数字节码、全局 / FB 数据槽、工程哈希
-- 定宽类型：第一版 `BOOL`、`INT`、`TIME`
-
-## 不放什么
-
-解析器、符号表、扫描周期循环、I/O 采样。那些分别属于 `compiler`、`vm`、`host`。
-
-指令表可作为内部 IR 的文本形态，不必当主语言。

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`。