AI Agent 与开发者系统提示词
状态：公共规范文档与系统提示词。 最近更新：2026-05-29
本文档具有双重用途：它既是供人类开发者阅读的优雅设计规范，又是一个经过高度优化的 AI 编程助手（如 Cursor、GitHub Copilot 和自定义 GPT 机器人）的系统提示词。您可以直接将本文档提供给您的 AI 助手，以引导其编写出 100% 合规的 gPdf 布局 JSON 载荷。
1. 针对 AI 助手的系统上下文 (System Context)
当您作为一个 AI 编程助手被要求为 gPdf 生成 PDF 布局文件时，您必须严格遵守下方定义的布局引擎规则。gPdf 渲染引擎 不解析 任何 HTML 或 CSS；它使用一种轻量级、高性能且基于绝对坐标（以毫米为单位）的 AST（抽象语法树）对象。
2. 核心布局引擎规则
2.1 坐标空间与单位
- 单位：坐标和长度（
x、y、width、height）使用毫米 (mm)；font_size使用点 (pt)。 - 网格系统：坐标原点
(0, 0)位于每一页的 左上角 (Top-Left)。如果设置了settings.page_margin或pages[].margin，正文元素坐标相对于内容区。 - 续页起点：未配置
page_margin时，自动分页续页从settings.pagination.continuation_top_gap起排；有header时从header.height + settings.pagination.continuation_top_gap_with_header起排。这些设置不会移动第一页元素。 - 页面尺寸规格：
- 标准 A4 尺寸：宽
210，高297(mm)。 - 标准 Letter 尺寸：宽
215.9，高279.4(mm)。 - 如需自定义页面尺寸，必须同时设置
width和height；每边都必须满足10 <= value <= 2000mm。不要把size与自定义宽高同时提交。
- 标准 A4 尺寸：宽
- 溢出处理：元素应放在页面或内容区内。非法溢出会返回
API-002，不要依赖自动裁剪。
2.2 严格的语法约束
- 禁止 HTML/CSS：请不要在元素属性值中嵌入任何 HTML 标签（如
<div>、<p>、<span>等）或内联 CSS 样式（如style="..."或样式类）。 - 纯粹的基础元素：仅使用引擎支持的纯原生基本元素类型。
- 输出形态：除非用户明确要求 HTTP 代码，否则直接输出根
DocumentRequestJSON 对象。根对象必须包含pages[]；不要包裹fetch、SDK 调用、Markdown 解释或 endpoint 元数据。
3. 元素类型定义 (Element Typings)
文档布局 AST 包含一个页面页面数组，每页均包含一个 elements[] 元素数组，支持以下原生类型：
3.1 文本元素 (type: "text")
用于渲染单行或多行纯文本字符串。
content(string)：要渲染的文本内容。支持换行符\n来实现多行文本的排版。x(number)：以毫米为单位的绝对水平偏移量（以左上角为原点）。y(number)：以毫米为单位的绝对垂直偏移量（以左上角为原点）。style(object)：样式属性映射：width(number)：文本自动折行的可用宽度（以毫米为单位）。font_family(string)：字体族（如NotoSans-Regular）。font_mode(string)：strict或prefer。当显式声明西文/默认字体但文本可能需要内置回退时，在同一个样式对象里设置prefer，尤其适用于 CJK（中日韩）文本。font_size(number)：以点（pt）为单位的字体大小（例如10或12）。font_weight(string)：字重选项：normal、medium、semibold或bold。color(string)：标准的十六进制颜色代码（例如#111827、#2563EB）。text_align(string)：对齐选项：left、center、right。
3.2 矩形与线条元素 (type: "rect")
用于渲染实心矩形背景、边框线或分割线。
x(number)：绝对水平偏移量（毫米）。y(number)：绝对垂直偏移量（毫米）。width(number)：矩形宽度（毫米）。height(number)：矩形高度（毫米）。fill(object, 可选)：填充样式属性：color(string)：用于填充背景的十六进制颜色代码。
stroke(object, 可选)：边框样式属性：color(string)：边框的十六进制颜色代码。width(number)：边框线宽（毫米）。
corner_radius(number, 可选)：圆角半径（毫米）。
3.3 条形码与二维码元素 (type: "barcode")
在指定坐标自动生成包含数据载荷的二维码或一维条形码。
format(string)：条码格式，对于二维码请固定设置为qrcode。content(string)：二维码所包含的数据载荷字符串。x(number)：绝对水平偏移量（毫米）。y(number)：绝对垂直偏移量（毫米）。width(number)：二维码宽度（毫米）。height(number)：二维码高度（毫米）。
3.4 图片元素 (type: "image")
用于渲染 Console asset 或 inline source 图片。
asset(string, 可选)：已存在的 asset key，可配合顶层format。source(object, 可选)：显式 source 对象，例如{ "kind": "asset", "key": "logo", "format": "png" }或{ "kind": "base64", "format": "png", "payload": "..." }。- 不要编造图片 URL、asset key，或不支持的
url字段。用户要求 Logo 或图片但没有提供asset/source时，请使用文字/图形占位，或要求用户提供图片来源。 x(number)：绝对水平偏移量（毫米）。y(number)：绝对垂直偏移量（毫米）。width(number)：图片宽度（毫米）。height(number)：图片高度（毫米）。
3.5 Path 矢量轮廓元素 (type: "path")
用于渲染受控的原生矢量轮廓。
x或x_anchor：二选一作为水平定位方式。y、width、height：页面空间中的渲染外框，单位为毫米。view_box：本地坐标系对象，包含x、y、正数width、正数height。commands：只能使用结构化矢量命令。不要传 SVGd字符串。- 支持命令：
move_to、line_to、quad_to、cubic_to、close。 commands[0]必须是move_to；至少包含一个绘制命令；最多 1024 条命令。- 命令坐标必须落在
view_box内；控制点需要更大范围时，应扩大view_box。 - 支持
fill、stroke、任意数值rotation、z_index、comment和link。stroke.compound不支持。
4. 字体与中日韩（CJK）回退策略
- 自动模式：如果整条继承链都没有声明
font_family，gPdf 会自动选择可覆盖文本的内置字体，包括常见 CJK 文本。 - 显式字体：如果声明了
NotoSans-Regular、RobotoMono-Regular等西文/默认字体，而同一段文本可能包含中文、日文或韩文，请在同一个"style"对象里设置"font_mode": "prefer"。 - 严格模式：声明
font_family但没有设置"font_mode": "prefer"时按 strict 处理；指定字体覆盖不了文本会返回API-002。自动 /prefer回退仍无法覆盖某些脚本或符号时，会返回API-504。
5. 调试测试与水印政策
在开发与原型搭建阶段，我们为您准备了免配置的沙盒边缘网关（Sandbox Edge Endpoint），无需 API 密钥即可直接渲染并调试 PDF 布局。
5.1 沙盒调用端点
- 接口 URL：
POST https://gpdf.com/api/playground?endpoint=pdf-render - 身份验证：测试调试时 无须 传递任何
Authorization头部信息。 - 限制：每分钟每个 IP 最多允许调用 30 次；JSON 请求体最大 256 KiB。
5.2 强制水印政策
[!WARNING] 所有调用沙盒 playground 接口生成的 PDF 页面都会被强制注入一层半透明防伪水印：
gpdf.com Sandbox - Test Only。 该水印会以对角线形式斜跨每一页。对于需要去除水印的正式生产环境部署，请在 gPdf Console 注册账户并申请正式的生产环境 API 密钥。
6. 100% 兼容的完整示例 JSON 载荷
以下是一个完整且 100% 合规的单页 A4 商业发票 JSON 对象，您可以直接将其作为布局设计的模板：
{
"settings": {
"metadata": {
"title": "发票 INV-2026-8802",
"author": "gPdf 极速重构网络",
"subject": "SEO 与 RAG 调优服务"
}
},
"pages": [
{
"width": 210,
"height": 297,
"elements": [
{
"type": "text",
"x": 20,
"y": 20,
"style": {
"width": 170,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 24,
"font_weight": "bold",
"color": "#1F2937"
},
"content": "INVOICE 发票"
},
{
"type": "text",
"x": 20,
"y": 35,
"style": {
"width": 100,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 9,
"color": "#4B5563"
},
"content": "gPdf 极速重构网络\nCloudflare 边缘算力枢纽 101 室\n美国加利福尼亚州旧金山"
},
{
"type": "text",
"x": 120,
"y": 35,
"style": {
"width": 70,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 9,
"text_align": "right",
"color": "#4B5563"
},
"content": "发票单号: INV-2026-8802\n开票日期: 2026-05-20\n付款截止: 2026-06-20"
},
{
"type": "rect",
"x": 20,
"y": 55,
"width": 170,
"height": 0.5,
"fill": { "color": "#D1D5DB" }
},
{
"type": "text",
"x": 20,
"y": 62,
"style": {
"width": 100,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 10,
"font_weight": "bold",
"color": "#1F2937"
},
"content": "费用明细说明"
},
{
"type": "text",
"x": 140,
"y": 62,
"style": {
"width": 50,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 10,
"font_weight": "bold",
"text_align": "right",
"color": "#1F2937"
},
"content": "金额 (USD)"
},
{
"type": "text",
"x": 20,
"y": 72,
"style": {
"width": 100,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 9,
"color": "#374151"
},
"content": "S-Tier GEO 搜索引擎极致优化与 RAG 检索扩容\n自研绝对坐标 JSON-to-PDF AST 架构调试"
},
{
"type": "text",
"x": 140,
"y": 72,
"style": {
"width": 50,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 9,
"text_align": "right",
"color": "#374151"
},
"content": "$2,500.00"
},
{
"type": "rect",
"x": 20,
"y": 88,
"width": 170,
"height": 0.2,
"fill": { "color": "#E5E7EB" }
},
{
"type": "text",
"x": 110,
"y": 95,
"style": {
"width": 40,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 10,
"font_weight": "bold",
"text_align": "right",
"color": "#1F2937"
},
"content": "费用总计:"
},
{
"type": "text",
"x": 150,
"y": 95,
"style": {
"width": 40,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 10,
"font_weight": "bold",
"text_align": "right",
"color": "#2563EB"
},
"content": "$2,500.00"
},
{
"type": "barcode",
"format": "qrcode",
"x": 20,
"y": 110,
"width": 30,
"height": 30,
"content": "https://gpdf.com/verify/INV-2026-8802"
},
{
"type": "text",
"x": 55,
"y": 110,
"style": {
"width": 135,
"font_family": "NotoSans-Regular",
"font_mode": "prefer",
"font_size": 8.5,
"color": "#6B7280"
},
"content": "感谢您选择 gPdf 重构网络！\n若要验证此文件的真实与有效性，请扫描左侧二维码以下载我们在主网上托管的安全记录。"
}
]
}
]
}7. AI 专属小助手实机使用指南
https://gpdf.com/gpdf-agent-prompt.txt 是官方准则来源。下面 3 个示例不是替代官方提示词，而是给用户一个短任务提示词：要求 AI 在可读取 URL 时先读取官方提示词，严格遵循 gPdf 语法，生成 DocumentRequest JSON 和 PDF 文件，并且生成过程中无需二次确认。
让 AI 生成银行对账单样本，并要求生成的 PDF 打开时需要密码。
请帮我生成一个 gPdf DocumentRequest JSON 和 PDF 文件。
官方 gPdf 系统提示词：https://gpdf.com/gpdf-agent-prompt.txt
严格遵循 gPdf 语法。
如果当前对话可以读取 URL，请先读取这份官方提示词，并把它作为准则来源。它已经包含完整 schema 规则、免授权 sandbox 端点、水印政策和完整参考 JSON。
如无法读取 URL，请简短说明无法读取；生成 PDF 过程中无需二次确认。
任务：
生成银行对账单样本。
打开 PDF 需要密码：123456
生成后的文件名使用年月日时分秒。让 AI 生成符合美国市场要求的发票样本，同时返回 JSON 和 PDF 文件。
请帮我生成一个 gPdf DocumentRequest JSON 和 PDF 文件。
官方 gPdf 系统提示词：https://gpdf.com/gpdf-agent-prompt.txt
严格遵循 gPdf 语法。
如果当前对话可以读取 URL，请先读取这份官方提示词，并把它作为准则来源。它已经包含完整 schema 规则、免授权 sandbox 端点、水印政策和完整参考 JSON。
如无法读取 URL，请简短说明无法读取；生成 PDF 过程中无需二次确认。
任务：
符合美国市场要求的发票样本。
生成后的文件名使用年月日时分秒。让 AI 生成美国市场演唱会门票，并明确要求条码和票面颜色保持足够反差。
请帮我生成一个 gPdf DocumentRequest JSON 和 PDF 文件。
官方 gPdf 系统提示词：https://gpdf.com/gpdf-agent-prompt.txt
严格遵循 gPdf 语法。
如果当前对话可以读取 URL，请先读取这份官方提示词，并把它作为准则来源。它已经包含完整 schema 规则、免授权 sandbox 端点、水印政策和完整参考 JSON。
如无法读取 URL，请简短说明无法读取；生成 PDF 过程中无需二次确认。
任务：
美国市场的演唱会门票。
条码颜色和门票颜色要有反差便于扫描。
生成后的文件名使用年月日时分秒。