release: bump version to 0.58.0

Release 0.58.0 includes the Earth high-precision boundary PMTiles/MVT pipeline, standardized Earth boundary source collectors, China POV boundary configuration templates, and removal of the legacy low-precision GeoJSON fallback. It also adds Earth news target-location queueing/archive support, fixes datasource task status visibility, documents the Earth surface depth-spacing rules that prevent far-zoom z-fighting snow/black blocks, and updates bilingual operations/developer docs.

docs/CHANGELOG.md

@@ -8,6 +8,23 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`
 
+## [0.58.0] — 2026-05-15
+
+Released: 2026-05-15
+
+### Highlights
+- 新增 Earth 高精度国界 PMTiles/MVT 前端链路，移除旧低精度 GeoJSON 国界兜底，国界缺失时显式报错。
+- 将 Earth 边界数据拆成 Admin-0、coastline、claim-lines 三个标准源采集器，并把 `earth_boundary_tiles` 收口为下游 PMTiles 构建器。
+- 修复 Earth 远距缩放下海陆基座与高清贴图 z-fighting 导致的雪花/黑块闪烁，并记录地表多层 shell 的深度间距规则。
+
+### Added / Fixed / Improved
+- 新增 `earth_boundary_source` 目标 schema、China POV policy 配置、PMTiles readiness/build 脚本和 collector artifact 登记流程。
+- Earth 新闻巡航改为优先使用可缓存的目标地点解析队列，并补充媒体新闻归档采集器与回归测试。
+- 调整数据源列表任务状态展示，让 Earth 采集器失败/未就绪状态可见，不再表现为“未执行”。
+- 更新中英文采集器、数据源设置、Earth 图层顺序、运维 runbook、FAQ、规则和计划文档。
+
+---
+
 ## [0.57.0] — 2026-05-14
 
 Released: 2026-05-14

docs/plans/earth-high-precision-boundary-tiles-plan.md

@@ -1,132 +1,67 @@
-# Earth High Precision Boundary Tiles Plan
+# Earth High Precision Boundary PMTiles Plan
 
 ## Status
 
-Planning revised after visual review. The previous hand-authored China claim-line / point-buffer approach is rejected and must not be implemented.
+Current implementation:
 
-Implemented separately:
+- Three standard source collectors now handle real source ingestion: `earth_admin0_boundaries`, `earth_coastline`, and `earth_claim_lines`.
+- Each source collector reads endpoint / headers / auth / `target_schema=earth_boundary_source` from Collector Settings, downloads the configured payload, stores the full artifact under `data/earth-boundary-sources/<collector>/<sha256>.*`, and writes a hash / feature-count / artifact-path record to `CollectedData`.
+- The backend `earth_boundary_tiles` item is now a downstream PMTiles builder. It refuses to run until the three source records exist, then skips rebuilds when source / POV policy / build config are unchanged.
+- The frontend boundary layer now requires the production `pmtiles-mvt` provider and no longer falls back to legacy low-precision GeoJSON.
+- Generated loose boundary data is ignored by Git and is not the production deployment format.
+- Production PMTiles builds require external `tippecanoe` and `pmtiles` CLIs; missing tools fail the builder clearly instead of registering fake tile records.
 
-- 地表 hover 三模式已实现。
+Still required before claiming true one-to-one high precision:
 
-Still planned:
-
-- 权威 China POV 数据包。
-- OSM / coastline 高精度离线构建。
-- 版本化静态矢量瓦片输出。
-- 前端 bbox/tile/LRU 高精度加载器。
+- Replace the repository seed GeoJSON with audited high-precision admin boundary, coastline, and claim-line source packages.
+- Run a real geometry preparation step that applies the China POV policy through union / subtract / validity repair before PMTiles creation.
+- Build and publish `earth-boundaries-china-pov-v1.pmtiles` plus its manifest.
 
 ## Summary
 
-Earth 国界线目标从“明显提升”升级为 **最高精度档按真实地图源一比一还原**：
+The Earth boundary layer should use one static PMTiles archive containing MVT tiles instead of thousands of loose GeoJSON files. The artifact is POV-specific: `earth-boundaries-china-pov-v1.pmtiles` has China POV baked in during offline source preparation, and the browser never patches political boundaries at runtime.
 
-- 高缩放时不能使用当前 `countries-admin0.min.geojson` 这种低精度简化线。
-- 最高 tile zoom 必须忠实保留选定权威矢量源的原始折点，不做视觉平滑，不做人工凭感觉补线。
-- 藏南、阿克赛钦等争议陆地直接作为中国国家面的一部分表达；hover 只显示普通 `中国 / CHN`，不显示特殊区域名。
-- 九段线 / 十段线必须来自官方标准地图口径或经地理配准校核后的权威矢量数据；不能手工目测画线，不能把马来西亚、菲律宾等周边陆地或近岸底盘划入中国面。
+Production must serve a single PMTiles artifact through static hosting and HTTP range requests. Missing PMTiles is a hard boundary-layer error, not a silent low-precision fallback.
 
-方案仍采用 **离线构建 + 静态矢量瓦片**。低缩放加载简化 base line；高缩放按当前视野 bbox 加载高精度 boundary tiles。第一版不使用 Redis，依靠 Nginx 静态服务、浏览器 HTTP cache 和前端 LRU。
+## Key Implementation Rules
 
-## Data Source and Policy
+- Source inputs must be auditable. OSM admin boundaries, coastline packages, and claim-line endpoints are configured through Collector Settings using the `earth_boundary_source` target schema; `config/earth-boundary-sources.example.json` remains the versioned example template.
+- China POV geometry is applied before tiling:
+  - Zangnan and Aksai Chin are unioned into China and subtracted from India.
+  - Taiwan/Penghu, Diaoyu Dao and affiliated islands, Chiwei Yu, and South China Sea islands are China hover/country features.
+  - The South China Sea dashed line is a claim-line layer only; it never consumes Malaysian, Philippine, Vietnamese, or other land polygons.
+  - Kosovo is not an independent country surface in this profile; Gaza is a Palestine region.
+- PMTiles/MVT layer names are fixed for the frontend:
+  - `boundary_admin0`
+  - `boundary_disputed_internal`
+  - `coastline`
+  - `claim_line`
+- The frontend provider is selected from the boundary manifest:
+  - `tileProvider: "pmtiles-mvt"` reads the PMTiles artifact.
+  - Any other provider, missing manifest, or missing PMTiles artifact is treated as an error.
+- Redis is not part of v1. Static PMTiles plus browser/CDN range caching is the default performance model.
 
-- 基础陆地国界使用 OSM `boundary=administrative` + `admin_level=2`，并补充高精度 coastline，避免只靠粗糙国家面导致海岸线缺失。
-- China POV 覆盖数据必须独立成包，构建时优先级高于 OSM 原始归属：
-  - 藏南 union 到中国面，同时从印度面 subtract。
-  - 阿克赛钦 union 到中国面，同时从相关邻接面 subtract。
-  - 台湾、澎湖、钓鱼岛及附属岛屿、赤尾屿、东沙、西沙、中沙、南沙等作为中国国家面/岛礁面的一部分进入 hover index。
-  - 岛礁很小时可有最小可交互面，但 tooltip 仍是 `中国 / CHN`，不展示“某特殊区域归属”标签。
-- 九段线 / 十段线是独立 maritime claim line 图层：
-  - 只渲染 dashed line，不参与国家陆地面。
-  - 不用于吞并周边国家陆地或近岸水域。
-  - 坐标必须来自官方标准地图、权威矢量数据，或从官方示意图配准后人工复核，不接受手工猜测坐标。
-- 必须保留 OSM 数据归因：`© OpenStreetMap contributors, ODbL`。
+## Cleanup And Documentation
 
-## Precision Requirements
-
-- 最高精度档的验收口径是 **source-faithful**，不是“看起来更细”：
-  - 对高精度源线，最高 zoom tile 不允许 Douglas-Peucker 简化。
-  - 坐标量化精度至少保留到 `1e-5` 度级别，构建时不得把经纬度粗暴四舍五入到低精度。
-  - 球面渲染只允许 densify 长边来贴合地球曲率；不允许 CatmullRom、Bezier 或任何会改变边界走向的平滑。
-  - 海岸/边界红框类区域必须与源地图折线逐点对齐；若有偏差，只能追溯并替换数据源，不能靠渲染平滑掩盖。
-- 低缩放允许简化，但必须有误差预算：
-  - base line 只服务远景识别。
-  - 中 zoom tile 可简化到屏幕误差低于 `0.5px`。
-  - 最高 zoom tile 使用无简化或近零误差版本。
-
-## Implementation Plan
-
-### 1. Data pipeline
-
-新增边界构建脚本，使用 `/home/ray/.local/bin/uv` 运行：
-
-1. 读取 OSM PBF 或预处理后的 admin-0 边界 / coastline GeoJSON。
-2. 读取 China POV override package。
-3. 使用可靠几何库做 union / difference / validity repair，禁止手写 polygon overlay。
-4. 生成中国国家面时直接合并藏南、阿克赛钦和相关岛礁；从相邻国家面扣除同一区域。
-5. 单独读取官方口径九段线 / 十段线矢量，生成 claim-line tiles。
-6. 输出：
-   - 低精度 global base line。
-   - 无简化 high-precision hover polygon index。
-   - 高精度静态瓦片：`frontend/public/earth/data/boundaries/v1/{z}/{x}/{y}.geojson`。
-   - 海上断续线瓦片：`frontend/public/earth/data/boundaries/v1/china-claims/{z}/{x}/{y}.geojson`。
-   - manifest，记录数据源、覆盖规则版本、构建时间、简化误差和 attribution。
-
-### 2. Tile levels and size budget
-
-- Earth zoom `< 1.6`：只显示 global base line 和低精度 claim line。
-- Earth zoom `1.6-2.8`：加载 tile zoom `4-5`。
-- Earth zoom `2.8-4.0`：加载 tile zoom `6-7`。
-- Earth zoom `> 4.0`：加载 tile zoom `8-10`，使用最高精度无简化折线。
-- 单 tile gzip 目标 `20-80KB`，但最高精度档优先保证几何真实性；若超限，优先提高 tile zoom 或拆 tile，而不是简化真实线。
-
-### 3. Frontend loading model
-
-`country-boundaries.js` 拆成 base layer、tile layer 和 China claim layer：
-
-- 首屏加载 base line + hover index，不阻塞 Earth 初始化。
-- 高缩放时根据 camera 可见范围计算经纬 bbox，再转换为 Web Mercator tile keys。
-- bbox 由屏幕中心、四角和边中点 raycast 得到，并扩张 `10-20%` 作为预取范围。
-- 处理反经线，必要时拆成两个 bbox。
-- 视野变化请求 debounce `150-250ms`。
-- 拖拽/惯性旋转中不每帧请求；缩放档或 tile key 集合没变时不刷新。
-- 加载当前视野 tile，并预取一圈邻接 tile。
-- base line 在高精度 tile 到达后降低 opacity，避免双线。
-
-### 4. Caching and memory control
-
-- 前端维护 `tileCache`、`inFlightTiles` 和 LRU 使用顺序。
-- tile cache 上限建议 `120-180` 个 tile；超过后释放最旧 tile 的 `BufferGeometry`。
-- Nginx 为 `/earth/data/boundaries/` 设置长缓存：
-  - `Cache-Control: public, max-age=31536000, immutable`
-  - gzip 包含 JSON。
-- tile URL 包含版本目录，例如 `v1`；数据更新时改版本目录破浏览器缓存。
-- 第一版不使用 Redis。只有改成动态裁剪 API、多 POV 同 URL、或压测证明静态服务成为瓶颈时再考虑 Redis。
-
-## Acceptance Criteria
-
-1. 最高 zoom 的海岸线和国界线与选定源地图逐点一致，不再只是“明显提升”。
-2. 红框类海岸/边界细节在最高 zoom 下不能出现肉眼可见的低精度折线、直线切边或圆滑失真。
-3. 藏南、阿克赛钦 hover 命中普通 `中国 / CHN`；印度或其他邻接国家不再包含这些区域。
-4. 钓鱼岛、赤尾屿、南海诸岛代表点 hover 命中普通 `中国 / CHN`。
-5. 九段线 / 十段线位置与权威来源一致，不压入马来西亚、菲律宾等周边陆地或错误包围近岸底盘。
-6. 首屏不加载全球超高精度整包。
-7. 高缩放只请求当前视野附近 tile，快速旋转不会出现请求风暴。
-8. 回到已访问区域命中前端 cache 或浏览器 cache。
-9. 国界图层开关、hover 高亮、移动端中心国家高亮、悬停提示三模式保持可用。
+- Do not commit generated loose tiles under `frontend/public/earth/data/boundaries/` or source downloads under `data/earth-boundary-sources/`.
+- Remove stale generated debug data before production builds; regenerate it only when smoke testing the debug path.
+- Keep the high-level plan, backend collector docs, layer style docs, and ops runbook aligned whenever the provider contract changes.
+- After implementation changes, provide user-facing operation steps covering source configuration, source collection, artifact build/deploy, page verification, and fallback troubleshooting.
 
 ## Verification
 
-- 构建阶段：
-  - 几何 validity check 全通过。
-  - China POV 代表点测试全部返回 `CHN`。
-  - 相邻国家代表点不得被 China override 误吞。
-  - 最高 zoom tile 抽样与源数据做坐标级 diff，确认未简化。
-- 前端阶段：
-  - 在 `frontend` 运行 `/home/ray/.bun/bin/bun run build`。
-  - 浏览器 DevTools 验证低缩放无高精度 tile 请求，高缩放请求数量受控，重复视野走 cache。
-  - 用截图中的红框区域、南海断续线、藏南、钓鱼岛、赤尾屿、南海诸岛做手动视觉验收。
+- The PMTiles builder fails as not ready when any of `earth_admin0_boundaries`, `earth_coastline`, or `earth_claim_lines` has not produced a current artifact record.
+- The PMTiles builder fails as not ready when source artifacts exist but `tippecanoe` / `pmtiles` are missing.
+- Running the PMTiles builder twice returns `unchanged` on the second run when inputs are stable.
+- `git add . --dry-run` does not include generated loose boundary tiles or source downloads.
+- `/home/ray/.bun/bin/bun run build` passes in `frontend`.
+- Manual Earth checks confirm:
+  - PMTiles range requests are issued only for visible tiles.
+  - Boundary toggle, hover tooltip, and country highlight still work.
+  - PMTiles failure reports a boundary-layer error; the frontend must not draw low-precision legacy boundaries.
 
-## Sources and Assumptions
+## Assumptions
 
-- 产品默认采用中国标准地图/公开地图合规口径；若后续支持多 POV，必须通过版本化数据目录隔离，不能让同一 URL 返回不同政治口径。
-- 当前仓库没有足够权威和足够精细的 China POV / 九段线矢量源，因此不能直接凭现有低精度 GeoJSON 完成“一比一还原”。
-- 实施前必须先引入或生成可审计的高精度源数据包；没有源数据时，只能实现加载框架，不能伪造边界。
+- "One-to-one" means source-faithful to the selected audited vector source, not hand-tuned to a screenshot.
+- The China POV artifact is static and versioned; no runtime region-based POV switching is planned.
+- The removed repository seed file cannot be used as a runtime fallback for country boundaries.

docs/plans/earth-high-resolution-basemap-tiles-plan.md

@@ -0,0 +1,118 @@
+# Earth High Resolution Basemap Tiles Plan
+
+## Summary
+
+High-precision borders now expose a separate visual problem: the vector coastline and border data are more accurate than the current raster Earth texture. The next step is a high-resolution basemap tile layer that aligns visually with the high-precision coastline instead of replacing the globe with one huge static image.
+
+Do not solve this by committing a larger single world texture. A single 16K/32K raster still wastes memory, loads slowly, and becomes blurry or misaligned when zooming into coastal detail. The target architecture is viewport-based raster tiles with cache control, similar to terrain tiles.
+
+## Goals
+
+- Render a high-resolution Earth imagery basemap that visually matches the high-precision coastline and country boundary layer.
+- Load imagery by visible bbox / tile key instead of loading a whole-world giant texture.
+- Keep the current global texture only as a low-zoom background, not as the source of truth for coastlines at inspection zoom.
+- Let imagery failures degrade only the imagery layer; high-precision borders and hover must continue working.
+- Keep generated imagery cache out of Git.
+
+## Data Sources
+
+Candidate sources, in recommended order:
+
+- NASA GIBS / Blue Marble / VIIRS style imagery for permissive global coverage and stable tile service behavior.
+- Sentinel-2 cloudless style public imagery if licensing and tile access are acceptable.
+- A self-hosted raster pyramid generated offline from audited global imagery if third-party online tile terms are unsuitable.
+
+The selected source must document:
+
+- license / attribution
+- max zoom and native resolution
+- tile matrix / projection
+- cache policy
+- whether commercial or public deployment is allowed
+
+## Architecture
+
+```text
+global low-zoom texture
+→ visible Earth bbox from camera raycast
+→ Web Mercator tile keys by zoom
+→ raster tile fetch/cache
+→ project tile image patches onto Earth surface
+→ high-precision coastline / border layer remains above imagery
+```
+
+Implementation should mirror the existing terrain tile discipline:
+
+- dedupe in-flight requests
+- LRU cache for decoded images / textures
+- debounce camera movement
+- cancel or ignore stale viewport requests
+- cap max tiles per frame / per view
+- expose loading/error diagnostics
+
+## Rendering Rules
+
+- The high-resolution imagery layer is visual only. It must not define country hover, coastline, or border geometry.
+- The high-precision coastline remains the visual alignment reference.
+- The border layer render order stays above the basemap imagery.
+- Low zoom may use the current global texture for speed.
+- Mid/high zoom overlays imagery tiles only for the visible region plus a small prefetch ring.
+- Do not draw decorative gradients or fake coastlines to hide mismatch.
+
+## Frontend Work
+
+- Add a new `basemap-imagery.js` module instead of expanding `country-boundaries.js`.
+- Add config in `constants.js`:
+  - source URL template
+  - attribution
+  - min/max zoom
+  - tile cache limit
+  - debounce interval
+  - opacity
+  - enable/disable setting
+- Add Earth settings control:
+  - `高清底图`: off / auto / on
+  - default `auto`
+- Add debug counters for:
+  - active tile count
+  - cached tile count
+  - failed tile count
+  - current imagery zoom
+
+## Backend / Ops Work
+
+- If using a third-party tile service directly, document attribution and rate-limit behavior.
+- If proxying tiles, add backend cache with request coalescing and timeout limits.
+- If self-hosting, add an offline builder that writes ignored tile artifacts under a dedicated data directory.
+- Update Nginx static serving if self-hosted raster tiles are used.
+
+## Performance Budget
+
+- Desktop target: keep visible imagery tiles under a configurable cap, initially 64.
+- Mobile target: lower max zoom and tile cap by default.
+- Decode and upload textures incrementally; avoid blocking Earth startup on high-resolution imagery.
+- First Earth paint must still use the existing lightweight global texture.
+
+## Verification
+
+- Compare high-precision coastline against imagery in coastal areas such as southeast China, Taiwan, Hainan, the Korean peninsula, Japan, and island chains in the South China Sea.
+- Verify zooming / panning does not create visible tile thrash or long blank periods.
+- Verify failed imagery requests do not hide borders or break hover.
+- Verify memory stabilizes after repeated pan/zoom due to LRU eviction.
+- Run `/home/ray/.bun/bin/bun run build`.
+
+## User Operation Steps
+
+After implementation, the user should be able to:
+
+1. Open Earth settings.
+2. Set `高清底图` to `auto` or `on`.
+3. Open Earth and zoom into a coastline.
+4. See imagery tiles refine under the high-precision boundary/coastline layer.
+5. Use diagnostics to confirm which imagery zoom and tile source are active.
+
+## Assumptions
+
+- The existing high-precision vector coastline is the alignment reference.
+- This plan improves visual texture fidelity; it does not replace the boundary data pipeline.
+- A single larger static Earth texture is rejected as the primary solution.

docs/plans/earth-mobile-center-country-highlight-plan.md

@@ -37,7 +37,7 @@
 ## Non-goals
 
 - 不改变桌面端 hover 交互。
-- 不替换 `countries-admin0.min.geojson` 数据源。
+- 不引入旧低精度国界兜底；移动端中心国家能力必须复用生产 PMTiles/MVT 国界源。
 - 不新增后端 API。
 - 不把国家面填充做成新的 selected country 面状 shader。
 - 不为移动端增加永久准星 UI，除非后续产品明确需要视觉准星。
@@ -249,4 +249,3 @@ mobileCenterHoverGlowOpacity
 3. 性能保护：加入节流、经纬度阈值和禁用态清理。
 4. 验证：本地构建通过，移动端 viewport 手动检查通过。
 5. 调优：根据截图或真机体验微调阻塞条件和节流阈值。
-

docs/plans/earthfeed-coordinate-queue-plan.md

@@ -0,0 +1,131 @@
+# EarthFeed 新闻坐标与异步精修计划
+
+## 目标
+
+EarthFeed 的每条新闻都直接携带巡航可用坐标。初始响应使用新闻所属大区的锚点坐标，后台通过消息队列异步推理更精确的目标地址，完成后用实时补丁替换原新闻坐标，实现前端无感更新。
+
+## 返回结构
+
+`GET /api/v1/news/earth-feed` 返回：
+
+```json
+{
+  "generated_at": "2026-05-15T03:16:43Z",
+  "focus": {
+    "lat": null,
+    "lon": null,
+    "region": "global",
+    "label": "全球焦点",
+    "accent": "#d6e6ff"
+  },
+  "sources": [
+    {
+      "id": "bbc-world",
+      "name": "BBC World",
+      "region": "global",
+      "homepage_url": "https://www.bbc.com/news/world"
+    }
+  ],
+  "items": [
+    {
+      "id": "bbc-world:af01519ba7dd",
+      "title": "Flattery and fanfare as Trump welcomed to China - but thorny issues remain",
+      "summary": "The leaders of the world's two superpowers were all smiles...",
+      "url": "https://www.bbc.com/news/articles/cdxpypg9dgeo",
+      "source": "BBC World",
+      "feed_name": "BBC World",
+      "region": "global",
+      "homepage_url": "https://www.bbc.com/news/world",
+      "published_at": "2026-05-14T13:02:13Z",
+      "latitude": 39.9057136,
+      "longitude": 116.3912972,
+      "location_label": "北京市, 中国",
+      "location_source": "headline_location_hint",
+      "verified": true,
+      "location_meta": {
+        "resolution_stage": "headline_location_hint",
+        "ai_attempted": false,
+        "ai_status": "skipped_text_hint",
+        "ai_error": null,
+        "debug_note": "text hint matched 北京市, 中国",
+        "target": {
+          "latitude": 39.9057136,
+          "longitude": 116.3912972,
+          "label": "北京市, 中国",
+          "source": "headline_location_hint",
+          "confidence": 0.78,
+          "country": "中国",
+          "city": "Beijing"
+        },
+        "anchor": {
+          "region": "global",
+          "label": "全球",
+          "latitude": 20.0,
+          "longitude": 0.0
+        }
+      },
+      "is_focus_match": true
+    }
+  ],
+  "errors": [],
+  "stale": false
+}
+```
+
+字段规则：
+
+- `latitude` / `longitude`：前端巡航唯一读取的坐标。
+- `location_label`：当前坐标展示名。
+- `location_source`：`region_anchor`、`headline_location_hint`、`headline_country_hint`、`ai_inferred_target` 等。
+- `verified`：`false` 表示仍是大区锚点；`true` 表示已经由标题规则、国家规则或 AI 得到目标地址。
+- `location_meta`：调试、诊断、AI 状态、目标地址和锚点详情都放这里，不再展开成 `t_*` 主字段。
+
+## 后台队列
+
+当前使用 Redis Streams：
+
+- stream：`earth_news:target_location:jobs`
+- consumer group：`earth_news_target_location`
+- result cache：`earth_news:target_location:result:{item_id}`
+- dedupe key：`earth_news:target_location:queued:{item_id}`
+
+请求流程：
+
+1. RSS 拉取并排序。
+2. 每条新闻先生成大区锚点坐标，`verified=false`。
+3. 若 Redis 已有该新闻的精修结果，则合并结果返回。
+4. 若没有精修结果，则把新闻 job 入队，接口立即返回。
+
+Worker 流程：
+
+1. 从队列消费新闻 job。
+2. 先跑标题/国家规则，再视情况调用 AI。
+3. 写入 result cache。
+4. 广播 WebSocket 补丁：
+
+```json
+{
+  "type": "data_frame",
+  "channel": "earth_news",
+  "timestamp": "2026-05-15T03:17:00Z",
+  "payload": {
+    "item_id": "bbc-world:af01519ba7dd",
+    "patch": {
+      "latitude": 39.9057136,
+      "longitude": 116.3912972,
+      "location_label": "北京市, 中国",
+      "location_source": "headline_location_hint",
+      "verified": true,
+      "location_meta": {}
+    }
+  }
+}
+```
+
+## 可迁移性
+
+业务代码只调用队列接口，不直接依赖 Redis Streams 细节。以后迁移 Kafka 时新增 Kafka adapter，保持 job payload、result patch 和 worker 推理逻辑不变。
+
+## 前端规则
+
+新闻面板和巡航都只读取新闻项内的 `latitude` / `longitude`。实时补丁到达后按 `item_id` 合并到现有 `payload.items`，重新渲染并触发 `earth:news-payload-updated`，巡航下一轮自然使用精修坐标。

docs/technical/en/backend-collectors.md

@@ -86,9 +86,17 @@ async def run(self, db):
 | TeleGeography | submarine_cable | Submarine cable information | 7 days |
 | BarentsWatch AIS | vessel | AIS vessel positions, speed, heading, MMSI, and related fields | Collector settings |
 | AISStream Vessels | vessel_ais | AIS WebSocket realtime stream, written to the raw observation layer and displayed through aggregation | Collector settings |
+| Earth Admin-0 Boundaries | earth_admin0_boundaries | Downloads the configured country-boundary source, saves an artifact, and writes an `earth_boundary_source` manifest record | Collector settings |
+| Earth Coastline | earth_coastline | Downloads the configured coastline source, saves an artifact, and writes an `earth_boundary_source` manifest record | Collector settings |
+| Earth Claim Lines | earth_claim_lines | Downloads the configured claim-line source, saves an artifact, and writes an `earth_boundary_source` manifest record | Collector settings |
+| Earth PMTiles Builder | earth_boundary_tiles | Reads the three Earth boundary source records and builds / registers the PMTiles artifact | Collector settings |
 
 AIS vessel collectors use a different persistence path from regular `CollectedData` collectors. BarentsWatch, AISStream, and custom `vessel_ais` sources write into the AIS raw observation layer first, then the aggregation service merges those observations into the GeoJSON and detail payloads used by the Earth vessel layer. This preserves source, transport, field conflicts, and observation time instead of letting one realtime source overwrite the final display table.
 
+Earth boundaries are now split into three real source collectors plus one downstream builder. `earth_admin0_boundaries`, `earth_coastline`, and `earth_claim_lines` read endpoint, headers, auth, and `config.target_schema=earth_boundary_source` from Collector Settings. Triggering them requests the configured endpoint, writes the full response to `data/earth-boundary-sources/<collector>/<sha256>.*`, and stores sha256, feature count, license, artifact path, sample properties, and mapping metadata in `CollectedData`.
+
+`earth_boundary_tiles` no longer means source-data collection. It reads the latest successful records from those three source collectors; if any source is missing, the task fails as "not ready" and does not register "4 high-precision tile" records. Once all sources exist, it uses `tippecanoe` / `pmtiles` to build `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`; if those tools are missing, the task fails with the missing-tool message. There is no legacy low-precision fallback for country boundaries.
+
 TOP500 and Epoch AI compute sources do not always provide usable coordinates. The unified Earth compute-center endpoint uses only valid source-provided coordinates or `compute_center_locations` dimension-table coordinates during the main map startup path; records without coordinates are returned as `unresolved` instead of being rendered from a local registry, country centroid, or guessed city. When users manually collect candidates, the backend queries ROR and Nominatim/OpenStreetMap from source fields; accepted candidates are saved into `compute_center_locations` and rendered from that table on the next layer refresh.
 
 ## IV. Data Format (stored in CollectedData table)
@@ -219,7 +227,8 @@ backend/app/services/collectors/
 ├── peeringdb.py         # PeeringDB collector
 ├── telegeraphy.py       # TeleGeography submarine cable collector
 ├── vessel_ais.py        # BarentsWatch AIS vessel collector
-└── aisstream.py         # AISStream WebSocket vessel collector
+├── aisstream.py         # AISStream WebSocket vessel collector
+└── earth_boundaries.py  # Earth boundary source verification and static tile artifact collector
 
 backend/app/services/
 ├── custom_datasource_runtime.py      # Custom REST / WebSocket mapping runtime

docs/technical/en/datasource-collector-settings-connectivity.md

@@ -307,6 +307,8 @@ Files:
 
 Custom sources are supplemental inputs for existing target schemas, not isolated data islands. The most complete target today is `vessel_ais`: a custom REST or WebSocket source is mapped deterministically, written into AIS raw observations, and then pushed to Earth through the `vessels` WebSocket channel.
 
+Earth high-precision boundaries use the same target-schema mechanism. `earth_boundary_source` receives mapped records for `earth_admin0_boundaries`, `earth_coastline`, and `earth_claim_lines`; full GeoJSON / JSON payloads are stored as artifacts, while the database only keeps source kind, sha256, feature count, license, artifact path, and sample properties so large geometries do not land in a single row.
+
 ### Configuration Semantics
 
 Important fields:
@@ -316,7 +318,7 @@ Important fields:
 - `auth_type`: `none`, `bearer`, `api_key`, or `basic`.
 - `headers`: static request headers.
 - `auth_config`: token, API key, or basic username/password; API keys can be sent by header or query.
-- `config.target_schema`: for example `vessel_ais`.
+- `config.target_schema`: for example `vessel_ais` or `earth_boundary_source`.
 - `config.delivery_mode`: REST defaults to `polling`; WebSocket defaults to `realtime_stream`.
 - `config.merge_target_source`: records which built-in source this custom source supplements, such as `barentswatch_vessels`.
 

docs/technical/en/earth-frontend-context.md

@@ -122,6 +122,9 @@ Responsibilities:
 - Globe sphere, cloud layer, atmosphere
 - Real terrain mesh
 - Terrain tile fetch, decode, displacement, and shading
+- Whole-globe land/ocean and border base overlays
+
+The Earth surface is a stack of near-concentric shells, not a single mesh. The base sphere and HD texture overlay in `earth.js`, plus the land/ocean base in `country-boundaries.js`, need explicit radius separation. At far zoom, GPU depth precision drops; neighboring shells that are too close can z-fight and show black flicker blocks or snow. The current stable spacing is `landAltitudeOffset = 0.32` and `textureOverlayAltitudeOffset = 0.48`. When adding or adjusting whole-globe surface overlays, update [Earth Render Layer Order](/home/ray/dev/linkong/planet/docs/technical/en/earth-render-layer-order.md) and verify at 50% zoom.
 
 ### 7. Layer Modules
 

docs/technical/en/earth-layer-style-reference.md

@@ -23,7 +23,7 @@ This document records the material, color, opacity, line width, radius offset, a
 | Earth base specular | `EARTH_MATERIAL_CONFIG.specular` | `0x1a2d45` | `MeshPhongMaterial.specular` |
 | Earth base shininess | `EARTH_MATERIAL_CONFIG.shininess` | `12` | `MeshPhongMaterial.shininess` |
 | Earth base opacity | `EARTH_MATERIAL_CONFIG.opacity` | `1` | `MeshPhongMaterial.opacity` |
-| HD texture radius offset | `EARTH_MATERIAL_CONFIG.textureOverlayAltitudeOffset` | `0.1` | Standalone HD texture sphere radius |
+| HD texture radius offset | `EARTH_MATERIAL_CONFIG.textureOverlayAltitudeOffset` | `0.48` | Standalone HD texture sphere radius; must keep enough depth separation from the land/ocean base and Earth base sphere to avoid far-zoom z-fighting |
 | HD texture opacity | `EARTH_MATERIAL_CONFIG.textureOverlayOpacity` | `0.88` | HD texture `MeshPhongMaterial.opacity` |
 | HD texture renderOrder | `EARTH_MATERIAL_CONFIG.textureOverlayRenderOrder` | `0.96` | `_earthTextureOverlay.renderOrder` |
 | HD texture specular | `EARTH_MATERIAL_CONFIG.textureOverlaySpecular` | `0x05080d` | Reduces specular highlight in direct-light areas to avoid blown-out texture |
@@ -78,11 +78,18 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor
 
 | Name | Variable | Current Value | Location / Notes |
 | --- | --- | --- | --- |
-| Country border data path | `COUNTRY_BOUNDARY_CONFIG.dataPath` | `"/earth/data/countries-admin0.min.geojson"` | GeoJSON input |
+| Boundary tile manifest | `COUNTRY_BOUNDARY_CONFIG.tileManifestPath` | `"/earth/data/boundaries/v1/manifest.json"` | Required production PMTiles manifest; missing manifest is an error |
+| Boundary tile provider | `COUNTRY_BOUNDARY_CONFIG.tileProvider` | `"pmtiles-mvt"` | Only PMTiles/MVT is accepted for country boundaries |
+| PMTiles artifact path | `COUNTRY_BOUNDARY_CONFIG.pmtilesPath` | `"/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles"` | Production single-file PMTiles/MVT artifact |
+| MVT layer names | `COUNTRY_BOUNDARY_CONFIG.mvtLayerNames` | `boundary_admin0 / boundary_disputed_internal / coastline / claim_line` | Fixed layer names decoded by the PMTiles provider |
+| Boundary tile base path | `COUNTRY_BOUNDARY_CONFIG.tileBasePath` | `"/earth/data/boundaries/v1/"` | PMTiles manifest base path |
+| Boundary tile zoom thresholds | `COUNTRY_BOUNDARY_CONFIG.tileZoomThresholds` | `1.6 -> z5`, `2.8 -> z6`, `3.4 -> z7`, `4.0 -> z8`, `4.6 -> z9`, `5.2 -> z10` | Production PMTiles zoom selection |
+| Boundary tile cache limit | `COUNTRY_BOUNDARY_CONFIG.tileCacheLimit` | `150` | Frontend LRU cache entries for loaded tile geometries |
+| Boundary tile debounce | `COUNTRY_BOUNDARY_CONFIG.tileDebounceMs` | `180` | View-change debounce before requesting visible tiles |
 | Ocean fill color | local `OCEAN_HEX` | `0x010609` | Land/ocean base canvas background |
 | Land fill color | `COUNTRY_BOUNDARY_CONFIG.landColor` | `0x080f1b` | Land/ocean base canvas land |
 | Land/ocean base opacity | `COUNTRY_BOUNDARY_CONFIG.landOpacity` | `1.0` | `MeshBasicMaterial.opacity` |
-| Land/ocean base radius offset | `COUNTRY_BOUNDARY_CONFIG.landAltitudeOffset` | `0.08` | `country-land-ocean` radius |
+| Land/ocean base radius offset | `COUNTRY_BOUNDARY_CONFIG.landAltitudeOffset` | `0.32` | `country-land-ocean` radius; separated from the Earth base sphere to avoid snow / black block flicker at 50% zoom |
 | Land/ocean base renderOrder | `COUNTRY_BOUNDARY_CONFIG.landRenderOrder` | `0.86` | `country-land-ocean.renderOrder` |
 | Land/ocean mask size | `landMaskWidth / landMaskHeight` | `2048 / 1024` | Canvas / DataTexture size |
 | Country tint color | `COUNTRY_BOUNDARY_CONFIG.tintColor` | `0x0b1830` | Tint when HD texture is off |
@@ -91,16 +98,16 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor
 | Border line color | `COUNTRY_BOUNDARY_CONFIG.lineColor` | `0x7fc7ff` | Normal border line |
 | Border line opacity | `COUNTRY_BOUNDARY_CONFIG.lineOpacity` | `0.58` | Normal border line opacity |
 | Border dimmed opacity on hover | `COUNTRY_BOUNDARY_CONFIG.dimmedLineOpacity` | `0.18` | Normal border opacity during hover |
-| Border line radius offset | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.115` | Normal border line radius; slightly above HD texture `0.10` and below terrain base `0.16` to reduce floating |
+| Border line radius offset | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.115` | Normal border line radius; line layers rely on renderOrder and independent geometry, not whole-globe shell depth spacing |
 | Border line renderOrder | `COUNTRY_BOUNDARY_CONFIG.lineRenderOrder` | `2.2` | Normal border line level |
 | Border hover color | `COUNTRY_BOUNDARY_CONFIG.hoverLineColor` | `0xff3b1f` | Neon red-orange |
 | Border hover opacity | `COUNTRY_BOUNDARY_CONFIG.hoverLineOpacity` | `1.0` | Hover line opacity |
-| Border hover radius offset | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.14` | Hover line radius; close to the surface but above normal border lines |
+| Border hover radius offset | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.115` | Hover line radius; matches the normal border geometry to avoid double-edge ghosting during highlight changes |
 | Border hover renderOrder | `COUNTRY_BOUNDARY_CONFIG.hoverLineRenderOrder` | `2.3` | Hover line level |
 | Border hover glow opacity | `COUNTRY_BOUNDARY_CONFIG.hoverGlowOpacity` | `0.38` | Glow line opacity |
 | Border hover glow line width | `COUNTRY_BOUNDARY_CONFIG.hoverGlowLineWidth` | `3` | Glow `LineBasicMaterial.linewidth` |
 | Border hover glow level offset | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRenderOrderOffset` | `0.01` | Glow renderOrder = `2.29` |
