aivmm

aivmm 是一个从零实现的系统虚拟机项目：自定义 AIVM64 RISC 指令集、CPU 解释器、RAM/MMIO、UART、镜像格式、汇编器和调试器均在本仓库中实现，不复用 现有 VM 核心。首版运行在 Ubuntu 24.04 LTS x86_64；不支持 macOS。

你只需要做这些

安装 Rust、Node.js 22 和 just：

sudo apt update
sudo apt install -y build-essential curl just
sudo snap install node --classic --channel=22
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup component add clippy rustfmt llvm-tools-preview
cargo install cargo-llvm-cov

进入仓库后运行：

npm install
just demo

你应该看到 Hello, AIVM! 和 VM 退出信息。just demo 会自动编译汇编器、 生成 examples/hello/hello.aivm，再启动 VM。

常用命令

just debug                         # 启动 REPL 调试器
just check                         # format、lint、Rust/TS 测试和 demo
just perf                          # release 模式性能门槛（至少 1 MIPS）
just coverage                      # 核心 workspace 行覆盖率至少 80%
cargo run -p aivm-cli -- --help

调试器支持 run/continue、step、break ADDR、delete ADDR、regs、 mem ADDR [LEN]、disasm [N]、reset 和 quit。

写 Guest 程序

参考 examples/hello/hello.asm。生成容器镜像：

cargo run -p aivm-cli -- asm program.asm program.aivm
cargo run -p aivm-cli -- run program.aivm

生成适合手敲/检查的 raw 机器码：

cargo run -p aivm-cli -- asm program.asm program.bin --raw
cargo run -p aivm-cli -- disasm program.bin --raw --base 4096
cargo run -p aivm-cli -- run program.bin --raw --load-address 4096

指令编码和完整 v1 opcode 见 docs/isa.md；容器字段见 docs/image-format.md。

配置

默认配置是 config/default.toml，另有最小和完整示例。覆盖顺序为：

1. Rust 内置安全默认值；
2. --config FILE 指定的 TOML；
3. AIVMM_MEMORY_SIZE、AIVMM_INSTRUCTION_LIMIT、AIVMM_ENTRY、 AIVMM_STACK_POINTER、AIVMM_DETERMINISTIC、AIVMM_RANDOM_SEED、 AIVMM_UART_BASE 环境变量；
4. 同名 CLI 参数。

检查或展开配置：

cargo run -p aivm-cli -- config check
cargo run -p aivm-cli -- config dump
cargo run -p aivm-cli -- --memory-size 2097152 run program.aivm

未知 TOML 字段、冲突地址、RAM 外入口/栈和尚未实现的 JIT 会被拒绝，不会静默 忽略。默认指令预算可以阻止失控 Guest 无限占用 CPU。

让 Cursor Agent 继续开发

本地模式会从 tasks/tasks.yaml 领取任务，每次最多运行 agent.config.toml 指定的轮数。它会保存 agent/run ID，下一次自动恢复； 只修改工作区并执行质量门禁，不允许自动 commit。

export CURSOR_API_KEY="cursor_..."
npm install
just agent

修改 max_rounds、max_cost_cents、model、重试和质量命令都在 agent.config.toml。费用数据由 SDK 提供且可能短暂延迟，因此金额门槛用于 阻止后续轮次，不保证在当前轮中硬截断。密钥只从环境变量读取，不要写入 TOML。

Cloud 模式要求仓库已推送到 GitHub，且 Cursor API key 能访问该仓库。Cloud Agent 在独立分支工作并自动创建 PR，绝不直接更新主分支：

just agent-cloud

模型 ID 会随账户能力变化；默认 auto。遇到认证错误先检查 CURSOR_API_KEY，遇到没有可运行任务则检查 YAML 中的 status 和 depends_on。Agent runner 是有界循环，不是无法停止的守护进程，因此费用和 失败范围由配置控制。

设计边界

• crates/aivm-core：原创 CPU、指令编码、RAM/Bus/UART 与扩展 trait。
• crates/aivm-format：版本化 AIVM 镜像和 raw 加载。
• crates/aivm-asm：两遍汇编和反汇编。
• crates/aivm-cli：运行、配置、性能和调试界面。
• tools/agent-runner：Cursor SDK 自动任务循环。

架构与扩展方法见 docs/architecture.md、docs/extensions.md；后续工作见 ROADMAP.md 和 tasks/tasks.yaml。

许可证

项目以 MIT 或 Apache-2.0 双许可证发布，任选其一使用。