📦 CopilotKit React Best Practices — CopilotKit React 最佳实践 — React 代理应用开发指南

# CopilotKit React 模式 使用 CopilotKit 构建 agentic React 应用的最佳实践。包含 6 大类共 25 条规则，按影响力排序，用于指导代码生成与重构。同时覆盖 v1（@copilotkit/react-core）与 v2（@copilotkit/react-core/v2）API。 ## 何时应用 在以下场景请查阅本指南： - 在 React 应用中配置 CopilotKit provider - 使用 agent hooks（useAgent、useFrontendTool、useCopilotAction） - 渲染来自 agent 的 tool calls 或自定义消息 - 通过 useCopilotReadable 或 useCoAgent 在 UI 与 agent 间共享状态 - 使用 CopilotChat、CopilotSidebar 或 CopilotPopup 构建聊天界面 - 为 agent 主动协助配置 suggestions ## 按优先级划分的规则类别 | 优先级 | 类别 | 影响 | 前缀 | |----------|----------|--------|--------| | 1 | Provider Setup | CRITICAL | provider- | | 2 | Agent Hooks | HIGH | agent- | | 3 | Tool Rendering | HIGH | tool- | | 4 | Context & State | MEDIUM | state- | | 5 | Chat UI | MEDIUM | ui- | | 6 | Suggestions | LOW | suggestions- | ## 速查表 ### 1. Provider Setup（关键） - provider-runtime-url - 始终配置 runtimeUrl 以连接 agent 后端 - provider-single-endpoint - 通过 agent 属性配置 CoAgent 路由 - provider-nested-providers - 使用嵌套 CopilotKit provider 限定 agent 配置作用域 - provider-tool-registration - 尽可能在 provider 内部通过 hooks 注册 tools，而非通过 props ### 2. Agent Hooks（高） - agent-use-agent-updates - 指定 update 订阅以避免不必要的重渲染 - agent-agent-id - 同时运行多个 agent 时务必传递 agentId - agent-context-description - 为 useCopilotReadable 提供描述性 context 值 - agent-frontend-tool-deps - 为 useFrontendTool 声明依赖数组 - agent-stable-tool-handlers - 对 tool 处理函数使用 useCallback ### 3. Tool Rendering（高） - tool-typed-args - 为 useRenderTool 参数定义 Zod schema（v2） - tool-status-handling - 处理 tool call 的三种状态（inProgress、executing、complete） - tool-wildcard-fallback - 注册通配符 renderer 作为未知 tool 的兜底 - tool-render-vs-frontend - 仅展示用 useRenderTool，有副作用用 useFrontendTool - tool-component-hook - 简单组件渲染使用 useFrontendTool 的 render prop ### 4. Context & State（中等） - state-minimal-context - 仅向 agent 提供相关上下文，而非整个应用状态 - state-structured-values - 在 useCopilotReadable 中使用结构化对象，而非序列化字符串 - state-context-granularity - 按领域将上下文拆分为多个 useCopilotReadable 调用 - state-avoid-stale-closures - 在 tool 处理函数中使用函数式状态更新避免闭包过期 ### 5. Chat UI（中等） - ui-chat-layout - 持久聊天选 CopilotSidebar，按需聊天选 CopilotPopup - ui-custom-labels - 始终根据业务域自定义标签，而非使用默认文案 - ui-welcome-screen - 提供带建议提示的欢迎界面 - ui-input-mode - 根据用例选择合适的 inputMode ### 6. Suggestions（低） - suggestions-configure - 使用 useConfigureSuggestions（v2）或 useCopilotChatSuggestions（v1） - suggestions-context-driven - 提供丰富上下文，使 suggestions 更相关 - suggestions-loading-state - 通过 useSuggestions（v2）处理 suggestion 加载状态 ## 如何使用 阅读各规则文件获取详细说明与代码示例： `` rules/provider-runtime-url.md rules/agent-use-agent-updates.md rules/tool-typed-args.md ` 每条规则文件包含： - 简明解释其重要性 - 错误代码示例及说明 - 正确代码示例及说明 - 额外上下文与参考链接 ## 完整编译文档 包含所有规则展开的完整指南： AGENTS.md`