-| Border hover glow radius offset | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRadiusOffset` | `0.04` | Glow radius = hover radius + 0.04 |
+| Border hover glow radius offset | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRadiusOffset` | `0` | Glow uses the same radius as the hover line to avoid coastline detail misalignment |
 
 ## Real Terrain
 

docs/technical/en/earth-render-layer-order.md

@@ -17,8 +17,8 @@ Note: the layer control panel order and the registration / startup load order ar
 | -1 | Earth occluder sphere | `earth.js` | Invisible inner sphere | Writes depth buffer | Occludes objects behind the Earth. |
 | 0 | Earth base sphere | `earth.js` | `CONFIG.earthRadius` | Surface picking fallback target | Dark base; still visible when all optional map layers are off. |
 | 0.2 | Country dark tint | `country-boundaries.js` | `tintAltitudeOffset` | Raycast disabled | Used when HD texture is off. |
-| 0.86 | Land/ocean base fill | `country-boundaries.js` | `landAltitudeOffset`; ocean `#010609`, land `#080f1b` | Raycast disabled | Base map remains usable even when country borders are off. |
-| 0.96 | HD Earth texture | `earth.js` | `textureOverlayAltitudeOffset` | Surface picking target when visible | HD texture always overlays the land/ocean base fill. |
+| 0.86 | Land/ocean base fill | `country-boundaries.js` | `landAltitudeOffset = 0.32`; ocean `#010609`, land `#080f1b` | Raycast disabled | Base map remains usable even when country borders are off; radius is separated from the base sphere to avoid far-zoom z-fighting. |
+| 0.96 | HD Earth texture | `earth.js` | `textureOverlayAltitudeOffset = 0.48` | Surface picking target when visible | HD texture always overlays the land/ocean base fill; radius must stay above the land/ocean base and far enough from the base sphere. |
 | 1 | Atmospheric glow and clouds | `earth.js` | Atmosphere / cloud spheres | Not in normal object selection path | Cloud layer controlled by the "Cloud Layer" toggle. |
 | 1 | Submarine cables | `cables.js` | `CABLE_CONFIG.line.renderOrder` | Cable picking path | Preserves existing cable layer level. |
 | 1.2 | Real terrain | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` plus terrain displacement | Raycast disabled | Terrain overlays HD texture; temporarily hidden when HD texture is off, restores to prior state when re-enabled. |
@@ -45,6 +45,17 @@ Note: the layer control panel order and the registration / startup load order ar
 | Border Lines off | Hides only interactive border lines and hover, clearing hover state; the land/ocean base fill remains as the Earth base map. |
 | Real Satellite Altitude off | Satellite dots, trails, and predicted orbits use the legacy same-sphere height; satellites with missing TLE data or failed propagation also use this fallback height. |
 
+## Depth Spacing Rules
+
+The Earth surface is not a single mesh. It is a stack of near-concentric shells: base sphere, land/ocean base, HD texture, terrain, clouds, atmosphere, and the occluder. Radius offsets that look harmless at close zoom can collapse into the same depth-buffer pixels at zoomed-out views such as 50%, causing z-fighting that appears as black blocks, snow, or flicker.
+
+Maintenance rules:
+
+- Do not reach first for hiding layers at far zoom. Check neighboring shell `altitudeOffset`, `renderOrder`, `depthTest`, and `depthWrite` first.
+- Whole-globe overlays such as the land/ocean base and HD texture must keep explicit separation from `CONFIG.earthRadius`; the current stable values are `landAltitudeOffset = 0.32` and `textureOverlayAltitudeOffset = 0.48`.
+- Any new whole-globe or near-whole-globe surface overlay must be screenshot-verified at 50% zoom and at common close zooms, with no black blocks, snow, flicker, or obvious floating.
+- If these radii change, update this document and the intent around the constants in `frontend/public/earth/js/constants.js`.
+
 ## Interaction Rules
 
 | Interaction | Current Rule |

docs/technical/en/faq.md

@@ -58,9 +58,9 @@ For temporary troubleshooting, you can stop IP Helper from Administrator PowerSh
 Stop-Service iphlpsvc -Force
 ```
 
