第10章：批量处理与命令行

产品官网：https://shandianweihu.com/

10.1 本章概述

前面九个章节详细介绍了同文（Tongwen）Studio 桌面工作台和 AutoCAD 插件环境下的各项功能——从图纸文字提取、术语库管理、翻译编辑、质量检查到回写图纸。这些功能在交互式图形界面中运行，面向的是”逐张图纸、逐条翻译、精细打磨”的工作模式。

但在实际工程中，您面对的往往不是一两张图纸，而是几十张、上百张甚至数百张。一栋商业综合体的全套施工图可能超过 200 张，覆盖建筑、结构、暖通、给排水、电气五大专业。如果每一张图都打开 Studio 工作台、建立翻译会话、等待机翻完成、逐条审校、执行回写——即便是最熟练的操作人员，也可能需要数天甚至数周的时间。

批量处理正是为解决这一规模问题而设计的。它让您无需一张张手动操作，而是将整套翻译流程——文字提取、机器翻译、质量检查、报告导出、译文回写——串联为一个全自动化的管道（Pipeline），按下回车键后即可等待最终结果输出。

本章将全面介绍同文的批量处理能力，覆盖三个主要维度：

1. Batch CLI（命令行批量处理）：通过命令行工具对一批 DWG 文件执行自动化翻译全流程，适合 IT 管理员、项目经理和需要集成脚本的高级用户。
2. Review CLI（命令行审查报告）：通过命令行生成独立的 HTML 审查报告，适合批量审查场景下的质量可视化和甲方交付。
3. Web API 服务：通过 HTTP 接口远程注册和管理批量处理任务，适合团队协作和系统集成场景。

此外，本章还将介绍在 AutoCAD 内部使用的批量测试命令，以及大量图纸批处理的最佳实践和常见问题的排查方法。

本章阅读建议：如果您只需要了解”如何一次性翻译 50 张图纸”，建议从 10.2 节（批量处理概述）开始，然后重点阅读 10.3 节（Batch CLI 使用指南）和 10.4 节（批量处理工作流）。如果您想要集成到自动化脚本中，请仔细阅读全部命令行参数详解。如果您关心审查报告的生成，可以直接跳至 10.6 节（Review CLI 使用指南）。

10.2 批量处理概述

10.2.1 什么场景需要批量处理

并非所有翻译任务都需要批量处理。下表列出了不同场景下最合适的工作模式：

选择是否使用批量处理的核心判断标准是：当逐张手动操作的时间成本超过了配置批处理参数的成本，就应该使用批处理。

10.2.2 批量处理的能力范围

同文的批量处理不是简单的”多张图一起翻”——它是一条完整的自动化管道（Pipeline），包含以下环节：

输入目录（DWG 文件）
    │
    ▼
[1] 文字提取 —— 自动扫描每张 DWG 的全部文字对象，提取原文及属性信息
    │
    ▼
[2] 翻译引擎调用 —— 调用配置好的翻译引擎（术语库 + TM + LLM）生成译文
    │
    ▼
[3] QA 质量检查 —— 对每条翻译执行占位符验证、术语验证和长度溢出验证
    │
    ▼
[4] 报告导出 —— 生成 JSON/CSV 格式的 QA 报告，记录每张图的翻译质量
    │
    ▼
[5] 译文回写 —— 根据配置的回写策略，将翻译结果写入新的 DWG 文件
    │
    ▼
输出目录（翻译后 DWG + QA 报告 + 日志）

每个环节自动串联，中间无需人工干预。处理完成后，您可以在输出目录中找到翻译好的 DWG 文件和完整的质量报告。

10.2.3 批量处理的优势

与传统的一张张手动操作相比，批量处理带来以下实际好处：

效率提升：这是最直观的优势。假设每张图纸在 Studio 中操作需要 15 分钟（打开会话、等待机翻、大致浏览确认、执行回写），100 张图就需要 25 小时（超过 3 个工作日）。而 Batch CLI 在配置好参数后，100 张图通常在 1~3 小时内即可全部完成（具体时间取决于图纸复杂度和机器翻译引擎的响应速度）。

一致性强：手动操作容易因疲劳或疏忽导致配置不一致——比如第 37 张图忘记选择”创建新图层”回写策略，第 58 张图用了另一套术语库。批量处理使用同一套配置处理全部图纸，确保策略、术语、质量标准完全统一。

可追溯：批处理自动生成每张图的处理日志和 QA 报告，完整记录翻译过程中的所有发现。如果甲方对某张图的翻译质量提出质疑，您可以快速定位到那张图的 QA 报告，查看当时的风险等级和具体问题。

可重复：批处理命令和配置文件可以保存下来，日后再跑一遍完全相同的流程。如果术语库更新了、翻译引擎升级了，或者甲方提出新的要求，您只需要修改配置后重新执行命令即可——不需要重新手动操作每一张图。

无人值守：批处理命令提交后即可离开，数小时后回来查看结果。这对于夜间执行、周末执行或服务器上执行特别实用。

10.2.4 批量处理的局限性

在享受批量处理便利的同时，也需要了解其适用边界：

不适合需要精细人工审校的场景：批量处理是全自动流水线，不包含人工逐条确认的环节。如果您的项目要求对每一句译文进行人工审核，批量处理产生的翻译结果仍然需要导入 Studio 工作台进行人工审校。批量处理更适合”翻译质量可接受即可”的场景，或作为人工审校的前置步骤（先自动翻译，再人工复核）。

不适合极端复杂的图纸：某些图纸包含大量动态块、自定义对象或第三方插件生成的特殊文字对象，自动提取可能无法 100% 覆盖。对于这类图纸，建议先在 Studio 中抽检几张，确认提取率满意后再批处理。

