Surflet

Payload Schema

完整的 Payload 结构定义

本页面定义了 Surflet Publish API 接受的完整 Payload 结构。

顶层结构

{
  "version": "1.0",
  "page_type": "approval",
  "template": "auto",
  "title": "...",
  "summary": "...",
  "priority": "high",
  "tags": ["..."],
  "auto_refresh_seconds": 3600,
  "theme": { "mode": "dark", "accent": "#8b5cf6" },
  "access": { "..." : "..." },
  "blocks": [],
  "actions": [],
  "notify": { "..." : "..." },
  "on_action": { "..." : "..." },
  "approval_chain": { "..." : "..." }
}
字段类型必填说明
versionstring是Payload 版本，当前固定为 "1.0"
page_typestring是页面类型：briefing / approval / review / form / dashboard / custom
templatestring否渲染模板，"auto" 为自动选择
titlestring是页面标题
summarystring否摘要描述
prioritystring否优先级：low / normal / high / urgent
tagsstring[]否标签列表
localestring否语言区域（如 zh-CN、en-US）
expires_innumber否过期时间（秒），默认 7 天 (604800)
idempotency_keystring否幂等键，防止重复发布
custom_dataobject否自定义元数据（不渲染，仅存储和回调时传递）
accessobject否访问控制配置
blocksarray是内容块列表
actionsarray否操作按钮列表
notifyobject否分发渠道配置
on_actionobject否回调配置
auto_refresh_secondsnumber否自动刷新间隔（秒），页面定时重载
themeobject否主题定制（暗色模式、自定义配色）
approval_chainobject否审批链配置（page_type 为 approval 时使用）

顶层元信息字段

title、summary、priority、tags 等元信息字段直接位于 payload 顶层（不再嵌套在 meta 对象中）。

{
  "title": "退款审批 #4821",
  "summary": "客户投诉产品损坏，AI 建议全额退款",
  "priority": "high",
  "tags": ["refund", "cs", "auto-analysis"],
  "locale": "zh-CN",
  "expires_in": 604800,
  "idempotency_key": "refund-4821-v1",
  "custom_data": {
    "ticket_id": "4821",
    "agent": "refund-bot"
  }
}

这些字段已在上方顶层结构表格中列出，此处不再重复。

auto_refresh_seconds — 自动刷新

设置页面自动刷新间隔（单位：秒）。适用于 dashboard 类型的实时监控页面。

{
  "auto_refresh_seconds": 3600
}

页面将每隔指定秒数自动重载内容。设为 0 或不设置则不自动刷新。

theme — 主题定制

通过 theme 对象设置暗色模式和自定义配色。

{
  "theme": {
    "mode": "dark",
    "accent": "#8b5cf6",
    "bg": "#1a1a2e",
    "text": "#e0e0e0",
    "border": "#333355"
  }
}
字段类型说明
modestring"dark" 或 "light"（默认）
accentstring主色调（默认 #3b82f6）
bgstring可选，自定义背景颜色
textstring可选，自定义文字颜色
borderstring可选，自定义边框颜色

access — 访问控制

{
  "access": {
    "mode": "authenticated",
    "allowed_identities": [
      {"type": "email", "value": "[email protected]"},
      {"type": "domain", "value": "company.com"}
    ],
    "one_time_options": {
      "burn_after_seconds": 300
    },
    "view_limit": 5,
    "expires_at": "2026-04-01T00:00:00Z",
    "password_hash": "sha256:a1b2c3d4..."
  }
}
字段类型说明
modestring模式：public / authenticated / one_time / view_limited / time_limited / password
allowed_identitiesarray允许的身份列表（authenticated 模式）
allowed_identities[].typestring身份类型：email / domain / group / role
allowed_identities[].valuestring身份值
one_time_options.burn_after_secondsnumber查看后销毁延迟秒数（one_time 模式）
view_limitnumber最大查看次数（view_limited 模式）
expires_atstring过期时间 ISO 8601（time_limited 模式）
password_hashstring密码哈希（password 模式），格式 sha256:<hex>

blocks — 内容块

{
  "blocks": [
    {
      "type": "key_value",
      "data": {
        "title": "工单概览",
        "pairs": [
          {"key": "客户", "value": "Alice Wang"},
          {"key": "金额", "value": "$127.50"}
        ]
      }
    },
    {
      "type": "callout",
      "data": {
        "message": "AI 建议全额退款",
        "style": "info"
      }
    },
    {
      "type": "table",
      "data": {
        "title": "事件时间线",
        "columns": [
          {"key": "date", "label": "日期"},
          {"key": "event", "label": "事件"}
        ],
        "rows": [
          {"date": "2026-03-20", "event": "下单"}
        ]
      }
    }
  ]
}

每个 Block 的 type 字段决定其 data 结构。支持的 25+ 种类型详见 Block 类型参考。

actions — 操作按钮

