meticulous-cli-update

安裝或更新 Meticulous CLI

@alwaysmeticulous/cli 套件正在積極開發中，並經常發布變更和改進。其他 Meticulous 技能假設 meticulous 指令已在 PATH 中且為最新版本，因此在任何 Meticulous 工作流程開始時，請執行此技能一次。

此技能只需在每次對話中執行一次。如果您已在本次對話中較早執行過，請跳過 — 無需在每次呼叫 Meticulous 技能時重新檢查版本或重新更新。

如何處理安裝/更新指令

此技能通常作為其他 Meticulous 技能的子步驟執行。下面的安裝/更新指令（步驟 1、3 和 5）涉及安全性 — 它們會安裝套件並連線網路 — 因此請將其視為盡力而為且非阻塞：

• 您通常無法事先知道某個指令是否被列入白名單。如果被列入白名單，它會靜默執行；如果沒有，嘗試執行它會顯示權限提示。兩種結果都可以 — 讓這成為您發現的方式。
• 如果某個指令需要您沒有的權限（出現提示，或使用者拒絕），請將其視為建議而非強制的信號。告訴使用者建議執行某個動作 — 例如「建議執行 npm install --global @alwaysmeticulous/cli@latest 來更新 Meticulous CLI」— 然後繼續。被拒絕的提示不是失敗；它只是表示「稍後再執行」。
• 如果使用者現在不想執行，仍然繼續。 不要停止工作流程；繼續執行其餘步驟，然後返回呼叫端技能。唯一嚴格的要求是 meticulous 指令確實存在（步驟 1）— 如果它真的沒有安裝且使用者拒絕安裝，則任何 Meticulous 技能都無法繼續，因此請在此停止。

唯讀檢查（meticulous --version、npm view …、meticulous auth whoami）可以直接安全執行。

步驟 1 — 檢查已安裝的版本

meticulous --version

如果找不到指令，表示 CLI 未安裝。請全域安裝（盡力而為，請參閱上面的說明）：

npm install --global @alwaysmeticulous/cli@latest

如果安裝未被列入白名單，請建議使用者自行執行該指令。由於沒有 CLI 就無法執行任何 Meticulous 技能，這是唯一一種情況，如果使用者拒絕，您應該停止並等待 — 因為沒有其他事情可以繼續。安裝完成後，重新執行 meticulous --version 以確認它已在 PATH 中，然後跳到步驟 4。

步驟 2 — 檢查最新發布的版本

npm view @alwaysmeticulous/cli version

步驟 3 — 如果 CLI 過時則更新

如果已安裝的版本已與最新版本相符，請跳到步驟 4。

否則，根據 CLI 的安裝方式進行更新（盡力而為，請參閱上面的說明 — 如果更新未被列入白名單，請建議使用者執行適當的指令，然後無論如何繼續）：

• 全域安裝（典型情況 — which meticulous 解析到目前專案之外的路徑）：

  npm install --global @alwaysmeticulous/cli@latest
  

• 在專案中本地安裝（@alwaysmeticulous/cli 出現在專案的 package.json 中，且 which meticulous 解析到 node_modules/.bin 內）：

  npm install --save-dev @alwaysmeticulous/cli@latest
  # 或者，如果專案使用 pnpm：
  pnpm add --save-dev @alwaysmeticulous/cli@latest
  # 或 yarn：
  yarn add --dev @alwaysmeticulous/cli@latest
  

如果更新已執行，請重新執行 meticulous --version 並確認它與最新版本相符，然後再繼續。

步驟 4 — 檢查驗證和專案選擇

確認使用者已通過 Meticulous 驗證並已選擇專案：

meticulous auth whoami

如果顯示「未找到驗證資訊」，則需要登入。登入是瀏覽器 SSO，因此使用者必須在瀏覽器中完成；使用哪個登入指令取決於您執行的環境：

• 在使用者自己的機器上（該機器上的瀏覽器可以連線到本機的 localhost）：

  meticulous auth login --non-interactive
  

  這會列印一個登入 URL，然後在本地回呼伺服器上等待，因此請在背景執行它，然後將列印的 URL 提供給使用者，並要求他們開啟該 URL 並完成登入。一旦他們完成，指令就會結束並儲存 token，然後您可以繼續。

  或者，要求使用者自行執行 meticulous auth login — 在他們自己的終端機上，這會直接開啟瀏覽器。

• 在遠端或沙盒機器上（雲端代理、SSH 工作階段、容器），其他裝置上的瀏覽器無法連線到本機的 localhost：

  meticulous auth login --device
  

  這會使用 OAuth 裝置流程：它會列印一個 URL 和一個簡短代碼，而不是等待本地回呼。在背景執行它，然後將 URL 和代碼提供給使用者，並要求他們在任何裝置上開啟該 URL 並輸入代碼。確認後，指令就會結束並儲存 token。

如果顯示「未選擇專案」（當使用者屬於多個專案時會發生這種情況 — 包括在非互動式登入之後，因為它跳過了專案選擇器），則必須在執行專案範圍的指令之前選擇一個專案。詢問使用者要使用哪個組織/專案（如果您還不知道），然後以非互動方式固定它：

meticulous auth set-project --project "組織/專案"

或者，要求使用者自行執行 meticulous auth set-project（它會顯示互動式選擇器）。

步驟 5 — 更新已安裝的 Meticulous 技能

技能本身也在積極開發中。將它們更新到最新版本（盡力而為，請參閱上面的說明）：

npx skills update --project

如果此指令未被列入白名單，請建議使用者自行執行。無論如何 — 無論是已執行，還是使用者拒絕 — 都繼續執行呼叫端技能。