release: bump version to 0.66.0

docs/technical/zh/ops-runbook.md

@@ -136,6 +136,20 @@
 - 手机或平板演示 Earth
 - 局域网其他机器访问同一开发实例
 
+Windows 侧可以使用仓库根目录的 `planet.cmd` 作为一键入口。它会请求管理员权限，进入 `Ubuntu` WSL 发行版的 `/home/linkong/planet`，执行 `./planet.sh restart --allow-lan`，成功后打开 `http://localhost:3000/earth`，并把终端停留在 WSL shell 中便于继续排查日志。若本机发行版名称或项目路径不同，需要先按实际环境调整 `planet.cmd` 中的 `wsl.exe -d ... --cd ...` 参数。
+
+新机器优先确认 WSL 版本：
+
+```powershell
+wsl -l -v
+```
+
+Planet 开发环境建议使用 WSL2。WSL1 下网络、文件系统和进程模型与 Linux 差异更大，可能表现为 Bun 包管理命令只返回 `An unknown error occurred (Unexpected)`、端口释放不稳定，或局域网访问行为与脚本预期不一致。若发行版仍是 WSL1，可转换：
+
+```powershell
+wsl --set-version Ubuntu 2
+```
+
 `--allow-lan` 会让前端、后端和 AI Provider 直接对开发机开放：前端 `3000`、后端 `8000`、AI Provider `8010`。脚本启动前会检查这三个端口；如果 WSL/Linux 侧无法释放端口，并检测到 Windows 侧 listener 或旧 `portproxy`，会请求管理员 PowerShell 清理。WSL 中运行时，Windows 本机一般可以通过 `localhost` 访问，局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 防火墙放行。
 
 建议按顺序排查：
@@ -200,13 +214,32 @@ AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依
 ./planet.sh restart -a
 ```
 
+重建判断使用内容 fingerprint，而不是只看文件 mtime。`planet.sh` 会把 `aiprovider/` 文件、`aiprovider/Dockerfile`、`pyproject.toml`、`uv.lock`、`PYTHON_IMAGE`、`UV_IMAGE` 和依赖指纹合成 `AI_PROVIDER_BUILD_FINGERPRINT`，构建时写入镜像 label `planet.aiprovider.build-fingerprint`。如果现有 `planet-aiprovider:latest` 镜像的 label 与当前 fingerprint 一致，脚本会跳过 rebuild 并刷新本地 stamp；旧镜像没有 label 时才回退到 state/cache 里的 stamp 判断。
+
+Docker 构建统一使用 `uv sync --frozen`。为了让容器构建也能复用本机 uv 镜像源配置，脚本会解析以下顺序中的第一个配置文件，并通过 BuildKit secret 挂到容器内 `/root/.config/uv/uv.toml`：
+
+1. 当前环境的 `UV_CONFIG_FILE`
+2. 仓库根目录 `uv.toml`
+3. `${XDG_CONFIG_HOME:-~/.config}/uv/uv.toml`
+4. `~/.uv/uv.toml`
+
+如果都不存在，脚本会创建一个空的 state 文件作为 secret，避免 Compose 的 secret file 缺失。进入 Docker 构建前会清掉 `UV_DEFAULT_INDEX`、`UV_INDEX_URL`、`UV_EXTRA_INDEX_URL` 这类环境变量，只保留明确的 `UV_CONFIG_FILE`，让本地和容器里的依赖解析更可复现。需要临时使用清华源时，可在仓库根目录准备：
+
+```toml
+[[index]]
+name = "tsinghua"
+url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
+default = true
+```
+
 构建较慢时按层排查：
 
 | 现象 | 常见原因 | 处理方式 |
 | --- | --- | --- |
 | `transferring context` 很大 | build context 含前端资源等无关文件 | `.dockerignore` 只发送必需文件 |
-| `uv sync` 下载较慢 | 首次构建或缓存为空 | 等待首次完成，后续复用 BuildKit 缓存 |
+| `uv sync --frozen` 下载较慢 | 首次构建、缓存为空或 uv 镜像源未配置 | 等待首次完成，后续复用 BuildKit 缓存；必要时配置 `uv.toml` |
 | 改密钥后仍是旧配置 | 容器未重启 | `./planet.sh restart -a` |
+| 修改代码但镜像未重建 | fingerprint 与镜像 label 一致 | 确认改动是否进入 `aiprovider/`、Dockerfile 或 Python 依赖；必要时删除 `planet-aiprovider:latest` 后重试 |
 
 ## SMTP 邮件（公开注册依赖）
 
@@ -233,6 +266,15 @@ OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600
 
 ## 开发命令约定
 
+后端和脚本初始化统一使用锁文件：
+
+```bash
+uv python install 3.14
+uv sync --frozen --group dev
+```
+
+`--frozen` 会拒绝隐式改写 `uv.lock`，适合新机器、CI 和 Docker 构建。需要升级依赖时，应先在开发机明确更新 `pyproject.toml` / `uv.lock`，再提交锁文件。
+
 前端必须使用 Bun：
 
 ```bash