OpenAI ChatKit 示例

此仓库收集了基于场景的 ChatKit 演示。每个示例都由一个 FastAPI 后端和一个 Vite + React 前端组成，使用 ChatKit Python SDK 实现自定义后端，并将其与 ChatKit.js 客户端集成。

您可以运行以下示例：

• 猫咖啡馆 - 一位虚拟猫咪的照护者，帮助提升猫咪的能量、快乐度和清洁度等状态。
• 客户支持 – 一家航空公司的礼宾服务，提供实时行程数据、时间线同步以及领域特定工具。
• 新闻指南 – Foxhollow Dispatch 新闻编辑部助手，具备文章搜索、@提及功能及页面感知响应能力。
• 地铁地图 – 一款基于聊天的地铁规划工具，采用 React Flow 构建线路与站点网络。

快速入门

1. 导出 OPENAI_API_KEY。
2. 确保已安装 uv。
3. 从仓库根目录启动示例，或在项目目录下使用 npm run start：

示例	仓库根目录命令	项目目录命令	URL
猫咖啡馆	npm run cat-lounge	cd examples/cat-lounge && npm install && npm run start	http://localhost:5170
客户支持	npm run customer-support	cd examples/customer-support && npm install && npm start	http://localhost:5171
新闻指南	npm run news-guide	cd examples/news-guide && npm install && npm run start	http://localhost:5172
地铁地图	npm run metro-map	cd examples/metro-map && npm install && npm run start	http://localhost:5173

功能索引

服务器工具调用以获取应用数据用于推理

• 猫咖啡馆：
  • 函数工具 get_cat_status（cat_agent.py）会为代理拉取最新的猫咪状态数据。
• 新闻指南：
  • 代理在回复前会依赖一系列检索工具——list_available_tags_and_keywords、get_article_by_id、search_articles_by_tags/keywords/exact_text 和 get_current_page——并使用 show_article_list_widget 来展示结果（news_agent.py）。
  • 隐藏上下文，如特色首页，会被规范化为代理输入，以确保摘要和建议始终基于准确信息（news_agent.py）。
• 地铁地图：
  • 地铁代理通过 get_map 同步地图数据，并利用 list_lines、list_stations、get_line_route 和 get_station 展示线路和站点详情，然后再给出路线指引（metro_map_agent.py）。
  • show_line_selector 使用小部件向用户呈现多选题。
  • 路线规划回复会将建议路径中各站点的实体来源作为标注附上。
• 客户支持：
  • 礼宾服务会在每次对话开始前附加一个 <CUSTOMER_PROFILE> 快照（行程、会员等级、近期时间线），并暴露更改座位、取消行程、增加行李、选择餐食、显示航班选项以及针对每条线程的 AirlineStateManager 状态请求协助等工具（server.py、support_agent.py、airline_state.py）。

客户端工具调用，用于改变或获取 UI 状态

• 地铁地图：
  • 客户端工具 get_selected_stations 会从画布中拉取当前选中的节点，以便代理能够在响应中使用客户端状态（ChatKitPanel.tsx、metro_map_agent.py）。

即时执行的客户端效果

• 猫咖啡馆：
  • 客户端效果 update_cat_status 和 cat_say 由服务器工具调用，用于同步 UI 状态并显示气泡对话框；这些效果通过 ChatKitPanel.tsx 中的 onEffect 处理。
• 地铁地图：
  • 客户端效果 location_select_mode 在选择线路后由服务器动作处理器流式传输（server.py），并更新地铁地图画布（ChatKitPanel.tsx）。
  • 客户端效果 add_station 则由代理在地图更新后流式传输，以立即同步画布并聚焦新创建的站点（metro_map_agent.py、ChatKitPanel.tsx）。
• 客户支持：
  • 服务器会在工具或小部件操作后流式传输 customer_profile/update 效果，使侧边栏始终反映最新的行程、会员等级和时间线数据（support_agent.py、server.py）。

页面感知的模型响应

• 新闻指南：
  • ChatKit 客户端会在 article-id 头部中传递当前打开的文章 ID，以便后端可以将响应限定在“当前页面”范围内（ChatKitPanel.tsx）。
  • 服务器会读取该请求上下文，并暴露 get_current_page 工具，使代理无需用户粘贴内容即可加载完整内容（main.py、news_agent.py）。

进度更新

• 新闻指南：
  • 检索工具在搜索标签、作者、关键词、精确文本或加载当前页面时会流式传输 ProgressUpdateEvent 消息，从而让 UI 显示“正在搜索…”或“正在加载…”的状态（news_agent.py）。
  • 事件查找代理在扫描日期、星期几或关键词时也会发出进度通知，以在较长时间的查询过程中保持用户知情（event_finder_agent.py）。
• 地铁地图：
  • 地铁代理在调用 get_map 获取地图信息时会发出进度更新；同时，在等待客户端工具调用 get_selected_stations 完成时也会发出进度更新（metro_map_agent.py）。

回复生命周期中的 UI 状态

