開始使用

安裝 fx，連接團隊 manifest，並管理儲存庫、工具與編碼 Agent。

各版本的變更見更新日誌。請查看已安裝版本的 fx <command> --help 與隨附 Skill，確認目前執行檔支援的功能。

依任務選擇閱讀入口：

• 新建工作區：安裝，再快速上手。
• 還沒有 manifest：設定配套 CLI。
• 保持最新：更新工具和 Skill。
• 儲存庫較多：下載前選擇儲存庫。
• 設定中斷：判讀結果並復原。
• 編碼 Agent：結構化結果與 bundled Skill。

環境需求

• Node.js ≥22；開發版本以 package.json 為準。Bun 也可以作為執行環境。
• Git 位於 PATH 中。全域安裝和 fx self update 仍需要 npm，包括使用 Bun 時。
• 工作區需要團隊提供的 manifest，或自行建立的 manifest。只設定配套 CLI 時不需要。

支援 macOS 和 Linux。原生 Windows 介接器已實作，但 Windows 實機執行和 Agent 宿主啟用尚未完成驗證；目標為本機 NTFS 上的 PowerShell 5.1/7 和 cmd。請參閱 Windows 支援範圍。

Bitbucket Git 驗證

當 bitbucket-cli git --help 可用時，fx 會使用配套 CLI 既有的登入，透過 HTTPS 完成 manifest 初始化、儲存庫複製與同步。只要伺服器允許 HTTPS Git，Data Center PAT 具有儲存庫讀取權限即可；即使 manifest 使用 SSH URL，也不需要 SSH key。位址轉換僅對本次呼叫生效，已儲存的 remote 保持不變。fx 不讀取或儲存 token；推送仍需要寫入權限。

首次複製 manifest 前，先設定配套 CLI 的服務並登入。多個帳號可透過 BITBUCKET_CONTEXT 選擇初始化使用的 context；工作區操作優先使用 manifest 宣告的 context。用 bitbucket-cli git -- ls-remote <clone-url> 驗證實際 Git 讀取。配套 CLI 缺失或版本較舊時，繼續使用一般 Git 驗證，需升級配套 CLI 才能使用此能力。憑證遭拒時會保留錯誤。單獨執行 git fetch 仍需自行設定驗證，或改用 bitbucket-cli git -- -C <dir> fetch upstream。此機制不支援遞迴子模組。

安裝

公開套件

對外分發使用 npmjs 上的 @angelmsger/fx，不需團隊私有 Registry。

npm install -g @angelmsger/fx --registry=https://registry.npmjs.org/ --@angelmsger:registry=https://registry.npmjs.org/
fx --version

也可以從原始碼執行：

npm ci
npm run build
node bin/fx.js --help
node bin/fx.js --version

執行後續範例時，將 fx 替換為 node /absolute/path/to/fx-devkit/bin/fx.js。啟動器讀取 dist/，因此必須先建置。

PowerShell 執行原則阻止 .ps1 shim 時，可使用 npm.cmd 和 fx.cmd，不必變更原則。

更新

原始碼安裝可透過 Git 更新 checkout，再執行 npm ci 和 npm run build。使用 fx self info --format json 查看目前版本與套件更新來源。請參閱更新說明。

快速上手

只需要團隊提供的 manifest 來源，以及工作區要放置的目錄。可以直接告訴 Agent：「請用 fx 根據這個 manifest，把工作區準備到這個目錄。」自行操作終端時，先預覽再執行：

fx init ./work --from <manifest-repository> --dry-run
fx init ./work --from <manifest-repository>

fx 會檢查來源，完成已授權的本機工具與設定準備，複製選取的儲存庫，並準備 Agent 指南和 Skill。工作區名稱自動產生並避開既有註冊，既有檔案與已完成工作會保留。批准新命令前，請檢查顯示的完整參數。

看到 Ready to work 即可開始工作。若需要個人登入、權限或批准，fx 會集中列出剩餘事項。處理後使用傳回的繼續命令：

fx init --resume --workspace work

終端輸出會直接列出個人登入命令和繼續命令。在自己的終端完成登入，解決所列前置條件後執行繼續命令即可。

續跑會驗證目前狀態並略過已完成準備，不會重新匯入目錄來源或重建既有儲存庫。無需自行選擇內部階段或組合診斷命令。

新工作區預設選取全部共享儲存庫。需要縮小首次下載範圍時，先選擇儲存庫，在初始預覽和執行都加上 --repos。既有目錄會自動納入管理。日常更新使用 fx sync，查看儲存庫狀態使用 fx status。

