@makuraryu/yonde 0.3.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,177 @@
+# Yonde
+
+Yonde（読んで）是一个配置驱动的 Bun CLI：把日文文本翻译成逐句对照的双语听力稿，再通过 Edge TTS 与 ffmpeg 合成为可自定义朗读顺序的 MP3。
+
+## 快速开始
+
+需要 [Bun](https://bun.sh/) 1.3 或更新版本。生成 MP3 时还需要 `ffmpeg`；只运行翻译阶段则不需要。
+
+```bash
+bunx github:Makuraryu/Yonde init
+
+# 默认配置从这个环境变量读取 DeepSeek API Key
+export YONDE_API_KEY="your-api-key"
+
+bunx github:Makuraryu/Yonde input.txt
+```
+
+这会直接从公开 GitHub 仓库的默认分支安装并运行，不需要 npm 发布。版本记录可在 [GitHub Releases](https://github.com/Makuraryu/Yonde/releases) 查看。
+
+## 命令
+
+```text
+yonde <输入.txt> [选项]
+yonde init [配置文件]
+yonde config check [--config <配置文件>]
+```
+
+常用示例：
+
+```bash
+# 翻译并生成音频
+bunx github:Makuraryu/Yonde input.txt
+
+# 只翻译，或使用已有翻译生成音频
+bunx github:Makuraryu/Yonde input.txt --stage translate
+bunx github:Makuraryu/Yonde input.txt --stage audio
+
+# 指定配置和输出目录
+bunx github:Makuraryu/Yonde input.txt --config ./custom.toml --output-dir ./build
+
+# 检查最终合并后的配置
+bunx github:Makuraryu/Yonde config check
+bunx github:Makuraryu/Yonde config check --config ./custom.toml
+
+# 查看完整帮助
+bunx github:Makuraryu/Yonde --help
+```
+
+`init` 默认创建 `./yonde.toml`，且不会覆盖已有文件。
+
+## 配置发现与优先级
+
+高优先级覆盖低优先级：
+
+1. CLI 参数，例如 `--config`、`--output-dir`、`--stage`
+2. 环境变量
+3. `--config` 指定的 TOML
+4. 当前目录的 `yonde.toml`
+5. `~/.config/yonde/config.toml`
+6. 内置默认值
+
+Yonde 支持以下环境变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `YONDE_API_KEY` | 默认翻译 API Key |
+| `DEEPSEEK_API_KEY` | API Key 兼容变量 |
+| `YONDE_API_ENDPOINT` | 覆盖翻译 API 地址 |
+| `DEEPSEEK_BASE_URL` | API 基础地址兼容变量 |
+| `YONDE_MODEL` / `DEEPSEEK_MODEL` | 覆盖模型 |
+| `YONDE_TTS_CONCURRENCY` | 覆盖 TTS 并发数 |
+
+也可以用 `translation.api.api_key_env` 指定任意 API Key 环境变量。允许在 TOML 中直接写 `api_key`，但不推荐；Yonde 会提示检查文件权限。API Key 不会写入检查点、日志或音频清单。
+
+## TOML 配置
+
+运行 `yonde init` 会生成带全部默认值的模板。主要结构如下：
+
+```toml
+version = 1
+
+[translation]
+source_language = "ja"
+target_language = "zh-Hans"
+context_paragraphs = 6
+batch_size = 12
+temperature = 0.2
+
+[translation.api]
+endpoint = "https://api.deepseek.com/chat/completions"
+model = "deepseek-chat"
+api_key_env = "YONDE_API_KEY"
+timeout_ms = 120000
+
+[text]
+sentence_endings = ["。", "、", "！", "？"]
+
+[audio]
+concurrency = 8
+max_chunk_chars = 380
+paragraph_sequence = ["source_full", "sentences", "separator"]
+sentence_sequence = ["source_slow", "target_normal", "source_repeat"]
+
+[audio.profiles.source_full]
+text = "source"
+voice = "ja-JP-KeitaNeural"
+language = "ja-JP"
+rate = "+0%"
+pitch = "-5%"
+
+[audio.profiles.source_slow]
+text = "source"
+voice = "ja-JP-KeitaNeural"
+language = "ja-JP"
+rate = "-20%"
+pitch = "-5%"
+
+[audio.profiles.target_normal]
+text = "target"
+voice = "zh-CN-YunxiNeural"
+language = "zh-CN"
+rate = "+0%"
+pitch = "+0Hz"
+
+[audio.profiles.source_repeat]
+text = "source"
+voice = "ja-JP-NanamiNeural"
+language = "ja-JP"
+rate = "+0%"
+pitch = "+0Hz"
+
+[audio.separator]
+enabled = true
+package_asset = "uisfx/sounds/cinematic/select.mp3"
+```
+
+`paragraph_sequence` 可引用任意 profile，以及特殊项 `sentences` 和 `separator`。`sentence_sequence` 可重复引用同一 profile，例如 `["source_slow", "source_slow", "target_normal"]` 就会把慢速源文读两遍。profile 的 `text` 可选 `source` 或 `target`，因此翻译语言与语音可以独立配置。
+
+默认顺序是：每段源文全文 → 每句源文慢速、译文正常、源文复读 → 段落分隔音。
+
+## 输出与缓存
+
+默认输出到输入文件旁的 `output/`：
+
+- `<文件名>.listening.txt`：逐句双语听力稿
+- `<文件名>.listening.mp3`：合成音频
+- `.state/.../translation.json`：翻译检查点和动态术语表
+- `.state/.../audio-cache/`：TTS 片段缓存
+- `.state/.../audio-manifest.json`：实际音色、顺序和片段清单
+
+翻译缓存指纹包含输入内容、语言、模型、端点、提示词版本和分句规则，但不包含 API Key。音频缓存指纹包含文本、音色、语言、语速和音调。仅调整朗读顺序时，Yonde 会复用已有语音并重新合并。
+
+## 本地开发
+
+```bash
+git clone https://github.com/Makuraryu/Yonde.git
+cd Yonde
+bun install
+bun test
+bun run check
+bun run src/main.ts --help
+```
+
+## npm 发布（可选）
+
+```bash
+bun run check
+bun test
+npm pack --dry-run
+npm publish --access public
+```
+
+Yonde 不依赖 npm 发布即可通过上面的 `github:Makuraryu/Yonde` 包标识运行。npm 发布只是提供更短的 registry 包名。
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@makuraryu/yonde",
+  "version": "0.3.1",
+  "description": "Config-driven Bun CLI for creating bilingual Japanese listening scripts and MP3 audio",
+  "type": "module",
+  "bin": {
+    "yonde": "src/main.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/main.ts --target=bun --outdir=dist",
+    "check": "tsc --noEmit",
+    "test": "bun test",
+    "prepack": "bun run check && bun test"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Makuraryu/Yonde.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Makuraryu/Yonde/issues"
+  },
+  "homepage": "https://github.com/Makuraryu/Yonde#readme",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "cli",
+    "translation",
+    "tts",
+    "japanese"
+  ],
+  "dependencies": {
+    "node-edge-tts": "1.2.10",
+    "uisfx": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.2"
+  }
+}

