在网站中接入 Cadau 助手

将本文档交给负责网站或前端的同事，或粘贴给开发工具的 AI 作为完整集成上下文。

第三方完整手册（A/B 选型、Cadau 准备、B 路径代签、验收与排错）：README.md。

A 路径静态对照站：examples/cadau-embed-site/。

说明：带真实令牌与当前站点 URL 的版本请在 Cadau 我的智能体 → 管理 → 网站嵌入 生成令牌后点击「复制全文」。

---

1. 你能得到什么

• A：网站公开客服——任意站点用三件套（Cadau 地址、智能体 ID、嵌入令牌）加载对话浮层；无需宿主后端；知识挂在该智能体 / 工作区；开启人工客服后挂件可「人工客服」。
• B：宿主业务系统——登记/分配 + 服务端代签 + 须传当前登录用户身份（host_actor）；可按登录用户换智能体（见 §4.3 与 HR 范例）。
• 对话统一走 Cadau（POST /api/v1/chat/stream）；令牌可随时收回。
• （可选）回答内 mindlink://action/ 功能导航，见 §5。

---

2. 接入凭证（A 路径三件套）

尚未填入令牌：请在 Cadau 我的智能体 → 管理 → 网站嵌入 点击「生成新令牌」；完整令牌字符串仅在生成时展示一次。

注意

• 不必在页面填工作区 ID、应用标识或过期时间（工作区由令牌决定；未传 app_id 时默认 mindlink-embed）。
• 令牌勿写入公开仓库；泄露后在「网站嵌入」收回并换票。
• 支持短期与长期令牌；长期仍可收回。

MINDLINK_BASE_URL=https://your-mindlink.example.com
MINDLINK_USER_AGENT_ID=（智能体实例 ID）
MINDLINK_EMBED_TOKEN=（生成后填入）
MINDLINK_WIDGET_SCRIPT=https://your-mindlink.example.com/embed/mindlink-widget.min.js

---

3. 脚本地址

接口前缀由挂件推导为 {base_url}/api/v1（也可显式传 api_base_url）。脚本与 API 建议同源。

---

4. 页面初始化（A 路径）

<script src="https://your-mindlink.example.com/embed/mindlink-widget.min.js"></script>
<script>
  window.MindLinkWidget.init({
    base_url: "https://your-mindlink.example.com",
    user_agent_id: "（智能体 UUID）",
    auth: { token: "（网站嵌入令牌）" }
  });
</script>

data-* 自动挂载（可选；必填 data-base-url / data-agent-id / data-token，可选 data-app-id、data-theme、data-position、data-entry、data-title、data-greeting、data-welcome）。在 Cadau 网站嵌入复制脚本时可先选入口：只显示角落按钮、第一次来时出一句招呼、或打开页面就展开对话。data-position：bottom-right（默认）/ bottom-left / middle-right（右侧）/ center（中间）。

<script
  crossorigin
  src="https://your-mindlink.example.com/embed/mindlink-widget.min.js"
  data-base-url="https://your-mindlink.example.com"
  data-agent-id="（智能体 UUID）"
  data-token="（网站嵌入令牌）"
  data-app-id="mindlink-embed"
  data-theme="auto"
  data-entry="greeting"
  data-title="官网客服"
  data-greeting="有问题可以直接问我"
></script>

人工客服与工单：在该智能体 人工客服 中开启，并指定本区座席 或 授权客服小组后，挂件输入区旁会出现：

• 「人工客服」：马上有人在线聊（须至少一名覆盖该工作区的客服 上班——本区席位，或已授权小组的队员在小组工作台点了上班）；访客提交进入工作区 即时客服 队列。
• 「提交工单」：不必马上等到真人；进入工作区 工单 队列。无人上班时只保留此项。排队中可 「不等了，改提工单」。

谁能看见对话 / 客服 / 工单

• A（网站未登录访客）：按本浏览器隔离。同一浏览器再打开仍是同一访客；换浏览器或清站点数据会变成新访客。
• B（已登录宿主用户）：按当前登录用户隔离。须把 host_actor 传入 init（换用户时 updateHostActor）；用户甲看不到乙的历史会话、进行中客服与工单。换浏览器用同一账号仍是本人。

