Cuckoo Code：让网页AI执行本地工具

内嵌式 AI Agent 桌面应用——自动识别 AI 回复中的命令和工具调用并在本地执行

Cuckoo Code English | 中文 本系统仅用于学习使用,通过本系统造成的任何损失由使用者自行承担 下载最新版本 Cuckoo Code 是一个零 Token 成本的 AI Agent 桌面端。 📐 要改代码 / 做新需求？先读 架构与开发指南（目录结构、依赖规则、构建流程、任务手册）。 它通过 Electron 将 AI 网页版嵌入本地窗口，并注入侧边覆盖层。AI 被系统提示词引导生成工具调用（JavaScript 代码块），经用户确认后在本地沙箱中执行，再把结果回传给 AI。整个过程不需要 API Key，你用的是网页版账号，而不是按 Token 计费的接口。 本系统完全ai生成,人类在其中只扮演需求传话筒角色, 并且除最小实现(read / edit / write 工具)外是由其他agent工具实现,其他后续迭代功能全部由 cuckoo code 自行迭代完成. 捐赠与支持 我个人不需要你的捐赠。如果你愿意支持本项目，请去捐赠 壹基金（One Foundation） ：https://onefoundation.cn/donate/ 并且我个人不会收到任何捐赠也不需要大家对我个人捐赠 已收到 1 位捐赠者支持，累计向壹基金（One Foundation)捐赠: 100 元 序号 捐赠者 金额 日期 捐赠证书 1 王先生 100 元 2026-10-26 [查看证书](https://onefoundation.cn/cert/20261026131837934/) 名单持续更新中，完整历史详见 DONORS.md 捐赠者权益： 深度定制开发 单独社区群聊 优先咨询服务 💝 捐赠后请通过以下方式联系我（注明「Cuckoo 捐赠」），我会将你加入 捐赠者名单： QQ：61519628 微信：w_y_p666 邮箱：[email protected] 核心特性 丰富网页版AI能力 直接复用网页版聊天能力，把网页版 AI 丰富成可执行本地操作的 Agent。 多平台 Provider 框架 内置 平台 作为学习demo 每个平台独立封装输入框定位、发送按钮检测、回复完成判断、消息解析等差异 新建窗口时可选择平台，也可导入自定义 Provider（提供类型声明和模板，降低扩展门槛） 真正的 AI Agent 不只是聊天。AI 可以读写文件、搜索代码、执行命令、查询数据库、调用 MCP 工具，并依据执行结果继续下一步，形成"思考 → 行动 → 观察 → 再行动"的 Agent 循环。 主要功能 多窗口管理：每个窗口独立 Profile 上下文，互不干扰；可勾选「默认」在启动时自动打开 地址栏：顶部地址栏显示/复制 URL、前进后退刷新、快速跳转；下方状态条显示 token 用量与输出速度（TPS） 飞书推送：AI 回复可推送到飞书（交互卡片渲染 Markdown，含表格） 项目初始化：选择项目目录后，AI 获得目录树和系统提示词，操作基于真实项目上下文 纯净对话模式（Harness）：类 Codex 的纯对话界面——隐藏底层指令，只显示用户消息 / 模型回复 / 工具卡片，支持流式渲染、Markdown、KaTeX 数学公式、思考过程折叠、Goal/Plan 面板（Ctrl+Shift+H 切换） 工作区侧边栏：按项目分组列出所有对话，支持重命名 / 归档 / 新建；对话可展开查看子代理与压缩历史（会话血缘） 项目文件树：VSCode 风文件树，类型图标 / 配色、文件名搜索、悬停一键 @ 引用路径 文件预览（Monaco）：点文件在树右侧预览内容（VSCode 同款编辑器：行号 + 语法高亮），不遮挡 AI；左条拖拽调树宽、右条拖拽调侧栏总宽 插件市场：以 GitHub topic:cuckoo-plugin 为源自动发现插件，一键安装 / 卸载 / 启停（插件可打包技能 / 代理 / 规则 / MCP / 自定义平台 / 网页脚本）；支持 Gitee 源（国内访问更稳） AI 自动命名对话：AI 在对话开始时自动命名，工作区列表实时刷新 Skill 支持：对齐 Claude Code 的技能机制（项目级 .cuckoo/skills/ + 用户级 ~/.cuckoo/skills/），渐进式披露——教 AI 掌握特定领域的流程/规范/脚本。→ 配置与使用说明 Agent 支持：对齐 Claude Code 的子代理机制（项目级 .cuckoo/agents/ + 用户级 ~/.cuckoo/agents/），主对话可把任务委派给独立上下文的子代理，只回摘要——既隔离上下文又支持专门化。→ 配置与使用说明 Rules 支持：对齐 Claude Code 的规则机制（项目级 .cuckoo/rules/ + 用户级 ~/.cuckoo/rules/），规则可绑定文件路径（paths）——只在 AI 读到相关文件时才注入，把"改这里要注意什么"精准告诉 AI。→ 配置与使用说明 工具调用系统：AI 可调用读写文件、搜索代码、执行命令、查询数据库等工具 工具执行遮罩：执行期间在 AI 页面显示遮罩，可点击「停止」取消回传 MCP 支持：采用 Claude Desktop 兼容格式配置，支持 stdio / http 类型 server 覆盖层面板：显示命令预览、执行结果和历史记录，支持 Ctrl+Shift+C 或 Esc 切换 上下文压缩：长会话自动压缩（清 IDB + 刷新 + 建分享链接），避免超上下文上限 自动重试：两类机制——① 回复被服务端截断/失败时按退避重试；② 看门狗检测 SSE 流静默时催「请继续」 会话持久化：登录状态和设置保存到 %APPDATA%/cuckoo-ai-pro-session 安全机制：30 秒命令超时、60 秒沙箱超时、1MB 输出缓冲区、危险命令确认（含复合命令检测）；webFetch 可选拒绝访问内网地址（防 SSRF，设置页开启） 安装与运行 环境要求 Node.js >= 16.0.0（与 package.json 的 engines 一致；建议 18+） npm 步骤 # 克隆仓库 git clone https://github.com/wangyongpeng90/cuckoo-code.git cd cuckoo-code # 安装依赖 npm install # 若 npm 阻止了 electron/esbuild 的 postinstall 脚本（allowScripts 机制），先批准： # npm install-scripts ls # 查看被阻止的包 # npm install-scripts approve --all # 或逐个 approve electron esbuild # npm install # 再装一次，确保二进制下载 # 否则 electron 二进制不会下载，启动会报错 # 启动应用 npm start 使用指南 启动应用，选择平台（DeepSeek / Claude / 自定义 Provider） 正常登录对应平台的网页版账号 点击「初始化项目」选择项目目录，AI 会获得目录树和系统提示词 与 AI 对话，让它帮你修改文件、运行命令、查询代码等 AI 回复中的工具调用会被自动检测并执行 执行结果自动回传 AI，AI 继续下一步，直到任务完成 工具调用示例 AI 回复中包含以下格式的 cuckoo 代码块时，系统会在沙箱中执行，并把结果回传给 AI： ```cuckoo const content = await read("src/infra/paths.ts"); await write("src/infra/paths.ts", content.replace("resolveAsset", "resolveResource")); ``` 工具系统 支持的工具（通过 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 attachFile(path) 将本地文件作为附件上传到输入框 mcpListServers() 列出已配置的 MCP server mcpGetTools(serverName) 查看 MCP server 工具列表 mcpCall(server, tool, args) 调用 MCP 工具 log(...args) 输出中间结果到执行日志 所有文件操作均相对于当前绑定的项目目录，确保安全。 MCP 配置 MCP 配置采用 Claude Desktop 兼容格式（可直接分享/导入）： { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/my-project"] } } } 支持 stdio（command + args）和 http（url + headers）两种类型。启用/禁用状态单独存储，不污染主配置。通过覆盖层的「MCP」按钮打开管理面板。→ 配置与使用说明 Skill 配置 Skill（技能）让 AI 掌握特定领域的流程、规范、脚本，对齐 Claude Code 的 Agent Skills 机制。 技能是带 frontmatter 的 SKILL.md，放在约定目录下： 项目级：<项目根>/.cuckoo/skills/<name>/SKILL.md（随仓库走，团队共享） 用户级：~/.cuckoo/skills/<name>/SKILL.md（所有项目通用） 初始化项目时自动扫描，把技能的 name + description + 路径注入系统提示词（渐进式披露，不塞全文）。AI 判断任务相关时，会主动 read 该 SKILL.md 全文，再按其中指令执行；技能若附带脚本，AI 会用 bash/pwsh 运行。 --- name: my-skill description: 一句话说明这个技能做什么。当用户需要 xxx 时使用。 when_to_use: 用户想 xxx 时 allowed-tools: read, edit, bash --- # 技能正文 这里写具体流程、规范、示例。 完整说明（目录约定、字段、示例）→ Skill 配置与使用 Agent 配置 Agent（子代理）让主对话把任务委派给独立上下文的子对话，只回摘要，对齐 Claude Code 的 subagents 机制。 代理是带 frontmatter 的 .md 文件： 项目级：<项目根>/.cuckoo/agents/<name>.md（随仓库走，团队共享） 用户级：~/.cuckoo/agents/<name>.md（所有项目通用） 初始化项目时自动扫描，把代理的 name + description 注入系统提示词。主对话判断任务适合委派时，用 runAgent(name, task) 调用——子代理在独立上下文中完成，只把结果摘要返回。 双重价值：① 上下文隔离（缓解长对话卡顿）；② 专门化 + 工具限制。 --- name: code-reviewer description: 审查代码质量。写完代码后使用。 tools: read, grep, glob maxTurns: 20 --- 你是资深代码审查专家。审查指定代码，找出真问题并给出建议。 **完整说明（目录约定、字段、示例、内置代理）→ Agent 配置与使用 Rules 配置 Rules（规则）让 AI 只在读相关文件时看到对应的项目约束，对齐 Claude Code 的 .claude/rules/ 机制。 规则是带 frontmatter 的 .md 文件： 项目级：<项目根>/.cuckoo/rules/<name>.md（随仓库走，团队共享） 用户级：~/.cuckoo/rules/<name>.md（所有项目通用） 两种规则： 有 paths → 只在 AI 读匹配文件时注入（省上下文） 无 paths → 初始化时注入「## 项目规则」章节（始终适用） --- name: api-rules paths: - "src/api/**/*.ts" --- # API 开发规则 - 所有接口必须校验入参 - 使用统一的错误响应格式 AI 读 src/api/user.ts 时，会自动看到这条规则（首次注入全文，之后只给提醒）。 完整说明（目录约定、字段、示例）→ Rules 配置与使用** DSH 插件兼容 Cuckoo 支持直接安装运行 DSH（DeepSeek Harness）插件——类似"鸿蒙兼容 Android 应用"的思路：Cuckoo 不依赖 DSH 代码，而是自己实现同名 API，让 DSH 插件原样跑在 Cuckoo 里。 已支持的 DSH 能力 工具定义：@deepseek-ai/dsh-tools 的 defineTool 自动转换成 Cuckoo 工具 宿主服务：ctx.agents / ctx.fs / ctx.sessi