处理时间与图纸数量成正比：虽然批处理比手动操作快得多，但它不是”瞬间完成”。100 张复杂图纸可能需要数小时。请合理安排执行时间。

10.3 Batch CLI 使用指南

Batch CLI（Tongwen.Runner.BatchCli）是同文批量处理的核心工具。它是一个命令行可执行程序，接收输入目录、输出目录、配置文件等参数，自动完成从文字提取到译文回写的全流程。

10.3.1 工具位置

Batch CLI 随同文安装包一起部署，位于同文的安装目录下。典型路径如下：

• 默认安装路径：C:\Program Files\ShandianWeihu\Tongwen\Runners\Tongwen.Runner.BatchCli.exe
• 自定义安装路径：{您的安装目录}\Tongwen\Runners\Tongwen.Runner.BatchCli.exe

您可以在命令提示符（cmd）或 PowerShell 中直接调用。为了方便使用，建议将 Runner 所在目录添加到系统的 PATH 环境变量中，这样在任意路径下都可以直接输入 Tongwen.Runner.BatchCli 调用。

验证工具是否可用：打开命令提示符，输入以下命令：

Tongwen.Runner.BatchCli --help

如果工具正常，会输出所有命令行参数的说明。如果提示”不是内部或外部命令”，请检查：(1) 同文是否已正确安装；(2) 是否使用了完整的可执行文件路径。

10.3.2 命令行参数详解

Batch CLI 支持以下命令行参数：

10.3.3 配置文件说明

--config 参数指向的配置文件是一个 JSON 文件，用于指定批量处理的各项翻译参数。如果您不指定 --config，Batch CLI 将使用同文的全局默认配置。

配置文件的基本结构如下：

{
  "translation": {
    "engine": "deepseek-v4-fast",
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en-US"
  },
  "glossary": {
    "enabled": true,
    "paths": [
      "C:\\Tongwen\\Glossaries\\建筑.json",
      "C:\\Tongwen\\Glossaries\\暖通.json"
    ]
  },
  "translationMemory": {
    "enabled": true,
    "dbPath": "C:\\Tongwen\\TM\\project_tm.db"
  },
  "writeBack": {
    "strategy": "newLayer",
    "layerSuffix": "_EN",
    "mergeLayers": [],
    "preserveOriginal": true
  },
  "qa": {
    "enabled": true,
    "minSeverityToReport": "medium",
    "exportFormat": ["json", "csv"]
  },
  "logging": {
    "level": "info",
    "retainDays": 30
  }
}

配置项说明：

提示：建议为每个项目单独准备一份配置文件，保存在项目目录中。这样不仅方便日后重现结果，也便于在团队中共享统一的翻译标准。

10.3.4 典型命令示例

以下示例均假设 Batch CLI 已添加到系统 PATH 中。如果未添加，请使用完整路径。

示例一：最简单的批量翻译

将一个目录下的所有 DWG 文件翻译为英文，使用默认配置，输出到默认位置：

Tongwen.Runner.BatchCli --input-dir "D:\项目\中山医院\暖通图纸"

执行后，工具会：

1. 扫描 D:\项目\中山医院\暖通图纸 下的所有 .dwg 文件。
2. 使用默认翻译配置逐张处理。
3. 输出文件写入 D:\项目\中山医院\暖通图纸\_output 目录。

示例二：指定输出目录和配置文件

Tongwen.Runner.BatchCli --input-dir "D:\项目\中山医院\暖通图纸" --output-dir "D:\项目\中山医院\暖通图纸_EN" --config "D:\项目\中山医院\config.json"

示例三：使用并发加速处理

将最大并发数设为 3，同时处理 3 张图纸：

Tongwen.Runner.BatchCli --input-dir "D:\项目\中山医院\暖通图纸" --output-dir "D:\项目\中山医院\暖通图纸_EN" --max-concurrent 3

示例四：遇到错误不中断

即使某张图纸失败，也继续处理剩余图纸：

Tongwen.Runner.BatchCli --input-dir "D:\项目\中山医院\暖通图纸" --output-dir "D:\项目\中山医院\暖通图纸_EN" --fail-on-error false

注意：--fail-on-error 参数的值在命令行中应使用 true 或 false。不同 Shell 对布尔值的解析可能略有不同，PowerShell 中建议显式写为 --fail-on-error false。

示例五：组合使用多个参数

实际生产中最常见的用法——指定所有参数，容错执行，适度并发：

Tongwen.Runner.BatchCli -i "D:\项目\中山医院\暖通图纸" -o "D:\项目\中山医院\暖通图纸_EN" -c "D:\项目\中山医院\config.json" -m 3 --fail-on-error false

10.3.5 命令行执行过程的输出解读

Batch CLI 在执行过程中会在终端输出进度信息。以下是典型的输出示例及解读：

[2026-07-22 10:15:30] INFO  BatchCli started
[2026-07-22 10:15:30] INFO  Input directory: D:\项目\中山医院\暖通图纸
[2026-07-22 10:15:30] INFO  Found 47 DWG file(s) to process
[2026-07-22 10:15:30] INFO  Max concurrency: 3
[2026-07-22 10:15:31] INFO  [1/47] Processing: 一层暖通平面图.dwg
[2026-07-22 10:15:31] INFO  [2/47] Processing: 二层暖通平面图.dwg
[2026-07-22 10:15:31] INFO  [3/47] Processing: 三层暖通平面图.dwg
[2026-07-22 10:16:45] INFO  [1/47] Completed: 一层暖通平面图.dwg (74s, 23 translations, QA: 0 blocker, 2 high, 1 medium)
[2026-07-22 10:16:45] INFO  [4/47] Processing: 屋顶暖通平面图.dwg
...
[2026-07-22 12:34:20] INFO  [47/47] Completed: 暖通系统图.dwg (52s, 18 translations, QA: 0 blocker, 0 high, 0 medium)
[2026-07-22 12:34:20] INFO  All 47 files processed. Success: 45, Failed: 2
[2026-07-22 12:34:20] INFO  Total time: 02:18:50
[2026-07-22 12:34:20] INFO  Output directory: D:\项目\中山医院\暖通图纸\_output
[2026-07-22 12:34:20] INFO  See batch_report.json for detailed results.

