Skill: awsl1110/qinglong-skill (version 0.1.1)

--- name: qinglong description: 青龙面板管理助手。当用户需要操作青龙面板（定时任务/环境变量/脚本/订阅/依赖/系统设置）时触发。支持自然语言操作，例如："列出所有任务"、"添加环境变量"、"运行任务"、"查看日志"等。 argument-hint: "操作描述，例如: 列出所有环境变量 / 运行任务 123" allowed-tools: Bash, WebFetch, Read, Write, Edit --- # 青龙面板管理助手 你是一个青龙面板（Qinglong Panel）API 操作专家。用户通过自然语言描述需求，你负责调用对应的 HTTP API 完成任务。 ## 工作流程 ### 第一步：获取连接配置 首先检查用户是否已提供青龙面板地址和认证信息。如果没有，询问： ``` 请提供： 1. 青龙面板地址（例如: http://192.168.1.100:5700） 2. 登录账号和密码（推荐），或 client_id + client_secret ``` ### 第二步：获取 Token **方式一（推荐）：账号密码登录获取 JWT** ```bash curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"username":"<USER>","password":"<PASS>"}' \ "http://<HOST>/api/user/login" ``` 返回示例：`{"code":200,"data":{"token":"eyJ...","token_type":"Bearer"}}` **方式二：应用 Token（注意：Qinglong 2.20.x 存在 bug，open API 返回 UUID 格式 token，调用 `/open/*` 接口时报 `jwt malformed`，建议使用方式一）** ```bash curl -s "http://<HOST>/open/auth/token?client_id=<ID>&client_secret=<SECRET>" ``` 若收到 `jwt malformed` 错误，立即切换为方式一。 ### 第三步：理解用户需求 分析 `$ARGUMENTS` 或用户消息，判断操作类型： | 关键词 | 操作模块 | |--------|---------| | 任务、定时、cron | 定时任务管理 | | 环境变量、变量、env | 环境变量管理 | | 脚本、script | 脚本管理 | | 订阅、subscription | 订阅管理 | | 依赖、dependency | 依赖管理 | | 系统、通知、命令 | 系统设置 | ### 第四步：执行 API 调用 使用 Bash 工具通过 `curl` 执行 API 请求。标准请求格式： ```bash curl -s -X <METHOD> \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-Type: application/json" \ -d '<JSON_BODY>' \ "http://<HOST>/api/<ENDPOINT>" ``` 详细 API 参考见 [api-reference.md](api-reference.md)。 ### 第五步：解析并展示结果 - 成功响应格式：`{"code": 200, "data": ...}` - 以表格或清单形式展示结果 - 如有错误，说明原因并提供解决建议 --- ## 常用操作快速参考 ### 获取 Token（账号密码） ```bash curl -s -X POST -H "Content-Type: application/json" \ -d '{"username":"<USER>","password":"<PASS>"}' \ "http://<HOST>/api/user/login" ``` ### 定时任务 ```bash # 列出所有任务 curl -s -H "Authorization: Bearer <TOKEN>" "http://<HOST>/api/crons" # 运行任务（id数组） curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[<id1>, <id2>]' "http://<HOST>/api/crons/run" # 停止任务 curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[<id>]' "http://<HOST>/api/crons/stop" # 创建任务 curl -s -X POST -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '{"name":"任务名","command":"task xxx.js","schedule":"0 9 * * *"}' \ "http://<HOST>/api/crons" # 删除任务（id数组） curl -s -X DELETE -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[<id>]' "http://<HOST>/api/crons" # 查看任务日志 curl -s -H "Authorization: Bearer <TOKEN>" "http://<HOST>/api/crons/<id>/log" ``` ### 环境变量 ```bash # 列出所有变量（支持搜索） curl -s -H "Authorization: Bearer <TOKEN>" "http://<HOST>/api/envs?searchValue=<keyword>" # 新增变量（数组，支持批量） curl -s -X POST -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[{"name":"变量名","value":"变量值","remarks":"备注"}]' "http://<HOST>/api/envs" # 修改变量 curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '{"id":<id>,"name":"变量名","value":"新值","remarks":"备注"}' "http://<HOST>/api/envs" # 删除变量（id数组） curl -s -X DELETE -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[<id>]' "http://<HOST>/api/envs" # 启用/禁用变量 curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '[<id>]' "http://<HOST>/api/envs/enable" ``` ### 脚本管理 ```bash # 列出脚本 curl -s -H "Authorization: Bearer <TOKEN>" "http://<HOST>/api/scripts" # 查看脚本内容 curl -s -H "Authorization: Bearer <TOKEN>" "http://<HOST>/api/scripts/detail?filename=<name>&path=<dir>" # 运行脚本 curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '{"filename":"xxx.js","path":""}' "http://<HOST>/api/scripts/run" ``` ### 系统通知 ```bash curl -s -X PUT -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '{"title":"标题","content":"内容"}' "http://<HOST>/api/system/notify" ``` --- ## 注意事项 1. **认证优先级**：优先使用账号密码获取 JWT，Qinglong 2.20.x 的应用 Token（open API）存在 `jwt malformed` bug 2. **ID 格式**：批量操作接口接受 ID 数组 `[1, 2, 3]`，单个操作传 `[id]` 3. **Cron 表达式**：创建任务时 `schedule` 字段使用标准 5 位 cron 表达式 4. **变量命名**：环境变量名必须以字母或下划线开头，只含字母/数字/下划线 5. **错误处理**：若返回非 200，检查 Token 是否过期，必要时重新获取 6. **安全提示**：Token 具有完整操作权限，注意保密 如需了解完整 API 列表，参考 [api-reference.md](api-reference.md)。

