影片字幕校正代理人

使用 GitHub Copilot SDK 開發的影片字幕校正代理人，能自動分析、校正 VTT 字幕檔案中的錯字，並產生章節資訊與內容總結。

功能特色

1. 主題分析 - 自動分析影片的主要談論內容與方向
2. 關鍵字整理 - 根據主題領域整理常見的專業術語與專有名詞
3. 字幕校正 - 分析每段字幕的正確性，自動校正轉錄錯誤
4. 修正清單 - 記錄所有修正項目，包含原文、校正後文字與修正原因
5. 章節生成 - 自動建立分段章節，包含標題與時間戳
6. 內容總結 - 產生影片內容的摘要總結

安裝

全域安裝 (建議)

npm install -g @willh/subtitle-correction-agent
# 或
bun add -g @willh/subtitle-correction-agent

安裝完成後即可使用 subtitle-correction-agent 指令。

直接執行 (免安裝)

npx @willh/subtitle-correction-agent <vtt-file-path>

環境設定

本工具會依環境變數自動選擇 AI 提供者：

• 若已完整設定 AZURE_OPENAI_* 相關環境變數，則使用 Azure OpenAI (BYOK)。
• 否則使用 GitHub Copilot CLI (Default)（需先安裝並完成登入，且終端機可執行 copilot）。

使用 Azure OpenAI (BYOK)

複製 .env.example 為 .env 並填入 Azure OpenAI 的設定：

cp .env.example .env

需要設定以下環境變數：

| 變數名稱 | 說明 | |---------|------| | AZURE_OPENAI_ENDPOINT | Azure OpenAI 端點 URL | | AZURE_OPENAI_API_KEY | Azure OpenAI API 金鑰 | | AZURE_OPENAI_DEPLOYMENT | Azure OpenAI 部署名稱 | | AZURE_OPENAI_API_VERSION | API 版本 (預設: 2024-10-21) |

使用 GitHub Copilot CLI (Default)

若你要使用預設的 GitHub Copilot CLI：

• 請不要設定 AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_API_KEY / AZURE_OPENAI_DEPLOYMENT（可不建立 .env）。
• 若已複製 .env.example，請把上述三個變數的值清空或移除，避免誤判為 Azure 模式。

使用方式

# 基本使用
subtitle-correction-agent <vtt-file-path>

# 指定輸出目錄
subtitle-correction-agent <vtt-file-path> --output-dir <output-directory>

# 顯示版本與環境資訊
subtitle-correction-agent --version

# 範例
subtitle-correction-agent ./examples/sample.vtt
subtitle-correction-agent "C:\Videos\lecture.vtt" --output-dir ./output

Telegram Bot

只要使用者上傳 .vtt 檔案，Bot 會自動校正字幕並回傳所有輸出檔案。 目前 Telegram Bot 只支援 Azure OpenAI (BYOK)，因此需要設定 Azure OpenAI 的環境變數。

環境變數

| 變數名稱 | 說明 | |---------|------| | TELEGRAM_BOT_TOKEN | Telegram Bot Token | | OWNER_CHAT_ID | 允許使用 Bot 的唯一 chat id | | TELEGRAM_STARTUP_CHAT_ID | 啟動通知的 chat id (可用逗號分隔多個) | | BOT_MAX_CONCURRENT | 同時處理數量上限 (預設: 1) | | KEEP_TEMP_FILES | 保留暫存檔案 (1=保留，預設: 0) | | BOT_LOG_LEVEL | 日誌等級 (debug/info/warn/error，預設: info) | | BOT_DEBUG | 快速開啟 debug (1=啟用) | | BOT_DATA_DIR | 資料持久化目錄 (預設: 專案根目錄的 data/) |

執行

# 本地開發模式
bun run bot

# 建置後執行
bun run build:bot
node dist/telegram-bot.js

使用流程

1. 在 Telegram 對 Bot 傳送 /start
   • 只有 OWNER_CHAT_ID 指定的 chat 可以使用
2. 上傳 .vtt 字幕檔案
3. 等待校正完成後，Bot 會回傳：
   • 校正後字幕
   • 修正清單
   • 章節資訊
   • 內容總結
4. 另外會回傳一則執行摘要到聊天室
5. 聊天室 ID 會持久化到 BOT_DATA_DIR/telegram-chat-ids.json

輸出檔案

執行後會在 VTT 檔案所在目錄（或指定的輸出目錄）產生以下檔案：

| 檔案 | 說明 | |------|------| | {filename}-corrected.vtt | 校正後的字幕檔案 | | {filename}-corrections.txt | 修正清單 | | {filename}-chapters.txt | 章節資訊 | | {filename}-summary.txt | 內容總結 |

專案結構

subtitle-correction-agent/
├── package.json
├── tsconfig.json
├── .env.example
├── README.md
└── src/
    ├── index.ts          # CLI 入口
    ├── agent.ts          # 代理人核心邏輯
    ├── telegram-bot.ts   # Telegram Bot 入口
    ├── tools/
    │   ├── index.ts      # 工具匯出
    │   ├── read-vtt.ts   # VTT 讀取工具
    │   ├── write-file.ts # 檔案寫入工具
    │   └── update-vtt.ts # VTT 更新工具
    └── utils/
        └── vtt-parser.ts # VTT 解析器

技術細節

• GitHub Copilot SDK - 使用 @github/copilot-sdk 建立 AI 代理人
• Azure OpenAI BYOK - 支援自帶金鑰的 Azure OpenAI 服務
• 自訂工具 - 定義了讀取、更新 VTT 和寫入檔案等工具
• Bun - 以 Bun 進行建置與測試

處理流程

1. 讀取指定的 VTT 字幕檔案
2. 分析整體內容，判斷影片的主題方向
3. 根據主題領域整理正確的專業術語清單
4. 逐一分析每段字幕，找出潛在的轉錄錯誤
5. 根據上下文和專業術語清單進行校正
6. 產生修正清單，記錄所有變更
7. 儲存校正後的 VTT 檔案
8. 根據內容自動建立章節索引
9. 產生影片內容總結

開發

bun install

# 本地執行 (TS 直接執行)
bun run dev -- <vtt-file-path>

# 型別檢查
bun run typecheck

# 單元測試
bun run test

# 建置
bun run build

貢獻

歡迎 PR！建議流程：

1. Fork 專案並建立分支
2. 提交變更並補齊對應測試
3. 確認 bun run test 通過後送出 PR

授權

MIT License. 詳見 LICENSE。