codecin 5.4.2__py3-none-any.whl

codecin/memory.py

@@ -0,0 +1,348 @@
+import struct
+from typing import Dict, Iterator, Optional, Tuple
+
+from .console import Console, Table
+from .errors import MemoryAccessError, PageFaultError
+
+# ==================== MMU / 分页 (B1) ====================
+
+
+class Mmu:
+    """扁平 4K 页表: vpn -> (ppn, perms)。
+
+    - 默认按需 identity 映射 (vpn == ppn, perms='rwx');
+    - unmap 后访问触发 PageFaultError; 权限位按 'r'/'w'/'x' 检查。
+    """
+
+    PAGE_BITS = 12
+    PAGE_SIZE = 1 << PAGE_BITS
+    PAGE_MASK = PAGE_SIZE - 1
+
+    def __init__(self, mem_size: int):
+        self.mem_size = mem_size
+        self.pages: Dict[int, Tuple[int, str]] = {}
+        self._blacklist = set()   # 显式 unmap 的 vpn (禁止 identity 回填)
+        self._identity = True     # 未显式配置/未 unmap 的页按 identity 映射
+
+    def _page_count(self) -> int:
+        return (self.mem_size + self.PAGE_SIZE - 1) // self.PAGE_SIZE
+
+    def reset(self, mem_size: Optional[int] = None) -> None:
+        if mem_size is not None:
+            self.mem_size = mem_size
+        self.pages = {}
+        self._blacklist = set()
+
+    def map(self, vpn: int, ppn: Optional[int] = None,
+            perms: str = 'rwx') -> None:
+        """映射 vpn; 缺省 ppn 采用 identity (ppn = vpn)。"""
+        if ppn is None:
+            ppn = vpn
+        self.pages[vpn] = (ppn, perms)
+        self._blacklist.discard(vpn)
+
+    def map_page(self, vaddr: int, paddr: int, perms: str = 'rwx') -> None:
+        self.map(vaddr >> self.PAGE_BITS, paddr >> self.PAGE_BITS, perms)
+
+    def unmap(self, vaddr: int) -> bool:
+        vpn = vaddr >> self.PAGE_BITS
+        self._blacklist.add(vpn)
+        return self.pages.pop(vpn, None) is not None
+
+    def protect(self, vaddr: int, perms: str) -> None:
+        vpn = vaddr >> self.PAGE_BITS
+        if vpn in self.pages:
+            ppn, _ = self.pages[vpn]
+        elif vpn in self._blacklist:
+            raise MemoryAccessError(
+                f"Cannot protect unmapped page {vpn} (0x{vaddr:x})")
+        else:
+            ppn = vpn
+        self.pages[vpn] = (ppn, perms)
+        self._blacklist.discard(vpn)
+
+    def is_mapped(self, vaddr: int) -> bool:
+        vpn = vaddr >> self.PAGE_BITS
+        return vpn in self.pages or (self._identity and vpn not in self._blacklist)
+
+    def translate(self, vaddr: int, access: str) -> int:
+        vpn = vaddr >> self.PAGE_BITS
+        off = vaddr & self.PAGE_MASK
+        ent = self.pages.get(vpn)
+        if ent is None:
+            if self._identity and vpn not in self._blacklist:
+                ent = (vpn, 'rwx')     # 懒 identity
+                self.pages[vpn] = ent
+            else:
+                raise PageFaultError(
+                    f"Page fault at virtual 0x{vaddr:x} (page {vpn} unmapped)")
+        ppn, perms = ent
+        if access not in perms:
+            raise MemoryAccessError(
+                f"Page protection violation at 0x{vaddr:x} for '{access}'")
+        paddr = (ppn << self.PAGE_BITS) | off
+        if not 0 <= paddr < self.mem_size:
+            raise PageFaultError(
+                f"Physical address 0x{paddr:x} out of memory (size "
+                f"0x{self.mem_size:x})")
+        return paddr
+
+
+# ==================== 内存 ====================
+
+
+class FastMemory:
+    def __init__(self, size: int = 64 * 1024):
+        self._size = size
+        self._memory = bytearray(size)
+        self._view = memoryview(self._memory)
+        self._protection: Dict[int, str] = {}
+        # B1: 可选 MMU (None = 关)
+        self._mmu: Optional[Mmu] = None
+        # 调试日志钩子 (DEBUG 级别记录每次读写)
+        self._log = None
+
+    # ---------------- MMU ----------------
+
+    def attach_mmu(self, mmu: Optional[Mmu]) -> None:
+        self._mmu = mmu
+
+    @property
+    def mmu(self) -> Optional[Mmu]:
+        return self._mmu
+
+    def _phys(self, addr: int, access: str) -> int:
+        if self._mmu is None:
+            return addr
+        return self._mmu.translate(addr, access)
+
+    def _chunks(self, addr: int, size: int, access: str
+                ) -> Iterator[Tuple[int, int]]:
+        """把 [addr, addr+size) 翻译为物理分块 (含 MMU 分页)。"""
+        if self._mmu is None:
+            yield addr, size
+            return
+        end = addr + size
+        while addr < end:
+            paddr = self._mmu.translate(addr, access)
+            step = min(self._mmu.PAGE_SIZE - (addr & self._mmu.PAGE_MASK),
+                       end - addr)
+            yield paddr, step
+            addr += step
+
+    def attach_logger(self, logger) -> None:
+        """挂接日志器, DEBUG 级别下记录所有内存读写。"""
+        self._log = logger
+
+    @property
+    def _mem_trace(self) -> bool:
+        return self._log is not None and self._log.is_debug
+
+    def _trace_mem(self, op: str, addr: int, value, width: int) -> None:
+        vs = f"0x{value:x}" if isinstance(value, int) else repr(value)
+        self._log.trace(f"  MEM {op:<5} @0x{addr:04x} w={width} value={vs}")
+
+    def __len__(self) -> int:
+        return self._size
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def reset(self, size: Optional[int] = None) -> None:
+        if size is not None:
+            self._size = size
+        self._memory = bytearray(self._size)
+        self._view = memoryview(self._memory)
+        self._protection.clear()
+        if self._mmu is not None:
+            self._mmu.reset(self._size)
+
+    def resize(self, new_size: int) -> None:
+        if new_size <= self._size:
+            return
+        new_mem = bytearray(new_size)
+        new_mem[:self._size] = self._memory
+        self._memory = new_mem
+        self._view = memoryview(self._memory)
+        self._size = new_size
+        if self._mmu is not None:
+            self._mmu.reset(self._size)
+
+    def set_protection(self, addr: int, perms: str, size: int = 1) -> None:
+        for i in range(size):
+            self._protection[addr + i] = perms
+
+    def check_access(self, addr: int, access: str) -> bool:
+        perm = self._protection.get(addr, 'rwx')
+        return access in perm
+
+    def _check_bounds(self, addr: int, size: int = 1) -> None:
+        if not 0 <= addr <= self._size - size:
+            raise MemoryAccessError(
+                f"Address 0x{addr:x} out of bounds (memory size 0x{self._size:x}, "
+                f"access width {size})")
+
+    def _check_protection(self, addr: int, access: str) -> None:
+        if not self.check_access(addr, access):
+            raise MemoryAccessError(
+                f"Memory protection violation at 0x{addr:x} for '{access}'")
+
+    def _check_protection_range(self, addr: int, size: int, access: str) -> None:
+        """对 [addr, addr+size) 内每个被保护字节做访问检查 (块读写统一入口)。"""
+        if not self._protection:
+            return
+        end = addr + size
+        for paddr, perms in self._protection.items():
+            if addr <= paddr < end and access not in perms:
+                raise MemoryAccessError(
+                    f"Memory protection violation at 0x{paddr:x} "
+                    f"for '{access}' (range 0x{addr:x}+{size})")
+
+    # ---------------- 单字节 ----------------
+
+    def read_byte(self, addr: int) -> int:
+        p = self._phys(addr, 'r')
+        self._check_bounds(p)
+        self._check_protection(p, 'r')
+        v = self._view[p]
+        if self._mem_trace:
+            self._trace_mem('RD', addr, v, 1)
+        return v
+
+    def write_byte(self, addr: int, value: int) -> None:
+        p = self._phys(addr, 'w')
+        self._check_bounds(p)
+        self._check_protection(p, 'w')
+        self._view[p] = value & 0xFF
+        if self._mem_trace:
+            self._trace_mem('WR', addr, value & 0xFF, 1)
+
+    # ---------------- 定宽多字节 (要求不跨页) ----------------
+
+    def _rw_phys(self, addr: int, width: int, access: str) -> int:
+        p = self._phys(addr, access)
+        self._check_bounds(p, width)
+        self._check_protection(p, access)
+        return p
+
+    def read_word(self, addr: int) -> int:
+        p = self._rw_phys(addr, 2, 'r')
+        v = struct.unpack_from('<H', self._view, p)[0]
+        if self._mem_trace:
+            self._trace_mem('RD', addr, v, 2)
+        return v
+
+    def write_word(self, addr: int, value: int) -> None:
+        p = self._rw_phys(addr, 2, 'w')
+        struct.pack_into('<H', self._view, p, value & 0xFFFF)
+        if self._mem_trace:
+            self._trace_mem('WR', addr, value & 0xFFFF, 2)
+
+    def read_dword(self, addr: int) -> int:
+        p = self._rw_phys(addr, 4, 'r')
+        v = struct.unpack_from('<I', self._view, p)[0]
+        if self._mem_trace:
+            self._trace_mem('RD', addr, v, 4)
+        return v
+
+    def write_dword(self, addr: int, value: int) -> None:
+        p = self._rw_phys(addr, 4, 'w')
+        struct.pack_into('<I', self._view, p, value & 0xFFFFFFFF)
+        if self._mem_trace:
+            self._trace_mem('WR', addr, value & 0xFFFFFFFF, 4)
+
+    def read_qword(self, addr: int) -> int:
+        p = self._rw_phys(addr, 8, 'r')
+        v = struct.unpack_from('<Q', self._view, p)[0]
+        if self._mem_trace:
+            self._trace_mem('RD', addr, v, 8)
+        return v
+
+    def write_qword(self, addr: int, value: int) -> None:
+        p = self._rw_phys(addr, 8, 'w')
+        struct.pack_into('<Q', self._view, p, value & 0xFFFFFFFFFFFFFFFF)
+        if self._mem_trace:
+            self._trace_mem('WR', addr, value & 0xFFFFFFFFFFFFFFFF, 8)
+
+    def read_float(self, addr: int) -> float:
+        p = self._rw_phys(addr, 4, 'r')
+        return struct.unpack_from('<f', self._view, p)[0]
+
+    def write_float(self, addr: int, value: float) -> None:
+        p = self._rw_phys(addr, 4, 'w')
+        struct.pack_into('<f', self._view, p, value)
+
+    def read_double(self, addr: int) -> float:
+        p = self._rw_phys(addr, 8, 'r')
+        return struct.unpack_from('<d', self._view, p)[0]
+
+    def write_double(self, addr: int, value: float) -> None:
+        p = self._rw_phys(addr, 8, 'w')
+        struct.pack_into('<d', self._view, p, value)
+
+    # ---------------- 块 / 字符串 ----------------
+
+    def read_block(self, addr: int, size: int) -> bytes:
+        self._check_bounds(addr, size)
+        self._check_protection_range(addr, size, 'r')
+        if self._mmu is None:
+            return bytes(self._view[addr:addr + size])
+        parts = []
+        for p, step in self._chunks(addr, size, 'r'):
+            parts.append(bytes(self._view[p:p + step]))
+        return b''.join(parts)
+
+    def write_block(self, addr: int, data) -> None:
+        size = len(data)
+        self._check_bounds(addr, size)
+        self._check_protection_range(addr, size, 'w')
+        if self._mmu is None:
+            self._view[addr:addr + size] = data
+            return
+        src = bytes(data)
+        off = 0
+        for p, step in self._chunks(addr, size, 'w'):
+            self._view[p:p + step] = src[off:off + step]
+            off += step
+
+    def read_string(self, addr: int, max_len: int = 4096) -> str:
+        chars = []
+        for _ in range(max_len):
+            b = self.read_byte(addr)
+            if b == 0:
+                break
+            chars.append(b)
+            addr += 1
+        return bytes(chars).decode('utf-8', errors='replace')
+
+    def write_string(self, addr: int, text: str) -> int:
+        data = text.encode('utf-8') + b'\x00'
+        self.write_block(addr, data)
+        return len(data)
+
+    def load_bytes(self, addr: int, data) -> None:
+        self.write_block(addr, bytes(data))
+
+    def get_snapshot(self, start: int = 0, count: int = -1) -> bytes:
+        if count < 0:
+            count = self._size - start
+        return bytes(self._view[start:start + count])
+
+    def display_memory(self, title: str = "Memory Dump", start: int = 0,
+                       count: int = 32, console: Optional[Console] = None) -> None:
+        if console is None:
+            return
+        table = Table(title=title)
+        table.add_column("Address")
+        table.add_column("Hex")
+        table.add_column("ASCII")
+        table.add_column("Prot")
+        end = min(start + count, self._size)
+        for i in range(start, end, 16):
+            chunk = self._view[i:min(i + 16, end)]
+            hex_str = ' '.join(f'{b:02X}' for b in chunk)
+            ascii_str = ''.join(chr(b) if 32 <= b <= 126 else '.' for b in chunk)
+            perm = self._protection.get(i, 'rwx')
+            table.add_row(f"{i:04X}", hex_str, ascii_str, perm)
+        console.print(str(table))

