Xpersona
D

doc-holmes

CLAWHUB · Unverified

Layout-preserving precise translation for large PDFs. Keeps formulas, figures, tables, TOC and annotations intact; outputs a bilingual side-by-side PDF plus a pure-translation PDF. Tier-A documents also support a zero-dependency direct mode (extract, translate, apply - no engine, no API key) and one-command setup. Every file is triaged first into tier A (clean born-digital, high fidelity), tier B (noisy text layer, translated with a noise report), tier C (scanned/image-on ly, experimental OCR channel marked preview quality). Runs the BabelDOC engine (pdf2zh-next) as a subprocess on any OpenAI-compatible endpoint you configure (bring your own key; none bundled ). Batch mode ships resume, per-file timeout, audit log and rollback. Triggers include PDF tran slation, PDF to Chinese, translate paper, bilingual PDF, side-by-side translation, keep origina l layout, layout preserved, formula preservation, scanned PDF translation, medical literature t ranslation, batch PDF translate.

62
Rank
84
Safety
961
Downloads

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 961 downloads reported by the source. Last updated 10/12/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Install and run

Setup complexity: low.

clawhub skill install s17dagtwyk21qs6vpz98bzcrh1853t29:doc-holmes
  1. Install using `clawhub skill install s17dagtwyk21qs6vpz98bzcrh1853t29:doc-holmes` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/docsor1212/doc-holmes before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-doc-holmes/snapshot"

Run-check

$0.02 USD

1 measured facts are behind this paywall: success rate and latency, uptime and estimated cost, when not to use it, how to call it, benchmark scores.

Agents pay $0.02 in USDC. A card payment is $0.50, the smallest a card allows.

Documentation

CLAWHUB

160,000 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: doc-holmes
description: >-
  Layout-preserving precise translation for large PDFs. Keeps formulas, figures, tables, TOC and annotations intact; outputs a bilingual side-by-side PDF plus a pure-translation PDF. Tier-A documents also support a zero-dependency direct mode (extract, translate, apply - no engine, no API key) and one-command setup. Every file is triaged first into tier A (clean born-digital, high fidelity), tier B (noisy text layer, translated with a noise report), tier C (scanned/image-on ly, experimental OCR channel marked preview quality). Runs the BabelDOC engine (pdf2zh-next) as a subprocess on any OpenAI-compatible endpoint you configure (bring your own key; none bundled ). Batch mode ships resume, per-file timeout, audit log and rollback. Triggers include PDF tran slation, PDF to Chinese, translate paper, bilingual PDF, side-by-side translation, keep origina l layout, layout preserved, formula preservation, scanned PDF translation, medical literature t ranslation, batch PDF translate.
license: MIT
compatibility: Requires Python 3.10+ and the pdf2zh-next engine (pip install pdf2zh-next or uv tool install pdf2zh-next). Translation uses your own OpenAI-compatible endpoint and API key (env DOC_HOLMES_OPENAI_BASE_URL + DOC_HOLMES_OPENAI_API_KEY; the free-tier glm-4.5-flash on the official Zhipu open platform works well). No credentials are bundled. The OCR channel for scanned PDFs optionally uses tesseract. Works on Linux, macOS and Windows.
metadata:
  version: "3.0.0"
  author: docsor1212
  displayName: Doc Holmes - Layout-Preserving PDF Translation
  homepage: https://skillhub.cn
---

# doc-holmes

Precise translation of foreign-language PDFs **with the original layout preserved** — formulas, figures, tables, TOC and footnotes stay intact. Output: a **bilingual side-by-side PDF** plus a **pure-translation PDF**.

## When to use

- The user hands you a foreign-language PDF (paper / guideline / report) and wants it translated **without wrecking the layout**.
- Phrases like: PDF translation, translate this paper, full-text translation, bilingual PDF, keep the original layout, formulas intact, document translation, oversized PDFs, batch PDF translation.
- The user complains that other tools "destroyed all formulas / lost figures / scrambled two-column text".

## Responsible use

Translations are AI-assisted. Have a human review before any formal use (submission, clinical, legal), and follow the AI-content labeling rules that apply to your venue. Tier-C (scanned) outputs additionally carry a preview-quality notice and must not be used formally.

## Quick start

