#TryAndRun-TvT/fast_qr_moonbit

基于 MoonBit 的高性能二维码（QR Code）生成库。 纯 MoonBit 实现、无外部依赖，逐位对齐 Rust 参考库 fast_qr v0.14.0。

#目录

• 功能特性
• 能力与局限
• 快速开始
• 从源码构建
• 编译为 Wasm
• 性能与体积
• 测试
• 文档索引
• 代码放置约定
• 项目结构
• 开发与 CI
• 问题反馈与贡献
• License

#功能特性

• 纯 MoonBit 实现，无外部依赖，可直接 moon add 依赖到你的项目。
• 标准合规：遵循 ISO/IEC 18004 —— 版本 V01–V40、四种纠错级别（L/M/Q/H）、 三模式自动编码（Numeric / Alphanumeric / Byte）+ 自动回退、8 种掩码评分择优。
• 逐字节对齐参考：矩阵与 fast_qr v0.14.0 全量快照逐位一致，可解码读回原文。
• 单后端产物：仅 wasm-gc（体积小、性能好；宿主需支持 GC 提案）。
• 两用接口：过程式 QRCode::build 编排入口 + 链式 QRBuilder 便捷构造器。
• 多样输出：终端字符画（to_str/print）与 SVG 字符串（SvgBuilder，6 种模块形状）。

#能力与局限

• 编码模式仅支持 Byte/Alphanumeric/Numeric；Kanji 模式暂不支持（与参考 fast_qr 一致）。
• 输入按 ASCII 字节 处理（非 ASCII 多字节字符的语义见 S6 评审记录 的优化建议）。
• 产物形态面向 wasm：MoonBit Int 32 位、纠错位流 KEEP_LAST=33（取 Rust wasm32 分支）， 对真实 QR 语义无差别（详见 S9 评估记录 §2.4）。
• 仅支持 wasm-gc：moon.mod 声明 supported_targets = "+wasm-gc"，下游 native/JS 消费者会被构建系统 直接拒绝（实测 does not support target backend 'native'）。库本身是纯 MoonBit，此为有意的分发范围收缩； 其中 native 另需系统 C 编译器（当前 CI/本地镜像未装）。
• 宿主需支持 wasm-gc（GC 提案）：如 Node ≥ 22 / V8、启用 GC 的 wasmtime；CLI println 依赖 spectest.print_char 导入（非标准 WASI）。wasm(WASI) 通用兜底已移除，宿主接入面相应变窄。 取舍与复核见 S9n wasm-gc 收敛审计 §1。

#快速开始

# 需本模块已发布至 mooncakes；发布前的过渡期为 clone 本仓库按「从源码构建」体验
moon add TryAndRun-TvT/fast_qr_moonbit

发布状态：尚未发布（0.1.0 待发布）。发布流程、元数据/命名核验、归档面治理 与发布前门禁清单见 mooncakes-发布方案.md； 发布动作已脚本化：bash scripts/publish.sh（默认干跑，--publish 真发）， 模块名迁移记录见 模块名迁移与发布链路核验.md。

import {
  "TryAndRun-TvT/fast_qr_moonbit/lib",
}

/// 由字符串输入构建 QRCode（缺省全部自动：mode 自动、ECL=Q、version 最小、mask 择优）。
fn gen() -> @lib.QRCode {
  match @lib.QRBuilder::from_string("https://example.com/").build() {
    Ok(q) => q
    Err(_) => abort("content too large")
  }
}

fn main {
  let qr = gen()
  // 输出终端 Unicode 半块字符画（含边距）
  println(qr.to_str())
  // 输出 SVG 字符串（默认黑色方块 + 白色背景、margin=4），链式定制颜色与模块形状
  let svg = @lib.SvgBuilder::default()
    .module_color("#0000ff")
    .background_color("#ffffff")
    .shape(@lib.Shape::RoundedSquare)
    .to_str(qr)
  println(svg[:200].to_owned() + "...")
}

#矩阵读写与自建（宿主可拿到 QRCode）

// ① 已有编码结果：读/改单格（set 为不可变式，返回新 QRCode，不改源）
let (v, ecl, mask, mode) = qr.meta()          // 元数据快照
let dark = qr.get(0, 0).value()               // 逐格读
let qr2  = qr.set(0, 0, @lib.Module::new(true, @lib.ModuleType::Data))  // 逐格写