客服在 Cadau 客服工作台 处理（左侧：即时客服 / 工单 / 服务时段），不必刷新整页。一组客服服务多个客户工作区时，用 客服小组（本队建组 → 客户授权 → 列入服务范围）；队员在工作台右侧切到 小组工作台 接单，不必切换顶栏当前工作区。用户文案中 勿 把即时协助称作「工单」。机制见 Cadau docs/core-mechanisms/人工客服.md。

主题：默认 theme: auto（data-theme 可写 auto / light / dark）。auto 时跟随宿主页 html[data-theme]、html/body.dark，否则跟系统浅深色；切换宿主主题时挂件会同步。

API 返回 unauthorized / embed_token_revoked 时请换票。多人同时向同一嵌入助手提问时，超额会返回 embed_generation_limit（HTTP 429），挂件提示「当前对话人数已达上限，请稍后再试」。上限可在该智能体 管理 → 嵌入助手同时回复上限 调整（未设则服务器默认 20；智能体填 0 在服务器默认 > 0 时回落默认，并不能突破成不限制）。

4.1 可选：Web Component

<mindlink-widget
  base-url="https://your-mindlink.example.com"
  user-agent-id="ua_123"
  theme="auto"
  position="bottom-right"
></mindlink-widget>
<script>
  const el = document.querySelector("mindlink-widget");
  el.auth = { token: "…" };
</script>

HTML 还可覆盖 app-id、api-base-url、workspace-id 等；auth / host_actor 须用 JS 赋值。

4.2 可选：行内挂载

window.MindLinkWidget.init({
  base_url: "https://your-mindlink.example.com",
  user_agent_id: "…",
  auth: { token: "…" },
  position: "inline",
  container: "#my-assistant-host",
  entry: { auto_open: true }
});

4.3 B 路径：服务端代签（业务系统）

正式业务系统建议由宿主后端在用户已登录后：

1. 校验宿主侧权限与智能体分配；
2. 用 Cadau 集成账号调用 POST /api/v1/user-agents/{id}/embed-token，请求体带上当前登录用户的 host_actor（写入令牌登记，浏览器无法改成别人）；
3. 经 embed-session 下发 access_token 与同一份 host_actor；
4. 浏览器 init 须传入 host_actor（可另传 api_base_url / app_id / workspace_id / expires_at）。换登录用户时 updateHostActor 或重新 init。

人工客服 / 工单与 A 路径相同：代签得到的嵌入令牌即可使用挂件内入口，不必在宿主再做客服后台。须在 正在嵌入的那条智能体 上开启人工客服（静态官网开过，不等于业务系统里的助手已开），指定本区座席或授权客服小组，并让覆盖该区的客服 上班。对照手册：参考范例-HR接入指南.md §10.4。

范例：参考范例-HR接入指南.md、examples/hr-multi-tenant/。

---

5. 功能导航（AI 回答里可点的链接）

5.1 机制说明

1. 在智能体的知识文档中约定：回答需要跳转时，使用 Markdown 链接 + 自定义协议 mindlink://action/。
2. 用户点击后，嵌入挂件向宿主页抛出 action 事件（emit_event，kind: mindlink_action）。
3. 宿主页在 executeHostAction 中白名单解析动作名与查询参数，打开对应页面并应用筛选。

5.2 链接语法

`链接文案`

• 动作名：你在宿主页注册的业务动作，建议 page.<模块> 或 module.<模块>。
• 筛选参数：标准 URL 查询串，点击后原样传给宿主页（如 status、id、q、tenant_id 等）。

示例（写进知识文档，供智能体模仿）：

- `打开待审批订单`
- `查看客户详情`
- `去组织架构页`
- `打开仪表盘并筛选本月`

可选参数 label：仅用于链接文案或埋点，宿主页可忽略。

5.3 宿主页白名单实现（必做）

在宿主页维护动作表，只执行已注册动作；未知动作提示「暂不支持」。

