tei/pbf

Fork 0

Files

OpenAI Codex f3da1a6a32 docs: define PBF provider pipeline v1

2026-10-06 09:16:08 +08:00

11 KiB

Raw Blame History

PBF Pipeline 正式流程 v1

日期：2026-10-06
状态：实现基线
适用仓库：/root/sourceserver/pbf

1. 总体边界

PBF 项目负责从任意 Provider 的 Style、PBF/MVT、Sprite、Glyph 和 Provider 语义资料生产符合公开 NavSea Provider Contract 的 NavSea Provider Package。

PBF 项目不生成 ProviderExecutionPlan。ProviderExecutionPlan 只属于 NavSea。

NavSea 的职责是公开 Contract、验证 Provider Package、生成 Chart Provider Profile、ProviderCompiler 编译、ChartRuntime 安装和 Runtime 消费。

第三方可以完全绕过官方 PBF Pipeline，只要自行生产的数据满足公开 NavSea Provider Contract。

2. Pipeline v1

PBF-01 Provider Source Intake
        ↓
PBF-02 Style Visual Object Extract
        ↓
PBF-03 Actual Visual Object Instantiate
        ↓
PBF-04 Provider → NavSea Standard Mapping
        ↓
PBF-05 Provider Policy Compile
        ↓
PBF-06 Provider Package Validate
        ↓
PBF-07 NavSea Provider Package Export

Pipeline 正式终点是 NavSea Provider Package，不是 ProviderExecutionPlan。

3. PBF-01 Provider Source Intake

目标：把不同 Provider 的原始输入统一整理成可重复、可校验的 Source Intake。

输入至少支持：

provider identity
dataset identity
Style JSON / URL
PBF / MVT / MBTiles / XYZ URL
Sprite JSON / PNG
Glyph URL 或资源
Provider semantic metadata
sample tiles
bounds
minZoom / maxZoom

建议输出：

work/<provider-id>/
  intake/
    source-manifest.json
    style.snapshot.json
    sprite/
    semantic-source/
    samples/
    intake-report.json

source-manifest.json 至少记录 providerId、datasetId、providerVersion、style、tileSource、sprite、glyphs、bounds、zoom、sampleTiles、semanticSources、sourceFingerprint。

Gate：

Provider identity 已确定
Dataset identity 已确定
Style 可读取
PBF 来源可定位
Sprite/Glyph 状态明确
输入 Hash/Fingerprint 已记录
采样范围已确定

4. PBF-02 Style Visual Object Extract

目标：只从 Style + Sprite 中提取视觉事实，不在本阶段直接决定 NavSea Standard Layer。

当前工具：

tools/style-visual-object/style_vo_tool.py

输入：

style.snapshot.json
Sprite

输出：

anonymous-catalog.json
_sprite/sprite.json
_sprite/sprite.png

核心原则：产物为 Anonymous Visual Object。source-layer、Provider 字段名、Provider 对象类名称只作为 provenance/audit evidence，不得直接作为 NavSea Layer 映射依据。

Gate：

Anonymous Visual Object 可重复稳定生成
同输入重复执行结果一致
视觉组件与 Style Layer 引用完整
不包含 Provider-specific NavSea Layer 硬编码

5. PBF-03 Actual Visual Object Instantiate

目标：把 Style 定义与真实 PBF feature 结合，生成实际出现的视觉对象实例。

当前工具：

tools/visual-object-instantiation/instantiate_pbf_visual_objects.py

正式 Pipeline 必须去除 CM95-specific 主逻辑硬编码。Provider-specific 行为只能通过 manifest、adapter config、declarative metadata 或 policy input 表达。

输入：

Anonymous Visual Object Catalog
Style
Sprite
真实 PBF/MVT
sample tiles
Provider semantic metadata（辅助证据）

建议输出：

actual-visual-object-catalog.json
visual-object-occurrences.json
instantiation-report.json

每个 occurrence 至少可追踪 feature identity、tile、source、source-layer、matched style layers、render components、field evidence、geometry type、zoom、provenance。

Gate：

