@willh/subtitle-correction-agent 0.1.0 → 0.1.1

package/README.md

@@ -31,6 +31,13 @@ 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 的設定：
 
 ```bash
@@ -46,6 +53,13 @@ cp .env.example .env
 | `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 模式。
+
 ## 使用方式
 
 ```bash
@@ -55,6 +69,9 @@ 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
@@ -63,7 +80,7 @@ subtitle-correction-agent "C:\Videos\lecture.vtt" --output-dir ./output
 ## Telegram Bot
 
 只要使用者上傳 `.vtt` 檔案，Bot 會自動校正字幕並回傳所有輸出檔案。
-同樣需要設定 Azure OpenAI 的環境變數。
+目前 Telegram Bot 只支援 Azure OpenAI (BYOK)，因此需要設定 Azure OpenAI 的環境變數。
 
 ### 環境變數
 

package/dist/index.js

@@ -3270,9 +3270,10 @@ var require_main = __commonJS((exports) => {
 });
 
 // src/index.ts
-import * as path5 from "path";
+import * as path6 from "path";
 import * as fs5 from "fs";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
 
 // node_modules/@github/copilot-sdk/dist/client.js
 var import_node = __toESM(require_main(), 1);
@@ -3942,81 +3943,295 @@ class CopilotClient {
 
 // src/agent.ts
 import * as fs4 from "fs";
-import * as path4 from "path";
+import * as path5 from "path";
 
 // src/tools/read-vtt.ts
 import * as fs from "fs";
-import * as path from "path";
+import * as path2 from "path";
 
 // src/utils/vtt-parser.ts
-function parseTimeToSeconds(timeStr) {
-  const parts = timeStr.trim().split(":");
-  if (parts.length === 3) {
-    const [hours, minutes, seconds] = parts;
-    return parseInt(hours, 10) * 3600 + parseInt(minutes, 10) * 60 + parseFloat(seconds);
-  } else if (parts.length === 2) {
-    const [minutes, seconds] = parts;
-    return parseInt(minutes, 10) * 60 + parseFloat(seconds);
-  }
-  return parseFloat(timeStr);
+import * as path from "path";
+
+// src/utils/caption-converter.ts
+var ASS_HEADER = `[Script Info]
+Title: Converted from WebVTT
+ScriptType: v4.00+
+WrapStyle: 0
+PlayResX: 1280
+PlayResY: 720
+ScaledBorderAndShadow: yes
+
+[V4+ Styles]
+Format: Name,Fontname,Fontsize,PrimaryColour,SecondaryColour,OutlineColour,BackColour,Bold,Italic,Underline,StrikeOut,ScaleX,ScaleY,Spacing,Angle,BorderStyle,Outline,Shadow,Alignment,MarginL,MarginR,MarginV,Encoding
+Style: Default,LINE Seed TW_OTF Bold,48,&H0080FFFF,&H000000FF,&H00000000,&H00000000,-1,0,0,0,100,100,1,0,1,2,0,2,1,1,20,1
+Style: Secondary,Helvetica,12,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,-1,0,0,0,100,100,0,0,1,2,0,2,1,1,20,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+`;
+var SUPPORTED_EXTS = new Set([".srt", ".vtt", ".ass"]);
+function normalizeInput(content) {
+  let text = content.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`);
+  if (text.charCodeAt(0) === 65279) {
+    text = text.slice(1);
+  }
+  return text;
 }
