codecin 5.5.0__tar.gz → 5.6.0__tar.gz

{codecin-5.5.0 → codecin-5.6.0}/CHANGELOG.md

@@ -5,6 +5,199 @@
 
 ---
 
+## [5.6.0] - 2026-09-27
+
+一次以「静默错误清零 + 安全加固」为主的修复发布，落地 `docs/SUGGESTIONS_NEXT.md`
+第一轮评审的全部 P0/P1 项。所有语义修复均同步 Python 解释器与 Go 原生 VM 两条路径，
+并新增 25 个回归测试（`tests/test_p0_fixes.py`）；同时新增**键盘输入监听**宿主能力
+（非阻塞轮询）与键盘场景的**顺序实时输出**、终端输入缓存兼容。
+
+### 修复 (Fixed)
+
+- **`enum` 末成员无尾逗号解析失败**：`expect(RBRACE)` 前未跳过换行导致
+  `enum Color { RED, GREEN = 5 }` 报 `Expected RBRACE but got NL`。
+  Python 编译器与 Go 编译器同步修复。
+- **`input()` 真实现**：此前恒编译为 `MOV x0, 0`，任何输入都返回 0。现编译为
+  `IN` 指令：解释器从 `input_buffer` / 标准输入逐行读取（非法行返回 0），
+  Go 原生 VM 在缓冲耗尽后回退标准输入；CLI 启动时预读管道 stdin，
+  管道喂入（`echo 42 | ...`）与交互输入均可用。
+- **`substr` / `indexof` 统一字节语义**：此前按字符索引，与 `strlen` / `s[i]`
+  的字节语义不一致，非 ASCII 字符串算错下标。现与 Go 侧一致按 UTF-8 字节切片/查找。
+- **`sqrt` / `pow` 数学域错误对齐 NaN**：解释器此前对 `sqrt(-1.0)` 抛 CPython
+  `ValueError`，与 Go 路径（返回 NaN）不一致。现统一返回 NaN
+  （IEEE-754 允许同一 NaN 有多个位模式，不做精确位断言）。
+- **CLI 编码兜底**：Windows GBK 控制台下输出非 ASCII 即崩，`main()` 入口对
+  stdout/stderr 强制 `reconfigure(encoding='utf-8', errors='replace')`。
+- **Go 编译器无法构建**（既有）：`genRangeFor` 的 `elemType` 参数误声明为
+  `*Node` 导致整个 compiler 包编译失败，改回 `*Type`；同步修正两个从未跑通的
+  Go 测试（range-for 标签前缀、enum 全局初始化器用例的期望值）。
+
+### 安全 (Security)
+
+- **`--sandbox` 真实现**：此前为空壳。现拦截全部宿主能力 SYS 调用
+  （`AUDIOPLAY=39` 起的文件/网络/桌面/进程类），并强制放弃原生 DLL 路径
+  回退解释器执行，保证拦截无旁路。
+- **条件断点白名单求值**：`debugger` 的断点条件此前直接 `eval`，远程调试端口
+  可执行任意代码。现以 AST 白名单（字面量/寄存器名/算术比较/布尔逻辑）
+  校验后受限求值，拒绝 Call/Attribute/Subscript/推导式等一切可执行语法，
+  条件长度上限 512 字符。
+
+### 加固 (Hardened)
+
+- **JIT 栈保护补齐**：PUSH 生成代码补栈溢出检查（栈顶与堆区相撞即报错），
+  POP 补栈下溢检查，与解释器 / 原生 VM 对齐。
+- **汇编器非法数字字面量报错**：`0x_`、`0b__` 等残缺字面量此前静默求值为 0，
+  现编译报错。
+
+### 新增 (Added)
+
+#### CIN 语法
+
+- **`enum` 枚举**：`enum Color { RED, GREEN = 5, BLUE }`。成员是**编译期整数常量**，
+  未显式赋值时自动递增（首个成员从 `0` 起）；`= <整数常量表达式>` 支持
+  `+ - * / % << >> & | ^` 与一元 `-` / `~`，可引用**先前已定义**的成员。
+  枚举类型名等价于 `int`（`Color c = BLUE`），成员可用于表达式、全局初始化与 `case` 标签；
+  成员只读，赋值报 `Cannot assign to enum member: X (constants are read-only)`。
+- **范围 for**：`for (int v : arr)` 遍历定长数组元素（元素可为标量 / `string` / struct），
+  支持 `break` / `continue`。被遍历对象必须是定长数组：`int[]` 指针形式报
+  `range-for requires a fixed-size array`，多维数组报
+  `range-for over multi-dimensional arrays is not supported`（改用下标循环）。
+- **`for` 初始化子句支持赋值**：`for (i = 0; i < n; i = i + 1)` 现在与类型声明一样合法。
+- **`switch` 增强**：`case 1, 2, 7..9:` —— 逗号分隔的单值与**闭区间**范围可混用（含负数），
+  仍是 C 的贯穿语义；范围要求 `lo <= hi`，否则报 `Empty case range: lo..hi`。
+- **转义扩展**：`\xH` / `\xHH` 写入**原始字节**（`"\xE4\xB8\xAD"` 即 `"中"` 的 UTF-8 三字节）、
+  `\uHHHH` / `\UHHHHHHHH` 按 **Unicode 码点**解析并以 UTF-8 编码写入；新增 `\a \b \f \v`
+  （字符字面量同样支持这四个）。`\u` / `\U` 位数不足或码点越界都有明确报错；未知转义保持原样。
+- **多参数 `print` / `println`**：`println("a=", a, " b=", b)` 依次输出、**不加分隔符**；
+  `println()` 输出空行；单参数行为不变。
+
+#### 宿主 API（36 个，全部 Go 原生实现）
+
+- **路径与文件系统**：`path_join` `path_basename` `path_dirname` `path_abs`（string，路径分隔符随平台）、
+  `file_copy` `file_move` `dir_remove`（递归删除）`chdir`（int，`0`/`-1`）、
+  `is_dir`（`1`/`0`）、`file_mtime`（Unix 秒 / `-1`）、`temp_dir`（string）。
+- **时间与系统**：`time_ms`、`sleep_ms`（单次上限 10 分钟 / 600000 ms）、`cpu_count`、
+  `arch_name`、`mem_info`（JSON `{"total_kb":N,"free_kb":M}`，未知平台为 0）、`is_android`。
+- **网络**：`http_get` / `http_post`（返回响应体，失败空串；15 秒超时、8 MiB 上限）、
+  `download`（`0`/`-1`；非 2xx 算失败，落盘上限 256 MiB）。
+- **编码与哈希**：`sha256`（十六进制小写）、`base64_encode`、`base64_decode`（非法输入空串）。
+- **桌面集成**（Termux 优先，再按平台分发，命令缺失即优雅失败）：`clipboard_get` / `clipboard_set`、
+  `notify`、`open_url`。Windows 用 PowerShell `Get-Clipboard` / `cmd /c clip`、`Wscript.Shell.Popup`
+  （10 秒自动消失）、`cmd /c start`；Linux 用 `wl-paste` / `xclip` / `xsel`、`notify-send`、`xdg-open`；
+  macOS 用 `pbpaste` / `pbcopy`、`osascript`、`open`；Android/Termux 用 `termux-clipboard-*`、
+  `termux-notification`、`termux-open-url`。
+- **Android / Termux 扩展**（非 Android 环境一律优雅失败）：`android_intent`（`am start`，Termux 下回退
+  `termux-am`）、`termux_call`、`termux_share`、`termux_torch`、`termux_volume`、`termux_brightness`、
+  `termux_camera_photo`、`termux_fingerprint`、`termux_sensor`。
+- **`os_name()` 说明更新**：除 `"windows"` / `"darwin"` / `"linux"` 外，Android 原生构建返回 `"android"`。
+
+#### 键盘输入监听（SYS 116..118，非阻塞轮询）
+
+- **`key_hit()` / `get_key()` / `key_flush()`**：面向游戏循环 / TUI 的非阻塞键盘轮询，
+  核心实现全部由 Go 原生引擎承担（纯标准库，零第三方依赖）。
+  - `key_hit()` -> `1` 有待读按键 / `0` 无；
+  - `get_key()` -> 取出一个键码，无按键返回 `-1`；`0..255` 为原始字节
+    （Ctrl+字母 = 字母 & 0x1F，监听期间 Ctrl+C 不再终止程序），
+    方向键 / Home / End / PgUp / PgDn / Ins / Del 映射为 `1001..1010`，
+    F1..F10 映射为 `1021..1030`（Unix 转义序列与 Windows 扫描码在引擎内统一解码）；
+  - `key_flush()` -> 清空键盘输入缓冲。
+- **平台实现**：Windows 用 msvcrt `_kbhit`/`_getch`；Linux / macOS / Termux 用
+  termios 原始输入（只关行缓冲 / 回显 / Ctrl+C 信号，保留输出处理，
+  `println` 不受影响）；程序退出自动恢复终端设置（幂等，覆盖所有执行出口）。
+- **终端缓存兼容**：激活监听时清空控制台输入残留（Windows `FlushConsoleInputBuffer` /
+  Unix 非阻塞排空）；Windows 启用前先以 `GetConsoleMode` 校验 stdin 为控制台，
+  管道 / 重定向的判定与非 Windows 一致。
+- **顺序输出（禁止一股脑输出）**：真实终端下激活监听时，原生引擎先把已缓冲输出
+  落到终端，之后逐条直写 stdout 实时可见 —— "提示 → 等按键 → 反馈"顺序正确；
+  非终端环境（管道 / 重定向 / 测试捕获）保持"缓冲 + 结束回传"不变。
+- **非终端环境优雅失败**：`key_hit` 恒 `0`，`get_key` 恒 `-1`，不阻塞、不报错。
+- **`codecin/lib/key.cin` 标准库**：`enum Key` 键码常量（`K_UP`..`K_F10`、
+  `K_ESC` `K_ENTER` `K_TAB` `K_BACKSPACE`）+ `k_ctrl`（Ctrl 组合键码）+
+  `k_is_special`（扩展键码判定）+ `key_wait`（10ms 轮询阻塞等一键）。
+- 三个内建同时注册进 Python 编译器 `HOST_BUILTINS` 表；纯解释路径
+  （`--no-native`）调用报 `require the native Go runtime`（与全部宿主 API 一致），
+  `--sandbox` 同样拦截；`cpu.py` 宿主能力判定由编号区间改为
+  `>= AUDIOPLAY` 下界，未来新增宿主 SYS 不再漏判。
+
+### 文档 (Docs)
+
+- `docs/CIN_GUIDE.md`：新增「enum 枚举」「范围 for」「转义序列」小节，`switch` 增加多值/范围 case，
+  `for` 说明 init 赋值，`print`/`println` 改为多参数签名；宿主能力新增 6 个分组的 API 表
+  （路径与文件系统 / 时间与系统 / 网络 / 编码与哈希 / 桌面集成，含各平台机制对照表 / Android-Termux 扩展）、
+  限制与常见错误同步。
+- `docs/language/`：`types.md`（新增 enum 类型）、`control-flow.md`（范围 for、case 范围）、
+  `lexical.md`（转义表、关键字、续行运算符 `..`）、`strings.md`、`builtins.md`、`host-abilities.md`
+  （网络 / 编码 / 桌面 / Android 分组与能力矩阵）、`errors.md`、`arrays.md`、`variables.md`、`index.md` 同步。
+- `docs/beginner/`：`cheatsheet.md`、`ch11-io-host.md`（新增网络、编码与哈希、桌面集成、路径与文件管理、
+  时间与系统、Android/Termux 扩展小节）、`ch04-conditions.md`、`ch05-loops.md`、`index.md` 同步。
+- `misc/vim/syntax/cin.vim`：`enum` 加入类型高亮，36 个新宿主内建加入 `cinBuiltin`。
+- `docs/CIN_GUIDE.md`：新增「宿主能力: 键盘输入监听（非阻塞轮询）」分节
+  （键码约定表 + 游戏循环示例 + 平台实现与输出行为说明），官方标准库清单收录 `key.cin`。
+- 修正 `input()` 的过时描述（`docs/language/builtins.md`、`beginner/ch02-variables.md`、
+  `ch11-io-host.md`、`ch12-debug.md`、`cheatsheet.md`、`projects.md`）：
+  自本版起 `input()` 已真实现（读一行标准输入，非法行 / EOF 返回 `0`），
+  相关章节与避坑清单同步为实际行为；`cheatsheet.md` 的 `sqrt(-1)` 条目
+  同步为"两条路径一致返回 NaN"。
+- 本版宿主 API 均为 **Go 原生引擎实现**：纯解释路径（`--no-native`）调用会报
+  `host builtins (GUI/audio/system/Termux) require the native Go runtime`；
+  它们具备真实文件与网络权限，请只运行可信脚本。
+
+---
+
+## [5.5.3] - 2026-09-26
+
+以「消除静默算错地址」为主线的一次修复发布：两个会**读错/写错内存且不报错**的
+代码生成缺陷，配套文档站独立与 CI 适配。
+
+### 修复 (Fixed)
+
+#### 嵌套下标算错基址（静默读写错误内存）
+- **`A[B[i]]` 一类的嵌套下标把外层基址弄丢**。编译器约定是"任何跨子表达式存活
+  的临时值都存栈"，但 `_gen_index` 把数组/字符串基址暂存在 `x3` 才去求下标；
+  内层下标自己也要用 `x3` 存基址，于是外层 `ADD` 用的是**内层数组的基址**：
+  `A[B[i]]` 被算成 `&B[0]`，读取静默得到错值、赋值静默写到别的变量内存上
+  （不越界、不报错）。实测 11 个用例里 10 个算错。
+  现在基址改为入栈（`PUSH`/`POP`），Python 与 Go 两个编译器同步修复。
+- **同类缺陷一并修掉**：`_gen_assign` 把待写入的值放在 `x2` 之后才求左值地址
+  （`A[f(i)] = v` 会存错值）；`gen_init_2d_literal` 把行指针数组 `x4`、当前行
+  `x5` 跨元素表达式存活（`int[][] m = {{g(1), g(2)}, ...}` 元素含函数调用时写错行）。
+  两处均改为求值前入栈。
+
+#### 浮点下标被当成字节偏移
+- **`G_C[(lo + hi) / 2]` 抛 `address 379800000000000 out of bounds`**
+  （issue #1）。`/` 恒为浮点除法，所以下标类型是 float，而 `_gen_index` 是唯一
+  漏掉"int 上下文隐式截断"的地方：float 的 IEEE-754 位模式被直接当作字节偏移
+  乘 8（249.5 的位模式 × 8 = `0x0379_8000_0000_0000`，正是报告里那个恒定高位
+  `0x3798`）。标准 Hoare 快排因此完全无法运行。现在数组与字符串下标都会先按
+  与 `int x = 1.9` 一致的规则向零截断，且截断发生在边界检查之前。
+
+### 变更 (Changed)
+
+- **文档站迁至独立仓库** [Code-CIN-Docs](https://github.com/ByUsiStudio/Code-CIN-Docs)：
+  本仓库不再内嵌 `docs/` 子模块（`.gitmodules` 不再使用），README 相应改为单独克隆；
+  ISA 指令表文档一致性由文档仓库自己保证（`script/gen_isa_docs.py` 保留为生成器）。
+- **CI 适配 Node 20 下线**（GitHub 于 2026-09-23 移除 Node 20 运行时）：工作流里
+  全部动作升级到 Node 24 版本 —— `checkout@v6`、`setup-python@v7`、`setup-go@v7`、
+  `upload-artifact@v7`、`download-artifact@v7`、`softprops/action-gh-release@v3`。
+- **修复 `release.yml` 的非法工作流**：4 个 checkout 步骤各写了两个 `with:` 键，
+  GitHub 会判 `Invalid workflow file`（发布流程此前根本跑不起来）。同时移除所有
+  `submodules: recursive` 与已失效的文档一致性检查步骤。
+- **`requirements-dev.txt` 补 `PyYAML`**：`tests/test_workflows.py` 用
+  `pytest.importorskip('yaml')`，缺依赖时整块门禁被静默跳过 —— 上面那个重复键
+  错误就是这样漏过 CI 的。该文件现在还会检测**同层重复键**（PyYAML 默认静默
+  后者覆盖前者）。
+- **`.gitignore`/leak-check 排除表**补 `.gotmp`、`.gocache`、`pytest-cache-*`
+  （都是记录在案的临时/构建目录）；`MANIFEST.in` 去掉已不存在的 `docs/` 条目。
+
+### 测试 (Tests)
+- 新增 `tests/test_nested_subscript_codegen.py`：17 个嵌套下标用例 × 解释器/JIT/
+  原生三条路径，另有"写 `A[B[i]]` 不得触碰 `B` 的内存"用例；回退修复后 52 条中
+  46 条失败。
+- `codecin/native/compiler/compile_test.go` 新增同类 Go 侧用例（编译后直接在
+  Go VM 中执行）。
+
+---
+
 ## [5.5.0] - 2026-09-24
 
 以「Python 只做 CLI、Go 是唯一实现」为主线的架构收敛，配套标准库打包修复与 AOT 依赖加固。

{codecin-5.5.0 → codecin-5.6.0}/MANIFEST.in

@@ -7,7 +7,13 @@ recursive-include codecin/lib *.cin
 recursive-include codecin/native *.go *.txt go.mod go.sum build.sh build.ps1
 # 注: 不 include 预编译原生库 (*.dll/*.so/*.dylib) —— 它们在用户安装时由
 # setup.py 现场编译, 见 pyproject.toml 的 package-data 说明。
-recursive-include docs *.md
+# 注: 文档站已迁至独立仓库 Code-CIN-Docs, 本仓库不再有 docs/ —— 这里不收
+# docs 内容, 以免本地残留的文档检出 (node_modules 里有大量 *.md) 被误打进 sdist。
+# 注: Go 构建缓存 (AOT 构建器在只读 HOME 下的回退目录) 不属于源码。
+prune codecin/native/.gocache
+# 兜底: 任何本地编译出的预编译库都不得进入 sdist —— 即使 egg-info/SOURCES.txt
+# 里残留了历史条目 (setuptools 会保留已存在文件的旧清单), 这里也强制排除。
+global-exclude *.dll *.so *.dylib
 recursive-include misc *
 recursive-include examples *.cin *.asm *.pl
 recursive-include script *.py

{codecin-5.5.0/codecin.egg-info → codecin-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecin
-Version: 5.5.0
+Version: 5.6.0
 Summary: Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + Go 原生 VM + ARM64/RISC-V/FP/Vector 指令集)
 Author: ByUsi Studio, 北啊呢
 License-Expression: MIT
@@ -36,12 +36,35 @@ Code CIN 是一门简洁的类 C 高级语言及其跨平台运行时（VM）。
 
 ## 文档
 
+**官方文档站**位于独立仓库
+[Code-CIN-Docs](https://github.com/ByUsiStudio/Code-CIN-Docs) (VitePress +
+vitepress-plugin-tabs); 线上站点即由该仓库构建。本仓库不再内嵌 `docs/`
+(子模块已移除), 需要本地预览时请**单独克隆该仓库**:
+
+```bash
+git clone https://github.com/ByUsiStudio/Code-CIN-Docs.git
+cd Code-CIN-Docs
+npm install
+npm run docs:dev                           # 本地预览 (http://localhost:5173)
+npm run docs:build                         # 构建静态站点到 .vitepress/dist
+```
+
+站点内容划分: `guide/` (安装/快速开始/命令行/执行路径/架构/示例/FAQ)、`language/` (CIN 语言)、
+`asm/` (汇编与 ISA)、`stdlib/` (内置标准库参考)、`runtime/` (原生/JIT/格式/AOT)、
+`tools/` (调试器/远程调试/日志/性能/内存缓存)、`reference/` (ISA 编码表/寄存器与内存/Python API/更新日志)、
+`dev/` (项目结构/构建/测试/打包/扩展/贡献)。
+
+仓库的开发用文档**全部在独立仓库** [Code-CIN-Docs](https://github.com/ByUsiStudio/Code-CIN-Docs)
+(不进站点, 供源码树内直接查阅):
+
 | 文档 | 说明 |
 |------|------|
-| [指令集参考 (ISA)](docs/ISA.md) | 由 `codecin/isa.py` 自动生成的逐条指令表 (唯一真源) |
-| [开发者编译文档 (BUILDING)](docs/BUILDING.md) | 环境搭建、Go 原生库编译、构建产物、打包、日志系统、扩展指南 |
-| [CIN 编程指南 (CIN_GUIDE)](docs/CIN_GUIDE.md) | CIN 高级语言完整语法：类型/函数/struct/数组/字符串/内建函数 |
-| [远程调试协议 (REMOTE_DEBUG)](docs/REMOTE_DEBUG.md) | `--debug-server` 换行文本协议：命令/响应/状态机/示例会话 |
+| [指令集参考 (ISA)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md) | 由 `codecin/isa.py` 自动生成的逐条指令表 (唯一真源; 站点版为 `reference/isa.md`) |
+| [开发者编译文档 (BUILDING)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/BUILDING.md) | 环境搭建、Go 原生库编译、构建产物、打包、日志系统、扩展指南 |
+| [CIN 编程指南 (CIN_GUIDE)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/CIN_GUIDE.md) | CIN 高级语言完整语法：类型/函数/struct/数组/字符串/内建函数 |
+| [远程调试协议 (REMOTE_DEBUG)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/REMOTE_DEBUG.md) | `--debug-server` 换行文本协议：命令/响应/状态机/示例会话 |
+
+> 这些文件不在本仓库内: 需要时单独 `git clone` 上述文档仓库即可。
 
 ---
 
@@ -229,7 +252,8 @@ pie title Code CIN 指令集组成
 ```
 
 > 指令总数与分组由 `python script/gen_isa_docs.py` 依据 `codecin/isa.py` 自动生成/校验;
-> 完整的逐条指令表见 [docs/ISA.md](docs/ISA.md)。ARM64 的 WFE/WFI/SEV 无事件模型, 语义等同 NOP。
+> 完整的逐条指令表见 [ISA.md](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md)
+> (文档站已在独立仓库)。ARM64 的 WFE/WFI/SEV 无事件模型, 语义等同 NOP。
 
 ### 指令分类
 
@@ -393,7 +417,8 @@ flowchart TD
 **安装（pip）**
 
 ```bash
-pip install codecin          # 内置标准库 (codecin/lib/*.cin) 随包分发
+pip install codecin          # 安装 (内置标准库 codecin/lib/*.cin 随包分发)
+pip install -U codecin       # 升级到最新版 (不要锁定版本号)
 codecin --version
 ```
 
@@ -430,7 +455,6 @@ codecin --version
 
 ```bash
 python -m pytest                            # 指令黄金 / 三路径一致性 / 断点回归 / 内存保护 / CLI
-python script/gen_isa_docs.py --check       # docs/ISA.md 与指令集同步
 python script/gen_native_isa.py --check     # Go 原生常量与指令集同步
 ruff check codecin cpu.py script tests
 ```
@@ -438,7 +462,8 @@ ruff check codecin cpu.py script tests
 仓库内置 GitHub Actions CI (`.github/workflows/ci.yml`): 多 Python 版本测试、ruff、Go 构建校验,
 一个 `integration` 作业会**真实编译原生库**后跑全量测试 (带覆盖率门槛),
 以及一个 `dist` 作业断言 wheel/sdist 里确实带有内置标准库。
-完整逐条指令表由 `script/gen_isa_docs.py` 从 `codecin/isa.py` 生成至 [docs/ISA.md](docs/ISA.md)。
+完整逐条指令表由 `script/gen_isa_docs.py` 从 `codecin/isa.py` 生成到文档仓库
+([ISA.md](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md))。
 
 ### 执行路径
 
@@ -817,67 +842,81 @@ function main() {
 
 ### 斐波那契 (PL)
 
-```
+```asm
 .text
-    set x0, 10          // n = 10
-    call fibonacci
-    out x0
-    halt
-
-fibonacci:
-    cmp x0, 1
-    jle base_case
+main:
+    set x0, 10          ; n = 10
+    call fib
+    sys #22             ; ITOA: x0 -> 十进制字符串
+    sys #24             ; PRINT_STR
+    output #10
+    stop
+
+fib:                    ; 入口 x0 = n, 返回 x0 = fib(n)
+    compare x0, 1
+    jump_greater recurse
+    set x0, 1
+    return
+
+recurse:
     push x0
-    sub x0, 1
-    call fibonacci
+    decrement x0
+    call fib
     pop x1
     push x0
+    set x0, x1
+    decrement x0
+    decrement x0
+    call fib
+    pop x1
     add x0, x1
-    ret
-
-base_case:
-    set x0, 1
-    ret
+    return
 ```
 
-### 快速排序 (ASM)
+> 注意: 本 ISA **没有 `jle` / `jge`** 这类指令, 比较请用 `CMP` + `JG`/`JL`/`JE`
+> (PL 风格: `compare` + `jump_greater`/`jump_less`/`jump_equal`), 或 ARM64 的 `B.<cond>`。
+> 上面这段实测输出 `89`; 完整语法与逐条语义见文档站 (仓库内路径 `docs/asm/`)。
 
-```
-; 快速排序实现
+### 循环求和 + 字符串打印 (ASM, 见 `test_asm.asm`)
+
+```asm
 .text
 main:
-    ldr x0, =array
-    ldr x1, =size
-    bl quicksort
-    halt
-
-quicksort:
-    cmp x0, x1
-    bge done
-    
-    ; Partition
-    ldr x2, [x0]        ; pivot
-    mov x3, x0
-    mov x4, x1
-    
-partition:
-    cmp x3, x4
-    bge swap_pivot
-    
-    ldr x5, [x3]
-    cmp x5, x2
-    ble swap_left
-    
-    ; ... 更多代码
-    
-done:
-    ret
+    MOV x0, #msg
+    SYS #24              ; PRINT_STR
+
+    MOV x1, #0           ; sum
+    MOV x2, #1           ; i
+loop:
+    ADD x1, x2
+    INC x2
+    CMP x2, #11
+    B.NE loop
+
+    MOV x0, x1
+    SYS #22              ; ITOA -> x0 = 缓冲
+    SYS #24              ; PRINT_STR
+    OUT #10              ; 换行
+
+    MOV x3, #nums
+    SD x1, [x3]          ; 存回数据段
+    LD x4, [x3]
+    ADDI x4, x4, #100
+    MOV x0, x4
+    SYS #22
+    SYS #24
+    OUT #10
+
+    HALT
 
 .data
-array: .word 5, 3, 8, 1, 9, 2, 7, 4, 6
-size: .word 9
+msg: ASCIZ "Sum 1..10 = "
+nums: DQ 0
 ```
 
+> 实测输出: `Sum 1..10 = 55` 与 `155` (退出码 0)。更多汇编示例 (递归、数组遍历、
+> 立即数与表达式、条件后缀) 见文档站 `docs/asm/` 与 `docs/guide/examples.md`。
+
 ---
 
 ## 技术栈

{codecin-5.5.0 → codecin-5.6.0}/README.md

@@ -18,12 +18,35 @@ Code CIN 是一门简洁的类 C 高级语言及其跨平台运行时（VM）。
 
 ## 文档
 
+**官方文档站**位于独立仓库
+[Code-CIN-Docs](https://github.com/ByUsiStudio/Code-CIN-Docs) (VitePress +
+vitepress-plugin-tabs); 线上站点即由该仓库构建。本仓库不再内嵌 `docs/`
+(子模块已移除), 需要本地预览时请**单独克隆该仓库**:
+
+```bash
+git clone https://github.com/ByUsiStudio/Code-CIN-Docs.git
+cd Code-CIN-Docs
+npm install
+npm run docs:dev                           # 本地预览 (http://localhost:5173)
+npm run docs:build                         # 构建静态站点到 .vitepress/dist
+```
+
+站点内容划分: `guide/` (安装/快速开始/命令行/执行路径/架构/示例/FAQ)、`language/` (CIN 语言)、
+`asm/` (汇编与 ISA)、`stdlib/` (内置标准库参考)、`runtime/` (原生/JIT/格式/AOT)、
+`tools/` (调试器/远程调试/日志/性能/内存缓存)、`reference/` (ISA 编码表/寄存器与内存/Python API/更新日志)、
+`dev/` (项目结构/构建/测试/打包/扩展/贡献)。
+
+仓库的开发用文档**全部在独立仓库** [Code-CIN-Docs](https://github.com/ByUsiStudio/Code-CIN-Docs)
+(不进站点, 供源码树内直接查阅):
+
 | 文档 | 说明 |
 |------|------|
-| [指令集参考 (ISA)](docs/ISA.md) | 由 `codecin/isa.py` 自动生成的逐条指令表 (唯一真源) |
-| [开发者编译文档 (BUILDING)](docs/BUILDING.md) | 环境搭建、Go 原生库编译、构建产物、打包、日志系统、扩展指南 |
-| [CIN 编程指南 (CIN_GUIDE)](docs/CIN_GUIDE.md) | CIN 高级语言完整语法：类型/函数/struct/数组/字符串/内建函数 |
-| [远程调试协议 (REMOTE_DEBUG)](docs/REMOTE_DEBUG.md) | `--debug-server` 换行文本协议：命令/响应/状态机/示例会话 |
+| [指令集参考 (ISA)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md) | 由 `codecin/isa.py` 自动生成的逐条指令表 (唯一真源; 站点版为 `reference/isa.md`) |
+| [开发者编译文档 (BUILDING)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/BUILDING.md) | 环境搭建、Go 原生库编译、构建产物、打包、日志系统、扩展指南 |
+| [CIN 编程指南 (CIN_GUIDE)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/CIN_GUIDE.md) | CIN 高级语言完整语法：类型/函数/struct/数组/字符串/内建函数 |
+| [远程调试协议 (REMOTE_DEBUG)](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/REMOTE_DEBUG.md) | `--debug-server` 换行文本协议：命令/响应/状态机/示例会话 |
+
+> 这些文件不在本仓库内: 需要时单独 `git clone` 上述文档仓库即可。
 
 ---
 
@@ -211,7 +234,8 @@ pie title Code CIN 指令集组成
 ```
 
 > 指令总数与分组由 `python script/gen_isa_docs.py` 依据 `codecin/isa.py` 自动生成/校验;
-> 完整的逐条指令表见 [docs/ISA.md](docs/ISA.md)。ARM64 的 WFE/WFI/SEV 无事件模型, 语义等同 NOP。
+> 完整的逐条指令表见 [ISA.md](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md)
+> (文档站已在独立仓库)。ARM64 的 WFE/WFI/SEV 无事件模型, 语义等同 NOP。
 
 ### 指令分类
 
@@ -375,7 +399,8 @@ flowchart TD
 **安装（pip）**
 
 ```bash
-pip install codecin          # 内置标准库 (codecin/lib/*.cin) 随包分发
+pip install codecin          # 安装 (内置标准库 codecin/lib/*.cin 随包分发)
+pip install -U codecin       # 升级到最新版 (不要锁定版本号)
 codecin --version
 ```
 
@@ -412,7 +437,6 @@ codecin --version
 
 ```bash
 python -m pytest                            # 指令黄金 / 三路径一致性 / 断点回归 / 内存保护 / CLI
-python script/gen_isa_docs.py --check       # docs/ISA.md 与指令集同步
 python script/gen_native_isa.py --check     # Go 原生常量与指令集同步
 ruff check codecin cpu.py script tests
 ```
@@ -420,7 +444,8 @@ ruff check codecin cpu.py script tests
 仓库内置 GitHub Actions CI (`.github/workflows/ci.yml`): 多 Python 版本测试、ruff、Go 构建校验,
 一个 `integration` 作业会**真实编译原生库**后跑全量测试 (带覆盖率门槛),
 以及一个 `dist` 作业断言 wheel/sdist 里确实带有内置标准库。
-完整逐条指令表由 `script/gen_isa_docs.py` 从 `codecin/isa.py` 生成至 [docs/ISA.md](docs/ISA.md)。
+完整逐条指令表由 `script/gen_isa_docs.py` 从 `codecin/isa.py` 生成到文档仓库
+([ISA.md](https://github.com/ByUsiStudio/Code-CIN-Docs/blob/main/ISA.md))。
 
 ### 执行路径
 
@@ -799,67 +824,81 @@ function main() {
 
 ### 斐波那契 (PL)
 
-```
+```asm
 .text
-    set x0, 10          // n = 10
-    call fibonacci
-    out x0
-    halt
-
-fibonacci:
-    cmp x0, 1
-    jle base_case
+main:
+    set x0, 10          ; n = 10
+    call fib
+    sys #22             ; ITOA: x0 -> 十进制字符串
+    sys #24             ; PRINT_STR
+    output #10
+    stop
+
+fib:                    ; 入口 x0 = n, 返回 x0 = fib(n)
+    compare x0, 1
+    jump_greater recurse
+    set x0, 1
+    return
+
+recurse:
     push x0
-    sub x0, 1
-    call fibonacci
+    decrement x0
+    call fib
     pop x1
     push x0
+    set x0, x1
+    decrement x0
+    decrement x0
+    call fib
+    pop x1
     add x0, x1
-    ret
-
-base_case:
-    set x0, 1
-    ret
+    return
 ```
 
-### 快速排序 (ASM)
+> 注意: 本 ISA **没有 `jle` / `jge`** 这类指令, 比较请用 `CMP` + `JG`/`JL`/`JE`
+> (PL 风格: `compare` + `jump_greater`/`jump_less`/`jump_equal`), 或 ARM64 的 `B.<cond>`。
+> 上面这段实测输出 `89`; 完整语法与逐条语义见文档站 (仓库内路径 `docs/asm/`)。
 
-```
-; 快速排序实现
+### 循环求和 + 字符串打印 (ASM, 见 `test_asm.asm`)
+
+```asm
 .text
 main:
-    ldr x0, =array
-    ldr x1, =size
-    bl quicksort
-    halt
-
-quicksort:
-    cmp x0, x1
-    bge done
-    
-    ; Partition
-    ldr x2, [x0]        ; pivot
-    mov x3, x0
-    mov x4, x1
-    
-partition:
-    cmp x3, x4
-    bge swap_pivot
-    
-    ldr x5, [x3]
-    cmp x5, x2
-    ble swap_left
-    
-    ; ... 更多代码
-    
-done:
-    ret
+    MOV x0, #msg
+    SYS #24              ; PRINT_STR
+
+    MOV x1, #0           ; sum
+    MOV x2, #1           ; i
+loop:
+    ADD x1, x2
+    INC x2
+    CMP x2, #11
+    B.NE loop
+
+    MOV x0, x1
+    SYS #22              ; ITOA -> x0 = 缓冲
+    SYS #24              ; PRINT_STR
+    OUT #10              ; 换行
+
+    MOV x3, #nums
+    SD x1, [x3]          ; 存回数据段
+    LD x4, [x3]
+    ADDI x4, x4, #100
+    MOV x0, x4
+    SYS #22
+    SYS #24
+    OUT #10
+
+    HALT
 
 .data
-array: .word 5, 3, 8, 1, 9, 2, 7, 4, 6
-size: .word 9
+msg: ASCIZ "Sum 1..10 = "
+nums: DQ 0
 ```
 
+> 实测输出: `Sum 1..10 = 55` 与 `155` (退出码 0)。更多汇编示例 (递归、数组遍历、
+> 立即数与表达式、条件后缀) 见文档站 `docs/asm/` 与 `docs/guide/examples.md`。
+
 ---
 
 ## 技术栈

{codecin-5.5.0 → codecin-5.6.0}/codecin/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "5.5.0"
+__version__ = "5.6.0"
 __author__ = "ByUsi Studio"
 
 from .config import Config

{codecin-5.5.0 → codecin-5.6.0}/codecin/assembler.py

@@ -36,12 +36,12 @@ def _eval_expr(text: str, symbols: Dict[str, int]) -> Optional[int]:
         raw = match.group(0).replace('_', '')
         if len(raw) > 1 and raw[:2].lower() in ('0x', '0b', '0o'):
             raw = '0' + raw[1].lower() + raw[2:]
-        try:
-            return str(int(raw, 0))
-        except ValueError:
-            return '0'
+        return str(int(raw, 0))  # 非法字面量 (如 0x_) 抛 ValueError -> 整体求值失败
 
-    text = _RE_EXPR_NUM.sub(repl_num, text)
+    try:
+        text = _RE_EXPR_NUM.sub(repl_num, text)
+    except ValueError:
+        return None
 
     def repl_name(match):
         name = match.group(0)