企业知识库产品内嵌帮助对照清单:Docs Embed、知识小组件与上下文投递
产品内嵌帮助,是把已经发布的企业知识库或产品手册,以小组件、可编程 Embed 或简化视图的方式投递到产品界面里,让用户不必离开当前任务就能搜索、浏览或向同一知识源提问。它不等于在导航里放一个帮助中心外链,也不等于把某一篇公开页面用 iframe 嵌进网站。本文对照 GitBook Docs Embed、Document360 知识库小组件、基于 Confluence 发布层的 K15t Scroll Sites 小组件,以及 Notion Sites 的页面嵌入,给出一份可写进验收手册的对照清单。
浏览 9
巴克励步
导语:先分清「外链打开文档站」和「在产品里投递同一份知识」
产品内嵌帮助(in-app help / docs embed),是把已经发布的知识库或产品手册,以浮动小组件、可编程 Embed 或简化视图的方式投递到产品或网站里,让用户在当前任务中搜索、浏览页面,或向同一知识源提问。它解决的是分发面问题:知识已经写好、也已经能发布成文档站,但用户还要新开标签页才能读到。
三种常见做法不能写进同一格。第一种,只在产品菜单里放「帮助中心」外链,用户离开当前界面。第二种,把某一篇已发布页面嵌进网站或后台,页面会随源内容更新,但通常没有站内搜索、权限会话和按路由投递。第三种,才是本文要验收的产品内嵌帮助:同一份已发布知识,出现在产品里的搜索、浏览或问答界面,并且能按当前页面上下文和读者权限决定看见什么。
本文对照 GitBook Docs Embed、Document360 知识库小组件、把 Confluence 内容发布为帮助中心后再嵌入的 K15t Scroll Sites Help Center Widget,以及 Notion Sites 的页面嵌入。重点不是功能名谁更响,而是投递形态、上下文、身份权限和安全边界能不能写进运行手册。
为什么现在要单独验收这条分发面
最近给企业 Wiki 做选型时,文档站、多版本与多语言、权限模型和 AI 问答指标,往往已经各自有对照清单。缺的是「同一份知识资产如何进入产品界面」。用户提问发生在结算页、权限设置或集成配置里,而不是发生在文档站首页。如果内嵌层用了另一份摘录、另一个权限或另一套 AI 索引,文档站写对了,产品里仍可能答错、越权或过期。
对照时应看的六个维度
立项时先把下面六行写成必填项,再去看各家菜单叫 Embed、Widget 还是 Help Center。
投递形态。 是浮动小组件、可编程 Embed(脚本、NPM 或组件)、按页面打开的简化视图,还是仅把一篇公开页嵌进 iframe。形态决定你能不能自定义触发按钮、隐藏默认图标,以及在产品的某个区域而不是右下角打开。
上下文投递。 能否按当前 URL 的路径、查询参数或哈希,打开指定文章、分类、搜索结果,或在登录页、结账流里隐藏组件。没有这一层,小组件只是把文档站缩进了一个抽屉。
身份与权限。 公开知识库可以直接嵌入;私有或混合可见的知识库,必须说明令牌从哪来、过期后如何续发、读者组如何映射到可见文章。不要假设「文档站已经要登录,小组件就会自动带上同一会话」。
内容范围与链接行为。 小组件是看到整个项目、某一个工作区或某几组分类,链接是留在组件内还是新开标签。范围一改,原先按页面配置的上下文映射可能失效,需要同步回归。
AI 是否与同一知识源。 内嵌问答如果存在,要确认它检索的是已发布、当前读者有权看见的那份内容,而不是另一份未审核语料。也要确认启用问答是否有独立开关,避免文档能嵌、问答却未开。
安全边界。 域名白名单是否默认放行所有站点、密钥是否只显示一次、身份提供商的访问令牌能不能直接塞进 Embed。这几项写不清楚,内嵌帮助会变成一条新的内容泄漏面。
先看对照表,再进入各家细节
| 验收项 | GitBook Docs Embed | Document360 知识库小组件 | Confluence + K15t Scroll Sites | Notion Sites 页面嵌入 |
|---|---|---|---|---|
| 投递形态 | 可编程 Embed,可含问答、搜索、文档浏览三个标签 | 浮动知识库小组件,可按受众或环境建多个 | 帮助中心主题站点上的 Help Center Widget,也可用 iframe | 将已发布页面复制嵌入代码,贴到非 Notion 网站 |
| 上下文投递 | 可在产品里打开、定制建议问题与操作;需自行与产品路由结合 | 官方提供 URL 映射,可按路径、查询或哈希展示文章、列表、搜索、上下文 AI,或隐藏组件 | 脚本里指定要打开的帮助中心页面 URL;定位与行为可配置 | 嵌入的是选定的已发布页面,不是按产品路由映射多篇文章 |
| 私有内容访问 | 需传入 GitBook 签发的 visitor token;Embed 不能在组件内静默完成文档站 OIDC 登录 | 私有或混合可见项目可用 JWT,由产品后端换票,读者无需再看一遍登录屏 | 取决于已发布的 Scroll 站点本身如何做访问控制,需在发布层单独验收 | 帮助中心写的是把页面发布到 Web 后再嵌入,不把它当成私有知识库的会话投递 |
| 内容范围 | 以已发布的文档站为源,标签可按需只保留部分 | 可按项目、工作区、语言或分类过滤;与读者组权限取交集 | 显示指定帮助中心页面的简化视图;站点须已上线且使用帮助中心主题 | 发布一个页面时,其子页面也会一并发布,嵌入前要检查整棵子树 |
| AI 问答 | Assistant 标签需在站点的 AI 与 MCP 设置中单独启用 | 可在小组件中开启 AI 辅助搜索,但须先在项目的 Eddy AI 设置中启用 | 公开的小组件说明聚焦嵌入帮助页面,不把它写成独立的内嵌问答产品 | 官方嵌入说明针对的是页面嵌入,不是内嵌知识问答 |
| 安全与安装边界 | 脚本地址来自站点设置;受保护站点要在脚本 URL 和初始化参数里带上 token | 可限制信任域名,不支持通配符;空名单表示不限制。安装说明面向 Business Enterprise 方案,需核对当时定价 | 可用官方 unpkg 脚本,或不向第三方发请求、改为自行托管小组件 | 嵌入代码来自已发布页面的「Embed this page」 |
表里的 Confluence 一列写的是发布层方案,而不是 Confluence 编辑器自带小组件。协作 Wiki 要进入产品界面,通常要先经过可发布的帮助中心或文档站,这一点与替代 Confluence / 语雀 / 飞书时要看「能否发布」是同一条线。
GitBook:Docs Embed 是可编程分发面,登录不能想当然
GitBook 把 Docs Embed 写成把文档站嵌进产品或网站的窗口:用户可以向 GitBook Assistant 提问、搜索文档,或直接浏览页面,而不离开产品。Embed 默认可包含 Assistant、Search、Docs 三个标签,也可以按配置只保留其中一部分。打开方式可以是按钮、放进自有组件,或完全由程序控制。
接入前有两道前提。第一,文档必须已经发布,并且有可访问的站点 URL。第二,要从站点设置的 AI 与 MCP → Embed 取出嵌入脚本地址。若要使用 Assistant 标签,还须先在同一设置里启用 GitBook Assistant。实现上官方提供独立脚本、Node.js/NPM 包
@gitbook/embed,以及 React 组件,受保护文档要另走带身份验证的 Embed 说明。权限验收最容易在这里失手。Docs Embed 需要的是 GitBook 签发的 visitor token,而不是身份提供商的访问令牌或 ID 令牌。官方写明,Auth0、Descope 等使用 RS256 的令牌与 Embed 不兼容,不能把这类令牌改签或「转换」后再传入
visitor.token。对于以 OIDC 保护的文档站,支持的路径是:用户先到受保护的文档站完成交互式登录,GitBook 建立会话并写入 gitbook-visitor-token,产品再读取该令牌并传给 Embed。官方还写了一条硬边界:Docs Embed 不能发起、重定向或静默完成文档站的 OIDC 授权;如果希望用户第一次在产品里打开帮助就静默登录,目前没有受支持的集成路径。这意味着,GitBook 的内嵌帮助可以和文档站共用同一套已发布内容与问答,但「文档站能登录」并不自动等于「产品里的 Embed 已登录」。验收时应准备:未登录用户会看到什么、如何被引导到文档站登录、登录后 token 如何回到产品、脚本 URL 是否同时带上
jwt_token。Document360:小组件、URL 映射和 JWT 要当成三条配置
Document360 的知识库小组件是可以嵌在网站或产品里的浮动入口,用户不用离开当前页就能打开知识库。创建入口在知识库门户的 Connections → Knowledge base widget。官方建议在不同受众、产品区域或环境使用不同小组件,并用测试小组件验证配置,再影响到线上。创建时可以开关 AI 辅助搜索、更换图标和颜色、选择左右位置和边距、写不超过 50 个字符的欢迎语,也可以隐藏默认图标(改由自有按钮触发),或隐藏「最多搜索文章」区域。
安装方面,官方安装说明要求把脚本放到站点 HTML,既可装在 Document360 知识库站点上,也可装在外部产品里。页面描述把该能力写在 Business Enterprise 方案下,立项时要对照当时的定价与方案说明,不要只记下「有小组件」五个字。官方也建议:知识库站点和外部产品若都要装,使用各自独立的小组件,避免一套配置互相干扰。装好后,已检测到的域名是只读回填;真正决定「谁可以加载」的是安全设置。
小组件安全提供域名限制和 JWT 两类控制。域名限制只允许名单中的信任域名加载小组件:不支持
*.domain.com 通配符,也不支持带路径的条目;写父域即可覆盖其子域。空名单表示不限制,可在任意域名加载。本地联调和预发环境如果没写进名单,小组件会被拦截,表面上还可能像鉴权失败,官方提醒这时先查域名,再查 JWT。私有内容要走 JWT 配置。官方把 JWT 作为知识库可见性为 Private 或 Mixed 时的推荐做法:产品里的小组件向你配置的换票端点发静默请求,后端再向 Document360 换取签名 JWT,小组件按该读者可见范围取文章,读者不必再看一遍登录屏。启用 JWT 后,小组件脚本里的 API token 会被移除;若之后关闭 JWT,系统会重新生成 API token 并写回脚本。客户端密钥在项目内所有启用了 JWT 的小组件和聊天机器人之间共享,生成时只显示一次,轮换后必须同步更新所有调用方。官方示例把令牌有效期写在 300 到 86400 秒之间,并说明若已配置,过期后小组件可自动再要一张。另外,至少要配置一个有效的读者组 ID,小组件才能渲染内容。
内容范围是第三条配置。内容访问可按项目、工作区或分类过滤小组件里出现的内容,即使已经启用 JWT 也可以再收窄。读者登录后,系统用读者组权限与小组件级过滤器取交集,只有两边都允许的文章才会出现;点开组件内的链接时也会再检查,超出范围就进入受限状态。链接默认在小组件内打开,以保持「不离开产品」;也可以按组件分别设置外链或编辑器中的「新标签打开」是否真的新开。官方提醒:改内容访问会直接影响 URL 映射——过滤器一变,原先映射的文章可能不再属于当前范围,映射会失效。只能给当前过滤结果里仍然存在的文章配置映射。
上下文投递看 URL Mapping。安装小组件之后,才能按产品页面逐条配置小组件展示什么。可执行的动作有五种:展示单篇文章、在「推荐 / 最多搜索」区域列出选定文章、配置上下文 AI 提示、按指定检索词展示搜索结果,以及直接隐藏小组件。映射可匹配路径、查询参数或哈希,也支持正则。官方举例,登录页或结账流可以用「隐藏」;某个产品模块可以只推一组相关文章。注意:如果创建小组件时打开了「隐藏最多搜索文章」,「展示文章列表」不会出现。一条 URL 映射一次只关联一种语言;如果应用切语言时 URL 不变,就不能在同一 URL 上并列两套语言映射,需要为每种语言准备可区分的路径或参数。未配置映射的 URL,还可以选择回到知识库默认页,或保持用户上次在组件里打开的内容。
如果要把支持表单也放进同一入口,票务导流(ticket deflector)可以在小组件里增加一个菜单页:先展示相关文章,仍未解决再提交表单。它只能配在主工作区及其语言,离线状态的导流不能嵌入,决策树链接在小组件里也不受支持。这是客服闭环的加分项,不应代替前面的权限、范围和 URL 映射验收。
Confluence 生态:先有可发布的帮助中心,再谈内嵌
Confluence 本身首先是协作 Wiki。要把其中的操作说明送进产品界面,通常不是在编辑器里勾选一个「变成小组件」,而是先把内容发布成帮助中心或文档站,再在产品里嵌入这个发布结果。K15t 的 Scroll Sites Help Center Widget 就是这一类发布层能力:把帮助中心的内容嵌到应用、网站或其他资产里,用户不必跳到独立的 Scroll 帮助中心,也能在当前上下文打开帮助。
官方约束很具体。Scroll 站点必须已经上线,小组件才会显示;而且目前只适用于使用帮助中心主题的站点。最快捷的安装方式是在页面
<head> 中引入脚本,并传入要展示的帮助中心页面 URL;默认会出现在右下角。如果不希望向第三方服务发请求,可以不使用提供的 unpkg 地址,改为自行安装小组件。也可以在页面中手动放置组件,或用 iframe 做自有按钮和自有对话框。位置与行为可配置,例如按钮在左下或右下、对话框在按钮左侧或右侧、是否默认展开,以及用 CSS 选择器把已有元素替换为小组件。该说明页最近一次更新写在 2026 年 8 月 24 日,验收时仍以当时的帮助中心文档为准。对仍以 Confluence 为写作后台的团队,这意味着内嵌帮助的验收对象包括发布层,而不仅是空间权限和宏。没有可访问的已发布站点、主题不匹配,或只把 Confluence 页面链接丢进产品,都不算完成产品内嵌帮助。
Notion Sites:页面可以嵌入,但不要把它当成知识库小组件
Notion 帮助中心把 Notion Sites 写成把页面发布到 Web。发布后,源页面改动会自动同步到站点。同一篇说明里有「Make your site embeddable」:在已发布页面上点击
Embed this page,在对话框中 Copy this code,可选择是否显示页面标题,再把代码贴到自己网站的 HTML 或建站工具的代码块中,从而把已发布的 Notion 页面、表单、图表或数据库嵌进非 Notion 网站。这对营销页、公开说明或把某一篇手册嵌进官网是有用的,但和 GitBook、Document360 的产品内嵌帮助不是同一类能力。它没有官方的产品路由映射、没有「在组件内搜索整个知识库并按读者组过滤」的小组件模型,帮助中心也没有把它写成私有知识库的会话式投递。更需要小心的是官方提示:把一个 Notion 页面发布到 Web,意味着它的子页面也会一并发布。嵌入前要检查整棵子树,避免把内部讨论、草稿或权限说明一起公开发布后再嵌进产品。
如果团队的写作后台是 Notion,又希望在产品里提供搜索、问答和按页面投递,需要单独评估:公开站点嵌入是否足够,还是必须迁到具备发布面和内嵌投递的知识库,而不是把「可以 Embed this page」写成已经具备产品内嵌帮助。
一张最小可用的路由表示例
在选型和接入之前,先用一张表把「产品里的哪一页应该看到什么」写下来。下面是示例行,用来统一产品、文档和开发的验收口径,不是某家客户的真实路由。
| 产品界面(示例) | 路由特征(示例) | 目标读者 | 期望的内嵌行为 | 失败时不应出现的结果 |
|---|---|---|---|---|
| 结算与账单 | 路径包含 /settings/billing |
已登录的客户管理员 | 打开「如何更新付款方式 / 发票」类已发布文章,允许继续搜索同一权限范围内的手册 | 不该看到内部财务排障或未发布草稿 |
| 成员与权限 | 路径包含 /settings/members |
已登录的客户管理员 | 打开「邀请成员与角色」类文章;链接留在组件内,避免把人送出设置流程 | 不该看见只给内部实施顾问看的配置手册 |
| 登录与注册 | 路径包含 /login 或 /signup |
未登录访客 | 隐藏小组件,或只展示公开的登录说明 | 不该加载私有知识库,也不该弹出文档站登录墙打断登录 |
| 开放 API 引导 | 路径或哈希能区分语言,例如 /docs/api?lang=zh |
按语言区分的开发者 | 映射到对应语言的已发布条目;URL 不变就不要指望同一映射同时服务两种语言 | 不该在中文界面里打开另一语言的旧文,或映射因内容过滤变更而落空 |
有了这张表,再去核对 GitBook 的 token 回流、Document360 的 URL 映射和 JWT、以及 Confluence 发布层能否先给出可访问的帮助中心页面。表比演示环境里「右下角能弹出一个框」更接近真实验收。
可执行的验收清单
把下面这些写成立项和上线检查项,而不是演示通过就算完成。
- 先定义分发面。 写清要验收的是外链、单页嵌入,还是可搜索、可浏览、可按上下文投递的产品内嵌帮助。三种目标不要共用同一份通过标准。
- 源必须是已发布内容。 GitBook 要求文档站先有可访问 URL;K15t 要求 Scroll 站点已上线且为帮助中心主题。草稿、仅内部 Wiki 可见的页面,不能算内嵌帮助的源。
- 触发方式与页面覆盖。 验证默认浮动按钮、自有按钮、默认隐藏,以及在登录、结账、管理页等位置是显示、映射到指定文章,还是彻底隐藏。
- 上下文映射可回归。 若使用 Document360 的 URL 映射,准备一份「产品路由 → 期望文章或动作」表,覆盖路径、查询、哈希和默认行为;改内容范围后重新跑一遍映射,确认没有失效项。
- 公开与私有要分开测。 公开库只测域名限制和内容范围。私有或混合可见库必须测未登录、已登录、读者组切换、令牌过期续发,以及越权链接是否进入受限状态。
- 不要直接传入身份提供商令牌。 在 GitBook,应传入 GitBook visitor token,并接受「需先在文档站完成 OIDC 登录」这条边界;在 Document360,应由产品后端按官方 JWT 流程换票,保护客户端密钥。
- AI 与文档同源。 若启用内嵌问答,确认它已在站点或项目级打开,检索范围与当前小组件的内容过滤、读者权限一致,并能抽查引用是否来自已发布页面。指标仍按忠实度、引用覆盖与拒答另验,不把「组件里能聊天」当成通过。
- 环境隔离。 预发与生产使用不同小组件或不同信任域名;空域名名单等于不限制,不能把联调配置直接带到生产。
- 不要为内嵌层再复制一份文稿。 产品里看到的标题、版本、语言和更新时间,应与文档站同一条目一致。若发现为了「写得更短」而另维护一套内嵌文,先停下来改发布与摘录策略,而不是继续双源。
- 上线后看行为,不只看能打开。 记录哪些路由打开了映射文章、哪些检索发生在组件内、哪些人中途离开去提交工单。内嵌帮助的内容缺口,应回到搜索分析和内容治理,而不是只增加一个按钮。
落地时怎么排期:先定「在哪一页出现什么」,再选组件
排期不要从挑厂商商标开始。先列出产品里最需要帮助的 10 到 20 个界面,写成「当前路由、目标读者、应当看到的文章或分类、看不到时应发生什么」。有了这张表,才能判断你需要的是单页嵌入、可搜索的 Embed,还是带 URL 映射和 JWT 的小组件。
接着验收权限交付。如果文档既给内部员工又给客户或合作伙伴,内嵌层必须沿用同一套读者身份,而不是在产品里另做一份「简化公开文」。GitBook 要先跑通文档站登录再把 visitor token 带回产品;Document360 要跑通换票、读者组和内容过滤器的交集。这两步不过,先不要做 AI 问答和工单导流。
最后再看一源多站。同一份产品手册,对外是文档站,对产品内是 Embed 或小组件,对有权限的读者还可以进入 AI 检索。Baklib Wiki 把知识资产发布、权限交付和 AI 检索放在同一套能力里,评估内嵌帮助时也应坚持这一条:先保证源内容可发布、权限可按分发面交付,再把产品界面当作又一个投递出口,而不是再建设一套只存在于小组件里的知识副本。
若你正在比较协作 Wiki 与可发布文档站,也可以一并阅读文档即代码与可发布企业 Wiki 的治理对照,以及支柱页里对知识资产发布与权限交付的选型框架。
想要了解更多?
数字内容新基建白皮书
常见问题
在产品菜单里放一个帮助中心链接,算不算已经做了产品内嵌帮助?
不算。外链会把用户带离当前任务,也没有按当前页面投递指定文章、在组件内搜索或沿用同一会话权限这些能力。如果目标只是「找得到文档站」,外链可以先上;如果目标是「在结算或权限页当场看懂操作」,需要按本文的内嵌帮助清单另验。
文档站已经要登录,产品里的小组件会自动带上同一权限吗?
不会自动带上,必须按产品验收。GitBook 的 Docs Embed 需要 GitBook 签发的 visitor token,且不能在 Embed 内静默完成文档站 OIDC 登录。Document360 对私有或混合可见项目推荐由产品后端做 JWT 换票,并用读者组与小组件内容过滤器的交集决定可见文章。文档站能登录,只说明发布面有访问控制,不说明内嵌层已经接好。
能不能为内嵌帮助单独维护一套更短的说明?
不建议把它变成第二套知识库。内嵌层可以按路由只展示某篇文章或某个分类,但源仍应是已发布的同一条目。单独维护「小组件专用短文」,很快会和文档站在版本、语言和更新日期上分叉。需要更短的表述时,应改发布结构或在同一条目里提供可复用的简短说明,而不是另开一个只存在于产品里的副本。
Notion 的「Embed this page」和 GitBook、Document360 的组件是一回事吗?
不是同一类能力。Notion 官方说明是把已发布的 Notion 页面嵌入到非 Notion 网站,发布时子页面也会一并公开。GitBook Docs Embed 和 Document360 知识库小组件面向的是在产品里搜索、浏览或向同一知识源提问,并分别提供受保护站点的 token 流程,以及 URL 映射、JWT 和内容范围等验收项。选型时不要用「可以嵌入页面」代替「可以做产品内嵌帮助」。
没有 URL 映射,只在右下角放一个能搜的按钮,能不能先上线?
可以作为一个过渡,但要把限制写进范围说明:它只是把文档站缩小放进产品,并不保证用户在关键页面看到与当前任务相关的文章,也无法在登录或结账页按策略隐藏。若产品路由稳定,应尽快补齐「路由 → 文章或动作」的映射和回归表,否则内嵌帮助很容易变成又一个被忽略的通用入口。
相关产品
术语
相关阅读
- Baklib Wiki 是什么:企业知识资产发布、权限交付与 AI 检索平台选型指南
- 产品手册与 Docs AI 可见性:协作 Wiki 到可发布文档站的 llms.txt / GEO 清单
- 产品手册多版本与多语言发布对照清单:版本切换、语言变体与一源多站
- 企业知识库权限模型:空间 / 页级 / 属性权限、SSO/SCIM 与外部共享对照清单
- 替代 Confluence / 语雀 / 飞书知识库:可发布企业 Wiki 选型对照
- 企业知识库 AI 问答可验证指标:忠实度、引用覆盖与拒答对照清单
- 文档即代码 vs 可发布企业 Wiki:产品手册治理对照清单
- 企业知识库搜索分析:零结果、跳出检索与内容缺口对照清单
- Wiki 知识库
- Wiki 对外发布 · 知识库内容分发