@sokeai/cli 1.0.77 → 1.0.78

package/skills/mono/references/shared/cli-basics.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/mono/scripts/check_readiness.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Check prerequisites for the standalone Mono Skill package."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    package = Path(__file__).resolve().parent.parent
+    guide = package / "references" / "installation.md"
+    executable = shutil.which("soke-cli")
+    print("🔍 soke-cli Mono Skill — 环境检查")
+    print(f"  {'✅' if guide.is_file() else '❌'} 安装指南")
+    if not executable:
+        print("  ❌ soke-cli 未安装")
+        return 1
+    result = subprocess.run([executable, "--version"], capture_output=True, text=True, check=False)
+    print(f"  ✅ soke-cli: {result.stdout.strip() or '已找到'}")
+    print("✅ 环境检查完成")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/mono/scripts/gate_check.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+soke-ai-coach-director · 闸门一次性校验器（v2.42）
+Usage:
+    python3 scripts/gate_check.py /tmp/scenario_get.json
+
+输入：+get-scenario 重定向后的 JSON 文件（自动处理 {data:{...}} 嵌套）
+输出：单行结果 —— 全过输出 "GATE PASS"，否则 "GATE FAIL" + 逐项失败原因
+退出码：0 = 通过，1 = 失败
+
+设计目的：消除闸门阶段逐字段拆轮探查（历史实测浪费 ~8 积分）。
+AI 只需跑这一个脚本，禁止再用 Python 逐步看返回结构。
+"""
+
+import json
+import sys
+
+
+def unwrap(raw):
+    """处理 CLI 返回的可能嵌套：{data:{...}} / {code,data} / 裸对象。"""
+    if not isinstance(raw, dict):
+        return raw
+    d = raw.get("data")
+    if isinstance(d, dict):
+        return d
+    return raw
+
+
+def check(sc: dict) -> list:
+    errs = []
+
+    # ---------- Step 8 发布闸门（4 项，任一缺失禁止发布） ----------
+
+    # 1. 封面 = 固定默认图（非空且正确前缀）
+    cover = sc.get("scenario_cover") or sc.get("cover")
+    if not cover or "roles_avatars" in str(cover) or not str(cover).startswith("http"):
+        errs.append(f"[发布1] 封面缺失或非法: {cover!r:.80}")
+
+    # 2/3. 全部角色 avatar / voice_id 非空
+    roles = sc.get("ai_roles") or []
+    if not roles:
+        errs.append("[发布2] ai_roles 为空")
+    for i, r in enumerate(roles):
+        rd = r.get("role_data") or r
+        av = rd.get("avatar")
+        vi = rd.get("voice_id")
+        if not av or not str(av).startswith("http"):
+            errs.append(f"[发布2] 角色{i}({rd.get('name','?')}) avatar 非法: {av!r:.60}")
+        if not vi:
+            errs.append(f"[发布3] 角色{i}({rd.get('name','?')}) voice_id 为空")
+
+    # 4. 无"角色数据异常"：OS 存在且足够长
+    os_text = sc.get("ai_roles_overall_description") or ""
+    if len(os_text) < 500:
+        errs.append(f"[发布4] OS 过短({len(os_text)}<500)，疑似角色数据异常")
+
+    # ---------- Step 7 补查 3 项（Part 自检已过的 9 项跳过） ----------
+
+    # 8. Part 内容完整：name/key_points/tags 非空
+    if not sc.get("name"):
+        errs.append("[闸门8] 场景名为空")
+    if not sc.get("key_points"):
+        errs.append("[闸门8] key_points 为空（检查 Part1 是否误写数组）")
+    if not (sc.get("tags") and len(sc.get("tags", [])) >= 3):
+        errs.append("[闸门8] tags 少于 3 个")
+
+    # 12. 整体设定 ≤ 3000 字
+    if len(os_text) > 3000:
+        errs.append(f"[闸门12] OS 超长({len(os_text)}>3000)")
+
+    # 5. Part3 环节存在（回读 conversation_steps 非空；空则提示 CLI 限制，不阻塞）
+    steps = sc.get("conversation_steps") or []
+    if not steps:
+        print("WARN: conversation_steps 为空——已知 CLI/平台限制，发布后走 Web 后台补录（不阻塞）")
+
+    # 6. Part4 评分维度存在且权重和 = 100
+    cd = ((sc.get("scoring_criteria_config") or {}).get("criteria_data")) or sc.get("criteria_data") or {}
+    dims = cd.get("dimensions") or []
+    if not dims:
+        print("WARN: 评分维度在 get 返回中不可见——以 Part4 自检 + apply 成功为准（不阻塞）")
+    else:
+        w = sum(d.get("weight", 0) for d in dims)
+        if w != 100:
+            errs.append(f"[闸门6→发布] 维度权重和={w}≠100")
+
+    return errs
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: gate_check.py <scenario_get.json>", file=sys.stderr)
+        return 1
+    try:
+        with open(sys.argv[1], encoding="utf-8") as f:
+            raw = json.load(f)
+    except Exception as e:
+        print(f"GATE FAIL: JSON 读取失败 {e}", file=sys.stderr)
+        return 1
+
+    sc = unwrap(raw)
+    errs = check(sc)
+    if errs:
+        print("GATE FAIL")
+        for e in errs:
+            print(f"  {e}")
+        return 1
+    print("GATE PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())