wangyongpeng90/cuckoo-code

wangyongpeng90/cuckoo-code has 301 GitHub stars and 107 forks. GitHot measured -1 stars in 24 hours, 0 in 7 days, and +12 in 15 days. Last checked 2026-11-13 05:28 UTC. Last push 2026-11-05.

这些数字如何统计

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

301 星标 107 forks

实测星标增长

24小时: -1
7天: 0
15天: +12
1个月: 正在收集历史

各周期内的星标净变化，周期相互重叠，并非每日新增。缺失的测量保持空白。星标代表关注度，不代表软件质量。

README.md

原文

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/

所有捐赠款项直接进入壹基金公益账户，与作者无关，纯属公益行为。

已通过壹基金捐赠的善款：8 笔 / 690 元

捐赠者	金额	日期	捐赠证书
烈云	100 元	2026-10-29	https://onefoundation.cn/cert/20261101152146565/
石垚	2 元	2026-10-29	https://onefoundation.cn/cert/20261101205925282/
刘先生	100 元	2026-10-29	要求匿名
CS	100 元	2026-10-29	https://onefoundation.cn/cert/20261029003017507/
杨先生	88 元	2026-10-29	https://onefoundation.cn/cert/20261029065593254/)
Hazel	100 元	2026-10-26	https://onefoundation.cn/cert/20261027103737586/
十七不是石器ᯤ	100 元	2026-10-26	https://onefoundation.cn/cert/20261026213679892/
王先生	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.sessions / ctx.settings / ctx.shell / ctx.mcpResources 等 32 个服务
客户端运行时：支持 DSH 的 ./client 入口（UI 插件、Slot 注册、React 渲染）
工作区注册表：ctx.workspaceRegistry 持久化（对齐 DSH 五道校验）
设置面板：settings.section 动态渲染插件配置表单

已验证插件

@deepseek-ai/dsh-tool-todo（官方包）：与真 DSH 输出一致
dsh-tasks：定时任务调度、窗口定位、跨窗口跳转已兼容

限制

DSH 的 119 个 Context 服务中，当前实现 32 个（27%）。新插件如果用到未实现的服务，会走 stub（可能缺高级能力）。

适配新插件时，先对照 DSH API 覆盖度清单 看用到哪些服务。

💬 想兼容哪些 DSH 插件？请进群咨询 —— 见下方交流群章节，告诉我们你希望支持的具体插件，我们会按优先级逐个适配。

自定义 Provider

想要接入新的 AI 平台？复制 src/providers/custom/provider.template.js，按模板填写：

id / name / homeUrl 等基本信息
输入框、发送按钮的选择器
matchesUrl()、extractSessionId() 等方法
自动解析相关方法（完成检测、消息定位等）

类型声明见 src/providers/types.ts。在应用内通过平台选择页导入 JS 文件即可使用。

项目结构

cuckoo-code/
├── start.js                 # 跨平台启动脚本（先编译再启动，日志写入 wyp/log/）
├── package.json             # main 指向 out/src/app/entry.js（无薄壳入口）
├── src/
│   ├── app/                 # 应用外壳（主进程）
│   │   ├── entry.ts         # 应用入口、窗口创建、应用菜单
│   │   ├── shell-preload.ts # 地址栏壳页面 preload
│   │   ├── window.ts        # 多窗口管理（WebContentsView 架构）
│   │   ├── profile.ts       # 窗口 Profile 管理
│   │   ├── token-stats.ts   # 系统总累计 token（跨窗口持久化）
│   │   └── 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 加载器与模板
│   ├── skills/              # Skill 机制（扫描 / frontmatter / 提示词）
│   ├── mcp/                 # MCP 客户端与配置
│   ├── infra/               # 基础设施（路径 / 换行符 / 日志 / 危险命令）
│   ├── prompt/              # 各平台提示词模板
│   └── ui/                  # 壳页面（shell.html / platform-select.html）
├── scripts/                 # 构建脚本（hook 打包、工具 API 生成）
├── test/                    # 单元测试
└── out/                     # TypeScript 编译产物

构建与发布

本仓库已配置 GitHub Actions，推送 v* 标签（如 v0.7.1）会自动构建 Windows 和 macOS 安装包并发布到 Releases
本地手动构建：npm run build:win:local 或 npm run build:mac:local
构建产物输出到 dist/ 目录