输出信息解读：

• Found 47 DWG file(s) — 确认扫描到的 DWG 文件数量。如果此数字与预期不符，检查 --input-dir 路径是否正确，或是否有 DWG 文件被遗漏。
• [1/47] — 当前处理的图纸序号和总数，方便估算剩余时间。
• (74s, 23 translations, QA: 0 blocker, 2 high, 1 medium) — 单张图纸的处理摘要：耗时 74 秒、共 23 条翻译、QA 发现 0 个阻断、2 个高级问题、1 个中级问题。
• Success: 45, Failed: 2 — 最终统计。如果存在失败，需要在输出目录中查看错误详情（详见 10.5 节）。
• batch_report.json — 总体报告的汇总文件，包含每张图纸的处理状态和 QA 统计。

10.4 批量处理工作流

本节介绍一个完整的批量处理操作流程，从准备图纸到最终交付，逐步展开。

步骤一：准备待处理的图纸

整理图纸目录：将需要翻译的所有 DWG 文件集中到一个目录中。建议按专业或楼层分目录存放，例如：

D:\项目\中山医院\
├── 建筑图纸\
│   ├── 一层平面图.dwg
│   ├── 二层平面图.dwg
│   └── ...
├── 暖通图纸\
│   ├── 一层暖通平面图.dwg
│   ├── 二层暖通平面图.dwg
│   └── ...
├── 结构图纸\
│   └── ...
└── 电气图纸\
    └── ...

检查图纸完整性：在批处理之前，建议对图纸做一轮快速检查：

1. 使用 AutoCAD 打开几张典型图纸，确认图纸可以正常打开（无损坏、无密码保护）。
2. 浏览图纸中的文字内容，确认字体显示正常（没有被显示为 ?? 或乱码）。
3. 注意是否有外部参照（Xref），如果翻译要求包含外部参照的文字，需要确认参照文件也在输入目录中。
4. 备份原始图纸到安全位置——虽然批处理不会修改原始文件，但备份是一个好习惯。

步骤二：配置翻译参数

编写配置文件：根据项目需求创建 config.json。关键配置决策如下：

在同一台机器上准备术语库：如果配置文件引用了术语库路径，确保这些路径有效、文件存在且格式正确。术语库的 JSON 格式参见第06章”术语库与翻译知识”。

步骤三：试运行（Dry Run）

在正式对全部图纸执行批处理之前，强烈建议先做一次小规模试运行：

1. 从图纸目录中挑选 2~3 张代表性图纸，复制到一个临时目录中（例如 D:\项目\中山医院\试运行）。
2. 用相同的配置文件对试运行目录执行 Batch CLI：

Tongwen.Runner.BatchCli -i "D:\项目\中山医院\试运行" -o "D:\项目\中山医院\试运行\_output" -c "D:\项目\中山医院\config.json"

1. 检查试运行结果：
   • 用 AutoCAD 打开输出的 DWG 文件，检查回写效果——译文位置是否准确、图层是否正确、字体是否正常。
   • 查看 QA 报告，确认翻译质量是否符合预期。
   • 如果发现问题，调整配置文件后重新试运行，直到满意为止。

试运行是规避”批处理跑完才发现全局性配置错误”的最有效手段。这十几分钟的投入可以避免数小时的返工。

步骤四：执行全量批处理

确认试运行结果满意后，对目标目录执行全量批处理：

Tongwen.Runner.BatchCli -i "D:\项目\中山医院\暖通图纸" -o "D:\项目\中山医院\暖通图纸_EN" -c "D:\项目\中山医院\config.json" -m 3 --fail-on-error false

执行时的注意事项：

• 不要关闭命令行窗口：批处理过程中，命令行窗口必须保持打开状态。如果关闭窗口，进程会被终止。
• 留意磁盘空间：输出的 DWG 文件体积通常与原始文件相当或略大（双语对照模式可能翻倍）。确保输出目录所在磁盘有足够的剩余空间。
• 合理安排执行时间：大批量任务可以考虑在下班前启动，第二天上班查看结果。
• 保持机器稳定运行：批处理期间不要进行休眠、重启、强制关机等操作。如果使用笔记本电脑，请连接电源适配器并关闭自动休眠。

步骤五：查看结果与质量把关

批处理完成后，按以下顺序检查结果（详见 10.5 节对输出产物的完整说明）：

1. 先看汇总报告：打开 batch_report.json，查看”Success”和”Failed”的数量。确认失败的图纸有哪些。
2. 再看 QA 报告：打开 qa_summary.csv（或 qa_details.json），快速浏览哪些图纸有阻断级或高级 QA 问题。对这些图纸优先处理。
3. 抽检 DWG 输出：从输出目录中随机选取 3~5 张 DWG，用 AutoCAD 打开，检查回写质量。
4. 处理失败和问题：对于失败的图纸，查看日志定位原因。对于 QA 问题较多的图纸，考虑在 Studio 中打开对应翻译会话进行人工补审。

步骤六：处理异常

批处理中出现个别图纸失败是正常现象。常见的失败原因和处理方法参见 10.9 节”常见问题与排查”。

如果失败数量较多（超过总数的 10%），应该暂停交付，排查根本原因——通常是配置文件有问题、术语库格式错误或翻译引擎响应异常。

10.5 批量处理输出产物说明