codecin/native/aot/aot.go

@@ -0,0 +1,70 @@
+// Package aot 提供 AOT 构建: 把 CIN 程序编译成**独立静态可执行文件**。
+//
+// 产物不依赖 Python、不依赖 Go 工具链、不依赖任何动态库:
+// 字节码与初始内存镜像被嵌入二进制, 由内置的 Go VM 执行
+// (构建时 CGO_ENABLED=0, 因此 Windows / Linux / macOS 均为静态链接)。
+//
+// 构建流程 (Build):
+//  1. 在 codecin-native 模块内创建临时包目录 .aotbuild-<rand>/
+//     (Go 工具链会忽略以 '.' 开头的目录, 因此不影响 go build ./...);
+//  2. 写入 main.go (由共享模板 stub_main.go.txt 提供) 与两个资源文件;
+//  3. CGO_ENABLED=0 + GOOS/GOARCH 交叉编译出目标平台可执行文件;
+//  4. 删除临时目录。
+package aot
+
+import (
+	_ "embed"
+	"fmt"
+	"io"
+	"os"
+
+	"codecin-native/engine"
+)
+
+// StubSource 是生成的 main.go 模板, 与 Python 侧 codecin/aot.py 共用同一份
+// 文件 (codecin/native/aot/stub_main.go.txt), 避免两处模板漂移。
+//
+//go:embed stub_main.go.txt
+var stubSource string
+
+// StubSource 返回生成的 main.go 源码。
+func StubSource() string { return stubSource }
+
+const maxSteps = 100000000
+
+// stackSlot 与解释器/CLI 一致: 栈从内存末尾向下增长。
+const stackSlot = 8
+
+// Main 运行内嵌的字节码并返回进程退出码 (0 = 正常结束, 1 = 运行期错误)。
+//
+// 标准输入只在被重定向 (管道/文件) 时读取, 交互式终端下不会挂起等待 EOF。
+func Main(bytecode, memImage []byte) int {
+	mem := make([]byte, len(memImage))
+	copy(mem, memImage)
+
+	var in []byte
+	if fi, err := os.Stdin.Stat(); err == nil &&
+		fi.Mode()&os.ModeCharDevice == 0 {
+		if data, err := io.ReadAll(os.Stdin); err == nil {
+			in = data
+		}
+	}
+
+	sp := int64(len(mem) - stackSlot)
+	res := engine.Run(bytecode, mem, 0, sp, int64(len(mem)/2), in, maxSteps)
+	if res == nil {
+		fmt.Fprintln(os.Stderr, "runtime error: no result")
+		return 1
+	}
+	fmt.Print(res.Output)
+	if res.Status == engine.StatusError ||
+		res.Status == engine.StatusUnsupported {
+		msg := res.ErrMsg
+		if msg == "" {
+			msg = "unsupported instruction (原生 VM 未实现该指令)"
+		}
+		fmt.Fprintf(os.Stderr, "runtime error: %s\n", msg)
+		return 1
+	}
+	return 0
+}

