传软嵌入 SDK（host-embed）

目录名：sdk/host-embed 用途：第三方在自有业务系统中接入 Cadau 嵌入助手的完整文档包（可整体交付）。

交付说明：本目录（sdk/host-embed/）为第三方接入的 主文档包（总览、契约、网站集成、知识撰写、HR 对照、传软增强）。将本目录交给集成方即可开始对接；可运行全栈范例与部分机制真值仍在仓库其他路径（见下文链接），单独拷贝本目录时那些链接会失效。

适用对象：在自有业务系统（ERP、OA、行业 SaaS 等）中接入 Cadau 对话助手的 第三方团队——包括业务管理员、后端与前端开发、运维。

读完本文你能：在宿主页面挂上助手、按用户分配不同智能体、让助手在回答中引导用户打开业务页面，并确认登录用户之间互看不到对方的历史会话、人工客服与工单。

技术契约（字段、SSE、错误码）见 SDK契约.md（V1.5.12）；前端复制即用说明见 网站集成说明.md；A 路径静态范例 examples/cadau-embed-site/；B 路径全栈范例 examples/hr-multi-tenant/ 及 参考范例-HR接入指南.md。

并列 SDK：appsdk · platform-plugin · agent-capability · 本目录。 · 总览 sdk/README.md。

注意：浏览器加载的脚本路径仍是站点上的 /embed/mindlink-widget.min.js（HTTP 路由，与本文档目录名无关）。

本目录文档一览

1. 你能得到什么

在 你的业务页面 中：

• 出现右下角（或页面内嵌）的 对话助手，与 Cadau 里配置好的 我的智能体 对话；
• 对话走 Cadau 服务端，便于 权限、审计与随时收回访问；
• 助手可在回答里给出 可点击的导航链接，用户一点即可打开你系统里的对应页面并带上筛选条件（如「待审批订单」「某员工档案」）；
• 用户说「帮我打开某某页」时，挂件可在回答完成后 自动执行 第一条已登记的导航（可关闭，见 §8.3）。
• （可选）宿主 服务端 也可请指定智能体代答（审批摘要、按部门建议岗位等，用户不必看见挂件），见 宿主LLM服务.md。

Cadau 不负责：你的登录用户体系、业务权限、业务数据库。用户是谁、能看哪些菜单，仍由 宿主系统 决定。

2. 谁做什么

flowchart LR
  subgraph ML["Cadau（智能体提供方）"]
    UA["配置智能体与知识"]
    ET["签发嵌入访问凭证"]
    CHAT["对话与检索"]
  end

  subgraph Host["第三方宿主（你的系统）"]
    ADM["登记智能体、分配用户"]
    BFF["服务端代签凭证"]
    UI["业务页 + 对话挂件"]
  end

  ADM --> BFF
  BFF -->|"集成账号"| ET
  UI -->|"短期凭证"| CHAT
  UA --> CHAT

3. 两种接入方式怎么选

建议：

• 任意网站嵌客服、无业务登录体系 → 用 A；静态对照见 examples/cadau-embed-site/。
• 正式业务系统、按用户分配、凭证不进前端仓库 → 用 B（HR 范例见 参考范例-HR接入指南.md）。

代签（B）：宿主服务端用 Cadau 集成账号 调用 POST /api/v1/user-agents/{智能体ID}/embed-token，拿到短期嵌入凭证后交给浏览器；终端用户 不 登录 Cadau 主站。

4. Cadau 侧准备（智能体负责人）

在改造宿主之前，在 Cadau 完成下表（可与宿主方对齐后执行）：

B 路径不需要在 Cadau 界面为每个宿主用户重复「生成令牌」；宿主后端代签与界面按钮调用的是 同一套 API。

（A 路径必做） 在该助手 管理 → 网站嵌入 生成令牌；页面只需 站点 URL + 智能体 ID + 令牌（不必填工作区 ID）。若需挂件 「人工客服」 与 「提交工单」，在同一智能体的 人工客服 中开启，并指定本区座席 或 授权客服小组（无人上班时只保留提交工单）。完整说明可在该页 复制网站集成说明。

5. 宿主侧：管理人员要做什么

在 你的管理后台（或运维脚本）完成：

5.1 登记接入的智能体

为每条要接入的 Cadau 智能体建一条登记，只存智能体 ID，不存嵌入令牌：

（可选）生成/分析用智能体：宿主服务端代跑「建议岗位」等任务时，指定 另一条 已在 Cadau 配好的智能体——写在 .env 的 MINDLINK_GENERATE_USER_AGENT_ID，或管理页「嵌入助手登记」里选定（覆盖环境变量）。不是右下角对话助手。见 宿主LLM服务.md §5.1。

5.2 按登录用户分配

• 分配主体是 宿主登录用户（手机号/工号对应的账号），不是业务档案里的员工 ID（除非二者合一）。
• 为每个用户选择：使用哪条登记记录、具备哪些 操作范围（如仅查询、是否允许新增/编辑/删除——由宿主自定义枚举）。
• 未分配的用户：业务页 不展示 助手，或嵌入会话接口返回「暂无助手」。

