CLI 命令參考

sw 是 Swift Web 的命令列工具，提供專案建立、檔案生成、設定管理等功能。

全域旗標

以下旗標適用於所有命令，可放在命令的任意位置：

未傳 --json / --text 且 stdout 非 TTY（CI 管道 / 重定向）時自動降級為 text 模式，防互動 prompt 掛死。

範例：

# JSON 輸出（適合 CI 腳本）
sw create YC001-WEB-專案名 --yes --json

# 純文字輸出（適合管道處理）
sw info --text | grep framework

sw create

從 Starter 模板建立新的 Swift Web 專案。

語法

sw create [name] [選項]

參數

選項

專案名稱格式

sw create 只接受兩種格式（為保證所有內部專案的倉庫命名一致可追溯）：

YC 格式（強制要求的內部專案命名）

適用於按照 YC 編號管理的內部專案：

sw create YC117-WEB-影城管理系統

• 格式：YC + 數字（不限位數） + -WEB- + 專案標題，大小寫不敏感
• CLI 自動提取 name 與 title，非互動模式無需再詢問標題
• 生成目錄：yc117_web（YC 編號轉小寫，拼接 _web）
• swift.config.json 中記錄 project.name: "yc117"、project.type: "web"、project.title: "影城管理系統"

當前目錄（.）

mkdir my-project && cd my-project
sw create .

• 在當前目錄直接初始化，不建立子目錄
• CLI 會互動式詢問專案標題和描述
• project.name 取 basename(cwd)

不支援普通字串作為專案名（如 sw create my-project、sw create 123abc 會被拒絕，返回 INVALID_NAME）。這是強約束——所有內部專案必須從倉庫名一眼識別出 YC 編號。

互動式設定精靈

互動模式下，sw create 會在下載 starter 之後依次詢問以下問題（按 Enter 選預設）：

答案落盤到 swift.config.json，並同步改寫 package.json（相依套件增刪）/ nuxt.config.ts / i18n/locales/ / tailwind.css（Tailwind 的 stylelint 白名單已收進 @swift-web/standards base，cli 不再改 stylelint 設定）。--yes 模式跳過所有詢問，用保守預設值（tracker 與 dev mock 預設開啟，i18n / PWA / WebSocket / Tailwind 等其餘能力關閉）。

生成的內容

sw create 完成後，目標目錄包含：

• 完整的 Nuxt 4 專案結構（從 verdaccio npm pack @swift-web/starter 拉到的最新 starter 快照）
• swift.config.json（專案中繼資料，含互動選擇的框架能力開關）
• package.json 重置為「新專案」狀態：name 替換、version 歸 0.0.0、private: true、刪 publishConfig / release 等發版欄位、補 pnpm 11 守衛（preinstall）
• README.md 標題行替換為專案名
• .npmrc 自動生成（@swift-web → verdaccio 分流 + 跨平台 archs，無 authToken——套件匿名可裝）
• .env（從 .env.dev.example 自動複製，只含環境相關項：NUXT_PUBLIC_SITE_URL / NUXT_PUBLIC_API_BASE 等；專案常數已隨程式碼寫在 nuxt.config.ts）
• .mcp.json / .codex/config.toml / .cursor/mcp.json（讓 Claude Code / Codex / Cursor 等 AI 工具發現並呼叫 sw 命令）
• package.json 中的 @swift-web/framework 版本會自動拉取私有 registry 最新版

範例

# 互動式建立（預設方式）
sw create

# 提前給出 YC 名稱，跳過首輪詢問
sw create YC001-WEB-用戶中心

# 在當前空目錄建立
sw create .

# 跳過所有互動（CI 友善）
sw create YC001-WEB-用戶中心 --yes

# CI 環境，JSON 輸出
sw create YC001-WEB-用戶中心 --yes --json

JSON 輸出範例：

{
  "success": true,
  "action": "create",
  "project": {
    "name": "yc001_web",
    "title": "用戶中心",
    "dir": "/Users/yourname/projects/yc001_web"
  },
  "nextSteps": [
    "cd yc001_web",
    "pnpm install",
    "# 編輯 .env，填寫 NUXT_PUBLIC_SITE_URL 和 NUXT_PUBLIC_API_BASE",
    "# 接後端時在 nuxt.config.ts › swiftConfig.apiDocs 設文件源，token 放 .env API_DOCS_TOKEN，再執行：pnpm generate-api",
    "pnpm dev"
  ]
}

sw config get

查看當前專案的 swift.config.json 設定。

語法

sw config get [key]

