codecin 5.6.0__tar.gz → 5.8.0__tar.gz

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

@@ -5,6 +5,259 @@
 
 ---
 
+## [5.8.0] - 2026-10-04
+
+一次「图形、媒体与跨平台兼容」发布：新增 **GUI 窗口**（Windows Win32 /
+Linux X11）、**本地音频扩展**（真实音量 / 播放进度 / 合成蜂鸣）、**键盘输入
+多平台优化**（Unicode 码点、F11/F12、修饰键组合），并补齐 **命令行参数与
+行输入**（SYS 129..131）、**终端输出缓存的跨平台冲刷**（Windows VT/UTF-8
+初始化）与 **C/C++/Go 三语言标准库兼容层**（36 → 39 个）。随后在同一版本内
+继续增强：**音频控制全家桶**（查询 / 暂停恢复 / 音量读取，SYS 132..136）、
+**三兼容层 API 扩容**（40+ 新函数）、**工具链缺失检测与平台化安装提示**
+（environment）与 **`--libs` 内置库清单**（标注执行路径要求）。核心实现全部
+在 Go 原生引擎（纯标准库，零第三方依赖），三条执行路径语义与 5.7.x 保持一致。
+
+### 新增 (Added)
+
+#### GUI 窗口（SYS 119..125、128，全部 Go 原生实现）
+
+- **`gui_new(w, h, title)` / `gui_update()` / `gui_close()` / `gui_closed()` /
+  `gui_active()` / `mouse_x()` / `mouse_y()` / `mouse_button()`**：
+  - `gui_new` 成功返回 0 并把画布内建（`set_color` / `fill_rect` / `fill_circle` /
+    `draw_line` / `draw_text`）直接绑定为**窗口后备缓冲直画**，`gui_update`
+    处理事件并呈现一帧（主循环每帧调用）；`gui_close` 销毁窗口（画布保留，
+    仍可 `save_png`）；点 X / Alt+F4 / WM 删除协议由 `gui_closed` 报告。
+  - 平台后端：Windows 用 Win32（专用窗口线程 + 消息泵，`StretchDIBits`
+    呈现，`AdjustWindowRect` 精确客户区）；Linux 用**纯 Go X11 客户端**
+    （Unix socket / TCP 连接、MIT-MAGIC-COOKIE-1 认证、`PutImage` 分块呈现、
+    WM_DELETE_WINDOW 协议）；其他平台与无显示服务环境一律优雅失败
+    （`gui_new` 返回 -1，不报错不崩溃）。
+  - 鼠标：客户区坐标 + 键位掩码（bit0 左 / bit1 右 / bit2 中）；键盘事件注入
+    与终端共用的同一键码队列（`get_key` 可直接读）。
+  - 并发安全：快照复制防撕裂（呈现线程读 / VM 线程写）。
+- **`codecin/lib/gui.cin` 重构**：窗口封装 `g_new` / `g_update` / `g_close` /
+  `g_closed` / `g_active` / `g_clear` / `g_mouse_*`（含键位判定），并**保留**
+  5.7.x 的离屏绘图助手（`g_rgb` / `g_bar_chart` / `g_line_chart` / `g_grid` /
+  `g_rect_outline` / `g_save` / `g_show`）。
+
+#### 本地音频扩展（SYS 126、127）
+
+- **`audio_pos()`**：当前播放已进行毫秒；无播放 / 已播完 / 时长未知返回 -1。
+- **`beep(freq, ms)`**：合成 16-bit 单声道 22050Hz 正弦蜂鸣（10% / 5ms 淡入
+  淡出防爆音）；频率 20..20000 Hz、单次上限 10 秒，参数校验在三平台一致地
+  于触碰设备之前完成。
+- Windows 后端从 PlaySoundW 升级为 **waveOut 流式**：`audio_volume` 经
+  `waveOutSetVolume` 实时生效、`audio_stop` 即时中止（`waveOutReset`）；
+  Unix 后端向 `paplay` / `ffplay` / `afplay` 透传音量参数。
+
+#### 音频控制增强（SYS 132..136）
+
+- **`audio_duration()`**：当前播放总时长毫秒；无播放 / 自然播完 / 时长未知返回 -1
+  （播放与暂停期间返回同一总时长）。
+- **`audio_playing()`**：1 = 正在发声（已开始、未暂停、未播完），否则 0。
+- **`audio_pause()`**：暂停当前播放（Windows `waveOutPause`；Unix 向播放器
+  进程投递 SIGSTOP），成功 0；无播放 / 已暂停 / 平台失败为 -1。
+- **`audio_resume()`**：恢复暂停的播放，时间基线整体后移暂停时长——
+  `audio_pos` 无缝续走、自然结束时刻保持正确；成功 0 / 无暂停可恢复 -1。
+- **`audio_level()`**：读取当前音量 0..100（`audio_volume` 的读端）。
+- **`audio_pos` 暂停冻结**：暂停期间进度停在暂停时刻，不随真实时间前进；
+  `audio_stop` / 重新播放即解除暂停态。
+- 五个内建在两侧编译器同步登记，ISA 真源（`isa.py`）→ Go 生成物一致。
+
+#### 键盘输入多平台优化（键码表扩展）
+
+- 新增键码：**F11 / F12**（1031 / 1032）、**Ctrl+方向**（1101..1104）、
+  **Shift+方向**（1105..1108）、**Shift+Tab**（1109）。
+- **XTerm 修饰参数解析**：`CSI 1;5C`（Ctrl+Right）等修饰变体三端一致。
+- **Unicode 码点解码**（Linux / macOS / Termux）：终端 UTF-8 多字节序列解码为
+  码点（>255，如 "中" → 0x4E2D），非法序列回退按字节处理；Windows 端
+  UTF-16 代理对组合为同一码点。
+- **Windows 输入重写**：msvcrt `_getch` → `ReadConsoleInputW` 事件流
+  （UTF-16 字符 + VK 虚拟键，键抬起过滤、重复计数、扩展键），启用时关闭
+  QuickEdit 防误选卡死。
+- `codecin/lib/key.cin`：`K_F11` / `K_F12` / `K_CTRL_*` / `K_SHIFT_*` /
+  `K_SHIFT_TAB` 常量与 `k_is_function` / `k_is_modified_arrow` 判定；
+  `k_is_special` 范围同步扩展。
+
+#### 命令行参数与行输入（SYS 129..131，跨平台一致语义）
+
+- **`arg_count()` / `arg(i)`**：读取传给 CIN 程序的命令行参数（不含程序文件名；
+  越界 / 负下标返回空串）。传参约定三端统一：
+  - CLI：`codecin prog.cin -- a b c`（`--` 之后的参数全部交给 CIN 程序）；
+  - AOT 产物：直接取进程 `os.Args[1:]`；
+  - c-shared 库：新导出 `codecin_set_args`，Python 桥接层每次运行前注入
+    （空列表即清空，同进程多次运行不残留）。
+- **`input_str()`**：读入一行 UTF-8 文本（不含行尾；EOF 为空串）。优先消费
+  预读输入缓冲（与解释器 `input()` 的管道语义一致），耗尽后阻塞读标准输入；
+  Windows 控制台用 `ReadConsoleW`（UTF-16 → UTF-8，中文输入不乱码），其余平台
+  用 `bufio` 按行读；行尾 `\n` / `\r\n` 三平台统一剥离，与键盘 raw 模式
+  （监听激活时临时恢复行模式）互不干扰。
+- 新内建在两侧编译器同步登记（`arg_count` / `arg` / `input_str`）。
+
+#### 终端输出缓存与 Windows 控制台兼容
+
+- **阻塞读前冲刷输出缓冲**：原生引擎把输出缓冲到程序结束一次性回传；
+  当 `input_str()` / 数字输入将要阻塞读真实终端时先冲刷已缓冲输出，
+  `"你的名字: "` 这类交互提示立即可见。冲刷**仅在 stdout 为终端时生效**——
+  管道 / 重定向 / 测试捕获下输出字节序列与旧版本完全一致。
+- **Windows 控制台一次性初始化**（进程级、幂等、失败安全）：
+  `ENABLE_VIRTUAL_TERMINAL_PROCESSING`（ANSI/VT 转义序列在传统 conhost 上
+  与 Linux/macOS 行为一致）+ `SetConsoleOutputCP(65001)`（输出代码页切
+  UTF-8，中文 Windows 默认 GBK 下中文/Emoji 不再乱码）。
+- AOT 产物在打印输出前执行同一初始化；非 Windows 平台为空操作
+  （终端原生支持 VT 与 UTF-8）。
+
+#### C / C++ / Go 标准库兼容层（36 → 39 个，全部纯 CIN）
+
+- **`codecin/lib/cstd.cin`（`libc_*`）**：`<ctype.h>`（isdigit / toupper …，
+  字符码可用字符字面量 `'A'` 直接传入）、`<string.h>`（strlen / strcmp /
+  strstr / strchr / strrev / memcpy …）、`<stdlib.h>`（abs / atoi / qsort_asc）、
+  `<math.h>`（fabs / sqrt / pow / floor / ceil / fmod 商向零截断）与
+  `<stdio.h>`（puts / print）。
+- **`codecin/lib/cppstd.cin`（`stl_*`）**：`std::string`（find / rfind /
+  substr / append / to_string，npos 以 -1 表示）、`vector<int>` / `stack<int>` /
+  `queue<int>`（**数组 + 长度游标**表达，push/pop 返回新长度）、
+  `<utility>`（max / min / abs / swap / sort 固定升序）。
+- **`codecin/lib/gostd.cin`（`go_*`）**：`strings`（Contains / Index /
+  HasPrefix / Repeat / Count / ReplaceAll / EqualFold …）、`strconv`（Itoa /
+  Atoi / FormatFloat）、`math`、`slices`（Index / Contains / Max / Reverse …）
+  与 `os.Args`（经 `go_os_args_len` / `go_os_args_get`，依赖原生路径）。
+- 类型映射约定：C `char*` → `string`、C `char` → 字符码 `int`、C 数组参数 →
+  CIN 数组引用 + 显式长度；与 C/C++ 指针返回值不可表达的 API（如返回
+  `char*` 的 strchr）以**下标**语义对齐，头注释均注明差异。
+
+#### 兼容层 API 扩容（三库 40+ 新函数，纯 CIN、三路径一致）
+
+- **cstd**：`<ctype.h>` 补 iscntrl / isgraph / isblank / ispunct / toascii；
+  `<string.h>` 补 memmove / strspn / strcspn / strpbrk / strlwr / strupr；
+  `<stdlib.h>` 补 labs / rand / srand；`<math.h>` 补 sin / cos / tan /
+  round（C 语义半值远离零）/ trunc；`<stdio.h>` 补 putchar（配套内部
+  字符码 → 字符串转换）。
+- **cppstd**：`std::string` 补 starts_with / ends_with（C++20）/
+  find_first_of / find_last_of / at / front / back / insert / erase /
+  replace；`vector<int>` 补 find / count / insert / erase；`<algorithm>`
+  补 sort 降序版与 clamp。
+- **gostd**：`strings` 补 LastIndex / IndexAny / TrimLeft / TrimRight /
+  TrimPrefix / TrimSuffix；`strconv` 补 FormatInt（base 2..36）/
+  ParseInt（任意进制解析）；`math` 补 Round / Trunc；`slices` 补
+  LastIndex / Equal / Clone / Sort。
+
+#### 工具链缺失检测与平台化安装提示（environment）
+
+- **`codecin/environment.py`**：`find_tool` / `tool_available`（只读
+  `shutil.which` 探测，绝不自动安装）、`install_hint`（按当前平台给出可复制
+  执行的安装命令：Windows winget/MSYS2、macOS brew/xcode-select、Linux
+  apt/dnf/pacman、Termux pkg）、`missing_tool_message`（缺工具 + 用途 +
+  怎么装合一）、`native_runtime_hint`（原生库缺失时的三条出路指引）。
+- 接入点（所有缺失入口提示一致）：
+  - AOT 构建缺 Go：报错附 `install_hint('go')`（原先只有干巴巴的
+    "go 命令未找到"）；
+  - 解释路径（含 `--no-native`）调用宿主能力内建：报错附原生库安装指引；
+  - pip 安装（`setup.py`）缺 Go：打印安装命令并说明重装后获得原生加速。
+
+#### `--libs`：内置标准库清单与执行路径标注
+
+- 新 CLI 选项 **`--libs`**：列出 `codecin/lib/` 全部官方库并按**执行路径
+  要求**标注三类——纯 CIN（三路径一致）/ 兼容层（C/C++/Go 三语言标准库
+  兼容层）/ 需原生运行时（调用宿主能力内建，`--no-native` 与沙箱下不可用）。
+- 分类由**源码扫描**得出（是否引用 `HOST_BUILTINS` 内建名），与库头注释
+  保持单一事实来源；`gostd.cin` 的 `go_os_args_*` 原生依赖自动标注。
+
+#### 其他
+
+- 新内建在两侧编译器同步登记：Python `HOST_BUILTINS` 与 Go
+  `compiler.hostBuiltins`（并补上 5.6.0 遗漏的 `key_hit` / `get_key` /
+  `key_flush`）。
+- 新示例：`examples/gui_demo.cin`（无显示服务自动降级为提示后退出）、
+  `examples/local_audio.cin`、`examples/args_demo.cin`（`--` 传参与
+  `input_str`）。
+- 新测试：`tests/test_lib_compat.py`（三兼容层函数语义、参数注入管道、
+  预读缓冲行输入、无原生库可编译，解释 / 原生双路径参数化）。
+- 本轮新增：Go 侧 `engine/audio_test.go`（audio_duration / playing /
+  pause / resume 状态机、暂停冻结、自然播完回落）、`tests/test_environment.py`
+  （安装提示契约）、`tests/test_cli.py::test_list_libs_reports_categories`
+  （--libs 分类标注）；`examples/local_audio.cin` 增补音量读取与暂停 /
+  恢复演示。
+
+### 变更 (Changed)
+
+- **`lib/gui.cin` 签名变更**（窗口化重构）：`g_new(w, h)` → `g_new(w, h, title)`
+  （旧的无窗口画布用法请直接使用 `canvas(w, h)`）；`g_clear(w, h, rgb)` →
+  `g_clear(rgb)`（沿用最近一次窗口尺寸，从未开窗时返回 -1）。
+  图表助手内部已同步适配，`g_bar_chart` / `g_line_chart` / `g_save` /
+  `g_show` 调用方式不变。
+
+### 修复 (Fixed)
+
+- 音频自然播完后 `audio_pos` 不再恒返回总时长（正确恢复 -1）。
+- GUI：Windows 窗口线程改为常驻，`gui_close` 之后可以再次 `gui_new`；
+  窗口销毁（无论来自 `gui_close` 还是用户点 X）后清理失效句柄。
+- `guiSnapshot` 增加窗口打开校验（关闭后不再产出快照）。
+
+---
+
+## [5.7.4] - 2026-09-28
+
+一次「静默错误清零 + 标准库扩容」的发布：修掉一族会**静默破坏内存/静默给错结果**的
+struct 缺陷与两处**同一程序两条路径结论不同**的分歧，并把官方标准库从 20 个扩到 36 个。
+
+### 新增 (Added)
+
+- **标准库 20 → 36 个**（全部为纯 CIN，只调用语言内建，三条执行路径一致）：
+  - 数据结构与算法：`tree.cin`（`tree_`）、`unionfind.cin`（`uf_`）、`heap.cin`（`heap_`）、
+    `graph.cin`（`graph_`）、`dp.cin`（`dp_`）、`set.cin`（`set_`）、`bitset.cin`（`bs_`）
+  - 文本与格式化：`text.cin`（`txt_`）、`token.cin`（`tok_`）、`fmt.cin`（`fmt_`）、`csv.cin`（`csv_`）
+  - 数值与科学计算：`bigint.cin`（`bi_`，任意精度）、`frac.cin`（`fr_`，有理数）、
+    `combin.cin`（`comb_`，数论与组合）
+  - 工程与系统：`path.cin`（`path_`，纯字符串路径）、`codec.cin`（`codec_`，十六进制/URL/
+    Base64/RLE/摩尔斯/XOR）
+- **`const` 命名常量**：`const int N = 4`（全局与局部），支持 `int/float/bool/string`，
+  纯编译期、不占数据段，可用于**数组维度**与任意表达式；可被同名局部变量遮蔽。
+- **数组维度接受整型常量表达式**：`int a[N]`、`int a[2 + 3]`、`int a[enumMember + 1]`。
+- **struct 聚合初始化**：`P p = {3, 4}`、`P ps[2] = {{1,2},{3,4}}`、嵌套 `Out o = {{5,6},7}`；
+  未列出的字段取默认值，初始化器过多是编译期错误。
+- **`string +=`**：右侧任意可字符串化的值。
+- **`exit(code)`**：立即结束程序，三条路径与 AOT 产物一致。
+- **版本设施**：`codecin/version.py`（`version_info()` / `compare()` / `build_info()` 等，
+  `build_info()` 永不抛异常）、CLI 新增 `--build-info` 与 `--build-info --json`、
+  `script/bump_version.py`（改真源 → 重生成 Go 版本常量 → 插 CHANGELOG 骨架，含回滚与 `--dry-run`）。
+
+### 修复 (Fixed)
+
+- **struct 聚合初始化写穿指针槽**：`P p = {3, 4}` 会把第 2 个字面量写到 `FP + 0`，
+  **覆盖保存的帧指针**；全局 `P o = {3,4}` 覆盖对象指针。现按字段写入堆对象。
+- **struct 数组成员访问写到绝对地址 0 / 8**：元素槽被当成指针解引用，
+  `ps[0].y = 1` 会**静默破坏数据段**（字符串字面量所在处）。现统一为
+  「槽里存对象指针」模型，每个元素各有对象。
+- **初始化器过多时两条路径结论不同**：解释器越界写后返回残值、原生 VM 抛
+  `Address out of bounds`。现为编译期错误 `Too many initializers for struct P`。
+- **struct 整体赋值是指针别名**：`P b = a; b.x = 7` 会改到 `a.x`，与文档承诺的
+  「值拷贝」不符。现按槽逐字拷贝（**传参仍保持文档规定的「引用可见」**）。
+- **嵌套 struct 字段只按 1 槽推进**：`struct Out { In i; int c }` 的 `c` 压在 `i.b` 上；
+  且成员取值会把内嵌字段当指针解引用。两处均已修正。
+- **`parse_array_literal` 静默丢弃尾部平铺元素**：`{{5, 6}, 7}` 里的 `7` 消失。
+- **字符串字节语义分歧**：解释器侧 `+` / `substr` / `indexof` 先做 UTF-8 解码，
+  非法字节序列被替换成 U+FFFD，实测 `strlen(substr("中",2,1)+substr("中",1,1))`
+  解释器 9 / 原生 3。现全部改为字节级。
+- **用户函数与内建同名时永远不会被调用**：`--no-native` 报宿主能力错误、原生路径
+  静默走宿主实现（两条路径结论不同）。现用户函数优先于同名内建。
+- **局部 struct 字段默认值**：`MALLOC` 并不清零，此前「全零」只是堆恰好干净；
+  现于函数序言显式清零。
+- **AOT 临时目录**：清理失败不再静默（记 warning 并给出残留绝对路径与手动删除命令）；
+  每次构建前清扫超过 6 小时的 `.aotbuild-*` / `.aotprobe-*`；
+  新增 `[tool.setuptools.exclude-package-data]` 使残留不再进 wheel。
+
+### 变更 (Changed)
+
+- **无法自洽的 struct 写法改为编译期报错**（原先静默算错）：多维 struct 数组
+  `P ps[2][3]`、struct 数组字段 `struct Bag { P items[3] }`、跨 struct 类型赋值
+  `P p; Q q; p = q;`、把 struct 写进标量槽 `int a[2]; a[0] = p;`。
+- `tests/test_keyboard.py`、`tests/test_p0_fixes.py` 由 `tmp_path` 改用 `workdir` 夹具，
+  受限沙箱下不再出现 5 个 setup 阶段 `ERROR`。
+- 新增跨库集成护栏 `tests/test_all_libs_together.py`：31 个纯 CIN 库同时 import 并各调用一个接口。
+
+---
+
 ## [5.6.0] - 2026-09-27
 
 一次以「静默错误清零 + 安全加固」为主的修复发布，落地 `docs/SUGGESTIONS_NEXT.md`