一次批量处理完成后，输出目录中会生成以下文件和子目录：

{输出目录}/
├── *.dwg                    # 翻译后的 DWG 图纸文件
├── batch_report.json        # 批处理总体报告
├── qa_summary.csv           # QA 汇总报告（CSV 格式）
├── qa_details.json          # QA 详细报告（JSON 格式）
├── {图纸名}.qa.json         # 每张图纸的独立 QA 报告
├── {图纸名}.log             # 每张图纸的独立处理日志
├── review\                  # HTML 审查报告目录（如果执行了 Review CLI）
│   └── index.html
└── logs\                    # 全局日志目录
    └── batch_20260722_101530.log

10.5.1 翻译后的 DWG 文件

这是批量处理最重要的输出——翻译后的图纸文件。文件命名规则：如果原始文件为 一层暖通平面图.dwg，翻译后默认为 一层暖通平面图.dwg（输出到独立的输出目录，文件名不变）。

与原始 DWG 文件的区别：

• 文字内容已替换为译文（具体行为取决于回写策略）。
• 如果使用”创建新图层”策略，原文保留在原始图层，译文位于新增图层中。
• 其他所有图元（线段、圆弧、填充、块参照等）与原始文件完全一致。
• 文件的结构和元数据（图层列表、文字样式、标注样式等）保持完整。

10.5.2 batch_report.json（批处理总体报告）

汇总整个批处理任务的执行情况。典型内容如下：

{
  "taskId": "batch_20260722_101530",
  "startTime": "2026-07-22T10:15:30",
  "endTime": "2026-07-22T12:34:20",
  "totalFiles": 47,
  "successCount": 45,
  "failedCount": 2,
  "totalTranslations": 1042,
  "qaSummary": {
    "blocker": 0,
    "high": 23,
    "medium": 47,
    "low": 112
  },
  "files": [
    {
      "fileName": "一层暖通平面图.dwg",
      "status": "success",
      "duration": "00:01:14",
      "translations": 23,
      "qa": { "blocker": 0, "high": 2, "medium": 1, "low": 5 }
    },
    {
      "fileName": "暖通设备表.dwg",
      "status": "failed",
      "duration": "00:00:05",
      "error": "Translation engine timeout after 30s",
      "translations": 0
    }
  ]
}

关键字段解读：

• taskId：本次批处理任务的唯一标识，可用于追溯。
• totalFiles / successCount / failedCount：总文件数、成功数、失败数。
• qaSummary：全部图纸的 QA 问题汇总，快速了解整体翻译质量。
• files[].status：每张图纸的处理结果——success 或 failed。
• files[].error：失败原因描述（仅失败条目有此字段）。

10.5.3 QA 报告文件

批量处理会生成两种格式的 QA 报告：

qa_summary.csv（CSV 汇总报告）：

用 Excel 或 WPS 打开，适合快速浏览和制作统计图表。典型的列结构：

qa_details.json（JSON 详细报告）：

包含每条翻译的逐项 QA 检查结果，适合系统集成和程序化处理。每条记录包含原文、译文、各验证器的检查结果和风险等级。

{图纸名}.qa.json（单张图纸独立 QA 报告）：

与 qa_details.json 结构一致，但只包含单张图纸的 QA 数据。适用于归档和对单张图纸的独立追溯。

10.5.4 日志文件

全局日志：logs\batch_{taskId}.log 包含整个批处理任务的完整运行日志。当需要排查问题时，这是第一手信息来源。

单图日志：{图纸名}.log 包含单张图纸的处理日志。当批处理报告显示某张图失败时，打开对应的单图日志可以看到详细的错误堆栈。

日志保留策略：配置文件中的 logging.retainDays 参数控制日志保留天数。超过该天数的日志文件会被后续的批处理任务自动清理，避免日志堆积占用磁盘空间。

10.6 Review CLI 使用指南

Review CLI（Tongwen.Runner.Review）用于在批量翻译完成后，生成一个独立的、可在浏览器中查看的 HTML 审查报告。这个报告将所有图纸的翻译质量和 QA 发现集中展示，方便审校人员、项目经理或甲方进行整体质量的评估。

10.6.1 什么是 Review CLI

Review CLI 包含两个核心组件：

1. BatchReviewCli：批量审查命令行入口，负责读取批量处理的输出结果，汇总 QA 数据。
2. BatchReviewHtmlGenerator：审查 HTML 报告生成器，负责将审查数据渲染为可交互的 HTML 页面。

两者的关系是：BatchReviewCli 从批处理输出目录中读取数据、聚合分析；BatchReviewHtmlGenerator 将分析结果生成为可视化的 HTML 报告。

10.6.2 HTML 审查报告的内容

生成的 HTML 报告是一个完整的、自包含的网页文件（无需任何 Web 服务器，双击即可在浏览器中打开），包含以下核心板块：

翻译质量概览

报告首页展示整体翻译质量的汇总仪表盘，包括：

• 总翻译量：本次批处理涉及的全部翻译条数。
• QA 问题分布：阻断、高、中、低四个等级的发现数量，以柱状图或饼图形式可视化呈现。
• 处理成功率：成功处理的图纸数量与总数的对比。
• 术语覆盖率：术语库中已定义术语在实际翻译中的命中率。
• 翻译记忆命中率：翻译记忆库对重复文字的覆盖率。

QA 发现汇总

按验证器类别（占位符验证、术语验证、长度溢出验证）汇总所有 QA 发现，展示每类问题的数量、严重程度分布和涉及的文件清单。点击某个类别可以展开查看具体发现。

逐条翻译审查详情

报告提供每条翻译的详细审查信息：

风险等级可视化

报告使用颜色编码直观展示风险等级：

文件级质量视图

以文件为单位展示每张图纸的质量评分和问题清单。审校人员可以快速定位”问题最多”的图纸，优先处理。

