企业官网建设流程全解析

本文以 xqvm_py/README.md 为骨架，结合xqvm_py包源码、xqffi绑定、conformance测试与向量数据展开。xqvm_py是 X-Quadratic Virtual Machine（XQVM）的纯 Python 参考实现，其职责是作为 XQuad 工具链的"可执行一致性基准（conformance oracle）"：conformance/目录下每一个测试向量都必须在这一参考实现与 Rust 生产运行时xqvm上产生完全一致的可观测状态。阅读完本文，你将掌握xqvm_py的包结构与各模块职责、如何通过 CLI 与编程接口运行.xqasm/.xqb程序、其执行模型与计量/计费机制，以及它如何支撑跨实现的一致性验证。

项目定位：过渡性的参考实现，而非生产运行时

xqvm_py是一个 Python reference implementation（参考实现），对应规范见 spec/xqvm/SPEC.md（权威技术规范）。它与 Rust 生产运行时 xqvm 构成"参考 + 生产"的双实现格局。

README 开篇用一个醒目的Status -- transitional（过渡性状态）框定了它的生命周期定位：

• 每一个 conformance 目录下的向量，都必须在 Python 参考实现和 Rustxqvm生产运行时上产生完全一致的可观测状态；
• 一旦 Rust 运行时经过充分实战检验，xqvm_py可能被整体移除（届时一致性向量升级为"Rust 必须精确产出这些输出"的参考数据），或降级为原型沙盒——在 Python 中先行试验新 opcode / VM 特性，待其获得规范席位后再迁移；
• 因此，不要在基础设施上硬依赖xqvm_py的存在。从源码结构看，包内大量注释都在强调"镜像 Rust 实现"这一约束（例如 xqvm_py/metering.py 开篇即声明"常量与公式逐值镜像xqvm/src/metering.rs"）。

Scope：纯 Python 执行栈，不含汇编器

README 明确了xqvm_py的范围边界：

这意味着"文本 → 指令流"的解析路径完全委托给 Rust：xqvm_py/program.py中的program_from_xqasm调用xqffi.asm.parse_xqasm（见 xqffi/src/asm.rs），后者在 Rust 侧完成xqasm::assemble_source与codec::decode，再把(opcode_byte, operand_bytes, pc)元组列表和跳转表以 Python dict 形式回传，由 Python 侧包装成Instructiondataclass。历史上曾有xqvm.assembler树，已随 QUI-440 移除。

包布局（flat layout）

xqvm_py/目录本身就是包（扁平布局），所有核心模块直接位于包根下：

xqvm_py/ <-- 此目录即包本身（扁平布局） __init__.py re-export 公共表面（Executor、Program、……） __main__.py `python -m xqvm_py` 入口 executor.py 取指-译码-执行循环 state.py 栈、寄存器、循环控制、跳转表 opcodes.py Opcode 枚举 + 操作数元数据 program.py Program dataclass + program_from_xqasm() xqmx.py 稀疏二次矩阵（model + sample 模式） vector.py 类型化 vec<int> / vec<xqmx> errors.py 类型化运行时错误 tracer.py 逐步执行跟踪器 cli/ python -m xqvm_py run ... tests/ pytest 测试套件（构建 wheel 时排除）

