@sokeai/cli 1.0.77 → 1.0.79

package/skills/multi/soke-ai-coach-director/references/cases/micro-tune//345/206/234/346/210/267/345/274/240/350/200/201/346/235/277/347/263/273/345/210/227//345/206/234/346/210/267/345/274/240/350/200/201/346/235/277/346/217/220/347/244/272/350/257/215/344/274/230/345/214/226_V2_/350/257/212/346/226/255/344/272/244/344/273/230_20260609.md

@@ -0,0 +1,26 @@
+# 农户张老板提示词优化 V2 — 诊断与交付
+
+## 任务目标
+根据用户4个优化点（开场追问过多、被动转场、问题随机性不足、主题轮次不平衡），对农户张老板【现场面访-异议化解】提示词进行诊断和优化。
+
+## 分析对象
+AI（客户角色 - 农户张老板）的角色一致性、对话行为逻辑、问题随机性。
+
+## 诊断结论
+全部4个问题根因在提示词结构缺陷，非模型随机性问题：
+1. **开场无硬边界**：开场引导只有"抛出问题"逻辑，无结束条件，导致9轮追问
+2. **开场→三环节缺衔接**：开场完成后等待学员问"还有什么问题"，被动转场
+3. **随机性软指令失效**："等概率随机抽取"LLM天然倾向选列表第一项
+4. **化解条件过松**：主题C"找我们就可以了"即判定化解，无追问
+
+标签：P(4处)、S(1处)、L(2处)
+
+## 5处核心修改
+1. **开场增设3轮硬上限**（首发+最多2追问）
+2. **开场→三环节自动衔接**（不等学员询问）
+3. **随机性编号洗牌硬约束**（A1~A8等，禁止默认选排头题）
+4. **化解条件收紧**（必须包含实质性解释）
+5. **最小追问保底**（每主题至少1次引导性追问）+ 主题C追问方向指引
+
+## 交付物
+- 完整优化版提示词：`农户张老板现场面访_异议化解_优化版_V2_20260609.md`

package/skills/multi/soke-ai-coach-director/references/cases//345/233/233/345/244/247/345/234/272/346/231/257_GoodCase_BadCase_20260701.md