HR 多租户范例：侧栏 用户管理 → 接入的智能体 / 配置智能体；详见 参考范例-HR接入指南.md §8。

6. 宿主侧：开发人员改造清单

6.1 数据层（B 路径）

至少两张表（表名可自定）：

1. 登记接入智能体（§5.1 字段）
2. 用户智能体分配（租户 + 用户 → 登记记录 + 权限范围）

6.2 嵌入会话接口（B 路径核心）

提供类似接口（路径可自定，语义保持一致）：

GET /api/v1/.../me/embed-session
Authorization: Bearer <宿主登录凭证>

服务端逻辑：

1. 校验宿主用户已登录；
2. 查该用户是否有 有效分配；
3. 无分配 → 返回 200，body 含 available: false 与原因（勿用 404，避免浏览器误报）；
4. 有分配 → 用集成账号 登录 Cadau → 切换工作区 → 调用

POST /api/v1/user-agents/{智能体ID}/embed-token body 示例：{ "app_id": "your-app", "ttl_seconds": 3600 }；

1. 将下列字段返回给前端（字段名可与范例一致）：

集成账号密码、Cadau 对内地址 仅放服务端环境变量，不得提交前端仓库。

Cadau 代签顺序（服务端调用，非浏览器）：

POST /api/v1/auth/login
POST /api/v1/workspaces/{workspaceId}/switch
POST /api/v1/user-agents/{userAgentId}/embed-token

6.3 前端挂载挂件

1. 用户进入需要助手的业务页；
2. （B）带宿主登录凭证请求嵌入会话；或（A）读静态配置；
3. 动态加载 widget_script；
4. 初始化：

<script src="https://<Cadau 域名>/embed/mindlink-widget.min.js"></script>
<script>
  const widget = window.MindLinkWidget.init({
    app_id: "your-app-id",
    api_base_url: "https://<对外 API 前缀>/api/v1",
    user_agent_id: "<智能体 UUID>",
    workspace_id: "<工作区 UUID>",
    auth: {
      token: "<嵌入 access_token>",
      expires_at: "<ISO 8601>"
    },
    // B 路径必传：与 embed-session 下发的 host_actor 一致（历史/客服/工单隔离；传软查数）
    // 挂件会自动带 X-Host-External-User-Id，宿主页不必再设请求头
    host_actor: { external_user_id: "…", actor_kind: "employee" },
    theme: "auto",
    position: "bottom-right",
    locale: "zh-CN",
    entry: {
      auto_open: false,
      auto_execute_navigation: true
    }
  });

  widget.on("action", function (ev) {
    if (ev.type !== "action") return;
    handleHostNavigation(ev.action);
  });
</script>

1. 凭证将过期时：由后端重新代签，再 widget.updateAuth({ token, expires_at })；换登录用户时 widget.updateHostActor(hostActor)（或重新 init）。

行内嵌入：position: "inline" + container: "#你的容器选择器"。 Web Component：见 网站集成说明.md §4.1。

参考代码（在 Cadau 仓库中，非本目录交付物）：

• HR 范例挂载：examples/hr-multi-tenant/web/src/mindlinkOrgEmbed.ts
• HR 范例导航：examples/hr-multi-tenant/web/src/mindlinkHostActions.ts

6.4 网络与安全

服务端环境变量示例（B 路径）：

MINDLINK_API_BASE=https://mindlink.internal/api/v1
MINDLINK_API_BASE_PUBLIC=https://your-host.com/mindlink-api/v1
MINDLINK_WIDGET_SCRIPT=https://mindlink.internal/embed/mindlink-widget.min.js
MINDLINK_INTEGRATION_EMAIL=integration@your-corp.com
MINDLINK_INTEGRATION_PHONE=
MINDLINK_INTEGRATION_PASSWORD=<仅服务端>
MINDLINK_APP_ID=your-corp-app
MINDLINK_WORKSPACE_ID=<整套宿主共用的工作区 UUID>
MINDLINK_GENERATE_USER_AGENT_ID=<可选：生成/分析用智能体 UUID>

嵌入令牌有效期、挂件是否行内等有代码默认值，不必写入 .env。集成账号可用 邮箱或手机号 二选一登录 Cadau（与 HR 范例 server/.env 一致）。

7. 功能导航：让助手带你打开业务页

7.1 机制

1. 在智能体 知识文档 中约定：需要跳转时使用 Markdown 链接 + 协议 mindlink://action/；
2. 用户点击链接（或开启自动导航时由挂件触发）→ 宿主页收到 action 事件；
3. 宿主页 白名单 解析动作名与参数，跳转路由或打开抽屉。

7.2 链接写法（写进知识文档）

`打开待审批订单`
`查看组织架构`

• 动作名：你在宿主页注册的业务动作，建议 page.<模块>；
• 查询参数：原样传给宿主页（status、id、label 等）；label 可仅用于展示。

7.3 宿主页白名单（必做）

