vm 模块注释完善：Doxygen 风格。

- Image.h/.cpp：头 104 布局逐字段、SHA-256 增量状态机（update/process/final）、
  校验项清单（from）、型号标识契约、func_row/const_entry/data_len 等访问器语义
- Machine.h/.cpp：Fault 枚举逐项、create 校验顺序（解析→SHA→型号）、
  调用约定（r0 结果/r1..r7 实参）、exec_one 取指/计数/分发流程、
  do_call/do_ret 帧语义、do_cal 八 FB 字段布局、slot_get/set 边界契约

vm/src/Image.cpp

@@ -1,6 +1,6 @@
 /**
  * @file Image.cpp
- * @brief vm 自带的 .stb 只读视图（执行器侧）
+ * @brief vm 自带的 .stb 只读视图实现（执行器侧；compiler 各有实现）
  * @author 
  * @date 2026-08-21
  */
@@ -14,14 +14,22 @@ namespace vm {
 
 namespace {
 
-    const uint32_t kMagic = 0x43545353u;   // "STSC" 小端
+    /// 映像魔数："STSC" 小端。
+    const uint32_t kMagic = 0x43545353u;
+    /// 映像格式版本。
     const uint32_t kVersion = 1;
+    /// 映像头字节数（72 原字段 + 型号标识[32] @72，12.13 修订）。
     const size_t kHeaderSize = 104;
+    /// 常量表一行字节数（tag:4 + value:8）。
     const size_t kConstEntrySize = 12;
+    /// 函数表一行字节数（nregs/code_offset/code_len 各 4）。
     const size_t kFuncRowSize = 12;
+    /// SHA-256 摘要长度（文件尾）。
     const size_t kSha256Size = 32;
+    /// 型号标识长度（头内 @72，不足补 '\0'）。
     const size_t kModelIdSize = 32;
 
+    /// 小端读 32 位。
     uint32_t get_le32(const uint8_t* p) {
         return static_cast<uint32_t>(p[0])
             | (static_cast<uint32_t>(p[1]) << 8)
@@ -29,6 +37,7 @@ namespace {
             | (static_cast<uint32_t>(p[3]) << 24);
     }
 
+    /// 小端读 64 位。
     uint64_t get_le64(const uint8_t* p) {
         uint64_t v = 0;
         for (int i = 0; i < 8; ++i) {
@@ -39,6 +48,7 @@ namespace {
 
     // ---- SHA-256（执行器侧实现，与 compiler 各一份）----
 
+    /// SHA-256 轮常量 K[0..63]。
     const uint32_t kShaK[64] = {
         0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
         0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
@@ -53,15 +63,26 @@ namespace {
         0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
     };
 
+    /// 循环右移。
     inline uint32_t rotr(uint32_t x, uint32_t n) { return (x >> n) | (x << (32 - n)); }
 
+    /**
+     * @brief SHA-256 增量状态机。
+     * @details 标准 FIPS 180-4 实现：update() 吸收任意长度字节流，final() 输出
+     *          32 字节大端摘要。按 64 字节块 process()。
+     */
     struct Sha256 {
         uint32_t h[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
-                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};
-        uint64_t total = 0;
-        uint8_t block[64];
-        size_t block_len = 0;
+                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};  ///< 初始哈希值
+        uint64_t total = 0;   ///< 已吸收字节数（final 时编码进长度域）
+        uint8_t block[64];    ///< 当前块缓冲
+        size_t block_len = 0; ///< 块缓冲已用字节数
 
+        /**
+         * @brief 吸收数据。
+         * @param data 输入字节
+         * @param len 字节数
+         */
         void update(const uint8_t* data, size_t len) {
             total += len;
             while (len > 0) {
@@ -83,6 +104,7 @@ namespace {
             }
         }
 
+        /// 压缩一个满块（64 字节，w[0..63] 展开 + 64 轮）。
         void process() {
             uint32_t w[64];
             for (int i = 0; i < 16; ++i) {
@@ -115,6 +137,10 @@ namespace {
             h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
         }
 
+        /**
+         * @brief 结束并输出摘要。
+         * @param out 32 字节输出缓冲（大端）
+         */
         void final(uint8_t out[32]) {
             const uint64_t bitlen = total * 8;
             const uint8_t pad = 0x80;
@@ -136,18 +162,31 @@ namespace {
             }
         }
 
+        /// 大端读 32 位。
         static uint32_t get_be32(const uint8_t* p) {
             return (static_cast<uint32_t>(p[0]) << 24) | (static_cast<uint32_t>(p[1]) << 16) |
                    (static_cast<uint32_t>(p[2]) << 8) | static_cast<uint32_t>(p[3]);
         }
     };
 
+    /**
+     * @brief 一次性 SHA-256。
+     * @param data 输入字节
+     * @param len 字节数
+     * @param out 32 字节摘要输出
+     */
     void sha256(const uint8_t* data, size_t len, uint8_t out[32]) {
         Sha256 s;
         s.update(data, len);
         s.final(out);
     }
 
+    /**
+     * @brief 按型号标识约定填充 32 字节：name + version（如 "STATOR1"），余下补 '\0'。
+     * @param name 型号名
+     * @param version 版本号
+     * @param out 32 字节输出缓冲
+     */
     void fill_model_id(const std::string& name, uint32_t version, char out[32]) {
         const std::string id = name + std::to_string(version);
         for (size_t i = 0; i < 32; ++i) {
@@ -157,6 +196,12 @@ namespace {
 
 }  // namespace
 
+/**
+ * @brief 从原始字节构造只读视图（不拷贝，调用方保证生命周期）。
+ * @param buf 映像缓冲；可为 nullptr
+ * @param len 缓冲字节数
+ * @return 校验结果；ok() 判成功，error() 取失败原因
+ */
 Image Image::from(const uint8_t* buf, size_t len) {
     Image v;
     v.buf_ = buf;
@@ -194,7 +239,7 @@ Image Image::from(const uint8_t* buf, size_t len) {
     h.offset_fb = get_le32(buf + 64);
     h.offset_data = get_le32(buf + 68);
 
-    // 段校验（数据段之后是 SHA-256 文件尾；步骤 8 做校验，这里仅保证有尾）
+    // 段校验（数据段之后是 SHA-256 文件尾；这里仅保证有尾，sha_ok() 做完整性校验）
     if (len < static_cast<size_t>(h.offset_data) + kSha256Size) {
         v.err_ = "missing sha256 tail";
         return v;
@@ -232,10 +277,20 @@ Image Image::from(const uint8_t* buf, size_t len) {
     return v;
 }
 
+/**
+ * @brief 从 vector 构造只读视图。
+ * @param buf 映像缓冲（引用 data()，调用方保证生命周期）
+ * @return 同 from(const uint8_t*, size_t)
+ */
 Image Image::from(const std::vector<uint8_t>& buf) {
     return from(buf.data(), buf.size());
 }
 
+/**
+ * @brief 读函数表一行。
+ * @param i 函数下标
+ * @return 该行字段；越界（或校验失败）时全 0
+ */
 FuncRow Image::func_row(size_t i) const {
     FuncRow r;
     if (ok_ && i < hdr_.n_funcs) {
@@ -247,6 +302,11 @@ FuncRow Image::func_row(size_t i) const {
     return r;
 }
 
+/**
+ * @brief 读常量表一项。
+ * @param i 常量下标
+ * @return 该条目；越界（或校验失败）时全 0
+ */
 ConstEntry Image::const_entry(size_t i) const {
     ConstEntry e;
     if (ok_ && i < hdr_.n_consts) {
@@ -257,18 +317,34 @@ ConstEntry Image::const_entry(size_t i) const {
     return e;
 }
 
+/**
+ * @brief 字节码段起点。
+ * @return 段指针；校验失败返回 nullptr
+ */
 const uint8_t* Image::code_bytes() const {
     return ok_ ? buf_ + hdr_.offset_code : nullptr;
 }
 
+/**
+ * @brief 数据段起点。
+ * @return 段指针；校验失败返回 nullptr
+ */
 const uint8_t* Image::data_bytes() const {
     return ok_ ? buf_ + hdr_.offset_data : nullptr;
 }
 
+/**
+ * @brief 数据段字节数。
+ * @return 段长度（不含 SHA-256 尾）；校验失败返回 0
+ */
 size_t Image::data_len() const {
     return ok_ ? (len_ - kSha256Size) - hdr_.offset_data : 0;
 }
 
+/**
+ * @brief 型号标识字符串。
+ * @return 头 @72 起 32 字节，去 '\0' 截断；校验失败返回空串
+ */
 std::string Image::model_id() const {
     if (!ok_) {
         return "";
@@ -281,12 +357,22 @@ std::string Image::model_id() const {
     return s;
 }
 
+/**
+ * @brief 型号标识是否匹配。
+ * @param name 期望型号名（如 "STATOR"）
+ * @param version 期望版本（如 1）
+ * @return 头内 32 字节与 "name + version" 补零后逐字节相等
+ */
 bool Image::model_matches(const std::string& name, uint32_t version) const {
     char want[kModelIdSize];
     fill_model_id(name, version, want);
     return std::memcmp(buf_ + 72, want, kModelIdSize) == 0;
 }
 
+/**
+ * @brief 文件尾 SHA-256 完整性校验。
+ * @return 对 len-32 字节内容算摘要，与文件尾 32 字节相等
+ */
 bool Image::sha_ok() const {
     if (!ok_) {
         return false;