package/src/audio.ts

@@ -0,0 +1,210 @@
+import { EdgeTTS } from "node-edge-tts";
+import { copyFile, 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";
+
+type AudioItem = { kind: string; text?: string; path: string };
+type AudioSpec = { kind: string; text: string; profile: VoiceProfile };
+type PlannedItem = { type: "audio"; spec: AudioSpec } | { type: "separator" };
+
+async function fileIsUsable(path: string): Promise<boolean> {
+  try {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size <= 512) return false;
+    const header = new Uint8Array(await Bun.file(path).slice(0, 3).arrayBuffer());
+    return (header[0] === 0x49 && header[1] === 0x44 && header[2] === 0x33)
+      || (header[0] === 0xff && (header[1] & 0xe0) === 0xe0);
+  } catch { return false; }
+}
+
+function specHash(spec: AudioSpec): string {
+  return new Bun.CryptoHasher("sha256")
+    .update(JSON.stringify({ content: spec.text, profile: spec.profile, outputFormat: "audio-24khz-96kbitrate-mono-mp3" }))
+    .digest("hex")
+    .slice(0, 24);
+}
+
+async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string): Promise<string> {
+  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;
+
+  const temporary = `${output}.${process.pid}.${randomUUID()}.part.mp3`;
+  if (!/[\p{L}\p{N}]/u.test(spec.text)) {
+    const silence = Bun.spawn([
+      ffmpegPath, "-hide_banner", "-loglevel", "error", "-y", "-f", "lavfi", "-i",
+      "anullsrc=r=24000:cl=mono", "-t", "0.7", "-c:a", "libmp3lame", "-b:a", "96k", temporary,
+    ]);
+    if (await silence.exited !== 0) throw new Error(`无法为纯标点片段生成静音: ${spec.text}`);
+    await rename(temporary, output);
+    return output;
+  }
+  for (let attempt = 1; attempt <= 6; attempt += 1) {
+    try {
+      await rm(temporary, { force: true });
+      const tts = new EdgeTTS({
+        voice: spec.profile.voice,
+        lang: spec.profile.language,
+        outputFormat: "audio-24khz-96kbitrate-mono-mp3",
+        saveSubtitles: false,
+        rate: spec.profile.rate,
+        pitch: spec.profile.pitch,
+        timeout: 60_000,
+      });
+      await tts.ttsPromise(spec.text, temporary);
+      if (!(await fileIsUsable(temporary))) throw new Error("TTS 输出为空");
+      await rename(temporary, output);
+      return output;
+    } 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)}`);
+      await Bun.sleep(Math.min(12_000, 1000 * 2 ** (attempt - 1)));
+    }
+  }
+  throw new Error("无法生成语音");
+}
+
+async function runPool<T>(jobs: Array<() => Promise<T>>, concurrency: number): 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}`);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, jobs.length) }, worker));
+  if (jobs.length) process.stdout.write("\n");
+  return results;
+}
+
+function escapeConcatPath(path: string): string {
+  return path.replace(/'/g, "'\\''");
+}
+
+async function runFfmpeg(items: AudioItem[], outputPath: string, stateDir: string, ffmpegPath: 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`;
+  await rm(temporary, { force: true });
+  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" });
+  const exitCode = await processResult.exited;
+  if (exitCode !== 0) {
+    await rm(temporary, { force: true });
+    throw new Error(`ffmpeg 合并失败，退出码 ${exitCode}`);
+  }
+  await rename(temporary, outputPath);
+}
+
+function profileText(profile: VoiceProfile, source: string, target: string): string {
+  return profile.text === "target" ? target : source;
+}
+
+function addProfile(plan: PlannedItem[], id: string, source: string, target: string, config: AppConfig): void {
+  if (!Object.hasOwn(config.audio.profiles, id)) throw new Error(`未知音频 profile: ${id}`);
+  const profile = config.audio.profiles[id];
+  const text = profileText(profile, source, target);
+  for (const chunk of splitForTts(text, config.audio.maxChunkChars, config.text.sentenceEndings)) {
+    plan.push({ type: "audio", spec: { kind: id, text: chunk, profile } });
+  }
+}
+
+export function buildPlan(paragraphs: TranslatedParagraph[], config: AppConfig): PlannedItem[] {
+  const plan: PlannedItem[] = [];
+  paragraphs.forEach((paragraph, paragraphIndex) => {
+    for (const token of config.audio.paragraphSequence) {
+      if (token === "sentences") {
+        paragraph.sentences.forEach((sentence, sentenceIndex) => {
+          for (const id of config.audio.sentenceSequence) addProfile(plan, id, sentence, paragraph.translations[sentenceIndex], config);
+        });
+      } else if (token === "separator") {
+        if (config.audio.separator.enabled && paragraphIndex < paragraphs.length - 1) plan.push({ type: "separator" });
+      } else {
+        addProfile(plan, token, paragraph.original, paragraph.translations.join(""), config);
+      }
+    }
+  });
+  return plan;
+}
+
+function resolveSeparatorAsset(specifier: string): string {
+  const url = import.meta.resolve(specifier);
+  if (!url.startsWith("file:")) throw new Error(`分隔音效不是本地文件: ${specifier}`);
+  return fileURLToPath(url);
+}
+
+export async function buildAudio(
+  paragraphs: TranslatedParagraph[],
+  outputPath: string,
+  stateDir: string,
+  config: AppConfig,
+): Promise<void> {
+  const ffmpegPath = Bun.which("ffmpeg");
+  if (!ffmpegPath) throw new Error("找不到 ffmpeg；请先安装 ffmpeg，或仅运行 --stage translate");
+  const cacheDir = join(stateDir, "audio-cache");
+  await mkdir(cacheDir, { recursive: true });
+  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>();
+  for (const item of plan) if (item.type === "audio") uniqueSpecs.set(specHash(item.spec), item.spec);
+  if (uniqueSpecs.size === 0) throw new Error("音频顺序没有产生任何可朗读片段");
+
+  let separatorPath: string | undefined;
+  if (plan.some((item) => item.type === "separator")) {
+    separatorPath = join(stateDir, "separator.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`;
+      try {
+        await copyFile(source, temporarySeparator);
+        await rename(temporarySeparator, separatorPath);
+      } catch (error) {
+        await rm(temporarySeparator, { force: true });
+        throw error;
+      }
+    }
+  }
+
+  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 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,
+    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);
+}

