release: bump version to 0.46.1

.claude/commands/docs.md

@@ -63,6 +63,8 @@ ls docs/technical/zh/          # 查看现有文档
 - 采集器、数据源、凭证、设置页、连接检查、scheduler、后端 API 变化：更新相关后端文档，优先检查 `docs/technical/zh/backend-collectors.md` 和 datasource/settings 专题文档。
 - 如果某个旧 plan 的假设已经被当前实现推翻，在对应 `docs/plans/*.md` 增加现状修正或更新该段，不要让计划文档继续给出相反方向。
 - 新增 technical 文档后，如果需要被发现，更新 `docs/technical/zh/README.md`。
+- 如果 technical 文档需要在公开 Docs 页面显示，或从 technical README 链接进入，必须同步更新 `frontend/src/pages/Docs/docs-content.ts` 的 `DOCS_METADATA`。前端使用这份白名单，`docs/technical/{zh,en}/` 中存在 `.md` 文件并不会自动生成路由。
+- 公开 technical 文档必须按同名文件维护中英文双语版本：`docs/technical/zh/<name>.md` 与 `docs/technical/en/<name>.md`。如果某篇文档刻意只保留单语，完成说明中必须明确写出原因。
 - 对本次变更提取旧词做 stale search，例如旧 tab 名、旧路由职责、旧认证假设、改名前 UI 文案：
 
 ```bash
@@ -90,6 +92,7 @@ rg -n "旧文案|旧路由职责|旧认证假设" docs/technical docs/plans
 - 中文写作，技术术语保留英文原文
 - `docs/technical/zh/` 中的文档不得用英文原文占位；如果存在 `docs/technical/en/` 对应文件，禁止逐字复制成中文文件
 - 中文文档内部链接应指向 `docs/technical/zh/...`，除非明确引用英文专属文档
+- 公开文档的 Markdown 链接显示文字应使用可读标题，不要直接暴露 `manual.md`、`earth-frontend-context.md` 这类裸文件名
 
 **文档结构模板**：
 
@@ -141,6 +144,62 @@ PY
 rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2
 ```
 
