release: bump version to 0.43.0

2026-04-28 16:10:17 +08:00
parent 1cd2dab0ee
commit ac69d5d354
69 changed files with 6954 additions and 1141 deletions
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,21 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`

+## [0.43.0] — 2026-04-28
+
+### ✨ Highlights
+- 新增 Earth 船舶追踪链路，接入 BarentsWatch AIS 凭证配置、采集器、后端 vessel 模型/API 与前端 Earth 船舶图层
+- 新增自定义数据源映射流程，支持样本抓取、目标 schema、AI 辅助生成映射、预览校验和映射执行
+- Settings 拆分 AI Provider 与采集器凭证配置，DataSources 只保留采集状态、运行参数和必要引导
+
+### 🔧 Improvements
+- AI Provider 支持运行时 LLM 配置、provider preset 下拉与刷新，并在 Playground 中引导到 AI 配置页
+- Markdown 渲染器补齐代码块复制按钮、语言标签、任务列表、图片、自动链接、删除线和文档主题样式
+- Docs 公开导航改为显式元数据白名单，避免开发任务文档自动出现在“其他”分组
+- 将 Codex/Claude cleanup、docs、goal-driven、release 流程补充 CLI-first 约束，并把 `rules.md` 整理成可按模块加载的工程规则
+
+---
+
 ## [0.42.2] — 2026-04-28

 ### 🐛 Fixes
--- a/docs/plans/datasource-custom-api-mapping-plan.md
+++ b/docs/plans/datasource-custom-api-mapping-plan.md
@@ -0,0 +1,424 @@
+# 自定义 API 数据源与 LLM 映射系统 — 实施计划
+
+**状态**：规划中
+**创建日期**：2026-04-28
+**核心原则**：LLM 辅助生成映射配置；生产采集使用确定性转换引擎
+
+## 已确认决策
+
+| 项目 | 决策 |
+|-----|------|
+| 自定义 API 的定位 | 作为内置数据源的补充入口，不直接等同于 Earth 新功能 |
+| LLM 的职责 | 探索未知 API、分析样本 JSON、生成 mapping 草案 |
+| 采集时是否调用 LLM | 不调用；采集链路必须确定性、可审计、可复现 |
+| 自定义数据如何进入 Earth | 必须映射到已支持的目标 schema，或先进入通用数据沉淀 |
+| 外部凭证放置位置 | Settings / 外部集成统一管理 provider token；DataSources 引用 provider profile |
+| TimescaleDB | 放入 TODO；高频时序数据稳定后再评估迁移 |
+
+---
+
+## 一、背景与问题
+
+当前系统已经有 `datasource_configs`，可以配置自定义数据源的 endpoint、auth、headers、config，也已经有部分 collector 会读取这些配置。但这只能解决“怎么请求数据”，还没有解决以下问题：
+
+- API 返回 JSON 后，如何转换成系统已有领域模型。
+- 自定义数据源是补充已有能力，还是全新数据沉淀。
+- 转换规则由谁生成、谁校验、谁执行。
+- 未知数据是否能自动在 Earth 上展示。
+- 外部 token 是放在全局配置中心，还是放在每个 datasource 下。
+
+专业做法是把“请求配置”“外部凭证”“目标 schema”“字段映射”“采集执行”拆开：
+
+- Settings 管外部集成凭证，例如 AI Provider、BarentsWatch、未来付费 AIS API。
+- DataSources 管具体数据源实例，例如 endpoint、调度频率、目标 schema、mapping 版本。
+- LLM 只在配置阶段辅助生成 mapping，不进入生产采集链路。
+- Earth 只消费明确 schema 的数据，不消费任意未知 JSON。
+
+---
+
+## 二、目标架构
+
+### 2.1 自定义 API 数据源生命周期
+
+```mermaid
+flowchart LR
+    A[配置 endpoint/auth/request] --> B[抓取 sample JSON]
+    B --> C[选择目标 schema]
+    C --> D[LLM 生成 mapping 草案]
+    D --> E[确定性 mapping engine 预览]
+    E --> F[schema validation]
+    F --> G[保存 mapping version]
+    G --> H[scheduler 执行 mapped collector]
+    H --> I[写入目标表或 generic_records]
+```
+
+### 2.2 目标 schema 分层
+
+| schema | 用途 | Earth 可视化 |
+|-------|------|-------------|
+| `vessel_ais` | 船只 AIS 位置、航速、航向、MMSI 等 | 进入船舶图层 |
+| `geo_points` | 通用点位数据，包含经纬度、名称、类型、时间 | 进入通用 geo layer（TODO） |
+| `news_events` | 新闻/事件类数据，带时间、地点、摘要、来源 | 复用新闻/事件链路 |
+| `compute_centers` | 算力中心、机房、数据中心数据 | 复用算力中心图层 |
+| `generic_records` | 未知结构化数据沉淀 | 不直接展示 |
+
+v1 建议优先实现：
+
+- `vessel_ais`
+- `geo_points`
+- `generic_records`
+
+其他 schema 可先在 registry 中预留名称，但不承诺完整落库与可视化。
+
+### 2.3 LLM 的边界
+
+LLM 可以做：
+
+- 根据 API 文档或 sample JSON 解释字段含义。
+- 推荐目标 schema。
+- 生成 mapping JSON 草案。
+- 给出字段置信度和需要人工确认的字段。
+- 帮用户发现分页、数组路径、时间字段、坐标字段。
+
+LLM 不应该做：
+
+- 在正式采集时参与每批数据转换。
+- 生成并执行 Python/JavaScript 代码。
+- 接触 API key、bearer token、basic auth password。
+- 自动创建新的 Earth 图层或数据库表。
+
+---
+
+## 三、后端实施计划
+
+### Phase 1 — Target Schema Registry
+
+新增代码级 registry，统一描述系统支持的目标数据类型。
+
+每个 target schema 至少包含：
+
+- `key`：例如 `vessel_ais`。
+- `label`：前端展示名称。
+- `description`：适用场景。
+- `fields`：字段名、类型、是否必填、说明、示例。
+- `validator`：Pydantic 或等价校验器。
+- `destination`：写入目标，例如 vessel 表、generic_records、future geo layer。
+
+示例概念：
+
+```json
+{
+  "key": "vessel_ais",
+  "fields": [
+    {"name": "mmsi", "type": "integer", "required": true},
+    {"name": "lat", "type": "float", "required": true},
+    {"name": "lon", "type": "float", "required": true},
+    {"name": "sog", "type": "float", "required": false},
+    {"name": "cog", "type": "float", "required": false},
+    {"name": "received_at", "type": "datetime", "required": false}
+  ]
+}
+```
+
+### Phase 2 — Mapping Template Model
+
+新增 mapping 配置持久化表，建议命名为 `datasource_mapping_templates`。
+
+关键字段：
+
+- `id`
+- `datasource_config_id`
+- `target_schema`
+- `mapping_json`
+- `sample_payload_hash`
+- `validation_status`
+- `version`
+- `is_active`
+- `created_at`
+- `updated_at`
+
+`mapping_json` 是声明式 DSL，不允许任意代码执行。
+
+示例：
+
+```json
+{
+  "source": {
+    "items_path": "$.data.vessels[*]"
+  },
+  "fields": {
+    "mmsi": {"path": "$.mmsi", "type": "integer"},
+    "lat": {"path": "$.latitude", "type": "float"},
+    "lon": {"path": "$.longitude", "type": "float"},
+    "sog": {"path": "$.speedOverGround", "type": "float", "default": null},
+    "received_at": {"path": "$.timestamp", "type": "datetime"}
+  }
+}
+```
+
+### Phase 3 — Deterministic Mapping Engine
+
+实现独立 mapping engine，输入 sample/raw payload 和 mapping JSON，输出目标 schema 记录。
+
+v1 支持能力：
+
+- JSONPath/JMESPath 风格路径提取。
+- 数组展开。
+- 默认值。
+- 基础类型转换：string、integer、float、boolean、datetime。
+- 坐标范围校验。
+- 简单枚举映射。
+- 错误收集：缺字段、类型转换失败、路径不存在。
+
+明确不支持：
+
+- 任意表达式执行。
+- 用户提交脚本。
+- LLM runtime 修复。
+
+### Phase 4 — LLM Mapping Assistant API
+
+新增配置阶段 API：
+
+- `POST /api/v1/datasources/custom/sample`
+  - 按 datasource 请求配置抓取 sample JSON。
+- `GET /api/v1/datasources/target-schemas`
+  - 返回可选目标 schema 和字段说明。
+- `POST /api/v1/datasources/mappings/propose`
+  - 输入 sample JSON + target schema，调用 AI provider 生成 mapping 草案。
+- `POST /api/v1/datasources/mappings/preview`
+  - 使用确定性 mapping engine 预览转换结果。
+- `POST /api/v1/datasources/mappings`
+  - 保存 mapping 版本。
+- `PUT /api/v1/datasources/mappings/{id}`
+  - 更新 mapping，生成新版本或覆盖草稿。
+- `POST /api/v1/datasources/{id}/run-mapped`
+  - 手动触发一次 mapped collector。
+
+安全要求：
+
+- `propose` 请求发送给 LLM 前必须脱敏 sample。
+- auth headers、token、password 不进入 prompt。
+- LLM 返回结果必须再经过 mapping schema 校验。
+
+### Phase 5 — Generic Mapped HTTP Collector
+
+新增通用 collector：
+
+- 读取 `DataSourceConfig` 请求配置。
+- 读取 active mapping template。
+- 拉取 API 数据。
+- 使用 mapping engine 转换。
+- 使用 target schema validator 校验。
+- 调用 destination handler 写入目标表或 generic storage。
+- 将失败记录写入错误日志或 dead-letter 结构。
+
+对于 `generic_records`：
+
+- 保存 datasource id。
+- 保存 target schema。
+- 保存 normalized JSON。
+- 保存 raw payload 摘要或 raw reference。
+- 保存采集时间、source timestamp、mapping version。
+
+---
+
+## 四、前端实施计划
+
+### Phase 1 — Settings 外部集成
+
+Settings 中保留统一外部集成配置：
+
+- AI Provider：base URL、model、API key。
+- BarentsWatch：client id/client secret 或 bearer token。
+- 未来付费接口：AISHub、MarineTraffic、VesselFinder 等 provider profile。
+
+DataSources 不直接管理全局 secret，只引用 provider profile。
+
+### Phase 2 — DataSources 自定义源向导
+
+自定义数据源配置改成向导或右侧 drawer：
+
+1. Request
+   - endpoint
+   - method
+   - auth profile
+   - headers
+   - query/body config
+   - schedule
+2. Sample
+   - 点击抓取 sample
+   - 展示 JSON tree
+   - 支持选择数组根路径
+3. Target Schema
+   - 选择 `vessel_ais`、`geo_points`、`generic_records`
+   - 展示该 schema 必填字段
+4. Mapping Proposal
+   - 调用 LLM 生成 mapping 草案
+   - 显示字段匹配置信度
+   - 标出需要人工确认的字段
+5. Preview
+   - 用确定性 engine 预览前 N 条转换结果
+   - 展示校验错误
+6. Save & Enable
+   - 保存 mapping version
+   - 启用调度或仅保存草稿
+
+### Phase 3 — 运维视图
+
+为 mapped datasource 展示：
+
+- 上次运行时间。
+- 成功记录数。
+- 失败记录数。
+- 当前 mapping version。
+- 目标 schema。
+- 最近错误。
+- 手动运行按钮。
+
+---
+
+## 五、数据库与存储策略
+
+### v1：继续使用 PostgreSQL
+
+PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基础时序查询。v1 不必因为“时序数据”立刻引入 TimescaleDB。
+
+适合继续用 PostgreSQL 的场景：
+
+- 数据量可控。
+- 最近状态查询为主。
+- 历史保留窗口较短。
+- 查询模式还没稳定。
+- 需要快速迭代 schema 与 mapping。
+
+### TODO：TimescaleDB
+
+以下条件满足后，再评估 TimescaleDB：
+
+- AIS、遥测、轨迹类数据达到高频持续写入。
+- 需要按时间窗口做聚合、降采样、retention policy。
+- 单表时间序列查询明显成为瓶颈。
+- 历史轨迹保留从 24h 扩展到数周或数月。
+
+候选迁移对象：
+
+- `vessel_position`
+- future telemetry tables
+- future generic time-series records
+
+备选方案：
+
+- PostgreSQL 原生按天/月分区。
+- TimescaleDB hypertable。
+- 热数据 PostgreSQL，冷数据对象存储。
+
+---
+
+## 六、安全与治理
+
+### Secret 管理
+
+- Settings 中保存 provider credentials。
+- API 返回配置时必须 mask secret。
+- LLM prompt 只能包含脱敏 sample 和 schema 说明。
+- 后续 TODO：引入字段级加密或 KMS。
+
+### Mapping 治理
+
+- 每次 mapping 变更保留版本。
+- active mapping 只能有一个。
+- 允许保存 draft mapping。
+- 运行记录关联 mapping version。
+- 校验失败不能自动启用。
+
+### 错误处理
+
+常见错误类型：
+
+- API 401/403：凭证错误或过期。
+- API 429：限流，需要调整 schedule。
+- JSON path 不存在：上游结构变化。
+- 类型转换失败：mapping 规则错误。
+- schema validation failed：转换结果不满足目标模型。
+
+每次运行需要记录：
+
+- datasource id。
+- mapping version。
+- started_at / finished_at。
+- fetched count。
+- mapped count。
+- written count。
+- failed count。
+- error summary。
+
+---
+
+## 七、测试计划
+
+### Backend Unit Tests
+
+- mapping engine：
+  - path 提取。
+  - 数组展开。
+  - 默认值。
+  - 类型转换。
+  - datetime parse。
+  - 枚举映射。
+  - 缺字段错误。
+- target schema registry：
+  - `vessel_ais` 必填字段校验。
+  - `geo_points` 经纬度范围校验。
+  - `generic_records` 接受未知结构。
+- LLM assistant：
+  - mock provider 返回 mapping。
+  - 验证 secret 不进入 prompt。
+  - 验证非法 mapping 被拒绝。
+
+### Backend Integration Tests
+
+- sample JSON -> propose mapping -> preview -> save mapping。
+- mapped collector 使用保存的 mapping 写入 `generic_records`。
+- `vessel_ais` sample 写入船舶相关目标结构。
+- 上游 JSON 结构变化时，运行失败并记录错误。
+
+### Frontend Tests
+
+- 自定义数据源向导完整流程。
+- 未配置 AI Provider 时，提示去 Settings 配置，但允许手写 mapping。
+- LLM 返回不完整 mapping 时，Preview 阶段显示校验错误。
+- 保存 mapping 后展示 active version 和运行状态。
+
+---
+
+## 八、分期工作量
+
+| 阶段 | 内容 | 估算 |
+|-----|------|------|
+| Phase 0 | 完成本规划、确认 schema registry 设计 | 0.5 天 |
+| Phase 1 | target schema registry + mapping template model | 1–2 天 |
+| Phase 2 | deterministic mapping engine | 2–3 天 |
+| Phase 3 | sample/propose/preview/save API | 2–3 天 |
+| Phase 4 | DataSources 自定义源向导 | 3–5 天 |
+| Phase 5 | generic mapped collector + run history | 2–4 天 |
+| Phase 6 | vessel_ais / geo_points destination handler | 2–4 天 |
+
+---
+
+## 九、当前差距与下一步
+
+当前差距：
+
+- `datasource_configs` 只描述请求配置，不描述目标 schema 和 mapping。
+- 自定义源没有 sample -> schema -> mapping -> preview -> save 的闭环。
+- 生产采集还没有通用 mapped collector。
+- Settings 与 DataSources 的职责边界需要在 UI 上进一步明确。
+- Earth 还没有通用 `geo_points` 图层。
+
+下一步建议：
+
+1. 先实现 target schema registry 和 mapping engine，不急着接 LLM。
+2. 用固定 sample JSON 做 `vessel_ais` 和 `generic_records` 的单元测试。
+3. 再接 LLM propose API，让 LLM 产出的只是 mapping 草案。
+4. 最后做前端向导，把人工确认和 preview 放到启用之前。
--- a/docs/plans/earth-vessel-tracking-plan.md
+++ b/docs/plans/earth-vessel-tracking-plan.md
@@ -0,0 +1,272 @@
+# 实时船只监控系统 — 实施计划
+
+**状态**：规划中
+**创建日期**：2026-04-27
+**优先数据源**：BarentsWatch（免费）→ AISHub / MarineTraffic（TODO，付费）
+
+## 已确认决策
+
+| 项目 | 决策 |
+|-----|------|
+| 数据源 | BarentsWatch 先行；AISHub / MarineTraffic TODO |
+| 船只规模 | BarentsWatch 阶段全部显示；全球数据接入后按需加船型过滤（默认 Cargo + Tanker + Passenger） |
+| 更新频率 | 准实时：前端 5 分钟轮询，后端 Collector 每分钟拉取写库 |
+| 历史轨迹 | 保留（`vessel_position` 表保留 24h，后期按需扩展） |
+| 推送方式 | HTTP 轮询（不用 WebSocket）；换实时数据源后再评估升级 |
+
+---
+
+## 一、技术背景
+
+船只通过 AIS（自动识别系统）每 2–10 秒广播位置、航速、航向、目的地等信息。全球约 50 万艘持证船只在线，实时数据通过以下方式获取：
+
+| 来源类型 | 典型服务 | 覆盖范围 | 成本 | 状态 |
+|---------|---------|---------|------|------|
+| **BarentsWatch Open API** | live.ais.barentswatch.no | 挪威海域实时 | 完全免费 | **当前使用** |
+| **AISHub** | aishub.net | 全球实时 | 免费/小额 | TODO：付费接入 |
+| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | TODO：评估 tier |
+| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | TODO：备选 |
+| **自建 SDR 接收** | RTL-SDR + AIS-catcher | 仅本地 30–50km | 硬件 $30 | 不考虑 |
+| **NOAA 历史数据** | Marine Cadastre | 美国近海历史 | 免费 | 可用于冷启动 |
+
+### BarentsWatch API
+
+- 端点：`https://live.ais.barentswatch.no/v1/latest/combined`
+- 无需注册，直接 GET，返回挪威近海 2000–5000 艘船只 JSON
+- 字段：mmsi, lat, lon, sog, cog, heading, nav_status, name, vessel_type, flag
+- 刷新频率：数据约 30–60s 更新一次，可随意轮询
+
+### TODO：付费数据源接入
+
+- [ ] 评估 AISHub 订阅（全球覆盖，约 $30/月），接入全球实时流
+- [ ] 评估 MarineTraffic API tier，对比 AISHub 数据质量与成本
+- [ ] 实现多数据源适配器，通过 `datasource_config` 切换
+- [ ] 真实高频 AIS 稳定接入后，评估将 `vessel_position` 迁移为 TimescaleDB hypertable（保留 Postgres 原生分区作为备选）
+
+---
+
+## 二、实施计划
+
+### Phase 0 — 数据源验证与链路打通（1–2 天）
+
+- 接入 BarentsWatch Open API，验证数据格式与字段
+- 构建全球 mock 数据生成器（用于前端渲染压测，补充 BarentsWatch 的地域限制）
+- 确认前端可渲染船只点，整条链路走通
+
+### Phase 1 — 后端基础设施（3–4 天）
+
+#### 1.1 数据库 Schema
+
+```sql
+-- 船只静态信息（每 6h 刷新一次）
+CREATE TABLE vessel_static (
+    mmsi          BIGINT PRIMARY KEY,
+    name          VARCHAR(128),
+    callsign      VARCHAR(16),
+    vessel_type   SMALLINT,
+    vessel_type_name VARCHAR(64),
+    flag          VARCHAR(4),         -- ISO 国家码
+    length        FLOAT,
+    width         FLOAT,
+    draught       FLOAT,
+    imo           BIGINT,
+    updated_at    TIMESTAMPTZ
+);
+
+-- 船只实时位置（高频写入，保留 24h 轨迹）
+CREATE TABLE vessel_position (
+    id            BIGSERIAL PRIMARY KEY,
+    mmsi          BIGINT NOT NULL,
+    lat           FLOAT NOT NULL,
+    lon           FLOAT NOT NULL,
+    sog           FLOAT,              -- Speed over ground（节）
+    cog           FLOAT,              -- Course over ground（度）
+    heading       SMALLINT,           -- 真北航向
+    nav_status    SMALLINT,           -- 0=航行 1=锚泊 5=停靠 ...
+    received_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_vessel_pos_mmsi_time ON vessel_position(mmsi, received_at DESC);
+CREATE INDEX idx_vessel_pos_time      ON vessel_position(received_at DESC);
+
+-- 最新位置物化视图（地图渲染主数据源，避免全表扫描）
+CREATE MATERIALIZED VIEW vessel_latest AS
+SELECT DISTINCT ON (mmsi)
+    vp.*, vs.name, vs.vessel_type_name, vs.flag, vs.length
+FROM vessel_position vp
+LEFT JOIN vessel_static vs USING (mmsi)
+ORDER BY mmsi, received_at DESC;
+
+CREATE UNIQUE INDEX ON vessel_latest(mmsi);
+```
+
+> 后期如需完整历史轨迹查询，迁移 `vessel_position` 到 TimescaleDB 或按天分区。
+
+#### 1.2 Collector：VesselAISCollector
+
+文件：`backend/app/services/collectors/vessel_ais.py`
+
+- 继承 `BaseCollector`，注册到 `collector_registry`
+- 轮询间隔：30–60s（由数据源限速决定）
+- 支持多数据源切换，通过 `datasource_config` 配置 URL + API Key
+- 写入逻辑：upsert `vessel_latest`，append `vessel_position`
+- 接入现有调度系统（`scheduler.py`）
+
+#### 1.3 API 端点
+
+```
+GET /api/v1/visualization/geo/vessels
+    ?bbox=lon_min,lat_min,lon_max,lat_max   # 视口裁剪
+    ?type=cargo,tanker,passenger             # 船型过滤
+    ?limit=5000
+→ GeoJSON FeatureCollection（Point）
+
+GET /api/v1/visualization/vessels/{mmsi}           # 单船详情
+GET /api/v1/visualization/vessels/{mmsi}/track     # 历史轨迹（默认 6h）
+    ?hours=6
+→ GeoJSON LineString
+```
+
+GeoJSON Feature 格式：
+
+```json
+{
+  "type": "Feature",
+  "geometry": { "type": "Point", "coordinates": [lon, lat] },
+  "properties": {
+    "mmsi": 123456789,
+    "name": "EVER GIVEN",
+    "vessel_type": 70,
+    "vessel_type_name": "Cargo",
+    "flag": "PA",
+    "sog": 12.4,
+    "cog": 247.0,
+    "heading": 245,
+    "nav_status": 0,
+    "length": 400,
+    "received_at": "2026-04-27T10:00:00Z"
+  }
+}
+```
+
+#### 1.4 更新机制
+
+**HTTP 轮询**（不使用 WebSocket）：
+
+- 前端 `setInterval(fetchVessels, 5 * 60 * 1000)` 定期拉取最新快照
+- 后端 Collector 每 60s 从 BarentsWatch 拉取并写库，`vessel_latest` 物化视图随时可查
+- WebSocket 留给告警/事件驱动场景（BGP、系统通知），不混入周期性位置刷新
+- 换用 AISHub / MarineTraffic 实时流后，届时再评估是否升级为 WebSocket delta push
+
+---
+
+### Phase 2 — 前端渲染（3–4 天）
+
+文件：`frontend/public/earth/js/vessels.js`
+
+#### 2.1 渲染方案
+
+参考现有卫星系统（`satellites.js`）的 InstancedMesh 模式：
+
+- `THREE.InstancedMesh`：每个实例 = 一艘船，矩阵包含位置 + 旋转（朝向 COG）
+- 行进船：三角箭头图标，朝向 COG 方向
+- 静止/锚泊船：圆点图标
+- SVG 图标输出到 `frontend/public/earth/assets/icons/vessel-arrow.svg` 和 `vessel-dot.svg`
+
+#### 2.2 船型颜色规范
+
+| 船型 | 颜色 |
+|-----|------|
+| 货轮 Cargo | `#4A90D9` 蓝 |
+| 油轮 Tanker | `#E85D04` 橙红 |
+| 客船 Passenger | `#06D6A0` 绿 |
+| 渔船 Fishing | `#FFD166` 黄 |
+| 军舰 Military | `#73797E` 灰 |
+| 其他 | `#9B9B9B` 浅灰 |
+| 锚泊/停靠 | 降低饱和度 0.4x |
+
+#### 2.3 LOD（相机距离细节层次）
+
+| 相机距离 | 渲染策略 |
+|---------|---------|
+| > 400 | 仅渲染 top 1000 艘（按数据新鲜度 + 船型优先级） |
+| 200–400 | 渲染 top 5000 艘 |
+| < 200 | 渲染当前视口 bbox 内全部船只 |
+
+前端根据相机位置动态计算 bbox，附加到 API 请求中。
+
+#### 2.4 图层集成
+
+接入现有图层系统，新增"船只"图层项，支持：
+- 图层开/关，状态持久化
+- 子过滤（按船型选择显示哪类，可在图例或设置面板中配置）
+- 与海缆、BGP、卫星层级共存（renderOrder 待定，参考现有层级文档）
+
+#### 2.5 Info Card
+
+复用 `showInfoCard` 机制，点击船只弹出：
+
+```
+EVER GIVEN                              🚢
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+MMSI        123456789
+IMO         9811000
+旗帜        巴拿马 🇵🇦
+船型        散货轮
+当前航速     12.4 kn
+航向        247°
+状态        航行中
+目的地      ROTTERDAM
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[ 查看轨迹 ]   [ MarineTraffic ↗ ]
+```
+
+#### 2.6 轨迹可视化
+
+点击"查看轨迹" → 请求 `/vessels/{mmsi}/track` → 用 `THREE.CatmullRomCurve3` 渲染插值轨迹线，风格与海缆一致。
+
+---
+
+### Phase 3 — 功能完善（2–3 天）
+
+| 功能 | 说明 |
+|-----|------|
+| **船只搜索** | 接入现有搜索面板，按名称 / MMSI 搜索 |
+| **统计 HUD** | 显示当前在线船只数、各类型分布 |
+| **密度热图** | 超低 zoom 时切换为 hex-bin 热力图（避免点云爆炸） |
+| **港口标注** | 加载 WorldPorts 数据集，显示主要港口标记 |
+| **关键水道监控** | 马六甲、霍尔木兹、苏伊士等高亮 + 流量统计 |
+
+---
+
+### Phase 4 — 性能与生产化（2–3 天）
+
+- `vessel_position` 按天分区，7 天自动清理
+- TODO：真实数据量达到百万级/日后，将 `vessel_position` 升级为 TimescaleDB hypertable，配置 retention policy 与压缩策略
+- GeoJSON endpoint 用 Redis 缓存 15s
+- 若需 bbox 精确查询，引入 PostGIS `geography` + `ST_DWithin`
+- InstancedMesh + frustum culling，目标 5 万船只 60fps
+
+---
+
+## 三、工作量估算
+
+| Phase | 内容 | 估计时间 |
+|-------|-----|---------|
+| Phase 0 | 数据源验证、mock | 1–2 天 |
+| Phase 1 | 后端 Schema + Collector + API | 3–4 天 |
+| Phase 2 | 前端渲染（InstancedMesh + 图层 + Info Card） | 3–4 天 |
+| Phase 3 | 搜索 + 统计 + 轨迹 | 2–3 天 |
+| Phase 4 | 性能优化 + 生产数据源接入 | 2–3 天 |
+| **合计** | | **约 2–3 周** |
+
+---
+
+## 四、参考资料
+
+- BarentsWatch AIS API 文档：https://www.barentswatch.no/en/developer/ais-api/
+- MarineTraffic API：https://www.marinetraffic.com/en/ais-api-services
+- AISHub：https://www.aishub.net/api
+- AIS 导航状态码：ITU-R M.1371-5
+- 船型编码（vessel_type）：ITU/IMO AIS Message 5 Type and Cargo
+- WorldPorts 数据集：https://msi.nga.mil/Publications/WPI
--- a/docs/plans/frontend-markdown-renderer-plan.md
+++ b/docs/plans/frontend-markdown-renderer-plan.md
@@ -0,0 +1,97 @@
+# Markdown 渲染器完善计划
+
+## 背景
+
+Planet 控制台当前有三类主要 Markdown 使用场景：
+
+- 文档中心：技术文档、计划文档、运行手册。
+- AI Playground：模型回复、分析结果、代码片段。
+- BGP 简报：由系统生成并保存的态势报告。
+
+这些场景都复用 `frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx`。因此 Markdown 能力应该集中在共享渲染器内完成，页面只负责传入内容、链接转换和布局约束，不能让每篇文档或每个页面手写复制按钮、表格样式、列表样式等交互细节。
+
+## 目标
+
+建设一个稳定、可复用、适合技术文档和 AI 输出的 Markdown 渲染器，优先覆盖常用语法、代码块操作和清晰的阅读样式，并为后续语法高亮、锚点导航、内容安全策略留出接口。
+
+## 成功标准
+
+- 代码块支持 fenced language、语言标签、复制按钮、复制成功状态和横向滚动。
+- 常用块语法稳定渲染：标题 1-6、段落、引用、分割线、表格、无序列表、有序列表、任务列表。
+- 常用行内语法稳定渲染：链接、自动链接、图片、行内代码、粗体、斜体、删除线。
+- 文档中心、AI Playground、BGP 简报继续复用同一个组件，不出现页面级重复实现。
+- 样式在普通业务面板和文档中心都有合理表现，文档中心可以通过 `.docs-markdown` 覆盖主题变量。
+- 前端 TypeScript build 通过，`git diff --check` 无空白错误。
+
+## 当前实施范围
+
+### 第一阶段：共享渲染器补齐
+
+- 在 `MarkdownRenderer` 内解析 fenced code block 的语言信息。
+- 引入 `MarkdownCodeBlock` 子组件，负责语言标签、复制按钮和复制状态。
+- 保留现有 `Scrollbar` 横向滚动能力，避免长代码撑破页面。
+- 扩展标题渲染到 h1-h6，并保留 `getHeadingId` 对文档目录的支持。
+- 扩展列表解析，支持 `-`、`*`、`+`、`1.`、`1)` 和 GitHub 风格任务列表。
+- 扩展行内解析，支持图片、自动链接、删除线。
+
+### 第二阶段：样式统一
+
+- 全局 Markdown 样式覆盖业务场景，保持紧凑、清晰、可扫描。
+- 文档中心用 `.docs-markdown` 适配主题变量，避免硬编码颜色破坏明暗主题。
+- 代码块 toolbar 和 copy button 不依赖具体页面。
+- 图片默认响应式展示，避免超出内容区域。
+
+### 第三阶段：验证
+
+- 使用前端 build 验证 TypeScript 和 Vite 构建。
+- 使用 `git diff --check` 验证补丁格式。
+- 手动检查至少一个文档页中代码块复制按钮、语言标签和表格滚动是否出现。
+
+## 后续增强项
+
+### 语法高亮
+
+当前不新增高亮依赖，避免一次性引入过重运行时代码。后续可以在以下方案中二选一：
+
+- `shiki`：适合文档中心，视觉质量高，但包体和初始化成本更高。
+- `highlight.js`：接入简单，覆盖语言广，但样式控制需要额外约束。
+
+建议当文档代码块数量稳定增加后再引入，并做按需加载或懒加载。
+
+### 更完整 CommonMark 支持
+
+当前渲染器覆盖 Planet 常见内容，不追求完整 CommonMark 兼容。后续如果需要完整规范，建议切换到成熟生态：
+
+- `react-markdown`
+- `remark-gfm`
+- `rehype-sanitize`
+- `rehype-slug`
+
+切换前需要评估：链接转换、目录 ID、现有样式、AI 输出安全策略和包体影响。
+
+### 安全策略
+
+目前渲染器不解析原始 HTML，这是正确默认值。后续如需支持 HTML，必须先明确：
+
+- 是否允许用户输入 Markdown。
+- 是否需要 HTML 白名单。
+- 是否需要 `rehype-sanitize`。
+- 图片和链接是否需要域名策略。
+
+### 文档页能力
+
+可继续补齐：
+
+- 标题锚点悬浮复制。
+- Mermaid 图表。
+- 代码块折叠。
+- 文档内搜索结果定位到代码块。
+- 复制按钮埋点，用于判断文档片段是否真正被使用。
+
+## 维护约束
+
+- Markdown 语法能力优先放在共享渲染器，不在具体文档页面散落实现。
+- 文档内容只表达内容，不承载 UI 行为。
+- 新增 Markdown 能力必须同时考虑文档中心、AI Playground、BGP 简报三个调用方。
+- 不解析原始 HTML，除非同步引入明确的 sanitize 策略。
+- 与主题相关的样式优先走页面容器变量覆盖，不在组件内写死文档中心颜色。
--- a/docs/technical/zh/README.md
+++ b/docs/technical/zh/README.md
@@ -1,4 +1,4 @@
-# Technical Docs
+# 技术文档

 这里放“当前实现和当前结构”的文档，重点回答：