package/src/config.ts

@@ -0,0 +1,306 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export type VoiceProfile = {
+  text: "source" | "target";
+  voice: string;
+  language: string;
+  rate: string;
+  pitch: string;
+};
+
+export type AppConfig = {
+  version: 1;
+  translation: {
+    sourceLanguage: string;
+    targetLanguage: string;
+    contextParagraphs: number;
+    batchSize: number;
+    temperature: number;
+    api: {
+      endpoint: string;
+      model: string;
+      apiKeyEnv: string;
+      apiKey?: string;
+      timeoutMs: number;
+    };
+  };
+  text: { sentenceEndings: string[] };
+  audio: {
+    concurrency: number;
+    maxChunkChars: number;
+    paragraphSequence: string[];
+    sentenceSequence: string[];
+    profiles: Record<string, VoiceProfile>;
+    separator: { enabled: boolean; packageAsset: string };
+  };
+};
+
+export const DEFAULT_CONFIG: AppConfig = {
+  version: 1,
+  translation: {
+    sourceLanguage: "ja",
+    targetLanguage: "zh-Hans",
+    contextParagraphs: 6,
+    batchSize: 12,
+    temperature: 0.2,
+    api: {
+      endpoint: "https://api.deepseek.com/chat/completions",
+      model: "deepseek-chat",
+      apiKeyEnv: "YONDE_API_KEY",
+      timeoutMs: 120_000,
+    },
+  },
+  text: { sentenceEndings: ["。", "、", "！", "？"] },
+  audio: {
+    concurrency: 8,
+    maxChunkChars: 380,
+    paragraphSequence: ["source_full", "sentences", "separator"],
+    sentenceSequence: ["source_slow", "target_normal", "source_repeat"],
+    profiles: {
+      source_full: { text: "source", voice: "ja-JP-KeitaNeural", language: "ja-JP", rate: "+0%", pitch: "-5%" },
+      source_slow: { text: "source", voice: "ja-JP-KeitaNeural", language: "ja-JP", rate: "-20%", pitch: "-5%" },
+      target_normal: { text: "target", voice: "zh-CN-YunxiNeural", language: "zh-CN", rate: "+0%", pitch: "+0Hz" },
+      source_repeat: { text: "source", voice: "ja-JP-NanamiNeural", language: "ja-JP", rate: "+0%", pitch: "+0Hz" },
+    },
+    separator: { enabled: true, packageAsset: "uisfx/sounds/cinematic/select.mp3" },
+  },
+};
+
+export const DEFAULT_CONFIG_TOML = `version = 1
+
+[translation]
+source_language = "ja"
+target_language = "zh-Hans"
+context_paragraphs = 6
+batch_size = 12
+temperature = 0.2
+
+[translation.api]
+endpoint = "https://api.deepseek.com/chat/completions"
+model = "deepseek-chat"
+api_key_env = "YONDE_API_KEY"
+# api_key = "不推荐：优先使用上面的环境变量"
+timeout_ms = 120000
+
+[text]
+sentence_endings = ["。", "、", "！", "？"]
+
+[audio]
+concurrency = 8
+max_chunk_chars = 380
+paragraph_sequence = ["source_full", "sentences", "separator"]
+sentence_sequence = ["source_slow", "target_normal", "source_repeat"]
+
+[audio.profiles.source_full]
+text = "source"
+voice = "ja-JP-KeitaNeural"
+language = "ja-JP"
+rate = "+0%"
+pitch = "-5%"
+
+[audio.profiles.source_slow]
+text = "source"
+voice = "ja-JP-KeitaNeural"
+language = "ja-JP"
+rate = "-20%"
+pitch = "-5%"
+
+[audio.profiles.target_normal]
+text = "target"
+voice = "zh-CN-YunxiNeural"
+language = "zh-CN"
+rate = "+0%"
+pitch = "+0Hz"
+
+[audio.profiles.source_repeat]
+text = "source"
+voice = "ja-JP-NanamiNeural"
+language = "ja-JP"
+rate = "+0%"
+pitch = "+0Hz"
+
+[audio.separator]
+enabled = true
+package_asset = "uisfx/sounds/cinematic/select.mp3"
+`;
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function camelKey(key: string): string {
+  return key.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function normalizeKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(normalizeKeys);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+    const normalized = camelKey(key);
+    if (["__proto__", "prototype", "constructor"].includes(normalized)) throw new Error(`禁止的配置项: ${key}`);
+    return [normalized, normalizeKeys(child)];
+  }));
+}
+
+function merge(base: unknown, override: unknown): unknown {
+  if (!isRecord(base) || !isRecord(override)) return override;
+  const result: UnknownRecord = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    result[key] = key in result ? merge(result[key], value) : value;
+  }
+  return result;
+}
+
+function requireString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${path} 必须是非空字符串`);
+}
+
+function requireNumber(value: unknown, path: string, minimum: number, maximum: number): asserts value is number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new Error(`${path} 必须是 ${minimum} 到 ${maximum} 之间的数字`);
+  }
+}
+
+function requireStringArray(value: unknown, path: string): asserts value is string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || !item)) {
+    throw new Error(`${path} 必须是非空字符串数组`);
+  }
+}
+
+function rejectUnknown(record: UnknownRecord, allowed: string[], path: string): void {
+  const unknown = Object.keys(record).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`未知配置项: ${path}${unknown}`);
+}
+
+export function validateConfig(value: unknown): AppConfig {
+  if (!isRecord(value)) throw new Error("配置根节点必须是 TOML 表");
+  rejectUnknown(value, ["version", "translation", "text", "audio"], "");
+  if (isRecord(value.translation)) rejectUnknown(value.translation, ["sourceLanguage", "targetLanguage", "contextParagraphs", "batchSize", "temperature", "api"], "translation.");
+  if (isRecord(value.translation) && isRecord(value.translation.api)) rejectUnknown(value.translation.api, ["endpoint", "model", "apiKeyEnv", "apiKey", "timeoutMs"], "translation.api.");
+  if (isRecord(value.text)) rejectUnknown(value.text, ["sentenceEndings"], "text.");
+  if (isRecord(value.audio)) rejectUnknown(value.audio, ["concurrency", "maxChunkChars", "paragraphSequence", "sentenceSequence", "profiles", "separator"], "audio.");
+  if (isRecord(value.audio) && isRecord(value.audio.separator)) rejectUnknown(value.audio.separator, ["enabled", "packageAsset"], "audio.separator.");
+  if (isRecord(value.audio) && isRecord(value.audio.profiles)) {
+    for (const [id, profile] of Object.entries(value.audio.profiles)) {
+      if (isRecord(profile)) rejectUnknown(profile, ["text", "voice", "language", "rate", "pitch"], `audio.profiles.${id}.`);
+    }
+  }
+  const config = value as unknown as AppConfig;
+  if (config.version !== 1) throw new Error("仅支持 version = 1");
+  if (!config.translation || !config.translation.api) throw new Error("缺少 [translation] 或 [translation.api]");
+  requireString(config.translation.sourceLanguage, "translation.source_language");
+  requireString(config.translation.targetLanguage, "translation.target_language");
+  requireNumber(config.translation.contextParagraphs, "translation.context_paragraphs", 0, 100);
+  requireNumber(config.translation.batchSize, "translation.batch_size", 1, 100);
+  requireNumber(config.translation.temperature, "translation.temperature", 0, 2);
+  requireString(config.translation.api.endpoint, "translation.api.endpoint");
+  let endpoint: URL;
+  try { endpoint = new URL(config.translation.api.endpoint); } catch { throw new Error("translation.api.endpoint 必须是有效 URL"); }
+  const localHttp = endpoint.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname);
+  if (endpoint.protocol !== "https:" && !localHttp) throw new Error("translation.api.endpoint 必须使用 HTTPS（本机 localhost 可使用 HTTP）");
+  if (endpoint.username || endpoint.password) throw new Error("translation.api.endpoint 不得包含用户名或密码");
+  requireString(config.translation.api.model, "translation.api.model");
+  requireString(config.translation.api.apiKeyEnv, "translation.api.api_key_env");
+  if (config.translation.api.apiKey !== undefined) requireString(config.translation.api.apiKey, "translation.api.api_key");
+  requireNumber(config.translation.api.timeoutMs, "translation.api.timeout_ms", 1000, 600_000);
+  requireStringArray(config.text?.sentenceEndings, "text.sentence_endings");
+  if (config.text.sentenceEndings.some((ending) => [...ending].length !== 1)) throw new Error("text.sentence_endings 中每项必须是单个字符");
+  requireNumber(config.audio?.concurrency, "audio.concurrency", 1, 64);
+  requireNumber(config.audio?.maxChunkChars, "audio.max_chunk_chars", 20, 5000);
+  requireStringArray(config.audio?.paragraphSequence, "audio.paragraph_sequence");
+  requireStringArray(config.audio?.sentenceSequence, "audio.sentence_sequence");
+  if (!isRecord(config.audio.profiles) || Object.keys(config.audio.profiles).length === 0) throw new Error("audio.profiles 至少需要一个 profile");
+  for (const [id, profile] of Object.entries(config.audio.profiles)) {
+    if (!isRecord(profile) || !["source", "target"].includes(String(profile.text))) throw new Error(`audio.profiles.${id}.text 必须是 source 或 target`);
+    requireString(profile.voice, `audio.profiles.${id}.voice`);
+    requireString(profile.language, `audio.profiles.${id}.language`);
+    requireString(profile.rate, `audio.profiles.${id}.rate`);
+    requireString(profile.pitch, `audio.profiles.${id}.pitch`);
+  }
+  for (const token of config.audio.paragraphSequence) {
+    if (token !== "sentences" && token !== "separator" && !Object.hasOwn(config.audio.profiles, token)) throw new Error(`audio.paragraph_sequence 引用了未知项: ${token}`);
+  }
+  if (config.audio.paragraphSequence.every((token) => token === "separator")) throw new Error("audio.paragraph_sequence 至少需要一个 profile 或 sentences");
+  for (const token of config.audio.sentenceSequence) {
+    if (!Object.hasOwn(config.audio.profiles, token)) throw new Error(`audio.sentence_sequence 引用了未知 profile: ${token}`);
+  }
+  if (!config.audio.separator || typeof config.audio.separator.enabled !== "boolean") throw new Error("audio.separator.enabled 必须是布尔值");
+  requireString(config.audio.separator.packageAsset, "audio.separator.package_asset");
+  if (!/^uisfx\/sounds\/[a-zA-Z0-9_/-]+\.mp3$/.test(config.audio.separator.packageAsset) || config.audio.separator.packageAsset.includes("..")) {
+    throw new Error("audio.separator.package_asset 只允许 uisfx/sounds/ 下的 MP3 资源");
+  }
+  return config;
+}
+
+function environmentOverrides(): UnknownRecord {
+  const api: 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_TTS_CONCURRENCY) audio.concurrency = Number(process.env.YONDE_TTS_CONCURRENCY);
+  return { translation, audio };
+}
+
+async function existing(path: string): Promise<boolean> {
+  return Bun.file(path).exists();
+}
+
+export async function loadConfig(explicitPath?: string, cwd = process.cwd()): Promise<{ config: AppConfig; path?: string; warnings: string[] }> {
+  const userPath = join(homedir(), ".config", "yonde", "config.toml");
+  const projectPath = join(cwd, "yonde.toml");
+  let combined: unknown = DEFAULT_CONFIG;
+  let loadedPath: string | undefined;
+
+  const candidates = [userPath, projectPath];
+  if (explicitPath) candidates.push(resolve(cwd, explicitPath));
+  for (const candidate of [...new Set(candidates)]) {
+    if (!(await existing(candidate))) {
+      if (explicitPath && candidate === resolve(cwd, explicitPath)) throw new Error(`找不到配置文件: ${candidate}`);
+      continue;
+    }
+    const parsed = normalizeKeys(Bun.TOML.parse(await Bun.file(candidate).text()));
+    combined = merge(combined, parsed);
+    loadedPath = candidate;
+  }
+  combined = merge(combined, environmentOverrides());
+  const config = validateConfig(combined);
+  const warnings: string[] = [];
+  if (config.translation.api.apiKey && loadedPath) {
+    try {
+      const mode = (await stat(loadedPath)).mode & 0o777;
+      if ((mode & 0o077) !== 0) warnings.push(`配置内含 api_key，但 ${loadedPath} 权限为 ${mode.toString(8)}；建议 chmod 600`);
+      else warnings.push("配置内含明文 api_key；建议改用 api_key_env 指定的环境变量");
+    } catch {
+      warnings.push("配置内含明文 api_key；建议改用环境变量");
+    }
+  }
+  return { config, path: loadedPath, warnings };
+}
+
+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;
+}
+
+export function translationFingerprint(config: AppConfig): string {
+  const safe = {
+    sourceLanguage: config.translation.sourceLanguage,
+    targetLanguage: config.translation.targetLanguage,
+    contextParagraphs: config.translation.contextParagraphs,
+    batchSize: config.translation.batchSize,
+    temperature: config.translation.temperature,
+    endpoint: config.translation.api.endpoint,
+    model: config.translation.api.model,
+    sentenceEndings: config.text.sentenceEndings,
+    promptVersion: 2,
+  };
+  return new Bun.CryptoHasher("sha256").update(JSON.stringify(safe)).digest("hex");
+}

package/src/main.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env bun
+import { mkdir, open } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { buildAudio } from "./audio";
+import { DEFAULT_CONFIG_TOML, loadConfig, translationFingerprint } from "./config";
+import { atomicWrite, readJson, writeJson, type TranslationState } from "./state";
+import { parseParagraphs, renderListeningText } from "./text";
+import { translateAll } from "./translate";
+
+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";
+
+export const HELP_TEXT = `Yonde ${VERSION} — 配置驱动的双语听力材料生成器
+
+用法:
+  yonde <输入.txt> [选项]
+  yonde init [配置文件]
+  yonde config check [--config <配置文件>]
+
+命令:
+  <输入.txt>       翻译文本并生成双语听力稿与 MP3
+  init             创建配置模板（默认: ./yonde.toml，不覆盖已有文件）
+  config check     发现、合并并校验配置，但不生成内容
+
+选项:
+  --stage <阶段>       执行阶段: translate、audio 或 all（默认: all）
+  --config <文件>      使用指定 TOML 配置；优先于项目和用户配置
+  --output-dir <目录>  输出目录（默认: 输入文件旁的 output/）
+  -h, --help           显示帮助
+  -v, --version        显示版本
+
+配置优先级（高 → 低）:
+  CLI 选项 > 环境变量 > --config 文件 > ./yonde.toml
+  > ~/.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
+
+环境变量:
+  YONDE_API_KEY          默认翻译 API Key
+  YONDE_API_ENDPOINT     覆盖翻译 API 地址
+  YONDE_MODEL            覆盖翻译模型
+  YONDE_TTS_CONCURRENCY  覆盖 TTS 并发数`;
+
+function usage(exitCode = 1): never {
+  const output = exitCode === 0 ? console.log : console.error;
+  output(HELP_TEXT);
+  process.exit(exitCode);
+}
+
+function optionValue(args: string[], index: number): string {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) usage();
+  return value;
+}
+
+export function parseArgs(args: string[]): CliArgs {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) return { command: "help" };
+  if (args.includes("--version") || args.includes("-v")) return { command: "version" };
+  if (args[0] === "init") {
+    if (args.length > 2 || args[1]?.startsWith("--")) usage();
+    return { command: "init", path: args[1] ?? "yonde.toml" };
+  }
+  if (args[0] === "config") {
+    if (args[1] !== "check") usage();
+    let configPath: string | undefined;
+    for (let index = 2; index < args.length; index += 1) {
+      if (args[index] === "--config") configPath = optionValue(args, index++);
+      else usage();
+    }
+    return { command: "config-check", configPath };
+  }
+
+  let input: string | undefined;
+  let stage: Stage = "all";
+  let outputDir: string | undefined;
+  let configPath: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--stage") stage = optionValue(args, index++) as Stage;
+    else if (arg === "--output-dir") outputDir = optionValue(args, index++);
+    else if (arg === "--config") configPath = optionValue(args, index++);
+    else if (!arg.startsWith("--") && !input) input = arg;
+    else usage();
+  }
+  if (!input || !["translate", "audio", "all"].includes(stage)) usage();
+  return { command: "run", input, stage, outputDir, configPath };
+}
+
+async function initialize(path: string): Promise<void> {
+  const output = resolve(path);
+  await mkdir(dirname(output), { recursive: true });
+  let handle;
+  try {
+    handle = await open(output, "wx", 0o600);
+    await handle.writeFile(DEFAULT_CONFIG_TOML, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`不会覆盖已有文件: ${output}`);
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+  console.log(`已创建配置: ${output}`);
+}
+
+async function checkConfig(configPath?: string): Promise<void> {
+  const loaded = await loadConfig(configPath);
+  for (const warning of loaded.warnings) console.warn(`警告: ${warning}`);
+  console.log(`配置有效: ${loaded.path ?? "内置默认配置"}`);
+  console.log(`翻译: ${loaded.config.translation.sourceLanguage} → ${loaded.config.translation.targetLanguage}`);
+  console.log(`API: ${loaded.config.translation.api.endpoint} (${loaded.config.translation.api.model})`);
+  console.log(`段落顺序: ${loaded.config.audio.paragraphSequence.join(" → ")}`);
+  console.log(`逐句顺序: ${loaded.config.audio.sentenceSequence.join(" → ")}`);
+}
+
+function stateIsValid(state: unknown, paragraphs: ReturnType<typeof parseParagraphs>, inputHash: string, configHash: string): state is TranslationState {
+  if (!state || typeof state !== "object") return false;
+  const candidate = state as Partial<TranslationState>;
+  if (candidate.version !== 2 || candidate.inputHash !== inputHash || candidate.configHash !== configHash) return false;
+  if (!Array.isArray(candidate.paragraphs) || JSON.stringify(candidate.paragraphs) !== JSON.stringify(paragraphs)) return false;
+  if (!Array.isArray(candidate.translated) || candidate.translated.length > paragraphs.length) return false;
+  for (let index = 0; index < candidate.translated.length; index += 1) {
+    const item = candidate.translated[index];
+    if (!item || item.index !== paragraphs[index].index || item.original !== paragraphs[index].original) return false;
+    if (JSON.stringify(item.sentences) !== JSON.stringify(paragraphs[index].sentences)) return false;
+    if (!Array.isArray(item.translations) || item.translations.length !== item.sentences.length || item.translations.some((text) => typeof text !== "string")) return false;
+  }
+  if (!Array.isArray(candidate.glossary) || candidate.glossary.some((entry) => !entry || typeof entry.source !== "string" || typeof entry.target !== "string")) return false;
+  if (typeof candidate.complete !== "boolean" || candidate.complete !== (candidate.translated.length === paragraphs.length)) return false;
+  return typeof candidate.updatedAt === "string";
+}
+
+async function run(args: RunArgs): Promise<void> {
+  const loaded = await loadConfig(args.configPath);
+  for (const warning of loaded.warnings) console.warn(`警告: ${warning}`);
+  const { config } = loaded;
+  const inputPath = resolve(args.input);
+  const inputFile = Bun.file(inputPath);
+  if (!(await inputFile.exists())) throw new Error(`找不到输入文件: ${inputPath}`);
+  const inputText = await inputFile.text();
+  const inputHash = new Bun.CryptoHasher("sha256").update(inputText).digest("hex");
+  const configHash = translationFingerprint(config);
+  const stem = basename(inputPath).replace(/\.txt$/i, "");
+  const outputDir = resolve(args.outputDir ?? join(dirname(inputPath), "output"));
+  const stateDir = join(outputDir, ".state", `${stem}-${inputHash.slice(0, 10)}-${configHash.slice(0, 10)}`);
+  const statePath = join(stateDir, "translation.json");
+  const textOutput = join(outputDir, `${stem}.listening.txt`);
+  const audioOutput = join(outputDir, `${stem}.listening.mp3`);
+  await mkdir(stateDir, { recursive: true });
+
+  const parsedParagraphs = parseParagraphs(inputText, config.text.sentenceEndings);
+  const savedState = await readJson<unknown>(statePath);
+  let state: TranslationState;
+  if (!savedState) {
+    state = {
+      version: 2,
+      inputPath,
+      inputHash,
+      configHash,
+      paragraphs: parsedParagraphs,
+      translated: [],
+      glossary: [],
+      complete: false,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJson(statePath, state);
+  } else if (!stateIsValid(savedState, parsedParagraphs, inputHash, configHash)) {
+    throw new Error(`检查点格式无效，或与当前输入/配置不匹配: ${statePath}`);
+  } else {
+    state = savedState;
+  }
+  console.log(`输入: ${inputPath}`);
+  console.log(`配置: ${loaded.path ?? "内置默认配置"}`);
+  console.log(`语言: ${config.translation.sourceLanguage} → ${config.translation.targetLanguage}`);
+  console.log(`段落: ${state.paragraphs.length}，已翻译: ${state.translated.length}`);
+  console.log(`检查点: ${statePath}`);
+
+  if (args.stage === "translate" || args.stage === "all") {
+    state = await translateAll(state, statePath, config);
+    await atomicWrite(textOutput, `${renderListeningText(state.translated, config.audio.sentenceSequence, config.audio.profiles)}\n`);
+    console.log(`听力文本: ${textOutput}`);
+  }
+
+  if (args.stage === "audio" || args.stage === "all") {
+    if (!state.complete) throw new Error("翻译尚未完成；请先运行 --stage translate（会从检查点续跑）");
+    if (!(await Bun.file(textOutput).exists())) {
+      await atomicWrite(textOutput, `${renderListeningText(state.translated, config.audio.sentenceSequence, config.audio.profiles)}\n`);
+    }
+    await buildAudio(state.translated, audioOutput, stateDir, config);
+    console.log(`MP3: ${audioOutput}`);
+  }
+  console.log("完成。");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "help") usage(0);
+  if (args.command === "version") return console.log(VERSION);
+  if (args.command === "init") return initialize(args.path);
+  if (args.command === "config-check") return checkConfig(args.configPath);
+  return run(args);
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(`失败: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  });
+}

