@sokeai/cli 1.0.76 → 1.0.77

package/skills/soke-ai-coach-director/references/env-check.md

@@ -0,0 +1,146 @@
+# soke-cli 环境检测
+
+独立于页面/创作管线，仅在需要调用平台接口时执行。
+
+---
+
+## 依赖清单
+
+| 依赖 | 最低版本 | 用途 | 安装方式 |
+|------|----------|------|----------|
+| Node.js | v14+ | 运行时 | https://nodejs.org/ |
+| soke-cli | 1.0.67+ | 平台 CLI | 平台提供安装包 |
+| Python 3 | 3.10+ | 脚本执行 | https://www.python.org/ |
+| pdftotext | 系统自带 | PDF 文本提取 | macOS: `brew install poppler` · Linux: `apt install poppler-utils` |
+
+> ✅ `soke-cli auth login` 采用 **OAuth 设备流**：命令启动后自动尝试打开浏览器，同时输出授权链接，阻塞等待扫码授权。检测到未登录时，**由 AI 自动执行**（后台拉起 → 提取授权链接 → 前台引导用户扫码 → 授权完成后自动重检继续），**不要求用户手动运行命令**。
+
+---
+
+## 检测流程
+
+按顺序执行，任一步不通过则停止并引导修复。
+
+### 1. Node.js 版本
+
+```bash
+node --version
+```
+
+- ✅ >= 14.0.0 → 通过
+- ❌ 未安装或版本过低 → 提示：`需要 Node.js >= 14.0.0，请先安装或升级`
+- ❌ `command not found` → 提示安装 Node.js
+
+---
+
+### 2. soke-cli 安装
+
+```bash
+which soke-cli && soke-cli --version
+```
+
+- ✅ 输出版本号 → 通过
+- ❌ `command not found` → 执行安装：
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+npm install -g @sokeai/cli@latest
+```
+
+安装后重新执行 `which soke-cli && soke-cli --version` 验证。
+
+> Windows：将 `~/.zshrc` 替换为 PowerShell profile 路径，PATH 追加方式不同（见安装指南 Q2）。
+
+---
+
+### 3. 登录状态
+
+```bash
+soke-cli config show
+```
+
+判定字段：`用户凭证`（非空即已登录）。
+
+- ✅ 输出含 `用户凭证` 且非空 → 通过，进入下一步企业绑定检查
+- ❌ `用户凭证` 为空 → **AI 自动执行登录**（🔇 后台，无需用户手动跑命令）：
+
+```bash
+# Bash 工具参数：run_in_background=true, dangerouslyDisableSandbox=true
+soke-cli auth login
+```
+
+自动执行流程：
+
+1. 后台启动 `soke-cli auth login`，命令阻塞等待授权（OAuth 设备流，不会自行退出）
+2. 读取命令输出，提取授权链接（形如 `https://saas.soke.cn/...?cli_redirect_uri=http%3A%2F%2F127.0.0.1%3A<port>%2Fcallback`）
+3. 📺 前台告知用户（一句话）：「浏览器已自动打开，请扫码完成授权；若未自动打开，请访问：<授权链接>」
+4. 等待命令退出（用户在浏览器完成授权后进程自动结束）→ 重新执行 `soke-cli config show` 确认 `用户凭证` 已存在
+5. 授权完成 → 静默继续下一步企业绑定检查；若用户放弃/超时 → 停掉后台任务，提示用户随时说「继续」重新拉起登录
+
+> ⏳ 授权链接带 `cli_redirect_uri` 回调参数，必须完整复制、不可截断；浏览器未自动打开时用户手动访问该链接即可。
+
+- ❌ 返回 `401 Unauthorized` → Token 过期，自动重新登录：
+
+```bash
+soke-cli auth logout
+soke-cli auth login   # 按上述自动执行流程（后台拉起 + 引导扫码）
+```
+
+登录成功后重新执行 `soke-cli config show`，确认 `用户凭证` 已恢复。
+
+---
+
+### 4. 企业绑定（corp binding）
+
+```bash
+soke-cli config show
+```
+
+判定字段：`corpid`（非空即已绑定企业）。
+
+- ✅ `corpid` 非空 → 通过，记录企业 ID 供后续使用
+- ❌ `corpid` 为空 → 提示用户：
+  > 已登录，但当前账号未绑定企业。请先在授客AI平台完成企业绑定，再重新执行 `soke-cli auth login --force`
+
+如需强制刷新企业绑定信息，执行：
+
+```bash
+soke-cli auth login --force   # 自动执行流程同上（后台拉起 + 引导扫码）
+```
+
+完成后重新执行 `soke-cli config show`，确认 `corpid` 非空。
+
+如果仍为空，说明当前账号未加入任何企业，需联系管理员添加。
+
+---
+
+## 常见故障速查
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| `which soke-cli` 无输出但已安装 | PATH 未生效 | `source ~/.zshrc` 或新开终端 |
+| `401 Unauthorized` | Token 过期 | `soke-cli auth logout && soke-cli auth login`（后者自动执行） |
+| 登录时浏览器未打开 | 系统无默认浏览器 | 用户手动访问 AI 提供的授权链接（完整复制含 `cli_redirect_uri`） |
+| 授权链接无法访问 | 链接被截断/过期 | 停掉当前后台任务，重新 `soke-cli auth login` 生成新链接 |
+| `npm: command not found` | Node.js 未安装 | 安装 Node.js >= 14 |
+| `EACCES` 权限错误 | npm 全局安装需要 sudo | 使用 `~/.npm-global` 方案（见步骤2） |
+| `corpid` 为空 | 未绑定企业 | `soke-cli auth login --force` 重新授权，或联系管理员 |
+
+---
+
+## 使用方式
+
+```
+# 在 ai-coach-director 中
+read references/env-check.md
+按顺序执行 4 步检测：
+  1. node --version
+  2. which soke-cli && soke-cli --version
+  3. soke-cli config show → 确认「用户凭证」非空；为空则自动执行 soke-cli auth login（后台拉起 + 引导扫码）
+  4. soke-cli config show → 确认 corpid 非空
+全部通过 → 记录企业 ID，继续调度
+任一步失败 → 按修复流程处理（登录类自动拉起授权），不进入内容生成/同步
+```

