命令行界面 (CLI) 工具指南

概览

命令行是工程师与 Fuchsia 及其工具、驱动程序和设备交互的主要界面。提供清晰、一致且连贯的工具对于确保所有开发 Fuchsia 的工程师和团队获得更高的工作效率和满意度至关重要。本文档提供了有关为 Fuchsia 开发和改进 CLI 工具的指导。

这些准则分为三个主要部分：

• 注意事项
• 用户体验指南
• 技术指南

注意事项

Fuchsia 和运行 Fuchsia 的设备构成了广泛的开发者平台，可满足堆栈中各个层级的用户不同的需求和要求。在开发 Fuchsia 工具和子工具时，务必要确保最终用户获得一致性、可预测的架构、可靠性以及持续的支持和维护。

不同的工具对分发范围有不同的要求。以下指南和评分准则将帮助工具开发者了解 Fuchsia CLI 工具的用户体验注意事项、技术要求和文档要求。

受众群体

Fuchsia CLI 工具由许多不同的人员和团队构建、维护和使用。对于在不同环境中工作的用户（例如树内与树外用户或 SDK 用户），通用方法并不适用。 此外，某些用户可能在特定开发领域（例如驱动程序、内核或产品配置）中拥有独特的工作流程。

在开发或更新 Fuchsia 工具时，了解目标受众群体、他们的背景信息和具体使用情形对于打造更好的开发者体验至关重要。

Fuchsia CLI 工具

确保 CLI 工具可被发现且有完善的文档，将有助于开发者更轻松地找到现有工具、了解工作流程并发现缺口。在某些情况下，扩展现有工具以添加新功能可能比创建新子工具更有帮助。例如，如果您想通过 TCP 刷写设备，最好向 ffx target flash 添加 TCP 选项，而不是创建单独的工具。

使用哪种工具？

具体使用哪种工具、脚本或库取决于您的使用情形。ffx 是一种 CLI 工具，用于与目标设备互动或开发运行 Fuchsia 的产品（例如智能显示屏）。fx 等树内工具通常是了解 Fuchsia 之外的事物（例如构建系统、代码库和集成）的脚本。

示例

• 使用 ffx 与 Fuchsia 设备互动（例如，使用 ffx target flash 在设备上刷写 Fuchsia 映像，或使用 ffx component run 与设备上的组件互动）
• 使用 fx 在树中开发 Fuchsia（例如，使用 fx set 配置 build，或使用 fx test 在宿主机上运行测试）

用于与 Fuchsia 设备互动或管理 Fuchsia 设备的 CLI 工具

• 作为 SDK 的一部分分发；也供为 Fuchsia 开发的开发者使用，包括树内开发者。
• 遵循用户体验指南，强调可发现性、一致性和稳定性
• 对文档和 --help 内容有更高的要求，以便为开发者提供支持
• 其中一些工具可供开发者直接使用，也可通过集成脚本或构建系统使用。

平台源代码树中用于 Fuchsia 开发的内置工具

• 对于在 fuchsia.git 中工作的树内开发者
• 强调工具的低门槛和快速发展，通常主要用户是工具作者
• 预计会更频繁地发生变化，可能没有详细的文档

构建系统工具和脚本（例如 cmc、fidlc）

• 完全通过命令行选项和/或响应文件进行控制。
• 强调 CLI 的稳定性，以帮助在构建系统中使用。
• 作为 SDK 的一部分分发；用户总数未知，集成未知/不可访问。
• 通常永远不会由开发者直接运行，只会作为 build 系统的一部分运行。

工具的替代方案

除了 ffx 之外，还有一些库可用于与开发主机中的 Fuchsia 目标进行交互和编写交互脚本。

• Fuchsia Controller 是一个 Python 接口，可让开发者通过 FIDL 与目标进行交互
• Lacewing 是一种基于 Fuchsia 控制器构建的主机端系统交互测试，用于编写无法完全在目标端运行的测试，例如需要重启目标的测试。

FFX 概览

ffx 是一款顶级工具，可提供与运行 Fuchsia 的设备交互的核心开发者功能。ffx 具有可扩展的接口，可将对 Fuchsia 开发者有用的其他工具注册为子工具，从而更轻松地发现这些工具。

ffx 的目标是创建一个统一的工具平台，为命令提供稳定的命令行实参界面和标准化的 JSON 输出。理想情况下，ffx 子工具将能够使用配置、日志记录、错误处理和测试框架等通用服务。这将提供一组松散耦合且可根据具体项目需求进行调整的强大工具。

