# CodePilot **Repository Path**: kinkeylau/CodePilot ## Basic Information - **Project Name**: CodePilot - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-02 - **Last Updated**: 2026-03-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README CodePilot CodePilot === **Claude Code 的桌面 GUI 客户端** -- 通过可视化界面进行对话、编码和项目管理，无需在终端中操作。 [English](./README.md) | [日本語](./README_JA.md) [![GitHub release](https://img.shields.io/github/v/release/op7418/CodePilot)](https://github.com/op7418/CodePilot/releases) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/op7418/CodePilot/releases) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) ### 加入用户群 微信用户群二维码 扫描二维码加入微信用户群，交流使用心得、反馈问题和获取最新动态。 --- ## 功能特性 - **实时对话编码** -- 流式接收 Claude 的响应，支持完整的 Markdown 渲染、语法高亮代码块和工具调用可视化 - **会话管理** -- 创建、重命名、归档和恢复聊天会话。所有对话本地持久化存储在 SQLite 中，重启不丢失 - **项目感知上下文** -- 为每个会话选择工作目录。右侧面板实时展示文件树和文件预览，随时了解 Claude 正在查看的内容 - **可调节面板宽度** -- 拖拽聊天列表和右侧面板的边缘调整宽度，偏好设置跨会话保存 - **文件和图片附件** -- 在聊天输入框直接附加文件和图片。图片以多模态视觉内容发送给 Claude 进行分析 - **权限控制** -- 逐项审批、拒绝或自动允许工具使用，可选择不同的权限模式 - **多种交互模式** -- 在 *Code*、*Plan* 和 *Ask* 模式之间切换，控制 Claude 在每个会话中的行为方式 - **模型切换** -- 在对话中随时切换 Claude 模型（Opus、Sonnet、Haiku） - **MCP 服务器管理** -- 直接在扩展页面添加、配置和移除 Model Context Protocol 服务器。支持 `stdio`、`sse` 和 `http` 传输类型 - **自定义技能** -- 定义可复用的提示词技能（全局或项目级别），在聊天中作为斜杠命令调用 - **设置编辑器** -- 可视化和 JSON 编辑器管理 `~/.claude/settings.json`，包括权限和环境变量配置 - **Token 用量追踪** -- 每次助手回复后查看输入/输出 Token 数量和预估费用 - **自动更新检查** -- 应用定期检查新版本并在有更新时通知你 - **深色/浅色主题** -- 导航栏一键切换主题 - **斜杠命令** -- 内置 `/help`、`/clear`、`/cost`、`/compact`、`/doctor`、`/review` 等命令 - **Electron 打包** -- 桌面应用，隐藏标题栏，内置 Next.js 服务器，优雅关闭进程，自动端口分配 --- ## 截图 ![CodePilot](docs/screenshot.png) --- ## 环境要求 | 要求 | 最低版本 | |------|---------| | **Node.js** | 18+ | | **Claude Code CLI** | 已安装并完成认证（`claude --version` 可正常运行） | | **npm** | 9+（Node 18 自带） | > **注意**：CodePilot 底层调用 Claude Code Agent SDK。请确保 `claude` 命令在 `PATH` 中可用，并且已完成认证（`claude login`）。 --- ## 快速开始 ```bash # 克隆仓库 git clone https://github.com/op7418/CodePilot.git cd CodePilot # 安装依赖 npm install # 以开发模式启动（浏览器） npm run dev # -- 或者启动完整的 Electron 桌面应用 -- node scripts/build-electron.mjs # 编译 Electron 主进程（首次运行前需要） npm run electron:dev ``` 然后打开 [http://localhost:3000](http://localhost:3000)（浏览器模式）或等待 Electron 窗口弹出。 --- ## 下载 预编译版本可在 [Releases](https://github.com/op7418/CodePilot/releases) 页面下载。所有平台的安装包均由 GitHub Actions 自动构建发布。 ### 支持平台 - **macOS** -- 支持 arm64（Apple Silicon）和 x64（Intel）架构的 `.dmg` 安装包 - **Windows** -- NSIS 安装程序（`.exe`），包含 x64 + arm64 - **Linux** -- 支持 x64 和 arm64 架构，提供 `.AppImage`、`.deb` 和 `.rpm` 格式 --- ## 安装问题排查 CodePilot 尚未进行代码签名，因此操作系统在首次打开时会显示安全警告。 ### macOS 你会看到一个对话框提示 **"无法验证开发者"** 或 **"Apple 无法检查其是否包含恶意软件"**。 **方案一 -- 右键打开** 1. 在访达中右键（或 Control-点击）`CodePilot.app` 2. 从右键菜单中选择 **打开** 3. 在确认对话框中点击 **打开** **方案二 -- 系统设置** 1. 打开 **系统设置** > **隐私与安全性** 2. 向下滚动到 **安全性** 部分 3. 你会看到关于 CodePilot 被阻止的提示，点击 **仍要打开** 4. 如有提示则输入密码验证，然后启动应用 **方案三 -- 终端命令** ```bash xattr -cr /Applications/CodePilot.app ``` 此命令会移除隔离属性，macOS 将不再阻止该应用。 ### Windows Windows SmartScreen 会阻止安装程序或可执行文件。 **方案一 -- 仍要运行** 1. 在 SmartScreen 对话框中，点击 **更多信息** 2. 点击 **仍要运行** **方案二 -- 关闭应用安装控制** 1. 打开 **设置** > **应用** > **高级应用设置** 2. 将 **应用安装控制**（或"选择获取应用的位置"）切换为允许任何来源 --- ## 技术栈 | 层级 | 技术 | |------|------| | 框架 | [Next.js 16](https://nextjs.org/)（App Router） | | 桌面壳 | [Electron 40](https://www.electronjs.org/) | | UI 组件 | [Radix UI](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) | | 样式 | [Tailwind CSS 4](https://tailwindcss.com/) | | 动画 | [Motion](https://motion.dev/)（Framer Motion） | | AI 集成 | [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) | | 数据库 | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)（嵌入式，用户独立） | | Markdown | react-markdown + remark-gfm + rehype-raw + [Shiki](https://shiki.style/) | | 流式传输 | [Vercel AI SDK](https://sdk.vercel.ai/) + Server-Sent Events | | 图标 | [Hugeicons](https://hugeicons.com/) + [Lucide](https://lucide.dev/) | | 测试 | [Playwright](https://playwright.dev/) | | CI/CD | [GitHub Actions](https://github.com/features/actions)（自动构建 + tag 发版） | | 构建打包 | electron-builder + esbuild | --- ## 项目结构 ``` codepilot/ ├── .github/workflows/ # CI/CD：多平台构建和自动发版 ├── electron/ # Electron 主进程和预加载脚本 │ ├── main.ts # 窗口创建、内嵌服务器生命周期管理 │ └── preload.ts # Context bridge ├── src/ │ ├── app/ # Next.js App Router 页面和 API 路由 │ │ ├── chat/ # 新建对话页面和 [id] 会话页面 │ │ ├── extensions/ # 技能 + MCP 服务器管理 │ │ ├── settings/ # 设置编辑器 │ │ └── api/ # REST + SSE 接口 │ │ ├── chat/ # 会话、消息、流式传输、权限 │ │ ├── files/ # 文件树和预览 │ │ ├── plugins/ # 插件和 MCP 增删改查 │ │ ├── settings/ # 设置读写 │ │ ├── skills/ # 技能增删改查 │ │ └── tasks/ # 任务追踪 │ ├── components/ │ │ ├── ai-elements/ # 消息气泡、代码块、工具调用等 │ │ ├── chat/ # ChatView、MessageList、MessageInput、流式消息 │ │ ├── layout/ # AppShell、NavRail、ResizeHandle、RightPanel │ │ ├── plugins/ # MCP 服务器列表和编辑器 │ │ ├── project/ # FileTree、FilePreview、TaskList │ │ ├── skills/ # SkillsManager、SkillEditor │ │ └── ui/ # 基于 Radix 的基础组件（button、dialog、tabs...） │ ├── hooks/ # 自定义 React Hooks（usePanel 等） │ ├── lib/ # 核心逻辑 │ │ ├── claude-client.ts # Agent SDK 流式封装 │ │ ├── db.ts # SQLite 数据库、迁移、CRUD │ │ ├── files.ts # 文件系统工具函数 │ │ ├── permission-registry.ts # 权限请求/响应桥接 │ │ └── utils.ts # 通用工具函数 │ └── types/ # TypeScript 接口和 API 类型定义 ├── electron-builder.yml # 打包配置 ├── package.json └── tsconfig.json ``` --- ## 开发 ```bash # 仅运行 Next.js 开发服务器（在浏览器中打开） npm run dev # 编译 Electron 主进程（首次运行前需要执行） node scripts/build-electron.mjs # 运行完整的 Electron 桌面应用（开发模式） # （先启动 Next.js，等待就绪后打开 Electron） npm run electron:dev # 生产构建（Next.js standalone） npm run build # 构建 Electron 可分发包 + Next.js npm run electron:build # 打包特定平台 npm run electron:pack:mac # macOS DMG（arm64 + x64） npm run electron:pack:win # Windows NSIS 安装包 npm run electron:pack:linux # Linux AppImage、deb、rpm ``` ### CI/CD 项目使用 GitHub Actions 自动构建。推送 `v*` tag 会自动触发全平台构建并创建 GitHub Release： ```bash git tag v0.8.1 git push origin v0.8.1 # CI 自动构建 Windows + macOS + Linux，然后发布 Release ``` 也可以在 Actions 页面手动触发单个平台的构建。 ### 说明 - Electron 主进程（`electron/main.ts`）会 fork Next.js standalone 服务器，通过 `127.0.0.1` 上的随机可用端口进行连接 - 聊天数据存储在 `~/.codepilot/codepilot.db`（开发模式下为 `./data/`） - 应用使用 SQLite WAL 模式，并发读取性能优秀 --- ## 贡献 欢迎贡献代码。开始之前： 1. Fork 本仓库并创建功能分支 2. 使用 `npm install` 安装依赖 3. 运行 `npm run electron:dev` 在本地测试你的更改 4. 确保 `npm run lint` 通过后再提交 Pull Request 5. 向 `main` 分支提交 PR，并附上清晰的变更说明 请保持 PR 聚焦 -- 每个 PR 只包含一个功能或修复。 --- ## 许可证 MIT