release: bump version to 0.71.0

2026-06-11 16:47:24 +08:00
parent 8c204717cd
commit 899e3bce43
56 changed files with 4618 additions and 260 deletions
--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -109,9 +109,9 @@ Earth 设置面板现在按 `data-settings-tab` 和 `data-settings-tab-panel`
 - 将 `rotate_left`、`rotate_right`、`rotate_up`、`rotate_down`、`zoom_in`、`zoom_out`、`focus_prev`、`focus_next`、`layer_prev`、`layer_next`、`confirm` 映射到 `main.js` 暴露的动作入口。
 - 解析 `skeleton` 调试事件并派发 `earth:motion-debug-frame`。

-动作捕捉识别可以在浏览器本地执行，也可以在本地 Agent 中执行，但两者都不会把实时视频帧发给 SaaS 云端。`main.js` 暴露旋转、缩放、目标切换、图层切换和确认入口，并通过 `window.__planetEarth.motion` 提供调试入口。默认只有 URL 参数 `?motion=1`、本地存储 `planet-earth-motion-control-enabled=true`，或 Earth 设置中的“动捕调试模式”打开时才启动当前 provider。
+动作捕捉识别可以在浏览器本地执行，也可以在本地 Agent 中执行，但两者都不会把实时视频帧发给 SaaS 云端。`main.js` 暴露旋转、缩放、目标切换、图层切换和确认入口，并通过 `window.__planetEarth.motion` 提供调试入口。默认只有 URL 参数 `?motion=1`、本地存储 `planet-earth-motion-control-enabled=true`，或 Earth 设置中的“动捕调试模式”打开时才启动当前 provider。`shared.motionEnabledGestures` 保存用户允许识别的动作；浏览器端先过滤，Motion Agent 模式还会通过 `set_enabled_gestures` 同步给服务端。

-动捕调试面板由 [motion-debug-panel.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-debug-panel.js) 负责。它监听 `earth:motion-debug-frame`，用 canvas 绘制归一化骨架点和连线；Browser Camera provider 会额外通过 `earth:motion-debug-video-source` 提供本机 `<video>` 作为调试预览底图，`shared.motionDebugSkeletonOnly` 可切换为只显示骨骼。`停止匹配动作` 通过 `earth:motion-recognition-pause` 暂停 gesture 执行，但继续显示视频和骨架。未匹配动作为红色，匹配后变绿并显示动作名。设置项持久化在 `planet.earth.settings.v2` 的 `shared.motionDebugEnabled`、`shared.motionProvider` 与 `shared.motionDebugSkeletonOnly`，switch 和输入源控件都预留 `data-gatekeeper-permission="earth.motion_debug"`。
+动捕调试面板由 [motion-debug-panel.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-debug-panel.js) 负责。它监听 `earth:motion-debug-frame`，用 canvas 绘制归一化骨架点和连线；Browser Camera provider 会额外通过 `earth:motion-debug-video-source` 提供本机 `<video>` 作为调试预览底图，`shared.motionDebugSkeletonOnly` 可切换为只显示骨骼。`停止匹配动作` 通过 `earth:motion-recognition-pause` 暂停 gesture 执行，但继续显示视频和骨架。未匹配动作为红色，匹配后变绿并显示动作名。设置项持久化在 `planet.earth.settings.v2` 的 `shared.motionDebugEnabled`、`shared.motionProvider`、`shared.motionDebugSkeletonOnly` 与 `shared.motionEnabledGestures`，switch、输入源和动作白名单控件都预留 `data-gatekeeper-permission="earth.motion_debug"`。

 Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-browser-provider.js) 的 `recognizeGesture()`，按以下顺序匹配，前者命中即返回：

