[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-openai--openai-chatkit-advanced-samples":3,"tool-openai--openai-chatkit-advanced-samples":64},[4,17,27,35,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",151314,2,"2026-04-11T23:32:58",[13,14,15],"开发框架","Agent","语言模型","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":10,"last_commit_at":23,"category_tags":24,"status":16},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[25,14,26,13],"插件","图像",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":10,"last_commit_at":33,"category_tags":34,"status":16},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[25,13],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":41,"last_commit_at":42,"category_tags":43,"status":16},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,3,"2026-04-06T11:19:32",[15,26,14,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,15],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",85092,"2026-04-10T11:13:16",[26,60,61,25,14,62,15,13,63],"数据工具","视频","其他","音频",{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":80,"owner_location":80,"owner_email":80,"owner_twitter":80,"owner_website":81,"owner_url":82,"languages":80,"stars":83,"forks":84,"last_commit_at":85,"license":86,"difficulty_score":87,"env_os":88,"env_gpu":88,"env_ram":88,"env_deps":89,"category_tags":98,"github_topics":99,"view_count":10,"oss_zip_url":80,"oss_zip_packed_at":80,"status":16,"created_at":104,"updated_at":105,"faqs":106,"releases":137},6810,"openai\u002Fopenai-chatkit-advanced-samples","openai-chatkit-advanced-samples","Starter app to build with OpenAI ChatKit SDK","openai-chatkit-advanced-samples 是一套基于 OpenAI ChatKit SDK 构建的场景化示例合集，旨在帮助开发者快速上手并理解如何打造功能丰富的 AI 聊天应用。该项目通过四个生动的演示案例——虚拟宠物管家、航空客服助手、新闻编辑助理以及地铁路线规划器，展示了如何将 FastAPI 后端与 Vite + React 前端无缝结合，实现从数据检索到界面交互的完整闭环。\n\n它主要解决了开发者在集成 ChatKit 时面临的“如何落地具体业务场景”的难题，提供了涵盖服务器端工具调用（如获取实时状态、搜索文章、查询地图数据）和客户端状态同步（如读取画布选中节点）的成熟代码参考。无论是需要处理复杂领域知识，还是希望实现动态 UI 反馈，这些示例都给出了清晰的实现路径。\n\n这套资源特别适合具有一定开发经验的工程师和技术研究人员使用。其独特的技术亮点在于深入演示了 Agent 如何利用自定义工具链获取应用数据进行推理，以及如何通过“即发即弃”或双向通信机制灵活操控前端界面状态。通过直接运行这些预设项目，用户可以直观地学习如何构建具备上下文感知能力和实时交互能力的","openai-chatkit-advanced-samples 是一套基于 OpenAI ChatKit SDK 构建的场景化示例合集，旨在帮助开发者快速上手并理解如何打造功能丰富的 AI 聊天应用。该项目通过四个生动的演示案例——虚拟宠物管家、航空客服助手、新闻编辑助理以及地铁路线规划器，展示了如何将 FastAPI 后端与 Vite + React 前端无缝结合，实现从数据检索到界面交互的完整闭环。\n\n它主要解决了开发者在集成 ChatKit 时面临的“如何落地具体业务场景”的难题，提供了涵盖服务器端工具调用（如获取实时状态、搜索文章、查询地图数据）和客户端状态同步（如读取画布选中节点）的成熟代码参考。无论是需要处理复杂领域知识，还是希望实现动态 UI 反馈，这些示例都给出了清晰的实现路径。\n\n这套资源特别适合具有一定开发经验的工程师和技术研究人员使用。其独特的技术亮点在于深入演示了 Agent 如何利用自定义工具链获取应用数据进行推理，以及如何通过“即发即弃”或双向通信机制灵活操控前端界面状态。通过直接运行这些预设项目，用户可以直观地学习如何构建具备上下文感知能力和实时交互能力的下一代智能对话系统，从而大幅降低从零开发的门槛。","# OpenAI ChatKit Examples\n\nThis repository collects scenario-driven ChatKit demos. Each example pairs a FastAPI backend with a Vite + React frontend, implementing a custom backend using ChatKit Python SDK and wiring it up with ChatKit.js client-side.\n\nYou can run the following examples:\n\n- [**Cat Lounge**](examples\u002Fcat-lounge) - caretaker for a virtual cat that helps improve energy, happiness, and cleanliness stats.\n- [**Customer Support**](examples\u002Fcustomer-support) – airline concierge with live itinerary data, timeline syncing, and domain-specific tools.\n- [**News Guide**](examples\u002Fnews-guide) – Foxhollow Dispatch newsroom assistant with article search, @-mentions, and page-aware responses.\n- [**Metro Map**](examples\u002Fmetro-map) – chat-driven metro planner with a React Flow network of lines and stations.\n\n## Quickstart\n\n1. Export `OPENAI_API_KEY`.\n2. Make sure `uv` is installed.\n3. Launch an example from the repo root, or with `npm run start` from the project directory:\n\n| Example          | Command for repo root      | Command for project directory                              | URL                   |\n| ---------------- | -------------------------- | ---------------------------------------------------------- | --------------------- |\n| Cat Lounge       | `npm run cat-lounge`       | `cd examples\u002Fcat-lounge && npm install && npm run start`   | http:\u002F\u002Flocalhost:5170 |\n| Customer Support | `npm run customer-support` | `cd examples\u002Fcustomer-support && npm install && npm start` | http:\u002F\u002Flocalhost:5171 |\n| News Guide       | `npm run news-guide`       | `cd examples\u002Fnews-guide && npm install && npm run start`   | http:\u002F\u002Flocalhost:5172 |\n| Metro Map        | `npm run metro-map`        | `cd examples\u002Fmetro-map && npm install && npm run start`    | http:\u002F\u002Flocalhost:5173 |\n\n## Feature index\n\n### Server tool calls to retrieve application data for inference\n\n- **Cat Lounge**:\n  - Function tool `get_cat_status` ([cat_agent.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fcat_agent.py)) pulls the latest cat stats for the agent.\n- **News Guide**:\n  - The agent leans on a suite of retrieval tools—`list_available_tags_and_keywords`, `get_article_by_id`, `search_articles_by_tags\u002Fkeywords\u002Fexact_text`, and `get_current_page`—before responding, and uses `show_article_list_widget` to present results ([news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)).\n  - Hidden context such as the featured landing page is normalized into agent input so summaries and recommendations stay grounded ([news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)).\n- **Metro Map**:\n  - The metro agent syncs map data with `get_map` and surfaces line and station details via `list_lines`, `list_stations`, `get_line_route`, and `get_station` before giving directions ([metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)).\n  - `show_line_selector` presents the user a multiple-choice question using a widget.\n  - Route-planning replies attach entity sources for the stations in the suggested path as annotations.\n- **Customer Support**:\n  - The concierge prepends a `\u003CCUSTOMER_PROFILE>` snapshot (itinerary, loyalty, recent timeline) before each run and exposes tools to change seats, cancel trips, add bags, set meals, surface flight options, and request assistance against the per-thread `AirlineStateManager` state ([server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py), [support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py), [airline_state.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fairline_state.py)).\n\n### Client tool calls that mutate or fetch UI state\n\n- **Metro Map**:\n  - Client tool `get_selected_stations` pulls the currently selected nodes from the canvas so the agent can use client-side state in its response ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx), [metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)).\n\n### Fire-and-forget client effects\n\n- **Cat Lounge**:\n  - Client effects `update_cat_status` and `cat_say` are invoked by server tools to sync UI state and surface speech bubbles; handled via `onEffect` in [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx).\n- **Metro Map**:\n  - Client effect `location_select_mode` is streamed within the server action handler ([server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)) after a line is chosen and updates the metro map canvas ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n  - Client effect `add_station` is streamed by the agent after map updates to immediately sync the canvas and focus the newly created stop ([metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py), [ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n- **Customer Support**:\n  - The server streams `customer_profile\u002Fupdate` effects after tools or widget actions so the side panel mirrors the latest itinerary, loyalty, and timeline data ([support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py), [server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)).\n\n### Page-aware model responses\n\n- **News Guide**:\n  - The ChatKit client forwards the currently open article id in an `article-id` header so the backend can scope responses to “this page” ([ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n  - The server reads that request context and exposes `get_current_page` so the agent can load full content without asking the user to paste it ([main.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fmain.py), [news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)).\n\n### Progress updates\n\n- **News Guide**:\n  - Retrieval tools stream `ProgressUpdateEvent` messages while searching tags, authors, keywords, exact text, or loading the current page so the UI surfaces “Searching…”\u002F“Loading…” states ([news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)).\n  - The event finder emits progress as it scans dates, days of week, or keywords to keep users informed during longer lookups ([event_finder_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fevent_finder_agent.py)).\n- **Metro Map**:\n  - The metro agent emits a progress update while retrieving map information in `get_map`; it also emits a progress update while waiting for a client tool call to complete in `get_selected_stations` ([metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)).\n\n### Response lifecycle UI state\n\n- **Metro Map**:\n  - The client locks map interaction at response start and unlocks when the stream ends so canvas state doesn’t drift during agent updates by adding `onResponseStart` and `onResponseEnd` handlers ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n\n### Widgets without actions\n\n- **Cat Lounge**:\n  - Server tool `show_cat_profile` streams a presentation widget defined in [profile_card_widget.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fprofile_card_widget.py).\n\n### Widgets with actions\n\n- **Cat Lounge**:\n  - Server tool `suggest_cat_names` streams a widget with action configs that specify `cats.select_name` and `cats.more_names` client-handled actions.\n  - When the user clicks the widget, these actions are handled with the `handleWidgetAction` callback in [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx).\n- **Customer Support**:\n  - Flight and meal widgets stream with action payloads (`flight.select`, `support.set_meal_preference`) to capture choices before booking, built from `.widget` templates ([flight_options.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fflight_options.py), [meal_preferences.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fmeal_preferences.py), [support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py)).\n- **News Guide**:\n  - Article list widgets render “View” buttons that dispatch `open_article` actions for client navigation and engagement ([news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py), [article_list_widget.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fwidgets\u002Farticle_list_widget.py)).\n  - The event finder streams a timeline widget with `view_event_details` buttons configured for server handling so users can expand items inline ([event_finder_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fevent_finder_agent.py), [event_list_widget.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fwidgets\u002Fevent_list_widget.py)).\n- **Metro Map**:\n  - The server tool `show_line_selector` streams a widget with the `line.select` action configured to fire on list item click ([metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py), [line_select_widget.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fwidgets\u002Fline_select_widget.py)).\n\n### Server-handled widget actions\n\n- **Cat Lounge**:\n  - The `cats.select_name` action is also handled server-side to reflect updates to data and stream back an updated version of the name suggestions widget in [server.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fserver.py).\n  - It is invoked using `chatkit.sendAction()` from `handleWidgetAction` callback in [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx).\n- **Customer Support**:\n  - Action handlers persist bookings, meals, upsells, and rebooks; lock widgets; log hidden context; and refresh the profile when users click `flight.select`, `support.set_meal_preference`, `booking.*`, `upsell.*`, or `rebook.select_option` ([server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)).\n- **News Guide**:\n  - The `view_event_details` action is processed server-side to update the timeline widget with expanded descriptions without a round trip to the model ([server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py)).\n- **Metro Map**:\n  - The `line.select` action is handled server-side to stream an updated widget, add a `\u003CLINE_SELECTED>` hidden context item to thread, stream an assistant message to ask the user whether to add the station at the line’s start or end, and trigger the `location_select_mode` client effect for the UI to sync ([server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)).\n\n### Attachments\n\n- **Customer Support**:\n  - End-to-end image attachments: the backend issues upload\u002Fdownload URLs, enforces image\u002Fsize limits, and converts uploads to data URLs for the model ([attachment_store.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fattachment_store.py), [main.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fmain.py), [thread_item_converter.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fthread_item_converter.py)). The React panel registers `attachments.create`, uploads via the signed URL, and drops the attachment into the composer when travellers share inspiration photos ([CustomerContextPanel.tsx](examples\u002Fcustomer-support\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FCustomerContextPanel.tsx)).\n\n### Dictation (speech-to-text)\n\n- **Customer Support**:\n  - The chat composer supports built-in dictation (click the mic button to speak). It's enabled client-side via `composer.dictation` ([ChatKitPanel.tsx](examples\u002Fcustomer-support\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)) and handled server-side by implementing `ChatKitServer.transcribe()` ([server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)).\n\n### Annotations\n\n- **Metro Map**:\n  - The `plan_route` tool renders each station in a planned route as an entity source on the assistant message. The station is rendered as inline annotations in the assistant message and also in the sources list.\n  - The client’s entity click handler pans the React Flow canvas to the clicked station ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx), [metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)).\n\n### Thread titles\n\n- **Cat Lounge**:\n  - After the user names the cat, the `set_cat_name` tool locks in the name and updates the thread title to `{name}’s Lounge` before saving it ([cat_agent.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fcat_agent.py)).\n- **Customer Support**:\n  - A lightweight title agent names the conversation on the first user message without delaying the first reply ([title_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Ftitle_agent.py), [server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)).\n- **News Guide**:\n  - The `title_agent` runs on the first user message to generate a short newsroom-friendly title when none exists ([server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py), [title_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Ftitle_agent.py)).\n- **Metro Map**:\n  - The metro server uses a dedicated `title_agent` to set a brief metro-planning title on the first turn and persists it to thread metadata ([server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py), [title_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Ftitle_agent.py)).\n\n### Entity tags (@-mentions)\n\n- **News Guide**:\n  - Entity search and previews power @-mentions for articles\u002Fauthors in the composer (type `@` or click the `@` button) and render hover previews via `\u002Farticles\u002Ftags` ([ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx), [main.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fmain.py)).\n  - Tagged entities are converted into model-readable markers so the agent can fetch the right records (`\u003CARTICLE_REFERENCE>` \u002F `\u003CAUTHOR_REFERENCE>`) ([thread_item_converter.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fthread_item_converter.py)).\n  - Article reference tags are resolved into full articles via the instructed `get_article_by_id` tool before the agent cites details ([news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)).\n- **Metro Map**:\n  - The composer’s entity search lists stations so users can @-mention them (type `@` or click the `@` button); clicking a tag also focuses the station on the canvas ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n  - Tagged stations are converted into `\u003CSTATION_TAG>` blocks with full line metadata so the agent can answer without another lookup ([thread_item_converter.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fthread_item_converter.py), [server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)).\n\n### Tool choice (composer menu)\n\n- **News Guide**:\n  - The ChatKit client is configured with a `composer.tools` option that specifies options in the composer menu ([ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx))\n  - Composer tool buttons let users force specific agents (`event_finder`, `puzzle`), setting `tool_choice` on the request ([config.ts](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Flib\u002Fconfig.ts)).\n  - The backend routes these tool choices to specialized agents before falling back to the News Guide agent ([server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py)).\n\n### Custom header actions\n\n- **Metro Map**:\n  - The chat header uses a right-side icon toggle (`dark-mode` \u002F `light-mode`) to flip the app’s color scheme client-side ([ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)).\n\n### Image generation\n\n- **Cat Lounge**:\n  - The `cat_agent` includes an `ImageGenerationTool` configured with 3 partial images.\n  - The cat lounge server's `respond` method passes in `ResponseStreamConverter(partial_images=3)` when invoking `stream_agent_response` so that the helper correctly computes image generation progress when streaming each partial image.","# OpenAI ChatKit 示例\n\n此仓库收集了基于场景的 ChatKit 演示。每个示例都由一个 FastAPI 后端和一个 Vite + React 前端组成，使用 ChatKit Python SDK 实现自定义后端，并将其与 ChatKit.js 客户端集成。\n\n您可以运行以下示例：\n\n- [**猫咖啡馆**](examples\u002Fcat-lounge) - 一位虚拟猫咪的照护者，帮助提升猫咪的能量、快乐度和清洁度等状态。\n- [**客户支持**](examples\u002Fcustomer-support) – 一家航空公司的礼宾服务，提供实时行程数据、时间线同步以及领域特定工具。\n- [**新闻指南**](examples\u002Fnews-guide) – Foxhollow Dispatch 新闻编辑部助手，具备文章搜索、@提及功能及页面感知响应能力。\n- [**地铁地图**](examples\u002Fmetro-map) – 一款基于聊天的地铁规划工具，采用 React Flow 构建线路与站点网络。\n\n## 快速入门\n\n1. 导出 `OPENAI_API_KEY`。\n2. 确保已安装 `uv`。\n3. 从仓库根目录启动示例，或在项目目录下使用 `npm run start`：\n\n| 示例          | 仓库根目录命令      | 项目目录命令                              | URL                   |\n| ---------------- | -------------------------- | ---------------------------------------------------------- | --------------------- |\n| 猫咖啡馆       | `npm run cat-lounge`       | `cd examples\u002Fcat-lounge && npm install && npm run start`   | http:\u002F\u002Flocalhost:5170 |\n| 客户支持       | `npm run customer-support` | `cd examples\u002Fcustomer-support && npm install && npm start` | http:\u002F\u002Flocalhost:5171 |\n| 新闻指南       | `npm run news-guide`       | `cd examples\u002Fnews-guide && npm install && npm run start`   | http:\u002F\u002Flocalhost:5172 |\n| 地铁地图        | `npm run metro-map`        | `cd examples\u002Fmetro-map && npm install && npm run start`    | http:\u002F\u002Flocalhost:5173 |\n\n## 功能索引\n\n### 服务器工具调用以获取应用数据用于推理\n\n- **猫咖啡馆**：\n  - 函数工具 `get_cat_status`（[cat_agent.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fcat_agent.py)）会为代理拉取最新的猫咪状态数据。\n- **新闻指南**：\n  - 代理在回复前会依赖一系列检索工具——`list_available_tags_and_keywords`、`get_article_by_id`、`search_articles_by_tags\u002Fkeywords\u002Fexact_text` 和 `get_current_page`——并使用 `show_article_list_widget` 来展示结果（[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)）。\n  - 隐藏上下文，如特色首页，会被规范化为代理输入，以确保摘要和建议始终基于准确信息（[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)）。\n- **地铁地图**：\n  - 地铁代理通过 `get_map` 同步地图数据，并利用 `list_lines`、`list_stations`、`get_line_route` 和 `get_station` 展示线路和站点详情，然后再给出路线指引（[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)）。\n  - `show_line_selector` 使用小部件向用户呈现多选题。\n  - 路线规划回复会将建议路径中各站点的实体来源作为标注附上。\n- **客户支持**：\n  - 礼宾服务会在每次对话开始前附加一个 `\u003CCUSTOMER_PROFILE>` 快照（行程、会员等级、近期时间线），并暴露更改座位、取消行程、增加行李、选择餐食、显示航班选项以及针对每条线程的 `AirlineStateManager` 状态请求协助等工具（[server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)、[support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py)、[airline_state.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fairline_state.py)）。\n\n### 客户端工具调用，用于改变或获取 UI 状态\n\n- **地铁地图**：\n  - 客户端工具 `get_selected_stations` 会从画布中拉取当前选中的节点，以便代理能够在响应中使用客户端状态（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)、[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)）。\n\n### 即时执行的客户端效果\n\n- **猫咖啡馆**：\n  - 客户端效果 `update_cat_status` 和 `cat_say` 由服务器工具调用，用于同步 UI 状态并显示气泡对话框；这些效果通过 [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx) 中的 `onEffect` 处理。\n- **地铁地图**：\n  - 客户端效果 `location_select_mode` 在选择线路后由服务器动作处理器流式传输（[server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)），并更新地铁地图画布（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n  - 客户端效果 `add_station` 则由代理在地图更新后流式传输，以立即同步画布并聚焦新创建的站点（[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)、[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n- **客户支持**：\n  - 服务器会在工具或小部件操作后流式传输 `customer_profile\u002Fupdate` 效果，使侧边栏始终反映最新的行程、会员等级和时间线数据（[support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py)、[server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)）。\n\n### 页面感知的模型响应\n\n- **新闻指南**：\n  - ChatKit 客户端会在 `article-id` 头部中传递当前打开的文章 ID，以便后端可以将响应限定在“当前页面”范围内（[ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n  - 服务器会读取该请求上下文，并暴露 `get_current_page` 工具，使代理无需用户粘贴内容即可加载完整内容（[main.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fmain.py)、[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)）。\n\n### 进度更新\n\n- **新闻指南**：\n  - 检索工具在搜索标签、作者、关键词、精确文本或加载当前页面时会流式传输 `ProgressUpdateEvent` 消息，从而让 UI 显示“正在搜索…”或“正在加载…”的状态（[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)）。\n  - 事件查找代理在扫描日期、星期几或关键词时也会发出进度通知，以在较长时间的查询过程中保持用户知情（[event_finder_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fevent_finder_agent.py)）。\n- **地铁地图**：\n  - 地铁代理在调用 `get_map` 获取地图信息时会发出进度更新；同时，在等待客户端工具调用 `get_selected_stations` 完成时也会发出进度更新（[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)）。\n\n### 回复生命周期中的 UI 状态\n\n- **地铁地图**：\n  - 客户端会在回复开始时锁定地图交互，并在流式传输结束时解锁，以防止在代理更新期间画布状态发生偏移，方法是添加 `onResponseStart` 和 `onResponseEnd` 处理程序（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n\n### 不含操作的组件\n\n- **猫咪休息室**：\n  - 服务器工具 `show_cat_profile` 流式传输一个在 [profile_card_widget.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fprofile_card_widget.py) 中定义的展示组件。\n\n### 含有操作的组件\n\n- **猫咪休息室**：\n  - 服务器工具 `suggest_cat_names` 流式传输一个带有操作配置的组件，这些配置指定了由客户端处理的 `cats.select_name` 和 `cats.more_names` 操作。\n  - 当用户点击该组件时，这些操作会在 [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx) 中的 `handleWidgetAction` 回调函数中被处理。\n- **客户支持**：\n  - 航班和餐食组件会携带操作负载（`flight.select`、`support.set_meal_preference`）进行流式传输，以便在预订前捕获用户的选择，这些组件基于 `.widget` 模板构建而成（[flight_options.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fflight_options.py)、[meal_preferences.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fmeal_preferences.py)、[support_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fsupport_agent.py)）。\n- **新闻指南**：\n  - 文章列表组件会渲染“查看”按钮，这些按钮会分发 `open_article` 操作，用于客户端导航和互动（[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)、[article_list_widget.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fwidgets\u002Farticle_list_widget.py)）。\n  - 事件查找器会流式传输一个包含时间线的组件，其中的“查看事件详情”按钮配置为由服务器端处理，以便用户可以内联展开条目（[event_finder_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fevent_finder_agent.py)、[event_list_widget.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fwidgets\u002Fevent_list_widget.py)）。\n- **地铁地图**：\n  - 服务器工具 `show_line_selector` 流式传输一个带有 `line.select` 操作的组件，该操作在点击列表项时触发（[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)、[line_select_widget.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fwidgets\u002Fline_select_widget.py)）。\n\n### 由服务器端处理的组件操作\n\n- **猫咪休息室**：\n  - `cats.select_name` 操作同样由服务器端处理，以反映数据更新，并在 [server.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fserver.py) 中流式传输更新后的名称建议组件。\n  - 该操作通过 [ChatKitPanel.tsx](examples\u002Fcat-lounge\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx) 中的 `handleWidgetAction` 回调函数使用 `chatkit.sendAction()` 调用。\n- **客户支持**：\n  - 操作处理器会持久化预订、餐食、追加销售和重新预订信息；锁定组件；记录隐藏上下文；并在用户点击 `flight.select`、`support.set_meal_preference`、`booking.*`、`upsell.*` 或 `rebook.select_option` 时刷新个人资料（[server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)）。\n- **新闻指南**：\n  - `view_event_details` 操作在服务器端处理，以更新时间线组件中的扩展描述，而无需往返模型（[server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py)）。\n- **地铁地图**：\n  - `line.select` 操作由服务器端处理，用于流式传输更新后的组件，向对话中添加一个 `\u003CLINE_SELECTED>` 的隐藏上下文条目，流式传输助手消息以询问用户是否要在该线路的起点或终点添加车站，并触发客户端的 `location_select_mode` 效果以同步 UI（[server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)）。\n\n### 附件\n\n- **客户支持**：\n  - 端到端的图片附件：后端会提供上传\u002F下载 URL，强制执行图片\u002F大小限制，并将上传的文件转换为数据 URL 供模型使用（[attachment_store.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fattachment_store.py)、[main.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fmain.py)、[thread_item_converter.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fthread_item_converter.py)）。React 面板会注册 `attachments.create` 操作，通过签名的 URL 进行上传，并在旅客分享灵感照片时将附件放入编辑器中（[CustomerContextPanel.tsx](examples\u002Fcustomer-support\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FCustomerContextPanel.tsx)）。\n\n### 口述转文字（语音转文本）\n\n- **客户支持**：\n  - 聊天编辑器支持内置的口述功能（点击麦克风按钮即可说话）。该功能在客户端通过 `composer.dictation` 启用（[ChatKitPanel.tsx](examples\u002Fcustomer-support\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)），并在服务器端通过实现 `ChatKitServer.transcribe()` 来处理（[server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)）。\n\n### 注释\n\n- **地铁地图**：\n  - `plan_route` 工具会将计划路线中的每个车站作为实体来源呈现在助手消息中。这些车站既以内联注释的形式出现在助手消息中，也出现在来源列表中。\n  - 客户端的实体点击处理器会将 React Flow 画布平移到被点击的车站位置（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)、[metro_map_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Fmetro_map_agent.py)）。\n\n### 对话标题\n\n- **猫咪休息室**：\n  - 在用户为猫命名后，`set_cat_name` 工具会锁定该名称，并将对话标题更新为 `{name}’s Lounge`，然后保存（[cat_agent.py](examples\u002Fcat-lounge\u002Fbackend\u002Fapp\u002Fcat_agent.py)）。\n- **客户支持**：\n  - 一个轻量级的标题代理会在第一条用户消息时为对话命名，且不会延迟首次回复（[title_agent.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Ftitle_agent.py)、[server.py](examples\u002Fcustomer-support\u002Fbackend\u002Fapp\u002Fserver.py)）。\n- **新闻指南**：\n  - `title_agent` 会在第一条用户消息时运行，以在没有标题的情况下生成一个简短的、适合新闻编辑部的标题（[server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py)、[title_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Ftitle_agent.py)）。\n- **地铁地图**：\n  - 地铁服务器使用专门的 `title_agent` 来在第一次交互时设置一个简短的地铁规划标题，并将其持久化到对话元数据中（[server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)、[title_agent.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fagents\u002Ftitle_agent.py)）。\n\n### 实体标签（@提及）\n\n- **新闻指南**：\n  - 实体搜索和预览功能支持在消息编辑器中对文章\u002F作者进行@提及（输入`@`或点击`@`按钮），并通过`\u002Farticles\u002Ftags`接口渲染悬停预览（[ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx), [main.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fmain.py)）。\n  - 被标记的实体会被转换为模型可读的标记，以便智能体能够获取正确的记录（`\u003CARTICLE_REFERENCE>` \u002F `\u003CAUTHOR_REFERENCE>`）（[thread_item_converter.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fthread_item_converter.py)）。\n  - 在智能体引用具体内容之前，文章引用标签会通过指定的`get_article_by_id`工具解析为完整文章（[news_agent.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fagents\u002Fnews_agent.py)）。\n- **地铁地图**：\n  - 消息编辑器中的实体搜索会列出所有车站，用户可以通过@提及它们（输入`@`或点击`@`按钮）；点击标签还会将画布上的对应车站置为焦点（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n  - 被标记的车站会被转换为包含完整线路元数据的`\u003CSTATION_TAG>`块，这样智能体无需再次查找即可作答（[thread_item_converter.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fthread_item_converter.py), [server.py](examples\u002Fmetro-map\u002Fbackend\u002Fapp\u002Fserver.py)）。\n\n### 工具选择（编辑器菜单）\n\n- **新闻指南**：\n  - ChatKit客户端配置了`composer.tools`选项，用于指定编辑器菜单中的可用工具（[ChatKitPanel.tsx](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n  - 编辑器中的工具按钮允许用户强制指定特定的智能体（`event_finder`、`puzzle`），并在请求中设置`tool_choice`（[config.ts](examples\u002Fnews-guide\u002Ffrontend\u002Fsrc\u002Flib\u002Fconfig.ts)）。\n  - 后端会根据这些工具选择将请求路由到相应的专用智能体，若无法处理则回退到新闻指南智能体（[server.py](examples\u002Fnews-guide\u002Fbackend\u002Fapp\u002Fserver.py)）。\n\n### 自定义页眉操作\n\n- **地铁地图**：\n  - 聊天页眉右侧提供了一个图标切换按钮（`dark-mode` \u002F `light-mode`），用于在客户端层面切换应用的主题颜色（[ChatKitPanel.tsx](examples\u002Fmetro-map\u002Ffrontend\u002Fsrc\u002Fcomponents\u002FChatKitPanel.tsx)）。\n\n### 图像生成\n\n- **猫咪休息室**：\n  - `cat_agent`包含一个配置了3张部分图像的`ImageGenerationTool`。\n  - 猫咪休息室服务器的`respond`方法在调用`stream_agent_response`时传入了`ResponseStreamConverter(partial_images=3)`，以便助手在流式传输每一张部分图像时正确计算图像生成进度。","# OpenAI ChatKit 高级示例快速上手指南\n\n本指南帮助中国开发者快速运行 `openai-chatkit-advanced-samples` 仓库中的场景化演示。这些示例展示了如何结合 FastAPI 后端与 Vite + React 前端，利用 ChatKit Python SDK 和 ChatKit.js 客户端构建智能应用。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows (推荐 WSL2)。\n*   **Node.js**：已安装 Node.js (建议 v18+) 和 npm。\n*   **Python 工具链**：必须安装 [`uv`](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv) (高性能 Python 包安装器和项目管理器)。\n    *   安装命令 (macOS\u002FLinux): `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh`\n    *   安装命令 (Windows): `powershell -c \"irm https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.ps1 | iex\"`\n*   **API 密钥**：拥有有效的 `OPENAI_API_KEY`。\n*   **网络环境**：由于需要访问 OpenAI API 及部分 npm 源，建议配置好网络代理或使用国内镜像加速。\n    *   *npm 加速*: `npm config set registry https:\u002F\u002Fregistry.npmmirror.com`\n\n## 安装步骤\n\n您可以选择从仓库根目录一键启动，或进入特定示例目录单独运行。\n\n### 1. 获取代码\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples.git\ncd openai-chatkit-advanced-samples\n```\n\n### 2. 配置环境变量\n导出您的 OpenAI API 密钥：\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n# Windows PowerShell: $env:OPENAI_API_KEY=\"sk-...\"\n# Windows CMD: set OPENAI_API_KEY=sk-...\n```\n\n### 3. 运行示例\n推荐使用仓库根目录的快捷命令启动（会自动处理依赖安装）：\n\n| 示例名称 | 描述 | 启动命令 (根目录) | 访问地址 |\n| :--- | :--- | :--- | :--- |\n| **Cat Lounge** | 虚拟宠物养成 (状态管理、UI 同步) | `npm run cat-lounge` | http:\u002F\u002Flocalhost:5170 |\n| **Customer Support** | 航空客服 (行程数据、工具调用、附件) | `npm run customer-support` | http:\u002F\u002Flocalhost:5171 |\n| **News Guide** | 新闻助手 (文章检索、页面感知、进度流) | `npm run news-guide` | http:\u002F\u002Flocalhost:5172 |\n| **Metro Map** | 地铁规划 (React Flow 交互、地图实体标注) | `npm run metro-map` | http:\u002F\u002Flocalhost:5173 |\n\n> **备选方案**：若需单独进入某示例目录操作，可执行：\n> `cd examples\u002F\u003C示例名称> && npm install && npm run start`\n\n## 基本使用\n\n以 **Cat Lounge (虚拟宠物)** 为例，展示最基础的使用流程：\n\n1.  **启动服务**：\n    在项目根目录执行：\n    ```bash\n    npm run cat-lounge\n    ```\n    等待终端显示 `Local: http:\u002F\u002Flocalhost:5170` 且后端初始化完成。\n\n2.  **访问界面**：\n    打开浏览器访问 `http:\u002F\u002Flocalhost:5170`。\n\n3.  **交互体验**：\n    *   **查看状态**：系统会自动调用后端工具 `get_cat_status` 获取猫咪当前的能量、快乐值和清洁度。\n    *   **命名互动**：输入对话让猫咪起名，后端将流式传输一个包含操作按钮的 Widget (`suggest_cat_names`)。\n    *   **触发效果**：点击 Widget 中的名字选项，前端通过 `handleWidgetAction` 回调触发 `cats.select_name` 动作，后端更新数据并同步 UI 状态（如弹出气泡对话 `cat_say`）。\n\n**核心特性观察点**：\n*   **Server Tool Calls**: 观察后端如何自动拉取应用数据（如猫咪状态）作为推理上下文。\n*   **Client Effects**: 注意 UI 如何响应后端的 `update_cat_status` 指令实时更新进度条或状态图标。\n*   **Widgets**: 体验带有交互按钮的富文本回复，而非纯文本。\n\n其他示例（如 Metro Map 的地图连线、News Guide 的文章检索）遵循类似的交互逻辑，但侧重于不同的 ChatKit 能力（如实体标注、分页感知、复杂工作流）。","某航空公司的开发团队正致力于构建一个能实时读取旅客行程、自动处理改签与行李服务的智能客服助手。\n\n### 没有 openai-chatkit-advanced-samples 时\n- **数据割裂严重**：AI 模型无法直接访问后端数据库中的实时航班动态和旅客会员等级，只能基于训练数据“瞎猜”，导致回答缺乏时效性。\n- **状态同步困难**：前端界面展示的座位图或时间线与后台实际业务状态不同步，用户修改需求后，AI 往往不知道当前已选定了哪个航班或座位。\n- **开发成本高昂**：开发者需手动编写大量胶水代码来连接 FastAPI 后端与 React 前端，并自行设计复杂的函数调用（Function Calling）逻辑来处理退改签等具体指令。\n- **上下文管理混乱**：难以在每次对话中自动注入包含历史行程和偏好设置的 `\u003CCUSTOMER_PROFILE>`，导致用户需要反复陈述背景信息。\n\n### 使用 openai-chatkit-advanced-samples 后\n- **实时工具调用**：直接复用 Customer Support 示例中的架构，AI 能通过预置的 `AirlineStateManager` 工具实时查询并修改行程、锁定座位或添加行李，确保回复基于最新数据。\n- **双向状态同步**：利用客户端工具调用机制，前端画布或表单的选中状态（如特定航班）可即时传递给 AI，使助手能精准针对用户当前关注的对象进行回应。\n- **全栈快速落地**：基于现成的 FastAPI + Vite\u002FReact 模板，团队无需从零搭建，只需替换业务逻辑即可拥有具备领域专用工具链的生产级应用。\n- **智能上下文注入**：系统自动在每次推理前拼接旅客画像快照，使 AI 像专属管家一样熟知用户的历史偏好，无需重复询问即可提供个性化建议。\n\nopenai-chatkit-advanced-samples 通过提供标准化的全栈示例，将原本数周的复杂集成工作缩短为几天，让开发者能专注于业务逻辑而非底层架构搭建。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopenai_openai-chatkit-advanced-samples_8e707e84.png","openai","OpenAI","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fopenai_1960bbf4.png","",null,"https:\u002F\u002Fopenai.com\u002F","https:\u002F\u002Fgithub.com\u002Fopenai",609,284,"2026-04-11T02:24:39","NOASSERTION",4,"未说明",{"notes":90,"python":88,"dependencies":91},"该项目为 OpenAI ChatKit 的场景演示示例，包含后端（FastAPI + Python SDK）和前端（Vite + React）。运行前需导出 OPENAI_API_KEY 环境变量。项目使用 'uv' 作为包管理\u002F运行工具，通过 npm 脚本启动不同示例（如虚拟猫、客服、新闻助手、地铁规划）。主要依赖网络调用 OpenAI API，未在文档中提及本地 GPU、特定显存或大型模型下载需求。",[92,93,94,95,96,97],"FastAPI","Vite","React","ChatKit Python SDK","ChatKit.js","uv",[15,25],[100,76,101,102,103],"chatkit","openai-api","python","typescript","2026-03-27T02:49:30.150509","2026-04-12T14:00:09.123805",[107,112,117,122,127,132],{"id":108,"question_zh":109,"answer_zh":110,"source_url":111},30718,"为什么生产环境的 UI-chat 需要向服务注册域名？","这是出于安全原因。通过要求域名白名单（domain allowlisting），可以确保只有授权的域名才能向您的 ChatKit 集成发送请求，防止恶意行为者从未经授权的域名使用您的后端发送消息。目前无法绕过域名密钥（domain key）的要求。如果您想实现自定义后端逻辑，需要自行构建符合 ChatKit UI 预期端点的后端，但目前官方没有提供此类示例。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F9",{"id":113,"question_zh":114,"answer_zh":115,"source_url":116},30719,"运行后端时出现 'ModuleNotFoundError: No module named chatkit' 错误怎么办？","该错误通常与环境配置有关。您可以尝试在本地虚拟环境中直接运行以下命令来启动服务，而不是使用 npm 脚本：\n`.venv\u002Fbin\u002Fuvicorn app.main:app --reload`\n此外，请注意部分旧演示项目可能已被移除或更新，建议查看仓库中最新的 examples 目录获取最新代码。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F10",{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},30720,"ChatKit 不允许在本地开发环境（localhost）使用怎么办？","官方表示目前没有已知的针对自定义 ChatKit 后端或托管 ChatKit 的本地开发限制问题。如果您遇到工作流 ID 检测失败或被拒绝的情况，请检查您的环境配置和具体报错行为。对于初学者，可以参考官方的 starter repo (openai-chatkit-starter-app) 来搭建环境。如果在 hosts 文件中设置假域名仍无效，可能需要提供更多详细的错误信息以便进一步排查。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F13",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},30721,"UI 渲染混乱或聊天响应显示异常如何解决？","这是一个已知问题，通常与消息 ID 的处理有关。社区用户提供了一个变通方案：在流式处理响应时，拦截 `ThreadItemAddedEvent`，如果检测到事件项 ID 为默认的 `FAKE_RESPONSES_ID`，则将其替换为生成的唯一新 ID。这样可以避免 UI 将多条消息合并显示或更新错乱。具体代码逻辑涉及在 context 中存储 workaround_item_id 并在事件流转时进行替换。另外，也有用户指出该问题在样本应用更新后可能已不再相关，建议检查最新示例。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F6",{"id":128,"question_zh":129,"answer_zh":130,"source_url":131},30722,"代码中的变量名应该是 last_response_id 还是 response_id？","确实应该使用 `last_response_id`。在 `agents\u002Fresult.py` 的结果对象中，存在的属性是 `last_response_id` 而不是 `response_id`。维护者已确认变量命名应保持一致性，并已在相关 Pull Request 中修复了此问题，将代码中的引用更正为 `last_response_id`。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F16",{"id":133,"question_zh":134,"answer_zh":135,"source_url":136},30723,"如何在 Next.js 应用中正确集成和运行 ChatKit UI？","在 Next.js 中集成时，请确保组件文件顶部包含 `'use client'` 指令以启用客户端渲染。初始化 `useChatKit` 时，需正确配置 `api.url` 和 `api.domainKey`。如果在本地开发，配置文件中的 domainKey 可以使用占位符，但在部署生产环境前，必须在 OpenAI 平台的安全设置中注册您的生产域名并替换为真实的密钥。如果遇到渲染问题，请检查具体的错误日志以及运行环境（如 localhost 域名配置）。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fopenai-chatkit-advanced-samples\u002Fissues\u002F1",[]]