@qcplay/cli 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qcplay/cli",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "QCPlay CLI",
   "type": "module",
   "bin": {

package/templates/skills/qcplay-auth/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: qcplay-auth
+version: 1.0.0
+description: "QCPlay 登录认证：Use when user mentions 登录、认证、auth、权限查询、检查登录状态、退出登录、浏览器登录、access_token、auth.json 等；use for QCPlay authentication workflow only."
+metadata:
+  requires:
+    bins: ["qcplay", "qcplay-cli"]
+    native_bins: ["qcplay-auth.exe", "qcplay-auth-darwin-arm64"]
+  cliHelp: "qcplay auth --help"
+  authFile: "~/.qcplay/auth.json"
+  loginCommand: "qcplay auth"
+  statusCommand: "qcplay auth status"
+  logoutCommand: "qcplay auth logout"
+  permissionsCommand: "qcplay auth permissions"
+---
+
+# qcplay auth
+
+## CRITICAL — 认证工作流，必须遵循
+
+本 Skill 用于通过 QCPlay CLI 完成登录认证、检查登录状态、退出登录和查询权限。
+
+认证由本地原生程序 `qcplay-auth` 完成，CLI 只负责统一入口和状态检查。
+
+用户常用命令：
+
+```bash
+qcplay auth
+```
+
+或者：
+
+```bash
+qcplay-cli auth
+```
+
+## 核心命令
+
+### 1. 登录
+
+```bash
+qcplay auth
+```
+
+或：
+
+```bash
+qcplay-cli auth
+```
+
+当前程序行为：
+
+1. 打开浏览器登录窗口
+2. 用户在浏览器中完成登录
+3. 本地生成认证文件 `~/.qcplay/auth.json`
+
+### 2. 检查登录状态
+
+```bash
+qcplay auth status
+```
+
+或：
+
+```bash
+qcplay-cli auth status
+```
+
+如果已登录，当前 CLI 会输出：
+
+```txt
+已登录
+```
+
+如果未登录或登录无效，当前 CLI 会输出：
+
+```txt
+未登录或登录无效
+原因: ...
+
+请执行:
+  qcplay-cli auth
+```
+
+### 3. 退出登录
+
+```bash
+qcplay auth logout
+```
+
+或：
+
+```bash
+qcplay-cli auth logout
+```
+
+该命令会删除本地认证文件，并输出：
+
+```txt
+已退出登录
+```
+
+### 4. 查询权限
+
+```bash
+qcplay auth permissions
+```
+
+支持参数：
+
+```bash
+qcplay auth permissions --key <key>
+qcplay auth permissions --json
+```
+
+如果未登录，不得伪造权限结果，必须先提示用户登录。
+
+## 认证文件
+
+认证文件固定读取：
+
+```bash
+~/.qcplay/auth.json
+```
+
+Windows 示例：
+
+```bash
+C:\Users\Administrator\.qcplay\auth.json
+```
+
+macOS 示例：
+
+```bash
+/Users/<your-name>/.qcplay/auth.json
+```
+
+Linux 示例：
+
+```bash
+/home/<your-name>/.qcplay/auth.json
+```
+
+认证文件中至少需要存在有效的 `access_token`。
+
+当前 CLI 同时兼容这些字段命名：
+
+- `access_token`
+- `accessToken`
+- `token`
+- `data.access_token`
+- `data.accessToken`
+
+如果存在 `expires_at` / `expiresAt`，程序会同时兼容秒级和毫秒级时间戳。
+
+## Agent 执行要求
+
+当 AI Agent 帮用户处理认证时，必须遵守：
+
+1. 不要要求用户手动复制 `access_token`。
+2. 不要要求用户手动编辑 `auth.json`。
+3. 不要在终端输出完整 `access_token` 或 `refresh_token`。
+4. 如果浏览器登录尚未完成，不要谎报“已登录”。
+5. 如果用户只是想验证登录状态，优先执行 `qcplay auth status`。
+6. 如果用户只是想重新登录，优先执行 `qcplay auth`。
+
+## 安装联动
+
+执行下面命令时，也会自动触发登录：
+
+```bash
+qcplay install
+```
+
+或：
+
+```bash
+qcplay-cli install
+```
+
+因此，如果用户正在首次安装 QCPlay CLI，通常不需要再额外执行一次独立的 `auth` 命令。
+
+## 常见失败场景
+
+### 1. 认证文件不存在
+
+当前 CLI 会提示类似：
+
+```txt
+未登录或登录无效
+原因: 认证文件不存在: ~/.qcplay/auth.json
+```
+
+处理方式：
+
+- 提示用户执行 `qcplay auth`
+- 等待浏览器登录完成
+
+### 2. 认证文件不是合法 JSON
+
+当前 CLI 会提示类似：
+
+```txt
+原因: 认证文件不是合法 JSON: ...
+```
+
+处理方式：
+
+- 不要手改文件内容
+- 直接重新执行 `qcplay auth`
+
+### 3. 认证文件里没有 access_token
+
+当前 CLI 会提示类似：
+
+```txt
+原因: 认证文件中没有找到 access_token
+```
+
+处理方式：
+
+- 直接重新执行 `qcplay auth`
+
+### 4. 登录状态已过期
+
+当前 CLI 会提示类似：
+
+```txt
+原因: 登录状态已过期: ...
+```
+
+处理方式：
+
+- 重新执行 `qcplay auth`
+
+### 5. 本地认证程序不存在
+
+如果底层 `qcplay-auth` 原生程序不存在，CLI 会报错：
+
+```txt
+执行程序不存在: ...
+```
+
+这说明当前平台的原生文件未正确打包或未提供，不要伪造认证成功。
+
+## 禁止行为
+
+禁止：
+
+1. 未完成浏览器登录就声称认证成功。
+2. 让用户把 token 明文发到聊天里。
+3. 在项目目录中另存一份 token。
+4. 登录失败时伪造“已登录”状态。
+5. 未登录时伪造权限查询结果。
+
+## 最短操作建议
+
+如果用户只说“帮我登录 QCPlay”，默认执行：
+
+```bash
+qcplay-cli auth
+```
+
+如果用户只说“帮我看看现在有没有登录”，默认执行：
+
+```bash
+qcplay-cli auth status
+```