运行保留的原生代码。重新打开其已初始化的状态。 Capsulith 将选定的 ARM64 函数、其调用约定和自有内存打包,供 Node 或浏览器使用。保留原始指令,并在全新的 worker 中恢复已初始化的对象,无需原始应用程序。
打开原生图像工作台 并选择 Load & run example。准备好的 QOI 案例可在本地运行,无需账户、上传服务器、原始二进制文件或编译器。

PNG 使用浏览器解码的 RGBA 作为明确的比较基准;仅 QOI 输入没有独立的源像素比较。图像限制为每维 256 像素、1 MiB。这是一个已知来源的预制原生组件演示,并非新的编解码器或通用格式恢复。原始 QOI 源码、约定、独立的原生/FFmpeg 对照以及独立 Node 命令。
带来一张小尺寸 PNG 或 QOI 图像。提取出的原始编码器会写出一个 QOI 文件,一个独立的原生解码器返回其像素,你可以检查各个 RGBA 字节。保留已初始化的像素分配,关闭 worker,然后在一个全新的 worker 中恢复并释放它。
试用无密钥浏览器对象演示 并按下 Run lifecycle。它在本地执行实际提取出的指令;它不会调用服务器来生成结果。
从 release 下载 Python wheel,然后:
python3 -m pip install capsulith-0.3.1-py3-none-any.whl
capsulith studio
打开 http://127.0.0.1:6359。函数 Studio 保留了 LZ4 解码器和 xxHash 样本。打开 Object studio,选择 Open original LZ4 example,然后选择 Run lifecycle,以创建、压缩、保存字典、检查点、恢复、继续并释放一个实际编译的流。无需 API 密钥或付费服务。提取需要 Python 3.10+ 和 Capstone;浏览器通过内置的 WebAssembly 模拟器执行。Node 20+ 仅在 CLI 或导出的 Node 调用中需要。
Studio 接受 ARM64 Mach-O dylib,清点其函数,提取选定的根,并允许你编辑缓冲区、寄存器参数、标量输入和返回类型。依赖视图将辅助函数/导入连接到实际调用点和原始指令。执行事件链接到命名的内存区域和原始代码。已停止的执行会显示部分证据,而不会声称结果成功。
Export portable capsule 会下载当前字节、契约和输入、Node/浏览器运行器、固定版本的后端、完整的后端源代码/构建脚本以及许可证。解压并运行 node run.cjs,或通过 HTTP 提供该文件夹并打开其独立的浏览器运行器。这些调用不需要 Python、Capstone 和原始二进制文件。导出的 API 接受不同的输入,支持取消,并强制执行声明的限制。
Original LZ4 methods, restored dictionary access and exact native comparison in the object Studio
对象 Studio 导入提取的模块 JSON,或读取你拥有的 ARM64 Mach-O 工件,其中显式声明了命名方法。检查实际的根、块和依赖;从十六进制或本地文件分配命名的调用方缓冲区;选择一个方法并提供类型化的区域引用或整数。内存映射显示真实拥有的区域和初始化,使用不透明的原始字节而非猜测的字段。返回值、访问范围、计数器和有界事件来自原始指令。
在可能需要撤销的操作之前保存检查点。恢复匹配的模块会保留客户机地址和区域 ID,但会创建新的实例标识;按区域 ID 重新绑定引用。编辑输入会使过时的证据失效,而故障或取消需要先前的检查点或新实例。原生释放和调用方缓冲区释放是独立的显式生命周期操作。运行时从不猜测原生指针是否仍指向某个缓冲区。
CLI 示例使用仓库中的文件。上述 wheel 安装不会将 examples/ 或 runtime/ 放入你的工作目录。在没有现有 Capsulith 文件夹的目录中,克隆仓库并从其根目录运行命令:
git clone https://github.com/nazeeh111/Capsulith.git
cd Capsulith
capsulith module examples/lz4/liblz4.dylib \
--methods examples/native-objects/methods.json --out stream.module.json
node runtime/object-cli.cjs examples/native-objects/start.json \
--module stream.module.json --checkpoint-out first.checkpoint.json
# The first Node process has ended. This command opens a fresh worker.
node runtime/object-cli.cjs examples/native-objects/continue.json \
--module stream.module.json --checkpoint first.checkpoint.json
capsulith export-module stream.module.json \
--checkpoint first.checkpoint.json --out stream-object.zip
选择新的输出名称;module、checkpoint 和 object 导出命令会拒绝覆盖已存在的文件。所提供的操作程序特定于文档中描述的 LZ4 生命周期。通用模块需要其自身由调用方声明的方法和操作程序。
object 导出包含原始指令模块、可选的保留 checkpoint 字节、独立的 Node/浏览器运行器、object Studio、运行时及相应的后端源码/构建脚本、许可证,以及一个包含字节数、SHA256 和权限的文件清单。提供该文件夹的服务并打开 index.html,即可在没有 API 端点的情况下恢复捆绑的 checkpoint,或运行 node run.cjs your-operations.json --checkpoint checkpoint.json。执行时不需要原始二进制文件、Python 包和编译器。checkpoint 包含保留的调用方字节;分享前请先检查它们。参见object API 和操作格式以及原生示例。
一个遗留解码器、校验和或孤立的二进制例程可以变成一个小的可复用 API。Capsulith 会展示哪些字节和依赖项随之携带、执行在何处读取和写入,以及当某个功能需要不受支持的状态时为何无法被提取。
capsulith inspect legacy.dylib
capsulith extract legacy.dylib --root _decode \
--contract decode-contract.json --out decode.capsule.json
capsulith run decode.capsule.json --inputs input.json
capsulith export decode.capsule.json --inputs input.json --out decoder.zip
根选择也接受已验证的函数起始地址,例如 --root 0x440。导出符号不是原型。你提供实际的调用约定;Capsulith 不会推断 ABI(将参数和返回值放入寄存器的规则)。运行时指南 定义了缓冲区、32/64 位整数、内存导入和限制。examples/xxhash/contract.json 是一个完整的三参数示例。
LC_FUNCTION_STARTS。私有辅助函数名称可能被剥离;函数边界必须保留。__const/__cstring 保留、显式有界的 memmove、memcpy 和 memset 导入。malloc、bzero 和 free 内存模型、初始化的自有堆字节以及方法边界处的代码绑定检查点。不推断堆布局或指针重写。间接控制流、可写静态状态、重定位静态指针、不支持的导入、陷阱、其他架构和其他工件族会收到明确的诊断信息。静态地址候选是基本块语法证据;实际跟踪建立观察到的访问。此初始范围不恢复源代码、不推断任意原型、不克隆整个应用程序,也不建立模拟器安全隔离。工件哈希记录来源,不认证胶囊。仅提取和再分发你有权使用的工件。
测试使用真实的完整库工件,而非手写的算法替代品:
| 样本 | 原始代码 | 独立比较 |
|---|---|---|
| LZ4 v1.10.0 初始化流 | 12,548 代码字节,26 个函数 | 原始 create/compress/save/free;跨新进程的精确连续输出;字典读取证据;原生独立解码 |
| LZ4 v1.10.0 解压器 | 2,456 字节,三个函数 | 128 个全原生对照、畸形块、短输出、原始静态数据、声明的 memmove、剥离的辅助函数名称 |
| xxHash v0.8.3 XXH32,O2 | 308 字节 | 生产 Wasm 中 550 个不同的输入/种子组合 |
| xxHash v0.8.3 XXH32,单独编译的 O1 | 284 字节 | 相同的 550 个组合,不同的原始指令 |
初始化流将第一个 65,536 字节的数据包压缩到 8,459 字节,将不同的 32,768 字节数据包在恢复后压缩到 6,795 字节,而新流中为 8,355 字节。保留的输入和编译的 saveDict 路径都与独立的原生 oracle 完全匹配。浏览器 Studio 生命周期也计算了 8,459/6,795 字节,从保留历史中读取了 8,205 字节,并通过 freeStream 释放了原生堆。这些是有限的功能比较,不是吞吐量基准测试。
xxHash 原生对照还覆盖了四种实际指针对齐,总计 4,400 次原生调用。生产指针当前已对齐。源代码许可证、字面 oracle 输入/结果、工件哈希和编译器命令保留在 examples/ 中。这些有限对照支持声明的范围;它们不是通用等价性或性能证明。
从源代码检出运行发布门禁:
python3 -m pip install -e .
python3 -m unittest discover -s tests
node --test tests/*.test.cjs tests/*.test.mjs
node examples/xxhash/check-node.cjs
在 Apple Silicon 上,python3 examples/xxhash/build-native-oracle.py /tmp/new-xxhash-proof 会将两个完整的原生对照构建到全新目录中,并与保留的 oracle 进行比较。对象 oracle 可通过 python3 examples/native-objects/build-native-oracle.py /tmp/new-object-proof 复现,在 Apple Silicon 上使用固定的已知源码 LZ4 测试样本。原生加载仅限于这些受控的测试样本生成器;产品提取解析字节,执行则使用 Wasm。
Python 解析器和 Capstone 反汇编构建出一个可检查的依赖胶囊。JavaScript 运行时通过 Unicorn.js 和 Unicorn(成熟的 CPU 模拟项目)执行这些字节。在浏览器中执行原生指令正是它们的能力所在。
Capsulith 结合了提取、声明的契约、可访问的执行证据以及可独立复用的导出,现在还包含显式的已初始化对象所有权和分离式检查点续接。它并不声称发明了模拟、二进制分析或函数隔离。LZ4 和 xxHash 是公开、可验证的样本;它们现有的源码也可以直接编译为 Wasm。胶囊工作流面向的是你希望保留其隔离特性的受支持编译产物。
GPL-2.0-only。参见许可证与组件来源。已发布的模拟器包保持不变,固定的上游源码/构建脚本随附其中;该包的字节级一致本地重建尚未确立。欢迎通过 CONTRIBUTING.md 报告缺陷和贡献受支持 ABI 的改进。