AI 接入提示词

把下面的提示词复制给能够读取项目文件、查阅网页并运行测试的 AI 编程助手，让它在你的项目中完成 Open4X 接入。每个代码块右上角都有复制按钮。

使用方法

1. 在 AI 编程工具中打开你的项目。已有网站直接打开原项目，不必新建项目。
2. 选择一套开发提示词，补全方括号中的资料；不确定的内容写“待确认”。
3. 让 AI 先检查项目和官方文档，再实现、测试并交付。最后使用验收提示词复查。

API Key、Bot Token、Webhook Secret 和密码不要填入提示词。使用部署平台 Secrets 或不提交到仓库的服务端环境变量。用 AI 帮你写代码，不需要启用或购买 Open4X AI Model Gateway。

交付边界

提示词不是自动开通服务，也不保证一次生成即可上线。账户、权限、额度、域名、Provider 授权和生产发布需要实际配置及确认。AI 无法读取文档时，应请求不含密钥的官方文档，不要猜接口。

已接入：按端检查与排障

已有聊天接入但表现不对？先使用 Widget 分端检查与排障：个人端、网站客服端、商户管理员与控制台、空白与来源问题。这些检查模板明确区分凭证、分组路由和界面问题，不需要重新搭建整套接入。

模板一：通用服务接入

适合 AI Gateway、Bot、Webhook Push 等服务，也可用于先评估接入范围。

请作为本项目的集成工程师，将 Open4X 接入现有项目，完成代码和测试，不只是提供方案。

项目资料：
- 项目/业务名称：[填写]
- 需要的服务和场景：[例如 AI 问答、Telegram 通知、Webhook 推送]
- 前端、后端、部署平台：[填写或从项目识别]
- 验证环境：[本地 / 已授权 staging；待确认时只做 mock]
- 必须完成的流程：[填写]
- 不包含的功能：[填写]
- 测试费用和外部副作用授权：[默认不允许真实付费调用或发送消息]

先检查项目结构、鉴权、配置、测试和部署约定，保留已有改动，复用现有代码。
查阅以下官方资料，并继续阅读所选服务的文档：
https://docs.open4x.com/zh/guide/customer-integrations
https://docs.open4x.com/zh/guide/api-reference
https://docs.open4x.com/openapi/open4x.openapi.json
https://docs.open4x.com/zh/guide/connected-accounts
https://docs.open4x.com/zh/guide/pricing-billing
https://docs.open4x.com/zh/guide/security-operations

要求：
1. 列出实际使用的接口、鉴权、Scope、Service Alias、请求/响应字段和限制，标注文档地址、读取日期及规范版本（若存在）。冲突或无法读取的内容列为阻塞项，不编造接口、SDK、npm 包或价格。
2. https://api.open4x.com 是生产 API，不是默认测试地址。staging 的 URL、租户和 Key 必须来自同一交付包。缺少配置时只实现 mock，不自动切换生产。
3. 密钥只存在服务端；不读取或打印已有秘密值，不要求用户在聊天中提供秘密。只生成占位配置，说明部署平台 Secrets 配置位置。使用最小权限，不用全权限 Key 绕过 403。
4. 商户系统负责用户、订单、业务权限和资金操作。前端通过受保护的商户后端调用；服务商凭据使用 Connected Accounts 管理。
5. 按具体接口合同处理幂等、超时、重试、限流和异步结果，不能假定所有写接口都支持幂等。未知结果的写请求不能盲目重试。保留 request_id，日志脱敏。
6. 实现加载、成功、失败、超时、额度不足及降级。Open4X 故障不能阻断原有登录、订单和支付。
7. 完成最小闭环，不做无关重构。数据库变更需解释必要性并提供迁移和回滚，不承诺所有接入都无需数据库。
8. 运行本地自动化测试。真实 Provider 测试需明确授权、测试资源和费用上限；生产部署另行确认。

交付实际代码、配置说明、调用示例、测试结果、使用说明、回滚步骤和已完成/待配置/未验证清单。区分 mock、staging 实测和生产实测。现在开始检查项目，只询问真正阻塞实现的信息。

模板二：网站在线客服

默认目标是“已登录用户 → 网站 Widget → Open4X 工作台人工回复”，不包含 Telegram、AI 或工单同步。扩展功能应明确提出，单独验收。

请在当前项目中实现 Open4X 在线客服，完成代码、测试和商户交付说明。

项目资料：
- 网站名称和域名：[填写]
- 技术栈、部署平台：[填写或从仓库识别]
- 用户登录方式：[填写或从代码识别]
- 会话场景：[普通客服 / 订单咨询 / 买家与作者咨询]
- 客服工作台：[默认 Open4X 托管工作台]
- 环境：[本地或已授权 staging；待确认时使用 mock]
- 故障回退：[现有工单页或客服联系方式]