@@ -254,7 +507,7 @@
 
 ### 修复 (Fixed)
 
-- `python cpu.py --help` 的首行版本号长期停留在 `Code CIN v5.3`，现直接取
+- `codecin --help` 的首行版本号长期停留在 `Code CIN v5.3`，现直接取
   `codecin.__version__`（此前是全仓唯一残留的版本串）。
 - `--build-exe` 在程序文件不存在时抛裸 `FileNotFoundError` traceback，现在与普通路径
   一样给出 `Build Error` 面板。
@@ -305,7 +558,7 @@
 ### 新增 (Added)
 
 - **AOT 静态编译: 编译成独立可执行文件 (Windows / Linux / macOS)**：
-  `python cpu.py program.cin --build-exe app` 或 `codecin build program.cin -o app`，
+  `codecin program.cin --build-exe app` 或 `codecin build program.cin -o app`，
   支持 `--target OS/ARCH` 交叉编译（windows/amd64|arm64、linux/amd64|arm64、darwin/amd64|arm64）。
   产物内嵌 UCBC 字节码与初始内存镜像，由内置 Go VM 执行，**不依赖 Python、Go 工具链、
   libc 或任何动态库**（`CGO_ENABLED=0`，Linux 产物无 `PT_INTERP`）；入口 shell 模板由

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecin
-Version: 5.6.0
+Version: 5.8.0
 Summary: Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + Go 原生 VM + ARM64/RISC-V/FP/Vector 指令集)
 Author: ByUsi Studio, 北啊呢
 License-Expression: MIT