10.6.3 生成 HTML 审查报告

Review CLI 的使用方式与 Batch CLI 类似：

Tongwen.Runner.Review --input-dir "D:\项目\中山医院\暖通图纸\_output" --output-dir "D:\项目\中山医院\暖通图纸\_output\review"

执行后，在输出目录下会生成 index.html 文件。双击该文件即可在浏览器中查看完整的审查报告。

提示：HTML 报告是纯静态文件，不需要网络或服务器环境。您可以将其复制到 U 盘、发送邮件附件或上传到内部文件服务器，供没有安装同文的团队成员查看。

10.6.4 审查报告的使用场景

团队审校会：在审校会议上，将 HTML 报告投影到大屏幕上，团队成员共同浏览 QA 发现，逐条讨论高风险问题的处理方案。

甲方交付：将 HTML 报告作为翻译交付的一部分，向甲方展示翻译质量的管理过程和结果。甲方无需安装任何软件即可全面了解翻译质量。

质量归档：每次批处理完成后生成一份 HTML 报告，与翻译后的 DWG 文件一同归档。日后如有质量追溯需求，可以快速查阅。

第三方审校：将 HTML 报告发给专业的翻译审校团队，他们可以直接在浏览器中审阅全部翻译结果，标注问题后反馈。

10.7 Web API 使用说明

对于需要远程调度或团队协作的场景，同文提供了 Web API 服务（Tongwen.Server）。通过 HTTP 接口，您可以远程注册批量处理任务、查询任务状态和获取处理结果。

10.7.1 启动 Web API 服务

Web API 服务以独立进程运行，需要先启动服务才能使用。启动命令如下：

Tongwen.Server --port 5000

参数说明：

• --port：服务监听的端口号，默认为 5000。

启动成功后，终端会输出类似以下的信息：

[INFO] Tongwen Server started on http://localhost:5000
[INFO] API documentation available at http://localhost:5000/swagger

安全提示：默认情况下，Web API 绑定在 localhost，仅允许本机访问。如果需要从局域网内的其他机器访问，需要在启动时配置绑定地址。生产环境中务必配置身份验证和安全传输（HTTPS），具体配置方法请参考同文部署文档。

10.7.2 注册批处理任务

接口：POST /api/batch-runs

请求体示例：

{
  "inputDir": "D:\\项目\\中山医院\\暖通图纸",
  "outputDir": "D:\\项目\\中山医院\\暖通图纸_EN",
  "configPath": "D:\\项目\\中山医院\\config.json",
  "maxConcurrent": 3,
  "failOnError": false
}

请求体字段说明：

成功响应（HTTP 201）：

{
  "batchRunId": "br_20260722_101530_a1b2c3",
  "status": "registered",
  "createdAt": "2026-07-22T10:15:30",
  "message": "Batch run registered successfully. Use GET /api/batch-runs/{batchRunId} to track progress."
}

10.7.3 查询批处理任务状态

接口：GET /api/batch-runs（查询全部）或 GET /api/batch-runs/{batchRunId}（查询单个）

单个任务响应示例：

{
  "batchRunId": "br_20260722_101530_a1b2c3",
  "status": "processing",
  "progress": {
    "totalFiles": 47,
    "completedFiles": 12,
    "failedFiles": 0,
    "percentComplete": 25.5,
    "elapsedTime": "00:25:30",
    "estimatedRemaining": "01:13:30"
  },
  "createdAt": "2026-07-22T10:15:30",
  "startedAt": "2026-07-22T10:15:31"
}

全部任务列表响应：

{
  "totalCount": 3,
  "items": [
    {
      "batchRunId": "br_20260722_101530_a1b2c3",
      "status": "processing",
      "progress": { "percentComplete": 25.5 },
      "createdAt": "2026-07-22T10:15:30"
    },
    {
      "batchRunId": "br_20260720_143000_d4e5f6",
      "status": "completed",
      "progress": { "percentComplete": 100 },
      "createdAt": "2026-07-20T14:30:00"
    }
  ]
}

任务状态枚举：

10.7.4 典型集成场景

CI/CD 流水线集成：在图纸设计变更后，自动触发翻译流水线。例如，当设计院的图纸管理系统检测到 DWG 文件更新后，通过 Web API 自动注册一个批处理任务，翻译完成后邮件通知相关人员。

定时批处理：通过 Windows 任务计划程序或 cron（Linux 上通过 WSL）定时调用 Web API 接口，实现每天凌晨自动翻译当天新增的图纸。

内部管理系统集成：在公司的项目管理系统中嵌入”一键翻译”按钮，点击后调用同文 Web API 注册任务并实时展示进度。

10.8 批量测试命令说明

在 AutoCAD 内部，同文提供了一组以 TW_ 为前缀的命令，用于验证插件的正确性和批量处理流程。这些命令主要用于以下场景：

• 安装后验证：首次安装同文后，确认 AutoCAD 插件能否正常工作。
• 升级后回归测试：升级同文版本后，确保原有功能不受影响。
• 故障排查：当翻译功能出现异常时，通过测试命令缩小问题范围。

注意：以下命令均需要在 AutoCAD 的命令行中执行（即在 AutoCAD 界面底部的命令输入框中输入命令名后按回车）。它们生成的测试环境仅用于验证，不应在生产项目中运行。

10.8.1 TW_CREATE_SMOKE_FIXTURE_ENV（生成 Smoke 测试 DWG）

用途：在当前打开的 AutoCAD 环境中，自动创建一张用于 Smoke 测试的 DWG 图纸。这张图纸包含少量典型的文字对象（单行文字、多行文字、属性定义等），用于快速验证文字提取和翻译功能的基本可用性。

使用方法：

