接入步骤
先完成小程序自己的界面和业务逻辑,再给客服声明工具。当前协议只在访客样板间试用。
- 准备一个受众为「访客」的 artifact 小程序,把它加入专用测试角色的「可见应用」。
- 组织管理员用
POST /api/apps?patch=1给已有应用写入下方配置。将示例应用名、表名和字段替换成自己的。查询目录只声明允许访客读取的参考字段。 - 由组织管理员在访客角色编辑页开启「客服工具协议」。默认关闭。环境尚未开放试用时,可以先在样板间复现下方用例。
查展商
使用 lookup 组合查询关键词和展馆。这个最小配置使用 name、hall、booth、products 四列。展馆值可存「B1 供应链馆」,筛选时传 B1。
样板间输入
查 B1 展馆有哪些工业机器人的展商
卡片应同时显示 B1 和「工业机器人」,命中东麓分拣,展位 B1-26。
应用配置
{
"name": "查展商",
"mode": "artifact",
"受众": "访客",
"客服工具": {
"version": 1,
"name": "visitor_exhibitors_search",
"description": "按展品、展商或展位查目录。范围和关键词同时出现时传两者。",
"parameters": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"maxLength": 80,
"description": "核心展品、展商名或展位。只问全馆时省略。"
},
"filters": {
"type": "object",
"properties": {
"hall": {
"type": "string",
"maxLength": 8,
"description": "展馆编号,如 B1。"
}
},
"required": [],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
},
"operation": {
"kind": "lookup",
"table": "展商目录",
"keywordFields": [
"name",
"products",
"booth"
],
"filters": {
"hall": {
"field": "hall",
"match": "first-word"
}
},
"sortField": "booth",
"resultFields": [
"name",
"hall",
"booth"
]
}
},
"type": "展商目录",
"可读表": [
{
"type": "展商目录",
"字段": [
"name",
"hall",
"booth",
"products"
],
"最多": 40
}
]
}在小程序里读取查询结果
const { 参数: query = {}, 结果: result } = await aios.context()
if (result) renderResults(result.rows, result.total, query)将片段接到自己的 renderResults。独立打开小程序时由应用提供默认界面。查到零条时保留原查询条件。
发票草稿
用 open 打开空白草稿,也可预填已知的购方、税号和明细。样板用 chat-card.json 声明 {"mode":"draft"},便于多轮续填。
样板间输入
打开一张发票草稿。购方云杉科技,税号 DEMO123456,云服务 2 项,每项 120 元。
打开草稿核对合计 ¥240。再说「税号改为 DEMO987654」,购方和明细应保留。
应用配置
{
"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"
}
}
}在小程序里接收预填和续填
const { 参数: initial } = await aios.context()
if (initial) applyPrefill(initial)
aios.onSay((_message, details) => {
if (details?.参数) applyPrefill(details.参数)
})将片段接到自己的 applyPrefill,只更新收到的字段。由访客点击保存,再调用应用已授权的写入动作。
验收与回退
- 分别测试命中和无匹配,再测试关键词与展馆组合。核对卡片上的参数和总数。
- 依次验证空白、部分及完整预填,续填时核对未改字段。
- 关闭测试角色开关,或移除该角色对应用的可见权限。刷新访客入口,核对该工具不可用。