[U] Wrap into uv tool.

docs/uv-tool.md

@@ -0,0 +1,185 @@
+# Config-Man 的 UV Tool 用法
+
+## 适用场景
+
+`config-man` 已经通过 `pyproject.toml` 暴露了 CLI 入口，因此可以直接作为 `uv tool` 使用。
+
+- 临时从源码运行，适合验证命令是否可用：`uv tool run --from . config-man ...`
+- 安装为本地长期命令，适合需要持久配置的日常使用：`uv tool install --from . config-man`
+- 发布到包索引后，可直接安装：`uv tool install config-man`
+
+## 前置条件
+
+使用本工具前，需要准备以下环境：
+
+- Python 3.9+
+- `uv`
+- `rclone`
+- 可选的 Cloudflare 凭证，用于自动刷新 CDN 缓存
+
+安装 `rclone` 后，请先确认它在系统 `PATH` 中可用：
+
+```bash
+rclone version
+```
+
+如果命令无法执行，`config-man` 的非 `--mock` 模式也无法正常工作。
+
+## 从源码运行
+
+在仓库根目录执行：
+
+```bash
+uv tool run --from . config-man --help
+uv tool run --from . config-man show-config
+uv tool run --from . config-man view --version 0.30 --mock
+```
+
+这种方式适合：
+
+- 快速验证 CLI 是否能启动
+- 本地开发时试跑单个命令
+- 不需要保留用户级配置的临时操作
+
+## 本地安装为工具
+
+如果你会反复使用 `config-man`，更推荐安装为本地工具：
+
+```bash
+uv tool install --from . config-man
+config-man --help
+config-man show-config
+```
+
+常见维护命令：
+
+```bash
+uv tool upgrade config-man
+uv tool uninstall config-man
+```
+
+安装后更适合使用以下会写入本地配置的命令：
+
+```bash
+config-man set-config --key storage.path --value ab
+config-man set-config --key storage.rclone_remote --value remote
+config-man setup-cloudflare --api-token <token> --zone-id <zone_id>
+```
+
+## 配置来源优先级
+
+运行时配置优先级如下：
+
+1. 命令行参数
+2. 环境变量
+3. 用户配置文件 `~/.config/config-man/config-man.json`
+4. 项目默认配置
+
+默认用户配置文件路径由 `src/config_man/utils/config.py` 定义；执行 `set-config` 和 `setup-cloudflare` 后，配置会保存到该文件。
+
+## 常用环境变量
+
+如果你不想把配置写入文件，可以使用环境变量：
+
+```bash
+export CONFIG_MAN_STORAGE_PATH=ab
+export CONFIG_MAN_STORAGE_RCLONE_REMOTE=remote
+export CONFIG_MAN_CDN_BASE_URL=https://cdn.example.com
+export CONFIG_MAN_CDN_CLOUDFLARE_API_TOKEN=your_api_token
+export CONFIG_MAN_CDN_CLOUDFLARE_ZONE_ID=your_zone_id
+```
+
+Windows PowerShell 可使用：
+
+```powershell
+$env:CONFIG_MAN_STORAGE_PATH="ab"
+$env:CONFIG_MAN_STORAGE_RCLONE_REMOTE="remote"
+$env:CONFIG_MAN_CDN_BASE_URL="https://cdn.example.com"
+$env:CONFIG_MAN_CDN_CLOUDFLARE_API_TOKEN="your_api_token"
+$env:CONFIG_MAN_CDN_CLOUDFLARE_ZONE_ID="your_zone_id"
+```
+
+## 命令示例
+
+### 查看配置
+
+```bash
+config-man view --version 0.30 --mock
+config-man view --version 0.30 --json --mock
+```
+
+### 建议更新
+
+```bash
+config-man suggest-update --platform android --target-version 0.29 --update-version 0.30 --mock
+```
+
+### 强制更新
+
+```bash
+config-man force-update --platform ios --target-version 0.29 --update-version 0.30 --mock
+```
+
+### 查看当前生效配置
+
+```bash
+config-man show-config
+```
+
+### 交互式加密原始配置
+
+项目还提供一个附加命令：
+
+```bash
+uv tool run --from . config-man-encrypt
+```
+
+该命令为交互式脚本，更适合作为辅助工具，而不是主入口。
+
+## 验证建议
+
+建议至少验证以下命令：
+
+```bash
+uv tool run --from . config-man --help
+uv tool run --from . config-man show-config
+uv tool run --from . config-man view --version 0.30 --mock
+```
+
+如果你计划长期使用，再验证安装后的行为：
+
+```bash
+uv tool install --from . config-man
+config-man --help
+config-man show-config
+```
+
+同时建议手动确认：
+
+- `rclone` 在 tool 环境下可以被正常找到
+- Cloudflare 相关配置能够从环境变量或配置文件加载
+- 非 `--mock` 模式在目标网络环境中可访问对象存储与 CDN
+
+## 构建与发布
+
+如果目标是让其他人直接执行 `uv tool install config-man`，还需要先把包发布到索引。
+
+本地构建：
+
+```bash
+uv build
+```
+
+构建完成后可验证产物：
+
+```bash
+uv tool run --from dist/*.whl config-man --help
+```
+
+发布到索引后，用户即可通过：
+
+```bash
+uv tool install config-man
+```
+
+如果当前项目的 `project.urls` 仍是占位地址，请在正式发布前补成真实仓库和文档链接。