-This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. New `--allow-lan` runs a temporary Windows relay for `3000` / `8000`, so persistent portproxy is no longer required.
+This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. `--allow-lan` now binds `3000` / `8000` / `8010` directly, so persistent portproxy is no longer required.
 
-If the script prints `failed-stop-service`, `failed-stop-process`, or Vite reports `Port 3000 is already in use` followed by `Windows listener ... services=iphlpsvc`, an old Windows listener still owns the port. Startup stops immediately and prints the recovery order: use Administrator PowerShell to inspect `netsh interface portproxy show all`, delete the matching `listenport` rule, confirm the PID and services with `netstat` / `tasklist` if no portproxy rule exists, and temporarily run `Stop-Service iphlpsvc -Force` when appropriate. After old rules are gone, rerun `./planet.sh restart --allow-lan`; the script starts temporary relays while LAN devices still use `3000` / `8000`.
+If the script prints `Windows 侧端口 ... 存在监听者`, or Vite reports `Port 3000 is already in use` followed by `Windows listener ... services=iphlpsvc`, an old Windows listener still owns the port. The script requests Administrator PowerShell cleanup for that port. If the automatic cleanup is canceled, inspect `netsh interface portproxy show all`, delete the matching `listenport` rule, confirm the PID and services with `netstat` / `tasklist` if no portproxy rule exists, and temporarily run `Stop-Service iphlpsvc -Force` when appropriate. After old rules are gone, rerun `./planet.sh restart --allow-lan`; LAN devices still use `3000` / `8000` / `8010`.
 
 ### Which startup flags change default ports?
 
