Skip to content
Back to search

latex-automation

SkillWorks with Claude CodeGitHub

在本机 TeX Live 上自动化 LaTeX 任务:编译出 PDF、把 .log 变成带因果排序的结构化诊断、缺包缺字体给出离线安装命令、有界修复闭环自动试改、版面量化(溢出/空洞/孤行)与渲染页面做视觉检查、chktex 静态检查与 latexindent 格式化、从模板新建工程。触发词:LaTeX、latex、TeX、XeLaTeX、pdflatex、lualatex、编译 PDF、论文编译、排版、ctex、中文 LaTeX、latexmk、biber、bibtex、参考文献、.tex、.log、编译报错、overfull、underfull、缺包、缺字体、修复编译错误、自动修 LaTeX、版面检查、孤行、寡行、空洞、模板、latexindent、chktex、渲染页面、LaTeX 自动化。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ccyk-hash--latex-automation/badge.svg)](/listings/ccyk-hash--latex-automation)

HTML

<a href="/listings/ccyk-hash--latex-automation"><img src="/api/listings/ccyk-hash--latex-automation/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 354 lines
  1. ---
  2. name: latex-automation
  3. description: 在本机 TeX Live 上自动化 LaTeX 任务:编译出 PDF、把 .log 变成带因果排序的结构化诊断、缺包缺字体给出离线安装命令、有界修复闭环自动试改、版面量化(溢出/空洞/孤行)与渲染页面做视觉检查、chktex 静态检查与 latexindent 格式化、从模板新建工程。触发词:LaTeX、latex、TeX、XeLaTeX、pdflatex、lualatex、编译 PDF、论文编译、排版、ctex、中文 LaTeX、latexmk、biber、bibtex、参考文献、.tex、.log、编译报错、overfull、underfull、缺包、缺字体、修复编译错误、自动修 LaTeX、版面检查、孤行、寡行、空洞、模板、latexindent、chktex、渲染页面、LaTeX 自动化。
  4. license: MIT
  5. compatibility: Windows(MSYS bash 调用),已在 TeX Live 2026 + Python 3.14 实测;Linux/macOS 上同样可用,只是路径与引擎探测分支不同。需要本机已装 TeX Live(含 latexmk、pdflatex、xelatex),可选 biber/bibtex/kpsewhich/pdftoppm/pdfinfo/chktex/latexindent。不联网、不自动安装任何 TeX 包。
  6. allowed-tools: Read Write Edit Bash Glob Grep
  7. metadata:
  8. version: "0.4.0"
  9. last-reviewed: "2026-11-21"
  10. skill-author: built for DeepSeek Harness from the research in docs/01-research-report.md
  11. upstream: https://github.com/ccyk-hash/latex-automation
  12. verified-on: "DSH bash + WorkBuddy PortableGit bash + TeX Live 2026 (D:/Latex/texlive/2026) + Python 3.14.7 / 3.13.14 on Windows"
  13. disable-model-invocation: false
  14. ---
  15. # latex-automation:在本机 TeX Live 上做 LaTeX 自动化
  16. 把 `.tex` 变成 PDF,把看不懂的 `.log` 变成「哪一行、什么类别、怎么修」,把缺的包变成
  17. 一条可执行的安装命令,把 PDF 渲成图给模型自己看版面。全部走本机已装的 TeX Live,**不联网**。
  18. ## 唯一入口
  19. 约定 `SKILL_DIR` = 本 skill 根目录。三条等价入口,任选其一:
  20. ```bash
  21. # 本 skill 的根目录,选你实际装的那一处
  22. SKILL_DIR="${LATEX_SKILL_DIR:-$HOME/.dsh/skills/latex-automation}" # DeepSeek Harness
  23. # SKILL_DIR="$HOME/.workbuddy/skills/latex-automation" # WorkBuddy
  24. # 1) 包装脚本(推荐,自带 PYTHONPATH / UTF-8 / max_print_line 环境)
  25. bash "$SKILL_DIR/bin/latex-build" <项目目录>
  26. # 2) 直接跑模块
  27. PYTHONPATH="$SKILL_DIR" python -m latex_automation build <项目目录>
  28. # 3) 已把 bin/ 加进 PATH 时
  29. latex-build <项目目录>
  30. ```
  31. 包装脚本会自动挑一个**真能跑**的 Python(`python` → WorkBuddy 托管解释器 → `python3`
  32. → `py`,逐个实跑验证,跳过 Microsoft Store 的 python3 存根)。需要指定解释器就设
  33. `LATEX_SKILL_PYTHON`。Windows 上 `bin/*.sh` 用 Git Bash / MSYS bash 执行即可
  34. (WorkBuddy 自带 PortableGit,DSH 自带 bash)。
  35. ## 子命令一览
  36. | 命令 | 作用 | 典型场景 |
  37. | --- | --- | --- |
  38. | `doctor [dir]` | 探测引擎/工具/字体/tlpdb,给项目体检 | 接手新机器、编译前先确认环境 |
  39. | `build [dir]` | 编译出 PDF,写 `build-report.json` | 主入口,99% 的活都从这开始 |
  40. | `logs [dir]` | 解析已有 `.log`(不重编) | 编译产物还在、只想看诊断 |
  41. | `clean [dir]` | 删中间产物,保留 PDF | 交付前瘦身、强制全量重编 |
  42. | `render [dir]` | PDF 页 → PNG/JPEG | 版面视觉检查、给模型看效果 |
  43. | `repair [dir]` | 有界修复闭环,每轮落 `round-N.diag.json` | 编不过、想让它自己试一轮 |
  44. | `layout [dir]` | 版面量化:溢出/空洞/孤行,页码级结论 | 想知道版面哪里不对,而不只是"看着怪" |
  45. | `check [dir]` | chktex 静态检查 + latexindent | 语法风格、缩进规范 |
  46. | `init <target>` | 从模板新建工程 | 起新文档,别从空白开始 |
  47. | `templates` | 列出模板 | 不确定有哪些模板时 |
  48. 所有子命令都支持 `--json`,输出可直接被程序消费。
  49. ## build:默认就该这么用
  50. ```bash
  51. bash "$SKILL_DIR/bin/latex-build" path/to/project
  52. ```
  53. 它会自动做完这些判断,**你不需要先告诉它用哪个引擎**:
  54. - **主文档**:在项目里评分挑主 `.tex`(`main.tex`/`paper.tex`/`thesis.tex` 优先,其次浅层、
  55. 其次 `\documentclass` 所在)。挑错了就显式传 `--file other.tex`。
  56. - **引擎**:扫源码里的 `fontspec`/`ctex`/`xeCJK`/`unicode-math` → XeLaTeX;`luacode`/
  57. `luatexja` → LuaLaTeX;正文里有裸 CJK 字符(且没装 `CJK`/`CJKutf8` 这类 pdfLaTeX 方案)
  58. → XeLaTeX;否则 pdflatex。`--engine auto` 是默认值。
  59. 注释里的中文不算——pdfTeX 根本不读注释,为它换引擎只会让输出莫名变样。
  60. - **后端**:`biblatex` + `backend=biber` → biber;`\bibliography{}` → bibtex。
  61. - **驱动**:默认走 `latexmk`(自动跑够轮数、自动处理 bib)。`--no-latexmk` 才直调引擎
  62. 并按 `.aux` 指纹跑到稳定。
  63. 产物落在项目下的 `latex-out/`,报告是 `latex-out/build-report.json`(`schema: 4`)。
  64. ```bash
  65. # 常用开关
  66. --engine {auto,pdflatex,xelatex,lualatex}
  67. --backend {auto,none,bibtex,biber}
  68. --outdir latex-out # 必须是项目内的相对子目录
  69. --jobname NAME
  70. --timeout 300
  71. --no-latexmk # 直调引擎
  72. --stop-on-first-error # 默认关:先全量收集错误再排序
  73. --shell-escape # 默认永远不加,确有需要才显式开
  74. --synctex # 需要正向/反向搜索时
  75. --json
  76. ```
  77. ### 退出码与判据
  78. `build` 返回 0 才算成功。判定不只看退出码:还要有 `%PDF-` 魔数、PDF 真的落在磁盘上、
  79. 源码 sha256 在编译期间没被改动过。**退出码 0 但没出 PDF 的情况一律算失败**。
  80. ## 读诊断:先读 root_cause
  81. `build` 失败时的输出形如:
  82. ```
  83. build failed: File `nonexistentpkgxyz.sty' not found at misspkg.tex:3
  84. engine: pdflatex (...); backend: none
  85. failure: ...
  86. error [missing_package] misspkg.tex:3: File `nonexistentpkgxyz.sty' not found.
  87. ```
  88. 规则只有一条:**看 `root_cause`,不要看 `errors` 里的最后一条**。TeX 的错误会级联,
  89. `Emergency stop` / `Fatal error occurred` / `No pages of output` 是后果不是原因,
  90. 它们在 `counts.suppressed_cascade` 里计数,不进 `errors`。
  91. 因果优先级(`root_cause` 就是按这个排序取第一条):
  92. ```
  93. missing_package < missing_file < undefined_macro / undefined_environment / unbalanced_argument
  94. < math_or_brace < encoding < package_error < generic
  95. ```
  96. 同优先级下 `.tex` 文件优先于宏包文件,再按行号升序。**位置永远指向作者源码**,
  97. 不会指到 `size10.clo`、`main.aux` 或 `inserted text` 这类伪帧上去。
  98. 想拿完整结构:
  99. ```bash
  100. bash "$SKILL_DIR/bin/latex-build" proj --json | python -c "import json,sys; d=json.load(sys.stdin); print(d['log']['root_cause'])"
  101. ```
  102. ## 缺包 / 缺字体:离线解析,别去 tlmgr 联网
  103. `build` 失败时会把缺失的 `.sty`/`.cls` 拿去查本机 TeX Live 的文件清单
  104. (`tlpkg/texlive.tlpdb`,索引 1.4 万+ 文件名,0.1 秒建完并缓存),直接告诉你包名:
  105. ```
  106. missing packages:
  107. nonexistentpkgxyz.sty -> not provided by any installed TeX Live package
  108. algorithm2e.sty -> algorithm2e: tlmgr install algorithm2e
  109. ```
  110. `tlmgr search` / `tlmgr info` **必须联网**,离线必失败(而且失败时退出码还是 0,别被骗)。
  111. 所以判断「装没装、属于哪个包」一律走 `kpsewhich` + 本地 tlpdb 索引。
  112. **缺字形**(中文最常见的坑)表现为 `Missing character: There is no 中 in font ...`,
  113. 这类信息进 `log.missing_chars`,`detail` 是字体名。根因通常是:
  114. - 用 pdflatex 编了含中文的文档 → 换 `--engine xelatex` + `ctex`/`xeCJK`;
  115. - 字体真有缺口 → 换字体或加 `\setCJKmainfont`。
  116. ## 静态检查与格式化
  117. ```bash
  118. bash "$SKILL_DIR/bin/latex-check" proj # chktex 报告
  119. bash "$SKILL_DIR/bin/latex-check" proj --format # 顺带打印 latexindent 结果
  120. bash "$SKILL_DIR/bin/latex-check" proj --format --in-place # 直接改写
  121. ```
  122. `chktex` 在本机(v1.7.9)**不能用 `-o` 输出到文件**,会报 `Could not rename 'nul'`,
  123. 所以这里固定用 `-f "%f:%l:%c:%k:%m"` 走 stdout。`--in-place` 会改文件,改前想清楚。
  124. ## 新建工程
  125. ```bash
  126. bash "$SKILL_DIR/bin/latex-templates"
  127. bash "$SKILL_DIR/bin/latex-init" my-paper --template zh --title "论文标题" --author "作者"
  128. ```
  129. 模板:`article`(pdflatex) / `zh`(xelatex + ctexart) / `biblatex`(pdflatex + biber) /
  130. `beamer`(pdflatex) / `tikz`(lualatex)。生成后目录里有 `latex-project.json` 记着清单。
  131. ## 有界修复闭环
  132. 文档编不过时,**不要盲改源码**。`repair` 把这件事变成一个有上限的循环:
  133. ```bash
  134. bash "$SKILL_DIR/bin/latex-repair" proj # 先看它想怎么修
  135. bash "$SKILL_DIR/bin/latex-repair" proj --apply # 允许它改源码
  136. bash "$SKILL_DIR/bin/latex-repair" proj --apply --max-rounds 3 --json
  137. ```
  138. 语义要点:
  139. - **每轮只出一条建议、只改一处**。构建开关类建议(换引擎)不需要 `--apply`,
  140. 下一轮编译本身就能证明对错。
  141. - 不加 `--apply` 时只报告,`status` 为 `needs-apply`,源码一个字节都不动。
  142. - `--apply` 会**先备份再改**,备份在 `latex-out/repair/round-N/`。只改 UTF-8 文件——
  143. 把 CP936 文件按 UTF-8 写回会静默毁掉它,所以这类文件直接判 `needs-human`。
  144. - 每轮都会写 `latex-out/round-N.diag.json`,几轮之间可以 diff。
  145. `status` 的六种结果,各自该做什么:
  146. | status | 含义 | 下一步 |
  147. | --- | --- | --- |
  148. | `already-ok` | 一编就过 | 没你的事了 |
  149. | `repaired` | 改完过了 | 看一眼备份目录,确认改得对 |
  150. | `needs-apply` | 有建议但没授权改 | 加上 `--apply` 重跑 |
  151. | `needs-human` | 建议需要人做(装包、换字体、逻辑错) | 读 `stopped_reason`,照做 |
  152. | `failed` | 同一根因修了还在 | 停手,人工看源码 |
  153. | `exhausted` | 轮数用完还不过 | 提高 `--max-rounds` 或人工介入 |
  154. 哪些情况它**不会**硬试(这是设计,不是缺陷):缺包要联网装、需要加字体、缺图缺
  155. `.bib` 条目、源码逻辑错。这些停下来给结论比乱改更有用。
  156. 不想用闭环、只想手动走一遍时:`latex-build proj` → 读 `root_cause`(file / line /
  157. category / message)→ 只改那一处 → 重跑。`--shell-escape` 永远不是消错手段。
  158. ## 版面视觉检查
  159. 两件事,用途不同:
  160. **看图**(人/模型的眼睛):
  161. ```bash
  162. bash "$SKILL_DIR/bin/latex-render" proj --dpi 120 # 全部页
  163. bash "$SKILL_DIR/bin/latex-render" proj --first 1 --last 3 # 只看前 3 页
  164. bash "$SKILL_DIR/bin/latex-render" proj --jpeg # JPEG 更小
  165. ```
  166. 产物在 `latex-out/render/`,用 Read 工具打开 PNG 自己看。文字溢出页边、浮动体错位、
  167. 图表压字、目录页空白这些 `overfull` 说不清的问题,只能看图判断。
  168. **量化**(不必逐页看就能定位):
  169. ```bash
  170. bash "$SKILL_DIR/bin/latex-layout" proj
  171. bash "$SKILL_DIR/bin/latex-layout" proj --json --report latex-out/layout.json
  172. bash "$SKILL_DIR/bin/latex-layout" proj --only 2 3 # 只看第 2、3 页
  173. ```
  174. 它用 `pdftotext -bbox-layout` 拿每行坐标,报四类问题:
  175. | kind | 判据 | severity |
  176. | --- | --- | --- |
  177. | `overflow-edge` | 行尾超过**纸张**右边界 | `error`(确定) |
  178. | `overflow-margin` | 行尾超过**版心**右边界但仍在纸内 | `layout`(确定) |
  179. | `hole` | 相邻行间距 > 4× 正常行距 | `layout`(启发式,0.8) |
  180. | `widow-orphan` | 页首短行不缩进(寡行)/ 页末行缩进(孤行) | `warning`(启发式,0.7) |
  181. 几个判据是**校准过的**,改之前先读代码注释:行距取 20% 分位数而非中位数(否则短
  182. 页上的空洞会把"正常行距"拽过去);版心右边界取"至少两行互相印证的最右聚类"(单行
  183. 不能自证,越界行不能定义正常);孤行按**缩进**判而非按短行判(段落末行本来就是短
  184. 的,按短行判会给每个正常段落都报一次);空洞阈值 4× 而非 2.5×(标题前的 2.5–3× 间距
  185. 是正常排版)。
  186. **几何看不到的,日志补**:比版心宽、但还没冲出纸面的盒子,`pdftotext` 的坐标看不出
  187. 异常,只有 `.log` 的 `Overfull \hbox` 知道。所以 `layout` 默认读同名 `.log` 并把它
  188. 并进 `log_overfull`;测不出右边距时(短页、beamer 这类行数太少的文档)会在
  189. `measure_source` 标 `log`,并在摘要里明说"right margin not measurable"——这是诚实的
  190. 测不了,不是漏报。
  191. 退出码按**严重度**而非置信度:`error`/`layout` 类问题 rc=1,纯 `warning` 类 rc=0
  192. (可疑寡行只是样式提示,调用者可以合法忽略)。
  193. ## 必须知道的平台约束
  194. ### 1. `--outdir` 只能是项目内的相对子目录
  195. Windows TeX Live 有一个确定性缺陷:**绝对路径** `-output-directory` 且路径里「CJK 段紧跟
  196. 空格」时,`pdflatex`/`xelatex` 直接 `fatal: putenv(TEXMF_OUTPUT_DIRECTORY=...)` 死掉(rc=1,
  197. 无 PDF)。`lualatex` 不受影响,`latexmk -outdir=` 也不受影响。
  198. 所以本技能**永远给引擎传相对 outdir**,并在检测到风险路径时打印提示。想放到项目外
  199. (比如 `--outdir ../build`)会直接报错让你改回来 —— 这是故意的,不是 bug。
  200. ### 2. `-halt-on-error` 默认关
  201. 它会在第一个错误处停下,把后面的错误全吞掉。本技能的策略是**先全量收集再按因果排序**,
  202. 这比「第一行 `!` 就是根因」可靠得多(第一行 `!` 经常只是前一个错误的余波)。
  203. ### 3. 不要用 `texfot` 当证据源
  204. 本机实测:outdir 已存在时它报 `! I can't write on file '...log'` 却仍然 **exit 0**,
  205. 退出码不可信。判断成败只看本技能的 `build-report.json`。
  206. ### 4. 日志里的乱码是正常的
  207. `latexmk` 经 runscript 启动会打印两行 `Initial Win CP ...`,技能已过滤。
  208. `pdfinfo` 的时间字段在 CP936 控制台下必然是乱码,技能只解析 `Pages`/`Page size`,
  209. **不要拿 `pdfinfo` 的 CreationDate 去做任何判断**。
  210. ### 5. 绝不自动联网装 TeX 包
  211. `build` 不会执行 `tlmgr install`,只打印命令。装不装、装什么是用户决定。
  212. ### 6. 非 UTF-8 的 `.tex` 会被拒绝,而不是硬编
  213. GBK/GB18030 源交给 xelatex 会"编译成功",产出一份全是错字的 PDF —— 这比报错更糟,因为
  214. 没人看得出坏了。所以选 Unicode 引擎(xelatex/lualatex)时,`compile_project` **在启动前**
  215. 扫项目里的 `.tex`,发现非 UTF-8 直接失败并给 `encoding` 诊断,`repair` 也不会去改那个文件,
  216. 只告诉你先转码:
  217. ```bash
  218. iconv -f gb18030 -t utf-8 'main.tex' > 'main.tex.utf8' && mv 'main.tex.utf8' 'main.tex'
  219. ```
  220. pdfTeX 不做这个检查:`\usepackage[latin1]{inputenc}` 在 pdflatex 下是合法配置。
  221. ## 报告结构(`latex-out/build-report.json`)
  222. ```jsonc
  223. {
  224. "schema": 4,
  225. "status": "success" | "failed",
  226. "engine": "xelatex",
  227. "engine_reason": "document loads ctex/xeCJK/fontspec",
  228. "backend": "biber" | "bibtex" | null,
  229. "source": "...", "pdf": "...", "outdir": "...",
  230. "duration_ms": 1830,
  231. "steps": [{ "tool": "latexmk", "command": [...], "returncode": 0, "duration_ms": 1790 }],
  232. "log": { /* LogReport:success/pages/errors/warnings/layout/missing_chars/
  233. undefined_refs/undefined_cites/missing_files/missing_packages/
  234. root_cause/counts{errors,warnings,layout,missing_chars,suppressed_cascade} */ },
  235. "failure": null,
  236. "pdf_sha256": "...", "source_sha256": "...",
  237. "warnings": ["..."] // 技能自己给的提示,例如 putenv 规避
  238. }
  239. ```
  240. `repair` 与 `layout` 另有两类产物:
  241. - `latex-out/round-N.diag.json` —— 修复闭环每一轮的诊断快照(`status`/`root_cause`/
  242. `suggestion`/`applied`/`note`),几轮之间可直接 diff;
  243. - `latex-out/repair/round-N/<file>` —— `--apply` 改动前的原文件备份;
  244. - `--report` 指定的 `layout.json` —— 版面量化的完整结果(`counts`/`issues`/`log_overfull`/
  245. 逐页 `lines`/`measure_pt`)。
  246. ## 出错时怎么办
  247. | 现象 | 处理 |
  248. | --- | --- |
  249. | `no .tex file found` | 显式 `--file`,或确认目录里真有 `.tex` |
  250. | `output directory ... is outside the project` | `--outdir` 改回项目内 |
  251. | `log not found` | 先 `build` 一次;或 `--log` 指到具体 `.log` |
  252. | `python3` 存在但包装脚本没输出 | 那是 Store 存根;设 `LATEX_SKILL_PYTHON=python` |
  253. | `layout` 说 `right margin not measurable` | 行数太少无法定版心(beamer、单行页);这是诚实结论,此时看 `log_overfull` |
  254. | 编译成功但 PDF 是旧的 | 看 `report` 里的 `pdf_sha256`;不确定就 `clean --drop-pdf` 后重编 |
  255. | 中文全是空白/方框 | 引擎选错,`--engine xelatex`;看 `log.missing_chars` 确认字体 |
  256. ## 自检
  257. ```bash
  258. bash "$SKILL_DIR/tests/smoke.sh" # 31 个端到端用例,约 60 秒
  259. python -m unittest discover -s "$SKILL_DIR/tests" # 44 个单测(日志解析 + 引擎探测 + 版面量化)
  260. python "$SKILL_DIR/tests/verify_p6.py" # 25 项打包验收,约 60 秒;发布前必跑
  261. ```
  262. 冒烟套件里有两个**故意难看的目录名**(`带 空格 目录`、`中 文`)——它们就是 putenv 回归,
  263. 任何改动后都必须仍然全绿。
  264. `verify_p6.py` 不跑工作区,它跑 `git archive HEAD` 出来的包,解到 `包 目录/relocated`
  265. (中文 + 空格)再验证。工作区能跑而包里跑不了,就是打包漏了文件或丢了可执行位。
  266. 改代码时用 `--workspace` 迭代,发布前**不带参数**跑一遍。
