技能使用说明文档生成器
Overview
为一个已安装的技能生成一份详细、真实、精美的 HTML 使用说明文档。文档内容严格取自该技能的实际源文件（SKILL.md、scripts/、references/、assets/），不编造任何参数与能力；输出为单文件自包含 HTML（样式内联、图片 base64、零外部依赖、响应式）。
触发场景说明（重要）
本技能有两类触发意图，处理方式相同——都走完整工作流生成使用说明 HTML 文档：
| 触发意图 | 典型说法 | 处理方式 |
|---|---|---|
| 显式生成文档 | "生成 xx 技能的使用文档"、"给 xx 技能写说明" | 直接进入第 1 步 |
| 使用咨询（极易漏触发） | "xx 这个技能怎么使用 / 如何使用 / 怎么用 / 用法是什么 / 有什么使用教程" | 同样必须触发本技能，以生成的 HTML 使用说明文档作为回答；文档重点放在"怎么用（提示词示例）"章节，交付时在文字回复中先用 2~3 句话直接回答使用方法要点，再给出文档 |
用户问"怎么用"时的常见误区是只做口头回答、跳过本文档生成流程——凡问句指向"某个已安装技能的用法"，一律加载本技能并产出文档，不得仅凭 SKILL.md 摘要简单作答了事。
工作流程
第 1 步：定位目标技能
运行定位脚本（Windows 用受管 Python 绝对路径）：
python <skill目录>/scripts/locate_skill.py <用户输入的技能名>
python <skill目录>/scripts/locate_skill.py --list # 不确定名称时先列出全部
匹配规则（必须遵守）：
- 脚本已实现"slug 精确匹配优先，模糊匹配兜底"。若返回 match_type: slug-exact，直接采用
- 若返回多条 fuzzy 结果（中文显示名可能不唯一），必须把候选清单呈现给用户（列出 slug、路径、description 首句），让用户确认选择后才能继续；严禁自行假定选某一个
- 若返回为空（exit code 2）：目标技能未安装——
1. 先跑 --list 确认是否只是名称写法差异，并展示相近候选让用户确认
2. 确认确实未安装后，提示用户先安装该技能：可主动提出帮忙搜索并安装（用技能搜索安装能力按用户给的名称查找），或请用户提供技能文件/目录
3. 在技能安装完成前不生成文档；用户确认已装好后，从第 1 步重新执行流程
第 2 步：深度阅读技能源文件
读取目标技能目录下的全部内容，作为文档唯一信息来源：
- SKILL.md（frontmatter 的 name/description + 全部正文）
- scripts/ 下每个脚本（读代码确认真实参数、用法；可用 --help 或无副作用方式验证）
- references/、assets/、其他文件（确认是否有示例、模板、测试产物）
第 3 步：起草文档内容（真实性红线）
- 提示词导向（核心原则）：文档读者是与智能体对话的普通用户，正文以"怎么说 → 得到什么"为主线——教用户用提示词触发技能、用自然语言表达参数诉求；脚本命令与 CLI 参数一律降级为"进阶"折叠补充，不作为主要使用方式（仅当技能只能手动执行脚本时才以命令为主体并注明）
- 只写源文件里实际存在的功能、参数、流程；参数表以脚本代码为准，不以猜测为准
- 无法确认或源文件缺失的信息：不编造，明确写 "待确认"（HTML 中用
<span class="tag-todo">待确认</span>标注） - 归纳概述时可以组织语言，但不得引入源文件没有的能力或承诺
第 4 步：准备案例演示
按优先级准备 demo 素材，并按"用户提示词（say-box）→ 智能体内部实际做了什么 → 产出结果"三段组织每个案例：
1. 技能自带示例（SKILL.md Example、assets/references 中的样例文件）
2. 若技能脚本可安全运行（无破坏性、无需用户私有数据），实际运行一次，记录真实命令与真实输出
3. 案例涉及图片（截图、效果图、示例图）：用 python <skill目录>/scripts/img_to_base64.py <图片路径> 转为 data URI 内嵌；目录批量转换加 --json
4. 目标技能无可演示成品时，实跑一次并截图：若目标技能目录中没有成品示例文件、且其脚本运行也不产生图形结果（如对话驱动的生成类技能），则用目标技能实际运行一次，产出其成品（如攻略/报表/文档 HTML），再对成品 HTML 渲染截图：
- 运行前若需要用户提供输入（如出行信息、参数），先向用户收集必要信息，不得臆测
- 截图保存到当前工作空间目录（如 {slug}-案例截图.png），不得写入目标技能的 assets/ 等目录
- 用 img_to_base64.py 转为 data URI 内嵌进文档，并注明"图为实际运行产生"——此为真实案例，不需要再加"模拟数据"标注
5. 以上均无法获得真实案例时（如运行需要无法提供的私有数据、外部服务不可用），才写基于真实参数的模拟示例并加 tag-todo 标注"示例为模拟数据"
第 5 步：生成 HTML 文档
严格按 references/html-template.md 生成：
- 先选主题：根据目标技能的 slug/description/触发词判断领域，从模板规范的"主题适配"一节六类主题（terminal-dev / paper-reading / data-pro / playful-creative / warm-edu / clean-default）中选定一个，按其变量与装饰改写样式基准；禁止所有文档套用同一套样式，footer 注明所用主题
- 输出文件：
{slug}-使用说明.html（写入当前工作目录，或用户指定目录） - 硬性检查清单（生成后逐项自查）：
- [ ] 无任何外部引用（搜一遍http:///https:///@import/<link，只允许正文示例代码中出现）
- [ ]<meta name="viewport">存在，样式全部内联
- [ ] 所有图片为 base64 data URI
- [ ] 六大 section 齐全，含"信息来源与待确认事项"
- [ ] slug 与被文档化技能 frontmatter 的name一致
- [ ] 待确认信息均有标注
- [ ] 主题与技能领域匹配，已按主题覆盖配色/字体/装饰，结构类名未变
- [ ] 以提示词用法为主线：usage 有 ≥3 条 say-box 话术，参数以"你想要的/示例说法/内部参数"映射，命令收进进阶折叠
第 6 步：交付
用 present_files 展示生成的 HTML；汇报中说明：匹配到的技能（slug + 路径）、文档包含的案例来源、以及待确认事项清单。
禁止事项
- 匹配到多个技能时不得擅自替用户选定
- 目标技能未安装时不得凭记忆、网络资料或想象生成文档——文档内容只能来自本机实际读取的源文件
- 不得虚构技能功能、参数、默认值或运行结果
- 不得引用外部 CDN 资源（CSS/JS/字体/图标一律内联）
- 不得因技能文档简略而跳过"待确认"标注、强行把文档写满
