diff --git a/skills/operation/content/tutorial-generating/SKILL.md b/skills/operation/content/tutorial-generating/SKILL.md new file mode 100644 index 0000000..0e5076c --- /dev/null +++ b/skills/operation/content/tutorial-generating/SKILL.md @@ -0,0 +1,303 @@ +--- +name: tutorial-generating +description: Transform a folder of unnamed screenshots and a rough markdown draft into a polished, illustrated tutorial document. Use when the user has a set of screenshots (e.g., from Snipaste or other tools) with timestamp-based filenames and a brief markdown outline, and wants to produce a complete step-by-step instructional document with images renamed by content and inserted at appropriate positions. Triggers include "整理截图写文档", "screenshots to tutorial", "rename images and write guide", "把截图整理成教程", or when a folder of screenshots and a markdown draft are provided together. +--- + +# Tutorial Generating + +将一组以时间戳命名的截图和一份粗略的 Markdown 草稿,转化为一份完整的、图文并茂的操作指导文档。自动完成截图内容识别、语义化重命名,以及文档结构补全与图片插入。 + +## Workflow + +### 1. 扫描目标文件夹 + +列出用户指定文件夹中的所有文件,区分图片文件和文档文件: + +```bash +# 列出所有文件 +ls -la "/" + +# 筛选图片文件(支持 png/jpg/jpeg/gif/webp) +find "" -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.webp" \) | sort + +# 筛选 Markdown 文件 +find "" -maxdepth 1 -type f -name "*.md" +``` + +**输出**: +- 图片文件列表(按文件名/时间排序) +- Markdown 草稿文件路径 +- 文件数量统计 + +### 2. 识别图片内容(OCR) + +使用 macOS 系统自带的 Vision 框架进行 OCR 文字识别,提取每张图片中的关键文字信息。 + +#### 2.1 编译 OCR 工具 + +创建并编译一个 Swift 小工具,调用 macOS Vision 框架: + +```swift +// ocr_images.swift +import Foundation +import Vision +import AppKit + +let args = CommandLine.arguments +guard args.count > 1 else { + print("Usage: ocr_images ") + exit(1) +} + +let imagePath = args[1] +guard let image = NSImage(contentsOfFile: imagePath), + let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else { + print("ERROR: Cannot load image") + exit(1) +} + +let request = VNRecognizeTextRequest { request, error in + guard let observations = request.results as? [VNRecognizedTextObservation] else { return } + for observation in observations { + if let topCandidate = observation.topCandidates(1).first { + print(topCandidate.string) + } + } +} + +request.recognitionLevel = .accurate +request.recognitionLanguages = ["zh-Hans", "en-US"] + +let handler = VNImageRequestHandler(cgImage: cgImage, options: [:]) +try handler.perform([request]) +``` + +编译命令: + +```bash +swiftc -o ocr_tool ocr_images.swift -framework Vision -framework AppKit +``` + +#### 2.2 批量 OCR 所有图片 + +对每张图片执行 OCR,记录识别结果: + +```bash +for img in "/"*.png; do + echo "=== $(basename "$img") ===" + ./ocr_tool "$img" + echo "---" +done +``` + +**关键信息提取**:从 OCR 结果中识别: +- UI 元素(按钮文字、菜单项、对话框标题) +- 关键操作(安装、设置、搜索、选择) +- 上下文信息(应用名称、配置项名称) + +### 3. 语义化重命名图片 + +根据 OCR 识别出的内容,为每张图片生成语义化文件名。 + +#### 3.1 命名规则 + +文件名格式:`{序号}-{动作}-{对象}.png` + +- **序号**:两位数字,按操作流程顺序排列(`01`、`02`、`03`...) +- **动作**:描述截图中的核心操作(如 `install`、`enable`、`open`、`select`、`create`) +- **对象**:描述操作的目标(如 `copilot-extension`、`agent-skills-setting`) +- 使用英文小写和连字符,不使用空格或中文 + +**命名示例**: + +| OCR 关键内容 | 命名结果 | +|-------------|----------| +| GitHub Copilot 扩展安装页面 | `01-install-copilot-extension.png` | +| 设置搜索 chat.useAgentSkills | `04-enable-agent-skills-setting.png` | +| git clone 命令 | `10-git-clone-agent-skills-repo.png` | +| 资源管理器目录结构 | `11-agent-skills-repo-structure.png` | + +#### 3.2 执行批量重命名 + +使用 Python 脚本进行安全的批量重命名(避免 shell 转义问题): + +```python +import os + +base = "" +renames = { + "<原文件名1>.png": "<新文件名1>.png", + "<原文件名2>.png": "<新文件名2>.png", + # ... +} + +for old, new in renames.items(): + src = os.path.join(base, old) + dst = os.path.join(base, new) + if os.path.exists(src): + os.rename(src, dst) + print(f"OK: {old} -> {new}") + else: + print(f"SKIP: {old} not found") +``` + +> **注意**:文件夹路径包含空格时,shell 的 heredoc 和链式 `mv` 命令容易出错。推荐使用 Python 脚本文件而非内联命令。 + +### 4. 阅读并分析 Markdown 草稿 + +读取用户提供的 Markdown 草稿,理解其结构和意图: + +```bash +cat "/instruction.md" +``` + +**分析要点**: +- 识别文档主题和目标读者 +- 提取关键步骤的概要(通常是简短的要点列表) +- 确定步骤之间的逻辑顺序 +- 将草稿中的简略描述与 OCR 识别出的截图内容进行对应 + +### 5. 补全 Markdown 文档 + +将草稿扩展为完整的操作指导文档,遵循以下结构规范。 + +#### 5.1 文档结构模板 + +```markdown +# [文档标题] + +[一段简介,说明文档目的和适用对象] + +--- + +## 前置准备 + +[列出开始操作前需要满足的条件] + +### 1. [准备项1] +[详细说明 + 截图] + +### 2. [准备项2] +[详细说明 + 截图] + +--- + +## 步骤 N:[步骤标题] + +[简要说明本步骤的目的] + +### N.1 [子步骤] +[操作说明] + +![图片描述](xx-image-name.png) + +### N.2 [子步骤] +[操作说明] + +> **说明/提示:** [补充说明] + +--- + +## 常见问题 + +| 问题 | 解决方案 | +|------|----------| +| ... | ... | +``` + +#### 5.2 文档编写原则 + +- **标题层级**:使用 `#` 到 `####`,层级不超过4级 +- **步骤编号**:主步骤使用 "步骤 N",子步骤使用 "N.1"、"N.2" +- **操作描述**:具体、明确,包含 **UI 路径**(如"点击左下角齿轮图标 → 设置") +- **关键词加粗**:菜单名、按钮名、配置项用 `**粗体**` 标注 +- **代码块**:命令行操作使用 ` ```bash ``` ` 包裹 +- **引用提示**:使用 `> **说明:**` 或 `> **注意:**` 添加补充信息 +- **分隔线**:主要章节之间使用 `---` 分隔 + +### 6. 在文档中插入图片 + +将重命名后的图片以 Markdown 语法插入到文档的对应位置。 + +#### 6.1 图片插入语法 + +```markdown +![图片的中文描述](图片文件名.png) +``` + +#### 6.2 图片放置原则 + +- **紧跟操作说明之后**:先写文字描述操作步骤,紧接着插入对应截图 +- **一图一步**:每个关键操作步骤配一张截图,不堆叠多张 +- **描述文字有意义**:`![]()` 中的 alt 文字应准确描述图片内容,方便搜索和无障碍访问 +- **按操作流程排列**:图片顺序与步骤顺序严格一致 + +#### 6.3 图片与步骤对应示例 + +```markdown +### 2. 安装 GitHub Copilot 扩展 + +在 VS Code 的扩展市场中搜索 **GitHub Copilot** 并安装: + +![安装 GitHub Copilot 扩展](01-install-copilot-extension.png) +``` + +### 7. 最终检查与输出 + +完成文档后进行以下检查: + +#### 7.1 完整性检查 +- [ ] 所有截图均已在文档中引用 +- [ ] 文档中所有图片引用的文件名与实际文件名一致 +- [ ] 无遗漏的操作步骤 + +#### 7.2 格式检查 +- [ ] Markdown 语法正确(标题层级、列表、代码块等) +- [ ] 图片 alt 文字完整且有描述性 +- [ ] 表格格式正确 +- [ ] 无多余空行或格式错误 + +#### 7.3 验证图片引用 + +```bash +# 提取文档中所有图片引用 +grep -oP '!\[.*?\]\(\K[^)]+' "/instruction.md" + +# 对比实际图片文件 +ls "/"*.png + +# 检查是否有孤立图片(未被文档引用)或断链引用(文件不存在) +``` + +## 处理特殊情况 + +### 文件夹路径含空格 +路径含空格时(如 `skill instruction/`),shell 命令容易出错。应对策略: +- 使用 Python 脚本替代 shell 批量操作 +- 所有路径用双引号包裹 +- 避免 shell heredoc 内使用复杂路径 + +### 图片无法 OCR +某些截图可能是纯图形、图标或高度风格化的文字,OCR 无法识别。处理方式: +- 结合图片尺寸和时间戳推断在流程中的位置 +- 参照草稿中的步骤描述进行人工匹配 +- 使用通用描述命名(如 `05-step5-ui-overview.png`) + +### 草稿过于简略 +如果草稿仅有几个关键词,需要: +1. 优先依赖 OCR 结果理解完整流程 +2. 结合工作空间中的相关文件(README、其他文档)补充上下文 +3. 按截图的时间顺序还原操作流程 +4. 用行业通用的操作指导文档写法补全 + +### 非 macOS 环境 +Vision 框架仅限 macOS。在其他平台上: +- Linux/Windows:安装 `tesseract` 和 `pytesseract` +- 替代方案:`brew install tesseract`(macOS 备选)或使用在线 OCR API + +## 注意事项 + +- OCR 工具编译后的二进制文件和 Python 重命名脚本属于临时文件,完成后应清理 +- 重命名前建议备份原始图片,以防命名出错需要回溯 +- 文档中图片路径使用相对路径,确保文档和图片在同一目录下可正常显示 +- 对于包含敏感信息的截图(如 token、密码),应在文档中提醒脱敏处理