jp-pdf 用于把日文 Markdown 转成日文排版良好、带配色的 PDF。生成路径只有 pandoc → xelatex，不使用 Chrome 或外部服务，外部通信为零。文档中用 <SKILL_DIR> 指代该 SKILL.md 所在目录的实际路径。
用途 适合“把这份 Markdown 转成 PDF”“把研究计划书做成 PDF”这类请求，也适合需要以分发版式输出日文文档（设计书、提案书、报告）的场景。
依赖工具（均为本地或离线）
- pandoc：Markdown→LaTeX→PDF，安装例 brew install pandoc
- xelatex（TeX Live）：日文 PDF 引擎，MacTeX / TeX Live
- rsvg-convert（librsvg）：SVG 图→矢量 PDF，brew install librsvg
- IPAexGothic 字体：日文正文，~/Library/Fonts/ipaexg.ttf
- ghostscript（gs）：预览（PNG），brew install ghostscript 依赖缺失时，构建脚本会指出名称并停止。
基本步骤
- 准备输入 Markdown（可用现有文件）。没有图时，执行下面一条命令即可完成。
- 执行构建：
python3 "<SKILL_DIR>/scripts/build_pdf.py"
--input path/to/doc.md
--output path/to/doc.pdf
--title "文档标题"
--running-title "页眉短标题" --doc-tag "研究计划书"
--toc --preview 加 --preview 会把第一页输出为 doc_p1.png。也可用 gs 把任意页转 PNG 目视检查： gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -r120
-dFirstPage=1 -dLastPage=3 -sOutputFile=out-%02d.png doc.pdf
插入图（ASCII 图 → SVG） 可把正文中的 ASCII 图替换为更易读的 SVG 图。原稿 .md 保留 ASCII，仅 PDF 构建时替换为图片（原稿仍可在编辑器中阅读）。
- 导入 <SKILL_DIR>/scripts/svglib.py 编写作图脚本，模板为 <SKILL_DIR>/../../examples/gen_diagrams.py（导入 svglib 使用）。可组合圆角框 box()、箭头 arrow()、标签 label()、chip()。
- 生成的 SVG 放入 assets/。
- 用 figures.json 建立“哪个 ASCII 围栏替换为哪个 SVG”的对应关系（模板 examples/figures.example.json）： [ {"sig": "围栏内必定包含的唯一字符串", "svg": "pipeline.svg", "caption": "图：…"} ]
- 构建时传入 --assets assets --figures figures.json。对应围栏会被替换为 ，SVG 自动转为矢量 PDF。
设计要点（实践中遇到的问题）
- 完全离线：不使用 Chrome/HTML 路径；pandoc→xelatex 本地完成，不产生遥测或外部资源抓取。
- 字体：IPAexGothic 为单字重，粗体通过 AutoFakeBold 伪粗化（构建脚本默认启用）。
- 配色：由 <SKILL_DIR>/assets/style.tex 负责，青色系，含彩色标题与下划线、tcolorbox 提示框引用（> 区块）、rowcolors 斑马纹表格、fancyhdr 页眉页脚、标题上下装饰线。
- SVG 越界：textLength（拉伸指定）在 rsvg-convert 的 PDF 输出中被忽略（PNG 中有效，易被忽略）。svglib 改为按实际尺寸缩小字号来容纳（fitfs）。作图时使用其 box()/label() 更安全。
- 字形替换：IPAexGothic 中不存在的 ✕、≈ 仅在构建时替换为 ×、≒（默认，原稿不变）。其他缺字警告可加 --glyph-subs "字=替代,…"。
- 防止标签与框重叠：自由定位的 label() 不要放在与框的纵向范围（y〜y+h）和横向范围相交的坐标。箭头旁的名称只用箭头上方的短词，说明文字放在框行下方专门预留的带（纵向区域），区域之间至少间隔 16px。长文本标签必须指定 maxw 缩小。
- 验证（必须）：构建前先用 rsvg-convert -o check.png 把 SVG 转 PNG 目视，若文字与框、箭头重叠则修正后再集成。构建后用 gs 把页面转 PNG，目视确认图是否在框内、符号是否显示。重叠加未解决时不应视为完成。
build_pdf.py 主要参数 --input --output（必填）／--assets DIR／--figures JSON／--title／--running-title／--doc-tag／--style style.tex（默认同捆）／--font（默认 IPAexGothic）／--fontsize（默认 10pt）／--margin（默认 16mm）／--img-width（默认 88%）／--toc／--preview／--glyph-subs "a=b,c=d"。
示例（同捆样本）
examples/ 中有一套通用样本，可先跑一遍：
python3 "<SKILL_DIR>/../../examples/gen_diagrams.py" "<SKILL_DIR>/../../examples/assets"
python3 "<SKILL_DIR>/scripts/build_pdf.py"
--input "<SKILL_DIR>/../../examples/sample.md"
--output sample.pdf
--assets "<SKILL_DIR>/../../examples/assets"
--figures "<SKILL_DIR>/../../examples/figures.example.json"
--title "月次报告自动化的探讨笔记" --toc --preview
限制：需要本地具备所列依赖；缺字需通过 --glyph-subs 手动补充；SVG 拉伸指定在 PDF 输出中不可用，需依赖 svglib 的字号适配；尚无资料说明其他平台或收费信息。