docs: explain NavSea provider zip handoff

This commit is contained in:
OpenAI Codex
2026-10-06 10:40:00 +08:00
parent 405f6e01d5
commit 3d9ee10437
2 changed files with 647 additions and 0 deletions

View File

@@ -2392,3 +2392,11 @@
- 两个 ZIP 均经外部 `unzip -t` 验证 9/9 文件 OK。
- 自动测试从 6 项增加到 8 项,8/8 PASS;新增覆盖严格白名单与缺文件拒绝打包。
- 详细结果:`docs/报告/PBF_Provider_Pipeline_v1_Codex完成报告_v3.md`。
## 2026-10-06 PBF Provider ZIP → NavSea 使用说明
- 新增文档 `docs/PBF_Provider_ZIP在NavSea中的使用说明_v1.md`。
- 文档以当前 NavSea 实际工作树 `D:\React\NavSea-PBF-Multisource` 和当前 `help/chart-profile-tools` 能力为基线编写。
- 已明确当前 Chart Profile Tools 尚无 ZIP Import 入口,第一轮应增加统一 ProviderPackageImporter / import-package 薄层,再进入现有 Profile Validator / ProviderCompiler。
- 文档包含两个当前 ZIP 的路径与 SHA-256、9 文件固定结构、安全校验、Contract 校验、Package→Profile 映射、NavSea/CM95 双 Provider 试跑顺序、第一轮验收清单及禁止事项。
- 第一轮明确不覆盖正式 Profile,不同时实施 UI Provider 切换或 Runtime 多 Provider 原子切换;先证明 ZIP → Profile → ProviderCompiler → PLAN_READY。

View File

