Skip to main content
蘇小強 CLI 用於在 superun 專案和本地目錄之間同步檔案，終端機命令是 sxq。你可以在熟悉的 IDE 或 AI 程式設計智慧體中修改專案，再把改動推送回 superun、生成預覽並正式上線。
蘇小強 CLI 與 superun 產品內的 AI 助手「蘇小強」名稱相同，但不是同一個東西。產品內的蘇小強負責諮詢和使用說明；sxq 命令負責從終端機管理專案。
它是 專案開發和發佈工具，不能替代用於操作線上業務資料和接口的 superun CLI。

​
準備工作

你需要：
  • Node.js 18 或更高版本；
  • 目標 superun 專案的存取權限；
  • 專案的 sessionId，可以在 superun 專案頁面的 URL 中找到。

​
安裝並登入

sxq login 會開啟瀏覽器授權，並將臨時憑證換成 PAT。從 v1.1.2 起，登入憑證預設儲存在 macOS 鑰匙圈、Windows 認證管理員或 Linux Secret Service，並依 API 基礎 URL 隔離。已有 token 仍可透過以下命令匯入：
已有 PAT 可用 sxq login --pat 隱藏輸入，或用 sxq login --stdin 從標準輸入匯入；線上校驗成功後才替換本地憑證。SUPERUN_PAT 優先於本地憑證，設定後執行 sxq login 只校驗該環境變數，不開啟瀏覽器、不儲存到本地。空值或格式錯誤會報錯；要使用本地憑證，請先取消該環境變數。不建議透過命令列參數傳遞 PAT，以免進入命令歷史。 沒有工作階段 D-Bus 的無介面 Linux 環境會回退到本地明文憑證檔案並提示，Unix 檔案權限為 0600。憑證庫已鎖定、無法讀取或損壞時，CLI 會報錯，不會自動改用明文檔案；請解鎖或修復憑證庫，也可以從密鑰管理工具注入 SUPERUN_PAT。安裝 CLI 時需保留 npm optional dependencies，才能載入對應平台的原生憑證庫模組。 系統憑證庫可用但沒有憑證時，請重新登入；CLI 不會讀取或遷移舊版明文 token，並會清理目前環境的舊明文登入憑證。sxq logout 只刪除目前 API 環境在所選儲存區中的登入憑證，不撤銷伺服器端 PAT；如果設定了 SUPERUN_PAT，仍需自行取消該環境變數。

​
CLI 版本更新

從 v1.1.1 起，CLI 每天首次執行命令時檢查 npm 升級策略。latest 提示新版本；若目前版本低於維護者設定的 required，CLI 會自動升級後重新執行原命令。sxq upgrade、sxq logout、--version 和 --help 始終可直接執行。網路異常時沿用快取策略；沒有快取時放行。該策略無法約束尚未包含升級門禁的舊版 CLI。

​
關聯並拉取專案

建立一個空目錄，把它關聯到遠端專案，然後拉取檔案：
關聯時會校驗程式碼同步權限和專案可見性。專案必須完成樣式選擇，階段至少為 2（演示）；階段缺失、無效或低於 2 時拒絕關聯，原有綁定保持不變。首次拉取為全量拉取，之後為增量拉取並進行三方合併。

​
與 Git 協作

.sxq/attachments.json 儲存的是目前目錄上次同步的遠端基線，不是 Git 索引。.sxq/ 預設不進入 Git，因此切換分支時，程式碼檔案會改變，但同步基線不會跟著分支切換。新分支中較舊、內容不同或不存在的檔案，可能被識別為修改或刪除，即使你沒有手動改動它們。
在包含 .sxq 的目錄中切換分支後，不要立即執行 sxq push。先回到允許推送的分支，執行 sxq pull，再檢查 git status、git diff 和 CLI 顯示的完整推送清單。出現意外的大量修改或刪除時，應取消推送並檢查工作樹和 .sxq 是否匹配。
Git 專案預設只允許從 main 推送。專案使用其他主分支時，執行：
建議為同時使用的每個分支建立獨立的 Git worktree，並在每個 worktree 中分別執行 sxq link 和 sxq pull，讓每個工作目錄維護自己的 .sxq 基線。不要在儲存庫、worktree、分支或不完整的原始碼目錄之間複製 .sxq，也不要強制把它加入 Git。 sxq push -f 只會忽略分支限制，不能證明目前檔案就是你想推送的內容。僅在確認目前分支並核對完整清單後使用；它不能繞過 reset、rebase、歷史改寫或 worktree 不匹配等安全檢查。

​
修改並推送程式碼

完成本地修改後，把改動推送回 superun：
sxq push 會先拉取遠端變化。如果檔案無法自動合併，命令會中止，並在檔案中寫入 Git 風格的 <<<<<<<、======= 和 >>>>>>> 衝突標記。 拉取和合併完成後，CLI 會列出本次全部新增（+）、修改（M）和刪除（D）檔案，並要求 y/N 確認。-y 會保留清單顯示但跳過輸入確認，只應在已經核對並授權這些路徑後使用。不要把 -f -y 當作失敗後的通用重試方式。 處理全部衝突、刪除標記並測試後，再次執行 sxq push。如果清單與預期不符，尤其是突然出現大量 M 或 D，請選擇取消而不是繼續。專案 .gitignore 匹配的檔案，以及 node_modules、dist、.git 等內建忽略項不會同步。

​
預覽和正式上線

更新前端預覽並等待編譯完成。front 是預設目標，可以省略：
只部署目前主線最新版本中的 Edge Function 到預覽環境：
舊命令 sxq publish 仍可繼續使用，行為等同於 sxq preview front。
確認預覽無誤後，開啟專案發佈確認頁：
只查看發佈狀態，不觸發上線：
sxq deploy 只負責在瀏覽器中開啟發佈確認頁，不會直接呼叫發佈接口。請在頁面中檢查關聯專案、預覽結果和目標區域，再由使用者完成最終確認。

​
執行資料庫遷移

在 supabase/migrations/ 下建立以下格式的遷移檔案：
字首必須是嚴格的 14 位 yyyyMMddHHmmss 時間戳，例如：
時間戳字首用於確定遷移回放順序，在同一個專案中必須唯一。禁止使用 Unix 時間戳、帶分隔符的日期、縮短日期或其他位數的字首。建立遷移前先檢查已有檔名；如果時間戳已存在，請產生一個更晚的時間戳，不要重複使用。 然後執行遠端還不存在的遷移：
CLI 會先拉取遠端基線並找出待執行遷移。只要任一新增 SQL 檔名沒有嚴格的 14 位時間戳字首，或待執行遷移與其他待執行遷移、遠端已有遷移重複使用時間戳，整批任務就會在執行任何 SQL 前中止。校驗通過後才按時間戳升序執行，遇到第一個失敗後停止。遷移成功後，服務端會自動將檔案儲存為專案附件。不要通過 sxq push 推送遷移檔案，CLI 會直接攔截。

​
命令速查

在 CI 或 AI 智慧體中，只有在完整推送清單已被核對和授權後才能新增 -y。在非互動環境中，不帶 -y 的推送會在提交前報錯，不會一直等待輸入。正式發佈始終需要使用者在瀏覽器頁面確認。

npm 上的蘇小強 CLI

檢視已發佈的軟體套件和當前版本。

原始碼

閱讀完整參考資料或提交問題。