@@ -0,0 +1,194 @@
+# 四大高频陪练场景 — Good Case & Bad Case 对话示例
+
+> 基于《服装导购 AI 陪练体系方案》评分维度生成
+> 以下所有对话均为学员与 AI 顾客之间的文字交互，评分仅基于学员的文字输出
+
+---
+
+## 场景 A：黄金前 7 秒——破冰与闪躲
+
+### Good Case（得分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（S型慢热） | （进店，目光四处扫了一下）……我随便看看。 |
+| 2 | 🎓 **学员** | 好的姐，您先随便看看，不着急。这边是我们这周刚到的新款春装，那边是经典款专区，您自己感受一下。我不打扰您，有需要随时叫我哈。 |
+
+> **🏆 评分要点命中：**
+> - ✅ 空间承诺：「您先随便看看」「不打扰」「有需要叫我」→ 三项空间释放语全部命中
+> - ✅ 产品信息软吸引：「这周刚到的新款春装」「经典款专区」→ 给了顾客两个可关注的锚点
+> - ✅ 顾客说"随便看看"后不再紧逼 → 一轮回应即止
+> - ✅ 未使用任何禁止话术
+
+---
+
+### Bad Case（扣分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（S型慢热） | （进店，目光四处扫了一下）……我随便看看。 |
+| 2 | 🎓 **学员** | 您好，想看点什么？我们这边有新到的春季外套，要不要试试？最近这款卖得特别好。您平时穿什么风格的？ |
+| 3 | 🤖 AI 顾客 | ……（皱眉，往后退了半步）真的就随便看看。 |
+| 4 | 🎓 **学员** | 没关系没关系！我们这边还有连衣裙、半裙，您喜欢什么类型的？我帮您推荐几款。 |
+
+> **🚨 扣分点分析：**
+> - ❌ 踩中禁止话术「想看点什么？」→ 触发扣分
+> - ❌ 紧跟推销「要不要试试？」30秒内出现 → 触发扣分
+> - ❌ 顾客说随便看看后继续追问 → 没有空间释放
+> - ❌ 连珠炮发问（3个问题一句输出）→ 信息释放节奏差
+> - ❌ 第四轮还在追 → 典型"吓跑顾客"型
+> - **得分预测：10/100**
+
+---
+
+## 场景 B：试穿/试衣——连带与扩单
+
+### Good Case（得分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（I型情绪型） | （从试衣间出来，照着镜子）嗯……这件西装上身效果确实不错！ |
+| 2 | 🎓 **学员** | 姐，这件西装剪裁很利落，您穿上特别提气质！不过我注意到您里面搭的这件高领毛衣稍微有点厚重，显得上半身不够轻盈。您试试这件真丝V领吊带，往里面一搭，那种法式松弛高级感立马就出来了。我帮您一起拿进试衣间？ |
+| 3 | 🤖 AI 顾客 | 哦？那试试看吧……不过我今天主要就是买西装的。 |
+| 4 | 🎓 **学员** | 没问题姐，西装肯定是主角。这件吊带您先感受一下搭配效果，喜欢就一起带走，今天刚好满2000减200，两件一起还能省一笔。不喜欢也完全没关系，您试了再说。 |
+
+> **🏆 评分要点命中：**
+> - ✅ 连带时机：顾客先说"效果确实不错"，确认满意后才推 → 时机正确
+> - ✅ 连带理由：搭配逻辑（剪裁利落+高领厚重+真丝轻盈）+ 风格描述（法式松弛高级感）→ 有具体搭配理由
+> - ✅ 连带数量：只推了 1 件（真丝吊带）→ 不超过 2 件
+> - ✅ 给拒绝空间：「不喜欢也完全没关系，您试了再说」→ 低压迫
+> - ✅ 附加：优惠顺带「满2000减200」自然融入，不生硬
+> - ✅ 未使用禁止话术
+
+---
+
+### Bad Case（扣分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（I型情绪型） | （从试衣间出来，照着镜子）嗯……这件西装上身效果确实不错！ |
+| 2 | 🎓 **学员** | 那必须的！对了姐，要不要再看看这个内搭？这件也不错，还有这条裤子，跟这件西装配一套特别好看。还有这条丝巾，也是这季的热卖款，都带上吧！我帮您一起包起来。 |
+
+> **🚨 扣分点分析：**
+> - ❌ 连带时机尚可（顾客说了满意），但……
+> - ❌ 踩中禁止话术「要不要再看看这个？」→ 直接扣分
+> - ❌ 连带理由缺失 → 只说"特别好看"，没讲为什么搭
+> - ❌ 连带数量失控 → 内搭+裤子+丝巾 = 3件，"洗劫式"推荐
+> - ❌ 踩中禁止话术「都带上吧」→ 直接扣分
+> - ❌ 没给拒绝空间 → 直接「帮您包起来」，压迫感拉满
+> - **得分预测：15/100**
+
+---
+
+## 场景 C：临门一脚——嫌贵与抗拒
+
+### Good Case（得分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（C型理性型） | （试穿了羊绒大衣，照镜子看了很久）……好看是好看，但这个价格……确实有点高了。 |
+| 2 | 🎓 **学员** | 姐，我特别理解您。这件大衣第一眼看价格确实不低，很多老顾客第一次看到也是这个感受。 |
+| 3 | 🎓 **学员** | 不过姐，我跟您说实话——这件是100%纯山羊绒的，市面上这个级别的基本都在5000往上。而且羊绒这种东西，穿得好打理得好，三五年不走型。您算一下，一件穿5年，一年穿3个月，平均一天才一块多钱。一块多钱您上哪儿买到这种高级感对吧？ |
+| 4 | 🤖 AI 顾客 | 嗯……话是这么说，但还是有点纠结。 |
+| 5 | 🎓 **学员** | 纠结很正常，买大件确实得想清楚。不过姐我跟您透个底——这个烟灰色是我们这季的限定色，全国每家门店配额就几件。我们店今天就剩这一件您的尺码了，早上刚走一件。您要是今天带走，我帮您申请店长折扣，还能再省一笔。来，这边我帮您包起来？ |
+
+> **🏆 评分要点命中：**
+> - ✅ 先认同：「我特别理解您」「第一眼看价格确实不低」→ 站在顾客这边
+> - ✅ 总价→单位成本：「一件5年，平均一天一块多钱」→ 价值拆解到位
+> - ✅ 可验证证据：「100%纯山羊绒」「5000往上」→ 具体材质+市场对比
+> - ✅ 社会证明+稀缺感：「很多老顾客也是这个感受」「限定色」「就剩一件」「早上刚走一件」→ 合理制造紧迫感
+> - ✅ 推进成交：「来，这边我帮您包起来」→ 拆解完主动推进
+> - ✅ 未使用禁止话术
+
+---
+
+### Bad Case（扣分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客（C型理性型） | （试穿了羊绒大衣，照镜子看了很久）……好看是好看，但这个价格……确实有点高了。 |
+| 2 | 🎓 **学员** | 这不贵了姐，一分钱一分货嘛！好东西就是贵，我们家衣服质量摆在这儿呢。您还差这点钱吗？喜欢就带走吧！ |
+
+> **🚨 扣分点分析：**
+> - ❌ 踩中禁止话术「这不贵了」→ 直接扣分
+> - ❌ 踩中禁止话术「一分钱一分货」→ 直接扣分（红线级别）
+> - ❌ 踩中禁止话术「好东西就是贵」→ 直接扣分
+> - ❌ 踩中禁止话术「您还差这点钱吗？」→ 直接扣分（侮辱性）
+> - ❌ 四句回应踩了四条禁止话术黑名单
+> - ❌ 没有认同 → 开头直接否定顾客感受
+> - ❌ 没有价值拆解 → 一句"质量摆在这儿"空泛无证据
+> - ❌ 没有总价→单位成本换算
+> - **得分预测：0/100（四条红色禁语同时触发，直接不及格）**
+
+---
+
+## 场景 D：离店前——私域锁客
+
+### Good Case A：已购顾客
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客 | （买了一件真丝衬衫，拎着购物袋准备走）谢谢啊，那我先走了。 |
+| 2 | 🎓 **学员** | 姐等一下！这件真丝衬衫洗涤方面有些讲究的。我加您个企业微信，稍后把真丝洗涤和保养的视频发给您，平常看看就不会洗坏了。以后衣服扣子松了、抽丝了这种小问题，您随时微信拍给我，我帮您安排回店免费打理，不用您专门跑一趟售后。 |
+| 3 | 🤖 AI 顾客 | 哦那挺方便的，那加一个吧。 |
+| 4 | 🎓 **学员** | 好嘞姐！您扫这个码就行。以后有什么新款到店，或者您喜欢的这种真丝材质的单品，我也第一时间发给您看看。祝您穿得开心！ |
+
+> **🏆 评分要点命中：**
+> - ✅ 服务价值前置：「真丝洗涤讲究」「洗涤保养视频」「回店免费打理」→ 全是"为你服务"
+> - ✅ 区分已购客话术 → 以售后/保养为切入点，恰当
+> - ✅ 记住了顾客特征：「您喜欢的这种真丝材质的单品」→ 体现"我记得你"
+> - ✅ 被拒绝前的预防性铺垫到位 → 顾客自然接受
+> - ✅ 未使用任何禁止话术
+
+---
+
+### Good Case B：未购顾客
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客 | （聊了半小时，试了好几件，但最终没买）算了，今天先不买了，回头再说吧。谢谢你啊。 |
+| 2 | 🎓 **学员** | 没事的姐，选衣服就得选到真心喜欢的。不过您今天试的那件燕麦色风衣其实特别适合您——您肩膀线条好，穿这种落肩版型特别好看。下周二我们刚好有一批高端定制新品到店，我加您个微信，到了我先把图片发您过目，有喜欢的帮您提前留码，您不用再跑一趟来碰运气。 |
+| 3 | 🤖 AI 顾客 | （犹豫了一下）嗯……那行吧，你扫我。 |
+| 4 | 🎓 **学员** | 好的姐，加了。您放心，我不会没事骚扰您的，只有确实适合您风格的款到了我才发。祝您今天愉快！ |
+
+> **🏆 评分要点命中：**
+> - ✅ 明确后续价值：「高端定制新品到店」「提前留码，不用白跑」→ 价值清晰
+> - ✅ 区分未购客话术 → 以"新品先看/留码"为切入点，恰当
+> - ✅ 记住了顾客特征：「肩膀线条好」「落肩版型」「燕麦色风衣」→ 细节记忆体现专业
+> - ✅ 不忘降低防备：「不会没事骚扰您」→ 主动消解顾虑
+> - ✅ 未使用任何禁止话术
+
+---
+
+### Bad Case（扣分示例）
+
+| 轮次 | 角色 | 对话内容 |
+|:---:|:---:|---|
+| 1 | 🤖 AI 顾客 | （没买，聊了会儿准备走）行，那我先走了，谢谢你啊。 |
+| 2 | 🎓 **学员** | 好的！对了姐，加个微信吧，以后有活动通知你。来扫一下码。 |
+| 3 | 🤖 AI 顾客 | 呃……不用了吧，我平时不怎么加微信的。 |
+| 4 | 🎓 **学员** | 加一下又不费事！我们经常有优惠活动的，你不加就错过了。而且以后新款到了也能通知你，来吧扫一下。 |
+
+> **🚨 扣分点分析：**
+> - ❌ 踩中禁止话术「加个微信吧，有活动通知你」→ 纯营销动机，直接扣分
+> - ❌ 踩中禁止话术「扫一下码吧」→ 直接扣分
+> - ❌ 服务价值缺失 → 没提供任何"为你服务"的理由
+> - ❌ 被拒绝后纠缠 → "加一下又不费事"+ 继续要求 → 触发红线扣分
+> - ❌ 未区分未购客话术 → 对未购客用促销活动来留微信，逻辑完全走偏
+> - ❌ 没有记住顾客任何特征 → 泛泛而谈
+> - **得分预测：5/100**
+
+---
+
+## 附：评分对照速查表
+
+| 场景 | Good Case 关键信号 | Bad Case 致命错误 |
+|:---:|---|---|
+| **A 破冰** | 空间承诺 + 产品信息锚点 + 不追问 | 「想看点什么？」「要不要试试？」+ 连续追问 |
+| **B 连带** | 主品确认后推 + 搭配理由 + ≤2件 + 给拒绝空间 | 「要不要再看看？」+ 无理由 + ≥3件 + 「都带上吧」 |
+| **C 嫌贵** | 先认同 + 总价→日成本 + 材质证据 + 推进成交 | 「一分钱一分货」「这不贵了」「好东西就是贵」「您还差这点钱吗」 |
+| **D 锁客** | 服务价值前置 + 区分已购/未购 + 记住特征 + 不纠缠 | 「有活动通知你」+ 被拒后「加一下又不费事」 |
+
+---
+
+> **使用方法**：培训师/店长可将 Bad Case 对话直接复制到 AI 陪练系统作为反例教材，学员需逐条指出错误并改写为 Good Case。亦可用于新人入职培训时的"找茬"训练环节。

