name: video-to-doc description: 將操作影片自動轉換為圖文並茂的Word操作指南文件，支援智慧截圖、語音轉錄、LLM內容提煉和流程圖生成 version: 1.0.0

Video to Doc 技能

將影片教程轉換為圖文並茂的Word操作指南文件。

功能描述

本技能能夠： 1. 自動分析影片檔案，提取關鍵幀截圖 2. 使用釦子平臺內建 read_image 工具識別截圖中的介面元素 3. 生成結構化的圖文操作指南Word文件

適用場景

• 軟體操作教程影片 → 操作指南文件
• 系統演示影片 → 使用者手冊
• 培訓影片 → 培訓材料
• 產品演示影片 → 產品說明文件

使用前提

必需依賴

# 安裝 ffmpeg（影片處理）
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# 安裝 Python 依賴
pip install python-docx pillow faster-whisper

可選配置

語音轉錄支援多種方案： - 方案A（推薦）：使用釦子平臺官方「語音轉文本」外掛（免費配額每日20次） - 方案B：本地 faster-whisper 模型（首次執行自動下載，約75MB） - 方案C：OpenAI Whisper API（需要API Key）

LLM內容提煉使用釦子平臺內建大模型能力，無需額外配置。

工作流程

新版流程（使用 read_image）

本版本採用主對話分析 + 指令碼合併的架構，充分利用釦子平臺內建的 read_image 視覺理解能力：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Python指令碼      │    │  主對話         │    │  Python指令碼      │
│  提取截圖/語音   │ →  │  read_image分析 │ →  │  合併生成文件    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

步驟1：提取截圖和語音（Python 指令碼）

python video_to_doc.py video.mp4

指令碼自動完成： 1. 智慧截圖（根據影片時長自適應） 2. 音訊提取 3. 語音轉錄

完成後輸出：

[3/6] 等待截圖分析...
截圖目錄: video_frames
分析結果儲存到: video_frames_analysis.json

並列印標記：

[MARKER_FOR_MAIN_AGENT]
WAIT_FOR_FRAME_ANALYSIS
frames_dir=video_frames
analysis_output=video_frames_analysis.json
frame_count=15
[/MARKER_FOR_MAIN_AGENT]

步驟2：截圖分析（主對話用 read_image）

主對話收到 WAIT_FOR_FRAME_ANALYSIS 標記後：

1. 讀取截圖列表：glob.glob("video_frames/*.jpg")
2. 逐個分析：使用 read_image 工具分析每張截圖
3. 彙總結果：按格式生成 JSON

read_image 分析提示詞模板：

分析截圖中的：
1. UI元素：按鈕、表單、選單等（text + type）
2. 文本內容：介面上顯示的主要文字
3. 操作提示：根據畫面推斷下一步操作

格式要求：
- ui_elements: [{"text": "文字", "type": "按鈕/輸入框/選單項/..."}]
- text_content: 介面主要內容摘要
- action_hint: 簡短的步驟描述（如"點選確定按鈕"）

輸出格式（儲存到 video_frames_analysis.json）：

{
  "frames": [
    {
      "timestamp": 0,
      "ui_elements": [
        {"text": "新增", "type": "按鈕"},
        {"text": "請輸入名稱", "type": "輸入框"}
      ],
      "text_content": "員工管理頁面，顯示新增和刪除按鈕",
      "action_hint": "點選新增按鈕新增員工"
    },
    {
      "timestamp": 6,
      "ui_elements": [
        {"text": "確定", "type": "按鈕"},
        {"text": "取消", "type": "按鈕"}
      ],
      "text_content": "新增員工對話方塊",
      "action_hint": "填寫資訊後點擊確定"
    }
  ]
}

步驟3：繼續生成文件

主對話分析完成後，執行：

python video_to_doc.py --continue

指令碼自動完成： 1. 合併截圖分析和語音轉錄 2. 時間戳對齊 3. 生成Word文件

呼叫方式彙總

# 完整流程
python video_to_doc.py video.mp4           # 步驟1：提取截圖和語音
# [主對話用 read_image 分析截圖]
python video_to_doc.py --continue          # 步驟3：生成文件

# 可選引數
python video_to_doc.py video.mp4 -o my.docx      # 指定輸出檔案
python video_to_doc.py video.mp4 -m 20            # 最多20張截圖
python video_to_doc.py video.mp4 --no-audio      # 跳過語音轉錄

智慧截圖策略

自動策略選擇

系統根據影片特徵自動選擇最優截圖策略：

場景變化檢測（自動觸發）

• 當預計幀數超過30張時，自動切換到場景變化檢測
• 只擷取畫面明顯變化的幀，避免冗餘
• 如果檢測幀數太少，自動回退到間隔模式

