Flan246/dsh-latex-guard

dsh-latex-guard

npm version
npm downloads
GitHub stars
license

面向 DeepSeek Harness 及任意 agent 的 LaTeX 编译检查与 BibTeX lint/fill/audit 工具。

功能特性

- check — 使用 latexmk 编译 LaTeX 项目，并返回包含错误、警告和未定义引用的结构化报告
- bib-lint — 对条目键去重，按条目类型检查必填字段，规范化格式
- bib-fill — 通过 DOI 或标题从 Crossref 补全缺失的条目字段（绝不覆盖已有值）
- cite-audit — 将 .tex 文件中的引用键与 .bib 文件进行比对：被引用但缺失的条目，以及从未被引用的条目。可识别的命令：\cite、\citep、\citet、\parencite、\textcite，以及 biblatex 命令 \autocite、\footcite、\fullcite、\nocite（\nocite 的键计为已引用）。

所有命令默认返回人类可读的输出，使用 --json 时返回结构化 JSON。退出码：0 表示成功，1 表示业务错误，2 表示用法错误。check 若编译成功但报告 status: "failed"，同样以 1 退出；skipped 的检查（latexmk 不可用）以 0 退出，因为优雅降级不算错误。

用法

1. 作为 dsh 插件

dsh plugin add dsh-latex-guard

注册四个 agent 工具：latex_check、bib_lint、bib_fill、cite_audit。

2. 作为独立 CLI

npx dsh-latex-guard check   [--engine ] [--json]
npx dsh-latex-guard bib-lint  [--write]
npx dsh-latex-guard bib-fill  [--write]
npx dsh-latex-guard cite-audit

--write 会就地修改 bib 文件——使用前请先确认。作为安全网，当 bib 无法被完整解析时（例如某个条目缺少闭合花括号），两条写入路径都会拒绝写入，而不是静默丢弃无法解析的尾部内容。

check --engine  选择 latexmk 引擎：auto（默认）、pdflatex、xelatex 或 lualatex。在 auto 模式下，引擎从入口 tex（以及本地的 \documentclass 文件）中检测：% !TeX program = ... 魔法注释、\RequireXeTeX、xeCJK 或 {ctex 会选择 xelatex，\RequireLuaTeX 会选择 lualatex，否则为 pdflatex。报告中的 engine 字段记录实际使用的引擎；当编译失败且没有任何可解析的错误行时，报告还会附带 logTail，包含 latexmk 日志的最后几行。

已知限制

- cite-audit 会把被注释掉（% ...）的行中的 \cite 键计为真实引用。
- passed 的检查报告仍可能带有 latexmk 中间轮次产生的引用警告；只有最后一轮才反映真实的引用状态。

3. 作为 agent skill
本包中附带的 skill/SKILL.md 会教任何兼容 SKILL.md 的 agent 如何驱动该 CLI。

latexmk 依赖

check 需要 PATH 上有一个提供 latexmk 的 TeX 安装（例如 TeX Live 或 MiKTeX）。当找不到 latexmk 时，check 会优雅降级：它返回一个带有 skipped: true 的报告，而不是失败，因此其他三个命令（纯 BibTeX/文本处理，不需要 TeX）仍然完全可用。

bib-fill 是唯一需要网络访问的命令（Crossref API，10 秒超时，重试一次）。

许可证

MIT