diff --git a/isa/include/isa/Encode.h b/isa/include/isa/Encode.h
index ea4d8ad..b4dfcfa 100644
--- a/isa/include/isa/Encode.h
+++ b/isa/include/isa/Encode.h
@@ -1,6 +1,7 @@
 /**
  * @file Encode.h
  * @brief 指令编解码与反汇编
+ * @details 给 STCompiler --disasm 与测试往返使用；文本格式见 Doc/isa/指令与映像.md。
  * @author 
  * @date 2026-08-19
  */
@@ -14,18 +15,40 @@
 #include "isa/Op.h"
 
 namespace isa {
-    // 解码后的字段视图
+    /**
+     * @brief 解码后的字段视图。
+     * @details 各字段是 8 位原始值，含义按操作数形态（OpFormat）解释，
+     *          a|b 可用 imm16 / off16 组合成 16 位视图。
+     */
     struct Decoded {
-        Op op;
-        uint8_t rd;
-        uint8_t a;
-        uint8_t b;
+        Op op;      ///< 操作码
+        uint8_t rd; ///< 目标寄存器 / 条件寄存器
+        uint8_t a;  ///< 源寄存器 / 立即数低 8 位 / 偏移低 8 位
+        uint8_t b;  ///< 源寄存器 / 立即数高 8 位 / 偏移高 8 位
     };
 
-    // 编解码往返：encode(decode(w)) == w
+    /**
+     * @brief 编码：字段视图打包成一条 32 位指令字。
+     * @param d 解码后的字段视图
+     * @return 打包后的指令字；满足 encode(decode(w)) == w
+     */
     Instr encode(Decoded d);
+
+    /**
+     * @brief 解码：指令字拆成字段视图。
+     * @param w 32 位指令字
+     * @return 各字段视图
+     */
     Decoded decode(Instr w);
 
-    // 反汇编一行文本，写入 out，至多 cap 字节（含 '\0'）。格式见 Doc/isa/指令与映像.md。
+    /**
+     * @brief 反汇编一条指令为一行文本。
+     * @param w 指令字
+     * @param out 输出缓冲
+     * @param cap 缓冲容量（含 '\0'）；cap==0 时直接返回、不写 out
+     * @details 按操作数形态表驱动输出（如 `RET`、`MOVE r1, r2`、`LOADK r0, 3`、
+     *          `ADD r1, r2, r3`、`JMP +4`、`JT r0, -1`、`CALL 1`、`CAL_TON 0`）；
+     *          未知操作码输出 `??? 0x<w>`。
+     */
     void disasm(Instr w, char* out, size_t cap);
 }
diff --git a/isa/include/isa/Instr.h b/isa/include/isa/Instr.h
index 72afc27..f9e4a6d 100644
--- a/isa/include/isa/Instr.h
+++ b/isa/include/isa/Instr.h
@@ -1,6 +1,8 @@
 /**
  * @file Instr.h
- * @brief 32-bit 指令打包 / 拆字段
+ * @brief 32-bit 指令字打包 / 拆字段
+ * @details 指令字布局：`[ op:8 | rd:8 | a:8 | b:8 ]`，整体是一个小端 uint32_t。
+ *          字段含义按操作码形态解释，见 Doc/isa/指令与映像.md。
  * @author 
  * @date 2026-08-19
  */
