zioncode

将文件编码为高弹性的离线符号。通过强完整性校验将其解码还原。
_{专为网闸传输、嘈杂的捕获路径以及明确的恢复诊断而构建。}

## 📖 目录 - [🎯 zioncode 是什么？](#-what-is-zioncode) - [✨ 核心亮点](#-highlights) - [🧭 适用场景](#-when-to-use-it) - [🏗️ 架构](#-architecture) - [🚀 快速入门](#-quick-start) - [🧬 编解码管线](#-codec-pipeline) - [🛡️ 多层鲁棒性](#-layered-robustness) - [🗺️ 路线图](#-roadmap) - [🧪 测试与强化](#-testing--hardening) - [📐 格式规范](#-format-contract) - [🤝 贡献](#-contributing) - [📜 许可证](#-license) ## 🎯 zioncode 是什么？ `zioncode` 是一个 Rust 编解码器 (codec)，用于**在恶劣的离线通道中传输文件**——想象一下网闸 (air-gapped) 计算机、打印的纸张、摄像头拍摄，或者任何源端发出的字节与到达目的地的字节不一致的路径。 v1 版本代码库附带**子系统 A：离线字节编解码器**。它通过压缩、纠错码 (ECC)、交错、逐块及全局完整性校验，将文件转换为一个或多个独立的 `.zbin` 符号，并提供一个带类型的重组器，能够报告*哪些*块丢失，而不是直接失败。 光学渲染（子系统 B）和摄像头解码（子系统 C）被有意设计为未来的独立层——当前的编解码器是一个可独立交付的单元。 ``` file bytes ─▶ zion-codec ─▶ .zbin symbols ─▶ [optical transport] ─▶ captured symbols ─▶ zion-codec ─▶ restored file ``` ## ✨ 核心亮点 - 🚫 **`#![forbid(unsafe_code)]`** — 纯安全 Rust，启用 clippy pedantic 规则 - 🗜️ **逐块 zstd 压缩**，并在压缩效果不佳时回退到原始模式 - 🛡️ **GF(256) 下的 Reed–Solomon 配置** — `safe`、`balanced` 和 `dense` 密度模式 - 🧵 **按列交错 (Column-major interleaving)** — 将突发错误分散到各个码字中 - ✅ **逐块 CRC32C** + **全局 BLAKE3-256 哈希** — 分层完整性校验 - 🧩 **乱序符号重组**，具备类型化错误模型 (missing / duplicate / divergent) - 🔬 **取证模式 (Forensic mode)** — 即使全局哈希不一致也能恢复结构 - 🧪 **经过 Fuzz 强化的**解码器 (`cargo-fuzz`，超过 3000 万次执行，零 panic) - 📦 **冻结的 v1 传输格式** — 规范与代码同处一处 ## 🧭 适用场景 **✅ 适用的场景** - 无网络计算机之间的网闸传输 - 通过可能损坏、截断或重复字节的介质进行传输 - 需要报告*为什么*无法恢复数据的流水线 - 需要独立逐块完整性校验的长期归档 **❌ 不适用的场景** - 实时流处理（这是一个批量编解码器） - 静态数据加密——完整性 ≠ 机密性；如有需要，请在上面叠加一层加密 - ECC 开销占比过大的极小负载——你更需要一个简单的哈希 ## 🏗️ 架构 ``` flowchart LR subgraph A["🧱 Subsystem A · offline codec ✅"] direction TB lib["zion-codec
<sub>library crate</sub>"] cli["zion-cli
<sub>zion binary</sub>"] cli --> lib end subgraph B["🖼️ Subsystem B · optical renderer 🔜"] render["byte stream ➜ grayscale symbol"] end subgraph C["📷 Subsystem C · optical decoder 🔜"] capture["image ➜ byte stream"] end file[("📄 file")] -->|encode| lib lib -->|.zbin bytes| render render -->|print / screen| world(((📡 air gap))) world -->|camera / scan| capture capture -->|.zbin bytes| lib lib -->|decode| restored[("📄 restored file")] classDef done fill:#10B981,stroke:#065F46,color:#fff classDef todo fill:#1F2937,stroke:#4B5563,color:#9CA3AF,stroke-dasharray: 5 5 class A done class B,C todo ``` | 路径 | 职责 | 状态 | |----------------------------------------------|--------------------------------------------------------------------|--------| | [`zion-codec/`](zion-codec/) | 核心库：格式、压缩、ECC、编码、解码、重组 | ✅ v1 | | [`zion-cli/`](zion-cli/) | 围绕核心库构建的轻量级 `zion` 命令行工具 | ✅ v1 | | [`zion-codec/tests/`](zion-codec/tests/) | 往返测试 + 基于属性的不可变式 | ✅ v1 | | [`zion-codec/benches/`](zion-codec/benches/) | 关键路径的 Criterion 基准测试 | ✅ v1 | | [`fuzz/`](fuzz/) | `cargo-fuzz` 目标 (nightly) | ✅ v1 | | [`docs/superpowers/specs/`](docs/) | v1 传输格式的真实来源 | ✅ v1 | ## 🚀 快速入门

