windsurf-helper-opensource

🚀 Windsurf 自动注册助手 - 开源版

🎯 全自动化 Windsurf 账号注册浏览器插件，完全开源，无隐私问题。

🌟 核心优势

• 🤖 全自动化：自动生成账号 → 自动填表 → 自动获取验证码 → 一键完成
• 🔒 安全可靠：代码开源透明，数据本地存储，零隐私风险
• ⚡ 快速便捷：3分钟开始使用，两种模式任选

🎯 两种使用模式

💡 两种模式任选一，插件默认读取 extension/email-config.js 中的 provider 字段决定走哪条路径（兼容旧字段 mode）。临时邮箱模式无需后端；本地后端模式需同时启动 backend/ 下的 Node 服务。

⚠️ 重要说明

本项目完全开源，不提供预配置服务：

• ✅ 代码透明，无后门
• ✅ 数据自控，保护隐私
• ⚠️ 需要自己配置邮箱服务
• 📚 提供完整配置教程

🚀 快速开始

步骤1：下载项目

git clone https://github.com/bjfwan/windsurf-helper-opensource.git
cd windsurf-helper-opensource

步骤2：一键配置

Windows：双击 setup.bat
Mac/Linux：运行 ./setup.sh

步骤3：安装插件

1. 打开 Edge 浏览器（或 Chrome）
2. 访问 edge://extensions/
3. 打开"开发者模式"
4. 点击"加载已解压的扩展程序"
5. 选择 extension 文件夹

步骤4：配置邮箱服务

选项 A：临时邮箱模式（最简，无需后端）

⚠️ 注意：需要自己找到并集成 Windsurf 接受的临时邮箱服务，公共服务通常已被屏蔽。

编辑 extension/email-config.js：

const EMAIL_PROVIDER = 'temp-mail';

配置步骤：参考 临时邮箱配置指南

选项 B：本地后端模式（推荐长期使用）

通过 Cloudflare Email Routing 将自有域名邮箱转发到 QQ 邮箱，本地 Node.js 后端用 IMAP 拉取验证码。

前置要求：

编辑 extension/email-config.js：

const EMAIL_PROVIDER = 'qq-imap';

完整 IMAP / Cloudflare 配置见 本地后端配置指南。

步骤 5：启动本地后端（仅"本地后端模式"需要）

# Windows：一键启动（首次会自动 npm install + 创建配置文件）
start-backend.bat

# Mac/Linux：
cd backend
npm install
cp backend-config.example.js backend-config.js
# 编辑 backend-config.js 填入 QQ_EMAIL / QQ_AUTH_CODE / DOMAIN
node server.js

后端默认监听 http://localhost:3000，提供以下端点：

• GET /api/health — 健康检查
• POST /api/start-monitor — 开始监控某个邮箱
• GET /api/check-code/:sessionId — 拉取验证码
• POST /api/accounts / GET /api/accounts / DELETE /api/accounts/:id — 账号管理

步骤 6：开始使用

1. 访问 https://windsurf.com/account/register
2. 点击插件图标
3. 点击"开始注册"
4. 等待自动完成（临时邮箱模式 5 分钟内；本地后端模式 ~2 分钟）

📚 详细文档

• 📖 临时邮箱配置完整指南
• 📖 本地后端 / 云端部署配置指南
• 📐 项目架构 · 📝 变更日志

🔧 手动配置（可选）

创建配置文件

如果不使用 setup 脚本：

# Windows
copy extension\email-config.example.js extension\email-config.js
copy extension\config.example.js extension\config.js

# Mac/Linux
cp extension/email-config.example.js extension/email-config.js
cp extension/config.example.js extension/config.js

临时邮箱模式配置示例

编辑 extension/email-config.js：

// ==================== 选择来源 ====================
const EMAIL_PROVIDER = 'temp-mail';  // 临时邮箱模式

// ==================== 临时邮箱配置 ====================
const TEMP_MAIL_CONFIG = {
  provider: 'your-service',  // 子服务名称（1secmail / guerrilla-mail / ...）
  pollInterval: 5000,        // 轮询间隔：5秒
  maxAttempts: 60            // 最大尝试次数：60次（5分钟）
};