不用 manifest 設定配套 CLI

沒有團隊 manifest 時，不帶目錄執行 fx init，即可在本機設定 fx 支援的配套 CLI。它會列出這些工具並詢問需要哪些，按 Enter 選擇全部。直接寫出名稱則不再詢問：

fx init
fx init --tools bitbucket-cli,jira-cli --dry-run
fx init --tools all

fx 會安裝尚未安裝的工具，讓每個工具把自己的 Skill 與 fx 自身的 Skill 一起安裝到你的編碼 Agent 中，並檢查你是否已登入。對於尚未設定的工具，fx 會詢問是否啟動該工具自己的設定，例如 bitbucket-cli config init，它會詢問服務位址和你的憑證。如果你拒絕、傳入 --yes 或在沒有終端時執行，fx 會改為列出這些命令；執行之後再執行一次 fx init --tools <names> 即可確認。既有的工具保持原樣；更新是單獨的一步。

這樣不會註冊工作區，也不預設任何內容。有 manifest 時，fx init <dir> --from <manifest> 會決定工具，並為你填好每個服務的位址。

保持工具和 Skill 最新

fx self update --yes   # 更新 fx，再更新你已安裝的 fx Skill 副本
fx tool update --all   # 更新你已安裝的每個配套 CLI，再更新它的 Skill

fx tool update --all 只更新已經安裝的配套 CLI，不會安裝新的工具；那是 fx tool install 的事。fx 每安裝或更新一個工具，都會讓它再為你的編碼 Agent 安裝一次自己的 Skill，這樣 Agent 讀到的就是你現在這個版本的說明。fx self update 最後會讓新的 fx 更新比它舊的自身 Skill 副本，fx skill update 也可以單獨做這件事。在工作區內，同樣的命令會更新工作區使用的工具，fx sync 也會更新 Skill。

探索與管理工作區

fx workspace list 可在任意目錄執行，即使沒有預設工作區，或某項註冊的根目錄、manifest 已遺失。fx workspace show <name> 回傳身分、來源、健康狀態與選擇脈絡，不要求 manifest 完整。使用 fx status --workspace <name> 明確選擇；未指定時，目前目錄所屬工作區優先於 default_workspace。

fx workspace list
fx workspace show work
fx status --workspace work
fx config set default_workspace work

目錄已移動時，使用 workspace relocate <name> <new-dir> 更新註冊；它不會移動或重新複製 checkout。使用 workspace rebind <name> --from <source> 更換 manifest 來源，同時保留工作區身分和個人選擇。將同一實體目錄註冊為第二個名稱不等於遷移。

workspace unregister <name> 解除管理並保留業務 checkout。先使用 --dry-run 預覽生命週期操作，檢查受管資源清理與衝突；外來檔案會保留。

下載前選擇儲存庫

初始化時使用 --repos 限制首次下載，名稱必須存在於已檢查的 manifest；--no-repos 表示空儲存庫集合。重複 init 時不帶這兩個參數會保留既有選擇。

fx init ./work --from <manifest-repository> --repos example-api --dry-run
fx init ./work --from <manifest-repository> --repos example-api

既有工作區中，select 取代集合，pick 加入名稱，unpick 移除名稱。選擇操作不刪除檔案，也不會自行下載 checkout；隨後執行 sync 取得或更新已選儲存庫。

fx repo select example-api
fx repo pick example-web
fx sync --dry-run
fx sync
fx repo select --all
fx env select dev
fx env select --none
fx env select --all

僅使用明確 Git URL、未綁定程式碼託管 provider 的 manifest，同步儲存庫不需設定程式碼託管使用者名稱。

尚未下載的儲存庫仍保留在完整目錄中。可以直接讓 Agent 處理該儲存庫的任務，或執行 fx repo show <name>：傳回的 next_steps 會在正確的工作區補選儲存庫並同步下載，隨後在傳回的路徑繼續工作。

--all 持續跟隨團隊完整集合，包括未來新增項目；逐個選中目前全部名稱仍是固定清單。--none 選擇空集合。清單與選擇結果顯示目前模式，避免將空選誤認為未設定預設值。

只有這些命令會改變環境選擇。fx login 不會詢問它：未設定時涵蓋所有已宣告的環境並說明如何收窄，--env 只限定這一次執行，不改變選擇。