@@ -9,24 +9,24 @@

 适合放入这里的内容：

- Quickstart 和使用手册
+- 快速开始和使用手册
 - 前端上下文
 - Earth 前端结构
- Earth 卫星 footprint 策略
+- Earth 卫星覆盖策略
 - Earth 渲染图层顺序
 - Earth 图层样式属性索引
 - 后端运行控制
- collector 现状
+- 采集器现状
 - 采集格式约定

 ## 使用入口

- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/quickstart.md)：从零启动 Planet 的最短路径
- [manual.md](/home/ray/dev/linkong/planet/docs/technical/manual.md)：控制台、`planet.sh`、Earth 和 Docs 的完整使用手册
+- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)：从零启动 Planet 的最短路径
+- [manual.md](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)：控制台、`planet.sh`、Earth 和 Docs 的完整使用手册

 不适合放入这里的内容：

- 尚未完成的 roadmap
+- 尚未完成的路线图
 - 未来迭代方案
 - 大范围重构计划

--- a/docs/technical/zh/agents-aiprovider.md
+++ b/docs/technical/zh/agents-aiprovider.md
@@ -1,108 +1,108 @@
-# AI Provider Guide
+# AI Provider 指南

-## Overview
+## 概览

-`aiprovider` is the model-adapter service for Planet.
+`aiprovider` 是 Planet 的模型适配服务。

