polpo-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polpo UI

Composable React chat components for Polpo AI agents. Three composition levels, three installation methods.

用于Polpo AI Agent的可组合React聊天组件。三种组合层级，三种安装方式。

Install

安装

New project

新项目

bash

undefined

bash

undefined

Interactive

交互式

npx create-polpo-app

Non-interactive (CI / AI agents)

非交互式（CI / AI Agent）

npx create-polpo-app my-app -t chat -y npx create-polpo-app my-app -t chat-widget -y npx create-polpo-app my-app -t multi-agent -y

undefined

npx create-polpo-app my-app -t chat -y npx create-polpo-app my-app -t chat-widget -y npx create-polpo-app my-app -t multi-agent -y

undefined

Add to existing project (shadcn-style, copies source)

添加到现有项目（shadcn风格，复制源代码）

bash

undefined

bash

undefined

Interactive multi-select

交互式多选

npx @polpo-ai/ui add

Non-interactive

非交互式

npx @polpo-ai/ui add --all npx @polpo-ai/ui add tools hooks --overwrite

undefined

npx @polpo-ai/ui add --all npx @polpo-ai/ui add tools hooks --overwrite

undefined

npm package (compiled)

npm包（已编译）

bash

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

Consumer adds Tailwind scanning:

css

/* Tailwind v4 */
@source "../node_modules/@polpo-ai/chat/dist/**/*.js";

// Tailwind v3 — tailwind.config.js
content: ["./node_modules/@polpo-ai/chat/dist/**/*.js"]

bash

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

消费者需添加Tailwind扫描配置：

css

/* Tailwind v4 */
@source "../node_modules/@polpo-ai/chat/dist/**/*.js";

// Tailwind v3 — tailwind.config.js
content: ["./node_modules/@polpo-ai/chat/dist/**/*.js"]

Provider Setup

Provider配置

tsx

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

// baseUrl is root URL — SDK appends /v1/ internally. Do NOT add /v1/.
<PolpoProvider baseUrl="https://api.polpo.sh" apiKey={process.env.NEXT_PUBLIC_POLPO_API_KEY} autoConnect={false}>
  {children}
</PolpoProvider>

tsx

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

// baseUrl为根URL — SDK会在内部自动追加/v1/。请勿添加/v1/。
<PolpoProvider baseUrl="https://api.polpo.sh" apiKey={process.env.NEXT_PUBLIC_POLPO_API_KEY} autoConnect={false}>
  {children}
</PolpoProvider>

Composition Levels

组合层级

Level 1 — Zero Config

层级1 — 零配置

tsx

<Chat agent="coder" sessionId="session_abc" />

tsx

<Chat agent="coder" sessionId="session_abc" />

Level 2 — Compose (children replace default input)

层级2 — 自定义组合（子组件替换默认输入框）

tsx

<Chat agent="coder" avatar={<Avatar />}>
  <MyCustomInput />
</Chat>

tsx

<Chat agent="coder" avatar={<Avatar />}>
  <MyCustomInput />
</Chat>

Level 3 — Primitives

层级3 — 基础组件

tsx

import { ChatMessage, ChatSkeleton } from "@polpo-ai/chat";
import { useChat } from "@polpo-ai/react";

tsx

import { ChatMessage, ChatSkeleton } from "@polpo-ai/chat";
import { useChat } from "@polpo-ai/react";

Render Function Pattern

渲染函数模式

tsx

<Chat agent="coder" onSessionCreated={(id) => router.replace(`/chat/${id}`)}>
  {({ hasMessages }) => hasMessages ? <ChatInput /> : <LandingPage />}
</Chat>

tsx

<Chat agent="coder" onSessionCreated={(id) => router.replace(`/chat/${id}`)}>
  {({ hasMessages }) => hasMessages ? <ChatInput /> : <LandingPage />}
</Chat>

Session Navigation

会话导航

Package does NOT handle routing. Use

onSessionCreated

callback:

tsx

<Chat onSessionCreated={(id) => router.push(`/chat/${id}`)} />

本包不处理路由。请使用

onSessionCreated

回调：

tsx

<Chat onSessionCreated={(id) => router.push(`/chat/${id}`)} />

Components

组件列表

Component	Purpose
`Chat`	Root compound — Provider + Messages + Input
`ChatInput`	Textarea + submit + file attach + drag & drop
`ChatMessage`	Message dispatcher (user/assistant)
`ChatMessages`	Virtuoso list with auto-scroll
`ChatProvider`	Context wrapping useChat + useFiles
`ChatSessionList`	Flat session list with select/delete
`ChatSessionsByAgent`	Sessions grouped by agent
`ChatAgentSelector`	Agent picker dropdown
`ChatSuggestions`	Suggestion button grid
`ChatAskUser`	Ask-user-question wizard
`ChatLanding`	Landing + greeting + input + suggestions
`ChatScrollButton`	Scroll-to-bottom indicator
`ChatSkeleton`	Loading skeleton
`ChatTyping`	Typing dots
`ToolCallChip`	Auto-dispatching tool renderer
`ToolCallShell`	Base tool renderer with expand/collapse

组件	用途
`Chat`	根复合组件 — 包含Provider + 消息列表 + 输入框
`ChatInput`	文本域 + 提交按钮 + 文件上传 + 拖拽功能
`ChatMessage`	消息分发器（区分用户/助手消息）
`ChatMessages`	带自动滚动的Virtuoso列表
`ChatProvider`	包裹useChat + useFiles的上下文组件
`ChatSessionList`	支持选择/删除的扁平化会话列表
`ChatSessionsByAgent`	按Agent分组的会话列表
`ChatAgentSelector`	Agent选择下拉框
`ChatSuggestions`	建议按钮网格
`ChatAskUser`	引导用户提问的向导组件
`ChatLanding`	着陆页 + 问候语 + 输入框 + 建议
`ChatScrollButton`	滚动到底部的指示器
`ChatSkeleton`	加载骨架屏
`ChatTyping`	输入状态动画（打点效果）
`ToolCallChip`	自动分发的工具渲染器
`ToolCallShell`	支持展开/收起的基础工具渲染器

Hooks

tsx

const { messages, sendMessage, isStreaming, abort, uploadFile, pendingToolCall } = useChatContext();
const handleSubmit = useSubmitHandler(sendMessage, uploadFile);
const dragging = useDocumentDrag();

tsx

const { messages, sendMessage, isStreaming, abort, uploadFile, pendingToolCall } = useChatContext();
const handleSubmit = useSubmitHandler(sendMessage, uploadFile);
const dragging = useDocumentDrag();

References

参考资料

Component props: references/components.md — full props for every component
Composition patterns: references/patterns.md — app assembly, ask-user, sessions, custom tools
CLI commands: references/cli.md — create-polpo-app, @polpo-ai/ui, flags
Theming: references/theming.md — colors, dark mode, fonts, Tailwind config

组件属性: references/components.md — 所有组件的完整属性说明
组合模式: references/patterns.md — 应用组装、引导用户提问、会话管理、自定义工具
CLI命令: references/cli.md — create-polpo-app、@polpo-ai/ui及相关参数
主题配置: references/theming.md — 颜色、深色模式、字体、Tailwind配置