ffx 子工具生命周期

在开发、更新或废弃 ffx 子工具之前，需要考虑以下几点。此工具适合哪些人？它将仅在 SDK 中提供，还是仅在树内提供？是否已存在类似的工具？

构建新工具时，请使用以下提示作为指南。您还可以参考 CLI 工具开发评分准则来确定您的工具是否满足 Fuchsia 要求。

用户体验注意事项

该工具的目标用户是谁？他们将如何使用该工具？

• 该工具在现有命令结构中处于什么位置？

人类用户和脚本/其他工具是否都能同样出色地使用该工具？

• 是否明确定义了工具的哪些部分适用于机器和自动化工作流？
• 机器接口是否有完备的文档？

命令界面是否符合 Fuchsia 指南和最佳实践？

• 该工具是否遵循用户体验指南？
• 该工具是否为用户提供了符合 CLI 帮助要求的可靠文档和帮助？
• 该工具是否提供清晰实用的错误消息？
• 您是否考虑过无障碍功能？

是否有其他用户测试过该工具？

• 请团队以外的人员运行命令并查看输出，以确定它们是否可用。

技术要求

该工具是否已编译，并且独立于运行时环境？

• 该工具是否会最大限度地减少运行时链接依赖项？
• 该工具是否基于 fuchsia.git 源代码树构建？

该工具是否支持机器接口？

• 是否有关于机器接口的全面文档？
• 该工具是否包含用于机器输入的清单文件或 JSON 文件？

该工具的兼容性保证是什么？

该工具是否会收集指标？

• 是否符合收集指标的隐私权要求？

产品管理

您将如何分发该工具？

• 它是否仅在树内提供，还是会包含在 SDK 中？

谁将负责维护该工具？

• 是否有计划更新、改进或弃用该工具？

用户可以在哪里找到常见问题的解答或提出新问题？

您如何跟踪用户报告的问题？

• 帮助输出和错误输出是否包含 bug 链接？

哪些事件已实现插桩？在哪里可以找到此工具的指标？

CLI 工具开发评分标准

键

1. 需要大幅改进
2. 需要改进
3. 满足最低要求
4. 超出了我的预期
5. 极好

用户体验指南

提供清晰、一致且连贯的工具对于确保所有开发 Fuchsia 的工程师和团队获得更高的工作效率和满意度至关重要。这些用户体验指南旨在帮助构建和集成 CLI 工具的人员为用户打造一致的开发者体验。这些指南使用 Fuchsia 的主要开发者工具 ffx 来演示最佳实践。

设计原则

始终力求使 ffx 界面尽可能简单。

• 以用户为先：考虑所有潜在用户的需求：工具用户、工具集成者、工具构建者和工具平台构建者。
• 清晰明了：确保工具的用途、使用方式和反馈易于理解。提供实用且可操作的错误消息和帮助文本。
• 保持一致性：保持输入/输出模式、语言和 Fuchsia 核心概念的一致性。
• 采用整体方法：确保工具能够独立运行，也能与其他工具集成，并在各种情境中保持一致的行为。
• 打造高效工具：设计性能出色且响应迅速的工具，最大限度地减少延迟，并实现快速迭代周期。
• 优先考虑无障碍功能：使用通俗易懂的语言，并遵循 CLI 的无障碍功能指南，确保不同能力的用户都能轻松使用。
• 提前规划：力求实现灵活性、可扩展性和可伸缩性，以满足未来的需求和增长。

ffx 用户选区

• 工具用户：直接使用 ffx 工具进行 Fuchsia 工作流（平台或产品）的用户
• 工具集成者：通过将 ffx 工具与其他工具集成或在特定环境中使用 ffx 工具。这包括编写封装 ffx 功能的新高级别工具。
• 工具构建者：创作和维护由 ffx 托管的一个或多个工具
• 工具平台构建者：发展并维护用于运行 ffx 工具的底层工具平台

命令结构

ffx 命令以树状结构位于根 ffx 命令下。这支持分层组织，可简化用户体验：用户无需遍历工具列表，而是可以遍历命令树，从而消除与所需功能无关的路径。

ffx 命令树上的路径应遵循名词 名词…动词结构。命令路径由内部节点（名词，特指程度不断提高）组成，最终到达叶节点（动词，即实际命令）。

例如，在 ffx component run <URL> 中，有一个根命令名词 (ffx)、一个子工具名词 (component)、一个子命令动词 (run) 和一个实参 (网址)，该实参是命令执行时传递给命令的值。

ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm

