Merge branch 'dev' into main

CMakePresets.json

@@ -13,7 +13,8 @@
       "binaryDir": "${sourceDir}/build/${presetName}",
       "cacheVariables": {
         "CMAKE_C_COMPILER": "gcc",
-        "CMAKE_CXX_COMPILER": "g++"
+        "CMAKE_CXX_COMPILER": "g++",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
       }
     },
     {

executor/src/main.cpp

@@ -234,6 +234,7 @@ int main(int argc, char** argv) {
     }
 
     const std::string stb_path = argv[1];
+    // 参数：--cycles N / --replay <file> / --step（缺省 cycles=10、无回放、非单步）
     uint32_t cycles = 10;
     bool step_mode = false;
     std::string replay;
@@ -247,6 +248,7 @@ int main(int argc, char** argv) {
         }
     }
 
+    // 读 .stb 映像（二进制）到字节缓冲
     std::string err;
     std::vector<uint8_t> bytes;
     {
@@ -257,6 +259,7 @@ int main(int argc, char** argv) {
         }
         bytes.assign(std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>());
     }
+    // 结构校验（Image::from）+ 型号/SHA-256 校验（Machine::create）
     const vm::Image img = vm::Image::from(bytes);
     if (!img.ok()) {
         std::fprintf(stderr, "error: %s\n", img.error().c_str());
@@ -268,7 +271,7 @@ int main(int argc, char** argv) {
         return 1;
     }
 
-    // sidecar：<name>.runtime.toml
+    // sidecar 路径推导：<name>.stb → <name>.runtime.toml
     std::string sidecar_path = stb_path;
     const size_t dot = sidecar_path.find_last_of('.');
     if (dot != std::string::npos) {
@@ -281,7 +284,7 @@ int main(int argc, char** argv) {
         return 1;
     }
 
-    // 回放缓冲
+    // 回放缓冲（当前行 0/1 序列）+ 打开回放文件；打不开 → 报错退出
     std::vector<int> replay_line;
     std::ifstream replay_in;
     if (!replay.empty()) {