@sokeai/cli 1.0.79 → 1.0.81

package/skills/mono/references/shared/write-guard.md

@@ -0,0 +1,34 @@
+# soke-cli 高风险写操作守卫
+
+本文件定义发布、删除、指派、绑定、批量写入等高风险操作的共用规则。
+
+## 风险等级
+
+- L0：查询、列表、详情
+- L1：创建草稿、上传素材
+- L2：更新、绑定、批量写入、分配对象
+- L3：发布、删除、关闭、批量指派、平台同步
+
+## 通用要求
+
+- L2 及以上必须先展示目标、影响范围和对象。
+- L3 必须获得明确确认。
+- 删除和关闭类操作必须明确说明不可逆影响。
+- 批量操作必须说明数量、字段和失败处理方式。
+- 平台同步必须说明将要修改的场景、知识包或配置摘要。
+
+## 确认摘要模板
+
+```text
+操作：<动作>
+目标：<对象名称>
+范围：<影响范围>
+影响：<简要说明>
+是否确认？
+```
+
+## 规则
+
+- 未确认前不执行写操作。
+- 不把预览结果当作执行结果。
+- 重试前先确认上一步是否已经成功，避免重复写入。

package/skills/mono/references/shared/write-verify.md

@@ -0,0 +1,33 @@
+# soke-cli 写操作验证与幂等
+
+本文件定义写操作后的验证、重试和幂等处理。
+
+## 统一流程
+
+1. 执行写操作。
+2. 检查退出码和返回状态。
+3. 提取真实 ID 或任务 ID。
+4. 只在必要时进行回读验证。
+5. 保存状态，供下一步使用。
+
+## 幂等原则
+
+- 能使用 idempotency-key 的地方必须使用。
+- 重试前先判断上一次是否可能已经成功。
+- 不要因为没有看到完整输出就重复创建。
+- 异步任务必须保存 task ID 或等价标识。
+
+## 回读规则
+
+- 回读只验证本次写入的关键结果，不做无意义全量复核。
+- 回读结果如与写入结果不一致，优先判断是否存在平台延迟或最终一致性问题。
+- 不要用回读替代写操作。
+
+## 适用场景
+
+- 课程创建后查课程 ID
+- 素材上传后查 uuid
+- 课件创建后查 lesson-id
+- 任务创建后查 task-id
+- 场景同步后查版本 ID
+- 发布后查状态

package/skills/mono/references/workflows/README.md

@@ -0,0 +1,115 @@
+# 跨模块工作流
+
+这里存放跨业务模块的流程编排。模块自身的字段、命令和专项限制仍以对应模块文档为准。
+
+## 使用规则
+
+先按用户的核心动作选择一条工作流，再读取对应模块文档。不要因为出现“课程”“素材”或“学习”等名词，就自动进入完整创建流程。
+
+## 通用前置
+
+所有需要访问授客平台的流程统一遵循：
+
+```text
+environment-check → auth-check → 业务输入检查
+→ 执行当前操作 → 提取真实 ID → 执行依赖该 ID 的后续操作
+```
+
+- 环境检测见 `../shared/environment-check.md`。
+- 登录与企业绑定见 `../shared/auth-check.md`。
+- 纯本地输入检查可以在环境检测前准备，但平台操作必须先完成环境和登录验证。
+- “提取真实 ID”是上传、创建或查询成功后的结果，不要求所有操作在执行前都已有 ID。
+- 只在必要时加载具体模块文档，避免全量读取。
+
+## 课程与素材工作流
+
+### 仅上传素材
+
+```text
+environment-check → auth-check → 文件检查 → 上传素材 → 返回素材真实 ID
+```
+
+适用于用户只要求把视频、音频或文档放入素材库，不创建课程或课件。
+
+入口：`../modules/soke-material/MODULE.md`。
+
+### 已有课程添加课件
+
+```text
+environment-check → auth-check → 确认 course-id
+→ 上传素材或选择已有素材 → 获取素材真实 ID
+→ 创建课件 → 可选排序
+```
+
+入口：
+
+- `../modules/soke-material/MODULE.md`
+- `../modules/soke-lesson/MODULE.md`
+
+### 从零创建并发布课程
+
+```text
+environment-check → auth-check → 课程分类 → 创建课程
+→ 上传/选择素材 → 创建课件 → 配置课程
+→ 发布课程 → 指派学员
+```
+
+入口：
+
+- `../modules/soke-course/MODULE.md`
+- `../modules/soke-material/MODULE.md`
+- `../modules/soke-lesson/MODULE.md`
+- `../modules/soke-assign/MODULE.md`
+
+### 命令前缀说明
+
+本 Mono Skill 的 CLI 命令统一使用 `soke-cli` 前缀。执行前先用当前版本的帮助确认命令和参数，不要凭文档旧例猜测：
+
+```bash
+soke-cli --help
+soke-cli file --help
+soke-cli course --help
+```
+
+课程相关示例：
+
+```bash
+soke-cli file +upload --path "/absolute/path/to/file"
+soke-cli course +lesson-create --course-id <course-id> --title "课件标题"
+```
+
+若其他资料出现 `soke file ...`、`soke course ...` 或其他旧前缀，只能视为历史写法；实际执行时统一改用 `soke-cli`，并以当前 CLI 帮助为准。
+
+## 课程工作流的选择判断
+
+| 用户表达 | 应选择 |
+|---|---|
+| “上传文件”“把视频放素材库” | 仅上传素材 |
+| “给这门课程添加视频/课件” | 已有课程添加课件 |
+| “创建一门课程并上传课件” | 从零创建并发布课程；是否发布需另行确认 |
+| “从素材库添加到课程” | 已有课程添加课件；不重复上传 |
+
+注意：上传素材和创建课件是两个不同动作。素材上传成功返回的 `uuid`、`object` 等字段，必须原样传给课件创建流程；不能用文件名或自行编造的 ID 代替。
+
+## 考试创建与成绩查询
+
+```text
+题库分类 → 创建题库 → 创建试题 → 创建试卷 → 发布试卷 → 创建考试 → 指派 → 查询成绩
+```
+
+入口：`../modules/soke-exam/MODULE.md`。
+
+## 学习地图与统计导出
+
+```text
+地图分类 → 创建地图 → 查询课程 → 创建阶段 → 发布地图 → 指派 → 创建导出任务 → 查询任务状态
+```
+
+入口：`../modules/soke-learning-map/MODULE.md`；导出任务规则见 `../modules/soke-task/MODULE.md`。
+
+## 规则
+
+- 跨模块流程只传递 CLI 返回的真实 ID。
+- 发布、指派、删除、批量写入和平台同步前必须取得明确确认。
+- 前一步未成功或缺少真实 ID 时，不得推进下一步。
+- 具体模块文档与当前 CLI `--help` 不一致时，以当前 CLI 为准。