命令结构设计注意事项

在开发新的 CLI 工具时，请务必考虑整个平台上的开发者体验。确保工具下的命令数量合理有序。避免重复操作，或向工具添加无关的命令。在帮助和文档中合理组织命令。

一般来说，对于涵盖常见工作流（例如主机到目标平台的互动、系统集成和发布）的工具，最好扩展现有工具，而不是创建新的独立工具。添加标志、选项或子命令，以利用共享代码和功能。

不过，如果启用的总体工作流不存在，请考虑使用新命令或更高级别的子分组。查看现有的命令界面参考文档，了解新命令或工具可能适合的位置。

受众群体

工具可用于不同的开发任务。在大型团队中，这些角色可能由不同的人员担任。考虑哪些用户可能会使用该工具，并根据受众群体调整工具。

示例

• 组件开发
• 驱动程序开发
• Fuchsia 开发 (SDK)
• 构建集成（GN 等）
• 系统集成商（例如，设备端网络工具）
• 发布（从开发主机到服务器）
• 部署（从服务器到客户）

工具可能对集成有不同的预期。例如，进行组件开发的开发者可能希望工具能与集成开发环境 (IDE) 集成，而 build 集成工具可能会从脚本中调用。

将相关命令分组

与 Fuchsia 工作流相关的命令应归入一个通用工具下。例如，ffx 分为与高级别 Fuchsia 子系统对应的子工具和命令组。这有助于引导团队采用共享工作流程，并提供单一的发现点。

范围

命令行工具的范围可能会因用户需求和目标而异。请创建符合其用途的人体工学工具。有时，一个简单的单用途工具可能有助于自动执行耗时的流程。功能更丰富的大型工具应涵盖用户（开发者）级别的整个任务。

示例

• 避免制作仅能完成任务中的一个小步骤的工具；而应设计能够完成整个任务的工具。
  • 例如，在开发 C++ 应用时：运行预处理器、运行编译器、运行链接器、启动构建的可执行文件。
• 最好选择默认情况下可完成所有必需步骤的工具，但允许高级用户执行部分步骤。
  • 例如，传递一个实参，让 C++ 编译器仅运行预处理器。

FFX 子工具设计注意事项

ffx 子工具（之前称为插件）分为与高级 Fuchsia 子系统对应的命令组。在 ffx target 中，ffx 是根命令，target 是子工具（子命令）。ffx 子工具可能具有自己的实参和选项（例如 ffx target list --format [format] [nodename]）。

ffx CLI 应遵循标准结构和词汇，以便用户将 ffx 视为一个整体，而不是一组单独的工具。 熟悉一种 ffx 工具的用户应该能够预测和理解另一种工具中的命令名称。

在设计 ffx 子工具时，需要在复杂性和简洁性之间进行权衡。一般来说，ffx 子工具应映射到有文档记录的 Fuchsia 概念或子系统（例如 target, package, bluetooth）。如果可能，子工具命令组应仅限于主要功能或能力，并以标志的形式添加其他选项。不建议添加辅助命令组，但有时不可避免。清晰比简洁更重要。

命名

对于 ffx 命令（也称为 ffx 子工具），请使用广为人知的美国英语名词。子命令应为祈使动词。

• 知名名词是指在文档中作为 Fuchsia 概念或子系统的常用名称出现的名词。如需查看当前 ffx 命令的列表，请参阅 ffx 参考文档。
• FFX 子工具名称应至少包含 3 个字符。（例如，ffx bluetooth，而非 ffx bt）
• 命令和选项应始终使用小写字母 (a-z)
• 子工具名称不应包含连字符。如果需要，选项（标志）可以使用单连字符分隔字词（例如 --log-level）。

结构

遵循“名词-名词-动词”结构。将相关命令嵌套为父工具下的子命令。

请勿创建名称中包含连字符的工具，例如 add-foo 和 remove-foo。 请改为创建接受 add 和 remove 子命令的 foo 命令。

操作

使用清晰简洁且能准确反映命令操作的动词。

优先使用子命令，而不是使用连字符分隔的多个工具（例如，避免使用 foo-start, foo-stop, foo-reset；而是使用接受命令 start|stop|reset 的 foo）

一致性

与既定的 Fuchsia 术语和模式保持一致，以尽量降低认知负荷。使用常见的动词搭配（例如 start/stop, add/remove, import/export），并遵循现有的 ffx 命令模式。

简短

