uv 风格指南深度解读：STYLE.md 如何统一 CLI 输出、日志与文档写作

本文以 uv 仓库根目录下的 STYLE.md 为主线，完整解析 uv 官方风格指南的全部规则：通用写作规范、uv 命名约定、术语表、三层文档结构（Guides/Concepts/Reference）、代码块规范，以及 CLI 消息、日志、警告与 Hint 的输出约定。读完后你不仅能照着规范撰写与 uv 风格一致的文案和文档，还能看到每一条规范在 uv-warnings、uv-errors、uv-logging 等 crate 源码中的落地实现，理解这些规范是如何被代码"强制执行"的。

一、风格指南的适用范围

STYLE.md 开篇即声明：这是一份"进行中的风格指南（work-in-progress style guide）"，约束对象是 CLI 输出和文档中的用户可见文案（user-facing messaging）。也就是说，它管的不是 Rust 代码格式（那由 rustfmt.toml 和 clippy.toml 负责），而是终端消息、警告、错误提示与官方文档的文字表达。

二、通用写作规则（General）

STYLE.md 的 General 小节给出了 10 条基础排版规则，逐条继承如下：

1. e.g. 与 i.e. 必须被逗号包围，例如本条的写法。
2. 允许使用破折号，但在等宽字体下不推荐；必须使用真正的 em-dash 字符 —，而不是 -- 或 -。
3. em-dash 两侧必须留空格，写作 "hello — world" 而不是 "hello—world"。
4. 复合词要加连字符，例如 platform-specific 而非 platform specific。
5. 用反引号转义（escape）：命令、代码表达式、包名和文件路径。
6. 裸 URL 用尖括号包裹，例如 <https://astral.sh>；但如果是代码示例，则改用反引号。
7. 参考文档之外应避免裸 URL，优先使用带标签的链接，例如 name。
8. 消息若以单个相关值结尾，值前面要加冒号，例如 This is the value: value；如果该值是字面量，用反引号包裹。
9. Markdown 文件按 100 字符换行。
10. 命令行参数与其取值之间用空格而非等号，例如 --resolution lowest，而不是 --resolution=lowest。

其中第 10 条值得特别注意：它不仅影响文档，还直接体现在 docs 目录的所有示例中——uv 文档统一教用户使用 --flag value 形式书写命令，保持 CLI 参数习惯在全站一致。

三、uv 自身的命名规范（Styling uv）

规则只有一条总纲加三条细则——"Just uv, please"：

1. 不要给 uv 加反引号，除非特指 uv 可执行文件本身；
2. 不要大写首字母，例如句首也不写 "Uv"；
3. 不要全大写，例如 "UV" 只允许出现在环境变量语境，例如 UV_PYTHON。

这一约定在仓库内部是自我一致的：环境变量一律以 UV_ 前缀出现（如 STYLE.md 提到的 UV_NO_PROGRESS），而文档正文中对项目的称呼始终是小写的 "uv"。

四、术语表（Terminology）

1. 写作 lockfile，不写 "lock file"。
2. 写作 pre-release，不写 "prerelease"；但在代码中是另一套规则：类型/标识符用 Prerelease 而非 PreRelease，函数/变量等小写语境用 prerelease 而非 pre_release。

uv 的版本解析能力来自 uv-pep440 crate（PEP 440 版本规范的 Rust 实现），其中预发布版本正是以 Prerelease 这类标识符命名的。STYLE.md 的这条术语规则，实质上是在把 PEP 440 的术语（pre-release）与 Rust 命名惯例（camelCase 类型名）在"文档侧"和"代码侧"分别固定下来，避免同一概念在文档和代码里出现三种写法。

五、文档写作总则与三层结构（Documentation / Sections）

STYLE.md 规定官方文档整体分四层写作规则：

文档全局规则

1. 所有句子（包括列表项）句末用句号，除非该列表项只是单个条目（single item）。
2. 避免居高临下的措辞，例如 "simply do this"。
3. "the user" 一词只允许出现在内部或贡献者文档中。
4. 避免使用 "we"，改用 "uv" 或祈使语气。

三层文档结构

uv 的文档被划分为 Guides、Concepts、Reference documentation 三层，每层有明确的受众与语气约束：

Guides（指南）

• 假设读者对 uv 没有任何前置知识；
• 可以假设读者具备领域（Python 生态）基础；
• 应引用相关的概念文档；
• 应有清晰的行文流程，并以明确的行动号召（call to action）收尾；
• 只覆盖上手所需的基本行为，不深入细节，不穷举所有可能性；
• 除非某主题没有对应的概念文档，否则不直接链接到参考文档；
• 可以忽略平台差异；
• 使用第二人称视角，使用祈使语气。

Concepts（概念）

• 应详细覆盖行为（behavior in detail）；
• 不穷举所有可能性，但应覆盖最常见的配置；
• 应引用对应的参考文档；
• 应讨论平台相关行为；
• 使用第三人称视角（避免 "you"）；
• 不使用祈使语气。