-It isolates model-vendor details from the main backend so the rest of the system can call a stable business API:
+它把模型厂商差异隔离在主后端之外，让系统其它部分可以调用稳定的业务 API：

- Caller service -> `planet backend`
+- 调用方服务 -> `planet backend`
 - `planet backend` -> `aiprovider`
- `aiprovider` -> concrete model provider
+- `aiprovider` -> 具体模型提供方

-The recommended default is:
+推荐默认方式：

- External and cross-service callers use `planet backend`
- Only infrastructure-grade internal jobs call `aiprovider` directly
+- 外部调用方和跨服务调用方统一调用 `planet backend`
+- 只有基础设施级内部任务才直接调用 `aiprovider`

-## Responsibilities
+## 职责边界

-`backend` is responsible for:
+`backend` 负责：

- authentication and authorization
- business-level request shaping
- stable `/api/v1/ai/...` endpoints
- internal service-to-service authentication toward `aiprovider`
+- 身份认证和权限控制
+- 业务层请求整理
+- 稳定的 `/api/v1/ai/...` 接口
+- 面向 `aiprovider` 的内部服务认证

-`aiprovider` is responsible for:
+`aiprovider` 负责：

- model protocol adaptation
- provider selection by `.env`
- timeout and lightweight retry
- request tracing via `X-Request-ID`
+- 模型协议适配
+- 基于 `.env` 选择 provider
+- 超时和轻量重试
+- 通过 `X-Request-ID` 串联请求追踪

-This now follows an OpenClaw-like seam:
+当前配置采用类似 OpenClaw 的拆分方式：

- `AI_PROVIDER` identifies the vendor or logical provider
- `AI_PROVIDER_API` identifies the wire adapter
+- `AI_PROVIDER` 标识厂商或逻辑 provider
+- `AI_PROVIDER_API` 标识实际请求协议适配器

