Widget 分端检查与 AI 排障提示词

个人页面出现“选择接收人”、客服漏掉同分组的订单、管理员无法介入时，先确定当前入口应使用什么身份、实际签发了什么 Session，再检查列表和消息。不要先隐藏按钮或扩大权限。

选择下面对应端的提示词，补充方括号资料，直接复制给能读取项目的 AI 编程助手。每个模板可独立使用；只提供脱敏字段，不提供 API Key、完整 Session Token、Cookie、密码或客户聊天正文。使用这些模板不需要开启 Open4X AI 服务。

接入端与身份合同

当前入口	商户服务端适配器身份	Open4X 凭证与接口	应有表现
个人用户会话列表	role: 'customer'	POST /v1/conversations/customer-session，内部 Token 类型 widget_customer_session	本人获授权的普通、订单客服会话，含从未打开的会话；无接收人选择、内部备注
个人用户单个会话	同上，服务端验证用户及订单归属	POST /v1/conversations/{id}/widget-session，Token 类型 widget_session	只打开指定会话；接收人由后端决定；不是全量列表凭证
商户网站客服	role: 'support_agent'	POST /v1/conversations/workbench-sessions，wbs_，scope: 'groups' + group_tags	授权组内明确加入客服队列的会话；公开回复与内部备注分开
商户网站管理员	role: 'admin'	同一工作台签发接口，wbs_，scope: 'tenant', mode: 'agent', supervise: true	当前商户范围查看；加入后回复，可接管；manage: true 另开状态、分配操作
Open4X 商户控制台	控制台验证当前商户账户及团队权限	控制台内部调用 /v1/conversations/console-session	仍使用同一个 Widget；第三方网站不要复用此签发接口
Open4X 平台运营	不等同于商户管理员	不因平台运营身份签发跨商户聊天授权	不能以排障为由查看其他商户正文

role 是商户本地 createOpen4XUnifiedSessionHandler 的可信解析结果，不是给所有 Open4X HTTP 接口随意增加的字段。工作台 HTTP 接口使用 scope、mode、supervise、manage 表达能力；mode: 'agent' 本身不代表商户全会话权限。wbs_ 只说明是工作台凭证，不说明它属于哪个组或是否为管理员。

同一账号兼任客服或管理员时，进入个人咨询页面仍应走个人分支。后端同时验证登录身份和当前接入场景，不能因为 isAdmin 就把所有入口升级为管理员，也不能直接信任浏览器传来的 role、用户 ID、订单或 tag。新接入统一使用 widget.js / Open4XWidget；旧 workbench.html 仅为兼容入口，不需要另建一套工作台组件。

个人端检查提示词

请诊断本项目 Open4X 个人用户端，读取实际代码后做最小修复，不先隐藏按钮。
页面及商户 Session 路由：[填写，不带 Token]
环境、现象和发生时间：[本地/staging/生产；例如出现接收人、没有列表、订单串消息]
授权样本：[脱敏用户别名、普通会话和两个订单会话 ID；没有则用本地 mock]
参考：
https://docs.open4x.com/zh/guide/widget-integration-diagnostics
https://docs.open4x.com/zh/guide/unified-widget-session
https://docs.open4x.com/zh/guide/customer-conversation-list
https://docs.open4x.com/zh/guide/conversation-groups

1. 追踪浏览器调用的商户 Session 路由、后端登录解析、Open4X 签发接口和实际挂载位置。个人入口应按 customer 解析，即使账号兼任客服也不能默认走工作台。role 是本地适配器字段，不是 customer-session 的 HTTP 参数。
2. 仅在授权本地调试中判断凭证类型，输出类型而不是原值。个人列表使用 widget_customer_session，单会话使用 widget_session。若拿到 wbs_，定位后端分支、混用路由或缓存；不得改 Token 前缀、伪造 JWT、用 URL 参数或 CSS 掩盖错误。JWT 解码仅用于诊断，鉴权仍由服务端执行。
3. 核对普通会话及订单是否已创建、活动 customer 归属和稳定 external_user_id。已有 Widget 绑定必须有效；2.3.7 起未打开的普通客服会话也可列出，唯一客服时首次打开自动绑定，多客服返回 widget_setup_required 由后端明确配置。单会话凭证没有列表不能靠前端扩权。conversationId 是默认展示位置，不是授权；不要自动导入全部历史订单或改写身份。
4. 用户和订单归属必须在后端校验；用户、订单使用稳定且独立的会话映射。发送对象由后端 participant_id/recipient_participant_ids 确定，个人界面不显示选择接收人、内部备注或转述。缺少接收人应修复服务端配置，不能广播给所有人。
5. 客服按用户分组接待，metadata.tag 不是授权。用户设置分组及后续 Upsert 会关联符合条件的单 customer 普通客服会话；作者私聊、争议、多 customer 不自动共享。检查 0056 迁移、路由归属及客服 group_tags，不因为个人列表能看到就认定任意客服也能看到。
6. 检查退出、换账号或换接入场景是否 destroy 后重新初始化、清理旧凭证缓存及未读状态。凭证续期仍需后端重新验证身份。发现误发工作台授权，列出需要撤销的 Session ID 和重新签发步骤，不输出 Token；生产撤销及配置变更须单独确认。
7. 测试本人普通会话和两个订单可独立切换、他人会话不可见、无接收人选择/内部备注、重试不串会话、过期和换账号清理。区分 mock 与实际环境结果。

