Cadau 产品说明书（用户侧 · 集成侧）
本版以 企业管理员 / 运营 与 宿主系统开发 / 架构 为主；以下为建议阅读范围。
来源 docs/产品手册.md
文档目的：用 用户能理解的表达 说明如何 创建智能体、建立与维护知识文档、第三方系统嵌入与使用，并指向仓库内规格与契约原文。
真值来源：产品能力与流程以
docs/产品规格.md页眉表述为准；嵌入以sdk/host-embed/SDK契约.md为准；知识索引生成规则以docs/core-mechanisms/AI重建知识索引规则.md为准。实现细节：API 路径、字段名、运行时目录等仅在必要时用括号或独立小节标明，主文不替代用户可见文案。
1. 说明书适用对象
本版以 企业管理员 / 运营 与 宿主系统开发 / 架构 为主；以下为建议阅读范围。
| 角色 | 建议阅读章节 |
|---|---|
| 企业管理员 / 运营（配置智能体、知识、协作边界） | §2、§3、§5 |
| 宿主开发 / 架构（嵌入与对接） | §4，并常备 sdk/host-embed/SDK契约.md |
| 部署与运维（全局帮助文档、环境变量） | §3.5、§6 |
| 日常成员（简要用法，可选） | §5 |
2. 如何创建智能体
2.1 先理解三个概念
- 工作区：你们团队协作的边界；进入与智能体、会话相关的许多能力前，通常要先选定当前工作区（与「运行时里每个智能体实例自己的文件目录」不是同一概念，后者是系统实现用语）。
- 用户智能体（「我的智能体」）：归你（及工作区策略）使用的一个助手实例，能绑定 说明与偏好、知识文档、技能/工具；对话时通过选择智能体或传入绑定信息让助手按该实例来回答。
- 市场模板（若已开通）：他人或平台发布的可复用模板；可从模板 生成你自己的一份 智能体，再在之上改名、改说明、换知识库等。
2.2 创建方式（产品流程）
当前环境（本版前提）：智能体市场尚未作为对外主路径，日常以 自建智能体 为主。若日后市场上线，可再增加「从模板创建」的运维说明。
- 创建空白 / 自建智能体（当前主路径）
- 在 我的智能体（或等价入口）选择 新建 → 填写名称与基础说明 → 保存。 - 再按需：上传或编写 知识文档、绑定 工作区知识、配置 技能（以当前产品界面为准）。
- 从市场创建（若已对您开放）
- 在 智能体市场 中选择模板 → 按提示创建 你的实例。 - 创建后在 我的智能体 中继续编辑说明、知识、工具等。
- 对话时如何绑定
- 新会话：需要选定（或 implicitly 绑定）要使用哪一个智能体；更换助手时，产品规则一般为 新建会话 再选另一个，而不是在同一条会话里无提示切换（见 产品规格.md §7.4.5）。 - 嵌入场景：由宿主初始化参数固定一个智能体实例标识（见 §4）。
2.3 与后端的接口对照（便于集成或脚本）
规格里约定的 REST 摘要见 产品规格.md §7.3～7.4，主要包括：列出/创建/更新用户智能体、从模板创建实例、触发训练任务等。实际路径与请求体 以当前部署的 OpenAPI / 后端实现为准；本说明书不逐字段复制，避免与版本漂移。
3. 知识文档目录：如何建立与维护
宿主页嵌入场景：业务方编写给嵌入智能体用的 Markdown，另见 宿主知识文档撰写要求.md （用户表达、功能导航动作表、检查清单）。
3.0 职责约定（本企业、本版正文）
| 事项 | 负责人 |
|---|---|
| 工作区层知识（团队共用） | 工作区管理员 |
各智能体专属知识（该助手的 .md 与索引） | 智能体创建者 |
| 重建索引（改文档后的刷新） | 与上传、编辑该知识的人员相同（谁维护内容，谁负责触发索引重建） |
| 发布审批 | 当前不需要；若以后启用「先审后发」，以届时制度为准，并回看本说明书修订 |
3.1 三层知识（用户能理解的说法）
产品上把「给智能体检索用的、成体系的知识文件」统称为 知识文档目录，分三层（产品规格.md §3.2.1）：
| 层级 | 谁能用 | 典型用途 |
|---|---|---|
| 全局 | 在平台策略允许范围内广域使用 | 全员 onboarding、公告规范；与 帮助智能体 可读的全局挂载同一类机制（部署侧配置，见 §3.5） |
| 工作区 | 同一工作区内的成员与智能体 | 团队制度、内部 Wiki、项目说明；同一工作区里多个智能体通常共用这一层 |
| 用户 | 仅当前账号 | 个人笔记、补充材料；默认不与同事共享 |
维护时：在对应层级 增删改文档 后，若系统使用检索索引，需按 §3.3 刷新索引（或等产品/任务的自动重建策略）。
3.2 单个智能体的「知识文档目录」（Markdown + 索引）
每个用户智能体可以有一套 自己的知识树（实现上在服务的运行时目录下；对用户可说「在该智能体的知识管理里维护」）：
- 放什么：以 Markdown（
.md） 为主；内容应是助手回答用户时可引用的说明、流程、接口约定等。 - 目录结构（推荐）
- 根目录可直接放若干 .md。 - 也可以按 一级主题 建子文件夹，每个文件夹里多篇 .md（便于分工与检索）。
- 两层索引（系统用）
- 根目录 index.json：总览「根下有哪些文档、有哪些一级主题文件夹」及摘要、关键词。 - 每个一级主题文件夹 内 index.json：列出该主题下各篇文档的路径与摘要。 - 规则细节（白名单、路径不写 ..、先根后子目录生成等）见 AI重建知识索引规则.md。
用户侧表达：改完文档后，应执行一次「用 AI 重新生成索引」（或全量重建），否则对话可能仍按旧索引选篇，漏掉新内容。
3.3 刷新索引（维护流程）
- 编辑/上传/删除
.md文件，保持 UTF-8、路径合理。 - 调用产品提供的 「知识重建索引」 能力（或后台任务）。与实现相关的分步接口示例（预览 → 根索引 → 各主题子索引 → 一键）见
AI重建知识索引规则.md文末「分步生成与进度」表；HTTP 路径挂在/api/v1/user-agents/{id}/knowledge/reindex...一类路由上（以当前路由为准）。 - 失败时根据返回说明检查：模型是否配置、磁盘路径是否可读、某篇
.md是否损坏等。
3.4 与工作区知识、全局知识的配合
- 智能体私有的
.md+ 索引：最贴该助手业务，适合角色专用口径。 - 工作区知识：适合多人共建、多智能体共用；需在产品中按工作区范围上传/授权。
- 全局帮助：由运维配置挂载目录与根索引文件（见 §3.5），主要服务 未选工作区时 的 帮助智能体 等场景。
3.5 运维：全局帮助文档目录（实现名）
部署 Cadau 时可通过环境变量指定帮助侧静态文档根目录与索引文件名，例如：
HELP_DOCS_DIR：全局帮助文档根目录（默认help）HELP_DOCS_INDEX_FILE：根索引文件名（默认index.json）
具体以 backend/internal/config 中加载逻辑为准。此为 运维/对接文档 用语，面向最终用户可只说「全站帮助知识挂载在服务端」。
4. 第三方如何嵌入「我的智能体」
4.1 总体分工
| 一方 | 责任 |
|---|---|
| Cadau 运维 | 提供 HTTPS、API、嵌入脚本 URL（通常与 API 同源，如 /embed/mindlink-widget.min.js） |
| 宿主后端 | 用自有账号体系登录后，向 Cadau 或自建签发服务申请 短期令牌（含过期时间、app_id、允许的 user_agent_id、workspace_id 等声明）；不得把长期密钥下发浏览器 |
| 宿主前端 | 加载脚本 → 调用 init（或 Web Component）→ 监听事件 → 对 action 做白名单校验后再执行业务跳转或接口 |
完整字段、TypeScript 类型、动作白名单、错误码与时序见 sdk/host-embed/SDK契约.md（必读）。可交付集成说明（含 init 示例、功能导航、服务端代签）见 sdk/host-embed/网站集成说明.md；宿主侧知识文档写法见 sdk/host-embed/宿主知识文档撰写要求.md。
鉴权（推荐做法，供宿主架构对齐）：用户登录宿主后，由 宿主后端 向 Cadau（或 Cadau 认可的签发服务）换取 短期嵌入令牌，再将 token 与 expires_at 交给前端 init；浏览器不持有长期密钥。联调原型可参考范例中的环境变量注入，上线前应收敛为后端换票。若贵司另有时序图或内部 wiki，可在下节 §6「深入阅读」中增加 标题 + 链接，不要在说明书正文粘贴密钥或完整 claims。
4.2 最小接入步骤（前端）
- 引入脚本：
https://<mindlink-域名>/embed/mindlink-widget.min.js
- 在登录宿主系统且拿到 短期
token后执行：
window.MindLinkWidget.init({ base_url, user_agent_id, auth: { token }, host_actor?, app_id?, api_base_url?, workspace_id?, theme?, position?, locale?, entry? }) A 路径最小只需 base_url + user_agent_id + auth.token。B 路径须传 host_actor（当前登录用户身份）。entry.auto_execute_navigation 默认为 true：用户明确说「帮我打开…」时，回答结束后自动执行首条 mindlink://action/ 导航（宿主须实现 action 白名单）。
- 令牌将过期时：宿主刷新令牌后调用
updateAuth；换登录用户时调用updateHostActor（见契约中的WidgetHostApi）。
4.3 主题、位置与宿主页面一致
theme：light|dark|auto。auto：优先跟随宿主页面<html data-theme="dark|light">，其次html/body的.darkclass，再使用系统prefers-color-scheme（详见sdk/host-embed/SDK契约.md§6.2）。position：bottom-right（默认）、bottom-left、middle-right（右侧居中）、center（页面正中）、inline（需指定容器）。
4.4 范例：HR 多租户工作台（仓库内）
- 嵌入 BFF 与分配：
examples/hr-multi-tenant/docs/嵌入智能体接入指南.md（embed-session、服务端代签、用户↔智能体分配）。 - 宿主知识文档（中文分篇）：
examples/hr-multi-tenant/docs/宿主知识文档/导读.md。 - 开发期环境变量注入见
examples/hr-multi-tenant/web/README.md。不要将带真实令牌的.env提交到公开仓库。
4.5 联调与安全检查（摘要）
嵌入契约 §8 联调检查清单、§9 错误码；产品设计边界：不在嵌入端执行任意脚本，不持有长期密钥，动作仅允许 open_url / open_module / emit_event 等白名单类型。
5. 使用产品（成员日常）
- 登录：手机号或邮箱 + 密码或验证码（
产品规格.md§1.5.2）。 - 选择工作区（若账号在多个团队中）：当前工作区决定可见的工作区知识、协作资源等。
- 聊天：新建或继续会话；需要时 选定智能体 再提问。
- 操作助手（主站内）：在工作区场景下的浮动帮助入口（具体文案与能力以界面为准；机制见
产品规格.md§4.1.5 与工作区帮助快捷一句.md）。 - 人工客服：为智能体开启人工客服（本区席位或授权客服小组）后，用户可在对话中点 「人工客服」；客服同事用 客服工作台 接单（见
人工客服.md、help/product-features/human-customer-service.md）。 - 嵌入助手：在第三方页面里使用 §4 的组件，会话与令牌独立于主站 Web，但对话仍走 Cadau 后端。
6. 深入阅读索引（维护本说明书时）
| 主题 | 文档 |
|---|---|
| 总规格与 API 摘要 | docs/产品规格.md |
| 嵌入 SDK | sdk/host-embed/SDK契约.md |
| 网站嵌入集成说明（可交付） | sdk/host-embed/网站集成说明.md |
| 宿主知识文档撰写 | sdk/host-embed/宿主知识文档撰写要求.md |
| 索引生成规则与接口表 | docs/core-mechanisms/AI重建知识索引规则.md |
| 索引与反馈闭环方法论 | docs/core-mechanisms/索引式文档与反馈闭环.md |
| 管理员端能力 | docs/管理员端规格.md（含附录运维） |
| 人工客服 | docs/core-mechanisms/人工客服.md、help/product-features/human-customer-service.md |
| HR 范例（嵌入 + 知识） | sdk/host-embed/参考范例-HR接入指南.md、examples/hr-multi-tenant/docs/宿主知识文档/导读.md |
7. 本版正文前提（已与读者确认）
| 项目 | 约定 |
|---|---|
| 主要读者 | 企业管理员 / 运营 与 宿主开发 / 架构 |
| 智能体市场 | 未作为主路径；以 自建智能体 为主 |
| 工作区知识 | 工作区管理员 维护 |
| 智能体专属知识 | 智能体创建者 维护 |
| 重建索引 | 与上传/编辑知识的人员相同 |
| 知识审批 | 当前不需要；以后若启用，以届时制度为准 |
| 嵌入令牌 | 推荐宿主 后端换短期令牌 再给浏览器；内部时序文档可列入 §6 链接，不写密钥 |
| 交付形态 | Markdown；PDF / 飞书 / Confluence 等 暂不需要（以后若要再定版式） |
| 合规专节 | 本版不写；需要时另开文档或由法务定稿后增补 |
*版本：1.3（与仓库 docs 对齐；嵌入以 sdk/host-embed/SDK契约.md V1.5.10 与 sdk/host-embed/网站集成说明.md 为准。接口与 UI 以部署实例为准。 §7 为约定快照，变更时请同步修订。）*