-That split makes MiniMax, Claude-compatible gateways, and self-hosted OpenAI-compatible services easier to model without overloading one config field.
+这个拆分能更清楚地表达 MiniMax、Claude 兼容网关、自托管 OpenAI 兼容服务等情况，避免把所有含义塞进一个配置项。

-## Supported Providers
+## 支持的 Provider

-`aiprovider` currently supports these provider identities:
+`aiprovider` 当前支持以下 provider 标识：

 - `openai`
 - `anthropic`
 - `minimax`
 - `ollama`

-Supported request adapters:
+支持的请求适配器：

 - `openai-completions`
 - `anthropic-messages`
 - `ollama-generate`

-Backward-compatible aliases still accepted:
+仍然兼容的历史别名：

 - `openai_compatible`
 - `anthropic_compatible`
 - `claude_compatible`

-Provider mapping:
+推荐映射关系：

- `vLLM`, `LM Studio`, `One API`: `AI_PROVIDER=openai`, `AI_PROVIDER_API=openai-completions`
- `MiniMax`: `AI_PROVIDER=minimax`, `AI_PROVIDER_API=anthropic-messages`
- Claude-compatible gateways: `AI_PROVIDER=anthropic`, `AI_PROVIDER_API=anthropic-messages`
- `Ollama`: `AI_PROVIDER=ollama`, `AI_PROVIDER_API=ollama-generate`
+- `vLLM`、`LM Studio`、`One API`：`AI_PROVIDER=openai`，`AI_PROVIDER_API=openai-completions`
+- `MiniMax`：`AI_PROVIDER=minimax`，`AI_PROVIDER_API=anthropic-messages`
+- Claude 兼容网关：`AI_PROVIDER=anthropic`，`AI_PROVIDER_API=anthropic-messages`
+- `Ollama`：`AI_PROVIDER=ollama`，`AI_PROVIDER_API=ollama-generate`

-## API Surfaces
+## API 面

-### Main backend API
+### 主后端 API

-Preferred stable entrypoints:
+推荐使用的稳定入口：

 - `GET /api/v1/ai/provider/status`
 - `POST /api/v1/ai/situational-awareness/analyze`

-Authentication:
+认证方式：

 - `Authorization: Bearer <jwt>`

-Optional tracing header:
+可选追踪头：

 - `X-Request-ID: <caller-generated-id>`

-The backend will propagate `X-Request-ID` to `aiprovider` and return the same header in the response.
+后端会把 `X-Request-ID` 透传给 `aiprovider`，并在响应中返回同一个 header。

-### AI provider internal API
+### AI Provider 内部 API

-Internal-only endpoints:
+仅供内部调用的接口：

 - `GET /v1/provider/status`
 - `POST /v1/analyze`

-Authentication:
+认证方式：

 - `X-Provider-Token: <shared-secret>`

-Optional tracing header:
+可选追踪头：

 - `X-Request-ID: <caller-generated-id>`

-## Request Example
+## 请求示例

-### Call through backend
+### 通过后端调用

 ```bash
 curl -X POST http://localhost:8000/api/v1/ai/situational-awareness/analyze \
@@ -127,7 +127,7 @@ curl -X POST http://localhost:8000/api/v1/ai/situational-awareness/analyze \
  }'
 ```

-### Call `aiprovider` directly
+### 直接调用 `aiprovider`

 ```bash
 curl -X POST http://localhost:8010/v1/analyze \
@@ -149,9 +149,9 @@ curl -X POST http://localhost:8010/v1/analyze \
  }'
 ```

-## Response Shape
+## 响应结构

-Both backend and `aiprovider` return the same payload shape:
+后端和 `aiprovider` 返回相同的 payload 结构：

 ```json
 {
@@ -166,15 +166,15 @@ Both backend and `aiprovider` return the same payload shape:
 }
 ```

-Both services also return:
+两个服务都会返回：

 - `X-Request-ID: <id>`

-## Configuration
+## 配置

-### Backend
+### 后端

-Recommended backend `.env`:
+推荐的后端 `.env`：

 ```env
 AI_PROVIDER_SERVICE_URL=http://localhost:8010
@@ -183,21 +183,21 @@ AI_PROVIDER_TIMEOUT_SECONDS=60
 AI_PROVIDER_RETRY_ATTEMPTS=2
 ```

-Reference file:
+参考文件：

 - [backend/.env.example](/home/ray/dev/linkong/planet/backend/.env.example)

 ### AI Provider

-Reference file:
+参考文件：

 - [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)

-Frontend local reference:
+前端本地参考：

 - [frontend/.env.example](/home/ray/dev/linkong/planet/frontend/.env.example)

-Common settings:
+通用配置：

 ```env
 SERVICE_NAME=planet-ai-provider
@@ -208,7 +208,7 @@ AI_HTTP_RETRY_ATTEMPTS=2
 AI_ANALYSIS_SYSTEM_PROMPT=你是态势感知分析助手。请基于输入的上下文、观测与约束，输出结构化、克制、可执行的分析。
 ```

-### OpenAI-compatible example
+### OpenAI 兼容示例

 ```env
 AI_PROVIDER=openai
@@ -218,7 +218,7 @@ AI_API_KEY=local-key
 AI_MODEL=your-local-model
 ```

-### MiniMax CN example
+### MiniMax 中国区示例

 ```env
 AI_PROVIDER=minimax
@@ -230,13 +230,13 @@ AI_MAX_TOKENS=1200
 AI_ANTHROPIC_VERSION=2023-06-01
 ```

-MiniMax note:
+MiniMax 说明：

- This follows the same Anthropic Messages request shape as the official MiniMax examples.
- For MiniMax, `aiprovider` now disables `thinking` by default unless the caller explicitly passes a `thinking` object.
- This mirrors OpenClaw's caution around MiniMax Anthropic-compatible behavior.
+- 这里使用官方 MiniMax 示例中的 Anthropic Messages 请求结构。
+- 对 MiniMax，`aiprovider` 默认不会开启 `thinking`，除非调用方显式传入 `thinking` 对象。
+- 这个行为和 OpenClaw 对 MiniMax Anthropic 兼容接口的谨慎处理保持一致。

-### Anthropic-compatible example
+### Anthropic 兼容示例

 ```env
 AI_PROVIDER=anthropic
@@ -248,7 +248,7 @@ AI_MAX_TOKENS=1200
 AI_ANTHROPIC_VERSION=2023-06-01
 ```

-### Ollama example
+### Ollama 示例

 ```env
 AI_PROVIDER=ollama
@@ -258,36 +258,36 @@ AI_API_KEY=
 AI_MODEL=qwen2.5:7b
 ```

-## Deployment Modes
+## 部署模式

-### Single machine
+### 单机部署

-Recommended local flow:
+推荐的本地流程：

- `backend` on `localhost:8000`
- `aiprovider` on `localhost:8010`
- local model gateway on `localhost:11434` or another local port
+- `backend` 运行在 `localhost:8000`
+- `aiprovider` 运行在 `localhost:8010`
+- 本地模型网关运行在 `localhost:11434` 或其它本地端口

-Helpers already included:
+仓库内已包含辅助入口：

 - [planet.sh](/home/ray/dev/linkong/planet/planet.sh)
 - [docker-compose.local-model.yml](/home/ray/dev/linkong/planet/docker-compose.local-model.yml)

-### Multi-machine
+### 多机部署

-Example topology:
+示例拓扑：

- app machine: `backend`
- AI gateway machine: `aiprovider`
- model machine: local model service or cloud proxy
+- 应用机器：`backend`
+- AI 网关机器：`aiprovider`
+- 模型机器：本地模型服务或云代理

-In that case, this becomes service-to-service HTTP RPC:
+此时链路变成服务间 HTTP RPC：

 - caller -> backend
 - backend -> `http://10.0.0.12:8010`
- `aiprovider` -> model endpoint
+- `aiprovider` -> 模型端点

-Recommended cross-machine backend config:
+推荐的跨机器后端配置：

 ```env
 AI_PROVIDER_SERVICE_URL=http://10.0.0.12:8010
@@ -296,38 +296,38 @@ AI_PROVIDER_TIMEOUT_SECONDS=60
 AI_PROVIDER_RETRY_ATTEMPTS=2
 ```

-Recommended operating rules:
+推荐运行规则：

- keep `aiprovider` on a private network
- protect it with `X-Provider-Token` at minimum
- always send `X-Request-ID`
- keep callers on the backend API unless they are infrastructure jobs
+- 将 `aiprovider` 放在私有网络内
+- 至少用 `X-Provider-Token` 保护它
+- 始终发送 `X-Request-ID`
+- 除基础设施任务外，调用方优先走后端 API

-## Retry And Failure Behavior
+## 重试和失败行为

-`backend -> aiprovider`:
+`backend -> aiprovider`：

- retries lightweight network / 5xx failures
- returns `502` when the provider service is unavailable
+- 对轻量网络错误和 5xx 失败进行重试
+- provider 服务不可用时返回 `502`

-`aiprovider -> model provider`:
+`aiprovider -> model provider`：

- retries lightweight network / 5xx failures
- returns `502` when the model provider is unavailable
+- 对轻量网络错误和 5xx 失败进行重试
+- 模型提供方不可用时返回 `502`

-This is intentionally conservative. It avoids masking persistent errors while still absorbing short hiccups.
+这个策略故意保持保守：它能吸收短暂抖动，但不会掩盖持续性错误。

-## Operational Notes
+## 运维说明

- `./planet.sh start` now starts `aiprovider` automatically
- `./planet.sh restart -a` restarts only `aiprovider`
- `./planet.sh log -a` tails `aiprovider` logs
- `./planet.sh health` reports `aiprovider` health
+- `./planet.sh start` 会自动启动 `aiprovider`
+- `./planet.sh restart -a` 只重启 `aiprovider`
+- `./planet.sh log -a` 跟随查看 `aiprovider` 日志
+- `./planet.sh health` 会报告 `aiprovider` 健康状态

-## Recommended Calling Policy
+## 推荐调用策略

- Frontend and application services: call `backend`
- Scheduled infra jobs and diagnostics: optionally call `aiprovider`
- Do not let multiple business services integrate model vendors independently
+- 前端和应用服务：调用 `backend`
+- 定时基础设施任务和诊断任务：可选直接调用 `aiprovider`
+- 不要让多个业务服务分别接入模型厂商