package/skills/multi/soke-ai-coach-director/references/cases//346/241/210/344/276/213/345/272/223/350/241/245/345/205/205_2026-06-24.md

@@ -0,0 +1,41 @@
+# 案例库补充 — 2026-06-24
+
+## 操作
+将 历史项目提示词目录 下 21 个 AI 陪练提示词文件批量复制到案例库。
+
+## 目标位置
+本技能 `references/cases/` 目录
+
+## 新增清单（21 份）
+### 银行面访（5）
+- 企业家王总【电话约访】
+- 企业家王总【现场面访-寒暄破冰】
+- 企业家王总【现场面访-个人及家庭情况KYC】
+- 企业家王总【现场面访-事业经营KYC】
+- 企业家王总【现场面访-合作促成】
+
+### 零售服装销售（3）
+- 主推产品（N36BA6B057 女款冲锋衣）FAB 话术
+- 主推产品（N26BZ01657）FAB 话术
+- 主推产品（N36BATG017 王俊凯同款防晒衣）FAB 话术
+
+### 超市导购（2）
+- 某功效护肤品牌牙膏七步SOP实战演练3.0
+- 舒客宝贝抗糖盾牙膏SOP销售演练
+
+### 民宿管家（9）
+- 办理入住流程演练 v2.0
+- 在住客房清洁 v2.0
+- 宾客电话回访 v2.0
+- 电话预订流程 v2.0（两份）
+- 销售区产品售后处理 v2.0
+- 投诉处理标准化 v2.0
+- 客人异常事件投诉处理
+- 退房时满意度沟通 v2.0
+
+### 餐厅服务（2）
+- 菜品不合口味退菜处理 v2.0
+- 顾客等待超时投诉处理
+
+## 结果
+案例库从 16 份 → **37 份**，后续 prompt-engineer / prompt-optimizer 参考样本更丰富。

