45 lines
3.3 KiB
Markdown
45 lines
3.3 KiB
Markdown
# Phase 2：独立仓库与 CLI 边界设计
|
||
|
||
## Architecture
|
||
|
||
P1 已将实现收敛到 `packages/road-compiler/`。P2 把该目录以保留历史的方式导出为独立 package 仓库，保留两个明确方向的边界：
|
||
|
||
```
|
||
宿主 area config
|
||
-> scripts/lib/area-config.js
|
||
-> RoadCompilerInput JSON（宿主 staging）
|
||
-> @osm-asset/road-compiler CLI（子进程）
|
||
-> native-road/ + NATIVE_ROAD_COMPILE_DONE
|
||
-> build-area.js / Blender / preview
|
||
```
|
||
|
||
编译器不知道区域配置、宿主仓库、Blender 或宿主输出目录约定以外的输入路径。宿主不知道 compiler 内部源文件；它只拥有输入 JSON、CLI 的完成标记和写出的契约文件。
|
||
|
||
## CLI Contract
|
||
|
||
- CLI 接收一个 JSON 文件中的 `RoadCompilerInput`，而不是宿主的 area config。
|
||
- `comparisonDir` 继续作为可选输入，以维持现有 `comparison.json` 产物和 P0 baseline 的可比性。
|
||
- 成功只打印一次 `NATIVE_ROAD_COMPILE_DONE <JSON>`。payload 必须至少含 `areaId`、`output`、`roads`、`endpoints` 和 `diagnostics`。
|
||
- `build-area.js` 保持同步批处理模式，子进程日志对用户可见；为了验证标记，输出同时被捕获或 tee。它对启动失败、非零状态、signal、缺失/重复/非法标记和 payload 与当前输入不一致都报错。
|
||
- 产物先由 compiler 的现有 staging/atomic promotion 逻辑写入目标 `native-road/`；宿主不接管这一写入过程。
|
||
|
||
## Repository Contents
|
||
|
||
独立仓库拥有：compiler source、public API、CLI、check、workbench、fixture、两个 parity baseline、契约文档、README、package lockfile 和 workbench 的 `ol` 依赖。测试和 workbench 均必须在没有宿主 checkout 的环境运行。
|
||
|
||
宿主保留：area-config 读取/归一化、`RoadCompilerInput` 映射、pipeline 阶段编排、Blender/preview、区域配置、运行产物和一份升级回归 baseline。宿主 spec 仅保留指针，契约正文随 compiler 仓库维护。
|
||
|
||
## History Extraction
|
||
|
||
导出只允许 `git subtree split` 或 `git filter-repo`。必须在独立仓库验证 `git log --follow src/compile/native-road.js`；验证的是迁移前的逻辑历史，而非仅 P1 的边界移动提交。导出和验证先在临时分支/clone 完成，外部远端创建和 push 必须使用用户给出的地址和授权范围。
|
||
|
||
## Dependency and Rollout
|
||
|
||
初始发布源定为私有 `https://git.app.que01.top/que01/road-compiler.git`。仓库以带注释 tag `v0.1.0` 首发，宿主以该精确 tag 作为依赖并写入 lockfile。开发临时形态可以指向独立 checkout 的本地 `file:` 依赖；它不能成为验收时的唯一消费方式。两个区域 parity 通过后删除 `packages/road-compiler/`；回滚由 revert 宿主消费改造实现，不能让 production host 继续直接 import 该目录。
|
||
|
||
## Compatibility and Risks
|
||
|
||
这是位置和调用方式迁移，不改变 compiler 行为。两个区域的 strict content/order hash 是主要 oracle；信号文档的确定性生成仍应通过 parity 覆盖。P2 不处理 `check:area` 的历史 stage-manifest freshness warning，也不把 Blender/Metal 沙箱问题归因为道路产物。
|
||
|
||
若外部 CLI 无法及时使用，回滚宿主消费 commit 即可；外部仓库历史和 tag 不需要删除。对于完整 Blender 构建，macOS Metal 初始化必须在提权的宿主环境运行。
|