codecin/native/aot/build.go

@@ -0,0 +1,219 @@
+package aot
+
+import (
+	"bytes"
+	"crypto/rand"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+// DefaultMemSize 与解释器 / Go CLI 保持一致 (64 KiB)。
+const DefaultMemSize = 65536
+
+// Target 是构建目标平台。
+type Target struct {
+	GOOS   string
+	GOARCH string
+}
+
+func (t Target) String() string { return t.GOOS + "/" + t.GOARCH }
+
+// ExeSuffix 返回该平台可执行文件的后缀。
+func (t Target) ExeSuffix() string {
+	if t.GOOS == "windows" {
+		return ".exe"
+	}
+	return ""
+}
+
+// SupportedTargets 是文档/CLI 帮助里列出的常用目标。
+var SupportedTargets = []string{
+	"windows/amd64", "windows/arm64",
+	"linux/amd64", "linux/arm64",
+	"darwin/amd64", "darwin/arm64",
+}
+
+// BuildOptions 描述一次 AOT 构建。
+type BuildOptions struct {
+	// ModuleDir 是含 `module codecin-native` 的 go.mod 的目录。
+	ModuleDir string
+	Bytecode  []byte
+	MemImage  []byte
+	// Out 是输出可执行文件路径 (相对当前工作目录)。
+	Out    string
+	Target Target
+	// KeepTemp 为真时保留临时构建目录 (排查构建失败用)。
+	KeepTemp bool
+	Stdout   io.Writer
+	Stderr   io.Writer
+}
+
+// Build 生成独立静态可执行文件, 返回产物的绝对路径。
+//
+// 静态性来自 CGO_ENABLED=0: Windows / Linux / macOS 三个平台都不再依赖
+// libc 或任何动态库, 也不需要 Python 与 Go 运行时。
+func Build(opts BuildOptions) (string, error) {
+	if opts.ModuleDir == "" {
+		return "", fmt.Errorf("未指定 Go 模块目录 (含 codecin-native/go.mod 的目录)")
+	}
+	if opts.Out == "" {
+		return "", fmt.Errorf("未指定输出路径")
+	}
+	if opts.Target.GOOS == "" {
+		opts.Target.GOOS = runtime.GOOS
+	}
+	if opts.Target.GOARCH == "" {
+		opts.Target.GOARCH = runtime.GOARCH
+	}
+	if len(opts.Bytecode) == 0 {
+		return "", fmt.Errorf("字节码为空")
+	}
+
+	// 临时包放在模块内并以 '.' 开头: Go 工具链会忽略这类目录,
+	// 因此既不影响 `go build ./...`, 也无需 replace/绝对路径。
+	//
+	// 注意: 这里用 os.Mkdir(0755) 而不是 os.MkdirTemp —— MkdirTemp 会建 0700
+	// 目录, 在受限环境 (沙箱 / 部分 CI 安全策略) 下随后向其中写文件会被拒绝。
+	tmp, err := newBuildDir(opts.ModuleDir)
+	if err != nil {
+		return "", fmt.Errorf("创建临时构建目录失败 (模块目录可写?): %w", err)
+	}
+	if !opts.KeepTemp {
+		defer func() { _ = os.RemoveAll(tmp) }()
+	}
+
+	write := func(name string, data []byte) error {
+		return os.WriteFile(filepath.Join(tmp, name), data, 0o644)
+	}
+	if err := write("main.go", []byte(stubSource)); err != nil {
+		return "", fmt.Errorf("写入 main.go 失败: %w", err)
+	}
+	if err := write("program.ucbc", opts.Bytecode); err != nil {
+		return "", fmt.Errorf("写入 program.ucbc 失败: %w", err)
+	}
+	if err := write("program.mem", opts.MemImage); err != nil {
+		return "", fmt.Errorf("写入 program.mem 失败: %w", err)
+	}
+
+	outAbs, err := filepath.Abs(opts.Out)
+	if err != nil {
+		return "", fmt.Errorf("解析输出路径失败: %w", err)
+	}
+	if dir := filepath.Dir(outAbs); dir != "" {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			return "", fmt.Errorf("创建输出目录失败: %w", err)
+		}
+	}
+
+	pkg := "." + string(filepath.Separator) + filepath.Base(tmp)
+	cmd := exec.Command("go", "build",
+		"-trimpath",
+		"-tags", "netgo,osusergo", // 纯 Go 网络/用户实现, 保证无 libc 依赖
+		"-ldflags", "-s -w", // 去掉符号表与调试信息
+		"-o", outAbs, pkg)
+	cmd.Dir = opts.ModuleDir
+	cmd.Stdout = opts.Stdout
+	stderr := &bytes.Buffer{}
+	if opts.Stderr != nil {
+		cmd.Stderr = io.MultiWriter(opts.Stderr, stderr)
+	} else {
+		cmd.Stderr = stderr
+	}
+
+	env := append(os.Environ(),
+		"CGO_ENABLED=0", // 关键: 静态链接
+		"GOOS="+opts.Target.GOOS,
+		"GOARCH="+opts.Target.GOARCH,
+	)
+	cmd.Env = env
+	err = cmd.Run()
+
+	// 受限环境 (沙箱 / 只读 HOME / 部分 CI) 下 Go 默认构建缓存可能不可写,
+	// 直接失败会给出难以理解的 "Access is denied"; 此时回退到仓库内 .gocache 重试一次。
+	if err != nil && cacheWriteDenied(stderr.String()) && os.Getenv("GOCACHE") == "" {
+		cache := fallbackCacheDir(opts.ModuleDir)
+		if mkErr := os.MkdirAll(cache, 0o755); mkErr == nil {
+			retry := exec.Command("go", cmd.Args[1:]...)
+			retry.Dir = opts.ModuleDir
+			retry.Stdout = opts.Stdout
+			retry.Stderr = cmd.Stderr
+			retry.Env = append(env, "GOCACHE="+cache)
+			if retryErr := retry.Run(); retryErr == nil {
+				return outAbs, nil
+			} else {
+				err = fmt.Errorf("%w (已回退缓存目录 %s 仍失败)", retryErr, cache)
+			}
+		}
+	} else if err != nil && cacheWriteDenied(stderr.String()) {
+		err = fmt.Errorf("%w (提示: 构建缓存不可写, 可用 GOCACHE 指向可写目录)", err)
+	}
+	if err != nil {
+		return "", fmt.Errorf("go build 失败 (目标 %s): %w", opts.Target, err)
+	}
+	return outAbs, nil
+}
+
+// fallbackCacheDir 返回仓库内的构建缓存目录 (install 脚本同款, 已被 .gitignore 忽略)。
+func fallbackCacheDir(moduleDir string) string {
+	root := filepath.Dir(filepath.Dir(filepath.Clean(moduleDir)))
+	return filepath.Join(root, ".gocache")
+}
+
+// cacheWriteDenied 判断 go build 的报错是否属于"构建缓存不可写"。
+func cacheWriteDenied(text string) bool {
+	low := strings.ToLower(text)
+	if !strings.Contains(low, "cache") && !strings.Contains(low, "go-build") {
+		return false
+	}
+	return strings.Contains(low, "access is denied") ||
+		strings.Contains(low, "permission denied") ||
+		strings.Contains(low, "operation not permitted")
+}
+
+// newBuildDir 在模块内创建一个 0755 的临时包目录。
+// 不用 os.MkdirTemp: 它建的是 0700 目录, 受限环境下随后写入会被拒绝。
+func newBuildDir(moduleDir string) (string, error) {
+	var buf [6]byte
+	if _, err := rand.Read(buf[:]); err != nil {
+		return "", err
+	}
+	path := filepath.Join(moduleDir, fmt.Sprintf(".aotbuild-%x", buf))
+	if err := os.Mkdir(path, 0o755); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+// FindModuleDir 从给定的若干起点向上查找 `module codecin-native` 所在目录。
+func FindModuleDir(starts ...string) string {
+	for _, start := range starts {
+		if start == "" {
+			continue
+		}
+		dir, err := filepath.Abs(start)
+		if err != nil {
+			continue
+		}
+		if fi, err := os.Stat(dir); err == nil && !fi.IsDir() {
+			dir = filepath.Dir(dir)
+		}
+		for {
+			gomod := filepath.Join(dir, "go.mod")
+			if data, err := os.ReadFile(gomod); err == nil &&
+				strings.Contains(string(data), "module codecin-native") {
+				return dir
+			}
+			parent := filepath.Dir(dir)
+			if parent == dir {
+				break
+			}
+			dir = parent
+		}
+	}
+	return ""
+}

codecin/native/aot/stub_main.go.txt

@@ -0,0 +1,22 @@
+// Code generated by the Code CIN AOT builder; DO NOT EDIT.
+//
+// 这是独立可执行文件的入口 shell: program.ucbc 与 program.mem 由构建器
+// 生成并嵌入, 运行时由内置 Go VM 执行 (静态链接, 无需 Python/动态库)。
+package main
+
+import (
+	_ "embed"
+	"os"
+
+	"codecin-native/aot"
+)
+
+//go:embed program.ucbc
+var bytecode []byte
+
+//go:embed program.mem
+var memImage []byte
+
+func main() {
+	os.Exit(aot.Main(bytecode, memImage))
+}

codecin/native/build.ps1

@@ -0,0 +1,33 @@
+# Code CIN 原生库构建脚本 (Windows)
+# 依赖: Go 1.26+ 且启用 cgo (需 C 编译器, 如 MinGW-w64 / TDM-GCC 的 gcc / clang)
+# 用法: 在本目录执行  .\build.ps1
+#     静态链接: $env:CODECIN_STATIC = '1'  (默认尝试静态, 失败自动回退动态)
+#     动态链接: $env:CODECIN_STATIC = '0'
+param()
+$ErrorActionPreference = 'Stop'
+$dir = Split-Path -Parent $MyInvocation.MyCommand.Path
+Set-Location $dir
+$env:CGO_ENABLED = '1'
+
+$out = Join-Path $dir '..\codecin_native.dll'
+$mode = if ($env:CODECIN_STATIC) { $env:CODECIN_STATIC } else { 'auto' }
+
+$staticLd = '-linkmode external -extldflags -static'
+$built = $false
+
+if ($mode -ne '0') {
+    Write-Host "Building (static linking)..."
+    go build -buildmode=c-shared -ldflags $staticLd -o $out .
+    if ($LASTEXITCODE -eq 0) { $built = $true }
+    elseif ($mode -eq '1') { throw "static go build failed (exit $LASTEXITCODE)" }
+    else { Write-Host "static linking unavailable, falling back to dynamic" -ForegroundColor Yellow }
+}
+if (-not $built) {
+    Write-Host "Building (dynamic linking)..."
+    go build -buildmode=c-shared -o $out .
+    if ($LASTEXITCODE -ne 0) { throw "go build failed (exit $LASTEXITCODE)" }
+}
+
+# c-shared 会附带生成头文件, Python ctypes 不需要
+Remove-Item -Force (Join-Path $dir '..\codecin_native.h') -ErrorAction SilentlyContinue
+Write-Host ("Built: " + (Resolve-Path $out).Path)