Reference documentation（参考文档）

• 应穷举所有选项；
• 一般由代码中的文档自动生成；
• 使用第三人称视角，不使用祈使语气。

这一分层在仓库中可以直接对照验证。docs/ 目录的组织与 STYLE.md 完全吻合：

• docs/guides/ 存放上手与集成指南（如 docs/guides/tools.md、docs/guides/scripts.md）；
• docs/concepts/ 存放行为详解（如 docs/concepts/resolution.md、docs/concepts/python-versions.md）；
• docs/reference/ 存放参考文档（如 docs/reference/installer.md、docs/reference/troubleshooting/ 下的故障排查）。

文档站由 MkDocs Material 主题构建，站点配置见 mkdocs.yml。而"参考文档由代码生成"这一点，对应的是 crates/uv-dev/ 中的生成工具链：generate_cli_reference.rs 从 CLI 定义生成命令参考，generate_options_reference.rs 生成配置项参考，generate_env_vars_reference.rs 生成环境变量参考。贡献者通过 cargo dev generate-all 重新生成这些参考页——这一点在 CONTRIBUTING.md 的 Documentation 一节有说明。

六、代码块规范（Code blocks）

1. 所有代码块必须带语言标记。
2. 使用 console 语法时，用 $ 表示命令——其余内容一律视为输出。
3. 展示命令输出时绝不使用 bash 语法。
4. 优先使用带 $ 前缀的 console，而不是 bash。
5. 尽量不贴命令输出——输出很难保持长期准确。
6. 示例文件用 title 属性标明文件名，例如 pyproject.toml、Dockerfile、example.py。

