---
name: uv tool 封装计划
overview: 把现有 `config-man` 项目整理为可通过 `uv tool` 使用的 CLI 工具，重点补齐安装方式、配置持久化说明、外部依赖说明和发布验证文档，并将计划落在 `docs/` 下的 markdown 文档中。
todos:
  - id: audit-packaging
    content: 核对 `pyproject.toml` 的脚本入口、元数据和 Python 版本约束是否适合 UV tool 分发
    status: pending
  - id: document-uv-usage
    content: 在 `docs/` 中新增一份面向 UV tool 的安装、运行、配置和验证文档
    status: pending
  - id: align-existing-docs
    content: 更新 `README.md` 与 `docs/USAGE.md`，把旧的 `python main.py` / `pip install -e .` 说明与 UV 用法对齐
    status: pending
  - id: define-validation-release
    content: 整理本地验证命令与可选发布流程，确保从源码和从索引两条路径都清晰
    status: pending
isProject: false
---

# 将 Config-Man 封装为 UV Tool

## 现状判断

- 项目已经是标准可安装包：`[pyproject.toml](D:/workwork/config-man-new-repo/pyproject.toml)` 使用 `hatchling` 构建，并采用 `src` 布局。
- 项目已经暴露 CLI 入口，具备 `uv tool` 的基础条件：

```42:44:pyproject.toml
[project.scripts]
config-man = "config_man.cli.main:main"
config-man-encrypt = "config_man.encrypt_config:main"
```

- CLI 主入口已经集中在 `[src/config_man/cli/main.py](D:/workwork/config-man-new-repo/src/config_man/cli/main.py)`，适合直接作为 `uv tool` 的命令入口。
- 配置持久化逻辑已经存在于 `[src/config_man/utils/config.py](D:/workwork/config-man-new-repo/src/config_man/utils/config.py)`，会优先读取 `~/.config/config-man/config-man.json`，这很适合 tool 安装后的用户级使用。
- 远程配置读写核心已集中在 `[src/config_man/core/config_manager.py](D:/workwork/config-man-new-repo/src/config_man/core/config_manager.py)` 与 `[src/config_man/core/suggest_update_command.py](D:/workwork/config-man-new-repo/src/config_man/core/suggest_update_command.py)`，因此本次工作不需要重写业务逻辑，重点是分发与使用体验。

## UV Tool 做法摘要

- 保持当前 `[project.scripts]` 方案不变。这正是 `uv tool install` / `uv tool run` 识别 CLI 的标准方式。
- 明确两种使用路径：
  - 本地源码验证：`uv tool run --from . config-man --help`
  - 发布后安装：`uv tool install config-man`
- 将工具运行前置条件写清楚：该工具除 Python 依赖外，还依赖外部命令 `rclone`，并且部分命令需要 Cloudflare 配置与网络访问。
- 明确配置来源优先级：命令行参数 > 环境变量 > `~/.config/config-man/config-man.json` > 项目默认配置。
- 补一份专门面向 `uv` 用户的文档，优先放在 `[docs/](D:/workwork/config-man-new-repo/docs/)` 下，例如新增 `[docs/uv-tool.md](D:/workwork/config-man-new-repo/docs/uv-tool.md)`。
- 如果目标不仅是“本地可作为 tool 使用”，还要“别人可直接安装”，则补充打包校验与发布步骤：`uv build` 或 `python -m build`，然后上传到包索引。

## 计划范围

- 只整理为“可作为 UV tool 使用和分发”的项目。
- 不改远程配置读写逻辑本身，除非在验证过程中发现入口或路径问题。
- 文档以用户安装、配置、验证、发布为主，代码改动以最小必要为原则。

## 实施步骤

1. 校验入口与元数据

- 复核 `[pyproject.toml](D:/workwork/config-man-new-repo/pyproject.toml)` 中的包名、版本、`[project.scripts]`、`readme`、`requires-python`、`project.urls` 是否适合对外发布。
- 确认 CLI 暴露的是稳定入口 `config-man`，并评估 `config-man-encrypt` 是否也需要被纳入 UV tool 使用文档。

1. 统一 UV 使用方式

- 在主文档 `[README.md](D:/workwork/config-man-new-repo/README.md)` 与新文档 `[docs/uv-tool.md](D:/workwork/config-man-new-repo/docs/uv-tool.md)` 中明确：
  - 如何本地运行：`uv tool run --from . config-man --help`
  - 如何本地安装：`uv tool install --from . config-man`
  - 如何卸载/升级：`uv tool uninstall config-man`、`uv tool upgrade config-man`
- 说明哪些命令适合 `uv tool run`，哪些命令因需要持久配置更适合 `uv tool install` 后长期使用。

1. 补齐运行前置条件说明

- 在文档中明确外部依赖 `rclone` 的安装与配置要求。
- 说明 Cloudflare 相关配置项和可选环境变量来源，引用 `[src/config_man/utils/config.py](D:/workwork/config-man-new-repo/src/config_man/utils/config.py)` 中已有键名。
- 明确用户配置文件落点 `~/.config/config-man/config-man.json`，以及 `set-config` / `setup-cloudflare` 如何写入该文件。

1. 验证 UV Tool 体验

- 规划验证命令：
  - `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`
- 若需要更稳定的 tool 体验，可再验证安装后行为：`uv tool install --from . config-man`，然后运行 `config-man --help`。
- 特别确认从 tool 环境调用 `rclone` 时，PATH 与外部命令查找逻辑是否正常。

1. 预留发布路径

- 如果要让他人直接通过 `uv tool install config-man` 安装，则补充发布文档：构建 wheel/sdist、上传到索引、验证索引安装。
- 将现有 `[PROJECT_STRUCTURE.md](D:/workwork/config-man-new-repo/PROJECT_STRUCTURE.md)` 里的构建/发布说明与新的 `uv` 文档保持一致，避免出现 `pip install -e .` 与 `python main.py` 为主的旧说明主导用户路径。

## 预期改动文件

- 主要新增：`[docs/uv-tool.md](D:/workwork/config-man-new-repo/docs/uv-tool.md)`
- 可能更新：`[README.md](D:/workwork/config-man-new-repo/README.md)`
- 可能更新：`[docs/USAGE.md](D:/workwork/config-man-new-repo/docs/USAGE.md)`
- 视情况微调：`[pyproject.toml](D:/workwork/config-man-new-repo/pyproject.toml)`

## 风险与注意点

- 当前 `requires-python = ">=3.13"` 会限制 `uv tool` 安装人群；若这是刻意要求，可保留，否则应评估是否放宽。
- `[src/config_man/encrypt_config.py](D:/workwork/config-man-new-repo/src/config_man/encrypt_config.py)` 是交互式脚本，适合作为附加命令，但不一定适合作为文档主入口。
- 部分现有文档仍以 `python main.py`、`pip install -e .` 为主，需要避免与 `uv tool` 用法并存时造成歧义。
- 该工具依赖外部系统命令 `rclone`，因此即使 Python 打包完整，仍需单独说明系统环境准备。

## 完成标准

- 用户能看着文档直接用 `uv tool run --from . config-man ...` 运行项目。
- 用户能理解何时应改用 `uv tool install --from . config-man` 以获得持久 CLI 体验。
- 文档准确说明配置文件位置、环境变量、外部依赖与发布路径。
- 如需对外分发，项目具备清晰的构建与发布说明，可支持未来 `uv tool install config-man`。