真实 PBF feature 与 Style 命中关系可对应
同一原始 feature 的多个 render component 可归并
不按屏幕距离拼接对象
occurrence 可回溯原始 feature

6. PBF-04 Provider → NavSea Standard Mapping

目标：把 Provider Actual Visual Object / Composite Visual Evidence 映射到 NavSea Frozen Standard Catalog / Standard Layer。

输入：

Provider Actual Visual Object Catalog
NavSea Frozen Standard Catalog
Visual Matcher 建议
Provider 官方语义资料
人工审核结果

NavSea Frozen Standard Catalog：

tools/style-visual-object/output/navsea-standard/standard-catalog.json

默认只读，不重新生成或修改。

最终映射状态：

VISUAL_OBJECT_MATCH
LAYER_ONLY
COMPONENT_ONLY
AMBIGUOUS
UNKNOWN

VISUAL_OBJECT_MATCH：可确定到 Standard Visual Object + Standard Layer。

LAYER_ONLY：可确定 Standard Layer，但不要求存在 1:1 Standard Visual Object；这是正常结果。

COMPONENT_ONLY：只表示完整视觉对象组成部分，如 topmark、buoy_body、beacon_body、light、auxiliary_mark、fill_pattern、line_pattern、text、other；COMPONENT 自身不决定最终 Standard Layer。

AMBIGUOUS：存在多个合理候选，禁止 Runtime 任意选择。

UNKNOWN：无法可靠确定 Standard Layer。

建议输出：

mapping/
  provider-layer-assignment.json
  provider-layer-assignment.csv
  provider-layer-assignment.html
  mapping-validation-report.json

Gate：

所有 occurrence 有明确状态
无未审核项
AMBIGUOUS/UNKNOWN 写入 limitations
人工决定优先于自动 matcher
matcher 不覆盖人工结论
Provider 语义建议与人工结论冲突只产生 WARN

7. PBF-05 Provider Policy Compile

这是当前 Pipeline 缺失的关键桥梁。

输入：

Visual Object / Layer Assignment
+ Provider Source Facts
+ Provider Semantic Metadata
+ Capabilities
+ Human Review

输出：

Provider Policy

NavSea Provider、CM95 Provider 和未来第三方 Provider 必须使用同一 Policy Schema。

禁止：

NavSea → 特殊 Runtime 直通
CM95 → Provider Policy

统一为：

NavSea Provider → NavSea Provider Policy → NavSea Standard Layer
CM95 Provider  → CM95 Provider Policy  → NavSea Standard Layer
Provider B     → Provider B Policy     → NavSea Standard Layer

建议新增：

tools/provider-policy-compiler/
  README.md
  compile_provider_policy.py
  validate_provider_policy.py
  schema/
  tests/

Compiler 输入：

source-manifest.json
actual-visual-object-catalog.json
provider-layer-assignment.json
Provider semantic metadata
capability declaration
manual review result
NavSea Standard Catalog identity

Provider Policy 至少覆盖：

schemaVersion
provider
dataset
standardCatalog
resources
mapping
display
pickup
planning
danger
capabilities
unresolved
limitations
provenance
fingerprints

Provider Policy 不包含 ProviderExecutionPlan、Runtime cache、最终 query buckets、Runtime layer handles 或 React/MapLibre Runtime 对象。

Gate：

NavSea 和 CM95 Policy 通过同一 validator
Schema 无 provider-specific 分叉
Python 主逻辑不得写 provider == cm95
Mapping 可追溯到 PBF-04
unresolved/limitations 不得静默丢失

8. PBF-06 Provider Package Validate

目标：在离开 PBF 项目前验证 Provider Package 是否符合公开 NavSea Provider Contract。

验证至少包括：

providerId / datasetId / version
Style / PBF / Sprite / Glyph / bounds / zoom
Standard Layer mapping
Standard Visual Object reference
COMPONENT/LAYER_ONLY/UNKNOWN/AMBIGUOUS 约束
Display / Pickup / Planning / Danger
capabilities
schema version
file/resource hash
package fingerprint
standard catalog fingerprint
source fingerprint
unresolved / unsupported / partial capability / missing resource