package/src/state.ts

@@ -0,0 +1,49 @@
+import { open, mkdir, rename, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import type { Paragraph, TranslatedParagraph } from "./text";
+
+export type GlossaryEntry = { source: string; target: string };
+
+export type TranslationState = {
+  version: 2;
+  inputPath: string;
+  inputHash: string;
+  configHash: string;
+  paragraphs: Paragraph[];
+  translated: TranslatedParagraph[];
+  glossary: GlossaryEntry[];
+  complete: boolean;
+  updatedAt: string;
+};
+
+export async function readJson<T>(path: string): Promise<T | null> {
+  try {
+    return (await Bun.file(path).json()) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function atomicWrite(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/src/text.ts

@@ -0,0 +1,76 @@
+import type { VoiceProfile } from "./config";
+
+export type Paragraph = {
+  index: number;
+  original: string;
+  sentences: string[];
+};
+
+export type TranslatedParagraph = Paragraph & {
+  translations: string[];
+};
+
+const DEFAULT_ENDINGS = ["。", "、", "！", "？"];
+
+function escapeCharacterClass(value: string): string {
+  return value.replace(/[\\\]\-^]/g, "\\$&");
+}
+
+export function splitSentences(paragraph: string, endings = DEFAULT_ENDINGS): string[] {
+  const normalized = paragraph.replace(/\r\n?/g, "\n");
+  const punctuation = endings.map(escapeCharacterClass).join("");
+  const pattern = new RegExp(`[^${punctuation}\\n]+[${punctuation}]+[」』）】〉》”’"]*|[^${punctuation}\\n]+(?=\\n|$)`, "gu");
+  const matches = normalized.match(pattern);
+  return (matches ?? [normalized]).map((part) => part.trim()).filter(Boolean);
+}
+
+export function parseParagraphs(text: string, endings = DEFAULT_ENDINGS): Paragraph[] {
+  return text
+    .replace(/\r\n?/g, "\n")
+    .trim()
+    .split(/\n\s*\n+/)
+    .map((original) => original.trim())
+    .filter(Boolean)
+    .map((original, index) => ({ index, original, sentences: splitSentences(original, endings) }));
+}
+
+export function renderListeningText(
+  paragraphs: TranslatedParagraph[],
+  sentenceSequence = ["source", "target", "source"],
+  profiles?: Record<string, VoiceProfile>,
+): string {
+  const sequence = profiles
+    ? sentenceSequence.map((id) => profiles[id]?.text).filter((value): value is "source" | "target" => Boolean(value))
+    : sentenceSequence;
+  return paragraphs
+    .map((paragraph) => {
+      const lines = ["[段落全文]", paragraph.original, "[逐句]"];
+      paragraph.sentences.forEach((sentence, index) => {
+        for (const text of sequence) lines.push(`-[${text === "target" ? paragraph.translations[index] : sentence}]`);
+      });
+      lines.push("[/逐句]");
+      return lines.join("\n");
+    })
+    .join("\n\n");
+}
+
+export function splitForTts(text: string, maxChars = 380, endings = DEFAULT_ENDINGS): string[] {
+  if (text.length <= maxChars) return [text];
+  const sentences = splitSentences(text, endings);
+  const chunks: string[] = [];
+  let current = "";
+  for (const sentence of sentences) {
+    if (sentence.length > maxChars) {
+      if (current) chunks.push(current);
+      for (let start = 0; start < sentence.length; start += maxChars) chunks.push(sentence.slice(start, start + maxChars));
+      current = "";
+    } else if (current && current.length + sentence.length > maxChars) {
+      chunks.push(current);
+      current = sentence;
+    } else {
+      current += sentence;
+    }
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}

package/src/translate.ts

@@ -0,0 +1,175 @@
+import type { AppConfig } from "./config";
+import { resolveApiKey } from "./config";
+import type { GlossaryEntry, TranslationState } from "./state";
+import { writeJson } from "./state";
+import type { Paragraph, TranslatedParagraph } from "./text";
+
+type ChatCompletionResponse = {
+  choices?: Array<{ message?: { content?: string } }>;
+  error?: { message?: string };
+};
+
+type ModelTranslation = {
+  translations: string[];
+  glossaryUpdates?: GlossaryEntry[];
+};
+
+function systemPrompt(config: AppConfig): string {
+  return `你是文学翻译者。任务是把 ${config.translation.sourceLanguage} 文学片段翻译成自然、准确、适合听力学习的 ${config.translation.targetLanguage}。
+必须保持叙述人称、人物称谓、专有名词和文体与已有上下文一致。不要解释，不要合并或拆分输入片段。
+只输出合法 JSON：{"translations":["逐项译文"],"glossaryUpdates":[{"source":"源语言词","target":"固定目标语言译法"}]}。
+translations 必须与输入 sentences 数量和顺序完全相同。glossaryUpdates 只收录值得跨段保持一致的人名、称谓、专名或反复出现的关键词。`;
+}
+
+function mergeGlossary(current: GlossaryEntry[], updates: GlossaryEntry[]): GlossaryEntry[] {
+  const merged = new Map(current.map((entry) => [entry.source, entry.target]));
+  for (const entry of updates) {
+    if (entry?.source?.trim() && entry?.target?.trim()) merged.set(entry.source.trim(), entry.target.trim());
+  }
+  return [...merged].map(([source, target]) => ({ source, target })).slice(-120);
+}
+
+function parseModelJson(content: string): ModelTranslation {
+  const cleaned = content.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start < 0 || end < start) throw new Error("模型响应中没有 JSON 对象");
+  return JSON.parse(cleaned.slice(start, end + 1)) as ModelTranslation;
+}
+
+async function translateBatch(
+  paragraph: Paragraph,
+  sentenceOffset: number,
+  sentences: string[],
+  earlierInParagraph: Array<{ text: string; translation: string }>,
+  translated: TranslatedParagraph[],
+  glossary: GlossaryEntry[],
+  apiKey: string,
+  config: AppConfig,
+): Promise<ModelTranslation> {
+  const context = translated.slice(-config.translation.contextParagraphs).map((item) => ({
+    original: item.original,
+    translations: item.translations,
+  }));
+  const payload = {
+    model: config.translation.api.model,
+    temperature: config.translation.temperature,
+    response_format: { type: "json_object" },
+    messages: [
+      { role: "system", content: systemPrompt(config) },
+      {
+        role: "user",
+        content: JSON.stringify({
+          sourceLanguage: config.translation.sourceLanguage,
+          targetLanguage: config.translation.targetLanguage,
+          rollingBilingualContext: context,
+          establishedGlossary: glossary,
+          paragraph: paragraph.original,
+          earlierInThisParagraph: earlierInParagraph,
+          sentences: sentences.map((text, index) => ({ index: sentenceOffset + index, text })),
+        }),
+      },
+    ],
+  };
+
+  const response = await fetch(config.translation.api.endpoint, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(config.translation.api.timeoutMs),
+  });
+  const raw = await response.text();
+  let body: ChatCompletionResponse;
+  try { body = JSON.parse(raw) as ChatCompletionResponse; } catch { throw new Error(`翻译 API HTTP ${response.status} 返回了非 JSON 响应`); }
+  if (!response.ok) throw new Error(`翻译 API HTTP ${response.status}: ${body.error?.message ?? response.statusText}`);
+  const content = body.choices?.[0]?.message?.content;
+  if (!content) throw new Error("翻译 API 返回了空响应");
+  const parsed = parseModelJson(content);
+  if (!Array.isArray(parsed.translations) || parsed.translations.length !== sentences.length) {
+    throw new Error(`译文数量不符：期望 ${sentences.length}，得到 ${parsed.translations?.length ?? 0}`);
+  }
+  if (parsed.translations.some((item) => typeof item !== "string" || !item.trim())) throw new Error("译文包含空项");
+  return parsed;
+}
+
+async function translateOne(
+  paragraph: Paragraph,
+  translated: TranslatedParagraph[],
+  glossary: GlossaryEntry[],
+  apiKey: string,
+  config: AppConfig,
+): Promise<ModelTranslation> {
+  const translations: string[] = [];
+  const glossaryUpdates: GlossaryEntry[] = [];
+
+  async function alignedBatch(offset: number, sentences: string[]): Promise<ModelTranslation> {
+    let result: ModelTranslation | undefined;
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        result = await translateBatch(
+          paragraph,
+          offset,
+          sentences,
+          paragraph.sentences.slice(0, offset).map((text, index) => ({ text, translation: translations[index] })),
+          translated,
+          glossary,
+          apiKey,
+          config,
+        );
+        break;
+      } catch (error) {
+        lastError = error;
+        if (attempt < 2) await Bun.sleep(750);
+      }
+    }
+    if (result) return result;
+    if (sentences.length === 1) throw lastError;
+
+    const middle = Math.ceil(sentences.length / 2);
+    const left = await alignedBatch(offset, sentences.slice(0, middle));
+    translations.push(...left.translations);
+    glossaryUpdates.push(...(left.glossaryUpdates ?? []));
+    return alignedBatch(offset + middle, sentences.slice(middle));
+  }
+
+  const batchSize = config.translation.batchSize;
+  for (let offset = 0; offset < paragraph.sentences.length; offset += batchSize) {
+    const result = await alignedBatch(offset, paragraph.sentences.slice(offset, offset + batchSize));
+    translations.push(...result.translations);
+    glossaryUpdates.push(...(result.glossaryUpdates ?? []));
+  }
+  return { translations, glossaryUpdates };
+}
+
+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 中配置`);
+
+  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));
+        }
+      }
+    }
+    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("完成");
+  }
+  return state;
+}