文章目录为什么选 uv而不是再手搓 venv目录与模块边界函数优先CLI 另放跨平台能统一就统一不能统一就拆文件项目根怎么找只认 pyproject.toml资源释放与中断退出即清空占用小结可复制的检查清单自己维护一堆零散脚本时最难受的往往不是「写不出来」而是依赖装乱、Win/macOS 行为不一致、业务逻辑和 argparse 缠在一起、跑完留下孤儿进程。本文以一套真实的跨平台 Python CLI 工具库mscc-cli为例整理可复用的工程约定。为什么选 uv而不是再手搓 venvmscc-cli 用pyproject.toml声明项目与依赖日常在仓库根执行uvsyncuv run ai/cli.py--prompt短任务uv run会按当前锁文件起隔离环境再跑脚本团队成员少争论「你本机 Python 是哪一版」。项目要求requires-python 3.13依赖写在[project].dependencies开发依赖放[dependency-groups].dev。核心可复用包如core用 hatchling 打进 wheel业务脚本直接from core...导入。要点uv run是快捷测试入口不是业务主路径。长文本、多行任务应走可 import 的函数避免 Windows 上命令行参数被截断。目录与模块边界函数优先CLI 另放约定可以压成一句话能力做成函数命令行只做薄壳。文件职责xxx.py/workflow.py可 import 的业务函数cli.py仅 argparse、校验、退出码再调用函数例如 Agent 入口业务用from ai.agent import run_agent人工试跑用uv run ai/cli.py--prompt用一句话总结本仓库多步编排同理workflow.py不含argparse、不含__main__cli.py不复制编排逻辑。其它脚本只调主入口不直接 import 某一平台实现文件。跨平台能统一就统一不能统一就拆文件跨平台优先pathlib、sys.platform子进程用参数列表禁止shellTrue。同一套代码拧不动时不要在一个文件里堆if win / else实现拆成*_win.py/*_mac.py必要时*_linux.py由workflow.py或主入口按平台选用cli.py不感知平台细节状态输出统一用[OK]/[SKIP]/[FAIL]/[ERROR]失败非零退出方便脚本串联与日志检索。项目根怎么找只认 pyproject.toml硬编码parent.parent、或拿.git/ 文档文件当根标记换目录就碎。mscc-cli 的做法是自脚本路径或 cwd 向上找第一个带pyproject.toml的目录即根defrepo_root(start:Path|NoneNone)-Path:here(startorPath.cwd()).resolve()ifhere.is_file():herehere.parentforcandidatein(here,*here.parents):if(candidate/pyproject.toml).is_file():returncandidatereturnPath.cwd().resolve()ensure_repo_path再把根目录插入sys.path保证任意子目录脚本都能稳定from core.logger import Logger。中间产物放build/日志用统一Logger写到logs/日期_run.log不要各脚本自建一套。资源释放与中断退出即清空占用浏览器、子进程、文件锁、HTTP session只要脚本进程要退出成功、失败、超时、CtrlC都必须收尾。实践上用with/try/finally禁止只在成功分支里closefinally里清理要防二次异常且幂等CtrlC 视为正常中止打印[SKIP] 已中断退出码130并杀掉本脚本拉起的子进程浏览器自动化统一走共用封装如core.browser.open_browser按--user-data隔离 profile退出关闭 context / Playwright避免残留 Chrome。小结可复制的检查清单依赖与运行交给 uv pyproject.toml业务函数可 importcli.py只做参数与退出码平台差异拆文件主入口统一调度根目录只认pyproject.toml产物进build/日志统一任何退出路径都释放占用按这几条搭工具库脚本会从「能跑」变成「能复用、能协作、能在三端稳定跑」。后续加新能力时先问自己别人能不能import调用uv run 模块/cli.py能不能一分钟验通答得上结构就对了。