📦 将文件编码为符号

``` cargo run -p zion-cli -- encode ./input.bin --output-prefix ./out/input # ▶ 写入 ./out/input_000.zbin, ./out/input_001.zbin, ... ``` 默认情况下，CLI 会选择一个自动的 `K` 值，以最小化所选配置下的输出字节数。当渲染器需要固定的物理符号大小时，请使用 `--k` 覆盖。 配置： ``` --profile safe # RS(255,223), strongest default profile --profile balanced # RS(255,239), lower overhead, less correction --profile dense # RS(255,247), lowest overhead, smallest correction budget ``` 使用 `--zstd-level` (3 · 6 · 9) 调整压缩级别。

🔍 检查单个符号

``` cargo run -p zion-cli -- inspect ./out/input_000.zbin ``` 打印解析后的头部信息：ECC 配置、file_id、symbol_index、block_start/count、全局 BLAKE3 哈希以及块状态。

🔄 解码回文件

``` cargo run -p zion-cli -- decode ./out/input_*.zbin --output ./restored.bin ``` 可以按**任意顺序**传入符号——重组器会通过 `symbol_index` 对它们进行排序。仅当全局哈希不匹配的取证恢复场景下，才使用 `--force-write-corrupt`。

🧰 作为库使用

``` use zion_codec::{Decoder, Encoder, EncoderConfig}; let config = EncoderConfig::fixed_k(148)?; let encoded = Encoder::new(config).encode(&file_bytes)?; let restored = Decoder::default().decode_file(&encoded.symbols)?; assert_eq!(restored, file_bytes); ```

