@sokeai/cli 1.0.77 → 1.0.79

package/skills/multi/soke-material/references/shared.md

@@ -0,0 +1,185 @@
+---
+name: soke-shared
+summary: 授客CLI共享基础（配置/登录/权限/错误处理/安全规则）
+version: 1.0.0
+description: "授客CLI共享基础：应用配置初始化、认证登录（auth login）、权限管理、错误处理、安全规则。当用户需要第一次配置（soke-cli auth login）、使用登录授权（soke-cli auth login）、遇到权限不足、或首次使用soke-cli时触发。"
+---
+
+# soke-cli 共享规则
+
+本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `soke-cli auth login` 完成应用配置。
+
+当你帮用户初始化配置时，引导用户按照交互式提示完成配置：
+
+```bash
+# 初始化配置
+soke-cli auth login
+```
+
+配置项包括：
+- `app_id`: 开放平台应用ID
+- `app_key`: 开放平台应用Key
+- `app_secret`: 开放平台应用Secret
+- `api_base_url`: API地址（默认: https://opendev.soke.cn）
+- `corpid`: 企业ID
+
+配置文件保存在 `~/.soke-cli/config.json`
+
+## 认证
+
+### 用户登录
+
+用户需要通过OAuth授权获取访问令牌：
+
+```bash
+# 用户登录授权
+soke-cli auth login
+```
+
+登录成功后，`access_token` 和 `refresh_token` 会自动保存到配置文件中。
+
+### Token管理
+
+- **access_token**: 用户访问令牌，用于调用API
+- **refresh_token**: 刷新令牌，用于获取新的access_token
+- Token过期后需要重新执行 `soke-cli auth login`
+
+### 查看当前配置
+
+```bash
+# 查看当前配置（不显示敏感信息）
+soke-cli config show
+```
+
+## 权限不足处理
+
+遇到权限相关错误时，通常有以下几种情况：
+
+### 1. 未登录或Token过期
+
+**错误特征**: 返回401 Unauthorized或Token无效
+
+**解决方案**:
+```bash
+soke-cli auth login
+```
+
+### 2. 缺少必要权限
+
+**错误特征**: 返回403 Forbidden或权限不足提示
+
+**解决方案**:
+- 联系管理员在开放平台后台为应用开通相应权限
+- 确认企业ID（corpid）和应用配置正确
+
+### 3. 参数错误
+
+**错误特征**: 返回400 Bad Request或参数验证失败
+
+**解决方案**:
+- 检查必需参数是否提供
+- 使用 `--help` 查看命令参数说明
+- 参考API文档确认参数格式
+
+## 命令结构
+
+### Shortcuts（推荐）
+
+Shortcuts是对常用操作的高级封装，参数友好，最适合AI Agent调用：
+
+```bash
+soke-cli <service> +<verb> [flags]
+```
+
+示例：
+```bash
+soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
+soke-cli course +list-courses --page 1 --page-size 10
+```
+
+### 通用API调用
+
+支持直接调用任意API：
+
+```bash
+soke-cli api <METHOD> <path> [--data <json>] [--params <json>]
+```
+
+示例：
+```bash
+soke-cli api GET /users/me
+soke-cli api POST /some/endpoint --data '{"key": "value"}'
+```
+
+## 输出格式
+
+### JSON格式（默认）
+
+所有命令默认输出JSON格式，便于程序解析：
+
+```bash
+soke-cli exam +list-exams --format json
+```
+
+### 表格格式
+
+部分命令支持表格格式输出，更易读：
+
+```bash
+soke-cli exam +list-exams --format table
+```
+
+## 安全规则
+
+- **禁止输出密钥**（app_secret、access_token）到终端明文
+- **写入/删除操作前必须确认用户意图**
+- 敏感操作建议先使用 `--dry-run`（如果支持）预览
+
+## 错误处理
+
+当命令执行失败时：
+
+1. **检查配置**: 运行 `soke-cli config show` 确认配置正确
+2. **检查登录状态**: 如果是认证错误，运行 `soke-cli auth login`
+3. **检查参数**: 使用 `soke-cli <service> <command> --help` 查看参数说明
+4. **查看错误信息**: 错误响应中通常包含详细的错误原因
+
+## 常见问题
+
+### Q: 如何获取app_key和app_secret？
+
+A: 登录授客AI开放平台（https://opendev.soke.cn），创建应用后即可获取。
+
+### Q: Token过期了怎么办？
+
+A: 重新执行 `soke-cli auth login` 进行授权。
+
+### Q: 如何切换企业？
+
+A: 运行 `soke-cli auth login` 重新配置，或直接编辑 `~/.soke-cli/config.json` 文件。
+
+### Q: 支持哪些业务模块？
+
+A: 目前支持以下模块：
+- `contact`: 组织架构（部门、用户、岗位、讲师）
+- `course`: 课程管理
+- `exam`: 考试管理
+- `training`: 培训管理
+- `learning_map`: 学习地图
+- `credit`: 学分管理
+- `point`: 积分管理
+- `news`: 资讯管理
+- `certificate`: 证书管理
+- 等等...
+
+每个模块都有对应的Skill，AI Agent会根据用户意图自动选择。
+
+## 相关链接
+
+- 授客AI开放平台: https://opendev.soke.cn
+- NPM包: @sokeai/cli
+- 代码仓库: https://codeup.aliyun.com/5edbc121d1d1abe63b55f1c7/soke/soke-cli.git