从文档仓库的实际情况看，console 代码块是绝对主流：仅 docs/pip/compile.md 就有 16 处 ```console 块，docs/guides/tools.md 有 32 处，docs/guides/scripts.md 有 18 处。以 docs/pip/compile.md 为例，输入命令写作 $ uv pip compile requirements.in，其后的依赖锁定结果全部是"输出"，不带 $——这正是上述规则 2、3 的具体形态。用 console 而非 bash 还有一个工程动机：bash 标记会诱导读者把整段（包括输出）当作可执行脚本复制，而 console + $ 明确区分了"你敲的"和"机器说的"。

七、CLI 消息规范（CLI）

语气

1. 句子末尾不加句号（除非消息超过一句话）。
2. 可以使用第二人称，例如 "Did you mean...?"。

这两条让 CLI 输出更像对话而非文档：短、直接、不拖泥带水。

颜色与样式

这是 STYLE.md 中最具强制性的一节：

1. 所有 CLI 输出在不使用颜色的情况下都必须可解读（例如命令即使用绿色渲染，也要包裹反引号）；
2. 必须尊重 NO_COLOR 环境变量；
3. 必须尊重 UV_NO_PROGRESS 环境变量（用于禁用进度条、spinner 等样式）；
4. 颜色语义统一为：
   • 绿色：成功；
   • 红色：错误；
   • 黄色：警告；
   • 青色：提示（hints）、文件路径、重要的用户可见字面量（例如消息中的包名）；
   • 绿色：命令。

这套颜色语义在源码中是可以逐条对上的。日志级别前缀的着色在 crates/uv-logging/src/lib.rs 中实现：TRACE 紫色、DEBUG 蓝色、INFO 绿色、WARN 黄色、ERROR 红色。用户警告的着色在 crates/uv-warnings/src/lib.rs 的 warn_user! 宏中："warning" 用黄色加粗、冒号加粗、消息体加粗。而"青色 hint" 的实现见 crates/uv-errors/src/lib.rs 中的 HintPrefix 类型——"hint" 青色加粗后跟加粗冒号。

"颜色不是信息载体"这条规则在实现中体现为多层兜底：日志输出统一写入经过 anstream 包装的 stderr 流（见 crates/uv/src/logging.rs），anstream 会按终端能力（包括 NO_COLOR）自动剥离 ANSI 序列，因此即使代码里写了 "hello".green()，在非彩色终端下也能读纯文本。uv-logging 的测试 strips_ansi_from_message_fields 还专门验证了字段值中混入的 ANSI 序列会被剥掉，保证日志行永远"去色后可读"。

日志与 verbose 级别

STYLE.md 规定：

1. warn、info、debug、trace 四级日志都通过 --verbose 系列标志显示；显示的具体级别由 RUST_LOG 环境变量控制；
2. 所有日志都必须写到 stderr。

实现上，crates/uv/src/logging.rs 的 setup_logging 函数定义了内部 Level 枚举（Off / DebugUv / TraceUv / TraceAll），每级对应一条默认的 tracing 过滤指令（如 uv=debug、uv=trace），再叠加 RUST_LOG 环境变量通过 EnvFilter 进行覆盖（见 logging.rs）。这与 STYLE.md "显示级别由 RUST_LOG 控制" 的表述严格一致。--verbose 每加一级，默认指令就从 uv=debug 升到 uv=trace 再到全局 trace。日志写入目标是 anstream::AutoStream::new(std::io::stderr(), ...)（logging.rs），从实现层面锁死了"日志只进 stderr"。

CONTRIBUTING.md 的 "Trace-level logging" 小节进一步给出了用户侧用法：

$ RUST_LOG=trace uv

配合 TRACING_DURATIONS_FILE 还可以导出 span 时长可视化文件用于并发分析，属于同一套 RUST_LOG 过滤机制的延伸。

输出流划分（Output）

STYLE.md 只有一条但很关键：只有"可以被管道传给其他程序的数据"才允许写到 stdout。结合上文"日志一律走 stderr"，uv 的流划分就是：stdout 承载可组合的数据（如 uv pip compile 生成的锁定结果），stderr 承载日志、进度、警告。这也解释了为什么 uv 的进度条不会污染管道输出——进度样式与日志同属 stderr 侧。

警告（Warnings）

1. warn_user 和 warn_user_once 两种方法不需要 --verbose 即可显示；当警告是"可行动的"（actionable）时，应优先于 tracing 警告使用这两个方法；
2. 弃用警告必须使用这两个方法；
3. 弃用警告必须是可行动的——即告诉用户下一步该做什么。

这两个方法在 crates/uv-warnings/src/lib.rs 中实现，细节与规范一一对应：

• warn_user! 宏（lib.rs）先检查全局开关 ENABLED，然后以 warning: <加粗消息> 的格式写入 stderr；
• warn_user_once! 宏（lib.rs）在其之上维护了一个进程级 WARNINGS 去重集合（FxHashSet<String>），按消息内容去重——同一警告在一次运行中最多出现一次，避免批量场景（例如一次锁定数百个包）时刷屏。

全仓库对 warn_user! / warn_user_once! 的调用散布在几十个命令与子 crate 中（如 crates/uv-python/src/discovery.rs、crates/uv-resolver/src/resolver/mod.rs、crates/uv-auth/src/providers.rs），覆盖了"配置被弃用""解释器发现失败""认证提示"等典型的可行动场景，验证了这条规范是跨命令统一执行的。

提示（Hints）

1. 错误后面可以跟提示（hint）来建议解决方案；
2. hint 与错误之间必须空一行；
3. hint 的样式固定为 hint: <内容>。

这三条在 crates/uv-errors crate 中被硬编码为渲染逻辑：错误链输出时先写错误，再为每条 hint 写一个 \n（空行）加 HintPrefix（青色 hint + 加粗冒号）加内容（见 lib.rs）。Hints 类型还支持自动去重（extend 时跳过重复条目），并有对应的快照测试验证"错误与 hint 之间有空行分隔"的行为（lib.rs 中 error_with_hints_separates_hints_from_error 等测试）。因此"hint 格式"不依赖开发者自觉，而是由统一的错误输出层保证。

八、规范如何被验证：测试与快照

STYLE.md 的很多规则之所以能长期稳定，是因为它们落在输出层的快照测试里：

• crates/uv-warnings/src/lib.rs 的 format_warning_chain 测试用 insta 快照固定了 warning: 前缀的 ANSI 序列与去色后的纯文本形态；
• crates/uv-logging/src/lib.rs 的测试固定了日志字段对 ANSI 序列的剥离行为；
• crates/uv-errors 的测试固定了 hint 的换行、前缀与去重行为。

这意味着任何修改 warning/hint/日志格式的代码改动，都会通过快照 diff 显式暴露出来，风格规范实际上获得了"测试即规范"的执行力。

九、落地检查清单

如果你在为 uv 撰写文档或用户可见消息，可以按本文归纳的清单自查：

1. 通用排版：em-dash 用 — 且两侧留空、复合词连字符化、命令/包名/路径加反引号、--flag value 用空格分隔参数与取值；
2. 命名：小写 uv，环境变量才用 UV_ 前缀；
3. 术语：lockfile、pre-release；
4. 文档分层：指南用第二人称+祈使语气+行动号召，概念用第三人称+详解行为，参考由代码生成并穷举选项；
5. 代码块：全部带语言标记，命令输出用 console + $，少贴输出，示例文件用 title；
6. CLI：句尾不加句号、颜色不承载信息、NO_COLOR 与 UV_NO_PROGRESS 生效、绿成功/红错误/黄警告/青提示与路径；
7. 流：数据进 stdout，日志与警告进 stderr；
8. 警告：可行动的弃用提示走 warn_user! / warn_user_once!；
9. 提示：hint: <内容>，与错误之间空一行。

这份风格指南的价值在于把"用户体验的一致性"从口头共识变成了可检查的约定：写作侧靠规范与评审，输出侧靠 uv-warnings、uv-errors、uv-logging 中的统一实现与快照测试来兜底。