@@ -87,6 +87,7 @@ Check in this order before changing firewall rules:
 # In WSL or the shell running Planet
 curl http://localhost:3000
 curl http://localhost:8000/health
+curl http://localhost:8010/health
 ```
 
 Then verify from Windows PowerShell:
@@ -94,6 +95,7 @@ Then verify from Windows PowerShell:
 ```powershell
 curl http://localhost:3000
 curl http://localhost:8000/health
+curl http://localhost:8010/health
 ```
 
 If both localhost checks pass but a phone or another computer cannot connect, start with LAN enabled:
@@ -108,16 +110,18 @@ The flag must be written as `--allow-lan`. `allowlan` or `--allowlan` is not rec
 ./planet.sh restart -f 3000 --allow-lan
 ```
 
-If `ss -ltnp` shows the frontend listening on `0.0.0.0:3000`, but `Test-NetConnection <Windows LAN IP> -Port 3000` still fails from Windows PowerShell, the problem is usually Windows-side forwarding or firewall policy rather than Vite or `.zshrc`.
+If `ss -ltnp` shows the frontend listening on `0.0.0.0:3000`, but `Test-NetConnection <Windows LAN IP> -Port 3000` still fails from Windows PowerShell, the problem is usually Windows-side port ownership, stale `portproxy`, or firewall policy rather than Vite or `.zshrc`.
 