@@ -443,9 +443,9 @@ codecin --version
 
 3. 运行:
    ```
-   python cpu.py basic.cin                          # 唯一 CLI 入口 (自动用 Go 原生库)
+   codecin basic.cin                          # 唯一 CLI 入口 (自动用 Go 原生库)
    codecin basic.cin                                # 安装后等价的 console script
-   python cpu.py --help
+   codecin --help
    ```
 
 > **Python 只是 CLI 外壳**: 语言实现 (`codecin/native/` 下的 Go 编译器与字节码 VM) 全部在 Go 侧,
@@ -485,11 +485,11 @@ ruff check codecin cpu.py script tests
 
 ```bash
 # 本机平台
-python cpu.py program.cin --build-exe program          # Windows 自动补 .exe
+codecin program.cin --build-exe program          # Windows 自动补 .exe
 
 # 交叉编译 (只需要安装 Go 工具链)
-python cpu.py program.cin --build-exe app-linux --build-target linux/amd64
-python cpu.py program.cin --build-exe app-mac   --build-target darwin/arm64
+codecin program.cin --build-exe app-linux --build-target linux/amd64
+codecin program.cin --build-exe app-mac   --build-target darwin/arm64
 ```
 
 | 目标 | 说明 |
@@ -506,10 +506,10 @@ python cpu.py program.cin --build-exe app-mac   --build-target darwin/arm64
 ### 命令行选项
 
 **基础执行**