// ② 从零自建：空矩阵（全亮）作起点，逐格写入后输出
let canvas = @lib.QRCode::empty(@lib.Version::V05)   // 边长 = 版本*4+17
let drawn  = canvas.set(10, 10, @lib.Module::new(true, @lib.ModuleType::Data))
println(drawn.to_str())

命名/形状等辅助入口：Shape::from_name("circle")（按名取形状）、 ECL::to_char(ECL::Q)（级别显示字符）、SvgBuilder::default().module_color(...)（链式配色）。

#从源码构建

curl -fsSL https://cli.moonbitlang.cn/install/unix.sh | bash
export PATH="$HOME/.moon/bin:$PATH"

moon build lib          # 编译库包
moon build cmd/main     # 编译 CLI
moon run   cmd/main     # 运行 CLI 演示（终端字符画 + SVG）
moon test               # 运行单元/快照测试

export PATH="$HOME/.moon/bin:$PATH"
moon fmt && moon info && moon check --deny-warn && moon test
moon build lib --target wasm-gc --release
moon build cmd/main --target wasm-gc --release
moon test --target wasm-gc

#编译为 Wasm

# 唯一后端 wasm-gc（体积最小、性能最优，宿主只需提供 spectest.print_char）
moon build cmd/main --release
moon run   cmd/main

引用规范：cmd/bench / cmd/main 是「命令形态」产物，外壳不随库分发， 不能代表库被宿主嵌入时的实际体积——引用库体积请用 cmd/qr-min 口径并注明后端与优化档。 体积金字塔（wasm-gc，-Oz）：运行时地板（一行 println）263 B → QR 核心净增 +31102 B（cmd/qr-min）→ 输出层（终端画 + SVG）+2228 B（cmd/main）→ 基准外壳 +4809 B（cmd/bench）。

# -Oz 体积最优档（默认后端 wasm-gc）：
#   --all-features 会开 custom-descriptors(RTT)，其 exact heap type 在 Node/moonrun 上编译不过；
#   --disable-custom-descriptors 才产出「可被真实宿主加载」的最优档。
moon-wasm-opt _build/wasm-gc/release/build/cmd/main/main.wasm \
  --all-features --disable-custom-descriptors -Oz -o main.min.wasm   # 33593 B

结论：库对库，wasm-gc 在 raw 与 -Oz 两档都约 0.69–0.70×；扣掉运行时地板后核心净增 1.21×——差距大头是两侧运行时地板（wasm-gc 263 B vs Rust 20052 B，76×），非 QR 实现差异。 命令形态（cmd/bench 含 argv/迭代外壳）对照与其他档位明细见 S9i · S9f。

#性能与体积

引用的性能数字仅作选型与迭代基线，不代表对 fast_qr 的追赶承诺；逐条口径见 S9 系列文档。

① 的数据随本轮 P0/P2/P2b 优化已刷新（2026-09-12 重测）；② 为优化前（2026-09-06）历史口径， 未随本轮重测，量级参考即可。

#① vs fast_qr-wasm32：性能明细

旧命令形态口径（cmd/bench，保留作对照）：A 每次新建 Instance （与 fast_qr「一次调用」同形，会系统性夸大差距）fast/ours = 0.263 / 0.528 / 0.728×； B 单实例摊薄 = 0.340 / 0.574 / 0.737×。三者对照见 S9p §4.1。 护栏全绿：宿主面 checksum 与 cmd/bench <点> 1 逐点相同（41/81/230，证明两个口径 是同一计算）· 同实例重复调用结果恒定 · 逐位对齐 sha256 三点相同 · Node shim vs moonrun 跨宿主一致。 统计口径（S9q）：上表上行为「R=5 中位数」口径（R=3 回退取最小并与离散成对报出）。 同一产物重复测量（15 轮 × 5 次）的比值 CV：V03H 5.98% ≫ V10H 3.54% > V40H 0.35%—— 单次 build 越便宜，相对统计误差越大（固定项占比）；V03H 单轮最坏可偏离真值 +17.3%。 噪声非白噪声（lag-1 自相关 r1 = 0.28~0.68，存在热/频漂移），故同一进程内加轮次收益有限； 更大偏差来自宿主调度态（6 线程满载竞争使三点一致慢 1.43–1.50×）与 Node 大版本（v22→v24 两侧共模 1.12–1.23×）。 纪律：只用「同 run 内成对比值」，不跨 run 加减绝对毫秒；主数取中位数而非算术平均（分布右偏）。 绝对毫秒数绑定测量环境（本表 Node v24.21.0 + 2026-09-14 宿主）：跨环境只比「同 run 成对比值」， 方向性结论全环境成立，归因见 S9h。 生态另两个 QR 包（qrc/moonbitqrcode）缺完整择优/Format 等，不可同口径对齐，仅参考口径见 S9d。