```bash
# 0) Pre-flight triage (zero dependencies, works before the engine is installed)
doc_holmes_cli.py triage paper.pdf --json          # tier A/B/C grading - know what you can promise
doc_holmes_cli.py estimate big.pdf                 # pages/chars/partition/time estimate (no endpoint)
python3 scripts/doc_holmes_cli.py merge a.pdf b.pdf -o merged.pdf   # merge tra

README.md

# doc-holmes

[![GitHub Stars](https://img.shields.io/github/stars/docsor1212/doc-holmes?style=social&label=Star)](https://github.com/docsor1212/doc-holmes/stargazers)

保持原文排版的外文 PDF 精准翻译（triage A/B/C 分级 + BabelDOC 子进程引擎）。MIT 自有代码；AGPL 引擎（pdf2zh-next）只以子进程调用，零 vendor、零改源。

**China mirror (ModelScope 魔搭)**: <https://modelscope.cn/skills/Docsor/doc-holmes> — if you find this skill useful, a like there helps others find it.

## 开发

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python pymupdf pytest pytest-timeout
.venv/bin/python -m pytest tests/ -q          # 全套离线测试（桩引擎，数随版本增长）
.venv/bin/python -m pytest tests/ -q -k net   # 真网用例需 DOC_HOLMES_NET_TESTS=1
```

- 开发树：`src/doc_holmes/`；打包视图：`scripts/doc_holmes/`（由 `pkg` 阶段从 src 同步，断言一致）。
- 语料：`corpus/`（manifest 入库，PDF 本体 gitignore）。
- 宪章（不可违背）：**不内置任何端点/密钥，用户自带**；Coding Plan 订阅端点对分发默认拒绝（防用户封号；开发者自用需显式解锁）、AGPL 零 vendor 零改源、密钥全 env、C 级强制预览质量标注、每版发布前回归必跑。见 `plan.md` §0。

## 打包与发布

打包视图生成：`rsync -a --delete src/doc_holmes/ scripts/doc_holmes/`，随后跑五断言（双目录 pkg 脚本内嵌）。发布链走 SkillHub（中文包 SKILL_ZH.md）+ ClawHub（英文包 SKILL.md）双目录隔离。

_meta.json

{
  "ownerId": "kn7b6sjwend7cwwmhf7mdg1wzx82dfbf",
  "slug": "doc-holmes",
  "version": "3.0.0",
  "publishedAt": 1791263744008
}

references/batch-iron-rules.md

# 批量工程铁律（doc-holmes runner）

> 每条铁律都有对应用例（tests/test_runner.py），改 runner 必须全绿。

## 八条铁律

1. **realpath 归一**：所有输入/输出路径 `os.path.realpath()` 后比较与存储；黑名单匹配不受符号链接与相对路径干扰。
2. **排除目录**：`os.walk` 显式剔除 `_duplicates/ _non_pdf_assets/ __pycache__/ .git/ output/ _translated/ .venv/ node_modules/`——历史事故：把 `_duplicates` 里的旧副本一起翻了，白烧 3 小时端点配额。
3. **set 化**：黑名单、完成表一律 `set`（sha256 为 key）；列表 `in` 在千级文件上是 O(n²)。
4. **默认单进程**：`--workers N` 显式开启且 N≤4（engine 是子进程，并发过高 OOM/限流双风险；Docling 每进程 ~3GB 的教训）。
5. **每文件超时**：默认 `min(max(180, 15s×页数), 600)`；`subprocess.run(timeout=)` 到点 kill，绝不挂死批次。卡死文件进审计 `status=timeout`，批次继续。
6. **watchdog 停滞监测**：30s 一拍跟踪最近完成时刻，停滞 >300s 记入审计与报告（per-file 超时负责杀进程，watchdog 负责让停滞可见）。
7. **断点续传**：`audit.jsonl` 重放，`status=success` 且产物文件仍在 → skip。中断/Ctrl-C/崩溃后直接重跑同一条命令即可。
8. **编译门**：`python -m compileall src` 进测试链（`test_rule_8_compileall_source`），语法错误挡在发布前。

> **回滚语义**（不属于八条编号，属审计行为）：每个文件使用独立输出子目录 `outdir/<sha256[:12]>/`，失败/超时当场删除该目录内本次产生的残缺产物——并发互不波及、绝不跨文件误删（评审 P0-2 回归锁：`test_discovery_exact_stem_boundary`）。
> **C 级语义**：批量通路不自动 OCR，tier C 显式 skip（reason=tier_C_needs_ocr）；OCR 是单文件 `translate --ocr auto` 的显式决策。

## 审计格式

- 单文件：`<stem>.audit.json`（triage 全量 + 引擎结果（密钥脱敏）+ OCR 统计）。
- 批量：`audit.jsonl` 逐行一条：

```json
{"path": "papers/a.pdf", "sha256": "…", "tier": "B", "status": "success",
 "duration_s": 41.2, "dual_path": "…dual.pdf", "mono_path": "…mono.pdf",
 "chars_per_page": 2318.4, "triage_reasons": ["…"],
 "repair": {"pages": 8, "spans_duplicated": 3, "chars_duplicated": 210,
            "examples": ["…"]}, "error": null}
```

- `status ∈ success / failed / timeout / skipped`；failed/timeout 的残缺产物**当场回滚**（不留半成品）。
- 同内容 PDF（sha256 相同）按同一文件处理：续传时自动跳过副本，属刻意去重。

