# 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` 仍是占位地址，请在正式发布前补成真实仓库和文档链接。