;\n agentId?: string;\n}\n```\n\n#### 前端工具示例\n\n```tsx\n// 资料来源：examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md\n\nimport { useCopilotAction } from \"@copilotkit/react-core\";\n\nfunction ChatInterface() {\n // 注册高亮文本的前端工具\n useCopilotAction({\n name: \"highlight_note\",\n description: \"将指定文本高亮显示\",\n parameters: z.object({\n text: z.string(),\n color: z.string().optional().default(\"yellow\"),\n }),\n render: ({ args, status }) => (\n \n 高亮文本: {args.text}\n {status === \"in-progress\" && 处理中...}\n
\n ),\n });\n\n return ;\n}\n```\n\n资料来源：[examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md)\n\n---\n\n## 显示组件\n\n### Headless 聊天界面\n\nCopilotKit 提供了完整的 Headless API，允许开发者完全自定义聊天界面的每一个细节。\n\n#### 核心 Hooks\n\n| Hook 名称 | 功能描述 |\n|-----------|----------|\n| `useAgent` | 获取原始代理句柄，包含 messages、isRunning、addMessage 等 |\n| `useCopilotKit` | 暴露 connectAgent、runAgent、stopAgent 方法 |\n| `useRenderTool` | 为特定工具注册自定义渲染器 |\n| `useCopilotReadable` | 将前端状态共享给 AI 代理 |\n\n#### Headless 实现示例\n\n```tsx\n// 资料来源：examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md\n\nimport { useAgent, useCopilotKit, useRenderTool } from \"@copilotkit/react-core\";\nimport { WeatherCard } from \"./components/WeatherCard\";\n\nfunction HeadlessChat() {\n const { messages, isRunning, addMessage, stop } = useAgent({ \n agentId: \"main-agent\",\n threadId: \"user-thread-1\" \n });\n const { connectAgent, runAgent, stopAgent } = useCopilotKit();\n\n // 注册天气工具的渲染器\n useRenderTool(\n \"get_weather\",\n ({ args, status, result }) => {\n if (status === \"in-progress\") {\n return 获取天气信息...
;\n }\n return ;\n }\n );\n\n return (\n \n \n \n addMessage({ role: \"user\", content: text })}\n />\n
\n );\n}\n```\n\n### 消息列表渲染\n\n```tsx\n// 消息列表组件\n// 资料来源：examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md\n\nfunction MessageList({ messages }) {\n return (\n \n {messages.map((message, index) => (\n \n ))}\n
\n );\n}\n\n// 消息气泡组件\nfunction MessageBubble({ role, content, toolCalls, reasoning, status }) {\n return (\n \n {role === \"user\" &&
}\n \n {role === \"assistant\" && (\n <>\n {reasoning &&
}\n
\n \n {toolCalls?.map((toolCall, idx) => (\n
\n ))}\n \n
\n \n )}\n
\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n \n\n# 人在回路 (Human-in-the-Loop)\n\n## 概述\n\n人在回路（Human-in-the-Loop，HitL）是一种设计模式，允许 AI 代理在执行关键操作前暂停执行流程，等待人类用户确认或提供额外输入。这种机制确保了 AI 系统在执行敏感操作时的安全性和可控性，特别适用于需要人工审批的业务场景。\n\n在 CopilotKit 架构中，人在回路通过以下核心机制实现：\n\n- **工具级中断**：Agent 调用特定工具时暂停，等待用户响应\n- **实时 UI 渲染**：在等待期间向用户展示操作详情和审批界面\n- **状态同步**：用户的决策结果实时同步回 Agent 继续执行\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n## 核心概念\n\n### 与前端工具的区别\n\n| 特性 | 前端工具 (Frontend Tools) | 人在回路 (HitL) |\n|------|---------------------------|-----------------|\n| 执行时机 | 立即执行，无需等待 | 暂停等待用户确认 |\n| 用户交互 | 可选 UI 渲染 | 必须有审批 UI |\n| 状态转换 | 异步完成 | 同步等待响应 |\n| 典型场景 | 数据查询、格式化 | 预算审批、敏感操作确认 |\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[Agent 决策] --> B{需要人工确认?}\n B -->|否| C[继续执行]\n B -->|是| D[触发 HitL 工具]\n D --> E[渲染审批 UI]\n E --> F[等待用户响应]\n F --> G{用户决策}\n G -->|批准| H[返回批准结果]\n G -->|拒绝| I[返回拒绝结果]\n G -->|修改参数| J[返回修改后参数]\n H --> K[Agent 继续执行]\n I --> L[Agent 取消操作]\n J --> K\n```\n\n## Angular 集成\n\n### HumanInTheLoopConfig 接口\n\n```typescript\nexport interface HumanInTheLoopConfig {\n name: string; // 工具名称\n description: string; // 工具描述\n parameters: z.ZodType; // 参数 Schema\n component: Type>; // 审批 UI 组件\n agentId?: string; // 可选的 Agent 作用域\n}\n```\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n### HumanInTheLoopToolRenderer 组件\n\n```typescript\nexport interface HumanInTheLoopToolRenderer {\n toolCall: Signal>; // 包含 respond(result) 方法\n}\n```\n\n审批组件通过 `toolCall` 信号接收工具调用信息，并通过 `respond()` 方法向 Agent 返回用户的决策结果。\n\n### 配置示例\n\n```typescript\nexport const hitlConfig: HumanInTheLoopConfig = {\n name: \"approve_budget\",\n description: \"审批预算支出\",\n parameters: budgetApprovalSchema,\n component: BudgetApprovalCard,\n agentId: \"finance-agent\"\n};\n```\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n## Vue 集成\n\n### CopilotKitProvider 配置\n\n在 Vue 生态中，HitL 功能通过 `CopilotKitProvider` 的配置项启用：\n\n```vue\n\n \n\n```\n\n### 状态信号\n\n| 信号名称 | 类型 | 说明 |\n|---------|------|------|\n| `runtimeConnectionStatus` | `Signal` | 运行时连接状态 |\n| `runtimeUrl` | `Signal` | 运行时 URL |\n| `agents` | `Signal>` | 可用 Agent 列表 |\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## React 集成\n\n### useCopilotAction Hook\n\n在 React 中使用 HitL 功能，通过 `useCopilotAction` 定义需要审批的工具：\n\n```typescript\nuseCopilotAction({\n name: \"approve_budget\",\n description: \"Prompt the user to review and approve the budget\",\n parameters: [\n {\n name: \"prompt\",\n type: \"string\",\n required: true,\n description: \"The approval prompt to show the user\"\n }\n ],\n render: ({ status, result, args }) => {\n // 返回审批 UI 组件\n return ;\n },\n});\n```\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n### render 回调参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `status` | `\"in-progress\" \\| \"executing\" \\| \"complete\"` | 工具执行状态 |\n| `result` | `string \\| undefined` | 工具返回结果 |\n| `args` | `Record` | 工具调用参数 |\n\n## 深度 Agent 集成\n\n### LangGraph 深度 Agent\n\n深度 Agent（Deep Agents）模式允许构建多层级、多工具的复杂 Agent 系统，HitL 作为关键节点确保人类参与关键决策点：\n\n```python\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n### 研究工具集成\n\n```python\n@tool\nasync def create_character(\n name: str,\n description: str,\n prompt: str,\n state: Annotated[dict, InjectedState] # 访问共享状态\n) -> dict:\n api_key = state.get(\"apiKey\", \"\")\n image_url = await generate_image(prompt, api_key=api_key)\n return {\"name\": name, \"description\": description, \"imageUrl\": image_url}\n```\n\n当 Agent 调用 `create_character` 时，可以在返回前插入 HitL 审批环节。\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n## LlamaIndex 集成\n\n### 工具渲染配置\n\n```typescript\nexport interface RenderToolCallConfig {\n name: string; // 工具名或 \"*\" 通配符\n args: z.ZodType; // Zod Schema\n component: Type>;\n agentId?: string; // 可选的 Agent 作用域\n}\n```\n\n### 数据流架构\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as Canvas UI\n participant CK as CopilotKit\n participant Agent as LlamaIndex Agent\n participant Tools\n participant Composio\n\n User->>UI: 交互操作\n UI->>CK: 通过 useCoAgent 更新状态\n CK->>Agent: 发送状态 + 消息\n Agent->>Agent: 使用 GPT-4o 处理\n Agent->>Tools: 执行工具\n Tools-->>Agent: 返回结果\n Agent->>CK: 返回更新后的状态\n CK->>UI: 同步状态变更\n UI->>User: 显示更新\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n## 预算审批实战案例\n\n### BudgetApprovalCard 组件\n\n在实际业务场景中，预算审批是最常见的 HitL 用例。以下是典型实现结构：\n\n```typescript\ninterface BudgetApprovalProps {\n status: \"in-progress\" | \"executing\" | \"complete\";\n result?: string;\n args: {\n amount: number;\n category: string;\n description: string;\n };\n}\n\n// 组件应处理三种状态：\n// 1. in-progress: 显示审批表单\n// 2. executing: 显示处理中指示器\n// 3. complete: 显示审批结果\n```\n\n### 状态机设计\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 用户发起请求\n Pending --> Reviewing: 渲染审批 UI\n Reviewing --> Approved: 用户点击批准\n Reviewing --> Rejected: 用户点击拒绝\n Reviewing --> Modifying: 用户修改参数\n Approved --> [*]: 返回结果给 Agent\n Rejected --> [*]: 取消操作\n Modifying --> Reviewing: 重新提交\n```\n\n## 应用场景\n\n### 1. 财务审批\n\n- 预算支出审批\n- 费用报销确认\n- 付款授权\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n### 2. 内容生成确认\n\n- AI 生成内容的审核\n- 图像生成参数确认\n- 文档内容校正\n\n### 3. 数据操作审批\n\n- 数据库修改确认\n- 文件删除审批\n- 配置变更确认\n\n## 最佳实践\n\n### 设计原则\n\n1. **明确性**：工具描述应清晰说明需要用户确认什么\n2. **最小化干预**：只在必要时使用 HitL，避免过度打断流程\n3. **快速响应**：审批 UI 应简洁，减少用户等待时间\n4. **可追溯性**：记录所有审批决策，便于审计\n\n### 错误处理\n\n```typescript\nfunction onProviderError(event: {\n code: string;\n error: Error;\n context: Record;\n}) {\n console.error(\n \"CopilotKit provider error\",\n event.code,\n event.context,\n event.error,\n );\n}\n```\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 调试与日志\n\n### debug 配置选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `events` | `boolean` | 启用事件日志 |\n| `lifecycle` | `boolean` | 启用生命周期日志 |\n| `verbose` | `boolean` | 启用完整事件负载 |\n\n```typescript\nconst debug: DebugConfig = {\n events: true,\n lifecycle: true,\n verbose: false\n};\n```\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 相关资源\n\n- [CopilotKit 文档](https://docs.copilotkit.ai)\n- [LangGraph 深度 Agent 集成](https://docs.copilotkit.ai/integrations/langgraph/deep-agents)\n- [构建深度 Agent 前端](https://www.copilotkit.ai/blog/how-to-build-a-frontend-for-langchain-deep-agents-with-copilotkit)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：CopilotKit/CopilotKit\n\n摘要：发现 28 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…。\n\n## 1. 安装坑 · 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged s…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_409f46a5944945278264fc47e297b72a | https://github.com/CopilotKit/CopilotKit/issues/4885 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6230695b9a44704927b31badcc61437 | https://github.com/CopilotKit/CopilotKit/issues/3454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_93af324180434026b3961aff8938714f | https://github.com/CopilotKit/CopilotKit/issues/4911 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0efd9d1f363946d48e1168b691b0ad4c | https://github.com/CopilotKit/CopilotKit/issues/4893 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f934812319464fb5acab93b86e00ed00 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: v1.55.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.55.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.55.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.55.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_67f1e990977177cadc4a1a612db8df88 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.55.3 | v1.55.3\n\n## 7. 安装坑 · 失败模式：installation: v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.0. Context: Observed when using node, python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_8ede7507e3ef26c20ae94eb3ff6a0f6f | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.0 | v1.56.0\n\n## 8. 安装坑 · 失败模式：installation: v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a12898a84c35b19ec1421880ce10e28 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.1 | v1.56.1\n\n## 9. 安装坑 · 失败模式：installation: v1.56.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a917a302b0681683ac2482e6cdefd4b | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.2 | v1.56.2\n\n## 10. 安装坑 · 失败模式：installation: v1.56.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_386de57caa0b418e81af496ef3e832e1 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.3 | v1.56.3\n\n## 11. 安装坑 · 失败模式：installation: v1.56.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.4\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.4. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ba48c40eb329f48223cab1a600a088ca | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.4 | v1.56.4\n\n## 12. 安装坑 · 失败模式：installation: v1.56.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.5\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.5. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_985bd4475e66904ba7c8c53ae2d6f26a | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.5 | v1.56.5\n\n## 13. 安装坑 · 失败模式：installation: v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.0. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_60e47d47ceb61ba142df495e376e2453 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.0 | v1.57.0\n\n## 14. 安装坑 · 失败模式：installation: v1.57.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ddfe5da6e5463254a7ca21a7897af5c7 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.1 | v1.57.1\n\n## 15. 安装坑 · 失败模式：installation: v1.57.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_90e0287612ace3e3e390a222dfb52f45 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.2 | v1.57.2\n\n## 16. 安装坑 · 失败模式：installation: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3b813b40a8ae8f0fbc8b566627e75943 | https://github.com/CopilotKit/CopilotKit/issues/4911 | 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n## 17. 安装坑 · 失败模式：installation: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Functio...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ad59dd9220304dfaf2d38e53d40c383e | https://github.com/CopilotKit/CopilotKit/issues/2622 | 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n\n## 18. 安装坑 · 失败模式：installation: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB). Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_bc9acdf64647823252fafc35e7d96b1a | https://github.com/CopilotKit/CopilotKit/issues/4893 | 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n## 19. 安装坑 · 来源证据：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Back…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36feede08b6a456fa0702692343460fa | https://github.com/CopilotKit/CopilotKit/issues/2622 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | README/documentation is current enough for a first validation pass.\n\n## 21. 运行坑 · 失败模式：runtime: LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：Developers may hit a documented source-backed failure mode: LangGraph thread history is not hydrated after cold restart until first new message\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: LangGraph thread history is not hydrated after cold restart until first new message. Context: Observed when using python, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0bf1b00ba8b8f47db81aeaa235b28a67 | https://github.com/CopilotKit/CopilotKit/issues/3454 | LangGraph thread history is not hydrated after cold restart until first new message\n\n## 22. 运行坑 · 失败模式：runtime: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_96f6f8c3f4d6fc2c196cdd9c8b7b7356 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n## 23. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | last_activity_observed missing\n\n## 24. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 25. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 26. 能力坑 · 失败模式：capability: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / termin...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 对用户的影响：Developers may hit a documented source-backed failure mode: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0d7ae1046b9b8f5803ce38f0cd0f6a38 | https://github.com/CopilotKit/CopilotKit/issues/4885 | @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n\n## 27. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | issue_or_pr_quality=unknown\n\n## 28. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | release_recency=unknown\n\n\n",
"markdown_key": "copilotkit",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:655515393",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/CopilotKit/CopilotKit"
},
{
"evidence_id": "art_2e8fd87fcb0445049bcf6aeda58fca6d",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/CopilotKit/CopilotKit#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "CopilotKit 说明书",
"toc": [
"https://github.com/CopilotKit/CopilotKit 项目说明书",
"目录",
"快速入门指南",
"什么是 CopilotKit",
"前置要求",
"安装方式",
"React 快速开始",
"Vue 快速开始",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "4749ac138c54edcf3e142deb016423017d3c9adf",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/props.ts",
"docs/package-lock.json",
"docs/POSTHOG_BROKEN_LINKS.md",
"docs/vercel.json",
"docs/pnpm-lock.yaml",
"docs/source.config.ts",
"docs/pnpm-workspace.yaml",
"docs/model-allowlist.json",
"docs/package.json",
"docs/README.md",
"docs/middleware.ts",
"docs/tsconfig.json",
"docs/components.json",
"docs/docs/broken-link-handling.md",
"docs/scripts/check-broken-links.js",
"docs/scripts/verify-broken-links.js",
"docs/snippets/use-agent.mdx",
"docs/snippets/copilot-cloud-configure-remote-endpoint-langgraph.mdx",
"docs/snippets/install-python-sdk.mdx",
"docs/snippets/copilot-ui.mdx",
"docs/snippets/self-hosting-copilot-runtime-starter.mdx",
"docs/snippets/crew-quickstart.mdx",
"docs/snippets/langgraph-platform-deployment-tabs.mdx",
"docs/snippets/install-sdk.mdx",
"docs/snippets/find-your-copilot-runtime.mdx",
"docs/snippets/landing-code-showcase.mdx",
"docs/snippets/self-hosting-copilot-runtime-configure-copilotkit-provider.mdx",
"docs/snippets/headless-ui.mdx",
"docs/snippets/self-hosting-copilot-runtime-langgraph-endpoint.mdx",
"docs/snippets/copilot-cloud-configure-remote-endpoint.mdx",
"docs/snippets/llm-adapters.mdx",
"docs/snippets/self-hosting-copilot-runtime-create-endpoint.mdx",
"docs/snippets/copilot-cloud-configure-copilotkit-provider.mdx",
"docs/snippets/component-examples.mdx",
"docs/snippets/copilot-runtime.mdx",
"docs/snippets/use-client-callout.mdx",
"docs/snippets/self-hosting-remote-endpoints.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# CopilotKit - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 CopilotKit 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx copilotkit@latest create -f ` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx copilotkit@latest init` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx create-ag-ui-app my-agent-app` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install @copilotkit/{core,angular}` 证据：`packages/angular/README.md` Claim：`clm_0007` unverified 0.25\n- `npm install @copilotkit/react-native` 证据：`packages/react-native/README.md` Claim：`clm_0008` unverified 0.25\n- `pnpm add @copilotkit/voice openai` 证据：`packages/voice/README.md` Claim：`clm_0009` unverified 0.25\n- `pnpm add @copilotkit/vue @copilotkit/core` 证据：`packages/vue/README.md` Claim：`clm_0010` unverified 0.25\n- `npx create-mcp-use-app my-server` 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md` Claim：`clm_0011` unverified 0.25, `clm_0012` unverified 0.25, `clm_0013` unverified 0.25, `clm_0014` unverified 0.25\n- `npx create-mcp-use-app my-server --npm` 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md` Claim：`clm_0012` unverified 0.25\n- `npx create-mcp-use-app my-server --pnpm` 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md` Claim：`clm_0013` unverified 0.25\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等 Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `AGENTS.md`, `CLAUDE.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `AGENTS.md`, `CLAUDE.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等 Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`, `.claude/skills/git-hooks/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/references/foundations/quickstart.md`, `packages/angular/README.md`, `packages/react-native/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：12400\n- 重要文件覆盖：40/12400\n- 证据索引条目：84\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 CopilotKit 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 CopilotKit 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 CopilotKit 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **copilotkit-demo-parity**（skill）：Keeps examples/integrations/ demos aligned to the north-star langgraph-python . Use when the user says \"sync demos\", \"sync integrations\", \"port to north-star\", \"align integration demos\", \"parity check\", or when working inside examples/integrations/ and tracked files diverge. Drives the pnpm parity:sync / parity:verify commands and handles the manual-merge zones agent code, api route, Dockerfile . 激活提示：当用户任务与“copilotkit-demo-parity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/copilotkit-demo-parity/SKILL.md`\n- **git-hooks**（skill）：CopilotKit pre-commit hook reference. Load automatically when the user mentions git hooks failing, pre-commit errors, lefthook issues, commit blocked, or \"hooks don't work\", or when user wants to commit/push anything Contains the full hook topology so debugging skips discovery and goes straight to diagnosis. 激活提示：当用户任务与“git-hooks”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/git-hooks/SKILL.md`\n- **chatgpt-app-builder**（skill）： 激活提示：当用户任务与“chatgpt-app-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md`\n- **mcp-apps-builder**（skill）： 激活提示：当用户任务与“mcp-apps-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md`\n- **mcp-builder**（skill）： 激活提示：当用户任务与“mcp-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-builder/SKILL.md`\n\n## 证据索引\n\n- 共索引 84 条证据。\n\n- **fumadocs-test**（documentation）：This is a Next.js application generated with Create Fumadocs https://github.com/fuma-nama/fumadocs . 证据：`docs/README.md`\n- **Framework Overview Component**（documentation）：The FrameworkOverview component is a reusable landing page component that allows you to create consistent framework-specific landing pages with customizable content. 证据：`docs/components/content/landing-pages/README.md`\n- **General Guidelines for working with Nx**（documentation）：General Guidelines for working with Nx 证据：`AGENTS.md`\n- **General Guidelines for working with Nx**（documentation）：General Guidelines for working with Nx 证据：`CLAUDE.md`\n- **CopilotKit**（documentation）：Docs https://docs.copilotkit.ai/?ref=github readme · Examples https://www.copilotkit.ai/examples · Enterprise Intelligence Platform https://go.copilotkit.ai/enterprise-intelligence-platform · Discord https://discord.gg/6dffbvGU3D?ref=github readme 证据：`README.md`\n- **CopilotKit Examples**（documentation）：This directory contains 47 consolidated demo repositories showcasing CopilotKit integrations, canvas apps, and showcases. 证据：`examples/README.md`\n- **CopilotKit Python SDK**（documentation）：! PyPI version https://badge.fury.io/py/copilotkit.svg https://badge.fury.io/py/copilotkit ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT 证据：`sdk-python/README.md`\n- **Showcase Platform**（documentation）：Per-framework demos of CopilotKit LangGraph, CrewAI, Mastra, Claude Agent SDK, etc. . Each package is a Next.js frontend + agent backend bundled in a Docker image. Railway deploys those images from main on push. This README is the from-scratch setup for running the same stack locally. 证据：`showcase/README.md`\n- **Hacktoberfest 2025: Contribute to CopilotKit and Win Exclusive Swag!**（documentation）：! hacktoberfest banner https://github.com/user-attachments/assets/813f2f32-999e-4e91-a527-9c1748380154 证据：`community/content/README.md`\n- **Open Gemini Canvas**（documentation）：https://github.com/user-attachments/assets/1e95c9e1-2d55-4f63-b805-be49fe94a493 证据：`examples/canvas/gemini/README.md`\n- **CopilotKit < LangGraph AG-UI Canvas Starter**（documentation）：CopilotKit < LangGraph AG-UI Canvas Starter 证据：`examples/canvas/langgraph-python/README.md`\n- **Fullstack Agents Hackathon Starter**（documentation）：Welcome to the Fullstack Agents hackathon! This starter gives you a complete AI-powered canvas application with real-world integrations. Utilizing LlamaIndex https://developers.llamaindex.ai , Composio https://docs.composio.dev , and CopilotKit https://docs.copilotkit.ai . 证据：`examples/canvas/llamaindex-composio/README.md`\n- **Llama Index Agent Starter: Python**（documentation）：This package is a quick starter example for building AG-UI agents with Llama Index and CopilotKit. 证据：`examples/canvas/llamaindex-composio/agent/README.md`\n- **CopilotKit < LlamaIndex AG-UI Canvas Starter**（documentation）：CopilotKit < LlamaIndex AG-UI Canvas Starter 证据：`examples/canvas/llamaindex/README.md`\n- **Llama Index Agent Starter: Python**（documentation）：This package is a quick starter example for building AG-UI agents with Llama Index and CopilotKit. 证据：`examples/canvas/llamaindex/agent/README.md`\n- **AG-UI Mastra Workshop**（documentation）：A comprehensive workshop demonstrating AG-UI Agent User Interaction protocol with Mastra integration. This workshop shows how to build sophisticated AI applications with shared state, multiple client interfaces, and rich user interactions. 证据：`examples/canvas/mastra-pm/README.md`\n- **CopilotKit < Mastra AG-UI Canvas Starter**（documentation）：CopilotKit < Mastra AG-UI Canvas Starter 证据：`examples/canvas/mastra/README.md`\n- **CopilotKit < PydanticAI AG-UI Canvas Starter**（documentation）：CopilotKit < PydanticAI AG-UI Canvas Starter 证据：`examples/canvas/pydantic-ai/README.md`\n- **Examples E2E Playwright — Notes for Agents & Future Devs**（documentation）：Examples E2E Playwright — Notes for Agents & Future Devs 证据：`examples/e2e/AGENTS.md`\n- **parity/ — integration-demo parity tooling**（documentation）：parity/ — integration-demo parity tooling 证据：`examples/integrations/_parity/README.md`\n- **CopilotKit < A2A + A2UI Starter**（documentation）：This is a starter template for building AI agents that use A2UI https://a2ui.org and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated restaurant finder agent that can find restaurants and book reservations 证据：`examples/integrations/a2a-a2ui/README.md`\n- **A2UI Extension Implementation**（documentation）：This is the Python implementation of the a2ui extension. 证据：`examples/integrations/a2a-a2ui/a2ui_extension/README.md`\n- **A2UI Restaurant finder and table reservation agent sample.**（documentation）：A2UI Restaurant finder and table reservation agent sample. 证据：`examples/integrations/a2a-a2ui/agent/README.md`\n- **A2A + AG-UI Multi-Agent Starter**（documentation）：A minimal starter template for building multi-agent applications with A2A Protocol Agent-to-Agent and AG-UI Protocol Agent-UI . This project demonstrates how to coordinate multiple AI agents across different frameworks LangGraph and Google ADK to solve tasks collaboratively. 证据：`examples/integrations/a2a-middleware/README.md`\n- **CopilotKit < ADK Starter**（documentation）：This is a starter template for building AI agents using Google's ADK https://google.github.io/adk-docs/ and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated investment analyst agent that can research stocks, analyze market data, and provide investment insights. 证据：`examples/integrations/adk/README.md`\n- **CopilotKit < Agent Spec Starter**（documentation）：This is a starter template for building AI agents using Agent Spec and CopilotKit. It provides a modern Next.js application wired to a FastAPI backend that serves an Agent Spec agent with A2UI-powered frontend tool rendering calendar, inbox, email compose, daily brief dashboard . 证据：`examples/integrations/agent-spec/README.md`\n- **CopilotKit + AWS AgentCore**（documentation）：Chat UI with generative charts, shared-state todo canvas, and inline tool rendering — deployed on AWS Bedrock AgentCore. Pick LangGraph or Strands. 证据：`examples/integrations/agentcore/README.md`\n- **Terraform Infrastructure**（documentation）：Equivalent of ../infra-cdk/ using Terraform. 证据：`examples/integrations/agentcore/infra-terraform/README.md`\n- **CopilotKit < Agno Starter**（documentation）：This is a starter template for building AI agents using Agno https://agno.com and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated investment analyst agent that can research stocks, analyze market data, and provide investment insights. 证据：`examples/integrations/agno/README.md`\n- **CopilotKit < CrewAI Crew Starter**（documentation）：This is a starter template for building AI agents using CrewAI Crews https://docs.crewai.com/en/concepts/crews and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated CrewAI Crew agent to be built on top of. 证据：`examples/integrations/crewai-crews/README.md`\n- **CopilotKit < CrewAI Flow Starter**（documentation）：This is a starter template for building AI agents using CrewAI Flows https://docs.crewai.com/en/concepts/flows and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated CrewAI Flow agent to be built on top of. 证据：`examples/integrations/crewai-flows/README.md`\n- **CopilotKit < LangGraph Starter**（documentation）：This is a starter template for building AI agents using LangGraph https://www.langchain.com/langgraph and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated LangGraph agent to be built on top of. 证据：`examples/integrations/langgraph-fastapi/README.md`\n- **CopilotKit < LangGraph Starter**（documentation）：This is a starter template for building AI agents using LangGraph https://www.langchain.com/langgraph and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated LangGraph agent TypeScript to be built on top of. 证据：`examples/integrations/langgraph-js/README.md`\n- **CopilotKit + LangGraph Todo Demo**（documentation）：This repository serves as both a showcase and template for building AI agents with CopilotKit and LangGraph. It demonstrates how CopilotKit can drive interactive UI beyond just chat, using a collaborative todo list as the primary example. 证据：`examples/integrations/langgraph-python-threads/CLAUDE.md`\n- **CopilotKit + LangGraph Python**（documentation）：A starter template for building AI agents using LangGraph https://www.langchain.com/langgraph Python and CopilotKit https://copilotkit.ai , with optional CopilotKit Intelligence for durable conversation threads. 证据：`examples/integrations/langgraph-python-threads/README.md`\n- **CopilotKit + LangGraph Todo Demo**（documentation）：This repository serves as both a showcase and template for building AI agents with CopilotKit and LangGraph. It demonstrates how CopilotKit can drive interactive UI beyond just chat, using a collaborative todo list as the primary example. 证据：`examples/integrations/langgraph-python/CLAUDE.md`\n- **CopilotKit < LangGraph Starter**（documentation）：This is a starter template for building AI agents using LangGraph https://www.langchain.com/langgraph and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated LangGraph agent to be built on top of. 证据：`examples/integrations/langgraph-python/README.md`\n- **CopilotKit < LlamaIndex Starter**（documentation）：This is a starter template for building AI agents using LlamaIndex https://llamaindex.com and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated investment analyst agent that can research stocks, analyze market data, and provide investment insights. 证据：`examples/integrations/llamaindex/README.md`\n- **Llama Index Agent Starter: Python**（documentation）：This package is a quick starter example for building AG-UI agents with Llama Index and CopilotKit. 证据：`examples/integrations/llamaindex/agent/README.md`\n- **CopilotKit < Mastra Starter**（documentation）：This is a starter template for building AI agents using Mastra https://mastra.ai and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with integrated AI capabilities and a beautiful UI. 证据：`examples/integrations/mastra/README.md`\n- **CopilotKit < MCP Apps Starter**（documentation）：This is a starter template for integrating MCP Apps https://mcpui.dev with CopilotKit https://copilotkit.ai . It uses the Three.js example https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server from the official Model Context Protocol organization on GitHub. 证据：`examples/integrations/mcp-apps/README.md`\n- **Example: Three.js App**（documentation）：Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration. 证据：`examples/integrations/mcp-apps/threejs-server/README.md`\n- **CopilotKit < Microsoft Agent Framework Starter**（documentation）：CopilotKit < Microsoft Agent Framework Starter 证据：`examples/integrations/ms-agent-framework-dotnet/README.md`\n- **CopilotKit < Microsoft Agent Framework Python**（documentation）：CopilotKit < Microsoft Agent Framework Python 证据：`examples/integrations/ms-agent-framework-python/README.md`\n- **CopilotKit < PydanticAI Starter**（documentation）：This is a starter template for building AI agents using PydanticAI https://ai.pydantic.dev/ and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated investment analyst agent that can research stocks, analyze market data, and provide investment insights. 证据：`examples/integrations/pydantic-ai/README.md`\n- **CopilotKit < strands Starter**（documentation）：This is a starter template for building AI agents using strands https://strands.com and CopilotKit https://copilotkit.ai . It provides a modern Next.js application with an integrated investment analyst agent that can research stocks, analyze market data, and provide investment insights. 证据：`examples/integrations/strands-python/README.md`\n- **AG-UI + A2A Multi-Agent Communication Demo**（documentation）：AG-UI + A2A Multi-Agent Communication Demo 证据：`examples/showcases/a2a-travel/README.md`\n- **Repository Guidelines**（documentation）：Project Structure & Module Organization 证据：`examples/showcases/adk-dashboard/AGENTS.md`\n- **CopilotKit + ADK Generative Canvas**（documentation）：https://github.com/user-attachments/assets/9201d528-573f-43cc-9d31-571c362318a7 证据：`examples/showcases/adk-dashboard/README.md`\n- **CopilotKit Demo App**（documentation）：This demo application highlights the capabilities of CopilotKit by demonstrating how to build an app that emphasizes authorization, supports multiple operations, and incorporates generative UI elements. The banking application scenario serves as a practical example of these features in action. 证据：`examples/showcases/banking/README.md`\n- **Open ChatKit Studio**（documentation）：Explore and build embeddable chat experiences. 证据：`examples/showcases/chatkit-studio/README.md`\n- **CopilotKit Chat Playground**（documentation）：A visual playground for customizing CopilotKit chat components. Adjust colors, fonts, and text, then export production-ready code. 证据：`examples/showcases/chatkit-studio/apps/playground/README.md`\n- **🌍 CopilotKit World Explorer**（documentation）：Interactive world travel app demonstrating CopilotKit and AG-UI protocol integration with LangGraph agents. 证据：`examples/showcases/chatkit-studio/apps/world/README.md`\n- **Job Application Assistant**（documentation）：A Job assistant built with CopilotKit http://copilotkit.ai/ Next.js on the frontend and DeepAgents https://github.com/langchain-ai/deepagents by LangChain on the backend. Users upload their resume PDF , the system extracts skills and context and DeepAgents orchestrate sub-agents & tools to search the web via Tavily for relevant job postings. Results stream back to the UI in real time and are rendered alongside the chat. 证据：`examples/showcases/deep-agents-job-search/README.md`\n- **Deep Research Assistant**（documentation）：A CopilotKit https://copilotkit.ai Deep Agents demo showcasing planning, memory/files, and generative UI using Tavily https://www.tavily.com/ for web research. 证据：`examples/showcases/deep-agents/README.md`\n- **CopilotKit Demo App**（documentation）：This demo application highlights the capabilities of CopilotKit by demonstrating how to build an app that emphasizes authorization, supports multiple operations, and incorporates generative UI elements. The banking application scenario serves as a practical example of these features in action. 证据：`examples/showcases/enterprise-brex/README.md`\n- **UI Protocols Demo**（documentation）：Generative UI playground showcasing three protocols for AI-powered interfaces. 证据：`examples/showcases/generative-ui-playground/CLAUDE.md`\n- **Generative UI Demo**（documentation）：https://github.com/user-attachments/assets/79ead351-f63c-4119-9d28-9d604e7f8876 证据：`examples/showcases/generative-ui-playground/README.md`\n- **A2A Agent**（documentation）：Python A2A agent with A2UI declarative generative UI support for dynamic UI generation. 证据：`examples/showcases/generative-ui-playground/a2a-agent/CLAUDE.md`\n- **A2A UI Generator Agent**（documentation）：Python A2A agent for general-purpose UI generation with A2UI support. 证据：`examples/showcases/generative-ui-playground/a2a-agent/README.md`\n- 其余 24 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/components/content/landing-pages/README.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/components/content/landing-pages/README.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **快速入门指南**：importance `high`\n - source_paths: README.md, examples/README.md\n- **项目结构**：importance `medium`\n - source_paths: examples/canvas/gemini/package.json, examples/integrations/langgraph-fastapi/package.json\n- **系统架构**：importance `high`\n - source_paths: dev-docs/architecture/ARCHITECTURE.md, docs/content/docs/learn/architecture.mdx\n- **通信协议**：importance `high`\n - source_paths: docs/content/docs/learn/ag-ui-protocol.mdx, docs/content/docs/learn/a2a-protocol.mdx, docs/content/docs/learn/generative-ui/index.mdx\n- **Chat UI 组件**：importance `high`\n - source_paths: docs/content/docs/reference/v2/components/CopilotChat.mdx, docs/content/docs/reference/v2/components/CopilotPopup.mdx, docs/content/docs/reference/v2/components/CopilotSidebar.mdx, examples/showcases/todo/src/components/TodoItem.tsx\n- **React Hooks API**：importance `high`\n - source_paths: docs/content/docs/reference/v2/hooks/useAgent.mdx, docs/content/docs/reference/v2/hooks/useCopilotKit.mdx, docs/content/docs/reference/v2/hooks/useHumanInTheLoop.mdx, docs/content/docs/reference/v2/hooks/useThreads.mdx\n- **CopilotRuntime 后端运行时**：importance `high`\n - source_paths: docs/content/docs/backend/copilot-runtime.mdx, docs/content/docs/reference/v1/classes/CopilotRuntime.mdx, examples/canvas/langgraph-python/src/app/api/copilotkit/route.ts\n- **后端工具系统**：importance `high`\n - source_paths: docs/content/docs/(root)/frontend-tools.mdx, docs/content/docs/integrations/built-in-agent/server-tools.mdx, examples/integrations/langgraph-fastapi/agent/src/todos.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `4749ac138c54edcf3e142deb016423017d3c9adf`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/props.ts`, `docs/package-lock.json`, `docs/POSTHOG_BROKEN_LINKS.md`, `docs/vercel.json`, `docs/pnpm-lock.yaml`, `docs/source.config.ts`, `docs/pnpm-workspace.yaml`, `docs/model-allowlist.json`, `docs/package.json`, `docs/README.md`, `docs/middleware.ts`, `docs/tsconfig.json`, `docs/components.json`, `docs/docs/broken-link-handling.md`, `docs/scripts/check-broken-links.js`, `docs/scripts/verify-broken-links.js`, `docs/snippets/use-agent.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged s…\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_409f46a5944945278264fc47e297b72a | https://github.com/CopilotKit/CopilotKit/issues/4885 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：LangGraph thread history is not hydrated after cold restart until first new message\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：LangGraph thread history is not hydrated after cold restart until first new message\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e6230695b9a44704927b31badcc61437 | https://github.com/CopilotKit/CopilotKit/issues/3454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_93af324180434026b3961aff8938714f | https://github.com/CopilotKit/CopilotKit/issues/4911 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0efd9d1f363946d48e1168b691b0ad4c | https://github.com/CopilotKit/CopilotKit/issues/4893 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_f934812319464fb5acab93b86e00ed00 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 失败模式：installation: v1.55.3\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.55.3\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.55.3. Context: Observed when using node\n- Why it matters: Upgrade or migration may change expected behavior: v1.55.3\n- Evidence: failure_mode_cluster:github_release | fmev_67f1e990977177cadc4a1a612db8df88 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.55.3 | v1.55.3\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 失败模式：installation: v1.56.0\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.56.0\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.56.0. Context: Observed when using node, python\n- Why it matters: Upgrade or migration may change expected behavior: v1.56.0\n- Evidence: failure_mode_cluster:github_release | fmev_8ede7507e3ef26c20ae94eb3ff6a0f6f | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.0 | v1.56.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 失败模式：installation: v1.56.1\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.56.1\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.56.1. Context: Observed when using node\n- Why it matters: Upgrade or migration may change expected behavior: v1.56.1\n- Evidence: failure_mode_cluster:github_release | fmev_7a12898a84c35b19ec1421880ce10e28 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.1 | v1.56.1\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 失败模式：installation: v1.56.2\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.56.2\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.56.2. Context: Observed when using node\n- Why it matters: Upgrade or migration may change expected behavior: v1.56.2\n- Evidence: failure_mode_cluster:github_release | fmev_7a917a302b0681683ac2482e6cdefd4b | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.2 | v1.56.2\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 失败模式：installation: v1.56.3\n\n- Trigger: Developers should check this installation risk before relying on the project: v1.56.3\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v1.56.3. Context: Observed when using node\n- Why it matters: Upgrade or migration may change expected behavior: v1.56.3\n- Evidence: failure_mode_cluster:github_release | fmev_386de57caa0b418e81af496ef3e832e1 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.3 | v1.56.3\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：CopilotKit/CopilotKit\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：LangGraph thread history is not hydrated after cold restart until first new message（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/CopilotKit/CopilotKit 项目说明书\n\n生成时间：2026-05-17 23:57:37 UTC\n\n## 目录\n\n- [快速入门指南](#getting-started)\n- [项目结构](#project-structure)\n- [系统架构](#system-architecture)\n- [通信协议](#protocols)\n- [Chat UI 组件](#chat-ui-components)\n- [React Hooks API](#react-hooks)\n- [CopilotRuntime 后端运行时](#copilot-runtime)\n- [后端工具系统](#backend-tools)\n- [生成式 UI](#generative-ui)\n- [人在回路 (Human-in-the-Loop)](#human-in-the-loop)\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Chat UI 组件](#chat-ui-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/CopilotKit/CopilotKit/blob/main/README.md)\n- [examples/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/README.md)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [examples/v1/state-machine/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/v1/state-machine/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n \n\n# 快速入门指南\n\n本文档为开发者提供 CopilotKit 的完整快速入门路径，涵盖环境准备、安装配置、核心概念及示例运行等关键环节。\n\n---\n\n## 什么是 CopilotKit\n\nCopilotKit 是一个用于构建 AI 原生应用的框架，支持 React、Vue、Angular 等主流前端框架的无缝集成。通过 CopilotKit，开发者可以快速将 AI 能力嵌入现有应用，实现自然语言交互、工具调用代理等功能。\n\n资料来源：[README.md:1]()\n\n---\n\n## 前置要求\n\n在开始使用 CopilotKit 之前，请确保开发环境满足以下要求：\n\n| 类别 | 版本要求 |\n|------|----------|\n| Node.js | 18+ |\n| 包管理器 | npm / yarn / pnpm |\n\n资料来源：[examples/v1/form-filling/README.md:1]()\n\n---\n\n## 安装方式\n\n### 使用 Copilot Cloud（推荐）\n\nCopilot Cloud 提供托管式运行时，无需自行搭建后端服务。开发者只需获取公开 API Key 即可快速集成：\n\n```bash\nNEXT_PUBLIC_CPK_PUBLIC_API_KEY=your_copilotkit_api_key\n```\n\n> **注意**：公开 API Key 以 `ck_pub_` 开头，可从 [Copilot Cloud](https://cloud.copilotkit.ai) 获取。\n\n资料来源：[examples/v1/travel/README.md:1]()\n\n### 自托管运行时\n\n如需完全控制运行时，可选择自托管方式。使用 `runtimeUrl` 配置自定义后端：\n\n```typescript\n\n```\n\n资料来源：[packages/vue/README.md:1]()\n\n---\n\n## React 快速开始\n\n### 基础配置\n\nReact 是 CopilotKit 最成熟的集成方案。首先在应用入口处配置 Provider：\n\n```tsx\n// app/layout.tsx\nimport { CopilotKit } from \"@copilotkit/react-core\";\n\nexport default function RootLayout({ children }) {\n return (\n \n \n \n {children}\n \n \n \n );\n}\n```\n\n资料来源：[examples/v1/form-filling/README.md:1]()\n\n### CopilotKit 配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `publicApiKey` | string | 是（使用 Copilot Cloud 时） | Copilot Cloud 公开 API Key |\n| `runtimeUrl` | string | 是（自托管时） | 后端运行时地址 |\n| `headers` | Record | 否 | 默认请求头 |\n| `licenseKey` | string | 否 | Copilot Cloud 许可证密钥 |\n\n资料来源：[packages/angular/README.md:1]()\n\n### 运行时配置\n\nCopilotKit 运行时支持多种高级配置选项：\n\n```typescript\nimport { CopilotKit } from \"@copilotkit/react-core\";\n\nexport default function App() {\n return (\n \n {children}\n \n );\n}\n```\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:1]()\n\n---\n\n## Vue 快速开始\n\n### 安装依赖\n\n```bash\nnpm install @copilotkit/vue\n```\n\n### Provider 配置\n\n```vue\n\n\n\n \n \n \n\n```\n\n### 错误处理\n\nVue 集成支持统一的错误处理回调：\n\n```vue\n\n\n\n \n \n \n\n```\n\n资料来源：[packages/vue/README.md:1]()\n\n### Debug 日志配置\n\n```typescript\nimport { CopilotKitProvider, type DebugConfig } from \"@copilotkit/vue\";\n\nconst debug: DebugConfig = { \n events: true, \n lifecycle: true \n};\n```\n\n支持的值：\n\n| 值 | 说明 |\n|----|------|\n| `true` / `false` | 启用或禁用事件 + 生命周期日志 |\n| `{ events?: boolean; lifecycle?: boolean; verbose?: boolean }` | 细粒度控制 |\n\n资料来源：[packages/vue/README.md:1]()\n\n---\n\n## Angular 快速开始\n\n### 安装依赖\n\n```bash\nnpm install @copilotkit/angular\n```\n\n### Provider 配置\n\n```typescript\nimport { provideCopilotKit } from \"@copilotkit/angular\";\n\n@Component({\n // ...\n})\nexport class AppComponent {}\n```\n\n### CopilotKitConfig 配置接口\n\n```typescript\nexport interface CopilotKitConfig {\n runtimeUrl?: string;\n headers?: Record;\n licenseKey?: string;\n properties?: Record;\n agents?: Record;\n tools?: ClientTool[];\n renderToolCalls?: RenderToolCallConfig[];\n frontendTools?: FrontendToolConfig[];\n humanInTheLoop?: HumanInTheLoopConfig[];\n}\n```\n\n| 参数 | 说明 |\n|------|------|\n| `runtimeUrl` | CopilotKit 运行时 URL |\n| `headers` | 默认请求头 |\n| `licenseKey` | Copilot Cloud 公开 API Key (`ck_pub_...`) |\n| `properties` | 转发到 agent runs 的任意属性 |\n| `agents` | 浏览器内本地 agents，按 `agentId` 索引 |\n| `tools` | 运行时工具定义（无处理器） |\n| `frontendTools` | 带处理器的客户端工具 |\n| `humanInTheLoop` | 暂停等待用户输入的工具 |\n\n资料来源：[packages/angular/README.md:1]()\n\n---\n\n## 运行示例项目\n\n### 示例仓库结构\n\nCopilotKit 仓库包含 47 个综合演示项目，展示各种集成方式和应用场景。\n\n```mermaid\ngraph TD\n A[CopilotKit 示例] --> B[集成示例
17个]\n A --> C[Canvas 应用
示例]\n A --> D[Showcase
展示项目]\n A --> E[v1/v2 旧版
示例]\n \n B --> B1[LangGraph Python]\n B --> B2[LangGraph JS]\n B --> B3[Mastra]\n B --> B4[LlamaIndex]\n B --> B5[CrewAI Flows]\n \n C --> C1[LLamaIndex + Composio]\n \n D --> D1[Shell Docs]\n D --> D2[Spreadsheet]\n D --> D3[Deep Agents]\n```\n\n资料来源：[examples/README.md:1]()\n\n### 通用运行步骤\n\n大多数示例遵循统一的启动流程：\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/CopilotKit/CopilotKit.git\ncd CopilotKit\n\n# 2. 进入示例目录\ncd examples/showcases/spreadsheet\n\n# 3. 安装依赖\npnpm install\n\n# 4. 配置环境变量\ncp .env.local.example .env.local\n# 编辑 .env.local 填入必要的 API Key\n\n# 5. 启动开发服务器\npnpm dev\n\n# 6. 访问应用\n# 打开 http://localhost:3000\n```\n\n资料来源：[examples/showcases/spreadsheet/README.md:1]()\n\n### 使用状态机模式\n\n`examples/v1/state-machine` 展示了基于 CopilotKit 的状态机架构：\n\n```mermaid\ngraph LR\n S1[getContactInfo] --> S2[buildCar]\n S2 --> S3[sellFinancing]\n S3 --> S4[getFinancingInfo]\n S4 --> S5[getPaymentInfo]\n S5 --> S6[confirmOrder]\n```\n\n每个阶段都有独立的 Hook 文件：\n\n| 阶段 | Hook 文件 |\n|------|-----------|\n| 收集客户信息 | `use-stage-get-contact-info.tsx` |\n| 配置汽车选项 | `use-stage-build-car.tsx` |\n| 展示融资选项 | `use-stage-sell-financing.tsx` |\n| 收集融资详情 | `use-stage-get-financing-info.tsx` |\n| 处理支付信息 | `use-stage-get-payment-info.tsx` |\n| 确认订单 | `use-stage-confirm-order.tsx` |\n\n资料来源：[examples/v1/state-machine/README.md:1]()\n\n### 集成 LangGraph\n\n对于需要复杂代理逻辑的应用，CopilotKit 支持与 LangGraph 深度集成：\n\n```python\nfrom copilotkit import CopilotKitMiddleware\n\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-4\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md:1]()\n\n---\n\n## 数据流架构\n\nCopilotKit 采用前后端分离架构，核心数据流如下：\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as 前端 UI\n participant CK as CopilotKit\n participant Agent as AI Agent\n participant Tools\n participant External as 外部服务\n\n User->>UI: 自然语言输入\n UI->>CK: 发送消息\n CK->>Agent: 转发请求\n Agent->>Tools: 执行工具\n Tools->>External: 调用外部 API\n External-->>Tools: 返回结果\n Tools-->>Agent: 工具执行结果\n Agent->>CK: 返回响应\n CK->>UI: 更新状态\n UI->>User: 显示结果\n```\n\n---\n\n## 环境变量配置\n\n### 必填变量\n\n| 变量名 | 说明 | 获取方式 |\n|--------|------|----------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | [OpenAI Platform](https://platform.openai.com) |\n| `NEXT_PUBLIC_COPILOT_PUBLIC_API_KEY` | Copilot Cloud 公开 API Key | [Copilot Cloud](https://cloud.copilotkit.ai) |\n\n### 可选变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `COPILOT_CLOUD_PUBLIC_API_KEY` | CopilotKit Cloud 功能 |\n| `GOOGLE_MAPS_API_KEY` | 地图服务集成（部分示例需要） |\n| `COMPOSIO_API_KEY` | Composio 工具集成 |\n\n资料来源：[examples/canvas/llamaindex-composio/README.md:1]()\n\n---\n\n## 核心概念\n\n### 可读取状态（useCopilotReadable）\n\n将前端应用状态暴露给 AI 引擎：\n\n```tsx\nimport { useCopilotReadable } from \"@copilotkit/react-core\";\n\nfunction Spreadsheet() {\n const data = useRef([[\"Header\", \"Value\"]]);\n\n useCopilotReadable({\n name: \"spreadsheet data\",\n description: \"Current spreadsheet content\",\n value: data.current,\n });\n\n // ...\n}\n```\n\n### 可操作动作（useCopilotAction）\n\n定义 AI 可以执行的操作：\n\n```tsx\nimport { useCopilotAction } from \"@copilotkit/react-core\";\n\nuseCopilotAction({\n name: \"updateCell\",\n description: \"更新电子表格单元格\",\n parameters: [\n {\n name: \"cell\",\n type: \"string\",\n required: true,\n },\n {\n name: \"value\",\n type: \"string\",\n required: true,\n },\n ],\n handler: async ({ cell, value }) => {\n // 执行更新逻辑\n return { success: true };\n },\n});\n```\n\n### 工具渲染\n\n自定义工具调用的 UI 渲染：\n\n```tsx\nexport interface RenderToolCallConfig {\n name: string; // 工具名，\"*\" 表示通配符\n args: z.ZodType; // 参数 Zod schema\n component: Type>;\n agentId?: string; // 可选的 agent 作用域\n}\n```\n\n资料来源：[packages/angular/README.md:1]()\n\n---\n\n## 常见问题\n\n### 依赖冲突\n\n如果遇到 Python 导入错误：\n\n```bash\ncd agent\nuv sync\n```\n\n如问题持续，删除虚拟环境后重新创建：\n\n```bash\ncd agent\nrm -rf .venv\nuv venv\nuv sync\n```\n\n### 不同包管理器\n\n所有示例都支持多种包管理器：\n\n| 命令 | npm | yarn | pnpm |\n|------|-----|------|------|\n| 安装依赖 | `npm install` | `yarn install` | `pnpm install` |\n| 启动开发 | `npm run dev` | `yarn dev` | `pnpm dev` |\n\n资料来源：[examples/v1/form-filling/README.md:1]()\n\n---\n\n## 下一步\n\n- 查看 [官方文档](https://docs.copilotkit.ai/getting-started/quickstart-chatbot) 获取完整功能说明\n- 探索 [示例项目](https://github.com/CopilotKit/CopilotKit/tree/main/examples) 寻找灵感\n- 加入 [Discord 社区](https://discord.gg/6dffbvGU3D) 获取帮助\n- 关注 [X (Twitter)](https://x.com/copilotkit) 和 [LinkedIn](https://www.linkedin.com/company/copilotkit/) 了解最新动态\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [examples/showcases/presentation/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/presentation/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n- [examples/showcases/adk-dashboard/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/adk-dashboard/README.md)\n- [examples/integrations/langgraph-fastapi/package.json](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-fastapi/package.json)\n- [examples/integrations/ms-agent-framework-python/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/ms-agent-framework-python/README.md)\n- [showcase/integrations/langgraph-typescript/src/app/demos/gen-ui-tool-based/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/langgraph-typescript/src/app/demos/gen-ui-tool-based/README.md)\n \n\n# 项目结构\n\nCopilotKit 是一个开源的 AI 助手和代理集成框架，旨在帮助开发者快速将深度集成的 AI 功能嵌入到应用程序中。项目采用 Monorepo 架构，组织清晰，包含核心运行时包、示例项目和展示应用。\n\n## 目录架构概览\n\n```\nCopilotKit/\n├── packages/ # 核心运行时包\n├── examples/ # 示例项目集合\n├── showcase/ # 集成展示应用\n├── README.md # 项目主文档\n├── CONTRIBUTING.md # 贡献指南\n└── LICENSE # MIT 许可证\n```\n\n## 核心包（packages）\n\n核心包提供了 CopilotKit 的基础功能，包括运行时客户端、React 组件和 API 接口。\n\n| 包名称 | 说明 |\n|--------|------|\n| `runtime-client-gql` | GraphQL 运行时客户端，负责与后端代理通信 |\n| `react-textarea` | React 文本域组件，提供 AI 辅助输入功能 |\n| 其他核心包 | 提供状态管理、上下文共享、UI 组件等 |\n\n核心包的特点包括：\n\n- **分钟级集成**：通过 CLI 快速启动项目\n- **框架无关**：支持 React、Next.js、AGUI 等多种框架\n- **生产级 UI**：提供可定制的组件或无头 UI\n- **内置安全**：包含提示注入保护机制\n\n资料来源：[packages/runtime-client-gql/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime-client-gql/README.md)\n\n## 示例项目（examples）\n\n`examples` 目录包含 47 个独立演示项目，展示 CopilotKit 与各种代理框架和应用的集成方式。每个示例都是自包含的项目，需要单独克隆和配置。\n\n```bash\nGIT_LFS_SKIP_SMUDGE=1 git clone \ncd examples//\n# 按照示例的 README 进行设置\n```\n\n> **注意**：`v1/` 和 `v2/` 目录是早期版本的遗留工作区示例，不属于当前的统一演示集。\n\n资料来源：[examples/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/README.md)\n\n### 集成示例（integrations）\n\n集成示例展示了 CopilotKit 与主流代理框架的集成方式，目前共有 17 个框架集成入门模板。\n\n| 示例项目 | 说明 |\n|----------|------|\n| `langgraph-python` | 使用 LangGraph (Python) 和 CopilotKit 构建 AI 代理 |\n| `langgraph-js` | 使用 LangGraph (JS) 的 Turborepo 单仓库模板 |\n| `langgraph-fastapi` | 使用 LangGraph + FastAPI + Poetry 的模板 |\n| `mastra` | 使用 Mastra 和 CopilotKit 构建代理 |\n| `crewai-flows` | 使用 CrewAI Flows (uv-based) 的模板 |\n| `llamaindex` | LlamaIndex 投资分析师代理模板 |\n| `ms-agent-framework-python` | Microsoft Agent Framework (Python) 集成 |\n\n集成项目通常包含以下目录结构：\n\n```\n/\n├── frontend/ # Next.js 前端应用\n├── agent/ # 代理服务器代码\n├── package.json # 项目依赖配置\n└── README.md # 设置说明\n```\n\n资料来源：[examples/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/README.md)\n\n### 展示应用（showcases）\n\n展示应用提供了功能完整的 CopilotKit 集成示例，涵盖从聊天界面到复杂业务应用的多种场景。\n\n#### Deep Agents\n\n深度代理展示应用演示了如何构建支持研究工具的 AI 代理系统。\n\n**前端架构**：\n\n```typescript\n// 定义工具卡片组件\nconst researchToolCard = frame(({ props }) => {\n return ;\n});\n```\n\n**后端代理配置**：\n\n```python\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n#### Presentation\n\n演示文稿展示应用演示了如何将研究代理集成到幻灯片应用中。\n\n#### Spreadsheet\n\n电子表格展示应用允许用户通过自然语言请求构建预算表格。\n\n**关键代码位置**：\n\n- `/api/copilotkit/route.ts` - 研究代理 API 路由\n- `/api/copilotkit/tavily.ts` - Tavily 研究 API 集成\n- `useCopilotReadable` - 前端上下文共享钩子\n- `updateSpreadsheet`、`appendToSpreadsheet`、`createSpreadsheet` - 表格操作钩子\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n#### ADK Dashboard\n\nGoogle Agent Development Kit (ADK) 仪表板展示应用。\n\n**目录结构**：\n\n```\nadk-dashboard/\n├── src/app/ # Next.js 应用代码\n├── agent/ # ADK 代理代码\n├── package.json\n└── .env.local\n```\n\n**环境变量配置**：\n\n| 变量名 | 说明 |\n|--------|------|\n| `GOOGLE_API_KEY` | Google API 凭证 |\n| `OPENAI_API_KEY` | OpenAI API 凭证 |\n\n资料来源：[examples/showcases/adk-dashboard/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/adk-dashboard/README.md)\n\n## 展示目录（showcase）\n\n`showcase` 目录包含与最新代理框架集成的演示应用，采用统一的项目结构。\n\n### 通用项目结构\n\n```\nshowcase/integrations//\n├── src/\n│ └── app/\n│ ├── demos/\n│ │ └── gen-ui-tool-based/\n│ │ └── README.md # 演示说明\n│ ├── page.tsx # 主页面\n│ └── layout.tsx # 布局组件\n├── package.json\n├── next.config.js\n└── tailwind.config.ts\n```\n\n### 关键钩子\n\n| 钩子名称 | 功能 |\n|----------|------|\n| `useAgent` | 原始代理句柄，提供 `messages`、`isRunning`、`addMessage` 等 |\n| `useCopilotKit` | 暴露 `connectAgent`、`runAgent`、`stopAgent` 方法 |\n\n资料来源：[showcase/integrations/langgraph-typescript/src/app/demos/gen-ui-tool-based/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/langgraph-typescript/src/app/demos/gen-ui-tool-based/README.md)\n\n### 无头聊天（Headless Chat）\n\n无头聊天演示展示了如何使用低级钩子从零构建完整的聊天 UI，而不依赖预构建组件。\n\n**核心文件**：\n\n| 文件 | 说明 |\n|------|------|\n| `page.tsx` | 提供者、代理连接、发送/停止处理器、工具调用渲染器注册 |\n| `message-list.tsx` | 可滚动消息区域、用户/助手气泡、输入指示器 |\n| `use-rendered-messages.tsx` | 按角色分发消息渲染 |\n\n资料来源：[showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md)\n\n## 可用脚本\n\n### 集成项目脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `dev` | 启动 UI + 代理服务器（默认） |\n| `dev:debug` | 启用调试日志启动 |\n| `dev:ui` | 仅启动 Next.js UI 服务器 |\n| `dev:agent` | 仅启动代理服务器 |\n| `build` | 生产环境构建 |\n| `start` | 启动生产服务器 |\n| `lint` | 运行 ESLint 代码检查 |\n| `install:agent` | 安装代理 Python 依赖 |\n\n资料来源：[examples/integrations/ms-agent-framework-python/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/ms-agent-framework-python/README.md)\n\n## 架构流程图\n\n### 应用架构\n\n```mermaid\ngraph TD\n A[用户界面] --> B[CopilotKit 前端组件]\n B --> C[useCopilotKit 钩子]\n C --> D[运行时客户端]\n D --> E[代理中间件]\n E --> F[AI 代理框架]\n F --> G[外部 API / 工具]\n G --> F\n F --> E\n E --> D\n D --> C\n C --> B\n B --> A\n```\n\n### 代理通信流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant F as 前端组件\n participant R as 运行时客户端\n participant M as 代理中间件\n participant A as AI 代理\n \n U->>F: 发送消息\n F->>R: addMessage\n R->>M: 转发请求\n M->>A: 调用代理\n A->>A: 处理任务\n A->>G: 使用工具\n G-->>A: 返回结果\n A-->>M: 返回响应\n M-->>R: 格式化结果\n R-->>F: 更新状态\n F-->>U: 显示结果\n```\n\n## 技术栈概览\n\n| 层级 | 技术选型 |\n|------|----------|\n| 前端框架 | React、Next.js |\n| 样式方案 | Tailwind CSS |\n| 代理框架 | LangGraph、Mastra、CrewAI、LlamaIndex、ADK 等 |\n| 后端服务 | FastAPI、Python 运行时 |\n| 部署方式 | Vercel、容器化 |\n\n## 环境配置\n\n### 常见环境变量\n\n| 变量 | 说明 | 必需 |\n|------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 是 |\n| `GOOGLE_API_KEY` | Google API 密钥 | ADK 示例必需 |\n| `TAVILY_API_KEY` | Tavily 研究 API | 研究代理示例必需 |\n\n### 端口配置\n\n| 服务 | 默认端口 |\n|------|----------|\n| Next.js UI | 3000 |\n| Python 代理 | 8000 |\n| FastAPI 服务 | 8000 |\n\n## 贡献指南\n\nCopilotKit 欢迎各种形式的贡献，包括代码、文档、演示应用创建或社区推广。\n\n- **代码贡献**：参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)\n- **文档贡献**：参阅 [文档贡献指南](https://docs.copilotkit.ai/contributing/docs-contributions)\n- **社区支持**：[Discord 服务器](https://discord.gg/6dffbvGU3D)\n\n## 许可证\n\n本项目源码采用 MIT 许可证开源。\n\n资料来源：[README.md - License](https://github.com/CopilotKit/CopilotKit/blob/main/LICENSE)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[CopilotRuntime 后端运行时](#copilot-runtime), [通信协议](#protocols)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [examples/showcases/presentation/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/presentation/README.md)\n \n\n# 系统架构\n\n## 概述\n\nCopilotKit 是一个用于构建 AI 原生应用的框架，提供了前端组件、运行时引擎和工具集成能力。其核心架构采用分层设计，涵盖前端 UI 组件层、运行时客户端层、后端运行时层以及多种框架集成适配层。\n\n## 核心架构分层\n\n### 技术栈概览\n\n| 层级 | 技术范围 | 主要职责 |\n|------|----------|----------|\n| 前端组件层 | React、Vue、Angular | 提供可嵌入的 Copilot 聊天界面和交互组件 |\n| 运行时客户端层 | @copilotkit/react、@copilotkit/vue、@copilotkit/angular | 管理状态、消息传递和工具调用 |\n| 运行时引擎层 | @copilotkit/runtime | 处理 LLM 请求、工具执行和上下文管理 |\n| 框架集成层 | LangGraph、Mastra、CrewAI、LlamaIndex | 与主流 AI 代理框架集成 |\n\n## 运行时架构\n\n### CopilotRuntime 核心配置\n\n`CopilotRuntime` 是后端运行时的核心类，负责处理来自前端的请求并与 LLM 进行交互。\n\n```typescript\n// 资料来源：packages/runtime/src/lib/runtime/copilot-runtime.ts\nconst copilotRuntime = new CopilotRuntime({\n runtimeUrl: \"/api/copilotkit\",\n publicApiKey: process.env.COPILOT_CLOUD_PUBLIC_API_KEY,\n});\n```\n\n### 运行时配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `runtimeUrl` | `string` | CopilotKit 运行时端点地址 |\n| `publicApiKey` | `string` | Copilot Cloud 公共 API 密钥 (`ck_pub_...`) |\n| `headers` | `Record` | 默认请求头 |\n| `licenseKey` | `string` | 许可证密钥 |\n| `properties` | `Record` | 转发到 agent 运行的自定义属性 |\n| `agents` | `Record` | 本地浏览器内代理 |\n| `tools` | `ClientTool[]` | 工具定义 |\n| `renderToolCalls` | `RenderToolCallConfig[]` | 工具调用 UI 渲染配置 |\n| `frontendTools` | `FrontendToolConfig[]` | 客户端工具配置 |\n| `humanInTheLoop` | `HumanInTheLoopConfig[]` | 需要用户输入的工具 |\n| `mcpServers` | `MCPEndpointConfig[]` | MCP 服务器配置 |\n| `logging` | `CopilotObservabilityConfig` | 日志和可观测性配置 |\n\n### 可观测性配置\n\n```typescript\n// 资料来源：packages/runtime/src/lib/runtime/copilot-runtime.ts\nlogging: {\n enabled: true, // 启用日志\n progressive: true, // 流式日志输出\n logger: {\n logRequest: (data) => langfuse.trace({ name: \"LLM Request\", input: data }),\n logResponse: (data) => langfuse.trace({ name: \"LLM Response\", output: data }),\n logError: (errorData) => langfuse.trace({ name: \"LLM Error\", metadata: errorData }),\n },\n}\n```\n\n## 前端框架集成\n\n### React 集成\n\nReact SDK 提供核心组件和 Hook：\n\n| 组件/Hook | 功能 |\n|-----------|------|\n| `CopilotKit` | 根组件，配置运行时连接 |\n| `CopilotChat` | 聊天界面组件 |\n| `useCopilotReadable` | 将应用状态同步到 Copilot 引擎 |\n| `useCopilotAction` | 定义可被代理调用的动作 |\n| `useCoAgent` | 与代理状态双向同步 |\n\n### Vue 集成\n\nVue SDK 通过 `CopilotKitProvider` 和 `CopilotChatMessageView` 提供聊天消息渲染能力：\n\n```vue\n// 资料来源：packages/vue/README.md\n\n \n\n```\n\n### Angular 集成\n\nAngular 通过 `provideCopilotKit` 注入配置：\n\n```typescript\n// 资料来源：packages/angular/README.md\nexport interface CopilotKitConfig {\n runtimeUrl?: string;\n headers?: Record;\n licenseKey?: string;\n properties?: Record;\n agents?: Record;\n tools?: ClientTool[];\n renderToolCalls?: RenderToolCallConfig[];\n frontendTools?: FrontendToolConfig[];\n humanInTheLoop?: HumanInTheLoopConfig[];\n}\n```\n\n## 数据流架构\n\n### 完整数据流\n\n```mermaid\ngraph TD\n User[用户交互] --> UI[前端 UI 组件]\n UI --> CK[CopilotKit 客户端]\n CK --> Runtime[CopilotRuntime]\n Runtime --> LLM[LLM Provider]\n LLM --> Runtime\n Runtime --> Agent[AI Agent 框架]\n Agent --> Tools[工具执行]\n Tools --> External[外部服务]\n External --> Tools\n Tools --> Agent\n Agent --> Runtime\n Runtime --> CK\n CK --> UI\n UI --> User\n \n subgraph 前端层\n UI\n CK\n end\n \n subgraph 后端层\n Runtime\n LLM\n Agent\n Tools\n end\n```\n\n### LlamaIndex + Composio 示例数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant UI as Canvas UI\n participant CK as CopilotKit\n participant Agent as LlamaIndex Agent\n participant Tools as 工具\n participant Composio as Composio\n participant GSheets as Google Sheets\n\n User->>UI: 与画布交互\n UI->>CK: 通过 useCoAgent 更新状态\n CK->>Agent: 发送状态 + 消息\n Agent->>Agent: 使用 GPT-4o 处理\n Agent->>Tools: 执行工具\n \n alt Google Sheets 同步\n Agent->>Composio: 执行 sheets_sync_all\n Composio->>GSheets: 更新电子表格\n GSheets-->>Composio: 确认更新\n Composio-->>Agent: 返回状态\n end\n\n Tools-->>Agent: 返回结果\n Agent->>CK: 返回更新后的状态\n CK->>UI: 同步状态变更\n UI->>User: 显示更新\n\n Note over Agent: 维护真相来源\n Note over UI,CK: 实时双向同步\n Note over Composio,GSheets: 外部工具集成\n```\n\n## 工具系统架构\n\n### 工具类型体系\n\n| 工具类型 | 说明 | 配置方式 |\n|----------|------|----------|\n| 客户端工具 | 前端执行的工具 | `FrontendToolConfig` |\n| 服务端工具 | 后端执行的工具 | `ClientTool` |\n| 远程工具 | 由代理运行时处理 | `available: \"remote\"` |\n| 人机交互工具 | 需要用户确认 | `HumanInTheLoopConfig` |\n\n### 工具定义接口\n\n```typescript\n// 资料来源：packages/angular/README.md\nexport interface FrontendToolConfig {\n name: string;\n description: string;\n parameters: z.ZodType;\n component?: Type>;\n handler: (args: Args, context: FrontendToolHandlerContext) => Promise;\n agentId?: string;\n}\n\nexport interface RenderToolCallConfig {\n name: string; // 工具名称，\"*\" 表示通配符\n args: z.ZodType; // 参数 Zod schema\n component: Type>;\n agentId?: string; // 可选的代理作用域\n}\n```\n\n### 工具渲染器\n\n工具调用通过渲染器组件显示：\n\n```typescript\n// 资料来源：packages/angular/README.md\nexport interface ToolRenderer {\n toolCall: Signal>;\n}\n\nexport interface HumanInTheLoopToolRenderer {\n toolCall: Signal>; // 包含 respond(result)\n}\n```\n\n## 代理架构\n\n### 代理配置\n\n代理通过配置与 CopilotKit 集成：\n\n```python\n# 资料来源：examples/showcases/deep-agents/README.md\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n### 支持的代理框架\n\n| 框架 | 语言 | 集成方式 |\n|------|------|----------|\n| LangGraph | Python | `CopilotKitMiddleware` |\n| LangGraph | JS/TS | Turborepo monorepo |\n| Mastra | TypeScript | 原生集成 |\n| CrewAI Flows | Python | uv-based 工作流 |\n| LlamaIndex | Python | `get_ag_ui_workflow_router` |\n\n## 消息渲染系统\n\n### Vue 消息插槽\n\n```vue\n// 资料来源：packages/vue/README.md\n\n \n \n \n \n \n \n \n \n \n \n \n\n```\n\n### 支持的插槽类型\n\n| 消息级插槽 | 工具级插槽 |\n|------------|------------|\n| `message-before` | `tool-call-` |\n| `assistant-message` | `tool-call` (后备) |\n| `user-message` | |\n| `reasoning-message` | |\n| `activity-` | |\n| `activity-message` | |\n| `message-after` | |\n| `cursor` | |\n\n## MCP 协议集成\n\n### MCP 服务器配置\n\n```typescript\n// 资料来源：packages/runtime/src/lib/runtime/copilot-runtime.ts\nmcpServers?: MCPEndpointConfig[];\n```\n\nMCP（Model Context Protocol）允许连接外部 MCP 兼容服务器，获取其定义的工具：\n\n> **配置说明：** 使用 `experimental_createMCPClient` 函数创建 MCP 客户端实例，支持 `@copilotkit/runtime` 和 `ai` 库。\n\n## 状态管理\n\n### 全局状态同步\n\n```typescript\n// 资料来源：examples/v1/state-machine/README.md\n// 通过 useCopilotReadable 同步应用状态\nuseCopilotReadable({\n instructions: \"提供当前表单状态\",\n getValue: () => ({\n stage: currentStage,\n data: formData,\n progress: calculateProgress(),\n }),\n});\n```\n\n### 阶段化状态机模式\n\n| 阶段 | 文件位置 | 功能 |\n|------|----------|------|\n| getContactInfo | `use-stage-get-contact-info.tsx` | 收集客户信息 |\n| buildCar | `use-stage-build-car.tsx` | 配置汽车选项 |\n| sellFinancing | `use-stage-sell-financing.tsx` | 展示融资方案 |\n| getFinancingInfo | `use-stage-get-financing-info.tsx` | 收集融资详情 |\n| getPaymentInfo | `use-stage-get-payment-info.tsx` | 处理支付信息 |\n| confirmOrder | `use-stage-confirm-order.tsx` | 确认订单 |\n\n## 部署架构\n\n### 典型部署拓扑\n\n```mermaid\ngraph LR\n subgraph 前端\n NextJS[Next.js 应用]\n ReactApp[React 应用]\n end\n \n subgraph CopilotKit 层\n CKProvider[CopilotKit Provider]\n CKRuntime[运行时服务]\n end\n \n subgraph 代理框架\n LangGraph[LangGraph]\n Mastra[Mastra]\n LlamaIndex[LlamaIndex]\n end\n \n subgraph 外部服务\n OpenAI[OpenAI API]\n Tavily[Tavily 搜索]\n Composio[Composio]\n end\n \n NextJS --> CKProvider\n ReactApp --> CKProvider\n CKProvider --> CKRuntime\n CKRuntime --> LangGraph\n CKRuntime --> Mastra\n CKRuntime --> LlamaIndex\n LangGraph --> OpenAI\n LangGraph --> Tavily\n LlamaIndex --> Composio\n Composio --> ExternalApps[外部应用]\n```\n\n### 环境变量配置\n\n| 变量 | 示例 | 用途 |\n|------|------|------|\n| `COPILOT_CLOUD_PUBLIC_API_KEY` | `ck_pub_...` | CopilotKit Cloud 功能 |\n| `OPENAI_API_KEY` | `sk-...` | LLM API 密钥 |\n| `COMPOSIO_API_KEY` | `...` | Composio 集成 |\n| `TAVILY_API_KEY` | `...` | 在线研究功能 |\n\n## 调试与日志\n\n### Provider 调试配置\n\n```typescript\n// 资料来源：packages/vue/README.md\nconst debug: DebugConfig = { \n events: true, \n lifecycle: true,\n verbose: true // 启用完整事件载荷\n};\n```\n\n### 调试粒度控制\n\n| 配置项 | 说明 |\n|--------|------|\n| `events` | 启用事件日志 |\n| `lifecycle` | 启用生命周期日志 |\n| `verbose` | 输出完整事件载荷 |\n\n### 错误处理\n\n```typescript\n// 资料来源：packages/vue/README.md\nfunction onProviderError(event: {\n code: string;\n error: Error;\n context: Record;\n}) {\n console.error(\n \"CopilotKit provider error\",\n event.code,\n event.context,\n event.error,\n );\n}\n```\n\n## 相关文档\n\n- [快速开始指南](https://docs.copilotkit.ai/getting-started/quickstart-chatbot)\n- [前端工具开发](https://docs.copilotkit.ai/core-concepts/tools)\n- [代理开发](https://docs.copilotkit.ai/core-concepts/agents)\n- [深度代理文档](https://docs.copilotkit.ai/integrations/langgraph/deep-agents)\n\n---\n\n\n\n## 通信协议\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [生成式 UI](#generative-ui)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/integrations/a2a-middleware/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/a2a-middleware/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n \n\n# 通信协议\n\nCopilotKit 是一个多代理协作框架，支持多种通信协议以实现不同组件、代理和外部服务之间的高效交互。本文档详细介绍 CopilotKit 中的核心通信协议架构，包括 A2A 协议、AG-UI 协议、MCP 协议以及内部消息转换机制。\n\n## 协议概述\n\nCopilotKit 采用分层协议架构，支持从前端 UI 到后端代理、从单个应用到外部服务的全链路通信。\n\n### 协议层次架构\n\n```mermaid\ngraph TD\n A[前端 UI 层] --> B[AG-UI 协议]\n B --> C[CopilotKit Runtime]\n C --> D[A2A 协议]\n D --> E[多代理协调层]\n C --> F[MCP 协议]\n F --> G[外部 MCP 服务器]\n E --> H[LangGraph Agents]\n E --> I[其他 Agent 框架]\n```\n\nCopilotKit 的协议支持包括：\n\n| 协议名称 | 全称 | 用途 | 数据格式 |\n|---------|------|------|----------|\n| AG-UI | Agent-User Interface | AI 代理与应用 UI 的双向通信 | JSON/GraphQL |\n| A2A | Agent-to-Agent | 多代理之间的任务协作 | JSON over HTTP |\n| MCP | Model Context Protocol | 与外部工具和服务的集成 | JSON-RPC |\n| GraphQL | Graph Query Language | 运行时内部消息传递 | GraphQL |\n\n资料来源：[examples/integrations/a2a-middleware/README.md]()\n\n## AG-UI 协议\n\nAG-UI（Agent-User Interface）协议是 CopilotKit 的核心协议，定义了 AI 代理与应用界面之间的标准通信方式。该协议支持生成式 UI 渲染、实时状态同步和工具调用等功能。\n\n### 数据流架构\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as Canvas UI\n participant CK as CopilotKit\n participant Agent as LlamaIndex Agent\n participant Tools\n participant Composio\n participant GSheets as Google Sheets\n\n User->>UI: Interact with canvas\n UI->>CK: Update state via useCoAgent\n CK->>Agent: Send state + message\n Agent->>Agent: Process with GPT-4o\n Agent->>Tools: Execute tools\n\n alt Google Sheets Sync\n Agent->>Composio: Execute sheets_sync_all\n Composio->>GSheets: Update spreadsheet\n GSheets-->>Composio: Confirm update\n Composio-->>Agent: Return status\n end\n\n Tools-->>Agent: Return results\n Agent->>CK: Return updated state\n CK->>UI: Sync state changes\n UI->>User: Display updates\n```\n\n### 消息转换机制\n\nCopilotKit Runtime 内部使用 `aguiToGQL` 函数将 AG-UI 协议消息转换为 GraphQL 格式，以支持统一的内部消息处理：\n\n```typescript\nimport { aguiToGQL } from \"../../graphql/message-conversion/agui-to-gql\";\n```\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:19]()\n\n## A2A 协议\n\nA2A（Agent-to-Agent）协议是 CopilotKit 用于多代理协作的通信标准。通过 A2A 中间件，CopilotKit 可以与基于不同框架构建的专门代理进行通信。\n\n### 架构设计\n\n```mermaid\ngraph LR\n A[Next.js UI
CopilotKit] -->|AG-UI 协议| B[A2A Middleware]\n B -->|A2A 协议| C[Research Agent
LangGraph]\n B -->|A2A 协议| D[Analysis Agent
Mastra]\n B -->|A2A 协议| E[Custom Agent
任意框架]\n```\n\n### A2A 中间件配置\n\nA2A 中间件通过 `A2AMiddlewareAgent` 类实现，支持配置多个代理端点：\n\n```typescript\nimport { A2AMiddlewareAgent } from \"@copilotkit/runtime\";\n\nconst a2aMiddlewareAgent = new A2AMiddlewareAgent({\n agentUrls: [\n researchAgentUrl,\n analysisAgentUrl,\n newAgentUrl,\n ],\n});\n```\n\n资料来源：[examples/integrations/a2a-middleware/README.md]()\n\n### 代理注册流程\n\n添加新代理到 A2A 中间件的完整流程：\n\n| 步骤 | 操作 | 位置 |\n|------|------|------|\n| 1 | 在指定端口运行代理服务 | `agents/new_agent.py` |\n| 2 | 注册代理 URL 到中间件 | `app/api/copilotkit/route.ts` |\n| 3 | 添加开发脚本到 package.json | `package.json` |\n| 4 | 更新并发运行命令 | `concurrently` 配置 |\n\n### 代理通信示例\n\n代理通过标准化的消息格式进行通信：\n\n```json\n{\n \"agentId\": \"research-agent\",\n \"capabilities\": [\"web-search\", \"content-analysis\"],\n \"skills\": [\"research\", \"fact-checking\"],\n \"message\": {\n \"type\": \"task\",\n \"content\": \"Research AI trends in 2024\"\n }\n}\n```\n\n## MCP 协议\n\nMCP（Model Context Protocol）协议用于连接 CopilotKit 与外部 MCP 兼容服务器，使代理能够调用远程定义的工具。\n\n### MCP 配置选项\n\nCopilotKit Runtime 支持通过 `mcpServers` 配置项连接外部 MCP 服务器：\n\n```typescript\nconst copilotKit = new CopilotRuntime({\n mcpServers: [\n {\n url: \"https://mcp-server.example.com\",\n name: \"external-tools\",\n },\n ],\n experimental_createMCPClient: async (endpoint) => {\n // 创建 MCP 客户端实例\n },\n});\n```\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:89-110]()\n\n### MCP 端点配置\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `url` | string | MCP 服务器地址 |\n| `name` | string | 服务器标识名称 |\n| `headers` | Record | 认证和自定义请求头 |\n\n## 生成式 UI 协议\n\n生成式 UI（Generative UI）是 CopilotKit 的独特能力，允许代理动态生成用户界面组件。\n\n### 工具调用渲染\n\n通过 `useCopilotAction` 钩子注册工具调用的 UI 渲染：\n\n```tsx\nimport { useCopilotAction } from \"@copilotkit/core\";\n\nuseCopilotAction({\n name: \"hello_world\",\n description: \"Say hello to the user\",\n available: \"remote\",\n parameters: [\n {\n name: \"name\",\n type: \"string\",\n required: true,\n description: \"The name to greet\",\n },\n ],\n handler: ({ name }) => {\n return `Hello, ${name}!`;\n },\n});\n```\n\n### 前端工具与后端工具\n\n| 工具类型 | 定义位置 | 调用方式 | 示例 |\n|----------|----------|----------|------|\n| 后端工具 | Python/LlamaIndex | 通过 A2A 执行 | `research()`, `analyze()` |\n| 前端工具 | TypeScript/React | 浏览器端处理 | `highlightText()`, `showCard()` |\n\n资料来源：[examples/canvas/llamaindex-composio/README.md]()\n\n## LangGraph 集成协议\n\nCopilotKit 通过中间件模式与 LangGraph 深度集成，支持复杂的多代理工作流。\n\n### 中间件集成方式\n\n```python\nfrom copilotkit import CopilotKitMiddleware\n\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md]()\n\n### 状态同步协议\n\nLangGraph 代理通过 CopilotKit 运行时保持与应用状态的实时双向同步：\n\n```mermaid\ngraph LR\n A[应用状态] <-->|useCoAgent| B[CopilotKit Runtime]\n B <-->|AG-UI| C[LangGraph Agent]\n C <-->|MCP| D[外部工具]\n```\n\n## 传输层配置\n\n### 运行时传输方式\n\nCopilotKit 支持多种传输层配置：\n\n| 传输方式 | 描述 | 适用场景 |\n|----------|------|----------|\n| REST | 标准 HTTP 请求响应 | 简单同步调用 |\n| Streamable | 流式传输 | 实时生成内容 |\n| Single | 单次往返 | 轻量级集成 |\n\n### 头信息配置\n\n运行时支持自定义 HTTP 头，用于认证和元数据传递：\n\n```typescript\nconst copilotKit = new CopilotRuntime({\n runtimeUrl: \"/api/copilotkit\",\n headers: {\n \"Authorization\": \"Bearer token\",\n \"X-Custom-Header\": \"value\",\n },\n});\n```\n\n## 协议安全考虑\n\n### 公共 API 密钥\n\n使用 Copilot Cloud 服务时需要配置公钥：\n\n```tsx\n\n```\n\n### 头部注入防护\n\nCopilotKit 内置提示注入防护机制，所有外部输入通过协议层时都会经过安全验证。\n\n## 相关资源\n\n- [AG-UI 协议文档](https://docs.ag-ui.com)\n- [A2A 协议规范](https://a2a-protocol.org)\n- [LangGraph 文档](https://langchain-ai.github.io/langgraph/)\n- [CopilotKit 文档](https://docs.copilotkit.ai)\n\n---\n\n\n\n## Chat UI 组件\n\n### 相关页面\n\n相关主题：[React Hooks API](#react-hooks), [人在回路 (Human-in-the-Loop)](#human-in-the-loop)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/react-ui/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-ui/README.md)\n- [showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md)\n- [showcase/integrations/ms-agent-python/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-python/src/app/demos/headless-complete/README.md)\n- [packages/angular/src/lib/components/chat/copilot-chat-input.types.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/src/lib/components/chat/copilot-chat-input.types.ts)\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n \n\n# Chat UI 组件\n\n## 概述\n\nCopilotKit 的 Chat UI 组件是一套用于构建 AI 对话界面的 React/Vue/Angular 组件库。这些组件提供了开箱即用的对话体验，包括消息展示、输入处理、工具调用渲染等功能，同时支持高度定制以满足不同应用场景的需求。\n\nChat UI 组件的主要特点包括：\n\n- **开箱即用的 UI 组件**：提供完整的聊天界面实现，无需从零开始构建\n- **生成式 UI 支持**：支持 AI 动态生成的用户界面组件\n- **工具调用渲染**：自动渲染代理调用的工具及其结果\n- **多框架支持**：提供 React、Vue 和 Angular 的实现\n- **可组合性**：所有组件都可以独立使用或组合使用\n\n资料来源：[packages/react-ui/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-ui/README.md)\n\n## 组件架构\n\nCopilotKit 的 Chat UI 采用分层架构，从底层到顶层依次为：\n\n```mermaid\ngraph TD\n A[应用层] --> B[Chat UI 组件层]\n B --> C[React Core Hooks]\n C --> D[Runtime Client]\n D --> E[后端 Agent]\n \n B1[CopilotChat] --> B2[CopilotChatMessageView]\n B2 --> B3[CopilotChatInput]\n B3 --> B4[useAgent Hook]\n \n F[Headless 模式] --> B4\n```\n\n### 核心组件层级\n\n| 层级 | 组件 | 说明 |\n|------|------|------|\n| UI 层 | CopilotChat / CopilotPopup / CopilotSidebar | 完整聊天界面组件 |\n| 消息层 | CopilotChatMessageView | 消息展示与渲染 |\n| 输入层 | CopilotChatInput | 文本输入与控制 |\n| 钩子层 | useAgent / useCopilotKit | 核心状态管理 |\n\n资料来源：[showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md)\n\n## 主要组件类型\n\n### CopilotChat\n\n完整的聊天界面组件，包含消息列表和输入框。这是构建标准聊天体验的主要组件。\n\n**功能特性：**\n\n- 内置消息列表，支持滚动和自动滚动到最新消息\n- 集成的文本输入区域\n- 打字指示器显示\n- 工具调用渲染区域\n\n### CopilotPopup\n\n弹出式对话窗口组件，适用于需要临时呼出 AI 助手的场景。\n\n**典型使用场景：**\n\n- 浮动助手按钮触发\n- 模态框式对话\n- 侧边栏集成\n\n### CopilotSidebar\n\n侧边栏形式的对话组件，适合长时间对话或需要边浏览边对话的场景。\n\n资料来源：[packages/react-ui/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-ui/README.md)\n\n## Headless 模式\n\nHeadless 模式允许开发者完全从底层钩子构建自定义的聊天界面，而不依赖预建的 UI 组件。这是展示组件高度可组合性的最佳实践。\n\n### 核心钩子\n\n```mermaid\ngraph LR\n A[useAgent] --> B[返回 messages]\n A --> C[返回 isRunning]\n A --> D[返回 addMessage]\n \n E[useCopilotKit] --> F[connectAgent]\n E --> G[runAgent]\n E --> H[stopAgent]\n \n I[useRenderToolCall] --> J[渲染工具调用结果]\n```\n\n#### useAgent\n\n提供原生的代理句柄，访问对话状态和操作：\n\n```tsx\nconst agent = useAgent({ agentId, threadId });\n\n// 可访问的属性\nagent.messages // 消息列表\nagent.isRunning // 运行状态\nagent.addMessage() // 添加消息方法\n```\n\n#### useCopilotKit\n\n暴露运行时连接方法，用于驱动代理执行：\n\n```tsx\nconst { connectAgent, runAgent, stopAgent } = useCopilotKit();\n\n// 连接代理\nconnectAgent({ agentId });\n\n// 运行代理\nrunAgent({ agentId, message });\n\n// 停止执行\nstopAgent();\n```\n\n#### useRenderToolCall\n\n将工具调用转换为渲染的 React 节点：\n\n```tsx\nconst renderToolCall = useRenderToolCall();\n\nconst renderedNode = renderToolCall(toolCallEntry);\n```\n\n资料来源：[showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md)\n\n### Headless 实现示例\n\n一个完整的 Headless 聊天实现通常包含以下文件结构：\n\n```\npage.tsx # 提供者、代理连接、事件处理\nmessage-list.tsx # 消息容器、用户/助手消息气泡\nuse-rendered-messages.tsx # 消息角色分发、渲染逻辑\n```\n\n**文件职责：**\n\n| 文件 | 职责 |\n|------|------|\n| page.tsx | Provider 配置、agent 连接、send/stop 处理器、工具注册、输入栏 |\n| message-list.tsx | 滚动消息区域、用户/助手气泡、输入指示器 |\n| use-rendered-messages.tsx | 消息角色分发、工具调用渲染、reasoning 渲染 |\n\n资料来源：[showcase/integrations/ms-agent-python/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-python/src/app/demos/headless-complete/README.md)\n\n## 消息渲染系统\n\n### 消息类型\n\nCopilotKit 支持多种消息类型的渲染：\n\n| 消息类型 | 说明 | 渲染方式 |\n|----------|------|----------|\n| user | 用户消息 | 用户消息气泡 |\n| assistant | 助手文本消息 | 助手消息气泡 |\n| toolCall | 工具调用 | 工具卡片/组件 |\n| reasoning | 推理过程 | 推理折叠区域 |\n| activity | 活动消息 | 活动指示器 |\n\n### 工具调用渲染\n\n工具调用渲染是 CopilotKit 的核心功能之一，支持后端工具和前端工具两种模式：\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as Chat UI\n participant Agent as Agent Runtime\n participant Backend as Backend Tools\n participant Frontend as Frontend Tools\n\n User->>UI: 发送消息\n UI->>Agent: 转发请求\n Agent->>Backend: 调用后端工具\n Backend-->>Agent: 返回结果\n Agent->>Frontend: 前端工具调用\n Frontend-->>Agent: 返回结果\n Agent-->>UI: 返回消息 + 工具调用\n UI->>UI: 渲染工具结果\n```\n\n#### 前端工具注册\n\n使用 `useCopilotAction` 注册前端工具：\n\n```tsx\nuseCopilotAction({\n name: \"show_card\",\n description: \"显示卡片信息\",\n parameters: [\n {\n name: \"title\",\n type: \"string\",\n required: true,\n },\n {\n name: \"body\",\n type: \"string\",\n required: true,\n },\n ],\n handler: ({ title, body }) => {\n // 处理工具调用\n return \"Card displayed\";\n },\n});\n```\n\n#### 后端工具渲染\n\n后端工具通过 `useRenderToolCall` 进行渲染：\n\n```tsx\nuseRenderToolCall({\n toolCall: toolCallEntry,\n render: (props) => ,\n});\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n## 聊天输入配置\n\n### Angular 组件类型定义\n\n在 Angular 实现中，聊天输入组件提供了丰富的配置选项：\n\n```typescript\ninterface CopilotChatInputConfig {\n mode?: CopilotChatInputMode;\n toolsMenu?: (ToolsMenuItem | \"-\")[];\n autoFocus?: boolean;\n additionalToolbarItems?: TemplateRef;\n value?: string;\n class?: string;\n}\n```\n\n### 输入插槽配置\n\n```typescript\ninterface CopilotChatInputSlots {\n textArea?: Type | TemplateRef;\n sendButton?: Type | TemplateRef;\n startTranscribeButton?: Type | TemplateRef;\n cancelTranscribeButton?: Type | TemplateRef;\n finishTranscribeButton?: Type | TemplateRef;\n addFileButton?: Type | TemplateRef;\n toolsButton?: Type | TemplateRef;\n toolbar?: Type | TemplateRef;\n audioRecorder?: Type | TemplateRef;\n}\n```\n\n### 输出事件\n\n```typescript\ninterface CopilotChatInputOutputs {\n submitMessage: (value: string) => void;\n startTranscribe: () => void;\n cancelTranscribe: () => void;\n finishTranscribe: () => void;\n addFile: () => void;\n changeValue: (value: string) => void;\n}\n```\n\n资料来源：[packages/angular/src/lib/components/chat/copilot-chat-input.types.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/src/lib/components/chat/copilot-chat-input.types.ts)\n\n## 组件集成流程\n\n### 标准集成模式\n\n```mermaid\ngraph TD\n A[应用入口] --> B[CopilotKitProvider]\n B --> C[CopilotChat 组件]\n \n D[配置运行时] --> B\n D1[runtimeUrl] --> D\n D2[agents] --> D\n \n C --> E[消息列表]\n C --> F[输入区域]\n \n E --> G[useRenderedMessages]\n F --> H[submitMessage]\n```\n\n### Vue 集成示例\n\n```vue\n\n\n\n \n \n \n\n```\n\n**配置说明：**\n\n| 配置项 | 说明 |\n|--------|------|\n| runtimeUrl | CopilotKit 运行时端点 |\n| selfManagedAgents | 自管理代理配置 |\n| onError | 错误处理回调 |\n| a2ui.theme | 生成式 UI 主题配置 |\n| debug | 调试日志配置 |\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 生成式 UI (a2ui)\n\n生成式 UI 是 CopilotKit 的核心特性，允许 AI 动态生成用户界面组件。\n\n### a2ui 配置\n\n```typescript\na2ui: {\n theme: {\n mode: 'light' | 'dark' | 'system'\n },\n surfaces: ['inline', 'sheet', 'modal']\n}\n```\n\n### 渲染流程\n\n```mermaid\ngraph LR\n A[Agent 响应] --> B{包含 a2ui?}\n B -->|是| C[前端渲染 a2ui 组件]\n B -->|否| D[标准消息渲染]\n \n C --> E[主题应用]\n E --> F[显示在指定 surface]\n```\n\n### 自定义渲染器\n\n可以注册自定义的组件渲染器来处理特定工具调用：\n\n```tsx\nuseRenderTool({\n toolName: \"weather\",\n render: (props) => ,\n});\n```\n\n当没有为工具注册自定义渲染器时，系统会使用 `useDefaultRenderTool` 作为后备渲染器。\n\n资料来源：[showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/ms-agent-dotnet/src/app/demos/headless-complete/README.md)\n\n## 调试与日志\n\n### Provider 调试配置\n\n```typescript\nconst debug: DebugConfig = {\n events: true, // 事件日志\n lifecycle: true, // 生命周期日志\n verbose: false // 详细载荷（可选）\n};\n```\n\n### 日志级别\n\n| 级别 | 说明 |\n|------|------|\n| true/false | 启用/禁用基本事件和生命周期日志 |\n| events | 事件日志 |\n| lifecycle | 生命周期日志 |\n| verbose | 包含完整载荷的详细日志 |\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 最佳实践\n\n### 1. 组件选择\n\n- **标准场景**：使用 `CopilotChat` 获得完整功能\n- **临时助手**：使用 `CopilotPopup` 减少界面占用\n- **边浏览边对话**：使用 `CopilotSidebar`\n\n### 2. 自定义 UI\n\n- 需要完全控制 UI 时，选择 Headless 模式\n- 利用 `useAgent` 和 `useRenderToolCall` 构建自定义界面\n- 复用 CopilotKit 的工具渲染机制\n\n### 3. 性能优化\n\n- 使用消息虚拟化处理长对话\n- 懒加载工具渲染器\n- 合理使用 `isRunning` 状态控制 UI 更新\n\n### 4. 错误处理\n\n- 配置 Provider 级别的 `onError` 处理器\n- 在组件级别添加 `CopilotChat.onError` 处理\n- 实现工具调用的错误边界\n\n## 相关资源\n\n- [CopilotKit 文档](https://docs.copilotkit.ai/getting-started/quickstart-chatbot)\n- [CopilotKit GitHub 仓库](https://github.com/CopilotKit/CopilotKit)\n- [Discord 社区](https://discord.gg/6dffbvGU3D)\n\n---\n\n\n\n## React Hooks API\n\n### 相关页面\n\n相关主题：[Chat UI 组件](#chat-ui-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/react-native/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-native/README.md)\n- [packages/react-core/package.json](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-core/package.json)\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [examples/v1/form-filling/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/v1/form-filling/README.md)\n- [examples/v1/chat-with-your-data/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/v1/chat-with-your-data/README.md)\n- [examples/showcases/presentation/package.json](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/presentation/package.json)\n- [examples/integrations/langgraph-python-threads/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-python-threads/README.md)\n \n\n# React Hooks API\n\n## 概述\n\nReact Hooks API 是 CopilotKit 为 React 应用提供的核心编程接口，通过一系列 Hook 函数实现前端与 AI Copilot 的交互能力。这些 Hooks 封装了 CopilotKit 的状态管理、事件通信和 UI 控制逻辑，使开发者能够在 React 组件中便捷地接入 AI 功能。\n\nCopilotKit 的 Hooks API 主要分布在两个包中：\n\n| 包名 | 说明 | 导出内容 |\n|------|------|---------|\n| `@copilotkit/react-core` | 核心 Hooks，包含状态管理和交互逻辑 | `useAgent`、`useCopilotKit`、`useHumanInTheLoop`、`useThreads` 等 |\n| `@copilotkit/react-native` | React Native 专用绑定，重导出 react-core 的 Hooks | 与 react-core 相同的 Hooks 集合 |\n\n资料来源：[packages/react-native/README.md:1-10]()\n\n## 核心 Hooks\n\n### useCopilotKit\n\n`useCopilotKit` 是获取 CopilotKit 上下文的根级 Hook，返回与 CopilotKit 实例交互所需的属性和方法。\n\n**基本用法：**\n\n```tsx\nimport { useCopilotKit } from \"@copilotkit/react-core\";\n\nfunction ChatScreen() {\n const { \n copilotKit, \n threadId, \n messages, \n inputContent, \n setInputContent,\n isGenerating \n } = useCopilotKit();\n \n // 执行业务逻辑\n}\n```\n\n**典型应用场景：**\n\n在表单填写示例中，开发者使用 `useCopilotKit` 获取 CopilotKit 实例以实现表单状态同步：\n\n```tsx\nimport { useCopilotKit } from \"@copilotkit/react-core\";\n\nexport default function App() {\n return (\n \n \n \n );\n}\n```\n\n资料来源：[packages/react-native/README.md:20-35]()\n\n### useAgent\n\n`useAgent` Hook 用于与 Copilot Agent 进行交互，支持获取代理状态、执行操作和处理事件。\n\n**导入来源：**\n\n```tsx\n// 从 @copilotkit/react-core 导入\nimport { useAgent } from \"@copilotkit/react-core\";\n\n// 或从 @copilotkit/react-native 导入（重导出）\nimport { useAgent } from \"@copilotkit/react-native\";\n```\n\n**API 导出配置：**\n\n`@copilotkit/react-core` 包的 exports 配置支持两种导入方式：\n\n```json\n{\n \"exports\": {\n \".\": {\n \"import\": \"./dist/index.mjs\",\n \"require\": \"./dist/index.cjs\"\n },\n \"./v2\": {\n \"import\": \"./dist/v2/index.mjs\",\n \"require\": \"./dist/v2/index.cjs\"\n }\n }\n}\n```\n\n资料来源：[packages/react-core/package.json:20-32]()\n\n### useHumanInTheLoop\n\n`useHumanInTheLoop` Hook 实现人机协作模式，允许 AI 在执行关键操作前等待用户确认。\n\n**功能特性：**\n\n- 中断 AI 执行流程\n- 向用户展示操作预览\n- 等待用户确认或取消\n- 恢复或放弃操作执行\n\n**使用示例：**\n\n```tsx\nimport { useHumanInTheLoop } from \"@copilotkit/react-core\";\n\nfunction DisambiguationPrompt() {\n const { \n interrupt, \n resume, \n discard \n } = useHumanInTheLoop();\n \n // 处理用户交互逻辑\n}\n```\n\n资料来源：[packages/react-native/README.md:8]()\n\n### useThreads\n\n`useThreads` Hook 提供会话线程管理能力，支持创建、切换和持久化对话上下文。\n\n**线程管理功能：**\n\n- 创建新线程\n- 加载历史线程\n- 切换活跃线程\n- 线程元数据管理\n\n**导出配置：**\n\n```json\n{\n \"exports\": {\n \"./v2/context\": {\n \"import\": \"./dist/v2/context.mjs\",\n \"require\": \"./dist/v2/context.cjs\"\n }\n }\n}\n```\n\n资料来源：[packages/react-core/package.json:32-36]()\n\n## 状态管理 Hooks\n\n### useCopilotReadable\n\n`useCopilotReadable` 用于将组件状态共享给 AI，使 Copilot 能够感知当前应用状态。\n\n**典型用法：**\n\n```tsx\nimport { useCopilotReadable } from \"@copilotkit/react-core\";\n\nfunction Dashboard() {\n const formState = useFormState();\n \n useCopilotReadable({\n description: \"仪表盘数据，包括销售趋势和产品表现\",\n value: {\n salesData,\n productData,\n metrics: {\n totalRevenue,\n totalProfit,\n conversionRate\n }\n }\n });\n}\n```\n\n**应用场景：**\n\n| 场景 | 描述 |\n|------|------|\n| 表单状态同步 | 将表单字段和当前值传递给 AI |\n| 数据仪表盘 | 共享业务指标和趋势数据 |\n| 用户信息 | 提供当前用户上下文给 Copilot |\n\n资料来源：[examples/v1/form-filling/README.md:30-45]()\n\n### useCopilotAction\n\n`useCopilotAction` 允许 AI 执行前端操作，实现生成式 UI 交互模式。\n\n**定义可执行动作：**\n\n```tsx\nuseCopilotAction({\n name: \"fillIncidentReportForm\",\n description: \"填写安全事件报告表单\",\n parameters: [\n { name: \"incidentType\", type: \"string\" },\n { name: \"description\", type: \"string\" }\n ],\n renderAndWaitForResponse: ({ args, status }) => {\n return ;\n }\n});\n```\n\n资料来源：[examples/v1/form-filling/README.md:50-60]()\n\n## 完整使用架构\n\n### 组件层级结构\n\n```mermaid\ngraph TD\n A[应用根组件] --> B[CopilotKitProvider]\n B --> C[业务组件]\n C --> D[useCopilotKit]\n C --> E[useAgent]\n C --> F[useCopilotReadable]\n C --> G[useCopilotAction]\n D --> H[CopilotKit 上下文]\n E --> H\n F --> H\n G --> H\n```\n\n### 状态流转\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant R as React组件\n participant H as Hooks API\n participant C as CopilotKit上下文\n participant A as AI后端\n \n U->>R: 触发交互\n R->>H: 调用 useCopilotKit/useAgent\n H->>C: 读取/更新状态\n C->>A: 发送请求\n A->>C: 返回响应\n C->>H: 推送更新\n H->>R: 触发重新渲染\n R->>U: 更新UI\n```\n\n## React Native 支持\n\n### 与 Web SDK 的差异\n\n| 特性 | Web SDK | React Native |\n|------|---------|--------------|\n| API 版本 | `/v2` 子路径导出 | 根路径即 v2 API |\n| DOM 依赖 | 完整支持 | 无 DOM/CSS 依赖 |\n| UI 组件 | 提供 UI 组件库 | 仅提供纯 Hooks |\n\n**安装配置：**\n\n```bash\nnpm install @copilotkit/react-native\n```\n\n**入口文件配置：**\n\n```javascript\n// index.js\nimport \"@copilotkit/react-native/polyfills\";\n\nimport { AppRegistry } from \"react-native\";\nimport App from \"./App\";\nimport { name as appName } from \"./app.json\";\n\nAppRegistry.registerComponent(appName, () => App);\n```\n\n### 分片导入\n\nReact Native 包支持按需导入 polyfills：\n\n```javascript\n// 仅导入所需的 polyfill\nimport \"@copilotkit/react-native/polyfills/streams\";\nimport \"@copilotkit/react-native/polyfills/encoding\";\nimport \"@copilotkit/react-native/polyfills/crypto\";\nimport \"@copilotkit/react-native/polyfills/dom\";\nimport \"@copilotkit/react-native/polyfills/location\";\n```\n\n资料来源：[packages/react-native/README.md:50-60]()\n\n## 依赖包版本\n\n当前稳定版本为 **1.57.2**，相关包的版本信息：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `@copilotkit/react-core` | 1.57.2 | 核心 Hooks |\n| `@copilotkit/react-native` | 1.57.2 | React Native 支持 |\n| `@copilotkit/react-ui` | 1.57.2 | UI 组件库 |\n| `@copilotkit/runtime` | 1.57.2 | 运行时核心 |\n\n资料来源：[packages/react-core/package.json:3]()\n资料来源：[packages/react-native/package.json:3]()\n\n## 与后端集成\n\n### 运行时配置\n\n`CopilotKitProvider` 需要配置 `runtimeUrl` 指向 CopilotKit 后端服务：\n\n```tsx\n\n \n\n```\n\n### 线程持久化\n\n使用 `useThreads` 管理对话历史，支持跨会话恢复：\n\n```tsx\nfunction ChatInterface() {\n const { threads, activeThread, createThread, switchThread } = useThreads();\n \n // 线程管理逻辑\n}\n```\n\n资料来源：[examples/integrations/langgraph-python-threads/README.md:60-80]()\n\n## 最佳实践\n\n### 1. 状态同步时机\n\n- 在组件挂载时调用 `useCopilotReadable` 初始化状态\n- 使用 `useCallback` 包装状态更新逻辑，避免不必要的重新渲染\n\n### 2. 错误处理\n\n```tsx\ntry {\n const { copilotKit } = useCopilotKit();\n await copilotKit.doSomething();\n} catch (error) {\n console.error(\"CopilotKit 错误:\", error);\n}\n```\n\n### 3. 类型安全\n\n利用 TypeScript 类型定义确保 API 调用的正确性：\n\n```typescript\nimport type { CopilotKitConfig, Thread, Message } from \"@copilotkit/react-core\";\n```\n\n## 总结\n\nReact Hooks API 是 CopilotKit 前端开发的核心接口，通过 `@copilotkit/react-core` 和 `@copilotkit/react-native` 两个包提供完整的状态管理、动作执行和上下文共享能力。开发者应优先使用 `useCopilotKit` 获取基础上下文，根据具体场景选择 `useCopilotReadable` 共享状态或 `useCopilotAction` 定义可执行动作。对于需要人机协作的场景，可结合 `useHumanInTheLoop` 实现中断和确认流程。\n\n---\n\n\n\n## CopilotRuntime 后端运行时\n\n### 相关页面\n\n相关主题：[后端工具系统](#backend-tools), [系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/runtime/src/lib/runtime/copilot-runtime.ts](https://github.com/CopilotKit/CopilotKit/blob/main/packages/runtime/src/lib/runtime/copilot-runtime.ts)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n- [examples/integrations/a2a-middleware/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/a2a-middleware/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [examples/v1/state-machine/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/v1/state-machine/README.md)\n \n\n# CopilotRuntime 后端运行时\n\n## 概述\n\nCopilotRuntime 是 CopilotKit 框架的核心后端运行时组件，负责管理与 AI Agent 的通信、工具调用路由、消息转换以及前端与后端之间的状态同步。它作为 Next.js API 路由或独立后端服务运行，为 CopilotKit 前端组件提供运行时支持。\n\n**核心职责：**\n\n- 接收前端发送的 AI 请求并路由到相应的 Agent\n- 管理工具定义和工具调用执行\n- 处理消息格式转换（AG-UI 协议与 GraphQL 格式互转）\n- 支持可观测性配置（日志记录、追踪）\n- 连接外部 MCP（Model Context Protocol）服务器\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:1-100]()\n\n## 核心配置选项\n\nCopilotRuntime 通过配置对象初始化，支持多种定制化选项：\n\n```typescript\nimport { CopilotRuntime } from \"@copilotkit/runtime\";\n\nconst copilotKit = new CopilotRuntime({\n runtimeUrl: \"/api/copilotkit\",\n headers: { \"Authorization\": `Bearer ${token}` },\n licenseKey: \"ck_pub_...\",\n properties: { customKey: \"value\" },\n agents: agentConfig,\n tools: [],\n renderToolCalls: [],\n frontendTools: [],\n humanInTheLoop: [],\n observability_c: { logging: { enabled: true } },\n mcpServers: [],\n experimental_createMCPClient: async (config) => { /* ... */ }\n});\n```\n\n### 配置参数详解\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `runtimeUrl` | `string` | 否 | CopilotKit 运行时 URL，默认使用当前服务 |\n| `headers` | `Record` | 否 | 默认请求头，会被每个请求继承 |\n| `licenseKey` | `string` | 否 | Copilot Cloud 公用 API 密钥（`ck_pub_...`） |\n| `properties` | `Record` | 否 | 转发到 Agent 运行时的自定义属性 |\n| `agents` | `Record` | 否 | 本地浏览器内 Agent 配置 |\n| `tools` | `ClientTool[]` | 否 | 向运行时广告的工具定义（无处理器） |\n| `renderToolCalls` | `RenderToolCallConfig[]` | 否 | 渲染工具调用的 UI 组件配置 |\n| `frontendTools` | `FrontendToolConfig[]` | 否 | 带处理器的客户端工具 |\n| `humanInTheLoop` | `HumanInTheLoopConfig[]` | 否 | 暂停等待用户输入的工具 |\n| `observability_c` | `CopilotObservabilityConfig` | 否 | 可观测性配置（日志、追踪） |\n| `mcpServers` | `MCPEndpointConfig[]` | 否 | 外部 MCP 服务器连接配置 |\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n## 架构设计\n\n### 运行时架构图\n\n```mermaid\ngraph TD\n subgraph 前端层 [\"前端层 (Frontend)\"]\n UI[CopilotKit UI 组件]\n React[React / Vue / Angular]\n end\n\n subgraph 运行时层 [\"CopilotRuntime 层\"]\n CR[CopilotRuntime 实例]\n MW[中间件处理]\n MSG[消息转换器]\n TOOL[工具路由]\n end\n\n subgraph Agent 层 [\"Agent 层\"]\n LG[LangGraph Agent]\n MI[LlamaIndex Agent]\n MA[Mastra Agent]\n CA[CrewAI Agent]\n A2A[A2A Middleware Agent]\n end\n\n subgraph 外部服务 [\"外部服务\"]\n MCP[MCP Server]\n OBS[可观测性服务]\n end\n\n UI --> CR\n CR --> MW\n MW --> MSG\n MSG --> TOOL\n TOOL --> LG\n TOOL --> MI\n TOOL --> MA\n TOOL --> CA\n TOOL --> A2A\n CR --> MCP\n CR --> OBS\n```\n\n### 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant UI as CopilotKit UI\n participant RT as CopilotRuntime\n participant Agent as AI Agent\n participant Tools as 工具系统\n\n User->>UI: 发送自然语言请求\n UI->>RT: 转发请求 (Action)\n RT->>RT: 消息格式转换\n RT->>Agent: 调用 Agent 执行\n Agent->>Agent: LLM 推理\n Agent->>Tools: 请求工具调用\n Tools-->>Agent: 返回工具结果\n Agent-->>RT: 返回响应结果\n RT->>RT: 状态更新\n RT-->>UI: 流式事件推送\n UI-->>User: 显示 AI 响应\n```\n\n## 使用方式\n\n### Next.js API 路由集成\n\nCopilotRuntime 最常见的用法是在 Next.js 应用中作为 API 路由处理程序：\n\n```typescript\n// app/api/copilotkit/route.ts\nimport { CopilotRuntime, CopilotKitServiceAdapter } from \"@copilotkit/runtime\";\nimport { LangGraphApolloClient } from \"@langchain/langgraph-sdk\";\n\nconst langgraphAdapter = new LangGraphApolloClient({\n deployment: process.env.LANGGRAPH_DEPLOYMENT!,\n apiKey: process.env.LANGGRAPH_API_KEY,\n});\n\nexport async function POST(req: Request): Promise {\n const copilotKit = new CopilotRuntime({\n tools: [\n {\n id: \"research\",\n name: \"Research\",\n description: \"Search for information\",\n argument: {\n type: \"object\",\n properties: {\n query: { type: \"string\" }\n }\n }\n }\n ]\n });\n\n return copilotKit.streamRequest(\n req,\n langgraphAdapter\n );\n}\n```\n\n资料来源：[examples/canvas/langgraph-python/src/app/api/copilotkit/route.ts](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/langgraph-python/src/app/api/copilotkit/route.ts)\n\n### 可观测性配置\n\nCopilotRuntime 支持详细的可观测性配置，可集成 Langfuse 等追踪服务：\n\n```typescript\nconst copilotKit = new CopilotRuntime({\n observability_c: {\n logging: {\n enabled: true,\n progressive: true, // 设为 false 启用缓冲日志\n logger: {\n logRequest: (data) => langfuse.trace({ \n name: \"LLM Request\", \n input: data \n }),\n logResponse: (data) => langfuse.trace({ \n name: \"LLM Response\", \n output: data \n }),\n logError: (errorData) => langfuse.trace({ \n name: \"LLM Error\", \n metadata: errorData \n }),\n },\n },\n },\n});\n```\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:50-70]()\n\n## 工具系统\n\n### 工具类型\n\nCopilotRuntime 支持多种工具定义方式：\n\n| 工具类型 | 说明 | 配置位置 |\n|----------|------|----------|\n| **Backend Tools** | 后端定义的工具，Agent 调用后由运行时执行 | `tools` 参数 |\n| **Frontend Tools** | 前端定义的工具，Agent 调用后回传前端执行 | `frontendTools` 参数 |\n| **Human-in-the-Loop** | 需人工确认的工具调用 | `humanInTheLoop` 参数 |\n| **MCP Tools** | 外部 MCP 服务器提供的工具 | `mcpServers` 参数 |\n\n### 后端工具定义示例\n\n```typescript\nconst copilotKit = new CopilotRuntime({\n tools: [\n {\n id: \"update_spreadsheet\",\n name: \"Update Spreadsheet\",\n description: \"更新电子表格中的单元格值\",\n argument: {\n type: \"object\",\n properties: {\n cell: { type: \"string\", description: \"单元格引用，如 A1\" },\n value: { type: \"string\", description: \"要写入的值\" }\n },\n required: [\"cell\", \"value\"]\n }\n }\n ]\n});\n```\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n### 前端工具定义\n\n```typescript\nimport { useCopilotAction } from \"@copilotkit/core\";\n\nuseCopilotAction({\n name: \"update_spreadsheet\",\n description: \"更新电子表格中的单元格值\",\n available: \"remote\",\n parameters: [\n {\n name: \"cell\",\n type: \"string\",\n required: true,\n description: \"单元格引用\"\n },\n {\n name: \"value\", \n type: \"string\",\n required: true,\n description: \"要写入的值\"\n }\n ],\n handler: ({ cell, value }) => {\n // 在前端执行实际更新\n return updateCell(cell, value);\n }\n});\n```\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n## MCP 服务器集成\n\nCopilotRuntime 支持连接外部 Model Context Protocol (MCP) 服务器，获取外部工具定义：\n\n```typescript\nimport { experimental_createMCPClient } from \"ai\"; // 从 vercel ai 库导入\n\nconst copilotKit = new CopilotRuntime({\n mcpServers: [\n {\n id: \"tavily-search\",\n serverUrl: \"https://api.tavily.com/mcp\",\n headers: {\n \"Authorization\": `Bearer ${process.env.TAVILY_API_KEY}`\n }\n }\n ],\n experimental_createMCPClient: async (config) => {\n return await experimental_createMCPClient({\n ...config,\n // 额外的 MCP 客户端配置\n });\n }\n});\n```\n\n**MCP 集成特性：**\n\n- 自动获取远程服务器的工具定义\n- 标准化工具参数验证\n- 支持自定义请求头和认证\n- 实验性功能，需启用 `experimental_createMCPClient`\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:80-110]()\n\n## Agent 集成\n\n### 与 LangGraph 集成\n\n```python\nfrom copilotkit import CopilotKitMiddleware\nfrom langgraph.checkpoint.memory import MemorySaver\nfrom langchain_openai import ChatOpenAI\n\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-4\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n### 与 LlamaIndex 集成\n\n```python\nfrom llama_index.core.workflow import DrawableWorkflow\nfrom llama_index.core.workflow.events import StartEvent, StopEvent\nfrom copilotkit import copilotkit_emit_event\n\nclass MyWorkflow(DrawableWorkflow):\n @step\n async def process(self, ev: StartEvent) -> StopEvent:\n result = f\"Processing: {ev.input}\"\n await copilotkit_emit_event(\n event_name=\"progress\",\n data={\"message\": \"处理中...\"}\n )\n return StopEvent(result=result)\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n### 与 A2A 中间件集成\n\n```typescript\nimport { A2AMiddlewareAgent } from \"@copilotkit/plugin-a2a\";\n\nconst a2aMiddlewareAgent = new A2AMiddlewareAgent({\n agentUrls: [\n \"http://localhost:9001/research\",\n \"http://localhost:9002/analysis\",\n \"http://localhost:9003/new-agent\",\n ],\n defaultHandoffs: [\n { agent: \"research\", description: \"研究代理\" }\n ]\n});\n```\n\n资料来源：[examples/integrations/a2a-middleware/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/a2a-middleware/README.md)\n\n## 状态管理\n\n### 全局状态管理\n\nCopilotRuntime 支持前端状态读取和应用状态同步：\n\n```typescript\n// 前端读取应用状态\nimport { useCopilotReadable } from \"@copilotkit/core\";\n\nfunction AppComponent() {\n const appState = useMemo(() => ({\n spreadsheet: spreadsheetData,\n user: currentUser\n }), [spreadsheetData, currentUser]);\n\n useCopilotReadable({\n description: \"当前应用状态\",\n value: appState\n });\n\n return ;\n}\n```\n\n```typescript\n// 前端修改应用状态\nimport { useCopilotAction } from \"@copilotkit/core\";\n\nuseCopilotAction({\n name: \"updateSpreadsheet\",\n description: \"更新电子表格\",\n parameters: [\n { name: \"cell\", type: \"string\" },\n { name: \"value\", type: \"string\" }\n ],\n handler: ({ cell, value }) => {\n return updateSpreadsheet(cell, value);\n }\n});\n```\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n### 状态流图\n\n```mermaid\ngraph LR\n subgraph Frontend [\"前端状态\"]\n UI[用户界面]\n READ[useCopilotReadable]\n ACT[useCopilotAction]\n end\n\n subgraph Runtime [\"CopilotRuntime\"]\n SYNC[状态同步]\n ROUTE[请求路由]\n end\n\n subgraph Backend [\"后端状态\"]\n AGENT[AI Agent]\n TOOLS[工具执行]\n end\n\n READ --> SYNC\n SYNC --> AGENT\n ACT --> ROUTE\n ROUTE --> TOOLS\n TOOLS --> SYNC\n SYNC --> UI\n```\n\n## 框架适配\n\n### Vue 集成\n\n```vue\n\n\n\n \n \n \n\n```\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n### Angular 集成\n\n```typescript\nimport { provideCopilotKit } from \"@copilotkit/angular\";\n\n@Component({\n selector: \"app-root\",\n standalone: true,\n providers: [\n provideCopilotKit({\n runtimeUrl: \"/api/copilotkit\",\n licenseKey: \"ck_pub_...\",\n agents: {},\n tools: [],\n renderToolCalls: [],\n frontendTools: [],\n humanInTheLoop: []\n })\n ],\n template: ``\n})\nexport class AppComponent {}\n```\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n## 版本演进\n\nCopilotRuntime 正在从 v1 版本向 v2 版本迁移，提供新的 API 和功能：\n\n```typescript\nimport { \n CopilotRuntime as CopilotRuntimeVNext,\n InMemoryAgentRunner,\n type AgentsConfig,\n type AgentsFactory \n} from \"@copilotkit/runtime/v2\";\n\nconst config: AgentsConfig = {\n // 新的 Agent 配置格式\n};\n\nconst runtime = new CopilotRuntimeVNext({\n agents: config\n});\n```\n\n**v2 新特性：**\n\n- 改进的 Agent 配置系统\n- 支持更多中间件类型\n- 增强的类型安全性\n- 更好的性能优化\n\n资料来源：[packages/runtime/src/lib/runtime/copilot-runtime.ts:200-250]()\n\n## 最佳实践\n\n### 生产环境配置\n\n| 配置项 | 推荐值 | 说明 |\n|--------|--------|------|\n| `licenseKey` | 必填 | 使用 Copilot Cloud 功能必需 |\n| `observability_c.logging.enabled` | true | 生产环境建议启用 |\n| `observability_c.logging.progressive` | true | 实时日志便于调试 |\n| 错误处理 | 必需 | 实现 `onError` 回调 |\n\n### 性能优化\n\n1. **工具定义精简**：只暴露必要的工具，减少 LLM 上下文\n2. **状态同步控制**：合理使用 `useCopilotReadable` 避免过度同步\n3. **MCP 连接池**：复用 MCP 客户端连接\n4. **消息压缩**：大响应启用流式处理\n\n### 安全考虑\n\n```typescript\nconst copilotKit = new CopilotRuntime({\n headers: {\n \"Authorization\": `Bearer ${validateToken()}`,\n \"X-Request-ID\": generateRequestId()\n },\n properties: {\n \"userId\": sanitize(userId),\n \"sessionId\": sessionId\n }\n});\n```\n\n- 始终验证和清理用户输入\n- 使用安全的认证头传递凭证\n- 限制暴露给 Agent 的系统属性\n\n## 相关资源\n\n- [CopilotRuntime API 参考](https://docs.copilotkit.ai/reference/v1/classes/CopilotRuntime)\n- [Copilot Runtime 概念文档](https://docs.copilotkit.ai/concepts/copilot-runtime)\n- [LangGraph 集成指南](https://docs.copilotkit.ai/integrations/langgraph)\n- [A2A 协议集成](https://docs.copilotkit.ai/integrations/a2a)\n\n---\n\n\n\n## 后端工具系统\n\n### 相关页面\n\n相关主题：[CopilotRuntime 后端运行时](#copilot-runtime), [生成式 UI](#generative-ui)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [examples/integrations/langgraph-fastapi/agent/src/todos.py](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-fastapi/agent/src/todos.py)\n- [examples/integrations/langgraph-fastapi/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-fastapi/README.md)\n- [examples/integrations/a2a-middleware/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/a2a-middleware/README.md)\n \n\n# 后端工具系统\n\n## 概述\n\n后端工具系统是 CopilotKit 架构中连接 AI Agent 与外部服务、业务逻辑的桥梁。该系统允许在服务器端（Python/Node.js）定义工具函数，使 AI Agent 能够执行复杂的后端操作，如数据库查询、API 调用、文件处理等。与前端工具不同，后端工具由 Agent 在推理过程中调用，结果通过 CopilotKit Runtime 同步回前端界面。\n\n## 核心概念\n\n### 后端工具 vs 前端工具\n\n| 特性 | 后端工具 | 前端工具 |\n|------|---------|---------|\n| 执行位置 | 服务器端（Agent 运行时） | 浏览器端 |\n| 调用时机 | Agent 推理过程中自动调用 | 需显式定义 `handler` |\n| 适用场景 | 数据库操作、外部 API、复杂计算 | UI 交互、状态更新、本地计算 |\n| 状态管理 | 通过 `useCoAgent` 同步状态 | 直接操作 React 状态 |\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n### 工具注册流程\n\n```mermaid\ngraph TD\n A[定义后端工具函数] --> B[注册到 Agent 框架]\n B --> C[生成工具 Schema]\n C --> D[CopilotKit Runtime 暴露工具]\n D --> E[前端通过 useCopilotAction 渲染]\n```\n\n## LlamaIndex 集成\n\n### 基本用法\n\n使用 `get_ag_ui_workflow_router` 可以快速定义后端工具。以下示例展示了一个问候语工具的定义：\n\n```python\ndef hello_world(name: str) -> str:\n return f\"Hello, {str}\" # 工具返回结果\n\nagentic_chat_router = get_ag_ui_workflow_router(\n llm=OpenAI(model=\"gpt-4.1\"),\n backend_tools=[hello_world]\n)\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n### 工具参数定义\n\n后端工具支持类型化的参数定义，参数规范会自动生成给 LLM 使用：\n\n```python\ndef create_task(\n title: str, # 必需参数\n description: str = \"\", # 可选参数\n priority: int = 1 # 带默认值的参数\n) -> dict:\n return {\"status\": \"created\", \"title\": title}\n```\n\n### 工具结果处理\n\n工具执行完成后，结果通过 AG-UI 协议返回前端。前端可以使用 `useCopilotAction` 渲染工具调用界面：\n\n```tsx\nuseCopilotAction({\n name: \"hello_world\",\n render: () => {\n return Called hello_world tool...
\n }\n})\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n## LangGraph 集成\n\n### FastAPI + LangGraph 架构\n\n```mermaid\ngraph TB\n subgraph \"Frontend\"\n UI[Next.js UI]\n CK[CopilotKit]\n end\n \n subgraph \"Backend\"\n FA[FastAPI Server]\n LG[LangGraph Agent]\n Tools[Backend Tools]\n end\n \n UI <--> CK\n CK <--> FA\n FA <--> LG\n LG --> Tools\n```\n\n在 LangGraph 集成中，后端工具通过 `CopilotKitMiddleware` 与图节点交互：\n\n```python\nfrom copilotkit import CopilotKitMiddleware\n\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n### 任务管理工具示例\n\n```python\n# examples/integrations/langgraph-fastapi/agent/src/todos.py\n\nfrom pydantic import BaseModel, Field\nfrom typing import Optional\n\nclass TodoItem(BaseModel):\n id: str = Field(description=\"唯一标识符\")\n title: str = Field(description=\"任务标题\")\n completed: bool = Field(default=False, description=\"完成状态\")\n\nclass TodoInput(BaseModel):\n title: str = Field(description=\"新建任务的标题\")\n\ndef get_todos() -> list[dict]:\n \"\"\"获取所有待办事项\"\"\"\n return [{\"id\": \"1\", \"title\": \"示例任务\", \"completed\": False}]\n\ndef create_todo(input: TodoInput) -> dict:\n \"\"\"创建新的待办事项\"\"\"\n return {\"id\": \"new-1\", \"title\": input.title, \"completed\": False}\n```\n\n资料来源：[examples/integrations/langgraph-fastapi/agent/src/todos.py](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-fastapi/agent/src/todos.py)\n\n## 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as 前端 UI\n participant CK as CopilotKit Runtime\n participant Agent as AI Agent\n participant Tool as 后端工具\n\n User->>UI: 发送自然语言请求\n UI->>CK: 转发消息\n CK->>Agent: 传递消息和上下文\n Agent->>Agent: 推理并决定调用工具\n Agent->>Tool: 执行工具函数\n Tool-->>Agent: 返回执行结果\n Agent->>CK: 返回更新后的状态\n CK->>UI: 同步状态变化\n UI->>User: 显示结果\n```\n\n## 外部工具集成\n\n### Composio 集成\n\nCopilotKit 支持通过 Composio 集成外部服务（如 Google Sheets）：\n\n```python\nfrom composio import Composio\n\ncomposio = Composio()\n\ndef sheets_sync_all(data: list[dict]) -> str:\n \"\"\"同步数据到 Google Sheets\"\"\"\n action = composio.action(\"sheets_sync_all\")\n result = action.execute(data=data)\n return result\n\ndef sheets_create_new(title: str) -> str:\n \"\"\"创建新的电子表格\"\"\"\n action = composio.action(\"sheets_create_new\")\n result = action.execute(title=title)\n return result\n\ndef sheets_get_url(spreadsheet_id: str) -> str:\n \"\"\"获取电子表格 URL\"\"\"\n return f\"https://docs.google.com/spreadsheets/d/{spreadsheet_id}\"\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n### Tavily 搜索工具\n\n```python\n# examples/showcases/deep-agents/agent/tools.py\n\nfrom langchain.tools import tool\nfrom tavily import TavilyClient\n\ntavily_client = TavilyClient()\n\n@tool\ndef research(query: str) -> str:\n \"\"\"根据查询进行网络研究并返回摘要\"\"\"\n results = tavily_client.search(query=query, max_results=5)\n summaries = [r['content'] for r in results]\n return \"\\n\\n\".join(summaries)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n## A2A 协议工具调用\n\nCopilotKit 支持通过 A2A（Agent-to-Agent）协议调用外部代理服务：\n\n```python\n# 在路由中注册外部代理\nconst newAgentUrl = \"http://localhost:9003\";\n\nconst a2aMiddlewareAgent = new A2AMiddlewareAgent({\n agentUrls: [\n researchAgentUrl,\n analysisAgentUrl,\n newAgentUrl,\n ],\n});\n\n# 外部代理定义工具能力\nagent = new Agent(\n name=\"research_agent\",\n description=\"Deep research with web search\",\n skills=[web_search_skill], # 定义可调用工具\n port=9001,\n);\n```\n\n资料来源：[examples/integrations/a2a-middleware/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/a2a-middleware/README.md)\n\n## 最佳实践\n\n### 1. 工具命名规范\n\n| 规范 | 说明 | 示例 |\n|------|------|------|\n| 动词短语 | 工具名应描述操作 | `create_task`, `update_status` |\n| 小写下划线 | 使用 snake_case | `sync_sheets`, `get_user_data` |\n| 清晰描述 | 添加 docstring 说明 | `\"\"\"获取用户信息\"\"\"` |\n\n### 2. 参数类型提示\n\n始终使用类型提示，使 LLM 能够正确理解参数：\n\n```python\ndef process_data(\n data: list[str], # 列表类型\n options: dict = {}, # 可选字典\n limit: int = 10 # 带默认值的整数\n) -> dict: # 明确返回值类型\n ...\n```\n\n### 3. 错误处理\n\n```python\ndef safe_operation(input_data: str) -> dict:\n try:\n result = risky_operation(input_data)\n return {\"success\": True, \"data\": result}\n except ValidationError as e:\n return {\"success\": False, \"error\": str(e)}\n except Exception as e:\n logger.error(f\"Unexpected error: {e}\")\n return {\"success\": False, \"error\": \"Internal error\"}\n```\n\n## 总结\n\n后端工具系统是 CopilotKit 实现 Agent 能力扩展的核心组件。通过标准化的工具定义接口，开发者可以：\n\n- 将任意后端逻辑暴露给 AI Agent\n- 通过 Composio 等集成服务连接外部 API\n- 使用 A2A 协议实现多 Agent 协作\n- 利用 LangGraph、LlamaIndex 等框架构建复杂的工作流\n\n该系统与前端工具形成互补，共同支撑 CopilotKit 的端到端 AI 辅助能力。\n\n---\n\n\n\n## 生成式 UI\n\n### 相关页面\n\n相关主题：[Chat UI 组件](#chat-ui-components), [通信协议](#protocols)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/content/docs/(root)/generative-ui/display.mdx](https://github.com/CopilotKit/CopilotKit/blob/main/docs/content/docs/(root)/generative-ui/display.mdx)\n- [docs/content/docs/(root)/generative-ui/interactive.mdx](https://github.com/CopilotKit/CopilotKit/blob/main/docs/content/docs/(root)/generative-ui/interactive.mdx)\n- [docs/content/docs/(root)/generative-ui/tool-rendering.mdx](https://github.com/CopilotKit/CopilotKit/blob/main/docs/content/docs/(root)/generative-ui/tool-rendering.mdx)\n- [examples/integrations/langgraph-fastapi/src/components/generative-ui/charts/bar-chart.tsx](https://github.com/CopilotKit/CopilotKit/blob/main/examples/integrations/langgraph-fastapi/src/components/generative-ui/charts/bar-chart.tsx)\n- [examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n \n\n# 生成式 UI\n\n## 概述\n\n生成式 UI（Generative UI）是 CopilotKit 的核心特性之一，它使 AI 代理能够在运行时动态生成和渲染用户界面组件。与传统的固定 UI 模式不同，生成式 UI 允许 AI 根据对话上下文和工具执行结果，实时生成丰富的可视化内容、交互式表单、图表等复杂 UI 元素。\n\nCopilotKit 提供了完整的生成式 UI 技术栈，包括：\n\n- **组件渲染**：AI 可生成任意 React/Vue/Angular 组件\n- **工具调用渲染**：为特定工具绑定自定义 UI 展示\n- **交互式组件**：支持人机协作的工具执行模式\n- **状态同步**：前后端状态的双向实时同步\n\n资料来源：[examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md)\n\n---\n\n## 核心架构\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph 前端 [前端层 - CopilotKit SDK]\n UI[用户界面]\n CK[CopilotKit Provider]\n Hooks[Hooks API]\n Renderer[组件渲染器]\n end\n\n subgraph 中间层 [CopilotKit Runtime]\n Runtime[Runtime Service]\n StateSync[状态同步]\n MessageProc[消息处理]\n end\n\n subgraph 后端 [Agent 后端]\n Agent[AI Agent]\n Tools[工具定义]\n LLM[大语言模型]\n end\n\n UI --> Hooks\n Hooks --> Renderer\n Renderer --> CK\n CK --> Runtime\n Runtime --> StateSync\n Runtime --> MessageProc\n MessageProc --> Agent\n Agent --> Tools\n Agent --> LLM\n\n style 前端 fill:#e1f5fe\n style 中间层 fill:#fff3e0\n style 后端 fill:#e8f5e9\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant UI as 前端组件\n participant Hooks as CopilotKit Hooks\n participant Runtime as CopilotKit Runtime\n participant Agent as AI Agent\n participant LLM as 大语言模型\n\n User->>UI: 输入请求\n UI->>Hooks: useAgent / useCopilotAction\n Hooks->>Runtime: 发送消息\n Runtime->>Agent: 转发请求\n Agent->>LLM: 调用 LLM\n LLM-->>Agent: 返回生成结果\n Agent-->>Runtime: 返回工具调用/组件\n Runtime-->>Hooks: 同步状态更新\n Hooks-->>UI: 触发重新渲染\n UI-->>User: 显示生成式 UI\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n---\n\n## 工具渲染\n\n### 工具渲染配置\n\n工具渲染（Tool Rendering）允许为特定的 AI 工具绑定自定义的 UI 展示组件。当 AI 调用某个工具时，系统会自动使用对应的渲染器来展示结果，而不是显示默认的文本格式。\n\n#### React 工具渲染配置\n\n```typescript\n// 定义渲染工具调用的配置\ninterface RenderToolCallConfig {\n name: string; // 工具名称，或 \"*\" 匹配所有\n args: z.ZodType; // 参数的 Zod schema\n component: Type>; // 渲染器组件\n agentId?: string; // 可选的代理作用域\n}\n```\n\n#### 渲染器组件示例\n\n```typescript\n// 示例：天气卡片渲染器\n// 资料来源：examples/integrations/langgraph-fastapi/src/components/generative-ui/charts/bar-chart.tsx\n\nimport React from \"react\";\n\ninterface WeatherCardProps {\n toolCall: {\n args: { city: string; temperature: number; condition: string };\n status: \"in-progress\" | \"executing\" | \"complete\";\n result?: string;\n };\n}\n\nexport const WeatherCard: React.FC = ({ toolCall }) => {\n const { args, status } = toolCall;\n \n return (\n \n
{args.city}
\n
{args.temperature}°C
\n
{args.condition}
\n {status === \"in-progress\" &&
加载中...
}\n
\n 高亮文本: {args.text}\n {status === \"in-progress\" && 处理中...}\n
\n ),\n });\n\n return ;\n}\n```\n\n资料来源：[examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md)\n\n---\n\n## 显示组件\n\n### Headless 聊天界面\n\nCopilotKit 提供了完整的 Headless API，允许开发者完全自定义聊天界面的每一个细节。\n\n#### 核心 Hooks\n\n| Hook 名称 | 功能描述 |\n|-----------|----------|\n| `useAgent` | 获取原始代理句柄，包含 messages、isRunning、addMessage 等 |\n| `useCopilotKit` | 暴露 connectAgent、runAgent、stopAgent 方法 |\n| `useRenderTool` | 为特定工具注册自定义渲染器 |\n| `useCopilotReadable` | 将前端状态共享给 AI 代理 |\n\n#### Headless 实现示例\n\n```tsx\n// 资料来源：examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md\n\nimport { useAgent, useCopilotKit, useRenderTool } from \"@copilotkit/react-core\";\nimport { WeatherCard } from \"./components/WeatherCard\";\n\nfunction HeadlessChat() {\n const { messages, isRunning, addMessage, stop } = useAgent({ \n agentId: \"main-agent\",\n threadId: \"user-thread-1\" \n });\n const { connectAgent, runAgent, stopAgent } = useCopilotKit();\n\n // 注册天气工具的渲染器\n useRenderTool(\n \"get_weather\",\n ({ args, status, result }) => {\n if (status === \"in-progress\") {\n return 获取天气信息...
;\n }\n return ;\n }\n );\n\n return (\n \n \n \n addMessage({ role: \"user\", content: text })}\n />\n
\n );\n}\n```\n\n### 消息列表渲染\n\n```tsx\n// 消息列表组件\n// 资料来源：examples/showcases/integrations/claude-sdk-typescript/src/app/demos/headless-complete/README.md\n\nfunction MessageList({ messages }) {\n return (\n \n {messages.map((message, index) => (\n \n ))}\n
\n );\n}\n\n// 消息气泡组件\nfunction MessageBubble({ role, content, toolCalls, reasoning, status }) {\n return (\n \n {role === \"user\" &&
}\n \n {role === \"assistant\" && (\n <>\n {reasoning &&
}\n
\n \n {toolCalls?.map((toolCall, idx) => (\n
\n ))}\n \n
\n \n )}\n
\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n- [examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n- [packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n- [packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n- [examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n- [examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n \n\n# 人在回路 (Human-in-the-Loop)\n\n## 概述\n\n人在回路（Human-in-the-Loop，HitL）是一种设计模式，允许 AI 代理在执行关键操作前暂停执行流程，等待人类用户确认或提供额外输入。这种机制确保了 AI 系统在执行敏感操作时的安全性和可控性，特别适用于需要人工审批的业务场景。\n\n在 CopilotKit 架构中，人在回路通过以下核心机制实现：\n\n- **工具级中断**：Agent 调用特定工具时暂停，等待用户响应\n- **实时 UI 渲染**：在等待期间向用户展示操作详情和审批界面\n- **状态同步**：用户的决策结果实时同步回 Agent 继续执行\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n## 核心概念\n\n### 与前端工具的区别\n\n| 特性 | 前端工具 (Frontend Tools) | 人在回路 (HitL) |\n|------|---------------------------|-----------------|\n| 执行时机 | 立即执行，无需等待 | 暂停等待用户确认 |\n| 用户交互 | 可选 UI 渲染 | 必须有审批 UI |\n| 状态转换 | 异步完成 | 同步等待响应 |\n| 典型场景 | 数据查询、格式化 | 预算审批、敏感操作确认 |\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[Agent 决策] --> B{需要人工确认?}\n B -->|否| C[继续执行]\n B -->|是| D[触发 HitL 工具]\n D --> E[渲染审批 UI]\n E --> F[等待用户响应]\n F --> G{用户决策}\n G -->|批准| H[返回批准结果]\n G -->|拒绝| I[返回拒绝结果]\n G -->|修改参数| J[返回修改后参数]\n H --> K[Agent 继续执行]\n I --> L[Agent 取消操作]\n J --> K\n```\n\n## Angular 集成\n\n### HumanInTheLoopConfig 接口\n\n```typescript\nexport interface HumanInTheLoopConfig {\n name: string; // 工具名称\n description: string; // 工具描述\n parameters: z.ZodType; // 参数 Schema\n component: Type>; // 审批 UI 组件\n agentId?: string; // 可选的 Agent 作用域\n}\n```\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n### HumanInTheLoopToolRenderer 组件\n\n```typescript\nexport interface HumanInTheLoopToolRenderer {\n toolCall: Signal>; // 包含 respond(result) 方法\n}\n```\n\n审批组件通过 `toolCall` 信号接收工具调用信息，并通过 `respond()` 方法向 Agent 返回用户的决策结果。\n\n### 配置示例\n\n```typescript\nexport const hitlConfig: HumanInTheLoopConfig = {\n name: \"approve_budget\",\n description: \"审批预算支出\",\n parameters: budgetApprovalSchema,\n component: BudgetApprovalCard,\n agentId: \"finance-agent\"\n};\n```\n\n资料来源：[packages/angular/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/angular/README.md)\n\n## Vue 集成\n\n### CopilotKitProvider 配置\n\n在 Vue 生态中，HitL 功能通过 `CopilotKitProvider` 的配置项启用：\n\n```vue\n\n \n\n```\n\n### 状态信号\n\n| 信号名称 | 类型 | 说明 |\n|---------|------|------|\n| `runtimeConnectionStatus` | `Signal` | 运行时连接状态 |\n| `runtimeUrl` | `Signal` | 运行时 URL |\n| `agents` | `Signal>` | 可用 Agent 列表 |\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## React 集成\n\n### useCopilotAction Hook\n\n在 React 中使用 HitL 功能，通过 `useCopilotAction` 定义需要审批的工具：\n\n```typescript\nuseCopilotAction({\n name: \"approve_budget\",\n description: \"Prompt the user to review and approve the budget\",\n parameters: [\n {\n name: \"prompt\",\n type: \"string\",\n required: true,\n description: \"The approval prompt to show the user\"\n }\n ],\n render: ({ status, result, args }) => {\n // 返回审批 UI 组件\n return ;\n },\n});\n```\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n### render 回调参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `status` | `\"in-progress\" \\| \"executing\" \\| \"complete\"` | 工具执行状态 |\n| `result` | `string \\| undefined` | 工具返回结果 |\n| `args` | `Record` | 工具调用参数 |\n\n## 深度 Agent 集成\n\n### LangGraph 深度 Agent\n\n深度 Agent（Deep Agents）模式允许构建多层级、多工具的复杂 Agent 系统，HitL 作为关键节点确保人类参与关键决策点：\n\n```python\nagent_graph = create_deep_agent(\n model=ChatOpenAI(model=\"gpt-5.2\"),\n system_prompt=MAIN_SYSTEM_PROMPT,\n tools=[research],\n middleware=[CopilotKitMiddleware()],\n checkpointer=MemorySaver(),\n)\n```\n\n资料来源：[examples/showcases/deep-agents/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/deep-agents/README.md)\n\n### 研究工具集成\n\n```python\n@tool\nasync def create_character(\n name: str,\n description: str,\n prompt: str,\n state: Annotated[dict, InjectedState] # 访问共享状态\n) -> dict:\n api_key = state.get(\"apiKey\", \"\")\n image_url = await generate_image(prompt, api_key=api_key)\n return {\"name\": name, \"description\": description, \"imageUrl\": image_url}\n```\n\n当 Agent 调用 `create_character` 时，可以在返回前插入 HitL 审批环节。\n\n资料来源：[examples/showcases/scene-creator/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/scene-creator/README.md)\n\n## LlamaIndex 集成\n\n### 工具渲染配置\n\n```typescript\nexport interface RenderToolCallConfig {\n name: string; // 工具名或 \"*\" 通配符\n args: z.ZodType; // Zod Schema\n component: Type>;\n agentId?: string; // 可选的 Agent 作用域\n}\n```\n\n### 数据流架构\n\n```mermaid\nsequenceDiagram\n participant User\n participant UI as Canvas UI\n participant CK as CopilotKit\n participant Agent as LlamaIndex Agent\n participant Tools\n participant Composio\n\n User->>UI: 交互操作\n UI->>CK: 通过 useCoAgent 更新状态\n CK->>Agent: 发送状态 + 消息\n Agent->>Agent: 使用 GPT-4o 处理\n Agent->>Tools: 执行工具\n Tools-->>Agent: 返回结果\n Agent->>CK: 返回更新后的状态\n CK->>UI: 同步状态变更\n UI->>User: 显示更新\n```\n\n资料来源：[examples/canvas/llamaindex-composio/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/canvas/llamaindex-composio/README.md)\n\n## 预算审批实战案例\n\n### BudgetApprovalCard 组件\n\n在实际业务场景中，预算审批是最常见的 HitL 用例。以下是典型实现结构：\n\n```typescript\ninterface BudgetApprovalProps {\n status: \"in-progress\" | \"executing\" | \"complete\";\n result?: string;\n args: {\n amount: number;\n category: string;\n description: string;\n };\n}\n\n// 组件应处理三种状态：\n// 1. in-progress: 显示审批表单\n// 2. executing: 显示处理中指示器\n// 3. complete: 显示审批结果\n```\n\n### 状态机设计\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 用户发起请求\n Pending --> Reviewing: 渲染审批 UI\n Reviewing --> Approved: 用户点击批准\n Reviewing --> Rejected: 用户点击拒绝\n Reviewing --> Modifying: 用户修改参数\n Approved --> [*]: 返回结果给 Agent\n Rejected --> [*]: 取消操作\n Modifying --> Reviewing: 重新提交\n```\n\n## 应用场景\n\n### 1. 财务审批\n\n- 预算支出审批\n- 费用报销确认\n- 付款授权\n\n资料来源：[examples/showcases/spreadsheet/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/examples/showcases/spreadsheet/README.md)\n\n### 2. 内容生成确认\n\n- AI 生成内容的审核\n- 图像生成参数确认\n- 文档内容校正\n\n### 3. 数据操作审批\n\n- 数据库修改确认\n- 文件删除审批\n- 配置变更确认\n\n## 最佳实践\n\n### 设计原则\n\n1. **明确性**：工具描述应清晰说明需要用户确认什么\n2. **最小化干预**：只在必要时使用 HitL，避免过度打断流程\n3. **快速响应**：审批 UI 应简洁，减少用户等待时间\n4. **可追溯性**：记录所有审批决策，便于审计\n\n### 错误处理\n\n```typescript\nfunction onProviderError(event: {\n code: string;\n error: Error;\n context: Record;\n}) {\n console.error(\n \"CopilotKit provider error\",\n event.code,\n event.context,\n event.error,\n );\n}\n```\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 调试与日志\n\n### debug 配置选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `events` | `boolean` | 启用事件日志 |\n| `lifecycle` | `boolean` | 启用生命周期日志 |\n| `verbose` | `boolean` | 启用完整事件负载 |\n\n```typescript\nconst debug: DebugConfig = {\n events: true,\n lifecycle: true,\n verbose: false\n};\n```\n\n资料来源：[packages/vue/README.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/README.md)\n\n## 相关资源\n\n- [CopilotKit 文档](https://docs.copilotkit.ai)\n- [LangGraph 深度 Agent 集成](https://docs.copilotkit.ai/integrations/langgraph/deep-agents)\n- [构建深度 Agent 前端](https://www.copilotkit.ai/blog/how-to-build-a-frontend-for-langchain-deep-agents-with-copilotkit)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：CopilotKit/CopilotKit\n\n摘要：发现 28 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…。\n\n## 1. 安装坑 · 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged s…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_409f46a5944945278264fc47e297b72a | https://github.com/CopilotKit/CopilotKit/issues/4885 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6230695b9a44704927b31badcc61437 | https://github.com/CopilotKit/CopilotKit/issues/3454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_93af324180434026b3961aff8938714f | https://github.com/CopilotKit/CopilotKit/issues/4911 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0efd9d1f363946d48e1168b691b0ad4c | https://github.com/CopilotKit/CopilotKit/issues/4893 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f934812319464fb5acab93b86e00ed00 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: v1.55.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.55.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.55.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.55.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_67f1e990977177cadc4a1a612db8df88 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.55.3 | v1.55.3\n\n## 7. 安装坑 · 失败模式：installation: v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.0. Context: Observed when using node, python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_8ede7507e3ef26c20ae94eb3ff6a0f6f | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.0 | v1.56.0\n\n## 8. 安装坑 · 失败模式：installation: v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a12898a84c35b19ec1421880ce10e28 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.1 | v1.56.1\n\n## 9. 安装坑 · 失败模式：installation: v1.56.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a917a302b0681683ac2482e6cdefd4b | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.2 | v1.56.2\n\n## 10. 安装坑 · 失败模式：installation: v1.56.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_386de57caa0b418e81af496ef3e832e1 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.3 | v1.56.3\n\n## 11. 安装坑 · 失败模式：installation: v1.56.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.4\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.4. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ba48c40eb329f48223cab1a600a088ca | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.4 | v1.56.4\n\n## 12. 安装坑 · 失败模式：installation: v1.56.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.5\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.5. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_985bd4475e66904ba7c8c53ae2d6f26a | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.5 | v1.56.5\n\n## 13. 安装坑 · 失败模式：installation: v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.0. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_60e47d47ceb61ba142df495e376e2453 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.0 | v1.57.0\n\n## 14. 安装坑 · 失败模式：installation: v1.57.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ddfe5da6e5463254a7ca21a7897af5c7 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.1 | v1.57.1\n\n## 15. 安装坑 · 失败模式：installation: v1.57.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_90e0287612ace3e3e390a222dfb52f45 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.2 | v1.57.2\n\n## 16. 安装坑 · 失败模式：installation: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3b813b40a8ae8f0fbc8b566627e75943 | https://github.com/CopilotKit/CopilotKit/issues/4911 | 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n## 17. 安装坑 · 失败模式：installation: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Functio...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ad59dd9220304dfaf2d38e53d40c383e | https://github.com/CopilotKit/CopilotKit/issues/2622 | 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n\n## 18. 安装坑 · 失败模式：installation: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB). Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_bc9acdf64647823252fafc35e7d96b1a | https://github.com/CopilotKit/CopilotKit/issues/4893 | 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n## 19. 安装坑 · 来源证据：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Back…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36feede08b6a456fa0702692343460fa | https://github.com/CopilotKit/CopilotKit/issues/2622 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | README/documentation is current enough for a first validation pass.\n\n## 21. 运行坑 · 失败模式：runtime: LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：Developers may hit a documented source-backed failure mode: LangGraph thread history is not hydrated after cold restart until first new message\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: LangGraph thread history is not hydrated after cold restart until first new message. Context: Observed when using python, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0bf1b00ba8b8f47db81aeaa235b28a67 | https://github.com/CopilotKit/CopilotKit/issues/3454 | LangGraph thread history is not hydrated after cold restart until first new message\n\n## 22. 运行坑 · 失败模式：runtime: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_96f6f8c3f4d6fc2c196cdd9c8b7b7356 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n## 23. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | last_activity_observed missing\n\n## 24. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 25. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 26. 能力坑 · 失败模式：capability: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / termin...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 对用户的影响：Developers may hit a documented source-backed failure mode: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0d7ae1046b9b8f5803ce38f0cd0f6a38 | https://github.com/CopilotKit/CopilotKit/issues/4885 | @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n\n## 27. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | issue_or_pr_quality=unknown\n\n## 28. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：CopilotKit/CopilotKit\n\n摘要：发现 28 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…。\n\n## 1. 安装坑 · 来源证据：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never rende…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged s…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_409f46a5944945278264fc47e297b72a | https://github.com/CopilotKit/CopilotKit/issues/4885 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6230695b9a44704927b31badcc61437 | https://github.com/CopilotKit/CopilotKit/issues/3454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_93af324180434026b3961aff8938714f | https://github.com/CopilotKit/CopilotKit/issues/4911 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0efd9d1f363946d48e1168b691b0ad4c | https://github.com/CopilotKit/CopilotKit/issues/4893 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f934812319464fb5acab93b86e00ed00 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: v1.55.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.55.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.55.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.55.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_67f1e990977177cadc4a1a612db8df88 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.55.3 | v1.55.3\n\n## 7. 安装坑 · 失败模式：installation: v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.0. Context: Observed when using node, python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_8ede7507e3ef26c20ae94eb3ff6a0f6f | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.0 | v1.56.0\n\n## 8. 安装坑 · 失败模式：installation: v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a12898a84c35b19ec1421880ce10e28 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.1 | v1.56.1\n\n## 9. 安装坑 · 失败模式：installation: v1.56.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_7a917a302b0681683ac2482e6cdefd4b | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.2 | v1.56.2\n\n## 10. 安装坑 · 失败模式：installation: v1.56.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.3. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_386de57caa0b418e81af496ef3e832e1 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.3 | v1.56.3\n\n## 11. 安装坑 · 失败模式：installation: v1.56.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.4\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.4. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ba48c40eb329f48223cab1a600a088ca | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.4 | v1.56.4\n\n## 12. 安装坑 · 失败模式：installation: v1.56.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.56.5\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.56.5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.56.5. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_985bd4475e66904ba7c8c53ae2d6f26a | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.56.5 | v1.56.5\n\n## 13. 安装坑 · 失败模式：installation: v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.0. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_60e47d47ceb61ba142df495e376e2453 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.0 | v1.57.0\n\n## 14. 安装坑 · 失败模式：installation: v1.57.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.1. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ddfe5da6e5463254a7ca21a7897af5c7 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.1 | v1.57.1\n\n## 15. 安装坑 · 失败模式：installation: v1.57.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v1.57.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v1.57.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.57.2. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_90e0287612ace3e3e390a222dfb52f45 | https://github.com/CopilotKit/CopilotKit/releases/tag/v1.57.2 | v1.57.2\n\n## 16. 安装坑 · 失败模式：installation: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3b813b40a8ae8f0fbc8b566627e75943 | https://github.com/CopilotKit/CopilotKit/issues/4911 | 🐛 Bug: @copilotkit/web-inspector@1.57.2 publishes \"workspace:*\" reference, breaks pnpm install\n\n## 17. 安装坑 · 失败模式：installation: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Functio...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ad59dd9220304dfaf2d38e53d40c383e | https://github.com/CopilotKit/CopilotKit/issues/2622 | 🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n\n## 18. 安装坑 · 失败模式：installation: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 对用户的影响：Developers may fail before the first successful local run: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB). Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_bc9acdf64647823252fafc35e7d96b1a | https://github.com/CopilotKit/CopilotKit/issues/4893 | 🐛 Bug: v2 barrel bundles streamdown/mermaid/shiki into all consumers (~+15MB)\n\n## 19. 安装坑 · 来源证据：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Back…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Bug: useRenderToolCall, useFrontendTool, useCopilotAction(disabled, remote ) Render Function Never Triggered for Backend Tool Calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36feede08b6a456fa0702692343460fa | https://github.com/CopilotKit/CopilotKit/issues/2622 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 20. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | README/documentation is current enough for a first validation pass.\n\n## 21. 运行坑 · 失败模式：runtime: LangGraph thread history is not hydrated after cold restart until first new message\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: LangGraph thread history is not hydrated after cold restart until first new message\n- 对用户的影响：Developers may hit a documented source-backed failure mode: LangGraph thread history is not hydrated after cold restart until first new message\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: LangGraph thread history is not hydrated after cold restart until first new message. Context: Observed when using python, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0bf1b00ba8b8f47db81aeaa235b28a67 | https://github.com/CopilotKit/CopilotKit/issues/3454 | LangGraph thread history is not hydrated after cold restart until first new message\n\n## 22. 运行坑 · 失败模式：runtime: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_96f6f8c3f4d6fc2c196cdd9c8b7b7356 | https://github.com/CopilotKit/CopilotKit/issues/2481 | 🐛 Bug: Cannot send 'TOOL_CALL_START' event: A tool call is already in progress. Complete it with 'TOOL_CALL_END' first.\n\n## 23. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | last_activity_observed missing\n\n## 24. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 25. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | no_demo; severity=medium\n\n## 26. 能力坑 · 失败模式：capability: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / termin...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 对用户的影响：Developers may hit a documented source-backed failure mode: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0d7ae1046b9b8f5803ce38f0cd0f6a38 | https://github.com/CopilotKit/CopilotKit/issues/4885 | @copilotkitnext/web-inspector: Current State is stale-by-one (connect STATE_SNAPSHOT / terminal STATE_DELTA never render) — missing post-apply onStateChanged subscriber\n\n## 27. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | issue_or_pr_quality=unknown\n\n## 28. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:655515393 | https://github.com/CopilotKit/CopilotKit | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# CopilotKit - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 CopilotKit 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. getting-started：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. protocols：通信协议。围绕“通信协议”模拟一次用户任务，不展示安装或运行结果。\n4. chat-ui-components：Chat UI 组件。围绕“Chat UI 组件”模拟一次用户任务，不展示安装或运行结果。\n5. react-hooks：React Hooks API。围绕“React Hooks API”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. getting-started\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. protocols\n输入：用户提供的“通信协议”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. chat-ui-components\n输入：用户提供的“Chat UI 组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. react-hooks\n输入：用户提供的“React Hooks API”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / getting-started：Step 1 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / protocols：Step 3 必须围绕“通信协议”形成一个小中间产物，并等待用户确认。\n- Step 4 / chat-ui-components：Step 4 必须围绕“Chat UI 组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / react-hooks：Step 5 必须围绕“React Hooks API”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/CopilotKit/CopilotKit\n- https://github.com/CopilotKit/CopilotKit#readme\n- .claude/skills/copilotkit-demo-parity/SKILL.md\n- .claude/skills/git-hooks/SKILL.md\n- examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/chatgpt-app-builder/SKILL.md\n- examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-apps-builder/SKILL.md\n- examples/showcases/open-mcp-client/apps/mcp-use-server/.agent/skills/mcp-builder/SKILL.md\n- README.md\n- examples/README.md\n- dev-docs/architecture/ARCHITECTURE.md\n- docs/content/docs/learn/architecture.mdx\n- docs/content/docs/learn/ag-ui-protocol.mdx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 CopilotKit 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：CopilotKit/CopilotKit\n\n## 官方安装入口\n\n### GitHub Copilot CLI · 官方安装入口\n\n```bash\nnpx copilotkit@latest\n```\n\n来源：https://github.com/CopilotKit/CopilotKit#readme\n\n## 来源\n\n- repo: https://github.com/CopilotKit/CopilotKit\n- docs: https://github.com/CopilotKit/CopilotKit#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_dbf96537fd044b08a99f8cb5cbba7412"
}