宿主知识文档撰写要求

版本：1.3

读者：在 宿主页（你的业务系统页面）嵌入 Cadau 助手时，负责编写或审核 智能体知识文档 的人员——通常为 产品 / 业务专家 与 前端或集成开发 协作完成。

表述：正文说明以 用户能懂的自然用语 为主；API 路径、字段名、环境变量等实现细节放在专门章节或括号中，不要用实现名词替代对用户行为的描述（与仓库 docs/产品规格.md 表述约定一致）。

关联文档：网站集成说明.md（§5 功能导航）、SDK契约.md。

---

1. 什么是「宿主知识文档」

宿主指接入 Cadau 嵌入挂件（或等价 SDK）的 你的业务系统，不是 Cadau 控制台本身。

宿主知识文档指：你方编写并挂载到 「我的智能体」→ 知识文档（或工作区层知识，见 §2）中的 Markdown 说明，供该智能体在 你的页面场景 下检索与作答。其核心目标是：

• 让助手 说对你的产品（页面叫什么、用户能做什么、常见限制是什么）；
• 让助手 会引导用户去对的页面（通过 §6 的功能导航链接，由宿主页白名单执行）；
• 让助手 不编造 你方未开放的数据、权限或未实现的接口。

Cadau 主站内置的 帮助智能体 知识（如 module.workspace）不自动适用于宿主页；嵌入场景须以 本文 + 你方文档 + 宿主页已实现的动作表 为准。

---

2. 写在哪一层（与 Cadau 三层知识的关系）

产品上知识分 全局 / 工作区 / 用户 三层（docs/产品规格.md §3.2.1）。宿主侧撰写时建议：

网站嵌入联调时，至少为该嵌入智能体维护 智能体专属 知识；若同一工作区内多个助手共用一套业务口径，再同步维护 工作区层 文档，避免每份拷贝不一致。

索引结构：文档较多时，建议 一篇总览 + 多主题文件夹（各夹内可配 index.json，见 docs/core-mechanisms/AI重建知识索引规则.md）。范例见 examples/hr-multi-tenant/docs/宿主知识文档/导读.md（两层目录：根导读 + 主题子夹）。

---

3. 撰写原则（必守）

3.1 用户表达优先

• 先写：谁、在什么页面、能完成什么结果（例如「在组织架构页右键部门可新增子部门」）。
• 后写：对应的 HTTP 方法、路径、JSON 字段（给助手排错与引用，不作为首屏话术）。
• 按钮、菜单、错误提示的称呼须与 宿主页 UI 文案一致，避免助手说「点 Workspace」而页面上是「工作区」。

3.2 真值边界

• 只写 宿主页已实现 的能力；未上线的功能标注「规划中」或 不要写入，避免助手承诺做不到的事。
• 业务数据若不在 Cadau 落库（宿主增强形态，见 docs/产品规格.md §4.2.4 与本目录 宿主增强-AgentRun与数据权限.md），助手 不得 捏造订单号、客户余额、他人租户数据等；应引导用户 在当前登录上下文 的页面查看，或调用 你已开放且已写入知识 的接口。
• 租户 / 组织 / 工作区 等隔离：明确写出「助手须以当前用户可见范围为准」「勿编造其他租户 id」。嵌入场景下，历史对话 / 人工客服 / 工单由挂件按当前登录用户（或网站访客）隔离，不要在知识里写「大家共用同一条聊天记录」。

3.3 与宿主页代码一致

• 功能导航（§6）中的 动作名、参数名 必须与宿主页动作白名单（如 executeHostAction / handleMindlinkWidgetAction）完全一致（区分大小写）。
• 代码增删动作后，同一次发布 更新知识文档中的 动作登记表（§6.4）。
• 宿主实现变更（路由哈希、模块名）时，同步改知识中的示例链接。
• 若宿主开启 entry.auto_execute_navigation（挂件默认 开启）：用户说「帮我打开…」时会 自动执行回答里第一条 导航链接——知识中须保证 第一条链接即最相关页面，且表中动作均已实现（见 网站集成说明.md §5.6）。

3.4 安全与合规

• 禁止在知识文档中写入：嵌入访问令牌、API 密钥、密码、私钥、完整个人信息样本。
• 禁止教助手输出 javascript:、data: 等不安全链接协议；外链仅 http/https，且域名宜在宿主页 open_url 白名单内。
• 涉及删数据、调权限、转账等 高风险操作：知识中写清「须由用户在宿主页确认」，不要 假设助手可直接代执行（除非宿主已实现带鉴权的受控动作且写入明确流程）。

3.5 篇幅与可检索性

• 单篇 .md 建议 聚焦一个主题（如「组织架构页」「订单列表筛选」）；过长则拆篇并建 一级主题文件夹。
• 改文后须在 Cadau 对该智能体执行 「用 AI 重新生成索引」（见 docs/core-mechanisms/AI重建知识索引规则.md），否则对话可能仍按旧索引选篇。

---

4. 推荐文档结构（模板）

可按下面章节组织 一篇总览 + 多篇专题；专题名与宿主页模块对应。

# <业务系统名> · <助手角色> 知识文档

> 用途：供嵌入在 <宿主页名称> 的 Cadau 智能体检索。
> 范围：仅描述 <系统/模块>；不代替 Cadau 产品规格。
> 维护：与宿主页版本 <x.y> 同步；代码动作表见 §5。

## 1. 用户在页面上能做什么（用户表达）

- （按页面或角色列举能力、限制、与其它页的关系）

## 2. 浏览器与后端如何对话（给助手用的摘要）