-That keeps provider switching centralized and avoids model-specific drift across the system.
+这样可以集中管理 provider 切换，避免模型相关差异在系统里四处扩散。
--- a/docs/technical/zh/backend-datasources-api-performance.md
+++ b/docs/technical/zh/backend-datasources-api-performance.md
@@ -0,0 +1,100 @@
+# DataSources 列表接口性能优化
+
+## 背景
+
+`GET /api/v1/datasources` 是数据源管理页面的核心接口，响应慢会直接阻塞页面渲染。
+
+## 优化前的查询链路
+
+`_load_datasource_list_context` 按顺序执行以下查询：
+
+| 序号 | 函数 | 查询内容 | 瓶颈 |
+|------|------|---------|------|
+| 1 | `_load_latest_running_tasks` | collection_tasks 窗口函数，stale check 依赖此结果 | 必须串行 |
+| 2 | `_load_latest_completed_tasks` | collection_tasks 窗口函数（最近完成任务） | 串行等待 |
+| 3 | `_load_datasource_data_counts` | `COUNT(*) GROUP BY source` on collected_data | **最慢，全表扫描** |
+| 4 | `_load_datasource_endpoint_overrides` | datasource_configs 简单 SELECT | 串行等待 |
+
+## 第一阶段：并行化
+
+将 2/3/4 三个互不依赖的查询改为 `asyncio.gather` + 独立 session 并行执行：
+
+```python
+async def _fetch_completed():
+    async with async_session_factory() as s:
+        return await _load_latest_completed_tasks(s, datasource_ids)
+
+async def _fetch_counts():
+    async with async_session_factory() as s:
+        return await _load_datasource_data_counts(s, sources)
+
+async def _fetch_overrides():
+    async with async_session_factory() as s:
+        return await _load_datasource_endpoint_overrides(s, sources)
+
+completed_tasks, data_counts, endpoint_overrides = await asyncio.gather(
+    _fetch_completed(), _fetch_counts(), _fetch_overrides(),
+)
+```
+
+> **注意**：SQLAlchemy `AsyncSession` 不支持在同一 session 上并发，每个协程必须独立开 session。
+
+## 第二阶段：删除重量级查询
+
+### 删除 `_load_datasource_data_counts`
+
+`data_count` 字段仅用于前端在"最近采集"列显示 `(0条)` 的边缘提示，不值得为此维持一次 `COUNT(*) GROUP BY` 全表扫描。
+
+- 前端同步移除 `(0条)` 显示逻辑
+- 移除 `BuiltInDataSource` 接口中的 `data_count` 字段
+
+### 删除 `_load_latest_completed_tasks`
+
+`last_status` 和 `last_run_at` 已由 collector 在任务完成时直接更新到 `DataSource` 模型字段，不需要再 JOIN collection_tasks 获取：
+
+```python
+# 优化前：需要查 completed_tasks
+last_run_at = datasource.last_run_at or (last_task.completed_at if last_task else None)
+last_status = datasource.last_status or (last_task.status if last_task else None)
+
+# 优化后：直接读模型字段
+last_run_at = datasource.last_run_at
+last_status = datasource.last_status
+```
+
+同步移除 `last_records_processed` 字段（来源是 completed_tasks，列表不显示此字段）。
+
+## 优化后的查询链路
+
+```
+datasources SELECT          → 主数据，必须
+_load_latest_running_tasks  → 必须（进行中状态 + stale check）
+_load_datasource_endpoint_overrides → 必须（endpoint 覆盖，编辑内置 collector 时需要默认值）
+```
+
+3 个查询（原来 5 个），后两个顺序执行（running tasks 先完成用于 stale check，endpoint overrides 轻量）。
+
+## 前端 triggerDatasource 双调修复
+
+`triggerDatasource` 中存在双重 `fetchData()` 调用：
+
+```typescript
+// 修复前
+} else {
+    window.setTimeout(() => { fetchData() }, 800)  // 无 task_id 时延迟刷
+}
+fetchData()  // 总是立即刷 → 与上面的延迟刷重叠
+
+// 修复后（二者互斥）
+if (res.data.task_id) {
+    setTaskProgress(...)
+    fetchData()           // 有 task_id：立即刷一次
+} else {
+    window.setTimeout(fetchData, 800)  // 无 task_id：等 800ms 再刷一次
+}
+```
+
+## 相关文件
+
+- `backend/app/api/v1/datasources.py` — `_load_datasource_list_context`、`list_datasources`
+- `frontend/src/pages/DataSources/DataSources.tsx` — `BuiltInDataSource` interface、`triggerDatasource`
--- a/docs/technical/zh/backend-system-service-control.md
+++ b/docs/technical/zh/backend-system-service-control.md
@@ -1,61 +1,57 @@
-# System Service Control
+# 系统服务控制

-This document defines the fixed mapping between admin control-plane actions and
-the existing `planet.sh` service-management commands.
+本文定义后台控制面动作与现有 `planet.sh` 服务管理命令之间的固定映射。

-The goal is to reuse the current operational script semantics without exposing
-arbitrary shell execution to the frontend or API callers.
+目标是在复用当前运维脚本语义的同时，不向前端或 API 调用方暴露任意 shell 执行能力。

-## Scope
+## 范围

- This mapping is for admin-side operational controls only.
- The control plane must submit a fixed action name, not a raw shell command.
- The backend is responsible for translating an allowed action into a fixed
-  `planet.sh` invocation.
+- 这套映射只用于管理端运维控制。
+- 控制面必须提交固定 action 名称，而不是原始 shell 命令。
+- 后端负责把允许的 action 翻译成固定的 `planet.sh` 调用。

-## Design Rules
+## 设计规则

- Only whitelist actions may be executed.
- The frontend must never send arbitrary shell strings.
- The backend must build command arguments from a fixed mapping table.
- High-risk actions should be restricted to `super_admin`.
- Prefer partial restarts over full-stack restarts when UI continuity matters.
+- 只允许执行白名单 action。
+- 前端绝不能发送任意 shell 字符串。
+- 后端必须从固定映射表构造命令参数。
+- 高风险 action 应限制为 `super_admin`。
+- 在 UI 连续性重要时，优先局部重启，而不是全栈重启。

-## Action Mapping
+## Action 映射

-| Action name | Intended use | `planet.sh` command | Notes |
+| Action 名称 | 用途 | `planet.sh` 命令 | 备注 |
 | --- | --- | --- | --- |
-| `restart-backend` | Restart backend API only | `./planet.sh restart -b` | Recommended first implementation for UI-triggered restart flows. |
-| `restart-database` | Restart PostgreSQL and Redis containers | `./planet.sh restart -d` | Useful when database/cache services need a controlled bounce without restarting the UI. |
-| `restart-system` | Restart the whole application stack | `./planet.sh restart` | Frontend continuity breaks briefly; UI should switch to guided recovery mode. |
-| `restart-frontend` | Restart frontend dev server only | `./planet.sh restart -f` | Use with caution; UI continuity is weaker than backend-only restart. |
-| `restart-backend-port` | Restart backend on a specific port | `./planet.sh restart -b <port>` | Port must be backend-validated before execution. |
-| `restart-frontend-port` | Restart frontend on a specific port | `./planet.sh restart -f <port>` | Port must be backend-validated before execution. |
-| `health-check` | Read current service health | `./planet.sh health` | Safe read-only operational action. |
-| `show-logs-backend` | Inspect backend logs | `./planet.sh log -b` | Best used for CLI/operator tooling, not normal Web UI streaming. |
-| `show-logs-frontend` | Inspect frontend logs | `./planet.sh log -f` | Best used for CLI/operator tooling, not normal Web UI streaming. |
+| `restart-backend` | 只重启后端 API | `./planet.sh restart -b` | 推荐作为 UI 触发重启流程的第一阶段实现。 |
+| `restart-database` | 重启 PostgreSQL 和 Redis 容器 | `./planet.sh restart -d` | 适合数据库/缓存需要受控重启但不希望重启 UI 的场景。 |
+| `restart-system` | 重启整个应用栈 | `./planet.sh restart` | 前端会短暂中断；UI 应进入引导恢复模式。 |
+| `restart-frontend` | 只重启前端开发服务器 | `./planet.sh restart -f` | 谨慎使用；UI 连续性弱于只重启后端。 |
+| `restart-backend-port` | 在指定端口重启后端 | `./planet.sh restart -b <port>` | 执行前必须由后端校验端口。 |
+| `restart-frontend-port` | 在指定端口重启前端 | `./planet.sh restart -f <port>` | 执行前必须由后端校验端口。 |
+| `health-check` | 读取当前服务健康状态 | `./planet.sh health` | 安全的只读运维动作。 |
+| `show-logs-backend` | 查看后端日志 | `./planet.sh log -b` | 更适合 CLI/运维工具，不建议作为普通 Web UI 日志流。 |
+| `show-logs-frontend` | 查看前端日志 | `./planet.sh log -f` | 更适合 CLI/运维工具，不建议作为普通 Web UI 日志流。 |

-## Not Exposed In UI By Default
+## 默认不暴露到 UI 的能力

-The following existing script capabilities should not be exposed directly in the
-Web UI unless there is an explicit product need and an additional safety review:
+除非有明确产品需求并经过额外安全评审，否则以下脚本能力不应直接暴露到 Web UI：

 - `./planet.sh restart`
 - `./planet.sh start`
 - `./planet.sh stop`
 - `./planet.sh createuser`
- any future raw shell passthrough
+- 任何未来的原始 shell 透传能力

-Reason:
+原因：

- full restart can break the current control session;
- stop/start have larger blast radius;
- user creation is not a service-control operation;
- raw shell passthrough creates unnecessary privilege risk.
+- 全量重启可能打断当前控制会话；
+- stop/start 影响面更大；
+- 用户创建不是服务控制操作；
+- 原始 shell 透传会引入不必要的权限风险。

-## Recommended First-Phase UI Contract
+## 第一阶段推荐 UI 契约

-### Frontend action payload
+### 前端 action payload

 ```json
 {
@@ -63,7 +59,7 @@ Reason:
 }
 ```

-### Backend command resolution
+### 后端命令解析

 ```text
 restart-backend -> ["./planet.sh", "restart", "-b"]
@@ -73,19 +69,19 @@ restart-frontend -> ["./planet.sh", "restart", "-f"]
 health-check -> ["./planet.sh", "health"]
 ```

-## API Draft
+## API 草案

-### Primary Endpoint
+### 主接口

 - `POST /api/v1/system/restart-tasks`

-Purpose:
+用途：

- create a controlled restart task;
- resolve a whitelist action into a fixed `planet.sh` command;
- hand execution off to an external runner or detached subprocess.
+- 创建受控重启任务；
+- 将白名单 action 解析成固定 `planet.sh` 命令；
+- 把执行交给外部 runner 或 detached subprocess。

-### Request Body
+### 请求体

 ```json
 {
@@ -93,7 +89,7 @@ Purpose:
 }
 ```

-Optional future shape:
+未来可选形态：

 ```json
 {
@@ -102,7 +98,7 @@ Optional future shape:
 }
 ```

-### Response
+### 响应

 ```json
 {
@@ -114,11 +110,11 @@ Optional future shape:
 }
 ```

-### Task Query Endpoint
+### 任务查询接口

 - `GET /api/v1/system/restart-tasks/{task_id}`

-Response shape:
+响应结构：

 ```json
 {
@@ -136,11 +132,11 @@ Response shape:
 }
 ```

-### Optional Log Endpoint
+### 可选日志接口

 - `GET /api/v1/system/restart-tasks/{task_id}/logs`

-Suggested response:
+建议响应：

 ```json
 {
@@ -154,10 +150,9 @@ Suggested response:
 }
 ```

-This log endpoint is optional for phase one. The first version can work with
-task state plus `/health` polling alone.
+日志接口在第一阶段不是必需项。首版可以只依赖任务状态加 `/health` 轮询。

-## Task State Model
+## 任务状态模型

 ### Status

@@ -177,35 +172,32 @@ task state plus `/health` polling alone.
 - `healthy`
 - `failed`

-### Interpretation
+### 含义

- `status` is the high-level terminal or non-terminal state.
- `stage` is the operator-facing execution phase for the UI.
- `message` is the short human-readable line shown in the modal or full-screen
-  overlay.
+- `status` 是高层终态/非终态状态。
+- `stage` 是面向运维人员和 UI 的执行阶段。
+- `message` 是 modal 或全屏遮罩中展示的短文本。

-## Permission Model
+## 权限模型

- `restart-backend` should require `super_admin`.
- Permission checks should follow the same role pattern already used in
-  [users.py](/home/ray/dev/linkong/planet/backend/app/api/v1/users.py).
- Frontend visibility may hide controls for non-`super_admin`, but backend must
-  still enforce authorization.
+- `restart-backend` 应要求 `super_admin`。
+- 权限检查应沿用 [users.py](/home/ray/dev/linkong/planet/backend/app/api/v1/users.py) 中已有的角色模式。
+- 前端可以对非 `super_admin` 隐藏控件，但后端必须继续强制鉴权。

-## Storage Model
+## 存储模型

-Recommended first implementation:
+推荐第一阶段实现：

- store restart task state in Redis;
- keep task lifetime short;
- keep recent logs as a bounded list.
+- 将重启任务状态存入 Redis；
+- 任务生命周期保持较短；
+- 最近日志用有界列表保存。

-Suggested keys:
+建议 key：

 - `system:restart_task:{task_id}`
 - `system:restart_task:{task_id}:logs`

-Suggested stored fields:
+建议字段：

 - `task_id`
 - `action`
@@ -217,22 +209,21 @@ Suggested stored fields:
 - `created_at`
 - `updated_at`

-## Execution Model
+## 执行模型

-The request-handling API process should not depend on itself surviving long
-enough to stream the whole restart output.
+处理请求的 API 进程不应依赖自身持续存活来流式输出完整重启日志。

-Recommended execution flow:
+推荐执行流程：

-1. validate caller and action
-2. create task state in Redis
-3. resolve action to fixed `planet.sh` argv
-4. spawn detached executor
-5. return `task_id`
-6. executor updates task state while restart is in progress
-7. frontend polls health and/or task state until recovery
+1. 校验调用方和 action
+2. 在 Redis 中创建任务状态
+3. 将 action 解析为固定 `planet.sh` argv
+4. 启动 detached executor
+5. 返回 `task_id`
+6. executor 在重启过程中更新任务状态
+7. 前端轮询健康状态和/或任务状态，直到服务恢复