## 报告

`report.md` 逐文件状态表 + 末行「汇总: 总计/成功/失败/超时/跳过」——验收链 grep 依赖这一行（无「汇总」即视为批次无效）。

references/engine-matrix.md

# 引擎矩阵与版本边界（doc-holmes）

> 立场：本 skill 是自有 MIT 胶水层；AGPL 引擎只以**子进程**调用其官方 CLI，零 vendor、零改源。引擎升级必须重跑回归集后才随版发布。

## 主路径引擎

| 组件 | 版本基线 | 说明 |
|---|---|---|
| pdf2zh-next | ≥2.9（2026-05-15 起，BabelDOC IR 后端） | 官方 CLI `pdf2zh_next`；v2.0 正式版（2026-09-08）同线。锁 minor 升级需回归 |
| BabelDOC | pdf2zh-next 内置 | IR 论文 arXiv:2605.10845，**已正式发表于 ACL 2026**（稳定性背书）；DocLayout-YOLO ONNX 版面分析 |
| PyMuPDF | ≥1.24 | triage / OCR 栅格化 / 说明页插入；pip 依赖唯一 |

## 翻译端点

| 端点 / 模型 | 用途 | 状态（2026-09-20 真网实测） |
|---|---|---|
| `https://open.bigmodel.cn/api/paas/v4` + `glm-4.5-flash`（**面向用户的推荐默认**） | 智谱开放平台官方 API（用户自己的 key） | 官方合法通道；flash 档免费 |
| `https://open.bigmodel.cn/api/coding/paas/v4` + `glm-5.3-flash` 等 | **仅限开发者自用**（Coding Plan 订阅） | ✅ 实测可用，但**分发默认禁止**：订阅仅限编码工具，第三方翻译接入违反 ToS 有封号风险（配置层默认拒绝，`DOC_HOLMES_ALLOW_CODING_ENDPOINT=1` 显式解锁） |
| 同端点 + `glm-4.6` / `glm-4.7` / `glm-4.5-flash` | 旧代兜底 | ✅ 200；`glm-4.7-flash` 曾瞬时超时（HTTP 000），复测 200，遇超时先重试 |
| `https://opencode.ai/zen/go/v1` + `deepseek-v4-flash` | **多厂商实测**（OpenCode Go 套餐） | ✅ 3s 出干净译文；Go 端点需 `x-opencode-session` 头（由调用方配置，本 skill 直连标准 OpenAI 兼容 API 时无需） |
| 同上 + `kimi-k2.6` 等 reasoning 系 | ⚠️ 不推荐做翻译引擎 | 推理 token 挤占输出预算（content 为空）；翻译选非 reasoning 模型 |
| SiliconFlow 等 OpenAI 兼容端点 | 备用 | 直接配置即可，不拦 |

> **模型选型口径**：翻译质量对决用固定医学段落（利妥昔单抗/ITP），对比术语准确度与流畅度；
> 默认取"最新一代 flash 层级"，`DOC_HOLMES_MODEL` 一行即可换。注意用量：Go 等套餐测试只用
> 短段落 × 单次，不跑批量。

## OCR 通道（C 级，实验性）

| 通道 | 要求 | 状态 |
|---|---|---|
| Tesseract | `apt install tesseract-ocr`（中文加 `tesseract-ocr-chi-sim`） | ✅ 已接入（能力探测，缺语言包给安装指引） |
| PP-Structure（GPU A5000，锁 paddleocr 2.9.1） | CUDA 11.8+cuDNN 8.9 | 计划中（82 服务器，后续版本评估） |
| GLM-OCR 0.9B（OmniDocBench 94.62） | transformers + 显存 | 计划中（后续版本评估） |

## 硬件参考（2026-09-20 WSL 实测）

- RTX 3070 Laptop 8GB：DocLayout-YOLO ONNX 可跑；无 GPU 时 CPU 版面分析可用（慢 3-8 倍）。
- 16 线程 CPU / 15GB 内存：批量 `--workers ≤4` 安全上限（超过会拖垮宿主机，runner 已硬编码拒绝）。

## 已知边界

1. `pdf2zh_next` 无 `--no-config-file` 参数（那是 pdf2zh 3.x 的）；配置自动落盘属引擎行为，与本 skill 无冲突。
2. 产物命名 `<stem>.<watermark_mode>.<lang>.dual/mono.pdf`，产物发现按 stem 前缀 + mtime 最新。
3. 引擎会自动抽取术语表 `*.glossary.csv`，当前版本不注入自定义术语（后续版本计划：医学词汇表走 `--glossaries`）。
4. `--no-dual/--no-mono` 可关掉对应产物；audit 的产物发现随之可能为空，属正常。

Sponsored

Ads related to doc-holmes and adjacent AI workflows.