From 6df3465b37b4f1ccba269215c4999d917a6e624d Mon Sep 17 00:00:00 2001
From: chentianya <xiangyangtianya@qq.com>
Date: Thu, 20 Aug 2026 22:51:05 +0800
Subject: [PATCH] =?UTF-8?q?=E7=99=BB=E8=AE=B0=E7=AC=AC=E4=B8=89=E6=96=B9?=
 =?UTF-8?q?=E5=AD=90=E6=A8=A1=E5=9D=97=E5=B9=B6=E9=A2=84=E7=95=99=20TUI=20?=
 =?UTF-8?q?=E8=A7=82=E5=AF=9F=E6=8E=A5=E5=8F=A3=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- third_party：tomlplusplus（v3.4.0）+ FTXUI（main@9221a3b）git 子模块
- vm/扫描周期.md：可观察性接口（v1 预留）——step/snapshot、只读轮询、快照 POD 化
- executor/执行器入口.md：TUI 观察界面（最后做）——TUI 属执行器，输出层可替换
- 初步计划 12.11 补 TUI 归属；C++11 残留引用同步为 C++20
---
 .gitmodules                |  3 +++
 Doc/executor/执行器入口.md | 11 +++++++++++
 Doc/isa/指令与映像.md      |  2 +-
 Doc/vm/扫描周期.md         | 28 ++++++++++++++++++++++++++++
 Doc/初步计划.md            |  1 +
 isa/README.md              |  2 +-
 third_party/FTXUI          |  1 +
 third_party/README.md      | 14 +++++++++++++-
 8 files changed, 59 insertions(+), 3 deletions(-)
 create mode 160000 third_party/FTXUI

diff --git a/.gitmodules b/.gitmodules
index 6c69223..154ee6c 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +1,6 @@
 [submodule "third_party/tomlplusplus"]
 	path = third_party/tomlplusplus
 	url = https://github.com/marzer/tomlplusplus.git
+[submodule "third_party/FTXUI"]
+	path = third_party/FTXUI
+	url = https://github.com/ArthurSonzogni/FTXUI.git
diff --git a/Doc/executor/执行器入口.md b/Doc/executor/执行器入口.md
index 006e180..be0b218 100644
--- a/Doc/executor/执行器入口.md
+++ b/Doc/executor/执行器入口.md
@@ -16,3 +16,14 @@ BytecodeExecutor 模块：可执行入口。CMake 目标：`BytecodeExecutor`（
 - 指令与映像编码见 [`指令与映像.md`](../isa/指令与映像.md)
 - ST 解析与链接见 [`编译管线.md`](../compiler/编译管线.md)，本模块不碰 `.st`
 - 寄存器执行循环见 [`扫描周期.md`](../vm/扫描周期.md)
+
+---
+
+## TUI 观察界面（最后做，v1 只预留）
+
+TUI 属于本模块（`BytecodeExecutor` 的界面），用途是**观察 VM 运行状态**（寄存器、I/Q/M、全局、FB 字段、pc、cycle 计数）。v1 不做 TUI，只预留两点：
+
+1. **可替换输出层**：所有人类可读输出走可注入 sink（默认文本模式）。将来 TUI 独占终端时，文本输出换成 TUI 渲染器，互不污染。
+2. **展示层与 vm 观察 API 分离**：TUI 只轮询 vm 的只读快照（见 [`扫描周期.md`](../vm/扫描周期.md) 可观察性接口），不写 VM 状态。
+
+候选库：`third_party/FTXUI/`（占位，vendor 在 TUI 阶段进行，见 [`third_party/README.md`](../third_party/README.md)）。
diff --git a/Doc/isa/指令与映像.md b/Doc/isa/指令与映像.md
index a36fb46..7d2c0fb 100644
--- a/Doc/isa/指令与映像.md
+++ b/Doc/isa/指令与映像.md
@@ -56,7 +56,7 @@ CMake 目标：`isa`（`STATIC`），无依赖。公开头：`isa/include/isa/`
 
 ## 类型
 
-C++11 定宽：
+C++20 定宽：
 
 - `BOOL`：`uint8_t`，0/1
 - `INT`：`int16_t`；加减乘除溢出饱和