{
  "actions": [
    {
      "action_id": "act_approve",
      "label": "批准退款",
      "style": "primary",
      "requires_comment": false,
      "confirm_message": "确定批准退款 $127.50？",
      "disabled": false,
      "visible_to": ["[email protected]"]
    },
    {
      "action_id": "act_reject",
      "label": "拒绝",
      "style": "danger",
      "requires_comment": true,
      "comment_placeholder": "请填写拒绝理由..."
    },
    {
      "action_id": "act_escalate",
      "label": "升级处理",
      "style": "secondary"
    }
  ]
}
字段类型必填说明
action_idstring是唯一标识，回调时使用
labelstring是按钮显示文本
stylestring否样式：primary / secondary / danger，默认 secondary
requires_commentboolean否是否要求填写理由，默认 false
comment_placeholderstring否理由输入框占位文本
confirm_messagestring否点击后的确认弹窗提示
disabledboolean否是否禁用
visible_tostring[]否仅对指定身份可见

notify — 分发渠道

{
  "notify": {
    "channels": [
      {
        "type": "slack",
        "target": "#cs-approvals",
        "mention": ["@manager"]
      },
      {
        "type": "email",
        "to": ["[email protected]"],
        "subject_prefix": "[退款审批]"
      }
    ],
    "retry": {
      "max_attempts": 3,
      "backoff": "exponential",
      "initial_delay_seconds": 60
    },
    "schedule": {
      "send_at": "2026-03-24T09:00:00Z",
      "timezone": "Asia/Shanghai"
    }
  }
}
字段类型说明
channelsarray渠道列表
channels[].typestring渠道类型（见 分发渠道指南）
retryobject重试配置
retry.max_attemptsnumber最大重试次数
retry.backoffstring退避策略（exponential / linear / fixed）
retry.initial_delay_secondsnumber初始延迟秒数
scheduleobject定时发送配置
schedule.send_atstring发送时间 ISO 8601
schedule.timezonestring时区

on_action — 回调配置

{
  "on_action": {
    "default_url": "https://agent.example.com/webhook/surflet",
    "action_urls": {
      "act_approve": "https://agent.example.com/webhook/approve",
      "act_reject": "https://agent.example.com/webhook/reject"
    },
    "hmac_secret": "your-secret-key-here",
    "events": [
      "action.executed",
      "approval.step_completed",
      "approval.chain_completed",
      "page.expired",
      "page.viewed",
      "form.submitted"
    ],
    "headers": {
      "X-Custom-Header": "custom-value"
    },
    "retry": {
      "max_attempts": 5,
      "backoff": "exponential",
      "initial_delay_seconds": 60
    }
  }
}
字段类型必填说明
default_urlstring是默认回调 URL
action_urlsobject否按 action_id 配置不同的回调 URL
hmac_secretstring否HMAC-SHA256 签名密钥
eventsstring[]否订阅的事件类型，默认全部
headersobject否自定义请求头
retryobject否重试配置

approval_chain — 审批链

Sequential（顺序）

{
  "approval_chain": {
    "mode": "sequential",
    "steps": [
      {
        "step_id": "step_manager",
        "name": "经理审批",
        "assignees": [
          {"type": "email", "value": "[email protected]"}
        ],
        "policy": {
          "type": "any"
        },
        "timeout_hours": 24,
        "on_timeout": "escalate",
        "escalation_target": {
          "type": "email",
          "value": "[email protected]"
        }
      },
      {
        "step_id": "step_finance",
        "name": "财务确认",
        "assignees": [
          {"type": "email", "value": "[email protected]"},
          {"type": "email", "value": "[email protected]"}
        ],
        "policy": {
          "type": "threshold",
          "min_approvals": 1
        }
      }
    ],
    "on_reject_at_any_step": "halt"
  }
}

Parallel（并行）

{
  "approval_chain": {
    "mode": "parallel",
    "steps": [
      {
        "step_id": "step_legal",
        "name": "法务审核",
        "assignees": [{"type": "email", "value": "[email protected]"}],
        "policy": {"type": "any"}
      },
      {
        "step_id": "step_security",
        "name": "安全审核",
        "assignees": [{"type": "email", "value": "[email protected]"}],
        "policy": {"type": "any"}
      }
    ],
    "on_reject_at_any_step": "halt"
  }
}

Conditional（条件）

{
  "approval_chain": {
    "mode": "conditional",
    "condition_field": "amount",
    "routes": [
      {
        "condition": {"operator": "lt", "value": 1000},
        "steps": [
          {
            "step_id": "step_manager",
            "name": "经理审批",
            "assignees": [{"type": "email", "value": "[email protected]"}],
            "policy": {"type": "any"}
          }
        ]
      },
      {
        "condition": {"operator": "gte", "value": 1000},
        "steps": [
          {
            "step_id": "step_manager",
            "name": "经理审批",
            "assignees": [{"type": "email", "value": "[email protected]"}],
            "policy": {"type": "any"}
          },
          {
            "step_id": "step_cfo",
            "name": "CFO 审批",
            "assignees": [{"type": "email", "value": "[email protected]"}],
            "policy": {"type": "any"}
          }
        ]
      }
    ]
  }
}

Step 字段参考