-- `python cpu.py program.cin` - 运行CIN程序
-- `python cpu.py program.pl` - 运行PL程序
-- `python cpu.py program.asm` - 运行ASM程序
-- `python cpu.py program.bin` - 运行字节码
+- `codecin program.cin` - 运行CIN程序
+- `codecin program.pl` - 运行PL程序
+- `codecin program.asm` - 运行ASM程序
+- `codecin program.bin` - 运行字节码
 
 **执行路径**
 - `--no-native` - 禁用 Go 原生库, 强制纯 Python

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

@@ -425,9 +425,9 @@ codecin --version
 
 3. 运行:
    ```
-   python cpu.py basic.cin                          # 唯一 CLI 入口 (自动用 Go 原生库)
+   codecin basic.cin                          # 唯一 CLI 入口 (自动用 Go 原生库)
    codecin basic.cin                                # 安装后等价的 console script
-   python cpu.py --help
+   codecin --help
    ```
 
 > **Python 只是 CLI 外壳**: 语言实现 (`codecin/native/` 下的 Go 编译器与字节码 VM) 全部在 Go 侧,
@@ -467,11 +467,11 @@ ruff check codecin cpu.py script tests
 
 ```bash
 # 本机平台
-python cpu.py program.cin --build-exe program          # Windows 自动补 .exe
+codecin program.cin --build-exe program          # Windows 自动补 .exe
 
 # 交叉编译 (只需要安装 Go 工具链)
-python cpu.py program.cin --build-exe app-linux --build-target linux/amd64
-python cpu.py program.cin --build-exe app-mac   --build-target darwin/arm64
+codecin program.cin --build-exe app-linux --build-target linux/amd64
+codecin program.cin --build-exe app-mac   --build-target darwin/arm64
 ```
 
 | 目标 | 说明 |