#后续优化 Roadmap

#测试

• 强负向对照（变异检测）：就地植入 21 类最小缺陷 → 21 类全部被现有测试检出 （复跑 bash scripts/test-audit.sh mutation）。历次审计共发现 4 条真漏检，全部已修： ① 容量表改中间项、② Format 表改非抽查 (ECL,mask)（初版，由 T1-f/T2-e 修复）； ③ N1 结算阈值 5→6（「恰好 5 连后立刻变色」路径无覆盖，由 T2-b2/b3 修复）； ④ 择优并列 s < best → s <= best（并列规则是文档契约却无用例，由 T2-d2 修复）。 这两条首跑即漏检，是本轮审计最大的价值——分支存在 ≠ 分支被测、契约必须显式锁定。
• 独立第三方解码回读：用纯 JS 解码器 jsqr 对矩阵做像素化解码， ① 三基准点（V03H/V10H/V40H）全部读回原文； ② T3-d 全语料 54 组（三模式 × 4 ECL × 4 版本 + 6 组自动版本靶点）全部读回原文； ③ --mutate 负向对照组（破坏定位图案）全部解码失败——证明该证据链「能红、可信」 （入口 bash scripts/test-audit.sh decode，口径与标定见 S10 附录 D）。
• ⚠️ 测试基础设施抓到了一条真 bug（v5）：T3-d 探针首跑即暴露 QRCode::select_capacity 的模式语义缺陷——显式 mode 未参与容量判定， 较长 Alphanumeric/Byte 输入被静默按 Numeric 选版本，数据区装不下实际位流 → 矩阵不可解码（旧实现下 4/54 组 jsQR 返回 NULL）。 修复后与参考在 83,160 组参数上零差异；详见 S10c-select_capacity模式语义缺陷-定位与修复.md。
• 证据链钉版可复现：所有「与参考逐位一致」的黄金值均可由 scripts/gen-goldens.sh 在钉版参考上重建/校验（--verify 四项零差异），并已实测检出「中间项改值」「布局偏移」「系数改值」类缺陷。
• 差分门禁：scripts/diff-gate.sh（T4-c，本地/按需；已并入 gates.sh），把「与参考 wasm 逐位 sha256」 从仅打印升级为门禁；无参考制品时显式打印 skipped，避免静默假绿。
• 覆盖率：bash scripts/coverage.sh（T5-a 报告，见 S10b）； --floor 为 T5-b「不下降」门禁（lib/** 未覆盖行 ≤ S10b 顶部 coverage-floor 标记）。 不设绝对百分比阈值——覆盖率是变异检测的补充而非替代（铁律 3），绝对阈值会诱发造无信息量用例。
• 文档互链死链检查：bash scripts/docs-link-check.sh（T6-c，本地/按需；已并入 gates.sh）； 检查受版本控制 Markdown 的相对链接存在性（跳过外链/锚点、忽略代码块），当前 487 条零死链。
• 测试规模护栏：bash scripts/test-scale.sh（T7-b，本地/按需；已并入 gates.sh），单测试文件 ≤800 行。

#文档索引

面向读者的口径与结论汇总在本文；实现细节、逐条口径、历史记录在下列文档 （随附代码实测与复跑方式）。文件名前缀 S1–S9n 为按实现顺序编号的阶段文档。

⤷ 行是该目录/系列的总入口（不再逐篇平铺，避免索引与文档本体重复）。 S11 是清理/收敛的评估入口（无效代码与冗余文档的判定口径 + 处置队列）， 不替代 S10（测试覆盖面）与 S10b（覆盖率数字）。 其中 S1–S9n 每篇含「实现方案 / 实现记录 / 评审与优化」等分部，按阶段顺序编号； 性能相关重点篇目：S9b（优化路线与已否决项）、S9d（vs moonbit 生态）、S9f/S9g（历史体积口径）、 S9h（环境归因）、S9l（参考 fast_qr 拆解）、S9m（ReadOnlyArray）。

#代码放置约定（方案 3：模块根无包，库包在 lib/）

#项目结构

.
├── moon.mod                    # MoonBit 模块配置（模块根不建包）
├── lib/                        # 库包（公共 API，lib/moon.pkg）
│   ├── ecl / version / mode / mask.mbt  # 公共枚举（ECL/Version/Mode/Mask）
│   ├── module.mbt              #   公共 Module / ModuleType（单字节位打包）
│   ├── qr.mbt                  #   QRCode 结果容器 + QRCodeError + 访问器
│   ├── qr_build.mbt            #   编排/构造：select_capacity + build_fixed/build
│   ├── qr_builder.mbt          #   公共 QRBuilder 构造器
│   ├── helpers.mbt             #   输出层：终端画渲染 + QRCode::to_str/print
│   ├── svg.mbt / shape.mbt     #   输出层：SVG 渲染 + Shape 枚举
│   ├── *_test.mbt / *_wbtest.mbt          # 黑盒测试 / 白盒测试
│   └── internal/               #   实现子包（各带 moon.pkg；不反向依赖 lib）
│       ├── constants/          #     常量表 + 容量/元数据表
│       ├── bitstream/          #     位流缓冲（CompactQR）
│       ├── reedsolomon/        #     GF(256) 除法 + 交织
│       ├── data_encoding/      #     三模式编码 + 自动回退
│       └── matrix/             #     module/matrix/placement/datamasking/score
├── cmd/main/                   # CLI 可执行入口（演示终端画 + SVG）
├── cmd/bench/                  # 性能基准（含 --dump 值全集导出）
├── cmd/qr-min/                 # 纯库调用体积探针（库实际体积口径，零外壳）
├── docs/                       # 项目文档（见上文「文档索引」）
│   └── assets/                 #   文档资源（qr-example.svg = README 示例码）
├── scripts/                    # 构建与开发辅助脚本（见下节）
├── .githooks/                  # 可选 Git 钩子（需自行启用）
├── .cnb.yml                    # 云原生构建（CNB CI）配置
├── AGENTS.md                   # AI 协作代理指南
├── README.md                   # 本文件（moon.mod 的 readme）
└── LICENSE                     # Apache-2.0

#开发与 CI

• 代码门禁：bash scripts/gates.sh（一键全量：moon fmt --check + moon check --deny-warn + moon test + 死链/规模护栏 + wasm-gc release 回归 + 差分门禁 + 发布前门禁； 支持 STAGES="check test" / SKIP_SLOW=1）。 push CI 已于 2026-09-14 移除（每次推送重复全量构建，资源收益不成比例）， 门禁脚本零改动、改为本地/发布前按需执行，故提交前跑一遍是必须动作。 （不加 native 阶段——需系统 C 编译器。）
• 发布：bash scripts/publish.sh（默认干跑：环境自检 + 发布前门禁 + 归档清单 + moon publish --dry-run）；真实发布 bash scripts/publish.sh --publish（不可逆，需确认）。 凭据属本地私有，发布不进 CI。
• 基准复跑：见性能与体积的复跑入口；参数口径见 性能测试脚本-公开评审说明.md。
• Git 钩子（可选）：git config core.hooksPath .githooks（个人本地配置，仓库不代设）。
• 编码 / 提交规范：见 AGENTS.md（密钥安全、MoonBit 布局、文档死链零容忍等硬性约定）。

#问题反馈与贡献

• 问题与建议：提交至仓库 Issue。
• 贡献流程：改动前请阅读 AGENTS.md（密钥安全、MoonBit 布局、文档死链零容忍等 硬性约定），并跑通开发与 CI 中的收尾检查后再提交。

#License