Files
agent/skills/x2pdf/SKILL.md
T
kicer 4e1c1f36d0 refactor(skills): 本机环境说明改放技能目录的 AGENTS.md,启动器不再特判任何技能
上一版把安装说明写成 INSTALL.md 并在 SKILL.md 里加段落,两处都不对:SKILL.md 是用法说明,
不该塞安装内容;启动器为 office 单独注入 PATH 也不成立,再加技能就得逐条改 start.sh。

- 删除 4 个 INSTALL.md,改为各技能目录下的 AGENTS.md(只写命令:下载/安装/验证、
  平台资产名、字体路径),SKILL.md 恢复原样
- start.sh 去掉 office 的 PATH 注入;技能要命令入口时由 AGENTS.md 指导按次前缀
  (PATH="$SK/scripts:$PATH" office ...)。启动器只保留 AGENT_SKILLS_DEPS 这个路径变量
- 找不到依赖时的指路不放在 core 里做特征匹配,而是各自报错带自己 AGENTS.md 的绝对路径
  (office 封装层 ENOENT / x2pdf 缺包或无后端 / image-process 缺字体)
- env-local 提示词加一句:技能失败就读其目录下的 AGENTS.md

实测:无 PATH 时 office 报 command not found,按 AGENTS.md 加前缀后 --version 正常;
三条缺依赖报错均给出 AGENTS.md 绝对路径。
2026-11-11 19:12:01 +08:00

3.8 KiB

name, description, required, input_schema, output_schema
name description required input_schema output_schema
x2pdf 通用 PDF 转换。把 Markdown / HTML / txt / Word / Excel / PPT 转为 PDF true
type properties required
object
input output css page
type description
string 输入文件路径,支持 .md/.markdown/.txt/.html/.htm/.docx/.xlsx/.pptx/.odt/.ods/.odp
type description
string 输出 PDF 路径(可选,默认与输入同名)
type description
string 自定义 CSS 文件路径(可选,仅对 md/html/txt 生效,优先级最高)
type description properties
object 页面设置(可选,仅对 md/html/txt 生效;Office 文档版式由原文件决定,忽略本参数)
size margin font_size
type description
string 页面尺寸,默认 A4;也可传 "A5"、"letter"、"210mm 297mm" 等
type description
string 页边距,默认 20mm;可单值或 "上 右 下 左" 四值
type description
string 正文字号,默认 10.5pt;标题/代码等按 em 相对缩放,压页数时调小本值
input
type description
string 生成的 PDF 文件路径

功能说明

统一 PDF 转换入口,按扩展名自动分派两条渲染路径:

  • md / txt / html → WeasyPrint(CSS 排版,字体走 fontconfig,中文用系统文泉驿/Noto,无需字体文件); 本机没有 WeasyPrint(缺包,或缺它依赖的 pango/cairo)时自动回落 LibreOffice—— 能出件,但 page/css 只部分生效,不适合精确排版
  • docx / xlsx / pptx / odt / ods / odp → LibreOffice headless(忠于原文档版式,page/css 参数不生效)

Markdown 输入(.md / .markdown)

  • 标准语法之外,支持表格(管道语法)、围栏代码块(```/~~~)、脚注、定义列表、 标题锚点、属性列表、HTML 内联(Markdown extra 全家桶);
  • 文首 YAML front matter 当元数据剔除,不渲染;
  • 图片:相对路径按 输入文件所在目录 解析,也支持绝对路径与 http(s) 图片;
  • 自动套用默认 CSS(见下)。

txt 输入(.txt)

  • 不解析,按原文转义后整篇以等宽 <pre> 渲染(保换行,超长行自动折行)。

HTML 输入(.html / .htm)

  • 文档原样渲染,不套默认 CSS——自带 <style>/外链样式即所见即所得;
  • page 参数仅在显式传入对应字段时生效(默认不注入 @page,避免干扰文档自带版式);
  • css 文件作为外部样式表追加在文档自带样式之后,同优先级声明可覆盖文档内样式(用于强制微调);
  • 渲染媒体默认为 print:文档里只写给 screen 的样式不生效,请把打印样式写进 css 文件或 @media print。

默认 CSS(md/txt 自动套用)

  • 黑白友好:字号分明、浅灰底代码块/表头、隔行底纹表格,不依赖颜色传达信息;
  • A4 页脚自动页码(当前页 / 总页数);标题 break-after: avoid 不落页尾。

样式优先级(md/txt)

默认 CSS < page 参数(生成 CSS)< css 文件。压单页的常用手法: page.font_size 调小(如 9pt)+ page.margin 收窄(如 12mm)。

调用方式

通过 skill 的 {"op":"run","name":"x2pdf","args":{...}} 调用,参数:

  • input:输入文件路径(必填)
  • output:PDF 输出路径(可选,默认与输入同名)
  • css:自定义 CSS 文件路径(可选,仅 md/html/txt)
  • page:{size, margin, font_size}(可选,仅 md/html/txt)

选择建议:简单文档直接写 Markdown 交给本技能,默认样式即可;需要精确控版面 (分页、边距、多栏、黑白打印细节)再写 HTML + CSS。

示例

{"input": "report.md"}
{"input": "cheatsheet.md", "page": {"font_size": "9pt", "margin": "12mm"}}
{"input": "layout.html", "css": "print-override.css"}