力求使用最短的命令和选项名称，同时不牺牲清晰度或可发现性。命令名称的长度应至少为 3 个字符。

避免使用定义不明确的首字母缩写词或缩写词（例如，bt 在不同的 Google 产品中可能表示蓝牙、Bigtable 或英国电信）。

命令行参数

实参是指在执行命令时传递给命令的值。 ffx 中的实参可以是确切的文本、有序实参（也称为位置实参）或无序选项（也称为标志）。

选项

选项（也称为标志）是无序的，可以出现在定义它们的组或命令中的任何位置，包括最后。请参阅顶级 ffx 选项。

• 选项应至少包含 3 个字符，并且应可供用户阅读
• 如果需要，选项可以使用单连字符分隔字词。在包含多个字词的选项名称中，使用单个短划线分隔字词（例如 --log-level）
• 在选项前添加双连字符 (--)。单连字符 (-) 可用于单字符选项，但应谨慎使用短标志，以免造成歧义。请参阅有关简短别名的指南

请勿使用大写字母表示选项。请勿使用数字选项。如果需要数值，请创建键控选项，例如 --repeat <number>。

开关

如果存在开关，则表示其所代表的功能处于“开启”状态；如果不存在开关，则表示该功能处于“关闭”状态。开关默认处于“关闭”状态。

• 所有开关都必须记录在案（不允许使用隐藏开关）
• 与键控选项不同，开关不接受值。例如，-v 是一个常见的开关，表示详细模式；它不接受值。

使用开关来改进工具的功能。与功能标志相比，开关更容易控制。

不允许同时运行多个开关，例如 -xzf 或 -vv，每个开关都必须单独运行：-x -z -f 或 -v -v。

短别名

一般来说，用户体验团队建议避免使用短标志。不过，我们也认识到，专家使用一些常用选项的简短别名可能会很有帮助。过度使用短别名可能会造成混淆和歧义（例如，-b 是指 --bootloader、--product-bundle 还是 --build-dir？）。应谨慎使用短别名。

• 并非每个选项都需要别名。如有疑问，请明确说明。
• 具有严重不可逆后果的命令应具有较长的名称，以免因排字错误而调用这些命令
• 只能使用小写字母；不得使用数字

应在整个 ffx CLI 中以一致的方式使用简短别名（例如，-c 不应在主 ffx 工具中是 --config 的简写，在某个子工具中是 --command 的简写，而在另一个子工具中是 --font-color 的简写）。

位置实参

位置实参或有序实参必须显示在命令名称之后，并按其显示顺序进行标识。仅对顺序对于理解至关重要的参数（例如 copy <source> <destination>）使用有序实参。一般而言，应避免使用位置实参，而应优先使用带有特定选项的确切文本实参。

帮助输出

可通过 --help 访问的 CLI 帮助文本是用户的重要通信工具。它应清晰简洁，可让用户一目了然地获取必要信息，并提供深入了解相关文档的途径。如需了解更多详情和示例，请参阅 CLI 工具帮助要求。

写作帮助文本

终端是一个极简的文本环境。提供的信息过多可能会导致用户难以在当下获得所需帮助。帮助输出应标准化，以便为用户提供可据以采取行动的指导，并在需要时提供清晰的途径来查找更多信息。

必需元素

• 说明 - 工具的功能和用途摘要，包括有关使用情况的关键信息。
• 用法 - 清晰概述了如何使用该命令，包括语法和实参，使用 < > 表示必需元素，使用 [ ] 表示可选元素。
• 选项 - 所有选项、其效果和默认值的详细细分
• 子命令 - 所有可用子命令的列表和摘要

推荐的元素

• 备注 - 重要详细信息和提醒
• 示例 - 有关如何使用该工具的示例
• 错误代码 - 工具专用错误及其含义列表

格式设置帮助文本

帮助文本应采用清晰的结构和样式，以实现最佳可读性，包括一致的缩进和 80 个字符的自动换行。文本应使用清晰且语法正确的美国英语撰写，并遵循 Fuchsia 的文档标准。

错误消息

当出现未按预期运行的情况时，错误会向开发者提供关键信息。错误消息和警告可帮助开发者准确了解系统或工具的运作方式及其预期用途。Fuchsia 错误消息应能帮助具有一定技术水平的用户快速轻松地理解和解决问题。

这些准则适用于作为 Fuchsia 平台一部分创建的错误。由 Fuchsia 之外的特定运行时或语言创建的错误可能不遵循这些准则。

写作错误