@@ -0,0 +1,639 @@
# PBF Provider ZIP 在 NavSea 中的使用说明 v1
日期:2026-10-06
适用范围:PBF Pipeline v1.1 / PBF-08 NavSea Delivery ZIP
目标:指导 NavSea 使用 `.navsea-provider.zip` 完成 Provider Package 导入、验证、Profile 生成和 ProviderCompiler 试跑。
## 1. 总原则
PBF 交给 NavSea 的正式交付单位固定为:
<provider>-<dataset>-<version>.navsea-provider.zip
NavSea 不再从 PBF 项目手工复制零散 JSON、Style、Sprite 或 Mapping 文件。
正式链路:
ZIP
→ Package Import / Validate
→ Chart Provider Profile
→ ProviderCompiler
→ ProviderExecutionPlan
→ ChartRuntime
PBF 不生成 `ProviderExecutionPlan`。
## 2. 当前两份可直接测试的 ZIP
### 2.1 NavSea Provider
X220:
/root/sourceserver/pbf-provider-pipeline-v1/dist/navsea/delivery-full-semantic-extentfix/
navsea-delivery-full-semantic-extentfix-1.0.0.navsea-provider.zip
SHA-256:
54aff8d8b882211ced6e77b3a93e8e793c780b44a1faa982ed8fc64693124fd5
### 2.2 CM95 Provider
X220:
/root/sourceserver/pbf-provider-pipeline-v1/dist/cm95/s52-full/
cm95-s52-full-1.0.0.navsea-provider.zip
SHA-256:
603cc004833bcff5571a32843d8ceedc7858b2fc4b28c41056db6807c7d511ee
注意:`dist/` 是 PBF 可重建运行产物,不进入 Git。交付时复制 ZIP 本身。
## 3. NavSea 收到 ZIP 后先校验整个 ZIP
无论通过共享目录、SCP、U 盘或其他方式复制,NavSea 机器收到 ZIP 后首先计算 SHA-256。
Windows PowerShell:
Get-FileHash .\navsea-delivery-full-semantic-extentfix-1.0.0.navsea-provider.zip -Algorithm SHA256
或:
Get-FileHash .\cm95-s52-full-1.0.0.navsea-provider.zip -Algorithm SHA256
必须和第 2 节记录一致。不一致时停止导入。
## 4. ZIP 固定结构
每个 ZIP 必须且只能包含一个顶层目录,目录中固定 9 个文件:
<provider>-<dataset>-<version>/
provider-package.json
provider-policy.json
mapping-layer-assignment.json
resources-style.json
resources-sprite.json
resources-sprite.png
validation.json
validation.md
MANIFEST.json
NavSea 导入器不得接受额外文件、多个顶层目录或缺文件的 ZIP。
## 5. 9 个文件分别怎么用
### provider-package.json
这是 NavSea 的正式入口文件。
Schema:
navsea-provider-package/v1
主要包含 Provider/Dataset/Package identity、资源声明、Standard Layer Mapping、Provider Policy、Display/Pickup/Planning/Danger、capabilities、fingerprints、unresolved、limitations、provenance 和 validation。
NavSea 不应绕过它直接把其他文件作为入口。
### provider-policy.json
统一 Provider Policy。
Schema:
navsea-provider-policy/v1
NavSea Provider、CM95 Provider 和未来 Provider 都使用相同 Schema。
### mapping-layer-assignment.json
Provider Actual Visual Object → NavSea Standard Layer 的正式 Mapping。
允许状态:
VISUAL_OBJECT_MATCH
LAYER_ONLY
COMPONENT_ONLY
AMBIGUOUS
UNKNOWN
NavSea 不得把 `AMBIGUOUS` 或 `UNKNOWN` 自动猜成某个 Standard Layer。
### resources-style.json
PBF 生产当前 Package 时使用的 Style snapshot。
NavSea 做 Package/Profile 校验时使用 ZIP 内 snapshot,不要重新从网络下载“看起来相同”的 Style 静默替换。
### resources-sprite.json / resources-sprite.png
当前 Package 对应的 Sprite snapshot,是视觉资源证据和可复现输入。
### validation.json
机器可读 PBF 出厂验证结果。
只允许:
PASS
PASS_WITH_WARNINGS
FAIL
NavSea 必须拒绝 `FAIL`。
`PASS_WITH_WARNINGS` 可以继续,但 warnings 必须保留进 NavSea diagnostics,不得静默丢失。
### validation.md
给人看的验证摘要,不是程序权威输入。
### MANIFEST.json
记录 Provider/Dataset/Package identity、version、fingerprints、validation result、known limitations,以及当前 v1 中部分核心文件 SHA-256。
注意:当前 `MANIFEST.json.files` 不是 9 个 ZIP 文件全部逐文件 SHA-256。NavSea 不应误认为它已经覆盖全部 9 个文件。
ZIP 整体完整性首先使用 PBF-08 输出的 ZIP SHA-256;包内部再结合 MANIFEST、Package fingerprints、Style/Sprite hash 等继续校验。
## 6. ZIP 不包含真实 PBF 数据集本体
真实 PBF 来源在:
provider-package.json
resources
pbfTemplate
pbfSamples
其中保存 XYZ URL template、样本 URL/hash/bytes 等信息。
ZIP 也不包含完整 Glyph 数据;Glyph 使用 Package 中声明的 URI template。
因此 ZIP 是:
Provider 定义
+ Policy
+ Mapping
+ Style/Sprite snapshot
+ Validation
不是离线海图数据包。
## 7. 当前 NavSea 的真实状态
当前 NavSea 工作树:
D:\React\NavSea-PBF-Multisource
branch: feature/pbf-multisource
已有:
help/chart-profile-tools/
当前 CLI:
inspect
generate
validate
diff
audit-render
当前还没有 Provider Package ZIP 导入命令。
现有 `generate` 仍主要从 `source.json + semantic-policy.json` 生成 Schema 2.1.0 Chart Provider Profile。
因此第一轮 NavSea 测试不能假装 ZIP 已能直接喂给现有 `generate`。
## 8. NavSea 下一步最小改动
建议在:
help/chart-profile-tools/navsea_chart_profile_tools/
增加一个 Provider Package 导入层,例如:
provider_package.py
并在 CLI 增加一个命令,例如:
import-package
建议调用形式:
python -m navsea_chart_profile_tools import-package ^
--package <xxx.navsea-provider.zip> ^
--output output/package-import/<provider>.candidate.navsea-chart.json ^
--sidecar-dir output/package-import
具体命令名可以调整,但职责不要改变。
## 9. Importer 严格执行顺序
### Step 1:ZIP 安全检查
检查:
- 只有一个顶层目录;
- 路径不得包含 `..`;
- 不允许绝对路径;
- 不允许释放到目标目录之外;
- 必须恰好是规定的 9 个文件;
- 缺文件立即 FAIL;
- 多文件立即 FAIL。
不要直接对不可信 ZIP 做无检查的 extract-all。
### Step 2:validation.json
只接受:
PASS
PASS_WITH_WARNINGS
`FAIL` 立即停止。
### Step 3:MANIFEST.json
检查 manifest schema、provider identity、dataset identity、package identity/version、validationResult、knownLimitations 和已声明 hash。
### Step 4:provider-package.json
要求:
schemaVersion == navsea-provider-package/v1
并检查必填域。
### Step 5:provider-policy.json
要求:
schemaVersion == navsea-provider-policy/v1
### Step 6:身份一致性
以下三组必须分别一致:
provider-package.json.provider
provider-policy.json.provider
MANIFEST.json.provider
provider-package.json.dataset
provider-policy.json.dataset
MANIFEST.json.dataset
provider-package.json.package
provider-policy.json.package
MANIFEST.json.package
任意不一致直接 FAIL。
### Step 7:Mapping 一致性
核对:
provider-package.json.standardLayerMapping
与:
mapping-layer-assignment.json
语义一致。
不得重新运行 CM95 matcher 覆盖 Package 中已确认 Mapping。
### Step 8:Style / Sprite
使用 ZIP 内:
resources-style.json
resources-sprite.json
resources-sprite.png
核对 Package 声明的 Style/Sprite hash。
验证阶段不要静默用网络最新版替换 snapshot。
### Step 9:保留诊断
以下内容必须继续保留:
unresolved
limitations
validation.warnings
至少进入 Profile sidecar / diagnostics。
## 10. 建议先形成统一内部对象
不要让 Profile Generator 到处直接读取 ZIP 文件。
建议先形成类似:
ImportedProviderPackage
package
policy
mapping
styleSnapshot
spriteMetadata
spriteImage
manifest
validation
zipSha256
packageRoot
然后:
ZIP
→ ProviderPackageImporter
→ ImportedProviderPackage
→ Chart Profile Adapter
→ Chart Provider Profile
这样 ZIP 安全、Contract 校验和 Profile 生成彼此分离。
## 11. 如何连接现有 Chart Profile Tools
目标不是把 ZIP 再拆回长期保存的:
providers/<provider>/source.json
providers/<provider>/semantic-policy.json
那样会重新产生两个真相来源。
正确方向:
Provider Package
→ 临时/内存 Adapter
→ 现有 profile_generator / profile_validator
→ Schema 2.1.0 Chart Provider Profile
Package 中已经存在的 Provider Policy 和 Mapping 是上游正式结果。
NavSea 不再重新研究:
- CM95 S-52 语义;
- Visual Object 分类;
- 图标属于哪个 Standard Layer;
- UNKNOWN 应该猜成什么;
- Provider-specific 语义规则。
这些属于 PBF Pipeline。
## 12. Package → 当前 NavSea Profile 的主要映射
建议:
provider-package.provider
→ Profile provider identity
provider-package.dataset
→ Profile dataset identity
provider-package.package
→ Profile package provenance
provider-package.resources
→ Profile resources
resources-style.json
→ Profile 生成/验证 Style snapshot
provider-package.standardLayerMapping
→ Profile logical layer / semantic mapping 输入
provider-policy.display
→ Display
provider-policy.pickup
→ Pickup
provider-policy.planning
→ Planning
provider-policy.danger
→ Danger
provider-policy.capabilities
→ capabilities
unresolved / limitations / validation.warnings
→ diagnostics / sidecar
字段形式可以适配,但不得改变上游已经确认的语义结论。
## 13. 第一轮不要覆盖正式 Profile
建议先把 ZIP 放到临时测试位置:
D:\React\NavSea-PBF-Multisource\.codex\tmp\provider-package-test\
这只是第一轮测试位置,不是未来正式目录 Contract。
输出先放:
help\chart-profile-tools\output\package-import\
例如:
navsea.candidate.navsea-chart.json
cm95.candidate.navsea-chart.json
确认转换和 ProviderCompiler 完整通过以前,不要覆盖:
src\assets\pbf\providers\current.navsea-chart.json
src\assets\pbf\providers\cm95-japan.navsea-chart.json
## 14. 第一轮先跑 NavSea ZIP
先用:
navsea-delivery-full-semantic-extentfix-1.0.0.navsea-provider.zip
预期 identity:
providerId = navsea
datasetId = delivery-full-semantic-extentfix
packageId = navsea-delivery-full
version = 1.0.0
validation = PASS_WITH_WARNINGS
当前 warnings:
limitations:present
mapping:unresolved_present
当前 Package capabilities:
vectorTiles = true
sprite = true
glyphs = true
display = true
pickup = false
planning = false
danger = false
第一轮主要验证:
ZIP
→ Package Import
→ Display Profile
→ ProviderCompiler
→ PLAN_READY
不要因为旧 Current Profile 有更多能力,就从旧 Profile 偷偷把 Pickup / Planning / Danger 补回新 Package。
Package 声明什么,就先按什么测试。
## 15. NavSea 跑通后再跑 CM95 ZIP
第二个测试:
cm95-s52-full-1.0.0.navsea-provider.zip
预期:
providerId = cm95
datasetId = s52-full
packageId = cm95-s52-full
version = 1.0.0
validation = PASS_WITH_WARNINGS
当前 capabilities:
vectorTiles = true
sprite = true
glyphs = false
display = true
pickup = false
planning = false
danger = false
CM95 必须走和 NavSea ZIP 完全相同的 Importer / Validator / Adapter。
禁止在正式 Importer 里写:
if provider == cm95:
...
Provider-specific 差异只能来自 Package 自己的数据。
## 16. ProviderCompiler 侧验收
Package 转成 Schema 2.1.0 Chart Provider Profile 后继续走现有链:
ValidatedProviderDefinition
→ ProviderCompiler
→ ProviderExecutionPlan
→ ChartRuntime
第一轮至少检查:
- Profile Schema 2.1.0 validate PASS;
- Style binding 完成;
- ProviderCompiler finalize 成功;
- ExecutionPlan provider/dataset identity 正确;
- logical layer mapping 来自 Package;
- capabilities 与 Package 一致;
- unresolved/limitations 未丢失;
- 最终进入 `PLAN_READY`;
- NavSea 和 CM95 不需要两套 compiler 分支。
## 17. 明确禁止
1. 不要手工拆 ZIP 后重新编辑 JSON。需要修改语义/Mapping 时回 PBF 重新生成 Package。
2. 不要重新做 CM95 语义研究。
3. 不要用旧 `semantic-policy.json` 覆盖 Package Policy。
4. 不要把 UNKNOWN / AMBIGUOUS 强行补全。
5. 不要为了和旧 Profile 一致而偷偷补 Package 没声明的能力。
6. NavSea 不再生成 Provider Policy,只验证和消费。
## 18. 第一轮 NavSea 开发范围
先只完成:
读取 ZIP
→ 安全校验
→ Contract 校验
→ candidate Chart Provider Profile
→ profile_validator PASS
→ ProviderCompiler compile/finalize
→ 输出 ExecutionPlan 摘要
第一轮不要同时做:
- UI Provider 切换;
- Runtime 多 Provider 原子切换;
- 正式 assets 覆盖;
- 自动下载/更新 ZIP;
- Provider Package 缓存管理;
- ZIP 签名体系;
- 后台更新机制。
先证明 Package Contract 能稳定进入 ProviderCompiler。
## 19. 第一轮验收清单
NavSea ZIP:
[ ] ZIP SHA-256 正确
[ ] 只有一个顶层目录
[ ] 9 个文件齐全且无额外文件
[ ] validation != FAIL
[ ] Package Schema v1 通过
[ ] Policy Schema v1 通过
[ ] provider/dataset/package identity 一致
[ ] Style/Sprite hash 校验通过
[ ] Mapping 读取成功
[ ] unresolved/limitations/warnings 保留
[ ] candidate Profile Schema 2.1.0 通过
[ ] ProviderCompiler 成功
[ ] PLAN_READY
CM95 ZIP:
[ ] 使用同一个 Importer
[ ] 不存在 cm95-specific Python/TS 分支
[ ] 9 个文件齐全
[ ] validation != FAIL
[ ] Package/Policy/identity 校验通过
[ ] Mapping 使用 Package 中人工确认结果
[ ] UNKNOWN/AMBIGUOUS 未被猜测覆盖
[ ] candidate Profile Schema 2.1.0 通过
[ ] ProviderCompiler 成功
[ ] PLAN_READY
## 20. 两套 ZIP 都通过以后
再进入:
Provider Package 安装/缓存
→ Runtime Provider 选择
→ 多 Provider 原子切换
→ ChartRuntime 正式切换
→ UI
不要在第一轮 ZIP 接入中一起完成。
## 21. 最终边界
PBF
输入:
Provider Style / PBF / Sprite / Glyph / 语义资料
输出:
*.navsea-provider.zip
==================== Contract Boundary ====================
NavSea
输入:
*.navsea-provider.zip
内部:
ProviderPackageImporter
→ Contract Validator
→ Chart Provider Profile
→ ProviderCompiler
→ ProviderExecutionPlan
→ ChartRuntime
以后用户实际操作只需要确认拿到哪一个 `.navsea-provider.zip`,不再需要记住要复制哪些 JSON、Style、Sprite 或 Mapping 文件。