儲存庫選擇只控制共用項目；本機另行註冊的儲存庫和 manifest checkout 仍分別管理。select 接收以空格分隔的名稱，init 的 --repos 接收以逗號分隔的清單。

判讀儲存庫狀態

fx status 標明工作區並顯示未追蹤檔案數。fx status --dirty 同時查找已追蹤檔案的修改與新建的未追蹤檔案。JSON 保留 dirty 表示已追蹤檔案或索引修改，新增 uncommitted 表示任一類未提交工作。被忽略檔案不計入未追蹤工作。空結果說明是未選擇儲存庫，還是沒有儲存庫符合篩選。

工作區根目錄不是 Git 儲存庫，因此 fx status 還會回傳 stray_entries：根目錄下既不是 checkout、派生指南、fx 維護的 Go 工作區、Agent 或服務設定，也不是工作台的檔案與目錄。fx doctor 在 root 群組中逐項列出，等級為警告，不影響就緒判定。

sync 保留工作檔案與分支。請查看計畫動作：已追蹤檔案修改可能觸發 skip_dirty；checkout 位於其他分支時，只更新被追蹤的分支參照。空的 upstream 會被略過，因為沒有可 fast-forward 的內容；缺少被追蹤分支的 upstream 同樣會被略過，但會作為需要檢查的問題回報。如果更新會覆寫分支未追蹤的本機檔案（包括 .env 這類被忽略的檔案），sync 會保持該 checkout 不變，回報 outcome local_files_in_the_way，並在 files_in_the_way 中列出這些檔案；將它們移開後再次執行 sync。status 預設不 fetch，需要更新遠端比較時明確加上 --fetch。

在終端機裡，sync 和 init 只顯示需要關注的儲存庫或 Skill 列，成功的由狀態列計數。兩者最後都按階段各給一列結論，再按解決方式分組列出阻擋項：登入、服務拒絕的存取，或本機連不上的伺服器，後者會給出重新檢查的命令。--verbose 會顯示每一列，管道或 --format json 仍會收到全部列。

核心概念

工作區和 manifest

工作區是已註冊的普通目錄，包含獨立 checkout 和受管理的 Agent 資源。manifest 來源位於 ~/.fx/workspaces/<name>/source，fx 不會在受管理的工作區根目錄執行 Git。同步不會透過切換分支、reset 或 stash 覆蓋未提交變更、分歧狀態或其他分支上的工作。

不屬於任何儲存庫的產出放在工作區根目錄的 .workbench/ 下：每個任務一個帶日期的目錄，存放報告、計畫與證據；worktrees/ 放 git worktree add 的目標；tmp/ 放隨時可以捨棄的內容。派生指南向 Agent 說明相同的規則。fx 不會寫入該目錄。

根目錄的 AGENTS.md 是 fx 派生的唯一一份指南，各 Agent 會自行讀取。Claude Code 從 2.1.277 起也是如此，前提是工作區根目錄及其上層目錄中沒有 CLAUDE.md 或 CLAUDE.local.md。一旦存在，Claude Code 會改讀該檔案而不讀指南，因此請在其開頭寫上 @AGENTS.md。

workspace、environments、tools 和 members 文件儲存共用資訊；選用的 harness 文件描述 MCP 和規則。使用以下命令查看欄位：

fx manifest explain 'repos[].upstream'
fx manifest schema --kind tools

個人設定

全域設定記錄工作區和偏好。Agent 選擇在同一 FX_HOME 註冊的工作區間共用；儲存庫與環境選擇屬於各自工作區。repo add 登記本機參照，repo remove 僅移除參照並保留檔案。設定匯出不會複製憑證、信任記錄或 manifest checkout。

能力、提供者與配套工具

capability 表示程式碼託管、CI、日誌、錯誤追蹤等意圖，provider 透過配套 CLI 實作。manifest 繫結能力、提供者和環境座標。can 查詢就緒狀態，where 查詢座標，release check 查詢宣告的發佈檢查項目。

工作區級能力一次繫結：code-host、issue-tracker、knowledge-base、im、channel、calendar、meeting、task、worklog；環境級能力按平台實例繫結：error-tracker、log-store、metrics、ci、cluster。不帶目標的 fx can 列出這些能力以及目前工作區裡各由誰提供；fx manifest providers 列出已繫結的內容和每個能力可選的 provider。calendar 是行程與忙閒所在；meeting 是承載線上會議及其錄製、紀要的會議系統，在一個產品排行程、在另一個產品開會的團隊兩者都繫結。在企業微信上，wecom-calendar 透過 WeCom CLI 列出其機器人可見的行程，wecom-calendar-cli 則在每位成員自己行事曆的本機鏡像中連同歷史一起搜尋；登入以及用 wecom-calendar-cli sync 填充鏡像都由成員自己完成。