• 说明问题 - 确定出了什么问题、问题发生的原因以及在哪里可以解决问题。
• 帮助用户解决问题 - 提供清晰、合理且切实可行的解决方案。提供链接以获取更多帮助。
• 面向人类撰写内容 - 避免使用行话，保持积极的语气，并确保内容简洁明了且前后一致。

确定原因并建议解决方案

用户应确切了解哪里出了问题，以及问题的原因。错误消息应提供解决方案、后续步骤，或说明如何更正特定错误。

包含短链接

使用短链接将用户重定向到正确的文档，并通过进一步说明问题来协助进行问题排查。请按照这些准则创建短链接。

州要求

指明是否未满足特定限制或前提条件。用户应了解错误是因输入验证（例如，找不到文件）、处理（例如，文件中的语法错误）还是其他意外原因（例如，文件损坏、无法从磁盘读取）而发生。

内容要具体

如果错误涉及用户可以修改的值（文本、设置、命令行参数等），则错误消息应指明有问题的这些值。这样可以更轻松地调试问题。不过，对于非常长的值，应仅逐步披露或截断。

使用一致的术语和结构

日志数据可帮助用户详细了解错误发生的方式和原因。使用规范名称、类别和值，并在文档中添加清晰的说明，以便轻松参考错误。

建议：创建错误代码目录

除了消息之外，还包含唯一标识符或标准化错误代码，有助于用户轻松识别错误，并在错误索引或错误目录中找到更多信息。例如，FIDL 中的错误代码始终以“fi-”前缀开头，后跟一个四位数的代码，例如“fi-0123”。

• 请参阅示例：FIDL 编译器错误目录

技术指南

为了在 Fuchsia 中提供一致的开发者体验，CLI 工具应使用标准库、一致的配置、通用日志记录和错误处理，并持续为用户提供支持。

编程语言

Fuchsia CLI 工具可以使用 C++、Rust 和 Go 编写。工具必须经过编译，并且独立于运行时环境。不支持 Bash、Python、Perl 和 JavaScript 等编程语言。

运行时链接依赖项

为了更轻松地分发和维护已编译的工具，请尽量减少运行时链接依赖项。建议改为静态链接依赖项。在 Linux 上，可以接受在运行时链接到 glibc 库套件（libm 等）；不允许其他运行时链接依赖项。

通过源代码构建

Fuchsia 工具应从 fuchsia.git 源代码树构建。使用与平台源代码树中的代码相同的 build 和依赖项结构。不要单独构建工具构建系统。

指标

指标对于提升质量和制定业务决策至关重要。必须仔细选择所收集指标的类型和内容。

可使用指标回答的问题

• 我们的用户使用哪些操作系统？- 确定各个平台工作的优先级
• 他们使用的是哪些工具？- 确定投资重点，并了解当前正在使用的工作流程，以便确定投资重点或发现薄弱环节
• 他们使用工具的频率如何？- 这样我们就能知道如何确定投资的优先顺序，并了解目前正在使用哪些工作流程，以便确定投资的优先顺序或找出薄弱环节
• 我们的工具是否会在实际使用中崩溃？频率如何？- 这样我们就能知道如何优先维护工具
• 他们如何使用工具？- 假设某个工具可以执行一项或多项操作，我们希望了解如何优先投资于该工具的特定工作流程

配置和环境

工具通常需要了解其运行的环境和上下文。本部分提供了有关如何收集和/或存储这些信息的指南。

如何阅读

工具不应尝试直接从其运行的环境中收集或读取设置或状态文件。应从独立于平台的来源收集附加目标设备的 IP 地址、build 产品的输出目录或用于写入临时文件的目录等信息。分离执行平台特定工作的代码将使工具能够在不同的平台之间保持可移植性。

在切实可行的情况下，配置信息应以宿主机用户熟悉的方式存储（例如，在 Windows 上，使用注册表）。工具应从 SDK 文件或封装了从 Windows 注册表或 Linux 环境读取工作的平台专用工具中收集信息。

工具应不偏向任何构建系统或环境。允许访问通用文件（例如 build 输入依赖项文件）。

撰写信息

工具不应修改配置或环境设置，除非该工具明确设计用于修改环境的预期部分。

如果修改工具正常范围之外的环境可能有助于用户，则该工具可以在征得用户明确许可的情况下进行修改。

测试

在 SDK 中分发或包含在构建系统中的工具必须包含可保证正确行为的测试。每种工具都包含单元测试和集成测试。测试将在 Fuchsia 持续集成中运行。

文档