// ==================== 导出配置 ====================
const EMAIL_CONFIG = {
  provider: EMAIL_PROVIDER,
  tempMail: TEMP_MAIL_CONFIG,
  qqImap: QQ_IMAP_CONFIG,

  // 兼容旧字段
  get mode() { return this.provider; },
  get prefix() {
    return this.provider === 'temp-mail' ? 'windsurf' : this.qqImap.emailPrefix;
  },
  get domain() {
    return this.provider === 'temp-mail' ? 'tempr.email' : this.qqImap.domain;
  }
};

本地后端模式配置示例

编辑 extension/email-config.js：

// ==================== 选择来源 ====================
const EMAIL_PROVIDER = 'qq-imap';  // 本地后端模式

// ==================== 邮箱配置 ====================
const QQ_IMAP_CONFIG = {
  domain: 'yourdomain.com',      // 您的域名（在 Cloudflare 转发到 QQ 邮箱）
  emailPrefix: 'windsurf',       // 邮箱前缀，生成 [email protected]
  pollInterval: 5000,            // 轮询间隔
  timeout: 120000                // 超时时间：2 分钟
};

编辑 extension/config.js（默认连本地后端）：

const API_CONFIG = {
  BASE_URL: 'http://localhost:3000',  // 本地后端默认地址
  API_KEY: '',                          // 本地后端不需要密钥
  TIMEOUT: 10000,
  POLL_INTERVAL: 5000,
  ENDPOINTS: {
    HEALTH: '/api/health',
    START_MONITOR: '/api/start-monitor',
    CHECK_CODE: '/api/check-code',
    SAVE_ACCOUNT: '/api/accounts',
    UPDATE_ACCOUNT: '/api/accounts',
    DELETE_ACCOUNT: '/api/accounts',
    GET_ACCOUNTS: '/api/accounts'
  }
};

编辑 backend/backend-config.js（后端读取的 IMAP 凭证）：

const BACKEND_CONFIG = {
  PORT: 3000,                              // 必须与 上面的 BASE_URL 一致
  QQ_EMAIL: '[email protected]',              // 接收转发邮件的 QQ 邮箱
  QQ_AUTH_CODE: 'xxxxxxxxxxxxxxxx',        // QQ 邮箱 IMAP 授权码（不是登录密码）
  DOMAIN: 'yourdomain.com'                 // 与 email-config.js 中的 domain 一致
};
module.exports = { BACKEND_CONFIG };

💡 如果你偏好云端部署（Vercel + Supabase）而非本地后端，参考 本地后端 / 云端部署配置指南 中的 Vercel 部分，并将 BASE_URL 改为你的 Vercel 域名。

📁 项目结构

windsurf-helper-opensource/
├── README.md                  # 项目说明（本文件）
├── ARCHITECTURE.md            # 架构概览（开发者文档）
├── CHANGELOG.md               # 变更日志
├── .editorconfig              # 缩进 / EOL / 字符集一致性
├── setup.bat / setup.sh       # 浏览器插件一键配置脚本
├── start-backend.bat          # Windows 一键启动本地 Node 后端
├── docs/                      # 详细配置教程
│   ├── temp-mail-setup.md     # 临时邮箱配置指南
│   └── self-hosted-api.md     # 本地后端 / 云端部署指南
├── backend/                   # 本地 Node.js 后端（QQ 邮箱 IMAP 验证码拉取）
│   ├── server.js              # Express 服务端入口
│   ├── imap-client.js         # IMAP 客户端封装
│   ├── backend-config.example.js  # 后端配置模板
│   ├── accounts.json          # 账号本地存储（首次运行后生成）
│   └── package.json           # express + cors + imap + mailparser
└── extension/                 # 浏览器插件（MV3）
    ├── manifest.json          # 插件清单
    ├── *.example.js           # 配置模板（config / email-config）
    ├── popup/                 # 弹出界面（HTML + CSS + 脚本）
    ├── content/               # 内容脚本（注入 windsurf.com）
    ├── background/            # service worker
    └── utils/                 # 工具库（logger / ui-toast / state-machine 等）

✨ 功能特性

核心功能