const HOST_ACTIONS = {
  "page.orders": (params) => {
    app.navigate("/orders", { status: params.status || "" });
  },
  "page.org": (params) => {
    app.navigate("/org", { tab: params.tab || "tree" });
  },
};

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

禁止执行 javascript: 等不安全协议；未知动作提示「暂不支持」。

7.4 自动导航

entry.auto_execute_navigation 默认为 true：用户明确说「帮我打开 / 跳转…」时，回答流式结束后自动执行正文中 首条宿主可执行的 mindlink://action/ 链接（与点击过滤一致）。若只希望手动点击，设为 false。

知识文档须写清：用户要求打开页面时，回答末尾应给出 1～3 条登记链接，且第一条宿主可执行链接为最相关目标。

撰写规范：宿主知识文档撰写要求.md。

8. 推荐实施顺序

8.1 自动化冒烟（HR 范例）

冒烟测试是用脚本按真实 API 顺序做的 最小联调检查：不打开浏览器，任一步失败即报错，用于改配置或发版后快速确认「能不能测」。

在 examples/hr-multi-tenant/web 目录（需 Cadau :8080 与 HR 后端 :18089 已启动，server/.env 已配 MINDLINK_*）：

不能替代完整验收：SQLite 数据连接、access policy 写入、界面体验等仍须手工核对（HR 范例见仓库 examples/hr-multi-tenant/docs/ACCEPTANCE_HOST_LEGACY.md）。

8.2 本地联调 HR 范例

# 见 examples/hr-multi-tenant/README.md
cd examples/hr-multi-tenant/web
npm run setup:mindlink    # 自动注册集成账号并写入 ../server/.env
cd ../server && go run ./cmd/hrms-server   # 另开终端
cd ../web && npm run dev
# 浏览器 http://localhost:5180 ；演示登录 13800138000 / Demo-HR-2026
npm run smoke:embed         # 可选：嵌入冒烟
npm run smoke:host-agent    # 可选：传软增强冒烟

将已有 Cadau 智能体接入 HR 范例登记：

cd examples/hr-multi-tenant/web
npm run link:mindlink-agent -- <MindLink智能体UUID>

注意：link:mindlink-agent 默认读写本地 SQLite backend/mindlink.db。若 Cadau 主库为 Postgres（常见本地开发配置），请在 Cadau UI 将集成账号邀请进工作区，并核对登记表 mindlink_workspace_id；或重新运行 setup:mindlink。

9. 运行观测：智能体主人如何看嵌入对话

嵌入对话记在 代签用的 Cadau 身份 下，不会出现在该身份个人「消息」列表里。

智能体归属人在 Cadau 主站：

1. 我的智能体 → 运行记录；
2. 左侧选择对应助手；
3. 来源选 嵌入（可按 应用标识 筛选）；
4. 点击会话 只读查看 对话内容。

从智能体 管理 → 概览 可点 查看运行记录 直达该助手嵌入记录。

10. 联调与验收清单

Cadau

• [ ] 智能体已创建，知识文档已挂载（含可跳转页面清单）
• [ ] app_id 与宿主一致
• [ ] B：集成账号可登录、已加入智能体工作区，能成功代签
• [ ] 登记表中的工作区 ID 与智能体实际工作区一致（本期整套宿主共用一个 Cadau 工作区）
• [ ] （可选）该智能体已开启 人工客服（本区席位或授权客服小组）；覆盖该区的客服已 上班；挂件出现「人工客服 / 提交工单」

宿主后端

• [ ] 登记、分配接口可用
• [ ] 已分配用户：嵌入会话返回 available: true 与 access_token
• [ ] 未分配用户：返回 available: false（HTTP 200）
• [ ] 集成密码未出现在前端或公开仓库

宿主前端

• [ ] 登录后出现助手，能流式对话
• [ ] 不同用户分配不同智能体时，对话身份正确（B）
• [ ] （B）init 已传入 host_actor；两名登录用户互看不到对方的历史会话、人工客服与工单
• [ ] （A）两名网站访客互看不到对方的历史会话、人工客服与工单（换浏览器或清站点数据即新访客）
• [ ] 两名访客可同时提问并各自收到回复；过载时挂件提示「当前对话人数已达上限，请稍后再试」
• [ ] 凭证过期前可 updateAuth 或重新进入页面续签
• [ ] （可选）回答内导航链接可跳转；自动导航符合预期
• [ ] 未知导航有友好提示

传软增强（若接入 Host Agent Run / 业务库查数）

• [ ] 宿主 BFF 在 embed-session / agent-run 中携带完整 host_actor
• [ ] 工作区数据连接已配置，access_policy_json 已写入
• [ ] 员工自助仅本人行；主管/管理员范围符合预期；不同用户会话不串话
• [ ] （可选）npm run smoke:host-agent 通过

安全与运维

• [ ] 生产以 B 为主；A 仅 dev
• [ ] Cadau API 经同域代理或合规 CORS
• [ ] 集成账号轮换、令牌收回流程已文档化
• [ ] 生产使用 自建 集成账号，非 HR 范例演示邮箱

11. 常见问题

12. 文档索引（本目录）

13. 维护信息