1. 打开 AutoCAD，新建一张空白图纸。
2. 在命令行输入 TW_CREATE_SMOKE_FIXTURE_ENV，按回车。
3. 工具会自动在图纸中生成测试文字，并保存为一个 .dwg 文件。

适用场景：快速冒烟测试——确认同文插件已正确加载，能正常提取和翻译文字。

10.8.2 TW_CREATE_TEST_FIXTURE_ENV（生成全面测试 DWG）

用途：创建一张包含全面测试用例的 DWG 图纸。与 Smoke 测试不同，这张图纸覆盖了更丰富的场景：

• 多种文字类型：单行文字（TEXT）、多行文字（MTEXT）、属性定义（ATTDEF）、块属性（ATTRIB）、标注文字（DIMENSION）。
• 复杂格式文本：包含堆叠文字、上下标、字体颜色切换、多段落排版。
• 特殊字符：AutoCAD 特殊符号（%%C、%%D、%%P）、Unicode 字符、换行符。
• 多比例布局：不同视口和注释比例下的文字对象。

使用方法：

1. 打开 AutoCAD，新建一张空白图纸。
2. 在命令行输入 TW_CREATE_TEST_FIXTURE_ENV，按回车。
3. 等待工具生成测试图纸。

适用场景：全面功能验证——在升级同文版本后，或在新机器上部署后，确认所有文字类型和格式场景都能正确处理。

10.8.3 TW_BATCH_SMOKE_ENV（批量 Smoke 测试）

用途：自动创建多张 Smoke 测试 DWG，并对其执行批量翻译流程，验证整个 Batch CLI 管道是否正常工作。

使用方法：

1. 打开 AutoCAD。
2. 在命令行输入 TW_BATCH_SMOKE_ENV，按回车。
3. 工具会自动创建测试 DWG、执行批量处理、输出结果到临时目录。
4. 在命令行输出区域查看测试结果摘要。

适用场景：验证”从图纸创建到批量翻译回写”这一完整链路的正确性——确保 Batch CLI 调用、翻译引擎连接、QA 检查和回写功能协同工作。

10.8.4 TW_BATCH_RUN_ENV（批量运行）

用途：对当前打开的项目或指定目录，执行一次完整的批量翻译运行。与 Batch CLI 的区别在于：此命令在 AutoCAD 内部执行，利用 AutoCAD 的运行时环境，可以实时在 AutoCAD 界面中看到处理进度。

使用方法：

1. 打开 AutoCAD，加载同文插件。
2. 在命令行输入 TW_BATCH_RUN_ENV，按回车。
3. 根据提示输入或选择目标目录。

适用场景：在 AutoCAD 环境中快速测试一批图纸的翻译效果——不需要切换到命令行，直接在 AutoCAD 内部完成。

10.8.5 TW_BATCH_VERIFY_ENV（验证持久化 DWG）

用途：验证批量翻译回写后的 DWG 文件的数据完整性。它会比对新旧 DWG 文件，检查图层数量、文字对象数量、关键属性（坐标、字体、高度等）是否保持一致。

使用方法：

1. 在命令行输入 TW_BATCH_VERIFY_ENV，按回车。
2. 根据提示选择原始 DWG 目录和翻译后的 DWG 目录。
3. 工具会输出完整性验证报告。

适用场景：

• 批量处理后，验证输出文件的完整性——确认没有丢失文字、图层或属性。
• 排查”为什么翻译后图纸异常”问题时，用此命令对比新旧文件。

10.8.6 TW_VERIFY_SMOKE_ENV（验证 Smoke 测试结果）

用途：读取之前由 TW_BATCH_SMOKE_ENV 或 TW_CREATE_SMOKE_FIXTURE_ENV 生成的结果，验证其中的翻译内容是否正确。

使用方法：

1. 在命令行输入 TW_VERIFY_SMOKE_ENV，按回车。
2. 工具会自动查找最近的测试结果并验证。

适用场景：在 TW_BATCH_SMOKE_ENV 执行之后，确认翻译的实际内容与预期一致。

10.8.7 测试命令使用建议

1. 首次安装后：依次运行 TW_CREATE_SMOKE_FIXTURE_ENV → TW_BATCH_SMOKE_ENV → TW_VERIFY_SMOKE_ENV，确保全套功能正常工作。
2. 版本升级后：运行 TW_CREATE_TEST_FIXTURE_ENV → TW_BATCH_RUN_ENV，全面验证兼容性。
3. 遇到异常：先用 TW_CREATE_SMOKE_FIXTURE_ENV 验证基本功能是否正常。如果 Smoke 测试通过但实际图纸有问题，说明问题出在特定图纸的特性上，而非插件本身。

10.9 大量图纸批处理的最佳实践

在处理数十张乃至上百张图纸时，合理的工作方法对最终效果和质量有着决定性影响。以下建议来自大量实际项目的经验总结。

10.9.1 分批策略

不要一次性处理所有图纸。将大项目按合理维度拆分为多个批次，逐批执行：

分批的好处：

• 降低风险：如果配置文件有问题，只会影响一个批次，而不是全部图纸。
• 便于并行：如果您有多台安装了同文的机器，可以将不同批次分配到不同机器上并行处理。
• 方便验收：一个批次完成后可以立即开始审校，而不需要等全部图纸处理完。
• 易于管理：每个批次的输出独立存放，不互相干扰。

10.9.2 并发控制

--max-concurrent 参数控制同时处理的图纸数量。设置建议：

并发数的选择取决于三个因素：

1. 翻译引擎的并发限制：如果您使用的 LLM API 有并发请求数限制，Batch CLI 的并发数不应超过该限制。
2. 本机 CPU 和内存：每增加一个并发，约消耗 500MB~1GB 内存和一定量的 CPU。请确保机器有足够资源。
3. DWG 文件复杂度：包含大量文字对象的图纸（超过 500 条翻译/张）处理时间较长，并发效益更明显；文字量少的图纸（少于 50 条/张）并发效益有限。