-For traditional WSL NAT networking, `./planet.sh start --allow-lan` starts temporary Windows relays so Windows still exposes `3000` / `8000`. Before startup, the script checks for stale `portproxy` rules and requests Administrator PowerShell to delete them. It also checks Windows Firewall and, when inbound allow rules for `3000` / `8000` are missing, triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:
+`./planet.sh start --allow-lan` directly exposes `3000` / `8000` / `8010` and checks port availability, stale `portproxy`, and Windows Firewall before startup. If a Windows-side listener owns a port, the script requests Administrator PowerShell cleanup. When inbound allow rules are missing, it also triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:
 
 ```powershell
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
+netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
 
 New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
 New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
 ```
 
 LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.
@@ -127,6 +131,7 @@ If `wslinfo --networking-mode` prints `mirrored`, also check Hyper-V firewall. E
 ```powershell
 New-NetFirewallHyperVRule -Name "Planet-Frontend-3000" -DisplayName "Planet Frontend 3000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 3000 -Action Allow
 New-NetFirewallHyperVRule -Name "Planet-Backend-8000" -DisplayName "Planet Backend 8000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8000 -Action Allow
+New-NetFirewallHyperVRule -Name "Planet-AIProvider-8010" -DisplayName "Planet AI Provider 8010" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8010 -Action Allow
 ```
 
 Use these commands to inspect the current Hyper-V firewall state:

docs/technical/en/ops-planet-sh-startup.md

@@ -177,7 +177,7 @@ Frontend startup now has an additional pre-start cleanup retry layer:
 - `PORT_PRESTART_RETRIES`: defaults to 3 attempts.
 - `PORT_PRESTART_RETRY_INTERVAL`: defaults to 2 seconds.
 
-`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it tries to stop the owning Windows service or force-stop the owning process through PowerShell. If permissions are missing, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and Administrator PowerShell recovery commands, then stops startup immediately instead of launching the service into the same port error. If the frontend Vite process only discovers `Port 3000 is already in use` after launch, the script prints the same Windows listener recovery commands. Non-WSL environments do not run the Windows cleanup path. On WSL, `--allow-lan` uses temporary Windows relays to expose `3000` / `8000`, so old persistent portproxy rules should be removed.
+`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it requests Administrator PowerShell to delete stale `portproxy` rules, stop services that own the port, or force-stop the owning process. If the administrator request is canceled, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and Administrator PowerShell recovery commands, then stops startup immediately instead of launching the service into the same port error. If the frontend Vite process only discovers `Port 3000 is already in use` after launch, the script prints the same Windows listener recovery commands. Non-WSL environments do not run the Windows cleanup path. `--allow-lan` now exposes `3000` / `8000` / `8010` directly and no longer starts an extra Windows forwarding process; old persistent portproxy rules should be removed.
 
 ## Issue 4: `restart` Behavior
 

docs/technical/en/ops-runbook.md

@@ -120,7 +120,7 @@ Useful for:
 - Demoing Earth from a phone or tablet
 - Other LAN machines reaching the same dev instance
 
-`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but other LAN machines reaching the Windows LAN IP still need Windows port forwarding and firewall rules.
+`--allow-lan` directly exposes the frontend, backend, and AI Provider from the development machine: frontend `3000`, backend `8000`, and AI Provider `8010`. Before startup, the script checks all three ports. If WSL/Linux cannot release a port and a Windows-side listener or stale `portproxy` rule owns it, the script requests Administrator PowerShell cleanup. When Planet runs in WSL, Windows can usually reach it through `localhost`; other LAN machines reaching the Windows LAN IP still need Windows Firewall allow rules.
 
 Diagnose in this order:
 
@@ -128,20 +128,23 @@ Diagnose in this order:
 # From the shell running Planet
 curl http://localhost:3000
 curl http://localhost:8000/health
-ss -ltnp | grep -E ':3000|:8000'
+curl http://localhost:8010/health
+ss -ltnp | grep -E ':3000|:8000|:8010'
 ```
 
-If WSL services are running but the LAN IP still fails, let `./planet.sh start --allow-lan` launch temporary Windows relays. The relays keep Windows exposed on `3000` / `8000` and exit automatically when the WSL target port goes away. The script checks stale `portproxy` rules and requests Administrator PowerShell to delete them, then checks Windows Firewall and triggers a UAC Administrator PowerShell request when inbound allow rules are missing. Manual fallback commands:
+If the services are running but the LAN IP still fails, first remove stale `portproxy` rules and confirm Windows Firewall allows the ports. The script checks this automatically and requests Administrator PowerShell when needed. Manual fallback commands:
 
 ```powershell
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
+netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
 
 New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
 New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
 ```
 
-LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.
+LAN devices should use the Windows external ports, for example `http://<Windows LAN IP>:3000/earth`, `http://<Windows LAN IP>:8000/health`, and `http://<Windows LAN IP>:8010/health`.
 
 ## AI Provider Environment and Builds
 