將工作區能力 channel 綁定到 wecom-channel-cli 即可安裝 CLI 和 Skill。就緒檢查透過代理通訊端執行 doctor。頻道監聽會排除以同一 Bot 身分發送的訊息，包括其他用戶端使用該身分發送的內容。升級 CLI 時應同時升級 broker，並依配套 CLI 的遷移指南核對舊監聽檢查點或 relay 佇列。

智慧機器人對話可在受限 worker 工作區中將 im 綁定到 wecom-chat-cli。fx can im 檢查目前任務的存取權限並傳回讀取命令，不輸出對話內容。使用 fx tool install wecom-chat-cli 安裝 CLI；套件內的 Skill 需透過隔離宿主手動安裝。參見 worker 設定。

metrics 由 prometheus-cli 提供。它的座標是服務的抓取 job：where 輸出一條 up{job="..."} 查詢，回傳該服務各抓取目標的標籤集合，可作為撰寫後續選擇器的起點。選擇器比對不到任何序列時查詢仍然成功，因此指標不提供存在性探測，where --probe 對它回報 unknown，不作猜測。

tool list/show 顯示工具需求，tool install/update 使用宣告的安裝程式，login 引導設定。驗證由各工具負責，包括已儲存的憑證可以送往哪個服務。fx 為內建工具定義的命令無需確認即可執行；團隊 tools.yaml 新增或覆寫的命令向量需要信任一次，向量改變後需要重新確認。口頭確認手動步驟不能取代驗證成功。

工具定義由內建目錄與所選工作區的 tools.yaml 合併；工作區的工具鏈則是其中它真正使用的部分：被繫結 provider 驅動的工具，加上 tools.yaml 宣告的工具。fx tool list 說明每個工具因何在此，--catalog 會再列出 fx 知道但沒有被選用的工具。工作區優先順序為 --workspace、FX_WORKSPACE、目前目錄所屬的已註冊工作區、default_workspace；無法確定工作區時沒有繫結可推導，因此列出內建目錄。套件管理器決定安裝位置，工具由多個工作區共用。

tool install 和 tool update 必須指定名稱或 --all，兩者互斥。安裝的 --all 補齊已啟用且 PATH 缺少的工具；更新的 --all 選擇目前工具表中已啟用且在 PATH 上的工具，在工作區內還會以 TOOLS_NOT_INSTALLED 通知列出被略過的工具。明確名稱可以選擇已停用的工具。無參數呼叫會在執行套件操作前報錯。套件操作之後，每個被安裝或更新的工具會為所選 Agent 安裝自己的 Skill，列中的 skill 回報結果。

doctor 預設檢查工作區宣告的工具及所選環境中實際啟用的 provider 相依項目。未使用的內建工具仍可透過 tool list --catalog 或明確指定 doctor --tool <name> 查詢；缺少它們不會導致無關工作區不健康。工具鏈本身涵蓋 manifest 宣告的所有環境（安裝是整機的），而 doctor 的檢查仍依所選環境收窄。活躍 provider 的相依工具若被停用，仍會回報檢查不完整。

init/sync 使用相同的相關工具範圍。缺少選用工具仍會顯示，但不阻斷準備。啟用的 install_on_init 工具需要驗證；已停用的選用工具不會僅因這個安裝標記而變成必要工具。

內建 Sentry 工具透過 npm 的 sentry 套件安裝；manifest 啟用初始化安裝時也適用。

共用服務設定與個人憑證

manifest 可宣告 URL、context、組織和驗證方式等公共 service 設定。init、明確執行的 sync 和 login 透過配套工具自身的命令準備設定；背景 hook 只檢查。宣告的驗證方式只是 fx 新建 context 時的預設值；你自己的 context 只要已經能存取宣告的服務，無論以哪種方式登入都算就緒。使用 fx sync --only services --dry-run 預覽。

設定與身分驗證分開進行。每位成員透過配套 CLI 取得並儲存自己的憑證。既有衝突設定會保留並回報；sync 不執行個人登入。但它每次執行都會把你在同一服務上既有的登入關聯到工作區的 context，在別處登入之後不需要再記著做什麼。Sentry 僅寫入工作區 .sentryclirc 的公共預設值，保留外來檔案。

