@sokeai/cli 1.0.61 → 1.0.63

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

@@ -0,0 +1,287 @@
+---
+name: soke-photo-gallery
+summary: 授客图片库管理（查询分类/图片列表、上传图片、批量删除），上传自动处理 OSS 存储
+version: 1.0.0
+description: "授客图片库管理：查询图片分类列表、查询图片库列表、上传本地图片到图片库（自动先上传 OSS 再创建记录）、批量删除图片。当用户需要管理图片库、上传图片、查询图片、删除图片时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli photo-gallery --help"
+---
+
+# 图片库管理 (soke-photo-gallery)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.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"）
+
+## 相关文档
+
+- [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) — 认证、配置、权限
+- [`../../docs/photo-gallery-api.md`](../../docs/photo-gallery-api.md) — 图片库接口文档

package/skills/oss-upload/skill.md

@@ -1,50 +0,0 @@
----
-name: oss-upload
-description: 上传本地文件到阿里云OSS存储
-skill_version: 1.0.0
----
-
-# OSS文件上传工具
-
-这个skill用于将本地文件上传到阿里云OSS对象存储。
-
-## 功能特性
-
-- 通过授客AI接口动态获取上传签名
-- 支持表单POST方式上传文件（无需安装阿里云SDK）
-- 自动处理认证和签名
-- 支持自定义文件路径
-- 支持进度显示
-
-## 使用方法
-
-```bash
-# 上传单个文件
-soke-cli oss upload <本地文件路径> [--object-name <OSS对象名>]
-
-# 示例
-soke-cli oss upload ./document.pdf
-soke-cli oss upload ./document.pdf --object-name uploads/2024/document.pdf
-```
-
-## 参数说明
-
-- `file`: 本地文件路径（必填）
-- `--object-name`: OSS中的对象名称（可选，默认使用文件名）
-
-## 配置要求
-
-需要先登录授客AI：
-
-```bash
-
-# 用户登录
-soke-cli auth login
-```
-
-## 实现原理
-
-1. 从配置文件读取用户访问令牌（UserToken）
-2. 调用授客AI接口获取OSS上传签名和配置
-3. 使用获取的签名通过表单方式上传文件到OSS
-4. 无需在本地配置OSS密钥，更安全便捷

package/skills/oss-upload/upload.py

