linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

release: bump version to 0.50.0

Browse Source
This commit is contained in:
rayd1o
2026-05-10 22:06:01 +08:00
parent e1984c7a35
commit 455b8360d0
80 changed files with 10936 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/technical/en/README.md
View File

@@ -25,6 +25,7 @@ What belongs here:
- [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
- [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md): Central troubleshooting entry for Windows / WSL, ports, dependencies, motion capture, credentials, and Docs permissions
- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md): Collect and preview coordinate candidates for compute centers and BGP collectors on Earth
- [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
- [Shared Location Resolution Pipeline Development Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-development.md): Backend location resolver / pipeline interfaces, registries, and extension points

96
docs/technical/en/agents-aiprovider.md
View File

@@ -23,11 +23,12 @@ The recommended default is:
- business-level request shaping
- stable `/api/v1/ai/...` endpoints
- internal service-to-service authentication toward `aiprovider`
- reading the default provider, model, and per-provider keys saved in Settings, then overriding `aiprovider` `.env` defaults through internal headers
`aiprovider` is responsible for:
- model protocol adaptation
- provider selection by `.env`
- provider selection by `.env` when no backend override headers are present
- timeout and lightweight retry
- request tracing via `X-Request-ID`
@@ -85,6 +86,18 @@ Optional tracing header:
The backend will propagate `X-Request-ID` to `aiprovider` and return the same header in the response.
### Settings API
The AI settings page uses:
- `GET /api/v1/settings/integrations`
- `PUT /api/v1/settings/integrations`
- `POST /api/v1/settings/integrations/ai-provider/connect`
- `GET /api/v1/settings/integrations/ai-provider/secrets`
- `GET /api/v1/settings/integrations/ai-provider/presets`
These endpoints require an authenticated user. The `secrets` endpoint is only used when the settings page reveals a key or token; hiding the field restores the masked preview.
### AI provider internal API
Internal-only endpoints:
@@ -172,6 +185,75 @@ Both services also return:
## Configuration
### Runtime Configuration Flow
The backend Settings system owns the global LLM default. The runtime flow is:
1. Frontend or application code calls a `backend` `/api/v1/ai/...` endpoint.
2. `backend` reads `category = external_integrations` from the PostgreSQL `system_settings` table.
3. `payload.ai_provider.default_provider` selects the active provider.
4. `payload.ai_provider.providers[provider]` supplies that provider's `api_key`, `provider_api`, `base_url`, `model`, `max_tokens`, and `anthropic_version`.
5. `backend` converts those values to internal headers such as `X-AI-Provider`, `X-AI-Provider-API`, `X-AI-Base-URL`, `X-AI-API-Key`, and `X-AI-Model`.
6. `aiprovider` uses those headers to override its `.env` defaults before calling the real model vendor.
After the AI settings page saves a new default provider/model/key, Playground, alert briefs, datasource mapping generation, and other backend AI calls all use that same default.
#### Persistence Shape
AI settings are persisted in PostgreSQL, not a JSON file. The core payload shape is:
```json
{
"ai_provider": {
"service_url": "http://localhost:8010",
"service_token": "",
"default_provider": "openai",
"providers": {
"openai": {
"provider_api": "openai-completions",
"base_url": "https://api.openai.com/v1",
"model": "gpt-5.1",
"api_key": "<saved secret>",
"max_tokens": 4096,
"anthropic_version": "2023-06-01"
},
"minimax": {
"provider_api": "anthropic-messages",
"base_url": "https://api.minimaxi.com/anthropic",
"model": "MiniMax-M2.7",
"api_key": "<saved secret>",
"max_tokens": 1200,
"anthropic_version": "2023-06-01"
}
},
"timeout_seconds": 60,
"retry_attempts": 2
}
}
```
Legacy single-slot settings are mapped to `providers[provider]` on read and are written back in the new shape on save.
#### Key Fallback
Each provider has its own key slot. Resolution order is:
1. `providers[provider].api_key` in PostgreSQL
2. the provider-specific variable in `aiprovider/.env`, such as `OPENAI_API_KEY`, `MINIMAX_API_KEY`, or `ANTHROPIC_API_KEY`
3. the generic `AI_API_KEY` in `aiprovider/.env`
`.env` is only a fallback. After the settings page saves successfully, or after the connection test succeeds, PostgreSQL becomes the global default source.
#### Settings Page Behavior
- The Provider select controls the global default provider.
- The model select saves the default model for the selected provider.
- The LLM API Key field shows a masked preview while hidden; keys with a `-` prefix keep the prefix, for example `sk-********`, and keys without a prefix are fully masked.
- Clicking the eye icon fetches and displays the full plaintext value; hiding restores the masked preview.
- `Save AI Configuration` saves the current form as the global default.
- `Test Connection` uses the current form for a real model-chain test, then saves it as the global default only when the test succeeds.
- Leaving a key field empty keeps the old key; it does not delete it.
### Backend
Recommended backend `.env`:
@@ -208,6 +290,18 @@ AI_HTTP_RETRY_ATTEMPTS=2
AI_ANALYSIS_SYSTEM_PROMPT=你是态势感知分析助手。请基于输入的上下文、观测与约束，输出结构化、克制、可执行的分析。
```
Optional provider-specific keys:
```env
MINIMAX_API_KEY=sk-cp-xxxxx
OPENAI_API_KEY=sk-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
DEEPSEEK_API_KEY=sk-xxxxx
DASHSCOPE_API_KEY=sk-xxxxx
MOONSHOT_API_KEY=sk-xxxxx
OPENROUTER_API_KEY=sk-or-xxxxx
```
### OpenAI-compatible example
```env

33
docs/technical/en/earth-frontend-context.md
View File

@@ -81,7 +81,26 @@ Responsibilities:
- Status message
- Tooltip / error / cleanup logic
### 5. Globe and Terrain
### 5. Motion Capture Control Adapter
- [motion-control.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-control.js)
Responsibilities:
- Act as the Motion Provider manager for both `browser_camera` and `motion_agent`.
- Use browser `getUserMedia` plus local MediaPipe recognition by default; advanced setups can connect to the local Motion Capture Agent WebSocket.
- Handle browser camera permission/secure-context errors, plus Agent disconnects, reconnects, `status`, and `heartbeat` messages.
- Filter low-confidence and overly repeated gesture events.
- Map `rotate_left`, `rotate_right`, `rotate_up`, `rotate_down`, `zoom_in`, `zoom_out`, `focus_prev`, `focus_next`, `layer_prev`, `layer_next`, and `confirm` to the action entry points exposed by `main.js`.
- Parse `skeleton` debug events and dispatch `earth:motion-debug-frame`.
Gesture recognition may run locally in the browser or inside the local Agent, but neither path sends realtime camera frames to the SaaS cloud. `main.js` exposes rotation, zoom, target focus, layer switching, and confirm entry points, plus a `window.__planetEarth.motion` debug entry. The adapter starts only when `?motion=1` is present, browser local storage contains `planet-earth-motion-control-enabled=true`, or Earth settings enable Motion Debug Mode.
[motion-debug-panel.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-debug-panel.js) owns the debug panel. It listens for `earth:motion-debug-frame` and draws normalized skeleton joints and bones on a canvas. The Browser Camera provider also emits `earth:motion-debug-video-source` with the local `<video>` element so the panel can show a local preview behind the skeleton; `shared.motionDebugSkeletonOnly` switches the panel back to skeleton-only rendering. `Stop Matching Gestures` dispatches `earth:motion-recognition-pause`, which suppresses gesture execution while video and skeleton drawing continue. Unmatched skeletons are red; matched gestures turn green and display the gesture name. Settings are persisted under `shared.motionDebugEnabled`, `shared.motionProvider`, and `shared.motionDebugSkeletonOnly` in `planet.earth.settings.v2`, and both the switch and provider selector reserve `data-gatekeeper-permission="earth.motion_debug"`.
[presentation-controller.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/presentation-controller.js) is the new Presentation layer. In the first stage only Motion uses it: `motion-cruise-adapter.js` uses a persistent presentation that reuses the cruise fixed-card placement and connector, but mouse movement does not auto-hide the card. The connector recalculates source and target anchors every frame so dragged cards, globe rotation, and moving targets stay connected. BGP/News still use the existing `CruiseSequencer` auto-advance path to preserve the old cruise experience.
### 6. Globe and Terrain
- [earth.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/earth.js)
- [terrain.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/terrain.js)
@@ -92,7 +111,7 @@ Responsibilities:
- Real terrain mesh
- Terrain tile fetch, decode, displacement, and shading
### 6. Layer Modules
### 7. Layer Modules
- [satellites.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/satellites.js)
- [cables.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cables.js)
@@ -109,8 +128,12 @@ Each module is responsible for its own:
- State tracking (loaded, visible, hover, locked)
- Self-cleanup (dispose on scene destroy)
`tv.js` owns the live / aggregation-news tabs inside `media-panel`. Toolbar open and tab-switch actions write back through `earth:tv-visibility-change` and `earth:tv-tab-change`: panel visibility remains viewport-scoped at `views.<scope>.panelVisibility.media-panel`, while the active tab is stored at `shared.mediaPanelActiveTab`. Refreshing the page therefore restores the user's last live/news state. Temporary hides from `closeTransientMobileOverlays()` carry `persist:false` and do not overwrite the preference.
The compute-center layer row has a notification badge for GeoJSON `unresolved` records. The badge means "no trustworthy coordinates, cannot render on the globe"; it is different from the `?` marker drawn on already positioned but unconfirmed compute centers. Clicking the badge opens a fixed info card beside the layer panel. Row-level `采集` fetches candidates only. Header-level `一键采用` processes the queue top-to-bottom, saves the highest-confidence valid candidate, removes successful rows, renumbers the list, and dispatches `earth:compute-center-unresolved-count-change` so the badge updates immediately. When the batch ends, `earth:compute-center-location-saved` refreshes the real layer.
Location candidate state in the details card is cached in [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) by `entityType:entityId`. If the user closes the details card or unresolved queue and reopens the same compute center / BGP collector, previously collected candidates and status text are restored. Header-level `一键采用` prefers cached candidates, avoiding repeated online geocoding or LLM factcheck calls. After a location is saved, that entity's candidate list is cleared to a "refreshing layer" status so stale candidates do not keep misleading the user.
### AIS Vessel Layer
The vessel layer fetches `/api/v1/visualization/geo/vessels` and renders the aggregated AIS GeoJSON through `createInteractableLayer()`. By default it does not send a `limit` parameter, and `VESSEL_CONFIG.maxRenderedMarkers = 0` means the frontend does not clip the result to 5000 vessels. A positive `options.limit` or positive `maxRenderedMarkers` can still be used as an explicit temporary cap.
@@ -119,21 +142,21 @@ Vessel color and vessel type text must use the same normalized classification. `
AISStream `PositionReport` messages commonly carry live position and `MetaData.ShipName`, while vessel type usually comes from lower-frequency `ShipStaticData.Type`. The backend normalizes `MetaData.ShipName` into the vessel name and maps numeric type codes into Cargo / Tanker / Passenger / Fishing / Military where available. Missing type detail should wait for a static AIS message or the planned vessel profile enrichment; the frontend should not invent a more specific type.
### 7. HUD Panels and Search
### 8. HUD Panels and Search
- [hud-panels.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/hud-panels.js)
- [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js)
- [search.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/search.js)
- [legend.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/legend.js)
### 8. Cruise Mode
### 9. Cruise Mode
- [cruise-sequencer.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cruise-sequencer.js)
- [callout-connector.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/callout-connector.js)
The cruise sequencer handles generic logic: current target, queue order, camera focus, and dwell / hide / switch. Business modules supply target queues and content — they should not contain camera control logic.
### 9. Constants
### 10. Constants
- [constants.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/constants.js)

306
docs/technical/en/faq.md Normal file
View File

@@ -0,0 +1,306 @@
# FAQ
This page collects common troubleshooting paths for local startup, Windows / WSL, dependencies, motion capture, credentials, and Docs permissions. Deeper background stays in the topic-specific docs; this page focuses on what to check first and which command to run.
## Startup and Ports
### What should I do when the backend port is already in use?
The error usually looks like:
```text
Backend address is already in use: 0.0.0.0:8000 / 127.0.0.1:8000 / [::1]:8000
Address already in use
```
First try:
```bash
./planet.sh restart -b
```
If the port remains occupied, start on a different backend port:
```bash
./planet.sh start -b 8001
```
In WSL, the listener may be on the Windows side rather than a Linux process. A common diagnostic line looks like:
```text
Windows listener: 0.0.0.0:8000 pid=4700 process=svchost.exe services=iphlpsvc
```
`iphlpsvc` is the Windows IP Helper service. It often hosts IPv6, tunneling, proxying, port forwarding, WSL, or developer-tool networking features. Do not start by killing that `svchost.exe`; first check whether an old portproxy rule owns the port.
From Administrator PowerShell, inspect portproxy rules:
```powershell
netsh interface portproxy show all
```
If you see `0.0.0.0:8000` or `listenport=8000`, delete that rule:
```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
```
If there is no portproxy rule, confirm which services are hosted by that PID:
```powershell
netstat -ano | findstr :8000
tasklist /svc /fi "PID eq 4700"
```
For temporary troubleshooting, you can stop IP Helper from Administrator PowerShell:
```powershell
Stop-Service iphlpsvc
```
This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. If the Windows forwarding rule must stay, use a different Planet backend port.
If the script prints `failed-stop-service` or `failed-stop-process`, the current shell does not have permission to clear the Windows listener. Startup stops immediately instead of launching the backend into the same port conflict.
### Which startup flags change default ports?
| Service | Default port | Flag |
| --- | --- | --- |
| Frontend | `3000` | `-f <port>` |
| Backend | `8000` | `-b <port>` |
| AI Provider | `8010` | `-a <port>` |
| Motion Agent | `8765` | `--motion-agent-port <port>` |
Example:
```bash
./planet.sh start -f 3001 -b 8001 -a 8101
```
## Windows / WSL / LAN
### LAN access does not work on Windows / WSL. What should I check?
Check in this order before changing firewall rules:
```bash
# In WSL or the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
```
Then verify from Windows PowerShell:
```powershell
curl http://localhost:3000
curl http://localhost:8000/health
```
If both localhost checks pass but a phone or another computer cannot connect, start with LAN enabled:
```bash
./planet.sh start --allow-lan
```
Then configure portproxy and firewall from Administrator PowerShell:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
LAN devices should open the Windows LAN IP, for example `http://<Windows LAN IP>:3000/earth`, not the internal WSL IP.
### How do `--allow-lan` and the Motion Agent LAN URL fit together?
`--allow-lan` binds the frontend, backend, and optional Motion Agent to `0.0.0.0`. If a remote browser needs to connect to the display machine's Motion Agent, pass the Agent URL explicitly:
```text
http://<LAN_IP>:3000/earth?motion=1&motionProvider=agent&motionAgent=ws://<LAN_IP>:8765/ws/gestures
```
Browser Camera mode does not need a `motionAgent` URL.
## Dependencies and Environment Variables
### Why should I use `uv` instead of `pip`?
Planet manages Python dependencies through `uv` and `pyproject.toml`. Avoid `pip install` in the project environment, because it can diverge from the lock file and startup scripts.
For Motion Agent live dependencies, use:
```bash
uv add mediapipe opencv-python
```
`planet.sh start --motion-agent` checks and installs those live dependencies automatically. To disable auto-install:
```bash
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
```
### Why should I use `bun` instead of `npm run`?
The frontend runtime is Bun. This avoids WSL / Windows mixed-path issues that can happen when npm invokes `cmd.exe`.
Common commands:
```bash
bun install
bun run dev
bun run build
```
If a non-interactive shell cannot find `bun`, `planet.sh` searches the current PATH, `~/.bun/bin`, zsh config, and PowerShell command resolution.
### When does `planet.sh` read environment variables from `.zshrc`?
By default, `planet.sh` statically parses simple lines in `~/.zshrc`:
```bash
export KEY=value
KEY=value
```
This avoids slow shell themes, plugins, and interactive initialization. For complex shell expansion, opt in to source mode:
```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```
To ignore `~/.zshrc` while troubleshooting:
```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```
Never put real secret values in docs or commits; documentation should only mention variable names and purposes.
## Motion Capture / Cameras
### Does Browser Camera mode need the `motionAgent` parameter?
No. Browser Camera mode uses webpage `getUserMedia` and runs recognition locally in the browser.
Recommended URL:
```text
/earth?motion=1&motionProvider=browser
```
You can also open Earth settings, enable Motion Debug Mode, and select Browser Camera as the input source. The page must run on HTTPS or localhost, and the user must grant browser camera permission.
### When do I need Motion Agent?
Use Motion Agent for:
- dual USB cameras
- RTSP / HTTP camera streams
- edge devices or client integration
- a standalone local recognition service
Common commands:
```bash
./planet.sh start --motion-agent
./planet.sh start --motion-agent --motion-agent-camera-indexes 0,1
./planet.sh start --motion-agent --motion-agent-camera-urls rtsp://example/live
./planet.sh start --motion-agent --motion-agent-dry-run
```
`--motion-agent-dry-run` is only for protocol and frontend connection testing; it does not open cameras.
### Why does WSL not find my camera?
Windows cameras usually do not appear inside WSL as `/dev/video*`. Check first:
```bash
ls /dev/video*
```
If no device appears, use Browser Camera for ordinary web demos. For Agent live mode, use an RTSP / HTTP camera URL:
```bash
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
```
USB passthrough into WSL is an advanced path. The script does not silently downgrade missing-camera live mode to dry-run.
## Docker / AI Provider
### Why does changing the AI key, base URL, or model not rebuild the image?
Keys, base URLs, and model names are runtime configuration. They do not require a Docker image rebuild. Restart AI Provider:
```bash
./planet.sh restart -a
```
The first Docker build may be slow because of image layers or `uv sync` dependency downloads. Later builds reuse `.dockerignore`, BuildKit, and uv cache.
### What should I do when Docker health checks fail?
Start with:
```bash
./planet.sh health
```
Then inspect logs:
```bash
./planet.sh log
```
If only AI Provider is unhealthy, restart just that service:
```bash
./planet.sh restart -a
```
## Datasource and Collector Credentials
### Connectivity validation passes, but collection cannot read credentials. Why?
Connectivity validation can read saved console settings, environment variables, and some credentials from `~/.zshrc`. For actual collection, prefer saving credentials in Settings -> Collector Settings, especially for AISStream's long-lived WebSocket collector.
If `AISSTREAM_API_KEY` only lives in `~/.zshrc`, confirm the backend process actually inherited it. Otherwise validation may pass while the collector runtime has no key.
### Where should BarentsWatch / AISStream credentials live?
For temporary debugging, environment variables or `~/.zshrc` are fine:
```bash
export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."
```
For stable operation, save credentials in Collector Settings so connectivity validation, collection jobs, and Earth realtime aggregation use the same configuration.
## Docs / Permissions
### Why can I not see some Docs pages?
Docs visibility is controlled by Gatekeeper groups:
- Quickstart, Manual, FAQ, and other basic docs are public.
- Development docs usually require `docs_developer`.
- Operations and service-control docs usually require `docs_admin`.
- `admin` and `super_admin` have Docs access by default; ordinary users need groups assigned from the Users page.
## Earth Common Tasks
### Why did collecting a location candidate not write anything?
Collecting and saving are two separate actions. Candidates can be previewed on Earth first. A candidate is written only after clicking Save or using the unresolved list's one-click adopt flow.
Compute-center saves write to `compute_center_locations` and refresh the layer. Records with no candidate stay in the unresolved list; Planet does not fabricate a location from a country center or hard-coded hint.
### Why does Motion Debug not show camera video?
With the Browser Camera source, the debug panel shows the local browser camera preview and draws the skeleton over it. If `Skeleton Only` is enabled, the video preview is hidden and the panel keeps only the dark canvas plus red/green skeleton.
With the Motion Agent source, the Agent WebSocket sends normalized joints, bones, and matched gestures only. It does not stream raw camera frames to Earth, which keeps privacy risk, bandwidth, and latency lower. In that mode the panel is a skeleton debug view rather than a video stream.

27
docs/technical/en/location-pipeline-development.md
View File

@@ -61,6 +61,9 @@ class LocationResolver(Protocol):
| `RegistryResolver` | `resolvers/registry.py` | Legacy generic resolver; current compute-center and BGP runtime paths do not use it to generate candidates |
| `NominatimResolver` | `resolvers/nominatim.py` | Runs a domain query plan against Nominatim with LRU cache and rate limiting |
| `InheritFromAnotherEntityResolver` | `resolvers/inherit.py` | Wraps an externally resolved entity location as a candidate |
| `LocationLLMFallback` | `location/llm_fallback.py` | Generates a confirmation-required candidate through the current default AI Provider when user-triggered collection has no regular candidates |
Nominatim is the geocoding service in the OpenStreetMap ecosystem. Given a place name, city, country, organization, or facility query, it returns possible coordinates, a display name, and structured address fields. It is useful for turning city/facility text into candidate coordinates, but it is not an authoritative fact registry and can match same-name places or broad administrative areas. Planet therefore treats Nominatim output as confirmation-required candidates and uses it with caching and rate limiting.
`RegistryResolver` remains available for future controlled import scenarios, but it should not be reconnected as a hard-coded hint source for compute centers or BGP. Matching common fields such as `operator` or `city` was the main reason multiple entities could collapse onto the same point.
@@ -81,7 +84,7 @@ StoredComputeCenterLocationResolver()
The main map startup path is source coordinates first, then the database-backed current-location table. The table is `compute_center_locations`, keyed by `(source, source_id)`, and stores manually accepted locations or true coordinates migrated from source records. `init_db()` only migrates source records that already contain real coordinates; it does not import old hard-coded hints and does not run ROR, Nominatim, or LLM geocoding during startup.
Candidate collection is intentionally separate from rendering. `collect_location_candidates()` builds ROR and Nominatim/OpenStreetMap queries from source fields, but it does not emit the current `compute_center_locations` row as a candidate. After a user accepts a candidate, the save endpoint upserts it into the dimension table; the next map refresh renders it through `StoredComputeCenterLocationResolver`.
Candidate collection is intentionally separate from rendering. `collect_location_candidates()` builds ROR and Nominatim/OpenStreetMap queries from source fields, but it does not emit the current `compute_center_locations` row as a candidate. If those regular candidates are empty, the API layer calls `LocationLLMFallback` through the current default AI Provider and only returns `source="llm_location_factcheck"` candidates with `needs_confirmation=true`. LLM candidates use a combined threshold made from the model self-score plus backend evidence scoring; when the LLM provides a credible city/country but no coordinates, the backend may fill city-level coordinates through Nominatim without increasing the evidence score. After a user accepts a candidate, the save endpoint upserts it into the dimension table; the next map refresh renders it through `StoredComputeCenterLocationResolver`.
`resolve_compute_center_location()`, `resolve_compute_center_location_full()`, and `collect_location_candidates()` remain the domain API. `visualization.py` consumes that API and no longer owns coordinate hints, country-centroid fallbacks, or Nominatim details.
@@ -102,7 +105,7 @@ StoredCollectorLocationResolver()
NominatimResolver(_bgp_collector_query_plan)
```
The 23 RIPE RIS collector coordinates moved from the old table into the `bgp_collector_locations` dimension table with `source=legacy_seed` and `needs_confirmation=true`. The legacy dictionary is still maintained from the DB-backed cache for compatibility; manual candidate collection uses stored site/city/country as context but does not emit stored rows as candidates.
The 23 RIPE RIS collector coordinates moved from the old table into the `bgp_collector_locations` dimension table with `source=legacy_seed` and `needs_confirmation=true`. The legacy dictionary is still maintained from the DB-backed cache for compatibility; manual candidate collection uses stored site/city/country as context but does not emit stored rows as candidates. If Nominatim cannot produce a city-level candidate, the collection endpoint uses the current default AI Provider as an LLM factcheck fallback and returns a confirmation-required candidate instead of saving automatically.
### BGP Events
@@ -139,6 +142,26 @@ Both `collect-location` endpoints return the same envelope:
}
```
The LLM fallback only runs inside user-triggered `collect-location` requests, and only after regular candidates are empty. It does not run during `/geo/compute-centers` startup rendering, scheduled collection, or batch persistence, and it never writes directly to `compute_center_locations` or `bgp_collector_locations`. Internally it is no longer a single "strict JSON or fail" step. It first asks the LLM to factcheck the location; if the answer is not JSON, it makes a second normalization request that may only extract facts from the original text; if that still fails, it conservatively extracts a city/country pair from the prose. The backend then performs coordinate filling, combined scoring, and candidate creation through one shared path.
This lets an answer such as "DeepL Mercury is in Falun, Sweden" become a city-level candidate after backend Nominatim coordinate filling, and lets a prose first answer be normalized into JSON on the second pass. Regardless of the path, only `precise`, `site`, or `city` precision with non-zero coordinates and a sufficient combined score is converted to a candidate. Failed, low-score, country-only, or cityless responses stay as diagnostics.
The LLM-provided `confidence` is only the model's self-score. The backend recomputes a combined score and uses that value as the candidate `confidence`:
```text
combined =
0.25 * model_confidence
+ source_quality
+ entity_match
+ geography_match
+ precision_quality
+ name_location_hint
- conflict_penalty
- weak_evidence_penalty
```
Current component caps: authoritative/government/academic evidence can add up to `0.35`, reputable databases or news up to `0.25`, generic web evidence up to `0.15`; evidence that clearly names the queried entity can add `0.25`; city+country geography match adds `0.20`, country-only match adds `0.05`; precision adds `precise=0.15`, `site=0.12`, or `city=0.08`; `name_location_hint` adds signal when the entity name and candidate city overlap, such as `TAIPEI-1` and `Taipei`; explicit conflicts can subtract up to `0.45`; weak-evidence wording can subtract up to `0.30`, capped at `0.15` when entity and city/country match and no conflict is present. Candidates below `0.55` are rejected. This lets cases such as Alem.Cloud and TAIPEI-1 recover from a low model self-score when entity and city evidence align, while genuinely weak or conflicting evidence still fails.
`POST /api/v1/visualization/compute-centers/{source_id}/location` upserts the candidate selected by the frontend into `compute_center_locations`. Manual saves default to `needs_confirmation=false`, `verification_status="verified"`, and a `verified_at` timestamp. Future automated staging can pass `needs_confirmation=true` explicitly.
The frontend [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) renders the shared candidate list and preview events. The compute-center layer button shows an `unresolved` badge; clicking it opens the unresolved queue. Row-level `采集` only fetches candidates. Header-level `一键采用` walks the queue top-to-bottom, picks the highest-confidence candidate with valid coordinates, saves it, removes the row, renumbers the list, and dispatches `earth:compute-center-unresolved-count-change` so the badge updates immediately. When the batch finishes, `earth:compute-center-location-saved` refreshes the real layer.

12
docs/technical/en/location-pipeline-user.md
View File

@@ -1,6 +1,6 @@
# Earth Location Candidate Collection User Guide
Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, and online geocoding results into a previewable candidate list.
Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, online geocoding results, and, when needed, LLM factcheck fallback results into a previewable candidate list.
## Supported Entities
@@ -18,13 +18,15 @@ Clicking a compute center or BGP collector on Earth opens a detail card with loc
| Field | Meaning |
| --- | --- |
| Location precision | Precise coordinates, site-level, city-level, or unconfirmed |
| Location source | Source coordinates, ROR organization registry, Nominatim online search, or stored BGP collector locations |
| Location source | Source coordinates, ROR organization registry, Nominatim online search, LLM factcheck fallback, or stored BGP collector locations |
| Location confidence | Relative confidence reported by the backend resolver |
| Verification status | Confirmed, estimated, or online result pending confirmation |
| Resolution reason | Why the location was selected |
| Matched location name | Canonical name from an open source, online result, or stored collector location |
| Verified at | Verification date for confirmed locations; online candidates are usually empty |
Nominatim here means the online geocoding service from the OpenStreetMap ecosystem. It converts place names, cities, countries, organizations, or campus/facility queries into possible coordinate candidates, but it can match same-name places or broad administrative areas. The UI therefore treats these results as pending confirmation.
Compute-center GeoJSON no longer renders country centroids, unknown locations, or `[0, 0]` placeholders. Records that cannot reach city-level precision are returned in the endpoint's `unresolved` list and can be improved through candidate collection.
A compute center with a `?` marker on Earth is not unresolved. It already has coordinates, but the coordinates still need confirmation, either because `needs_confirmation=true` or because the source is online geocoding. Truly unresolved records have no trustworthy coordinates and are therefore absent from the globe.
@@ -82,7 +84,7 @@ Both `collect-location` endpoints use the same response shape:
}
```
When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason` plus the attempted queries. This helps distinguish missing source fields, open-source gaps, and online geocoding misses.
When regular candidates are empty, the endpoint asks the current default AI Provider for one LLM factcheck fallback. LLM candidates always require human confirmation and are never saved automatically; only strict JSON results with city-or-better precision, non-zero coordinates, and sufficient confidence appear in the candidate list. When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason`, `llm_failure_reason`, and attempted queries. This helps distinguish missing source fields, open-source gaps, online geocoding misses, and unusable LLM responses.
## Registry Maintenance
@@ -122,6 +124,10 @@ Earth only renders coordinates that reach city-level precision or better. If sou
Nominatim/OpenStreetMap results may match same-name cities, organizations, or campuses. They are useful for previewing candidates, but should be manually confirmed before being persisted as verified locations.
### Can the LLM fallback change the map directly?
No. The LLM runs only after a user clicks candidate collection and regular sources have no candidates. It returns confirmation-required candidates only. Earth startup GeoJSON, scheduled collection, and batch rendering do not call the LLM automatically; a location affects future rendering only after a user saves the candidate into the dimension table.
### Why do BGP events no longer all land in Amsterdam?
The old behavior could match common fields like `operator="RIPE NCC"` and incorrectly promote `rrc00`. BGP event inheritance now uses a strict owning-collector lookup in the DB-backed cache instead of registry fuzzy matching.

42
docs/technical/en/manual.md
View File

@@ -7,7 +7,7 @@ This manual is for daily use, demos, development integration, and local operatio
- Console: admin backend (login required)
- Docs: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups
For the shortest path to getting started, see [Quickstart](/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). For common troubleshooting, see the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
## Entry Overview
@@ -17,6 +17,7 @@ After a default startup, the common URLs are:
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
| Docs | `http://localhost:3000/docs` | Partly | Usage docs are public; developer, backend, and operations docs require Gatekeeper groups |
| FAQ | `http://localhost:3000/docs/faq` | No | Windows / WSL, ports, dependencies, motion capture, credentials, and permission troubleshooting |
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
| AI Playground | `http://localhost:3000/playground` | Yes | AI Provider status and debugging |
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |
@@ -280,7 +281,7 @@ Search results can be used to quickly locate objects and open their details.
### Location Candidate Collection
Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. Stored BGP collector locations are used as query context only and are not emitted as candidates.
Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. If those regular sources return no candidates, the current default AI Provider is used once as an LLM factcheck fallback. Stored BGP collector locations are used as query context only and are not emitted as candidates.
Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the `compute_center_locations` dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use `一键采用` to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md) for the full workflow.
@@ -288,11 +289,10 @@ Candidates can be previewed directly on Earth. Compute-center candidates can be
The settings panel contains:
- Rotation mode / cruise mode
- Cruise modules: BGP, News
- Satellite display style: self-glow, real ground footprint
- Day/night mode
- Panel visibility toggles
- Rotation mode / cruise mode / motion mode
- Cruise modules: BGP, News, Compute Centers, Vessels, Cables, Satellites
- View settings: satellite display style, day/night mode, panel visibility
- Motion Debug Mode, Motion Input Source, skeleton-only debug view
- Globe default size
- Terrain opacity
- Reset settings
@@ -318,6 +318,30 @@ When zooming, the top capsule briefly shows the current zoom level, for example
Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.
### Motion Capture Controls
Earth has a motion-capture control entry point for large-screen and future 3D displays. There are two realtime input sources: the default `Browser Camera` source uses webpage `getUserMedia` and recognizes gestures locally in the browser; the advanced `Motion Agent` source uses `camera/RTSP/HTTP -> local Agent -> local WebSocket -> Earth page`. Neither path sends camera frames or realtime gesture decisions to the cloud, and neither path reuses the news/RSS aggregation APIs.
It is disabled by default. Enable `Motion Debug Mode` in settings, open Earth with `?motion=1`, or set `planet-earth-motion-control-enabled=true` in browser local storage to start the selected source. The default source is `Browser Camera`; it requires HTTPS or localhost and a granted browser camera permission, but does not require installing an app. For dual cameras, USB indexes, phone/network camera streams, client integration, or edge devices, switch the setting to `Motion Agent`. The default Agent URL is `ws://127.0.0.1:8765/ws/gestures`; the `motionAgent` URL parameter can override it.
URL parameters can also force the source: `?motion=1&motionProvider=browser` uses the browser camera, `?motion=1&motionProvider=agent` uses Motion Agent, and providing `motionAgent=ws://...` automatically selects Motion Agent.
Current gesture semantics:
| Gesture event | Result |
| --- | --- |
| `rotate_left` | Rotates the globe left |
| `rotate_right` | Rotates the globe right |
| `rotate_up` | Rotates the globe upward |
| `rotate_down` | Rotates the globe downward |
| `zoom_in` | Zooms in |
| `zoom_out` | Zooms out |
| `focus_prev` / `focus_next` | Switches targets within the current motion layer |
| `layer_prev` / `layer_next` | Switches the motion candidate layer and cruises to the nearest target in that layer |
| `confirm` | Confirms the currently selected target; browser recognition currently keeps the two-hands-up confirm gesture disabled |
The settings panel also includes `Motion Debug Mode`, which opens the debug panel. With the Browser Camera source, the panel shows a local live preview and draws joints and bones over it. With the Motion Agent source, the Agent sends normalized skeleton events only and does not send raw video frames. The `Skeleton Only` switch hides the video preview and keeps the dark canvas plus skeleton; `Stop Matching Gestures` pauses gesture execution while preview and skeleton drawing can continue for debugging. Unmatched skeletons are red; once a gesture matches, the skeleton turns green and the matched gesture name is shown. Both this entry and the `Motion Input Source` control already carry Gatekeeper permission markers for future authorization control.
### Cruise Mode
Cruise mode makes Earth automatically cycle through focus targets.
@@ -326,6 +350,10 @@ Current cruise modules:
- BGP
- News
- Compute Centers
- Vessels
- Cables
- Satellites
Suitable for demos, monitoring displays, or unattended presentations.

