开发者 Cookbook

为 ISV 和组织内开发者准备的 AIOS 接入示例。从一个访客小程序开始,让客服按约定的参数查数据或预填表单。

打开访客样板间

接入步骤

先完成小程序自己的界面和业务逻辑,再给客服声明工具。当前协议只在访客样板间试用。

  1. 准备一个受众为「访客」的 artifact 小程序,把它加入专用测试角色的「可见应用」。
  2. 组织管理员用 POST /api/apps?patch=1 给已有应用写入下方配置。将示例应用名、表名和字段替换成自己的。查询目录只声明允许访客读取的参考字段。
  3. 由组织管理员在访客角色编辑页开启「客服工具协议」。默认关闭。环境尚未开放试用时,可以先在样板间复现下方用例。

发票草稿

用 open 打开空白草稿,也可预填已知的购方、税号和明细。样板用 chat-card.json 声明 {"mode":"draft"},便于多轮续填。

样板间输入

打开一张发票草稿。购方云杉科技,税号 DEMO123456,云服务 2 项,每项 120 元。

打开草稿核对合计 ¥240。再说「税号改为 DEMO987654」,购方和明细应保留。

应用配置
JSON
{
  "name": "发票草稿",
  "mode": "artifact",
  "受众": "访客",
  "客服工具": {
    "version": 1,
    "name": "visitor_invoice_draft",
    "description": "打开或续填发票草稿。只传访客给过的字段,由访客核对后保存。",
    "parameters": {
      "type": "object",
      "properties": {
        "intent": {
          "type": "string",
          "maxLength": 4,
          "description": "new 新建,edit 续填当前草稿。",
          "enum": [
            "new",
            "edit"
          ]
        },
        "buyer": {
          "type": "string",
          "maxLength": 80,
          "description": "购方名称"
        },
        "taxId": {
          "type": "string",
          "maxLength": 30,
          "description": "税号"
        },
        "lines": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 80,
                "description": "项目名称"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9999
              },
              "price": {
                "type": "number",
                "minimum": 0.01,
                "maximum": 999999
              }
            },
            "required": [
              "name"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "intent"
      ],
      "additionalProperties": false
    },
    "operation": {
      "kind": "open"
    }
  }
}
在小程序里接收预填和续填
JavaScript
const { 参数: initial } = await aios.context()
if (initial) applyPrefill(initial)
aios.onSay((_message, details) => {
  if (details?.参数) applyPrefill(details.参数)
})

将片段接到自己的 applyPrefill,只更新收到的字段。由访客点击保存,再调用应用已授权的写入动作。

验收与回退

  • 分别测试命中和无匹配,再测试关键词与展馆组合。核对卡片上的参数和总数。
  • 依次验证空白、部分及完整预填,续填时核对未改字段。
  • 关闭测试角色开关,或移除该角色对应用的可见权限。刷新访客入口,核对该工具不可用。