## 🧬 编解码管线 ``` flowchart TD raw([📄 raw file]) raw --> split["🪓 split · 8 KiB blocks"] split --> zstd{{"🗜️ zstd vs raw
<sub>pick whichever is smaller</sub>"}} zstd --> pack["📦 greedy packing
<sub>up to 4 blocks / symbol</sub>"] pack --> hdr["🧾 header · 82 B
<sub>magic, version, file_id, index</sub>"] hdr --> crc["🧮 CRC32C · per block"] crc --> ecc["🛡️ Reed-Solomon profile
<sub>safe · balanced · dense</sub>"] ecc --> inter["🧵 column-major interleave"] inter --> sym([🔣 .zbin symbol]) sym -.capture / transport.-> sym2([🔣 received symbol]) sym2 --> dinter["↔️ deinterleave"] dinter --> rsd["🛡️ RS decode
<sub>profile auto-detected</sub>"] rsd --> verify["🧮 verify block CRCs"] verify --> reasm["🧩 reassemble blocks
<sub>out-of-order · duplicates ok</sub>"] reasm --> blake["🔐 BLAKE3-256 global check"] blake --> out([📄 restored file]) classDef pipe fill:#0F172A,stroke:#334155,color:#E2E8F0 classDef decision fill:#4338CA,stroke:#1E1B4B,color:#fff classDef io fill:#10B981,stroke:#065F46,color:#fff class split,pack,hdr,crc,ecc,inter,dinter,rsd,verify,reasm,blake pipe class zstd decision class raw,sym,sym2,out io ``` ## 🛡️ 多层鲁棒性 | # | 层级 | 作用域 | 捕获的内容 | |:-:|-----------------------------|-----------------|----------------------------------------------------------------------------------------------------| | 1 | **zstd + 原始回退** | 每 8 KiB 大小的块 | 不可压缩的数据不会膨胀 | | 2 | **CRC32C** | 每个块 | 局部负载损坏（单块丢失是可恢复的） | | 3 | **Reed–Solomon 配置** | 每个码字 | `safe` 最多纠正 16 个字节错误；`balanced` 8 个；`dense` 4 个 | | 4 | **按列交错** | 每个符号 | 突发错误会被分散到各个码字中 | | 5 | **头部 CRC32C** | 每个符号 | 畸形的元数据快速失效，不引发噪音 | | 6 | **BLAKE3-256** | 整个文件 | 跨符号的端到端篡改检测 | | 7 | **类型化重组器** | 整个文件 | `MissingBlocks`、`DuplicateSymbol { divergent }`、`InconsistentFileMetadata`、`GlobalHashMismatch` | ## 🗺️ 路线图 | 里程碑 | 子系统 | 状态 | |----------------------------|-------------------------------------------------|:-----:| | **M1 · v1 冻结** | 传输格式、常量、错误模型 | ✅ | | **M2 · 编解码器核心** | 编码 / 解码 / 重组 / 测试 | ✅ | | **M3 · 强化** | 属性测试、`cargo-fuzz`、criterion 基准测试 | ✅ | | **M4 · 光学渲染器** | 字节流 → 灰度 PNG (子系统 B) | 🔜 | | **M5 · 光学解码器** | 摄像头帧 → 字节流 (子系统 C) | 🔜 | | **M6 · `.zion` 容器** | PNG + sidecar 元数据，统一的文件扩展名 | 🔜 | ## 🧪 测试与强化 ``` cargo test --workspace # unit + integration + property tests cargo clippy --all-targets --all-features # pedantic lints, -D warnings cargo fmt --all --check # formatting gate cargo bench -p zion-codec # criterion hot paths ``` Fuzz 测试需要 nightly 版本（参见 [`CLAUDE.md`](CLAUDE.md)）： ``` cd fuzz rustup run nightly cargo fuzz run decode_full -- -max_total_time=30 rustup run nightly cargo fuzz run parse_header -- -max_total_time=30 rustup run nightly cargo fuzz run parse_block -- -max_total_time=30 ``` **由属性测试固定的不可变式** — `output.len() == K * 255`，干净流上的字节级一致往返测试，ECC 容忍范围内的有限损坏总能恢复，重复符号会合并有用的块，结构上的分歧会被拒绝。 ## 📐 格式规范 v1 二进制格式已被**冻结**，并位于： ``` docs/superpowers/specs/2026-04-23-zioncode-codec-offline-design.md ``` 任何对头部布局、ECC 参数、交错、块打包、验证不变量、错误语义或兼容性规则的更改，都必须首先更新规范，如果是破坏性更改，还需提升头部中的版本字节。 ## 🤝 贡献 我们遵循 **superpowers 工作流**：`brainstorming` → `writing-plans` → `subagent-driven-development`，每个逻辑步骤对应一次提交，使用以 **gitmoji** 为前缀的英文主题。 完整清单（fmt、clippy、测试、fuzz、PR 模板）请参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 涉及安全敏感的解析器或解码器更改时，应包含针对畸形输入的测试覆盖，并在相关时更新 fuzz 目标。 ## 📜 许可证 采用双重许可，您可选择以下任一： - Apache License, Version 2.0 ([`LICENSE-APACHE`](LICENSE-APACHE)) - MIT License ([`LICENSE-MIT`](LICENSE-MIT)) 详情请参阅指向文件的 [`LICENSE`](LICENSE)。

_{使用 🦀 构建 · 使用 🧪 强化 · 使用 🔐 签名}

标签：BLAKE3哈希, CRC32C校验, meg, Reed-Solomon纠删码, Rust, Zenmap, Zstandard压缩, 信息安全, 列式交织, 前向纠错, 可视化界面, 安全数据传输, 对抗性信道传输, 恶意环境传输, 抗干扰通信, 数据完整性, 数据恢复, 文件编解码, 暗网传输工具, 物理隔离, 离线数据同步, 离线编解码器, 网络信息收集, 网络流量审计, 通知系统, 防篡改, 隐私计算, 隐秘通信, 高容错传输