Compass Protocol v0.9.0 发布
NodeStone Compass Protocol(NCP)v0.9.0 已于 2026-11-22 发布。上一版定下了「可变索引直出、不可变版本做种」的分工,这一版把不可变那一半的打包颗粒度彻底简化,并补上了过去只能靠实现者自行猜测的细节。
一个游戏版本 = 一个种子
v0.8.0 把不可变资源拆成两类种子:版本核心种子(minecraft-core-<ver>)与大版本 Assets 种子(minecraft-assets-<major>)。实际运行下来,后者是复杂度来源——每发布一个小版本(1.21.3 → 1.21.4),大版本 Assets 种子就可能因为新增对象而重新打包,InfoHash 随之变化,历史种子、客户端缓存与做种任务都要跟着收拾。
v0.9.0 改成按单个游戏版本打包:
- 每个已发布版本对应一个
minecraft-version-<ver>种子,包含该版本的<version>.json、client.jar、该版本依赖的全部libraries、对应的<asset_index>.json,以及该索引关联的全部assets/objects。 .torrent文件本身约 300 KB,拉取成本可以忽略;不同版本种子之间包含相同的公共libraries/assets文件也没关系——BT v2 中相同文件的pieces root完全一致,公共文件的 NSFID 指向任意一个已展开的版本种子都能正常下载。- 种子一旦发布,InfoHash 永久固定,不需要在发新版本时重打历史种子。
连带的效果是清单更小:nsci.raw_kv 现在只收录 version_manifest_v2.json 与各版本 <version>.json。<asset_index>.json 不再单独列出,它作为版本种子的子文件,在展开 file tree 时自动写入客户端缓存——启动器请求 <version>.json 的那一刻,client.jar、libraries、asset index 与全部 assets 的映射一次性补齐。
路径必须能被无损还原
种子里的路径既要在磁盘上可读,又要在拼回 URL 时不出现二次转义。v0.9.0 把规则写死:
info["file tree"]第一级固定为官方源规范化后的主机名(<host>[:<port>],小写、不含默认端口)。- 后续各级目录与文件名必须是百分号解码后的原始 UTF-8(URL 里的
%20在种子里存成空格)。 - 客户端还原
orig_url时,对除主机名外的每级路径段执行 RFC 3986 编码(quote(seg, safe="-._~"),十六进制大写)。 info["name"]必须是纯 ASCII 且不含/(如minecraft-version-1.21.4),否则本地 WebSeed 代理在剥离/<info.name>/前缀时会产生切分歧义。
另外,ns-schemes 从种子顶层移进 info 字典:这样通过磁力链接 BEP-9 ut_metadata 拉取元数据的客户端也不会丢字段,且该字段受 InfoHash v2 完整性校验保护。顶层同名副本仅作兼容,标准 BEP-19 url-list 依然禁用。
WebSeed 桥接:307 + torrenthash 前缀
无 Peer 时的兜底代理改成了 307 Temporary Redirect,路径固定为:
http://127.0.0.1:<port>/webseed/<torrenthash>/<info.name>/<rel_path>
末尾斜杠必须保留(否则引擎会丢掉相对路径)。代理剥掉 /webseed/<torrenthash>/<info.name>/ 前缀、按 torrenthash 查到该种子的 ns-schemes,对剩余路径段解码后重新编码,再以 307 跳到官方源,Range 头与方法原样保留。
同时明确了一条发布侧要求:标准种子必须提供 delivery.url。HTTP WebSeed 无法响应 BEP-52 的 hash request,客户端如果只拿到磁力链接,就可能在无 Peer 环境下拿不到 piece layers、无法校验大于 16 KiB 的文件。磁力链接保留为可选能力。
本地缓存落到 SQLite
.nodestone/cache/nsci.db 成为推荐的缓存实现:WAL 模式 + busy_timeout = 5000,三张表 meta_state、torrents_state、nsci_cache。两个关键约束:
- Upsert 只更新
torrenthash(ON CONFLICT(nsfid) DO UPDATE SET torrenthash = excluded.torrenthash),保留已有的rel_path与orig_url,避免新清单覆盖掉可用的本地定位信息。 - 展开
file tree与写入is_expanded = 1必须在同一事务内完成,避免中断后留下「以为已展开」的半成品状态。
raw_file 的语义也收紧了:内嵌载荷每次请求现场解码、校验整体 SHA-256 后直接交付,不再在 .nodestone/ 下按 Hash 留存历史副本。
兼容性
清单路径升到 <源>/v09/<namespace>/latest.json,filetype 固定为 "nscl/v0.9"。v0.9.0 不保证与 v0.8.0 逐字段兼容(种子命名、nsci.raw_kv 收录范围、WebSeed 代理路径都有变化),请以 协议规范 的字段表与客户端推荐实现、服务端推荐实现 为准。变更明细见版本历史。
