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，让宿主前端按白名单执行跳转、聚焦、打开弹窗。

10 Minutes

10 分钟内应该怎么接

不要先做华丽 UI。先拿一条真实页面链路证明它有用。
  • 先打开 Web 示例，确认公网 SDK 和 query 已能访问。
  • 再打开动作闭环演示，确认宿主白名单动作不是文案，而是页面真的会响应。
  • 把你们系统的一条真实页面 route、pageTitle、selectedMenu 带进去，先问“这个页面下一步怎么做？”。
  • 再问 3 个真实问题：在哪里、怎么做、为什么报错，确认不是只会答说明书。
  • 如果结果可用，再接入宿主自己的菜单、权限和页面上下文，不要先做复杂 UI。
  • 最后再补 feedback、多模态和动作协议。
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 不是另一个介绍页，而是当前最短的“动作协议可见验收页”。如果这里的focus_field、scroll_to、open_dialog 看起来成立，客户就更容易理解后续为什么要补availableActions。

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.route || "/"),
      focusField: (plan) => focusHostField(plan.target || ""),
      scrollTo: (plan) => document.querySelector(plan.target || "")?.scrollIntoView({ behavior: "smooth", block: "center" }),
      openDialog: (plan) => openDialog(plan.target),
    },
  }),
  title: "智引操作内核",
  subtitle: "权限感知式操作指引",
  buttonLabel: "打开使用助手",
  contextLabel: "当前页面",
  defaultOpen: true,
});

await widget.refreshContext();

Validation

接完先问这 4 句

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

订单管理在哪里？

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

这个页面下一步怎么做？

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

为什么保存不了？

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

怎么给新员工开账号？

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

Boundary

上线前边界

这些话要先讲清楚，避免客户把公开演示站当成最终生产方案。
  • 公网 ESM 与 examples 现在已公开可访问；tgz 安装包仍走商务收口。
  • 控制接口、知识导入、供应商配置和审计接口不建议公开放开。
  • 没有宿主权限体系时，只能先按 viewer/editor/admin 这类粗粒度角色降级接入。
  • 动作协议必须由宿主白名单执行，不能让模型直接落动作。