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 publish 已弃用，请使用 sxq preview 代替”。
确认预览无误后，打开项目发布确认页：
只查看发布状态，不触发上线：
sxq deploy 只负责在浏览器中打开发布确认页，不会直接调用发布接口。请在页面中检查关联项目、预览结果和目标区域，再由用户完成最终确认。

​
执行数据库迁移

在 supabase/migrations/ 下创建以下格式的迁移文件：
前缀必须是严格的 14 位 yyyyMMddHHmmss 时间戳，例如：
时间戳前缀用于确定迁移回放顺序，在同一个项目中必须唯一。禁止使用 Unix 时间戳、带分隔符的日期、缩短日期或其他位数的前缀。创建迁移前先检查已有文件名；如果时间戳已存在，请生成一个更晚的时间戳，不要复用。 然后执行远端还不存在的迁移：
CLI 会先拉取远端基线并找出待执行迁移。只要任一新增 SQL 文件名没有严格的 14 位时间戳前缀，或待执行迁移与其他待执行迁移、远端已有迁移复用了时间戳，整批任务就会在执行任何 SQL 前中止。校验通过后才按时间戳升序执行，遇到第一个失败后停止。迁移成功后，服务端会自动将文件保存为项目附件。不要通过 sxq push 推送迁移文件，CLI 会直接拦截。

​
命令速查

在 CI 或 AI 智能体中，只有在完整推送清单已被核对和授权后才能添加 -y。在非交互环境中，不带 -y 的推送会在提交前报错，不会一直等待输入。正式发布始终需要用户在浏览器页面确认。

npm 上的苏小强 CLI

查看已发布的软件包和当前版本。

源代码

阅读完整参考资料或提交问题。