Back to Details

pdfcraft

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PdfCraft

PdfCraft

Operate PdfCraft through its structured automation interfaces. Preserve the user's requested document and editing workflow.
通过 PdfCraft 的结构化自动化接口进行操作。保留用户要求的文档处理和编辑工作流。

References

参考资料

PdfCraft documents automation in two bundled snapshots, captured from upstream on 2026-11-02:
  • references/mcp.md — the MCP server: startup flags, tool surface, and file-access confinement. Source: PdfCraft MCP conventions.
  • references/cli-batch.md — 
    pdfcraft-cli batch
    for convert, OCR, and optimize over files and folders. Source: PdfCraft batch docs.
Both are distributed under the bundled MIT license. Relative links inside the snapshots resolve against 
https://github.com/storytold/pdfcraft/blob/main/docs/
. The desktop control channel is described in the upstream README; discover installed commands and flags rather than borrowing schemas from other ArtCraft applications.
PdfCraft 在两个随附的快照中记录了自动化功能，这些快照于 2026-11-02 从上游捕获：
  • references/mcp.md——MCP 服务器：启动标志、工具接口和文件访问限制。来源：PdfCraft MCP conventions。
  • references/cli-batch.md——用于批量转换、OCR 和优化文件及文件夹的 
    pdfcraft-cli batch
    。来源：PdfCraft batch docs。
两者均依据随附的 MIT 许可证分发。快照中的相对链接基于 
https://github.com/storytold/pdfcraft/blob/main/docs/
解析。桌面控制通道在上游 README中有详细说明；应发现已安装的命令和标志，而不是借用其他 ArtCraft 应用的 schema。

Select the surface

选择操作接口

  • MCP (headless, opt-in): 
    pdfcraft-cli mcp [--root DIR] [--compact] [--automation-read-root DIR] [--automation-write-root DIR]
    runs over stdin/stdout JSON lines, opens no port, and stops on EOF. It always runs in its own process; it never attaches to the desktop app.
  • Desktop control (live window): start 
    pdfcraft --control ~/.pdfcraft-control.json
    to let an agent see and operate the real interface — widget tree, clicks, typing, keys, commands, screenshots. Off by default, loopback only, and every connection must present the random token in that file. Keep the control file in a folder only you can write (never 
    /tmp
    ); 
    pdfcraft-cli ui
    refuses symlinked or world-readable control files. Drive it with 
    pdfcraft-cli ui --control <file> inspect|click|key|command|drag|screenshot|resize|focus|quit
    .
  • One-off file processing: 
    pdfcraft-cli batch
    (see the batch reference) and the CLI's other subcommands.
Discover available executables and sessions first and reuse a running session when possible. If the required connection or executable is missing, report the concrete prerequisite; this skill does not install PdfCraft or register MCP servers.
  • MCP（无头、选择性启用）： 
    pdfcraft-cli mcp [--root DIR] [--compact] [--automation-read-root DIR] [--automation-write-root DIR]
    通过 stdin/stdout JSON lines 运行，不开放端口，并在 EOF 时停止。它始终在独立进程中运行，绝不附着到桌面应用。
  • 桌面控制（实时窗口）： 启动 
    pdfcraft --control ~/.pdfcraft-control.json
    ，使 Agent 能够查看并操作真实界面，包括 widget 树、点击、输入、按键、命令和截图。该功能默认关闭，仅允许 loopback 连接，并且每次连接都必须提供该文件中的随机 token。将控制文件保存在只有你拥有写权限的文件夹中（绝不要放在 
    /tmp
    中）；
    pdfcraft-cli ui
    会拒绝使用符号链接或全局可读的控制文件。使用 
    pdfcraft-cli ui --control <file> inspect|click|key|command|drag|screenshot|resize|focus|quit
    进行操作。
  • 一次性文件处理： 
    pdfcraft-cli batch
    （参见批处理参考资料）以及 CLI 的其他子命令。
首先发现可用的可执行文件和会话，并在可能的情况下复用正在运行的会话。如果缺少所需的连接或可执行文件，请报告具体的前置条件；此 skill 不会安装 PdfCraft 或注册 MCP 服务器。

Tools and discovery

工具与发现

The MCP surface maps document work to five common tools: 
command_list {doc?, filter?, enabled_only?}
, 
command_run {id, params?}
, 
command_batch {steps, stop_on_error?}
, 
doc_inspect {doc?}
, and 
render_preview {doc?, page?, max_side?}
; existing task tools (
doc_open
, 
doc_save
, 
page_*
, 
form_*
, 
sign_*
, 
ocr_*
, …) remain available. 
pdfcraft://document
and 
pdfcraft://commands
resources mirror 
doc_inspect
and 
command_list
. Discover command ids and mapped tool schemas before running commands; unknown top-level MCP arguments are refused with JSON-RPC 
-32602
, and a failed batch reports per-step errors. Inspect the returned 
doc
id after 
file.open
and pass it to dependent commands.
MCP 接口通过五个常用工具映射文档处理工作：
command_list {doc?, filter?, enabled_only?}
、
command_run {id, params?}
、
command_batch {steps, stop_on_error?}
、
doc_inspect {doc?}
和 
render_preview {doc?, page?, max_side?}
；现有任务工具（
doc_open
、
doc_save
、
page_*
、
form_*
、
sign_*
、
ocr_*
等）仍可使用。
pdfcraft://document
和 
pdfcraft://commands
资源分别对应 
doc_inspect
和 
command_list
。运行命令前，应先发现命令 ID 和映射后的工具 schema；未知的顶层 MCP 参数会触发 JSON-RPC 
-32602
错误而被拒绝，批处理失败时会报告各步骤的错误。执行 
file.open
后，检查返回的 
doc
ID，并将其传递给依赖该 ID 的命令。

File access and output

文件访问与输出

Read and write roots are separate launch-time capabilities: every file a tool reads must lie inside the read root and every file it writes inside the write root; a root left out grants none of that access. Paths are resolved (links followed) and compared by whole folder names; a refused path is an ordinary, correctable tool error — do not bypass it with ambient filesystem commands. 
--root
confines everything and can be combined with the automation roots (both must accept the path). Keychain or certificate-store signing identities and printer jobs are not file access and are not covered.
Exports complete synchronously; there is no background progress or cancellation. Save the requested deliverable (edited PDF in place or to a new path) and verify outputs exist and render: re-open or 
doc_inspect
the saved file and 
render_preview
the pages that matter, checking text, annotations, form fields, and page order. For batches, read the JSON report and surface skipped files and per-file errors.
读写根目录是彼此独立的启动时权限：工具读取的每个文件都必须位于读根目录内，工具写入的每个文件都必须位于写根目录内；未指定某个根目录即不授予对应的访问权限。路径会被解析（跟随链接），并按完整文件夹名称进行比较；路径被拒绝属于普通且可纠正的工具错误——不要使用环境文件系统命令绕过限制。
--root
会限制所有访问，并可与自动化根目录结合使用（两者都必须接受该路径）。钥匙串或证书存储中的签名身份以及打印任务不属于文件访问，因此不在此限制范围内。
导出操作会同步完成；不提供后台进度或取消机制。保存要求的交付物（原地编辑 PDF 或保存到新路径），并验证输出文件存在且能够渲染：重新打开保存的文件或使用 
doc_inspect
检查，并使用 
render_preview
预览相关页面，检查文本、批注、表单字段和页面顺序。对于批处理任务，应读取 JSON 报告，并呈现被跳过的文件和每个文件的错误。