quickdev-cli

Quick Dev 平台命令行工具（可执行名 quickdev）。面向 AI 模型设计：所有命令输出单行 JSON 信封，可直接通过 shell 驱动，用于建项目 / 挂应用 / 建分支。

环境要求

• Node.js >= 18
• macOS（凭证存储在系统 Keychain，依赖内置 security 命令；其他平台会明确报错）

安装

从 npm 全局安装（安装时 postinstall 会自动安装 AI skill，见下）：

npm i -g @quickcep/quickdev-cli

或在仓库内本地构建：

npm install
npm run build      # tsc 编译到 dist/
npm link           # 可选：把 quickdev 链接到全局

安装后使用 quickdev 命令。也可以直接用 node dist/index.js。

单文件可执行（需安装 Bun）：

npm run build:bin  # 产出 ./quickdev 独立二进制

AI Skill（自动安装到各 agent 工具）

安装本包时，postinstall 会自动把 quick-dev-cli skill 安装到本机所有 agent 工具（Claude / opencode / Junie 等）：

npx -y skills add [email protected]:jingshuai/skills.git -y -g --all

若安装脚本被跳过（如 --ignore-scripts）或想手动刷新，可执行：

quickdev skills install   # 安装 skill
quickdev skills update    # 更新已安装的 skill

• skill 源仓库：[email protected]:jingshuai/skills.git（结构 skills/quick-dev-cli/SKILL.md）
• 规范位置：~/.agents/skills/quick-dev-cli/，由 skills 软链到各 agent 目录。

认证

PAT（个人访问令牌）只存于 macOS Keychain（service quick-dev-cli，account = profile 名），密码与临时 JWT 不会落盘。

quickdev auth login            # 默认：打开浏览器完成授权（推荐），自动回跳并存入 PAT
quickdev auth login --password # 回退：在终端交互输入账号 / 密码
quickdev auth status           # 查看当前 profile、apiHost、PAT 前缀、有效期与有效性
quickdev auth logout           # 删除当前 profile 的 Keychain 凭证

浏览器授权流程：CLI 起本地回环服务 → 打开平台登录页 /login?cli_callback=... → 登录后前端调 POST /user/token 生成 PAT 并回跳到本地 → CLI 存入 Keychain。

非交互环境（如 CI / 模型调用）用 --password + 环境变量：

QUICKDEV_ACCOUNT=me QUICKDEV_PASSWORD=*** quickdev auth login --password

多环境 profile

内置 local（http://localhost:7001）与 prod（https://quick-dev.quickcip.com/api），默认使用 prod。

quickdev profile list
quickdev profile add test --host https://quick-dev-test.example.com/api
quickdev profile use prod

命令示例

# 1. 建项目（返回新项目 id）
quickdev project create --name demo --version 1.0.0 --comment "演示项目" --type feat --yes

# 2. 挂应用（触发异步建分支）
quickdev app attach --project-id 42 --application quickcep --application-id 7 --project-version 1.0.0 --yes

# 3. 建分支（异步，不保证立即存在）
quickdev branch create --project-id 42 --application quickcep --application-id 7 --branch feat-x --yes

查询：

quickdev project list --page 1 --size 20
quickdev app list --project-id 42
quickdev branch list --project-id 42 --application quickcep

JSON 契约

所有命令都输出一行 JSON。

成功：

{"ok":true,"data":{...},"error":null}

失败：

{"ok":false,"data":null,"error":{"code":500401,"message":"登录超时","hint":"quickdev auth login"}}

需要确认（写操作缺少 --yes）：

{"ok":false,"data":null,"error":{"type":"confirmation","subtype":"confirmation_required","action":"project.create","message":"..."}}

退出码

| 退出码 | 含义 | |--------|------| | 0 | 成功 | | 1 | 一般错误（校验失败 / 后端失败 / 网络错误 / 认证失败） | | 10 | 写操作缺少 --yes，需要确认（未发起任何请求） |

写操作门禁与预览

• 写命令（project create、app attach、branch create）必须带 --yes，否则以退出码 10 结束且不发送请求。
• 任意命令加 --dry-run 只打印将要发送的请求（method / URL / body）并以退出码 0 结束，不发起网络请求。
• 后端返回 success:false 时，其 code / message 会原样透传到 error。

认证机制

• 请求头使用 token: <PAT>（不是 Authorization: Bearer）。
• PAT 形如 qd_...，明文仅在 auth login 时出现一次。
• 收到 HTTP 401/403 或信封 code:500401 时，CLI 返回可读错误并提示执行 quickdev auth login。

异步分支语义

app attach 与 branch create 会触发 GitLab 侧异步建分支。命令成功时会在输出中附带 note 字段提示「分支为异步创建，不保证立即存在」，请用 branch list 查询确认，不要假设分支已就绪。

开发

npm run build   # tsc 编译
npm run dev     # tsc --watch

参见 AGENTS.md 了解面向 agent 的完整命令面与契约。