-function parseVtt(content, filePath) {
-  const lines = content.replace(/\r\n/g, `
-`).split(`
+function splitWithLimit(text, delimiter, limit) {
+  const parts = [];
+  let current = "";
+  let count = 0;
+  for (let i = 0;i < text.length; i += 1) {
+    const char = text[i];
+    if (char === delimiter && count < limit - 1) {
+      parts.push(current);
+      current = "";
+      count += 1;
+    } else {
+      current += char;
+    }
+  }
+  parts.push(current);
+  return parts;
+}
+function parseSrtVttTime(raw) {
+  const clean = raw.trim().replace(",", ".");
+  const pieces = clean.split(".");
+  if (pieces.length !== 2) {
+    return null;
+  }
+  const timePart = pieces[0];
+  const msPart = pieces[1];
+  if (!/^\d{1,3}$/.test(msPart)) {
+    return null;
+  }
+  const timePieces = timePart.split(":");
+  if (timePieces.length !== 2 && timePieces.length !== 3) {
+    return null;
+  }
+  const numbers = timePieces.map((value) => Number(value));
+  if (numbers.some((value) => Number.isNaN(value))) {
+    return null;
+  }
+  const [hours, minutes, seconds] = timePieces.length === 3 ? numbers : [0, numbers[0], numbers[1]];
+  const ms = Number(msPart.padEnd(3, "0"));
+  return ((hours * 60 + minutes) * 60 + seconds) * 1000 + ms;
+}
+function parseSrtVtt(content) {
+  const normalized = normalizeInput(content);
+  const blocks = normalized.split(/\n{2,}/);
+  const cues = [];
+  for (const block of blocks) {
+    const lines = block.split(`
+`);
+    const timeIndex = lines.findIndex((line) => line.includes("-->"));
+    if (timeIndex === -1) {
+      continue;
+    }
+    const timeLine = lines[timeIndex];
+    const match = timeLine.match(/(.+?)\s*-->\s*(.+)/);
+    if (!match) {
+      continue;
+    }
+    const startRaw = match[1].trim();
+    let endRaw = match[2].trim();
+    endRaw = endRaw.split(/\s+/)[0];
+    const start = parseSrtVttTime(startRaw);
+    const end = parseSrtVttTime(endRaw);
+    if (start === null || end === null) {
+      continue;
+    }
+    const textLines = lines.slice(timeIndex + 1);
+    const text = textLines.join(`
+`).replace(/\s+$/, "");
+    cues.push({ start, end, text });
+  }
+  return cues;
+}
+function parseAssTime(raw) {
+  const match = raw.trim().match(/^(\d+):(\d{2}):(\d{2})\.(\d{1,2})$/);
+  if (!match) {
+    return null;
+  }
+  const hours = Number(match[1]);
+  const minutes = Number(match[2]);
+  const seconds = Number(match[3]);
+  const cs = Number(match[4].padEnd(2, "0"));
+  if ([hours, minutes, seconds, cs].some((value) => Number.isNaN(value))) {
+    return null;
+  }
+  return ((hours * 60 + minutes) * 60 + seconds) * 1000 + cs * 10;
+}
+function assToPlainText(text) {
+  let cleaned = text.replace(/\{[^}]*\}/g, "");
+  cleaned = cleaned.replace(/\\N/g, `
+`);
+  cleaned = cleaned.replace(/\\n/g, `
+`);
+  cleaned = cleaned.replace(/\\h/g, " ");
+  return cleaned;
+}
+function parseAss(content) {
+  const normalized = normalizeInput(content);
+  const lines = normalized.split(`
 `);
   const cues = [];
-  let index = 0;
-  let i = 0;
-  while (i < lines.length && !lines[i].includes("-->")) {
-    i++;
-  }
-  while (i < lines.length) {
-    const line = lines[i].trim();
-    if (line.includes("-->")) {
-      const timeParts = line.split("-->");
-      if (timeParts.length >= 2) {
-        const startTime = timeParts[0].trim().split(" ")[0];
-        const endTime = timeParts[1].trim().split(" ")[0];
-        const textLines = [];
-        i++;
-        while (i < lines.length && lines[i].trim() !== "" && !lines[i].includes("-->")) {
-          textLines.push(lines[i].trim());
-          i++;
-        }
-        if (textLines.length > 0) {
-          cues.push({
-            index: index++,
-            startTime,
-            endTime,
-            startSeconds: parseTimeToSeconds(startTime),
-            endSeconds: parseTimeToSeconds(endTime),
-            text: textLines.join(`
-`)
-          });
-        }
-      } else {
-        i++;
-      }
-    } else {
-      i++;
+  let inEvents = false;
+  let format = null;
+  let indices = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      inEvents = trimmed.toLowerCase() === "[events]";
+      continue;
+    }
+    if (!inEvents) {
+      continue;
+    }
+    if (trimmed.toLowerCase().startsWith("format:")) {
+      format = trimmed.slice(7).split(",").map((part) => part.trim());
+      indices = {
+        start: format.findIndex((entry) => entry.toLowerCase() === "start"),
+        end: format.findIndex((entry) => entry.toLowerCase() === "end"),
+        text: format.findIndex((entry) => entry.toLowerCase() === "text")
+      };
+      continue;
+    }
+    if (!trimmed.toLowerCase().startsWith("dialogue:")) {
+      continue;
+    }
+    if (!format || !indices || indices.start === -1 || indices.end === -1 || indices.text === -1) {
+      continue;
     }
+    const payload = trimmed.slice(9).trim();
+    const fields = splitWithLimit(payload, ",", format.length);
+    if (fields.length < format.length) {
+      continue;
+    }
+    const start = parseAssTime(fields[indices.start] ?? "");
+    const end = parseAssTime(fields[indices.end] ?? "");
+    if (start === null || end === null) {
+      continue;
+    }
+    const textRaw = fields[indices.text] ?? "";
+    const text = assToPlainText(textRaw);
+    cues.push({ start, end, text });
+  }
+  return cues;
+}
+function pad(value, size) {
+  return String(value).padStart(size, "0");
+}
+function formatSrtTime(ms) {
+  const total = Math.max(0, Math.round(ms));
+  const hours = Math.floor(total / 3600000);
+  const minutes = Math.floor(total % 3600000 / 60000);
+  const seconds = Math.floor(total % 60000 / 1000);
+  const millis = total % 1000;
+  return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)},${pad(millis, 3)}`;
+}
+function formatVttTime(ms) {
+  const total = Math.max(0, Math.round(ms));
+  const hours = Math.floor(total / 3600000);
+  const minutes = Math.floor(total % 3600000 / 60000);
+  const seconds = Math.floor(total % 60000 / 1000);
+  const millis = total % 1000;
+  return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)}.${pad(millis, 3)}`;
+}
+function formatAssTime(ms) {
+  const totalCs = Math.max(0, Math.round(ms / 10));
+  const cs = totalCs % 100;
+  const totalSeconds = Math.floor(totalCs / 100);
+  const seconds = totalSeconds % 60;
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  const minutes = totalMinutes % 60;
+  const hours = Math.floor(totalMinutes / 60);
+  return `${hours}:${pad(minutes, 2)}:${pad(seconds, 2)}.${pad(cs, 2)}`;
+}
+function plainToAssText(text) {
+  return text.replace(/\r/g, "").split(`
+`).join("\\N");
+}
+function renderSrt(cues) {
+  const blocks = cues.map((cue, index) => {
+    const text = cue.text ?? "";
+    return `${index + 1}
+${formatSrtTime(cue.start)} --> ${formatSrtTime(cue.end)}
+${text}`;
+  });
+  return blocks.join(`
+
+`) + (blocks.length ? `
+` : "");
+}
+function renderVtt(cues) {
+  const blocks = cues.map((cue) => {
+    const text = cue.text ?? "";
+    return `${formatVttTime(cue.start)} --> ${formatVttTime(cue.end)}
+${text}`;
+  });
+  return `WEBVTT
+
+${blocks.join(`
+
+`)}${blocks.length ? `
+` : ""}`;
+}
+function renderAss(cues) {
+  const lines = [ASS_HEADER.trimEnd()];
+  for (const cue of cues) {
+    const text = plainToAssText(cue.text ?? "");
+    lines.push(`Dialogue: 0,${formatAssTime(cue.start)},${formatAssTime(cue.end)},Default,,0,0,0,,${text}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function parseByExt(ext, content) {
+  switch (ext.toLowerCase()) {
+    case ".srt":
+      return parseSrtVtt(content);
+    case ".vtt":
+      return parseSrtVtt(content);
+    case ".ass":
+      return parseAss(content);
+    default:
+      return [];
   }
+}
+function renderByExt(ext, cues) {
+  switch (ext.toLowerCase()) {
+    case ".srt":
+      return renderSrt(cues);
+    case ".vtt":
+      return renderVtt(cues);
+    case ".ass":
+      return renderAss(cues);
+    default:
+      return "";
+  }
+}
+
+// src/utils/vtt-parser.ts
+function parseVtt(content, filePath) {
+  const ext = path.extname(filePath);
+  const captionCues = parseByExt(ext, content);
+  const cues = captionCues.map((cue, idx) => ({
+    index: idx,
+    startTime: formatVttTime(cue.start),
+    endTime: formatVttTime(cue.end),
+    startSeconds: cue.start / 1000,
+    endSeconds: cue.end / 1000,
+    text: cue.text
+  }));
   return {
     filePath,
     cues,
     rawContent: content
   };
 }