sync 的 stages.services 和 stage_details.services.items 表示階段結果；init 將這些欄位放在 sync 下。摘要保留阻塞與失敗，--details 也包含成功項目。參閱服務預設與復原參考。

工具安裝歷史

fx tool history --format json
fx tool history bitbucket-cli --format json
fx tool inventory --format json

init、tool install 和 tool update 在 $FX_HOME/tool-history.json 記錄嘗試。installed 表示套件管理器成功，但後續版本核對仍可能失敗；單獨的 started 不證明成功。dry-run 和 init 略過的既有工具不產生記錄。

tool inventory 的安裝來源與 tool list/show 的定義來源分別表達不同事實：

相依檢查涵蓋同一 FX_HOME 的全部已註冊工作區，包括啟用的選用工具與內建預設項目。只有已確認由 fx 安裝且沒有剩餘需求的工具才可成為 unused；其他 FX_HOME 和未註冊專案不在範圍內。建議供人工判斷，sync/doctor 從不解除安裝。讀取失敗或證據不足不能證明可以移除。

查詢不會接管 PATH 中的工具，也不重建舊安裝歷史。完整欄位見安裝清單參考，資料範圍見本機資料。

fx 伴生 Skill 與團隊 Skill

fx 伴生 Skill 引導 Agent 使用 CLI。無需安裝或註冊工作區即可讀取：

fx self info --format json
fx skill show
fx skill status

希望宿主自動探索副本時，使用 fx skill install --agent codex。--project 面向目前目錄；--dir ./custom-skills 面向獨立目錄，不能與 --agent、--project 同用。獨立 Skill 命令的目標選擇不依賴工作區 Agent 設定。偵測、取代與解除安裝規則見Skill 參考。

明確執行 install 會將已識別副本更新為呼叫 CLI 的版本，包括同版修復和取代較新副本。skill update 只更新比呼叫 CLI 舊的已識別副本，涵蓋所有 Agent 的目錄，不新裝副本；self update 會從新安裝的 fx 執行它。init/sync 同版重用且不降級。取代外來內容需要確認和備份。解除安裝不改變 Agent 選擇，後續 sync 可能再次安裝。

skill status 報告安裝版本與 activation: unverified。檔案已安裝不代表宿主已載入。按需閱讀隨包指南。

團隊 Skill 位於 manifest 的 skills/，由 init/sync 連結到所選宿主，並在根 AGENTS.md 產生目錄。請從工作區根啟動，子儲存庫的探索行為沒有保證。使用 fx sync --only docs,skills 更新；不要透過團隊共用連結安裝 fx 伴生 Skill，應使用使用者副本或獨立目錄。

貢獻共用知識

source push 可預覽或提交所選來源檔案，保留來源 checkout 的 HEAD、索引和工作檔案。提交需要個人 fork 及其上游關係的證據，manifest 來源須託管在 Bitbucket 或 GitHub 上。實際提交前閱讀 fx source push --help 與貢獻契約。

常用命令

使用 fx <topic> --help 查看標準入口與相容別名。集合參數接受重複參數和逗號分隔的值。

完整語法以 --help 和自動產生的 CLI 參考為準。

給編碼 Agent

先執行 fx self info --format json。初始化任務讀取傳回的 initialization_guide，並持續使用同一準確入口。完整 Skill 提供其他任務的路由。

使用 --format json 分開保存 stdout 結果與 stderr 進度、通知和錯誤。預設結果保留準備結論及全部阻塞項，--details 展開階段證據。human 預設先顯示任務結論與下一步。release check 的 human 輸出在每個儲存庫開頭先說明它將發佈的內容：目標分支宣告的版本、兩個分支的最新提交，以及來源分支上尚未合併到目標分支的提交數。開頭分別統計失敗、警告、未完成、通過和不適用的檢查。已確認的問題按儲存庫列出；相同的不可用或部分結果按原因合併，並註明受影響的檢查、儲存庫和恢復步驟。已確認的失敗也可能同時未完成。只有檢查已完成且無問題的儲存庫才進入完成分組；明確排除的檢查與通過項分別統計。--details 展開各儲存庫的全部檢查。沒有確認失敗但仍有未完成項時，通知為 RELEASE_INCOMPLETE；JSON 保留原有 ok/complete 語義及查詢失敗的結構化資訊。缺少錯誤追蹤專案時報告未完成，不再查詢整個組織。在終端上還會加上顏色與符號、依寬度收窄表格，並以文字顯示錯誤；管線或檔案取得純文字和 JSON 錯誤信封，NO_COLOR 去掉顏色。命令執行期間，終端上還會有一行狀態列，顯示已用時間、可計數工作的進度與正在等待的對象；命令結束後這一行消失，管線、檔案、JSON 輸出與 --quiet 都不會收到它。git 或安裝器執行期間可能在同一終端上詢問主機金鑰或密碼片語，這時狀態列不再原地重繪，改為每五秒列印一行。明確的 --fields 從完整報告擷取欄位，點路徑保留為扁平鍵，例如 fx sync --format json --fields operation,preparation.state,items,summary。