• ✅ 自动生成账号信息
• ✅ 自动填写注册表单
• ✅ 自动获取验证码（5 分钟内）
• ✅ 自动提交并完成注册

高级功能

• 🎯 智能状态机管理 + 会话断点续传
• 💾 本地 IndexedDB 存储（插件侧） + 本地 JSON（后端侧）
• 📨 两种邮箱获码路径在代码中统一抽象（handleVerificationCodeReceived）
• 📊 账号管理 + 注册成功率统计面板
• 🔍 分级日志器，默认 info 级别静默，Logger.setLevel('debug') 一键详细
• 🧠 内置超级智能大脑诊断面板，一键检查环境/后端/状态机

❓ 常见问题

基础问题

extension/email-config.js
extension/config.js

故障排除

🛠️ 开发指南

重新加载插件

edge://extensions/ → 点击插件的 🔄 图标

查看调试日志

右键插件图标 → 检查 → Console 标签

调整日志详尽程度

插件使用统一的分级日志器（extension/utils/logger.js），默认级别 info。在控制台执行：

// 调试期间显示全部日志（包括 5s 轮询、状态转换、邮件检查等）
Logger.setLevel('debug');

// 只看警告与错误
Logger.setLevel('warn');

// 持久化到 chrome.storage（重新打开 popup 仍然生效）
Logger.saveLevelToStorage('debug');

可用级别：debug / info / warn / error / silent。

静态检查（无需安装依赖）

修改代码后可在项目根目录用 PowerShell 跑一遍静态 lint：

# JS 语法
Get-ChildItem extension/utils/*.js, extension/popup/*.js, `
              extension/background/*.js, extension/content/*.js |
  ForEach-Object { node -c $_.FullName }

# manifest.json 合法
Get-Content extension/manifest.json -Raw | ConvertFrom-Json | Out-Null

完整脚本（含 HTML 引用解析、CSS 变量一致性、加载顺序）见 CHANGELOG.md。

架构与变更历史

• 📐 项目架构：ARCHITECTURE.md
• 📝 变更历史：CHANGELOG.md

参与贡献

欢迎提交 Bug、功能建议或 Pull Request。提交前请：

1. 跑通上面的静态检查
2. 遵循 .editorconfig 风格（2 空格缩进、LF 行尾）
3. 用户面板提示用 ui.toast / ui.alert / ui.confirm，不要用原生 alert/confirm
4. 高频路径用 logger.debug，里程碑用 logger.info

🤝 贡献

Fork → 创建分支 → 提交更改 → Push → 发起 Pull Request

我们欢迎：

• 🐛 Bug 报告
• 💡 功能建议
• 📖 文档改进
• 🔧 代码贡献
• 📣 项目推广

📜 许可证

MIT License © 2025 bjfwan

本项目采用 MIT 许可证，允许：

• ✅ 免费使用
• ✅ 修改源代码
• ✅ 商业使用
• ✅ 私有部署
• ✅ 重新分发

⚠️ 免责声明

本工具仅供学习研究使用，请遵守相关服务条款。使用本工具产生的后果由使用者自行承担。

📞 联系方式

• 📧 Email: [email protected]
• 🐙 GitHub: @bjfwan
• 🐛 Issues: 提交问题

☕ 赞助支持

如果这个项目对您有帮助，欢迎请作者喝杯咖啡 ☕

💰 打赏方式

微信打赏

支付宝打赏

🎁 打赏福利

• 💝 所有打赏者：真诚感谢 + 优先技术支持
• 🌟 ¥50+：提出功能建议，优先开发
• 👑 ¥100+：一对一配置指导
• 🏆 ¥200+：定制化功能开发

打赏后请添加作者微信，备注"打赏+GitHub用户名"

🙏 特别鸣谢

感谢以下赞助者的支持（按时间顺序）：

暂无赞助记录，期待您成为第一位支持者！ 中转站推荐：https://vsllm.com

💬 其他支持方式

⭐ Star项目 | 🐛 提交Bug | 💡 功能建议 | 📖 改进文档 | 🔧 贡献代码 | 📣 分享推广

⭐ 如果这个项目对您有帮助，请给它一个 Star！

Made with ❤️ by bjfwan