參數

範例

# 查看完整設定
sw config get

# 查看頂層欄位
sw config get project

# 使用點路徑查看巢狀欄位
sw config get project.title
sw config get framework.theme
sw config get framework.i18n.defaultLocale
sw config get features.tailwind

輸出範例：

project.title: 影城管理系統

// --json 輸出
{
  "success": true,
  "key": "project.title",
  "value": "影城管理系統"
}

不傳 key 時返回整份設定，結構不同（無 key / value，改為 config）：

// sw config get --json
{
  "success": true,
  "config": { "project": { "title": "影城管理系統" }, "framework": { } }
}

注意：此命令需在 Swift Web 專案根目錄（含 swift.config.json）下執行，否則報錯 NOT_PROJECT。

sw config set

更新 swift.config.json 中的設定項目，並自動同步更新相關專案檔案。

語法

sw config set <key> <value>

參數

檔案同步規則

sw config set 不只修改 swift.config.json，對於特定 key，它還會同步更新對應的專案檔案：

專案檔案同步失敗時會自動回滾已改的專案檔案；swift.config.json 已先行寫入，不還原。

可管理的 framework.* 欄位

除互動嚮導問到的五項（theme / i18n / pwa / websocket / request.mock）與建立時預設寫入的 tracker / errorHandler 外，FrameworkConfig 還有 9 組可選欄位不進 sw create 嚮導（保持建立步驟精簡），但全部可經 sw config set framework.<path> <value>（及 MCP 工具 sw_config_set）按需修改——這些欄位無 applier，寫入 swift.config.json 後由 nuxt.config.ts 的 ...swiftConfig.framework spread 自動聯動，重啟 dev server 即生效：

⚠️ auth 安全確認：關守衛（framework.auth.enabled 置 false）或縮短 guardedPaths 會讓原本受保護的頁面變公開——互動模式下 sw config set 會二次確認；非互動（--json / --text / MCP）放行執行，但 JSON 回應額外帶 warning 欄位提示。另外，顯式設定 guardedPaths 會整體覆蓋 framework 預設守衛清單（預設含 /mine），CLI 會附帶覆蓋提示（JSON 回應可選 notice 欄位）。

陣列 / 巢狀物件欄位（seo.sitemap.exclude / guardedPaths / providers 等）用 JSON 字串作值：sw config set framework.seo.sitemap.exclude '["/admin/**"]'；或走 MCP 用自然語言修改。

範例

# 修改專案標題（同時更新 README.md）
sw config set project.title "新的專案標題"

# 修改專案描述
sw config set project.description "這是一個影城會員管理平台"

# 修改站點編號（package.json 的 name 會被寫成 <name>_web，不是原樣填入的值）
sw config set project.name yc002

# 開啟 PWA
sw config set framework.pwa true

# 修改 i18n 預設語言
sw config set framework.i18n.defaultLocale zh-TW

# 啟用 errorHandler（全域錯誤上報）
sw config set framework.errorHandler true

framework.errorHandler 在 sw create 互動嚮導中未單獨提問，預設關閉；如需啟用， sw config set framework.errorHandler true 即可——nuxt.config.ts 經 import swift.config.json 自動聯動，改完即生效，無需 sync。

輸出範例：

✔ swift.config.json 已更新：project.title = 新的專案標題
  同步更新檔案：README.md

// --json 輸出
{
  "success": true,
  "action": "set",
  "key": "project.title",
  "value": "新的專案標題",
  "updatedFiles": ["README.md"]
}

updatedFiles 的取值語義（消費方注意，cli#45 / 稽核 Y-9）：

取值	含義
真實相對路徑陣列	該命令直接改寫的檔案（如 ["README.md"]）
["<applier>"]	走了 feature applier（pwa / tailwind / theme 等）——改動由 applier 內部完成、不是檔案路徑，別當路徑解析
["nuxt.config.ts", "i18n/locales/"]	i18n applier 的固定標識（同樣是語義標識而非精確改動清單）
[]	該 key 無檔案聯動，僅寫入 swift.config.json

auth 危險方向的改動（關守衛 / 縮短 guardedPaths）在非互動模式下放行執行，此時 JSON 回應會額外帶可選的 warning 欄位（內容為具體的安全提示文案），腳本 / AI 消費方應檢查並透出。

注意：此命令需在 Swift Web 專案根目錄下執行。

sw config sync

重新觸發所有功能開關 applier，把 swift.config.json 的當前狀態強制同步到 nuxt.config.ts 和其他派生專案檔案。 適合手工編輯 swift.config.json 後用一條命令對齊所有副作用。