package/skills/soke-ai-coach-director/references/exec-common.md

@@ -0,0 +1,126 @@
+# 通用执行约束（Common Execution Rules）
+
+> v2.41 从 exec-handbook.md 拆分。所有 Part 共享的 CLI 参数、材料铁律、字段类型硬规则、状态快照规则。
+> 各 Part 专属模板/断言/反面案例见 `exec-partN.md`。
+
+---
+
+## CLI 参数固定值
+
+- `--scenario-id <id>`（不是 `--scenario <id>`）
+- apply 需要 `--idempotency-key <unique>` 和 `--reason "PartN同步"`（v2.41：省略 --reason 会导致 422）
+- 每次 apply 后必须重新获取 `updated_at` 作为下次 `--base-updated-at`
+- **所有 CLI 输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向**，禁止 `--pretty` 直出到对话。Python 从重定向文件提取字段，不回显 JSON 原文。
+- **apply 禁止用于验证**。验证数据用 `+get-scenario`，apply 后只从返回值提取 `updated_at`（`tail -1` 或 Python 提取），不回显 operations/snapshot_id。用 apply 回读环节会导致 `add_conversation_step` 重复添加。
+
+---
+
+## 材料预处理铁律（v2.41 强化：预过滤）
+
+非结构化材料（PDF/DOCX/PPT）处理流程：
+1. **预过滤（v2.41 新增）**：先看文件名/标题，只对与场景直接相关的材料做 pdftotext。无关材料直接标注「已跳过：与场景无关」。
+2. **一次成型写提炼稿**：pdftotext 提取到 `/tmp/` → **一次性** grep 定位 + sed 读取关键段落 → Write 落盘提炼稿到 `/tmp/xxx_refined.md`。**禁止分多轮 sed 回看**。
+3. **原始材料全文不再进入后续 Part 上下文**——Part1-5 生成只读提炼稿
+4. 提炼稿只保留 Part1-5 所需结构化要素（业务背景/训练对象/话术/画像线索/异议/红线/评分线索）
+5. 提炼稿删除无关段落（目录/版权页/附录/重复章节）
+6. 提炼稿 ≤1500 字（硬上限），超了二次压缩只保留核心要素
+7. **提炼稿落盘后，后续 Part1-5 只 Read 这一个文件**，不再碰原始 PDF/DOCX
+
+---
+
+## 后台静默规则（G1/G3）
+
+所有 CLI 错误（stderr / 非零退出 / 422 / 409）**禁止对用户展示**。AI 内部分析修正（最多 2 次重试），仍失败仅告知"Part N 同步异常"+ ≤50 字原因。
+
+---
+
+## 输出过滤规则（v2.35 反压缩强化）
+
+后台 Python 脚本的 print() 输出、JSON 文件大小、字符数统计、自查断言结果（"✅ xxx"）→ 🔇 后台静默，**禁止出现在对话消息中**。
+
+**CLI 输出强制静默**：
+- 所有 soke-cli 命令输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向
+- preview/apply 命令一律 `2>/dev/null | tail -3`，只看结尾 3 行状态
+- `+get-scenario` 回读一律 `> /tmp/xxx.json` 重定向，Python 只打印 `True/False` 布尔判断
+- snapshot_id / updated_at / warnings / operations 回显**一律吞掉**
+- **apply 禁止用于验证**：apply 是写入操作，不是读取操作。用 apply 回读环节会导致 `add_conversation_step` 重复添加 → 需快照回滚 → 浪费 3-5 积分。验证用 `+get-scenario`。
+- 仅失败时输出 ≤50 字原因
+
+---
+
+## 平台头像库
+
+正确路径前缀：`https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/`（❌ 错误：`/public/ai/avatar/`，存进去 UI 空白）。
+头像 URL 一律通过 `soke-cli ai-training +list-role-avatars` **重定向到 /tmp/avatars.json 后 Python 按性别/年龄关键词过滤 title 字段提取 url**（禁止 `--pretty` 直出，禁止 `--gender`/`--age-group` 参数——CLI 不支持）。声音同理重定向到 `/tmp/voices.json` 后 Python 提取 `id`。
+
+---
+
+## JSON 字段类型硬规则
+
+> 原则：**文档是什么类型，就严格按什么类型生成。**
+
+### string 字段：必须生成字符串
+
+多条内容用顿号、分号、编号或 `\n` 拼接为一个字符串，禁止写成数组。
+
+关键 string 字段：`name`、`description`、`key_points`、`role_data.name`、`role_data.description`、`role_data.avatar`、`role_data.communication_style`、`role_data.background`、`role_data.personality_type`、`role_data.personality`、`role_data.voice_id`、`ai_roles_overall_description`、`opening_dialogue`、`conversation_steps[].step_name`、`conversation_steps[].student_objective`、`conversation_steps[].ai_task`、`criteria_data.name`、`criteria_data.description`、`dimensions[].code`、`dimensions[].name`、`dimensions[].description`、`dimensions[].scoring_rule`
+
+### string[] 字段：只有明确数组字段才生成数组
+
+每条一个元素：`tags`、`conversation_knowledge_base_ids`、`scoring_knowledge_base_ids`、`role_data.tags`、`role_data.knowledge_level`、`role_data.taboos_objections`、`dimensions[].criteria`
+
+### number / boolean / null 字段
+
+- number 不加引号：`weight`、`total_weight`、`max_rounds`、`max_practice_attempts`、`passing_score`、`pass_difficulty`、`dimensions[].sort_order`
+- boolean 不加引号：`is_custom_role`、`is_custom_criteria`、`ai_assistance_enabled`
+- null 写 `null`，不写空字符串或 `"null"`
+
+### 创建/更新差异
+
+- 创建 `conversation_steps` 用 `ai_objective`；更新用 `ai_task`。
+- 创建 `conversation_steps[].sort_order` 写字符串（`"1"`）；评分维度 `sort_order` 写数字（`1`）。
+
+### 生成前自检
+
+```text
+☐ string 字段没有被写成数组或对象
+☐ string[] 字段没有被写成逗号分隔字符串
+☐ number 字段没有加引号
+☐ boolean 字段没有加引号
+☐ null 字段没有写成 "" 或 "null"
+☐ 创建/更新 sort_order 类型符合对应接口要求
+```
+
+---
+
+## 状态快照与缓存规则
+
+### state-snapshot.json 结构
+
+```json
+{
+  "mode": "partwise",
+  "scenario_id": "scn_xxx",
+  "scenario_short": "b7730195",
+  "updated_at": "2026-07-10T01:40:58.216028Z",
+  "current_part": "part3",
+  "confirmed_data": { "part1": {}, "part2": {}, "part3": {}, "part4": {}, "part5": {} },
+  "applied": { "part1": true, "part2": true, "part3": false, "part4": false, "part5": false },
+  "cached": { "role_profile": {}, "scenario_type": "" },
+  "file_reads": 0
+}
+```
+
+### 依赖与回滚规则
+
+- Part1 修改 → Part2-Part5 全部待复核
+- Part2 修改 → 至少重检 Part3 与 Part5
+- Part3 修改 → 至少重检 Part4 与 Part5
+- Part4 修改 → 重检 Part5
+- Part5 修改通常不反推前序 Part，但若改动通关分数/难度，需检查与 Part4 评分体系一致
+
+---
+
+## 沙箱绕过（G4）
+
+WorkBuddy Bash 调用 soke-cli 必须设 `dangerouslyDisableSandbox: true`。