English | 中文
Cuckoo Code 是一个零 Token 成本的 AI Agent 桌面端。
📐 要改代码 / 做新需求？先读 架构与开发指南（目录结构、依赖规则、构建流程、任务手册）。
它通过 Electron 将 AI 网页版（DeepSeek、Claude 等）嵌入本地窗口，并注入侧边覆盖层。AI 被系统提示词引导生成工具调用（JavaScript 代码块），经用户确认后在本地沙箱中执行，再把结果回传给 AI。整个过程不需要 API Key，不产生 API 调用费用——你用的是网页版账号，而不是按 Token 计费的接口。
不调用任何 AI 平台 API，不使用 API Token。直接复用网页版聊天能力，把网页版 AI 变成可执行本地操作的 Agent。
- 内置 DeepSeek、Claude、ChatGPT 三个平台
- 每个平台独立封装输入框定位、发送按钮检测、回复完成判断、消息解析等差异
- 新建窗口时可选择平台，也可导入自定义 Provider（提供类型声明和模板，降低扩展门槛）
不只是聊天。AI 可以读写文件、搜索代码、执行命令、查询数据库、调用 MCP 工具，并依据执行结果继续下一步，形成"思考 → 行动 → 观察 → 再行动"的 Agent 循环。
- 多窗口管理：每个窗口独立 Profile 上下文，互不干扰
- 项目初始化：选择项目目录后，AI 获得目录树和系统提示词，操作基于真实项目上下文
- 工具调用系统：AI 可调用读写文件、搜索代码、执行命令、查询数据库等工具
- 命令拦截：自动检测 cmd / powershell / bash 代码块，确认后执行
- MCP 支持：采用 Claude Desktop 兼容格式配置，支持 stdio / http 类型 server
- 覆盖层面板：显示命令预览、执行结果和历史记录，支持 Ctrl+Shift+C 或 Esc 切换
- 自动重试：JS 代码执行失败且疑似代码不完整时，自动等待 1 秒重新获取并重试（最多 3 次），仍失败才回传 AI
- 会话持久化：登录状态和设置保存到 %APPDATA%/cuckoo-ai-pro-session
- 安全机制：30 秒命令超时、60 秒沙箱超时、1MB 输出缓冲区、危险命令确认
- Node.js >= 22.0.0
- npm
# 克隆仓库
git clone https://github.com/wangyongpeng90/cuckoo-code.git
cd cuckoo-code
# 安装依赖
npm install
# 如果 npm 提示 electron postinstall 脚本被阻止（allowScripts），先批准：
# npm install-scripts ls
# npm install-scripts approve electron
# npm install
# 否则 electron 二进制不会下载，启动会报错
# 启动应用
npm start- 启动应用，选择平台（DeepSeek / Claude / 自定义 Provider）
- 正常登录对应平台的网页版账号
- 点击「初始化项目」选择项目目录，AI 会获得目录树和系统提示词
- 与 AI 对话，让它帮你修改文件、运行命令、查询代码等
- AI 回复中的工具调用会被自动检测并执行
- 执行结果自动回传 AI，AI 继续下一步，直到任务完成
AI 回复中包含以下格式的 cuckoo 代码块时，系统会在沙箱中执行，并把结果回传给 AI：
```cuckoo
const content = await read("src/utils/helper.js");
await write("src/utils/helper.js", content.replace("formatDate", "formatTime"));
```支持的工具（通过 cuckoo 代码块调用）：
| JS 函数 | 功能描述 |
|---|---|
read(path, options?) |
读取文本文件（带行号窗口） |
readLines(path, options?) |
读取文件为结构化行数组 |
write(path, content) |
创建或覆盖文件 |
edit(path, old, new, replaceAll?, dryRun?) |
精确替换文件内容 |
glob(pattern, searchPath?) |
按 glob 模式查找文件 |
grep(pattern, options?) |
正则搜索文件内容 |
bash(command, options?) |
执行 shell 命令（cmd） |
pwsh(command, options?) |
执行 PowerShell 命令 |
todoWrite(todos) |
管理结构化任务列表 |
deleteFile(path) |
删除文件（不可恢复） |
webFetch(url) |
获取 HTTP(S) URL 内容（HTML 转 Markdown） |
mysql(options) |
执行 MySQL SQL |
openBrowserWindow(url, options?) |
打开 Electron 浏览器窗口 |
injectJS(windowId, code) |
向指定窗口注入 JS |
mcpListServers() |
列出已配置的 MCP server |
mcpGetTools(serverName) |
查看 MCP server 工具列表 |
mcpCall(server, tool, args) |
调用 MCP 工具 |
log(...args) |
输出中间结果到执行日志 |
所有文件操作均相对于当前绑定的项目目录，确保安全。
MCP 配置采用 Claude Desktop 兼容格式（可直接分享/导入）：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/my-project"]
}
}
}支持 stdio（command + args）和 http（url + headers）两种类型。启用/禁用状态单独存储，不污染主配置。通过覆盖层的「MCP」按钮打开管理面板。
想要接入新的 AI 平台？复制 src/providers/custom/provider.template.js，按模板填写：
id/name/homeUrl等基本信息- 输入框、发送按钮的选择器
matchesUrl()、extractSessionId()等方法- 自动解析相关方法（完成检测、消息定位等）
类型声明见 src/providers/types.ts。在应用内通过平台选择页导入 JS 文件即可使用。
cuckoo-code/
├── main.js # Electron 主进程入口（薄壳，加载 out/src/app/entry.js）
├── start.js # 跨平台启动脚本（先编译再启动，日志写入 wyp/log/）
├── preload.js # Preload 入口（薄壳）
├── src/
│ ├── app/ # 应用外壳（主进程）
│ │ ├── entry.ts # 应用入口、窗口创建、应用菜单
│ │ ├── shell-preload.ts # 地址栏壳页面 preload
│ │ ├── window.ts # 多窗口管理（WebContentsView 架构）
│ │ ├── profile.ts # 窗口 Profile 管理
│ │ └── ipc/ # IPC 处理器（project/session/command/tool/renderer/shell）
│ ├── session/ # 会话与项目上下文
│ │ ├── store.ts # 会话-目录映射持久化
│ │ ├── project-context.ts # 项目初始化
│ │ ├── prompt-builder.ts # 系统提示词组装
│ │ └── compaction.ts # 上下文压缩
│ ├── bridge/ # 与 AI 网页桥接（preload）
│ │ ├── entry.ts # preload 入口
│ │ ├── api.ts # contextBridge API 暴露
│ │ ├── intercept/ # 网络拦截响应处理
│ │ ├── parser/ # JS/JSON 工具调用解析
│ │ └── loop/ # 执行器、看门狗、重试引擎
│ ├── overlay/ # 覆盖层 UI
│ │ ├── panel.ts # 面板基础能力（注入、提示、历史）
│ │ ├── events.ts # 事件绑定（编排）
│ │ ├── panels/ # 各面板（窗口管理 / MCP / 设置）
│ │ ├── fab.ts # 悬浮球拖动
│ │ └── template/ # HTML/CSS 模板（构建期生成 TS）
│ ├── tools/ # 工具系统
│ │ ├── api.d.ts # AI 工具契约（构建期生成）
│ │ ├── core/ # Tool / ToolRegistry / ToolResult
│ │ ├── runtime/ # JsRunner 沙箱执行器
│ │ └── impl/ # 各工具实现
│ ├── providers/ # 平台 Provider
│ │ ├── types.ts # Provider 接口
│ │ ├── deepseek.ts / claude.ts / chatgpt.ts
│ │ ├── hooks/ # 网络拦截器源码（构建期打包为字符串）
│ │ └── custom/ # 自定义 Provider 加载器与模板
│ ├── mcp/ # MCP 客户端与配置
│ ├── infra/ # 基础设施（路径 / 日志 / 危险命令）
│ └── prompt/ # 各平台提示词模板
├── scripts/ # 构建脚本（hook 打包、工具 API 生成）
├── test/ # 单元测试
└── out/ # TypeScript 编译产物
- 本仓库已配置 GitHub Actions，推送
v*标签（如v0.3.0）会自动构建 Windows 和 macOS 安装包并发布到 Releases - 本地手动构建：
npm run build:win:local或npm run build:mac:local - 构建产物输出到
dist/目录
下一阶段计划见 Roadmap.md。
加入 Cuckoo Code 用户交流群，与其他用户交流使用经验：
QQ 群
微信群
群二维码约 7 天过期，如已失效请在 Issues 中提醒更新。
欢迎提交 Issue 和 Pull Request。
- 报告 Bug 或建议新功能：Issues
- 提交代码：Pull Requests
本项目使用 GNU General Public License v3.0 许可证。详见 LICENSE 文件。
- DeepSeek、Claude 提供强大的 AI 能力
- Electron 提供跨平台桌面框架
- @27584：Provider 发送扩展接口、流式稳定性双通道、自定义 Provider 渲染进程加载、MCP 工具识别等框架级改进（PR #9）
- 所有贡献者和用户