path: api-reference.md
content: # 青龙面板 API 完整参考

官方文档：https://qinglong.online/api/

所有 API 基础路径：`http://<HOST>/api`
认证方式：`Authorization: Bearer <TOKEN>`
响应格式：`{"code": 200, "data": <结果>}`

---

## 认证

### 获取 Token
```
GET /open/auth/token?client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>
```
返回：`{"token": "xxx", "token_type": "Bearer", "expiration": 1234567890}`

> 注意：所有开放 API 接口的基础路径为 `/open`，获取 token 后在 Header 中携带 `Authorization: Bearer <token>`

---

## 定时任务 `/crons`

### 任务 CRUD

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/crons` | 列出所有任务 | - |
| GET | `/crons/:id` | 获取单个任务 | - |
| GET | `/crons/detail` | 获取任务详情 | query: `?id=` |
| POST | `/crons` | 创建任务 | `{name, command, schedule, labels?}` |
| PUT | `/crons` | 更新任务 | `{id, name, command, schedule, ...}` |
| DELETE | `/crons` | 删除任务 | `[id1, id2, ...]` |

**创建任务请求体示例：**
```json
{
  "name": "签到任务",
  "command": "task jd_sign.js",
  "schedule": "30 0 * * *",
  "labels": ["签到"]
}
```

### 任务控制

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| PUT | `/crons/run` | 运行任务 | `[id1, id2, ...]` |
| PUT | `/crons/stop` | 停止任务 | `[id1, id2, ...]` |
| PUT | `/crons/enable` | 启用任务 | `[id1, id2, ...]` |
| PUT | `/crons/disable` | 禁用任务 | `[id1, id2, ...]` |
| PUT | `/crons/pin` | 置顶任务 | `[id1, id2, ...]` |
| PUT | `/crons/unpin` | 取消置顶 | `[id1, id2, ...]` |

### 任务日志

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/crons/:id/log` | 获取最新日志 |
| GET | `/crons/:id/logs` | 获取全部日志记录 |

### 任务标签

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| POST | `/crons/labels` | 添加标签 | `{ids: [...], labels: [...]}` |
| DELETE | `/crons/labels` | 删除标签 | `{ids: [...], labels: [...]}` |