10.9.3 错误处理策略

通过 --fail-on-error 参数和配置文件的组合，您可以定义遇到错误时的行为：

策略一：快速失败（fail-on-error=true，默认）

适合首次试运行或配置验证阶段。一旦某张图失败，立即停止，方便快速发现和修复配置问题。

策略二：容错执行（fail-on-error=false）

适合正式生产。单张或几张图纸失败不影响整体进度，最后统一处理失败项。

策略三：混合策略

先用 fail-on-error=true 试运行 3~5 张，确认配置无误后，再切换为 fail-on-error=false 全量执行。

10.9.4 术语库和翻译记忆的准备

批量处理的质量高度依赖前期准备的充分程度：

1. 术语库准备：在批处理之前，花时间整理项目专属术语库。术语条目越多、越准确，翻译结果就越专业。如果发现批处理结果中反复出现某个术语翻译不当，将它加入术语库，重新执行批处理即可全局修复。
2. 翻译记忆预热：如果这是该项目的第一次批处理，翻译记忆为空。首次处理速度较慢（每条都需要调用 LLM）。第二次批处理时，大量重复文字会被记忆命中，速度显著提升。因此，可以考虑先对少量图纸跑一次批处理作为”预热”，再用积累的翻译记忆处理全量图纸。
3. 术语库分专业管理：不要把所有专业的术语混在一个文件中。建议按专业建立独立的术语库文件，在配置文件中按需加载。例如处理暖通图纸时只加载暖通和通用术语库，避免结构专业的术语干扰翻译。

10.9.5 输出管理

创建清晰的目录结构：建议按以下模式组织输出：

D:\项目\中山医院\
├── 01_原始图纸\
│   ├── 建筑\
│   ├── 暖通\
│   └── ...
├── 02_翻译输出\
│   ├── 建筑\
│   │   ├── _output\
│   │   └── review\
│   ├── 暖通\
│   │   ├── _output\
│   │   └── review\
│   └── ...
├── 03_配置文件\
│   ├── 建筑_config.json
│   └── 暖通_config.json
└── 04_交付\
    └── 20260722\

定期清理临时文件：批处理会产生大量中间文件（日志、临时提取数据等），建议配置 logging.retainDays 自动清理旧日志，并定期手动清理不再需要的 QA 报告文件。

10.9.6 跨批次的一致性保证

如果项目需要分多个批次处理，确保以下配置在每个批次中保持一致：

• 术语库：使用完全相同的术语库路径和版本。
• 翻译引擎：使用相同的引擎类型（deepseek-v4-fast 或 deepseek-v4-pro）。
• 回写策略：使用相同的回写参数（strategy、layerSuffix、mergeLayers）。
• QA 设置：使用相同的报告级别。

一个实用技巧是：创建一个”项目基准配置文件”，所有批次的配置都引用它（或在必要时复制后仅修改 inputDir 和 outputDir）。

10.10 常见问题与排查

10.10.1 Batch CLI 提示”不是内部或外部命令”

原因：系统 PATH 中未包含 Batch CLI 所在的目录。

解决方法：

1. 确认同文已安装，找到 Tongwen.Runner.BatchCli.exe 的完整路径（通常在 C:\Program Files\ShandianWeihu\Tongwen\Runners\ 下）。
2. 使用完整路径执行命令，例如：

   "C:\Program Files\ShandianWeihu\Tongwen\Runners\Tongwen.Runner.BatchCli.exe" --input-dir "D:\图纸"
   

3. （可选）将 Runner 目录添加到 PATH：右键”此电脑”→属性→高级系统设置→环境变量→在”Path”中添加 Runner 目录路径。

10.10.2 扫描到的 DWG 文件数量与预期不符

可能原因：

• 目录中包含非 .dwg 后缀的文件（如 .dwl、.dwl2、.bak），这些不会被识别。
• DWG 文件存放在子目录中，但期望递归扫描的深度不够（Batch CLI 默认递归扫描所有子目录）。
• 文件被其他程序占用（如 AutoCAD 正在打开该文件），导致无法读取。

解决方法：

1. 用文件资源管理器打开输入目录，确认 DWG 文件确实存在。
2. 检查是否有 .dwg 文件被隐藏（如在 Windows 资源管理器中显示隐藏文件）。
3. 关闭所有可能占用 DWG 文件的程序后重试。
4. 确认文件名中没有特殊字符（如全角空格、不可见字符）导致路径解析异常。

10.10.3 某张图纸处理失败

常见失败原因及解决方法：

失败后的恢复策略：

1. 查看 batch_report.json 中的 files 数组，找到状态为 failed 的条目。
2. 查看对应图纸的日志文件（{图纸名}.log）获取详细错误信息。
3. 修复问题后，可以将失败的图纸单独放到一个新目录中，对该目录重新执行 Batch CLI。
4. 如果使用了 --fail-on-error false，成功的图纸不需要重新处理，只处理失败的即可。

10.10.4 并发处理时部分图纸结果异常

原因：并发模式下，多张图纸同时调用翻译引擎和写入文件，可能出现资源竞争。少数情况下，翻译引擎的并发限流会导致部分请求被拒绝。

解决方法：

1. 降低并发数——将 --max-concurrent 从 3 降为 2 或 1。
2. 如果降并发后仍异常，尝试将异常图纸单独串行处理。
3. 检查翻译引擎 API 的并发限制（如果使用了云端 LLM）。

10.10.5 QA 报告中出现大量阻断级问题

可能原因：

