| 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. 扫描目标文件夹
列出用户指定文件夹中的所有文件，区分图片文件和文档文件：
ls -la "<target_folder>/"
find "<target_folder>" -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.webp" \) | sort
find "<target_folder>" -maxdepth 1 -type f -name "*.md"
输出：
- 图片文件列表（按文件名/时间排序）
- Markdown 草稿文件路径
- 文件数量统计
2. 识别图片内容（OCR）
使用 macOS 系统自带的 Vision 框架进行 OCR 文字识别，提取每张图片中的关键文字信息。
2.1 编译 OCR 工具
创建并编译一个 Swift 小工具，调用 macOS Vision 框架：
import Foundation
import Vision
import AppKit
let args = CommandLine.arguments
guard args.count > 1 else {
print("Usage: ocr_images <image_path>")
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])
编译命令：
swiftc -o ocr_tool ocr_images.swift -framework Vision -framework AppKit
2.2 批量 OCR 所有图片
对每张图片执行 OCR，记录识别结果：
for img in "<target_folder>/"*.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 转义问题）：
import os
base = "<target_folder>"
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 草稿，理解其结构和意图：
cat "<target_folder>/instruction.md"
分析要点：
- 识别文档主题和目标读者
- 提取关键步骤的概要（通常是简短的要点列表）
- 确定步骤之间的逻辑顺序
- 将草稿中的简略描述与 OCR 识别出的截图内容进行对应
5. 补全 Markdown 文档
将草稿扩展为完整的操作指导文档，遵循以下结构规范。
5.1 文档结构模板
# [文档标题]
[一段简介，说明文档目的和适用对象]
---
## 前置准备
[列出开始操作前需要满足的条件]
### 1. [准备项1]
[详细说明 + 截图]
### 2. [准备项2]
[详细说明 + 截图]
---
## 步骤 N：[步骤标题]
[简要说明本步骤的目的]
### N.1 [子步骤]
[操作说明]
### N.2 [子步骤]
[操作说明]
> **说明/提示：** [补充说明]
---
## 常见问题
| 问题 | 解决方案 |
|------|----------|
| ... | ... |
5.2 文档编写原则
- 标题层级：使用
# 到 ####，层级不超过4级
- 步骤编号：主步骤使用 "步骤 N"，子步骤使用 "N.1"、"N.2"
- 操作描述：具体、明确，包含 UI 路径（如"点击左下角齿轮图标 → 设置"）
- 关键词加粗：菜单名、按钮名、配置项用
**粗体** 标注
- 代码块：命令行操作使用
```bash ``` 包裹
- 引用提示：使用
> **说明：** 或 > **注意：** 添加补充信息
- 分隔线：主要章节之间使用
--- 分隔
6. 在文档中插入图片
将重命名后的图片以 Markdown 语法插入到文档的对应位置。
6.1 图片插入语法
6.2 图片放置原则
- 紧跟操作说明之后：先写文字描述操作步骤，紧接着插入对应截图
- 一图一步：每个关键操作步骤配一张截图，不堆叠多张
- 描述文字有意义：
![]() 中的 alt 文字应准确描述图片内容，方便搜索和无障碍访问
- 按操作流程排列：图片顺序与步骤顺序严格一致
6.3 图片与步骤对应示例
### 2. 安装 GitHub Copilot 扩展
在 VS Code 的扩展市场中搜索 **GitHub Copilot** 并安装：
7. 最终检查与输出
完成文档后进行以下检查：
7.1 完整性检查
7.2 格式检查
7.3 验证图片引用
grep -oP '!\[.*?\]\(\K[^)]+' "<target_folder>/instruction.md"
ls "<target_folder>/"*.png
处理特殊情况
文件夹路径含空格
路径含空格时（如 skill instruction/），shell 命令容易出错。应对策略：
- 使用 Python 脚本替代 shell 批量操作
- 所有路径用双引号包裹
- 避免 shell heredoc 内使用复杂路径
图片无法 OCR
某些截图可能是纯图形、图标或高度风格化的文字，OCR 无法识别。处理方式：
- 结合图片尺寸和时间戳推断在流程中的位置
- 参照草稿中的步骤描述进行人工匹配
- 使用通用描述命名（如
05-step5-ui-overview.png）
草稿过于简略
如果草稿仅有几个关键词，需要：
- 优先依赖 OCR 结果理解完整流程
- 结合工作空间中的相关文件（README、其他文档）补充上下文
- 按截图的时间顺序还原操作流程
- 用行业通用的操作指导文档写法补全
非 macOS 环境
Vision 框架仅限 macOS。在其他平台上：
- Linux/Windows：安装
tesseract 和 pytesseract
- 替代方案：
brew install tesseract（macOS 备选）或使用在线 OCR API
注意事项
- OCR 工具编译后的二进制文件和 Python 重命名脚本属于临时文件，完成后应清理
- 重命名前建议备份原始图片，以防命名出错需要回溯
- 文档中图片路径使用相对路径，确保文档和图片在同一目录下可正常显示
- 对于包含敏感信息的截图（如 token、密码），应在文档中提醒脱敏处理