• 地铁地图：
  • 客户端会在回复开始时锁定地图交互，并在流式传输结束时解锁，以防止在代理更新期间画布状态发生偏移，方法是添加 onResponseStart 和 onResponseEnd 处理程序（ChatKitPanel.tsx）。

不含操作的组件

• 猫咪休息室：
  • 服务器工具 show_cat_profile 流式传输一个在 profile_card_widget.py 中定义的展示组件。

含有操作的组件

• 猫咪休息室：
  • 服务器工具 suggest_cat_names 流式传输一个带有操作配置的组件，这些配置指定了由客户端处理的 cats.select_name 和 cats.more_names 操作。
  • 当用户点击该组件时，这些操作会在 ChatKitPanel.tsx 中的 handleWidgetAction 回调函数中被处理。
• 客户支持：
  • 航班和餐食组件会携带操作负载（flight.select、support.set_meal_preference）进行流式传输，以便在预订前捕获用户的选择，这些组件基于 .widget 模板构建而成（flight_options.py、meal_preferences.py、support_agent.py）。
• 新闻指南：
  • 文章列表组件会渲染“查看”按钮，这些按钮会分发 open_article 操作，用于客户端导航和互动（news_agent.py、article_list_widget.py）。
  • 事件查找器会流式传输一个包含时间线的组件，其中的“查看事件详情”按钮配置为由服务器端处理，以便用户可以内联展开条目（event_finder_agent.py、event_list_widget.py）。
• 地铁地图：
  • 服务器工具 show_line_selector 流式传输一个带有 line.select 操作的组件，该操作在点击列表项时触发（metro_map_agent.py、line_select_widget.py）。

由服务器端处理的组件操作

• 猫咪休息室：
  • cats.select_name 操作同样由服务器端处理，以反映数据更新，并在 server.py 中流式传输更新后的名称建议组件。
  • 该操作通过 ChatKitPanel.tsx 中的 handleWidgetAction 回调函数使用 chatkit.sendAction() 调用。
• 客户支持：
  • 操作处理器会持久化预订、餐食、追加销售和重新预订信息；锁定组件；记录隐藏上下文；并在用户点击 flight.select、support.set_meal_preference、booking.*、upsell.* 或 rebook.select_option 时刷新个人资料（server.py）。
• 新闻指南：
  • view_event_details 操作在服务器端处理，以更新时间线组件中的扩展描述，而无需往返模型（server.py）。
• 地铁地图：
  • line.select 操作由服务器端处理，用于流式传输更新后的组件，向对话中添加一个 <LINE_SELECTED> 的隐藏上下文条目，流式传输助手消息以询问用户是否要在该线路的起点或终点添加车站，并触发客户端的 location_select_mode 效果以同步 UI（server.py）。

附件

• 客户支持：
  • 端到端的图片附件：后端会提供上传/下载 URL，强制执行图片/大小限制，并将上传的文件转换为数据 URL 供模型使用（attachment_store.py、main.py、thread_item_converter.py）。React 面板会注册 attachments.create 操作，通过签名的 URL 进行上传，并在旅客分享灵感照片时将附件放入编辑器中（CustomerContextPanel.tsx）。

口述转文字（语音转文本）

• 客户支持：
  • 聊天编辑器支持内置的口述功能（点击麦克风按钮即可说话）。该功能在客户端通过 composer.dictation 启用（ChatKitPanel.tsx），并在服务器端通过实现 ChatKitServer.transcribe() 来处理（server.py）。

注释

• 地铁地图：
  • plan_route 工具会将计划路线中的每个车站作为实体来源呈现在助手消息中。这些车站既以内联注释的形式出现在助手消息中，也出现在来源列表中。
  • 客户端的实体点击处理器会将 React Flow 画布平移到被点击的车站位置（ChatKitPanel.tsx、metro_map_agent.py）。

对话标题

• 猫咪休息室：
  • 在用户为猫命名后，set_cat_name 工具会锁定该名称，并将对话标题更新为 {name}’s Lounge，然后保存（cat_agent.py）。
• 客户支持：
  • 一个轻量级的标题代理会在第一条用户消息时为对话命名，且不会延迟首次回复（title_agent.py、server.py）。
• 新闻指南：
  • title_agent 会在第一条用户消息时运行，以在没有标题的情况下生成一个简短的、适合新闻编辑部的标题（server.py、title_agent.py）。
• 地铁地图：
  • 地铁服务器使用专门的 title_agent 来在第一次交互时设置一个简短的地铁规划标题，并将其持久化到对话元数据中（server.py、title_agent.py）。

实体标签（@提及）

• 新闻指南：
  • 实体搜索和预览功能支持在消息编辑器中对文章/作者进行@提及（输入@或点击@按钮），并通过/articles/tags接口渲染悬停预览（ChatKitPanel.tsx, main.py）。
  • 被标记的实体会被转换为模型可读的标记，以便智能体能够获取正确的记录（<ARTICLE_REFERENCE> / <AUTHOR_REFERENCE>）（thread_item_converter.py）。
  • 在智能体引用具体内容之前，文章引用标签会通过指定的get_article_by_id工具解析为完整文章（news_agent.py）。