-Recommended command resolution examples:
+推荐命令解析示例：

 ```text
 restart-backend      -> ["./planet.sh", "restart", "-b"]
@@ -241,25 +232,25 @@ restart-backend-port -> ["./planet.sh", "restart", "-b", "<port>"]
 health-check         -> ["./planet.sh", "health"]
 ```

-## Frontend Polling Flow
+## 前端轮询流程

-Recommended first-phase UX:
+推荐第一阶段 UX：

-1. user clicks `重启后端`
-2. confirmation modal explains temporary unavailability
-3. frontend calls `POST /api/v1/system/restart-tasks`
-4. UI enters blocking restart state
-5. frontend polls `/health` every `1-2s`
-6. temporary request failures are treated as expected
-7. after `2-3` consecutive successful health checks, frontend reloads page
+1. 用户点击 `重启后端`
+2. 确认 modal 说明服务会短暂不可用
+3. 前端调用 `POST /api/v1/system/restart-tasks`
+4. UI 进入阻塞式重启状态
+5. 前端每 `1-2s` 轮询 `/health`
+6. 临时请求失败视为预期现象
+7. 连续 `2-3` 次健康检查成功后，前端刷新页面

-Optional richer polling:
+可选增强轮询：

-1. poll task status endpoint while backend is still reachable
-2. switch to `/health` recovery polling after disconnect begins
-3. refresh page after health recovery
+1. 后端仍可达时轮询任务状态接口
+2. 断连开始后切换为 `/health` 恢复轮询
+3. 健康恢复后刷新页面

-## Frontend State Machine
+## 前端状态机

 - `idle`
 - `confirming`
@@ -270,7 +261,7 @@ Optional richer polling:
 - `failed`
 - `timeout`

-Suggested UI messages:
+建议 UI 文案：

 - `已发送重启指令`
 - `正在停止后端服务`
@@ -278,70 +269,65 @@ Suggested UI messages:
 - `服务已恢复，正在刷新页面`
 - `恢复超时，请手动检查服务状态`

-## Phase-One Recommendation
+## 第一阶段建议

-Implement only the following in phase one:
+第一阶段只实现：

 - `restart-backend`
- `super_admin` permission gate
- task creation endpoint
- Redis-backed task state
- frontend confirmation modal
- frontend `/health` polling
- automatic page reload after recovery
+- `super_admin` 权限门禁
+- 任务创建接口
+- Redis 任务状态
+- 前端确认 modal
+- 前端 `/health` 轮询
+- 恢复后自动刷新页面

-Do not implement in phase one:
+第一阶段不要实现：

- full `./planet.sh restart`
- raw shell command passthrough
- arbitrary service control
- full terminal stdout streaming
- multi-action concurrent restart queueing
+- 完整 `./planet.sh restart`
+- 原始 shell 命令透传
+- 任意服务控制
+- 完整终端 stdout 流式输出
+- 多 action 并发重启队列

-## Implementation Checklist
+## 实现清单

-### Backend
+### 后端

-1. add a dedicated system-control API module under `backend/app/api/v1/`
-2. add a whitelist-based action resolver for `planet.sh`
-3. store restart task state in Redis
-4. add detached restart-runner script execution
-5. expose:
+1. 在 `backend/app/api/v1/` 下新增专用系统控制 API 模块
+2. 增加基于白名单的 `planet.sh` action 解析器
+3. 将重启任务状态存入 Redis
+4. 增加 detached restart-runner 脚本执行
+5. 暴露：
   - `POST /api/v1/system/restart-tasks`
   - `GET /api/v1/system/restart-tasks/{task_id}`
-   - optional task log endpoint
-6. enforce `super_admin` permission on all restart-task endpoints
+   - 可选任务日志接口
+6. 对所有 restart-task 接口强制 `super_admin` 权限

-### Frontend
+### 前端

-1. add a `重启后端` control on the dashboard for `super_admin`
-2. show a confirmation modal before dispatch
-3. after submission, switch modal into blocking restart state
-4. poll `/health` until backend recovery is confirmed
-5. auto-refresh page after consecutive successful health checks
-6. show short stage-oriented logs instead of raw terminal streaming
+1. 在 dashboard 为 `super_admin` 增加 `重启后端` 控件
+2. 发送前展示确认 modal
+3. 提交后将 modal 切换为阻塞式重启状态
+4. 轮询 `/health` 直到确认后端恢复
+5. 连续健康检查成功后自动刷新页面
+6. 展示简短阶段日志，而不是原始终端流

-### Operational Notes
+### 运维说明

-1. phase one should target backend-only restart
-2. frontend restart should remain out of scope initially
-3. command execution must always originate from repository root
-4. only fixed action names may cross the API boundary
+1. 第一阶段目标应限定为只重启后端
+2. 前端重启初期保持在范围外
+3. 命令执行必须始终从仓库根目录发起
+4. API 边界只能传递固定 action 名称

-## Validation Requirements
+## 校验要求

- Reject any action not present in the whitelist.
- If a port-bearing action is added, validate the port as an integer in
-  `1..65535`.
- Resolve commands from the repository root so `planet.sh` runs with a stable
-  working directory.
- Record the requested action, operator identity, execution start time, and
-  result.
+- 拒绝任何不在白名单中的 action。
+- 如果增加带端口 action，端口必须校验为 `1..65535` 的整数。
+- 从仓库根目录解析命令，确保 `planet.sh` 的工作目录稳定。
+- 记录请求 action、操作者身份、执行开始时间和结果。

-## Implementation Guidance
+## 实现建议

- For UI-triggered restart flows, prefer `restart-backend` first.
- Do not rely on the current API request process to stream full restart output
-  after it triggers its own restart.
- Use a task record plus polling/health-check recovery flow instead of raw
-  terminal streaming as the primary UX.
+- UI 触发重启流程时，优先实现 `restart-backend`。
+- 不要依赖当前 API 请求进程在触发自身重启后继续输出完整日志。
+- 主 UX 使用任务记录加轮询/健康检查恢复流程，而不是原始终端流。
--- a/docs/technical/zh/earth-bgp-context.md
+++ b/docs/technical/zh/earth-bgp-context.md
@@ -1,31 +1,31 @@
-# BGP Context
+# BGP 态势上下文

-## Current Goal
+## 当前目标

-The BGP module is being evolved from an anomaly-only demo into a layered observability pipeline:
+BGP 模块正在从一个只展示异常的演示功能，演进为分层观测管线：

 `raw observations -> enrichment -> detectors -> incidents -> console/Earth visualization`

-The practical product goal is no longer just to "show incidents on the globe". The current product objective is:
+实际产品目标已经不只是“在地球上显示事件”。当前目标是：

-1. keep BGP visually present on Earth even when incident density is low
-2. make incidents clearly feel like a higher-confidence layer than anomalies
-3. show that the observation network is still active even when there are no active incidents
+1. 即使 incident 密度很低，也让 BGP 在 Earth 上保持可见存在感
+2. 让 incident 明显比 anomaly 更像高置信度事件层
+3. 即使没有活跃 incident，也能表达观测网络仍在运行

-In practice, that means Earth should behave like an observability surface, not only an incident map:
+换句话说，Earth 应该表现为观测面，而不只是事件地图：

- `collectors` show that observation is happening
- `activity` shows where routing state is currently active or noisy
- `incidents` become the highest-confidence focus layer
+- `collectors` 表达观测正在发生
+- `activity` 表达哪里的路由状态近期活跃或噪声较高
+- `incidents` 成为最高置信度的聚焦层

-## Current Backend Architecture
+## 当前后端架构

-### Data Layers
+### 数据层

 1. `BGPObservation`
-   - File: `backend/app/models/bgp_observation.py`
-   - Purpose: store normalized raw routing observations from live/history sources.
-   - Typical fields:
+   - 文件：`backend/app/models/bgp_observation.py`
+   - 用途：存储从实时/历史来源归一化后的原始路由观测。
+   - 典型字段：
     - `source`
     - `collector`
     - `peer_asn`
@@ -42,80 +42,80 @@ In practice, that means Earth should behave like an observability surface, not o
     - `ingest_batch_id`

 2. `BGPAnomaly`
-   - File: `backend/app/models/bgp_anomaly.py`
-   - Purpose: hold atomic detector outputs.
-   - Current detector output types include:
+   - 文件：`backend/app/models/bgp_anomaly.py`
+   - 用途：保存原子级 detector 输出。
+   - 当前 detector 输出类型包括：
     - `origin_change`
     - `more_specific_burst`
     - `mass_withdrawal`

 3. `BGPIncident`
-   - File: `backend/app/models/bgp_incident.py`
-   - Purpose: aggregate atomic anomalies into incident-level objects for humans and the UI.
+   - 文件：`backend/app/models/bgp_incident.py`
+   - 用途：把原子 anomaly 聚合成人类和 UI 可消费的 incident 对象。

-### Pipeline
+### 管线

-Main flow is currently anchored in:
+主流程目前集中在：

 - `backend/app/services/collectors/bgp_common.py`
 - `backend/app/services/bgp_enrichment.py`
 - `backend/app/services/bgp_detectors.py`
 - `backend/app/services/bgp_incidents.py`

-Operational flow:
+运行流程：

-1. collectors fetch raw BGP data
-2. `normalize_bgp_event()` standardizes payloads
-3. observations are persisted to `bgp_observations`
-4. enrichment augments events with analysis context
-5. detectors create `bgp_anomalies`
-6. incident aggregation rolls anomalies up into `bgp_incidents`
+1. 采集器抓取原始 BGP 数据
+2. `normalize_bgp_event()` 规范化 payload
+3. observation 写入 `bgp_observations`
+4. enrichment 为事件补充分析上下文
+5. detector 创建 `bgp_anomalies`
+6. incident 聚合把 anomaly 汇总为 `bgp_incidents`

-### Current Ingest Sources
+### 当前接入来源

 1. `RIPE RIS Live`
-   - Collector file: `backend/app/services/collectors/ris_live.py`
-   - Used for realtime observation flow.
+   - 采集器文件：`backend/app/services/collectors/ris_live.py`
+   - 用于实时观测流。

 2. `CAIDA BGPStream Backfill`
-   - Collector file: `backend/app/services/collectors/bgpstream.py`
-   - Used as history/backfill entry point.
+   - 采集器文件：`backend/app/services/collectors/bgpstream.py`
+   - 用作历史/回填入口。

-## Current Enrichment Status
+## 当前 enrichment 状态

-Implemented enrichment skeleton in:
+已在以下文件实现 enrichment 骨架：

 - `backend/app/services/bgp_enrichment.py`

-Current enrichments:
+当前 enrichment 内容：

 - prefix family / prefix length
- supernet / more-specific derivation
- deduplicated AS path
- path prepending hints
- collector region info
- prefix baseline hints
- new-origin detection
- ASN organization profile from PeeringDB where available
- prefix scope / impacted region hints
- prefix geography source priority:
-  - `OpenGeoFeed` (override/high confidence)
-  - `IPtoASN` (country-range baseline)
-  - `NRO delegated stats` (registry-allocation fallback)
+- supernet / more-specific 推导
+- 去重 AS path
+- path prepending 提示
+- collector 区域信息
+- prefix baseline 提示
+- new-origin 检测
+- 可用时从 PeeringDB 获取 ASN 组织画像
+- prefix scope / 受影响区域提示
+- prefix 地理来源优先级：
+  - `OpenGeoFeed`（override，高置信）
+  - `IPtoASN`（国家范围 baseline）
+  - `NRO delegated stats`（registry allocation fallback）

-Current limitation:
+当前限制：

- `RPKI` is still placeholder-only and returns `unknown`
- no real ROA validation source is integrated yet
- `inetnum` / `inet6num` whois fallback is still pending
+- `RPKI` 仍只是占位，返回 `unknown`
+- 尚未集成真实 ROA 校验来源
+- `inetnum` / `inet6num` whois fallback 仍待实现

-## Current API Surface
+## 当前 API 面

-Primary API file:
+主 API 文件：

 - `backend/app/api/v1/bgp.py`

-Available endpoints:
+可用接口：

 - `/api/v1/bgp/events`
 - `/api/v1/bgp/events/summary`