@@ -238,6 +241,16 @@ uv sync
 uv run pytest backend/tests/test_otp_service.py
 ```
 
+## Earth Boundary PMTiles Operations
+
+1. In Collector Settings, configure endpoints, headers/auth, `config.target_schema=earth_boundary_source`, license, and mapping for `Earth Admin-0 Boundaries`, `Earth Coastline`, and `Earth Claim Lines`.
+2. In the data-source console, collect those three sources first. Each successful source writes the full artifact to `data/earth-boundary-sources/<collector>/<sha256>.*` and stores sha256, feature count, artifact path, and sample properties.
+3. After all three sources succeed, collect `Earth PMTiles Builder`. If any source is missing, it fails as "not ready" and does not update Earth boundaries.
+4. The builder requires `tippecanoe` and `pmtiles` on PATH. Missing tools fail the task with a clear message.
+5. A successful production build outputs `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles` and its manifest.
+6. After deployment, open Earth, enable "Border Lines", and inspect China's southeast coast, Taiwan, Hainan, the South China Sea, Zangnan, Kosovo, and Gaza for hover behavior and boundary policy.
+7. If PMTiles loading fails, Earth reports a boundary-layer error and does not draw legacy low-precision borders. Troubleshoot in this order: browser Network range requests for PMTiles, manifest `tileProvider: "pmtiles-mvt"`, Nginx static serving for `.pmtiles`, and artifact path / sha256 consistency with the manifest.
+
 ## Related Docs
 
 - [planet.sh Startup Mechanism](/home/ray/dev/linkong/planet/docs/technical/en/ops-planet-sh-startup.md)

docs/technical/zh/backend-collectors.md

@@ -87,9 +87,17 @@ async def run(self, db):
 | Space-Track TLE | satellite_tle | 卫星轨道 TLE 数据 | 依采集器配置 |
 | BarentsWatch AIS | vessel | 船只位置、航速、航向、MMSI 等 AIS 数据 | 依采集器配置 |
 | AISStream Vessels | vessel_ais | AIS WebSocket 实时流，写入原始观测层并由聚合接口展示 | 依采集器配置 |
+| Earth Admin-0 Boundaries | earth_admin0_boundaries | 从配置 endpoint 下载国家级边界源，保存 artifact 并写入 `earth_boundary_source` manifest 记录 | 依采集器配置 |
+| Earth Coastline | earth_coastline | 从配置 endpoint 下载海岸线源，保存 artifact 并写入 `earth_boundary_source` manifest 记录 | 依采集器配置 |
+| Earth Claim Lines | earth_claim_lines | 从配置 endpoint 下载主张线源，保存 artifact 并写入 `earth_boundary_source` manifest 记录 | 依采集器配置 |
+| Earth PMTiles Builder | earth_boundary_tiles | 读取三类 Earth 边界源采集结果并构建 / 登记 PMTiles 产物 | 依采集器配置 |
 
 AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同。BarentsWatch、AISStream 和自定义 `vessel_ais` 源都会进入 AIS 原始观测层，随后由聚合服务合并成 Earth 船只图层使用的 GeoJSON 和详情数据。这样做可以保留来源、传输方式、字段冲突和观测时间，避免某个实时源直接覆盖最终展示表。
 
+Earth 边界现在拆成三个真实源采集器和一个下游构建器。`earth_admin0_boundaries`、`earth_coastline`、`earth_claim_lines` 都读取后台 Collector Settings 里的 endpoint、headers、auth 和 `config.target_schema=earth_boundary_source`，点击采集时会真实请求 endpoint，保存完整响应到 `data/earth-boundary-sources/<collector>/<sha256>.*`，并在 `CollectedData` 中写入 sha256、feature count、license、artifact path、sample properties 和 mapping 信息。
+
+`earth_boundary_tiles` 不再代表源数据采集。它只读取上述三类源的最新成功记录；缺任一源时任务失败并显示“未就绪”，不会登记“4 条高精度瓦片”。三类源齐全后，它会调用 `tippecanoe` / `pmtiles` 生成 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`；本机缺少这些工具时任务失败并说明缺失工具。国界不再有旧低精度兜底。
+
 TOP500 和 Epoch AI 算力数据的公开源不总是提供可用经纬度。Earth 统一算力中心接口在主地图启动链路中只使用源数据自带坐标或 `compute_center_locations` 维表坐标；缺少坐标的记录会进入 `unresolved`，不会通过本地注册表、国家质心或猜测城市自动渲染。用户手动采集候选时，后端会用源字段调用 ROR 组织注册 API 和 Nominatim/OpenStreetMap 在线搜索；候选经前端保存后写入 `compute_center_locations`，后续地图刷新再从维表渲染。
 
 ## 四、数据格式 (统一存储到 CollectedData 表)
@@ -244,7 +252,8 @@ backend/app/services/collectors/
 ├── peeringdb.py         # PeeringDB采集器
 ├── telegeraphy.py       # TeleGeography海底光缆采集器
 ├── vessel_ais.py        # BarentsWatch AIS 船只采集器
-└── aisstream.py         # AISStream WebSocket 船只采集器
+├── aisstream.py         # AISStream WebSocket 船只采集器
+└── earth_boundaries.py  # Earth 国界源校验和静态瓦片 artifact 采集器
 
 backend/app/services/
 ├── custom_datasource_runtime.py      # 自定义 REST / WebSocket 映射运行时

docs/technical/zh/datasource-collector-settings-connectivity.md

@@ -309,6 +309,8 @@ GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=
 
 自定义源现在不是独立的新数据孤岛，而是作为内置数据源的补充源写入目标 schema。当前最完整的目标是 `vessel_ais`：自定义 REST 或 WebSocket 源经过确定性 mapping 后写入 AIS raw observations，再通过 `vessels` WebSocket channel 推送给 Earth。
 
+Earth 高精度边界使用同一套目标 schema 机制。`earth_boundary_source` 承接 `earth_admin0_boundaries`、`earth_coastline`、`earth_claim_lines` 三类源的映射结果；完整 GeoJSON / JSON 原文保存为 artifact，数据库只保存 source kind、sha256、feature count、license、artifact path 和 sample properties，避免把大型几何塞进单行记录。
+
 ### 配置语义
 
 关键字段：
@@ -318,7 +320,7 @@ GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=
 - `auth_type`：`none`、`bearer`、`api_key`、`basic`。
 - `headers`：静态请求头。
 - `auth_config`：token、API key、basic 用户名密码，API key 支持 header 或 query。
-- `config.target_schema`：例如 `vessel_ais`。
+- `config.target_schema`：例如 `vessel_ais` 或 `earth_boundary_source`。
 - `config.delivery_mode`：REST 默认 `polling`，WebSocket 默认 `realtime_stream`。
 - `config.merge_target_source`：记录该自定义源补充哪个内置数据，例如 `barentswatch_vessels`。
 

docs/technical/zh/earth-frontend-context.md

@@ -123,12 +123,16 @@ Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/h
 
 - [earth.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/earth.js)
 - [terrain.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/terrain.js)
+- [country-boundaries.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/country-boundaries.js)
 
 职责：
 
 - 地球球体、云层、大气
 - 真实地形 mesh
 - terrain tile 拉取、解码、位移、着色
+- 海陆基座与国界底图的整球 overlay
+
+Earth 地表是多层近似同心球，不是单一 mesh。`earth.js` 的基座球、高清材质 overlay、云层/大气，以及 `country-boundaries.js` 的海陆基座都需要明确半径间距。远距视图下 GPU 深度精度会下降，相邻 shell 过近会 z-fighting，表现为黑色闪烁块或雪花。当前稳定策略是让海陆基座使用 `landAltitudeOffset = 0.32`，高清材质使用 `textureOverlayAltitudeOffset = 0.48`；后续新增或调整整球地表 overlay 时，必须同步检查 [Earth 渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)，并在 50% 缩放视图验证。
 
 ### 7. 图层模块
 

docs/technical/zh/earth-layer-style-reference.md

@@ -26,7 +26,7 @@
 | Earth 基座 specular | `EARTH_MATERIAL_CONFIG.specular` | `0x1a2d45` | `MeshPhongMaterial.specular` |
 | Earth 基座 shininess | `EARTH_MATERIAL_CONFIG.shininess` | `12` | `MeshPhongMaterial.shininess` |
 | Earth 基座 opacity | `EARTH_MATERIAL_CONFIG.opacity` | `1` | `MeshPhongMaterial.opacity` |
-| 高清材质半径偏移 | `EARTH_MATERIAL_CONFIG.textureOverlayAltitudeOffset` | `0.1` | 独立高清材质球半径 |
+| 高清材质半径偏移 | `EARTH_MATERIAL_CONFIG.textureOverlayAltitudeOffset` | `0.48` | 独立高清材质球半径；必须与海陆基座和地球基座保持足够深度间距，避免远距 z-fighting |
 | 高清材质透明度 | `EARTH_MATERIAL_CONFIG.textureOverlayOpacity` | `0.88` | 高清材质 `MeshPhongMaterial.opacity` |
 | 高清材质 renderOrder | `EARTH_MATERIAL_CONFIG.textureOverlayRenderOrder` | `0.96` | `_earthTextureOverlay.renderOrder` |
 | 高清材质 specular | `EARTH_MATERIAL_CONFIG.textureOverlaySpecular` | `0x05080d` | 降低直射区域镜面高光，避免贴图死白 |
@@ -84,11 +84,18 @@
 
 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
 | --- | --- | --- | --- |
-| 国界数据路径 | `COUNTRY_BOUNDARY_CONFIG.dataPath` | `"/earth/data/countries-admin0.min.geojson"` | GeoJSON 输入 |
+| 国界瓦片 manifest | `COUNTRY_BOUNDARY_CONFIG.tileManifestPath` | `"/earth/data/boundaries/v1/manifest.json"` | 必需的生产 PMTiles manifest；缺失即报错 |
+| 国界瓦片 provider | `COUNTRY_BOUNDARY_CONFIG.tileProvider` | `"pmtiles-mvt"` | 国界只接受 PMTiles/MVT |
+| PMTiles 产物路径 | `COUNTRY_BOUNDARY_CONFIG.pmtilesPath` | `"/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles"` | 生产单文件 PMTiles/MVT artifact |
+| MVT 图层名 | `COUNTRY_BOUNDARY_CONFIG.mvtLayerNames` | `boundary_admin0 / boundary_disputed_internal / coastline / claim_line` | PMTiles provider 解码时读取的固定 layer 名 |
+| 国界瓦片基础路径 | `COUNTRY_BOUNDARY_CONFIG.tileBasePath` | `"/earth/data/boundaries/v1/"` | PMTiles manifest 基础路径 |
+| 国界瓦片缩放阈值 | `COUNTRY_BOUNDARY_CONFIG.tileZoomThresholds` | `1.6 -> z5`, `2.8 -> z6`, `3.4 -> z7`, `4.0 -> z8`, `4.6 -> z9`, `5.2 -> z10` | 生产 PMTiles zoom 选择 |
+| 国界瓦片缓存上限 | `COUNTRY_BOUNDARY_CONFIG.tileCacheLimit` | `150` | 前端已加载瓦片几何的 LRU 缓存条目数 |
+| 国界瓦片 debounce | `COUNTRY_BOUNDARY_CONFIG.tileDebounceMs` | `180` | 视野变化后请求可见瓦片前的防抖时间 |
 | 海洋填充色 | local `OCEAN_HEX` | `0x010609` | 海陆基座 canvas 背景 |
 | 陆地填充色 | `COUNTRY_BOUNDARY_CONFIG.landColor` | `0x080f1b` | 海陆基座 canvas 陆地 |
 | 海陆基座透明度 | `COUNTRY_BOUNDARY_CONFIG.landOpacity` | `1.0` | `MeshBasicMaterial.opacity` |
