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 自动联动）， 把结果写回项目文件，并按需增删 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 数据？」的来龙去脉