發佈版本優先讀取來源分支根目錄的 VERSION 檔案, 並在兩個分支的最新提交上讀取相同路徑. 內容會去除首尾空白, 空內容保持為未知. 沒有 VERSION 時, 繼續從相依檔案 (如 package.json) 讀取版本. 相依檢查仍讀取相依宣告.

發佈錯誤視窗可以使用相對時長, 或一對包含時區的明確時間. 絕對區間包含起點, 不包含終點; 要包含完整的一天, 終點使用當地次日零點. 例如:

fx release check fx-example-api --from 2026-04-01T00:00:00+08:00 --to 2026-04-15T00:00:00+08:00 --format json --details
fx repo version fx-example-api --ref main --baseline v1.2.0 --format json
fx repo version fx-example-sdk --path packages/client/package.json --format json

版本證據將參照固定到提交, 標明實際宣告欄位, 並沿第一父提交歷史查找該欄位最近一次值變更. 僅修改相依不算版本變化. 歷史基準比較從該參照以來的全部變更, 與尚未合入發佈分支的提交分開. 原始碼版本或修改時間不能證明已發佈. 歷史缺失或查詢預算耗盡時, 傳回帶有原因的部分證據. CLI 參考 說明如何在多儲存庫發佈檢查中請求這些證據, 以及如何選擇套件路徑.

自動探索版本證據時會略過 requirements.txt 等只宣告相依關係的檔案. 已存在但無法讀取的受支援版本來源會使證據不完整, 不會隱含改選其他套件; Gradle 可以使用相鄰的 gradle.properties. Maven 支援字面版本, 或可從專案 properties 解析為字面值的單一 ${property}. 組合運算式、巢狀運算式或無法解析的運算式會回傳 VERSION_DECLARATION_UNREADABLE, 並保留證據不完整狀態.

Sentry 證據保留符合未解決查詢且在視窗內活躍的已收集候選, 包括舊問題. 後續確認 resolved 或 ignored 的狀態保留在稽核證據中, 但不計入新問題判定, 並區分生命週期首次出現時間與清單/視窗時間. 分頁或中繼資料失敗會明確保留; 部分證據不能證明問題不存在. 狀態與負責人反映讀取各回應時的情況, 不代表歷史視窗內的狀態. 事件數的統計範圍未知, 不能當成本輪新增事件次數. 錯誤檢查按生命週期首次出現時間計數; 舊問題是否復發需要另行判斷.

repo show 也傳回 ownership_evidence: 儲存庫關聯的業務範圍、人員、團隊和集體職責. 日期篩選只對目前成員文件中宣告的有效區間求值, 不還原歷史快照, 也不決定指派給誰.

準備就緒結束代碼為 0，未完成為 12；預覽只是計畫。設定或執行異常保留原分類結束代碼，也可能傳回部分 stdout。doctor.coverage 單獨描述診斷涵蓋範圍；選用宿主啟用未驗證不會阻塞必要工作，檔案存在也不證明啟用。

發佈報告成功產生後仍以 0 結束. ok 表示沒有失敗檢查, complete 表示檢查涵蓋完整. evidence_complete 還包括已請求的儲存庫事實; 為 false 時應查看 facet_coverage 和失敗原因. observed_at 是命令開始時間. 每個儲存庫記錄自己的標準化時間區間; 儲存庫原則使用不同視窗時, 頂層區間為 null.

Init 會自行執行已授權的本地準備。結果保留已完成步驟；認證未完成時，不要重複這些步驟。

若需儲存輸出進行分析，請使用任務授權目錄；唯讀姿態無法控制 shell 重新導向。