- 同源/代理约定、鉴权方式（用户语言描述「登录后由服务端下发嵌入会话」）
- 租户/工作区如何获取（须写「以接口返回为准，勿编造」）
- 错误时用户会看到什么

## 3. 业务接口或数据约定（可选，实现细节集中在此）

- Base URL、路径表、必填字段、常见错误码

## 4. 嵌入助手在本站的特殊说明

- 挂件形态（右下角 / 行内）、是否全站可用
- 与 Cadau 主站能力的差异（如不能代替用户点宿主按钮）
- 用户明确要求打开页面时，挂件可能自动执行第一条功能导航（须输出正确链接顺序）

## 5. 功能导航（mindlink://action/）

- 动作登记表（§6.4）
- 回答规范：何时在文末给出 1～3 条链接；自动导航时第一条须最相关
- 示例 Markdown 链接（与登记表一致）

## 6. 版本与维护

- 对应宿主仓库路径、负责人、最近更新日期

仓库内范例：examples/hr-multi-tenant/docs/宿主知识文档/导读.md（人力资源多租户 · 全套中文分篇；总览见同目录 00-总则与功能导航.md）。

---

5. 建议挂载清单（嵌入联调最低集）

为 网站嵌入 场景，建议该智能体至少挂载：

不要 把 嵌入访问令牌 写进知识文档；令牌只出现在宿主页配置、环境变量或后端 embed-session / 代签 逻辑中。

---

6. 功能导航专章（嵌入场景必写）

6.1 机制（给撰写者）

1. 在知识中约定：需要帮用户 打开某页 / 带筛选查看 时，助手在回答中使用 Markdown 链接 + 协议 mindlink://action/。
2. 用户点击后，Cadau 挂件向宿主页抛出 action 事件（emit_event，kind: mindlink_action）。
3. 宿主页 仅执行已注册动作；未注册动作应友好提示，不 执行任意脚本。

语法：

`链接文案`

• 动作名：建议 page.<模块> 或 module.<模块>，与宿主页白名单键一致。
• 查询参数：标准 URL 查询串（如 status、id、tenant_id）；可选 label 供文案或埋点，宿主页可忽略。
• 链接文案：用用户能懂的话（如「打开待审批订单」），不要用动作名代替。

详细示例见 网站集成说明.md §5。

6.2 回答规范（写进知识，让模型遵守）

• 用户问「去哪看 / 帮我打开 / 跳转」时：在正文 末尾 给出 1～3 条 已登记动作链接，参数与 当前对话上下文 一致（如刚提到的订单 id）。
• 用户 明确请求打开（如「帮我打开组织架构」）且宿主未关闭自动导航时：挂件会在回答完成后 自动执行第一条 链接——第一条须为最相关、已实现的动作，其余链接供用户手动点选。
• 不要 一次堆砌十几条链接；不要 给出未在动作表登记的 action。
• 不要 使用 Cadau 主站专用动作（如 module.workspace、chat.new-session）除非宿主页已映射；否则用户点击无效（见 docs/core-mechanisms/帮助动作链接.md）。
• 未实现的筛选参数（如 tab=tree 但宿主只跳页面）：在动作表注明 「参数保留，当前仅跳转页面」，避免助手承诺未实现的子视图。

6.3 宿主页必须实现（技术，写入知识前先完成）

• widget.on("action", …) 中处理 mindlink_action（及可选的 open_url、open_module）。
• 维护 HOST_ACTIONS 或等价路由表；未知动作提示「暂不支持」。
• 生产环境由 服务端代签 短期令牌并下发 embed-session；浏览器 init 时 app_id、user_agent_id 与登记一致；过期时 updateAuth。

实现参考：网站集成说明.md §4、§4.3、§5.3；HR 范例：examples/hr-multi-tenant/web/src/mindlinkHostActions.ts。

6.4 动作登记表（复制到每份宿主知识文档 §5）

要求：下表由 宿主产品 + 前端 共同维护，与代码白名单 逐行一致。

示例链接（须能上表逐条对应）：

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

参数若尚未在宿主实现（如 tab=tree），须在表中注明 「参数保留，当前仅跳转页面」，避免助手承诺未实现的子视图。

---

7. 质量检查清单（发布前自检）

• [ ] 文中页面/按钮名称与宿主页 UI 一致，且无已下线功能描述。
• [ ] 未包含令牌、密钥、真实用户隐私样本。
• [ ] 动作登记表与宿主页白名单代码 一致；示例链接均可点击且跳转正确。
• [ ] 已说明租户/权限边界，含「勿编造 id」类约束。
• [ ] 文档变更后已对该智能体执行 「用 AI 重新生成索引」。
• [ ] 在真实宿主页完成联调：能对话、能点击回答中的导航链接；用户说「帮我打开 xx」时自动导航符合预期（见 网站集成说明.md §5.6、§6）。

---

8. 维护流程建议

1. 需求变更（新页面、改路由）→ 更新宿主页白名单代码 → 更新知识 §5 动作表与 §1 用户能力描述。
2. 接口变更 → 更新 §3 接口摘要，并抽查助手是否仍引用旧路径。
3. 发版 → 用 AI 重新生成索引 → 在预发宿主页抽 3～5 个典型问题回归（含「帮我打开 xx 页」与仅询问「去哪看」两种问法）。
4. 多环境（开发/预发/生产）→ 若动作或文案不一致，用 不同工作区 或 不同智能体 区分知识，勿混用生产真值。

---

9. 延伸阅读

---

10. 文档修订