Skill 中文说明生成器
为已安装的 Skill（任何平台、任何目录，只要包含 SKILL.md）自动生成专业、结构化的中文使用说明文档（默认 README_CN.md，兼容 使用说明.md）。机械步骤（目录发现、解析、草稿、报告、质检）由 scripts/generate_readme.py 完成；语言本地化与示例补全由你（Agent）基于脚本产出的草稿完成。
触发条件
- 「为 [skill-name] 生成中文说明」
- 「给 [skill-name] 添加中文文档 / 写中文使用说明 / 翻译文档 / 创建中文 README」
- 「为所有 skill 生成中文说明 / 批量添加中文文档 / 一键生成中文文档 / 全部翻译成中文」
- 关键词组合：
skill+中文+说明/文档/README，或生成+中文+skill，或翻译+skill+中文
核心能力
- 目录自动发现 — 默认扫描本技能的上级文件夹（见「目录发现规则」）。
- 容错解析 — 解析 SKILL.md 的 YAML frontmatter 与 Markdown 章节；frontmatter 异常时降级为正则提取，不中断。
- 草稿生成 — 产出结构完整的 README_CN.md 草稿（标题 / 简介 / 触发条件 / 功能特性 / 参数 / 配置 / 注意事项）；能从源 SKILL.md 预填触发条件、功能特性、注意事项、参数表、使用方法/配置对应章节的原文，待译处统一标注
<!-- TODO(translate) -->，Agent 只需翻译与润色。 - 批量与跳过 — 支持「全部」模式；已存在中文文档时默认跳过，除非
--force。 - 质量检查 — 生成后校验必备章节、标题层级、表格列数、未翻译占位符。
前置依赖
- Python 3.8+（脚本零第三方依赖，使用标准库）。
- 无需网络。
工具脚本（可选加速器）
机械步骤优先调用脚本（更快、更一致、带 QA）。若环境无 Python 或脚本缺失，Agent 按下方「草稿模板」直接完成，功能不受影响。
# 定位脚本
SCRIPT="scripts/generate_readme.py"
PY="python" # 任意 Python 3.8+ 解释器均可
# 可用性自检（不可用时跳过本段，走 Agent 直接生成）
command -v "$PY" >/dev/null 2>&1 && [ -f "$SCRIPT" ] || echo "NO_PYTHON_FALLBACK"
# 单数：生成草稿（不覆盖已存在）
$PY "$SCRIPT" --skill summarize
# 一键翻译：LLM 回填中文并直接写回 README_CN.md（需配置 .env 的 DEEPSEEK_API_KEY）
$PY "$SCRIPT" --skill summarize --translate
# 仅导出结构化 JSON（供外部 LLM 回填，不写 md）
$PY "$SCRIPT" --skill summarize --json-out draft.json
# 单数：强制覆盖
$PY "$SCRIPT" --skill summarize --force
# 批量：扫描所有技能目录，生成缺失者
$PY "$SCRIPT" --all
# 预览将要处理的技能（不写文件）
$PY "$SCRIPT" --all --dry-run
# 指定目录 / 输出 JSON 报告（默认扫描本技能的上级文件夹，即兄弟技能包所在目录）
$PY "$SCRIPT" --all --report-json
脚本退出码：0 全部成功或仅跳过；1 存在生成失败；2 参数错误。
> 无 Python 也不影响功能：脚本仅是加速器。检测不到 python 或脚本文件时，Agent 仍可按「草稿模板」独立生成中文文档，不依赖任何外部运行时。
本地化指引（Agent 翻译步骤）
将源 SKILL.md 映射为 8 段中文文档：
| 中文章节 | 来源 | 处理 |
|---|---|---|
| 简介 | frontmatter description |
去技术腔，缩为 1–2 句 |
| 触发条件 | 源「触发」章节 bullets | 逐条翻译（脚本已预填原文） |
| 功能特性 | 源「功能 / Features / 核心能力」bullets | 逐条翻译（脚本已预填原文） |
| 使用方法 | 源「使用方法 / Usage」章节 | 保留代码块原样，仅译说明文字；补 2–3 个场景示例 |
| 参数说明 | 源参数表格 | 表头译中文；单元格的参数名/类型/英文值保留，说明翻译 |
| 配置说明 | 源「配置 / 环境」章节 | 环境变量名保留英文，说明翻译 |
| 注意事项 | 源「注意 / Notes」bullets | 逐条翻译（脚本已预填原文） |
规则：技术术语（API/CLI/JSON/SDK）、代码、参数名（--model）、环境变量名（OPENAI_API_KEY）一律不译；使用中文标点；定稿前移除全部 <!-- TODO(translate) -->。术语中英对照见 references/terminology.md。
> 脚本已预填的章节（功能特性 / 触发条件 / 注意事项 / 参数表 / 使用方法·配置源文块）无需从零撰写，直接翻译预填内容即可，显著降低翻译负担与遗漏风险。
一键翻译模式（--translate）
已配置 LLM 密钥时，可跳过 Agent 手工翻译，实现真正一键生成：
python scripts/generate_readme.py --skill <name> --translate
内部流程：脚本解析 → 产出结构化 JSON（字段模型）→ scripts/llm_bridge.py 调用 DeepSeek 将各字段回填中文 → 直接写回 README_CN.md。翻译由 LLM 完成，Agent 无需逐段改写。
配置（写入 scripts/.env 或环境变量，密钥不入库）：
- DEEPSEEK_API_KEY（必填）
- DEEPSEEK_BASE_URL / DEEPSEEK_MODEL（可选，默认 deepseek-chat）
- LLM_PROXY（可选；留空直连）
分离用法（调试 / 外部管线）：先用 --json-out draft.json 导出结构化 JSON，再 python scripts/llm_bridge.py draft.json --out zh.json 翻译，最后由 Agent 按 render_final 渲染。
优雅降级：无密钥 / 网络失败 / 返回非 JSON 时，自动回退为带 <!-- TODO(translate) --> 的草稿并提示，不会报错中断任务。
目录发现规则
唯一规则：默认扫描本技能的上级文件夹（即兄弟技能包所在目录）。需要扫描其它目录时，用 --skills-dir <path> 显式指定。平台无关：只要目录下各技能包内含 SKILL.md 即可被发现。
标准工作流程
用户输入
→ 提取 skill 名称 / 判断单数·批量
→ 检测 Python 与脚本是否可用？
├─ 可用 → 运行脚本完成：目录发现 + 解析 + 草稿 + 跳过判断 + 报告
└─ 不可用（NO_PYTHON_FALLBACK）→ Agent 直接按「草稿模板」生成，步骤相同
→ Agent 读取草稿（或自行产出），翻译待译章节、补全「使用方法」示例与「注意事项」
→ 写入最终 README_CN.md（或 使用说明.md）
→ 运行脚本 QA 校验；无脚本时自行核对质量检查清单
Agent 分工：脚本可用时，脚本负责「确定性」工作，你负责「语言」工作；脚本不可用时（无 Python / 文件缺失），你按「草稿模板」直接完成全部工作。不要因缺少 Python 而判定任务失败。
草稿模板（无脚本时由 Agent 直接套用）
当无法调用脚本时，Agent 依此骨架直接写出 README_CN.md（待译章节用 <!-- TODO(translate) --> 标注，最终定稿前移除）：
# {Skill 名称} 使用说明
## 简介
{功能概述，1–2 句} <!-- TODO(translate) 若原文为英文 -->
## 触发条件
- {明确激活场景 1}
- {明确激活场景 2}
## 功能特性
- {核心能力 1}
- {核心能力 2}
## 使用方法
### {典型场景 1 名称}
`{可执行命令或代码}`
### {典型场景 2 名称}
`{可执行命令或代码}`
## 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| {param} | {type} | {是/否} | {说明} |
## 配置说明
- `{ENV_VAR}` - {说明}
## 注意事项
- {提示或限制 1}
- {提示或限制 2}
输出规范
文件命名
- 首选：
README_CN.md（写入技能所在目录） - 备选：
使用说明.md（当README_CN.md已存在且用户要求兼容名时） - 已存在且非
--force：跳过并提示用户选择（覆盖 / 备份后覆盖 / 跳过 / 新建带后缀文件）
文档结构（必须包含）
# {Skill 名称} 使用说明## 简介— 1–2 句功能概述## 触发条件— 明确的激活场景（bullet）## 功能特性— 3–5 个核心能力（bullet）## 使用方法— 2–3 个典型场景，含可执行代码示例## 参数说明— 四列表格（参数 / 类型 / 必填 / 说明）## 配置说明— 环境变量、配置文件（如有）## 注意事项— 2–3 条提示或限制
格式要求
- 标题层级
# ## ###正确；代码块标注语言（bash/json/python） - 表格标准 Markdown 语法；列表用
-或1. - 中文标点（，。：；""''）；技术术语与代码保持英文（API、CLI、JSON、
--model、OPENAI_API_KEY）
批量处理模式
扫描技能目录 → 列出候选 → 逐个检查 SKILL.md 存在性
→ 已存在中文文档？是→跳过（记录）；否→脚本生成草稿 + Agent 本地化
→ 汇总报告（成功 / 跳过 / 失败计数）
跳过策略：已存在 README_CN.md 或 使用说明.md → 跳过（除非 --force）；无 SKILL.md → 记录失败并继续。
错误处理
| 情况 | 处理 |
|---|---|
| 未找到 skill / SKILL.md | 提示名称拼写或安装问题；批量中记录失败继续 |
| frontmatter 解析失败 | 脚本降级正则提取 name/description；仍失败则基于目录名生成标题 |
| 文件写入失败（权限/磁盘） | 改用带数字后缀的文件名；提示检查权限与空间 |
| 命名冲突 | 询问覆盖 / 备份后覆盖（*.bak）/ 跳过 / 新建后缀文件 |
质量检查清单
生成后核对：
- [ ] 一级标题格式：# {Skill 名称} 使用说明
- [ ] 含全部必备章节（简介 / 触发条件 / 使用方法）
- [ ] 代码示例语法高亮正确、命令可执行
- [ ] 参数表格 4 列且对齐
- [ ] 无遗留 <!-- TODO(translate) --> 占位符
- [ ] 技术术语未误译、无机器翻译腔
- [ ] 文档长度 20–500 行
示例
输入：为 summarize 生成中文说明
执行：
python scripts/generate_readme.py --skill summarize
脚本输出草稿并返回路径；Agent 翻译 <!-- TODO(translate) --> 章节、补全「使用方法」示例，最终得到如：
# Summarize 使用说明
## 简介
Summarize 是一款快速命令行工具，用于总结网页链接、本地文件与 YouTube 视频内容。
## 触发条件
- 需要快速了解网页内容时
- 需要总结 PDF / 图片 / 音频文件时
## 功能特性
- 支持网页 URL 内容总结
- 支持本地文件（PDF、图片、音频）总结
## 使用方法
### 总结网页
`summarize "https://example.com" --model google/gemini-flash`
## 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--length` | string | 否 | 总结长度：short/medium/long |
| `--model` | string | 否 | AI 模型 |
## 注意事项
- 使用前请设置相应 API 密钥
版本历史
- v1.0.0 — 初始版本（纯文档式流程，路径写死
.trae/skills/，无执行脚本） - v1.1.0 — 生产级重构：WorkBuddy 原生目录发现、scripts/generate_readme.py 工具脚本、容错解析、批量与跳过、QA 检查
- v1.2.0 — 一键翻译：scripts/llm_bridge.py（DeepSeek 回填中文）、build_struct 结构化 JSON 与 render_final、--translate/--json-out；草稿源文预填增强；新增术语表 references/terminology.md
- v1.2.1 — 通用化：移除 WorkBuddy 平台绑定（目录发现唯一规则=本技能上级文件夹，仅 --skills-dir 可覆盖；文案与 LLM 提示词平台无关），适用于任何「技能目录 + SKILL.md」结构