package/skills/mono/scripts/check_package.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Run static quality checks for the standalone Mono Skill package."""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+
+OLD_COMMAND_PATTERNS = (
+    r"(?<![-\w])soke\s+(?:file|course|exam|assign|api|learning-map)\b",
+)
+STALE_PATHS = (
+    "references/installation.md",
+    "./references/installation.md",
+)
+REQUIRED_MODULE_FILES = ("references/modules/README.md",)
+ADAPTER_DIR = "references/modules/soke-ai-coach-director/platform/adapters"
+ADAPTER_MATRIX = "references/modules/soke-ai-coach-director/platform/platform-support-matrix.md"
+REQUIRED_ADAPTER_FILES = ("README.md", "workbuddy.md", "qwen.md", "zework.md", "qclaw.md")
+ADAPTER_INDEX_MARKERS = {
+    "workbuddy.md": ("WorkBuddy", "workbuddy.md"),
+    "qwen.md": ("千问", "qwen.md"),
+    "zework.md": ("Zework", "zework.md"),
+    "qclaw.md": ("QClaw", "qclaw.md"),
+}
+MODULE_EXCLUSIONS = {"soke-shared"}
+MODULE_CONTRACT_GROUPS = {
+    "responsibility": ("职责", "技能定位"),
+    "input": ("输入", "使用前提", "材料完整性检查", "输入完整性", "输入包", "材料缺口"),
+    "process": ("流程", "任务类型", "推荐同步", "创建型任务流程"),
+    "business-output": ("业务产出", "完成判定", "完成条件"),
+    "failure": ("失败", "降级", "异常", "缺失规则", "错误处理"),
+    "verification": ("验证", "检查清单", "回读", "核对", "质量闸门", "完成判定"),
+    "special-cases": ("业务特例", "注意", "关键硬规则"),
+    "output": ("输出", "完成摘要"),
+}
+ENTRY_BUSINESS_MARKERS = (
+    "conversation_steps",
+    "scoring_rule",
+    "ai_roles[]",
+    "base_updated_at",
+    "advisor_golden_script",
+)
+
+REQUIRED_SHARED_FILES = (
+    "README.md",
+    "rule-ownership.md",
+    "installation.md",
+    "environment-check.md",
+    "auth-check.md",
+    "cli-basics.md",
+    "command-discovery.md",
+    "object-context.md",
+    "pagination.md",
+    "interaction.md",
+    "write-guard.md",
+    "output-policy.md",
+    "write-verify.md",
+    "async-task.md",
+    "file-input.md",
+    "state-machine.md",
+    "error-handling.md",
+)
+
+
+def check_links(package: Path) -> list[str]:
+    failures: list[str] = []
+    pattern = re.compile(r"\]\(([^)]+)\)")
+    for path in sorted(package.rglob("*.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        for link in pattern.findall(text):
+            if link.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            target = link.split("#", 1)[0]
+            if target and not (path.parent / target).exists():
+                failures.append(f"{path.relative_to(package)} -> {target}")
+    return failures
+
+
+def check_old_commands(package: Path) -> list[str]:
+    failures: list[str] = []
+    patterns = [re.compile(pattern) for pattern in OLD_COMMAND_PATTERNS]
+    for path in sorted(package.rglob("*.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            if "历史写法" in line or "旧前缀" in line:
+                continue
+            if any(pattern.search(line) for pattern in patterns):
+                failures.append(f"{path.relative_to(package)}:{line_number}")
+    return failures
+
+
+def check_stale_paths(package: Path) -> list[str]:
+    failures: list[str] = []
+    for path in sorted(package.rglob("*.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            for stale_path in STALE_PATHS:
+                if stale_path in line and "references/shared/installation.md" not in line:
+                    failures.append(f"{path.relative_to(package)}:{line_number} contains {stale_path}")
+    return failures
+
+
+def check_shared_files(package: Path) -> list[str]:
+    shared = package / "references" / "shared"
+    return [f"references/shared/{name}" for name in REQUIRED_SHARED_FILES if not (shared / name).is_file()]
+
+
+def check_modules(package: Path) -> list[str]:
+    failures: list[str] = []
+    modules = package / "references" / "modules"
+    shared_markers = ("shared/", "../shared/")
+    for path in sorted(modules.glob("*/MODULE.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        relative = str(path.relative_to(package))
+        if path.parent.name in MODULE_EXCLUSIONS:
+            continue
+        if not any(marker in text for marker in shared_markers):
+            failures.append(f"{relative}: missing shared entrypoint")
+        if not re.search(r"共享前置|共用前置|shared/", text, re.IGNORECASE):
+            failures.append(f"{relative}: missing shared entrypoint section")
+        headings = "\n".join(
+            line.lstrip("#").strip().lower()
+            for line in text.splitlines()
+            if re.match(r"^#{2,4}\s+|^\*\*[^*]+\*\*", line)
+        )
+        missing = [
+            name for name, markers in MODULE_CONTRACT_GROUPS.items()
+            if not any(marker.lower() in headings for marker in markers)
+        ]
+        for name in missing:
+            failures.append(f"{relative}: missing contract group {name}")
+    return failures
+
+
+def check_route_consistency(package: Path) -> list[str]:
+    failures: list[str] = []
+    modules_dir = package / "references" / "modules"
+    index = modules_dir / "README.md"
+    entry = package / "SKILL.md"
+    if not index.is_file() or not entry.is_file():
+        return ["route-consistency: missing SKILL.md or modules README"]
+    module_names = {
+        path.parent.name
+        for path in modules_dir.glob("*/MODULE.md")
+        if path.parent.name not in MODULE_EXCLUSIONS
+    }
+    index_text = index.read_text(encoding="utf-8", errors="replace")
+    entry_text = entry.read_text(encoding="utf-8", errors="replace")
+    for name in sorted(module_names):
+        marker = f"`{name}`"
+        link_marker = f"modules/{name}/MODULE.md"
+        if marker not in index_text:
+            failures.append(f"modules/README.md: missing module {name}")
+        if link_marker not in entry_text:
+            failures.append(f"SKILL.md: missing route link for {name}")
+    return failures
+
+
+def check_entry_bloat(package: Path) -> list[str]:
+    failures: list[str] = []
+    entry = package / "SKILL.md"
+    if not entry.is_file():
+        return ["SKILL.md: missing entrypoint"]
+    text = entry.read_text(encoding="utf-8", errors="replace")
+    for marker in ENTRY_BUSINESS_MARKERS:
+        if marker in text:
+            failures.append(f"SKILL.md: contains module-specific marker {marker}")
+    return failures
+
+
+def check_required_module_files(package: Path) -> list[str]:
+    return [name for name in REQUIRED_MODULE_FILES if not (package / name).is_file()]
+
+
+def check_platform_adapters(package: Path) -> list[str]:
+    failures: list[str] = []
+    adapter_dir = package / ADAPTER_DIR
+    matrix = package / ADAPTER_MATRIX
+    if not matrix.is_file():
+        return [f"{ADAPTER_MATRIX}: missing support matrix"]
+    matrix_text = matrix.read_text(encoding="utf-8", errors="replace")
+    for name in REQUIRED_ADAPTER_FILES:
+        if not (adapter_dir / name).is_file():
+            failures.append(f"{ADAPTER_DIR}/{name}: missing adapter file")
+    index = adapter_dir / "README.md"
+    if index.is_file():
+        text = index.read_text(encoding="utf-8", errors="replace")
+        for filename, markers in ADAPTER_INDEX_MARKERS.items():
+            if all(marker not in text for marker in markers):
+                failures.append(f"{ADAPTER_DIR}/README.md: missing index entry for {filename}")
+            if filename not in matrix_text:
+                failures.append(f"{ADAPTER_MATRIX}: missing matrix entry for {filename}")
+    for path in sorted(adapter_dir.glob("*.md")):
+        if path.name == "README.md":
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        relative = str(path.relative_to(package))
+        if "适配器" not in text:
+            failures.append(f"{relative}: missing adapter declaration")
+        if not any(marker in text for marker in ("运行环境检测", "适配器路由")):
+            failures.append(f"{relative}: missing environment routing section")
+        business_markers = ("exec-part", "conversation_steps")
+        if any(marker in text for marker in business_markers):
+            failures.append(f"{relative}: adapter contains business-layer rules")
+    return failures
+
+
+def check_shared_duplication(package: Path) -> list[str]:
+    failures: list[str] = []
+    modules = package / "references" / "modules"
+    patterns = (
+        ("pagination", re.compile(r"(?:所有|通用|统一).{0,12}(?:分页|去重)")),
+        ("interaction", re.compile(r"(?:所有|通用|统一).{0,12}(?:确认|选择)(?!分类|标签)")),
+        ("output-policy", re.compile(r"(?:所有|通用|统一).{0,12}(?:脱敏|不回显|不显示)")),
+        ("write-verify", re.compile(r"(?:所有|通用|统一).{0,12}(?:回读|幂等|重试前)")),
+    )
+    for path in sorted(modules.glob("*/MODULE.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if path.parent.name == "soke-shared":
+            continue
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            if "共享前置" in line or "按需加载" in line or "业务特有" in line:
+                continue
+            if "标签-分类严格绑定" in line or "标签来源仅限当前分类" in line:
+                continue
+            for name, pattern in patterns:
+                if pattern.search(line):
+                    failures.append(f"{name}: {path.relative_to(package)}:{line_number}")
+    return failures
+
+
+def check_auth_duplication(package: Path) -> list[str]:
+    failures: list[str] = []
+    modules = package / "references" / "modules"
+    for path in sorted(modules.glob("*/MODULE.md")):
+        if path.parent.name == "soke-shared":
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        lines = text.splitlines()
+        for line_number, line in enumerate(lines, start=1):
+            if "auth login" in line or "config show" in line:
+                context = "\n".join(lines[max(0, line_number - 3):line_number + 2])
+                if any(marker in context for marker in ("登录失败", "未登录", "认证错误", "重新登录", "按共享层", "参见共享")):
+                    continue
+                if "共享前置" not in line and "按需加载" not in line and "兼容" not in line:
+                    failures.append(f"{path.relative_to(package)}:{line_number}")
+    return failures
+
+
+def check_python(package: Path) -> list[str]:
+    failures: list[str] = []
+    for path in sorted(package.rglob("*.py")):
+        try:
+            ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        except (OSError, SyntaxError, UnicodeError) as exc:
+            failures.append(f"{path.relative_to(package)}: {exc}")
+    return failures
+
+
+def check_cache_files(package: Path) -> list[str]:
+    return [
+        str(path.relative_to(package))
+        for path in sorted(package.rglob("*"))
+        if path.is_file() and (path.suffix == ".pyc" or path.name == "__pycache__")
+    ]
+
+
+def report(name: str, failures: list[str]) -> bool:
+    if failures:
+        print(f"FAIL {name} count={len(failures)}")
+        for failure in failures[:20]:
+            print(f"  - {failure}")
+        if len(failures) > 20:
+            print(f"  - ... {len(failures) - 20} more")
+        return False
+    print(f"PASS {name}")
+    return True
+
+
+def main() -> int:
+    package = Path(__file__).resolve().parent.parent
+    checks = (
+        ("shared-files", check_shared_files(package)),
+        ("module-index", check_required_module_files(package)),
+        ("platform-adapters", check_platform_adapters(package)),
+        ("markdown-links", check_links(package)),
+        ("stale-paths", check_stale_paths(package)),
+        ("command-prefix", check_old_commands(package)),
+        ("module-contracts", check_modules(package)),
+        ("route-consistency", check_route_consistency(package)),
+        ("entry-bloat", check_entry_bloat(package)),
+        ("auth-duplication", check_auth_duplication(package)),
+        ("shared-duplication", check_shared_duplication(package)),
+        ("python-syntax", check_python(package)),
+        ("python-cache", check_cache_files(package)),
+    )
+    passed = all(report(name, failures) for name, failures in checks)
+    if passed:
+        print("PACKAGE_CHECK_PASS")
+        return 0
+    print("PACKAGE_CHECK_FAIL")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/mono/scripts/check_readiness.py

@@ -11,7 +11,7 @@ from pathlib import Path
 
 def main() -> int:
     package = Path(__file__).resolve().parent.parent
-    guide = package / "references" / "installation.md"
+    guide = package / "references" / "shared" / "installation.md"
     executable = shutil.which("soke-cli")
     print("🔍 soke-cli Mono Skill — 环境检查")
     print(f"  {'✅' if guide.is_file() else '❌'} 安装指南")

package/skills/mono/scripts/check_syntax.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Check Python syntax without writing __pycache__ files."""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    package = Path(__file__).resolve().parent.parent
+    files = sorted(package.rglob("*.py"))
+    failures: list[tuple[Path, Exception]] = []
+
+    for path in files:
+        try:
+            source = path.read_text(encoding="utf-8")
+            ast.parse(source, filename=str(path))
+        except (OSError, SyntaxError, UnicodeError) as exc:
+            failures.append((path, exc))
+            print(f"FAIL {path}: {exc}")
+        else:
+            print(f"OK   {path}")
+
+    if failures:
+        print(f"Python 语法检查失败：{len(failures)} 个文件")
+        return 1
+
+    print(f"Python 语法检查通过：{len(files)} 个文件（未写入 __pycache__）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/mono//357/275/223/357/275/217/357/275/213/357/275/205/357/274/215/357/275/203/357/275/214/357/275/211/346/225/264/344/275/223/346/236/266/346/236/204.html

@@ -0,0 +1,13 @@
+<!doctype html><html lang="zh-CN" data-page-node-id="giwDng1lMQa5QKK8yCk6IX"><head data-page-node-id="TgEtDCFS1kvRuFzGYBlc2E"><meta charset="utf-8" data-page-node-id="JrkCtnBihQB8AD2kxMvJ6g"><meta name="viewport" content="width=device-width, initial-scale=1" data-page-node-id="2Sx1tfupCzGyrWFUsNMAlp"><title>Soke CLI Mono 架构与子技能开发指南</title><style>:root{--ink:#182230;--muted:#64748b;--line:#d8dee8;--paper:#fff;--bg:#f4f6f9;--blue:#2563eb;--blue-soft:#eaf1ff;--teal:#0f766e;--teal-soft:#e7f7f4;--amber:#b45309;--amber-soft:#fff4df;--rose:#be123c;--rose-soft:#fff0f3;--dark:#1e293b}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;line-height:1.65}.shell{display:grid;grid-template-columns:250px minmax(0,1fr);min-height:100vh}.side{position:sticky;top:0;height:100vh;padding:28px 20px;background:#172033;color:#dbe5f5}.brand{font-size:18px;font-weight:700;color:#fff;margin-bottom:4px}.version{font-size:12px;color:#9fb0ca;margin-bottom:25px}.side a{display:block;color:#b9c8dc;text-decoration:none;font-size:13px;padding:8px 10px;border-radius:6px;margin:2px 0}.side a:hover,.side a.active{background:#2b3b57;color:#fff}.main{max-width:1180px;width:100%;margin:0 auto;padding:52px 58px 80px}.hero{background:var(--paper);border:1px solid var(--line);border-radius:12px;padding:34px 38px;margin-bottom:26px}.eyebrow{font-size:12px;color:var(--blue);font-weight:700;letter-spacing:.04em}.hero h1{font-size:34px;line-height:1.2;margin:8px 0 14px;color:#111827}.hero p{max-width:760px;color:var(--muted);margin:0}.grid{display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin:18px 0 28px}.card{background:var(--paper);border:1px solid var(--line);border-radius:8px;padding:20px}.card h3{margin:0 0 6px;font-size:16px}.card p{margin:0;color:var(--muted);font-size:13px}.section{margin:34px 0}.section h2{font-size:24px;margin:0 0 14px;padding-top:10px}.section h3{font-size:17px;margin:24px 0 8px}.lead{color:var(--muted)}.flow{display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:16px 0;padding:18px;background:var(--blue-soft);border:1px solid #cbdcff;border-radius:8px}.step{background:#fff;border:1px solid #b9cdfb;border-radius:6px;padding:8px 12px;font-size:13px}.arrow{color:var(--blue);font-weight:700}.layer{display:grid;grid-template-columns:150px 1fr;gap:0;border:1px solid var(--line);border-radius:8px;overflow:hidden;margin:12px 0;background:#fff}.layer strong{padding:15px;background:var(--dark);color:#fff;font-size:14px}.layer span{padding:15px;color:var(--muted);font-size:14px}.callout{border-left:4px solid var(--blue);background:var(--blue-soft);padding:14px 18px;margin:15px 0;border-radius:0 7px 7px 0}.callout.teal{border-color:var(--teal);background:var(--teal-soft)}.callout.amber{border-color:var(--amber);background:var(--amber-soft)}table{width:100%;border-collapse:collapse;background:#fff;border:1px solid var(--line);border-radius:8px;overflow:hidden;font-size:13px;margin:14px 0}th,td{text-align:left;padding:11px 13px;border-bottom:1px solid var(--line);vertical-align:top}th{background:#f0f3f8;color:#334155;font-weight:700}tr:last-child td{border-bottom:0}code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em;background:#eef2f7;padding:2px 5px;border-radius:4px;color:#334155}pre{background:#111827;color:#dbeafe;padding:17px 19px;border-radius:8px;overflow:auto;font-size:13px;line-height:1.7}ul,ol{padding-left:23px}.check{list-style:none;padding:0}.check li{padding:6px 0}.check li:before{content:"□";color:var(--blue);font-weight:700;margin-right:9px}.footer{margin-top:42px;padding-top:22px;border-top:1px solid var(--line);color:var(--muted);font-size:12px}@media(max-width:850px){.shell{display:block}.side{position:static;height:auto;padding:16px}.side nav{display:flex;gap:4px;overflow:auto}.side a{white-space:nowrap}.main{padding:24px 16px 52px}.hero{padding:25px 22px}.hero h1{font-size:28px}.grid{grid-template-columns:1fr}.layer{grid-template-columns:1fr}.layer strong{padding-bottom:8px}.layer span{padding-top:8px}}</style></head><body data-page-node-id="hBr5gBr6y2g0GxZdAJIBNn"><div class="shell" data-page-node-id="8r8xclmvTJ0stdUtApgALA"><aside class="side" data-page-node-id="5ONDK7D3MujiLqBQFXqXxV"><div class="brand" data-page-node-id="LyyqHmlQ0znRHstqxkg8uD">Soke CLI Mono</div><div class="version" data-page-node-id="I4HNFqNSZhk3CVoAaZAMR3">架构与扩展指南 · v1.0</div><nav data-page-node-id="cl9a43syiqtRoZsHaKddLj"><a href="#overview" class="active" data-page-node-id="AzNoIvBUY0qcHwv2sZxiRs">总览</a><a href="#layers" data-page-node-id="EaoCUuW5vhGnggH1YVqrDq">分层架构</a><a href="#graph" data-page-node-id="TFcXoUSoOzGvuRS9njTeV2">业务图谱</a><a href="#new" data-page-node-id="pkKXQw7qqCamsGgyAbMWNr">新增子技能</a><a href="#team" data-page-node-id="dqKe24KB6DLi8Qj5DdukSx">多人协作</a><a href="#done" data-page-node-id="lVjPGaXoEvpQ4WSrFR2t7D">完成定义</a></nav></aside><main class="main" data-page-node-id="tOex177WSBnspCDCjHsJCv"><header class="hero" id="overview" data-page-node-id="3UGjuIWEj4o0iXCx0G99lk"><div class="eyebrow" data-page-node-id="aYpL00Bu7rv9BrCCPidycy">TEAM DEVELOPMENT REFERENCE</div><h1 data-page-node-id="dGZmzs6IwY8BLVr7OOlB0I">架构与子技能开发指南</h1><p data-page-node-id="boh94yFhpQnTkwonRRjEXJ">面向后续功能开发、多人协作和代码审查的长期参考。核心目标是让每个新需求都能找到清晰归属、唯一事实源和可验证的完成标准。</p></header><div class="grid" data-page-node-id="Acm2xC9pEYEwQEqC6c5Gni"><div class="card" data-page-node-id="0UvgYzmZnbAH6AXZ1Oa8hG"><h3 data-page-node-id="NY3MUpL80tB6vl579CZUbZ">共享规则</h3><p data-page-node-id="SOk4nQlvTOGAXAhjCQDALy">认证、分页、确认、脱敏、验证等跨模块能力。</p></div><div class="card" data-page-node-id="kn1upIYiqcDMH2OkvA1hSS"><h3 data-page-node-id="pgyuGX4a8iGSoKKtbK6Rvr">业务模块</h3><p data-page-node-id="YqvlC7LaEgkPwPEzFAlZgt">围绕业务对象组织职责、输入、流程和特例。</p></div><div class="card" data-page-node-id="goTUEHYIZH3lL5hcTFfNM2"><h3 data-page-node-id="p40svXjR8ThFBQD7Rfy2wM">质量闸门</h3><p data-page-node-id="4Z1PLUocPSTZXQd4fTrL3N">通过自动检查和真实场景验收保障交付质量。</p></div></div><section class="section" id="layers" data-page-node-id="WrEzMzBZNeSVVU8OCCABZF"><h2 data-page-node-id="qQyRaEezstNyTSFcrJEM78">分层架构</h2><p class="lead" data-page-node-id="VMoCI95gHJaGtRiMvwHu9Y">每一层只解决自己的问题，避免规则重复和职责越界。</p><div class="layer" data-page-node-id="ZquIm8qjzZpxZDFfWrsjtp"><strong data-page-node-id="0UnwLNokY6yKwRiQejMEFv">入口调度层</strong><span data-page-node-id="9FoMM8aGWJ8qE9Niuyiud0"><code data-page-node-id="WVTAfxdcThrBeumsF25QyV">SKILL.md</code>：意图识别、模块路由、读取顺序、确认边界。</span></div><div class="layer" data-page-node-id="BPDKv88dkLjA9e2FqtA0vo"><strong data-page-node-id="BAxiDWEIrzjxFzDFHYRap2">共享能力层</strong><span data-page-node-id="jMEOtirCFjiP1PHaDDgUZd"><code data-page-node-id="Nzz8FEIT8K3qDNL22VCnkA">references/shared/</code>：安装、认证、对象、分页、交互、写保护、输出、异步、错误。</span></div><div class="layer" data-page-node-id="pV68pHR0V0RG8DlYo9Pzv2"><strong data-page-node-id="OBAFgL33r6Sesm7v3GVsua">业务模块层</strong><span data-page-node-id="G9jvTLxXCn2nGzB656GWqB"><code data-page-node-id="r4siLY3OIFfxZcGzd3SXKU">references/modules/</code>：课程、考试、地图、指派、AI 教练、AI 陪练等业务对象。</span></div><div class="layer" data-page-node-id="puBHsQUhSCZ3SqT5rPP3bT"><strong data-page-node-id="Yd0rOYJliphPZFPTohknWz">工作流层</strong><span data-page-node-id="WdbekBCV3evDeSDLgIAxsO"><code data-page-node-id="HNTPA5Eh3FQQcw7iEKqa7H">references/workflows/</code>：描述多个模块之间的对象交接，不复制内部规则。</span></div><div class="layer" data-page-node-id="fx4t6yTIc9PpPpNErEJJvi"><strong data-page-node-id="6uuEY50GSP7dNsgzVEPCLO">平台适配层</strong><span data-page-node-id="Yj9BG5JuUyHOcV156k78Ht"><code data-page-node-id="LRjEQ1mmD928psOqv4FNK7">platform/adapters/</code>：WorkBuddy、千问、Zework、QClaw 和通用降级。</span></div><div class="layer" data-page-node-id="eEWvMfyJ6qihlf6oj7oVqc"><strong data-page-node-id="pRg52H4BScmpgbzAtWBFCe">质量保障层</strong><span data-page-node-id="BSRFRDfFZwjnFVqskhJZXp"><code data-page-node-id="87UBBuPG1tSRQRu6xUOq13">scripts/</code>：包结构、链接、命令、入口、矩阵和语法检查。</span></div><div class="callout" data-page-node-id="jpi21HFD5ArGFRDj4TpZkO"><strong data-page-node-id="73NNBGvzUWmj6jA3EsjxY5">边界原则：</strong>共享规则只定义通用约束，模块只保留业务差异，工作流只定义对象交接，适配器只处理平台差异。</div></section><section class="section" id="graph" data-page-node-id="UBY2g5sA518yL239SYyPSH"><h2 data-page-node-id="HTSDTz25YZM5wfeXtfmRU2">业务知识图谱</h2><h3 data-page-node-id="BcfOQ0TeSRkO3EaDQX0dNp">课程链路</h3><div class="flow" data-page-node-id="SAABExsHL0rkseJTGxFNPB"><span class="step" data-page-node-id="kk5VtxAltHqcZvIGOlJXSr">素材上传</span><span class="arrow" data-page-node-id="h8bB8jokSjiZMLKuHfzZIW">→</span><span class="step" data-page-node-id="CoEQpduHe84TDLuEwzyTaU">课件创建</span><span class="arrow" data-page-node-id="RFV8htB44MxH1HrNMyQeGG">→</span><span class="step" data-page-node-id="Tq5UqksDXnf3xV4dlhNePi">课程配置与发布</span><span class="arrow" data-page-node-id="nQ53pFphwEiSvIpoO6rcgF">→</span><span class="step" data-page-node-id="yxgMmWQrdw1XNiWFxOkp02">学习对象指派</span></div><p class="lead" data-page-node-id="nOxJUhGawHWGvHjviqSrOx"><code data-page-node-id="BBYVJc3EwUgdXUisriyW9d">soke-material</code> 的真实素材 ID 是 <code data-page-node-id="rnxqv6tcvvTMS74NvAZ5XW">soke-lesson</code> 的输入，发布后的课程再交给 <code data-page-node-id="s0lFjMwojqypqm4C62pVnn">soke-assign</code>。</p><h3 data-page-node-id="dEK570LEeRc6O99IDI0yu0">考试与学习路径</h3><div class="flow" data-page-node-id="y5GetxBR6zSLtcjaTxHjiq"><span class="step" data-page-node-id="1Syzp3AzpmduEF8aUR5DtM">题库与试卷</span><span class="arrow" data-page-node-id="cKaJlguetpZW8hhFge7xFd">→</span><span class="step" data-page-node-id="ZH475n1nMNulXcE8XzcLUn">考试发布</span><span class="arrow" data-page-node-id="CFCOOGw9zR1IGBSMhCJ11r">→</span><span class="step" data-page-node-id="yrTYvC20p7EnixQ5Gusga2">指派</span><span class="arrow" data-page-node-id="o2uVtTYVctYFPPwGG2kJWx">→</span><span class="step" data-page-node-id="cOQE6ahOb9IZlAJuAeDtVe">成绩或练习分析</span></div><h3 data-page-node-id="Lq3MOCPJJfBXJGReHAmja2">AI 链路</h3><div class="flow" data-page-node-id="BZiZKr3XGkrQEBUHxG7Y1Z"><span class="step" data-page-node-id="XCeJjqa1nn8HJY9CTroNts">原始材料</span><span class="arrow" data-page-node-id="VlIDpSLG3noC3Yxqb98Glb">→</span><span class="step" data-page-node-id="Ula23fEbhAIEGU4NHgnhDY">一次提炼</span><span class="arrow" data-page-node-id="bNUvLaXvVW0Fb3ISgrl6VX">→</span><span class="step" data-page-node-id="FuNtkwS2zoohT2nFQY5cJ1">AI 陪练 Part1-Part5</span><span class="arrow" data-page-node-id="6tkUw3juOuhOEmnwmJDB44">→</span><span class="step" data-page-node-id="D2BPoOFLO3a1Mhpop5fJ6W">同步、闸门、发布</span><span class="arrow" data-page-node-id="9kCNqqpiHmRegnX85jbGUG">→</span><span class="step" data-page-node-id="waGDjvCbVZMmkh7a3yDMjm">知识包绑定</span></div><div class="callout teal" data-page-node-id="4Ub1yxmifViToph92UiTQS"><strong data-page-node-id="aa1ACwJn3p0M7BoC8o4Erz">知识包边界：</strong><code data-page-node-id="VC4MnEmtAeMCkwwAwWdFCY">soke-ai-coach-director</code> 负责原始材料提炼和陪练场景，<code data-page-node-id="WdgNNU7q7hDFPv9PYdbHHr">soke-ai-training</code> 复用提炼稿，负责 source、entries、版本和绑定，不做二次提炼。</div></section><section class="section" id="new" data-page-node-id="3BhSyVEea9DDFkGKIhLav7"><h2 data-page-node-id="veQ7fpE9a2o68bTovtwCmc">新增子技能</h2><h3 data-page-node-id="rNA9c7dEXNzpo5wESzzjgE">先判断归属层</h3><table data-page-node-id="MjrVxqgaK3wuDfAwpPFDXd"><thead data-page-node-id="rZHJSPhWE0BjMUMGTujMYg"><tr data-page-node-id="LpWI0AFxJluOTNLbpGWLlF"><th data-page-node-id="WxmYuaPzKmZaNpG7vZq7Yv">需求特征</th><th data-page-node-id="EALHHpfARXtpiv3WcqFYVB">放置位置</th></tr></thead><tbody data-page-node-id="wwQVck3OzZbsd7ERBvktQd"><tr data-page-node-id="VW2mV6I3T8bZ0HunI7VXHx"><td data-page-node-id="txSxg19BthpJLLBqnXLB5S">多个模块复用的通用能力</td><td data-page-node-id="ua9wJeCGacPEYHKiwkobw7"><code data-page-node-id="V4fLhIofsUMEIc1E75Rbai">references/shared/</code></td></tr><tr data-page-node-id="NiIbpxXqfM3ksx3OJekCRV"><td data-page-node-id="HVkZ0oxfLaIuaCAA4yjwaw">已有业务对象的新动作</td><td data-page-node-id="pem6sF4Jmiy1WkrZKGvuBe">修改现有模块</td></tr><tr data-page-node-id="mrvucDZUNpvdEO70W8hCCB"><td data-page-node-id="OrQHsndeHbfeocPjFyVuVb">新的业务对象</td><td data-page-node-id="fvEhChEvSqWU0GGlGBBM1T">新建 <code data-page-node-id="exz5sElw7xTfBac3BDwvcd">references/modules/soke-xxx/</code></td></tr><tr data-page-node-id="HXB23MLSv8MXdAeggxvITF"><td data-page-node-id="C5SSrhIFAZe3Znvs6ezbYN">两个以上模块串联</td><td data-page-node-id="cEfpbLSiIz1dqg08axPzsp"><code data-page-node-id="CkyAIt1Twy8lxdAuKhd3Wr">references/workflows/</code></td></tr><tr data-page-node-id="ffX8mJchTVzF6pjAV5Uy52"><td data-page-node-id="lfct0GkdnJikF6ogyEQCtY">平台显示、交互或命令差异</td><td data-page-node-id="lTD1L9I2pipupC11Hvkv0O">平台适配器</td></tr><tr data-page-node-id="3ZnRT6zQJba6oqpJfS35O0"><td data-page-node-id="5T5GxguycDeaFu8veRfzEq">可自动验证的约束</td><td data-page-node-id="w9WheTCXbHDWQLK7JGsCRB"><code data-page-node-id="vtcMia9eiUdu8wBkFEClcB">scripts/</code></td></tr></tbody></table><h3 data-page-node-id="CnFEXrV2FcSlJYIY1NyOOx">九步开发法</h3><ol data-page-node-id="JPT9Afgja4CYKHHiZ3ASOk"><li data-page-node-id="vUWdepQ4eAfsYTj7DcBMgP">写清需求边界：谁、对什么对象、做什么动作、得到什么结果。</li><li data-page-node-id="RV0q98CrbpK0yfPRO9eYQi">确认对象与状态：输入、父对象、状态变化、真实 ID、幂等性。</li><li data-page-node-id="1jRWdA7U7yatwQy1GUt51V">选择归属层：共享、现有模块、新模块、工作流、适配器或检查器。</li><li data-page-node-id="TFJYlTQfud3L0EyDix9ali">查询当前 CLI 帮助：<code data-page-node-id="jaKE4bRQeuVqerBNJY6h4B">soke-cli --help</code>、父命令帮助、叶子命令帮助。</li><li data-page-node-id="qeSD6sjsnBIQup85QPzo9c">实现最小闭环：前置检查 → 查询 ID → 确认 → 执行 → 验证 → 输出。</li><li data-page-node-id="KoVn8FCWD5x5dpG1ca84eF">接入入口和索引：更新 <code data-page-node-id="GZ0n9GcaOGdUscdyfXMLd8">SKILL.md</code> 与模块责任矩阵。</li><li data-page-node-id="mg0fzV8lRAstYzmk5Gv5ER">补充专项规则：只保留字段、状态、红线和异常特例。</li><li data-page-node-id="f57PeavpPcGhPUFbqhDiTg">加入自动检查：文件、链接、路径、命令、入口、重复规则和语法。</li><li data-page-node-id="ybCqR9YkniRkQ7H5rrvirr">完成真实场景验收：从用户输入走到最终输出。</li></ol><h3 data-page-node-id="b7Gv8C2nZ9vYpdNGkjvotd">标准模块入口</h3><pre data-page-node-id="Jx1mY6zzNBowH3gFLnfoK0"># soke-new-feature
+
+## 共享前置
+## 职责
+## 不负责
+## 输入
+## 流程
+## 业务特例
+## 输出</pre></section><section class="section" id="team" data-page-node-id="d3VYQLYzAt0eWlNh9qwSCk"><h2 data-page-node-id="GKpa9zUfBtABhUwkyE5U4M">多人协作</h2><table data-page-node-id="vCkaFp5zA8FYEJV09OwNtC"><thead data-page-node-id="V6tNCg56HMFb1OsKx9EDkT"><tr data-page-node-id="jhRvfzPBRR3BfSgpHZhidt"><th data-page-node-id="mtMSADRfBTrV9kiCcVfuSL">角色</th><th data-page-node-id="BItHgaKZ2ic54hHfm5uNuD">负责范围</th></tr></thead><tbody data-page-node-id="wUUpil19MMtAtg2ExHnCsw"><tr data-page-node-id="18dzPu19rkyz45Pe956Dr9"><td data-page-node-id="6hWvurXnqpkpP3oczaihWz">架构维护者</td><td data-page-node-id="XOnaYibc0axdhTmVWA5yIP"><code data-page-node-id="1CjIVrkctLqqxjOGG0K2Qv">SKILL.md</code>、共享规则、唯一来源矩阵</td></tr><tr data-page-node-id="4U4reJFx3exoSjh81Ivosy"><td data-page-node-id="AFMMnAKO31o3vYbofQSoD5">业务开发者</td><td data-page-node-id="ABGLaGTdcTPwuFWi4fXbGd">单个业务模块目录</td></tr><tr data-page-node-id="sfRUCkep3yCDGbGf580yWJ"><td data-page-node-id="Gr8SEsO5tT0vrR7xM1NnKJ">工作流开发者</td><td data-page-node-id="2V3C1U7PUGCkEzx2UmYIwJ">跨模块流程和交接契约</td></tr><tr data-page-node-id="a9zpBuZc25C4DQ0lY0JSB8"><td data-page-node-id="pLnqS4kDoshivWS8QEbWjF">平台开发者</td><td data-page-node-id="sTshb4uexItvlh03djXGKH">单个平台适配器和支持矩阵</td></tr><tr data-page-node-id="uvOhtksLZJ4OwntYvf7Jmj"><td data-page-node-id="qkv1v6AxB5usMPHDb3CmSv">质量维护者</td><td data-page-node-id="1lp7y28c0lgY9sLUIm3lMH"><code data-page-node-id="xPixrKQ0u94Wa9lgQ6qrRs">check_package.py</code> 和检查规则</td></tr><tr data-page-node-id="3UwFSLCZyudfKvGLB6ozbf"><td data-page-node-id="ox8UMqW0jeoTOEl9xNJ1Yp">验收人员</td><td data-page-node-id="8eAZRswAnsQx7iXacTOsm1">CLI 帮助、真实场景和回归验证</td></tr></tbody></table><div class="callout amber" data-page-node-id="Op4hjfdAUDptMW1G2P52Tq"><strong data-page-node-id="tR47VF8Rviw8d8yFYrw2rA">协作红线：</strong>同一时间尽量不要多人修改同一个入口文件。若两人同时修改共享规则、两个模块争夺同一对象，或检查器与业务特例冲突，应先建立唯一事实源再继续。</div><h3 data-page-node-id="ftuxYAUh0sS3UZG6mZo9RN">开发前声明</h3><pre data-page-node-id="gBRBGmUOegituWg62PME04">修改文件：
+不修改文件：
+依赖模块：
+验收命令：</pre><h3 data-page-node-id="VVKHm4QGMGDAuAY82lydCw">合并前命令</h3><pre data-page-node-id="1NLuLCca9sAU7b7KumPjwc">/Users/edy/.workbuddy/binaries/python/versions/3.13.12/bin/python3 skills/mono/scripts/check_package.py
+git diff --check</pre></section><section class="section" id="done" data-page-node-id="3xh6FXGiDSbZQ0bItCBHbp"><h2 data-page-node-id="u6IaLWDdr1LHqUK0vXr7Ds">完成定义</h2><ul class="check" data-page-node-id="wbba9yBsn76PFfdd8qUBJV"><li data-page-node-id="UkEAvj0Fim04MrAYkoJjqu">业务对象和职责边界已定义。</li><li data-page-node-id="LFOcoshvBfUKTSFcHIzvH5">归属层级已确定，不重复已有能力。</li><li data-page-node-id="2MxghxOszQ2XfrMPTOeqwj">模块入口符合标准结构。</li><li data-page-node-id="h46s2uKubsUfWH9EEywr5R">真实 ID 来源和状态变化明确。</li><li data-page-node-id="7bQn1ADDqSkgp85Fa55DUo">写操作有确认、验证和幂等策略。</li><li data-page-node-id="AtTYlRAova1jTvb0mSlL0A">入口路由、模块矩阵和工作流已更新。</li><li data-page-node-id="oCxHmNIk5myJfWb1OCtYXA">机器检查通过。</li><li data-page-node-id="P9MDiYmBAMuDEz2BBtR3Kr"><code data-page-node-id="IOqmxF6WOiBzFHfJCd5GUC">git diff --check</code> 通过。</li><li data-page-node-id="wxjf0ab6FEYAj9CCHunZNM">至少完成一条真实场景验收。</li><li data-page-node-id="9SwE0JW33gaVJFEPgcA8RZ">变更范围和剩余风险已记录。</li></ul><div class="footer" data-page-node-id="FxzHq4ATuOKVbwuW9IFovi">唯一原则：先判层级，再定边界；先定义对象，再选命令；先复用共享，再写特例；先完成闭环，再扩展异常。</div></section></main></div></body></html>

package/skills/multi/soke-course/.skill-metadata.yaml

@@ -0,0 +1,40 @@
+examples:
+  - id: create-and-publish
+    title:
+      zh: 创建课程并发布
+    description:
+      zh: 从零创建一门线上课，走完课件、发布全流程
+    prompt:
+      zh: |-
+        帮我创建一门线上课：
+
+        课程标题：{{课程标题}}
+        课程分类：{{可选，分类名称}}
+
+        创建完成后引导我添加课件并发布。
+  - id: add-courseware
+    title:
+      zh: 给课程加课件
+    description:
+      zh: 给已有课程添加视频/音频/文档/图片/小测验课件
+    prompt:
+      zh: |-
+        给课程「{{课程名称}}」添加课件：
+
+        素材：{{本地文件路径或"从素材库选择"或"小测验/图片"}}
+  - id: publish-and-assign
+    title:
+      zh: 发布并指派学员
+    description:
+      zh: 对已有课程执行发布校验、发布，并指派给部门
+    prompt:
+      zh: |-
+        把课程「{{课程名称}}」发布，并指派给{{部门名称}}，{{必修|选修}}。
+  - id: query-progress
+    title:
+      zh: 查学习进度
+    description:
+      zh: 查询课程完成率、学员进度、作业提交情况
+    prompt:
+      zh: |-
+        看看课程「{{课程名称}}」的学习进度和完成率。