-| 海陆基座半径偏移 | `COUNTRY_BOUNDARY_CONFIG.landAltitudeOffset` | `0.08` | `country-land-ocean` 半径 |
+| 海陆基座半径偏移 | `COUNTRY_BOUNDARY_CONFIG.landAltitudeOffset` | `0.32` | `country-land-ocean` 半径；与地球基座拉开以避免 50% 缩放时雪花/黑块闪烁 |
 | 海陆基座 renderOrder | `COUNTRY_BOUNDARY_CONFIG.landRenderOrder` | `0.86` | `country-land-ocean.renderOrder` |
 | 海陆 mask 尺寸 | `landMaskWidth / landMaskHeight` | `2048 / 1024` | canvas / DataTexture 尺寸 |
 | 国界 tint 颜色 | `COUNTRY_BOUNDARY_CONFIG.tintColor` | `0x0b1830` | 高清材质关闭时 tint |
@@ -97,16 +104,16 @@
 | 国界线颜色 | `COUNTRY_BOUNDARY_CONFIG.lineColor` | `0x7fc7ff` | 普通国界线 |
 | 国界线透明度 | `COUNTRY_BOUNDARY_CONFIG.lineOpacity` | `0.58` | 普通国界线 opacity |
 | 国界线 hover 时压暗透明度 | `COUNTRY_BOUNDARY_CONFIG.dimmedLineOpacity` | `0.18` | hover 时普通国界线 opacity |
-| 国界线半径偏移 | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.115` | 普通国界线半径；略高于高清材质 `0.10`，低于地形基准 `0.16`，减少悬浮感 |
+| 国界线半径偏移 | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.115` | 普通国界线半径；线层靠 renderOrder 和独立 geometry 叠加，不作为整球基座深度间距参考 |
 | 国界线 renderOrder | `COUNTRY_BOUNDARY_CONFIG.lineRenderOrder` | `2.2` | 普通国界线层级 |
 | 国界 hover 颜色 | `COUNTRY_BOUNDARY_CONFIG.hoverLineColor` | `0xff3b1f` | 霓虹红橘 |
 | 国界 hover 透明度 | `COUNTRY_BOUNDARY_CONFIG.hoverLineOpacity` | `1.0` | hover 实线 opacity |
-| 国界 hover 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.14` | hover 实线半径；贴近地表但高于普通国界线 |
+| 国界 hover 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.115` | hover 实线半径；与普通国界线同源几何对齐，避免高亮切换时出现重影 |
 | 国界 hover renderOrder | `COUNTRY_BOUNDARY_CONFIG.hoverLineRenderOrder` | `2.3` | hover 实线层级 |
 | 国界 hover glow 透明度 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowOpacity` | `0.38` | glow 线 opacity |
 | 国界 hover glow 线宽 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowLineWidth` | `3` | glow `LineBasicMaterial.linewidth` |
 | 国界 hover glow 层级偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRenderOrderOffset` | `0.01` | glow renderOrder = `2.29` |
-| 国界 hover glow 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRadiusOffset` | `0.04` | glow 半径 = hover 半径 + 0.04 |
+| 国界 hover glow 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowRadiusOffset` | `0` | glow 与 hover 实线共用半径，避免海岸细节处双线错位 |
 
 ## 真实地形
 

docs/technical/zh/earth-render-layer-order.md

@@ -18,15 +18,15 @@
 | -1 | Earth 遮挡球 | `earth.js` | 地球内侧不可见球 | 写入深度 | 遮挡地球背面的对象。 |
 | 0 | Earth 基座球 | `earth.js` | `CONFIG.earthRadius` | 地表拾取兜底目标 | 深色基座，所有可选地图层关闭时仍可见。 |
 | 0.2 | 国界暗色 tint | `country-boundaries.js` | `tintAltitudeOffset` | 禁用 raycast | 高清材质关闭时使用。 |
-| 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用。 |
-| 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充。 |
+| 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset = 0.32`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用；半径与基座球拉开以避免远距 z-fighting。 |
+| 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset = 0.48` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充；半径必须高于海陆基座并与基座球保持足够间距。 |
 | 1 | 大气辉光和云图 | `earth.js` | 大气 / 云层球 | 不走普通对象选择路径 | 云图由“大气云图”图层开关控制。 |
 | 1 | 海缆 / 登陆点 | `cables.js` | 海缆线和登陆点都使用 `renderOrder = 1`；半径偏移都为 `0.2`；登陆点是专用 `THREE.Sprite` 黄色扁平球 | 海缆走海缆拾取路径；登陆点 `depthTest: false` 保持球体完整，并用相机到球心的球体遮挡判断避免背面穿透 | 登陆点和海缆同层贴地，避免地表设施层的凌空感。 |
 | 1.2 | 真实地形 | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` 加地形位移 | 禁用 raycast | 地形压过高清材质；高清材质关闭时临时隐藏，重新开启后恢复原状态。 |
 | 2.05 | 经纬线 | `earth.js` | `CONFIG.earthRadius + 0.14` | 禁用 raycast | 低透明度显示在高清材质上。 |
-| 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = 0.115` | `depthTest: true`，禁用 raycast | 略高于高清材质 `0.10`，低于地形基准 `0.16`，减少悬浮感；地形 `depthWrite: false`，所以地形开启时仍可见。 |
+| 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = 0.115` | `depthTest: true`，禁用 raycast | 线层使用独立 line geometry 与 `renderOrder` 控制；地形 `depthWrite: false`，所以地形开启时仍可见。 |
 | 2.29 | 国界 hover 光晕 | `country-boundaries.js` | hover 半径加 glow 偏移 | `depthTest: false`，禁用 raycast | 用 additive 光晕增强交界边和地形开启时的 hover 可见性。 |
-| 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset = 0.14` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；中国和中国（台湾）共享高亮组。 |
+| 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset = 0.115` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；与普通国界线同源半径对齐，避免重影；中国和中国（台湾）共享高亮组。 |
 | 3 | 卫星 footprint 填充 / Iridium coverage ring | `satellites.js`, `iridium-footprint-adapter.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested；Iridium adapter 的 fill / ring 也使用同一 renderOrder | Footprint 在 land / texture / terrain 和国界线之上，但在算力中心和卫星之下。 |
 | 3-4.5 | BGP 观测站、事件扩散圈和事件 marker | `bgp.js`, `interactable.js` | BGP 观测站和事件 marker 均使用 `Interactable` 批量 `THREE.Points`；事件 marker 使用 `BGP_EVENT_RENDER_ORDER = 4.5`；观测站主图标使用 `BGP_COLLECTOR_RENDER_ORDER = 4.4` 和 `BGP_CONFIG.collectorAltitudeOffset = 0.2`；事件 overlay 进入 `bgp-event-overlay-layer`；观测站 halo 和覆盖扇形进入 `bgp-collector-radar-layer` | BGP 事件和观测站都通过 `Interactable` 屏幕空间 picking，并参与同坐标避让 | BGP 观测站主图标与船只同层；BGP 事件与算力中心同层；向外扩散圈、观测站雷达/覆盖动画继续由 BGP 业务逻辑驱动。 |
 | 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
@@ -48,6 +48,17 @@
 | 国界线 off | 只隐藏可交互国界线和 hover，高亮状态会清除；海陆基座填充仍作为 Earth 底图保留。 |
 | 真实卫星高度 off | 卫星点、轨迹和预测轨道都使用旧版同层球面；缺失 TLE 或传播失败的卫星也使用同一 fallback 高度。 |
 
+## 深度间距规则
+
+Earth 的地表不是单一 mesh，而是多层近似同心球：基座球、海陆基座、高清材质、地形、云层、大气和遮挡球。近距看起来只差几个小数的半径偏移，在 50% 这类远距视图下会被深度缓冲压到同一批像素，导致 z-fighting，表现为黑块、雪花或闪烁。
+
+维护规则：
+
+- 不要用“远距隐藏图层”作为第一反应；先检查相邻 shell 的 `altitudeOffset`、`renderOrder`、`depthTest` 和 `depthWrite`。
+- 海陆基座和高清材质这类整球 overlay 必须与 `CONFIG.earthRadius` 保持明确间距；当前稳定值为 `landAltitudeOffset = 0.32`、`textureOverlayAltitudeOffset = 0.48`。
+- 新增整球或近整球地表 overlay 时，必须在 50% 缩放和常用近距视图各截一次图，确认没有黑块、雪花、闪烁，也没有明显漂浮感。
+- 如果必须调整这些半径，需同步更新本文和 `frontend/public/earth/js/constants.js` 的注释/常量意图。
+
 ## 交互规则
 
 | 交互 | 当前规则 |

docs/technical/zh/faq.md

@@ -58,9 +58,9 @@ tasklist /svc /fi "PID eq 4700"
 Stop-Service iphlpsvc -Force
 ```
 
-这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务；新版本 `--allow-lan` 会用临时 Windows relay 暴露 `3000` / `8000`，不再需要保留持久 portproxy。
+这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务；`--allow-lan` 会直接绑定 `3000` / `8000` / `8010`，不再需要保留持久 portproxy。
 
-如果脚本输出 `failed-stop-service`、`failed-stop-process`，或 Vite 报 `Port 3000 is already in use` 后显示 `Windows listener ... services=iphlpsvc`，说明旧的 Windows listener 仍在占用端口。脚本会停止启动，并提示用管理员 PowerShell 检查 `netsh interface portproxy show all`，删除对应 `listenport` 规则；如果没有 portproxy 规则，再用 `netstat` / `tasklist` 确认服务，必要时临时 `Stop-Service iphlpsvc -Force`。清理旧规则后重新运行 `./planet.sh restart --allow-lan`，脚本会启动临时 relay，局域网仍访问 `3000` / `8000`。
+如果脚本输出 `Windows 侧端口 ... 存在监听者`，或 Vite 报 `Port 3000 is already in use` 后显示 `Windows listener ... services=iphlpsvc`，说明旧的 Windows listener 仍在占用端口。脚本会请求管理员 PowerShell 清理对应端口；如果自动清理被取消，再手动检查 `netsh interface portproxy show all`，删除对应 `listenport` 规则。如果没有 portproxy 规则，再用 `netstat` / `tasklist` 确认服务，必要时临时 `Stop-Service iphlpsvc -Force`。清理旧规则后重新运行 `./planet.sh restart --allow-lan`，局域网仍访问 `3000` / `8000` / `8010`。
 
 ### 默认端口冲突时应该改哪些参数？
 
