@casatwy/deyo 0.1.9 → 0.2.0

package/deyo.mjs

@@ -6,12 +6,15 @@ import { createRequire } from 'node:module'
 import { basename, dirname, extname, isAbsolute, resolve } from 'node:path'
 import { homedir } from 'node:os'
 import process from 'node:process'
+import { handleSkillCommand } from './skill-manager.mjs'
 
 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 SSE_RECONNECT_DELAYS_MS = [1000, 2000, 4000]
+const SSE_RECOVERY_INTERVAL_MS = 15000
 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'])
@@ -80,6 +83,7 @@ function printUsage() {
   deyo [选项] <url|file>
   deyo [选项] --file <file>
   deyo auth <login|logout|status> [选项]
+  deyo skill <install|status> [选项]
 
 转写选项:
   --api-key <key>       可选，Deyo API key
@@ -90,6 +94,7 @@ function printUsage() {
   --language <value>    可选，转写语言，默认 ${DEFAULT_LANGUAGE}
   --format <value>      可选，text | srt | vtt | json | verbose_json
   --progress-format <v> 可选，auto | text | jsonl，默认 auto
+  --stream-transcript   可选，通过 stderr JSONL 输出稳定正文；仅支持 text 且必须搭配 --progress-format jsonl
   --base-url <url>      可选，默认 ${DEFAULT_BASE_URL}
   -h, --help            显示帮助
   -v, --version         显示 CLI 版本
@@ -99,6 +104,10 @@ auth 子命令:
   deyo auth logout
   deyo auth status
 
+Skill 管理:
+  deyo skill install --platform codex|claude|gemini|openclaw [--scope user|workspace|global]
+  deyo skill status [--platform codex|claude|gemini|openclaw] [--json]
+
 API key 读取优先级:
   1. --api-key
   2. 环境变量 DEYO_API_KEY
@@ -133,6 +142,7 @@ function parseTranscriptionArgs(argv) {
     language: '',
     format: '',
     progressFormat: 'auto',
+    streamTranscript: false,
     baseUrl: '',
     url: '',
     positional: [],
@@ -205,6 +215,11 @@ function parseTranscriptionArgs(argv) {
       continue
     }
 
+    if (current === '--stream-transcript') {
+      args.streamTranscript = true
+      continue
+    }
+
     if (current === '--base-url') {
       args.baseUrl = argv[index + 1] || ''
       index += 1
@@ -299,6 +314,20 @@ function inferFormat(outputPath, explicitFormat) {
   return 'text'
 }
 
+function validateTranscriptStreaming(args, format) {
+  if (!args.streamTranscript) {
+    return
+  }
+
+  if (format !== 'text') {
+    fail('--stream-transcript 仅支持 text 结果格式')
+  }
+
+  if (args.progressFormat !== 'jsonl') {
+    fail('--stream-transcript 必须搭配 --progress-format jsonl')
+  }
+}
+
 function isAbortError(error) {
   return error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
 }
@@ -823,6 +852,39 @@ async function requestResult(baseUrl, apiKey, taskId, format, options = {}) {
   return response.text()
 }
 
+async function requestTranscriptPreview(baseUrl, apiKey, taskId, options = {}) {
+  const response = await fetch(`${baseUrl}/api/cli/transcriptions/${encodeURIComponent(taskId)}/preview`, {
+    method: 'GET',
+    signal: options.signal,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  })
+
+  if (response.status === 204) {
+    return {
+      available: true,
+      text: null,
+    }
+  }
+
+  if (response.status === 404 || response.status === 405 || response.status === 501) {
+    return {
+      available: false,
+      text: null,
+    }
+  }
+
+  if (!response.ok) {
+    throw new HttpCliError(await readErrorMessage(response), response.status)
+  }
+
+  return {
+    available: true,
+    text: await response.text(),
+  }
+}
+
 function sleep(ms) {
   return new Promise(resolvePromise => setTimeout(resolvePromise, ms))
 }
@@ -1262,6 +1324,50 @@ function createProgressReporter(progressFormat) {
         error: errorMessage || null,
       })
     },
+    reportTranscriptDelta(input) {
+      if (resolvedMode !== 'jsonl') {
+        return
+      }
+
+      writeJsonEvent({
+        event: 'task.transcript.delta',
+        taskId: input.taskId,
+        sequence: input.sequence,
+        source: input.source,
+        startOffset: input.startOffset,
+        endOffset: input.endOffset,
+        text: input.text,
+      })
+    },
+    reportTranscriptReset(input) {
+      if (resolvedMode !== 'jsonl') {
+        return
+      }
+
+      writeJsonEvent({
+        event: 'task.transcript.reset',
+        taskId: input.taskId,
+        sequence: input.sequence,
+        source: input.source,
+        reason: input.reason,
+        text: input.text,
+        characterCount: input.characterCount,
+      })
+    },
+    reportTranscriptCompleted(input) {
+      if (resolvedMode !== 'jsonl') {
+        return
+      }
+
+      writeJsonEvent({
+        event: 'task.transcript.completed',
+        taskId: input.taskId,
+        sequence: input.sequence,
+        source: input.source,
+        characterCount: input.characterCount,
+        sha256: input.sha256,
+      })
+    },
     reportResultWritten(outputPath, format) {
       emitTextOrJson(`结果已写入：${outputPath}`, {
         event: 'task.result_written',
@@ -1306,7 +1412,114 @@ function parseSseBlock(block) {
   }
 }
 
-async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, reporter, signal) {
+function countCodePoints(value) {
+  return Array.from(String(value || '')).length
+}
+
+function longestCommonCodePointPrefix(first, second) {
+  const firstCodePoints = Array.from(String(first || ''))
+  const secondCodePoints = Array.from(String(second || ''))
+  const length = Math.min(firstCodePoints.length, secondCodePoints.length)
+  let index = 0
+
+  while (index < length && firstCodePoints[index] === secondCodePoints[index]) {
+    index += 1
+  }
+
+  return firstCodePoints.slice(0, index).join('')
+}
+
+function createTranscriptStreamState(taskId, reporter) {
+  let stableText = ''
+  let stableCharacterCount = 0
+  let previousPreviewSnapshot = null
+  let sequence = 0
+
+  function nextSequence() {
+    sequence += 1
+    return sequence
+  }
+
+  function applyStableSnapshot(snapshot, source, resetReason = 'non_prefix_snapshot') {
+    if (typeof snapshot !== 'string' || snapshot === stableText) {
+      return
+    }
+
+    if (snapshot.startsWith(stableText)) {
+      const appendedText = snapshot.slice(stableText.length)
+      const startOffset = stableCharacterCount
+
+      stableText = snapshot
+      stableCharacterCount += countCodePoints(appendedText)
+
+      if (appendedText) {
+        reporter.reportTranscriptDelta({
+          taskId,
+          sequence: nextSequence(),
+          source,
+          startOffset,
+          endOffset: stableCharacterCount,
+          text: appendedText,
+        })
+      }
+      return
+    }
+
+    stableText = snapshot
+    stableCharacterCount = countCodePoints(stableText)
+    reporter.reportTranscriptReset({
+      taskId,
+      sequence: nextSequence(),
+      source,
+      reason: resetReason,
+      text: stableText,
+      characterCount: stableCharacterCount,
+    })
+  }
+
+  return {
+    applySseSnapshot(snapshot) {
+      if (typeof snapshot === 'string') {
+        previousPreviewSnapshot = null
+      }
+      applyStableSnapshot(snapshot, 'sse')
+    },
+    applyPreviewSnapshot(snapshot) {
+      if (typeof snapshot !== 'string') {
+        return
+      }
+
+      if (previousPreviewSnapshot === null) {
+        previousPreviewSnapshot = snapshot
+        return
+      }
+
+      const stablePreviewText = longestCommonCodePointPrefix(previousPreviewSnapshot, snapshot)
+      previousPreviewSnapshot = snapshot
+
+      if (
+        stablePreviewText.length < stableText.length
+        && stableText.startsWith(stablePreviewText)
+      ) {
+        return
+      }
+
+      applyStableSnapshot(stablePreviewText, 'preview')
+    },
+    complete(authoritativeText) {
+      applyStableSnapshot(authoritativeText, 'result', 'final_result_mismatch')
+      reporter.reportTranscriptCompleted({
+        taskId,
+        sequence: nextSequence(),
+        source: 'result',
+        characterCount: stableCharacterCount,
+        sha256: createHash('sha256').update(authoritativeText, 'utf8').digest('hex'),
+      })
+    },
+  }
+}
+
+async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, reporter, signal, transcriptState = null) {
   const response = await fetch(`${baseUrl}/api/cli/transcriptions/${encodeURIComponent(taskId)}/events`, {
     method: 'GET',
     signal,
@@ -1316,12 +1529,13 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, reporter,
   })
 
   if (!response.ok || !response.body) {
-    throw new Error(await readErrorMessage(response))
+    throw new HttpCliError(await readErrorMessage(response), response.status)
   }
 
   const reader = response.body.getReader()
   const decoder = new TextDecoder()
   let buffer = ''
+  let streamDone = false
   let task = {
     ...initialTask,
   }
@@ -1365,68 +1579,117 @@ async function consumeTaskEvents(baseUrl, apiKey, taskId, initialTask, reporter,
     reporter.reportProgress(data)
   }
 
-  while (true) {
-    const { value, done } = await reader.read()
+  function processSseBlock(block) {
+    const normalizedBlock = block.replace(/\r\n?/g, '\n').trim()
 
-    if (done) {
-      break
+    if (!normalizedBlock) {
+      return false
     }
 
-    buffer += decoder.decode(value, { stream: true })
-    buffer = buffer.replace(/\r\n/g, '\n')
+    const { event, data } = parseSseBlock(normalizedBlock)
 
-    let separatorIndex = buffer.indexOf('\n\n')
+    if (event === 'job.snapshot') {
+      transcriptState?.applySseSnapshot(data?.committedText)
 
-    while (separatorIndex >= 0) {
-      const block = buffer.slice(0, separatorIndex).trim()
-      buffer = buffer.slice(separatorIndex + 2)
-      separatorIndex = buffer.indexOf('\n\n')
-
-      if (!block) {
-        continue
+      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)
       }
+      return TERMINAL_STATUSES.has(data?.status)
+    }
 
-      const { event, data } = parseSseBlock(block)
+    if (event === 'job.status_changed') {
+      applyStatus(data?.status)
+      return TERMINAL_STATUSES.has(data?.status)
+    }
 
-      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)
-        }
-        continue
-      }
+    if (event === 'job.progress') {
+      renderProgress(data)
+      return false
+    }
 
-      if (event === 'job.status_changed') {
-        applyStatus(data?.status)
-        continue
-      }
+    if (event === 'transcript.delta') {
+      transcriptState?.applySseSnapshot(data?.committedText)
+      return false
+    }
 
-      if (event === 'job.progress') {
-        renderProgress(data)
-        continue
+    if (event === 'job.completed') {
+      applyTerminal('completed', null)
+      return true
+    }
+
+    if (event === 'job.failed') {
+      applyTerminal('failed', data?.error || data?.message || '转写失败')
+      return true
+    }
+
+    if (event === 'job.cancelled') {
+      applyTerminal('cancelled', '转写任务已取消')
+      return true
+    }
+
+    return false
+  }
+
+  function drainSseBuffer(flush = false) {
+    while (true) {
+      const separator = /\r\n\r\n|\n\n|\r\r/.exec(buffer)
+
+      if (!separator || typeof separator.index !== 'number') {
+        break
       }
 
-      if (event === 'job.completed') {
-        applyTerminal('completed', null)
-        return task
+      const block = buffer.slice(0, separator.index)
+      buffer = buffer.slice(separator.index + separator[0].length)
+
+      if (processSseBlock(block)) {
+        return true
       }
+    }
 
-      if (event === 'job.failed') {
-        applyTerminal('failed', data?.error || data?.message || '转写失败')
-        return task
+    if (flush && buffer.trim()) {
+      const tail = buffer
+      buffer = ''
+      return processSseBlock(tail)
+    }
+
+    return false
+  }
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+
+      if (done) {
+        streamDone = true
+        buffer += decoder.decode()
+        if (drainSseBuffer(true)) {
+          return task
+        }
+        break
       }
 
-      if (event === 'job.cancelled') {
-        applyTerminal('cancelled', '转写任务已取消')
+      buffer += decoder.decode(value, { stream: true })
+
+      if (drainSseBuffer()) {
         return task
       }
     }
+  } finally {
+    if (!streamDone) {
+      await reader.cancel().catch(() => {})
+    }
+
+    try {
+      reader.releaseLock()
+    } catch {
+      // The stream may already have released its lock while aborting.
+    }
   }
 
-  reporter.close()
   return task
 }
 
@@ -1953,11 +2216,36 @@ async function createCliTask(baseUrl, apiKey, createPayload, reporter, runContex
   return created
 }
 
-async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporter, runContext) {
-  let currentTask = task
+function reportTaskStatusTransition(reporter, previousStatus, task) {
+  if (task.status === previousStatus) {
+    return task.status
+  }
+
+  if (TERMINAL_STATUSES.has(task.status)) {
+    reporter.reportTerminal(task.status, task.error || null)
+  } else {
+    reporter.reportStatusChanged(task.status)
+  }
+
+  return task.status
+}
+
+async function waitForTranscriptionTask(baseUrl, apiKey, initialTask, reporter, runContext, transcriptState) {
+  let currentTask = initialTask
   let lastStatus = currentTask.status
+  let lastSseError = null
+
+  for (let attempt = 0; attempt <= SSE_RECONNECT_DELAYS_MS.length; attempt += 1) {
+    if (attempt > 0) {
+      const delayMs = SSE_RECONNECT_DELAYS_MS[attempt - 1]
+      reporter.reportNotice(`事件流中断，${delayMs / 1000} 秒后重连${lastSseError ? `：${lastSseError}` : ''}`)
+      await sleep(delayMs)
+    }
+
+    if (runContext.state.interrupting) {
+      throw new ReportedCliError('已中断', 130)
+    }
 
-  if (currentTask.mode === 'transcription' && !TERMINAL_STATUSES.has(currentTask.status)) {
     try {
       currentTask = await consumeTaskEvents(
         baseUrl,
@@ -1966,17 +2254,33 @@ async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporte
         currentTask,
         reporter,
         runContext.signal,
+        transcriptState,
       )
       lastStatus = currentTask.status
+
+      if (TERMINAL_STATUSES.has(currentTask.status)) {
+        return currentTask
+      }
+
+      lastSseError = '服务端在任务结束前关闭了事件流'
     } catch (error) {
       if (runContext.state.interrupting || isAbortError(error)) {
         throw new ReportedCliError('已中断', 130)
       }
 
-      reporter.reportNotice(`事件流中断，回退到轮询状态：${error instanceof Error ? error.message : String(error)}`)
+      if (!isRetryableRequestError(error)) {
+        throw error
+      }
+
+      lastSseError = error instanceof Error ? error.message : String(error)
     }
   }
 
+  reporter.reportNotice(`事件流连续中断，回退到状态轮询${transcriptState ? '和正文预览' : ''}`)
+
+  let previewAvailable = !!transcriptState
+  let lastSseRecoveryAt = Date.now()
+
   while (!TERMINAL_STATUSES.has(currentTask.status)) {
     await sleep(POLL_INTERVAL_MS)
 
@@ -1984,26 +2288,115 @@ async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporte
       throw new ReportedCliError('已中断', 130)
     }
 
-    currentTask = await requestJson(
-      baseUrl,
-      apiKey,
-      `/api/cli/transcriptions/${encodeURIComponent(currentTask.taskId)}`,
-      {
-        signal: runContext.signal,
-        retry: true,
-      },
-    )
+    try {
+      currentTask = await requestJson(
+        baseUrl,
+        apiKey,
+        `/api/cli/transcriptions/${encodeURIComponent(currentTask.taskId)}`,
+        {
+          signal: runContext.signal,
+          retry: true,
+        },
+      )
+      lastStatus = reportTaskStatusTransition(reporter, lastStatus, currentTask)
+    } catch (error) {
+      if (runContext.state.interrupting || isAbortError(error)) {
+        throw new ReportedCliError('已中断', 130)
+      }
 
-    if (currentTask.status !== lastStatus) {
-      if (TERMINAL_STATUSES.has(currentTask.status)) {
-        reporter.reportTerminal(currentTask.status, currentTask.error || null)
-      } else {
-        reporter.reportStatusChanged(currentTask.status)
+      if (!isRetryableRequestError(error)) {
+        throw error
       }
+
+      reporter.reportNotice(`状态轮询失败，将继续重试：${error instanceof Error ? error.message : String(error)}`)
+    }
+
+    if (TERMINAL_STATUSES.has(currentTask.status)) {
+      break
+    }
+
+    if (previewAvailable && transcriptState) {
+      try {
+        const preview = await requestTranscriptPreview(baseUrl, apiKey, currentTask.taskId, {
+          signal: runContext.signal,
+        })
+
+        if (!preview.available) {
+          previewAvailable = false
+          reporter.reportNotice('当前服务端不支持 CLI 正文预览，将继续等待最终结果')
+        } else if (preview.text !== null) {
+          transcriptState.applyPreviewSnapshot(preview.text)
+        }
+      } catch (error) {
+        if (runContext.state.interrupting || isAbortError(error)) {
+          throw new ReportedCliError('已中断', 130)
+        }
+
+        if (!isRetryableRequestError(error)) {
+          throw error
+        }
+
+        reporter.reportNotice(`正文预览读取失败，将继续重试：${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+
+    if (Date.now() - lastSseRecoveryAt < SSE_RECOVERY_INTERVAL_MS) {
+      continue
+    }
+
+    lastSseRecoveryAt = Date.now()
+
+    try {
+      reporter.reportNotice('正在尝试恢复事件流')
+      currentTask = await consumeTaskEvents(
+        baseUrl,
+        apiKey,
+        currentTask.taskId,
+        currentTask,
+        reporter,
+        runContext.signal,
+        transcriptState,
+      )
       lastStatus = currentTask.status
+
+      if (TERMINAL_STATUSES.has(currentTask.status)) {
+        return currentTask
+      }
+
+      reporter.reportNotice('事件流再次提前结束，将继续轮询')
+    } catch (error) {
+      if (runContext.state.interrupting || isAbortError(error)) {
+        throw new ReportedCliError('已中断', 130)
+      }
+
+      if (!isRetryableRequestError(error)) {
+        throw error
+      }
+
+      reporter.reportNotice(`事件流恢复失败，将继续轮询：${error instanceof Error ? error.message : String(error)}`)
     }
   }
 
+  return currentTask
+}
+
+async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporter, runContext) {
+  let currentTask = task
+  const transcriptState = args.streamTranscript
+    ? createTranscriptStreamState(currentTask.taskId, reporter)
+    : null
+
+  if (currentTask.mode === 'transcription' && !TERMINAL_STATUSES.has(currentTask.status)) {
+    currentTask = await waitForTranscriptionTask(
+      baseUrl,
+      apiKey,
+      currentTask,
+      reporter,
+      runContext,
+      transcriptState,
+    )
+  }
+
   reporter.reportTerminal(currentTask.status, currentTask.error || null)
 
   if (currentTask.status !== 'completed') {
@@ -2016,10 +2409,12 @@ async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporte
 
   if (args.output) {
     const outputPath = await writeOutput(args.output, result)
+    transcriptState?.complete(result)
     reporter.reportResultWritten(outputPath, format)
     return
   }
 
+  transcriptState?.complete(result)
   reporter.close()
   process.stdout.write(result)
 
@@ -2030,6 +2425,8 @@ async function waitForTaskAndOutput(baseUrl, apiKey, task, args, format, reporte
 
 async function handleTranscription(argv) {
   const args = parseTranscriptionArgs(argv)
+  const format = inferFormat(args.output, args.format)
+  validateTranscriptStreaming(args, format)
   const reporter = createProgressReporter(args.progressFormat)
   let runContext = null
 
@@ -2055,7 +2452,6 @@ async function handleTranscription(argv) {
       fail('缺少内容链接或本地文件')
     }
 
-    const format = inferFormat(args.output, args.format)
     runContext = createRunContext(baseUrl, resolvedApiKey.apiKey, reporter)
     let createPayload
     let created
@@ -2132,10 +2528,19 @@ async function main() {
     return
   }
 
+  if (primaryCommand === 'skill') {
+    await handleSkillCommand(argv, CLI_VERSION)
+    return
+  }
+
   await handleTranscription(argv)
 }
 
 main().catch((error) => {
+  if (error?.name === 'SkillCommandReportedError') {
+    process.exit(error.exitCode || 1)
+  }
+
   if (error instanceof ReportedCliError) {
     process.exit(error.exitCode || 1)
   }