@@ -127,16 +127,16 @@ Available endpoints:
 - `/api/v1/bgp/incidents/summary`
 - `/api/v1/bgp/incidents/{id}`

-Visualization GeoJSON endpoints:
+可视化 GeoJSON 接口：

 - `backend/app/api/v1/visualization.py`
 - `/api/v1/visualization/geo/bgp-collectors`
 - `/api/v1/visualization/geo/bgp-anomalies`
 - `/api/v1/visualization/geo/bgp-incidents`

-## Current Earth Behavior
+## 当前 Earth 行为

-Relevant files:
+相关文件：

 - `frontend/public/earth/js/bgp.js`
 - `frontend/public/earth/js/main.js`
@@ -144,56 +144,56 @@ Relevant files:
 - `frontend/public/earth/js/constants.js`
 - `frontend/public/earth/index.html`

-Current design:
+当前设计：

-1. Collectors are always shown when BGP is enabled.
-2. Incident markers are now the primary Earth BGP markers.
-3. If there are no incidents, Earth falls back to anomaly markers.
-4. If there are no anomalies either, collectors still provide presence.
-5. A dedicated `activity layer` now adds:
-   - per-collector recent 15-minute activity halos
-   - clustered regional activity hints derived from active collectors
-6. Incident markers now use:
-   - symbol-driven event cores
-   - outward ring pulses
-   - reduced diffuse glow compared with older Earth builds
-5. The right-side stats now show:
+1. BGP 启用时始终显示 collectors。
+2. Incident marker 现在是 Earth BGP 的主 marker。
+3. 如果没有 incident，Earth 回退显示 anomaly marker。
+4. 如果也没有 anomaly，collector 仍然提供存在感。
+5. 专用 `activity layer` 现在增加：
+   - 每个 collector 最近 15 分钟活动 halo
+   - 基于活跃 collector 推导的区域聚合活动提示
+6. Incident marker 现在使用：
+   - 由符号驱动的事件核心
+   - 向外扩散的环形脉冲
+   - 相比旧版 Earth 更少的弥散 glow
+7. 右侧统计现在显示：
   - BGP events
   - collector count
   - BGP status summary

-This is directionally correct, but still incomplete for low-event-density periods. Right now Earth can still feel too quiet when incidents are sparse because the system lacks a dedicated `activity layer` between raw observation and incident focus.
+这个方向是对的，但在低事件密度时期仍不完整。当前 Earth 在 incident 稀疏时仍可能显得过于安静，因为系统还缺少位于原始观测和 incident 聚焦之间的专用 `activity layer`。

-Current BGP status strategy:
+当前 BGP 状态策略：

- incidents present: show active incident count
- no incidents but anomalies present: show active anomaly count, plus active observation regions when available
- no incidents/anomalies but activity present: show `观测网络运行中`
- no incidents/anomalies but collectors present: show `观测网络运行中 · 当前未发现聚合级事件`
- no BGP data at all: show `暂无观测数据`
+- 有 incident：显示活跃 incident 数量
+- 无 incident 但有 anomaly：显示活跃 anomaly 数量，并在可用时显示活跃观测区域
+- 无 incident/anomaly 但有 activity：显示 `观测网络运行中`
+- 无 incident/anomaly 但有 collectors：显示 `观测网络运行中 · 当前未发现聚合级事件`
+- 完全无 BGP 数据：显示 `暂无观测数据`

-Earth info-card strategy:
+Earth info-card 策略：

- `bgp` card is now incident-centric in wording
- `bgp_collector` card shows collector location and current event count
+- `bgp` 卡片文案以 incident 为中心
+- `bgp_collector` 卡片显示 collector 位置和当前事件数

-## Current Product Gap
+## 当前产品缺口

-The main product gap is not architecture correctness. It is low-density visualization strategy.
+主要缺口不是架构正确性，而是低密度可视化策略。

-Current reality:
+当前事实：

- incident count is naturally much lower than anomaly count
- that is expected, because incidents are aggregated and de-noised
- but incident-first rendering makes the Earth view look too quiet unless there is another always-available activity layer
+- incident 数量天然远低于 anomaly 数量
+- 这是预期行为，因为 incident 是聚合和去噪后的结果
+- 但 incident-first 渲染会让 Earth 显得过于安静，除非有另一层始终可用的 activity layer

-Implementation detail for the recommended `activity layer` is expanded in [bgp-region-aggregation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-bgp-region-aggregation-plan.md).
+推荐 `activity layer` 的实现细节在 [bgp-region-aggregation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-bgp-region-aggregation-plan.md) 中展开。

-So the immediate next milestone is:
+因此最近的里程碑是：

 `event map -> observability map`

-That means Earth needs three simultaneously readable layers:
+这意味着 Earth 需要三层同时可读：

 1. `observation layer`
   - collectors
@@ -205,108 +205,108 @@ That means Earth needs three simultaneously readable layers:
   - regional activity scoring
   - incident presence bonus
 3. `incident layer`
-   - sparse but highly legible, high-confidence event objects
-   - symbol-driven markers
-   - outward ring pulse instead of broad diffuse glow
+   - 稀疏但高度清晰的高置信事件对象
+   - 符号化 marker
+   - 向外环形脉冲，而不是大面积弥散 glow

-## Incident Visual Direction
+## Incident 视觉方向

-The Earth `incident` layer should not read like a large glowing patch. It should read like a compact, high-confidence event focus.
+Earth 的 `incident` 层不应该像一大片发光区域，而应该像紧凑、高置信度的事件焦点。

-Design principles:
+设计原则：

-1. `incident` markers should use a strong primary symbol
-   - the symbol shape should carry type meaning where possible
-   - examples:
-     - `origin_change`: triangle-like warning marker
-     - `mass_withdrawal`: alert/exclamation-style marker
-     - `more_specific_burst`: split/radiating marker
+1. `incident` marker 应使用强主符号
+   - 符号形状尽量承载类型含义
+   - 示例：
+     - `origin_change`：类似三角警告 marker
+     - `mass_withdrawal`：告警/感叹号风格 marker
+     - `more_specific_burst`：分裂/放射 marker

-2. emphasis should come from outward ring pulses, not area flooding
-   - use a compact hot core
-   - use one or more expanding ring pulses
-   - avoid broad luminous blobs that make the event center feel vague
+2. 强调应来自向外扩散的环形脉冲，而不是区域泛光
+   - 使用紧凑高亮核心
+   - 使用一个或多个扩张环形脉冲
+   - 避免让事件中心变得模糊的大面积亮斑

-3. `collector` and `incident` must stay visually distinct
-   - collectors are observation infrastructure
-   - incidents are extracted event focus
-   - collector activity should stay quieter than incident pulse language
+3. `collector` 和 `incident` 必须保持视觉区别
+   - collector 是观测基础设施
+   - incident 是抽取后的事件焦点
+   - collector activity 应比 incident pulse 更安静

-4. calm periods still need observability presence
-   - collectors and activity layers should keep the map alive
-   - once incidents appear, they should clearly dominate nearby BGP visuals
+4. 平静期仍需要观测存在感
+   - collectors 和 activity layer 应让地图保持活跃
+   - 一旦出现 incident，它们应明确压过附近 BGP 视觉元素

-5. incident geography should become `prefix-centric`
-   - collectors should remain evidence sources, not the primary event location
-   - preferred geography priority:
+5. incident 地理位置应转向 `prefix-centric`
+   - collector 应保持证据来源身份，而不是主要事件位置
+   - 推荐地理优先级：
     - `prefix_geography`
     - `prefix_scope`
     - `ASN organization region`
-     - `collector centroid` as final fallback
-   - `prefix_scope` should remain an observation-derived scope hint
-   - a new `prefix_geography` layer should be introduced for actual prefix-centric placement
+     - `collector centroid` 作为最终 fallback
+   - `prefix_scope` 应保持为由观测推导出的范围提示
+   - 应新增真正面向 prefix 位置的 `prefix_geography` 层

-Reference inspiration:
+参考灵感：

 - `World Monitor`
-  - sparse event symbols
-  - compact centers
-  - ring-like outward pulses
-  - stronger incident legibility than diffuse glow
+  - 稀疏事件符号
+  - 紧凑中心
+  - 类似环形的向外脉冲
+  - 比弥散 glow 更强的 incident 可读性

-## Current Console Behavior
+## 当前控制台行为

-Relevant page:
+相关页面：

 - `frontend/src/pages/BGP/BGP.tsx`

-Current BGP console page has three levels:
+当前 BGP 控制台页面有三层：

-1. observation summary
-   - total events
-   - collector count
-   - prefix count
+1. 观测摘要
+   - 总事件数
+   - collector 数量
+   - prefix 数量

-2. incident summary and incident table
+2. incident 摘要和 incident 表格

-3. anomaly detail table plus recent observation events
+3. anomaly 详情表和最近 observation events

-This means the BGP page still has useful signal even when there are zero anomalies.
+这意味着即使 anomaly 为零，BGP 页面仍有可用信号。

-## Known Product/Engineering Boundaries
+## 已知产品/工程边界

-1. The current system is still closer to an event board than a full BGP sensing platform.
-2. RIS coverage still needs to expand beyond narrow subscription scope.
-3. BGPStream history is still not full MRT-to-prefix decoded analytics.
-4. Collector geography still depends heavily on static RIPE RIS mappings.
-5. Incident-to-cable/IXP/region association is still weak and early-stage.
-6. Earth currently visualizes logical observation/impact structure, not true physical traffic paths.
+1. 当前系统仍更接近事件看板，而不是完整 BGP sensing platform。
+2. RIS 覆盖范围仍需从较窄订阅范围继续扩展。
+3. BGPStream 历史数据仍不是完整 MRT-to-prefix 解码分析。
+4. Collector 地理位置仍高度依赖静态 RIPE RIS 映射。
+5. Incident 与海缆、IXP、区域之间的关联仍较弱，且处于早期阶段。
+6. Earth 当前可视化的是逻辑观测/影响结构，而不是真实物理流量路径。

-## Test Status
+## 测试状态

-BGP-specific tests live in:
+BGP 专项测试位于：

 - `backend/tests/test_bgp.py`

-Verified status at this point:
+当前已验证状态：

- `25 passed` for `backend/tests/test_bgp.py`
- `62 passed` for `backend/tests`
+- `backend/tests/test_bgp.py` 为 `25 passed`
+- `backend/tests` 为 `62 passed`

-Covered areas include:
+覆盖范围包括：

 - normalization
 - observation serialization
 - enrichment
- detectors, including route leak candidate and path flap
+- detectors，包括 route leak candidate 和 path flap
 - incident aggregation
 - batch anomaly creation
 - BGP events/incidents API
 - summary endpoints

-## Most Relevant Files
+## 最相关文件

-Backend:
+后端：

 - `backend/app/models/bgp_observation.py`
 - `backend/app/models/bgp_anomaly.py`
@@ -318,7 +318,7 @@ Backend:
 - `backend/app/api/v1/bgp.py`
 - `backend/app/api/v1/visualization.py`

-Frontend:
+前端：

 - `frontend/src/pages/BGP/BGP.tsx`
 - `frontend/public/earth/js/bgp.js`
@@ -327,29 +327,29 @@ Frontend:
 - `frontend/public/earth/js/constants.js`
 - `frontend/public/earth/index.html`

-## Recommended Next Steps
+## 推荐下一步

-### Next Backend / Detection Priority
+### 后端 / 检测优先级

-1. Integrate real RPKI validation data.
-2. Expand realtime collector coverage and include withdrawals more broadly.
-3. Continue refining route leak and path instability detectors with stronger heuristics.
+1. 集成真实 RPKI 校验数据。
+2. 扩展实时 collector 覆盖范围，并更广泛纳入 withdrawals。
+3. 用更强启发式继续完善 route leak 和 path instability detector。

-### Next Correlation / Storytelling Priority
+### 关联 / 叙事优先级

-4. Strengthen incident aggregation semantics and titles.
-5. Add weak correlation from incidents to:
-   - cable corridors
-   - landing points
+4. 强化 incident 聚合语义和标题。
+5. 增加 incident 与以下对象的弱关联：
+   - 海缆走廊
+   - 登陆点
   - IXPs