88
docs/technical/en/ops-planet-sh-startup.md
View File

@@ -177,7 +177,7 @@ Frontend startup now has an additional pre-start cleanup retry layer:
- `PORT_PRESTART_RETRIES`: defaults to 3 attempts.
- `PORT_PRESTART_RETRY_INTERVAL`: defaults to 2 seconds.
`kill_port_if_requested()` only kills processes when the current environment can identify listening PIDs. If no PID is visible but the port still cannot bind, it logs diagnostics and lets the service startup flow make the final decision. `start_frontend_with_retry()` only enters the pre-cleanup retry path when a listener PID is visible, so the script no longer spends its retry budget repeatedly killing nothing while a host-side or external network namespace is still releasing the port. Seeing "no listener found but port still unavailable" on the first restart usually means the external environment is still releasing the port, not that a local process cleanup loop is useful.
`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it tries to stop the owning Windows service or force-stop the owning process through PowerShell. If permissions are missing, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and stops startup immediately instead of launching the service into the same port error. Non-WSL environments do not run the Windows cleanup path. At that point, use Administrator PowerShell to clear the portproxy/service ownership, or choose another port.
## Issue 4: `restart` Behavior
@@ -188,6 +188,92 @@ Before the stamp path fix:
After moving the stamp file, plain `restart` uses the same `stop + start` behavior and the same fingerprint check as `restart -b`.
## Optional Motion Agent Startup
`planet.sh` can now manage the local Motion Capture Agent. It is disabled by default so ordinary development machines do not fail startup when cameras, OpenCV, or MediaPipe are unavailable.
Start it with:
```bash
./planet.sh start --motion-agent
```
Common options:
- `--motion-agent` / `-m`: start or restart the Motion Agent for this command.
- `--motion-agent-port <port>`: override the default WebSocket port `8765`.
- `--motion-agent-camera-indexes <indexes>`: override auto-detected camera indexes, for example `0` or `0,1`. The same can be provided through `MOTION_AGENT_CAMERA_INDEXES=0,1`.
- `--motion-agent-camera-urls <urls>`: use RTSP/HTTP camera streams, useful for WSL, phone cameras, or network cameras. The same can be provided through `MOTION_AGENT_CAMERA_URLS=...`.
- `--motion-agent-dry-run`: start only the protocol service without opening cameras or loading CV dependencies; useful for Web client debugging.
Non-dry-run live mode checks `mediapipe` and `opencv-python` before startup. If the current `.venv` is missing them, the script automatically runs:
```bash
uv add mediapipe opencv-python
```
To disable startup-time auto-install:
```bash
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
```
Live mode auto-detects `/dev/video*` and passes the first two indexes to the Motion Agent. In WSL, Windows cameras usually do not appear as `/dev/video*` automatically. Check available devices first:
```bash
ls /dev/video*
```
To override auto-detection, pass indexes explicitly:
```bash
./planet.sh start --motion-agent --motion-agent-camera-indexes 1,2
```
In WSL, the more general path is to connect a phone or network camera through an RTSP/HTTP stream:
```bash
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
```
If WSL has no `/dev/video*` and no `--motion-agent-camera-urls` is provided, live startup stops and prints guidance instead of silently falling back to dry-run. Choose one of:
```bash
./planet.sh start --motion-agent --motion-agent-camera-urls http://<phone-ip>:8080/video
./planet.sh start --motion-agent --motion-agent-dry-run
```
Automatic dry-run fallback only happens when `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1` is explicitly set.
Environment-variable startup is also supported:
```bash
PLANET_START_MOTION_AGENT=1 ./planet.sh start
MOTION_AGENT_DRY_RUN=1 PLANET_START_MOTION_AGENT=1 ./planet.sh start
```
Logs:
```bash
./planet.sh log -m
```
To expose it together with the frontend on the LAN:
```bash
./planet.sh start --allow-lan --motion-agent
```
In this mode the Motion Agent binds `0.0.0.0`, and startup output prints both the local WebSocket URL and the recommended LAN WebSocket URL. When opening Earth from another LAN browser, point `motionAgent` at the display machine:
```text
http://<LAN_IP>:3000/earth?motion=1&motionAgent=ws://<LAN_IP>:8765/ws/gestures
```
`./planet.sh stop` also stops a script-managed Motion Agent. `./planet.sh health` reports its online/offline status. The Earth page still requires `?motion=1` or browser local storage to enable the Web client connection explicitly.
For ordinary web, WSL, or no-install demo scenarios, you can skip Motion Agent entirely: choose the `Browser Camera` input source in Earth settings and enable Motion Debug Mode. This route uses browser `getUserMedia`, so the page must run on HTTPS or localhost and the user must grant camera permission.
## Other Cleanup
Two redundant `sleep 3` waits were removed because health checks already cover the same readiness:

8
docs/technical/en/quickstart.md
View File

@@ -2,6 +2,8 @@
This guide is for developers or demo operators starting Planet for the first time. The goal is to get services running via the shortest path and know which URLs to open.
If you run into port conflicts, Windows / WSL LAN access, `uv` / `bun`, camera, or Docs permission issues, start with the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
## Prerequisites
Recommended: run in a WSL / Linux shell.
@@ -64,6 +66,8 @@ If the default ports are taken, specify custom ports:
./planet.sh start -f 3001 -b 8001 -a 8101
```
If backend port `8000` is occupied by a Windows listener or an old portproxy rule, follow the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md) troubleshooting order.
## 2. Create a Login User
The console requires login. For first-time use:
@@ -91,9 +95,9 @@ Once in, verify:
- The globe renders correctly
- The right-side layer panel can toggle layers on/off
- Search can find cables, satellites, compute centers, BGP events
- Compute-center and BGP collector detail cards can collect and preview coordinate candidates; the compute-center unresolved badge can open the queue and save candidates
- Compute-center and BGP collector detail cards can collect and preview coordinate candidates; when regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback; the compute-center unresolved badge can open the queue and save candidates
- Mouse drag, wheel zoom, and zoom percent feedback work correctly
- Settings panel can switch cruise mode, day/night mode, satellite display style
- Settings panel can switch rotate / cruise / motion mode, day/night mode, and satellite display style; Motion Debug Mode can show the local Browser Camera preview plus skeleton overlay
## 4. Open the Console