arxiv-paper-zh 0.1.2 → 0.2.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-paper-zh",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Verify and translate arXiv papers into compilable Chinese editions with paired English and Chinese PDFs.",
   "author": {
     "name": "AndrewYq",

package/README.md

@@ -33,9 +33,11 @@ npm 包地址：[arxiv-paper-zh](https://www.npmjs.com/package/arxiv-paper-zh)
 
 - 核对论文简称、标题、作者、摘要、URL 与 arXiv ID，避免翻错同名论文。
 - 按 `arxiv-paper/<paper-name>/` 统一保存原始源码、中文源码以及中英文 PDF。
-- 按可见英文词量均衡分片，支持多个 subagent 并行处理长论文。
+- 将可见英文切成紧凑任务包，公式、引用、URL、代码和注释使用可逆占位符，不再让模型重复读取整份 TeX。
+- 按词量自适应分配 worker；长论文并行、短论文自动减少 worker，单文件论文也能分片。
 - 保留公式、数值、引用键、标签、人名、模型名、数据集名和常用缩写。
 - 翻译正文、章节标题、脚注、表头、表注和 caption。
+- 参考文献标题与条目保持原文，并在翻译分片和漏译审计中自动跳过。
 - 批量检查并安装缺失的 TeX 宏包，复用共享 TinyTeX/TeX Live 缓存。
 - 自动执行漏译审计、BibTeX/Biber 构建和引用收敛检查。
 - 使用 XeLaTeX 生成中文 PDF，并要求逐页视觉核验。
@@ -64,13 +66,17 @@ arxiv-paper-zh/
 │       │   ├── build_and_check.py
 │       │   ├── inventory_and_shard.py
 │       │   ├── prepare_output_layout.py
-│       │   └── prepare_tex_runtime.py
+│       │   ├── prepare_tex_runtime.py
+│       │   ├── translation_tasks.py
+│       │   └── tex_translation_utils.py
 │       └── references/
 │           └── paper-translation-packages.txt
 ├── install.sh
 ├── package.json
 ├── tests/
-│   └── installer.test.mjs
+│   ├── installer.test.mjs
+│   ├── test_bibliography_exclusion.py
+│   └── test_translation_tasks.py
 ├── .gitignore
 └── README.md
 ```
@@ -237,7 +243,7 @@ arxiv-paper/EST/
 
 `paper-name` 使用用户熟悉的简短名称并保留大小写，例如 `EST`、`Onetrans`，且只能包含英文字母、数字、点、下划线和连字符。
 
-参考文献元数据默认不翻译；原图内部文字不修改，只翻译必要 caption。公式内的英文说明按“公式不变”原则保留。
+整个参考文献部分保持原文，包括标题和全部条目；`.bib`、`.bbl`、内嵌 bibliography 环境和单独的参考文献 TeX 文件均不参与翻译。正文中的文献综述仍照常翻译。原图内部文字不修改，只翻译必要 caption。公式内的英文说明按“公式不变”原则保留。
 
 ## 内置工具
 
@@ -245,8 +251,12 @@ arxiv-paper/EST/
 # 创建并输出固定的论文产物路径
 python3 skills/arxiv-paper-zh/scripts/prepare_output_layout.py EST --root arxiv-paper
 
-# 统计文件并生成均衡翻译分片
-python3 skills/arxiv-paper-zh/scripts/inventory_and_shard.py arxiv-paper/EST/latex/paper-zh --entry main.tex --workers 3 --json
+# 生成紧凑翻译任务包（3 是 worker 上限，小论文会自动减少）
+python3 skills/arxiv-paper-zh/scripts/translation_tasks.py prepare arxiv-paper/EST/latex/paper-zh --entry main.tex --workers 3 --json
+
+# worker 填写各自的 worker-*.task 后，检查进度并安全合并
+python3 skills/arxiv-paper-zh/scripts/translation_tasks.py status arxiv-paper/EST/latex/paper-zh
+python3 skills/arxiv-paper-zh/scripts/translation_tasks.py apply arxiv-paper/EST/latex/paper-zh
 
 # 检查预装包和论文专用宏包
 python3 skills/arxiv-paper-zh/scripts/prepare_tex_runtime.py arxiv-paper/EST/latex/paper-zh --preset --kpsewhich /path/to/kpsewhich
@@ -267,7 +277,7 @@ python3 skills/arxiv-paper-zh/scripts/build_and_check.py arxiv-paper/EST/latex/p
 - 是否允许网络下载与安装宏包。
 - 是否提供可写文件系统和本地 XeLaTeX。
 
-客户端不支持 subagent 时，Agent 应顺序处理分片；不影响翻译规则与构建脚本的使用。
+客户端不支持 subagent 时，Agent 应顺序填写任务包。任务包仍会剔除不需要发送给模型的内容，因此同样能降低上下文开销；只是不具备并行加速。
 
 ## 开发与发布检查
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "arxiv-paper-zh",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Install the arxiv-paper-zh Agent Skill for Codex, Claude Code, and compatible agents.",
   "type": "module",
   "bin": {
-    "arxiv-paper-zh": "./bin/arxiv-paper-zh.mjs"
+    "arxiv-paper-zh": "bin/arxiv-paper-zh.mjs"
   },
   "files": [
     ".codex-plugin/",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "check": "node --check bin/arxiv-paper-zh.mjs && python3 -c \"from pathlib import Path; [compile(path.read_bytes(), str(path), 'exec') for path in Path('skills/arxiv-paper-zh/scripts').glob('*.py')]\" && npm test"
+    "check": "node --check bin/arxiv-paper-zh.mjs && python3 -c \"from pathlib import Path; [compile(path.read_bytes(), str(path), 'exec') for path in Path('skills/arxiv-paper-zh/scripts').glob('*.py')]\" && python3 -m unittest discover -s tests -p 'test_*.py' && npm test"
   },
   "engines": {
     "node": ">=18"

package/skills/arxiv-paper-zh/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: arxiv-paper-zh
-description: Verify that a requested paper name, acronym, title, authors, abstract, URL, and arXiv ID identify the intended work; then rapidly download and translate its TeX source into Chinese with balanced subagent sharding, deterministic artifact paths under arxiv-paper, paired English/Chinese PDFs, cached dependencies, audits, XeLaTeX compilation, and full-page visual verification. Use when a user asks to locate and translate an arXiv or LaTeX research paper into a compilable Chinese edition, especially for ambiguous acronyms or long papers requiring parallel translation.
+description: Verify an arXiv or LaTeX paper's identity, then produce complete, compilable English and Chinese sources and PDFs. Use for locating and translating research papers while preserving math, citations, data, and layout; the workflow uses compact protected translation packets, adaptive parallel workers, cached TeX dependencies, audits, XeLaTeX compilation, and full-page visual verification.
 ---
 
 # arXiv 论文快速中文化
 
-交付保留原始数学、数据、引用和作者信息的中英文可编译源码及经过页面核验的中英文 PDF。身份正确性与译文完整性优先，但要并行执行互不依赖的阶段。
+交付保留数学、数据、引用和作者信息的中英文源码与经过页面核验的 PDF。身份正确性和译文完整性优先；翻译阶段使用紧凑任务包，避免将整份 TeX 和重复会话上下文发送给每个 worker。
 
-## 输出目录契约
+## 输出目录
 
-将全部用户产物固定放到 `arxiv-paper/<paper-name>/`。`paper-name` 优先使用用户给出的论文简称并保留大小写，例如 `EST`、`Onetrans`；若用户只给出标题，则核验论文身份后生成简短名称。名称必须匹配 `[A-Za-z0-9][A-Za-z0-9._-]*`，不得包含空格、斜杠或 arXiv ID，除非 ID 本身就是用户指定名称。
+全部产物固定放在 `arxiv-paper/<paper-name>/`：
 
 ```text
 arxiv-paper/<paper-name>/
@@ -17,81 +17,85 @@ arxiv-paper/<paper-name>/
 │   ├── source.tar
 │   ├── paper-en/
 │   └── paper-zh/
-├── paper-en/
-│   └── <paper-name>-en.pdf
-└── paper-zh/
-    └── <paper-name>-zh.pdf
+├── paper-en/<paper-name>-en.pdf
+└── paper-zh/<paper-name>-zh.pdf
 ```
 
-`latex/paper-en/` 保存未经翻译的解压源码，`latex/paper-zh/` 保存其完整中文副本；两个 PDF 目录只保存最终交付 PDF。开始下载前先运行：
+`paper-name` 优先使用用户简称并保留大小写，且必须匹配 `[A-Za-z0-9][A-Za-z0-9._-]*`。开始下载前运行：
 
 ```bash
 python3 scripts/prepare_output_layout.py <paper-name> --root arxiv-paper
 ```
 
-以脚本输出的绝对路径为准，后续不得另建 `work/<arxiv-id>`、顶层 `paper_cn/` 或其他平行交付目录。临时渲染图、构建日志和联系表可放在论文目录下的隐藏临时目录，交付前不得混入 `paper-en/` 或 `paper-zh/`。
+以脚本输出的绝对路径为准，不另建平行交付目录。`.translation-tasks/`、渲染图和日志属于论文目录内的临时文件，不得混入最终 PDF 目录。
 
-## 共享论文翻译运行时
+## 工作流
 
-优先复用固定位置的 TinyTeX/TeX Live，不要将运行时复制进每个论文目录。首次建立或主动刷新共享运行时时，使用内置预装清单一次检查并一次批量安装：
+1. 从 arXiv 摘要页或 API 核验规范化 ID、完整标题、作者、摘要、版本和日期。简称不是唯一标识；候选不唯一时让用户确认。向用户明确标题、作者和 arXiv ID。
+2. 创建输出目录，将 `https://export.arxiv.org/e-print/<ID>` 保存为 `latex/source.tar` 并解压到 `latex/paper-en/`。用主 TeX 的标题、作者或 README 二次核验身份；不一致时停止。
+3. 将英文源码内容完整复制到 `latex/paper-zh/`，不得多套一层目录；此后只修改中文副本。分别定位中英文入口文件。
+4. 先完成中文入口的 XeLaTeX/ctex 改造和模板可见字符串本地化，再生成翻译任务。通常加入 `\usepackage[UTF8,fontset=fandol]{ctex}`，移除仅适用于 pdfLaTeX 的 `inputenc` 和 T1 `fontenc`。生成任务后、合并任务前不要再编辑中文 TeX 源码，合并器会检查快照。
+5. 生成紧凑任务包。脚本包含入口文件，因此单文件论文也能按片段并行；它自动省略参考文献，并用可逆占位符保护公式、引用、URL、代码和注释：
 
-```bash
-python3 scripts/prepare_tex_runtime.py --preset \
-  --kpsewhich <shared-tex-root>/bin/<platform>/kpsewhich \
-  --tlmgr <shared-tex-root>/bin/<platform>/tlmgr --install
-```
-
-预装清单位于 `references/paper-translation-packages.txt`，覆盖 XeLaTeX 中文排版、BibTeX/Biber、常见数学与字体、表格、算法、代码、绘图、caption，以及 ACM、IEEE、Elsevier、Springer 模板。首次安装需要联网；后续任务先离线检查，只有论文特有依赖缺失时才联网批量补装。不要安装 `scheme-full`。
-
-## 快速流水线
-
-1. 从 arXiv 摘要页或 API 核验规范化 ID、完整标题、作者、摘要、版本和日期。简称不是唯一标识。只有一个候选与用户主题高度一致时才继续，否则先让用户确认。明确告知用户“标题 + 作者 + arXiv ID”。
-2. 确定并校验 `paper-name`，运行 `scripts/prepare_output_layout.py`。从 `https://export.arxiv.org/e-print/<ID>` 下载原始压缩包到 `latex/source.tar`，解压到 `latex/paper-en/`。用主 TeX 的 `\title{}`、作者或 README 做第二次身份核验；不一致时停止。
-3. 将 `latex/paper-en/` 的全部内容完整复制到 `latex/paper-zh/`，不得产生 `latex/paper-zh/paper-en/` 额外嵌套；此后只修改中文副本。分别定位英文和中文入口文件。
-4. 立即并行启动两条路径：
+   ```bash
+   python3 scripts/translation_tasks.py prepare \
+     arxiv-paper/<paper-name>/latex/paper-zh \
+     --entry main.tex --workers 3 --json
+   ```
 
-   - 翻译路径：按可见英文词量生成均衡文件分片；正文较多时占满可用 subagent 槽位。每个代理只能编辑明确分配的文件。
-   - 构建路径：主代理同时本地化入口/样式文件、准备中文字体并预检 TeX 依赖。不要等待翻译结束后才开始配置编译。
+   默认 `--workers 3` 是上限；小论文会自动减少 worker，避免启动开销。只有需要改变速度/上下文折中才调整 `--chunk-words` 或 `--min-words-per-worker`。
+6. 每个 `worker-*.task` 只交给一个 worker。支持隔离上下文时使用空/最小历史，而不是复制完整会话；任务提示只需：
 
-   ```bash
-   python3 scripts/inventory_and_shard.py arxiv-paper/<paper-name>/latex/paper-zh --entry main.tex --workers 3 --json
-   python3 scripts/prepare_tex_runtime.py arxiv-paper/<paper-name>/latex/paper-zh --preset --kpsewhich /path/to/kpsewhich
+   ```text
+   翻译 <packet> 的全部 SOURCE 区块，把译文填入对应 TRANSLATION 区块。
+   严格遵守文件头规则，只编辑该任务包，不读取或修改论文源码。
    ```
 
-5. 若依赖缺失，使用同一脚本增加 `--tlmgr /path/to/tlmgr --install`，在一次 `tlmgr` 调用中补齐预装包和论文特有包；不得逐个安装。优先复用共享运行时。只有不存在可用运行时时才在可写缓存目录安装便携 TinyTeX；不得使用 `sudo`、`scheme-full` 或完整 TeX Live collection。
-6. 主代理修改入口文件以支持 XeLaTeX 中文排版，通常使用 `\usepackage[UTF8,fontset=fandol]{ctex}`。删除仅适用于 pdfLaTeX 的 `inputenc` 和 T1 `fontenc`。本地化模板硬编码的 `Abstract`、`References`、`Keywords` 等可见字符串。
-7. 翻译所有渲染的英文自然语言：标题、摘要、正文、章节标题、列表、脚注、表头、表注和 caption。保留公式、数学符号、数值、引用键、label/ref、URL、LaTeX 结构、人名、模型名、数据集名、缩写与通行技术标识。图片只翻译必要 caption；算法/代码只翻译自然语言注释、docstring、caption 和说明。参考文献元数据默认不翻译。
-8. 子代理完成后，主代理只运行一次全局审计并人工复核全部命中；不得仅扫描顶层章节，也不得把子代理的自检当作最终证明：
+   Worker 不需要读取本 Skill、整篇论文或其他任务包。不同 worker 并行编辑各自任务包；不支持 subagent 时顺序处理。主 agent 同时编译英文版、检查中文依赖，但不修改已快照的中文 TeX。
+7. Worker 完成后只运行一次合并。合并器先整体校验任务完整性、占位符、LaTeX 结构和源文件哈希，任何错误都会在写文件前停止：
 
    ```bash
+   python3 scripts/translation_tasks.py status arxiv-paper/<paper-name>/latex/paper-zh
+   python3 scripts/translation_tasks.py apply arxiv-paper/<paper-name>/latex/paper-zh
    python3 scripts/audit_tex_translation.py arxiv-paper/<paper-name>/latex/paper-zh
    ```
 
-9. 先使用原论文声明或兼容的构建引擎编译 `latex/paper-en/`，确保英文源码、参考文献和交叉引用收敛。再使用自动构建脚本识别 BibTeX/Biber，并完成中文 XeLaTeX 收敛：
+   `status` 未完成时只返工列出的任务；`apply` 报错时只检查对应 segment，不重新读取或重译全部论文。主 agent 必须人工复核全局审计命中。
+8. 使用原论文声明或兼容引擎编译英文源码。中文使用自动构建脚本识别 BibTeX/Biber 并完成 XeLaTeX 收敛：
 
    ```bash
-   python3 scripts/build_and_check.py arxiv-paper/<paper-name>/latex/paper-zh/main.tex --tex-bin /path/to/tex/bin
+   python3 scripts/build_and_check.py \
+     arxiv-paper/<paper-name>/latex/paper-zh/main.tex --tex-bin /path/to/tex/bin
    ```
 
-   若仍报告缺包，一次批量安装全部新缺失项后重试。不得接受 LaTeX 错误、未定义引用/citation 或缺失字符。
-10. 分别低分辨率渲染中英文 PDF 的全部页面生成联系表，检查裁切、重叠、表格溢出、图片和页数；只对可疑页面高分辨率渲染。另用能正确显示 CJK 的系统 PDF 引擎抽查中文字体。Poppler 缺少 CMap 时不得把空白中文误判为正常。
-11. 将英文成品复制为 `paper-en/<paper-name>-en.pdf`，将中文成品复制为 `paper-zh/<paper-name>-zh.pdf`。回复列出完整标题、作者、arXiv ID、`latex/paper-en/`、`latex/paper-zh/` 以及两个 PDF 的绝对路径。
+9. 分别低分辨率渲染中英文 PDF 的全部页面并检查裁切、重叠、溢出、图片和页数；只对可疑页面高分辨率渲染。另用支持 CJK 的系统 PDF 引擎抽查中文字体。Poppler 缺少 CMap 时不得把空白中文误判为正常。
+10. 将英文成品复制为 `paper-en/<paper-name>-en.pdf`，中文成品复制为 `paper-zh/<paper-name>-zh.pdf`。回复列出论文身份、两套源码目录和两个 PDF 的绝对路径。
 
-## 并行规则
+## 翻译边界
 
-- 分片前先创建 `latex/paper-zh/`，并按脚本的权重而非文件数分配。
-- 入口文件、共享宏和样式只由主代理修改；任何文件不得由两个代理同时编辑。
-- 主代理在翻译进行时完成依赖预检、字体方案和编译入口改造。
-- 共享运行时只建立一次；论文任务不得重复下载或复制相同运行时。
-- 对小论文不强制派发代理；代理启动与合并开销高于预计翻译时间时直接处理。
+- 翻译标题、摘要、正文、章节标题、列表、脚注、表头、表注和 caption。
+- 保留公式、数学符号、数值、引用键、label/ref、URL、LaTeX 结构、人名、模型名、数据集名、缩写与通行技术标识。
+- 图片内部文字默认不修改；算法和代码块（含内嵌注释/docstring）默认保持原样，只翻译 caption 与外部说明。用户明确要求时再单独处理代码内文本。
+- 参考文献元数据保持原文；`.bib`、`.bbl`、内嵌 bibliography 环境和独立参考文献 TeX 文件均不进入任务包。
+- 不把完整 TeX 内容粘贴进 agent 提示，不让 worker 直接编辑论文文件，也不让多个 worker 处理同一任务包。
 
-## 完成标准
+## 共享 TeX 运行时
+
+优先复用固定位置的 TinyTeX/TeX Live。首次建立或主动刷新时，使用 `references/paper-translation-packages.txt` 一次检查并批量安装，不安装 `scheme-full`：
+
+```bash
+python3 scripts/prepare_tex_runtime.py --preset \
+  --kpsewhich <shared-tex-root>/bin/<platform>/kpsewhich \
+  --tlmgr <shared-tex-root>/bin/<platform>/tlmgr --install
+```
 
-- arXiv 元数据与源码身份两次核验通过，原始源码未修改。
-- 英文与中文源码分别完整位于 `latex/paper-en/` 和 `latex/paper-zh/`，原始压缩包位于 `latex/source.tar`；渲染的英文自然语言均已翻译或被人工判定为允许保留项。
-- `paper-en/<paper-name>-en.pdf` 与 `paper-zh/<paper-name>-zh.pdf` 均构建成功，参考文献和交叉引用收敛；中文版无缺字。
-- 中英文 PDF 的全部页面均已检查，中文字体由 CJK 能力正常的渲染器确认。
+后续先离线检查；论文特有依赖缺失时再用同一脚本和一次 `tlmgr` 调用批量补装。只有没有可用运行时时才在可写缓存目录建立便携 TinyTeX，不使用 `sudo`。
+
+## 完成标准
 
-## 方案参考
+- arXiv 元数据与源码身份两次核验通过，`latex/paper-en/` 未修改。
+- 中文任务全部合并，全局漏译审计已人工复核；所有可见自然语言均已翻译或明确允许保留。
+- 中英文 PDF 均构建成功，参考文献和交叉引用收敛，中文版无缺字。
+- 中英文 PDF 全部页面均已检查，中文字体经 CJK 能力正常的渲染器确认。
 
-本 Skill 的论文中文化方案参考了科学空间文章：[《让 AI 翻译一篇完整的论文》](https://spaces.ac.cn/archives/11578)。具体实现结合 Codex 的并行代理、依赖缓存、自动审计和 XeLaTeX 构建流程进行了调整。
+方案参考科学空间文章[《让 AI 翻译一篇完整的论文》](https://spaces.ac.cn/archives/11578)，并结合紧凑任务包、并行 agent、依赖缓存和自动审计实现。

package/skills/arxiv-paper-zh/scripts/audit_tex_translation.py

@@ -7,13 +7,19 @@ import argparse
 import re
 from pathlib import Path
 
+from tex_translation_utils import is_bibliography_file, mask_bibliography
+
 
 PROSE = re.compile(r"[A-Za-z]{4,}(?:[ \t]+[A-Za-z][A-Za-z'’-]{2,}){2,}")
 COMMAND_ONLY = re.compile(r"^[ \t]*\\(?:usepackage|documentclass|input|include|addbibresource)\b")
 
 
 def tex_files(root: Path) -> list[Path]:
-    return sorted(path for path in root.rglob("*.tex") if path.is_file())
+    return sorted(
+        path
+        for path in root.rglob("*.tex")
+        if path.is_file() and not is_bibliography_file(path)
+    )
 
 
 def visible_part(line: str) -> str:
@@ -45,7 +51,8 @@ def main() -> int:
 
     hits = 0
     for path in files:
-        for number, raw in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
+        text = mask_bibliography(path.read_text(encoding="utf-8", errors="replace"))
+        for number, raw in enumerate(text.splitlines(), 1):
             line = visible_part(raw)
             if not line.strip() or COMMAND_ONLY.match(line):
                 continue

package/skills/arxiv-paper-zh/scripts/inventory_and_shard.py

@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
-"""Inventory reachable TeX sources and greedily balance translation shards."""
+"""Inventory translatable TeX sources and greedily balance translation shards."""
 from __future__ import annotations
 import argparse, json, re
 from pathlib import Path
+
+from tex_translation_utils import is_bibliography_file, mask_bibliography
+
 INCLUDE = re.compile(r"\\(?:input|include)\s*\{([^}]+)\}")
 COMMENT = re.compile(r"(?<!\\)%.*$")
 COMMAND = re.compile(r"\\[A-Za-z@]+\*?(?:\[[^]]*\])?")
@@ -13,17 +16,19 @@ def reachable(entry: Path, root: Path) -> list[Path]:
         path = pending.pop()
         if path in seen or not path.is_file() or (root not in path.parents and path != root): continue
         seen.add(path)
-        for value in INCLUDE.findall(path.read_text(encoding="utf-8", errors="replace")):
+        text = mask_bibliography(path.read_text(encoding="utf-8", errors="replace"))
+        for value in INCLUDE.findall(text):
             child = (path.parent / value.strip()).resolve()
             pending.append(child if child.suffix else child.with_suffix(".tex"))
     return sorted(seen)
 def weight(path: Path) -> int:
-    text = "\n".join(COMMENT.sub("", line) for line in path.read_text(encoding="utf-8", errors="replace").splitlines())
+    text = mask_bibliography(path.read_text(encoding="utf-8", errors="replace"))
+    text = "\n".join(COMMENT.sub("", line) for line in text.splitlines())
     return len(re.findall(r"[A-Za-z]{2,}", COMMAND.sub("", MATH.sub("", text))))
 def main() -> int:
     parser = argparse.ArgumentParser(); parser.add_argument("root", type=Path); parser.add_argument("--entry", type=Path); parser.add_argument("--workers", type=int, default=3); parser.add_argument("--min-weight", type=int, default=1); parser.add_argument("--json", action="store_true"); args = parser.parse_args()
     root = args.root.resolve(); entry = (root / args.entry).resolve() if args.entry else None
-    files = reachable(entry, root) if entry else sorted(root.rglob("*.tex")); shared = {"macro.tex", "macros.tex", "commands.tex"}; records = [(p, weight(p)) for p in files if p.is_file() and p != entry and p.name.lower() not in shared]; records = [(p, score) for p, score in records if score >= args.min_weight]
+    files = reachable(entry, root) if entry else sorted(root.rglob("*.tex")); shared = {"macro.tex", "macros.tex", "commands.tex"}; records = [(p, weight(p)) for p in files if p.is_file() and p != entry and p.name.lower() not in shared and not is_bibliography_file(p)]; records = [(p, score) for p, score in records if score >= args.min_weight]
     groups = [[] for _ in range(max(1, args.workers))]; totals = [0] * len(groups)
     for path, score in sorted(records, key=lambda item: item[1], reverse=True):
         index = min(range(len(groups)), key=totals.__getitem__); groups[index].append((path, score)); totals[index] += score

package/skills/arxiv-paper-zh/scripts/tex_translation_utils.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Shared helpers for excluding bibliography content from translation work."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+_BIBLIOGRAPHY_ENVIRONMENT = re.compile(
+    r"\\begin\s*\{(?P<name>thebibliography|biblist|references)\}"
+    r".*?"
+    r"\\end\s*\{(?P=name)\}",
+    re.IGNORECASE | re.DOTALL,
+)
+_BIBLIOGRAPHY_HEADING = re.compile(
+    r"\\(?P<level>chapter|section)\*?\s*"
+    r"(?:\[[^]]*\]\s*)?"
+    r"\{\s*(?:references|bibliography|literature\s+cited)\s*\}"
+    r".*?"
+    r"(?="
+    r"\\(?:chapter|section)\*?\s*(?:\[[^]]*\]\s*)?\{"
+    r"|\\end\s*\{document\}"
+    r"|\Z)",
+    re.IGNORECASE | re.DOTALL,
+)
+_BIBITEM_BLOCK = re.compile(
+    r"^[ \t]*\\bibitem(?:\[[^]]*\])?\s*\{[^}]*\}.*?"
+    r"(?="
+    r"^[ \t]*\\bibitem(?:\[[^]]*\])?\s*\{"
+    r"|^[ \t]*\\end\s*\{thebibliography\}"
+    r"|\Z)",
+    re.IGNORECASE | re.MULTILINE | re.DOTALL,
+)
+_BIBLIOGRAPHY_CONTROL = re.compile(
+    r"^[ \t]*\\(?:"
+    r"addbibresource|bibliography|bibliographystyle|printbibliography"
+    r")\b"
+    r"|^[ \t]*\\renewcommand\s*\{\\(?:bibname|refname)\}",
+    re.IGNORECASE,
+)
+_BIBLIOGRAPHY_EXACT_NAMES = {
+    "bib",
+    "biblio",
+    "bibliography",
+    "bibliographies",
+    "ref",
+    "refs",
+    "reference",
+    "references",
+}
+_BIBLIOGRAPHY_NAME_PARTS = {
+    "bib",
+    "biblio",
+    "bibliography",
+    "bibliographies",
+    "refs",
+    "references",
+}
+
+
+def _blank(match: re.Match[str]) -> str:
+    """Mask content without changing line numbers."""
+    return re.sub(r"[^\n]", " ", match.group(0))
+
+
+def mask_bibliography(text: str) -> str:
+    """Blank bibliography regions and controls while preserving newlines."""
+    text = _BIBLIOGRAPHY_ENVIRONMENT.sub(_blank, text)
+    text = _BIBLIOGRAPHY_HEADING.sub(_blank, text)
+    text = _BIBITEM_BLOCK.sub(_blank, text)
+    return "\n".join(
+        "" if _BIBLIOGRAPHY_CONTROL.match(line) else line
+        for line in text.split("\n")
+    )
+
+
+def is_bibliography_file(path: Path) -> bool:
+    """Recognize common filenames used only for reference lists."""
+    stem = path.stem.lower()
+    if stem in _BIBLIOGRAPHY_EXACT_NAMES:
+        return True
+    parts = {part for part in re.split(r"[-_.]+", stem) if part}
+    return bool(parts & _BIBLIOGRAPHY_NAME_PARTS)

package/skills/arxiv-paper-zh/scripts/translation_tasks.py

@@ -0,0 +1,594 @@
+#!/usr/bin/env python3
+"""Prepare compact TeX translation packets and safely merge their results."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter, defaultdict
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import re
+import tempfile
+from typing import Iterable, Optional
+
+from tex_translation_utils import is_bibliography_file, mask_bibliography
+
+
+VERSION = 1
+DEFAULT_TASK_DIR = ".translation-tasks"
+INCLUDE = re.compile(r"\\(?:input|include)\s*\{([^}]+)\}")
+COMMENT = re.compile(r"(?<!\\)%[^\n]*")
+COMMAND = re.compile(r"\\(?:[A-Za-z@]+\*?|.)")
+WORD = re.compile(r"[A-Za-z][A-Za-z'’-]*")
+PLACEHOLDER = re.compile(r"⟪T\d{4}⟫")
+TEXT_COMMAND = re.compile(
+    r"\\(?:title|subtitle|chapter|section|subsection|subsubsection|paragraph|"
+    r"subparagraph|caption|footnote|thanks|keyword|keywords)\*?\b",
+    re.IGNORECASE,
+)
+CONTROL_ONLY = re.compile(
+    r"^[ \t]*\\(?:documentclass|usepackage|RequirePackage|input|include|"
+    r"addbibresource|bibliography|bibliographystyle|includegraphics|label|"
+    r"setlength|newcommand|renewcommand|providecommand|def)\b",
+    re.IGNORECASE,
+)
+NON_TEXT_COMMAND = re.compile(
+    r"\\(?:documentclass|usepackage|RequirePackage|input|include|"
+    r"addbibresource|bibliography|bibliographystyle|includegraphics|label|"
+    r"ref|eqref|pageref|autoref|cite\w*|url|path)\*?"
+    r"(?:\s*\[[^]]*\])*\s*\{[^{}]*\}",
+    re.IGNORECASE,
+)
+MATH_ENVIRONMENT = re.compile(
+    r"\\begin\s*\{(?P<name>equation\*?|align\*?|alignat\*?|gather\*?|"
+    r"multline\*?|displaymath|math|eqnarray\*?)\}.*?"
+    r"\\end\s*\{(?P=name)\}",
+    re.IGNORECASE | re.DOTALL,
+)
+VERBATIM_ENVIRONMENT = re.compile(
+    r"\\begin\s*\{(?P<name>verbatim\*?|lstlisting|minted)\}.*?"
+    r"\\end\s*\{(?P=name)\}",
+    re.IGNORECASE | re.DOTALL,
+)
+DISPLAY_MATH = re.compile(r"\$\$.*?\$\$|\\\[.*?\\\]", re.DOTALL)
+INLINE_MATH = re.compile(r"(?<!\\)\$(?!\$).*?(?<!\\)\$|\\\(.*?\\\)", re.DOTALL)
+VERB = re.compile(r"\\verb(?P<delimiter>[^A-Za-z0-9\s]).*?(?P=delimiter)")
+REFERENCE_COMMAND = re.compile(
+    r"\\(?:cite\w*|ref|eqref|pageref|autoref|label|url|path|"
+    r"includegraphics|input|include)\*?(?:\s*\[[^]]*\])*\s*\{[^{}]*\}",
+    re.IGNORECASE,
+)
+HREF_TARGET = re.compile(r"\\href\s*\{[^{}]*\}", re.IGNORECASE)
+PACKET_BLOCK = re.compile(
+    r"^@@@ SEGMENT (?P<id>\S+)\n"
+    r"^@@@ SOURCE\n(?P<source>.*?)"
+    r"^@@@ TRANSLATION\n(?P<translation>.*?)"
+    r"^@@@ END(?:\n|\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+
+PACKET_HEADER = """# 只在每个 TRANSLATION 区块填写简体中文译文；不要改 SOURCE 或标记行。
+# 严格保留 LaTeX 结构及每个 ⟪T0000⟫ 形式的占位符；保留人名、模型名、数据集名、缩写、数值和引用键。
+"""
+
+
+def _inside(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def reachable(entry: Path, root: Path) -> list[Path]:
+    """Return TeX files reachable through input/include, including the entry."""
+    pending = [entry.resolve()]
+    seen: set[Path] = set()
+    while pending:
+        path = pending.pop()
+        if path in seen or not path.is_file() or not _inside(path, root):
+            continue
+        seen.add(path)
+        text = mask_bibliography(path.read_text(encoding="utf-8", errors="replace"))
+        for value in INCLUDE.findall(text):
+            child = (path.parent / value.strip()).resolve()
+            pending.append(child if child.suffix else child.with_suffix(".tex"))
+    return sorted(seen)
+
+
+def _without_protected_text(text: str) -> str:
+    for pattern in (
+        VERBATIM_ENVIRONMENT,
+        MATH_ENVIRONMENT,
+        COMMENT,
+        DISPLAY_MATH,
+        INLINE_MATH,
+        VERB,
+        REFERENCE_COMMAND,
+        HREF_TARGET,
+    ):
+        text = pattern.sub(" ", text)
+    return text
+
+
+def english_weight(text: str) -> int:
+    """Estimate visible English prose words, excluding common TeX controls."""
+    text = NON_TEXT_COMMAND.sub(" ", _without_protected_text(text))
+    text = COMMAND.sub(" ", text)
+    return len([word for word in WORD.findall(text) if len(word) > 1])
+
+
+def _is_translatable(text: str) -> bool:
+    score = english_weight(text)
+    return score >= 3 or (score >= 1 and bool(TEXT_COMMAND.search(text) or "&" in text))
+
+
+def _protect(source: str) -> tuple[str, list[dict[str, str]]]:
+    """Replace expensive immutable spans with checked, reversible placeholders."""
+    protected: list[dict[str, str]] = []
+    masked = source
+
+    def replace(match: re.Match[str]) -> str:
+        placeholder = f"⟪T{len(protected):04d}⟫"
+        protected.append({"placeholder": placeholder, "value": match.group(0)})
+        return placeholder
+
+    for pattern in (
+        VERBATIM_ENVIRONMENT,
+        MATH_ENVIRONMENT,
+        COMMENT,
+        DISPLAY_MATH,
+        INLINE_MATH,
+        VERB,
+        REFERENCE_COMMAND,
+        HREF_TARGET,
+    ):
+        masked = pattern.sub(replace, masked)
+    return masked, protected
+
+
+def _paragraph_ranges(masked_text: str) -> Iterable[tuple[int, int]]:
+    """Yield zero-based, end-exclusive line ranges separated by hard controls."""
+    lines = masked_text.splitlines(keepends=True)
+    start: Optional[int] = None
+    for index, line in enumerate(lines):
+        separator = not line.strip() or bool(CONTROL_ONLY.match(line))
+        if separator:
+            if start is not None:
+                yield start, index
+                start = None
+        elif start is None:
+            start = index
+    if start is not None:
+        yield start, len(lines)
+
+
+def _chunk_range(
+    lines: list[str], start: int, end: int, chunk_words: int
+) -> Iterable[tuple[int, int]]:
+    cursor = start
+    score = 0
+    for index in range(start, end):
+        score += english_weight(lines[index])
+        if score >= chunk_words and index + 1 < end:
+            yield cursor, index + 1
+            cursor = index + 1
+            score = 0
+    if cursor < end:
+        yield cursor, end
+
+
+def segments_for(path: Path, root: Path, chunk_words: int) -> list[dict[str, object]]:
+    original = path.read_text(encoding="utf-8", errors="replace")
+    bibliography_masked = mask_bibliography(original)
+    original_lines = original.splitlines(keepends=True)
+    masked_lines = bibliography_masked.splitlines(keepends=True)
+    units: list[tuple[int, int, int]] = []
+
+    for paragraph_start, paragraph_end in _paragraph_ranges(bibliography_masked):
+        for start, end in _chunk_range(
+            masked_lines, paragraph_start, paragraph_end, chunk_words
+        ):
+            visible = "".join(masked_lines[start:end])
+            if not _is_translatable(visible):
+                continue
+            units.append((start, end, english_weight(visible)))
+
+    merged: list[list[int]] = []
+    for start, end, score in units:
+        if merged:
+            previous = merged[-1]
+            gap = "".join(original_lines[previous[1] : start])
+            if not gap.strip() and previous[2] + score <= chunk_words:
+                previous[1] = end
+                previous[2] += score
+                continue
+        merged.append([start, end, score])
+
+    segments: list[dict[str, object]] = []
+    for start, end, score in merged:
+        source = "".join(original_lines[start:end])
+        masked_source, protected = _protect(source)
+        packet_source = (
+            masked_source if masked_source.endswith("\n") else masked_source + "\n"
+        )
+        relative = str(path.relative_to(root))
+        identity = f"{relative}:{start + 1}:{end}:".encode() + source.encode()
+        segment_id = "s" + hashlib.sha256(identity).hexdigest()[:12]
+        segments.append(
+            {
+                "id": segment_id,
+                "path": relative,
+                "start_line": start + 1,
+                "end_line": end,
+                "weight": score,
+                "source": source,
+                "source_sha256": hashlib.sha256(source.encode()).hexdigest(),
+                "packet_source": packet_source,
+                "protected": protected,
+            }
+        )
+    return segments
+
+
+def _allocate(
+    segments: list[dict[str, object]], requested_workers: int, min_words: int
+) -> list[list[dict[str, object]]]:
+    total = sum(int(segment["weight"]) for segment in segments)
+    useful_workers = max(1, math.ceil(total / max(1, min_words)))
+    count = min(max(1, requested_workers), useful_workers, max(1, len(segments)))
+    groups: list[list[dict[str, object]]] = [[] for _ in range(count)]
+    totals = [0] * count
+    for segment in sorted(segments, key=lambda item: int(item["weight"]), reverse=True):
+        index = min(range(count), key=totals.__getitem__)
+        groups[index].append(segment)
+        totals[index] += int(segment["weight"])
+    for group in groups:
+        group.sort(key=lambda item: (str(item["path"]), int(item["start_line"])))
+    return groups
+
+
+def _packet_text(segments: list[dict[str, object]]) -> str:
+    parts = [PACKET_HEADER]
+    for segment in segments:
+        parts.extend(
+            [
+                f"@@@ SEGMENT {segment['id']}\n",
+                "@@@ SOURCE\n",
+                str(segment["packet_source"]),
+                "@@@ TRANSLATION\n",
+                "@@@ END\n",
+            ]
+        )
+    return "".join(parts)
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        "w", encoding="utf-8", dir=path.parent, delete=False
+    )
+    temporary = Path(handle.name)
+    try:
+        with handle:
+            handle.write(text)
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()
+
+
+def prepare(args: argparse.Namespace) -> int:
+    root = args.root.resolve()
+    if not root.is_dir():
+        raise SystemExit(f"paper root does not exist: {root}")
+    task_dir = (root / args.output).resolve()
+    if not _inside(task_dir, root):
+        raise SystemExit(f"task directory must stay below paper root: {task_dir}")
+    manifest_path = task_dir / "manifest.json"
+    if manifest_path.exists() and not args.force:
+        raise SystemExit(f"task manifest already exists: {manifest_path}; use --force")
+    if args.force and task_dir.is_dir():
+        for stale_packet in task_dir.glob("worker-*.task"):
+            stale_packet.unlink()
+
+    if args.entry:
+        entry = (root / args.entry).resolve()
+        if not entry.is_file():
+            raise SystemExit(f"entry file does not exist: {entry}")
+        files = reachable(entry, root)
+    else:
+        entry = None
+        files = sorted(root.rglob("*.tex"))
+    files = [path for path in files if path.is_file() and not is_bibliography_file(path)]
+    segments = [
+        segment
+        for path in files
+        for segment in segments_for(path, root, args.chunk_words)
+    ]
+    if not segments:
+        raise SystemExit(f"no translatable TeX prose found below {root}")
+
+    groups = _allocate(segments, args.workers, args.min_words_per_worker)
+    packets = []
+    for index, group in enumerate(groups, 1):
+        name = f"worker-{index:02d}.task"
+        _write_atomic(task_dir / name, _packet_text(group))
+        packets.append(
+            {
+                "worker": index,
+                "path": name,
+                "weight": sum(int(segment["weight"]) for segment in group),
+                "segments": [str(segment["id"]) for segment in group],
+            }
+        )
+
+    scanned_bytes = sum(path.stat().st_size for path in files)
+    selected_bytes = sum(len(str(segment["source"]).encode()) for segment in segments)
+    packet_source_bytes = sum(
+        len(str(segment["packet_source"]).encode()) for segment in segments
+    )
+    reduction = (
+        round(100 * (1 - packet_source_bytes / scanned_bytes), 1)
+        if scanned_bytes
+        else 0.0
+    )
+    manifest = {
+        "version": VERSION,
+        "root": str(root),
+        "entry": str(entry.relative_to(root)) if entry else None,
+        "packets": packets,
+        "segments": segments,
+        "metrics": {
+            "files": len(files),
+            "segments": len(segments),
+            "workers": len(groups),
+            "visible_english_words": sum(int(segment["weight"]) for segment in segments),
+            "scanned_bytes": scanned_bytes,
+            "selected_bytes": selected_bytes,
+            "packet_source_bytes": packet_source_bytes,
+            "input_byte_reduction_percent": reduction,
+        },
+    }
+    _write_atomic(manifest_path, json.dumps(manifest, ensure_ascii=False, indent=2) + "\n")
+    public_packets = [
+        {
+            "worker": packet["worker"],
+            "path": packet["path"],
+            "weight": packet["weight"],
+            "segments": len(packet["segments"]),
+        }
+        for packet in packets
+    ]
+    payload = {
+        "task_dir": str(task_dir),
+        **manifest["metrics"],
+        "packets": public_packets,
+    }
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(
+            f"prepared {len(segments)} segments for {len(groups)} worker(s); "
+            f"estimated input reduction {reduction:.1f}%"
+        )
+        for packet in packets:
+            print(f"{packet['path']}: words={packet['weight']} segments={len(packet['segments'])}")
+    return 0
+
+
+def parse_packet(path: Path) -> dict[str, dict[str, str]]:
+    text = path.read_text(encoding="utf-8")
+    result: dict[str, dict[str, str]] = {}
+    for match in PACKET_BLOCK.finditer(text):
+        segment_id = match.group("id")
+        if segment_id in result:
+            raise ValueError(f"duplicate segment {segment_id} in {path}")
+        result[segment_id] = {
+            "source": match.group("source"),
+            "translation": match.group("translation"),
+        }
+    return result
+
+
+def _load_manifest(root: Path, output: Path) -> tuple[Path, dict[str, object]]:
+    task_dir = (root / output).resolve()
+    if not _inside(task_dir, root):
+        raise SystemExit(f"task directory must stay below paper root: {task_dir}")
+    manifest_path = task_dir / "manifest.json"
+    if not manifest_path.is_file():
+        raise SystemExit(f"task manifest does not exist: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("version") != VERSION:
+        raise SystemExit(f"unsupported task manifest version: {manifest.get('version')}")
+    return task_dir, manifest
+
+
+def _read_results(
+    task_dir: Path, manifest: dict[str, object]
+) -> tuple[dict[str, dict[str, str]], list[str]]:
+    results: dict[str, dict[str, str]] = {}
+    errors: list[str] = []
+    for packet in manifest["packets"]:  # type: ignore[index]
+        packet_path = task_dir / packet["path"]
+        try:
+            parsed = parse_packet(packet_path)
+        except (OSError, ValueError) as error:
+            errors.append(str(error))
+            continue
+        for segment_id, value in parsed.items():
+            if segment_id in results:
+                errors.append(f"duplicate result for {segment_id}")
+            results[segment_id] = value
+    return results, errors
+
+
+def status(args: argparse.Namespace) -> int:
+    root = args.root.resolve()
+    task_dir, manifest = _load_manifest(root, args.output)
+    results, errors = _read_results(task_dir, manifest)
+    expected = {str(segment["id"]) for segment in manifest["segments"]}  # type: ignore[index]
+    completed = {
+        segment_id
+        for segment_id, value in results.items()
+        if value["translation"].strip()
+    }
+    missing = sorted(expected - completed)
+    payload = {
+        "segments": len(expected),
+        "completed": len(expected) - len(missing),
+        "missing": missing,
+        "errors": errors,
+    }
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"completed={payload['completed']}/{payload['segments']}")
+        for error in errors:
+            print(f"error: {error}")
+        for segment_id in missing:
+            print(f"missing: {segment_id}")
+    return 0 if not missing and not errors else 1
+
+
+def _restore(translation: str, protected: list[dict[str, str]]) -> str:
+    for item in protected:
+        translation = translation.replace(item["placeholder"], item["value"])
+    return translation
+
+
+def _structure_signature(text: str) -> tuple[Counter[str], int, int]:
+    return Counter(COMMAND.findall(text)), text.count("{"), text.count("}")
+
+
+def apply(args: argparse.Namespace) -> int:
+    root = args.root.resolve()
+    task_dir, manifest = _load_manifest(root, args.output)
+    results, errors = _read_results(task_dir, manifest)
+    replacements: defaultdict[Path, list[tuple[int, int, str]]] = defaultdict(list)
+    expected_sources = {
+        (str(segment["path"]), int(segment["start_line"]), int(segment["end_line"])): (
+            str(segment["source"]),
+            str(segment["source_sha256"]),
+        )
+        for segment in manifest["segments"]  # type: ignore[index]
+    }
+
+    for segment in manifest["segments"]:  # type: ignore[index]
+        segment_id = str(segment["id"])
+        result = results.get(segment_id)
+        if result is None:
+            errors.append(f"missing segment {segment_id}")
+            continue
+        if result["source"] != segment["packet_source"]:
+            errors.append(f"SOURCE was modified for {segment_id}")
+            continue
+        translation = result["translation"].lstrip("\n")
+        if not translation.strip():
+            errors.append(f"empty translation for {segment_id}")
+            continue
+        expected_placeholders = Counter(
+            item["placeholder"] for item in segment["protected"]
+        )
+        actual_placeholders = Counter(PLACEHOLDER.findall(translation))
+        if actual_placeholders != expected_placeholders:
+            errors.append(f"placeholder mismatch for {segment_id}")
+            continue
+        if _structure_signature(translation) != _structure_signature(
+            str(segment["packet_source"])
+        ):
+            errors.append(f"LaTeX structure mismatch for {segment_id}")
+            continue
+
+        source = str(segment["source"])
+        if source.endswith("\n"):
+            if not translation.endswith("\n"):
+                translation += "\n"
+        else:
+            translation = translation.rstrip("\n")
+        restored = _restore(translation, segment["protected"])
+        path = root / str(segment["path"])
+        replacements[path].append(
+            (int(segment["start_line"]), int(segment["end_line"]), restored)
+        )
+
+    for path, items in replacements.items():
+        text = path.read_text(encoding="utf-8", errors="replace")
+        lines = text.splitlines(keepends=True)
+        for start, end, _translation in items:
+            current = "".join(lines[start - 1 : end])
+            expected, expected_hash = expected_sources[
+                (str(path.relative_to(root)), start, end)
+            ]
+            if (
+                current != expected
+                or hashlib.sha256(current.encode()).hexdigest() != expected_hash
+            ):
+                errors.append(f"source changed since prepare: {path.relative_to(root)}:{start}-{end}")
+
+    if errors:
+        for error in errors:
+            print(f"error: {error}")
+        return 1
+    if args.check:
+        print(f"validated {sum(len(items) for items in replacements.values())} translations")
+        return 0
+
+    for path, items in replacements.items():
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines(keepends=True)
+        for start, end, translation in sorted(items, reverse=True):
+            lines[start - 1 : end] = [translation]
+        _write_atomic(path, "".join(lines))
+    print(
+        f"applied {sum(len(items) for items in replacements.values())} translations "
+        f"to {len(replacements)} file(s)"
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    prepare_parser = subparsers.add_parser("prepare", help="create compact worker packets")
+    prepare_parser.add_argument("root", type=Path)
+    prepare_parser.add_argument("--entry", type=Path)
+    prepare_parser.add_argument("--workers", type=int, default=3)
+    prepare_parser.add_argument("--chunk-words", type=int, default=900)
+    prepare_parser.add_argument("--min-words-per-worker", type=int, default=1200)
+    prepare_parser.add_argument("--output", type=Path, default=Path(DEFAULT_TASK_DIR))
+    prepare_parser.add_argument("--force", action="store_true")
+    prepare_parser.add_argument("--json", action="store_true")
+    prepare_parser.set_defaults(handler=prepare)
+
+    status_parser = subparsers.add_parser("status", help="report packet completion")
+    status_parser.add_argument("root", type=Path)
+    status_parser.add_argument("--output", type=Path, default=Path(DEFAULT_TASK_DIR))
+    status_parser.add_argument("--json", action="store_true")
+    status_parser.set_defaults(handler=status)
+
+    apply_parser = subparsers.add_parser("apply", help="validate and merge packet translations")
+    apply_parser.add_argument("root", type=Path)
+    apply_parser.add_argument("--output", type=Path, default=Path(DEFAULT_TASK_DIR))
+    apply_parser.add_argument("--check", action="store_true")
+    apply_parser.set_defaults(handler=apply)
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    if getattr(args, "workers", 1) < 1:
+        parser.error("--workers must be positive")
+    if getattr(args, "chunk_words", 1) < 1:
+        parser.error("--chunk-words must be positive")
+    if getattr(args, "min_words_per_worker", 1) < 1:
+        parser.error("--min-words-per-worker must be positive")
+    return int(args.handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())