--- a/docs/technical/zh/earth-news-sources.md
+++ b/docs/technical/zh/earth-news-sources.md
@@ -86,6 +86,55 @@ Earth 态势新闻使用 `/api/v1/news/earth-feed` 输出给前端。新闻源

 `GET /api/v1/earth/news-sources` 返回默认或已保存配置。`PUT /api/v1/earth/news-sources` 保存配置并递增 `cache_version`，同时清理进程内 region cache。`POST /api/v1/earth/news-sources/reset` 恢复默认源。`POST /api/v1/earth/news-sources/test` 只测试单个 RSS/Atom/Aggregated 源，不写入新闻表。

+## 手动新闻内容
+
+手动新闻是内容管理能力，不是 RSS 源配置。Admin 入口是 `智能星球内容 -> 新闻内容`，左栏按 RSS 来源和手动新闻组聚合；进入手动组详情后可以按条添加新闻或上传 JSON 数组批量导入。手动新闻写入 `earth_news_items`，并标记 `feed_type/source_type = manual`；前台展示文案是“手动添加”。它不参与 RSS 连通性测试，也不会进入 RSS 抓取流程。
+
+手动新闻采用“先展示，再精修”的策略：
+
+1. 保存后立即写入 `earth_news_items`。
+2. 没有人工坐标时使用所选区域锚点，`verified=false`。
+3. 有人工坐标时使用 `location_source=manual_location`，`verified=true`，后续 AI 精修不会覆盖该坐标。
+4. 创建或重新处理后进入新闻增强队列，后台补清洗、翻译、分类、重要度、Breaking 和目标位置推断。
+5. 精修完成后更新同一条新闻，并通过 Earth news reload / patch 让前端无感替换。
+
+后台接口挂在 `/api/v1/earth/news-items`：
+
+- `GET /earth/news-groups`：返回 RSS 虚拟来源组和手动新闻组。
+- `POST /earth/news-groups`：新建手动新闻组。
+- `PUT /earth/news-groups/{group_id}`：重命名手动新闻组，并同步组内新闻 meta。
+- `GET /earth/news-items`：分页查询 RSS 与手动新闻，支持来源类型、区域、类型和状态过滤。
+- `POST /earth/news-items`：新增一条手动新闻。
+- `POST /earth/news-items/import`：上传 JSON 数组批量导入，`group_id` 指定当前手动新闻组。
+- `PUT /earth/news-items/{id}`：编辑手动新闻；RSS 新闻只读。
+- `DELETE /earth/news-items/{id}`：删除手动新闻，并触发 Earth 新闻重载。
+- `POST /earth/news-items/{id}/reprocess`：重新进入清洗、翻译和定位队列。
+
+JSON 导入首版只支持数组：
+
+```json
+[
+  {
+    "title": "必填标题",
+    "summary": "可选摘要",
+    "content": "可选正文",
+    "url": "https://example.com/story",
+    "source": "手动添加",
+    "region": "global",
+    "published_at": "2026-05-15T03:00:00Z",
+    "category": "business",
+    "tags": ["manual", "analysis"],
+    "location": {
+      "label": "北京市, 中国",
+      "latitude": 39.9057,
+      "longitude": 116.3913
+    }
+  }
+]
+```
+
+重复导入使用稳定 ID 去重，ID 由标题、发布时间、URL 和来源生成，格式为 `manual:{hash}`。同一条手动新闻再次导入会更新原记录，不会重复出现在 EarthFeed。
+
 ## Feed 查询与类型过滤

 星球端和 UE 端统一使用 `GET /api/v1/news/earth-feed` 获取新闻。接口支持服务端过滤，不要求客户端拿全量列表后自行筛选。
@@ -107,6 +156,8 @@ GET /api/v1/news/earth-feed?region=global&categories=business,ecommerce&locale=z

 Web 星球端的新闻类型按钮只保存当前浏览器的显示偏好；偏好变化后会重新请求接口。UE 端应直接把类型选择拼到 `categories` 参数里，不需要再做主过滤。