語法

sw config sync [選項]

選項

行為

讀 swift.config.json 後執行 i18n / PWA / Tailwind / theme 四個開關 applier（errorHandler / tracker 無 applier——nuxt.config.ts 經 import swift.config.json 自動聯動）， 把結果寫回 nuxt.config.ts，並按需增刪 layer 檔案（如 i18n 占位檔）。

適用場景

• VCS 拉到他人改過的 swift.config.json，本地讓 nuxt.config.ts 跟上
• 手工編輯 swift.config.json 後偷懶，一條命令對齊
• 升級 framework 後某些 applier 行為變化，重跑一次讓 nuxt.config.ts 反映新規則

範例

sw config sync           # 預設 interactive 彩色輸出
sw config sync --json    # 給 AI / 腳本消費

注意：此命令需在 Swift Web 專案根目錄下執行。

sw add

在當前專案中快速生成新的檔案（頁面、元件、Store 或 API 模組）。

語法

sw add <type> <name> [選項]

參數

選項

類型詳解

page — 頁面

sw add page product-detail

生成檔案：app/pages/product-detail.vue，範本包含 defineRouteRules 渲染策略宣告 + useSeo() SEO 占位（與 framework SEO 強制啟用對齊，每個頁面必填 SEO 元資訊）。

<script setup lang="ts">
// 渲染策略：預設 ISR 快取 1h；按頁面性質調整 —— 私有/登入態頁改 ssr:false，純靜態頁 prerender:true
// 選型速查：https://sw.djatm.cloud/guide/rendering-quick-guide
// 深入與避坑：https://sw.djatm.cloud/guide/rendering-strategies
defineRouteRules({ isr: 3600 })

// TDK 長度（顯示寬度：中文算 2 / 英文算 1）：title 建議中文 5-30 字，description
// 必須補成摘要式段落——中文 25-80 字 / 英文 50-160 字元（偏短會觸發 lint + dev 警告）。
// 登入 / 中轉等工具頁改傳 robots: 'private' + silenceLengthWarnings: true。
useSeo({
  title: 'product-detail',
  description: 'TODO: 用 25-80 個中文字概括本頁內容與價值（當前佔位必須替換，過短會有 SEO 警告）',
})
</script>

<template>
  <div>
    <!-- product-detail page -->
  </div>
</template>

檔案名使用 kebab-case，與路由路徑對應（/product-detail）。

component — 元件

sw add component UserCard

生成檔案：app/components/UserCard.vue

<script setup lang="ts"></script>

<template>
  <div>
    <!-- UserCard -->
  </div>
</template>

檔案名使用 PascalCase，Nuxt 自動匯入，無需手動 import。

store — Pinia Store

sw add store cart

生成檔案：app/store/cart.ts

export const useCartStore = defineStore('cart', () => {
  // state
  const data = ref<unknown>(null)

  // actions

  return { data }
})

Store 模板內不寫 import 語句，因為 Starter 專案中有 Nuxt 自動匯入，defineStore、ref 等無需手動引入。

api — API 模組

sw add api order

生成檔案：app/api/manual/order.ts（手寫模組目錄；modules/ 歸 generate-api、重生成會整刪。重跑 generate-api 後自動註冊為 api.order）

⚠️ api 名稱須以字母開頭（v2-order / oauth2 可以，2fa / 3d-viewer 不行）—— 名字會成為 api.<name> 的鍵名（generate-api 按檔名註冊），數字開頭是非法識別字。CLI 直接拒絕並提示，不會產出壞檔案。

// 手寫 API 模組（app/api/manual/）：generate-api 不改寫本目錄，重跑後自動註冊為 api.order
/** 列表 */
export async function list(params?: Record<string, unknown>): Promise<unknown[]> {
  return request<unknown[]>('/order/list', { params })
}

/** 詳情 */
export async function detail(id: number | string): Promise<unknown> {
  return request<unknown>(`/order/detail/${id}`)
}

範例

# 生成頁面
sw add page about-us
sw add page products/index      # 生成 app/pages/products/index.vue
sw add page products/[id]       # 生成動態路由頁面

# 生成元件
sw add component HeroSection
sw add component AdBanner

# 生成 Store（多詞用 kebab-case，函式名自動轉 PascalCase）
sw add store order-list         # → useOrderListStore
sw add store shopping-cart      # → useShoppingCartStore

# 生成 API 模組
sw add api product
sw add api user-auth

# 強制覆蓋已存在的檔案
sw add component HeroSection --force

