config-man/docs/uv-tool.md

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 中可用：

rclone version

如果命令无法执行，config-man 的非 --mock 模式也无法正常工作。

从源码运行

在仓库根目录执行：

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，更推荐安装为本地工具：

uv tool install --from . config-man
config-man --help
config-man show-config

常见维护命令：

uv tool upgrade config-man
uv tool uninstall config-man

安装后更适合使用以下会写入本地配置的命令：

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 后，配置会保存到该文件。

常用环境变量

如果你不想把配置写入文件，可以使用环境变量：

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 可使用：

$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"

命令示例

查看配置

config-man view --version 0.30 --mock
config-man view --version 0.30 --json --mock

建议更新

config-man suggest-update --platform android --target-version 0.29 --update-version 0.30 --mock

强制更新

config-man force-update --platform ios --target-version 0.29 --update-version 0.30 --mock

查看当前生效配置

config-man show-config

交互式加密原始配置

项目还提供一个附加命令：

uv tool run --from . config-man-encrypt

该命令为交互式脚本，更适合作为辅助工具，而不是主入口。

验证建议

建议至少验证以下命令：

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

如果你计划长期使用，再验证安装后的行为：

uv tool install --from . config-man
config-man --help
config-man show-config

同时建议手动确认：

• rclone 在 tool 环境下可以被正常找到
• Cloudflare 相关配置能够从环境变量或配置文件加载
• 非 --mock 模式在目标网络环境中可访问对象存储与 CDN

构建与发布

如果目标是让其他人直接执行 uv tool install config-man，还需要先把包发布到索引。

本地构建：

uv build

构建完成后可验证产物：

uv tool run --from dist/*.whl config-man --help

发布到索引后，用户即可通过：

uv tool install config-man

如果当前项目的 project.urls 仍是占位地址，请在正式发布前补成真实仓库和文档链接。