Host Guide

宿主接入标准清单

这页是给宿主技术负责人和实施同学看的。目标不是讲产品愿景，而是说明接入时最少要给什么、补什么最值钱、做到什么程度才算真的开始像智能体。

看接入指南看接入助手看标准化方案看 Starter Kit
One Sentence

先让 Ziin 知道你在哪、你能做什么、你卡在哪里，再谈它像不像智能体。

  • 语音和 UI 不是最核心的差异点。
  • 页面理解、权限边界和动作协议才是关键分水岭。
  • 宿主不给上下文，回答再流畅也还是容易空。

Checklist

最小字段清单

先把对效果最敏感的字段说清楚，避免宿主接入时靠猜。

必须给

softwareId、tenantId、userId、question、route。没有这几项，Ziin 只能退化成泛化问答。

强烈建议给

pageTitle、selectedMenu、platform、pageId、roleCodes、permissionCodes。

排错场景建议给

errors、formState、workflowNode、recordId。这样才能知道用户到底卡在哪一步。

往智能体升级建议给

availableActions 和 executor context，例如 routerPush、setQuestion、focusInput、submitQuestion。

Progression

宿主能力分级

接入不是二元状态，而是从说明书型逐步走到可执行助手型。
Maturity

L1 说明书型

只有 question，最多加 route。能回答一些问题，但更像会说话的帮助中心。

Maturity

L2 基础上下文型

带 route、pageTitle、selectedMenu、platform，开始知道用户当前在哪一页。

Maturity

L3 页面理解型

再加 pageId、recordId、workflowNode、errors、formState，开始能判断当前卡点。

Maturity

L4 可执行助手型

再加 nextAction 消费和白名单 executor，宿主支持跳转、追问、定位、聚焦字段等动作协议。

Maturity

L5 持续优化型

知识、反馈、命中率、版本变更和宿主评估形成持续闭环，而不是一次性接入。

Payload

推荐的 Query 上下文示例

这里不是理论字段表，而是一条宿主真正可以照着发的请求体。
{
  "question": "为什么这个页面提交失败？",
  "mode": "embedded-agent",
  "softwareId": "erp-suite",
  "tenantId": "tenant-east-cn",
  "userId": "u-1001",
  "module": "inventory",
  "context": {
    "route": "/inventory/inbound/create",
    "pageTitle": "新建入库单",
    "selectedMenu": "仓储中心 / 入库管理",
    "platform": "web",
    "pageId": "inventory_inbound_create",
    "recordId": "IN-20260417-001",
    "roleCodes": ["warehouse_clerk"],
    "permissionCodes": ["inventory.write"],
    "workflowNode": "draft",
    "errors": [
      { "code": "REQUIRED_FIELD", "field": "warehouseId", "message": "仓库不能为空" }
    ],
    "formState": {
      "supplierId": "SUP-01",
      "lineCount": 2
    },
    "availableActions": ["navigate", "scroll_to", "focus_field", "open_dialog"]
  }
}

Action Contract

宿主动作用结构化协议接

不要从 answer 文本里反推动作。优先消费 taskState、nextAction、followups、cards；SDK actionPlans 继续按 payload-first 方式兼容。
{
  "intent": "ship_create",
  "taskState": "ship_drafting",
  "riskLevel": "draft",
  "nextAction": {
    "type": "create_order_draft",
    "payload": {
      "destinationCity": "成都",
      "cargoName": "日用品",
      "weight": "300公斤"
    }
  },
  "followups": ["直接帮我生成草稿", "我只是先咨询"],
  "cards": [
    {
      "type": "draft",
      "title": "订单草稿建议",
      "data": {
        "destinationCity": "成都",
        "cargoName": "日用品",
        "weight": "300公斤"
      }
    }
  ],
  "actionPlans": [
    {
      "action": "navigate",
      "payload": { "route": "/orders/list", "openInNewTab": false }
    },
    {
      "action": "focus_field",
      "payload": {
        "fieldKey": "customerName",
        "target": "[name=\"customerName\"]",
        "behavior": "focus"
      }
    },
    {
      "action": "explain_permission",
      "payload": {
        "permissionKey": "inventory.write",
        "roleCode": "warehouse_clerk"
      }
    }
  ]
}
Executor

宿主只需要开放可控执行上下文：routerPush、setQuestion、setTextMode、setStatus、focusInput、submitQuestion。所有动作都走白名单，不允许模型直接写业务数据。

executeFloatingAssistantNextAction({
  action: result.nextAction,
  response: { answer: result.answer },
  context: {
    routerPush: (route) => router.push(route),
    setQuestion,
    setTextMode,
    setStatus,
    focusInput: () => inputRef.current?.focus(),
    submitQuestion: (question) => query(question),
  },
});

Delivery

宿主应该准备的资料

不是只给一个 API Key 就能接好，宿主还需要把真实系统知识和边界准备出来。
  • 菜单树与页面路由清单
  • 角色与权限码映射
  • 试点模块操作手册 / SOP / FAQ
  • 常见错误和排错说明
  • Token 或 query 上下文字段说明
  • 版本变更时的知识更新负责人

Improve

怎么把效果提上去

这条路线更务实：先让它答得贴近当前页面，再让它逐步能帮你动手。

第一步：先跑通

先用一个试点模块把 query 跑通，不要一上来覆盖全系统。

第二步：补真实上下文

优先补 route、pageId、permissionCodes、errors、formState，不要先纠结 UI。

第三步：接反馈闭环

把 useful / not_useful 和未解决问题回流接上，否则无法判断是不是真的好用。

第四步：补动作协议

让助手不止会解释，还能通过 nextAction / actionPlans 推动页面动作，但必须由宿主前端按白名单执行。

第五步：接连续陪跑

围绕同一个 recordId 继承 route、pageId、workflowNode，让后续追问不用每次重新说明上下文。