@@ -12,11 +14,17 @@
 #include "isa/Op.h"
 
 namespace isa {
-    // 指令字：[ op:8 | rd:8 | a:8 | b:8 ]，整体是一个小端 uint32_t。
-    // 字段含义按操作码形态解释，见 Doc/isa/指令与映像.md。
+    /// 指令字：`[ op:8 | rd:8 | a:8 | b:8 ]`，小端 uint32_t。
     typedef uint32_t Instr;
 
-    // 打包 / 拆字段
+    /**
+     * @brief 打包：四个字段拼成一条指令字。
+     * @param op 操作码（低 8 位）
+     * @param rd 目标寄存器 / 条件寄存器（第 8..15 位）
+     * @param a  源寄存器 / 立即数低 8 位 / 偏移低 8 位（第 16..23 位）
+     * @param b  源寄存器 / 立即数高 8 位 / 偏移高 8 位（第 24..31 位）
+     * @return 打包后的指令字
+     */
     inline Instr pack(Op op, uint8_t rd, uint8_t a, uint8_t b) {
         return static_cast<uint32_t>(static_cast<uint8_t>(op))
             | (static_cast<uint32_t>(rd) << 8)
@@ -24,69 +32,143 @@ namespace isa {
             | (static_cast<uint32_t>(b) << 24);
     }
 
+    /**
+     * @brief 取操作码。
+     * @param w 指令字
+     * @return 低 8 位解释为 Op
+     */
     inline Op op(Instr w) {
         return static_cast<Op>(w & 0xFFu);
     }
 
+    /**
+     * @brief 取目标寄存器字段。
+     * @param w 指令字
+     * @return rd（第 8..15 位）
+     */
     inline uint8_t rd(Instr w) {
         return static_cast<uint8_t>((w >> 8) & 0xFFu);
     }
 
+    /**
+     * @brief 取 a 字段。
+     * @param w 指令字
+     * @return a（第 16..23 位）
+     */
     inline uint8_t a(Instr w) {
         return static_cast<uint8_t>((w >> 16) & 0xFFu);
     }
 
+    /**
+     * @brief 取 b 字段。
+     * @param w 指令字
+     * @return b（第 24..31 位）
+     */
     inline uint8_t b(Instr w) {
         return static_cast<uint8_t>((w >> 24) & 0xFFu);
     }
 
-    // 组合视图：a|b 拼成 16 位（const_id / fn_id / slot）
+    /**
+     * @brief 组合视图：a|b 拼成 16 位无符号数。
+     * @param w 指令字
+     * @return 小端拼出的 16 位值，用作 const_id / fn_id / slot 号
+     */
     inline uint16_t imm16(Instr w) {
         return static_cast<uint16_t>(a(w) | (static_cast<uint16_t>(b(w)) << 8));
     }
 
-    // 组合视图：a|b 为有符号相对偏移，单位是指令条数
+    /**
+     * @brief 组合视图：a|b 为有符号相对偏移。
+     * @param w 指令字
+     * @return 偏移量，单位是指令条数（跳转目标 = 下一条指令 + off）
+     */
     inline int16_t off16(Instr w) {
         return static_cast<int16_t>(imm16(w));
     }
 
-    // 按形态的便捷编码
+    /**
+     * @brief 按 RR 形态编码。
+     * @param op 操作码（MOVE / NOT）
+     * @param rd 目标寄存器
+     * @param rs 源寄存器（放进 a）
+     * @return 指令字
+     */
     inline Instr enc_rr(Op op, uint8_t rd, uint8_t rs) {
-        return pack(op, rd, rs, 0);            // MOVE / NOT：a = rs
+        return pack(op, rd, rs, 0);
     }
 
+    /**
+     * @brief 按 RRR 形态编码。
+     * @param op 操作码（AND/OR/ADD/.../CMP_xx）
+     * @param rd 目标寄存器
+     * @param ra 第一源寄存器
+     * @param rb 第二源寄存器
+     * @return 指令字
+     */
     inline Instr enc_rrr(Op op, uint8_t rd, uint8_t ra, uint8_t rb) {
-        return pack(op, rd, ra, rb);           // AND/OR/ADD/.../CMP_xx
+        return pack(op, rd, ra, rb);
     }
 
+    /**
+     * @brief 按 IMM 形态编码。
+     * @param op 操作码（LOADK）
+     * @param rd 目标寄存器
+     * @param imm 16 位立即数（const_id），拆成 a|b 存放
+     * @return 指令字
+     */
     inline Instr enc_imm(Op op, uint8_t rd, uint16_t imm) {
         return pack(op, rd, static_cast<uint8_t>(imm & 0xFFu),
-                    static_cast<uint8_t>((imm >> 8) & 0xFFu));   // LOADK
+                    static_cast<uint8_t>((imm >> 8) & 0xFFu));
     }
 
+    /**
+     * @brief 按 JMP 形态编码。
+     * @param off 有符号相对偏移（条数），拆成 a|b 存放
+     * @return 指令字
+     */
     inline Instr enc_jmp(int16_t off) {
         return pack(Op::JMP, 0,
                     static_cast<uint8_t>(static_cast<uint16_t>(off) & 0xFFu),
                     static_cast<uint8_t>((static_cast<uint16_t>(off) >> 8) & 0xFFu));
     }
 
+    /**
+     * @brief 按 JC 形态编码（条件跳转）。
+     * @param op 操作码（JT / JF）
+     * @param r 条件寄存器（放进 rd）
+     * @param off 有符号相对偏移（条数），放进 a|b
+     * @return 指令字
+     */
     inline Instr enc_jc(Op op, uint8_t r, int16_t off) {
-        // JT / JF：条件寄存器在 rd，偏移在 a|b
         return pack(op, r,
                     static_cast<uint8_t>(static_cast<uint16_t>(off) & 0xFFu),
                     static_cast<uint8_t>((static_cast<uint16_t>(off) >> 8) & 0xFFu));
     }
 
+    /**
+     * @brief 按 SLOT 形态编码。
+     * @param op 操作码（LOAD_I / STORE_Q / LOAD_M / STORE_M / LOAD_GLOBAL / STORE_GLOBAL / CAL_*）
+     * @param rd 目标寄存器（CAL_* 时置 0）
+     * @param slot 槽号 / 实例号，放进 a|b
+     * @return 指令字
+     */
     inline Instr enc_slot(Op op, uint8_t rd, uint16_t slot) {
-        // LOAD_I / STORE_Q / LOAD_M / STORE_M / LOAD_GLOBAL / STORE_GLOBAL / CAL_*
-        // 槽号 / 实例号在 a|b
         return enc_imm(op, rd, slot);
     }
 
+    /**
+     * @brief 按 CALL 形态编码。
+     * @param fn_id 函数表下标，放进 a|b
+     * @return 指令字
+     */
     inline Instr enc_call(uint16_t fn_id) {
         return enc_imm(Op::CALL, 0, fn_id);
     }
 
+    /**
+     * @brief 按 NONE 形态编码（RET）。
+     * @return 指令字
+     */
     inline Instr enc_ret() {
         return pack(Op::RET, 0, 0, 0);
     }
diff --git a/isa/include/isa/Op.h b/isa/include/isa/Op.h
index a28440d..a3684ac 100644
--- a/isa/include/isa/Op.h
+++ b/isa/include/isa/Op.h
@@ -1,6 +1,8 @@
 /**
  * @file Op.h
- * @brief 操作码枚举 + 助记符
+ * @brief 操作码枚举、操作数形态与编译期指令表
+ * @details 操作码数值即 .stb 指令编码。执行器（vm）只依赖本表；
+ *          编译器侧的登记见 Doc/isa/指令配置.md（compiler/machine.toml，与之强校验）。
  * @author 
  * @date 2026-08-19
  */
@@ -10,8 +12,11 @@
 #include <cstdint>
 
 namespace isa {
-    // 操作码一次列全。数值即编码：冻结后不得改顺序、不得插值，
-    // 增加指令只能追加到末尾，并同步 Doc/isa/指令与映像.md 与测试。
+    /**
+     * @brief 操作码枚举。
+     * @details 数值即编码：冻结后不得改顺序、不得插值，增加指令只能追加到末尾，
+     *          并同步 Doc/isa/指令与映像.md、compiler/machine.toml 与测试。
+     */
     enum class Op : uint8_t {
         MOVE = 0,          // MOVE rd, rs
         LOADK = 1,         // LOADK rd, const_id
@@ -50,10 +55,13 @@ namespace isa {
         RET = 33,          // RET
     };
 
-    // 操作码总数
+    /// 操作码总数（= 最大 opcode + 1，kOpDefs 的下标上界）。
     static const int kOpCount = 34;
 
-    // 操作数形态（三层分类第二层，见 Doc/isa/指令配置.md）
+    /**
+     * @brief 操作数形态（三层分类第二层，见 Doc/isa/指令配置.md）。
+     * @details 决定操作数 a|b 的解释方式与反汇编文本格式。
+     */
     enum class OpFormat : uint8_t {
         RR,     // 两寄存器：rd rs（MOVE / NOT）
         RRR,    // 三寄存器：rd ra rb（逻辑 / 算术 / 比较）
@@ -66,19 +74,28 @@ namespace isa {
         NONE,   // 无操作数（RET）
     };
 
-    // 操作对象大类（三层分类第一层）
+    /**
+     * @brief 操作对象大类（三层分类第一层）。
+     */
     enum class OpClass : uint8_t {
         Plain,     // 无实例：寄存器 / 立即数 / 槽 / 分支 / 调用
         Instance,  // 有实例：操作数据区实例块（内建 FB）
     };
 
-    // 编译期指令表：下标与 Op 数值一一对应（ops.txt 强校验的基准）
+    /**
+     * @brief 编译期指令表条目。
+     * @details 一条指令的名称、操作数形态与大类；下标与 Op 数值一一对应。
+     */
     struct OpDef {
-        const char* name;
-        OpFormat format;
-        OpClass cls;
+        const char* name;   ///< 助记符（与 .stb / machine.toml 一致）
+        OpFormat format;    ///< 操作数形态
+        OpClass cls;        ///< 操作对象大类
     };
 
+    /**
+     * @brief 编译期指令表：下标与 Op 数值一一对应（machine.toml 强校验的基准）。
+     * @details 表与 Op 枚举同步维护；查询入口见 mnemonic / format / op_class。
+     */
     static const OpDef kOpDefs[kOpCount] = {
         {"MOVE", OpFormat::RR, OpClass::Plain},          // 0
         {"LOADK", OpFormat::IMM, OpClass::Plain},        // 1
@@ -116,17 +133,31 @@ namespace isa {
         {"RET", OpFormat::NONE, OpClass::Plain},         // 33
     };
 
-    // 助记符 / 格式 / 大类：查表（越界返回哨兵）
+    /**
+     * @brief 查助记符。
+     * @param op 操作码
+     * @return 对应助记符；越界返回哨兵 "???"
+     */
     inline const char* mnemonic(Op op) {
         const int idx = static_cast<int>(op);
         return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].name : "???";
     }
 
+    /**
+     * @brief 查操作数形态。
+     * @param op 操作码
+     * @return 对应 OpFormat；越界返回 OpFormat::NONE
+     */
     inline OpFormat format(Op op) {
         const int idx = static_cast<int>(op);
         return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].format : OpFormat::NONE;
     }
 
+    /**
+     * @brief 查操作对象大类。
+     * @param op 操作码
+     * @return 对应 OpClass；越界返回 OpClass::Plain
+     */
     inline OpClass op_class(Op op) {
         const int idx = static_cast<int>(op);
         return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].cls : OpClass::Plain;
diff --git a/isa/include/isa/Types.h b/isa/include/isa/Types.h
index 2fa1efb..104e783 100644
--- a/isa/include/isa/Types.h
+++ b/isa/include/isa/Types.h
@@ -1,6 +1,8 @@
 /**
  * @file Types.h
- * @brief 类型定义
+ * @brief 定宽类型与饱和算术
+ * @details 虚拟机字长与类型契约的唯一来源。compiler 与 vm 共用同一套规则，
+ *          详见 Doc/isa/指令与映像.md。
  * @author 
  * @date 2026-08-18
  */
@@ -12,15 +14,28 @@
 
 namespace isa {
     namespace types {
-        // 定宽类型。整数溢出规则：饱和（夹到 INT 最小/最大），
-        // 由 compiler 与 vm 按同一规则实现，见 Doc/isa/指令与映像.md。
-        using BOOL = uint8_t;   // 只允许 0/1
-        using INT = int16_t;    // IEC INT
-        // 毫秒，有符号。64 位理由见 Doc/isa/指令与映像.md：
-        // 差值可负、为 DATE_AND_TIME 与 64 位定时器预留。槽位按 8 字节对齐。
+        /**
+         * @brief 布尔值：8 位，只允许 0/1（0=FALSE，1=TRUE）。
+         */
+        using BOOL = uint8_t;
+
+        /**
+         * @brief IEC INT：16 位有符号整数，溢出按饱和规则处理。
+         */
+        using INT = int16_t;
+
+        /**
+         * @brief 时间：64 位有符号整数，单位毫秒。
+         * @details 取 64 位的理由见 Doc/isa/指令与映像.md：差值可负、
+         *          为 DATE_AND_TIME 与 64 位定时器预留。槽位按 8 字节对齐。
+         */
         using TIME = int64_t;
 
-        // 槽 / 常量表类型标记，数值冻结：0=BOOL、1=INT、2=TIME（见映像规范）
+        /**
+         * @brief 槽 / 常量表类型标记。
+         * @details 数值冻结并写入 .stb 常量表：0=BOOL、1=INT、2=TIME（见映像规范），
+         *          不得改顺序、不得插值。
+         */
         enum TypeTag : uint8_t {
             Bool = 0,
             Int = 1,
@@ -29,6 +44,13 @@ namespace isa {
 
         // 饱和算术：夹到 INT 最小/最大，编译期与 VM 共用同一规则。
 
+        /**
+         * @brief 饱和加法。
+         * @param a 加数
+         * @param b 加数
+         * @return a+b，超出 INT 范围时夹到最小/最大值
+         * @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
+         */
         inline INT sat_add(INT a, INT b) {
             const int32_t sum = static_cast<int32_t>(a) + static_cast<int32_t>(b);
             return static_cast<INT>(sum < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -36,6 +58,13 @@ namespace isa {
                 : sum);
         }
 
+        /**
+         * @brief 饱和减法。
+         * @param a 被减数
+         * @param b 减数
+         * @return a-b，超出 INT 范围时夹到最小/最大值
+         * @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
+         */
         inline INT sat_sub(INT a, INT b) {
             const int32_t diff = static_cast<int32_t>(a) - static_cast<int32_t>(b);
             return static_cast<INT>(diff < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -43,6 +72,13 @@ namespace isa {
                 : diff);
         }
 
+        /**
+         * @brief 饱和乘法。
+         * @param a 乘数
+         * @param b 乘数
+         * @return a*b，超出 INT 范围时夹到最小/最大值
+         * @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
+         */
         inline INT sat_mul(INT a, INT b) {
             const int32_t prod = static_cast<int32_t>(a) * static_cast<int32_t>(b);
             return static_cast<INT>(prod < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -50,12 +86,17 @@ namespace isa {
                 : prod);
         }
 
+        /**
+         * @brief 饱和除法。
+         * @param a 被除数
+         * @param b 除数
+         * @return a/b；b==0 视为除以 1 返回 a；INT_MIN / -1 溢出饱和到 INT_MAX
+         * @details b==0 返回 a 是为避免未定义行为；除零的语义由 compiler/VM 层报错。
+         */
         inline INT sat_div(INT a, INT b) {
-            // b == 0 视为除以 1，避免未定义行为；除零的语义由 compiler/VM 层报错
             if (b == 0) {
                 return a;
             }
-            // INT_MIN / -1 溢出：饱和到 INT_MAX
             if (a == std::numeric_limits<INT>::min() && b == -1) {
                 return std::numeric_limits<INT>::max();
             }
diff --git a/isa/src/Encode.cpp b/isa/src/Encode.cpp
index fdd74a9..db74a9a 100644
--- a/isa/src/Encode.cpp
+++ b/isa/src/Encode.cpp
@@ -1,6 +1,6 @@
 /**
  * @file Encode.cpp
- * @brief 指令编解码与反汇编
+ * @brief 指令编解码与反汇编实现
  * @author 
  * @date 2026-08-19
  */
@@ -11,10 +11,20 @@
 
 namespace isa {
 
+/**
+ * @brief 编码：字段视图打包成一条 32 位指令字。
+ * @param d 解码后的字段视图
+ * @return 打包后的指令字；满足 encode(decode(w)) == w
+ */
 Instr encode(Decoded d) {
     return pack(d.op, d.rd, d.a, d.b);
 }
 
+/**
+ * @brief 解码：指令字拆成字段视图。
+ * @param w 32 位指令字
+ * @return 各字段视图
+ */
 Decoded decode(Instr w) {
     Decoded d;
     d.op = op(w);
@@ -24,6 +34,14 @@ Decoded decode(Instr w) {
     return d;
 }
 
+/**
+ * @brief 反汇编一条指令为一行文本。
+ * @param w 指令字
+ * @param out 输出缓冲
+ * @param cap 缓冲容量（含 '\0'）；cap==0 时直接返回、不写 out
+ * @details 按操作数形态表驱动输出，文本与 Doc/isa/指令与映像.md 一致；
+ *          未知操作码输出 `??? 0x<w>`。
+ */
 void disasm(Instr w, char* out, size_t cap) {
     if (cap == 0) {
         return;