-function formatVtt(vttFile) {
-  const lines = ["WEBVTT", ""];
-  for (const cue of vttFile.cues) {
-    lines.push(`${cue.startTime} --> ${cue.endTime}`);
-    lines.push(cue.text);
-    lines.push("");
-  }
-  return lines.join(`
-`);
-}
 function formatCuesForDisplay(vttFile) {
   return vttFile.cues.map((cue) => `[${cue.index}] ${cue.startTime} --> ${cue.endTime}
 ${cue.text}`).join(`
@@ -4031,18 +4246,18 @@ function getCachedVttFile() {
 }
 var readVttTool = {
   name: "read_vtt_file",
-  description: "讀取並解析 VTT 字幕檔案，回傳所有字幕的時間戳和內容。",
+  description: "讀取並解析字幕檔案 (支援 .vtt, .srt, .ass)，回傳所有字幕的時間戳和內容。",
   parameters: {
     type: "object",
     properties: {
-      filePath: { type: "string", description: "VTT 檔案的完整路徑" }
+      filePath: { type: "string", description: "字幕檔案的完整路徑" }
     },
     required: ["filePath"]
   },
   handler: async ({ filePath }) => {
     try {
       console.log(`[DEBUG] readVttTool: Starting to read ${filePath}`);
-      const absolutePath = path.resolve(filePath);
+      const absolutePath = path2.resolve(filePath);
       if (!fs.existsSync(absolutePath)) {
         console.log(`[DEBUG] readVttTool: File not found ${absolutePath}`);
         return { success: false, error: `檔案不存在: ${absolutePath}` };
@@ -4096,7 +4311,7 @@ var getVttCuesTool = {
 };
 // src/tools/write-file.ts
 import * as fs2 from "fs";
-import * as path2 from "path";
+import * as path3 from "path";
 var writeFileTool = {
   name: "write_file",
   description: "將內容寫入到指定的檔案中。用於產生修正清單、章節資訊、總結等輸出檔案。",
@@ -4111,8 +4326,8 @@ var writeFileTool = {
   },
   handler: async ({ filePath, content, encoding = "utf-8" }) => {
     try {
-      const absolutePath = path2.resolve(filePath);
-      const dir = path2.dirname(absolutePath);
+      const absolutePath = path3.resolve(filePath);
+      const dir = path3.dirname(absolutePath);
       if (!fs2.existsSync(dir)) {
         fs2.mkdirSync(dir, { recursive: true });
       }
@@ -4140,7 +4355,7 @@ var appendFileTool = {
   },
   handler: async ({ filePath, content }) => {
     try {
-      const absolutePath = path2.resolve(filePath);
+      const absolutePath = path3.resolve(filePath);
       fs2.appendFileSync(absolutePath, content, "utf-8");
       return {
         success: true,
@@ -4154,7 +4369,7 @@ var appendFileTool = {
 };
 // src/tools/update-vtt.ts
 import * as fs3 from "fs";
-import * as path3 from "path";
+import * as path4 from "path";
 var updateCueTool = {
   name: "update_cue",
   description: "更新指定索引的字幕內容。用於校正字幕中的錯字。",
@@ -4233,7 +4448,7 @@ var batchUpdateCuesTool = {
 };
 var saveVttTool = {
   name: "save_vtt",
-  description: "將修改後的 VTT 字幕儲存到檔案。",
+  description: "將修改後的字幕儲存到檔案 (支援 .vtt, .srt, .ass)。",
   parameters: {
     type: "object",
     properties: {
@@ -4247,8 +4462,14 @@ var saveVttTool = {
       return { success: false, error: "請先使用 read_vtt_file 載入 VTT 檔案" };
     }
     try {
-      const targetPath = outputPath ? path3.resolve(outputPath) : vttFile.filePath;
-      const content = formatVtt(vttFile);
+      const targetPath = outputPath ? path4.resolve(outputPath) : vttFile.filePath;
+      const ext = path4.extname(targetPath);
+      const captionCues = vttFile.cues.map((c) => ({
+        start: c.startSeconds * 1000,
+        end: c.endSeconds * 1000,
+        text: c.text
+      }));
+      const content = renderByExt(ext, captionCues);
       fs3.writeFileSync(targetPath, content, "utf-8");
       return {
         success: true,
@@ -4348,23 +4569,49 @@ async function sendAndWait(session, prompt, eventLogger) {
     });
   });
 }
+function isCopilotTimeoutError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.message.includes("Timeout: 等待 Copilot 回應超過 120 秒");
+}
+async function sendAndWaitWithRetry(session, prompt, eventLogger, maxRetries = 5) {
+  let attempt = 0;
+  while (true) {
+    try {
+      return await sendAndWait(session, prompt, eventLogger);
+    } catch (error) {
+      if (!isCopilotTimeoutError(error) || attempt >= maxRetries) {
+        throw error;
+      }
+      attempt += 1;
+      const waitMs = Math.min(2000 * attempt, 1e4);
+      console.warn(`發生 Copilot Timeout，將在 ${waitMs / 1000} 秒後重試 (${attempt}/${maxRetries})...`);
+      await new Promise((resolve5) => setTimeout(resolve5, waitMs));
+    }
+  }
+}
 async function runSubtitleCorrectionAgent(config) {
-  const { vttFilePath } = config;
-  const absolutePath = path4.resolve(vttFilePath);
-  const dir = config.outputDir || path4.dirname(absolutePath);
-  const baseName = path4.basename(absolutePath, path4.extname(absolutePath));
+  const { vttFilePath, overwrite, aiProvider } = config;
+  const absolutePath = path5.resolve(vttFilePath);
+  const dir = config.outputDir || path5.dirname(absolutePath);
+  const originalExt = path5.extname(absolutePath);
+  const baseName = path5.basename(absolutePath, originalExt);
+  const outputBaseName = overwrite ? baseName : `${baseName}-corrected`;
+  const correctedVttPath = path5.join(dir, `${outputBaseName}${originalExt}`);
+  const correctionsPath = path5.join(dir, `${outputBaseName}-corrections.txt`);
+  const chaptersPath = path5.join(dir, `${outputBaseName}-chapters.txt`);
+  const summaryPath = path5.join(dir, `${outputBaseName}-summary.txt`);
   const debugEvents = isDebugEnabled();
-  const eventLogPath = debugEvents ? path4.join(dir, `${baseName}-copilot-events.json`) : undefined;
+  const eventLogPath = debugEvents ? path5.join(dir, `${baseName}-copilot-events.json`) : undefined;
   const eventLogger = eventLogPath ? new EventLogger(eventLogPath) : undefined;
-  const correctedVttPath = path4.join(dir, `${baseName}-corrected.vtt`);
-  const correctionsPath = path4.join(dir, `${baseName}-corrections.txt`);
-  const chaptersPath = path4.join(dir, `${baseName}-chapters.txt`);
-  const summaryPath = path4.join(dir, `${baseName}-summary.txt`);
   console.log("=".repeat(60));
   console.log("字幕校正代理人 - 啟動");
   console.log("=".repeat(60));
   console.log(`輸入檔案: ${absolutePath}`);
   console.log(`輸出目錄: ${dir}`);
+  console.log(`覆寫模式: ${overwrite ? "開啟" : "關閉"}`);
+  console.log(`AI Provider: ${aiProvider || process.env.AI_PROVIDER || "(Auto Detect)"}`);
   console.log("=".repeat(60));
   if (eventLogPath) {
     console.log(`偵錯: Copilot events 記錄到 ${eventLogPath}`);
@@ -4375,6 +4622,9 @@ async function runSubtitleCorrectionAgent(config) {
     const azureEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
     const azureApiKey = process.env.AZURE_OPENAI_API_KEY;
     const azureDeployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+    const openaiApiKey = process.env.OPENAI_API_KEY;
+    const openaiApiBase = process.env.OPENAI_API_BASE;
+    const selectedProvider = aiProvider || process.env.AI_PROVIDER;
     const tools = [
       readVttTool,
       getVttCuesTool,
@@ -4385,8 +4635,11 @@ async function runSubtitleCorrectionAgent(config) {
       saveVttTool
     ];
     let session;
-    if (azureEndpoint && azureApiKey && azureDeployment) {
+    if (selectedProvider === "azure" || !selectedProvider && azureEndpoint && azureApiKey && azureDeployment) {
       console.log("使用 Azure OpenAI 作為模型提供者");
+      if (!azureEndpoint || !azureApiKey || !azureDeployment) {
+        throw new Error("選擇了 Azure Provider 但未設定 AZURE_OPENAI_* 環境變數");
+      }
       session = await client.createSession({
         model: azureDeployment,
         streaming: true,
@@ -4400,16 +4653,31 @@ async function runSubtitleCorrectionAgent(config) {
         },
         tools
       });
+    } else if (selectedProvider === "openai" || !selectedProvider && openaiApiKey) {
+      console.log("使用 OpenAI 作為模型提供者");
+      if (!openaiApiKey) {
+        throw new Error("選擇了 OpenAI Provider 但未設定 OPENAI_API_KEY 環境變數");
+      }
+      session = await client.createSession({
+        model: "gpt-4o",
+        streaming: true,
+        provider: {
+          type: "openai",
+          apiKey: openaiApiKey,
+          baseUrl: openaiApiBase || "https://api.openai.com/v1"
+        },
+        tools
+      });
     } else {
-      console.log("未找到完整的 Azure 配置，將使用預設的 GitHub Copilot 認證");
+      console.log("使用 GitHub Copilot 作為模型提供者");
       session = await client.createSession({
         tools
       });
     }
     console.log(`
-【步驟 1/7】讀取 VTT 檔案並分析主題方向...
+【步驟 1/7】讀取字幕檔案並分析主題方向...
 `);
-    await sendAndWait(session, `請使用 read_vtt_file 工具讀取 VTT 檔案: "${absolutePath}"
+    await sendAndWaitWithRetry(session, `請使用 read_vtt_file 工具讀取字幕檔案: "${absolutePath}"
 
 讀取完成後，請仔細閱讀整個字幕內容，分析並整理出：
 1. 這部影片的主要談論內容是什麼？
@@ -4417,60 +4685,133 @@ async function runSubtitleCorrectionAgent(config) {
 3. 這是什麼類型的影片？（教學、訪談、講座、會議等）
 
 請給出簡潔但完整的分析。`, eventLogger);
+    const initialVtt = getCachedVttFile();
+    if (!initialVtt) {
+      throw new Error("無法取得字幕檔案內容");
+    }
+    const originalCues = JSON.parse(JSON.stringify(initialVtt.cues));
     console.log(`
 【步驟 2/7】整理主題相關的關鍵字與專有名詞...
 `);
-    await sendAndWait(session, `根據你剛才分析出的影片主題方向，請整理出這個主題領域中常見的：
+    await sendAndWaitWithRetry(session, `根據你剛才分析出的影片主題方向，請整理出這個主題領域中常見的：
 1. 專業術語與關鍵字
 2. 專有名詞（人名、產品名、技術名稱等）
 3. 常見的縮寫與其全稱
 
 【重要】請不要參考字幕的實際內容來整理這些詞彙（因為字幕可能有轉錄錯誤）。
 請根據你對這個主題領域的知識，列出這些詞彙的「正確寫法」，這將用於後續的字幕校正。`, eventLogger);
+    const CHUNK_SIZE = config.chunkSize || 100;
+    const totalCues = initialVtt.cues.length;
+    const totalChunks = Math.ceil(totalCues / CHUNK_SIZE);
+    const tempPass1Path = path5.join(dir, `${baseName}-temp-pass1${originalExt}`);
+    console.log(`
+【步驟 3-4 (Phase 1)/7】第一階段校正：修正聽寫與拼寫錯誤...
+`);
+    console.log(`總共有 ${totalCues} 個字幕片段，將分為 ${totalChunks} 個批次進行處理。
+`);
+    for (let i = 0;i < totalChunks; i++) {
+      const startIdx = i * CHUNK_SIZE;
+      const endIdx = Math.min((i + 1) * CHUNK_SIZE, totalCues);
+      const currentChunk = getCachedVttFile().cues.slice(startIdx, endIdx);
+      console.log(`[Phase 1] 正在處理第 ${i + 1}/${totalChunks} 批次 (索引 ${startIdx} - ${endIdx - 1})...`);
+      const chunkContent = currentChunk.map((c) => `[${c.index}] ${c.startTime} --> ${c.endTime}
+${c.text}`).join(`
+
+`);
+      await sendAndWaitWithRetry(session, `這是第一階段校正，第 ${i + 1}/${totalChunks} 批次 (索引 ${startIdx} 到 ${endIdx - 1})。
+
+${chunkContent}
+
+請根據主題上下文，修正上述字幕中的**聽寫錯誤**與**錯別字**。
+
+原則：
+1. **僅修正錯誤**：專注於同音異字（如「再/在」）、拼寫錯誤、或明顯的轉錄失誤。
+2. **保留原意**：嚴禁重寫句子或加入不存在的資訊。
+3. **術語一致**：參考之前的關鍵字列表，確保專有名詞正確。
+
+請使用 batch_update_cues 工具進行修正。如果沒有錯誤則無需操作。`, eventLogger);
+    }
+    console.log(`
+[Phase 1] 完成，儲存暫存檔至: ${tempPass1Path}`);
+    await sendAndWaitWithRetry(session, `請使用 save_vtt 工具將目前進度儲存到 "${tempPass1Path}"`, eventLogger);
     console.log(`
-【步驟 3-4/7】分析字幕正確性並進行校正...
+【步驟 4.5 (Phase 2)/7】第二階段校正：檢查一致性與遺漏...
 `);
-    await sendAndWait(session, `現在請逐一分析已載入的 VTT 字幕檔案中每一段 Cue 的正確性。
+    console.log(`正在讀取第一階段校正結果，準備進行複查...
+`);
+    for (let i = 0;i < totalChunks; i++) {
+      const startIdx = i * CHUNK_SIZE;
+      const endIdx = Math.min((i + 1) * CHUNK_SIZE, totalCues);
+      const currentChunk = getCachedVttFile().cues.slice(startIdx, endIdx);
+      console.log(`[Phase 2] 正在複查第 ${i + 1}/${totalChunks} 批次 (索引 ${startIdx} - ${endIdx - 1})...`);
+      const chunkContent = currentChunk.map((c) => `[${c.index}] ${c.startTime} --> ${c.endTime}
+${c.text}`).join(`
+
+`);
+      await sendAndWaitWithRetry(session, `這是第二階段複查，第 ${i + 1}/${totalChunks} 批次 (索引 ${startIdx} 到 ${endIdx - 1})。
+這些字幕已經經過初步校正。
 
-對於每個 Cue：
-1. 檢查是否有潛在的錯字、同音字錯誤、轉錄錯誤
-2. 根據上下文和你整理出的正確關鍵字/專有名詞，推理出正確的文字
-3. 如果需要校正，請使用 batch_update_cues 工具批次更新校正後的字幕
+${chunkContent}
 
-請特別注意：
-- 專業術語和專有名詞的正確性
-- 同音異義字的正確使用
-- 語句的通順和邏輯性
-- 標點符號的使用
+請進行最後檢查：
+1. **檢查遺漏**：是否有第一階段漏掉的明顯錯誤？
+2. **檢查一致性**：專有名詞的使用是否前後一致？
+3. **檢查過度校正**：確認第一階段沒有改變原意或產生幻覺（若有，請改回原意）。
 
-處理完成後，請報告發現了多少個需要校正的問題。`, eventLogger);
+請使用 batch_update_cues 工具修正任何殘留問題。若完美則無需操作。`, eventLogger);
+    }
     console.log(`
-【步驟 5/7】產生修正清單...
+所有批次複查完成。
 `);
-    await sendAndWait(session, `請整理所有剛才進行的字幕校正，使用 write_file 工具將修正清單寫入到：
-"${correctionsPath}"
-
-修正清單的格式應該包含：
-1. 標題：字幕修正清單
-2. 修正日期與時間
-3. 原始檔案路徑
-4. 修正統計（總共修正了多少處）
-5. 每一筆修正的詳細資訊：
-   - Cue 索引與時間戳
-   - 原始文字
-   - 校正後文字
-   - 修正原因說明
-
-請以清晰易讀的格式呈現。`, eventLogger);
     console.log(`
-【儲存校正後的 VTT 檔案】
+【步驟 5/7】產生修正清單 (自動比對)...
+`);
+    const finalCues = getCachedVttFile().cues;
+    let correctionsCount = 0;
+    let correctionsContent = `字幕修正清單
+產生日期: ${new Date().toLocaleString()}
+原始檔案: ${absolutePath}
+
+`;
+    correctionsContent += `| 索引 | 時間 | 原始文字 | 校正後文字 |
+`;
+    correctionsContent += `| --- | --- | --- | --- |
+`;
+    for (let i = 0;i < finalCues.length; i++) {
+      const original = originalCues[i];
+      const final = finalCues[i];
+      if (original.text !== final.text) {
+        correctionsCount++;
+        const oldText = original.text.replace(/\n/g, " ");
+        const newText = final.text.replace(/\n/g, " ");
+        correctionsContent += `| ${final.index} | ${final.startTime} | ${oldText} | ${newText} |
+`;
+      }
+    }
+    correctionsContent = `總共修正: ${correctionsCount} 處
+
+` + correctionsContent;
+    fs4.writeFileSync(correctionsPath, correctionsContent, "utf-8");
+    console.log(`修正清單已寫入: ${correctionsPath} (共 ${correctionsCount} 處修正)`);
+    console.log(`
+【儲存校正後的字幕檔案】
 `);
-    await sendAndWait(session, `請使用 save_vtt 工具將校正後的字幕儲存到：
-"${correctedVttPath}"`, eventLogger);
+    const vttFile = getCachedVttFile();
+    const captionCues = vttFile.cues.map((c) => ({
+      start: c.startSeconds * 1000,
+      end: c.endSeconds * 1000,
+      text: c.text
+    }));
+    for (const ext of SUPPORTED_EXTS) {
+      const targetPath = path5.join(dir, `${outputBaseName}${ext}`);
+      const content = renderByExt(ext, captionCues);
+      fs4.writeFileSync(targetPath, content, "utf-8");
+      console.log(`已儲存: ${targetPath}`);
+    }
     console.log(`
 【步驟 6/7】建立分段章節...
 `);
-    await sendAndWait(session, `你現在是一個 **Video Chapter Segmenter**，負責分析字幕內容並將影片分割成清晰、合理的章節。
+    await sendAndWaitWithRetry(session, `你現在是一個 **Video Chapter Segmenter**，負責分析字幕內容並將影片分割成清晰、合理的章節。
 
 ## 分析準則
 - **主題轉換**: 識別主題或討論重點的變化
@@ -4486,8 +4827,8 @@ async function runSubtitleCorrectionAgent(config) {
 - **風格一致**: 所有標題保持統一的格式和語調
 
 ## 輸出格式要求
-- **嚴格格式**: \`HH:mm:ss 章節標題\`
-- **第一章節**: 必須以 \`00:00:00 開始\` 開頭
+- **嚴格格式**: 
+- **第一章節**: 必須以 
 - **時間精確度**: 使用字幕檔案中的精確時間戳
 - **每行一章**: 每個章節獨立一行
 - **無額外格式**: 不使用項目符號、編號或特殊字元
@@ -4499,7 +4840,6 @@ async function runSubtitleCorrectionAgent(config) {
 - **完整覆蓋**: 確保從頭到尾完整覆蓋影片
 
 ## 輸出範例
-\`\`\`
 00:00:00 開始
 00:00:16 開發過程的混亂
 00:00:28 規格驅動開發的啟發
@@ -4508,7 +4848,6 @@ async function runSubtitleCorrectionAgent(config) {
 00:01:38 團隊協作的重要性
 00:02:04 從混沌到清晰的轉變
 00:02:29 終章：持續改進的承諾
-\`\`\`
 
 請根據校正後的字幕內容，深入分析並自動建立分段章節。
 使用 write_file 工具將章節資訊寫入到：
@@ -4518,7 +4857,7 @@ async function runSubtitleCorrectionAgent(config) {
     console.log(`
 【步驟 7/7】產生內容總結...
 `);
-    await sendAndWait(session, `請根據校正後的字幕內容，用一段話總結這部影片的主要內容。
+    await sendAndWaitWithRetry(session, `請根據校正後的字幕內容，用一段話總結這部影片的主要內容。
 
 總結應該：
 1. 概括影片的核心主題
@@ -4534,7 +4873,7 @@ async function runSubtitleCorrectionAgent(config) {
     console.log("=".repeat(60));
     console.log("字幕校正完成！");
     console.log("=".repeat(60));
-    console.log(`校正後字幕: ${correctedVttPath}`);
+    console.log(`校正後字幕 (Primary): ${correctedVttPath}`);
     console.log(`修正清單: ${correctionsPath}`);
     console.log(`章節資訊: ${chaptersPath}`);
     console.log(`內容總結: ${summaryPath}`);
@@ -4564,41 +4903,40 @@ function printUsage() {
 ========================
 
 使用方式:
-  subtitle-correction-agent <vtt-file-path> [options]
+  subtitle-correction-agent <file-path> [options]
   subtitle-correction-agent --version
 
 參數:
-  <vtt-file-path>     VTT 字幕檔案的路徑 (必須)
+  <file-path>           字幕檔案的路徑 (支援 .vtt, .srt, .ass)
 
 選項:
-  --output-dir <dir>  指定輸出目錄 (預設為 VTT 檔案所在目錄)
-  --version, -v       顯示版本與環境資訊
-  --help, -h          顯示此說明
+  --output-dir <dir>    指定輸出目錄 (預設為字幕檔案所在目錄)
+  --chunk-size <number> 指定分段處理的大小 (預設: 100)
+  --overwrite           直接覆寫原始檔案 (僅限 Git 專案且無未提交變更時可用)
+  --ai-provider <name>  指定 AI 提供者 (azure, openai, github，預設優先使用環境變數設定)
+  --version, -v         顯示版本與環境資訊
+  --help, -h            顯示此說明
 
 範例:
   subtitle-correction-agent ./video.vtt
+  subtitle-correction-agent ./video.srt --overwrite
+  subtitle-correction-agent ./video.ass --ai-provider azure
   subtitle-correction-agent ./video.vtt --output-dir ./output
-  subtitle-correction-agent --version
-  npx @willh/subtitle-correction-agent ./video.vtt
-  subtitle-correction-agent "C:\\Videos\\lecture.vtt"
-
-輸出檔案:
-  {filename}-corrected.vtt   校正後的字幕檔案
-  {filename}-corrections.txt 修正清單
-  {filename}-chapters.txt    章節資訊
-  {filename}-summary.txt     內容總結
 
 環境變數:
   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)
+  OPENAI_API_KEY             OpenAI API 金鑰
+  OPENAI_API_BASE            OpenAI API Base URL (選填，可用於 Ollama)
+  AI_PROVIDER                預設 AI 提供者 (azure, openai, github)
 `);
 }
 function parseArgs(args) {
   const result = {
     help: false,
-    version: false
+    version: false,
+    overwrite: false
   };
   for (let i = 0;i < args.length; i++) {
     const arg = args[i];
@@ -4608,6 +4946,15 @@ function parseArgs(args) {
       result.version = true;
     } else if (arg === "--output-dir" && i + 1 < args.length) {
       result.outputDir = args[++i];
+    } else if (arg === "--chunk-size" && i + 1 < args.length) {
+      const val = parseInt(args[++i], 10);
+      if (!isNaN(val) && val > 0) {
+        result.chunkSize = val;
+      }
+    } else if (arg === "--overwrite") {
+      result.overwrite = true;
+    } else if (arg === "--ai-provider" && i + 1 < args.length) {
+      result.aiProvider = args[++i];
     } else if (!arg.startsWith("-") && !result.vttFilePath) {
       result.vttFilePath = arg;
     }
@@ -4616,13 +4963,13 @@ function parseArgs(args) {
 }
 function resolveProjectRoot() {
   const currentFile = fileURLToPath(import.meta.url);
-  let dir = path5.dirname(currentFile);
+  let dir = path6.dirname(currentFile);
   while (true) {
-    const candidate = path5.join(dir, "package.json");
+    const candidate = path6.join(dir, "package.json");
     if (fs5.existsSync(candidate)) {
       return dir;
     }
-    const parent = path5.dirname(dir);
+    const parent = path6.dirname(dir);
     if (parent === dir) {
       return null;
     }
@@ -4641,7 +4988,7 @@ function resolveAppVersion(projectRoot) {
   if (!projectRoot) {
     return "未知";
   }
-  const pkgJson = readJsonFile(path5.join(projectRoot, "package.json"));
+  const pkgJson = readJsonFile(path6.join(projectRoot, "package.json"));
   if (pkgJson && typeof pkgJson.version === "string") {
     return pkgJson.version;
   }
@@ -4651,12 +4998,12 @@ function resolveCopilotSdkVersion(projectRoot) {
   if (!projectRoot) {
     return "未知";
   }
-  const modulePath = path5.join(projectRoot, "node_modules", "@github", "copilot-sdk", "package.json");
+  const modulePath = path6.join(projectRoot, "node_modules", "@github", "copilot-sdk", "package.json");
   const moduleJson = readJsonFile(modulePath);
   if (moduleJson && typeof moduleJson.version === "string") {
     return moduleJson.version;
   }
-  const pkgJson = readJsonFile(path5.join(projectRoot, "package.json"));
+  const pkgJson = readJsonFile(path6.join(projectRoot, "package.json"));
   if (!pkgJson) {
     return "未知";
   }
@@ -4712,14 +5059,9 @@ AZURE_OPENAI_ENDPOINT: ${endpoint ? formatEnvValue(endpoint) : "未設定"}
 AZURE_OPENAI_API_KEY: ${maskSecret(apiKey)}
 AZURE_OPENAI_DEPLOYMENT: ${formatEnvValue(deployment)}
 AZURE_OPENAI_API_VERSION: ${formatEnvValue(process.env.AZURE_OPENAI_API_VERSION)}
-TELEGRAM_BOT_TOKEN: ${maskSecret(process.env.TELEGRAM_BOT_TOKEN)}
-TELEGRAM_STARTUP_CHAT_ID: ${formatEnvValue(process.env.TELEGRAM_STARTUP_CHAT_ID)}
-OWNER_CHAT_ID: ${formatEnvValue(process.env.OWNER_CHAT_ID)}
-BOT_MAX_CONCURRENT: ${formatEnvValue(process.env.BOT_MAX_CONCURRENT)}
-KEEP_TEMP_FILES: ${formatEnvValue(process.env.KEEP_TEMP_FILES)}
-BOT_LOG_LEVEL: ${formatEnvValue(process.env.BOT_LOG_LEVEL)}
-BOT_DEBUG: ${formatEnvValue(process.env.BOT_DEBUG)}
-BOT_DATA_DIR: ${formatEnvValue(process.env.BOT_DATA_DIR)}
+OPENAI_API_KEY: ${maskSecret(process.env.OPENAI_API_KEY)}
+OPENAI_API_BASE: ${formatEnvValue(process.env.OPENAI_API_BASE)}
+AI_PROVIDER: ${formatEnvValue(process.env.AI_PROVIDER)}
 
 Copilot SDK
 -----------
@@ -4732,6 +5074,24 @@ Provider.apiVersion: ${apiVersion}
 Provider.apiKey: ${maskSecret(apiKey)}` : ""}
 `);
 }
+function checkGitStatus(dir) {
+  try {
+    execSync("git rev-parse --is-inside-work-tree", { cwd: dir, stdio: "ignore" });
+  } catch {
+    throw new Error("使用 --overwrite 參數時，目標目錄必須受 Git 版本控制");
+  }
+  try {
+    const status = execSync("git status --porcelain", { cwd: dir, encoding: "utf-8" });
+    if (status.trim().length > 0) {
+      throw new Error("使用 --overwrite 參數時，工作目錄必須是乾淨的 (請先 Commit 或 Stash 您的變更)");
+    }
+  } catch (error) {
+    if (error.message.includes("工作目錄必須是乾淨的")) {
+      throw error;
+    }
+    throw new Error("無法檢查 Git 狀態，請確認 git 指令可正常執行");
+  }
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.version) {
@@ -4742,21 +5102,39 @@ async function main() {
     printUsage();
     process.exit(args.help ? 0 : 1);
   }
-  const vttFilePath = path5.resolve(args.vttFilePath);
+  const vttFilePath = path6.resolve(args.vttFilePath);
   if (!fs5.existsSync(vttFilePath)) {
     console.error(`錯誤: 找不到檔案 "${vttFilePath}"`);
     process.exit(1);
   }
-  if (!vttFilePath.toLowerCase().endsWith(".vtt")) {
-    console.error(`錯誤: 檔案必須是 .vtt 格式`);
+  const ext = path6.extname(vttFilePath).toLowerCase();
+  if (!SUPPORTED_EXTS.has(ext)) {
+    console.error(`錯誤: 不支援的檔案格式 "${ext}"。支援的格式: ${Array.from(SUPPORTED_EXTS).join(", ")}`);
     process.exit(1);
   }
-  const vttDir = path5.dirname(vttFilePath);
+  process.on("SIGINT", () => {
+    console.log(`
+
+收到中斷訊號，正在停止程式...`);
+    process.exit(130);
+  });
+  const vttDir = path6.dirname(vttFilePath);
+  if (args.overwrite) {
+    try {
+      checkGitStatus(vttDir);
+    } catch (error) {
+      console.error(`錯誤: ${error.message}`);
+      process.exit(1);
+    }
+  }
   process.chdir(vttDir);
   console.log(`工作目錄: ${vttDir}`);
   const result = await runSubtitleCorrectionAgent({
     vttFilePath,
-    outputDir: args.outputDir
+    outputDir: args.outputDir,
+    chunkSize: args.chunkSize,
+    overwrite: args.overwrite,
+    aiProvider: args.aiProvider
   });
   if (!result.success) {
     console.error(`錯誤: ${result.error}`);
@@ -4770,7 +5148,7 @@ var isDirectRun = (() => {
     return metaMain;
   }
   const entryPath = fileURLToPath(import.meta.url);
-  return Boolean(process.argv[1]) && path5.resolve(process.argv[1]) === path5.resolve(entryPath);
+  return Boolean(process.argv[1]) && path6.resolve(process.argv[1]) === path6.resolve(entryPath);
 })();
 if (isDirectRun) {
   main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willh/subtitle-correction-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "影片字幕校正代理人 - 使用 GitHub Copilot SDK",
   "type": "module",
   "files": [
@@ -9,36 +9,30 @@
   "bin": {
     "subtitle-correction-agent": "dist/index.js"
   },
-  "main": "dist/index.js",
-  "scripts": {
-    "bump": "npm version patch --no-git-tag-version && npm install --package-lock-only",
-
-    "build": "bun build src/index.ts --outdir dist --target node --format esm",
-    "start": "npm run build && bun run src/index.ts",
-    "dev": "npm run build && bun run src/index.ts",
-
-    "build:bot": "bun build src/telegram-bot.ts --outdir dist --target node --format esm",
-    "bot": "npm run build:bot && bun run src/telegram-bot.ts",
-
-    "prepack": "npm run build",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit"
-  },
-  "keywords": [
-    "subtitle",
-    "vtt",
-    "correction",
-    "copilot-sdk",
-    "agent"
-  ],
-  "author": "Will 保哥",
-  "license": "MIT",
-  "dependencies": {
-    "@github/copilot-sdk": "^0.1.0",
-    "telegraf": "^4.16.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "typescript": "^5.3.3"
+    "main": "dist/index.js",
+    "scripts": {
+      "bump": "npm version patch --no-git-tag-version && npm install --package-lock-only",
+      "build": "bun build src/index.ts --outdir dist --target node --format esm",
+      "start": "npm run build && bun run src/index.ts",
+      "dev": "npm run build && bun run src/index.ts",
+      "prepack": "npm run build",
+      "test": "bun test",
+      "typecheck": "tsc --noEmit"
+    },
+    "keywords": [
+      "subtitle",
+      "vtt",
+      "correction",
+      "copilot-sdk",
+      "agent"
+    ],
+    "author": "Will 保哥",
+    "license": "MIT",
+    "dependencies": {
+      "@github/copilot-sdk": "^0.1.0"
+    },
+    "devDependencies": {
+      "@types/node": "^20.11.0",
+      "typescript": "^5.3.3"
+    }
   }
-}