polpo-ui

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是根地址 — 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 — 自定义组合（children替换默认输入框）

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配置相关内容