• xqvm_py/init.py re-export 了Executor、Program、Opcode、MachineState、Value、Vec、XQMX及大量工具函数，兼容旧的from xqvm_py import Executor, Opcode, ...导入习惯；当前版本号为0.4.3.dev0。
• 包元数据见 xqvm_py/pyproject.toml：requires-python = ">=3.13"，唯一硬依赖为与工作区同版本的xqffi==0.4.3.dev0（精确锁定，五个发行包共享同一工作区版本号）。wheel 构建通过 hatchling 排除tests/**、README.md等。

快速开始

环境准备

在 xquad 工作区根目录执行（README 原文）：

uv sync # 安装 xqvm_py（editable）+ xqffi（经 maturin 构建） uv run pytest xqvm_py/tests # 运行完整测试套件

uv sync会同时把xqffi的 Rust cdylib 经 maturin 构建出来——这是program_from_xqasm能工作的前提。Makefile中test-python目标（Makefile）同样以uv run --no-sync pytest xqvm_py/tests ...的方式执行，并刻意使用--no-sync以避免在测试前重新同步依赖。

CLI：python -m xqvm_py run

README 给出一个最小示例：

echo "PUSH 5 PUSH 3 ADD HALT" > /tmp/prog.xqasm uv run python -m xqvm_py run /tmp/prog.xqasm # CLI shim

run子命令的完整参数（实现在 xqvm_py/cli/run.py）：

JSON 输出契约（与 Rustxquad run二进制对齐）：

• 成功：{"outputs": [...], "final_stack": [...], "steps": N}。outputs是稀疏映射语义——从未被 OUTPUT 写过的槽位输出null；final_stack是 HALT 时的残留栈（自底向上）；
• 程序故障（XQVMError子类）：不是崩溃，而是输出{"error": {"type": "<异常类名>", "message": "..."}}并以退出码2返回。这一契约是 conformance harness 能跨实现比较故障身份的关键。

.xqb字节码路径会先经xqffi.asm.disassemble反汇编回文本再解析；反汇编输出携带 pc 偏移与.N标签，目前不可完整往返为可再汇编的源码，仅供展示。

编程接口

README 的程序化示例：

from xqvm_py import Executor, program_from_xqasm prog = program_from_xqasm("PUSH 10\nPUSH 5\nADD\nSTOW r0\nHALT\n") executor = Executor() executor.execute(prog) print(executor.state.get_register(0)) # 15

Executor.execute的完整签名（xqvm_py/executor.py）：

def execute( self, program: Program, input_data: dict[int, Any] | None = None, step_limit: int | None = DEFAULT_STEP_LIMIT, # 10_000_000 memory_limit: int = DEFAULT_MEMORY_LIMIT, # 1 << 30 output_slots: int = 0, # 与 xqvm::Vm::new() 一致 ) -> dict[int, Any]

要点：

• input_data按槽号键控，list会在边界被转成Vec（对齐xqvm::Vm::set_calldata的RegVal::VecInt语义）；
• output_slots默认0是对 Rust 的镜像：程序写输出槽之前，宿主必须声明预留了多少槽；
• 返回dict(self.state.output)，即输出映射。

执行模型：Fetch-Decode-Execute 与分派表

Executor的核心是取指-译码-执行循环加一张 opcode → handler 方法的分派表（xqvm_py/executor.py）：

• 主循环（execute）：while not halted and pc < len(program)，每轮先_charge_steps(BASE_STEPS, step_limit)计步、instructions += 1，再调step()；
• step()（xqvm_py/executor.py）：从self.program[pc]取指令，若注册了tracer先触发on_step_begin；handler 执行后仅当 handler 未修改 PC（未跳转、未 halt）时advance_pc()；异常会先触发tracer.on_error再抛出；halt 时触发on_halt；
• 分派表覆盖控制流（TARGET/JUMP1/JUMPI1/JUMP2/JUMPI2/LIDX/LVAL/NEXT/RANGE/ITER/NOP/HALT）、栈与寄存器 I/O（PUSH1-8/POP/COPY/SWAP/SCLR/LOAD/STOW/DROP/INPUT/OUTPUT）、算术（ADD/SUB/MUL/DIV/MOD/SQR/ABS/NEG/MIN/MAX/INC/DEC/BITLEN）、比较（EQ/LT/GT/LTE/GTE）、布尔（NOT/AND/OR/XOR）、位运算（BAND/BOR/BXOR/BNOT/SHL/SHR）、分配器（VEC/VECI/VECX/BQMX/SQMX/XQMX/BSMX/SSMX/XSMX）、Vec 访问（VECPUSH/VECGET/VECSET/VECLEN/SLACK）、XQMX 访问（GETLINE/SETLINE/ADDLINE/GETQUAD/SETQUAD/ADDQUAD）、向量数学（IDXGRID/IDXTRIU）、XQMX 网格（RESIZE/ROWFIND/COLFIND/ROWSUM/COLSUM）以及高层约束（ONEHOTR/ONEHOTC/EXCLUDE/IMPLIES/EQUALITY/ATLEAST/ATLEASTW/REDUCE/ENERGY）。

状态模型（MachineState）

xqvm_py/state.py 的MachineState承载全部 VM 状态：

• 栈：纯整数操作数栈，上限MAX_STACK_SIZE = 8192 (2^13)，每次push都经check_i64校验（Python 整数无界，必须显式守住有符号 64 位边界）；
• 寄存器：统一寄存器堆dict[int, Value]，Value = int | Vec | XQMX；读取未设置槽抛RegisterNotFound，clear_register幂等清除；
• 跳转控制（JumpControl）：目标表targets: dict[int, int]+ 循环栈loop_stack；RANGE 帧用惰性range保存迭代空间（永不物化，防止四指令程序耗尽宿主内存），ITER 帧则真实复制切片元素；循环深度上限MAX_LOOP_DEPTH = 8192，防止"跳回循环头而不执行 NEXT"造成无界增长；
• 输入/输出：input_slots/output_slots在运行前由宿主定死，读写越界分别抛CallDataIndex/OutputIndex；槽位"留空未设"是合法状态（对应 Rust 的RegVal::Unset）；
• reset()将每个字段（含两个槽计数）恢复初始值，保证一次execute()的干净起点。

指令与程序（Instruction / Program）

xqvm_py/program.py：

• Instruction是不可变 dataclass：opcode、operands: tuple[int, ...]（立即数/寄存器索引/目标 ID）、line（调试用源行号）；
• Program在构造时经_build_jump_targets预扫描 TARGET 并建好跳转表，让执行器免去每次运行的预扫（jump_targets: dict[int, int]映射顺序目标 ID → 指令下标）；
• make_program(instructions)直接由指令列表构建；run_program(instructions, input_data, output_slots=0)提供"构建 + 执行"一站式入口；
• program_from_bytecode（xqvm_py/program.py）解析.xqb字节码：15 字节 XQBC 头（b"XQBC"魔数、version=1、input_slots/output_slots、u32 BE 的 code_len、CRC-32/ISO-HDLC 校验和）+ 指令流，无 FFI 依赖，魔数/版本/长度/CRC 任一不符均抛ValueError。

Opcode 表与操作数元数据

xqvm_py/opcodes.py 以Opcode(Enum)定义全部指令，每个成员携带一个OpcodeMeta：

• code：数值 opcode（控制流 0x00-0x09，寄存器操作 0x0A-0x0F，依此类推）；
• stack_pop/stack_push：栈净效果；
• operand_count/operand_types：操作数个数与类型（IMMEDIATE/REGISTER/TARGET）；
• description：助记说明；
• stack_reset：整栈清空类指令专用标志（目前仅SCLR），镜像conformance/opcodes.yaml中的stack_reset字段，由 scripts/check-opcode-parity.py 逐字段比对。

例如：TARGET（0x00）、JUMP1（0x01，1 个 TARGET 操作数）、JUMPI1（0x02，先弹栈再条件跳转）、RANGE（0x08，弹 2 个值count, start）、ITER（0x09，弹end_idx, start_idx，1 个 REGISTER 操作数）。

值类型：Vec 与 XQMX

Vec（xqvm_py/vector.py）

同质动态数组，支持嵌套类型描述VecElem（"int" | "xqmx" | "vec" | "unset"，vec必须带 inner，unset仅作最内层）。类型在首次 push 时推断，或由VECI/VECX显式指定；with_capacity支持预分配；length/capacity分别追踪当前元素数与已分配容量。

XQMX（xqvm_py/xqmx.py）

稀疏二次矩阵，是 QUBO/Ising 模型的核心载体：

• 模式（mode）：MODEL（构建约束/目标函数）与SAMPLE（解）；xqvm_py/executor.py 中require_model_mode/require_sample_mode在两个模式间强制切换；
• 域（domain）：BINARY {0,1}、SPIN {-1,+1}、INTEGER {0,...,k-1}；domain_contains采用逐域判定而非闭区间比较，因为 SPIN 域在0处有"空洞"，闭区间会错误放行；domain_default返回新分配样本变量的默认值（SPIN 为-1，其余为0）；
• 维度：size（变量总数）、rows/cols（网格索引用，非网格为 0）、integer_k（INTEGER 域的取值个数，< 2抛InvalidIntegerK）；
• 稀疏表示：linear: dict[int, int]（变量索引 → 线性系数）、quadratic: dict[tuple[int, int], int]（i < j的无序对 → 耦合系数）；
• 工厂方法：binary_model/spin_model/integer_model/binary_sample等；SAMPLE 模式下linear存放变量赋值（0/1 或 -1/+1），直接构造时会逐项做域校验；
• 网格操作（row_find/col_find/row_sum/col_sum/triu/compute_energy）与高层约束展开（expand_onehot/expand_exclude/expand_implies/expand_equality/expand_reduce）都在此模块。

计量与计费：steps 与内存预算

XQVM 以steps（步骤）计量执行，而不是以指令为单位。度量单位语义在 xqvm_py/metering.py 中定义（规范文本见 spec/xqvm/METERING.md，常量必须与 xqvm/src/metering.rs 逐值一致，并由 scripts/check-metering-parity.py 强制）：

辅助函数：equality_expansion_steps(n)（EQUALITY 展开的最坏情况步数，n 项产生 n 个线性项 + n(n-1)/2 个二次项，全程饱和计算防溢出）、model_eval_steps(sample_len, terms)、value_copy_steps(value)（标量免费，模型/vec 按实际内容计费——克隆模型会克隆其系数表）。

内存预算（xqvm_py/executor.py）同样镜像 Rust：VARIABLE_BYTES = 8（每个 XQMX 变量，i64）、VEC_ELEMENT_BYTES = 16（vec 每元素，按 Rust Vec 倍增容量上限计）、LINEAR_ENTRY_BYTES = 32、QUAD_ENTRY_BYTES = 48、equality_expansion_bytes(n)给出 EQUALITY 展开的最坏字节数。

关键纪律（贯穿 xqvm_py/executor.py）：

• 先计费后分配：_charge在分配前扣费，超预算抛MemoryLimitExceeded；计费累积且不退还，因此"分配-丢弃"循环不可能超支；
• 先计费后执行：_charge_steps在干活前扣步数，付不起的指令一条都不会做；
• 饱和计数器：_saturating把计费钳制在 u64 范围，模拟 Rust 计数器饱和行为——否则 Python 无界整数会让两个 VM 在超长程序上对"可负担性"产生分歧；
• 分配器三步骤顺序（_allocation_size）：拒绝负 size → 扣费 → 与MAX_ALLOCATION_SIZE = 2^32-1比较（wasm32 下usize::MAX的显式字面量，见 xqvm_py/limits.py）。扣费先于范围检查，因此超限程序在普通预算下仍以MemoryLimitExceeded故障。

check_i64是 Python 无界整数世界的守门人：栈压入、模型系数、累加结果等任何可观测值离开有符号 64 位范围即抛ArithmeticOverflow，从而与 Rust 的 checked arithmetic 保持同步。

错误层级：类型化故障

xqvm_py/errors.py 定义了以XQVMError为基类的完整异常树，包括但不限于：StackUnderflow/StackOverflow、TypeMismatch、RegisterNotFound、InvalidOpcode、DivisionByZero、ArithmeticOverflow、MemoryLimitExceeded、InvalidAllocation、StepLimitExceeded、CallDataIndex、OutputIndex、IndexOutOfBounds、NoActiveLoop/UnmatchedLoop（QUI-1289 拆分后各自独立）、LoopStackOverflow、VecLengthMismatch、SizeMismatch、InvalidGridDimensions、InvalidIntegerK、SampleOutOfDomain、XQMXModeError、TruncatedInstruction、TargetNotFound等（完整清单见 xqvm_py/init.py 的 re-export）。

这些类名不是随意的：conformance harness 通过异常类名把 Python 故障映射到实现无关的故障词汇（见下文），所以类名的稳定性本身就是接口契约。

Conformance：跨实现一致性如何被强制

向量格式

每个一致性向量是conformance/vectors/<category>/<name>/下的一个目录，含三个文件（格式规范见 conformance/README.md）：

• program.xqasm：规范人类可读汇编源。harness 每次运行都在进程内汇编（编码正确性归xqasmcrate 自测负责，因此不提交预汇编字节码）；
• inputs.json：{"calldata": [i64|null, ...], "output_slots": N, "step_limit": N, "memory_limit": N}。null表示宿主保留但未设置的槽位（不能省略——省掉会缩短槽空间、移动CallDataIndex边界，这正是向量要捕捉的分歧）；output_slots默认 16、step_limit默认 10_000_000、memory_limit默认 1_073_741_824，均由 harness 解析一次后显式传给两个 runner（两实现曾对"缺省预算"理解不同，导致同一向量一个受限一个不限）；
• expected.json：要么{"outputs": [...], "final_stack": [...]}（成功），要么{"error": "FAULT"}（故障）；同时提供两者或都不提供会被拒绝为向量编写错误。成功向量可附加可选"steps": u64精确断言计量成本。outputs是稀疏映射：未写槽省略、显式写 0 保留；final_stack为 HALT 时残留栈。

故障词汇表（Fault identities）

由于 Rust 抛枚举变体、Python 抛异常类，两个词汇表无法一一对应，expected.json使用第三种实现无关词汇。映射表（节选，完整见 conformance/README.md）：

故障的字节位置刻意不作为身份的一部分——只比较故障本身，避免向量因无关代码生成变化而变脆。

测试生成与 CI 接线

• conformance/tests/rust.rs 与 conformance/tests/python.rs 由build.rs在cargo build时生成——每个向量在每个启用的运行时下生成一个命名#[test]，向量失败即命名测试失败，而非单个模糊 diff 转储；
• Rust runner 在进程内经xqvm::Vm执行（conformance/src/lib.rs）；Python runner 以子进程方式uv run python -m xqvm_py run执行，解析其 JSON stdout；
• CI 的verify:parityjob 运行make -k check-parity，-k 让一个目标失败后继续跑其余目标，防止 Python 侧回归掩盖 Rust 侧通过（或反之）；
• 相关 Makefile 目标（Makefile）：conformance-rs（cargo test -p xquad-conformance --no-default-features --features rust）、conformance-py（--features python）、conformance-coverage（--coverage打印向量清单）、opcode-parity与metering-parity（分别由 check-opcode-parity.py / check-metering-parity.py 保证 opcode 表与计量常量在 Rust/Python/规范三侧一致）。

一个真实向量示例：conformance/vectors/arithmetic/add_basic/——program.xqasm读取calldata[0]与calldata[1]相加写入输出槽 0，inputs.json给calldata: [10, 5]、output_slots: 4，expected.json断言outputs: [15]、空final_stack。两个实现都必须产出这一结果。

故障顺序（QUI-1178）：操作数弹出 → 计费 → 校验

spec/xqvm/SPEC.md固定了单条指令内的工作顺序：先弹栈、再扣分配费、后校验。xqvm_py曾把寄存器读取排在弹栈之前，在"短栈（verifier 拒绝）"与"操作数故障先于寄存器读取（verifier 放行）"两条路径上产生可观察分歧。22 个 opcode 被重排后，第二路径可到达的分歧由专用向量钉死，例如：

• RESIZE的InvalidGridDimensions无条件先于寄存器读取 →vectors/xqmx-grid/resize_type_after_dimension_check；
• VECPUSH/SETLINE/ADDLINE/SETQUAD/ADDQUAD/EXCLUDE/IMPLIES/REDUCE的MemoryLimitExceeded（仅在预算接近耗尽时可达）→vectors/metering/vecpush_charge_before_type_check；
• ATLEAST的IndexOutOfBounds（k 参数）→vectors/constraints/atleast_k_range_before_model_type；
• ATLEASTW的VecLengthMismatch→vectors/constraints/atleastw_length_before_model_type；
• EQUALITY的VecLengthMismatch（vec 长度比较先于模型寄存器区分与计费）→vectors/constraints/equality_length_mismatch_beats_model_type。

实现侧的关键手法是_peek_model_size/_peek_model_grid（xqvm_py/executor.py）：以is_model()门控的"窥视"来计量，而非解析寄存器后再计量。ONEHOTR/ONEHOTC曾因对样本按真实维度计费、而 Rust 按 0 计费，在紧预算下错误抛出MemoryLimitExceeded（QUI-1202）；_peek_model_grid修复后，样本在任何预算下都计 0 费，预算不再能决定故障类型。

测试与调试：Tracer

xqvm_py/tracer.py 的Tracer实现TracerProtocol（xqvm_py/executor.py 中的on_step_begin/on_step_end/on_error/on_halt回调协议）：

• verbosity=1：紧凑模式，每条指令一行（pc、opcode、操作数）；
• verbosity=2：详细模式，追加栈快照与完整寄存器状态（含变更集changed）；
• 事件包含pc、opcode.name、operands、stack_before/after、pre_registers/post_registers；halt 事件报告outputs_written（实际写入数，而非宿主预留的output_slots——历史 bug 曾把前者冒充后者输出）；
• format_trace()/format_event()提供文本化输出，_format_aligned对齐各列。

与 xquad / xqvm 生态的关系

xqvm_py不是孤岛：它通过 xqffi/src/asm.rs 的 pyo3 绑定消费 Rustxqasm汇编能力，通过 conformance 与 Rustxqvm生产运行时互相钉死行为，其 CLI 输出契约与 Rustxquad run二进制对齐，内存计费与 xquad/tests/test_memory_parity.py 等测试共同保证两实现的内存预算行为一致。作为 XQuad 工具链的"参考基准"，它的存在价值恰恰在于"可以被取代"：当 Rust 运行时完全成熟，这套 Python 栈要么整体退役（向量成为纯参考数据），要么退居原型沙盒，供新 opcode 与 VM 特性在进入规范之前先行验证。理解这一过渡性定位，是正确使用xqvm_py的前提。