• 原始图纸中的文字包含大量复杂格式码，翻译引擎未正确处理占位符。
• 术语库配置了极其严格的约束条件，与翻译引擎的实际输出冲突。
• 原文是表格类文字，翻译后的文字长度远超原文，触发了大量长度溢出。

解决方法：

1. 先查看具体是哪种验证器产生的阻断——占位符验证、术语验证还是长度溢出。
2. 如果是占位符问题：在 Studio 中打开几张典型图纸的翻译会话，检查占位符是否被正确保留。如果格式码特别复杂，可能需要调整提取阶段的格式码处理策略。
3. 如果是术语问题：检查术语库是否定义了过于严格的条件。考虑放宽部分术语的匹配规则。
4. 如果是长度溢出：检查是否是表格类文字。表格类文字对长度敏感，可能需要调整翻译策略——例如在回写时使用更紧凑的字体，或允许文字自动缩放。
5. 如果阻断问题集中在少数几张图纸，先将这几张图单独拿出来，在 Studio 中人工处理后回写。其余通过 QA 的图纸可以直接交付。

10.10.6 翻译后 DWG 字体显示为乱码或问号

原因：翻译后的文字使用了原文中没有的 Unicode 字符（如中文翻译为日文后出现了假名字符），而当前 DWG 指定的字体（SHX 或 TrueType 字体）不支持这些字符。

解决方法：

1. 在 AutoCAD 中打开翻译后的 DWG，执行 STYLE 命令，检查文字样式使用的字体。
2. 如果使用的是 SHX 字体（如 txt.shx、hztxt.shx），SHX 字体对 Unicode 的支持有限，建议切换为支持多语言的 TrueType 字体（如 Arial Unicode MS、SimSun、MS Gothic）。
3. 在回写配置中指定一个支持目标语言字符集的字体，作为翻译后的默认字体。

10.10.7 批处理中途中断（断电、关机等）

当前行为：由于 --resume 参数在当前版本中为预留（暂未启用），批处理中断后无法自动从断点恢复。

手动恢复方法：

1. 查看 batch_report.json 了解哪些图纸已成功处理。
2. 将未处理的图纸复制到一个新目录中。
3. 对新目录重新执行 Batch CLI。
4. 将两批输出合并到最终交付目录中。

避免中断的建议：

• 在笔记本电脑上执行大批量任务时，务必连接电源适配器并关闭自动休眠。
• 在台式机上执行时，关闭 Windows 自动更新（临时暂停）。
• 对于超过 100 张图纸的任务，考虑分批执行以减少单次运行时间。

10.10.8 Web API 无法访问

常见原因：

10.11 本章小结

本章全面介绍了同文（Tongwen）批量处理与命令行的各项功能和使用方法：

1. 批量处理概述：批量处理将文字提取、翻译、QA 检查、报告导出、译文回写串联为全自动化管道，适合 20 张以上图纸的项目。其核心优势在于效率、一致性、可追溯性和可重复性，但不适合需要逐条人工审校的精细翻译场景。

2. Batch CLI 使用指南：Tongwen.Runner.BatchCli 是命令行批量处理的核心工具，支持 --input-dir（输入目录）、--output-dir（输出目录）、--config（配置文件）、--max-concurrent（并发数）、--fail-on-error（容错策略）和 --help 等参数。配置文件为 JSON 格式，可指定翻译引擎、术语库、翻译记忆、回写策略和 QA 设置。

3. 批量处理工作流：完整的六步流程——准备图纸 → 配置参数 → 试运行 → 全量执行 → 查看结果 → 处理异常。试运行是确保配置正确的关键步骤，不应跳过。

4. 输出产物说明：批处理输出包括翻译后 DWG 文件、batch_report.json（总体报告）、qa_summary.csv（QA 汇总）、qa_details.json（QA 详情）、单图 QA 报告、单图日志和全局日志。

5. Review CLI 使用指南：Tongwen.Runner.Review 生成自包含的 HTML 审查报告，包含翻译质量概览、QA 发现汇总、逐条翻译详情和风险等级可视化。报告无需服务器即可在浏览器中查看，适合团队审校、甲方交付和质量归档。

6. Web API 使用说明：Tongwen.Server 提供 HTTP 接口，支持 POST /api/batch-runs 注册批处理任务和 GET /api/batch-runs 查询任务状态，适合 CI/CD 集成、定时任务和内部系统集成。

7. 批量测试命令：AutoCAD 内部提供 TW_CREATE_SMOKE_FIXTURE_ENV（生成 Smoke 测试 DWG）、TW_CREATE_TEST_FIXTURE_ENV（生成全面测试 DWG）、TW_BATCH_SMOKE_ENV（批量 Smoke 测试）、TW_BATCH_RUN_ENV（批量运行）、TW_BATCH_VERIFY_ENV（验证持久化 DWG）和 TW_VERIFY_SMOKE_ENV（验证 Smoke 测试结果），用于安装验证、升级回归和故障排查。

8. 最佳实践：按专业或楼层分批处理（每批 30~50 张）、合理控制并发（2~3 为常规推荐）、采用先试运行再全量的策略、提前准备术语库和翻译记忆、建立清晰的输出目录结构、确保跨批次配置一致性。

9. 常见问题与排查：覆盖了命令行环境配置、文件扫描数量异常、单张处理失败、并发结果异常、QA 大量阻断、字体乱码、中断恢复和 Web API 访问等八个方面的典型问题和解决方法。

批量处理是同文从”单兵作战”升级为”规模化生产”的关键能力。掌握了本章内容，您将能够高效地处理从几十张到数百张图纸的翻译任务，将时间和精力从重复性操作中解放出来，专注于翻译质量的把控和项目交付。

上一篇：第09章：术语库与翻译知识系统（待更新） 下一篇：第11章（待更新） 返回：同文教程目录