Mustapha/config-man

Fork 0

Files

tianbo.shan ca9e32763e [U] Wrap into uv tool.

2026-03-20 20:19:33 +08:00

6.9 KiB

Raw Blame History

name, overview, todos, isProject

name

overview

todos

isProject

uv tool 封装计划

把现有 `config-man` 项目整理为可通过 `uv tool` 使用的 CLI 工具，重点补齐安装方式、配置持久化说明、外部依赖说明和发布验证文档，并将计划落在 `docs/` 下的 markdown 文档中。

id	content	status
audit-packaging	核对 `pyproject.toml` 的脚本入口、元数据和 Python 版本约束是否适合 UV tool 分发	pending

id	content	status
document-uv-usage	在 `docs/` 中新增一份面向 UV tool 的安装、运行、配置和验证文档	pending

id	content	status
align-existing-docs	更新 `README.md` 与 `docs/USAGE.md`，把旧的 `python main.py` / `pip install -e .` 说明与 UV 用法对齐	pending

id	content	status
define-validation-release	整理本地验证命令与可选发布流程，确保从源码和从索引两条路径都清晰	pending

false

将 Config-Man 封装为 UV Tool

现状判断

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

[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 使用和分发”的项目。
不改远程配置读写逻辑本身，除非在验证过程中发现入口或路径问题。
文档以用户安装、配置、验证、发布为主，代码改动以最小必要为原则。

实施步骤

校验入口与元数据

复核 [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 使用文档。

统一 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 后长期使用。

补齐运行前置条件说明

在文档中明确外部依赖 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 如何写入该文件。

验证 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 与外部命令查找逻辑是否正常。

预留发布路径

如果要让他人直接通过 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。

6.9 KiB Raw Blame History Unescape Escape