@@ -488,10 +488,10 @@ python cpu.py program.cin --build-exe app-mac   --build-target darwin/arm64
 ### 命令行选项
 
 **基础执行**
-- `python cpu.py program.cin` - 运行CIN程序
-- `python cpu.py program.pl` - 运行PL程序
-- `python cpu.py program.asm` - 运行ASM程序
-- `python cpu.py program.bin` - 运行字节码
+- `codecin program.cin` - 运行CIN程序
+- `codecin program.pl` - 运行PL程序
+- `codecin program.asm` - 运行ASM程序
+- `codecin program.bin` - 运行字节码
 
 **执行路径**
 - `--no-native` - 禁用 Go 原生库, 强制纯 Python

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

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

{codecin-5.6.0 → codecin-5.8.0}/codecin/aot.py

@@ -9,18 +9,40 @@
 `codecin/native/aot` 共用同一份文件 (``stub_main.go.txt``), 避免两处漂移。
 临时包建在 `codecin-native` 模块内的 ``.aotbuild-*`` 目录: Go 工具链会忽略
 以 '.' 开头的目录, 因此既不影响 `go build ./...`, 也不需要 replace 指令。
+
+临时目录的生命周期 (加固, 见 docs/SUGGESTIONS_NEXT.md §3.3):
+  * 每次 :func:`build` 之前先调用 :func:`sweep_stale_build_dirs` 清理**陈旧**残留,
+    避免受限环境 (沙箱 / 只读 ACL) 下删不掉的目录无限累积;
+  * ``finally`` 里的 ``rmtree`` 失败**不再静默**: 有 logger 就 ``warning``,
+    没有 logger 时退回模块级 stdlib logger (``codecin.aot``), 绝不吞掉;
+  * 只清理 ``codecin/native/`` **本目录下**、名字带 ``.aotbuild-`` /
+    ``.aotprobe-`` 前缀、且**不是符号链接**的目录, 绝不递归删除别处。
 """
 
+import logging
 import os
 import platform
 import secrets
 import shutil
 import subprocess
-from typing import List, Optional
+import time
+from typing import List, NamedTuple, Optional
 
 #: 仓库内 codecin-native 模块目录 (含 go.mod)。
 _NATIVE_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'native')
 
+#: 模块级 logger: 调用方没有传 logger 时的兜底 (绝不能因为"没人接"就静默)。
+#: 它是 ``codecin`` logger 的子 logger, 因此 CLI 构造的 Logger (RichHandler) 会
+#: 照常渲染它; 完全没配置 logging 时 stdlib 的 lastResort 也会打到 stderr。
+_LOGGER = logging.getLogger(__name__)
+
+#: AOT 临时目录名前缀 (``.aotprobe-`` 是历史遗留, 一并纳入守卫)。
+TEMP_DIR_PREFIXES = ('.aotbuild-', '.aotprobe-')
+
+#: 陈旧残留的默认容忍时长 (6 小时): 远大于任何一次 go build, 因此不会误删
+#: 并发构建中的临时目录。
+DEFAULT_STALE_AGE_SECONDS = 6 * 3600
+
 #: 生成的 main.go 模板 (与 Go 侧共用)。
 STUB_PATH = os.path.join(_NATIVE_DIR, 'aot', 'stub_main.go.txt')
 
@@ -130,6 +152,156 @@ def _run_go_build(cmd, mod, env, logger):
     return proc, detail
 
 
+class SweepResult(NamedTuple):
+    """:func:`sweep_stale_build_dirs` 的结果 (两个绝对路径列表)。"""
+
+    #: 成功删除的目录
+    removed: List[str]
+    #: 判定为残留但删除/读取失败的目录 (调用方应提示用户手动处理)
+    failed: List[str]
+
+
+def _warn(logger, message: str) -> None:
+    """记一条 warning; 没有 logger 时退回模块级 stdlib logger (绝不静默)。
+
+    日志本身出问题不能掩盖构建结果 (本函数常在 ``finally`` 里被调用),
+    因此这里再包一层兜底。
+    """
+    try:
+        if logger is not None:
+            logger.warning(message)
+        else:
+            _LOGGER.warning(message)
+    except Exception:                     # noqa: BLE001 - 日志失败不得影响构建
+        pass
+
+
+def _debug(logger, message: str) -> None:
+    """记一条 debug (同样带兜底)。"""
+    try:
+        if logger is not None:
+            logger.debug(message)
+        else:
+            _LOGGER.debug(message)
+    except Exception:                     # noqa: BLE001
+        pass
+
+
+def _manual_removal_hint(path: str) -> str:
+    """给用户的「怎么手动删掉它」提示 (Windows + POSIX 各一条)。"""
+    return (f'请手动删除该目录 —— Windows PowerShell: '
+            f'Remove-Item -LiteralPath "{path}" -Recurse -Force ; '
+            f'Linux/macOS: rm -rf "{path}"')
+
+
+def _is_temp_dir_name(name: str) -> bool:
+    """名字是否是本模块自己产生的临时目录名 (只认前缀, 不做任何路径解析)。
+
+    显式拒绝 ``.``/``..``、含路径分隔符的名字以及绝对路径 —— 这些都不可能是
+    ``secrets.token_hex`` 的产物, 一旦出现就说明有人往我们手里塞了别的东西。
+    """
+    if not name or name in ('.', '..'):
+        return False
+    if name != os.path.basename(name):          # 含 / 或 \ -> 不是直接子项
+        return False
+    if os.sep in name or (os.altsep and os.altsep in name):
+        return False
+    if os.path.isabs(name):
+        return False
+    return name.startswith(TEMP_DIR_PREFIXES)
+
+
+def sweep_stale_build_dirs(max_age_seconds: float = DEFAULT_STALE_AGE_SECONDS,
+                           logger=None) -> SweepResult:
+    """删除 ``codecin/native/`` 下**陈旧**的 AOT 临时构建目录。
+
+    只处理 ``codecin/native/`` 的**直接子目录** (不递归), 名字必须带
+    ``.aotbuild-`` / ``.aotprobe-`` 前缀, 且 mtime 早于 ``max_age_seconds``;
+    符号链接与普通文件一律跳过。任何失败都不会抛异常, 只记录日志并把路径
+    放进 :attr:`SweepResult.failed`。
+
+    :param max_age_seconds: 容忍时长 (默认 6 小时)。``0`` 表示删除所有匹配目录
+        —— 并发构建时不要这么做。
+    :param logger: 可选 logger; 缺省时用模块级 stdlib logger。
+    :return: 被删除的路径与清理失败的路径
+    """
+    removed: List[str] = []
+    failed: List[str] = []
+
+    root = os.path.abspath(_NATIVE_DIR)
+    try:
+        names = os.listdir(root)
+    except OSError as e:                  # 目录不存在 / 不可读: 尽力而为
+        _warn(logger, f'AOT: 无法扫描临时目录所在位置 {root} ({e}); 跳过清理')
+        return SweepResult(removed, failed)
+
+    try:
+        max_age = max(0.0, float(max_age_seconds))
+    except (TypeError, ValueError):
+        max_age = float(DEFAULT_STALE_AGE_SECONDS)
+
+    now = time.time()
+    for name in names:
+        if not _is_temp_dir_name(name):
+            continue
+        path = os.path.join(root, name)
+        # 双保险: 解析后必须仍然是 root 的直接子项 (防 '..' / 绝对路径混入)
+        if os.path.dirname(os.path.abspath(path)) != root:
+            _warn(logger, f'AOT: 跳过可疑的临时目录路径: {path}')
+            continue
+        if os.path.islink(path) or not os.path.isdir(path):
+            _debug(logger, f'AOT: 跳过非普通目录的临时项: {path}')
+            continue
+
+        try:
+            age = now - os.path.getmtime(path)
+        except OSError as e:
+            failed.append(path)
+            _warn(logger, f'AOT: 无法读取残留临时目录的时间戳: {path} ({e}); '
+                          f'{_manual_removal_hint(path)}')
+            continue
+
+        if age < max_age:
+            _debug(logger, f'AOT: 临时目录仍然新鲜, 保留: {path} '
+                           f'({age / 3600:.1f} 小时前)')
+            continue
+
+        try:
+            shutil.rmtree(path)
+        except OSError as e:
+            failed.append(path)
+            _warn(logger, f'AOT: 残留临时目录清理失败: {path} '
+                          f'({age / 3600:.1f} 小时前, {e}); '
+                          f'{_manual_removal_hint(path)}')
+            continue
+
+        removed.append(path)
+        _debug(logger, f'AOT: 已清理陈旧临时目录: {path} '
+                       f'({age / 3600:.1f} 小时前)')
+
+    if removed:
+        _debug(logger, f'AOT: 陈旧临时目录清理完成, 共 {len(removed)} 个')
+    return SweepResult(removed, failed)
+
+
+def _remove_temp_dir(tmp: str, logger) -> None:
+    """删除本次构建的临时目录; 失败时告警而不是静默吞掉 (§3.3)。
+
+    ``shutil.rmtree(ignore_errors=True)`` 会让「删不掉」完全静默, 于是残留
+    在受限环境 (沙箱 / 异常 ACL) 里不断累积, 最终让任何遍历仓库的工具报
+    Access is denied。这里改为: 失败 -> warning (含绝对路径与手动删除提示)。
+    """
+    try:
+        shutil.rmtree(tmp)
+    except FileNotFoundError:
+        pass                              # 目录已不存在: 目的已达成
+    except Exception as e:                # noqa: BLE001 - rmtree 正常只抛 OSError,
+        # 但这里处于 finally, 任何异常都不能掩盖构建结果, 一律降级为 warning。
+        _warn(logger, f'AOT: 临时构建目录清理失败, 残留目录: '
+                      f'{os.path.abspath(tmp)} (原因: {e}); '
+                      f'{_manual_removal_hint(tmp)}')
+
+
 def build(bytecode: bytes,
           mem_image: bytes,
           out: str,
@@ -150,6 +322,14 @@ def build(bytecode: bytes,
     goos, goarch = parse_target(target) if target else parse_target(host_target())
     mod = module_dir()
 
+    # 先清掉上一次留下的陈旧残留 (默认 > 6 小时), 再建新目录: 受限环境下
+    # rmtree 可能失败, 没有这一步残留就会无限累积。
+    # 清理是尽力而为 —— 任何异常都必须吞掉, 绝不能因此让构建失败。
+    try:
+        sweep_stale_build_dirs(logger=logger)
+    except Exception as e:                # noqa: BLE001
+        _debug(logger, f'AOT: 陈旧临时目录清理跳过 ({e})')
+
     # 注意: 这里用 os.makedirs 而不是 tempfile.mkdtemp —— mkdtemp 会创建 0700
     # 目录, 在受限环境 (沙箱 / 部分 CI 安全策略) 下随后向其中写文件会被拒绝。
     tmp = os.path.join(mod, '.aotbuild-' + secrets.token_hex(6))
@@ -182,8 +362,9 @@ def build(bytecode: bytes,
         try:
             proc, detail = _run_go_build(cmd, mod, env, logger)
         except FileNotFoundError as e:
-            raise AotError('未找到 go 命令; AOT 构建需要 Go 工具链 '
-                           '(https://go.dev/dl/)') from e
+            from .environment import missing_tool_message
+            raise AotError(missing_tool_message(
+                'go', 'AOT 构建独立可执行文件')) from e
         except subprocess.TimeoutExpired as e:
             raise AotError('go build 超时') from e
         if proc.returncode != 0:
@@ -199,7 +380,7 @@ def build(bytecode: bytes,
             if logger:
                 logger.info(f'AOT 临时目录保留: {tmp}')
         else:
-            shutil.rmtree(tmp, ignore_errors=True)
+            _remove_temp_dir(tmp, logger)
 
 
 def program_dependencies(program_file: str) -> List[str]: