ai-pdf-filler-cli

用途

AI PDF Filler CLI 用于通过已安装的 simplicity-cli 命令行工具执行 PDF 表单自动填写工作流。当用户需要填写 PDF 表单时，优先使用直接命令执行而非手动调用 API。

主要能力

• 从本地 PDF 文件或 URL 创建新的表单填写任务。
• 使用上下文数据（--context）或源文档（--source-file/--source-url）作为填充依据。
• 支持对已有表单 ID 进行填写。
• 监控异步任务状态（status、wait）。
• 下载填写完成的 PDF 文件。
• 支持 JSON 输出以便自动化处理。

使用方式

安装与认证

确认 simplicity-cli 已安装：

simplicity-cli --help

若未安装，优先使用：

uv tool install ai-pdf-filler

备选：

python3 -m pip install ai-pdf-filler

认证方式（需在 https://simplicity.ai 创建账户并获取 API 密钥）：

• 交互式：simplicity-cli login，在隐藏提示中粘贴密钥。
• 非交互式：printf '%s' "$SIMPLICITY_AI_API_KEY" | simplicity-cli login --api-key-stdin
• 或设置环境变量：SIMPLICITY_AI_API_KEY

命令模式

从文件创建新表单并附加上下文：

simplicity-cli new \
  --form-file ./form.pdf \
  --context "name: John Doe; dob: 1990-07-07"

从文件创建新表单并附加源文档：

simplicity-cli new \
  --form-file ./form.pdf \
  --source-file ./w2.pdf \
  --source-file ./id.pdf

从 URL 创建新表单：

simplicity-cli new \
  --form-url "https://example.com/form.pdf" \
  --source-url "https://example.com/source.pdf"

对已有表单 ID 填写：

simplicity-cli existing FORM_ID --context "first_name: John; last_name: Smoke; dob: 1990-07-07"

任务监控：

simplicity-cli status TASK_ID
simplicity-cli wait TASK_ID --poll-interval-seconds 2 --max-wait-seconds 1800

规则与验证

• new 命令必须且只能指定 --form-file 或 --form-url 之一。
• new 命令至少需要一个源（--source-file/--source-url）或上下文（--context/--context-file）。
• --context 与 --context-file 互斥。
• --instructions 与 --instructions-file 互斥。
• 当设置 --no-download 时，拒绝 --output。

执行偏好

• 交互式运行使用人类可读输出模式。
• 自动化或需要机器可解析输出时使用 --json。
• 仅在用户明确要求异步交接时使用 --no-wait，否则等待完成。
• 用户指定文件路径时使用 --output。

失败处理

• 若找不到 simplicity-cli，先安装 ai-pdf-filler 再重试。
• 若缺少认证，提示运行 simplicity-cli login（或 --api-key-stdin）或设置 SIMPLICITY_AI_API_KEY。
• 若任务失败，报告任务 ID 和失败消息，不隐藏 API 错误详情。
• 若任务成功但下载失败，仍返回任务/表单标识符。
• 脚本场景下，使用 --json 重新运行并暴露 error.code 和 error.message。

适用场景

适用于需要自动填写 PDF 表单的各类流程，例如税务申报、行政申请、身份信息录入等，尤其适合批量处理或集成到自动化脚本中。

限制

• 需要安装 simplicity-cli 并配置有效的 API 密钥。
• 具体收费、价格、平台兼容性等细节暂未提供。
• 功能依赖 simplicity.ai 服务，需网络连接。