make-integration

make-integration

适用场景

当用户需要 Make Platform 集成能力时使用此技能，尤其是发票和账单的 OCR 识别。

当前能力：

• 通过 makecli integration ocr 识别账单和发票 OCR
• 可选的发票真伪验证
• 从 PDF/OFD/PNG/JPG/JPEG 文件中提取结构化信息
• 返回发票字段、印章、二维码、坐标以及可选的裁剪图像

依赖项

make-integration 依赖 makecli 技能和已安装的 makecli 二进制文件。

操作说明

运行前检查

运行 OCR 前：

0. 检查是否已安装 makecli。

   • 如未安装：运行 brew tap qfeius/makecli && brew install makecli

1. 检查 OCR 命令是否存在。

   • 运行 makecli integration ocr --help
   • 如果命令不存在，运行 makecli update 或升级 makecli。

2. 检查所选配置。

   • 运行 makecli configure verify --profile <profile> --output=json
   • 如果尚未配置，请告知用户运行交互式设置： ! makecli configure token --profile <profile>
   • 如果令牌无效或缺失，请停止并要求用户配置 makecli 凭据。不得在 makecli 之外识别、提取、推断、纠正或补全发票内容。

3. 检查 makecli 中的请求基础 URL。

   • 运行 makecli configure get server-url --profile <profile>
   • 优先使用配置文件中设置的服务 URL，而不是硬编码环境 URL。
   • 如果配置文件未设置服务 URL，makecli 将使用自己的默认基础 URL。

4. 检查输入文件。

   • 支持的扩展名：.pdf、.ofd、.png、.jpg、.jpeg
   • 仅上传用户提供或批准的文件。

识别工作流

如果用户只需要易读的结果，请使用表格输出：

makecli integration ocr -f <file> --profile <profile>

如果需要解析字段或将结果传入另一项 Make 操作，请使用 JSON 输出：

makecli integration ocr -f <file> --output=json --profile <profile>

常用选项：

# Recognize selected pages
makecli integration ocr -f invoice.pdf --pages "1,3,2"
makecli integration ocr -f invoice.pdf --pages "2-4"

# Bind a business document id
makecli integration ocr -f invoice.pdf --business-id <business-id>

# Explicitly disable invoice authenticity verification
makecli integration ocr -f invoice.pdf --verify-vat=false

# Optional response controls
makecli integration ocr -f invoice.pdf --coord-restore-original
makecli integration ocr -f invoice.pdf --crop-complete
makecli integration ocr -f invoice.pdf --crop-value
makecli integration ocr -f invoice.pdf --merge-elec
makecli integration ocr -f invoice.pdf --return-ppi

输出处理

对于 --output=json，请从以下内容中汇总：

data.file_name
data.bill_count
data.processing_duration_ms
data.result.pages[].bills[].items[]
data.result.pages[].bills[].stamps[]
data.result.pages[].bills[].qr_codes[]

向用户报告结果时：

• 在可用时，包含文件名、账单数量、页数和处理时长。
• 提取非空的 items[].value 字段。
• 如果存在且有用，请包含印章和二维码。
• 在常规摘要中不要包含 base64 裁剪图像数据。
• 仅报告 makecli integration ocr 成功输出中的 OCR 识别值。
• 仅将 makecli integration ocr 的输出视为识别结果。不得使用视觉检查、模型知识、文件解析、其他 OCR 工具、直接 HTTP 调用或用户可见的图像内容来识别或填充发票数据。
• 仅在技能文档示例、已提交样例、日志或调试片段中遮盖或替换特殊信息和个人信息。
• 如果要将 OCR 结果写入 Make 记录，请在识别后调用 makecli 技能执行记录操作。

故障处理

• API 错误 [990300403]: token验证失败
  • 所选环境中的令牌无效。请要求用户配置适用于该环境的令牌，然后通过 makecli 重试 OCR。
• API 错误 [990300404]: 服务不存在
  • 所选的 makecli 服务 URL 可能尚未部署 OCR 路由。请检查配置文件中的服务 URL 或确认是否已部署。
• unsupported file extension
  • 请用户提供受支持的 PDF/OFD/PNG/JPG/JPEG 文件。
• 打开文件失败
  • 检查本地路径和权限。
• 任何 makecli OCR 故障
  • 报告 makecli 故障，并说明下一步 makecli 配置或环境操作。不得继续自行识别发票内容。

硬性规则

• 不要将用户提供的令牌写入仓库文件。
• 用户提供一次性令牌时，优先使用临时配置目录。
• 除非用户要求保留，否则运行后清理临时凭据和 OCR 结果文件。
• 切勿打印、提交或复制令牌。
• 除非用户提供或批准，否则不要上传本地文件。
• 不要在技能示例中提交真实的发票号码、纳税人识别号、订单号、电话号码、地址、令牌、二维码载荷或其他敏感值。
• 不要将任何非 makecli 路径用作此技能的备用方案。如果 makecli 无法运行或 OCR 失败，先修复 makecli 配置／环境，然后通过 makecli 重试。