# SwarmCrate 产品方向与开发路线

确定日期：2026-10-27。本文由 AI 辅助制定，依据现有工程能力和公开工具/规范作产品判断，不把推断当作真实用户调研或采用量证明。实现保持 MoonBit 为主，围绕离线 BitTorrent 元数据与完整性核验推进。

| 优先级与方向 | 用户与实用价值 | 可持续扩展的交付物 | 完成标准 |
| --- | --- | --- | --- |
| P0：开源发布与数据集交付 | 发布维护者、数据集制作者在处理大目录前看清布局，再生成可复现的分发元数据 | 发布前规划、交付清单、种子/磁力链接与报告的组合导出、CI 发布示例 | 规划不读载荷；固定输入/参数的内容标识稳定；输出可被独立实现读取；不覆盖已有文件 |
| P1：离线镜像与资料库巡检 | 镜像维护者定位缺失、损坏与不可读范围，保存能对应到正确元数据的检查证据 | 带内容标识和范围的核验凭据、按文件汇总、待处理范围清单、批量巡检；有明确失效规则后再评估增量缓存 | 局部检查不能标成全量成功；报告能定位原始 infohash、文件与偏移；缓存不得仅凭时间戳冒充重新哈希通过 |
| P2：MoonBit 可复用完整性 SDK | 工具作者复用规划/核验/报告，而不依赖当前 Node CLI | 稳定的有类型 API、进度/取消语义、存储适配契约、可运行消费方与浏览器适配验证 | 根库保持 Wasm GC/JS；I/O 与核心分离；新接口兼容性有说明；取消、异常和资源上限可测试 |

三条方向共享同一核心与数据模型。近期先完成 P0 的一个完整链路，再推进 P1；P2 随公共 API 的实际需求逐步补强。暂不扩展下载器、做种、Tracker 服务或与上述目标无关的 UI。

## 为什么这样选

- [libtorrent 的创建文档](https://www.libtorrent.org/reference-Create_Torrents.html)把文件选择、属性设置、读取/哈希和编码分成不同阶段，指出读取所有载荷通常代价最高。这支持先提供无需载荷读取的发布前规划；它不证明某个用户群已经采用本项目。
- [BagIt（RFC 8493）](https://www.rfc-editor.org/rfc/rfc8493.html)体现了交付载荷、清单与校验信息之间的关系，可为后续交付凭据提供设计参考。当前 SwarmCrate 未实现 BagIt，不宣称兼容该格式。
- 当前项目已有真实文件创建、两套哈希、局部核验、错误定位及双后端 API，适合在同一离线流程上提高完整性和可集成性。先获得可复现的使用证据，再根据实际反馈决定更大范围扩展。

## 已落地与下一步

| 顺序 | 交付项 | 状态与验证方式 |
| --- | --- | --- |
| 1 | 发布前只读规划 `plan_torrent` / CLI `plan` | 已完成 0.7.0：真实字节、虚拟补零、两套分片计数、v1 哈希字节、v2 层字节上限；通过禁止打开载荷文件的真实测试，与实际种子独立解码结果对照 |
| 2 | 可保存的核验凭据与元数据身份绑定 | 已完成 0.8.0：`verify_with_receipt` / `--receipt` 绑定完整种子 SHA-256、infohash、真实文件映射、实际范围和结果；不可变快照，原 JSON/退出码兼容，普通未签名记录；27 个新增磁盘场景独立对照与保护验证 |
| 3 | 按文件的损坏/缺失/不可读汇总与待处理范围 | 已完成 0.9.0：独立诊断 JSON、凭据附加字段与 HTML 分组；物理区间并集和去重字节数、缺失/额外尾部、邻居与空文件问题；截断时明确清单不完整，不自动修复；32 个新增真实场景及位图/大偏移对照 |
| 4 | 核验 SDK 的进度与协作取消契约 | 已完成 0.10.0：`verify_with_control`、标量检查点、取消及观察者错误传递，保留普通读错和旧接口语义；双后端与真实文件消费方验证全部阶段，包括最终计数完成后取消仍不返回/保存凭据；同步检查点，不声称抢占式或浏览器事件适配 |
| 5 | 创建 SDK 的进度与协作取消 | 已完成 0.11.0：独立创建检查点、输入快照、编码后仍可取消；受控命令增加最终写入门槛和来源复查，暂存/fsync/原子不覆盖发布；78 个真实场景验证取消、错误、竞争和进程中断下的目标完整性；旧 API 保持兼容 |
| 6 | 终审前最低运行环境与交付复现 | 已落实 0.11.1：真实 Node 22.16.0 复现并修复 Windows 身份字段误判、关闭故障错误逃逸和 SDK 超限晚拒绝；最低环境完整链路及四组合公开 CI，发布后按流程验证全新精确版本消费；见 [运行环境与故障证据](runtime-compatibility.md) |
| 7 | 离线批量巡检、失败隔离与身份汇总 | 已实现 0.12.0：MoonBit 有界清单/顺序 SDK/磁盘命令，按任务捕获错误并继续，区分全量/局部/失败，绑定原始清单、种子与实际范围及同次凭据摘要；输入根保护、来源复查和原子汇总保存，见 [批量巡检](batch-audit.md) |
| 8 | 全批次进度与协作取消 | 已实现 0.13.0：附加受控 SDK/命令、累计真实读取及已接受行计数，全局取消不被任务隔离吞掉；最后计数/序列化/写入门槛仍可取消，无候选汇总发布；来源复查与 48 个真实子进程故障场景，见 [批量控制](batch-control.md) |
| 9 | 强制终止残留的识别与安全清理 | 已实现 0.14.0：新暂存绑定操作/本机记录和对象身份，只读列举后指定单个确认孤立任务；独占清理声明、二次快照核对和固定成员非递归删除，保留旧版/活动/未知内容与正式输出；见[暂存清理](staging-cleanup.md) |
| 10 | 终审前维护与交付复现 | 下一项：以实际复现缺陷、兼容性或证据缺口为准，保持离线创建、单项/批量核验与发布一致；异步/浏览器/信号适配仍需具体消费方设计，不作为已交付能力 |

异步存储、浏览器 Worker 适配、信号适配与断点恢复仍待具体消费方设计和验证，不作为当前已交付能力。核验与创建分别见 [SDK 核验控制](sdk-control.md) 和 [创建控制与发布](creation-control.md)。

规划中的 `storage_bytes` 表示逻辑布局，不等于磁盘占用或网络流量；哈希层大小在去重前只是上限，完整 metainfo 的字节数/节点上限仍由实际创建校验。规划不生成内容哈希，也不是载荷核验。

## 每轮推进规则

先读本路线图、验收自查和发布流程，核对当前代码与未完成事项。一次完成一个可验证的用户链路，优先修复阻碍其使用的缺陷。真实开发、测试、文档、公开 CI、精确版本 Mooncakes 安装验证和版本标签形成闭环；不为了行数、测试数或提交数制造工作。

2026-10-31 前优先保证已申报离线功能完整、稳定、可复现；之后仍按本路线图迭代。里程碑完成后更新状态与下一项。新增网络服务、改动已申报方向或引入重大兼容破坏，需先给出具体设计供用户决定。真实用户反馈缺失时如实记录，不虚构采用量、性能或验收结论。