使用者可強制指定

# 固定間隔
python smart_extract.py video.mp4 -s interval_5

# 場景檢測
python smart_extract.py video.mp4 -s scene

# 限制最大幀數
python smart_extract.py video.mp4 -m 20

截圖分析說明

read_image 分析要點

主對話使用 read_image 分析截圖時，關注：

1. UI元素識別
2. 按鈕（確定、取消、新增、刪除等）
3. 輸入框、核取方塊、下拉選單
4. 導航選單、標籤頁

5. 圖示（帶文字提示的）

6. 文本內容提取

7. 表格內容（關鍵欄位）
8. 表單標籤
9. 提示資訊

10. 錯誤資訊

    小蔥技能7w4.net持續更新中。

11. 操作推斷

12. 根據按鈕位置推斷操作順序
13. 根據表單欄位推斷填寫順序
14. 根據上下文推斷下一步

分析質量提升技巧

• 批次分析：可一次性分析多張截圖
• 保持一致性：使用統一的分析格式
• 時間上下文：考慮相鄰幀的關係

指令碼說明

LLM內容提煉

提煉目標

將口語化的語音轉錄內容轉換為規範的操作說明： - "然後我們點這個" → "點選【XX】按鈕" - "先去輸入" → "在「XX」輸入框填寫" - 去除口頭禪、重複表述 - 精簡步驟數量

提煉流程

1. 讀取分析資料：截圖分析結果 + 語音轉錄結果
2. 合併時間戳：將語音內容與截圖對應
3. LLM提煉：將口語化描述轉為規範操作說明
4. 合併步驟：將多個小步驟合併為核心步驟

提煉提示詞

將以下操作影片的內容提煉為規範的操作指南：

截圖分析：{frames_analysis}
語音轉錄：{audio_transcript}

要求：
1. 提取核心操作步驟（控制在4-6步）
2. 使用規範表述：
   - 點選操作：【按鈕名稱】
   - 輸入欄位：「欄位名稱」
   - 示例值：直接文本
3. 去除口語化表達和重複內容
4. 每個步驟包含：標題 + 操作描述

流程圖生成

流程圖格式

在文件開頭新增橫向箭頭流程圖，使用表格實現：

進入系統 → 填寫資訊 → 拍照上傳 → 查詢管理 → 完成

實現方式

# Word中用表格實現橫向流程圖
table = doc.add_table(rows=1, cols=9)
flow_steps = ['進入系統', '→', '填寫資訊', '→', '拍照上傳', '→', '查詢管理', '→', '完成']

節點數量

• 核心步驟 ≤ 4個：直接展示
• 核心步驟 5-6個：合併相似步驟
• 核心步驟 > 6個：提取主要流程

文件輸出規範

文件結構

一、操作概述
二、操作流程圖
三、詳細操作步驟
四、注意事項

操作標記規範

內容精簡原則

• 每個步驟控制在2-3句話
• 只保留核心操作，去除冗餘描述
• 截圖選擇：每個步驟配1張關鍵截圖
• 注意事項：控制在3-5條

技術架構

video_to_doc.py
├── 提取截圖 → smart_extract.py
├── 語音轉錄 → transcribe_audio.py
├── [主對話] → read_image 分析截圖
├── [主對話] → LLM 提煉內容
└── 合併生成 → merge_and_generate.py → generate_docx.py

關鍵設計： - Python 指令碼負責：檔案處理、音訊處理、資料合併、文件生成 - 主對話負責：視覺理解、截圖分析、內容提煉、操作推斷 - 分工明確，優勢互補

常見問題

Q: 為什麼截圖分析要在主對話做？

A: read_image 是釦子平臺的內建視覺理解工具，可以直接理解截圖內容，無需額外呼叫 API 或模型。

Q: 可以跳過語音轉錄嗎？

A: 可以，使用 --no-audio 引數。但建議保留語音，可以讓操作說明更準確。

Q: 分析結果檔案是什麼格式？

A: JSON 格式，包含 frames 陣列，每個幀包含 timestamp、ui_elements、text_content、action_hint。

Q: 如何調整截圖數量？

A: 使用 -m 引數，如 -m 20 表示最多20張截圖。

這個 Skill 能幫你把操作影片自動變成帶截圖的操作指南文件，對製作軟體教程、培訓材料很有用。智慧截圖和語音轉錄功能做得不錯，輸出的文件結構清晰、圖文並茂。主要缺點是需要安裝 ffmpeg 工具，首次使用配置稍複雜；另外長影片會生成很多截圖，可能需要手動篩選。總體來說功能實用，能有效節省製作文件的時間，適合有相關需求的創作者使用。