release: bump version to 0.53.0

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

@@ -22,10 +22,10 @@ image_exists AND stamp_non_empty AND fingerprint_match
 
 ### 修复
 
-将戳文件路径从 `/tmp/` 改到持久路径：
+将戳文件路径从临时目录改到持久缓存路径：
 
 ```bash
-AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
+AI_PROVIDER_BUILD_STAMP_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/planet/aiprovider_build.sha256"
 ```
 
 写入时确保目录存在：
@@ -94,7 +94,7 @@ COPY aiprovider /app/aiprovider
 
 ### 运行期配置来源
 
-`planet.sh` 启动 AI Provider 前会生成临时 env-file，并把它传给 Compose 或手动 `docker run` fallback。配置优先来自：
+`planet.sh` 启动 AI Provider 前会生成受当前用户保护的运行期 env-file，并把它传给 Compose 或手动 `docker run` fallback。默认路径位于 `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`。配置优先来自：
 
 1. `aiprovider/.env`
 2. `~/.zshrc` 中简单的 `export AI_...=...` 或 `AI_...=...` 行
@@ -202,6 +202,62 @@ PY
 
 修复戳文件路径后，无参 `restart` 同样使用 `stop + start`，fingerprint 检查正常生效，行为与 `restart -b` 完全一致。无需额外代码变更。
 
+## 状态文件、日志与失败清理
+
+`planet.sh` 不再把 PID、日志和运行期 env-file 写入固定 `/tmp/planet_*` 路径。默认状态目录为：
+
+```bash
+${XDG_STATE_HOME:-$HOME/.local/state}/planet
+```
+
+脚本启动时会创建该目录并尽量设置为 `700`。当前使用的文件包括：
+
+- `backend.pid` / `frontend.pid` / `motion_agent.pid`
+- `backend.log` / `frontend.log` / `motion_agent.log`
+- `aiprovider_build.log`
+- `aiprovider_runtime.env`
+- `ports.env`
+
+PID 文件写入前会校验 PID 为正整数，写入时带换行并尽量设置为 `600`。读取 PID 文件时，如果内容不是数字，脚本会忽略该文件，不会把垃圾内容传给 `kill`。
+
+`start` 成功后会把本次端口写入 `ports.env`。后续执行 `./planet.sh health` 时，会优先检查上次启动端口；如果没有状态文件，则回退到默认端口 `8000`、`3000`、`8010`、`8765`。这避免了用自定义端口启动后，健康检查仍只看默认端口的问题。
+
+启动过程有轻量失败清理：如果 `start` 中途失败，脚本只清理本轮已经拉起的本地进程（backend、frontend、Motion Agent），不会在正常启动完成后停止服务。AI Provider、PostgreSQL 和 Redis 容器仍按原有容器生命周期管理。
+
+## 健康检查与安全加固
+
+HTTP 健康检查统一使用 `curl -fsS --max-time`。因此 `/health` 返回 4xx/5xx 不再被视为在线。
+
+进程终止路径现在会校验：
+
+- signal 只允许 `TERM`、`KILL`、`INT`、`HUP`；
+- PID 必须是正整数；
+- 进程组 PGID 必须是正整数。
+
+这可以避免坏 PID 文件或错误 signal 造成不可预期的 `kill` 行为。
+
+前端和 Motion Agent 启动失败时，现在也会调用 `print_port_listener_details()`，输出与后端一致的端口监听诊断。WSL 下如果端口看起来被 Windows 侧占用，脚本仍只在检测到 WSL 时才调用 PowerShell 诊断或清理路径。
+
+## 跨平台注意事项
+
+当前脚本是 Linux-first，并带有 WSL 增强。普通 Linux 不会执行 WSL PowerShell 逻辑；WSL 下会额外提供 Windows listener、portproxy 和摄像头提示。
+
+如果要把同一份脚本扩展为 Linux、macOS、WSL 三平台通用，还需要继续封装这些命令差异：
+
+- `stat --format`、`sort -V`、`xargs -r` 是 GNU 风格，macOS 默认 BSD 工具不完全兼容。
+- `hostname -I`、`ss`、`fuser`、`systemctl` 在 macOS 上通常不可用。
+- `tac` 在 macOS 上不一定存在，可用 `awk` 或 Python 兜底。
+- Docker Desktop on macOS 不适用 `systemctl` daemon 诊断。
+- 摄像头自动发现依赖 `/dev/video*` / `v4l2-ctl`，这是 Linux 路线；macOS 应显式使用 camera URL 或另做 AVFoundation 检测。
+
+维护方向是增加一个小的 platform compatibility 层，把端口监听检测、版本比较、文件元信息、反向 tail、LAN IP 获取和 Docker daemon 诊断集中处理，而不是在业务启动流程里继续散落平台判断。
+
+## 正式交付边界
+
+`planet.sh` 是本地开发便利脚本，不作为正式生产启动入口。正式交付应通过 Kubernetes 的 `Deployment`、`Service`、`Ingress`、readiness/liveness probe 管理端口、健康检查、重启和滚动发布。这样生产环境不需要脚本抢占宿主机端口，也不会依赖 Vite dev server。
+
+前端生产形态是 `vite build` 生成静态资源，再由 nginx/Caddy 等 HTTP 服务器托管。不要在生产中使用 `bun run dev` 或 `vite preview`。当前不维护 Webpack 双构建链；如果未来需要评估更企业化的构建生态，优先做 Rsbuild/Rspack spike。Electron 仅在正式目标变成离线桌面软件时再单独评估。
+
 ## Motion Agent 可选启动
 
 `planet.sh` 现在可以管理本地动作捕捉 Agent，但默认不会启动它，避免普通开发机因为没有摄像头、OpenCV 或 MediaPipe 而影响后端/前端启动。