先讀 preparation.next：審閱預覽、準備完成後繼續原任務、執行 Agent 動作，或等待人工條件補齊。next_actions 只包含 Agent 可處理的動作；個人操作保留在阻塞項內並標為 actor: user。條件變化後才執行 resume。

一次閱讀全部 preparation.blockers。next_actions 提供準確 argv、cwd、可選 env 座標及批准要求；續跑時保留這些值，resume 繼續已註冊工作區。既有授權持續有效，新向量仍須審閱。不要憑註冊或複製推斷成功，不要為取得明細重複寫入，也不要將個人憑據放入 manifest。

檔案衝突的逐項結果保留在 stage_details.docs.files（init 中位於 sync 下）。取代外來內容需要批准，並保留同層備份。詳見回應契約。

設定

~/.fx 儲存工作區註冊、個人層、資源擁有權狀態、信任和快取。FX_HOME 只改變 fx 的個人目錄，不改變配套工具的憑證位置。

config list 顯示設定鍵、預設值、環境變數名稱及實際來源；config get <key> --explain 顯示各層。優先順序為明確參數、環境變數、設定檔、內建預設值。使用 config export/import 遷移個人設定。

匯入按名稱合併工作區註冊，保留 profile 中未提到的工作區；明確列出的個人層會被取代。匯入不會改變既有工作區的根目錄或來源，請先使用 workspace relocate 或 workspace rebind。使用 workspace unregister 明確解除管理。計畫會列出註冊情況與仍需完成的準備步驟；遺失的 manifest checkout 可透過輸出的 init 命令恢復。匯出不複製 manifest checkout、信任或憑證。

format 控制輸出。command_shell 只控制產生命令的文字，不改變執行方式；auto 在 Windows 選擇 PowerShell，其他平台選擇 POSIX。可使用 --command-shell、FX_COMMAND_SHELL 或 cmd 設定覆寫。manifest 中的 shell 範本保持原樣。

自動補齊支援 bash、zsh、fish 和 PowerShell，透過 fx completion <shell> 產生，依需求自行載入。

Agent 選擇

fx config set agents codex 選擇指定宿主，fx config set agents '' 或空 FX_AGENTS 選擇無宿主。取消設定和環境覆寫後恢復偵測。Agent 選擇影響同一 FX_HOME 的全部工作區；FX_HOME 不移動全域 Skill 或配套工具憑證。

整合

manifest 選擇工作區使用的 provider 和配套 CLI。fx manifest providers 列出本工作區中每項能力繫結了什麼；fx tool list --catalog 列出 fx 已知的全部配套工具，包括這裡沒有被選用的。通訊和知識入口交接給配套工具，不代表 fx 代理了所有服務 API。

Agent 探索包括 Claude Code、Codex CLI、Cursor 等已註冊宿主。Skill、hook、MCP 與規則的支援因宿主而異；使用 agent list、hook list、mcp list 檢查具體能力，不要假定各宿主功能一致。

判讀初始化與復原結果

依結果傳回的繼續操作處理。新來源尚未接受時，使用完整的原始重試命令；否則續跑讀取託管來源與現有選擇。註冊和檔案寫入只是已發生的效果，完成判定看 preparation.state 與阻塞項。

本機預覽檢查目錄、stdin 或 Git 已提交內容；新遠端來源在取得前保持 source_inspected: false。已知指南衝突與計畫命令會先顯示，預覽不授予信任。普通來源指南會在產生的目標中補齊 fx 區域，保留共享來源正文；模糊標記由維護者修正。

部分失敗會保留已完成儲存庫、本機準備和使用者檔案。補齊列出的前置條件後，依傳回操作繼續；既有安裝與已驗證步驟會略過。相對驗證檔案以工作區根為基準。含空格或 Unicode 的目錄會自動產生名稱，直接使用傳回的身分即可。

遇到 SKILL_WRITE_DENIED 先處理被拒絕的路徑；改變 FX_HOME 不會移動全域鎖。可用 fx sync --only repos,docs --no-refresh-manifest 繼續允許的工作，但不能宣稱 Skill 已修復。外來檔案置換仍須批准並保留備份。Git 來源刷新保留本機修改，正常重試重新檢查儲存庫可讀性。詳見支援。

人工接手後恢復登入

使用 doctor --tool <name> 定向診斷時, 只檢查或修復指定工具的安裝與準備狀態, 不更新無關儲存庫、指引或宿主資源. 省略 --tool 可檢查整個工作區. 用戶端啟動或版本檢查失敗時, 相依的命令檢查會等待此前置條件; 這不表示需要重新登入.