字段类型必填说明
step_idstring是步骤唯一标识
namestring是步骤显示名称
assigneesarray是审批人列表
assignees[].typestring是类型：email / group / role
assignees[].valuestring是值
policyobject是决策策略
policy.typestring是类型：any / unanimous / threshold / weighted
policy.min_approvalsnumber否最低批准数（threshold 类型）
policy.weightsobject否权重映射（weighted 类型）
policy.thresholdnumber否加权阈值（weighted 类型）
timeout_hoursnumber否超时小时数
on_timeoutstring否超时行为：escalate / auto_approve / auto_reject / skip
escalation_targetobject否升级目标（on_timeout 为 escalate 时）

Chain 字段参考

字段类型必填说明
modestring是模式：sequential / parallel / conditional
stepsarray是步骤列表（sequential / parallel 模式）
condition_fieldstring否条件字段（conditional 模式）
routesarray否路由列表（conditional 模式）
on_reject_at_any_stepstring否拒绝行为：halt / continue / restart

完整示例

以下是一个包含所有主要字段的完整 Payload 示例：

{
  "version": "1.0",
  "page_type": "approval",
  "template": "auto",
  "title": "退款审批 #4821",
  "summary": "客户 Alice Wang 投诉产品损坏，AI 建议全额退款 $127.50",
  "priority": "high",
  "tags": ["refund", "cs", "auto-analysis"],
  "locale": "zh-CN",
  "expires_in": 604800,
  "idempotency_key": "refund-4821-v1",
  "custom_data": {
    "ticket_id": "4821",
    "order_id": "ORD-20260321-7891",
    "agent": "refund-bot"
  },
  "access": {
    "mode": "authenticated",
    "allowed_identities": [
      {"type": "email", "value": "[email protected]"},
      {"type": "email", "value": "[email protected]"},
      {"type": "email", "value": "[email protected]"}
    ]
  },
  "blocks": [
    {
      "type": "key_value",
      "data": {
        "title": "工单概览",
        "pairs": [
          {"key": "客户", "value": "Alice Wang"},
          {"key": "订单号", "value": "#ORD-20260321-7891"},
          {"key": "金额", "value": "$127.50", "style": "highlight"},
          {"key": "原因", "value": "产品到货即损坏"}
        ]
      }
    },
    {
      "type": "callout",
      "data": {
        "message": "**AI 建议**：全额退款。历史记录良好，首次投诉。置信度 95%。",
        "style": "info"
      }
    },
    {
      "type": "table",
      "data": {
        "title": "事件时间线",
        "columns": [
          {"key": "date", "label": "日期"},
          {"key": "event", "label": "事件"},
          {"key": "detail", "label": "详情"}
        ],
        "rows": [
          {"date": "2026-03-20", "event": "下单", "detail": "标准配送"},
          {"date": "2026-03-22", "event": "签收", "detail": "本人签收"},
          {"date": "2026-03-22", "event": "投诉", "detail": "产品外壳破损"}
        ]
      }
    },
    {
      "type": "gallery",
      "data": {
        "title": "损坏证据",
        "items": [
          {
            "url": "https://storage.example.com/evidence/damage-01.jpg",
            "caption": "产品正面损坏"
          }
        ]
      }
    }
  ],
  "actions": [
    {
      "action_id": "act_approve",
      "label": "批准退款",
      "style": "primary",
      "confirm_message": "确定批准退款 $127.50？"
    },
    {
      "action_id": "act_partial",
      "label": "部分退款",
      "style": "secondary"
    },
    {
      "action_id": "act_reject",
      "label": "拒绝",
      "style": "danger",
      "requires_comment": true,
      "comment_placeholder": "请填写拒绝理由..."
    }
  ],
  "notify": {
    "channels": [
      {
        "type": "slack",
        "target": "#cs-approvals",
        "mention": ["@manager"]
      },
      {
        "type": "email",
        "to": ["[email protected]"],
        "subject_prefix": "[退款审批]"
      }
    ]
  },
  "on_action": {
    "default_url": "https://agent.example.com/webhook/surflet",
    "hmac_secret": "whsec_abc123...",
    "events": [
      "action.executed",
      "approval.chain_completed"
    ]
  },
  "approval_chain": {
    "mode": "sequential",
    "steps": [
      {
        "step_id": "step_manager",
        "name": "经理审批",
        "assignees": [
          {"type": "email", "value": "[email protected]"}
        ],
        "policy": {"type": "any"},
        "timeout_hours": 24,
        "on_timeout": "escalate",
        "escalation_target": {
          "type": "email",
          "value": "[email protected]"
        }
      },
      {
        "step_id": "step_finance",
        "name": "财务确认",
        "assignees": [
          {"type": "email", "value": "[email protected]"},
          {"type": "email", "value": "[email protected]"}
        ],
        "policy": {
          "type": "threshold",
          "min_approvals": 1
        }
      }
    ],
    "on_reject_at_any_step": "halt"
  }
}

Analytics & Quality Score

Page analytics and agent quality scoring

On this page

顶层结构顶层元信息字段auto_refresh_seconds — 自动刷新theme — 主题定制access — 访问控制blocks — 内容块actions — 操作按钮notify — 分发渠道on_action — 回调配置approval_chain — 审批链Sequential（顺序）Parallel（并行）Conditional（条件）Step 字段参考Chain 字段参考完整示例