Roadmap

下一阶段计划见 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）
- 纯净对话模式（Harness）：类 Codex 的纯对话界面——隐藏底层指令，只显示用户消息 / 模型回复 / 工具调用卡片，含流式渲染、思考过程折叠、Goal/Plan 面板、斜杠菜单（PR #22）
- Harness 增强 + 插件市场：多会话隔离、侧栏「对话」分页、Markdown/LaTeX（KaTeX）渲染、Goal/Plan 自动驱动、插件市场（GitHub topic 自动发现与安装）（PR #23）
@jiangchengnay：
- 插件网页脚本注入：插件新增 scripts/ 贡献类型——按 URL 匹配向网页主世界注入脚本，可作用于内置平台（PR #26）
- Gitee 插件市场支持：插件市场新增 Gitee 源（检索/下载/清单），与 GitHub 并行，解决国内访问 GitHub 不稳定（PR #28）
- 子代理发送修复：修复豆包等 contenteditable 平台子代理卡在"发送任务提示词"（PR #29）
- 统一 UA 版本：设置全局 app.userAgentFallback 为干净 Chrome UA，消除壳页面 / Service Worker 与 AI 页面 UA 不一致（暴露 Electron 标识与内核完整版本号，可能触发 DeepSeek 环境异常 / Google OAuth 拒绝）（PR #71）
@8555uuy：
- 危险命令检测加固：修复复合命令（&& || ; | &）绕过检测；统一为单一真相源并补充危险变体（PR #30）
- glob 排除产物目录：未指定 path 时默认排除 node_modules 等依赖/产物目录，避免淹没项目自身文件（PR #31）
- webFetch SSRF 防护：拒绝访问内网/回环/保留地址（可在设置页开启，默认关闭）（PR #32）
- 状态栏输出速度（TPS）：显示模型输出速度，DeepSeek 用服务端精确 token，ChatGPT/Claude 估算（PR #33）
- provider 自定义工具结果格式：新增 transformToolResult 可选钩子，插件可在工具结果回传前自定义文本格式（PR #34）
- 危险命令检测增强：修复前缀修饰词（sudo/env/nohup 等）、通配符根目录（rm -rf /*）、长选项（--recursive --force、--no-preserve-root）绕过（PR #38）
- edit 保留未编辑区域换行符：编辑混合换行符文件时不再全文规整成主导格式，只改写命中区间、逐字节保留未编辑区域行尾，消除 diff 噪音（PR #39）
- 用户记忆系统：跨会话/跨项目的长期记忆（remember/forgetMemory 工具 + 正文 [记忆]xxx 标记自动捕获 + 系统提示词注入 + 侧边栏管理），并保护 ~/.cuckoo/ 用户数据不被文件工具误改（PR #40）
@ZiJiangel：
- 飞书 Markdown 卡片：飞书推送 AI 回复改用交互卡片渲染 Markdown（含表格）（PR #35）
- 可执行插件系统 + 主题系统：引入可执行插件运行时（函数/对象/类三种插件形态、5 种事件派发、服务 provide/inject、可逆副作用、资源、工具注册），主题系统 ctx.theme（主进程权威 + IPC 代理 + --ck-* token + 自绘标题栏 + 持久化），UI 原子能力（overlay / shell 挂载 / slot 槽位 / addStyle 注入 CSS）（PR #36）
@yangjh888：
- ChatGPT 登录态完整适配：回复拦截重写为三态（finished/stopped/error）、SSE 裸 {v:[...]} 增量帧解析修复、fillInput（execCommand）+ triggerSend（真实 Enter）解决 ProseMirror 输入/发送、Google OAuth 指纹修正（Sec-CH-UA* / userAgentData / webdriver）（PR #47）
@brownie19850318：
- ChatGPT 多消息流适配：修复同一条 SSE 流内多条 assistant 消息场景下，后续含 cuckoo 块的消息被提前锁定丢弃（新增 endTurn 区分消息级/整轮结束、overwriteText 防正文被覆盖）（PR #49）
- 工具执行遮罩支持取消：工具调用执行期间遮罩显示「停止」按钮，长任务可中途取消（PR #49）
- 关窗释放渲染进程：修复窗口关闭时子视图（WebContentsView）渲染进程不释放（孤儿进程 + 内存泄漏）（PR #49）
所有贡献者和用户