diff --git a/Doc/vm/扫描周期.md b/Doc/vm/扫描周期.md
index 71dbbe0..f0d93d3 100644
--- a/Doc/vm/扫描周期.md
+++ b/Doc/vm/扫描周期.md
@@ -20,3 +20,31 @@ vm 模块：寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 [
 - `CALL` 目标是立即数 `fn_id`，有界调用栈
 - 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制
 - I/O 从哪来、Δt 谁给、回放怎么喂，属于 `BytecodeExecutor`（读 `.stb` + sidecar）
+
+---
+
+## 可观察性接口（v1 预留）
+
+TUI 是执行器（`BytecodeExecutor`）的界面，用途是方便观察 VM 运行状态。**v1 不做 TUI**，只预留接口，避免后续改 VM 的观察面。原则：
+
+- **数据与展示分离**：`vm` 只提供只读观察 API（数据）；TUI 渲染与文本输出属于 `executor`（展示）。vm 不画任何界面。
+- **只读轮询**：TUI 通过快照轮询，绝不写 VM 状态；"继续 / 单步"是 executor 侧命令，不改变确定性。
+- **快照 POD 化**：快照保持简单数据（将来跨进程 TUI 可序列化）。
+
+建议的 API 形态（12.9 实现时冻结签名，本节只定方向）：
+
+```cpp
+struct Snapshot {
+    uint32_t pc;           // 当前指令下标（相对函数字节码段）
+    uint32_t fn_id;        // 当前函数
+    uint32_t cycle_count;  // 本周期已执行指令数
+    uint32_t call_depth;   // 调用栈深度
+    // 寄存器 / I / Q / M / 全局 / FB 字段 的只读视图
+};
+
+bool step();               // 精确执行一条指令，停在指令边界
+const Snapshot& snapshot() const;
+```
+
+- 寄存器 ≤256、映像很小，快照拷贝成本可忽略。
+- 单步、回放、dump 都建立在同一套观察 API 上。
diff --git a/Doc/初步计划.md b/Doc/初步计划.md
index edaa3a3..4b3163f 100644
--- a/Doc/初步计划.md
+++ b/Doc/初步计划.md
@@ -549,6 +549,7 @@ BytecodeExecutor <name>.stb [--cycles N]      # 执行：加载 .stb + sidecar
 - `line1` 固定输入表：急停、start/stop 组合 → 期望 `Q0_0`。
 - 回放：同一 I 序列跑两遍，槽位与哈希一致。
 - 单步：能停在指令边界，看到寄存器和 I/Q/M（可先做打印，不必做 UI）。
+- TUI 界面**最后做**，v1 只预留接口：执行器（`BytecodeExecutor`）的观察界面，数据走 vm 观察 API（见 `Doc/vm/扫描周期.md`），展示与输出层分离（见 `Doc/executor/执行器入口.md`）。
 
 完成标准（第一版可交付）：**`MAIN` + 一个 Motor FB + I/O + 全局**，扫描周期可重复。
 
diff --git a/isa/README.md b/isa/README.md
index 5265c12..f17b372 100644
--- a/isa/README.md
+++ b/isa/README.md
@@ -88,7 +88,7 @@ target_include_directories(isa PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
 
 ### 2. `Types.h`
 
-`include/isa/Types.h`，inline，无对应 `.cpp`。命名空间 `isa`。C++11，不用 designated initializer。
+`include/isa/Types.h`，inline，无对应 `.cpp`。命名空间 `isa`。C++20；本模块保持简单结构体，不依赖花哨特性。
 
 - `Bool` = `uint8_t`，`Int` = `int16_t`，`Time` = `int64_t`（毫秒；理由见规范文）
 - `TypeTag`：`Bool` / `Int` / `Time`
diff --git a/third_party/FTXUI b/third_party/FTXUI
new file mode 160000
index 0000000..9221a3b
--- /dev/null
+++ b/third_party/FTXUI
@@ -0,0 +1 @@
+Subproject commit 9221a3bf199e5a06057d6b99d9d3797a78523c5d
diff --git a/third_party/README.md b/third_party/README.md
index 120fdd8..a338a56 100644
--- a/third_party/README.md
+++ b/third_party/README.md
@@ -2,6 +2,18 @@
 
 第三方源码或单头库，本仓库不把它们做成业务 CMake 目标。
 
-预期由 `compiler` **私有链接**（例如 toml 解析）。不要从 `isa`、`vm`、`host` 直接依赖本目录。
+预期由 `compiler` **私有链接**（例如 toml 解析）。不要从 `isa`、`vm`、`executor` 直接依赖本目录。
 
 新增依赖时在此注明来源、许可和所用版本。第一版不上 LLVM、不做 CPython / JIT。
+
+## 已登记
+
+| 目录 | 来源 | 许可 | 版本 | 形态 | 用途 |
+|---|---|---|---|---|---|
+| `tomlplusplus/` | marzer/tomlplusplus | MIT | v3.4.0 | **git 子模块**（需 `git submodule update --init` 检出） | compiler 解析 `project.toml` |
+| `FTXUI/` | ArthurSonzogni/FTXUI | MIT | main@9221a3b | **git 子模块** | 执行器 TUI 候选（最后做，见 `Doc/executor/执行器入口.md`） |
+
+## 说明
+
+- 两者都是子模块：拉取后先 `git submodule update --init --recursive` 才能编。
+- 首次检出可用 `--depth 1` 浅克隆加快（本仓库不依赖子模块历史）。