@sokeai/cli 1.0.79 → 1.0.81

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.79",
+    "version": "1.0.81",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/scripts/install.js

@@ -504,6 +504,12 @@ downloadFile(downloadURL, binaryPath)
       }
     }
 
+    /***
+    // WorkBuddy manages Connector Skills, PATH and the runtime sandbox.
+    // Temporarily disabled for WorkBuddy compatibility. Keep the original
+    // integration code here until WorkBuddy exposes a reliable install marker.
+    // Do not enable this unconditionally: these operations write to external
+    // agent workspaces, create system symlinks, and may restart GUI processes.
     try {
       syncSkillsToSokeclawWorkspace();
     } catch (_) {}
@@ -513,6 +519,8 @@ downloadFile(downloadURL, binaryPath)
     } catch (_) {}
 
     return maybeAssistGuiPath();
+    ****/
+    return Promise.resolve();
   })
   .then(() => {
     console.log('soke-cli 安装成功!');

package/scripts/run.js

@@ -4,7 +4,8 @@ const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
-// 特殊命令拦截：修复 sokeclaw 的 GUI PATH 问题
+// Legacy compatibility command. Connector installations do not invoke this
+// command; WorkBuddy manages PATH and GUI integration itself.
 if (process.argv[2] === 'setup-gui-env') {
   console.log('正在为 SokeClaw GUI 注入环境变量 PATH...');
   try {
@@ -138,4 +139,4 @@ child.on('exit', (code, signal) => {
 child.on('error', (err) => {
   console.error('执行 soke-cli 时出错:', err.message);
   process.exit(1);
-});
+});

package/skills/mono/.workbuddy/memory/2026-09-01.md

@@ -0,0 +1,2 @@
+- Completed course module decomposition: `soke-course` now only handles course orchestration, while `soke-material`, `soke-lesson`, and `soke-assign` remain independent modules.
+- Updated `references/modules/soke-course/MODULE.md` and synced the top-level route table in `SKILL.md`.

package/skills/mono/.workbuddy/memory/MEMORY.md

@@ -0,0 +1,4 @@
+# Project Memory
+
+- `soke-course` 现已定位为课程主流程编排，不再内嵌素材上传、课件创建、指派学员三类能力；这三类保持为独立子技能 `soke-material`、`soke-lesson`、`soke-assign`。
+- `references/modules/soke-course/MODULE.md` 是课程主技能参考入口，`mono/SKILL.md` 的路由表也已同步为分层结构。

package/skills/mono/ARCHITECTURE_AND_EXTENSION_GUIDE.md

@@ -0,0 +1,572 @@
+# Soke CLI Mono 架构与子技能开发指南
+
+> 面向后续功能开发、多人协作和代码审查的长期参考文档。
+>
+> 当前版本：v1.0  
+> 适用范围：`skills/mono/` 独立技能包
+
+## 1. 文档目标
+
+本指南回答四个问题：
+
+1. Mono Skill 当前由哪些层组成？
+2. 一个新需求应该放在哪一层？
+3. 如何新增一个子功能或子技能？
+4. 多人并行开发时如何避免重复、越界和冲突？
+
+核心原则：
+
+```text
+共享规则只定义通用约束
+业务模块只定义业务差异
+跨模块工作流只定义对象交接
+平台适配器只定义平台差异
+机器检查只定义可自动验证的质量规则
+```
+
+## 2. 总体架构
+
+```text
+用户自然语言
+    ↓
+SKILL.md：入口、意图识别、模块路由
+    ↓
+references/shared/：共享能力
+    ↓
+references/modules/：业务模块
+    ↓
+references/workflows/：跨模块对象链路
+    ↓
+platform/adapters/：平台交互差异
+    ↓
+scripts/：静态检查、字段校验、质量闸门
+```
+
+### 2.1 入口调度层
+
+文件：`SKILL.md`
+
+负责：
+
+- 识别用户动作：查询、创建、更新、发布、指派、删除、导出、同步；
+- 将业务语言路由到正确模块；
+- 规定读取顺序和确认边界；
+- 提供全局禁止事项与输出规则；
+- 引导复杂需求进入对应工作流。
+
+不负责：具体业务字段、完整 API 参数、平台专属交互和模块内部异常。
+
+### 2.2 共享能力层
+
+目录：`references/shared/`
+
+典型能力：
+
+- 安装与环境检测；
+- 认证与权限；
+- CLI 命令发现；
+- 真实对象 ID；
+- 分页和去重；
+- 交互确认；
+- 高风险写操作保护；
+- 输出脱敏；
+- 写后验证、幂等和重试；
+- 异步任务；
+- 本地文件输入；
+- 状态机；
+- 错误分类。
+
+抽取标准：同一规则至少被两个业务模块以相同语义、相同输入和相同异常处理复用，才考虑抽取。
+
+### 2.3 业务模块层
+
+目录：`references/modules/`
+
+模块按业务对象划分，例如：
+
+- 内容域：课程、素材、课件；
+- 测评域：考试、题库、试卷；
+- 路径域：学习地图、阶段；
+- 结果域：任务、档案、证书；
+- 运营域：培训需求、图片库；
+- AI 域：知识包、AI 陪练、AI 督导。
+
+每个模块入口统一采用同一套合同结构（`check_package.py` 的 `module-contracts` 按语义校验，标题可用等价别名）：
+
+```text
+共享前置 → 职责 → 输入 → 流程 → 业务产出/完成判定 → 失败降级 → 验证 → 业务特例 → 输出
+```
+
+- 「共享前置」也可写作「共用前置」，两者等价；
+- 编排主管型模块（如 `soke-course`、`soke-ai-coach-director`）在骨架之上可扩展额外的结构性章节（意图路由、加载白名单、分阶段编排等），但必须保留上述合同语义；
+- 机器检查按「标题或显式粗体合同标签」识别，不强制同名标题。
+
+### 2.4 跨模块工作流层
+
+目录：`references/workflows/`
+
+只描述模块之间的对象交接，不复制模块内部流程。
+
+示例：
+
+```text
+soke-material
+  → 真实素材 ID
+soke-lesson
+  → 课件记录
+soke-course
+  → 已发布课程
+soke-assign
+  → 指派记录
+```
+
+### 2.5 平台适配层
+
+目录：`references/modules/soke-ai-coach-director/platform/adapters/`
+
+适配器只负责：
+
+- 运行环境检测；
+- 内容展示；
+- 选项确认；
+- CLI 执行；
+- 平台能力不足时的降级。
+
+当前支持矩阵见：
+
+```text
+references/modules/soke-ai-coach-director/platform/platform-support-matrix.md
+```
+
+### 2.6 质量保障层
+
+目录：`scripts/`
+
+当前主要检查器：
+
+- `check_package.py`：包级结构、链接、路径、命令、模块和平台一致性；
+- `check_syntax.py`：使用 AST 做无缓存 Python 语法检查；
+- AI 陪练专项脚本：质量闸门和操作校验。
+
+## 3. 模块关系图
+
+### 3.1 课程链路
+
+```text
+soke-material（上传素材）
+        ↓ 真实素材 ID
+soke-lesson（创建课件）
+        ↓ 课件记录
+soke-course（配置/发布课程）
+        ↓ 已发布课程
+soke-assign（指派学习对象）
+```
+
+### 3.2 考试链路
+
+```text
+soke-exam（题库、试题、试卷、考试）
+        ↓
+soke-assign（指派考试）
+        ↓
+soke-exam-question-pool（独立答题练习）
+```
+
+答题练习不能替代考试发布，也不能替代考试成绩查询。
+
+### 3.3 学习地图链路
+
+```text
+soke-course
+        ↓
+soke-learning-map（地图和阶段）
+        ↓
+soke-assign
+        ↓
+soke-task（统计导出）
+        ↓
+soke-learning-profile（学习档案查询）
+```
+
+### 3.4 AI 链路
+
+```text
+原始材料
+    ↓ 一次提炼
+soke-ai-coach-director
+    ├─ Part1-Part5
+    ├─ 场景同步
+    ├─ 质量闸门
+    └─ 发布
+            ↓ 复用提炼稿
+soke-ai-training
+    ├─ source
+    ├─ entries
+    ├─ 知识包版本
+    └─ 场景绑定
+```
+
+知识包模块不重新提炼原始材料，也不负责陪练 Part1-Part5。
+
+## 4. 新增子技能的判定流程
+
+新增需求先回答：
+
+| 判断问题 | 放置位置 |
+|---|---|
+| 是通用能力，多个模块会复用？ | `references/shared/` |
+| 是已有业务对象的新动作？ | 修改现有模块 |
+| 是新的业务对象？ | 新建模块 |
+| 是两个以上模块的串联？ | `references/workflows/` |
+| 是平台显示、交互或命令差异？ | 平台适配器 |
+| 是可自动验证的规则？ | `scripts/` |
+| 是单一模块的专项规则、子流程或命令事实？ | 模块内部：`subs/<主题>/SOP.md`（子流程）、`cli-facts.md`（命令事实）；规则繁多时可用 `references/` 一级分组 |
+
+### 禁止的错误做法
+
+```text
+看到一个 CLI 命令 → 直接新建技能
+遇到一次重复 → 立刻抽取共享规则
+把平台差异写进业务模块
+把业务特例上提到 shared
+把所有新增说明都塞进 SKILL.md
+```
+
+正确顺序：
+
+```text
+业务对象 → 用户动作 → 前置数据 → 状态变化 → CLI 命令 → 输出对象
+```
+
+## 5. 新业务模块开发模板
+
+目录建议：
+
+```text
+references/modules/soke-new-feature/
+├── MODULE.md
+├── README.md
+├── cli-facts.md                 # 命令参数事实源
+├── subs/
+│   └── <主题>/SOP.md            # 子流程 / 专项 SOP
+└── scripts/
+    └── validate_new_feature.py
+```
+
+规则繁多、需要二级分组时，可把 `subs/` 与 `cli-facts.md` 收进 `references/` 一级分组（如 `soke-ai-coach-director`）；默认新模块按上表扁平结构，避免 `references/modules/<模块>/references/` 的双重 references 冗余。
+
+初始开发不必一次创建全部文件。推荐增量顺序：
+
+```text
+MODULE.md → README.md → 子流程 subs/ 与 cli-facts.md → 可自动验证 scripts/ → 真实案例
+```
+
+### MODULE.md 最小模板
+
+```markdown
+# soke-new-feature
+
+## 共享前置
+
+读取 `../../shared/README.md`，按需读取环境、认证、对象、交互、写后验证和错误处理规则。
+
+## 职责
+
+说明本模块负责的业务对象和动作，并写清不负责（相邻模块与跨模块工作流的边界）。
+
+## 输入
+
+列出用户输入、必需真实 ID、可选参数和文件要求。
+
+## 流程
+
+查询前置 → 用户确认 → 执行动作 → 写后验证 → 输出摘要。
+
+## 业务产出 / 完成判定
+
+说明每一步产生什么真实对象或状态，以及什么条件才算完成（不能把「命令执行过」当作成功）。
+
+## 失败降级
+
+说明缺少输入、对象不存在、权限不足、部分成功、写后异常时如何停止或降级。
+
+## 验证
+
+说明用哪个查询/回读确认结果真实落盘。
+
+## 业务特例
+
+只写本模块专属字段、状态、约束和异常。
+
+## 输出
+
+说明对用户展示的摘要，以及供后续模块复用的真实对象信息。
+```
+
+## 6. 新增子功能的九步开发法
+
+### 第 1 步：写需求边界
+
+用一句话定义：
+
+```text
+谁，在什么对象上，执行什么动作，得到什么结果。
+```
+
+同时写“不负责”。
+
+### 第 2 步：确认对象和状态
+
+明确：
+
+- 对象名称；
+- 创建前状态；
+- 执行后状态；
+- 依赖的父对象；
+- 输出的真实 ID；
+- 是否可重复执行。
+
+### 第 3 步：选择归属层
+
+依次判断共享层、现有模块、新模块、工作流、适配器或检查器。
+
+### 第 4 步：查询当前 CLI 帮助
+
+先确认父命令，再确认叶子命令：
+
+```bash
+soke-cli --help
+soke-cli <domain> --help
+soke-cli <domain> +<verb> --help
+```
+
+文档示例不能替代当前 CLI 帮助。
+
+### 第 5 步：编写最小闭环
+
+先实现：
+
+```text
+环境/认证
+→ 查询真实 ID
+→ 确认写入范围
+→ 执行一次主动作
+→ 验证结果
+→ 输出摘要
+```
+
+### 第 6 步：接入入口和索引
+
+至少更新：
+
+- `SKILL.md` 意图路由；
+- `references/modules/README.md` 模块矩阵；
+- 相关工作流 README；
+- 适配器矩阵（如适用）。
+
+### 第 7 步：补充专项规则
+
+只保留当前模块独有的：
+
+- 字段格式；
+- 状态转换；
+- 业务红线；
+- 资源限制；
+- 特殊异常。
+
+### 第 8 步：加入自动检查
+
+至少确保：
+
+```text
+文件存在
+入口已登记
+共享入口存在
+链接有效
+无旧路径
+无旧命令
+无重复认证
+无复制共享规则
+语法通过
+无缓存残留
+```
+
+### 第 9 步：真实场景验收
+
+静态检查通过后，用一条真实业务链路验证：
+
+```text
+输入 → 路由 → 前置查询 → 确认 → 执行 → 验证 → 输出
+```
+
+## 7. 多人开发协作规则
+
+### 7.1 按层和边界分工
+
+推荐拆分：
+
+| 角色 | 负责范围 |
+|---|---|
+| 架构维护者 | `SKILL.md`、共享规则、规则归属矩阵 |
+| 业务开发者 | 单个 `references/modules/soke-xxx/` |
+| 工作流开发者 | `references/workflows/` 和交接契约 |
+| 平台开发者 | 单个平台适配器及支持矩阵 |
+| 质量维护者 | `scripts/check_package.py` 和检查规则 |
+| 验收人员 | 真实场景、CLI 帮助和回归验证 |
+
+同一时间尽量不要让多人修改同一个入口文件。
+
+### 7.2 任务领取前检查
+
+每位开发者开始前先确认：
+
+```bash
+git status --short
+git diff --stat
+```
+
+并查看：
+
+- 当前模块是否已有未提交修改；
+- 是否已有同名任务；
+- 是否已经存在相邻功能；
+- 共享规则是否已有唯一来源。
+
+### 7.3 变更声明
+
+开发前先声明四项：
+
+```text
+修改文件
+不修改文件
+依赖模块
+验收命令
+```
+
+例如：
+
+```text
+修改：soke-new-feature/MODULE.md、modules/README.md
+不修改：shared/、其他业务模块
+依赖：object-context、write-verify
+验收：check_package.py、git diff --check
+```
+
+### 7.4 冲突处理
+
+出现以下情况必须暂停并对齐：
+
+- 两人同时修改共享规则；
+- 两个模块都声称负责同一对象；
+- 新功能既像模块又像工作流；
+- 需要修改多个入口文件；
+- 机器检查规则与业务特例冲突。
+
+优先建立唯一事实源，再继续开发。
+
+### 7.5 合并前质量闸门
+
+每个分支合并前必须运行：
+
+```bash
+/Users/edy/.workbuddy/binaries/python/versions/3.13.12/bin/python3 skills/mono/scripts/check_package.py
+git diff --check
+```
+
+若新增 Python 脚本，禁止用会生成缓存的方式作为唯一验证；使用 AST 检查。
+
+## 8. 唯一来源矩阵
+
+| 内容 | 唯一来源 |
+|---|---|
+| 安装与认证 | `references/shared/` |
+| 通用分页、确认、脱敏、重试 | `references/shared/` |
+| 模块职责和对象边界 | `references/modules/README.md` + 各模块 `MODULE.md` |
+| 跨模块交接 | `references/workflows/` |
+| AI 陪练通用执行规则 | `exec-common.md` |
+| AI 陪练 Part 规则 | 对应 `exec-partN.md` |
+| AI 平台支持状态 | `platform-support-matrix.md` |
+| 平台交互差异 | 对应 `platform/adapters/*.md` |
+| 机器质量规则 | `scripts/check_package.py` |
+
+## 9. 变更类型与影响范围
+
+### 新增共享规则
+
+必须：
+
+1. 证明至少两个模块复用；
+2. 更新规则归属矩阵；
+3. 删除模块内重复版本；
+4. 回归所有模块。
+
+### 新增业务模块
+
+必须：
+
+1. 创建标准 `MODULE.md`；
+2. 更新入口路由和模块矩阵；
+3. 明确依赖和不负责范围；
+4. 加入检查器；
+5. 用真实流程验收。
+
+### 新增平台
+
+必须：
+
+1. 创建适配器文件；
+2. 更新支持矩阵；
+3. 更新适配器索引；
+4. 写明稳定、可选或待验证状态；
+5. 通过平台一致性检查。
+
+### 删除平台
+
+必须同步删除或更新：
+
+- 适配器文件；
+- 支持矩阵行；
+- 适配器索引；
+- 路由说明；
+- 变更日志；
+- 检查器清单。
+
+通用降级路径不得删除。
+
+## 10. Definition of done
+
+新增子功能只有同时满足以下条件，才算完成：
+
+- [ ] 业务对象和边界已定义；
+- [ ] 归属层级已确定；
+- [ ] 不重复已有共享能力；
+- [ ] 模块入口具备完整合同结构（共享前置 + 职责/输入/流程/业务产出/失败降级/验证/业务特例/输出）；
+- [ ] 真实 ID 来源明确；
+- [ ] 写操作有确认和验证；
+- [ ] 入口路由和索引已更新；
+- [ ] 跨模块交接已定义；
+- [ ] 机器检查通过；
+- [ ] `git diff --check` 通过；
+- [ ] 至少完成一条真实场景验收；
+- [ ] 变更范围和后续风险已记录。
+
+## 11. 当前建议
+
+规则统一治理阶段已完成，后续进入能力建设和真实验证阶段：
+
+1. 优先验证 WorkBuddy 主路径；
+2. 再验证千问适配器；
+3. 根据真实需求决定 QClaw 是否保留；
+4. 对 Zework 完成最小可行验收；
+5. 新增功能按本指南逐项落地；
+6. 只有真实复用出现时才继续抽取共享规则。
+
+## 12. 最终原则
+
+```text
+先判层级，再定边界；
+先定义对象，再选命令；
+先复用共享，再写特例；
+先完成闭环，再扩展异常；
+先机器检查，再真实验收。
+```

package/skills/mono/README.md

@@ -2,6 +2,8 @@
 
 这是可独立安装的单入口 Skill 包。
 
+架构、子技能扩展和多人协作规范见 [`ARCHITECTURE_AND_EXTENSION_GUIDE.md`](./ARCHITECTURE_AND_EXTENSION_GUIDE.md)。
+
 ```bash
 cp -r skills/mono ~/.claude/skills/soke-cli
 ```