概述

互客鱼附带一个一流的 WordPress & WooCommerce 插件， 在每个公共页面上放置流式聊天小部件，将站点内容作为知识源同步， 并且（当 WooCommerce 活动时）与商店深度集成 — 产品卡片、优惠券应用、 订单查找、潜在客户镜像和弃购重新互动。

插件位于互客鱼 monorepo 的 wp-plugin/hukeyu/ 中， 并作为版本化 zip 分发，您可以从任何运行在 PHP 7.4+ 上的 WordPress 6.4+ 安装中的 Plugins → Add New → Upload Plugin 安装。

这个插件做什么

• 小部件嵌入 — 一个异步 <script> 标签注入到每个公共页面的 wp_footer 中，范围限定为您选择的帖子类型。RTL 感知。在 wp-admin、wp-login、AJAX、REST、XML-RPC 和 cron 请求上隐藏。
• 内容同步 — 批量 + 增量摄取帖子、页面、自定义帖子类型和 WooCommerce 产品到互客鱼知识源。在共享主机上可恢复，带有 30 秒执行上限。
• 页面构建器渲染 — Elementor、Divi、Beaver Builder、Oxygen 和 Bricks 页面通过每个构建器的原生 API 渲染，以便它们的可见 HTML 真正到达 RAG 存储（而不是空的 post_content）。
• 购物者上下文 — 登录的 WooCommerce 客户的 wp_user_id + email_hash（永远不是明文）被签名并转发到聊天会话，以便智能体知道谁在说话。
• 订单查找 — lookup_order 工具通过 HMAC 签名的 POST 回调到 /wp-json/hukeyu/v1/orders/lookup，以便智能体可以回答 "我的订单在哪里？" 而不暴露客户数据。
• 优惠券发放和应用 — 智能体在聊天中渲染 <coupon/> 卡片；应用按钮将代码暂存在 transient 中，并在访客的下一次购物车加载时应用它。
• 潜在客户镜像 — 每个互客鱼潜在客户都被推回 WordPress 作为 WC 客户（或没有 Woo 时的 WP 订阅者），用户元数据中包含对话关联。
• 弃购触发器 — 一个小前端脚本将 WC 购物车事件镜像到 localStorage；当购物车在配置的阈值后空闲时，小部件主动互动。

兼容性矩阵

组件	测试范围
WordPress	6.4 → 6.6
PHP	7.4 → 8.4
WooCommerce	8.0 → 9.x（可选 — 插件核心在没有 WC 的情况下工作）
多站点	支持（每站点激活；每个站点连接到自己的互客鱼工作区）
页面构建器	Elementor（Free + Pro）、Divi、Beaver Builder、Oxygen、Bricks
主题	与主题无关。小部件在 Shadow DOM 中渲染，与主题 CSS 隔离。
RTL 语言环境	是（阿拉伯语、希伯来语、波斯语、乌尔都语等）。小部件通过 data-page-dir 镜像。

分发插件（super_admin）

Super-admins 可以从互客鱼管理员内部生成插件的安装就绪 .zip，无需 ssh 访问。 打开 /admin/integrations/wordpress：

1. 点击 Build latest。服务器对捆绑的 wp-plugin/hukeyu/ 源树运行 php artisan hukeyu:build-wp-plugin，并将版本化归档写入 storage/app/private/wp-plugin-builds/hukeyu-{version}.zip。
2. 点击结果行上的 Download。归档以正确的 Content-Disposition 流式传输回来；大约 45 KB，包含顶级 hukeyu/ 目录。
3. 归档排除仅开发文件（.DS_Store、node_modules/、tests/、.git*），因此您的租户上传的内容正是 WordPress 应该安装的内容。

无头替代方案：php artisan hukeyu:build-wp-plugin 从 CLI 工作并打印结果路径。可选的 --output 标志覆盖目标目录。

安全模型概览

插件和互客鱼服务器使用两个不同的凭据相互身份验证，方向相反：

• 插件 → 互客鱼： bearer API 令牌。在 /settings/api-tokens 中创建，范围 wp:integration。互客鱼仅存储明文的 SHA-256 哈希。插件将明文保留在 wp_options 中（视为 wp-config.php 级别的秘密）。
• 互客鱼 → 插件： HMAC-SHA256 签名，使用每个令牌的 shopper_signing_secret。插件在握手响应中接收此秘密并将其本地存储。互客鱼使用它对每个回调（订单查找、优惠券应用、潜在客户推送）进行签名，以便 WordPress REST 端点可以验证调用者是互客鱼，而无需持有 bearer 明文。
• 重放保护： 两个方向都对 HMAC 签名强制执行 5 分钟时间戳窗口。

详见 REST API 参考 了解确切的签名方案和验证代码路径。

当前版本

插件版本 2.0.4。自 v1.x 以来的 notable：

2.0.x 补丁系列

• 2.0.4 — 管理列宽度修复。 在 WooCommerce 产品列表（和其他拥挤的列表表）上，"hukeyu" 列因为 WP 的自动宽度算法使其缺乏像素而每行渲染一个字母。通过 admin_head 样式块强制为 110px。
• 2.0.3 — "Indexed" 管理徽章 + 空主体回退。 帖子、页面和产品列表现在根据插件在每次推送时加盖的同步时间戳 + 内容哈希，为每行渲染绿色 "Indexed" 药丸、黄色 "Out of date" 药丸或灰色 "Not indexed" 药丸。特色图片_only / 构建器存根帖子的 the_content 折叠为空，从 title + excerpt + taxonomy terms 客户端合成，以便它们始终有可索引的文本。
• 2.0.2 — 空主体帖子 + 每种产品类型。 预修复帖子同步批次在第一次任何帖子有空主体时因 posts.N.content_html field is required 而死。预修复产品同步器过滤到 [simple, variable, grouped, external]，这静默丢弃了订阅、捆绑、会员、预订和自定义类型。两者都已修复；回退 WP_Query 覆盖其 wc_get_products 钩子链隐藏一切的主机。
• 2.0.1 — 诊断 Test connection。 通用的 "Connection failed" 消息已消失。插件现在显示 HTTP 状态、它尝试的 URL、网络故障时的传输级 cURL / DNS 代码，以及上游响应主体的前 800 个字符。"Show details" 切换显示完整的诊断块。HTTP 状态感知提示（401 → 重新颁发令牌，403 → 缺少范围，404 → 未部署，5xx → 服务器日志）。

2.0.0 — 主要版本

• 页面构建器内容真正到达 RAG 存储（之前对 Elementor/Bricks/Oxygen 为空）。
• WooCommerce 加载顺序竞争修复 — 插件的 WC 依赖钩子现在推迟到 woocommerce_loaded，而不是在 plugins_loaded 优先级 10 时信任 class_exists('WooCommerce')。
• 同步可在多个 WP-Cron tick 上恢复 — 大目录不再遇到 30 秒执行上限。
• 优惠券枚举从 wc_get_coupons()（不是公共 API）切换到 shop_coupon CPT 直接。
• abandoned_cart 规则种类暴露在智能体 Behavior triggers 管理员中。
• RTL 镜像 + 管理员后台同步通知。

详见 应用程序变更日志 了解完整的发布历史。