Host Onboarding

给宿主技术负责人的 10 分钟接入清单

这页不再讲定位。目标只有一个：让宿主技术团队用最短时间判断现在能不能接、先接什么、接完怎么验。

看完整接入指南看接入助手打开 Web 示例看动作闭环演示下载资料清单看宿主标准页

开始前确认

先确认这 4 件事

一个可用的 softwareId / tenantId / userId 约定
一条真实业务页面 route，例如 /orders/list
一个最小 Token，至少能区分角色和租户
一个试点模块，不要一开始就覆盖全系统

Checklist

宿主最少要提供什么

先把输入边界讲清楚，避免联调时一边测一边猜字段。

必须给

question、softwareId、tenantId、userId、route。少这几项，智引只能退化成普通问答。

建议同批给

pageTitle、selectedMenu、platform、module。这样回答会明显更贴当前页面。

排错场景补给

pageId、recordId、workflowNode、errors、formState。

想做成助手再补

availableActions 和 executor context，让宿主前端按白名单执行跳转、追问、聚焦、打开弹窗。

10 Minutes

10 分钟内应该怎么接

不要先做华丽 UI。先拿一条真实页面链路证明它有用。

先打开 Web 示例，确认公网 SDK 和 query 已能访问。
再打开 /embed 结构化 Agent 验收页，确认 nextAction、cards 和宿主执行日志都能看见。
把你们系统的一条真实页面 route、pageTitle、selectedMenu 带进去，先问“这个页面下一步怎么做？”。
再问 3 个真实问题：在哪里、怎么做、为什么报错，确认宿主消费的是 taskState / nextAction / followups / cards，而不是从 answer 文本里反推动作。
如果结果可用，再接入宿主自己的菜单、权限和页面上下文，不要先做复杂 UI。
最后再补 feedback、多模态和 SDK actionPlans。

First Query最小联调请求

curl -X POST https://ziin.shenliu.cc/api/ziin/query \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer editor|softwareId:erp-suite|tenantId:tenant-east-cn|userId:u-1001' \
  -d '{
    "question": "订单管理在哪里？",
    "mode": "ui-assistant",
    "module": "orders",
    "context": {
      "route": "/workbench/overview",
      "pageTitle": "经营总览",
      "selectedMenu": "工作台 / 经营总览",
      "platform": "web"
    }
  }'

为什么先看它

/embed 不是另一个介绍页，而是当前最短的“结构化 Agent 验收页”。如果这里的intent、taskState、nextAction、cards 和宿主执行日志都能成立，客户就更容易理解后续为什么要补 availableActions 和 executor context。

Web ESM

浏览器侧直接可用的接法

这段代码对应当前已公开的公网 ESM SDK，不需要先等 npm 包。

import {
  createHostRuntimeAdapter,
  createActionPlanExecutor,
  createZiinWidget,
} from "https://ziin.shenliu.cc/sdk/js/index.js";

const runtimeAdapter = createHostRuntimeAdapter({
  adapterConfig: {
    clientConfig: {
      baseUrl: "https://ziin.shenliu.cc",
      token: "editor|softwareId:erp-suite|tenantId:tenant-east-cn|userId:u-1001",
    },
    defaults: {
      mode: "ui-assistant",
      module: "orders",
      softwareId: "erp-suite",
      tenantId: "tenant-east-cn",
      userId: "u-1001",
    },
  },
  getContext: () => ({
    route: window.location.pathname,
    pageTitle: document.title,
    selectedMenu: readSelectedMenu(),
    platform: "web",
    pageId: readStablePageId(),
    availableActions: ["navigate", "focus_field", "scroll_to", "open_dialog"],
  }),
});

const widget = createZiinWidget({
  runtimeAdapter,
  actionExecutor: createActionPlanExecutor({
    allowActions: ["navigate", "focus_field", "scroll_to", "open_dialog"],
    handlers: {
      navigate: (plan) => router.push(plan.payload?.route || plan.route || "/"),
      focusField: (plan) =>
        focusHostField(plan.payload && "target" in plan.payload ? plan.payload.target || "" : plan.target || ""),
      scrollTo: (plan) =>
        document
          .querySelector(plan.payload && "target" in plan.payload ? plan.payload.target || "" : plan.target || "")
          ?.scrollIntoView({ behavior: "smooth", block: "center" }),
      openDialog: (plan) =>
        openDialog(plan.payload && "dialogId" in plan.payload ? plan.payload.dialogId : plan.target),
    },
  }),
  title: "智引操作内核",
  subtitle: "权限感知式操作指引",
  buttonLabel: "打开使用助手",
  contextLabel: "当前页面",
  defaultOpen: true,
});

await widget.refreshContext();

接入提醒

动作协议现在优先消费 payload：

- assistant nextAction 是任务推进动作，例如 ask_followup、goto_module、create_order_draft
- SDK actionPlans 是宿主页面动作计划，例如 navigate、scroll_to、focus_field、open_dialog
- 两层动作都必须由宿主白名单 executor 执行
- 不要从 answer 文本里反推动作

- navigate.payload.route
- scroll_to.payload.target
- focus_field.payload.target / fieldKey
- open_dialog.payload.dialogId

老字段 route / target / fieldKey 仍兼容，但不建议新宿主继续只按旧字段接。

Assistant nextAction

宿主优先消费结构化推进字段

{
  "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公斤"
      }
    }
  ]
}

Executor Context

宿主只开放可控执行能力

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),
  },
});

Validation

接完先问这 4 句

如果这几句都答不稳，问题通常不在 UI，而在宿主上下文、菜单映射和权限输入。

订单管理在哪里？

用你们系统真实页面、真实菜单、真实角色去问，不要只在空白 demo 页里测。

这个页面下一步怎么做？

用你们系统真实页面、真实菜单、真实角色去问，不要只在空白 demo 页里测。

为什么保存不了？

用你们系统真实页面、真实菜单、真实角色去问，不要只在空白 demo 页里测。

怎么给新员工开账号？

用你们系统真实页面、真实菜单、真实角色去问，不要只在空白 demo 页里测。

Boundary

上线前边界

这些话要先讲清楚，避免客户把公开演示站当成最终生产方案。

公网 ESM 与 examples 现在已公开可访问；tgz 安装包仍走商务收口。
控制接口、知识导入、供应商配置和审计接口不建议公开放开。
没有宿主权限体系时，只能先按 viewer/editor/admin 这类粗粒度角色降级接入。
动作协议必须由宿主白名单执行，不能让模型直接落动作。