@sokeai/cli 1.0.34 → 1.0.39

package/scripts/regress-baseline.md

@@ -0,0 +1,84 @@
+# auth 回归 baseline 流程(task 8.2)
+
+> 配套脚本:`scripts/regress-auth.sh`
+> 用途:在本 change 引入前后两次跑同一脚本,diff 验证零回归。
+
+## 1. baseline 采样(本 change 引入**前**)
+
+在 master 或上一个 release tag 下:
+
+```bash
+git checkout <last-release-tag>
+make install   # 或:go build -o bin/soke-cli main.go
+SOKE_CLIENT_ID=... SOKE_CLIENT_SECRET=... \
+  bash scripts/regress-auth.sh 2>&1 | tee /tmp/regress-before.txt
+```
+
+`/tmp/regress-before.txt` 即 baseline,包含:
+- 各步 stdout/stderr
+- 各步 exit code(脚本内 `==== [label] exit=N ====` 行)
+- timestamps 已 mask,仅保留结构性差异
+
+## 2. 引入后采样
+
+切到本 change 分支,重新 build 跑一次:
+
+```bash
+git checkout worktree-generalize-vendor-plugin
+make install
+SOKE_CLIENT_ID=... SOKE_CLIENT_SECRET=... \
+  bash scripts/regress-auth.sh 2>&1 | tee /tmp/regress-after.txt
+```
+
+## 3. diff
+
+```bash
+diff /tmp/regress-before.txt /tmp/regress-after.txt
+```
+
+期望:**无差异**(允许时间戳 mask 后的剩余 token 字段差异,因每次实际签发的
+token bytes 不同 —— 但 mask 应已覆盖)。
+
+若 diff 显示行为变化,本 change 视为引入回归,**禁止 merge**,
+回到代码层检查 ClientID() / Endpoints() / CallbackPath 取值路径。
+
+## 4. keychain 字段验证(任选其一,平台相关)
+
+macOS:
+```bash
+security find-generic-password -s "soke-cli" -g 2>&1 | grep -E "acct|cdat"
+```
+
+Linux(libsecret):
+```bash
+secret-tool search service soke-cli
+```
+
+字段名(`access_token` / `refresh_token` 等)与 baseline 完全一致。
+
+## 5. 三平台 matrix(task 8.3)
+
+本 change 不接入 GH Actions yml(避免 PR 卡在未跑通的 CI 任务),由 ①
+`make-soke-cli-mcp-first` 在 same release 时一并引入。matrix 草案:
+
+```yaml
+# .github/workflows/regress-auth.yml(草案,在 ① 同 release 一起合)
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+jobs:
+  regress:
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with: { go-version: '1.25' }
+      - run: |
+          go build -o bin/soke-cli main.go
+          # auth login 需要真账号,CI 内只跑 status / logout 路径
+          ./bin/soke-cli auth status --json
+          ./bin/soke-cli auth logout
+          ./bin/soke-cli auth status --json
+```
+
+跑出 CI matrix 三个 job 全绿,本 change 才视为通过 task 8.3 AC。

package/scripts/release.sh

