互 互客鱼 返回主站
/

WordPress 和 WooCommerce

安装和连接

本页引导您在新的 WP 网站上安装互客鱼 WordPress 插件， 将其连接到您的互客鱼工作区，并验证小部件是否真正在前端加载。

总时间：在 vanilla WordPress + WooCommerce 安装上约 3 分钟。 插件是完全自包含的 — 无需 composer install，无需构建步骤，无外部 CDN 依赖。

先决条件

  • 一个互客鱼工作区（在您的工作区 URL 注册，或请您的平台管理员创建一个）。
  • 运行在 PHP 7.4 或更高版本上的 WordPress 6.4 或更新版本。
  • 互客鱼中的工作区管理员或所有者角色（API 令牌页面是管理员限制的；查看者/编辑者被阻止）。
  • hukeyu-{version}.zip 归档文件 — 见下面的“我在哪里获取 zip？”

我在哪里获取 zip？

三种路径，选择适合您设置的：

  1. 从您的互客鱼工作区 — super_admin 打开 /admin/integrations/wordpress，点击 Build latest，然后 Download。归档文件位于服务器端的 storage/app/private/wp-plugin-builds/hukeyu-{version}.zip。
  2. 从 CLI 在互客鱼主机上：php artisan hukeyu:build-wp-plugin 写入 zip 并打印其路径。
  3. 从现有的租户安装 — 如果您的平台所有者已经向您分发了归档文件，那就是 zip；无需重新构建。

步骤 1. 上传和激活

  1. 在 WordPress 管理员中，打开 Plugins → Add New → Upload Plugin。
  2. 选择 hukeyu-{version}.zip 并点击 Install Now。
  3. 点击 Activate Plugin。
  4. 每个管理员页面顶部出现蓝色管理员通知："hukeyu is installed but not configured yet. Open Settings → hukeyu to connect."

插件注册自己，在步骤 3 之前没有前端行为 — 在您保存工作区 URL + 令牌之前， 小部件永远不会渲染。

步骤 2. 在互客鱼中创建工作区 API 令牌

  1. 登录您的互客鱼工作区。
  2. 打开 Settings → API tokens。
  3. 点击 Create token。以 WordPress 站点命名（例如 shop.example.com）。
  4. 授予 wp:integration 能力。
  5. 互客鱼仅一次显示明文令牌。格式：pbar_ + 48 个字母数字字符。现在复制它 — 只有 SHA-256 哈希被持久化，所以如果您丢失了明文，您必须撤销并重新颁发。

同一屏幕还在令牌创建时生成一个 shopper_signing_secret， 插件在其第一次握手时自动获取它（您永远不必粘贴它）。 详见 REST API 参考 了解秘密的用途。

步骤 3. 将 WordPress 连接到互客鱼

  1. 在 WordPress 管理员中，打开 Settings → hukeyu。
  2. 将您的互客鱼工作区基础 URL（例如 https://app.hukeyu.example）粘贴到 hukeyu base URL。尾部斜杠自动修剪。
  3. 将您刚刚创建的 API 令牌粘贴到 API token。
  4. 点击 Test connection。按钮禁用，状态行显示 "Testing connection…"，几秒钟内您要么得到绿色确认，要么得到红色错误。
  5. 成功时：空智能体下拉菜单替换为工作区中每个智能体的填充列表，工作区名称显示在下面（"Connected to workspace: Acme Storefront"）。插件还静默捕获了购物者签名秘密并将其存储在 wp_options 中。
  6. 选择哪个智能体应该在此站点上运行。每个智能体都有自己的下拉条目，附加其站点类型（例如 Storefront bot (ecommerce)）。
  7. 确认 Enabled 切换在 "Widget display" 下被选中。
  8. 勾选您希望小部件加载的 Post types。默认值：post + page。自定义帖子类型和（当 WooCommerce 活动时）product 作为额外的复选框出现。
  9. 点击 Save Changes。

步骤 4. 验证前端嵌入

  1. 在您的 WordPress 站点上打开公共页面（主页、博客文章、产品页面 — 任何匹配您启用的帖子类型的页面）。
  2. 互客鱼栏出现在页脚区域。默认情况下，它从底部边缘动画进入。
  3. 点击栏以打开聊天面板。输入问题 — 智能体流式传输响应。

如果小部件从未出现，请检查 故障排除 — 最常见的原因是主题省略了 wp_footer()， 或者缓存插件正在提供过时的 HTML 快照。

服务器端保存的内容

两部分内容存在于 WordPress 的 wp_options 表中，键为 hukeyu_settings（明文，因为 WordPress 选项在静态时未加密）：

  • API 令牌 — 完整明文值。信任级别：与 wp-config.php 秘密相同。随时从您的互客鱼工作区撤销以立即使其失效。
  • shopper_signing_secret — 每个令牌的明文秘密，互客鱼用于 HMAC 签名对您的 WP 站点的回调（订单查找、优惠券应用、潜在客户推送）。在第一次 Test connection 时自动捕获。
  • 选定的智能体、工作区 ID、工作区名称、启用的帖子类型、启用标志 — 小块配置。

通过 WordPress 仪表板卸载插件会删除这两个选项。 停用只会将它们保留在原位，因此重新激活不会丢失连接。

（重新）激活时发生的情况

如果插件在激活时已经配置（现有安装上的停用 → 激活周期）， 则一次性完全同步计划在 30 秒后通过 wp_schedule_single_event 在 hukeyu_run_full_sync_event 钩子上运行。当 WooCommerce 活动时，产品的第二个事件计划在 60 秒后运行 （以便帖子先完成）。这意味着上传新插件版本不会使过时内容孤立； 下一个 wp-cron tick 刷新智能体的知识库。

停用插件通过 wp_clear_scheduled_hook 清除两个计划的钩子， 因此在插件关闭后不会触发任何内容。

插件在 WP 管理员中显示的位置

  • Settings → hukeyu — 一切的单一配置屏幕（连接、智能体选择器、帖子类型切换、同步按钮）。
  • Plugins admin notice — 插件未配置时的柔和蓝色横幅，或者块状同步在后台完成时。
  • Users admin — 推送的潜在客户作为 WP 用户登陆（非 Woo 上的订阅者角色，Woo 上的 WC 客户），用户元数据中包含 hukeyu_lead_id + hukeyu_conversation_id。

权限

设置页面和所有 AJAX 操作需要 manage_options 能力 — 与 WordPress 用于 "General Settings" 的相同能力。 编辑者、作者和贡献者无法访问它。多站点 super_admins 也通过检查。

REST 端点（/wp-json/hukeyu/v1/*）故意是公开的 （permission_callback => __return_true）， 而是通过每个请求上的 HMAC 签名进行身份验证。 详见 REST API 参考。

干净地卸载

  1. 在 WP 管理员中打开 Plugins。
  2. 点击 hukeyu 旁边的 Deactivate。计划的同步事件被清除。
  3. 点击 Delete。WordPress 调用 uninstall.php，删除 hukeyu_settings 选项和 hukeyu_activation_flag 标志。
  4. 在互客鱼的 /settings/api-tokens 中撤销 WordPress API 令牌，以便存在于 wp_options 中的明文立即死亡。

插件已经推送到互客鱼的知识保留在知识库中 — 卸载插件不会删除智能体的 Sources 或 Documents。 如果您想要完全拆卸，请从互客鱼管理员中删除它们。