-   - other traffic anomaly sources
-6. Refine Earth hover/click handoff between collectors and incidents.
+   - 其它流量异常来源
+6. 优化 Earth 中 collector 和 incident 之间的 hover/click 交接。

-### Next Visualization Priority
+### 可视化优先级

-7. Refine regional activity scoring so the activity layer is informative without becoming noisy.
-8. Add more incident symbol types as new detectors land.
-9. Add a real prefix geography source:
-   - `IPtoASN / IPtoCountry` as the first practical dataset
-   - `OpenGeoFeed` as a higher-quality override layer
-   - registry/whois only as fallback
+7. 调整区域 activity scoring，让 activity layer 有信息量但不嘈杂。
+8. 随着新 detector 落地，增加更多 incident 符号类型。
+9. 增加真实 prefix geography 来源：
+   - `IPtoASN / IPtoCountry` 作为第一阶段可用数据集
+   - `OpenGeoFeed` 作为更高质量 override 层
+   - registry/whois 只作为 fallback
--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -1,11 +1,11 @@
-# Earth Frontend Context
+# Earth 前端结构

 本文件描述当前 Earth 大屏前端的真实结构，重点是帮助后续继续改 HUD、图层、媒体面板、真实地形、BGP 可视化时，不再重复踩结构和状态同步上的坑。

 相关规则建议一起参考：

 - [rules.md](/home/ray/dev/linkong/planet/rules.md)
- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)
+- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

 ## 当前目标

@@ -378,4 +378,4 @@ Earth 前端和控制台前端不是同一套 UI 系统：

 控制台相关结构见：

- [admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)
+- [admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
--- a/docs/technical/zh/earth-layer-style-reference.md
+++ b/docs/technical/zh/earth-layer-style-reference.md
@@ -2,7 +2,7 @@

 本文记录当前 Earth 前端各图层的材质、颜色、透明度、线宽、半径偏移和
 `renderOrder` 等样式属性。层级关系请配合
-[earth-render-layer-order.md](/home/ray/dev/linkong/planet/docs/technical/earth-render-layer-order.md)
+[earth-render-layer-order.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)
 查看。

 ## 命名约定
--- a/docs/technical/zh/earth-news-live-streams-collector-format.md
+++ b/docs/technical/zh/earth-news-live-streams-collector-format.md
@@ -1,4 +1,4 @@
-# News Live Streams Collector Format
+# 新闻直播采集格式

 `news_live_streams` 采集器面向“频道目录 JSON”输入，而不是直接抓网页。

--- a/docs/technical/zh/earth-satellite-footprint-policy.md
+++ b/docs/technical/zh/earth-satellite-footprint-policy.md
@@ -1,11 +1,11 @@
-# Earth Satellite Footprint Policy
+# Earth 卫星覆盖策略

 本文件记录 Earth 卫星图层当前关于 `footprint` 的产品边界、资料依据和已落地实现，目标是避免把 Starlink 这套专用地表覆盖模型误用到其它星座上。

 相关上下文：

- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/backend-collectors.md)
+- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
+- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
 - [backend/app/services/collectors/celestrak.py](/home/ray/dev/linkong/planet/backend/app/services/collectors/celestrak.py)
 - [frontend/public/earth/js/satellites.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/satellites.js)

--- a/docs/technical/zh/frontend-admin-frontend-context.md
+++ b/docs/technical/zh/frontend-admin-frontend-context.md
@@ -1,11 +1,11 @@
-# Admin Frontend Context
+# 控制台前端结构

 本文件描述当前控制台前端的真实结构，目标是帮助后续页面开发、表格改造、布局治理和状态收口时快速找到正确入口。

 相关规则建议一起参考：

 - [rules.md](/home/ray/dev/linkong/planet/rules.md)
- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)
+- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

 ## 当前目标

@@ -263,7 +263,7 @@

 详细经验见：

- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)
+- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

 ## 当前推荐改动方式

@@ -290,4 +290,4 @@

 Earth 相关结构见：

- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
+- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
--- a/docs/technical/zh/frontend-layout-guidelines.md
+++ b/docs/technical/zh/frontend-layout-guidelines.md
@@ -1,4 +1,4 @@
-# Frontend Layout Guidelines
+# 前端布局指南

 本项目后台页面默认遵循“单屏工作区”布局规范。目标不是让页面永远不溢出，而是确保在常见桌面视口下：

--- a/docs/technical/zh/manual.md
+++ b/docs/technical/zh/manual.md
@@ -7,7 +7,7 @@
 - 控制台：登录后的管理后台
 - Docs：公开开发文档与使用手册

-快速启动路径见 [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/quickstart.md)。
+快速启动路径见 [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。

 ## 入口总览

@@ -480,9 +480,9 @@ source ~/.zshrc && bun run build

 ## 相关文档

- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/quickstart.md)
- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)
- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/earth-layer-style-reference.md)
- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/backend-system-service-control.md)
- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/backend-collectors.md)
+- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
+- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
+- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
+- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
+- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
+- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
--- a/docs/technical/zh/ops-planet-sh-startup.md
+++ b/docs/technical/zh/ops-planet-sh-startup.md
@@ -0,0 +1,154 @@
+# planet.sh 启动性能优化
+
+## 背景
+
+`planet.sh` 管理所有服务的启动/停止/重启。原有实现存在以下问题：
+
+1. AI Provider 每次都重新构建（即使代码未变）
+2. 杀端口速度极慢（最长等 45 秒）
+3. 端口绑定检测用 Python 子进程（每次 ~300ms）
+4. 无参 `restart` 与 `restart -b` 行为不一致
+
+## 问题一：AI Provider 每次重建
+
+### 根因
+
+构建戳文件存放在 `/tmp/`，WSL/Linux 重启后 `/tmp` 被清空，导致三个条件中的"戳文件非空"这一条始终不满足，进而判定需要重建：
+
+```bash
+# 三个条件必须同时成立才跳过重建
+image_exists AND stamp_non_empty AND fingerprint_match
+```
+
+### 修复
+
+将戳文件路径从 `/tmp/` 改到持久路径：
+
+```bash
+AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
+```
+
+写入时确保目录存在：
+
+```bash
+write_ai_provider_build_stamp() {
+    mkdir -p "$(dirname "$AI_PROVIDER_BUILD_STAMP_FILE")"
+    compute_ai_provider_build_fingerprint > "$AI_PROVIDER_BUILD_STAMP_FILE"
+}
+```
+
+### fingerprint 计算提速
+
+原实现对整个 `aiprovider/` 打 tar 包再算 SHA，大目录下耗时可达数秒。改为 `find + stat`（只读文件元信息，不读内容）：
+
+```bash
+compute_ai_provider_build_fingerprint() {
+    find aiprovider \
+        -type f \
+        ! -path '*/__pycache__/*' \
+        ! -name '*.pyc' \
+        ! -name '*.pyo' \
+        | LC_ALL=C sort \
+        | xargs -r stat --format="%Y %s %n" 2>/dev/null
+    sha256sum docker-compose.yml docker-compose.simple.yml 2>/dev/null
+    python3 "$SCRIPT_DIR/scripts/compute_aiprovider_dependency_fingerprint.py" 2>/dev/null
+}
+```
+
+速度提升约 10 倍（大量小文件场景），误报率相同（mtime+size 变化 ≡ 文件被修改）。
+
+### 跳过重建的原理
+
+fingerprint 一致时不执行 `docker compose build`，而是：
+
+```bash
+docker start planet_aiprovider   # 启动已存在的容器，几秒内完成
+```
+
+`docker stop` 停容器，不删镜像；`cleanup_exit_containers` 删已退出容器，不删镜像。下次 `docker start` 会从现有镜像直接创建并启动容器。
+
+## 问题二：杀端口速度慢
+
+### 原因
+
+`wait_for_port_release` 默认最多等 45 秒（15 次 × 3 秒）。
+
+### 修复
+
+将后台进程清理场景的超时缩短至 3 秒（TERM→1.5s→KILL→1.5s）：
+
+```bash
+PORT_RELEASE_ATTEMPTS=15
+PORT_RELEASE_INTERVAL=0.2   # 每次等 0.2s，总计 3s
+
+# cleanup_backend_processes / kill_port_if_requested
+wait_for_port_release "$port" 15 0.2
+```
+
+`wait_for_port_release` 增加可选参数，允许不同场景使用不同超时：
+
+```bash
+wait_for_port_release() {
+    local port="$1"
+    local max_attempts="${2:-$PORT_RELEASE_ATTEMPTS}"
+    local interval="${3:-$PORT_RELEASE_INTERVAL}"
+    ...
+}
+```
+
+## 问题三：端口检测用 Python
+
+### 原因
+
+`can_bind_port` 用 `python3 -c "import socket..."` 检测端口，每次调用约 300ms。
+
+### 修复
+
+优先使用系统工具（~10ms），Python 作为兜底：
+
+```bash
+can_bind_port() {
+    local port="$1"
+    if command -v ss >/dev/null 2>&1; then
+        ! ss -tlnH 2>/dev/null | awk '{print $4}' | grep -qE ":${port}$"
+        return
+    fi
+    if command -v lsof >/dev/null 2>&1; then
+        [ -z "$(lsof -tiTCP:"${port}" -sTCP:LISTEN 2>/dev/null)" ]
+        return
+    fi
+    python3 - "$port" <<'PY'
+import sys, socket
+p = int(sys.argv[1])
+s = socket.socket()
+s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+try:
+    s.bind(("", p)); s.close(); sys.exit(0)
+except OSError:
+    sys.exit(1)
+PY
+}
+```
+
+## 问题四：restart 行为不一致
+
+### 现象
+
+- `restart -b`：停全部服务 → 检查 AI Provider fingerprint → 按需重建 → 启动
+- `restart`（无参）：停全部服务 → AI Provider 总是判定需要重建（因戳文件在 /tmp）
+
+### 修复
+
+修复戳文件路径后，无参 `restart` 同样使用 `stop + start`，fingerprint 检查正常生效，行为与 `restart -b` 完全一致。无需额外代码变更。
+
+## 其他：移除不必要的 sleep
+
+启动链路中两处 `sleep 3` 在实际已有健康检查覆盖的情况下多余，已移除：
+
+- `start_backend_service`：数据库健康检查通过后的 `sleep 3`
+- `restart_database_service`：重启后的等待 `sleep 3`
+
+## 相关文件
+
+- `planet.sh` — 全量修改
+- `scripts/compute_aiprovider_dependency_fingerprint.py` — 依赖 fingerprint（未改动）
--- a/docs/technical/zh/quickstart.md
+++ b/docs/technical/zh/quickstart.md
@@ -1,6 +1,6 @@
-# Quickstart
+# 快速开始

-这份 Quickstart 面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来，并知道应该打开哪些入口。
+这份快速开始面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来，并知道应该打开哪些入口。

 ## 前置条件

@@ -187,7 +187,7 @@ ss -ltnp | grep -E ':3000|:8000'

 ## 下一步

- 完整操作说明见 [manual.md](/home/ray/dev/linkong/planet/docs/technical/manual.md)
- 控制台结构见 [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)
- Earth 结构见 [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
- 后端采集器见 [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/backend-collectors.md)
+- 完整操作说明见 [manual.md](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
+- 控制台结构见 [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
+- Earth 结构见 [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
+- 后端采集器见 [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
--- a/docs/version-history.md
+++ b/docs/version-history.md
@@ -16,12 +16,13 @@
 ## Current Version

 - `main` 当前主线历史推导到：`0.16.5`
- `dev` 当前开发分支历史推导到：`0.42.2`
+- `dev` 当前开发分支历史推导到：`0.43.0`

 ## Timeline

 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.43.0` | feature | `dev` | `pending` | 新增 Earth 船舶追踪、自定义数据源映射、外部集成配置中心、Markdown 渲染器增强，并整理规则/技能文档加载约束 |
 | `0.42.2` | bugfix | `dev` | `pending` | Docs 中文模式补齐分组和文档标题翻译，并更新文档站品牌文案 |
 | `0.42.1` | bugfix | `dev` | `pending` | 修正 release skill 的 feature 版本计算规则，minor 进位时重置 patch 为 0 |
 | `0.42.0` | feature | `dev` | `pending` | 新增公开 `/docs` 文档站、中英文技术/使用文档、搜索与主题切换，并补充公共组件复用和 Earth 无高清材质边缘提示 |