@casatwy/deyo 0.1.3 → 0.1.4

package/README.md

@@ -93,6 +93,12 @@ deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 deyo --format srt -O ./transcript.srt 'https://www.youtube.com/watch?v=xxxx'
 ```
 
+为 AI 或日志系统输出结构化进度：
+
+```bash
+deyo --progress-format jsonl -O ./transcript.txt 'https://www.youtube.com/watch?v=xxxx'
+```
+
 如果输出文件名本身就是 `.srt`，也可以省略 `--format srt`，CLI 会自动识别格式。
 
 指定输出英文转写结果：
@@ -131,6 +137,21 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 - `.vtt` 会自动使用 `vtt`
 - 其他情况默认使用 `text`
 
+`--progress-format <value>`
+
+指定进度输出格式，支持：
+
+- `auto`
+- `text`
+- `jsonl`
+
+默认值是 `auto`：
+
+- 当 stderr 是 TTY 时，会保留当前的单行原地刷新进度体验
+- 当 stderr 不是 TTY 时，会退化成逐行文本进度，避免控制字符污染日志或代理输出
+
+如果你希望 AI 或脚本稳定读取进度事件，建议使用 `--progress-format jsonl`。此时 CLI 会继续把最终结果输出到 stdout 或文件，只把进度事件按 JSON Lines 写到 stderr。
+
 `--api-key <key>`
 
 为当前这一次命令临时指定 API Key。  
@@ -154,7 +175,7 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 2. 如何向你索取一次 API Key
 3. 如何在你的本地环境执行 `deyo auth login`
 
-完成后，你就可以让 AI 直接帮你调用 `deyo` 提交转写任务。
+完成后，你就可以让 AI 直接帮你调用 `deyo` 提交转写任务。对于需要在对话里持续同步进度的场景，AI 应优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把任务创建、状态切换、关键百分比和最终结果转述给你。
 
 ## 更多帮助
 

package/deyo.mjs

@@ -11,9 +11,12 @@ const CLI_VERSION = createRequire(import.meta.url)('./package.json').version
 const DEFAULT_BASE_URL = 'https://deyo.miaobi.fun'
 const DEFAULT_LANGUAGE = 'zh'
 const POLL_INTERVAL_MS = 1500
+const PROGRESS_FORMATS = new Set(['auto', 'text', 'jsonl'])
 const RESULT_FORMATS = new Set(['text', 'srt', 'vtt', 'json', 'verbose_json'])
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled'])
 
+class ReportedCliError extends Error {}
+
 function safeJsonParse(value) {
   try {
     return JSON.parse(value)
@@ -38,6 +41,7 @@ function printUsage() {
   --source <name>       可选，显式指定来源
   --language <value>    可选，转写语言，默认 ${DEFAULT_LANGUAGE}
   --format <value>      可选，text | srt | vtt | json | verbose_json
+  --progress-format <v> 可选，auto | text | jsonl，默认 auto
   --base-url <url>      可选，默认 ${DEFAULT_BASE_URL}
   -h, --help            显示帮助
   -v, --version         显示 CLI 版本
@@ -74,6 +78,7 @@ function parseTranscriptionArgs(argv) {
     source: '',
     language: '',
     format: '',
+    progressFormat: 'auto',
     baseUrl: '',
     url: '',
   }
@@ -116,6 +121,12 @@ function parseTranscriptionArgs(argv) {
       continue
     }
 
+    if (current === '--progress-format') {
+      args.progressFormat = argv[index + 1] || ''
+      index += 1
+      continue
+    }
+
     if (current === '--base-url') {
       args.baseUrl = argv[index + 1] || ''
       index += 1
@@ -456,6 +467,20 @@ function createOutputState() {
   }
 }
 
+function resolveProgressFormat(progressFormat) {
+  const normalized = String(progressFormat || 'auto').trim() || 'auto'
+
+  if (!PROGRESS_FORMATS.has(normalized)) {
+    fail(`--progress-format 不支持：${normalized}`)
+  }
+
+  if (normalized === 'auto') {
+    return process.stderr.isTTY ? 'interactive' : 'text'
+  }
+
+  return normalized
+}
+
 function clearInline(outputState) {
   if (!outputState.inlineActive) {
     return
@@ -484,6 +509,26 @@ function finishInline(outputState) {
   outputState.inlineActive = false
 }
 
+function buildStatusChangedMessage(status) {
+  return `状态更新：${formatStatus(status)}`
+}
+
+function buildTerminalMessage(status, errorMessage) {
+  if (status === 'completed') {
+    return '任务已完成'
+  }
+
+  if (status === 'failed') {
+    return errorMessage ? `任务失败：${errorMessage}` : '任务失败'
+  }
+
+  if (status === 'cancelled') {
+    return errorMessage ? `任务已取消：${errorMessage}` : '任务已取消'
+  }
+
+  return errorMessage ? `任务结束：${errorMessage}` : `任务结束：${formatStatus(status)}`
+}
+
 function normalizeProgressValue(progress, finishedChunks, totalChunks) {
   if (Number.isFinite(progress) && progress >= 0) {
     return Math.max(0, Math.min(1, progress))
@@ -521,6 +566,142 @@ function buildTranscribingProgressMessage(input = {}) {
   return `转写中 ${percent}%${chunksPart}`
 }
 
+function createProgressReporter(progressFormat) {
+  const resolvedMode = resolveProgressFormat(progressFormat)
+  const outputState = createOutputState()
+  let lastTextProgressMessage = ''
+  let lastTerminalSignature = ''
+
+  function writeTextMessage(message) {
+    writeStatusLine(outputState, message)
+  }
+
+  function writeJsonEvent(payload) {
+    clearInline(outputState)
+    process.stderr.write(`${JSON.stringify(payload)}\n`)
+  }
+
+  function emitTextOrJson(message, payload) {
+    if (resolvedMode === 'jsonl') {
+      writeJsonEvent({
+        ...payload,
+        message,
+      })
+      return
+    }
+
+    writeTextMessage(message)
+  }
+
+  return {
+    mode: resolvedMode,
+    reportTaskCreated(task) {
+      if (resolvedMode === 'jsonl') {
+        writeJsonEvent({
+          event: 'task.created',
+          message: `任务已创建：${task.taskId}`,
+          taskId: task.taskId,
+          title: task.title,
+          sourceType: task.sourceType,
+          status: task.status,
+          statusLabel: formatStatus(task.status),
+          consumedMinutes: task.consumedMinutes,
+          remainingMinutes: task.remainingMinutes,
+          mode: task.mode,
+          resultReady: task.resultReady,
+        })
+        return
+      }
+
+      writeTextMessage(`任务已创建：${task.taskId}`)
+      writeTextMessage(`标题：${task.title}`)
+      writeTextMessage(`来源：${task.sourceType}`)
+      writeTextMessage(`状态：${formatStatus(task.status)}`)
+      writeTextMessage(`本次消耗分钟：${task.consumedMinutes}`)
+      writeTextMessage(`剩余分钟：${task.remainingMinutes}`)
+    },
+    reportStatusChanged(status) {
+      emitTextOrJson(buildStatusChangedMessage(status), {
+        event: 'task.status_changed',
+        status,
+        statusLabel: formatStatus(status),
+      })
+    },
+    reportProgress(input = {}) {
+      const finishedChunks = Number(input.finishedChunks)
+      const totalChunks = Number(input.totalChunks)
+      const normalizedProgress = normalizeProgressValue(
+        Number(input.progress),
+        finishedChunks,
+        totalChunks,
+      )
+      const message = buildTranscribingProgressMessage(input)
+
+      lastTerminalSignature = ''
+
+      if (resolvedMode === 'interactive') {
+        writeInline(outputState, message)
+        return
+      }
+
+      if (resolvedMode === 'jsonl') {
+        writeJsonEvent({
+          event: 'task.progress',
+          message,
+          status: 'transcribing',
+          progress: normalizedProgress,
+          percent: normalizedProgress === null ? null : Math.round(normalizedProgress * 100),
+          finishedChunks: Number.isFinite(finishedChunks) ? Math.max(0, finishedChunks) : null,
+          totalChunks: Number.isFinite(totalChunks) && totalChunks > 0 ? totalChunks : null,
+        })
+        return
+      }
+
+      if (message === lastTextProgressMessage) {
+        return
+      }
+
+      lastTextProgressMessage = message
+      writeTextMessage(message)
+    },
+    reportTerminal(status, errorMessage) {
+      if (!status) {
+        return
+      }
+
+      finishInline(outputState)
+      const signature = `${status}:${errorMessage || ''}`
+
+      if (lastTerminalSignature === signature) {
+        return
+      }
+
+      lastTerminalSignature = signature
+      emitTextOrJson(buildTerminalMessage(status, errorMessage), {
+        event: `task.${status}`,
+        status,
+        statusLabel: formatStatus(status),
+        error: errorMessage || null,
+      })
+    },
+    reportResultWritten(outputPath, format) {
+      emitTextOrJson(`结果已写入：${outputPath}`, {
+        event: 'task.result_written',
+        outputPath,
+        format,
+      })
+    },
+    reportNotice(message) {
+      emitTextOrJson(message, {
+        event: 'task.notice',
+      })
+    },
+    close() {
+      finishInline(outputState)
+    },
+  }
+}
+
 function parseSseBlock(block) {
   const lines = block.split('\n')
   let event = 'message'
@@ -547,7 +728,7 @@ function parseSseBlock(block) {
   }
 }
 
-async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputState) {
+async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, reporter) {
   const response = await fetch(`${baseUrl}/api/cli/transcriptions/${encodeURIComponent(taskId)}/events`, {
     method: 'GET',
     headers: {
@@ -577,7 +758,13 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputSta
       ...task,
       status: nextStatus,
     }
-    writeStatusLine(outputState, `状态更新：${formatStatus(nextStatus)}`)
+
+    if (TERMINAL_STATUSES.has(nextStatus)) {
+      reporter.reportTerminal(nextStatus, task.error || null)
+      return
+    }
+
+    reporter.reportStatusChanged(nextStatus)
   }
 
   function applyTerminal(nextStatus, errorMessage) {
@@ -587,7 +774,7 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputSta
       status: nextStatus,
       error: errorMessage || task.error || null,
     }
-    finishInline(outputState)
+    reporter.reportTerminal(nextStatus, task.error || null)
   }
 
   function renderProgress(data) {
@@ -596,7 +783,7 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputSta
       ...task,
       status: 'transcribing',
     }
-    writeInline(outputState, buildTranscribingProgressMessage(data))
+    reporter.reportProgress(data)
   }
 
   while (true) {
@@ -625,6 +812,8 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputSta
       if (event === 'job.snapshot') {
         if (data?.status === 'transcribing') {
           renderProgress(data)
+        } else if (TERMINAL_STATUSES.has(data?.status)) {
+          applyTerminal(data.status, data?.error || data?.message || null)
         } else {
           applyStatus(data?.status)
         }
@@ -658,7 +847,7 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, outputSta
     }
   }
 
-  finishInline(outputState)
+  reporter.close()
   return task
 }
 
@@ -743,85 +932,95 @@ async function handleAuthCommand(argv) {
 
 async function handleTranscription(argv) {
   const args = parseTranscriptionArgs(argv)
-  const storedConfig = await readStoredConfig()
-  const resolvedApiKey = resolveApiKey(args.apiKey, storedConfig)
-
-  if (!resolvedApiKey) {
-    printUsage()
-    fail('缺少 API key。请传 --api-key、设置 DEYO_API_KEY，或先执行 deyo auth login')
-  }
+  const reporter = createProgressReporter(args.progressFormat)
+  try {
+    const storedConfig = await readStoredConfig()
+    const resolvedApiKey = resolveApiKey(args.apiKey, storedConfig)
 
-  if (!args.url) {
-    printUsage()
-    fail('缺少内容链接')
-  }
+    if (!resolvedApiKey) {
+      printUsage()
+      fail('缺少 API key。请传 --api-key、设置 DEYO_API_KEY，或先执行 deyo auth login')
+    }
 
-  const { baseUrl } = resolveBaseUrl(args.baseUrl, storedConfig)
-  const format = inferFormat(args.output, args.format)
-  const createPayload = {
-    url: args.url,
-    language: args.language || DEFAULT_LANGUAGE,
-  }
+    if (!args.url) {
+      printUsage()
+      fail('缺少内容链接')
+    }
 
-  if (args.source) {
-    createPayload.source = args.source
-  }
+    const { baseUrl } = resolveBaseUrl(args.baseUrl, storedConfig)
+    const format = inferFormat(args.output, args.format)
+    const createPayload = {
+      url: args.url,
+      language: args.language || DEFAULT_LANGUAGE,
+    }
 
-  const created = await requestJson(baseUrl, resolvedApiKey.apiKey, '/api/cli/transcriptions', {
-    method: 'POST',
-    body: createPayload,
-  })
-  const outputState = createOutputState()
+    if (args.source) {
+      createPayload.source = args.source
+    }
 
-  process.stderr.write(`任务已创建：${created.taskId}\n`)
-  process.stderr.write(`标题：${created.title}\n`)
-  process.stderr.write(`来源：${created.sourceType}\n`)
-  process.stderr.write(`状态：${formatStatus(created.status)}\n`)
-  process.stderr.write(`本次消耗分钟：${created.consumedMinutes}\n`)
-  process.stderr.write(`剩余分钟：${created.remainingMinutes}\n`)
+    const created = await requestJson(baseUrl, resolvedApiKey.apiKey, '/api/cli/transcriptions', {
+      method: 'POST',
+      body: createPayload,
+    })
+    reporter.reportTaskCreated(created)
+
+    let task = created
+    let lastStatus = created.status
+
+    if (task.mode === 'transcription' && !TERMINAL_STATUSES.has(task.status)) {
+      try {
+        task = await consumeTaskEvents(baseUrl, resolvedApiKey.apiKey, task.taskId, task, reporter)
+        lastStatus = task.status
+      } catch (error) {
+        reporter.reportNotice(`事件流中断，回退到轮询状态：${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
 
-  let task = created
-  let lastStatus = created.status
+    while (!TERMINAL_STATUSES.has(task.status)) {
+      await sleep(POLL_INTERVAL_MS)
+      task = await requestJson(baseUrl, resolvedApiKey.apiKey, `/api/cli/transcriptions/${encodeURIComponent(task.taskId)}`)
 
-  if (task.mode === 'transcription' && !TERMINAL_STATUSES.has(task.status)) {
-    try {
-      task = await consumeTaskEvents(baseUrl, resolvedApiKey.apiKey, task.taskId, task, outputState)
-      lastStatus = task.status
-    } catch (error) {
-      finishInline(outputState)
-      process.stderr.write(`事件流中断，回退到轮询状态：${error instanceof Error ? error.message : String(error)}\n`)
+      if (task.status !== lastStatus) {
+        if (TERMINAL_STATUSES.has(task.status)) {
+          reporter.reportTerminal(task.status, task.error || null)
+        } else {
+          reporter.reportStatusChanged(task.status)
+        }
+        lastStatus = task.status
+      }
     }
-  }
 
-  while (!TERMINAL_STATUSES.has(task.status)) {
-    await sleep(POLL_INTERVAL_MS)
-    task = await requestJson(baseUrl, resolvedApiKey.apiKey, `/api/cli/transcriptions/${encodeURIComponent(task.taskId)}`)
+    reporter.reportTerminal(task.status, task.error || null)
 
-    if (task.status !== lastStatus) {
-      finishInline(outputState)
-      process.stderr.write(`状态更新：${formatStatus(task.status)}\n`)
-      lastStatus = task.status
+    if (task.status !== 'completed') {
+      throw new ReportedCliError(task.error || `任务未成功完成：${formatStatus(task.status)}`)
     }
-  }
 
-  finishInline(outputState)
+    const result = await requestResult(baseUrl, resolvedApiKey.apiKey, task.taskId, format)
 
-  if (task.status !== 'completed') {
-    throw new Error(task.error || `任务未成功完成：${formatStatus(task.status)}`)
-  }
+    if (args.output) {
+      const outputPath = await writeOutput(args.output, result)
+      reporter.reportResultWritten(outputPath, format)
+      return
+    }
 
-  const result = await requestResult(baseUrl, resolvedApiKey.apiKey, task.taskId, format)
+    reporter.close()
+    process.stdout.write(result)
 
-  if (args.output) {
-    const outputPath = await writeOutput(args.output, result)
-    process.stderr.write(`结果已写入：${outputPath}\n`)
-    return
-  }
+    if (!result.endsWith('\n')) {
+      process.stdout.write('\n')
+    }
+  } catch (error) {
+    if (error instanceof ReportedCliError) {
+      throw error
+    }
 
-  process.stdout.write(result)
+    if (reporter.mode === 'jsonl') {
+      reporter.reportNotice(`执行失败：${error instanceof Error ? error.message : String(error)}`)
+      throw new ReportedCliError('执行失败')
+    }
 
-  if (!result.endsWith('\n')) {
-    process.stdout.write('\n')
+    throw error
   }
 }
 
@@ -848,6 +1047,10 @@ async function main() {
 }
 
 main().catch((error) => {
+  if (error instanceof ReportedCliError) {
+    process.exit(1)
+  }
+
   const message = error instanceof Error ? error.message : String(error)
   fail(`执行失败：${message}`)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casatwy/deyo",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI for submitting Deyo transcription jobs from the terminal",
   "homepage": "https://deyo.miaobi.fun/docs",
   "license": "UNLICENSED",