+未指定 `sources` 时，服务层会优先选择当前 `locale` 已有可展示标题和摘要的新闻，并从当前启用来源补齐候选后做来源轮转，避免一个来源的最新待处理条目占满默认 12 条。指定 `sources` 时保持精确来源过滤，不做跨来源补齐。数据库查询层只负责区域、类型、来源和排序条件，不包含语言展示策略。
+
 源测试只证明当前 RSS/Atom/XML 能解析到条目，不等于这些条目已经入库展示。展示链路还会检查区域、类型过滤和数据库新鲜度。保存或重置新闻源会递增配置版本并清理缓存；如果当前启用的 Feed 子项在库里没有近期条目，下一次 `earth-feed` 请求会补抓，避免新启用的 36氪、亿邦被旧 Google News 缓存挡住。

 ## Breaking News 插队
@@ -163,9 +214,11 @@ Admin 入口是 `Earth 内容 -> 新闻源`。界面不是整包 JSON 编辑，
 ```mermaid
 flowchart LR
  Admin["Admin: Earth 内容 / 新闻源"] --> Source["Source 配置"]
+  ManualAdmin["Admin: Earth 内容 / 新闻内容"] --> ManualAPI["/api/v1/earth/news-items"]
  Source --> Feed["Feed 子项"]
  Feed --> ConfigAPI["/api/v1/earth/news-sources"]
  ConfigAPI --> Config["SystemSetting: earth_news_sources"]
+  ManualAPI --> Store

  Earth["Earth 新闻面板"] --> NewsAPI["/api/v1/news/earth-feed"]
  NewsAPI --> Resolver["Source Resolver"]
--- a/docs/technical/zh/manual.md
+++ b/docs/technical/zh/manual.md
@@ -193,6 +193,7 @@ Base URL 输入框尾端的插头图标会触发连接测试。测试通过会
 - **品牌资源**：维护智能星球 HUD 使用的 logo、标题图、标题文本、副标题和描述；上传的图片会保存为智能星球品牌资产并立即供智能星球页面读取。
 - **关于**：维护智能星球设置面板里的关于卡片，包括 logo、眉标、标题、版本、描述和元信息。
 - **电视直播**：维护智能星球媒体面板里的直播源。
+- **新闻内容**：按 RSS 来源和手动新闻组查看新闻。RSS 新闻保持只读；手动新闻组可以新增、批量导入 JSON、编辑、删除和重新处理。
 - **国界精度**：查看当前国界 provider、低精 fallback、高精 PMTiles/manifest 状态，编辑本机源配置并手动构建。
 - **地球底图**、**图层资源**、**三维素材**、**新闻锚点策略**：目前是待接入占位页，不展示假数据。

@@ -297,7 +298,7 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军

 ### 设置

-设置面板按分类组织：运行、显示、面板、动捕、快捷键、系统。里面包含旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、快捷键启用与改键、地球默认大小、地形透明度、重置设置。
+设置面板按分类组织：运行、显示、面板、动捕、快捷键、系统。里面包含旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼 / 识别动作白名单、快捷键启用与改键、地球默认大小、地形透明度、重置设置。

 新闻类型使用与巡航模块一致的标签选择器，只筛选当前浏览器里的新闻面板和新闻巡航条目，不影响图层、TV、数据点、底图、边界、采集任务或后台新闻源配置。

@@ -335,6 +336,8 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军

 两种模式都不会把摄像头帧或实时手势发到云端，也不会复用新闻/RSS 聚合接口。

+“识别动作”可以单独关闭旋转、缩放、焦点切换、图层切换或确认手势。浏览器端会忽略未勾选动作；使用 Motion Agent 时，同一白名单也会通过控制协议同步给 Agent。
+
 手势语义：

 | 手势事件 | 作用 |
--- a/docs/technical/zh/ops-planet-sh-startup.md
+++ b/docs/technical/zh/ops-planet-sh-startup.md
@@ -258,22 +258,27 @@ HTTP 健康检查统一使用 `curl -fsS --max-time`。因此 `/health` 返回 4

 前端生产形态是 `vite build` 生成静态资源，再由 nginx/Caddy 等 HTTP 服务器托管。不要在生产中使用 `bun run dev` 或 `vite preview`。当前不维护 Webpack 双构建链；如果未来需要评估更企业化的构建生态，优先做 Rsbuild/Rspack spike。Electron 仅在正式目标变成离线桌面软件时再单独评估。

-## Motion Agent 可选启动
+## Motion Agent 默认启动

-`planet.sh` 现在可以管理本地动作捕捉 Agent，但默认不会启动它，避免普通开发机因为没有摄像头、OpenCV 或 MediaPipe 而影响后端/前端启动。
+`planet.sh` 现在默认随 `start` 和全量 `restart` 启动本地 Motion Agent。这样星球端、UE 或调试客户端可以直接连接 `ws://127.0.0.1:8765/ws/gestures`。如果当前机器没有可用摄像头，默认隐式启动会降级为 dry-run 协议服务，不会阻断后端/前端启动；只有显式传入 `--motion-agent`、摄像头 index、摄像头 URL 或 WSL USB 参数时，live 模式缺摄像头才会硬失败。

