指令列介面 (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 設定建構作業，或使用 fx test 在主體機器上執行測試)

與 Fuchsia 裝置互動或管理 Fuchsia 裝置的 CLI 工具

• 以 SDK 的形式發布，開發人員 (包括樹狀結構內開發人員) 為 Fuchsia 開發時也會使用。
• 遵循 UX 指南，強調可探索性、一致性和穩定性
• 對說明文件和 --help 內容有更高的期望，以支援開發人員
• 開發人員可直接使用部分工具，也可以透過整合指令碼或建構系統使用。

平台來源樹狀結構中的 Fuchsia 開發樹狀結構內工具

• 適用於在 fuchsia.git 中工作的樹狀結構內開發人員
• 強調工具的進入門檻低，且可快速演進，通常工具作者就是主要使用者
• 預計會更常變更，可能沒有詳細文件

建構系統工具和指令碼 (例如 cmc、fidlc)

• 只能透過指令列選項和/或回應檔案控制。
• 強調 CLI 的穩定性，協助在建構系統中使用。
• 以 SDK 的形式發布；使用者總數不明，且整合項目不明/無法存取。
• 通常不會由開發人員直接執行，只會做為建構系統的一部分執行。

工具替代方案

除了 ffx 之外，還有一些程式庫可與開發主機的 Fuchsia 目標互動，並編寫互動指令碼。

• Fuchsia 控制器 是 Python 介面，可讓開發人員透過 FIDL 與目標互動
• Lacewing 是以 Fuchsia Controller 為基礎建構的主機端系統互動測試，適用於無法純粹在目標端執行的指令碼測試，例如需要重新啟動目標的測試。

FFX 總覽

ffx 是頂層工具，可提供核心開發人員功能，用於與執行 Fuchsia 的裝置互動。ffx 具有可擴充的介面，可讓其他對 Fuchsia 開發人員有用的工具註冊為子工具，方便探索這些工具。

ffx 的目標是建立一致的工具平台，為指令提供穩定的指令列引數介面，以及標準化的 JSON 輸出。理想情況下，ffx 子工具應能使用常見服務，例如設定、記錄、錯誤處理和測試架構。這會提供一系列鬆散耦合的強大工具，可因應特定專案需求調整。

ffx 子工具生命週期

開發、更新或淘汰 ffx 子工具前，請先考量下列事項。這項工具的適用對象為何？是否只會提供 SDK 或樹狀結構內版本？是否已有類似工具？

建立新工具時，請參考下列提示。您也可以參閱 CLI 工具開發評量標準，判斷工具是否符合 Fuchsia 需求。

使用者體驗注意事項

這項工具的目標使用者是誰？他們會如何使用？

• 這個工具在現有的指令結構中扮演什麼角色？

人類使用者和指令碼/其他工具是否都能順利使用這項工具？

• 是否清楚定義工具的哪些部分適用於機器和自動化工作流程？
• 機器介面是否已妥善記錄？

指令介面是否符合 Fuchsia 指南和最佳做法？

• 工具是否遵循使用者體驗指南？
• 工具是否提供完善的說明文件和使用者說明，符合 CLI 說明需求？
• 工具是否提供清楚實用的錯誤訊息？
• 您是否考慮過無障礙設計？

是否有其他使用者測試過這項工具？

• 請團隊以外的人員執行指令並查看輸出內容，確認是否可用。

技術相關規定

工具是否已編譯，且與執行階段環境無關？

• 工具是否會盡量減少執行階段連結依附元件？
• 該工具是否從 fuchsia.git 來源樹狀結構建構？

這項工具是否支援機器介面？

• 是否有機器介面的完整說明文件？
• 這項工具是否包含機器輸入的資訊清單或 JSON 檔案？

這項工具提供哪些相容性保證？

工具是否會收集指標？

• 是否符合收集指標的隱私權規定？

產品管理

您要如何發布工具？

• 是否只會提供樹狀結構內版本，還是會納入 SDK？

誰會負責維護這項工具？

• 是否有更新、演進或淘汰這項工具的計畫？

使用者可以在哪裡找到常見問題的解答或提出新問題？

您如何追蹤使用者回報的問題？

• 說明輸出內容和錯誤輸出內容是否包含錯誤連結？

已導入哪些事件？可以在哪裡找到這項工具的指標？

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)、子工具名詞 (元件)、子指令動詞 (run) 和引數 (URL)，這是執行指令時傳遞的值。

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) 整合，而建構整合工具可能會從指令碼呼叫。

將相關指令歸到同一組

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 子工具名稱應為三個字元以上。(例如 ffx bluetooth，而非 ffx bt)
• 指令和選項一律應使用小寫英文字母 (a-z)
• 子工具名稱不得包含連字號。如有必要，選項 (旗標) 可使用單一連字號分隔字詞 (例如 --log-level)。

結構

請遵循「名詞-名詞-動詞」結構。Nest 相關指令會以子指令的形式，歸類在父項工具底下。

請勿建立名稱含連字號的工具，例如 add-foo 和 remove-foo。 請改為建立可接受 add 和 remove 子指令的 foo 指令。

動作