JSON 輸出範例：

{
  "success": true,
  "action": "add",
  "type": "component",
  "name": "HeroSection",
  "file": "app/components/HeroSection.vue"
}

注意：此命令需在 Swift Web 專案根目錄下執行（含 swift.config.json）。

sw info

顯示當前 Swift Web 專案的詳細資訊。

語法

sw info

顯示內容

• 專案名稱（標題，未設標題則顯示套件名）、描述
• 當前安裝的 @swift-web/framework 版本
• Node.js 版本
• 框架功能開關狀態（主題、i18n、PWA、WebSocket、errorHandler）

範例

sw info

輸出範例：

  影城管理系統
  影城會員管理與售票平台

  framework:  ^x.y.z
  node:       v22.12.0
  theme:        toggle
  i18n:         on
  pwa:          off
  websocket:    off
  errorHandler: off

JSON 輸出：

sw info --json

{
  "success": true,
  "info": {
    "project": {
      "name": "yc117",
      "type": "web",
      "title": "影城管理系統",
      "description": "影城會員管理與售票平台"
    },
    "framework": {
      "version": "^x.y.z",
      "config": {
        "theme": { "mode": "toggle", "toggleStates": 3 },
        "i18n": { "enabled": true, "defaultLocale": "zh-CN", "locales": ["zh-CN", "zh-TW", "en"] },
        "pwa": false,
        "websocket": false,
        "errorHandler": false,
        "tracker": { "enabled": true, "autoPageView": true }
      }
    },
    "features": { "tailwind": false },
    "node": "v22.12.0"
  }
}

注意：此命令需在 Swift Web 專案根目錄下執行。

sw upgrade

檢查 @swift-web/framework 是否有新版本可用，互動確認後自動執行升級。非互動環境（--json / 非 TTY / MCP）必須顯式加 --yes 才會執行寫操作；只想查用 --check。

語法

sw upgrade            # 互動確認後升級
sw upgrade --check    # 只檢查有無新版，不改動任何檔案
sw upgrade --yes      # 跳過確認直接升級（非互動環境必須帶）

選項

結束碼

⚠️ --check 網路不通時退 2 而不是 1 —— 否則呼叫方會把「查不到」誤讀成「有新版」，反而觸發升級。

工作原理

1. 讀取當前專案 package.json 中安裝的 @swift-web/framework 版本
2. 從私有 registry 查詢最新發布版本
3. 對比版本號，互動確認後改寫 package.json 的 framework 版本範圍（保留 ^ / ~），再依序執行 pnpm install --lockfile-only 與 pnpm install --frozen-lockfile（只重新解析 framework 相關條目，不帶出無關依賴升級，cli 0.23.2+ / cli#62）；--check 到第 3 步為止只報告，非互動環境缺 --yes 則拒絕執行並退 1

範例

sw upgrade

已是最新版時：

  正在檢查最新版本…

  ✔ 已是最新版本 0.x.y

有新版本時：

  正在檢查最新版本…

  當前版本：  ^x.y.z
  最新版本：  x.y.z

  ◆  升級到 x.y.z？ Yes

  …（改寫版本範圍後執行 pnpm install --lockfile-only 與 --frozen-lockfile）

  ✔ 已升級到 x.y.z

interactive 模式先詢問確認、再自動改寫版本範圍並執行 pnpm install --lockfile-only 與 pnpm install --frozen-lockfile； --text / --json / 非 TTY / MCP 等非互動環境不彈確認、也不執行 —— 必須顯式加 --yes， 否則退 1 並報 CONFIRMATION_REQUIRED。只想查有沒有新版用 --check。 升級完成後重新啟動開發伺服器即可生效。

JSON 輸出（三種 shape，由 status 欄位區分）：

⚠️ --check 發現新版時是 status: "outdated" + success: true 但退出碼 1 （沿用 git diff --exit-code 慣例：success 表示「查詢本身成功」，退出碼表示「有差異」）。 set -e 的腳本需顯式容忍這一檔。

// 已是最新版
{
  "success": true,
  "action": "upgrade",
  "status": "up-to-date",
  "version": "x.y.z"
}

// 有新版可升（`--check` 命中；`success: true`，退出碼 1）
{
  "success": true,
  "action": "upgrade",
  "status": "outdated",
  "from": "x.y.z",
  "to": "x.y.z+1"
}

// 升級成功
{
  "success": true,
  "action": "upgrade",
  "status": "upgraded",
  "from": "x.y.z",
  "to": "x.y.z+1"
}