@@ -1,355 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-阿里云OSS文件上传工具
-通过授客AI接口获取签名后上传文件
-仅使用Python标准库，无需安装第三方依赖
-"""
-
-import os
-import sys
-import json
-import urllib.request
-import urllib.parse
-import urllib.error
-import mimetypes
-import uuid
-import time
-
-
-MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024  # 2GB
-
-def load_config():
-    """加载配置文件获取access_token"""
-    config_path = os.path.expanduser("~/.soke-cli/config.json")
-    if not os.path.exists(config_path):
-        print("错误: 配置文件不存在，请先运行 'soke-cli config init'")
-        sys.exit(1)
-
-    with open(config_path, 'r', encoding='utf-8') as f:
-        config = json.load(f)
-
-    if 'UserToken' not in config or not config['UserToken']:
-        print("错误: 未找到用户令牌，请先运行 'soke-cli auth login' 登录")
-        sys.exit(1)
-
-    return config
-
-
-def get_upload_signature(access_token, api_base_url, max_retries=3):
-    """从接口获取上传签名和配置"""
-    params = urllib.parse.urlencode({
-        'lang': 'zh',
-        'utcoffset': '-28800'
-    })
-    signature_url = f"{api_base_url}/skills/uploadFile/signature?{params}"
-
-    headers = {
-        'Authorization': f'{access_token}',
-        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
-    }
-
-    for attempt in range(max_retries):
-        try:
-            if attempt > 0:
-                print(f"正在重试... ({attempt + 1}/{max_retries})")
-                time.sleep(2 ** attempt)  # 指数退避: 2s, 4s, 8s
-            else:
-                print("正在获取上传签名...")
-
-            req = urllib.request.Request(signature_url, method='POST', headers=headers)
-
-            with urllib.request.urlopen(req, timeout=30) as response:
-                response_data = response.read().decode('utf-8')
-                result = json.loads(response_data)
-
-            # 检查响应格式
-            # 支持多种格式:
-            # 1. {"code": 0, "message": "success", "data": {...}}
-            # 2. {"code": "get_success", "status": "ok", "message": "获取成功", "data": {...}}
-            # 3. {"success": true, "err_code": 0, "err_message": "success", "data": {...}}
-            code = result.get('code')
-            status = result.get('status', '')
-            success = result.get('success')
-            err_code = result.get('err_code')
-
-            # 判断是否成功
-            is_success = (
-                (isinstance(code, int) and code == 0) or  # 数字格式
-                (isinstance(code, str) and code in ['get_success', 'success']) or  # 字符串格式
-                (status == 'ok') or  # 通过status判断
-                (success is True and err_code == 0)  # success格式
-            )
-
-            if not is_success:
-                print(f"✗ 获取签名失败: {result.get('message', result.get('err_message', '未知错误'))}")
-                return None
-
-            # 提取签名数据
-            data = result.get('data', {})
-            if not data:
-                print("✗ 响应数据为空")
-                return None
-
-            print("✓ 签名获取成功")
-            return data
-
-        except urllib.error.HTTPError as e:
-            error_msg = f"HTTP {e.code} {e.reason}"
-            try:
-                error_body = e.read().decode('utf-8')
-            except:
-                error_body = ""
-
-            # 503/502/504 等服务端错误可以重试
-            if e.code in [502, 503, 504] and attempt < max_retries - 1:
-                print(f"✗ {error_msg} - 服务暂时不可用，将自动重试...")
-                continue
-            else:
-                print(f"✗ HTTP错误: {error_msg}")
-                if error_body:
-                    print(f"响应内容: {error_body}")
-                if e.code == 503:
-                    print("\n提示: 503错误通常表示服务端暂时不可用，请稍后重试")
-                    print("可能的原因:")
-                    print("  1. 服务正在维护或重启")
-                    print("  2. 服务负载过高")
-                    print("  3. 网络连接问题")
-                return None
-
-        except urllib.error.URLError as e:
-            if attempt < max_retries - 1:
-                print(f"✗ 网络错误: {str(e.reason)} - 将自动重试...")
-                continue
-            else:
-                print(f"✗ 请求失败: {str(e.reason)}")
-                return None
-
-        except json.JSONDecodeError as e:
-            print(f"✗ 响应解析失败: {str(e)}")
-            return None
-
-        except Exception as e:
-            print(f"✗ 发生错误: {str(e)}")
-            return None
-
-    print(f"✗ 已重试 {max_retries} 次，仍然失败")
-    return None
-
-
-def create_multipart_form_data(fields, file_path):
-    """创建multipart/form-data格式的请求体"""
-    boundary = f'----WebKitFormBoundary{uuid.uuid4().hex[:16]}'
-
-    body = []
-
-    # 添加表单字段
-    for key, value in fields.items():
-        body.append(f'--{boundary}'.encode())
-        body.append(f'Content-Disposition: form-data; name="{key}"'.encode())
-        body.append(b'')
-        body.append(str(value).encode())
-
-    # 添加文件
-    filename = os.path.basename(file_path)
-    mimetype = mimetypes.guess_type(file_path)[0] or 'application/octet-stream'
-
-    body.append(f'--{boundary}'.encode())
-    body.append(f'Content-Disposition: form-data; name="file"; filename="{filename}"'.encode())
-    body.append(f'Content-Type: {mimetype}'.encode())
-    body.append(b'')
-
-    with open(file_path, 'rb') as f:
-        body.append(f.read())
-
-    body.append(f'--{boundary}--'.encode())
-    body.append(b'')
-
-    content_type = f'multipart/form-data; boundary={boundary}'
-    body_bytes = b'\r\n'.join(body)
-
-    return content_type, body_bytes
-
-
-def upload_file(file_path, object_name, signature_data, corp_id):
-    """上传文件到OSS"""
-    if not os.path.exists(file_path):
-        print(f"错误: 文件不存在: {file_path}")
-        sys.exit(1)
-
-    # 从签名数据中提取上传配置
-    upload_url = signature_data.get('host')
-    access_key_id = signature_data.get('accessid') or signature_data.get('OSSAccessKeyId')
-    policy = signature_data.get('policy')
-    signature = signature_data.get('signature')
-    callback = signature_data.get('callback', '')
-    dir_prefix = signature_data.get('dir', '')
-
-    if not all([upload_url, access_key_id, policy, signature]):
-        print("✗ 签名数据不完整")
-        print(f"签名数据: {json.dumps(signature_data, indent=2, ensure_ascii=False)}")
-        return False
-
-    # 获取文件信息
-    file_size = os.path.getsize(file_path)
-    file_name = os.path.basename(file_path)
-    file_ext = os.path.splitext(file_name)[1].lstrip('.')  # 移除点号，如 pdf
-
-    # 构建完整的对象路径：CorpID/dir_prefix/object_name
-    if corp_id:
-        # 如果有CorpID，添加为顶层目录
-        if dir_prefix:
-            # 移除dir_prefix开头的斜杠（如果有）
-            dir_prefix = dir_prefix.lstrip('/')
-            full_path = f"{corp_id}/{dir_prefix}{object_name}"
-        else:
-            full_path = f"{corp_id}/{object_name}"
-    else:
-        # 如果没有CorpID，使用原逻辑
-        if dir_prefix and not object_name.startswith(dir_prefix):
-            full_path = dir_prefix + object_name
-        else:
-            full_path = object_name
-
-    # 准备表单数据
-    form_fields = {
-        'key': full_path,
-        'policy': policy,
-        'OSSAccessKeyId': access_key_id,
-        'signature': signature,
-        'success_action_status': '200',
-    }
-
-    # 如果有callback，添加到表单
-    if callback:
-        form_fields['callback'] = callback
-
-    # 显示上传信息
-    print(f"\n正在上传文件: {file_path}")
-    print(f"文件名称: {file_name}")
-    print(f"文件大小: {file_size} 字节")
-    print(f"文件后缀: {file_ext if file_ext else '(无后缀)'}")
-    if corp_id:
-        print(f"企业ID: {corp_id}")
-    print(f"目标路径: {full_path}")
-    print(f"上传地址: {upload_url}")
-
-    try:
-        # 创建multipart/form-data请求体
-        content_type, body = create_multipart_form_data(form_fields, file_path)
-
-        headers = {
-            'Content-Type': content_type,
-            'Content-Length': str(len(body))
-        }
-
-        req = urllib.request.Request(upload_url, data=body, headers=headers, method='POST')
-
-        with urllib.request.urlopen(req, timeout=300) as response:
-            response_code = response.getcode()
-            response_body = response.read().decode('utf-8')
-
-        if response_code == 200:
-            file_url = f"{upload_url.rstrip('/')}/{full_path}"
-
-            print(f"\n✓ 上传成功!")
-            print(f"=" * 60)
-            print(f"文件信息:")
-            print(f"  - 文件名: {file_name}")
-            print(f"  - 大小: {file_size} 字节")
-            print(f"  - 后缀: {file_ext if file_ext else '(无后缀)'}")
-            print(f"  - OSS路径: {full_path}")
-            print(f"  - 访问URL: {file_url}")
-            print(f"=" * 60)
-
-            # 如果有callback响应，打印出来
-            if response_body:
-                try:
-                    callback_result = json.loads(response_body)
-                    if callback_result:
-                        print(f"\n回调响应: {json.dumps(callback_result, indent=2, ensure_ascii=False)}")
-                except:
-                    pass
-
-            return True
-        else:
-            print(f"\n✗ 上传失败!")
-            print(f"状态码: {response_code}")
-            print(f"响应内容: {response_body}")
-            return False
-
-    except urllib.error.HTTPError as e:
-        print(f"\n✗ 上传失败: HTTP {e.code} {e.reason}")
-        try:
-            error_body = e.read().decode('utf-8')
-            print(f"响应内容: {error_body}")
-        except:
-            pass
-        return False
-    except urllib.error.URLError as e:
-        print(f"\n✗ 上传失败: {str(e.reason)}")
-        return False
-    except Exception as e:
-        print(f"\n✗ 发生错误: {str(e)}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-def main():
-    """主函数"""
-    if len(sys.argv) < 2:
-        print("用法: python upload.py <本地文件路径> [OSS对象名]")
-        print("示例: python upload.py ./document.pdf uploads/2024/document.pdf")
-        sys.exit(1)
-
-    file_path = sys.argv[1]
-
-    # 检查文件是否存在
-    if not os.path.exists(file_path):
-        print(f"错误: 文件不存在: {file_path}")
-        sys.exit(1)
-
-    # 检查是否是文件（不是目录）
-    if not os.path.isfile(file_path):
-        print(f"错误: 路径不是文件: {file_path}")
-        sys.exit(1)
-
-    # 检查文件大小（不能超过2GB）
-    file_size = os.path.getsize(file_path)
-    if file_size > MAX_FILE_SIZE:
-        print(f"错误: 文件大小超过限制")
-        print(f"  当前大小: {file_size / (1024 * 1024 * 1024):.2f} GB ({file_size} 字节)")
-        print(f"  最大限制: 2 GB ({MAX_FILE_SIZE} 字节)")
-        sys.exit(1)
-
-    # 如果未指定对象名，使用文件名
-    if len(sys.argv) >= 3:
-        object_name = sys.argv[2]
-    else:
-        object_name = os.path.basename(file_path)
-
-    # 加载配置
-    config = load_config()
-    access_token = config.get('UserToken')
-    api_base_url = config.get('APIBaseURL', 'https://app2651.eapps.dingtalkcloud.com/NewSoke')
-    corp_id = config.get('CorpID', '')
-
-    if not corp_id:
-        print("警告: 未找到CorpID配置，文件将上传到根目录")
-        print("建议在配置文件中添加 CorpID 字段")
-
-    # 获取上传签名
-    signature_data = get_upload_signature(access_token, api_base_url)
-    if not signature_data:
-        print("✗ 无法获取上传签名")
-        sys.exit(1)
-
-    # 上传文件
-    success = upload_file(file_path, object_name, signature_data, corp_id)
-
-    sys.exit(0 if success else 1)
-
-
-if __name__ == '__main__':
-    main()