输出：

validation/
  provider-package-validation.json
  provider-package-validation.md

结果只能是：

PASS
PASS_WITH_WARNINGS
FAIL

FAIL 时禁止进入 PBF-07。

9. PBF-07 NavSea Provider Package Export

目标：生成可直接交给 NavSea 或第三方 Validator 的正式 Provider Package。

建议：

dist/
  <provider-id>/
    <dataset-id>/
      <version>/
        provider-package.json
        provider-policy.json
        resources/
          style.json
          sprite.json
          sprite.png
        mapping/
          layer-assignment.json
        reports/
          validation.json
          validation.md
        MANIFEST.json

URL 型资源允许只保存 URL、hash、expected content identity、availability/fallback policy，不要求将所有 PBF 数据打入包。

MANIFEST 至少包含：

package schema version
provider identity
dataset identity
package version
createdAt
source fingerprint
style fingerprint
sprite fingerprint
standard catalog fingerprint
policy fingerprint
mapping fingerprint
validation result
known limitations

只有 PASS 或明确允许发布的 PASS_WITH_WARNINGS 才能正式 export。

10. NavSea Provider Package Contract

公开 Contract 至少覆盖：

provider identity
dataset identity
package/version identity
Style resource
PBF resource
Sprite resource
Glyph resource
NavSea Standard Layer mapping
Provider Policy
Display
Pickup
Planning
Danger
capabilities
validation requirements
hash / version / fingerprint
unresolved
limitations
provenance

公开 Contract 不要求第三方使用官方 PBF 工具。

11. NavSea 接收侧

NavSea Provider Package
        ↓
NavSea Contract Validate
        ↓
Chart Profile Tools
        ↓
Chart Provider Profile
        ↓
ProviderCompiler
        ↓
ProviderExecutionPlan
        ↓
ChartRuntime
        ↓
NavSea Runtime

NavSea 不再负责 CM95/S-52 语义研究、Visual Object 人工分类、Provider-specific 图标研究或 Provider Policy 推理生成。

12. 当前工具迁移关系

tools/style-visual-object/style_vo_tool.py → PBF-02。

tools/visual-object-instantiation/instantiate_pbf_visual_objects.py → PBF-03，但必须去 CM95 硬编码。

tools/visual-object-matcher/ 和 visual_anchor_matcher.py → PBF-04 辅助建议工具，不是最终权威。

tools/style-visual-object/reviewer/ → PBF-04 人工确认。

apply_reviewed_layer_assignment.py → PBF-04 输出编译。

validate_cm95_classification.py 暂保留为 CM95 基线校验；后续增加 Provider-neutral validator。

13. 实施顺序

第一优先级：冻结 Provider Policy Schema v1 和 Provider Package Schema v1。

第二优先级：实现 tools/provider-policy-compiler/，让 NavSea 与 CM95 生成完全同 Schema 的 Provider Policy。

第三优先级：实现 Provider Package Validator / Export。

第四优先级：调整 NavSea help/chart-profile-tools/，收敛为读取公开 Provider Package → Validate → Profile → ProviderCompiler。

14. 核心原则

PBF = 数据生产者
NavSea = Contract 定义者 + Validator + Compiler + Runtime

以及：

PBF Pipeline 的终点是 Provider Package。
ProviderExecutionPlan 永远属于 NavSea。

11 KiB Raw Blame History Unescape Escape

PBF Pipeline 正式流程 v1

1. 总体边界

2. Pipeline v1

3. PBF-01 Provider Source Intake

4. PBF-02 Style Visual Object Extract

5. PBF-03 Actual Visual Object Instantiate

6. PBF-04 Provider → NavSea Standard Mapping

7. PBF-05 Provider Policy Compile

8. PBF-06 Provider Package Validate

9. PBF-07 NavSea Provider Package Export

10. NavSea Provider Package Contract

11. NavSea 接收侧

12. 当前工具迁移关系

13. 实施顺序

14. 核心原则

11 KiB

Raw Blame History