@willh/subtitle-correction-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will 保哥
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# 影片字幕校正代理人
+
+使用 GitHub Copilot SDK 開發的影片字幕校正代理人，能自動分析、校正 VTT 字幕檔案中的錯字，並產生章節資訊與內容總結。
+
+## 功能特色
+
+1. **主題分析** - 自動分析影片的主要談論內容與方向
+2. **關鍵字整理** - 根據主題領域整理常見的專業術語與專有名詞
+3. **字幕校正** - 分析每段字幕的正確性，自動校正轉錄錯誤
+4. **修正清單** - 記錄所有修正項目，包含原文、校正後文字與修正原因
+5. **章節生成** - 自動建立分段章節，包含標題與時間戳
+6. **內容總結** - 產生影片內容的摘要總結
+
+## 安裝
+
+### 全域安裝 (建議)
+
+```bash
+npm install -g @willh/subtitle-correction-agent
+# 或
+bun add -g @willh/subtitle-correction-agent
+```
+
+安裝完成後即可使用 `subtitle-correction-agent` 指令。
+
+### 直接執行 (免安裝)
+
+```bash
+npx @willh/subtitle-correction-agent <vtt-file-path>
+```
+
+## 環境設定
+
+複製 `.env.example` 為 `.env` 並填入 Azure OpenAI 的設定：
+
+```bash
+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) |
+
+## 使用方式
+
+```bash
+# 基本使用
+subtitle-correction-agent <vtt-file-path>
+
+# 指定輸出目錄
+subtitle-correction-agent <vtt-file-path> --output-dir <output-directory>
+
+# 範例
+subtitle-correction-agent ./examples/sample.vtt
+subtitle-correction-agent "C:\Videos\lecture.vtt" --output-dir ./output
+```
+
+## Telegram Bot
+
+只要使用者上傳 `.vtt` 檔案，Bot 會自動校正字幕並回傳所有輸出檔案。
+同樣需要設定 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/) |
+
+### 執行
+
+```bash
+# 本地開發模式
+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. 產生影片內容總結
+
+## 開發
+
+```bash
+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`。