需要给现有或新项目接入 CopilotKit 时：检测框架…

适用于为已有或新建的 React-based 前端（Next.js App Router/Pages Router、Vite + React、Angular）接入 CopilotKit，从框架检测到首个可工作的聊天集成。

适用场景

解决思路

1. 使用 MCP 实时文档：若环境支持 MCP，连接 `copilotkit-docs`，用 `search-docs` 查询文档、`search-code` 查询源码；Claude Code 由插件 `.mcp.json` 自动配置，Codex 需按 copilotkit-debug skill 手动配置。
2. 开始前验证环境：Node.js >= 18；准备一个 AI provider API key（`OPENAI_API_KEY`、`ANTHROPIC_API_KEY` 或 `GOOGLE_API_KEY`）；确认前端是 React-based（Next.js App Router、Next.js Pages Router、Vite + React 或 Angular）；确认后端能运行 runtime（同一 Next.js app 的 API routes，或独立 Express/Hono server）。
3. 生成代码前检测框架：检查项目根目录文件；完整决策树见 `references/framework-detection.md`。
4. 按信号文件判断框架：`next.config.{js,ts,mjs}` + `app/` 目录 => Next.js App Router；`next.config.{js,ts,mjs}` + `pages/` 目录 => Next.js Pages Router；`angular.json` => Angular；`vite.config.{js,ts}` + package.json 中 React 依赖 => Vite + React。
5. 所有包使用 `@copilotkit` 命名空间；安装前端 React 包：`npm install @copilotkit/react @copilotkit/core`。
6. 安装 runtime 后端包：`npm install @copilotkit/runtime @copilotkit/agent`。
7. 如果 runtime 与前端在同一 Next.js app 中运行，一次性安装四个包：`@copilotkit/react @copilotkit/core @copilotkit/runtime @copilotkit/agent`。
8. 如果使用独立 Express 后端，额外安装：`npm install express cors`，以及 `npm install -D @types/express @types/cors`。
9. 配置 runtime：runtime 是服务端组件，负责管理 agent 执行；细节见 `references/runtime-architecture.md`。
10. 选择端点风格：multi-route（Hono）用 `createCopilotEndpoint`，需要 catch-all route（Next.js 中 `[[...slug]]`），每个操作（run、connect、stop、info、transcribe、threads）有独立 HTTP 路径；single-route（Hono 或 Express）用 `createCopilotEndpointSingleRoute` 或 `createCopilotEndpointSingleRouteExpress`，所有操作走同一个 POST 端点并用 method multiplexing。
11. Next.js App Router 推荐 multi-route + Hono：创建 `src/app/api/copilotkit/[[...slug]]/route.ts`，用 `new BuiltInAgent({ model: 'openai/gpt-4o', prompt: 'You are a helpful AI assistant.' })`，`new CopilotRuntime({ agents: { default: agent }, runner: new InMemoryAgentRunner() })`，`createCopilotEndpoint({ runtime, basePath: '/api/copilotkit' })`，并 `export const GET = handle(app); export const POST = handle(app);`；需要 `npm install hono`。
12. Next.js App Router 替代 single-route：创建 `src/app/api/copilotkit/route.ts`，同样构造 `BuiltInAgent`、`CopilotRuntime`、`InMemoryAgentRunner`，改用 `createCopilotEndpointSingleRoute({ runtime, basePath: '/api/copilotkit' })`，只 `export const POST = handle(app);`；前端 Provider 需设置 `useSingleEndpoint`。
13. 独立 Express server：创建 `src/index.ts`，引入 `express`、`CopilotRuntime`、`createCopilotEndpointSingleRouteExpress`（从 `@copilotkit/runtime/express`）、`BuiltInAgent`、`defineTool`、`z`；构造 `BuiltInAgent({ model: 'openai/gpt-4o' })` 和 `CopilotRuntime({ agents: { default: agent } })`；`app.use('/api/copilotkit', createCopilotEndpointSingleRouteExpress({ runtime, basePath: '/' }))`；监听 `Number(process.env.PORT ?? 4000)`。
14. 多路由 Express 使用 `createCopilotEndpointExpress`（从 `@copilotkit/runtime/express` 导入）替代单路由函数。
15. 独立 Hono server（非 Vercel）：引入 `CopilotRuntime`、`createCopilotEndpoint`、`BuiltInAgent`、`serve`（`@hono/node-server`）；构造 runtime；`createCopilotEndpoint({ runtime, basePath: '/api/copilotkit' })`；`serve({ fetch: app.fetch, port: 8787 })`；安装 `npm install hono @hono/node-server`。
16. 设置前端 Provider：用 `CopilotKitProvider`（来自 `@copilotkit/react`）包裹应用。
17. 在根 layout 引入样式：`import '@copilotkit/react/styles.css';`。
18. Next.js App Router 示例：在 `src/app/page.tsx` 或客户端组件中写 `'use client';`，用 `<CopilotKitProvider runtimeUrl='/api/copilotkit'>` 包裹 `<div style={{ height: '100vh' }}><CopilotChat /></div>`。
19. 连接外部 runtime：当 runtime 在独立 server（如 Express 端口 4000）时，设置 `<CopilotKitProvider runtimeUrl='http://localhost:4000/api/copilotkit' useSingleEndpoint>`；后端用 `createCopilotEndpointSingleRoute` 或 `createCopilotEndpointSingleRouteExpress` 时必须设置 `useSingleEndpoint`。
20. 按需配置 `CopilotKitProvider` 关键 props：`runtimeUrl`（runtime 端点 URL）；`useSingleEndpoint`（single-route 端点时设 `true`）；`headers`（每次请求带自定义 headers）；`credentials`（fetch credentials 模式，如 `'include'` 带 cookies）；`publicApiKey`（使用 hosted runtime 时的 Copilot Cloud public API key）；`showDevConsole`（显示 dev inspector，`'auto'` 仅开发环境）；`renderToolCalls`（自定义 tool call UI renderers）；`frontendTools`（前端定义 tools，`useFrontendTool` 的声明式替代）；`onError`（全局错误处理）。
21. 添加聊天 UI：三选一预构建布局：`CopilotChat`（内联聊天，填满容器）、`CopilotSidebar`（可折叠侧边栏面板）、`CopilotPopup`（浮动弹窗组件）。
22. Sidebar 示例：在 `CopilotKitProvider` 内加 `<CopilotSidebar defaultOpen width='420px' labels={{ modalHeaderTitle: 'AI Assistant', chatInputPlaceholder: 'Ask me anything...' }} />`，Provider 可设 `showDevConsole='auto'`。
23. 设置环境变量：创建 `.env.local`（Next.js）或 `.env`，写入 `OPENAI_API_KEY=sk-...`。
24. 理解 API key 自动解析：`BuiltInAgent` 根据 model 前缀从环境变量解析：`openai/*` 读 `OPENAI_API_KEY`，`anthropic/*` 读 `ANTHROPIC_API_KEY`，`google/*` 读 `GOOGLE_API_KEY`；也可直接向 `BuiltInAgent` 传 `apiKey`。
25. 连接云平台/遥测：询问用户是否连接 CopilotKit 云平台（默认 yes）。
26. 若同意，运行 `npx copilotkit auth`（先用 `npx copilotkit --help` 确认命令，可能随版本变化）。
27. 引导用户完成浏览器认证。
28. 认证完成后 CLI 输出 license key（格式 `ck_...`）。
29. 将 license key 加到 `CopilotKitProvider`：`licenseKey='ck_...'`；或存为环境变量 `COPILOTKIT_LICENSE_KEY`（`.env.local` 或 `.env`）并引用 `process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY`；细节见 `references/telemetry-setup.md`。
30. 验证 setup：启动 dev server。
31. 在浏览器打开应用。
32. 确认聊天 UI 渲染并连接到 runtime。
33. 发送测试消息，确认收到 AI 响应。
34. 检查 runtime 的 `/info` 端点（GET），确认报告可用 agents。
35. 参考包用途：`@copilotkit/react`（React 组件、hooks、provider）；`@copilotkit/core`（核心类型、agent 抽象、状态管理）；`@copilotkit/runtime`（服务端 runtime、endpoint factories、agent runners）；`@copilotkit/agent`（`BuiltInAgent`、`defineTool`、model resolution）；`@copilotkit/shared`（共享工具、logger、类型）。
36. 按框架选择 endpoint factory：`createCopilotEndpoint`（`@copilotkit/runtime`，multi-route Hono，Next.js App Router/Hono standalone）；`createCopilotEndpointSingleRoute`（`@copilotkit/runtime`，single-route Hono，Next.js App Router）；`createCopilotEndpointExpress`（`@copilotkit/runtime/express`，multi-route Express，Express standalone）；`createCopilotEndpointSingleRouteExpress`（`@copilotkit/runtime/express`，single-route Express，Express standalone）。
37. 选择 runtime class：`CopilotRuntime`（兼容 shim，自动选择 SSE 或 Intelligence 模式）；`CopilotSseRuntime`（显式 SSE 模式，默认，内存 threads）；`CopilotIntelligenceRuntime`（Intelligence 模式，持久 threads，实时事件）。
38. 选择 agent runner：`InMemoryAgentRunner`（默认，thread state 存在进程内存，适合开发与单实例部署）；`IntelligenceAgentRunner`（与 `CopilotIntelligenceRuntime` 自动使用，通过 WebSocket 连接 CopilotKit Intelligence Platform）。
39. 选择 BuiltInAgent 模型：格式为 `provider/model-name` 字符串或 Vercel AI SDK `LanguageModel` 实例。
40. OpenAI 模型可选：`openai/gpt-5`、`openai/gpt-5-mini`、`openai/gpt-4.1`、`openai/gpt-4.1-mini`、`openai/gpt-4.1-nano`、`openai/gpt-4o`、`openai/gpt-4o-mini`、`openai/o3`、`openai/o3-mini`、`openai/o4-mini`。
41. Anthropic 模型可选：`anthropic/claude-sonnet-4.5`、`anthropic/claude-sonnet-4`、`anthropic/claude-3.7-sonnet`、`anthropic/claude-opus-4.1`、`anthropic/claude-opus-4`、`anthropic/claude-3.5-haiku`。
42. Google 模型可选：`google/gemini-2.5-pro`、`google/gemini-2.5-flash`、`google/gemini-2.5-flash-lite`。
43. 自定义/未列出模型：`BuiltInAgent` 接受任意 `string`；provider 从 `/` 前的 prefix 解析。

适用边界 · 注意事项

• 前端不是 React-based（Next.js App Router/Pages Router、Vite + React、Angular）或后端无法运行 Node runtime 时，不要按此流程接入。
• Node.js < 18，或没有 `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`/`GOOGLE_API_KEY` 等 AI provider key 时，先补齐环境。
• 不想连接 CopilotKit 云平台/遥测时，跳过 Step 6（云平台连接）；这不影响本地聊天接入。