@makuraryu/yonde 0.3.1 → 0.4.0

package/README.md

@@ -7,15 +7,15 @@ Yonde（読んで）是一个配置驱动的 Bun CLI：把日文文本翻译成
 需要 [Bun](https://bun.sh/) 1.3 或更新版本。生成 MP3 时还需要 `ffmpeg`；只运行翻译阶段则不需要。
 
 ```bash
-bunx github:Makuraryu/Yonde init
+bunx @makuraryu/yonde@latest init
 
 # 默认配置从这个环境变量读取 DeepSeek API Key
 export YONDE_API_KEY="your-api-key"
 
-bunx github:Makuraryu/Yonde input.txt
+bunx @makuraryu/yonde@latest input.txt
 ```
 
-这会直接从公开 GitHub 仓库的默认分支安装并运行，不需要 npm 发布。版本记录可在 [GitHub Releases](https://github.com/Makuraryu/Yonde/releases) 查看。
+`bunx` 会从 npm 获取最新版并直接运行，无需全局安装。也可以使用 `bunx github:Makuraryu/Yonde` 试用 GitHub 默认分支上的未发布代码。版本记录见 [GitHub Releases](https://github.com/Makuraryu/Yonde/releases)。
 
 ## 命令
 
@@ -29,21 +29,21 @@ yonde config check [--config <配置文件>]
 
 ```bash
 # 翻译并生成音频
-bunx github:Makuraryu/Yonde input.txt
+bunx @makuraryu/yonde@latest input.txt
 
 # 只翻译，或使用已有翻译生成音频
-bunx github:Makuraryu/Yonde input.txt --stage translate
-bunx github:Makuraryu/Yonde input.txt --stage audio
+bunx @makuraryu/yonde@latest input.txt --stage translate
+bunx @makuraryu/yonde@latest input.txt --stage audio
 
 # 指定配置和输出目录
-bunx github:Makuraryu/Yonde input.txt --config ./custom.toml --output-dir ./build
+bunx @makuraryu/yonde@latest input.txt --config ./custom.toml --output-dir ./build
 
 # 检查最终合并后的配置
-bunx github:Makuraryu/Yonde config check
-bunx github:Makuraryu/Yonde config check --config ./custom.toml
+bunx @makuraryu/yonde@latest config check
+bunx @makuraryu/yonde@latest config check --config ./custom.toml
 
 # 查看完整帮助
-bunx github:Makuraryu/Yonde --help
+bunx @makuraryu/yonde@latest --help
 ```
 
 `init` 默认创建 `./yonde.toml`，且不会覆盖已有文件。
@@ -64,13 +64,11 @@ Yonde 支持以下环境变量：
 | 变量 | 用途 |
 | --- | --- |
 | `YONDE_API_KEY` | 默认翻译 API Key |
-| `DEEPSEEK_API_KEY` | API Key 兼容变量 |
 | `YONDE_API_ENDPOINT` | 覆盖翻译 API 地址 |
-| `DEEPSEEK_BASE_URL` | API 基础地址兼容变量 |
-| `YONDE_MODEL` / `DEEPSEEK_MODEL` | 覆盖模型 |
+| `YONDE_MODEL` | 覆盖模型 |
 | `YONDE_TTS_CONCURRENCY` | 覆盖 TTS 并发数 |
 
-也可以用 `translation.api.api_key_env` 指定任意 API Key 环境变量。允许在 TOML 中直接写 `api_key`，但不推荐；Yonde 会提示检查文件权限。API Key 不会写入检查点、日志或音频清单。
+也可以用 `translation.api.api_key_env` 明确指定一个 API Key 环境变量。若 TOML 中直接设置了 `translation.api.api_key`，它优先于环境变量；未设置时只读取 `api_key_env` 指定的变量（默认 `YONDE_API_KEY`）。Yonde 不会隐式读取 `DEEPSEEK_API_KEY` 或任何其他 Key 变量。Yonde 会提示检查含明文 Key 的文件权限。API Key 不会写入检查点、日志或音频清单。
 
 ## TOML 配置
 
@@ -150,6 +148,12 @@ package_asset = "uisfx/sounds/cinematic/select.mp3"
 
 翻译缓存指纹包含输入内容、语言、模型、端点、提示词版本和分句规则，但不包含 API Key。音频缓存指纹包含文本、音色、语言、语速和音调。仅调整朗读顺序时，Yonde 会复用已有语音并重新合并。
 
+翻译、语音生成和最终 MP3 合并都会显示单行进度条，包括完成比例、数量、耗时和 ETA。非交互终端按 5% 里程碑输出，避免日志刷屏。
+
+所有语音和分隔音效会统一为 24 kHz、单声道、96 kbps，最终 MP3 采用无损快速拼接，不再把数小时音频完整重编码。
+
+最终合并使用状态文件保护原子写入。若进程在 ffmpeg 已完成后、最终重命名前退出，下次运行会直接恢复成品；若在合并中途退出，只会重做最终合并，已经生成的翻译和 TTS 缓存不会丢失。
+
 ## 本地开发
 
 ```bash
@@ -161,7 +165,7 @@ bun run check
 bun run src/main.ts --help
 ```
 
-## npm 发布（可选）
+## npm 发布
 
 ```bash
 bun run check
@@ -170,7 +174,7 @@ npm pack --dry-run
 npm publish --access public
 ```
 
-Yonde 不依赖 npm 发布即可通过上面的 `github:Makuraryu/Yonde` 包标识运行。npm 发布只是提供更短的 registry 包名。
+发布后可通过 `bunx @makuraryu/yonde@latest` 直接运行；GitHub 包标识适合测试尚未发布的默认分支。
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makuraryu/yonde",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Config-driven Bun CLI for creating bilingual Japanese listening scripts and MP3 audio",
   "type": "module",
   "bin": {

package/src/audio.ts

@@ -1,16 +1,34 @@
 import { EdgeTTS } from "node-edge-tts";
-import { copyFile, lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
+import { lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AppConfig, VoiceProfile } from "./config";
 import type { TranslatedParagraph } from "./text";
 import { splitForTts } from "./text";
-import { atomicWrite, writeJson } from "./state";
+import { ProgressBar } from "./progress";
+import { atomicWrite, readJson, writeJson } from "./state";
 
 type AudioItem = { kind: string; text?: string; path: string };
 type AudioSpec = { kind: string; text: string; profile: VoiceProfile };
 type PlannedItem = { type: "audio"; spec: AudioSpec } | { type: "separator" };
+type SynthesisResult = { path: string; cached: boolean };
+type AudioManifest = {
+  version: 3;
+  mergeFingerprint: string;
+  profiles: AppConfig["audio"]["profiles"];
+  paragraphSequence: string[];
+  sentenceSequence: string[];
+  separator: AppConfig["audio"]["separator"];
+  items: AudioItem[];
+};
+type MergeState = {
+  version: 1;
+  fingerprint: string;
+  temporary: string;
+  status: "merging" | "complete";
+  expectedSeconds: number;
+};
 
 async function fileIsUsable(path: string): Promise<boolean> {
   try {
@@ -29,11 +47,11 @@ function specHash(spec: AudioSpec): string {
     .slice(0, 24);
 }
 
-async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string): Promise<string> {
+async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string): Promise<SynthesisResult> {
   const hash = specHash(spec);
   const safeId = spec.kind.replace(/[^a-zA-Z0-9_-]/g, "_");
   const output = join(cacheDir, `${safeId}-${hash}.mp3`);
-  if (await fileIsUsable(output)) return output;
+  if (await fileIsUsable(output)) return { path: output, cached: true };
 
   const temporary = `${output}.${process.pid}.${randomUUID()}.part.mp3`;
   if (!/[\p{L}\p{N}]/u.test(spec.text)) {
@@ -43,7 +61,7 @@ async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string)
     ]);
     if (await silence.exited !== 0) throw new Error(`无法为纯标点片段生成静音: ${spec.text}`);
     await rename(temporary, output);
-    return output;
+    return { path: output, cached: false };
   }
   for (let attempt = 1; attempt <= 6; attempt += 1) {
     try {
@@ -60,7 +78,7 @@ async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string)
       await tts.ttsPromise(spec.text, temporary);
       if (!(await fileIsUsable(temporary))) throw new Error("TTS 输出为空");
       await rename(temporary, output);
-      return output;
+      return { path: output, cached: false };
     } catch (error) {
       await rm(temporary, { force: true });
       if (attempt === 6) throw new Error(`${spec.kind} 生成失败（${spec.text.slice(0, 40)}）: ${error instanceof Error ? error.message : String(error)}`);
@@ -70,21 +88,18 @@ async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string)
   throw new Error("无法生成语音");
 }
 
-async function runPool<T>(jobs: Array<() => Promise<T>>, concurrency: number): Promise<T[]> {
+async function runPool<T>(jobs: Array<() => Promise<T>>, concurrency: number, onCompleted: (value: T) => void): Promise<T[]> {
   const results = new Array<T>(jobs.length);
   let next = 0;
-  let completed = 0;
   async function worker() {
     while (true) {
       const index = next++;
       if (index >= jobs.length) return;
       results[index] = await jobs[index]();
-      completed += 1;
-      process.stdout.write(`\r[TTS] ${completed}/${jobs.length}`);
+      onCompleted(results[index]);
     }
   }
   await Promise.all(Array.from({ length: Math.min(concurrency, jobs.length) }, worker));
-  if (jobs.length) process.stdout.write("\n");
   return results;
 }
 
@@ -92,24 +107,123 @@ function escapeConcatPath(path: string): string {
   return path.replace(/'/g, "'\\''");
 }
 
-async function runFfmpeg(items: AudioItem[], outputPath: string, stateDir: string, ffmpegPath: string): Promise<void> {
+export function audioMergeFingerprint(value: Omit<AudioManifest, "version" | "mergeFingerprint">): string {
+  return new Bun.CryptoHasher("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function mergeStateCanRecover(value: unknown, fingerprint: string, outputPath: string): value is MergeState {
+  if (!value || typeof value !== "object") return false;
+  const state = value as Partial<MergeState>;
+  const prefix = `${basename(outputPath)}.`;
+  return state.version === 1
+    && state.status === "complete"
+    && state.fingerprint === fingerprint
+    && typeof state.temporary === "string"
+    && dirname(state.temporary) === dirname(outputPath)
+    && basename(state.temporary).startsWith(prefix)
+    && basename(state.temporary).endsWith(".tmp.mp3");
+}
+
+async function temporaryOutputs(outputPath: string): Promise<string[]> {
+  const prefix = `${basename(outputPath)}.`;
+  return (await readdir(dirname(outputPath)))
+    .filter((entry) => entry.startsWith(prefix) && entry.endsWith(".tmp.mp3"))
+    .map((entry) => join(dirname(outputPath), entry));
+}
+
+async function estimateDurationSeconds(items: AudioItem[]): Promise<number> {
+  const sizes = new Map<string, number>();
+  let bytes = 0;
+  for (const item of items) {
+    let size = sizes.get(item.path);
+    if (size === undefined) {
+      size = (await lstat(item.path)).size;
+      sizes.set(item.path, size);
+    }
+    bytes += size;
+  }
+  return Math.max(1, bytes * 8 / 96_000);
+}
+
+async function recoverCompletedMerge(outputPath: string, stateDir: string, fingerprint: string): Promise<boolean> {
+  const statePath = join(stateDir, "audio-merge-state.json");
+  const state = await readJson<unknown>(statePath);
+  if (!mergeStateCanRecover(state, fingerprint, outputPath) || !(await fileIsUsable(state.temporary))) return false;
+  await rename(state.temporary, outputPath);
+  await rm(statePath, { force: true });
+  for (const stale of await temporaryOutputs(outputPath)) await rm(stale, { force: true });
+  const progress = new ProgressBar("恢复", 1);
+  progress.finish("已恢复完成的合并结果");
+  return true;
+}
+
+async function readFfmpegProgress(stream: ReadableStream<Uint8Array>, progress: ProgressBar, totalSeconds: number): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let pending = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    pending += decoder.decode(value, { stream: true });
+    const lines = pending.split(/\r?\n/);
+    pending = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.startsWith("out_time_us=")) continue;
+      const seconds = Number(line.slice("out_time_us=".length)) / 1_000_000;
+      if (Number.isFinite(seconds)) progress.update(Math.min(seconds, totalSeconds), `音频 ${Math.floor(seconds / 60)} 分钟`);
+    }
+  }
+}
+
+async function runFfmpeg(
+  items: AudioItem[],
+  outputPath: string,
+  stateDir: string,
+  ffmpegPath: string,
+  fingerprint: string,
+): Promise<void> {
   const listPath = join(stateDir, "concat.txt");
   const paths = items.map((item) => relative(stateDir, item.path));
   if (paths.some((path) => path.startsWith("..") || /[\r\n\0]/.test(path))) throw new Error("音频缓存路径超出状态目录或含控制字符");
   await atomicWrite(listPath, paths.map((path) => `file '${escapeConcatPath(path)}'`).join("\n") + "\n");
   const temporary = `${outputPath}.${process.pid}.${randomUUID()}.tmp.mp3`;
+  const mergeStatePath = join(stateDir, "audio-merge-state.json");
+  const expectedSeconds = await estimateDurationSeconds(items);
+  const progress = new ProgressBar("合并", expectedSeconds);
   await rm(temporary, { force: true });
+  await writeJson(mergeStatePath, {
+    version: 1,
+    fingerprint,
+    temporary,
+    status: "merging",
+    expectedSeconds,
+  } satisfies MergeState);
   const processResult = Bun.spawn([
     ffmpegPath, "-hide_banner", "-loglevel", "error", "-y", "-f", "concat", "-safe", "1", "-i", listPath,
-    "-af", "aresample=24000,aformat=sample_fmts=s16:channel_layouts=mono",
-    "-c:a", "libmp3lame", "-b:a", "96k", temporary,
-  ], { stdout: "inherit", stderr: "inherit" });
+    "-c:a", "copy", "-progress", "pipe:1", "-nostats", temporary,
+  ], { stdout: "pipe", stderr: "pipe" });
+  const progressReader = readFfmpegProgress(processResult.stdout, progress, expectedSeconds);
+  const stderrReader = new Response(processResult.stderr).text();
   const exitCode = await processResult.exited;
+  await progressReader;
+  const stderr = await stderrReader;
   if (exitCode !== 0) {
+    progress.fail(`退出码 ${exitCode}`);
     await rm(temporary, { force: true });
-    throw new Error(`ffmpeg 合并失败，退出码 ${exitCode}`);
+    await rm(mergeStatePath, { force: true });
+    const detail = stderr.trim().split("\n").at(-1);
+    throw new Error(`ffmpeg 合并失败，退出码 ${exitCode}${detail ? `: ${detail}` : ""}`);
   }
+  await writeJson(mergeStatePath, {
+    version: 1,
+    fingerprint,
+    temporary,
+    status: "complete",
+    expectedSeconds,
+  } satisfies MergeState);
+  progress.finish(`${items.length} 个片段`);
   await rename(temporary, outputPath);
+  await rm(mergeStatePath, { force: true });
 }
 
 function profileText(profile: VoiceProfile, source: string, target: string): string {
@@ -162,10 +276,6 @@ export async function buildAudio(
   for (const entry of await readdir(cacheDir)) if (entry.endsWith(".part.mp3")) await rm(join(cacheDir, entry), { force: true });
   const outputDir = dirname(outputPath);
   await mkdir(outputDir, { recursive: true });
-  const stalePrefix = `${basename(outputPath)}.`;
-  for (const entry of await readdir(outputDir)) {
-    if (entry.startsWith(stalePrefix) && entry.endsWith(".tmp.mp3")) await rm(join(outputDir, entry), { force: true });
-  }
 
   const plan = buildPlan(paragraphs, config);
   const uniqueSpecs = new Map<string, AudioSpec>();
@@ -174,13 +284,23 @@ export async function buildAudio(
 
   let separatorPath: string | undefined;
   if (plan.some((item) => item.type === "separator")) {
-    separatorPath = join(stateDir, "separator.mp3");
+    separatorPath = join(stateDir, "separator-24khz-96k-mono.mp3");
     if (!(await fileIsUsable(separatorPath))) {
       const source = resolveSeparatorAsset(config.audio.separator.packageAsset);
       if (!(await fileIsUsable(source))) throw new Error(`找不到可用的分隔音效: ${source}`);
-      const temporarySeparator = `${separatorPath}.${randomUUID()}.tmp`;
+      const temporarySeparator = `${separatorPath}.${randomUUID()}.tmp.mp3`;
       try {
-        await copyFile(source, temporarySeparator);
+        const conversion = Bun.spawn([
+          ffmpegPath, "-hide_banner", "-loglevel", "error", "-y", "-i", source,
+          "-ar", "24000", "-ac", "1", "-c:a", "libmp3lame", "-b:a", "96k", temporarySeparator,
+        ], { stdout: "ignore", stderr: "pipe" });
+        const stderrReader = new Response(conversion.stderr).text();
+        const exitCode = await conversion.exited;
+        const stderr = await stderrReader;
+        if (exitCode !== 0 || !(await fileIsUsable(temporarySeparator))) {
+          const detail = stderr.trim().split("\n").at(-1);
+          throw new Error(`分隔音效标准化失败${detail ? `: ${detail}` : ""}`);
+        }
         await rename(temporarySeparator, separatorPath);
       } catch (error) {
         await rm(temporarySeparator, { force: true });
@@ -190,21 +310,43 @@ export async function buildAudio(
   }
 
   const entries = [...uniqueSpecs.entries()];
-  console.log(`[TTS] ${entries.length} 个唯一片段，并发 ${config.audio.concurrency}（已有缓存会跳过）`);
-  const paths = await runPool(entries.map(([, spec]) => () => synthesize(spec, cacheDir, ffmpegPath)), config.audio.concurrency);
-  const generated = new Map(entries.map(([hash], index) => [hash, paths[index]]));
+  const synthesisProgress = new ProgressBar("语音", entries.length);
+  let completed = 0;
+  let cached = 0;
+  let results: SynthesisResult[];
+  try {
+    results = await runPool(
+      entries.map(([, spec]) => () => synthesize(spec, cacheDir, ffmpegPath)),
+      config.audio.concurrency,
+      (result) => {
+        completed += 1;
+        if (result.cached) cached += 1;
+        if (completed < entries.length) synthesisProgress.update(completed, `缓存 ${cached} · 新生成 ${completed - cached}`);
+      },
+    );
+    synthesisProgress.finish(`缓存 ${cached} · 新生成 ${completed - cached}`);
+  } catch (error) {
+    synthesisProgress.fail(`完成 ${completed}/${entries.length}`);
+    throw error;
+  }
+  const generated = new Map(entries.map(([hash], index) => [hash, results[index].path]));
   const items: AudioItem[] = plan.map((item) => item.type === "separator"
     ? { kind: "separator", path: separatorPath! }
     : { kind: item.spec.kind, text: item.spec.text, path: generated.get(specHash(item.spec))! });
 
-  await writeJson(join(stateDir, "audio-manifest.json"), {
-    version: 2,
+  const manifestBody = {
     profiles: config.audio.profiles,
     paragraphSequence: config.audio.paragraphSequence,
     sentenceSequence: config.audio.sentenceSequence,
     separator: config.audio.separator,
     items,
-  });
-  console.log(`[合并] ${items.length} 个音频片段`);
-  await runFfmpeg(items, outputPath, stateDir, ffmpegPath);
+  };
+  const mergeFingerprint = audioMergeFingerprint(manifestBody);
+  if (await recoverCompletedMerge(outputPath, stateDir, mergeFingerprint)) return;
+  const stale = await temporaryOutputs(outputPath);
+  if (stale.length) console.warn(`发现 ${stale.length} 个未完成的合并临时文件，将保留语音缓存并重新合并。`);
+  for (const path of stale) await rm(path, { force: true });
+  const manifest: AudioManifest = { version: 3, mergeFingerprint, ...manifestBody };
+  await writeJson(join(stateDir, "audio-manifest.json"), manifest);
+  await runFfmpeg(items, outputPath, stateDir, ffmpegPath, mergeFingerprint);
 }

package/src/config.ts

@@ -241,8 +241,7 @@ function environmentOverrides(): UnknownRecord {
   const translation: UnknownRecord = { api };
   const audio: UnknownRecord = {};
   if (process.env.YONDE_API_ENDPOINT) api.endpoint = process.env.YONDE_API_ENDPOINT;
-  else if (process.env.DEEPSEEK_BASE_URL) api.endpoint = `${process.env.DEEPSEEK_BASE_URL.replace(/\/$/, "")}/chat/completions`;
-  if (process.env.YONDE_MODEL ?? process.env.DEEPSEEK_MODEL) api.model = process.env.YONDE_MODEL ?? process.env.DEEPSEEK_MODEL;
+  if (process.env.YONDE_MODEL) api.model = process.env.YONDE_MODEL;
   if (process.env.YONDE_TTS_CONCURRENCY) audio.concurrency = Number(process.env.YONDE_TTS_CONCURRENCY);
   return { translation, audio };
 }
@@ -284,10 +283,8 @@ export async function loadConfig(explicitPath?: string, cwd = process.cwd()): Pr
 }
 
 export function resolveApiKey(config: AppConfig): string | undefined {
-  return process.env[config.translation.api.apiKeyEnv]
-    ?? process.env.YONDE_API_KEY
-    ?? process.env.DEEPSEEK_API_KEY
-    ?? config.translation.api.apiKey;
+  return config.translation.api.apiKey
+    ?? process.env[config.translation.api.apiKeyEnv];
 }
 
 export function translationFingerprint(config: AppConfig): string {

package/src/main.ts

@@ -11,7 +11,7 @@ type Stage = "translate" | "audio" | "all";
 type RunArgs = { command: "run"; input: string; stage: Stage; outputDir?: string; configPath?: string };
 type CliArgs = RunArgs | { command: "init"; path: string } | { command: "config-check"; configPath?: string } | { command: "help" } | { command: "version" };
 
-const VERSION = "0.3.1";
+const VERSION = "0.4.0";
 
 export const HELP_TEXT = `Yonde ${VERSION} — 配置驱动的双语听力材料生成器
 
@@ -37,17 +37,21 @@ export const HELP_TEXT = `Yonde ${VERSION} — 配置驱动的双语听力材料
   > ~/.config/yonde/config.toml > 内置默认值
 
 示例:
-  bunx github:Makuraryu/Yonde input.txt
-  bunx github:Makuraryu/Yonde input.txt --stage translate
-  bunx github:Makuraryu/Yonde input.txt --config ./yonde.toml
-  bunx github:Makuraryu/Yonde config check
-  bunx github:Makuraryu/Yonde init
+  bunx @makuraryu/yonde@latest input.txt
+  bunx @makuraryu/yonde@latest input.txt --stage translate
+  bunx @makuraryu/yonde@latest input.txt --config ./yonde.toml
+  bunx @makuraryu/yonde@latest config check
+  bunx @makuraryu/yonde@latest init
 
 环境变量:
   YONDE_API_KEY          默认翻译 API Key
   YONDE_API_ENDPOINT     覆盖翻译 API 地址
   YONDE_MODEL            覆盖翻译模型
-  YONDE_TTS_CONCURRENCY  覆盖 TTS 并发数`;
+  YONDE_TTS_CONCURRENCY  覆盖 TTS 并发数
+
+API Key 优先级:
+  translation.api.api_key > api_key_env 明确指定的环境变量
+  默认 api_key_env 为 YONDE_API_KEY；不会读取其他 Key 变量`;
 
 function usage(exitCode = 1): never {
   const output = exitCode === 0 ? console.log : console.error;

package/src/progress.ts

@@ -0,0 +1,102 @@
+type ProgressFormat = {
+  label: string;
+  current: number;
+  total: number;
+  elapsedMs: number;
+  detail?: string;
+  done?: boolean;
+  failed?: boolean;
+  barWidth?: number;
+  color?: boolean;
+};
+
+function duration(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return "--:--";
+  const value = Math.round(seconds);
+  const hours = Math.floor(value / 3600);
+  const minutes = Math.floor((value % 3600) / 60);
+  const remainder = value % 60;
+  return hours > 0
+    ? `${hours}:${String(minutes).padStart(2, "0")}:${String(remainder).padStart(2, "0")}`
+    : `${minutes}:${String(remainder).padStart(2, "0")}`;
+}
+
+function paint(value: string, code: number, enabled: boolean): string {
+  return enabled ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
+
+export function formatProgress(options: ProgressFormat): string {
+  const total = Math.max(0, options.total);
+  const current = Math.max(0, Math.min(options.current, total || options.current));
+  const ratio = total > 0 ? Math.min(1, current / total) : 1;
+  const width = Math.max(8, options.barWidth ?? 24);
+  const filled = Math.min(width, Math.floor(ratio * width));
+  const head = filled < width && current > 0 ? "╸" : "";
+  const bar = "━".repeat(filled) + head + "─".repeat(Math.max(0, width - filled - head.length));
+  const percent = `${Math.round(ratio * 100)}%`.padStart(4);
+  const count = total > 0 ? `${Math.round(current)}/${Math.round(total)}` : `${Math.round(current)}`;
+  const elapsed = duration(options.elapsedMs / 1000);
+  const etaSeconds = current > 0 && current < total ? (options.elapsedMs / 1000) * (total - current) / current : 0;
+  const eta = current > 0 && current < total ? ` 余 ${duration(etaSeconds)}` : "";
+  const icon = options.failed ? paint("✗", 31, Boolean(options.color)) : options.done ? paint("✓", 32, Boolean(options.color)) : paint("●", 36, Boolean(options.color));
+  const coloredBar = paint(bar, options.failed ? 31 : options.done ? 32 : 36, Boolean(options.color));
+  const detail = options.detail ? `  ${options.detail}` : "";
+  return `${icon} ${options.label.padEnd(4, "　")} ${coloredBar} ${percent}  ${count}  ${elapsed}${eta}${detail}`;
+}
+
+export class ProgressBar {
+  private current: number;
+  private readonly startedAt = Date.now();
+  private lastRenderedAt = 0;
+  private lastBucket = -1;
+
+  constructor(
+    private readonly label: string,
+    private readonly total: number,
+    initial = 0,
+    private readonly stream: NodeJS.WriteStream = process.stdout,
+  ) {
+    this.current = initial;
+    this.render(undefined, true);
+  }
+
+  update(current: number, detail?: string, force = false): void {
+    this.current = current;
+    this.render(detail, force);
+  }
+
+  finish(detail?: string): void {
+    this.current = this.total;
+    this.render(detail, true, true);
+  }
+
+  fail(detail?: string): void {
+    this.render(detail, true, false, true);
+  }
+
+  private render(detail?: string, force = false, done = false, failed = false): void {
+    const now = Date.now();
+    const ratio = this.total > 0 ? Math.min(1, this.current / this.total) : 1;
+    const bucket = Math.floor(ratio * 20);
+    const interactive = Boolean(this.stream.isTTY);
+    if (!force && interactive && now - this.lastRenderedAt < 80) return;
+    if (!force && !interactive && bucket === this.lastBucket) return;
+    this.lastRenderedAt = now;
+    this.lastBucket = bucket;
+    const terminalWidth = interactive ? this.stream.columns ?? 100 : 100;
+    const barWidth = Math.max(10, Math.min(30, terminalWidth - 66));
+    const line = formatProgress({
+      label: this.label,
+      current: this.current,
+      total: this.total,
+      elapsedMs: now - this.startedAt,
+      detail,
+      done,
+      failed,
+      barWidth,
+      color: interactive && !process.env.NO_COLOR,
+    });
+    if (interactive) this.stream.write(`\r\u001b[2K${line}${done || failed ? "\n" : ""}`);
+    else this.stream.write(`${line}\n`);
+  }
+}

package/src/translate.ts

@@ -3,6 +3,7 @@ import { resolveApiKey } from "./config";
 import type { GlossaryEntry, TranslationState } from "./state";
 import { writeJson } from "./state";
 import type { Paragraph, TranslatedParagraph } from "./text";
+import { ProgressBar } from "./progress";
 
 type ChatCompletionResponse = {
   choices?: Array<{ message?: { content?: string } }>;
@@ -145,31 +146,37 @@ async function translateOne(
 export async function translateAll(state: TranslationState, statePath: string, config: AppConfig): Promise<TranslationState> {
   const apiKey = resolveApiKey(config);
   if (!apiKey) throw new Error(`缺少 API Key；请设置环境变量 ${config.translation.api.apiKeyEnv}，或在 translation.api.api_key 中配置`);
+  const progress = new ProgressBar("翻译", state.paragraphs.length, state.translated.length);
 
-  for (let index = state.translated.length; index < state.paragraphs.length; index += 1) {
-    const paragraph = state.paragraphs[index];
-    process.stdout.write(`[翻译 ${index + 1}/${state.paragraphs.length}] ${paragraph.original.slice(0, 28)}… `);
-    let result: ModelTranslation | undefined;
-    let lastError: unknown;
-    for (let attempt = 1; attempt <= 4; attempt += 1) {
-      try {
-        result = await translateOne(paragraph, state.translated, state.glossary, apiKey, config);
-        break;
-      } catch (error) {
-        lastError = error;
-        if (attempt < 4) {
-          process.stdout.write(`重试 ${attempt}/3… `);
-          await Bun.sleep(1000 * 2 ** (attempt - 1));
+  try {
+    for (let index = state.translated.length; index < state.paragraphs.length; index += 1) {
+      const paragraph = state.paragraphs[index];
+      let result: ModelTranslation | undefined;
+      let lastError: unknown;
+      for (let attempt = 1; attempt <= 4; attempt += 1) {
+        try {
+          result = await translateOne(paragraph, state.translated, state.glossary, apiKey, config);
+          break;
+        } catch (error) {
+          lastError = error;
+          if (attempt < 4) {
+            progress.update(index, `第 ${index + 1} 段 · 重试 ${attempt}/3`, true);
+            await Bun.sleep(1000 * 2 ** (attempt - 1));
+          }
         }
       }
+      if (!result) throw lastError;
+      state.translated.push({ ...paragraph, translations: result.translations.map((item) => item.trim()) });
+      state.glossary = mergeGlossary(state.glossary, result.glossaryUpdates ?? []);
+      state.complete = state.translated.length === state.paragraphs.length;
+      state.updatedAt = new Date().toISOString();
+      await writeJson(statePath, state);
+      if (!state.complete) progress.update(state.translated.length, `术语 ${state.glossary.length}`);
     }
-    if (!result) throw lastError;
-    state.translated.push({ ...paragraph, translations: result.translations.map((item) => item.trim()) });
-    state.glossary = mergeGlossary(state.glossary, result.glossaryUpdates ?? []);
-    state.complete = state.translated.length === state.paragraphs.length;
-    state.updatedAt = new Date().toISOString();
-    await writeJson(statePath, state);
-    console.log("完成");
+    progress.finish(state.translated.length ? `术语 ${state.glossary.length}` : "无段落");
+    return state;
+  } catch (error) {
+    progress.fail(`停在 ${state.translated.length}/${state.paragraphs.length}`);
+    throw error;
   }
-  return state;
 }