README.md · README · 184 lines
  1. # latex-automation — 本机 LaTeX 自动化技能(DeepSeek Harness / WorkBuddy)
  2. 用一句话在本机 LaTeX 上干活:编译、诊断、渲染、检查、脚手架。全部离线。
  3. ## 这是什么
  4. 一个技能,两个宿主:DeepSeek Harness(`~/.dsh/skills/latex-automation/`)与
  5. WorkBuddy(`~/.workbuddy/skills/latex-automation/`)。它不是一个 LaTeX 插件,也不是一个
  6. GUI —— 它是一组能被 `Bash` 工具直接调用的命令行,加上一份教会模型怎么用这些命令、
  7. 怎么读诊断、什么时候该停手的说明书。两个宿主共用同一份 Python 包与同一份 SKILL.md
  8. 正文,只有头部(frontmatter)按平台生成,见 `docs/04-workbuddy.md`。
  9. - **入口**:`bin/latex-{build,doctor,logs,clean,render,check,init,templates}`
  10. - **实现**:`latex_automation/` 纯标准库 Python 包(无第三方依赖)
  11. - **产物**:落在调用者项目的 `latex-out/`,**不写 `~/.dsh` 或 `~/.workbuddy`,不留全局状态**
  12. ## 为什么不是插件
  13. 调研阶段(`docs/01-research-report.md`)扫过 DSH 生态:LaTeX 相关的十来个项目
  14. **清一色是「插件 + 网页 GUI + 预览窗口」**,没有一个走纯技能形态。插件路线要求
  15. DSH 侧长期维护一套 UI 和常驻服务;技能路线只要子进程能把活干完,模型看得懂输出就够了。
  16. LaTeX 编译天然是「输入文件 → 子进程 → 文本诊断」的形态,用技能更轻也更稳。
  17. ## 快装
  18. ```bash
  19. SKILL_DIR="$HOME/.dsh/skills/latex-automation"
  20. bash "$SKILL_DIR/bin/latex-doctor" # 先看环境
  21. bash "$SKILL_DIR/bin/latex-build" 你的项目/
  22. ```
  23. 要求(缺了会 `doctor` 里报 `warn`/`fail`,不会静默):
  24. | 级别 | 工具 |
  25. | --- | --- |
  26. | 必需 | `latexmk` `pdflatex` `xelatex` |
  27. | 推荐 | `biber` `bibtex` `kpsewhich` `pdftoppm` `pdfinfo` `chktex` `latexindent` |
  28. | 可选 | `lualatex` `dvisvgm` `pdftotext` `latexdiff` `lacheck` |
  29. Python ≥ 3.8(实测 3.14.7)。包装脚本会自动挑一个能真正执行起来的解释器,
  30. 可用 `LATEX_SKILL_PYTHON` 覆盖。
  31. ## 与调研结论的对应关系
  32. 技能是自研的,但四类设计明确借自 MIT 许可的公开项目,逐条对应:
  33. | 来源 | 借了什么 | 没借什么 |
  34. | --- | --- | --- |
  35. | `Calix-L/awesome-latex-skills`(MIT) | `build-report.json` 的 schema 形状、`%PDF-` 魔数校验、源码 sha256 未变校验、`-recorder` 指纹 | 绝对 `-output-directory`(本机会 putenv 崩)、`-halt-on-error`(会截断错误) |
  36. | `Yaohua-Leo/dsh-latex`(MIT) | 日志正则集(含 `Missing character`)、`docs/env-audit.md` 里的 Windows 事实、`-outdir` 单 argv、latexmk 退出码表 | 插件形态、网页编辑器、PDF 预览 |
  37. | `Qingzhu093/dsh-latex-studio`(MIT) | 引用/浮动体/重跑警告的正则、失败台账与门禁思路 | 环境探测层(硬编码 MiKTeX)、不解析 latexmk 的策略 |
  38. | `OpenRaiser/PaperFit`(MIT) | overfull 归因与 `compile_diagnostics` 的字段形状 | 常驻 monitor 服务、tectonic 依赖 |
  39. `ndpvt-web/latex-document-skill`(无 LICENSE)只读了引擎自动探测规则就停手,
  40. 它的「检测不到就自动下载 TeX Live」分支明确不采用。
  41. ## 自研补上的四个空缺
  42. 1. **CJK+空格的 putenv 规避** —— 生态里没有任何项目处理这个 Windows TeX Live 缺陷;
  43. 本技能把「绝对 outdir 会崩、相对 outdir 安全」做成硬约束。
  44. 2. **完全离线的缺包解析** —— `tlmgr` 离线必失败(且退出码撒谎),改用
  45. `kpsewhich` + `texlive.tlpdb` 本地索引,0.1 秒建 1.4 万条并缓存。
  46. 3. **全量收集 + 因果归并** —— 不靠 `-halt-on-error`;`Emergency stop`/`Fatal error`/
  47. `No pages of output` 全部折进 `suppressed_cascade`,`root_cause` 按类别优先级取第一条。
  48. 4. **DSH 技能契约** —— frontmatter、`allowed-tools`、bash 包装、产物落调用者工作区。
  49. ## 目录
  50. ```
  51. latex-automation/
  52. ├── SKILL.md # 技能说明书(模型读这个)
  53. ├── README.md # 本文件
  54. ├── CHANGELOG.md # 版本记录
  55. ├── LICENSE # MIT
  56. ├── bin/ # 10 个 bash 包装 + _bootstrap.sh
  57. ├── latex_automation/ # Python 包
  58. │ ├── proc.py # 子进程、解码链、runscript 噪音过滤、进程树杀掉
  59. │ ├── paths.py # 相对 outdir 计算、CJK 检测、项目文件遍历
  60. │ ├── logparse.py # 日志 → LogReport(本包最大件)
  61. │ ├── packages.py # tlpdb 离线索引 + 缺包 → 安装命令
  62. │ ├── engine.py # 引擎/后端探测、latexmk 与直调引擎、报告
  63. │ ├── doctor.py # 环境与项目体检
  64. │ ├── render.py # PDF → PNG/JPEG
  65. │ ├── lint.py # chktex + latexindent
  66. │ ├── scaffold.py # 5 个模板
  67. │ ├── repair.py # 有界修复闭环:建议 → 应用 → 复编
  68. │ ├── layout.py # 版面量化:溢出/空洞/孤行(pdftotext -bbox-layout)
  69. │ └── cli.py # argparse 子命令
  70. ├── tests/
  71. │ ├── test_logparse.py # 11 个日志解析单测(fixtures 是真实日志裁剪)
  72. │ ├── test_engine.py # 15 个引擎探测单测(裸 CJK / 注释 / CJKutf8 / 非 UTF-8 预检)
  73. │ ├── test_layout.py # 18 个版面量化单测(手造 box 数据)
  74. │ ├── test_workbuddy.py # 16 个双宿主契约单测(正文共用 / 头部 / 子命令文档)
  75. │ ├── verify_p6.py # 31 项打包验收(跑 git archive 出来的包)
  76. │ └── smoke.sh # 31 个端到端用例
  77. ├── tools/
  78. │ ├── install_workbuddy.py # 合成 WorkBuddy 版 SKILL.md 并安装
  79. │ └── verify_workbuddy.py # 15 项安装后验收(用 WorkBuddy 自带 bash)
  80. ├── workbuddy/
  81. │ └── frontmatter.yaml # WorkBuddy 头部;正文复用 SKILL.md
  82. ├── fixtures/ # broken.tex / misspkg.tex
  83. ├── research/ # 调研脚本与 L4 实测夹具(非运行依赖)
  84. └── docs/
  85. ├── 00-research-plan.md # 调研计划
  86. ├── 01-research-report.md # 调研报告与评分表
  87. ├── 02-p6-verification.md # P6 验收:为什么这样测、抓到什么缺陷
  88. ├── 03-p6-run.md # P6 执行记录:逐项判定与本次指标
  89. └── 04-workbuddy.md # WorkBuddy 版:两宿主的差异与合成方式
  90. ```
  91. ## 装到 DSH
  92. ```bash
  93. git clone https://github.com/ccyk-hash/latex-automation.git \
  94. "$HOME/.dsh/skills/latex-automation"
  95. bash "$HOME/.dsh/skills/latex-automation/bin/latex-doctor"
  96. ```
  97. ## 装到 WorkBuddy
  98. ```bash
  99. git clone https://github.com/ccyk-hash/latex-automation.git /tmp/latex-skill
  100. cd /tmp/latex-skill
  101. python tools/install_workbuddy.py --dry-run # 看会写哪些文件
  102. python tools/install_workbuddy.py # 装到 ~/.workbuddy/skills/latex-automation
  103. python tools/verify_workbuddy.py # 用 WorkBuddy 自带 bash 跑 15 项验收
  104. ```
  105. 两条命令各司其职:`--check` 逐文件 sha256 比对已装副本与仓库;
  106. `--force` 覆盖旧安装。WorkBuddy 的 SKILL.md 由 `workbuddy/frontmatter.yaml`
  107. 加 `SKILL.md` 的正文现场拼出来——仓库里只有一份正文,不存在两边不同步。
  108. DSH 启动时扫描 `~/.dsh/skills/*/SKILL.md`,读 frontmatter 的 `name` 与
  109. `description` 决定何时加载。本技能声明 `disable-model-invocation: false`,
  110. 所以描述里带触发词即可自动命中;也可在会话里直接说「用 latex-automation 编译这个项目」。
  111. ## 验证状态
  112. 在 TeX Live 2026 + Python 3.14.7 + Windows 上实测:
  113. - `python -m unittest discover -s tests` → **60/60 通过**(日志解析 11 + 引擎探测 15 +
  114. 版面量化 18 + 双宿主契约 16)
  115. - `python tests/verify_p6.py` → **31/31 通过**(约 55–75 s),跑的是 `git archive HEAD`
  116. 打出来的包,解到 `包 目录/relocated`(中文 + 空格)再验:文件齐、11 个 `100755`、
  117. 无 CRLF、无 token 泄漏、六用例全对、7 种路径 + 3 种文件名通过、CP936 源报错且字节不变。
  118. `--workspace` 模式少 6 项打包检查(25 项),只用于改代码时迭代,**不作为发布依据**
  119. - `python tools/verify_workbuddy.py` → **15/15 通过**(约 18 s),装到临时目录后用
  120. **WorkBuddy 的 PortableGit bash** 驱动真实项目:头部正确、正文逐字节一致、doctor 可跑、
  121. 中文+空格目录建工程并编译、layout 读得到 PDF、repair 遇不可修缺陷停手且不改源文件、
  122. render 出图、chktex 可跑
  123. - `bash tests/smoke.sh` → **31/31 通过**,含 5 个模板真编译、2 个 putenv 回归、
  124. 2 个失败文档的因果归并、渲染/检查/清理、**修复闭环 5 例**(干净文档直接收敛、
  125. `\usepackage` 错位自动搬回、备份与 `round-N.diag.json` 落盘、需人工时正确停手)、
  126. **版面量化 4 例**(合规文档静默、overfull 报警、JSON 报告契约)、报告 schema 契约
  127. - `doctor` → 在含主文档的项目里 `13 ok, 0 warn, 0 fail`;在空目录里多一条
  128. `[warn] project: no master .tex`(预期行为,不是失败)
  129. - 从 GitHub 下载的 tarball 解压到任意目录、在**非仓库根**的 cwd 下都能直接跑通
  130. 两套测试 —— 这一条专门验证 `bin/_bootstrap.sh` 的路径解析(见下)
  131. 改任何东西之后这两个套件都必须仍然全绿。两条容易踩的坑:
  132. 1. **`tests/smoke.sh` 必须保持 LF 行尾** —— 用 CRLF 存会让 Bash 把 `$?` 读成
  133. `"0\r"`,判定全错(踩过一次)。
  134. 2. **POSIX 路径不能直接进 `PYTHONPATH`** —— 本机 bash 不支持 `pwd -W`(那是 MSYS
  135. 扩展),必须用 `cygpath -w` 转成 `D:\...` 形式,否则 `python.exe` 找不到包,
  136. 而症状是「在仓库根能跑、换个 cwd 就 `No module named latex_automation`」
  137. (也踩过一次)。
  138. ## 已知边界
  139. - 不解析 `.dtx`、不做 `\write18` 沙箱、不做 SyncTeX 双向跳转(`--synctex` 只负责生成)。
  140. - 非 UTF-8 检测只覆盖项目内的 `.tex`;`\input` 项目外的文件、或 `.sty` 里的非 UTF-8 内容
  141. 不在检查范围。检测按 UTF-8 严格解码,BOM 视为合法(`utf-8-sig` 能读)。
  142. - 引擎自动探测只看主文档;多主文档项目请显式传 `--file` 与 `--engine`。
  143. - 版面量化只依赖 `pdftotext`,没有像素级比对(不做视觉回归基线);行数太少的文档
  144. 无法确定版心,此时会明说 `right margin not measurable` 并退回只看日志 overfull。
  145. - 修复闭环每轮只出一种建议、只改一处,不做多缺陷联合规划;`--apply` 只改 UTF-8 文件。
  146. - 只认 TeX Live 的 `texlive.tlpdb`;MiKTeX 的包库结构不同,缺包提示会退化成
  147. 「不属于任何已装包」。
  148. - 模板是 5 个最小可用骨架,不是期刊投稿模板库。
  149. ## 许可
  150. MIT。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.