+- 检查公开文档链接已进入 Docs 前端白名单。凡是 `docs/technical/{zh,en}/README.md` 中链接到的 technical `.md`，都必须存在于 `DOCS_METADATA`：
+
+```bash
+python - <<'PY'
+import re
+from pathlib import Path
+
+metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
+known = set(re.findall(r"'([^']+\.md)':\s*\{", metadata))
+known.add("README.md")
+
+missing = []
+for readme in [Path("docs/technical/zh/README.md"), Path("docs/technical/en/README.md")]:
+    if not readme.exists():
+        continue
+    for href in re.findall(r"\]\(([^)]+\.md)\)", readme.read_text()):
+        path = Path(href)
+        if "docs/technical/" not in href:
+            continue
+        filename = path.name
+        if filename not in known:
+            missing.append(f"{readme}: {filename}")
+
+if missing:
+    raise SystemExit("docs README links missing DOCS_METADATA: " + ", ".join(missing))
+print("docs README links are whitelisted")
+PY
+```
+
+- 检查公开文档双语同名文件齐备。除 `README.md` 外，所有白名单文档都应同时存在 zh/en 文件，除非本次说明中明确豁免：
+
+```bash
+python - <<'PY'
+import re
+from pathlib import Path
+
+metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
+filenames = sorted(set(re.findall(r"'([^']+\.md)':\s*\{", metadata)) - {"README.md"})
+missing = []
+for filename in filenames:
+    for lang in ("zh", "en"):
+        path = Path("docs/technical") / lang / filename
+        if not path.exists():
+            missing.append(str(path))
+if missing:
+    raise SystemExit("missing bilingual docs: " + ", ".join(missing))
+print("public docs have zh/en file pairs")
+PY
+```
+
+- 检查公开文档里没有用裸 `.md` 文件名当链接标题。这个命令在 polished public docs 中应无输出：
+
+```bash
+rg -n "\[[^]]+\.md\]\(" docs/technical/zh docs/technical/en
+```
+
 ```bash
 # 对文档中提到的关键路径做快速验证
 ls <mentioned_paths>
@@ -167,4 +226,7 @@ rg -n "\]\(([^)]+)\)" docs/technical/zh/<doc>.md
 - 不要在文档中引用 PR 号、issue 号、或当前对话——这些会随时间失效
 - 代码片段保持简洁，只保留说明问题的关键部分，省略无关样板代码
 - 如果某个变更已有文档记录，优先在原文档中追加，而不是新建
+- 公开 technical 文档没有注册 `DOCS_METADATA` 时，Docs 页面不会显示；不要只创建 `.md` 文件就结束。
+- 公开 technical 文档默认需要 zh/en 同名文件，不要只补一个语言版本。
+- 链接可见文字使用文档标题或语义标题，不要使用裸文件名。
 - 文档是给未来的开发者看的，假设读者熟悉项目但不了解这次改动的背景

.codex/skills/docs/SKILL.md

@@ -54,6 +54,8 @@ rg -n "class |def |function |export |router|@router|interface |type " <path>
 - Collector, datasource, credential, settings, connectivity, scheduler, or API changes must update the relevant backend docs, especially `docs/technical/zh/backend-collectors.md` and any datasource/settings-specific doc.
 - When a change turns an old plan assumption into current behavior, update the relevant `docs/plans/*.md` with a status note instead of leaving contradictory instructions.
 - If adding a new technical document, add it to `docs/technical/zh/README.md` when it should be discoverable from the technical docs index.
+- If a technical document should be visible in the public Docs page or linked from a technical README, register it in `frontend/src/pages/Docs/docs-content.ts` under `DOCS_METADATA`. The frontend uses this whitelist; files under `docs/technical/{zh,en}/` are not automatically routable.
+- For every public technical doc, keep the bilingual file pair in sync by filename: `docs/technical/zh/<name>.md` and `docs/technical/en/<name>.md`. If the content is intentionally Chinese-only or English-only, state that intentionally in the final note.
 - Search docs for stale terms introduced by the change, for example old tab names, old route responsibilities, obsolete auth assumptions, or renamed UI labels.
 
 4. Write the doc in Chinese:
@@ -100,6 +102,62 @@ rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh
 
 This command should return no matches.
 
+Check that public docs are whitelisted in the frontend Docs registry. Any `.md` linked from `docs/technical/{zh,en}/README.md` and located under `docs/technical/{zh,en}/` must have a matching `DOCS_METADATA` key:
+
+```bash
+python - <<'PY'
+import re
+from pathlib import Path
+
+metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
+known = set(re.findall(r"'([^']+\.md)':\s*\{", metadata))
+known.add("README.md")
+
+missing = []
+for readme in [Path("docs/technical/zh/README.md"), Path("docs/technical/en/README.md")]:
+    if not readme.exists():
+        continue
+    for href in re.findall(r"\]\(([^)]+\.md)\)", readme.read_text()):
+        path = Path(href)
+        if "docs/technical/" not in href:
+            continue
+        filename = path.name
+        if filename not in known:
+            missing.append(f"{readme}: {filename}")
+
+if missing:
+    raise SystemExit("docs README links missing DOCS_METADATA: " + ", ".join(missing))
+print("docs README links are whitelisted")
+PY
+```
+
+Check bilingual parity for public docs. Every whitelisted document except `README.md` should exist in both language directories unless intentionally documented otherwise:
+
+```bash
+python - <<'PY'
+import re
+from pathlib import Path
+
+metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
+filenames = sorted(set(re.findall(r"'([^']+\.md)':\s*\{", metadata)) - {"README.md"})
+missing = []
+for filename in filenames:
+    for lang in ("zh", "en"):
+        path = Path("docs/technical") / lang / filename
+        if not path.exists():
+            missing.append(str(path))
+if missing:
+    raise SystemExit("missing bilingual docs: " + ", ".join(missing))
+print("public docs have zh/en file pairs")
+PY
+```
+
+Check that Markdown links do not expose raw filenames as user-facing titles. This should return no matches for polished public docs:
+
+```bash
+rg -n "\[[^]]+\.md\]\(" docs/technical/zh docs/technical/en
+```
+
 If checking many links, prefer deterministic extraction:
 
 ```bash
@@ -118,6 +176,9 @@ rg -n "old label|old route purpose|obsolete provider assumption" docs/technical
 - Do not leave a Chinese doc with only an English title and English first-screen content.
 - When an English counterpart exists in `docs/technical/en/`, never duplicate it byte-for-byte into `docs/technical/zh/`.
 - Internal links inside `docs/technical/zh/` should point to `docs/technical/zh/...` for Chinese docs, unless intentionally linking to an English-only file.
+- Public technical documents must be registered in `frontend/src/pages/Docs/docs-content.ts` before considering them available in the Docs UI.
+- Public technical documents should have both zh and en files with the same filename, unless intentionally exempted.
+- Markdown link text in public docs should be a readable title, not a raw filename such as `manual.md`.
 - Do not reference PR numbers, issue numbers, or the current conversation.
 - Do not write changelog-style lists like "changed A, changed B, changed C" without the constraints and tradeoffs behind those changes.
 - Keep code snippets concise and relevant.
@@ -133,4 +194,7 @@ Updated:
 Verified:
 - no identical en/zh docs
 - no language-less docs/technical links in zh docs
+- public docs are registered in DOCS_METADATA
+- public docs have zh/en file pairs
+- no raw `.md` filenames as public link titles
 ```

VERSION

@@ -1 +1 @@
-0.46.0
+0.46.1

docs/CHANGELOG.md

@@ -8,6 +8,20 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`
 
+## [0.46.1] — 2026-04-30
+
+Released: 2026-04-30
+
+### 🐛 Fixes
+- 修复新增 technical docs 文件存在但未进入 Docs 前端白名单时，侧栏不显示且 Markdown 链接无法解析到 `/docs/<slug>` 的问题。
+- 补齐数据源/采集器连接验证与 Earth Interactable 使用说明的英文文档，保证公开 Docs 切换 EN 时同名页面可访问。
+- 清理中英文 technical docs 中裸 `.md` 文件名链接标题，改为面向读者的语义标题。
+
+### 📝 Documentation
+- 将 Docs 前端白名单、公开文档双语配对、裸文件名链接标题三项检查写入 Claude 与 Codex 的 docs 技能流程。
+
+---
+
 ## [0.46.0] — 2026-04-30
 
 Released: 2026-04-30

docs/technical/en/README.md

@@ -17,12 +17,16 @@ What belongs here:
 - Earth layer style property index
 - Backend runtime control
 - Collector status
+- Collector settings and connectivity validation
+- Earth Interactable integration
 - Collection format conventions
 
 ## Entry Points
 
-- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md): The shortest path to getting Planet running from scratch
-- [manual.md](/home/ray/dev/linkong/planet/docs/technical/en/manual.md): Complete usage guide for the console, `planet.sh`, Earth, and Docs
+- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md): The shortest path to getting Planet running from scratch
+- [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md): Complete usage guide for the console, `planet.sh`, Earth, and Docs
+- [Collector Settings and Connectivity Validation](/home/ray/dev/linkong/planet/docs/technical/en/datasource-collector-settings-connectivity.md): Data source catalog, collector settings, connectivity validation, and BarentsWatch credentials
+- [Earth Interactable Usage](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-usage.md): API, lifecycle, and integration examples for Earth surface icon Interactable
 
 What does not belong here:
 
@@ -32,4 +36,4 @@ What does not belong here:
 
 Those belong in:
 
-- [docs/plans/README.md](/home/ray/dev/linkong/planet/docs/plans/README.md)
+- [Plans Index](/home/ray/dev/linkong/planet/docs/plans/README.md)

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

@@ -0,0 +1,325 @@
+# Collector Settings and Connectivity Validation
+
+## Background
+
+The console now separates the "data source catalog" from "collector configuration":
+
+- `/datasources`
+  - Lists all data sources, including built-in and custom sources.
+  - Clicking a name only opens an information drawer.
+  - Focuses on status, manual collection, and running collection tasks.
+- `/settings?tab=collector_credentials`
+  - Displays as "Collector Settings".
+  - Owns endpoint, headers, base parameters, and credentials.
+  - Every collector exposes a connection button for health checks.
+
+This reduces first-use confusion: API endpoints, headers, credentials, and custom source configuration all belong to collector settings instead of being scattered across the data source list and system settings.
+
+## User-Facing Rules
+
+Connection state is not a frontend styling state. The backend derives it from the current configuration checksum and previously validated records.
+
+A built-in collector is considered "connected" when either condition is true:
+
+- The current configuration has successfully collected data.
+- The user clicked the connection button for the current configuration and backend validation succeeded.
+
+If endpoint, headers, base configuration, or credential fingerprint changes after the last successful validation, the state returns to "needs reconnection".
+
+## Frontend Entry Points
+
+### Data Source Catalog
+
+Files:
+
+- [DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx)
+- [index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
+
+Current behavior:
+
+- Built-in and custom data sources are merged into a `UnifiedDataSource` list.
+- The table only keeps view, collect, and status actions.
+- Clicking the name opens a read-only drawer.
+- The drawer shows:
+  - Whether the source is built in
+  - Whether it is enabled
+  - Module, priority, and frequency
+  - Endpoint
+  - Headers
+  - Base configuration
+  - Whether credentials are required
+- When tasks are running, the top progress area shows a clickable `Collecting N` pill.
+- Clicking `Collecting N` opens a task list modal with per-task progress.
+
+`data-source-bulk-toolbar__running-pill` is the styling entry point for the "Collecting" pill. It is aligned with other status tags, while hover treatment, arrow affordance, and blue outline indicate interactivity.
+
+### Collector Settings
+
+File:
+
+- [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx)
+
+Current behavior:
+
+- The `collector_credentials` tab is displayed as "Collector Settings".
+- A select lists all built-in collectors.
+- The only button beside the select is a plug icon for health checks.
+- Status tags below the select show:
+  - `Credentials required` / `No credentials required`
+  - Module
+  - `Enabled` / `Disabled`
+  - `Unchecked` / `Available` / `Unavailable`
+  - Whether the endpoint is overridden
+- Collectors that require credentials place the credential card above base configuration.
+- Collectors without credentials only show base configuration.
+
+The connection button uses an inline Tabler-style plug icon with `plug-connected` semantics, avoiding the older refresh icon for a connection action.
+
+## Backend APIs
+
+### Data Source Configuration List
+
+```http
+GET /api/v1/datasources/configs/all
+```
+
+Returns a merged view of YAML default data sources and database overrides. This route must be declared before `/configs/{config_id}`; otherwise FastAPI treats `all` as a path parameter and returns 422.
+
+Returned fields include:
+
+- `name`
+- `default_url`
+- `endpoint`
+- `is_overridden`
+- `is_active`
+- `source_type`
+- `auth_type`
+- `headers`
+- `config`
+- `config_id`
+- `description`
+
+Before returning `config`, internal connectivity validation fields are removed so the frontend does not display validation metadata as user configuration.
+
+### Built-In Collector Connection Status
+
+```http
+POST /api/v1/datasources/configs/builtin/connection-status
+```
+
+Purpose:
+
+- Accept a candidate configuration.
+- Compute its checksum.
+- Determine whether the current configuration is already connected.
+
+The current frontend mostly performs an immediate check through the connection button and does not strongly depend on this endpoint. It remains the backend basis for future save-button disabling and restoring initial page state.
+
+### Built-In Collector Connectivity Validation
+
+```http
+POST /api/v1/datasources/configs/builtin/connect
+```
+
+Purpose:
+
+- Free collectors request the endpoint directly.
+- Credentialed collectors go through their credential provider.
+- Successful validation writes a system-level connection record.
+
+Successful responses include:
+
+- `success`
+- `connected`
+- `checksum`
+- `stage`
+- `message`
+- `response_time_ms`
+- `credential_provider`
+- `credential_source`
+
+### BarentsWatch AIS Connectivity Validation
+
+```http
+POST /api/v1/settings/integrations/barentswatch/connect
+GET  /api/v1/settings/integrations/barentswatch/connectivity
+```
+
+BarentsWatch uses separate endpoints because draft credentials must be validated before saving:
+
+- Use draft `client_id` / `client_secret` to fetch a token.
+- Use that token to request the AIS endpoint.
+- After success, write a built-in collector connection record using the draft credential fingerprint.
+
+## Connectivity Validation Service
+
+File:
+
+- [datasource_connectivity.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_connectivity.py)
+
+Core responsibilities:
+
+- Compute built-in collector configuration checksums.
+- Read credentials from environment variables and `~/.zshrc`.
+- Determine whether the current configuration is already connected.
+- Run endpoint health checks.
+- Save successful connection records.
+
+### Checksum Inputs
+
+The checksum includes:
+
+- Collector name
+- Endpoint
+- Auth type
+- Headers
+- Config after removing internal validation fields
+- Credential provider
+- Credential fingerprint
+
+The credential fingerprint is a hash of credential content. Plaintext credentials are not written into connection records.
+
+### Connection Records
+
+Successful connection records are written to `SystemSetting`:
+
+```text
+category = datasource_connectivity_validations
+```
+
+The payload uses collector source as the key:
+
+```json
+{
+  "barentswatch_vessels": {
+    "checksum": "...",
+    "status": "success",
+    "validated_at": "2026-04-29T00:00:00+00:00",
+    "status_code": 200,
+    "credential_source": "datasource_config",
+    "connected_by": "connection_button"
+  }
+}
+```
+
+`connected_by` currently has two sources:
+
+- `connection_button`: the user manually clicked the connection button.
+- `collection`: a collection task completed successfully, so the system recorded the current effective configuration as connected.
+
+### Successful Collection Means Connected
+
+After a successful collection, the scheduler writes a connection record:
+
+- [scheduler.py](/home/ray/dev/linkong/planet/backend/app/services/scheduler.py)
+
+This prevents collectors that already have data from asking the user to validate again. Reconnection is only required when the configuration checksum changes.
+
+## BarentsWatch AIS Credential Chain
+
+Files:
+
+- [barentswatch.py](/home/ray/dev/linkong/planet/backend/app/services/barentswatch.py)
+- [vessel_ais.py](/home/ray/dev/linkong/planet/backend/app/services/collectors/vessel_ais.py)
+
+Resolution priority:
+
+1. `DataSourceConfig.auth_config`
+2. `DataSourceConfig.config`
+3. Environment variables
+4. `~/.zshrc`
+
+Supported environment variables:
+
+```bash
+export BARENTSWATCH_CLIENT_ID="..."
+export BARENTSWATCH_CLIENT_SECRET="..."
+```
+
+Historical misspellings are also supported:
+
+```bash
+export BARRENTSWATCH_CLIENT_ID="..."
+export BARRENTSWATCH_CLIENT_SECRET="..."
+```
+
+Token request rules:
+
+- Token URL: `https://id.barentswatch.no/connect/token`
+- `Content-Type`: `application/x-www-form-urlencoded`
+- Body:
+  - `grant_type=client_credentials`
+  - `client_id`
+  - `client_secret`
+  - `scope=ais`
+
+AIS request rules:
+
+- Default endpoint: `https://live.ais.barentswatch.no/v1/latest/combined`
+- Header: `Authorization: Bearer <access_token>`
+
+`VesselAISCollector` no longer reads environment variables directly. It goes through `resolve_barentswatch_config()` and `fetch_barentswatch_access_token()` so settings, connectivity validation, and collection do not fork into three credential flows.
+
+## Credential Guide
+
+File:
+
+- [credential_guides.py](/home/ray/dev/linkong/planet/backend/app/services/credential_guides.py)
+
+APIs:
+
+```http
+GET  /api/v1/settings/credential-guides/{provider}
+POST /api/v1/settings/credential-guides/{provider}/generate
+POST /api/v1/settings/credential-guides/{provider}/reset
+```
+
+Currently supported:
+
+- `barentswatch`
+
+The default guide includes the official BarentsWatch tutorial:
+
+```text
+https://developer.barentswatch.no/docs/tutorial
+```
+
+If the user clicks that the tutorial is not useful, the backend sends the default prompt to AI Provider, generates a new Chinese tutorial, and saves it to `SystemSetting`:
+
+```text
+category = collector_credential_guides
+```
+
+Reset deletes the custom tutorial and restores the default guide.
+
+## Save Rules
+
+When built-in collector configuration is saved, the internal `connectivity_validation` field is removed so validation state does not mix with user configuration.
+
+BarentsWatch `client_secret` has special handling:
+
+- The input shows a masked preview.
+- If the submitted value still matches the masked preview, the backend keeps the old secret.
+- If a new value is submitted, the secret is replaced.
+- The previous separate "clear current secret" checkbox is no longer provided.
+
+## Test Coverage
+
+Related tests:
+
+- [test_vessels.py](/home/ray/dev/linkong/planet/backend/tests/test_vessels.py)
+
+Added coverage:
+
+- BarentsWatch credentials can be parsed from `~/.zshrc`.
+- When environment variables are empty, `resolve_barentswatch_config()` can fall back to `~/.zshrc`.
+- Vessel data conversion and GeoJSON output remain compatible.
+
+## Current Provider Coverage
+
+Credential providers currently supported:
+
+- `barentswatch`
+- `spacetrack`
+
+Other collectors with `requires_credentials=true` return that their credential chain has not been wired yet, and the frontend shows `Unavailable`.

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

@@ -187,7 +187,7 @@ Current reality:
 - 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
 
-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).
+Implementation detail for the recommended `activity layer` is expanded in the [BGP Region Aggregation Plan](/home/ray/dev/linkong/planet/docs/plans/earth-bgp-region-aggregation-plan.md).
 
 So the immediate next milestone is:
 

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

@@ -4,8 +4,8 @@ This document describes the current real structure of the Earth display frontend
 
 Related references:
 
-- [rules.md](/home/ray/dev/linkong/planet/rules.md)
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
+- [Project Rules](/home/ray/dev/linkong/planet/rules.md)
+- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
 
 ## Current Goal
 
@@ -249,4 +249,4 @@ Therefore:
 
 For console structure, see:
 
-- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
+- [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)

docs/technical/en/earth-interactable-usage.md

@@ -0,0 +1,270 @@
+# Earth Interactable Usage
+
+`Interactable` is the shared rendering entry point for icon-like interactive elements on the Earth surface. It extracts the pattern proven by the vessel layer into reusable behavior: normal state uses batched `THREE.Points`, hover and locked states use small overlays, picking uses screen-space hit testing, icon assets are normalized into canvas textures, and the shared layer handles glow, state, size, ground rendering, and same-coordinate avoidance.
+
+Currently integrated layers:
+
+| Layer | Business File | Icon Source | Extra Animation |
+| --- | --- | --- | --- |
+| AIS vessels | `frontend/public/earth/js/vessels.js` | canvas draw, moving triangle / anchored dot | Vessel tracks are still maintained by the business layer |
+| Compute centers | `frontend/public/earth/js/compute-centers.js` | `assets/icons/compute-*.svg` | Estimated-location `?` badge is added through `icon.afterDraw()` |
+| BGP events | `frontend/public/earth/js/bgp.js` | canvas draw, symbol by event type | Expanding rings are still maintained by the BGP business layer |
+| BGP observers | `frontend/public/earth/js/bgp.js` | `assets/icons/bgp-broadcast-pin.svg` | Halo, activity core, coverage wedge, and radar sweep remain in the BGP business layer |
+
+Landing sites were previously attempted on Interactable, but pin-style SVGs were fragmented by `THREE.Points` depth testing near the Earth edge. They now use a dedicated `THREE.Sprite` path with a yellow flat-sphere texture generated by canvas. The old SVG assets remain in `assets/icons/`, but landing sites no longer depend on SVG at runtime.
+
+## Why Interactable Exists
+
+Before this layer, each surface icon layer could easily reimplement its own version of:
+
+- icon texture generation
+- hover / locked state
+- glow styling
+- picking radius
+- zoom-dependent size strategy
+- overlap avoidance for identical coordinates
+
+When this logic is scattered across business files, visual behavior drifts and later tuning becomes layer-by-layer repair. The boundary of `Interactable` is: the shared layer owns how icons remain stable on Earth and how they are selected; the business layer owns where data comes from, what the icon means, what detail cards show, and whether extra animation exists.
+
+## Entry Point
+
+```javascript
+import { createInteractableLayer } from "./interactable.js";
+```
+
+Core call shape:
+
+```javascript
+const layer = createInteractableLayer({
+  id: "example",
+  objectType: "example_object",
+  renderOrder: 4.4,
+  altitudeOffset: 0.2,
+  pointSize: 34,
+  icon: {
+    draw(context, options) {
+      // draw canvas icon
+    },
+  },
+  getPosition: (item) => ({
+    latitude: item.latitude,
+    longitude: item.longitude,
+  }),
+  getKind: (item) => item.kind || "default",
+});
+```
+
+Business modules usually expose only a thin wrapper:
+
+```javascript
+export function getExampleMarkers() {
+  return layer.getMarkers();
+}
+
+export function getExamplePointerIntersections(options) {
+  return layer.getPointerIntersections(options);
+}
+
+export function setExampleMarkerState(marker, state = "normal") {
+  layer.setMarkerState(marker, state);
+}
+
+export function updateExampleVisualState(lockedObjectType, lockedObject, camera) {
+  layer.updateVisualState(lockedObjectType, lockedObject, camera);
+}
+```
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `id` | required | Unique layer id used for group name, avoidance registration, and debug. |
+| `objectType` | `id` | Business type written to `marker.userData.type`; the main interaction layer uses it to identify locked objects. |
+| `renderOrder` | `4` | Base render order for normal points and hover / locked overlays. |
+| `altitudeOffset` | `0.2` | Business altitude, used as `CONFIG.earthRadius + altitudeOffset` for the original surface position. |
+| `pointSize` | `32` | Base screen pixel size used by both normal points and overlays. |
+| `sizeMode` | `"fixed"` | Fixed screen size by default; non-`"fixed"` modes scale by camera distance. |
+| `sizeScale` | `{ referenceFov: 75, min: 0.12, max: 3 }` | Scaling bounds when `sizeMode !== "fixed"`. |
+| `atlasCellSize` | `128` | Canvas texture cell size for icons. |
+| `colors` | `{}` | Supports `normal`, flattened kind keys, and `byKind`. |
+| `opacity` | `{ normal: 0.88, dimmed: 0.26, hover: 0.98, locked: 1 }` | Opacity per state. |
+| `stateScale` | `{ hover: 1, locked: 1, dimmed: 1 }` | Size multiplier per state. |
+| `pulse` | `{}` | Optional locked-state breathing scale, with `enabled`, `speed`, and `amplitude`. |
+| `avoidance` | `{ enabled: true, precision: 4, radius: 1.1, step: 0.35 }` | Same-coordinate avoidance across Interactable layers. |
+| `icon` | required | Icon source, supporting canvas draw, SVG / image asset, state asset, anchor, and post-processing. |
+| `getPosition(item)` | required | Returns `{ latitude, longitude }` or `THREE.Vector3`. |
+| `getKind(item)` | `item.type || "default"` | Returns a business kind for color and texture buckets. |
+| `getRotationBin(marker)` | `0` | Returns a rotation bucket, such as 32 heading buckets for vessels. |
+| `getBucketKey(marker)` | `String(getRotationBin(marker))` | Returns a texture / geometry bucket key. |
+| `getPointSizeMultiplier(marker)` | `1` | Per-marker size multiplier. BGP events use severity; observers use activity. |
+| `getUserData(item)` | `item` | Business fields written onto the marker. |
+
+## Icon Configuration
+
+`icon.anchor` is optional and defaults to `{ x: 0.5, y: 0.5 }`, meaning the texture center aligns with the marker coordinate. It is only suitable for small visual anchor offsets. If the icon body is large and must remain fully visible at the Earth edge, such as the old landing-site pin, it should not be forced through `THREE.Points + depthTest`; the body will be clipped by Earth depth.
+
+### Canvas Icons
+
+Canvas icons fit vessels and BGP events where symbols need to be drawn dynamically by state or rotation:
+
+```javascript
+const vesselIconLayer = createInteractableLayer({
+  id: "vessels",
+  objectType: "vessel",
+  pointSize: 34,
+  icon: {
+    draw(context, { marker, rotationBin = 0, glow = false, color = "#ffffff" }) {
+      if (!marker.userData.anchored) {
+        context.rotate((rotationBin / 32) * Math.PI * 2);
+      }
+      context.fillStyle = color;
+      context.shadowColor = color;
+      context.shadowBlur = glow ? 14 : 0;
+      context.beginPath();
+      context.moveTo(0, -37);
+      context.lineTo(28, 32);
+      context.lineTo(0, 17);
+      context.lineTo(-28, 32);
+      context.closePath();
+      context.fill();
+    },
+  },
+  getRotationBin: getCourseBin,
+  getBucketKey: (marker) => `${marker.userData.anchored ? "anchored" : "moving"}:${getCourseBin(marker)}`,
+});
+```
+
+When `icon.coordinates !== "canvas"`, `Interactable` translates the context to the atlas center first. Vessel-style icons that already draw around center coordinates do not need to declare `coordinates`.
+
+### SVG / Image Asset Icons
+
+Asset icons fit facilities such as compute centers and BGP observers:
+
+```javascript
+const computeCenterIconLayer = createInteractableLayer({
+  id: "computeCenters",
+  objectType: "compute_center",
+  pointSize: 36,
+  atlasCellSize: 128,
+  icon: {
+    coordinates: "canvas",
+    colorable: false,
+    fitSize: 60,
+    glowBlur: 16,
+    getSource({ marker, item }) {
+      const siteType = marker?.userData?.site_type || item?.site_type || "gpu_cluster";
+      return COMPUTE_CENTER_ICON_SOURCES[siteType];
+    },
+    afterDraw(context, { marker, item }) {
+      if (marker?.userData?.is_estimated ?? item?.is_estimated) {
+        drawComputeCenterEstimatedBadge(context, true);
+      }
+    },
+  },
+});
+```
+
+Asset conventions:
+
+- SVG / image files live in `frontend/public/earth/assets/icons/` and are referenced as `/earth/assets/icons/name.svg`.
+- Original SVGs should keep a standard `viewBox` and paths; avoid hard-coding transform only for display size.
+- Display size is controlled by `icon.fitSize`; it can be a number, `{ width, height }`, or a function.
+- If `icon.colorable !== false` and state colors are provided, the shared layer first draws the asset to a temporary canvas and then tints it with `source-in`.
+- Multicolor images or SVGs that should not be tinted must set `colorable: false`.
+
+## Lifecycle
+
+Typical load flow:
+
+```javascript
+export async function loadExampleLayer(_scene, earth) {
+  clearExampleData(earth);
+
+  const markerData = await fetchExampleData();
+  await layer.preloadAssets(markerData);
+  layer.setData(markerData);
+  layer.attach(earth);
+  layer.setVisible(showExampleLayer);
+
+  return { totalCount: layer.getCount() };
+}
+```
+
+Method responsibilities:
+
+| Method | Description |
+| --- | --- |
+| `preloadAssets(items)` | Collects asset sources that may be used by normal / hover / locked states and preloads them with browser `Image`. Canvas-drawn icons can skip this. |
+| `setData(items)` | Clears old points, creates markers, registers avoidance, and rebuilds `THREE.Points` by bucket. |
+| `attach(parent)` | Mounts the layer group onto the Earth root. |
+| `setVisible(next)` | Controls visibility for the group, points, and overlays. |
+| `setMarkerState(marker, state)` | Sets `normal` / `hover` and other states, then invalidates visual state. |
+| `updateVisualState(focusType, focusObject, camera)` | Updates normal opacity / size and refreshes hover / locked overlays. |
+| `getPointerIntersections(options)` | Runs screen-space picking and returns hits sorted by pixel distance. |
+| `clearData(parent)` | Unregisters avoidance, disposes geometry / material, clears markers, and removes the group from the parent. |
+
+## Picking Integration
+
+`Interactable` does not depend on the default Three.js raycast for `Points`. The main interaction layer passes Earth, camera, pointer, and hit radius:
+
+```javascript
+const intersects = getVesselPointerIntersections({
+  earth,
+  camera,
+  pointer,
+  radiusPx: 22,
+  width: window.innerWidth,
+  height: window.innerHeight,
+});
+```
+
+The shared layer:
+
+1. Converts the camera position into Earth-local coordinates.
+2. Skips markers on the back side.
+3. Projects marker world position into screen coordinates.
+4. Uses `radiusPx` for pixel-distance hits.
+5. Returns the nearest candidate objects.
+
+Earth dragging, inertia, and hover throttling still belong to `main.js` because they depend on global input state.
+
+## Same-Coordinate Avoidance
+
+Avoidance is enabled by default and applies to all layers created through `createInteractableLayer()`. The shared layer builds an `icon_avoidance_key` from latitude / longitude or `THREE.Vector3`, then arranges markers with the same key into a small circle along the surface tangent plane.
+
+Key points:
+
+- `icon_base_position` keeps the original business position.
+- Avoidance only changes rendering and picking position. It does not change business latitude / longitude.
+- When a single marker returns to its original position, it uses the business surface position computed from `altitudeOffset`.
+- When multiple markers share coordinates, the first ring uses `avoidance.radius`; later rings add `avoidance.step`.
+
+If a business layer must stay exactly on the original point, disable avoidance explicitly:
+
+```javascript
+createInteractableLayer({
+  id: "strict-layer",
+  avoidance: { enabled: false },
+});
+```
+
+## Business Animation Boundary
+
+`Interactable` currently owns only the icon body and common hover / locked overlays. Complex animations remain in business modules, but should follow the Interactable marker position:
+
+- BGP event expanding rings are independent ring sprites created by `bgp.js`, updated every frame with `position.copy(marker.position)`.
+- BGP observer halo, status core, coverage halo, and coverage wedge are managed by `bgp.js`; the icon body is managed by Interactable.
+- Vessel tracks remain in `vessels.js` because they depend on track data loaded after a click.
+
+This boundary avoids pushing every animation type into the shared interface too early. If multiple layers reuse the same animation type later, it can move into an Interactable `animations` extension.
+
+## New Layer Checklist
+
+1. Prepare marker data in the business file and keep required business fields.
+2. Choose an icon type: canvas draw, SVG / image asset, or dynamic `getSource()`.
+3. Configure `pointSize`, `icon.fitSize`, `colors`, `opacity`, and `stateScale`.
+4. Provide `getPointSizeMultiplier()` if business-specific size variation is needed.
+5. Provide `getRotationBin()` and a stable `getBucketKey()` if rotation exists.
+6. During load, call `preloadAssets()` before `setData()`, `attach()`, and `setVisible()`.
+7. Wire `getPointerIntersections()` in `main.js` and reuse the existing hover / locked state update flow.
+8. Record altitude, `renderOrder`, `pointSize`, and animation ordering in the layer style index and render order documents.

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

@@ -1,6 +1,6 @@
 # Earth Layer Style Property Index
 
-This document records the material, color, opacity, line width, radius offset, and `renderOrder` style properties of all Earth frontend layers. For layer ordering relationships, see [earth-render-layer-order.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-render-layer-order.md).
+This document records the material, color, opacity, line width, radius offset, and `renderOrder` style properties of all Earth frontend layers. For layer ordering relationships, see [Earth Render Layer Order](/home/ray/dev/linkong/planet/docs/technical/en/earth-render-layer-order.md).
 
 ## Naming Conventions
 

docs/technical/en/earth-satellite-footprint-policy.md

@@ -4,8 +4,8 @@ This document records the current product boundary, data rationale, and implemen
 
 Related context:
 
-- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
-- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
+- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
+- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/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)
 

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

@@ -4,8 +4,8 @@ This document describes the current real structure of the console frontend. The
 
 Related references:
 
-- [rules.md](/home/ray/dev/linkong/planet/rules.md)
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
+- [Project Rules](/home/ray/dev/linkong/planet/rules.md)
+- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
 
 ## Current Goal
 
@@ -263,7 +263,7 @@ These principles have been repeatedly validated in the project:
 
 For detailed experience, see:
 
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
+- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
 
 ## Recommended Change Approach
 
@@ -290,4 +290,4 @@ Therefore:
 
 For Earth-related structure, see:
 
-- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
+- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)

docs/technical/en/manual.md

@@ -7,7 +7,7 @@ This manual is for daily use, demos, development integration, and local operatio
 - Console: admin backend (login required)
 - Docs: public developer documentation and manual
 
-For the shortest path to getting started, see [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md).
+For the shortest path to getting started, see [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md).
 
 ## Entry Overview
 
@@ -585,9 +585,9 @@ When something goes wrong, follow this sequence:
 
 ## Related Docs
 
-- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
-- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
-- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
-- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
-- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
-- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
+- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
+- [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
+- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
+- [Earth Layer Style Reference](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
+- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
+- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)

docs/technical/en/quickstart.md

@@ -194,7 +194,7 @@ This shuts down the frontend, backend, AI Provider, PostgreSQL, and Redis.
 
 ## Next Steps
 
-- Full usage guide: [manual.md](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
-- Console structure: [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
-- Earth structure: [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
-- Backend collectors: [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
+- Full usage guide: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
+- Console structure: [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
+- Earth structure: [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
+- Backend collectors: [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)

docs/technical/zh/README.md

@@ -21,10 +21,10 @@
 
 ## 使用入口
 
-- [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 的完整使用手册
-- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)：数据源目录、采集器设置、连接验证、BarentsWatch 凭证链路
-- [earth-interactable-usage.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)：Earth 地表可交互图标 `Interactable` 的接口、生命周期和接入示例
+- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)：从零启动 Planet 的最短路径
+- [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)：控制台、`planet.sh`、Earth 和 Docs 的完整使用手册
+- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)：数据源目录、采集器设置、连接验证、BarentsWatch 凭证链路
+- [Earth 可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)：Earth 地表可交互图标 `Interactable` 的接口、生命周期和接入示例
 
 不适合放入这里的内容：
 
@@ -34,4 +34,4 @@
 
 这些应放入：
 
-- [docs/plans/README.md](/home/ray/dev/linkong/planet/docs/plans/README.md)
+- [计划文档索引](/home/ray/dev/linkong/planet/docs/plans/README.md)

docs/technical/zh/backend-collectors.md

@@ -224,7 +224,7 @@ if datasource.last_status == "success":
 相关实现见：
 
 - [datasource_connectivity.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_connectivity.py)
-- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
 
 ## 八、相关代码文件
 
@@ -314,7 +314,7 @@ POST /api/v1/settings/credential-guides/{provider}/reset
 
 更多细节见：
 
-- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
 
 ## 十一、数据使用场景
 

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

@@ -187,7 +187,7 @@ Earth info-card 策略：
 - 这是预期行为，因为 incident 是聚合和去噪后的结果
 - 但 incident-first 渲染会让 Earth 显得过于安静，除非有另一层始终可用的 activity layer
 
-推荐 `activity layer` 的实现细节在 [bgp-region-aggregation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-bgp-region-aggregation-plan.md) 中展开。
+推荐 `activity layer` 的实现细节在 [BGP 区域聚合计划](/home/ray/dev/linkong/planet/docs/plans/earth-bgp-region-aggregation-plan.md) 中展开。
 
 因此最近的里程碑是：
 

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

@@ -4,8 +4,8 @@
 
 相关规则建议一起参考：
 
-- [rules.md](/home/ray/dev/linkong/planet/rules.md)
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
+- [项目规则](/home/ray/dev/linkong/planet/rules.md)
+- [前端布局指南](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
 
 ## 当前目标
 
@@ -142,7 +142,7 @@ React 路由入口：
 
 新闻巡航摘要计划见：
 
-- [earth-news-cruise-summary-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-news-cruise-summary-plan.md)
+- [Earth 新闻巡航摘要计划](/home/ray/dev/linkong/planet/docs/plans/earth-news-cruise-summary-plan.md)
 
 ## 当前样式分层
 
@@ -311,7 +311,7 @@ asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文
 
 接口细节、生命周期和接入示例见：
 
-- [earth-interactable-usage.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)
+- [Earth 可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)
 
 ### 视角控制反馈
 

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/zh/earth-render-layer-order.md)
+[Earth 渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)
 查看。
 
 ## 命名约定

docs/technical/zh/earth-satellite-footprint-policy.md

@@ -4,8 +4,8 @@
 
 相关上下文：
 
-- [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)
+- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.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)
 

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

@@ -4,8 +4,8 @@
 
 相关规则建议一起参考：
 
-- [rules.md](/home/ray/dev/linkong/planet/rules.md)
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
+- [项目规则](/home/ray/dev/linkong/planet/rules.md)
+- [前端布局指南](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
 
 ## 当前目标
 
@@ -292,7 +292,7 @@
 
 相关后端设计见：
 
-- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
 
 ### 3. 复杂工作区页面
 
@@ -320,4 +320,4 @@
 
 详细经验见：
 
-- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
+- [前端布局指南](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

docs/technical/zh/manual.md

@@ -7,7 +7,7 @@
 - 控制台：登录后的管理后台
 - Docs：公开开发文档与使用手册
 
-快速启动路径见 [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。
+快速启动路径见 [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。
 
 ## 入口总览
 
@@ -629,10 +629,10 @@ source ~/.zshrc && bun run build
 
 ## 相关文档
 
-- [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)
-- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
+- [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
+- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
+- [Earth 图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
+- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
+- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
+- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)

docs/technical/zh/quickstart.md

@@ -194,7 +194,7 @@ ss -ltnp | grep -E ':3000|:8000'
 
 ## 下一步
 
-- 完整操作说明见 [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)
+- 完整操作说明见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
+- 控制台结构见 [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
+- Earth 结构见 [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
+- 后端采集器见 [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)

docs/version-history.md

@@ -16,12 +16,13 @@
 ## Current Version
 
 - `main` 当前主线历史推导到：`0.16.5`
-- `dev` 当前开发分支历史推导到：`0.46.0`
+- `dev` 当前开发分支历史推导到：`0.46.1`
 
 ## Timeline
 
 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.46.1` | bugfix | `dev` | `pending` | 修复新增 Docs 技术文档未进前端白名单导致页面不可访问的问题，补齐英文文档并固化白名单/双语/裸文件标题检查 |
 | `0.46.0` | feature | `dev` | `pending` | Earth 新增通用 Interactable 图标层，统一船只、算力中心、BGP 事件/观测站交互图标，并优化登陆点与 toolbar 初始渲染 |
 | `0.45.0` | feature | `dev` | `pending` | 新增采集任务 fetching 阶段量化进度，收敛 AI Provider 运行期环境注入和 Docker build context |
 | `0.44.2` | bugfix | `dev` | `pending` | 补充 Earth 船只批量渲染、屏幕拾取、图层顺序、样式参考和性能计划状态文档 |

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planet-frontend",
-  "version": "0.46.0",
+  "version": "0.46.1",
   "private": true,
   "packageManager": "bun@1",
   "dependencies": {

frontend/src/pages/Docs/docs-content.ts

@@ -95,6 +95,10 @@ const DOCS_METADATA: Record<string, DocsMetadataEntry> = {
     zh: { title: '新闻直播采集格式', group: 'Earth', order: 15 },
     en: { title: 'News Live Streams Collector Format', group: 'Earth', order: 15 },
   },
+  'earth-interactable-usage.md': {
+    zh: { title: 'Earth 可交互图标接入', group: 'Earth', order: 16 },
+    en: { title: 'Earth Interactable Usage', group: 'Earth', order: 16 },
+  },
   'frontend-admin-frontend-context.md': {
     zh: { title: '控制台前端结构', group: 'Frontend', order: 20 },
     en: { title: 'Admin Frontend Context', group: 'Frontend', order: 20 },
@@ -111,6 +115,10 @@ const DOCS_METADATA: Record<string, DocsMetadataEntry> = {
     zh: { title: '系统服务控制', group: 'Backend', order: 31 },
     en: { title: 'System Service Control', group: 'Backend', order: 31 },
   },
+  'datasource-collector-settings-connectivity.md': {
+    zh: { title: '数据源、采集器设置与连接验证', group: 'Backend', order: 32 },
+    en: { title: 'Datasource Collector Settings and Connectivity', group: 'Backend', order: 32 },
+  },
   'agents-aiprovider.md': {
     zh: { title: 'AI Provider 指南', group: 'Agents', order: 40 },
     en: { title: 'AI Provider Guide', group: 'Agents', order: 40 },

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "planet"
-version = "0.46.0"
+version = "0.46.1"
 description = "智能星球计划 - 态势感知系统"
 requires-python = ">=3.14"
 dependencies = [

uv.lock

@@ -475,7 +475,7 @@ wheels = [
 
 [[package]]
 name = "planet"
-version = "0.46.0"
+version = "0.46.1"
 source = { virtual = "." }
 dependencies = [
     { name = "aiofiles" },