不要索取或输出 Key、Token、Cookie、密码或聊天正文，不降低 CSP/来源校验，不自动生产发布或真实发送。交付已确认根因及文件/请求证据、最小修改、执行过的测试、未验证项；信息不足只列假设和下一项需要的脱敏证据，不声称已修好。

客服端检查提示词

请诊断本项目商户网站客服 Widget，重点排查同 tag 用户的普通会话和订单会话未进入列表。
页面、商户 Session 路由和环境：[填写，不带 Token]
授权样本：[客服别名、授权 group_tags、一个可见和一个缺失的 conversation_id、用户别名]
当前脱敏签发参数：[scope、group_tags、conversation_ids、constraints、mode、manage；未知写待查]
参考：
https://docs.open4x.com/zh/guide/widget-integration-diagnostics
https://docs.open4x.com/zh/guide/conversation-groups
https://docs.open4x.com/zh/guide/unified-widget-session
https://docs.open4x.com/openapi/conversation-groups.openapi.yaml

1. 先只读检查本项目后端身份和分组授权。客服使用 wbs_ 工作台凭证；经授权在 Widget 实际 origin 下查看 GET /v1/conversations/workbench-session，核对当前凭证实际授予的字段，不只看拟发送的配置，不输出凭证。不要把 role:support_agent 当作 HTTP 接口的全部配置。
2. 动态队列应是 scope:groups + 非空 group_tags，不传固定 conversation_ids。省略 scope 的固定 ID 模式只包含显式授权的会话，不会自动加入新会话。检查 constraints 是否进一步缩小结果，不为解决空列表改为 tenant、* 或全权限 Key。动态签发 Key 需 read/write/supervise 三项 conversation 权限，Key 仅在服务端。
3. 对可见和缺失样本逐项比较：同环境/同商户、conversation_type、稳定 external_user_id、权威用户 group_tag、路由归属、客服 group_tags、constraints、删除/参与者撤权。旧订单 tag 不再覆盖用户组。不要读取正文或扫描其他商户。
4. 分组不是 metadata.tag。PUT customer-groups 设置权威用户组并关联符合条件的历史单 customer 客服会话；后续 Upsert 继承。support_group:{} 或其中 null 继承；非空 tag 仅初始化未配置用户，冲突返回 409，不能用旧订单配置把用户改回旧组。清除用户组用 PUT customer-groups 的 group_tag:null；它不是公共组。检查 0056，历史冲突组由商户确认，不猜选、不私自改大小写。
5. 核对是否仅完成 customer-session 列表凭证签发却没有准备会话路由。历史漏关联会话可由授权商户后端 PUT /v1/conversations/{id}/support-routing，body 为 external_user_id 和 group_tag:null；只修复已确认归属的会话，先列变更及旧值、回滚方案，生产写入需批准。不得批量猜归属。general_support/content_support/order_support 可入组；creator_inquiry/dispute_case 不得为扩大列表而强行入组。
6. 检查 GET /v1/conversations/inbox 的状态/搜索/订单/用户筛选、offset/limit 和 pagination.has_more/next_offset；Widget 当前每页 25 条。比较接口是否已返回缺失 ID：已返回查前端分页/缓存/渲染，未返回查授权/路由/后端错误。API 非成功响应不能伪装成空数组，也不能以第一页无结果断言没有会话。
7. 检查 session origin 是否为实际 Widget iframe origin，不是商户页面 URL。过期或 Key 权限变化要按原权限重新鉴权；人员改组后撤销旧工作台 Session 并重新签发，不能让浏览器修改 group_tags。
8. 验收同组普通会话+两个订单、新建会话自动继承、分页后可找到、异组/其他租户不可见、旧订单 tag 不覆盖权威用户组、用户改组后旧组失去访问、已撤销参与者不能恢复。内部备注不对外；多人公开回复不得默认群发。

只使用授权样本和脱敏参数；不要求或打印完整 Key/Token，不自动发送真实消息、扩大权限或部署。交付“预期范围→实际授权→路由匹配→接口返回→界面显示”的证据链和最小修复。未拿到实际样本时标记待验证，不把推测写成线上根因。

商户管理员与控制台检查提示词

请诊断 Open4X 商户管理员的会话查看和介入功能。
入口：[第三方网站管理员 Widget / Open4X 商户控制台]
环境、商户/工作区别名、现象：[填写；不要提供 Token 或客户正文]
预期操作：[只查看 / 加入回复 / 接管 / 修改状态和分配]
参考：
https://docs.open4x.com/zh/guide/widget-integration-diagnostics
https://docs.open4x.com/zh/guide/unified-widget-session
https://docs.open4x.com/zh/guide/conversation-administration