-启动方式：
+如果本次不需要 Motion Agent：

 ```bash
-./planet.sh start --motion-agent
+./planet.sh start --non-motion-agent
+./planet.sh restart --non-motion-agent
 ```

 常用参数：

- `--motion-agent` / `-m`：随本次启动或重启拉起 Motion Agent。
+- `--non-motion-agent`：本次启动或全量重启不拉起 Motion Agent。
+- `--motion-agent` / `-m`：显式要求本次启动或重启拉起 Motion Agent；此时 live 摄像头失败会作为错误反馈。
 - `--motion-agent-port <端口>`：覆盖默认 WebSocket 端口 `8765`。
+- `--motion-agent-mode <模式>`：指定输入模式，可选 `auto`、`single`、`dual_redundant`、`single_fallback`、`calibrated_3d`；`dual` 作为兼容别名会进入双路冗余。
 - `--motion-agent-camera-indexes <indexes>`：覆盖自动发现的摄像头 index，例如 `0` 或 `0,1`。也可以用环境变量 `MOTION_AGENT_CAMERA_INDEXES=0,1`。
 - `--motion-agent-camera-urls <urls>`：使用 RTSP/HTTP 摄像头流，适合 WSL、手机摄像头或网络摄像头。也可以用环境变量 `MOTION_AGENT_CAMERA_URLS=...`。
+- `--motion-agent-wsl-usbipd`：在 WSL 中尝试通过 `usbipd-win` 自动把唯一的 Windows USB 摄像头透传到 Linux。
+- `--motion-agent-wsl-usbipd-busid <BUSID>`：在 WSL 中指定 `usbipd list` 里的摄像头 BUSID 后透传，适合多摄像头设备。
 - `--motion-agent-dry-run`：不打开摄像头、不加载 CV 依赖，只启动协议服务，适合调试 Web 端连接。

 非 dry-run 的 live 模式会在启动前检查 `mediapipe` 和 `opencv-python`。如果当前 `.venv` 缺包，脚本会自动执行：
@@ -282,13 +287,17 @@ HTTP 健康检查统一使用 `curl -fsS --max-time`。因此 `/health` 返回 4
 uv add mediapipe opencv-python
 ```

-如需禁止启动时自动安装，可设置：
+如需禁止启动时自动安装 Python CV 依赖，可设置：

 ```bash
-PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
+PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start
 ```

-live 模式会自动寻找 `/dev/video*`，优先取前两个 index 传给 Motion Agent。在 WSL 中，Windows 摄像头通常不会自动出现在 `/dev/video*`。可先用下面命令看设备：
+`./planet.sh init` 会在 WSL 中预检查 `usbipd-win`。如果没有 `usbipd.exe`，脚本会先尝试 `winget install -e --id dorssel.usbipd-win`，失败后复用仓库内置的 dorssel.usbipd-win MSI fallback；如果缓存缺失或需要其他架构版本，再下载 MSI 并请求管理员 PowerShell 安装。该步骤是 best-effort：失败会提示后续处理方式，但不会阻断普通初始化。可通过 `./planet.sh init --non-motion-agent` 跳过该预检。
+
+live 模式会自动寻找 `/dev/video*`，并优先用 OpenCV 实测过滤出真正能打开并读帧的 index，再传给 Motion Agent。在 WSL/USB 摄像头场景中，一个摄像头可能暴露多个 `/dev/video*` 节点，其中部分是 metadata 或非采集节点，脚本会跳过这类不可读 index。在 WSL 中，Windows 摄像头通常不会自动出现在 `/dev/video*`。可先用下面命令看设备：
+
+默认 live 采集使用低延迟参数：`640x360` 输入、约 `15Hz` 识别事件；worker 内部用 latest-frame 读帧线程，只保留每路摄像头的最新帧，避免 MediaPipe 慢帧时继续排队识别旧画面。骨架调试流默认关闭，只在星球端打开动捕调试面板时按约 `8Hz` 推送，避免日常手势控制被调试数据拖慢。状态事件会同时上报采集 FPS 与识别 FPS，方便区分摄像头掉帧和识别耗时。

 ```bash
 ls /dev/video*
@@ -306,20 +315,42 @@ WSL 下更通用的方式是把手机摄像头或网络摄像头以 RTSP/HTTP
 ./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
 ```

-如果 WSL 中没有发现 `/dev/video*`，且没有提供 `--motion-agent-camera-urls`，脚本会停止 live 启动并提示处理方式，不会自动降级为 dry-run。可选处理：
+如果希望直接使用 Windows USB 摄像头，可以让脚本调用 `usbipd-win` 透传。该能力是显式开启的，因为摄像头附加到 WSL 期间通常会从 Windows 应用中暂时断开。
+
+只有一个摄像头时：
+
+```bash
+./planet.sh start --motion-agent --motion-agent-wsl-usbipd
+```
+
+多个摄像头时，先查看 BUSID，再指定设备：
+
+```bash
+usbipd.exe list
+./planet.sh start --motion-agent --motion-agent-wsl-usbipd-busid 3-2
+```
+
+如果 `usbipd attach` 提示设备未共享或未绑定，脚本会尝试弹出 Windows 管理员 PowerShell 自动执行 `usbipd bind`，然后重试 attach。若 UAC 被取消或自动 bind 失败，可在 Windows 管理员 PowerShell 中手动执行：
+
+```powershell
+usbipd bind --busid 3-2
+usbipd attach --wsl --busid 3-2
+```
+
+如果 WSL 中没有发现 `/dev/video*`，且没有提供 `--motion-agent-camera-urls`，默认隐式启动会降级为 dry-run。显式 live 启动会停止并提示处理方式。可选处理：

 ```bash
 ./planet.sh start --motion-agent --motion-agent-camera-urls http://<手机IP>:8080/video
+./planet.sh start --motion-agent --motion-agent-wsl-usbipd
 ./planet.sh start --motion-agent --motion-agent-dry-run
 ```

-只有显式设置 `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1` 时，WSL 无摄像头才会自动降级。
+显式 live 启动时，只有设置 `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1`，WSL 无摄像头才会自动降级。

-也可以用环境变量启用：
+`--non-motion-agent` 是命令级跳过入口。环境变量仍可调整服务启动方式：

 ```bash
-PLANET_START_MOTION_AGENT=1 ./planet.sh start
-MOTION_AGENT_DRY_RUN=1 PLANET_START_MOTION_AGENT=1 ./planet.sh start
+MOTION_AGENT_DRY_RUN=1 ./planet.sh start
 ```

 日志入口：
--- a/docs/technical/zh/platform-data-flows.md
+++ b/docs/technical/zh/platform-data-flows.md
@@ -39,7 +39,7 @@ flowchart TB
  VesselRaw["AIS / BarentsWatch"] --> VesselDerived["vessel_static / vessel_position"]
  VesselDerived --> VesselLayer["vessels 图层"]
  Interactables["earth_interactables"] --> InteractableLayer["interactables 图层"]
-  NewsRaw["RSS / Live / News"] --> NewsItems["earth_news_items"]
+  NewsRaw["RSS / 手动新闻 / Live"] --> NewsItems["earth_news_items"]
  NewsItems --> NewsLayer["news / media 图层"]
 ```