• 地铁地图：
  • 消息编辑器中的实体搜索会列出所有车站，用户可以通过@提及它们（输入@或点击@按钮）；点击标签还会将画布上的对应车站置为焦点（ChatKitPanel.tsx）。
  • 被标记的车站会被转换为包含完整线路元数据的<STATION_TAG>块，这样智能体无需再次查找即可作答（thread_item_converter.py, server.py）。

工具选择（编辑器菜单）

• 新闻指南：
  • ChatKit客户端配置了composer.tools选项，用于指定编辑器菜单中的可用工具（ChatKitPanel.tsx）。
  • 编辑器中的工具按钮允许用户强制指定特定的智能体（event_finder、puzzle），并在请求中设置tool_choice（config.ts）。
  • 后端会根据这些工具选择将请求路由到相应的专用智能体，若无法处理则回退到新闻指南智能体（server.py）。

自定义页眉操作

• 地铁地图：
  • 聊天页眉右侧提供了一个图标切换按钮（dark-mode / light-mode），用于在客户端层面切换应用的主题颜色（ChatKitPanel.tsx）。

图像生成

• 猫咪休息室：
  • cat_agent包含一个配置了3张部分图像的ImageGenerationTool。
  • 猫咪休息室服务器的respond方法在调用stream_agent_response时传入了ResponseStreamConverter(partial_images=3)，以便助手在流式传输每一张部分图像时正确计算图像生成进度。

OpenAI ChatKit 高级示例快速上手指南

本指南帮助中国开发者快速运行 openai-chatkit-advanced-samples 仓库中的场景化演示。这些示例展示了如何结合 FastAPI 后端与 Vite + React 前端，利用 ChatKit Python SDK 和 ChatKit.js 客户端构建智能应用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 WSL2)。
• Node.js：已安装 Node.js (建议 v18+) 和 npm。
• Python 工具链：必须安装 uv (高性能 Python 包安装器和项目管理器)。
  • 安装命令 (macOS/Linux): curl -LsSf https://astral.sh/uv/install.sh | sh
  • 安装命令 (Windows): powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
• API 密钥：拥有有效的 OPENAI_API_KEY。
• 网络环境：由于需要访问 OpenAI API 及部分 npm 源，建议配置好网络代理或使用国内镜像加速。
  • npm 加速: npm config set registry https://registry.npmmirror.com

安装步骤

您可以选择从仓库根目录一键启动，或进入特定示例目录单独运行。

1. 获取代码

git clone https://github.com/openai/openai-chatkit-advanced-samples.git
cd openai-chatkit-advanced-samples

2. 配置环境变量

导出您的 OpenAI API 密钥：

export OPENAI_API_KEY="sk-..."
# Windows PowerShell: $env:OPENAI_API_KEY="sk-..."
# Windows CMD: set OPENAI_API_KEY=sk-...

3. 运行示例

推荐使用仓库根目录的快捷命令启动（会自动处理依赖安装）：

示例名称	描述	启动命令 (根目录)	访问地址
Cat Lounge	虚拟宠物养成 (状态管理、UI 同步)	npm run cat-lounge	http://localhost:5170
Customer Support	航空客服 (行程数据、工具调用、附件)	npm run customer-support	http://localhost:5171
News Guide	新闻助手 (文章检索、页面感知、进度流)	npm run news-guide	http://localhost:5172
Metro Map	地铁规划 (React Flow 交互、地图实体标注)	npm run metro-map	http://localhost:5173

备选方案：若需单独进入某示例目录操作，可执行： cd examples/<示例名称> && npm install && npm run start

基本使用

以 Cat Lounge (虚拟宠物) 为例，展示最基础的使用流程：

1. 启动服务： 在项目根目录执行：

   npm run cat-lounge
   

   等待终端显示 Local: http://localhost:5170 且后端初始化完成。

2. 访问界面： 打开浏览器访问 http://localhost:5170。

3. 交互体验：

   • 查看状态：系统会自动调用后端工具 get_cat_status 获取猫咪当前的能量、快乐值和清洁度。
   • 命名互动：输入对话让猫咪起名，后端将流式传输一个包含操作按钮的 Widget (suggest_cat_names)。
   • 触发效果：点击 Widget 中的名字选项，前端通过 handleWidgetAction 回调触发 cats.select_name 动作，后端更新数据并同步 UI 状态（如弹出气泡对话 cat_say）。

核心特性观察点：

• Server Tool Calls: 观察后端如何自动拉取应用数据（如猫咪状态）作为推理上下文。
• Client Effects: 注意 UI 如何响应后端的 update_cat_status 指令实时更新进度条或状态图标。
• Widgets: 体验带有交互按钮的富文本回复，而非纯文本。

其他示例（如 Metro Map 的地图连线、News Guide 的文章检索）遵循类似的交互逻辑，但侧重于不同的 ChatKit 能力（如实体标注、分页感知、复杂工作流）。