1. 先区分商户管理员、分组客服、个人用户和 Open4X 平台运营。验证已登录用户对当前商户及当前入口的权限；不能让平台运营自动取得其他商户的聊天数据。同一管理员进入个人咨询入口仍按 customer 处理。
2. 第三方网站由自己的受保护后端签发 workbench-sessions：scope:tenant、mode:agent、supervise:true；不带 group_tags 或固定 conversation_ids。Bridge Key 的 conversation:read/write/supervise 仅在后端。检查实际 /workbench-session 授权及 constraints，不把前端角色或 token 前缀当管理员证明。
3. Open4X 控制台使用当前商户账户和团队授权的 console-session，再嵌入同一个 Widget。第三方不调用此专用路由，不再挂载独立的旧 Conversation Hub/Workbench UI。切换工作区、退出、身份变更后必须清除旧 Session。
4. 全部会话指当前商户范围，未分组会话也可查看；删除流程、撤权、额外 constraints 和列表筛选仍需核对。检查 inbox 的过滤、25 条分页、HTTP 状态及实际返回，不用跨租户查询补齐列表。
5. 查看不自动加入。核对 GET /v1/conversations/{id}/supervision；需要回复先 POST 同一路由 action:join。takeover/release 带最新 revision，409 后刷新状态，不盲目重试。被移除的参与者不能自行恢复；manage:true 只另开状态/分配，不替代 supervise，也不绕过加入规则。
6. 唯一有效接收人自动选择，多人回复/转述明确选择，不默认广播；内部备注永不进入个人端。界面显示“管理员”不等于匿名操作，审计应保留实际身份。
7. 测试当前商户个人/订单/未分组会话可查看、加入后回复、接管冲突、释放、已撤权拒绝，以及其他商户不可访问、换工作区无残留。真实介入、消息发送和生产变更需另外确认，优先本地 mock。

只输出脱敏权限/状态和 request_id，不输出秘密、正文或其他商户数据。交付实际根因、最小修复、测试证据及未验证项，不把权限扩大或仅隐藏按钮当修复，不擅自上线。

空白、来源与版本检查提示词

请排查 Open4X Widget 的加载、跨域或版本问题，不改变用户授权范围。
入口和现象：[个人/客服/管理员；页面地址不带 Token；脱敏错误]
参考 https://docs.open4x.com/zh/guide/unified-widget-session 和 https://docs.open4x.com/zh/guide/widget-display
先确认实际 Loader 与 Widget runtime 版本；两者独立，不能只凭 Loader 日志认定运行界面最新版。核对 API、Widget、Key 的环境配套，不把 widget.open4x.com 当 API Base，也不自动切生产或 workers.dev。
逐层检查商户 Session 接口、脚本、iframe、API/WS 的请求状态与 Content-Type。响应为 HTML 时先排查 URL/代理/路由，不直接当 JSON，也不归因于权限。
核对发起请求的页面 CSP：script-src/frame-src 与 connect-src 各自生效；额外 fetch(widget.js) 会受 connect-src 限制。移除不必要预取或只批准必要来源，不全局放开 *。区分商户 Session 的 CORS/Cookie/CSRF 与 Widget 的来源校验。
核对真实 parent_origin 和发送窗口、工作台 Session 的 iframe origin。localhost 是本地调试地址，不是生产白名单；srcdoc URL 的 null 不等同于继承后的安全来源。不要把 null 改成 *，不要为不可信 iframe 取消 sandbox，不向未知来源 postMessage 凭证。
检查重复挂载、过期、换用户及旧凭证缓存；无授权时明确失败，不自动切换角色。输出定位层级、请求状态/request_id、版本、最小修复及桌面/移动端复测。不要输出完整 iframe URL/hash、Token 或 Cookie；无法实测标记未验证，生产发布另行确认。

脱敏诊断记录

让 AI 按下表交付；无需附原始请求头、完整响应包或数据库导出。对外分享时把用户、订单、会话及分组统一替换为一致的别名，保留匹配关系。

项目	记录内容
入口	个人列表/个人单会话/网站客服/网站管理员/商户控制台
环境与版本	API 和 Widget origin、环境名称、Loader/runtime 版本、检查时间
身份与授权	后端解析分支、Token 类型（非原值）、scope/group_tags/conversation_ids/constraints/mode/supervise/manage
样本与路由	可见与缺失 ID 别名、会话类型、用户别名、用户默认组、路由是否存在、会话组覆盖、实际匹配结果
请求与显示	脱敏路径、状态码、request_id、筛选、分页、接口是否返回目标 ID、界面是否显示
结论	已确认根因/待验证假设、依据文件位置、最小修复与回滚、生产操作是否获批
验收	实际执行的测试及环境、未执行项、其他用户/分组/商户不可访问的负面测试

完成标准： 正确端拿到正确凭证，授权范围内的目标会话能出现并正确通信，越权样本被拒绝。仅健康检查通过、HTTP 200、mock 成功或刷新后按钮消失，都不等于实际业务验收完成。