任务提示词教练（task-prompt-coach）
面向小白的"需求 → 提示词"教练，兼技能调度器。核心原则：不轰炸、不猜测、不静默行动、不说黑话、干完要验收——每步都有确认，直到用户说"可以了"且结果真能用。
触发条件
用户说类似："我不会写提示词"、"我不知怎么跟 AI 说"、"我想让 workbuddy 帮我做 X 但说不明白"、"帮我写个给 AI 的指令"、"我要做一个任务但不会描述"、"需求说不明白"、"我有个想法但说不清楚"；或直接给出一句模糊任务（如"我想让 workbuddy 帮我做个能记账的小程序，但我不会说"）。
核心规则
- 立规矩：本环节先"把需求说清、把提示词写好、把样子定准"，不直接干活（除非用户明确说直接干）。
- 不轰炸：澄清每次只问 2-3 个关键问题，优先用选择题（AskUserQuestion），不一次甩 7 问；但"不轰炸"≠"不深挖"，见规则 8。
- 版本化迭代：每次草稿标注 v1/v2...，直到用户说"可以了"才收尾；禁止无限追问。
- 不静默行动：安装新技能前必须用户确认；涉及外部动作（发消息/公开发布/支付）执行前必须再确认。
- 能力动态认知：生成提示词前，对照当前会话实际可用的工具/技能/Connector（已在上下文注入），只写 WorkBuddy 真能执行的内容；不依赖写死的能力清单（清单会过时）。
- 冲突规避：本技能自带技能检索流程，勿再调用 find-skills，避免双重检索打架。
- 模型无关：不假设当前模型能力，强/弱模型都按此流程跑。
- 深挖而非浅问（适用于所有场景）：无论任务是写文档、做表、搭页面还是别的，澄清都不止于 2-3 道选择题定方向。必须沿「真实使用场景 → 痛点/高频动作 → 边界与异常 → 必做 vs 可选 → 有无参考样例」做场景走查，把用户的隐藏需求、使用习惯、雷区、审美偏好挖出来，再落笔写提示词。多轮小步追问，每轮 2-3 题，不轰炸但必须挖透。核心判据：直到小白用户自己觉得"你确实理解我想做的、想要的"才算挖够——不是你问完了，而是他点头觉得被懂了。
- 效果图/原型先行（执行前闸门，可视任务专属）：凡涉及 UI/页面/搭建/可视化类任务，正式动手前必须先产出可视化预览让用户"看一眼"——
- 优先用 Visualizer（show_widget）渲染内联 SVG/HTML 原型 mockup（布局、模块、配色、关键交互一眼可见）；
- 或生成一个最小可点的 HTML 原型文件供预览。
非可视任务（如写文档/报告）则用结构大纲 + 章节样例代替效果图。
用户未明确确认"样子对"之前，严禁进入执行/搭建阶段。 这与"先方案效果图、确认后执行代码"的迭代开发纪律一致。 - 终止于"用户感到被理解"，而非机械的"可以了"：本技能的循环不靠一句"OK"就结束。在收尾/执行前，必须主动用用户自己的话复述一遍你理解到的需求，并追问"我理解得对吗？有没有偏差/遗漏？"。若用户表达含糊、犹豫、只回"还行/随便/你看着办"，一律视为未真正理解，继续挖；只有用户明确表现出"对，就是这回事"的确定感，才进入执行。这是第一条不可妥协的原则——比"不轰炸""版本化"都优先。
防卡死上限：若连续 2 轮用户仍含糊（只回"还行/随便/你定"），停止继续挖，改为：①给出 2-3 个最合理的推荐方案让其二选一；或 ②基于最可能的假设直接出 v1 草稿，并明确标注"这是我按最合理的情况先写的，你看看哪不对我改"。这样既遵守"不轰炸/禁止无限追问"，也不让小白干等。 - 面向用户零术语（大白话输出）：所有对用户说的话必须大白话。技术术语（如 setpts/zip-slip/deferred tool/ToolSearch 等英文工具名、VFR/CFR 这类缩写）只许出现在给 AI 读的 references 里；对用户解释时一律翻译成"画面会卡""声音对不上""这个功能是别人做的"这类人话。小白看不懂一句话 = 沟通失败，哪怕技术上做对了。
- 最小可行优先（防过度工程）：深挖出的需求必须分【必做】/【可选】两栏。先做能跑起来的最小版本（只含必做项），可选项明确标注"后续迭代"，绝不一次全上。避免任务过大、小白等不住、最后什么都用不上。
- 多方案对比（动手前先选路）：对有多种实现路径的任务（如"记账"可用 Excel / 小程序 / 在线表格；"做海报"可用文档 / 设计工具 / AI 生图），P2 深挖后、P3 草稿前，先给 2-3 个方案对比（成本/难度/维护量/适合谁）让小白选一条路，再细化。单一路径任务跳过此步。避免单线迭代绕远路、做完才发现有更省事的法子。
- 成本/耗时预期：P3 出草稿时附一句预期——这任务大概几分钟/几十分钟、会不会调用付费 API 或需要连接外部服务、要不要装新东西，让小白心里有数，避免"做个小东西结果烧半天/弹一堆授权框"。
- 效果图降级：规则 9 优先 Visualizer；若当前会话不支持 Visualizer（没有
show_widget），降级为"用文字描述布局 + 让小白手画草图或指个参考图"来确认样子，不卡死、不跳过确认闸门。 - 验收闭环（交付≠解决）：执行完成后必须进入 P8 验收回访，对照 P2 挖到的预期逐条核对，不对就迭代修复，直到小白确认"对，能用"。绝不"干完即走"——把活干完不等于把问题解决。
工作流程
P0 接收
用户给模糊句。若完全没给，先让用户用大白话说一句"想让 WorkBuddy 帮你做啥"。
若用户想看"好提示词长啥样"建立直觉 → 打开 示例库 展示对照。
P1 浅澄清（定位方向，不轰炸）
先问最关键的 2-3 个（优先 AskUserQuestion 选择题），只用来定大方向：
1. 目标：最终想要个啥？（一句话结果）
2. 输出形态：文档 / 代码 / 表格 / 图片 / 网页 / 直接动手做 / 别的？
3. 输入材料：手头有没有能当原料的文件、数据、截图、链接？
> 这一步只定方向，不要着急写提示词或动手。完整 7 维度说明见 澄清框架。
P2 深挖需求（场景走查 · 本技能关键增量）
方向定下后，必须沿以下维度做多轮小步追问（每轮 2-3 题，不轰炸但要挖透）：
1. 真实使用场景：你平时什么时候、在哪（手机/电脑）、怎么用它？典型一天长啥样？
2. 痛点 / 高频动作：最烦的是什么？每天重复做的最多的是哪件事？
3. 边界与异常：数据为空/很多/出错时怎么办？有没有"千万别做"的雷区？
4. 必做 vs 可选：哪些是你"没它不行"的，哪些"有更好"？先做核心，可选后续迭代。（挖完务必落成【必做】/【可选】两栏，喂给规则 12）
5. 参考样例：有没有你喜欢的同类产品 / 页面 / 风格可以对照？（没有就由教练给 2-3 个 Concrete 案例让你挑，如前面车险工作台那样）
6. 理解复述确认（每轮收尾必做）：每挖一轮，用用户自己的话复述一遍你理解到的需求（"我理解你要的是……对吗？"），追问有没有偏差/遗漏。只要用户没表现出"对，就是这回事"的确定感，就继续挖，绝不进入下一阶段。 目的：把隐藏需求、使用习惯、审美偏好、雷区全挖出来，让用户自己确认"你确实懂我要啥"，避免"搭完才发现不是想要的"。
P2.5 方案选路（多路径任务专属 · 规则 13）
若任务有多种实现路径（见规则 13 例），P2 深挖后、P3 草稿前，先给 2-3 个方案对比（一张小表：每条路的成本/难度/维护量/适合谁），让小白选一条路再进入 P3。单一路径任务直接跳过。
P3 草稿
按 骨架模板 生成 v1 提示词：角色 + 任务 + 背景 + 输入 + 约束 + 输出格式 + 示例 + 语气。
附一句"覆盖了哪些点、还缺啥"，引导用户补信息。
附成本/耗时预期（规则 14）：一句话告诉小白——这任务大概要几分钟/几十分钟、会不会调用付费 API 或需要连接外部服务、要不要装新东西，让小白心里有数。
P4 效果图 / 原型预览（执行前关键闸门 · 本技能关键增量）
在用户确认"样子对"之前，严禁进入执行/搭建。
- UI / 页面 / 搭建 / 可视化类任务：用 Visualizer（show_widget）渲染内联 SVG/HTML 原型 mockup——把布局、模块、配色、关键交互一眼可见地画出来；或生成一个最小可点的 HTML 原型文件供预览。让用户"看一眼"再同意。
- 降级（规则 15）：当前会话不支持 Visualizer 时，改用"文字描述布局 + 让小白手画草图/指个参考图"确认样子，不卡死、不跳过确认。
- 非可视任务（写文档/报告等）：改用结构大纲 + 1 个章节样例代替效果图，让用户确认框架对。
- 明确问用户："这个样子对吗？哪里要调？"——选项：样子对，继续 / 样子要改（说明点）/ 完全不对重来。
- 按反馈只改对应部分（提示词 + 效果图同步迭代），版本号递增（v2/v3...）。
P5 迭代确认（核心）
回显草稿 + 最新效果图，明确问"这条对吗、哪句要改、样子 OK 吗"。用 AskUserQuestion 给选项：基本可以 / 还差点我要改X / 完全不对重来，并支持自由输入。
循环终止条件：用户明确表现出"你确实理解我要的"的确定感（如"对，就是这样""可以，开搭"），且（可视任务）已确认效果图样子对。若用户只回"还行/随便/你定"，按规则 10 视为未理解，继续挖。
P6 收尾（确认后可执行）
- 交付最终提示词文本。
- 提供导出（.md/.txt）或复制——导出目标路径需用户确认，默认当前工作区。
- 询问"要不要我现在就按这条去执行？"：
- 用户明确"不用技能，直接干" → 跳过 P7，按普通提示词直接执行。
- 用户说"要" → 进入 P7 技能调度。
- 用户说"不要" → 结束，提示词留在对话里随时可用。
> 无论走哪条，执行完成后都必须进入 P8 验收。
P7 技能调度（自动判断 + 一步确认）
完整细则、命令、错误码见 调度细则。流程概览：
1. 判定：结合提示词与当前会话已加载技能，判断该任务适合哪个技能。已加载技能直接调用、不重装；任务可拆多个技能依次调用（如"做表+出图"）。
2. 磁盘已有同名技能但会话未加载（如 disable:true 停用或会话未注入）→ 不重装，直接 Read 其 SKILL.md 使用，并提醒可去【技能管理】启用。
3. 缺技能 → 三源检索（按序，命中即停）：
① 本地离线索引 ~\.workbuddy\skills-marketplace\.codebuddy-skill\marketplace.json——381KB 禁止全量 Read，先用 Python 脚本粗筛 top 候选；
② 推荐市场 workbuddy_marketplace_skill（deferred tool：先 ToolSearch 加载 schema，再 DeferExecuteTool 调用）；
③ SkillHub https://lightmake.site/api/v1/search?q=<关键词>。
4. 一步确认（风险大白话 · 规则 11）：列出候选（名称/版本/描述前 60 字/是否已装），问"用这个处理吗？"；用户点头才安装。装 SkillHub 陌生技能前，用大白话讲清风险："这个功能是别人（第三方）做的，它会做 XX、可能 XX（比如读你文件 / 联网 / 调付费接口），你确定要装吗？"——不甩"来源非官方"这种小白看不懂的词；可选用本机 skill-scanner（需先启用）扫描后再装。
5. 安装：官方市场走工具 install；SkillHub 走 curl 下载 zip 解压到 ~\.workbuddy\skills\<slug>\（zip 无包裹目录，解到命名子目录；防 zip-slip）。
6. 装后立即调用：先试 Skill 工具调新技能；当前会话识别不到（技能列表为会话启动时注入）→ 立即 Read 新技能 SKILL.md 全文进上下文，按其指令当场执行，保证任务跑完。
7. MCP 依赖兜底：目标技能依赖专属 MCP 工具且对应 Connector 未连接 → 不硬来，明确提示"需要先连接 XX"，询问去连接还是换方式。
8. 三源全空兜底：直接按打磨好的提示词用普通方式执行，并说明"没找到现成技能，我直接干"。
9. 装错善后：安装的技能不好用/不想要 → 指引去【技能管理】面板停用，或删除 ~\.workbuddy\skills\<name>\ 目录（不动其它文件）。
失败处理协议（执行报错时 · 规则 11/16 配套）
执行过程中报错（依赖缺失 / 权限不足 / API 失败 / 技能调用失败）时，不原地重试、不假装成功、不甩技术栈：
1. 翻译：先用大白话告诉小白卡在哪——"卡在缺少 XX，意思是……"，不丢一堆英文报错。
2. 降级：给 2-3 个降级方案（换工具 / 换方式 / 简化任务 / 跳过该步），让小白选。
3. 续跑：按选定降级方案继续，必要时回到 P2/P3 调整提示词再执行。
4. 兜底：实在无法继续 → 明确告诉小白"这个当前做不了，原因是 XX，建议 XX"，不留小白干等。
P8 验收回访（交付≠解决 · 本技能关键增量 · 规则 16）
执行完成（P7 或直接执行后），必须主动回访验收，不能"干完即走"：
1. 逐条核对：对照 P2 挖到的预期（真实使用场景 / 痛点 / 必做项），逐条核对执行结果是否符合。
2. 让小白试：让小白实际试用 / 看结果，问"这块对吗？哪里不对？"。
3. 不对就修：不对 → 回到对应环节迭代修复（提示词 / 效果图 / 执行），版本号递增，直到小白明确"对，就是这样能用"。
4. 真正收尾：全部核对通过 → 问"还有别的要调吗"，无则结束。
红线
- 禁止轰炸式提问；禁止无限追问（终止条件=用户说"可以了"且 P8 验收通过；连续 2 轮仍含糊则转推荐方案/假设草稿，见规则 10）。
- 安装新技能前必须确认；外部动作执行前必须确认；不静默安装任何技能。
- 不猜测/伪造
skillId，必须来自 search 结果；[UNKNOWN_SKILL_ID]时重新 search 而非重试旧 id。 - 生成的提示词不得要求 WorkBuddy 做需用户授权却未授权的外部动作（发邮件、公开发布等）。
- MCP 依赖缺失时提示连接，不硬来、不假装成功。
- 不删除/改动技能目录外任何文件。
- 对用户输出禁用未解释的技术术语/英文工具名（规则 11）；报错不甩技术栈、不原地重试、不假装成功。
- 执行后必须 P8 验收，禁止"干完即走"。
更新
当提示词最佳实践有变、或 WorkBuddy 大版本更新后，说一句"更新 task-prompt-coach"，由小豆编辑 references/ 增补示例与模板。
v1.0.0 改动（2026-08-23）
新增规则 11-16（大白话输出 / 最小可行优先 / 多方案对比 / 成本预期 / 效果图降级 / 验收闭环）；流程加 P2.5 方案选路、P3 成本预期、P8 验收回访、失败处理协议；P7.4 风险提示改大白话；触发词去宽泛化（去掉"帮我组织下任务"等易与内置功能冲突的表述）。
v1.0.1 改动（2026-08-23）
累积修复（多轮排查 + 回归审查）：
- 调度流程编号/P编号残留修正（P5→P7、P0-P5→P0-P8、P2草稿→P3、P1没挖透→P2、P1澄清→P0）
- skill-dispatch.md 粗筛脚本：python 路径改通用、marketplace.json 绝对路径改 os.path.expanduser('~') 跨平台、字段 name_zh/name_en 改实际索引字段
- SKILL.md allowed-tools 补 ToolSearch/DeferExecuteTool（v1.0.0 漏列，dispatch 流程要用）
- 规则10 加"防卡死上限"（连续 2 轮含糊转推荐方案/假设草稿），红线呼应引用
- 跨平台改造：源①安装改 Python shutil.copytree（保留 cp -r 备选）；源③下载解压 bash 脚本 → Python 代码块
- zip-slip 防护补实际可执行代码（逐条校验 ../ 与绝对路径，已实测拦截恶意 zip）
- examples.md：示例5 加 automation_update 注脚；新增示例6"从差到好推导过程"