can 和啟用檢查的 where 回傳已檢查工具的 execution.binary_path、version 和 cwd. 後續呼叫使用該路徑與工作目錄, 避免新 shell 從 PATH 選中其他安裝. Provider 命令與直接 handoff 命令已繫結路徑; manifest 自訂 shell 範本仍照原文輸出. tool install/update 同時回傳 binary_path 與 version_after. 更新後重新檢查就緒並載入相符的配套 Skill.

準備就緒不代表擁有每項 API 權限. 先驗證所需操作再補權: 搜尋失敗不能證明已知文件無法讀取. 不支援裝置 OAuth 的 Sentry 實例可宣告 service.auth_scheme: token, 改為人工設定個人 Token; 已有效的 CLI 登入仍可重用. 不要將 Token 寫入 manifest 或聊天.

login 需要人工輸入時，先完成已授權的 handoff，再重跑同一命令。fx 會先檢查目前狀態，再決定是否重複操作；之後重新執行原先的 can 或 doctor 檢查，繼續原任務。與 init 和 sync 一樣，login 會直接執行重用現有登入的內建步驟，即使帶 --no-input 也不詢問；只有登入前才會詢問。

機器呼叫端在非零結束時，也要同時讀取部分 stdout 與 stderr 錯誤。已完成步驟仍保留；handoff、blocked、failed、not_started 區分後續工作。彙總、計畫問題與步驟復原欄位見登入回應契約。

交給人處理的步驟會說明其檢查得到的回答。步驟的 check 帶有工具自己的訊息；fx 能讀懂失敗原因時還會給出成因：未能建立驗證、服務拒絕了權限，或連線未能建立。此時步驟的說明會針對該成因提供處理方式，重新登入前請先閱讀。多數檢查不提供成因，這時以工具的訊息和步驟的說明為準。

沒有得到回答的檢查（工具未能啟動，或逾時）不會交給人處理。can 與 where 將它列在 unfinished 中，沒有其他失敗時傳回 unknown；login 以該錯誤停止，並在 stdout 保留部分結果；doctor 將它回報為涵蓋不完整的檢查項。較早版本的 fx 沒有這些欄位；fx doctor --tool <tool> --env <env> 可查看單一工具給出的訊息。

Skill 所有權與宿主啟用

使用者層級 fx Skill 跨工作區共用，並由使用者層級鎖保護；團隊連結屬於各工作區，配套安裝器管理自己的版本行為。檔案正確不證明宿主已啟用。

用 hook list 查看支援和驗證狀態。已測試的 Grok 1.0.25 僅在 Git 根探索專案 hook，一般目錄信任不能解除此限制。使用明確的 fx sync --only docs,skills，維持工作區根為一般目錄；宿主執行核准仍獨立生效。

重用現有登入

初始化會保留團隊統一的 context 名稱。相容的配套 CLI 會先比對同一服務的現有登入，重用個人身分，再決定是否需要你登入。Token 繼續保存在原 CLI 的憑證儲存區，目前的 context 與現有身分保持不變。多個身分符合時，可使用原 CLI 的 auth reuse --from-context 選擇來源；網路或鑰匙圈問題會與缺少憑證分開回報。多個環境可能共用已儲存的登入：fx login 為其中一個環境完成登入後，會重新檢查該工具先前未能完成的環境，並把已經可用的回報為 verified。

成員歸屬與業務協作

以 fx member selectors 探索篩選值, 可用 --kind area、scenario、team 或 function 限定種類. 每列回傳種類、ID、名稱和所屬 area, 不列出人員. 將情境誤填為 area 時, 錯誤會提供正確父層的完整查詢. 缺少帳號欄位仍表示未知. 職責資料可支持分派建議, 不授權覆寫既有工作項目的負責人.

使用 fx member show <account> --system <system> --area <id> --format json 查詢作者。確認身分需要唯一的精確帳號比對。分別讀取目錄歸屬、業務責任團隊和個人協作職責。多個團隊可同時得到確認。候選關係仍待核實，未涵蓋的歸屬維持未知。省略業務領域會回傳所有適用關係。

使用 fx member list --team <id> --function <id> --area <id> 尋找負責該項工作的人。所有條件必須符合相同的協作關係。省略業務範圍時也可符合目錄關係。--as-of YYYY-MM-DD 按指定日期檢查宣告的有效期間。