package/skills/multi/soke-ai-coach-director/references/change-log-partwise-refactor.md

@@ -0,0 +1,74 @@
+# Partwise 重构变更摘要
+
+> 记录 `ai-coach-director` 从旧三步大包流程迁移到 Part1-Part5 逐段编排流程的关键变化，供后续维护、交接和回归检查使用。
+
+## 1. 架构层重构
+
+- 新增 `coaching/prompt-engineer/parts/part1-basic.md`
+- `prompt-engineer.md` 从 Step1/Step2/Step3 大包改为 Part1 → Part2 → Part3 → Part4 → Part5 串行生成、确认、同步
+- `interaction.md` 改为 5 个 Part 弹窗 + 1 个微调诊断弹窗
+- `sync-engine.md` 改为 Step1 create + Part2/Part3/Part4/Part5 operations 的 Partwise 同步引擎
+- 状态快照统一改为 `mode: "partwise"`，使用 `current_part`、`confirmed_data.part1~part5`、`applied.part1~part5`
+
+## 2. 真实 API 差异修正
+
+### Part3 对话流程
+- 历史旧写法：`replace_conversation_steps`
+- 实证结论：平台不接受整包替换
+- 当前规范：使用 `add_conversation_step` / `patch_conversation_step` / `remove_conversation_step` / `reorder_conversation_steps`
+
+### Part4 评分配置
+- 历史旧写法：`criteria_data` / `one_vote_veto` 直接平铺在 `data`
+- 实证结论：真实请求必须包在 `data.config`
+- 当前规范：使用 `data.config.criteria_data` 与 `data.config.one_vote_veto`
+
+### Step1 创建
+- 历史误区：只传基础字段即可创建
+- 实证结论：缺少 `scenario_cover` 会直接失败
+- 当前规范：直接写入固定默认封面到 `step1-create.json`
+
+## 3. Part2 角色结构升级
+
+### 已验证的稳定规则
+- `replace_ai_roles` 可用，但不能只传裸 `role_data`
+- 必须使用完整 custom role 外壳
+- `avatar` 输入必须是头像资源 URL（来自 `+list-role-avatars` 的 `url` 字段），不是资源 ID
+- `voice_id` 输入必须是声音资源 ID（来自 `+list-role-voices` 的 `id` 字段）
+- `knowledge_level` 必须是数组，不是字符串
+- `replace_ai_roles` 的数据键是 `data.roles`（非 `data.ai_roles`）
+- 必须提供 `scenario_role_id`（如 `role_kong_dajie`）
+- 建议同时写入 `tags`、`source_type`、`customized_fields`、`created_at`、`updated_at`
+
+### 上游约束同步
+- `prompt-engineer.md` Step2 已明确头像/语音留空待 Part2 apply 后自动匹配回填（见 `role-resource-matching.md`），不再在内容阶段手写资源 ID
+- `part2-roles.md` 已新增平台落地硬规则、资源字段和生成后自检清单
+- `sync-engine.md` 已加入 Part2 成功结构与错误排查规则
+
+## 4. 经验沉淀
+
+- 新增 `references/platform-api-pitfalls.md`
+- 当历史文档、示例和真实 CLI 返回冲突时，以踩坑清单 + 最新实证为准
+- `SKILL.md`、`prompt-engineer.md`、`sync-engine.md` 已显式引用该清单
+
+## 5. 审查结果
+
+本轮重构后，创建链路主文档已基本统一到 Partwise 口径：
+
+- `SKILL.md`：总控入口与平台同步主口径已切换
+- `prompt-engineer.md`：生成流程与 Part2 上游约束已切换
+- `interaction.md`：弹窗模板与回退链路已对齐
+- `sync-engine.md`：字段映射、CLI 模板、错误表已切换
+
+### 本轮补修的文案问题
+- 修复 `interaction.md` 中“取消回退链路”与实际按钮不一致的问题
+- 旧文案原先把模板 2-6 都写成“取消”，但实际按钮分别是“重设角色设定 / 重设对话流程 / 重设评分标准 / 重设练习设置和知识库 / 保持原样”
+- 现已改为与真实按钮一致的“回退链路”描述
+
+## 6. 建议的回归检查顺序
+
+1. 创建型流程：Part1 → Part5 各模板是否与按钮文案一致
+2. 同步层：各 Part 的 JSON 文件名、CLI 参数、错误处理表是否一致
+3. Part2：角色卡资源字段、数组字段、custom role 外壳是否完整
+4. Part3：流程操作是否仍误用整包替换
+5. Part4：评分配置是否仍遗漏 `data.config`
+6. apply 后是否强制执行一次 `+get-scenario --raw` 验收

package/skills/multi/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/multi/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`。