@@ -48,6 +48,13 @@ check_tools() {
 check_git_status() {
     echo -e "${YELLOW}检查 Git 状态...${NC}"
 
+    # 检查当前分支是否为 master
+    CURRENT_BRANCH=$(git branch --show-current)
+    if [ "$CURRENT_BRANCH" != "master" ]; then
+        echo -e "${RED}错误: 当前分支为 $CURRENT_BRANCH，发布必须在 master 分支上进行${NC}"
+        exit 1
+    fi
+
     if [ -n "$(git status --porcelain)" ]; then
         echo -e "${RED}错误: 工作目录有未提交的更改${NC}"
         echo "请先提交或暂存所有更改"

package/scripts/test-auto-detect.js

@@ -5,66 +5,14 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-
-// 复制 detectSkillNames 函数
-function detectSkillNames(packagedSkillsDir) {
-  if (!fs.existsSync(packagedSkillsDir)) return [];
-
-  try {
-    const entries = fs.readdirSync(packagedSkillsDir, { withFileTypes: true });
-    return entries
-      .filter(entry => entry.isDirectory() && entry.name.startsWith('soke-'))
-      .map(entry => entry.name)
-      .sort();
-  } catch (_) {
-    return [];
-  }
-}
-
-// 复制 parseSkillMetadata 函数
-function parseSkillMetadata(skillDir) {
-  const skillMdPath = path.join(skillDir, 'SKILL.md');
-  if (!fs.existsSync(skillMdPath)) {
-    return null;
-  }
-
-  try {
-    const content = fs.readFileSync(skillMdPath, 'utf8');
-
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontmatterMatch) return null;
-
-    const frontmatter = frontmatterMatch[1];
-    const metadata = {};
-
-    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
-    if (nameMatch) metadata.name = nameMatch[1].trim();
-
-    const summaryMatch = frontmatter.match(/^summary:\s*(.+)$/m);
-    if (summaryMatch) metadata.summary = summaryMatch[1].trim();
-
-    const descMatch = frontmatter.match(/^description:\s*["'](.+)["']$/m);
-    if (descMatch) {
-      metadata.description = descMatch[1].trim();
-    } else {
-      const descMatch2 = frontmatter.match(/^description:\s*(.+)$/m);
-      if (descMatch2) metadata.description = descMatch2[1].trim();
-    }
-
-    const versionMatch = frontmatter.match(/^version:\s*(.+)$/m);
-    if (versionMatch) metadata.version = versionMatch[1].trim();
-
-    const binsMatch = frontmatter.match(/bins:\s*\[(.+?)\]/);
-    if (binsMatch) {
-      metadata.bins = binsMatch[1].split(',').map(b => b.trim().replace(/['"]/g, ''));
-    }
-
-    return metadata;
-  } catch (_) {
-    return null;
-  }
-}
+const {
+  detectSkillNames,
+  parseSkillMetadata,
+  pruneManagedSkillDirs,
+  pruneRegistrySkills
+} = require('./install.js');
 
 // 测试
 const packageRoot = path.join(__dirname, '..');
@@ -102,19 +50,13 @@ for (const skillName of skillNames) {
 // 验证结果
 console.log('📊 验证结果:\n');
 
-const expectedSkills = ['soke-course', 'soke-exam', 'soke-shared'];
-const missingSkills = expectedSkills.filter(s => !skillNames.includes(s));
-const extraSkills = skillNames.filter(s => !expectedSkills.includes(s));
-
-if (missingSkills.length > 0) {
-  console.log(`❌ 缺少的 skills: ${missingSkills.join(', ')}`);
-} else {
-  console.log('✅ 所有预期的 skills 都已检测到');
-}
-
-if (extraSkills.length > 0) {
-  console.log(`ℹ️  额外的 skills: ${extraSkills.join(', ')}`);
+const requiredSkills = ['soke-shared'];
+const missingRequiredSkills = requiredSkills.filter(s => !skillNames.includes(s));
+if (missingRequiredSkills.length > 0) {
+  console.log(`❌ 缺少基础 skills: ${missingRequiredSkills.join(', ')}`);
+  process.exit(1);
 }
+console.log('✅ 基础 skills 检测通过');
 
 console.log('');
 console.log('🎉 测试完成！');
@@ -123,3 +65,38 @@ console.log('💡 提示:');
 console.log('   - 新增 skill 时，只需在 skills/ 目录下创建 soke-* 目录');
 console.log('   - 确保每个 skill 都有 SKILL.md 文件，包含完整的 frontmatter');
 console.log('   - install.js 会自动检测并注册所有 skills');
+
+// 验证清理逻辑
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'soke-skill-prune-'));
+const targetDir = path.join(tempRoot, 'skills');
+fs.mkdirSync(targetDir, { recursive: true });
+fs.mkdirSync(path.join(targetDir, 'soke-stale'));
+fs.mkdirSync(path.join(targetDir, 'soke-course'));
+fs.mkdirSync(path.join(targetDir, 'custom-skill'));
+
+const removedDirs = pruneManagedSkillDirs(targetDir, ['soke-course']);
+if (!removedDirs.includes('soke-stale')) {
+  console.error('❌ pruneManagedSkillDirs 未删除过期 managed skill');
+  process.exit(1);
+}
+if (!fs.existsSync(path.join(targetDir, 'custom-skill'))) {
+  console.error('❌ pruneManagedSkillDirs 错误删除了非受管 skill');
+  process.exit(1);
+}
+
+const registry = {
+  skills: [
+    { name: 'soke-stale' },
+    { name: 'soke-course' },
+    { name: 'custom-skill' }
+  ]
+};
+const removedEntries = pruneRegistrySkills(registry, ['soke-course']);
+if (removedEntries !== 1) {
+  console.error('❌ pruneRegistrySkills 未正确移除过期条目');
+  process.exit(1);
+}
+if (!registry.skills.find((entry) => entry.name === 'custom-skill')) {
+  console.error('❌ pruneRegistrySkills 错误移除了非受管条目');
+  process.exit(1);
+}

package/scripts/test-local-reconcile.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  pruneManagedSkillDirs,
+  pruneRegistrySkills,
+  updateWorkclawRegistry
+} = require('./local-test.js');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'soke-local-reconcile-'));
+const targetDir = path.join(tempRoot, 'skills');
+fs.mkdirSync(targetDir, { recursive: true });
+
+fs.mkdirSync(path.join(targetDir, 'soke-stale'));
+fs.mkdirSync(path.join(targetDir, 'soke-exam'));
+fs.mkdirSync(path.join(targetDir, 'custom-skill'));
+
+const removedDirs = pruneManagedSkillDirs(targetDir, ['soke-exam']);
+if (!removedDirs.includes('soke-stale')) {
+  console.error('❌ stale managed skill was not removed');
+  process.exit(1);
+}
+if (!fs.existsSync(path.join(targetDir, 'custom-skill'))) {
+  console.error('❌ unmanaged local skill should remain untouched');
+  process.exit(1);
+}
+
+const registry = {
+  skills: [
+    { name: 'soke-stale' },
+    { name: 'soke-exam' },
+    { name: 'custom-skill' }
+  ]
+};
+const removedEntries = pruneRegistrySkills(registry, ['soke-exam']);
+if (removedEntries !== 1) {
+  console.error('❌ registry stale entry removal failed');
+  process.exit(1);
+}
+if (!registry.skills.find((entry) => entry.name === 'custom-skill')) {
+  console.error('❌ unmanaged registry entry should remain untouched');
+  process.exit(1);
+}
+
+const registryPath = path.join(tempRoot, 'registry.json');
+updateWorkclawRegistry(registryPath, 'soke-contact', null, '/tmp/soke-contact');
+const updatedRegistry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+if (!updatedRegistry.skills.find((entry) => entry.name === 'soke-contact')) {
+  console.error('❌ registry update should tolerate missing metadata');
+  process.exit(1);
+}
+
+console.log('✅ local reconciliation tests passed');

package/skills/soke-business-training-report/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: soke-business-training-report
 description: 生成某场业务培训考试的整体分析报告，包括参考人数、通过率、平均分、最高分及未通过学员名单。
+requiredAuthorizations: [{"platformId":"soke-ai"}]
 ---
 
 # 培训考试整体分析报告 Skill

package/skills/soke-course/SKILL.md

@@ -3,6 +3,7 @@ name: soke-course
 summary: 授客课程管理（课程列表/分类/课程详情/学习记录），通过 soke-cli 查询
 version: 1.0.0
 description: "授客课程管理：查询课程、课程分类、课程详情、学习记录。查询课程列表、课程分类、课程用户学习记录、课件列表、人脸识别记录。当用户需要查询课程信息、查看课程列表、查询学习记录、查看课程分类时使用。"
+requiredAuthorizations: [{"platformId":"soke-ai"}]
 metadata:
   requires:
     bins: ["soke-cli"]
@@ -51,6 +52,7 @@ Shortcut 是对常用操作的高级封装（`soke-cli course +<verb> [flags]`
 | [`+get-course-user`](#get-course-user) | 获取单个用户的课程学习详情 |
 | [`+list-lesson-learns`](#list-lesson-learns) | 列出课件学习记录 |
 | [`+list-lesson-faces`](#list-lesson-faces) | 列出课件人脸识别记录 |
+| [`+batch-create-from-excel`](#batch-create-from-excel) | 通过 Excel 批量创建课程并上传课件(原 createcourse 工具能力,已合入) |
 
 ## 命令详解
 
@@ -483,6 +485,68 @@ soke-cli course +list-lesson-learns --lesson-id <lesson_id>
 soke-cli course +list-lesson-faces --lesson-id <lesson_id>
 ```
 
+### +batch-create-from-excel
+
+通过 Excel 文件批量创建课程并上传课件素材。能力来自原独立工具 createcourse,已物理合入本 CLI(`internal/courseimport`)。
+
+**命令格式**:
+```bash
+soke-cli course +batch-create-from-excel \
+  --file <课程信息.xlsx> \
+  [--material-dir <素材目录>] \
+  [--separator <分隔符>] \
+  [--mode default|hg] \
+  [--picture-time 6] \
+  [--material-category-id <分类ID>] \
+  [--json-events]
+```
+
+**Flags**:
+
+| 名称 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `--file` | 是 | - | Excel 文件路径,必须 `.xlsx` |
+| `--material-dir` | 否 | Excel 同目录 | 素材文件相对路径解析的根目录 |
+| `--separator` | 否 | `-` | Excel `分类` / `标签` 列的分隔符,同时影响两列 |
+| `--mode` | 否 | `default` | `default` 普通课程 / `hg` 海关学时模式 |
+| `--picture-time` | 否 | `6` | 视频抽帧秒数;仅当系统已装 ffmpeg 时生效 |
+| `--material-category-id` | 否 | 空 | 素材库默认分类 ID,空则交由后端兜底 |
+| `--json-events` | 否 | false | stdout 输出 JSON-lines 进度事件,供 sokeclaw 等 IPC 调用方解析 |
+
+**Excel 模板**: 详见 [`templates/batch-create-from-excel.md`](./templates/batch-create-from-excel.md)。
+
+**进度事件协议**(`--json-events` 模式):
+
+| `type` | 含义 |
+| --- | --- |
+| `env` | 启动时报告 ffmpeg 是否可用 |
+| `course_start` | 开始处理某门课程 |
+| `course_done` | 某门课程全流程成功 |
+| `course_failed` | 某门课程失败(单门失败不中断整批) |
+| `episode_uploaded` | 单节课件上传完成 |
+| `cover_fallback` | 封面降级为默认封面 |
+| `run_done` | 整批结束,带 `ok` / `failed` 计数 |
+
+**示例**:
+
+```bash
+# 默认模式,Excel 与素材同目录
+soke-cli course +batch-create-from-excel --file ./courses.xlsx
+
+# HG 学时模式,显式指定素材目录,机器可读输出
+soke-cli course +batch-create-from-excel \
+  --file ./hg-courses.xlsx \
+  --material-dir ./materials \
+  --mode hg \
+  --json-events
+```
+
+**注意**:
+
+- ffmpeg 是可选依赖:已装则启用视频抽帧封面;未装则封面策略自动降级到默认封面,不影响主流程。如需启用抽帧,把 ffmpeg 装到 `PATH`,或设置环境变量 `SOKE_CLI_FFMPEG_PATH` 指向可执行文件。
+- HG 模式下"所属单位标签"的 tag id 通过环境变量 `SOKE_CLI_HG_ORG_TAG_ID` 注入(原 createcourse 写死在 token 配置表里,合入 soke-cli 后改为外部注入)。
+- 单门课程失败不会中断整批运行,失败统计会在 `run_done` 事件汇总。
+
 ## 注意事项
 
 1. **时间格式**: 所有时间参数使用Unix时间戳（毫秒），不是秒

package/skills/soke-course/templates/batch-create-from-excel.md

@@ -0,0 +1,75 @@
+# `+batch-create-from-excel` Excel 模板说明
+
+`soke-cli course +batch-create-from-excel` 接受的 Excel 模板与原 `createcourse` 工具兼容。下面给出列定义、续行规则与制作技巧。
+
+## 列定义
+
+| 列名 | 必填 | 类型/格式 | 说明 |
+| --- | --- | --- | --- |
+| 序号 | 是 | 数字/文本 | 课程序号,行级唯一;续行(同一课程的下一节分集)填空 |
+| 课程名称 | 是 | 文本 | 课程标题。续行可留空或填与上一行相同的标题 |
+| 分类 | 否 | 分隔字符串 | 多级分类用 `--separator` 分隔,例如 `公共课-合规-反洗钱` |
+| 标签 | 否 | 分隔字符串 | 多标签同样按 `--separator` 分隔 |
+| 简介 | 否 | 文本 | 课程介绍 |
+| 学分 | 否 | 数字 | `default` 模式有效 |
+| 积分 | 否 | 数字 | `default` 模式有效;HG 模式忽略 |
+| 封面图 | 否 | 文本 | URL / `default` / 本地图片路径 / 数字(秒,需 ffmpeg) / 留空(视频自动抽帧,需 ffmpeg) |
+| 素材文件 | 否(分集行必填) | 路径 | 课件文件,相对路径会按 `--material-dir` 解析 |
+
+### HG 模式额外列
+
+启用 `--mode hg` 时,额外读取四列学时:
+
+| 列名 | 单位 | 说明 |
+| --- | --- | --- |
+| 习思想 | 学时 | 习近平新时代中国特色社会主义思想 |
+| 政治能力 | 学时 | - |
+| 业务能力 | 学时 | - |
+| 执法能力 | 学时 | - |
+
+## 表头规则
+
+- 前 2 行为表头,允许两行合并表头(工具按 trim 后的名称合并到位置映射)。
+- 第 3 行起为数据。
+- 总行数低于 4 会直接报错。
+
+## 续行(同一课程多分集)
+
+当一门课程含多节课件时:
+
+1. 第一行填完整课程信息(序号 + 课程名称 + 其他元数据 + 第 1 节素材文件)。
+2. 后续行的 `序号` 和 `课程名称` 留空(或 `课程名称` 与上一行相同),只填 `素材文件` (以及非 HG 模式的 `积分`)。
+3. 工具会自动把后续行 append 到上一门课程的 `Episodes` 数组。
+
+## 封面图来源策略
+
+按以下优先级决定课程封面:
+
+1. `封面图` 是 `http(s)://...` → 直接使用 URL。
+2. `封面图` 是 `default` → 使用平台默认封面。
+3. `封面图` 是本地图片路径(.jpg/.jpeg/.png/.gif/.bmp) → 上传 OSS 并使用返回的 URL。
+4. `封面图` 是数字(秒数) + `素材文件` 是视频 + 系统有 ffmpeg → 从视频抽帧并上传。
+5. `封面图` 留空 + `素材文件` 是视频 + 系统有 ffmpeg → 用 `--picture-time`(默认 6 秒)抽帧。
+6. 以上都不满足 → 使用平台默认封面,并 emit `cover_fallback` 事件。
+
+## 快速根据本地课件目录制作模板(Windows 示例)
+
+> 来自原 createcourse 工具的工作流提示。
+
+1. 打开 `cmd`,切到课件所在的最上层目录,例如 `cd d:\course`。
+2. 把所有文件路径导出到文本文件:
+   ```cmd
+   d:
+   cd course
+   dir /s /b /a:-d > filelist.txt
+   ```
+3. 打开空白 Excel,在「数据」选项卡选「从文本/CSV」导入 `filelist.txt`。
+4. 对导入的数据列进行分列。
+5. 根据实际存储情况合并单元格(同一课程的多节分集),补全课程学分、简介、封面图等信息。
+
+## 模板示例
+
+可参照仓库内随 createcourse 一起合入的两张样例图:
+
+- `internal/courseimport/template_example.jpg`
+- `internal/courseimport/template_example2.jpg`

package/skills/soke-learning-profile/SKILL.md

@@ -3,6 +3,7 @@ name: soke-learning-profile
 summary: 学员学习档案查询
 version: 1.0.0
 description: "学员学习档案查询：查询学员的完整学习记录，包括课程学习、考试成绩、证书获取、学分积分等。当用户需要查询学员学习档案、查看学员学习情况、统计学员学习数据、查询学员综合学习信息时使用。"
+requiredAuthorizations: [{"platformId":"soke-ai"}]
 metadata:
   requires:
     bins: ["soke-cli"]