为 Botpress ADK bot…

适用于 React 前端连接 Botpress ADK bot，需要处理认证、客户端管理、类型同步和调用 bot action 的场景。

适用场景

解决思路

1. 认证策略：在 Botpress Cloud 生成 PAT；前端用 cookie 存 PAT，不用 localStorage；实现 setCookie(name, value, days = 365)、getCookie(name)、deleteCookie(name)。
2. 用 React Context API 实现 AuthContext/AuthProvider，暴露 token、isAuthenticated、userProfile、isLoadingProfile、login(token)、logout()。
3. OAuth 流程：重定向到 https://app.botpress.cloud/cli-login?redirect=...；回调路由为 /auth/callback?pat=bp_pat_...；从查询参数取 PAT 写入 cookie，然后导航到应用。
4. 用 TanStack Router 做路由保护，未认证时重定向或拦截受保护路由。
5. 从 Botpress API 和 bot tables 获取 userProfile，并维护 isLoadingProfile 状态。
6. 处理 token 过期：检测 401 时清理认证状态并重新登录，必要时实现 reload retry logic。
7. 创建 stores/clientsStore.ts，用 Zustand 保存 APIClients 映射以缓存客户端。
8. 实现 getAPIClient(props)：有 botId 时 key 为 `${workspaceId}-${botId}`，否则 key 为 workspaceId 或 DEFAULT_API_CLIENT_KEY；命中缓存直接返回。
9. 未命中缓存时执行 new APIClient({ apiUrl: API_BASE_URL, workspaceId: props?.workspaceId, token: getPat() ?? '', botId: props?.botId })，并写回 Zustand store。
10. 导出 getApiClient(props?) = useClientsStore.getState().getAPIClient(props)，组件和服务统一通过它获取客户端。
11. 区分 workspace-scoped 与 bot-scoped 客户端；不需要 bot 操作时使用 workspace-scoped 客户端。
12. AI 操作使用 getZaiClient() 并配置扩展 timeout；不要用普通 client 调 Zai 操作。
13. 运行 adk dev/build 生成 .adk/ 目录类型：action-types.d.ts、table-types.d.ts、workflow-types.d.ts。
14. 在 types/index.ts 顶部用 triple-slash reference 指向 ../../../bot/.adk/action-types.d.ts 和 ../../../bot/.adk/table-types.d.ts。
15. 从 @botpress/runtime/_types/actions 导入 BotActionDefinitions，从 @botpress/runtime/_types/tables 导入 TableDefinitions。
16. 为生成类型创建 type aliases，例如 SendMessageAction = BotActionDefinitions['sendMessage']，TicketTableRow = TableDefinitions['TicketsTable']['Output']。
17. 保持类型同步：运行 adk dev；bot 变更后重启 adk dev、删除 .adk/ 重建、重启 TypeScript server、检查 bot 编译错误。
18. 在 services/bot-service.ts 建 service layer，封装 action 调用。
19. service 函数内用 getApiClient({ botId, workspaceId }) 获取客户端，调用 client.callAction({ type: 'sendMessage', input })，返回 result.output as SendMessageAction['output']。
20. 组件中不要直接调用 client.callAction，统一调用 service 函数。
21. 用 React Query useMutation 包装 service 函数，读取 mutate、isPending 等 loading/error 状态。
22. onSuccess 时 toast 成功并执行 queryClient.invalidateQueries({ queryKey: ['messages'] }) 刷新缓存。
23. onError 时 toast 错误并做错误处理。
24. 需要即时 UI 反馈时实现 optimistic updates。
25. 串联多个 action 时区分 sequential 与 parallel；独立 action 并行执行以提升性能。
26. 认证问题参考 authentication.md，按认证策略、AuthProvider 实现、OAuth 流程、路由保护、安全最佳实践来回答。
27. 客户端问题参考 botpress-client.md，展示 clientsStore.ts、客户端缓存、getApiClient()、workspace vs bot-scoped、getZaiClient()。
28. 类型问题参考 type-generation.md，解释 ADK 生成类型、triple-slash reference、导入生成类型、type aliases、自动同步。
29. 调用 action 问题参考 calling-actions.md，展示 callAction() 语法、类型安全 service、useMutation、错误处理、optimistic updates。
30. 回答时先给 1-2 段简洁解释，再给可运行代码示例。
31. 回答时包含文件引用，如 authentication.md:60-85。
32. 回答时强调安全考虑，并给出常见坑及避免方式。
33. 回答时链接相关主题，如路由保护 authentication.md:369-467、profile 获取 authentication.md:304-347、客户端初始化 botpress-client.md:29-51。
34. 安全最佳实践：生产环境用 HTTPS；cookie 用 SameSite=Lax 防 CSRF；SSR 尽量用 HttpOnly cookie；绝不记录 PAT/token；处理 token 过期。
35. 类型安全最佳实践：始终用 ADK 生成类型；创建 type aliases；正确使用 triple-slash reference；与 adk dev 同步；标注所有 action 输入输出。
36. 性能最佳实践：用 Zustand 缓存客户端；无需 bot 操作时用 workspace-scoped 客户端；用 optimistic updates；用 React Query 管理缓存；并行运行独立 action。
37. 错误处理最佳实践：始终处理 401 过期 token；给用户错误反馈；对临时失败实现 retry logic；日志中绝不记录 token；显示 loading 状态。
38. 代码组织最佳实践：action 调用走 service layer；类型集中到一个文件；认证逻辑放 context；客户端配置与使用分离；service 函数跨组件复用。
39. 排障 Cannot find module '@botpress/runtime/_types/actions'：检查 triple-slash 路径、确认 .adk/ 存在、重启 TypeScript server、确保 adk dev/build 已运行。
40. 排障 Types not updating after bot changes：重启 adk dev、删除 .adk/ 并重建、重启 TypeScript server、检查 bot 编译错误。
41. 排障 Authentication fails after reload：实现 reload retry logic、检查 cookie 过期、验证 token 读取、检查 CORS。
42. 排障 Client timeout on long operations：改用 getZaiClient() 并扩展 timeout、不要用普通 client 做 Zai 操作、考虑拆成更小操作。
43. 文档导航：references/authentication.md、botpress-client.md、calling-actions.md、type-generation.md、overview.md、project-setup.md、recommended-stack.md、service-layer.md、data-fetching.md、state-management.md、realtime-updates.md。
44. 项目设置：按 project-setup.md 用 Vite + React 脚手架、配置 TypeScript、设置环境变量；推荐技术栈参考 recommended-stack.md。
45. 数据与状态：按 service-layer.md 用服务层包装 API 调用并标注类型；按 data-fetching.md 用 TanStack Query mutations/optimistic updates；按 state-management.md 区分 Zustand 与 TanStack Query；按 realtime-updates.md 使用 polling strategies、interval tiers 和性能考虑。
46. 关键原则：始终提供 production-ready patterns，强调类型安全、安全和可维护性。

适用边界 · 注意事项

• 不适用于未使用 Botpress ADK 的通用前端或非 Botpress bot 集成。
• 没有 Botpress Cloud PAT/OAuth、无法生成 ADK 类型或不能安装 @botpress/client 时。
• 纯后端或完全不涉及前端调用 bot action/表数据的场景。