### 视图管理

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/crons/views` | 获取所有视图 | - |
| POST | `/crons/views` | 创建视图 | `{name, sorts?, filters?}` |
| PUT | `/crons/views` | 更新视图 | `{id, name, ...}` |
| DELETE | `/crons/views` | 删除视图 | `[id1, id2, ...]` |
| PUT | `/crons/views/move` | 移动视图 | `{id, fromIndex, toIndex}` |
| PUT | `/crons/views/enable` | 启用视图 | `[id1, id2, ...]` |
| PUT | `/crons/views/disable` | 禁用视图 | `[id1, id2, ...]` |

---

## 环境变量 `/envs`

| 方法 | 路径 | 说明 | 请求参数/体 |
|------|------|------|------------|
| GET | `/envs` | 获取变量列表 | query: `?searchValue=关键词` |
| GET | `/envs/:id` | 获取单个变量 | - |
| POST | `/envs` | 新增变量 | `[{name, value, remarks?}]` |
| PUT | `/envs` | 更新变量 | `{id, name, value, remarks?}` |
| DELETE | `/envs` | 删除变量 | `[id1, id2, ...]` |
| PUT | `/envs/enable` | 启用变量 | `[id1, id2, ...]` |
| PUT | `/envs/disable` | 禁用变量 | `[id1, id2, ...]` |
| PUT | `/envs/name` | 批量重命名 | `{ids: [...], name: "新名称"}` |
| PUT | `/envs/:id/move` | 移动变量排序 | `{fromIndex, toIndex}` |
| POST | `/envs/upload` | 从文件导入 | multipart/form-data (JSON文件) |

**新增变量示例（支持批量）：**
```json
[
  {"name": "JD_COOKIE", "value": "pt_key=xxx;pt_pin=yyy;", "remarks": "京东Cookie"},
  {"name": "BARK_KEY", "value": "your_bark_key", "remarks": "Bark推送"}
]
```

**变量命名规则：** 必须以字母或下划线开头，只能包含字母、数字和下划线。

---

## 订阅管理 `/subscriptions`

| 方法 | 路径 | 说明 | 请求参数/体 |
|------|------|------|------------|
| GET | `/subscriptions` | 获取订阅列表 | query: `?searchValue=&ids=` |
| POST | `/subscriptions` | 创建订阅 | 见下方示例 |
| PUT | `/subscriptions/run` | 运行订阅 | `[id1, id2, ...]` |
| PUT | `/subscriptions/stop` | 停止订阅 | `[id1, id2, ...]` |
| PUT | `/subscriptions/enable` | 启用订阅 | `[id1, id2, ...]` |
| PUT | `/subscriptions/disable` | 禁用订阅 | `[id1, id2, ...]` |
| GET | `/subscriptions/:id/log` | 最新日志 | - |
| GET | `/subscriptions/:id/logs` | 全部日志 | - |
| PUT | `/subscriptions/status` | 更新状态 | `{ids, status, pid?, log_path?}` |

**创建订阅示例（Git订阅）：**
```json
{
  "name": "订阅名称",
  "type": 0,
  "url": "https://github.com/user/repo",
  "branch": "main",
  "schedule": "0 0 * * *",
  "whitelist": "jd_",
  "blacklist": "test",
  "dependenceFile": "",
  "autoAddCron": true,
  "autoDelCron": false
}
```

**订阅类型 `type`：** `0`=公开仓库, `1`=私有仓库, `2`=单文件

---

## 脚本管理 `/scripts`

| 方法 | 路径 | 说明 | 请求参数/体 |
|------|------|------|------------|
| GET | `/scripts` | 获取脚本列表 | query: `?path=目录` |
| GET | `/scripts/detail` | 获取脚本内容 | query: `?filename=&path=` |
| POST | `/scripts` | 上传/创建脚本 | `{filename, content, path?}` 或 multipart |
| PUT | `/scripts` | 更新脚本内容 | `{filename, content, path?}` |
| DELETE | `/scripts` | 删除脚本 | `{filename, path?}` |
| POST | `/scripts/download` | 下载脚本 | `{filename, path?}` |
| PUT | `/scripts/run` | 运行脚本 | `{filename, path?}` |
| PUT | `/scripts/stop` | 停止脚本 | `{filename?, pid?}` |
| PUT | `/scripts/rename` | 重命名脚本 | `{filename, newFilename, path?}` |

---

## 依赖管理 `/dependencies`

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/dependencies` | 获取依赖列表 | query: `?searchValue=&type=` |
| GET | `/dependencies/:id` | 获取单个依赖 | - |
| POST | `/dependencies` | 新增依赖 | `{name, type, remark?}` |
| PUT | `/dependencies` | 更新依赖 | `{id, name, type, remark?}` |
| DELETE | `/dependencies` | 删除依赖 | `[id1, id2, ...]` |
| DELETE | `/dependencies/force` | 强制删除 | `[id1, id2, ...]` |
| PUT | `/dependencies/reinstall` | 重新安装 | `[id1, id2, ...]` |
| PUT | `/dependencies/cancel` | 取消安装 | `[id1, id2, ...]` |