使用簡潔扼要的動詞，準確反映指令的動作。

請優先使用子指令，而非連字號分隔的多個工具 (例如，請避免使用 foo-start, foo-stop, foo-reset，改用可接受指令的 foostart|stop|reset)。

一致性

請使用既有的 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。

簡短別名

一般來說，UX 建議避免使用短旗標。不過，我們也瞭解專家可能會想為某些常用選項使用簡短別名。過度使用簡短別名可能會造成混淆和模稜兩可 (例如，-b 是指 --bootloader、--product-bundle 還是 --build-dir？)。簡短別名應盡量少用。

• 每個選項不一定需要別名。如有疑慮，請明確指出。
• 如果指令會造成嚴重且無法復原的後果，就應該使用較長的名稱，以免因打字錯誤而叫用指令
• 只能使用小寫英文字母，不得使用數字

在整個 ffx CLI 中，應以一致的方式使用簡短別名 (例如，主要 ffx 工具中的 -c 不應是 --config 的簡寫，在一個子工具中是 --command，在另一個子工具中則是 --font-color)。

位置引數

位置或排序引數必須顯示在指令名稱後方，並依顯示順序識別。只有在順序對瞭解參數至關重要時 (例如 copy <source> <destination>)，才使用排序引數。一般來說，請避免使用位置引數，並偏好使用含有特定選項的確切文字引數。

說明輸出

使用者可透過 --help 存取 CLI 說明文字，這是重要的溝通工具。內容應簡明扼要，提供一目瞭然的重要資訊，並在需要時提供更深入的說明文件路徑。如需更多詳細資料和範例，請參閱 CLI 工具說明需求。

寫作輔助文字

終端機是極簡的文字環境。提供過多資訊可能會讓使用者難以在當下取得所需協助。建議將輸出內容標準化，為使用者提供可執行的指引，並在需要時提供清楚的路徑，方便使用者尋找更多資訊。

必要元素

• 說明 - 工具功能和用途的摘要，包括使用方式的重要資訊。
• 用法 - 清楚列出指令的使用方式，包括語法和引數，並使用 < > 表示必要元素，[ ] 表示選用元素。
• 選項 - 所有選項的詳細細目、效果和預設值
• 子指令 - 所有可用子指令的清單和摘要

建議元素

• 附註 - 重要詳細資料和提醒事項
• 範例 - 說明如何使用這項工具的範例
• 錯誤代碼 - 工具專屬錯誤及其含義清單

格式設定說明文字

為確保可讀性，說明文字應採用清楚的結構和樣式，包括一致的縮排和每行 80 個半形字元的換行。文字應以文法正確的美國英語撰寫，並遵循 Fuchsia 的文件標準。

錯誤訊息

如果發生非預期情況，錯誤會提供重要資訊給開發人員。錯誤訊息和警告可讓開發人員瞭解系統或工具的運作方式和預期用途，Fuchsia 錯誤訊息應協助具備基本技術知識的使用者快速輕鬆地瞭解並解決問題。

這些規範適用於 Fuchsia 平台建立的錯誤。Fuchsia 以外的特定執行階段或語言所建立的錯誤，可能不符合這些規範。

寫作錯誤

• 說明問題：找出錯誤、發生原因和修正位置。
• 協助使用者修正問題：提供清楚、合理且可行的解決方案。提供連結，取得進一步協助。
• 為人類撰寫內容：避免使用專業術語、保持正面語氣，並簡潔一致。

找出原因並建議解決方案

使用者應確切瞭解發生錯誤的原因和位置。錯誤訊息應提供解決方案、後續步驟，或說明如何修正特定錯誤。

包含短連結

使用短連結將使用者重新導向至正確的說明文件，並進一步說明問題，協助排解疑難。請按照這些規範建立短連結。

州/省相關規定

指出是否不符合特定限制或先決條件。使用者應瞭解錯誤是否因輸入驗證 (例如找不到檔案)、處理 (例如檔案中有語法錯誤) 或其他非預期原因 (例如檔案損毀、無法從磁碟讀取) 而發生。

提供清楚明確的說明

如果錯誤涉及使用者可修改的值 (文字、設定、指令列參數等)，錯誤訊息應指出違規值。這樣就能更輕鬆地偵錯問題。不過，如果值很長，建議逐步揭露或截斷。

使用一致的字詞和結構

記錄資料可協助使用者進一步瞭解錯誤發生方式和原因。使用標準名稱、類別和值，並在文件中加入清楚的說明，方便參照錯誤。

建議：建立錯誤碼目錄

除了訊息外，加入專屬 ID 或標準化錯誤代碼，有助於使用者輕鬆識別錯誤，並在錯誤索引或錯誤目錄中找到更多資訊。舉例來說，FIDL 中的錯誤代碼一律會以 fi- 前置字串加上四位數代碼呈現，例如 fi-0123。

• 請參閱範例：FIDL 編譯器錯誤目錄

技術規範

為在 Fuchsia 中提供一致的開發人員體驗，CLI 工具應使用標準程式庫、一致的設定、常見的記錄和錯誤處理方式，並持續為使用者提供支援。

程式語言

