copilotkit-contribute

为 CopilotKit 做贡献

重要： CopilotKit 内部的 v2 包使用 @copilotkit/* 命名空间。用户安装的公开 API 是 @copilotkit/*。贡献代码时，你操作的是 @copilotkit/* 源码，但用户永远看不到该命名空间。

实时文档（MCP）

此插件包含一个 MCP 服务（copilotkit-docs），提供 search-docs 和 search-code 工具，用于查询实时 CopilotKit 文档和源代码。

• Claude Code： 由插件的 .mcp.json 自动配置——无需设置。
• Codex： 需要手动配置。有关设置说明，请参阅 copilotkit-debug skill。

工作流

1. Fork 并克隆 CopilotKit/CopilotKit 仓库。
2. 安装依赖，使用 pnpm install（需要 pnpm v9.x 和 Node 20+）。
3. 构建一次，使用 pnpm build 以初始化所有包。
4. 创建分支，使用命名约定：feat/<ISSUE>-<name>、fix/<ISSUE>-<name> 或 docs/<ISSUE>-<name>。
5. 开发，使用 pnpm dev（监听所有包），或用 nx run @copilotkit/<pkg>:dev 指定某个特定包。
6. 编写并运行测试，使用 nx run @copilotkit/<pkg>:test。所有 v2 包都使用 Vitest。
7. Lint 和格式化，使用 pnpm run lint --fix && pnpm run format。
8. 提交，使用约定式提交格式：<type>(<scope>): <subject>（由 commitlint 强制执行）。
9. 推送并针对 main 分支发起 PR。CI 会构建所有包，并通过 pkg-pr-new 发布预览包。

发起 PR 之前

• 对于任何重要的工作，请先联系维护者（提交 issue 或在 Discord 上询问）。
• 运行 pnpm run test 以验证所有测试通过。
• 运行 pnpm run build 以验证完整构建成功。
• 运行 pnpm run check-prettier 以验证格式。
• 确保提交消息遵循 <type>(<scope>): <subject> 格式。

快速参考

任务	命令
安装依赖	pnpm install
构建所有包	pnpm build
开发模式（全部）	pnpm dev
开发模式（仅 v2）	pnpm dev:next
运行所有测试	pnpm run test
仅运行 v2 测试	pnpm test:next
运行单个包的测试	nx run @copilotkit/core:test
带覆盖率测试	pnpm run test:coverage
Lint	pnpm run lint
格式化	pnpm run format
检查格式	pnpm run check-prettier
类型检查	pnpm run check-types
包质量检查	pnpm run check:packages
依赖图	pnpm run graph

关键架构要点

• V2（@copilotkit/*）是真正的实现。V1（@copilotkit/*）封装了 V2。
• 新功能始终放在 packages/v2/ 下的 V2 包中。
• 前端与运行时之间的通信使用 AG-UI 协议（基于 SSE 的事件）。
• 此 monorepo 使用 Nx 进行任务编排，并使用 pnpm workspaces。

参考文档

• 贡献指南 — 完整入门演练
• 仓库结构 — 包布局与架构
• 测试指南 — Vitest 设置、运行测试、覆盖率
• PR 指南 — CI 检查、审查流程、期望