**依赖类型 `type`：** `0`=NodeJS, `1`=Python3, `2`=Linux

---

## 配置文件 `/configs`

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/configs` | 获取配置文件列表 | - |
| GET | `/configs/detail` | 获取配置内容 | query: `?filename=` |
| PUT | `/configs` | 更新配置内容 | `{filename, content}` |
| GET | `/configs/:name` | 获取指定配置 | - |

---

## 系统设置 `/system`

### 系统信息与配置

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/system` | 系统状态和版本信息 | - |
| GET | `/system/config` | 获取系统配置 | - |
| PUT | `/system/config/log-remove-frequency` | 设置日志清理频率 | `{frequency: <天数>}` |
| PUT | `/system/config/cron-concurrency` | 设置任务并发数 | `{concurrency: <数量>}` |
| PUT | `/system/config/dependence-proxy` | 设置依赖代理 | `{proxy: "http://..."}` |
| PUT | `/system/config/node-mirror` | 设置Node镜像 | `{url: "https://..."}` |
| PUT | `/system/config/python-mirror` | 设置Python镜像 | `{url: "https://..."}` |
| PUT | `/system/config/linux-mirror` | 设置Linux镜像 | `{url: "https://..."}` |

### 系统操作

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| PUT | `/system/update-check` | 检查更新 | - |
| PUT | `/system/update` | 执行更新 | - |
| PUT | `/system/reload` | 重载系统 | `{type?: ""}` |
| PUT | `/system/notify` | 发送通知 | `{title, content}` |
| PUT | `/system/command-run` | 执行Shell命令 | `{command: "ls -la"}` |
| PUT | `/system/command-stop` | 停止命令 | `{command?, pid?}` |

### 日志

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|---------|
| GET | `/system/log` | 获取系统日志 | query: `?time=&type=` |
| DELETE | `/system/log` | 删除系统日志 | - |

### 数据导入导出

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | `/system/data/export` | 导出系统数据 |
| PUT | `/system/data/import` | 导入系统数据（multipart/form-data） |

**通知支持渠道（21+）：** Telegram、企业微信、钉钉、飞书、Bark、Gotify、邮件、Server酱、PushPlus、微信推送、自定义Webhook 等。

---

## 错误码说明

| code | 含义 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | Token 无效或过期，需重新获取 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## curl 完整示例合集

### 获取Token并保存
```bash
[REDACTED_SECRET] -s "http://192.168.1.100:5700/api/user/login?client_id=xxx&client_secret=yyy" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['token'])")
```

### 批量查看任务状态（格式化输出）
```bash
curl -s -H "Authorization: Bearer $TOKEN" "http://192.168.1.100:5700/api/crons" | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for c in data.get('data', data) if isinstance(data, dict) else data:
    status = ['空闲','运行中','停止'][c.get('status',0)] if c.get('status',0) < 3 else '未知'
    print(f\"ID:{c['id']:4d} | {status:4s} | {c.get('schedule',''):15s} | {c.get('name','')}\")
"
```

### 搜索并运行指定名称任务
```bash
# 搜索任务ID
IDS=$(curl -s -H "Authorization: Bearer $TOKEN" "http://<HOST>/api/crons" | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
tasks = data.get('data', data) if isinstance(data, dict) else data
ids = [str(t['id']) for t in tasks if '签到' in t.get('name','')]
print(json.dumps([int(i) for i in ids]))
")
# 运行
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "$IDS" "http://<HOST>/api/crons/run"
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)