Fuchsia CLI 工具可以 C++、Rust 和 Go 編寫，且必須經過編譯，並獨立於執行階段環境。不支援 Bash、Python、Perl 和 JavaScript 等程式設計語言。

執行階段連結依附元件

為方便發布及維護已編譯的工具，請盡量減少執行階段連結依附元件。建議改為靜態連結依附元件。在 Linux 上，可以針對 glibc 程式庫套件 (libm 等) 進行執行階段連結，但不允許其他執行階段連結依附元件。

從來源建構

Fuchsia 工具應從 fuchsia.git 來源樹狀結構建構。請使用與平台來源樹狀結構中程式碼相同的建構和依附元件結構。請勿建立獨立系統來建構工具。

指標

指標對於提升品質和做出業務決策至關重要。請謹慎選擇要收集的指標類型和內容。

可透過指標回答的問題

• 使用者使用哪些作業系統？- 優先處理各種平台的工作
• 他們使用哪些工具？- 決定投資優先順序，並瞭解目前使用的工作流程，以便決定投資優先順序或找出弱點
• 他們使用工具的頻率為何？- 讓我們瞭解如何優先投資，以及目前使用的流程，以便優先投資或找出弱點
• 我們的工具是否會在實際環境中當機？頻率多高？- 讓我們瞭解如何優先維護工具
• 如何使用工具？- 假設工具可以執行一或多項作業，我們想瞭解如何優先投資工具的特定工作流程

設定和環境

工具通常需要瞭解執行環境和背景資訊。本節提供相關指南，說明如何收集及/或儲存這類資訊。

閱讀資訊

工具不應嘗試直接從執行環境中收集或讀取設定或狀態檔案。應從與平台無關的來源收集資訊，例如附加目標的 IP 位址、建構產品的輸出目錄，或是用於寫入暫存檔案的目錄。將執行平台專屬工作的程式碼分開，可讓工具在不同平台之間保持可攜性。

在實務上，設定資訊應以主機使用者熟悉的方式儲存 (例如在 Windows 上使用登錄)。工具應從 SDK 檔案或平台專屬工具收集資訊，這些工具會封裝從 Windows 登錄檔或 Linux 環境讀取資料的工作。

工具不應偏向任何建構系統或環境。允許存取常見檔案，例如建構輸入依附元件檔案。

撰寫資訊

工具不得修改設定或環境設定，除非工具明確設計用於修改環境的預期部分。

如果修改工具正常範圍外的環境有助於使用者，工具可能會在取得使用者明確許可後進行修改。

測試

SDK 中發布或建構系統內含的工具，必須包含可確保行為正確的測試。每項工具都包含單元測試和整合測試。測試會在 Fuchsia 持續整合中執行。

說明文件

所有 Fuchsia 工具都必須提供工具使用說明文件和疑難排解指南。標準 --help 輸出內容必須包含：

• 說明：工具功能和用途的摘要，包括使用方式的重要資訊。
• 用法：清楚說明如何使用指令，包括語法和引數，並使用 <> 表示必要元素，[ ] 表示選用元素。
• 選項：所有選項的詳細細目、效果和預設值
• 子指令：所有可用子指令的清單和摘要

更詳細的使用範例和說明應記錄在 fuchsia.dev 的 Markdown 中。

使用者與程式輔助互動

工具可由使用者以互動方式執行，或透過指令碼 (或其他工具) 以程式輔助方式執行。

如果工具可以判斷偏好的模式，預設會採用互動或非互動模式，但工具也必須接受明確指令，以特定模式執行 (例如，即使工具在互動式殼層中執行，也允許使用者執行程式設計介面)。

Stdin

對於通常不會互動的工具，請避免要求使用者輸入內容 (例如 readline 或 linenoise)。請勿新增非預期的提示，要求使用者回答問題。

如果是互動式工具 (例如 zxdb)，提示使用者輸入內容是預期行為。

Stdout

透過 stdout 將輸出內容傳送給使用者時，請使用正確的拼字和文法， 並避免使用不常見的縮寫。如果使用不常見的縮寫或字詞，請務必在專有名詞詞彙表中加入該字詞。

Stderr

使用 stderr 回報無效作業 (診斷輸出)，也就是工具行為異常時。如果工具的用途是回報問題 (例如 Linter，工具不會失敗)，請將結果輸出至 stdout，而非 stderr。

結束代碼

系統一律將結束代碼 0 視為「無錯誤」，結束代碼 1 則一律為「一般錯誤」。請勿依賴特定非零值。使用機器輸出內容傳回特定錯誤代碼和訊息。如需範例，請參閱 FIDL 錯誤目錄。

• 如要表示成功，請傳回結束代碼零
• 如果失敗，請傳回非零的結束代碼

除非輸出內容包含使用者完成工作流程下一個步驟的特定重要資訊 (例如檔案路徑)，否則請避免在成功時產生不必要的輸出內容。除非使用者要求詳細輸出內容，否則請勿列印「成功」。

記錄

記錄檔與一般輸出內容不同，通常會設定為重新導向至檔案，或應寫入 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 藝術會導致介面難以閱讀，且不相容於無障礙功能的螢幕閱讀器。