const HOST_ACTIONS = {
  "page.orders": (params) => {
    hostApp.navigate("/orders", {
      status: params.status || "",
      customer_id: params.customer_id || "",
    });
    hostApp.refreshList("orders");
  },
  "page.customer": (params) => {
    hostApp.openCustomerDrawer(params.id);
  },
  "page.org": (params) => {
    hostApp.navigate("/org", { tab: params.tab || "tree" });
  },
  "module.dashboard": (params) => {
    hostApp.navigate("/dashboard", { range: params.range || "week" });
  },
};

function executeHostAction(action, params) {
  const fn = HOST_ACTIONS[action];
  if (!fn) {
    hostApp.toast("暂不支持该导航：" + (params.label || action));
    return;
  }
  fn(params);
}

HR 多租户范例实现：examples/hr-multi-tenant/web/src/mindlinkHostActions.ts（哈希路由 page.*）。

5.4 让智能体稳定返回导航

在 Cadau 为该智能体挂载知识文档，加入（撰写规范见 宿主知识文档撰写要求.md）：

1. 可跳转页面清单（页面名、动作名、可用筛选参数及含义）。
2. 回答规范：用户问「去哪看 / 帮我打开」时，在正文末尾给出 1～3 条 mindlink://action/ 链接，参数与当前上下文一致（如刚提到的订单 id）。
3. 禁止使用 javascript: 等不安全协议。

Cadau 主站内置动作（仅主站有效，宿主页需自行映射）：module.workspace、module.chat、chat.new-session 等，见仓库 docs/core-mechanisms/帮助动作链接.md。

5.5 结构化动作（预留，未交付）

挂件事件类型支持 open_url / open_module / emit_event，§4 示例可预留处理。当前实现：仅 Markdown 正文中的 mindlink://action/ 会触发 action（emit_event + mindlink_action）。后端在 SSE 流中直接下发结构化动作卡片尚未交付（见 SDK契约.md §5.4、§6.3）。

5.6 用户明确要求打开时的自动导航

entry.auto_execute_navigation 默认为 true。当用户消息匹配「帮我打开 / 跳转 / 前往…」等意图时，助手回答流式结束后，挂件会自动执行回答正文中首条在嵌入表面可点击的 mindlink://action/ 链接（跳过主站专用动作，与手动点击过滤一致；仍走宿主页白名单）。

• 知识文档中须写清：用户明确要求打开时，仍应输出 1～3 条登记链接，且第一条宿主可执行链接须为最相关目标。
• 若只希望用户手动点击，设 entry: { auto_execute_navigation: false }。
• 宿主侧 widget.on("action", …) 必须已实现（§4），否则自动导航无效果。

---

6. 联调检查清单

• 宿主页能加载挂件并完成首轮对话（ready 事件、流式回复正常）。
• app_id、令牌、user_agent_id、workspace_id 与本文「接入凭证」一致。
• （B）host_actor 已传入；两名登录用户互看不到对方的历史会话、人工客服与工单。（传软查数隔离见 宿主增强-AgentRun与数据权限.md。）
• （A）两名网站访客互看不到对方的历史会话、人工客服与工单。
• 两名访客可同时向同一嵌入助手提问并各自收到回复（不必互相等待）；过载时挂件提示「当前对话人数已达上限，请稍后再试」。
• 智能体回答中含 mindlink://action/ 链接时，点击能触发宿主页跳转/弹层/列表筛选。
• 用户说「帮我打开 xx 页」时，回答完成后宿主收到 action 并执行（auto_execute_navigation 未关闭时）。
• （可选）已开启人工客服：挂件有「人工客服」（须有人上班）与「提交工单」；客服工作台能看到新单而无需整页刷新。本区席位或已授权客服小组均可接单；小组工作台接单不切换顶栏当前工作区。
• 未知动作有友好提示，不执行任意脚本。
• 令牌过期后可 updateAuth 恢复；收回后旧令牌返回 embed_token_revoked。
• （生产）令牌由服务端代签，前端静态页不含长期明文令牌。

---

7. 更多契约

事件名、TypeScript 类型、错误码与安全边界见同目录 《嵌入 SDK 契约》（V1.5.12）。