核心概念

在每个页面上都会看到的一些核心概念。如果您只阅读一篇文档， 那就读这一篇。

工作区

互客鱼中的每个数据都属于且仅属于一个工作区。用户可以成为多个 工作区的成员并在它们之间切换；智能体、对话、潜在客户、知识源和 分析数据永远不会跨越边界。

多租户由 BelongsToWorkspace Eloquent trait 强制执行， 它会添加一个全局作用域，按当前工作区过滤每个查询。有一个回归测试 （MultiTenancyTest），如果在没有该作用域的情况下查询 租户范围的模型，构建将失败。

智能体

智能体是您嵌入的基本单元。它拥有角色设定、系统提示词、主题、 开场白提示、允许来源、行为规则，以及——重要的是——自己的知识源。 一个工作区可以有多个智能体（例如，一个用于营销网站，一个用于帮助中心）。

智能体有 草稿 和 已发布 两种状态。 小部件运行时始终读取已发布版本，因此您可以自由编辑而不影响实时访客。 每次发布都会创建一个不可变的 agent_version 记录，您可以回滚到该版本。

知识源

知识源是您希望智能体学习的任何内容：URL、站点地图、Feed、粘贴的文本、 Notion 页面、Google Doc，或者——当自动索引开关开启时——访客访问的页面。 每个知识源产生一个或多个 文档；文档被分块成约 500 个 token 的片段，进行嵌入并 upsert 到向量存储中。

请参阅 知识源 了解导入流程， 以及 RAG 管道 了解检索工作原理。

对话

对话是一位访客与一个智能体之间的线程。它在页面重新加载后仍然存在—— 当小部件在 24 小时内重新初始化时，我们会恢复最近的对话而不是开始新的对话。 消息具有角色：user（用户）、assistant（助手）和 human-agent（人工客服，当操作员从收件箱接管时）。

潜在客户

潜在客户是您已捕获其联系信息的访客（姓名、邮箱、电话，以及您定义的任何 自定义字段）。当对话达到一定的意向阈值时，小部件会以内联方式询问这些信息—— 请参阅 语音、潜在客户和持久化。 潜在客户在每个智能体上按邮箱去重，因此同一人填写两次表单不会创建两条记录。

套餐

套餐是平台管理员管理的订阅层级（免费、专业版等）。每个套餐定义一个 每月对话配额和一个 功能配置——目前 features.remove_branding 是唯一的标志，但这是一个开放结构。 套餐会自动同步到 Stripe 作为产品和价格，因此管理员无需操作 Stripe 仪表板。

热路径

"热路径"指的是访客消息 → 首个 token 的路径。它有严格的 1 秒 p95 延迟目标——无数据库写入、无同步 webhook、无重试。管道流式传输 token， 然后在流完成后异步调度持久化和分析工作。详见 热路径和延迟。

来源白名单

小部件脚本是公开的——任何找到您的 data-agent-id 的人都可以 将其粘贴到自己的网站上。/v1/widget/init 端点为每个智能体执行 严格的来源白名单：空列表表示拒绝所有来源，否则进行精确的 scheme://host 匹配，不推断子域名。 允许来源 中有详细规则。

超级管理员与工作区成员

工作区成员看到的是客户界面（/dashboard、 /app/agents、/app/inbox、/app/billing）。 超级管理员还可以看到位于 /admin 的平台控制台，用于管理套餐、 监控使用情况、重试失败的作业以及为客户支持而模拟客户登录。该标志是 users.role = SuperAdmin，由 EnsureSuperAdmin 中间件控制（返回 404 而非 403，因此面板不会暴露其存在）。