sw run

執行當前專案 package.json 中的 npm 腳本；不傳腳本名時列出所有可用腳本及一句話說明，快速回答「這個專案能跑什麼」。

語法

sw run [script]

參數

列表模式

sw run

輸出範例（節選）：

  可用腳本：

  dev            啟動 Nuxt 開發伺服器（熱更新）
  build          正式建置
  preview        預覽正式建置
  lint           執行全部 lint 檢查（eslint + stylelint）
  type-check     TypeScript 型別檢查
  test           執行 Vitest 單元測試
  generate-api   從 YAPI 自動生成 API 型別和請求函式
  ...

  用法：
    sw run <腳本名>
    pnpm run <腳本名>       （無需安裝 CLI）

說明來源：優先取 CLI 內建的「標準腳本描述表」（dev / build / lint 等），其餘嘗試從腳本引用的 .ts 檔案頂部的 JSDoc 首行提取（約定：scriptName — 一句話描述）。

執行模式

sw run generate-api

等價於 pnpm run generate-api，透傳 stdio，保留腳本的顏色和互動。

JSON 輸出：

sw run generate-api --json

{
  "success": true,
  "script": "generate-api",
  "exitCode": 0,
  "output": "..."
}

失敗時返回 code: "SCRIPT_FAILED"，output 包含 stdout + stderr 合併文字。逾時上限 5 分鐘。

不傳 script 名（列表模式） 的 JSON 結構不同 —— MCP sw_run 不帶參數時拿到的就是它：

// sw run --json
{
  "success": true,
  "scripts": [
    { "name": "dev", "command": "nuxt dev", "description": "啟動開發伺服器" }
  ]
}

description 優先取內建已知腳本的說明，其次從腳本檔案 JSDoc 首行擷取，都沒有則為空字串。

此命令在任意包含 package.json 的目錄都能使用，不強制要求是 Swift Web 專案。

AI 工具鏈（MCP）

starter 倉直接入庫 MCP 設定——Claude Code 讀 .mcp.json、Codex 讀 .codex/config.toml、Cursor 讀 .cursor/mcp.json，三份設定均啟動 sw --mcp。Codex 按客戶端提示信任專案後才載入專案設定；確認目前工作階段已連線 MCP 後，AI 即可直接列出 / 執行 sw 命令。共用規則入口是 AGENTS.md，skills 主源與實體鏡像分別在 .claude/skills/、.agents/skills/：

• 查看專案資訊 → sw info
• 切換 i18n 預設語言 → sw config set framework.i18n.defaultLocale zh-TW
• 生成新頁面 → sw add page orders/[id]
• 查 framework 元件 / composable 清單 → 工具 sw_framework_docs（動態查詢，避免 AI 憑印象引用舊元件名）

完整 MCP tools 清單（15 個）：

sw_framework_docs 的五層 = 元件 / composable / store / util / serverUtil，另支援框架設定（config）短名查詢；資料來源為當前安裝版本 ship 的 framework-api.json，不會有版本錯位。

sw_project_apis 每次呼叫現讀磁碟解析 app/api/modules/*.ts（pnpm generate-api 產物）——重跑 generate-api 後立即反映，無快取無快照；不傳參數列模組目錄、傳 module 看單模組介面細節（method / path / 入參欄位中文註解）、傳 keyword 按 函式名 / path / 說明 跨模組過濾。AI 開發頁面業務前先查它判斷該呼叫哪個介面。

.mcp.json 內容固定（無需自訂）：

{
  "mcpServers": {
    "swift-web-cli": {
      "command": "sw",
      "args": ["--mcp"]
    }
  }
}

CLI 不提供 init-mcp 之類的命令——starter 已自帶 .mcp.json、.codex/config.toml 與 .cursor/mcp.json，新專案開箱即用。 若誤刪可從 starter 倉 拷一份回來（Codex 使用者拷 .codex/config.toml，Cursor 使用者拷 .cursor/mcp.json）。

錯誤碼參考

當使用 --json 旗標時，錯誤回應包含以下錯誤碼：

錯誤回應格式：

{
  "success": false,
  "error": "當前目錄不是 swift-web 專案",
  "code": "NOT_PROJECT"
}

相關連結

• 快速上手 —— sw create 起步 + 專案腳本一覽
• 框架設定 Module Options —— sw config 改的 swiftConfig 欄位速查
• 開發規範 —— sw add 產生的檔案遵循的命名 / 結構約定
• dev 期請求 mock —— sw create「啟用 dev mock 資料？」的來龍去脈