检查项目，核对以下官方文档及其中引用的接口/SDK 协议：
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
https://docs.open4x.com/zh/guide/support-integration
https://docs.open4x.com/zh/guide/conversation-hub
https://docs.open4x.com/zh/guide/conversation-administration
https://docs.open4x.com/openapi/open4x.openapi.json

以当前 Conversation Hub 合同为准，不混用旧版 Bot Session API。列出实际接口和字段，记录文档版本及读取日期。文档冲突、版本缺失或 SDK 无法取得时说明阻塞项，不猜包名和初始化/销毁方法。

实现要求：
1. 在商户后端实现受保护的 POST /api/open4x/session，这是商户自己的路由。从真实登录 Session 获取身份，实施 CSRF/Origin 校验和限流，不信任浏览器提交的用户 ID、角色或收件人。
2. Bridge Key 只在服务端，基本 Scope 为 conversation:read 和 conversation:write，可在 Console 的 API Keys 页面创建。仅管理事件 Webhook/重放时额外需要 conversation:events:write。禁止把 Bridge Key 或 conversation:supervise 权限给浏览器。
3. 按文档调用 POST /v1/conversations 创建或复用会话，使用稳定 external_conversation_id。匹配返回的活动参与者 ID 和角色；缺失、重复或不活动时拒绝签发，不能回退广播。
4. 按文档调用 POST /v1/conversations/{id}/widget-session。服务端固定 participant_id 和 recipient_participant_ids；TTL 在允许的 900–3600 秒内，默认 1800 秒。只向当前用户返回必要短期 token 和有效期，响应 no-store，不记录 token 或放入共享缓存。
5. 根据已确认版本的 Loader/SDK 挂载 Widget，提供加载、失败和回退状态。按官方协议处理过期、重新鉴权、退出和切换账户，不能假定存在刷新 API。没有发布版 SDK 时，使用文档确认的方式或列为待交付。
6. 生产地址为 https://api.open4x.com、https://widget.open4x.com 和 https://console.open4x.com，不是 staging Key 的默认配套地址。必须完整匹配环境，不使用 workers.dev 代替交付域名。
7. 正确配置 HTTPS、CSP、CORS，不通过公开 Key、关闭安全检查或放开全部来源解决跨域。只生成无秘密的配置示例和服务端 Secrets 说明。
8. 客服在 https://console.open4x.com/dashboard/conversations 加入会话并向指定客户公开回复。内部备注不得出现在用户端。订单咨询先做订单访问授权；多方会话明确每条消息的收件人，不能默认参与者互相可见。
9. AI 默认关闭，不向模型发送数据，不自动启用 Telegram 或真实 Provider。故障时原有登录、支付、工单正常，并显示回退入口。
10. 最小聊天复用现有用户数据；需要映射、outbox、事件去重和对账时才引入持久化，不用进程内存代替可靠同步。仅按接口的实际幂等合同重试。

测试双向消息、刷新恢复、断线恢复、两用户隔离、内部备注隔离、过期/退出/切换账户、故障回退和关闭 AI 的完整流程。Mock 不是线上验收；真实发送及生产发布需单独授权。

交付实际修改、配置清单、客服操作步骤、测试证据和阻塞项。不索要明文 Key，不打印 token，不宣称未执行的测试通过。现在从检查项目开始。

模板三：接入验收

开发完成后复制使用。此模板不授权真实发送、付费调用或生产部署。

请独立审查当前项目的 Open4X 接入，不根据此前完成声明直接判定通过。

检查实际代码、配置示例和测试，核对：
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
https://docs.open4x.com/zh/guide/security-operations
https://docs.open4x.com/openapi/open4x.openapi.json

重点检查服务端密钥、租户/用户隔离、业务授权、收件人控制、内部备注、会话/token 生命周期、环境匹配、幂等重试和故障降级。涉及 Webhook 时检查原始请求体签名验证、时间窗口、持久化去重和补偿；未接入模块标记不适用。

运行本地可执行测试。真实 Provider、外发消息、计费和生产部署另行授权。只检查秘密的配置状态，不输出值。无法验证的接口/SDK 行为标记未验证。

按严重程度输出问题并附文件位置，列实际测试、mock/staging/生产环境区分、未执行项及原因。结论使用“可继续联调 / 阻塞联调 / 可申请生产验收”。不把健康检查或 HTTP 200 当业务验收，不自行宣称 SLA、价格或合规条款已冻结。

商户还需准备什么

商户确认	AI 协助实现
租户、环境、Key 安全配置、实际额度及费用上限	服务端接入、配置示例、错误处理及测试
用户/订单/作者权限、客服负责人	复用鉴权、明确收件人、最小权限
正式域名、Provider 授权、回调入口	协议实现、部署说明、受控联调脚本
真实验收和生产发布批准	验收记录、未完成项、回滚步骤

提示词不代替价格、数据保留、DPA 或 SLA 约定。交付前仍需完成商户入门验收和对应服务的专项测试。