polpo-react

Polpo React

使用 @polpo-ai/react 管理运行时状态并使用钩子。使用 @polpo-ai/chat 构建可组合的 UI。 应用路由和业务侧客户端工具执行由使用方应用负责。

安装

npm install @polpo-ai/chat @polpo-ai/sdk @polpo-ai/react \
  react-virtuoso lucide-react streamdown

也可以使用 npx @polpo-ai/ui add 添加源组件。创建新应用时，请使用 npx create-polpo-app。

Provider

import { PolpoProvider } from "@polpo-ai/react";

<PolpoProvider baseUrl={process.env.NEXT_PUBLIC_POLPO_URL!} autoConnect={false}>
  {children}
</PolpoProvider>

baseUrl 是项目根路径；不要追加 /v1 或 /api/v1。不要在浏览器 bundle 中暴露特权 服务端 API 密钥。若凭证必须保留在服务端，请使用应用经过身份验证的后端／代理。

聊天选择

普通聊天请使用高级组件：

<Chat agent="support" sessionId={sessionId} />

如果产品需要可靠的消息传递、自定义交互、显式客户端工具、Loop 续接，或自行组合消息， 请直接使用 useChat。

UI 不变量

• 将 Polpo 的 Session 历史视为规范数据源；重连或客户端工具续接后，不要重复添加乐观消息。
• 将 reconnecting 与 streaming 分开显示，不要将已脱离连接的持久化运行标记为失败。
• 只有在根据本地处理器验证客户端工具的名称和参数后，才渲染该工具。
• 使用稳定的幂等键和当前 Session 版本继续传递工具结果。
• 建议属于生成它们的助手消息；只有当该消息仍是最新消息时，建议才可执行。
• 附件使用带类型的内容部分和经过身份验证的文件 URL 解析；绝不要在浏览器可见的消息中放入本地文件系统路径。

参考资料

• references/runtime-chat.md：现代 useChat、持久性、交互、技能和续接。
• references/components.md：组件属性。
• references/patterns.md：当前组合模式。
• references/cli.md：UI 脚手架命令。
• references/theming.md：令牌、深色模式、字体和 Tailwind。
• references/contract-version.md：已验证的软件包版本。