@@ -89,6 +89,7 @@ Stop-Service iphlpsvc -Force
 # 在 WSL 或运行 Planet 的 shell 中
 curl http://localhost:3000
 curl http://localhost:8000/health
+curl http://localhost:8010/health
 ```
 
 再到 Windows PowerShell 验证：
@@ -96,6 +97,7 @@ curl http://localhost:8000/health
 ```powershell
 curl http://localhost:3000
 curl http://localhost:8000/health
+curl http://localhost:8010/health
 ```
 
 如果 WSL 和 Windows localhost 都通，但手机或其他电脑访问不通，再考虑局域网开放：
@@ -110,16 +112,18 @@ curl http://localhost:8000/health
 ./planet.sh restart -f 3000 --allow-lan
 ```
 
-如果 `ss -ltnp` 显示前端已经监听 `0.0.0.0:3000`，但 Windows PowerShell 中 `Test-NetConnection <Windows局域网IP> -Port 3000` 仍失败，问题通常不在 Vite 或 `.zshrc`，而是在 Windows 侧转发或防火墙。
+如果 `ss -ltnp` 显示前端已经监听 `0.0.0.0:3000`，但 Windows PowerShell 中 `Test-NetConnection <Windows局域网IP> -Port 3000` 仍失败，问题通常不在 Vite 或 `.zshrc`，而是在 Windows 侧端口占用、旧 `portproxy` 或防火墙。
 
-传统 WSL NAT 场景下，`./planet.sh start --allow-lan` 会启动临时 Windows relay，让 Windows 对外仍使用 `3000` / `8000`。脚本会在启动前检测并请求管理员 PowerShell 删除旧 `portproxy`，也会检测 Windows 防火墙规则；如果缺少 `3000` / `8000` 入站放行，会触发一次 UAC 管理员 PowerShell 请求来自动创建。若自动请求被取消，可以手动清理：
+`./planet.sh start --allow-lan` 会直接开放 `3000` / `8000` / `8010`，并在启动前检测端口、旧 `portproxy` 和 Windows 防火墙规则。端口被 Windows 侧 listener 占用时，脚本会请求管理员 PowerShell 清理；缺少入站放行时，也会触发一次 UAC 管理员 PowerShell 请求来自动创建。若自动请求被取消，可以手动清理：
 
 ```powershell
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
+netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
 
 New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
 New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
 ```
 
 局域网设备访问 Windows 对外端口，例如 `http://<Windows局域网IP>:3000/earth`。
@@ -129,6 +133,7 @@ New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Al
 ```powershell
 New-NetFirewallHyperVRule -Name "Planet-Frontend-3000" -DisplayName "Planet Frontend 3000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 3000 -Action Allow
 New-NetFirewallHyperVRule -Name "Planet-Backend-8000" -DisplayName "Planet Backend 8000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8000 -Action Allow
+New-NetFirewallHyperVRule -Name "Planet-AIProvider-8010" -DisplayName "Planet AI Provider 8010" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8010 -Action Allow
 ```
 
 也可以用下面命令确认当前 Hyper-V firewall 状态：

docs/technical/zh/ops-planet-sh-startup.md

@@ -155,7 +155,7 @@ wait_for_port_release() {
 - `PORT_PRESTART_RETRIES`：默认 3 次。
 - `PORT_PRESTART_RETRY_INTERVAL`：默认 2 秒。
 
-`kill_port_if_requested()` 优先清理当前环境能找到的监听 PID；只有检测到当前运行在 WSL 且没有可杀 PID、但端口仍不可绑定时，才会检查 Windows 侧 listener，并尝试通过 PowerShell 停止对应服务或强制结束对应进程。若没有权限，或 `iphlpsvc` 这类系统服务拒绝停止，脚本会打印 Windows listener 详情和管理员 PowerShell 处理命令，然后立即停止启动，不再继续拉起服务碰同一个端口错误。前端 Vite 启动后才发现 `Port 3000 is already in use` 时，也会打印同一套 Windows listener 处理命令。非 WSL 环境不会尝试 Windows 清理路径。`--allow-lan` 在 WSL 下会使用临时 Windows relay 暴露 `3000` / `8000`，所以旧的持久 portproxy 规则应清理掉。
+`kill_port_if_requested()` 优先清理当前环境能找到的监听 PID；只有检测到当前运行在 WSL 且没有可杀 PID、但端口仍不可绑定时，才会检查 Windows 侧 listener，并请求管理员 PowerShell 删除旧 `portproxy`、停止占用端口的服务或强制结束对应进程。若管理员请求被取消，或 `iphlpsvc` 这类系统服务拒绝停止，脚本会打印 Windows listener 详情和管理员 PowerShell 处理命令，然后立即停止启动，不再继续拉起服务碰同一个端口错误。前端 Vite 启动后才发现 `Port 3000 is already in use` 时，也会打印同一套 Windows listener 处理命令。非 WSL 环境不会尝试 Windows 清理路径。`--allow-lan` 直接开放 `3000` / `8000` / `8010`，不再启动额外的 Windows 端口转发进程；旧的持久 portproxy 规则应清理掉。
 
 ## 问题三：端口检测用 Python
 

docs/technical/zh/ops-runbook.md

@@ -120,7 +120,7 @@
 - 手机或平板演示 Earth
 - 局域网其他机器访问同一开发实例
 
-`--allow-lan` 只负责让前端和后端监听 `0.0.0.0`。WSL 中运行时，Windows 本机一般可以通过 `localhost` 访问，但局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 端口转发和防火墙放行。
+`--allow-lan` 会让前端、后端和 AI Provider 直接对开发机开放：前端 `3000`、后端 `8000`、AI Provider `8010`。脚本启动前会检查这三个端口；如果 WSL/Linux 侧无法释放端口，并检测到 Windows 侧 listener 或旧 `portproxy`，会请求管理员 PowerShell 清理。WSL 中运行时，Windows 本机一般可以通过 `localhost` 访问，局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 防火墙放行。
 
 建议按顺序排查：
 
@@ -128,20 +128,23 @@
 # 在运行 Planet 的 shell 中
 curl http://localhost:3000
 curl http://localhost:8000/health
-ss -ltnp | grep -E ':3000|:8000'
+curl http://localhost:8010/health
+ss -ltnp | grep -E ':3000|:8000|:8010'
 ```
 
-如果看到 WSL 内部服务已经启动，但局域网 IP 仍访问失败，让 `./planet.sh start --allow-lan` 启动临时 Windows relay。relay 会让 Windows 对外继续使用 `3000` / `8000`，并在 WSL 目标端口断开后自动退出。脚本会检测并请求管理员 PowerShell 删除旧 `portproxy`，也会检测 Windows 防火墙规则；缺少入站放行时会触发一次 UAC 管理员 PowerShell 请求自动创建。手动兜底命令如下：
+如果服务已经启动但局域网 IP 仍访问失败，优先清理旧 `portproxy` 并确认 Windows 防火墙放行。脚本会自动检测并请求管理员 PowerShell 处理；自动请求被取消时，手动兜底命令如下：
 
 ```powershell
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
+netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
 
 New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
 New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
 ```
 
-局域网设备访问 Windows 对外端口，例如 `http://<Windows局域网IP>:3000/earth`。
+局域网设备访问 Windows 对外端口，例如 `http://<Windows局域网IP>:3000/earth`、`http://<Windows局域网IP>:8000/health`、`http://<Windows局域网IP>:8010/health`。
 
 ## AI Provider 环境变量与构建
 
@@ -238,6 +241,16 @@ uv sync
 uv run pytest backend/tests/test_otp_service.py
 ```
 
+## Earth 国界 PMTiles 操作步骤
+
+1. 在后台 Collector Settings 中分别配置 `Earth Admin-0 国界源`、`Earth 海岸线源`、`Earth 主张线源` 的 endpoint、headers/auth、`config.target_schema=earth_boundary_source`、license 和 mapping。
+2. 在数据源页依次采集这三个源。每个源成功后会保存完整 artifact 到 `data/earth-boundary-sources/<collector>/<sha256>.*`，并写入 sha256、feature count、artifact path、sample properties。
+3. 三个源都成功后，再采集 `Earth PMTiles 构建器`。缺任一源时它会失败为“未就绪”，不会更新 Earth 国界。
+4. 构建器需要本机 PATH 里有 `tippecanoe` 和 `pmtiles`。缺工具时任务失败并显示缺失工具。
+5. 生产构建成功后应输出 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles` 和对应 manifest。
+6. 部署后打开 Earth，开启“国界线”，放大中国东南海岸、台湾、海南、南海、藏南、科索沃、加沙等区域验证 hover 和边界口径。
+7. 如果 PMTiles 加载失败，Earth 会报国界图层错误并且不绘制旧低精度国界。排查顺序是：浏览器 Network 是否有 PMTiles range 请求、manifest 的 `tileProvider` 是否为 `pmtiles-mvt`、Nginx 是否能静态返回 `.pmtiles`、artifact 路径和 sha256 是否与 manifest 一致。
+
 ## 相关文档
 
 - [planet.sh 启动机制](/home/ray/dev/linkong/planet/docs/technical/zh/ops-planet-sh-startup.md)

docs/version-history.md

@@ -16,12 +16,13 @@
 ## Current Version
 
 - `main` 当前主线历史推导到：`0.16.5`
-- `dev` 当前开发分支历史推导到：`0.57.0`
+- `dev` 当前开发分支历史推导到：`0.58.0`
 
 ## Timeline
 
 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.58.0` | feature | `dev` | `pending` | Earth 高精度国界切换到 PMTiles/MVT 和标准源采集器，移除旧低精度兜底，修复远距地表 z-fighting 雪花/黑块，并补齐新闻目标地点队列与文档 |
 | `0.57.0` | feature | `dev` | `pending` | WSL `--allow-lan` 新增临时 Windows relay，保持 localhost 与局域网同用 3000/8000，并自动处理旧 portproxy、防火墙授权和 Vite ESM 配置 |
 | `0.56.0` | feature | `dev` | `pending` | 修复 Earth 卫星 ECI/TEME 到 ECF 坐标转换和闭合预测轨道，调校真实高度压缩上限，统一 BGP 光晕色调，并更新超算图标与 Earth HUD/新闻体验 |
 | `0.55.0` | feature | `dev` | `pending` | Earth 卫星新增真实高度压缩显示开关，轨迹和预测轨道跟随高度模式切换，并补齐设置面板、FAQ、用户手册和开发者文档 |