tei/pbf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7c64299c2237800cec06034b5b6ddfe8436bb8ce
pbf/docs/PBF_Provider_ZIP在NavSea中的使用说明_v1.md
OpenAI Codex 3d9ee10437 docs: explain NavSea provider zip handoff
2026-10-06 10:40:00 +08:00

15 KiB
Raw Blame History

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 文件。

Reference in New Issue View Git Blame Copy Permalink