@@ -51,7 +51,7 @@ flowchart TB
 | BGP 态势 | 展示观测站、异常事件、路由事件和区域态势 | `ris_live_bgp`、`bgpstream_bgp`、prefix geography sources | `bgp_observations`、`bgp_anomalies`、`bgp_incidents`、`bgp_collector_locations` | `bgp` | `clear_then_reload` |
 | 船舶 | 展示 AIS 船只、位置、轨迹和源健康 | AIS sources、`barentswatch_vessels` | `vessel_static`、`vessel_position`、`ais_raw_observations`、`ais_source_health` | `vessels` | `clear_then_reload` |
 | 可交互对象 | 支撑通用地表图标、人工点位和未来扩展对象 | `earth_interactables` | 无 | `interactables` | `delta` |
-| 新闻与媒体 | 支撑 Earth 新闻、直播和巡航摘要 | news sources | `earth_news_items` | `news` / `media` | `reload` |
+| 新闻与媒体 | 支撑 Earth 新闻、直播和巡航摘要 | RSS news sources、手动新闻、直播源 | `earth_news_items` | `news` / `media` | `reload` |

 ## 卫星链路

@@ -141,12 +141,12 @@ sequenceDiagram

 新闻与媒体数据用于 Earth 顶部新闻条、直播面板、新闻巡航和态势摘要。它们的视觉状态比地理对象更偏内容刷新，因此默认使用 `reload`。

- **采集入口**：RSS、直播源、新闻 source。
- **事实表**：新闻 source 的 `collected_data`。
+- **采集入口**：RSS 新闻源、`智能星球内容 -> 新闻内容` 的手动新闻、直播源。
+- **事实表**：新闻 source 的 `collected_data`；手动新闻直接写入 `earth_news_items`，并以 `feed_type/source_type=manual` 标记内容来源。
 - **派生表**：`earth_news_items`。
- **接口**：新闻、直播和媒体 visualization / content API。
+- **接口**：`/api/v1/news/earth-feed` 读取 `earth_news_items`；后台管理接口 `/api/v1/earth/news-items` 支持新增、JSON 导入、编辑、删除和重新处理手动新闻。
 - **删除语义**：删除新闻 source 或 `earth_news_items` 后广播 `news` / `media` reload；前端重拉后列表为空即隐藏对应内容。
- **常见异常**：直播面板仍显示旧内容，通常是媒体组件本地状态没有响应 layer update，或内容接口缓存未失效。
+- **常见异常**：手动新闻保存后只显示原文或大区锚点是正常的“先展示再精修”窗口；若长期不更新，应检查 `earth_news_enrichment` 队列、AI / Web Search 配置和 `enrichment_status`。直播面板仍显示旧内容，通常是媒体组件本地状态没有响应 layer update，或内容接口缓存未失效。

 ## 扩展新图层

--- a/docs/technical/zh/quickstart.md
+++ b/docs/technical/zh/quickstart.md
@@ -50,7 +50,7 @@
 - 搜索可以查找海缆、卫星、算力中心、BGP 事件
 - 算力中心和 BGP 观测站详情卡可以自动采集坐标候选，并能在智能星球上预览
 - 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
- 设置面板的旋转 / 巡航 / 动捕模式可以切换；视图设置里可以切换悬停提示，卫星相关设置里可以打开或关闭真实高度分层和轨迹显示
+- 设置面板的旋转 / 巡航 / 动捕模式可以切换；动捕设置可以选择输入源和允许识别的动作；视图设置里可以切换悬停提示，卫星相关设置里可以打开或关闭真实高度分层和轨迹显示

 ## 5. 找回密码