package/skills/multi/soke-photo-gallery/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: soke-photo-gallery
+description: "授客图片库管理：查询图片分类列表、查询图片库列表、上传本地图片到图片库（自动先上传 OSS 再创建记录）、批量删除图片。当用户需要管理图片库、上传图片、查询图片、删除图片时使用。 | Soke photo gallery management: query image category lists, query photo gallery lists, upload local images to the gallery (automatically uploads to OSS first, then creates the record), and batch delete images. Use when users need to manage the photo gallery, upload images, query images, or delete images."
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli photo-gallery --help"
+---
+
+# 图片库管理 (soke-photo-gallery)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`./references/shared.md`](./references/shared.md)，其中包含认证、配置、权限处理**
+
+## 使用前提
+
+1. 已安装 `soke-cli`
+2. 已登录授权: `soke-cli auth login`
+
+```bash
+soke-cli auth login
+soke-cli config show  # 验证登录状态
+```
+
+## 核心概念
+
+- **图片库（Photo Gallery）**: 企业统一管理图片资源的模块
+- **分类（Category）**: 图片可以归属到某个分类，树形结构，`parent_id="1"` 为顶级
+- **OSS 上传**: 图片文件先上传到阿里云 OSS，再将 OSS 路径注册到图片库
+
+## 端到端工作流
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ 1. (可选) 查询分类  →  获取 category-id                      │
+│ 2. 上传图片        →  本地文件 → OSS → 图片库记录             │
+│ 3. 查询图片列表    →  验证上传结果                            │
+│ 3.1 查询图片详情   →  获取单张图片完整 URL                     │
+│ 4. (可选) 批量删除 →  清理图片                                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 步骤1: 查询图片分类（可选）
+
+上传时如需归入某个分类，先查询分类 ID。
+
+```bash
+soke-cli photo-gallery +list-categories
+
+# JSON 输出供解析:
+soke-cli photo-gallery +list-categories --format json
+```
+
+**响应关键字段**:
+- `data.list.all[].uuid` → 分类 ID（上传时传入 `--category-id`）
+- `data.list.all[].title` → 分类名称
+- `data.list.all[].parent_id` → 父分类 ID，`"1"` 为顶级
+
+**参数**:
+| 参数 | 必填 | 默认 | 说明 |
+|------|------|------|------|
+| `--page` | 否 | 1 | 页码 |
+| `--limit` | 否 | 100 | 每页数量 |
+
+---
+
+## 步骤2: 上传图片到图片库
+
+`+create` 命令自动完成两步操作：
+1. 调用 OSS 上传脚本将本地文件上传到阿里云 OSS
+2. 调用图片库创建接口将 OSS 路径注册到图片库
+
+```bash
+# 上传图片，不指定分类
+soke-cli photo-gallery +create \
+  --file "./banner.png" \
+  --title "首页横幅"
+
+# 上传图片，指定分类
+soke-cli photo-gallery +create \
+  --file "./banner.png" \
+  --title "首页横幅" \
+  --category-id "CATEGORY-UUID"
+
+# JSON 输出
+soke-cli photo-gallery +create \
+  --file "./banner.png" \
+  --title "首页横幅" \
+  --format json
+```
+
+**参数**:
+| 参数 | 必填 | 默认 | 说明 |
+|------|------|------|------|
+| `--file` | 是 | — | 本地图片文件路径（支持 jpg/jpeg/png，最大 5 MB） |
+| `--title` | 是 | — | 图片标题 |
+| `--category-id` | 否 | empty | 分类 ID，不填则归入「未分类」 |
+
+**响应提取**:
+- `data.uuid` → 图片 UUID（批量删除时使用）
+- `data.object` → OSS 对象路径
+- `data.filename` → 文件名
+
+**支持的图片格式**: jpg、jpeg、png（最大 5 MB）
+
+---
+
+## 步骤3: 查询图片库列表
+
+```bash
+# 查询全部图片
+soke-cli photo-gallery +list
+
+# 按分类筛选
+soke-cli photo-gallery +list --category-id "CATEGORY-UUID"
+
+# 按文件名关键词搜索
+soke-cli photo-gallery +list --file-keyword "banner"
+
+# 分页
+soke-cli photo-gallery +list --page 1 --limit 20
+
+# JSON 输出
+soke-cli photo-gallery +list --format json
+```
+
+**参数**:
+| 参数 | 必填 | 默认 | 说明 |
+|------|------|------|------|
+| `--page` | 否 | 1 | 页码 |
+| `--limit` | 否 | 20 | 每页数量 |
+| `--category-id` | 否 | — | 分类 ID 筛选 |
+| `--file-keyword` | 否 | — | 文件名关键词搜索 |
+| `--from` | 否 | — | 来源筛选 |
+
+**响应关键字段**:
+- `data.list[].uuid` → 图片 UUID（删除时使用）
+- `data.list[].filename` → 文件名
+- `data.list[].photoUri` → 图片访问 URL
+- `data.list[].category_title` → 所属分类名称
+- `data.count` → 总数量
+
+---
+
+## 步骤3.1: 获取图片详情
+
+```bash
+# 获取单张图片详情（含完整访问 URL）
+soke-cli photo-gallery +get --uuid "IMAGE-UUID"
+
+# JSON 输出
+soke-cli photo-gallery +get --uuid "IMAGE-UUID" --format json
+```
+
+**参数**:
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--uuid` | 是 | 图片 UUID |
+
+**响应关键字段**:
+- `data.uuid` → 图片 UUID
+- `data.storage` → 存储类型（aliyun）
+- `data.photoUri` → 图片完整访问 URL
+
+---
+
+## 步骤4: 批量删除图片（可选）
+
+```bash
+# 删除单张图片
+soke-cli photo-gallery +batch-delete --uuids "IMAGE-UUID"
+
+# 批量删除多张图片（逗号分隔）
+soke-cli photo-gallery +batch-delete --uuids "UUID1,UUID2,UUID3"
+```
+
+**参数**:
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--uuids` | 是 | 图片 UUID，多个用逗号分隔 |
+
+> **注意**: 删除操作不可恢复，执行前请确认 UUID 正确。
+
+---
+
+## 可用命令全览
+
+| 命令 | 说明 | 风险 |
+|------|------|------|
+| `+list-categories` | 查询图片分类列表 | read |
+| `+list` | 查询图片库列表 | read |
+| `+get` | 获取图片详情（含完整访问 URL） | read |
+| `+create` | 上传图片到图片库 | write |
+| `+batch-delete` | 批量删除图片 | write |
+
+---
+
+## 完整示例
+
+```bash
+# === 1. 查询分类，选一个合适的分类 ===
+soke-cli photo-gallery +list-categories --format json
+
+# === 2. 上传图片 ===
+RESULT=$(soke-cli photo-gallery +create \
+  --file "./logo.png" \
+  --title "公司Logo" \
+  --category-id "CATEGORY-UUID" \
+  --format json)
+
+IMAGE_UUID=$(echo "$RESULT" | jq -r '.data.uuid')
+echo "图片UUID: $IMAGE_UUID"
+
+# === 3. 验证上传结果 ===
+soke-cli photo-gallery +list --file-keyword "logo" --format json
+
+# === 3.1 获取图片详情和访问 URL ===
+soke-cli photo-gallery +get --uuid "$IMAGE_UUID" --format json
+
+# === 4. 批量上传 ===
+for img in banner.jpg logo.png icon.png; do
+  soke-cli photo-gallery +create \
+    --file "./$img" \
+    --title "${img%.*}" \
+    --category-id "CATEGORY-UUID"
+done
+
+# === 5. 清理不需要的图片 ===
+soke-cli photo-gallery +batch-delete --uuids "$IMAGE_UUID"
+```
+
+---
+
+## API 接口映射
+
+| CLI 命令 | API 路径 | 方法 |
+|----------|----------|------|
+| `+list-categories` | `/skills/photoGallery/category/list` | GET |
+| `+list` | `/skills/photoGallery/list` | GET |
+| `+get` | `/skills/photoGallery/detail/{uuid}` | GET |
+| `+create` | OSS 上传 + `/skills/photoGallery/create` | POST |
+| `+batch-delete` | `/skills/photoGallery/batchDelete` | DELETE |
+
+---
+
+## 调试与故障排除
+
+### 常见错误速查
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `未登录授权` | Token 过期 | `soke-cli auth login` |
+| `文件不存在` | 路径错误 | 使用绝对路径或检查相对路径 |
+| `OSS上传失败` | 网络问题或 Token 失效 | 重新登录后重试 |
+| `不支持的图片格式` | 文件非 jpg/jpeg/png | 转换为支持的格式后重试 |
+| `文件大小超过限制` | 文件超过 5 MB | 压缩图片后重试 |
+
+### 调试检查清单
+
+```bash
+# 1. 确认登录状态
+soke-cli config show
+
+# 2. 查询图片列表确认上传成功
+soke-cli photo-gallery +list --format json | jq '.data.list[0]'
+
+# 3. 始终使用 --format json 获取结构化输出
+soke-cli photo-gallery +list --format json
+```
+
+---
+
+## 注意事项
+
+1. **上传图片是两步操作**: 先 OSS 上传再注册图片库，两步都必须成功
+2. **格式限制**: 仅支持 jpg/jpeg/png，其他格式会在上传前报错
+3. **大小限制**: 单张图片不超过 5 MB，超过会在上传前报错
+4. **删除不可恢复**: `+batch-delete` 执行前请确认 UUID 正确
+5. **分类 ID 可选**: 不指定 `--category-id` 时图片归入「未分类」（category_id="empty"）
+
+## 相关文档
+
+- [`./references/shared.md`](./references/shared.md) — 认证、配置、权限