所有 Fuchsia 工具都需要提供有关如何使用该工具的文档和问题排查指南。标准 --help 输出必须包含：

• 说明：对工具的功能和用途的总结，包括有关使用情况的关键信息。
• 用法：清晰概述了如何使用该命令，包括语法和实参，使用 <> 表示必需的元素，使用 [ ] 表示可选的元素。
• 选项：所有选项、其效果和默认值的详细细分数据
• 子命令：所有可用子命令的列表和摘要

应在 fuchsia.dev 上以 Markdown 格式记录更详细的用法示例和说明。

用户互动与程序化互动

工具可由人工用户以交互方式运行，也可通过脚本（或其他工具）以编程方式运行。

虽然每个工具在可以确定首选模式时都会默认采用互动模式或非互动模式，但它还必须接受以指定模式运行的明确指令（例如，即使工具在互动式 shell 中运行，也允许用户执行编程接口）。

Stdin

对于通常不进行交互的工具，请避免请求用户输入（例如，readline 或 linenoise）。不要添加意外的提示来询问用户问题。

对于交互式工具（例如 zxdb），提示用户输入是预期行为。

Stdout

通过标准输出向用户发送输出时，请使用正确的拼写和语法。 避免使用不常见的缩写。如果使用了不常见的缩写或术语，请务必确保术语表中包含相应条目。

stderr

使用 stderr 报告无效操作（诊断输出），即工具行为异常时。如果工具的目的是报告问题（例如，当工具未失败时，linter），请将这些结果输出到 stdout 而不是 stderr。

退出代码

退出代码 0 始终被视为“无错误”，而退出代码 1 始终被视为“一般错误”。请勿依赖于特定的非零值。使用机器输出返回特定错误代码和消息。如需查看示例，请参阅 FIDL 错误目录。

• 对于成功，返回退出代码 0
• 对于失败，返回非零退出代码

避免在成功时生成不必要的输出，除非输出包含用户完成工作流程中下一步所需的特定关键信息（例如文件路径）。除非用户要求提供详细输出，否则不要输出“成功”。

日志记录

日志记录与正常输出不同，通常配置为重定向到文件，或应写入 stderr。日志记录的受众群体通常是工具开发者或尝试调试问题的用户。

• 来自多个线程的日志记录不会在同一行中交织字词。输出的最小单位是完整的一行文本。
• 每行都会添加严重程度指示前缀：detail, info, warning, error, fatal

自动化

在合理的情况下，包含可实现自动化的程序化接口。如果该网域已有协议，请尽量遵循该协议（或有充分的理由不遵循）。MachineWriter (--machine) 可用于支持 JSON 格式的结构化输出。

样式指南

为了在整个 Fuchsia 中提供一致的开发者体验，CLI 工具应遵循现有的编程语言和 Fuchsia 文档样式指南。例如，如果该工具随 Zircon 一起提供，并且是用 C++ 编写的，请使用 Zircon 中的 C++ 样式指南。避免为 CLI 工具创建单独的风格指南。

所有 CLI 工具、输出和文档都应遵循 Fuchsia 的尊重性代码政策中规定的准则。详细了解 Fuchsia 的文档标准。

文件路径中的大小写区分

请勿依赖文件路径中的大小写区分。不同平台对大写和小写的处理方式不同。Windows 不区分大小写，而 Linux 区分大小写。明确指定具体的文件名。不要认为 src/BUILD 和 src/build 是不同的文件。

颜色

您可以在命令行界面中使用 ANSI 颜色，使文本更易于阅读或突出显示重要信息。使用颜色时，请务必使用对于可能无法看到全色范围的读者（例如色盲）而言清晰可辨的颜色

• 使用标准 8/16 色，与 256 色相比，用户更容易重新映射这些颜色
• 尽可能检查终端是否支持彩色，如果不支持，则禁止输出彩色。
• 始终允许用户手动禁止输出颜色，例如使用 --no-color 标志和/或通过设置 NO_COLOR 环境变量 (no-color.org)

切勿单纯依靠颜色来传达信息。仅使用颜色来增强效果。必须看到颜色才能正确解读输出内容。详细了解 Fuchsia 上的无障碍功能。

ASCII 艺术

所有 Fuchsia 工具都应使用标准输出格式，以确保外观和风格一致。请勿使用 ASCII 图形来设置表格格式或以其他方式增强输出效果。 ASCII 图案可能会使界面难以阅读，并且不兼容屏幕阅读器，因此无法实现无障碍功能。