[{"content":"项目地址: https://github.com/caixy-plus/cc-gateway\ncc-gateway 是一个用 Rust 编写的网关工具，让你通过 飞书/Lark、Telegram、QQ 聊天机器人或浏览器 WebUI，远程驱动运行在本机上的多种智能体 CLI —— Claude Code、Cursor、Pi、OpenCode 等。\n本次大更新：从最初\u0026quot;飞书 + 本地 CLI 控制 Claude\u0026quot;，进化为 多平台接入 + 多智能体可插拔 的网关，并新增聊天隔离、配对放行与 WebUI 仪表盘。\n功能特性 远程控制: 用手机上的聊天机器人操作本机智能体 多平台: 飞书/Lark、Telegram、QQ 官方机器人，可同时启用任意组合 多智能体: 可插拔后端（claude、cursor、pi、opencode 等），用 /agents 按聊天指定默认智能体 聊天隔离: 每个聊天/频道独立子进程，消息互不串线 配对放行: 可在 WebUI 中批准新聊天后再允许使用（建议开启） WebUI: 浏览器管理会话、配对、设置与实时事件 目录工具: /ll（飞书为交互卡片，Telegram/QQ/WebUI 为文本列表） 守护进程: start / stop / restart / log，端口绑定保证单实例 架构设计 用户 (飞书/Lark) \u0026lt;--\u0026gt; cc-gateway 守护进程 \u0026lt;--\u0026gt; 本地智能体 CLI 用户 (Telegram) \u0026lt;--\u0026gt; cc-gateway 守护进程 \u0026lt;--\u0026gt; claude / cursor / pi / … 用户 (QQ) \u0026lt;--\u0026gt; cc-gateway 守护进程 用户 (WebUI) \u0026lt;--\u0026gt; cc-gateway 守护进程 网关以子进程方式拉起各 provider CLI，并桥接聊天消息。不同智能体使用各自的通信协议：\n智能体 协议 Claude Code stream-json（stdio） Cursor / OpenCode ACP Pi JSON-RPC 快速开始 安装 macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/caixy-plus/cc-gateway/main/install.sh | sh 安装过程会执行 cc-gateway init、重启守护进程，并输出文档链接。\nWindows\nirm https://raw.githubusercontent.com/caixy-plus/cc-gateway/main/scripts/install-irm.ps1 | iex 从源码构建\ngit clone https://github.com/caixy-plus/cc-gateway.git cd cc-gateway ./install_local.sh # macOS/Linux：构建 WebUI 并安装到 ~/.local/bin # Windows: .\\install_local.ps1 初始化配置 cc-gateway init 也可在 cc-gateway start 后通过 WebUI 设置 或编辑 ~/.cc-gateway/config.json。按需启用机器人：\n平台 配置项 飞书 / Lark feishu.enabled、app_id、app_secret Telegram telegram.enabled、bot_token QQ qq.enabled、app_id、app_secret、sandbox 将 default_dir 设为远程用户可浏览的工作区根目录（如 ~/Workspace）。多个平台可同时运行。\n启动与使用 cc-gateway start # 启动守护进程 cc-gateway webui # 打开 WebUI（配对、设置、会话） cc-gateway stop # 停止 配对后，在 WebUI 输入框或飞书/Telegram/QQ 中用 /agent 即可开始对话。\n命令参考 CLI 命令 命令 说明 cc-gateway 显示帮助（同 --help） cc-gateway init 交互式配置向导（含可选机器人凭证） cc-gateway start / stop / restart 启停/重启守护进程 cc-gateway status 查看守护进程状态 cc-gateway log [-f] [-n 100] 查看日志（-f 跟踪） cc-gateway webui 在浏览器打开 WebUI（未运行时会先 start） cc-gateway webui-token [--refresh] 查看或重新生成 WebUI 访问令牌 cc-gateway enable / disable 开关开机自启（launchd / systemd 用户服务） cc-gateway update [-y] 检查并安装最新发布版 cc-gateway uninstall 卸载二进制与服务项 网关命令（聊天内） 在 WebUI 及已接入的机器人中可用（若开启配对须先放行）：\n命令 说明 /help 显示命令列表 /quit 结束当前智能体会话 /cd \u0026lt;路径\u0026gt; 更改工作目录 /cd_default 恢复为 default_dir /agent [provider] [参数...] 启动或重启智能体会话 /agents [provider] 设置本频道默认智能体 /agent-history [n] 列出最近会话；按序号恢复 /pwd 显示当前工作目录 /ll 选择目录（飞书卡片 / 文本列表） /mkdir \u0026lt;名称\u0026gt; 创建目录 /show-thinking / /hide-thinking 开关 Thinking 输出 /stop / /clear / /status / /esc 控制当前生成（视平台支持） 执行 /agent 后，普通文本会转发给智能体；网关命令仍可使用。/quit 结束当前会话。\n技术栈 组件 技术 语言 Rust 2021 Edition 异步运行时 Tokio CLI 框架 Clap v4 HTTP / WebSocket Reqwest（rustls） / Tokio-Tungstenite 序列化 Serde + Prost（protobuf） 持久化 SQLite（rusqlite，内置打包） 并发状态 DashMap（聊天隔离） 可插拔后端 async-trait 日志 Tracing 飞书配置 前往飞书开放平台创建应用 启用\u0026quot;机器人\u0026quot;能力 添加 im.message.receive_v1 事件，选择 WebSocket 长连接模式 将 app_id 和 app_secret 复制到配置文件中 将应用安装到工作区 更多机器人（Telegram / QQ）与配置细节见仓库 docs/ 下的中英双语文档。项目采用 MIT 协议开源，由 Cai Xin Yun 开发。\n","date":"2026-05-16T00:00:00Z","permalink":"/posts/cc-gateway/","title":"cc-gateway - 多平台远程驱动智能体 CLI 的网关"},{"content":"项目地址: https://github.com/caixy-plus/ai-gobang\nAI 指导棋是一款面向围棋爱好者的智能教学应用。\n核心体验是：用户与 AI 对弈或自战解说时，获得像人类高段棋手一样的实时指导、赛后复盘和互动问答。\n技术亮点 KataGo（v1.16.4，Metal GPU）提供围棋局面分析、胜率、选点、变化图 大模型（脑池 API）将 KataGo 的数值分析翻译为自然语言教学 Flutter 跨平台客户端（macOS / iOS / Android / Windows） Spring Boot 服务端，部署在本地 K8s（OrbStack） 功能规划 阶段 功能 Phase 1（MVP） 人机对弈（KataGo 执黑/白）、基础棋盘 UI、落子同步、SGF 导入导出 Phase 2（实时指导） 对弈中 AI 提示（胜率条、推荐选点、简短评语）、用户主动请求提示 Phase 3（复盘+对话） 赛后胜率曲线、关键失误/好手标注、自然语言复盘报告、对话式问答 Phase 4（课程） 死活题/定式题库、AI 出题、作答点评、进度追踪 项目结构 ai-gobang/ ├── admin/ # 管理后台 ├── backend/ # Spring Boot 服务端 ├── mobile/ # 移动端 ├── docs/ # 设计文档 ├── deploy/ # 部署配置 └── start.sh # 启动脚本 项目采用 MIT 协议开源，欢迎 Star 和贡献。\n","date":"2026-05-13T00:00:00Z","permalink":"/posts/ai-gobang/","title":"AI 指导棋 (ai-gobang)"},{"content":"项目地址: https://github.com/caixy-plus/brain-think\napp_plat OAuth + 脑池 AI API 的端到端验证应用。\n子项目 说明 server/ Spring Boot 3.2 + Java 21 服务端（OAuth 回调编排、脑池转发、会话/对话存储） client/ Flutter 跨平台客户端（macOS / Windows / Android / iOS） 整体流程 Flutter brain-think server (:9080) app_plat backend (:8080) app_plat frontend (:3000) │ │ │ 1) 打开 InAppWebView，加载 /oauth/authorize?client_id=…\u0026amp;redirect_uri=brainthink://callback │ │ │ 2) 用户在 WebView 中：登录 ⇄ 同意授权 │ │ 3) 同意页 GET /v1/oauth/authorize → {code} │ │ 4) window.location = brainthink://callback?code=xxx │ │ │ │ 5) WebView 拦截 brainthink:// → 提取 code │ │ 6) POST /api/auth/exchange {code} │ │ │ │ │ │ 7) POST /v1/oauth/token {clientId, clientSecret, code, …} │ │ │ ← {accessToken, refreshToken} │ │ │ 落库 user_session、签 brain-think 自家 JWT 返回 │ │ ← {sessionToken} │ │ │ │ │ 8) POST /api/chat/send Bearer btJwt {message} │ │ │ 9) POST /v1/brain/chat/completions X-API-Key: dev-key-2024 │ │ │ ← {choices:[{message:{content}}]} │ │ ← {reply} │ │ 前置准备 1. 启动 app_plat（端口冲突自查） cd /Users/caixinyun/Workspace/app_plat docker compose up -d # PG :5433、Redis :6380 cd backend \u0026amp;\u0026amp; ./mvnw spring-boot:run \u0026amp; # :8080 cd ../frontend \u0026amp;\u0026amp; npm run dev \u0026amp; # :3000 brain-think 需要 frontend 跑起来——它承载补齐的 /auth/login 和 /oauth/authorize 同意页（已在 app_plat 中创建）。\n2. 控制台注册 OAuth 应用 浏览器打开 http://localhost:3000/console/applications：\n应用名：brain-think redirect_uris：必须包含 brainthink://callback 创建后记下 clientId / clientSecret 3. 脑池 API Key 脑池目前仅校验 naochi.api-keys 配置（默认包含 dev-key-2024），开发期可直接用默认值；生产可通过控制台 /console/api-keys 创建后再把它加到 app_plat 的 application.yml 里。\n跑 brain-think 服务端 cd server export PLATFORM_CLIENT_ID=\u0026lt;填上\u0026gt; export PLATFORM_CLIENT_SECRET=\u0026lt;填上\u0026gt; export PLATFORM_BRAIN_API_KEY=dev-key-2024 export BT_JWT_SECRET=$(openssl rand -hex 32) export JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn spring-boot:run 健康检查：curl http://localhost:9080/api/health → {\u0026quot;code\u0026quot;:0,\u0026quot;data\u0026quot;:{\u0026quot;status\u0026quot;:\u0026quot;UP\u0026quot;}}\n客户端 编辑 client/lib/config.dart，把 kOAuthClientId 改为上一步注册得到的 clientId。\ncd client flutter pub get flutter run -d macos # 或 windows / iOS / Android Android 模拟器：把 kBrainThinkBaseUrl 与 kPlatformWebBase 中的 localhost 换成 10.0.2.2。\n端到端验证 brain-think 启动 → SplashPage → LoginPage（嵌入 WebView 加载 /oauth/authorize） WebView 跳到 app_plat 登录页，输入账号密码 回到同意页，点\u0026quot;同意授权\u0026quot; WebView URL 变成 brainthink://callback?code=…，被拦截 自动跳到 ChatPage 输入\u0026quot;你好\u0026quot;，2~5 秒收到 AI 回复 单点验证（cURL） server/README.md 的\u0026quot;故障排查\u0026quot;可对照排错。最小手动 cURL 链：\n# A) 登录拿 user JWT（app_plat） USER_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/user/auth/login \\ -H \u0026#39;Content-Type: application/json\u0026#39; \\ -d \u0026#39;{\u0026#34;email\u0026#34;:\u0026#34;alice@example.com\u0026#34;,\u0026#34;password\u0026#34;:\u0026#34;yourpass\u0026#34;}\u0026#39; | jq -r \u0026#39;.data.accessToken\u0026#39;) # B) 拿 code CODE=$(curl -s \u0026#34;http://localhost:8080/api/v1/oauth/authorize?client_id=$CID\u0026amp;redirect_uri=brainthink://callback\u0026amp;scope=read\u0026amp;state=test\u0026#34; \\ -H \u0026#34;Authorization: Bearer $USER_TOKEN\u0026#34; | jq -r \u0026#39;.data.code\u0026#39;) # C) 换 token curl -X POST http://localhost:8080/api/v1/oauth/token \\ -H \u0026#39;Content-Type: application/json\u0026#39; \\ -d \u0026#34;{\\\u0026#34;clientId\\\u0026#34;:\\\u0026#34;$CID\\\u0026#34;,\\\u0026#34;clientSecret\\\u0026#34;:\\\u0026#34;$CSE\\\u0026#34;,\\\u0026#34;code\\\u0026#34;:\\\u0026#34;$CODE\\\u0026#34;,\\\u0026#34;grantType\\\u0026#34;:\\\u0026#34;authorization_code\\\u0026#34;}\u0026#34; # D) 脑池 curl -X POST http://localhost:8080/api/v1/brain/chat/completions \\ -H \u0026#39;X-API-Key: dev-key-2024\u0026#39; -H \u0026#39;Content-Type: application/json\u0026#39; \\ -d \u0026#39;{\u0026#34;model\u0026#34;:\u0026#34;mimo-v2-pro\u0026#34;,\u0026#34;messages\u0026#34;:[{\u0026#34;role\u0026#34;:\u0026#34;user\u0026#34;,\u0026#34;content\u0026#34;:\u0026#34;hi\u0026#34;}]}\u0026#39; app_plat 这次顺手补齐 文件 内容 frontend/src/app/auth/login/page.tsx 用户登录页（OAuth 同意页未登录时跳转过来） frontend/src/app/oauth/authorize/page.tsx OAuth 同意页（替后端做 302 跳到 redirect_uri） ","date":"2026-05-13T00:00:00Z","permalink":"/posts/brain-think/","title":"Brain Think (头脑风暴)"},{"content":"项目地址: https://github.com/caixy-plus/metronome\n微秒级精度节拍器 | 一套代码 · 五端覆盖 | 零漂移计时\n功能预览 特性 说明 微秒级精度 Stopwatch 绝对时间戳补偿，长期运行零漂移 六端全覆盖 iOS / Android / Web / Windows / macOS 一套代码 感官同步 UI 闪烁先于音频，利用人脑听觉滞后实现物理级对齐 音效池 5 套音效原子切换，内置音量标准化补偿 防御式编程 全局 null 检查、过期回调检测、资源自动释放 支持的平台 iOS Android macOS Windows Web ✅ ✅ ✅ ✅ ✅* Web 需首次点击解锁音频（浏览器自动播放策略限制）\n快速开始 安装 下载对应平台的安装包：\nmacOS: Metronome.dmg Windows: Metronome.msi Web: 访问 caixy-plus.github.io/metronome 从源码构建 # 克隆仓库 git clone https://github.com/caixy-plus/metronome.git cd metronome # 安装依赖 flutter pub get # 运行（开发模式） flutter run # 构建发布版 flutter build macos # macOS flutter build windows # Windows flutter build apk # Android flutter build web # Web 构建指南 平台要求 平台 要求 macOS Flutter SDK + Xcode Windows Flutter SDK + Visual Studio Android Flutter SDK + Android SDK Web Flutter SDK + Chrome Web 首次使用 Web 浏览器有自动播放限制，首次打开会显示 \u0026ldquo;TAP TO START\u0026rdquo; 解锁界面，点击屏幕任意位置即可启用节拍音效。\n架构设计 ┌─────────────────────────────────────────────┐ │ UI Layer │ │ MetronomeProvider │ │ (BPM 逻辑 + 高精度计时) │ └──────────────────────┬──────────────────────┘ │ implements ┌──────────────────────▼──────────────────────┐ │ AudioServiceInterface │ │ (统一播放协议：init / play) │ └──────────────────────┬──────────────────────┘ │ conditional export ┌────────────┴────────────┐ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ audio_service_ │ │ audio_service_ │ │ native.dart │ │ web.dart │ │ (flutter_soloud) │ │ (HTML5 Audio) │ └──────────────────┘ └──────────────────┘ 目录结构 lib/ ├── main.dart # 应用入口 ├── models/ # 数据模型 │ ├── metronome_settings.dart # BPM、节拍配置 │ └── sound_type.dart # 音效类型枚举 ├── providers/ # 状态管理 │ └── metronome_provider.dart # 核心计时逻辑 ├── screens/ # 页面 │ ├── home_screen/ # 主页面（含子组件） │ │ ├── home_screen.dart │ │ ├── play_button.dart │ │ ├── help_dialog.dart │ │ └── settings_bottom_sheet.dart │ └── settings_screen.dart # 设置页面 ├── widgets/ # 通用组件 │ ├── beat_indicator.dart # 节拍指示器 │ ├── beat_type_selector.dart # 节拍类型选择器 │ ├── bpm_dial.dart # BPM 旋钮 │ └── sound_type_tile.dart # 音效类型磁贴 └── utils/ # 工具类 ├── audio_service.dart # 条件导出入口 ├── audio_service_native.dart # Native 音频实现 ├── audio_service_web.dart # Web 音频实现 ├── dynamic_island_service.dart # iOS Dynamic Island ├── notification_service.dart # 后台通知 └── volume_utils.dart # 音量工具 音效资源 目录结构 assets/sounds/{folder_name}/ ├── click_high.wav # 重拍（强音） └── click_low.wav # 轻拍（弱音） 支持的音效 音效 folder 特点 经典机械音 mechanical 清脆短促，古典首选 电子合成音 electronic 80年代风格 鼓机音效 drum 现代动感 木鱼/梆子 woodblock 最高穿透力 人声倒数 voice 直观友好 注意: Flutter 不支持目录递归注册，新增音效包需在 pubspec.yaml 中显式声明。\n音频规格 要求 规格 格式 16-bit PCM WAV 采样率 44100 Hz 启动延迟 0 ms 常见问题 Q: Windows 没有声音？\n检查日志是否包含以下输出：\n[AudioService] [Windows] 初始化音频引擎... [AudioService] [Windows] 成功加载音效包 Q: Web 没有声音？\n确认显示 \u0026ldquo;TAP TO START\u0026rdquo; 界面 点击屏幕任意位置解锁音频 查看日志 [AudioService] Web 初始化完成 贡献 欢迎提交 Issue 和 Pull Request！\n许可协议 本项目基于 MIT License 开源。\n","date":"2026-05-13T00:00:00Z","permalink":"/posts/metronome/","title":"Extreme Metronome - 极致全平台节拍器"},{"content":"项目地址: https://github.com/caixy-plus/ikindle\niKindle 是一个功能完整的电子书阅读平台，支持电子书管理、多端阅读、书架管理、订单支付与数据同步。\n技术架构 组件 技术栈 后端 Java 21 + Spring Boot 3.2.3 + PostgreSQL + Redis + QueryDSL PC 前端 React 18 + TypeScript + Ant Design 移动端 Flutter（iOS / Android / macOS / Windows） 管理后台 Node.js + React 认证 JWT Token 核心功能 书籍管理 电子书分类管理（Category）、标签管理（Tag） 热门书籍、推荐书籍、最新书籍智能推荐 支持关键词搜索、价格区间筛选、分类浏览 书籍发布/下架管理（Admin） 用户系统 用户注册/登录（JWT 认证） 个人书架管理（UserBookshelf） 阅读进度同步（SyncTask） 角色权限管理（Role、Permission、Menu） 订单与支付 电子书购买订单（Order、OrderItem） 账户充值订单（RechargeOrder） 账户余额管理（Account、AccountTransaction） 支付回调处理 管理后台 用户管理、书籍管理、订单管理 系统配置（SystemConfig）、数据字典（Dict） 权限菜单配置 项目结构 ikindle/ ├── backend/ # Spring Boot 后端（:8082） │ └── com/ikindle/ │ ├── controller/ # REST API（Book, User, Order, Account...） │ ├── service/ # 业务逻辑层 │ ├── repository/ # JPA + QueryDSL 数据访问 │ ├── entity/ # 实体类（Book, User, Order...） │ └── dto/ # MapStruct DTO 转换 ├── mobile/ # Flutter 多端应用 │ ├── features/ # 功能模块（书籍浏览、阅读器、书架...） │ ├── shared/ # 共享组件 │ └── core/ # 核心配置（路由、状态管理） ├── admin/ # Node.js 管理后台 └── docs/ # 部署文档 API 设计 所有 API 以 /api/ 为前缀，统一返回 ApiResponse\u0026lt;T\u0026gt; 格式：\n{ \u0026#34;code\u0026#34;: 200, \u0026#34;message\u0026#34;: \u0026#34;success\u0026#34;, \u0026#34;data\u0026#34;: { ... }, \u0026#34;timestamp\u0026#34;: 1715587200000 } 公开接口 GET /api/books — 书籍列表（支持分页、搜索、筛选） GET /api/books/hot — 热门书籍 GET /api/books/recommended — 推荐书籍 GET /api/books/latest — 最新书籍 POST /api/users/register — 用户注册 POST /api/users/login — 用户登录 认证接口 GET /api/users/** — 用户信息管理 GET /api/bookshelf/** — 书架管理 POST /api/orders/** — 订单创建与支付 快速开始 环境要求 Java: JDK 21+ PostgreSQL: 16.2+（数据库：ikindle） Redis: 7.2.4+ Node.js: 20.11.1+（管理后台） 启动后端 cd ikindle/backend mvn compile # 编译并生成 QueryDSL Q 类 mvn spring-boot:run # 启动后端（:8082） 启动移动端 cd ikindle/mobile flutter pub get flutter run # 运行 Flutter 应用 测试账号 系统启动后自动种子数据：\n管理员: admin / admin123 普通用户: test / test123 技术亮点 QueryDSL: 类型安全的动态查询，避免 SQL 拼接 MapStruct: 编译期 DTO/Entity 转换，零反射开销 统一响应: ApiResponse\u0026lt;T\u0026gt; 包装所有 API 返回 JWT 认证: 无状态认证，支持移动端和 Web 端 多端同步: SyncTask 实现阅读进度跨设备同步 权限控制: @PreAuthorize 注解实现方法级权限校验 项目采用 MIT 协议开源，由 Cai Xin Yun 开发。\n","date":"2026-05-13T00:00:00Z","permalink":"/posts/ikindle/","title":"iKindle - 电子书阅读平台"},{"content":"项目地址: https://github.com/caixy-plus/PortProcess\nPortProcess 是一款基于 Flutter 构建的跨平台端口管理工具，支持 macOS、Windows 和 Linux。\n功能特性 实时进程监控 - 自动列出所有绑定端口的本地进程 智能搜索 - 按端口号、PID 或进程名过滤进程 一键终止 - 单击终止进程（带确认提示） 原生系统集成 - UI 颜色与系统主题色无缝融合 自动刷新 - 进程列表每 5 秒自动刷新 自定义标题栏 - 所有平台统一的现代窗口样式 支持平台 平台 文件格式 macOS (Universal) .dmg Windows (x86_64) .msi Linux (x86_64) .tar.gz 快速开始 # 克隆仓库 git clone https://github.com/caixy-plus/PortProcess.git cd PortProcess # 安装依赖 flutter pub get # 运行应用 flutter run 技术架构 lib/ ├── main.dart # 应用入口 ├── models/ │ └── process_info.dart # 进程数据模型 ├── services/ │ └── process_service.dart # 平台特定的进程获取 └── screens/ └── home_screen.dart # 主界面 各平台支持的命令 平台 列出端口 终止进程 macOS lsof kill -9 Linux ss / netstat kill -9 Windows netstat taskkill 自动发布 推送版本标签即可触发 GitHub Actions 自动构建：\ngit tag v1.0.0 git push origin v1.0.0 项目采用 MIT 协议开源，由 Cai Xin Yun 开发。\n","date":"2026-05-13T00:00:00Z","permalink":"/posts/portprocess/","title":"PortProcess - 跨平台端口管理工具"},{"content":"项目地址: https://github.com/caixy-plus/super-async\n通用异步任务调度平台 —— 高吞吐、低延迟、可水平扩展的分布式任务调度与执行框架。\n项目介绍 SuperAsync 是一个面向生产环境的通用异步任务调度平台，支持两种执行模式：\nServer 本地模式：调度器与执行器同进程，适合单机高吞吐场景。 Worker 远程模式：调度器通过 HTTP 向独立 Worker 分发任务，支持水平扩展。 核心特性：\nPostgreSQL + FOR UPDATE SKIP LOCKED：原生支持高并发任务抢占，无需额外消息队列。 任务优先级 + 延迟调度：支持优先级队列与精确到毫秒的延迟执行。 自动重试 + 超时监控：失败自动退避重试，超时任务自动回滚。 定时任务（Cron）：内置 Cron 表达式解析，支持秒级精度。 工作流引擎（DAG）：支持基于 DAG 的复杂任务编排（Beta）。 Spring Boot 自动装配：一行配置即可接入现有项目。 架构概览 ┌─────────────────────────────────────────────────────────────┐ │ SuperAsync Server │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Task Submit │──▶│ PostgreSQL │◀──│ Task Polling │ │ │ │ REST API │ │ async_tasks │ │ Scheduler(5s) │ │ │ └─────────────┘ └──────────────┘ └─────────────────┘ │ │ │ ▲ │ │ │ │ │ ▼ │ │ │ ┌──────────────┐ ┌──────────┐ │ │ │ │ ScheduledJob │ │ Executor │ │ │ │ │ Engine │ │ Engine │ │ │ │ └──────────────┘ └──────────┘ │ │ │ │ │ │ ┌──────▼────────────────────────────────────────────▼───┐ │ │ │ REST API: /v1/worker/poll │ │ │ │ REST API: /v1/worker/complete │ │ │ └───────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ▲ │ HTTP ┌─────────────────────────────────────────────────────────────┐ │ SuperAsync Worker (SDK) │ │ ┌──────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │ │ Poll Loop │──▶│ SuperAsyncWorker │──▶│ Handler │ │ │ │ (3s/100ms) │ │ Registry │ │ @SuperAsync │ │ │ └──────────────┘ └─────────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ 调度流程 客户端通过 TaskDispatcher.submit() 将任务写入 async_tasks 表（状态 PENDING）。 本地模式：TaskPollingScheduler 定期轮询 PENDING 任务（默认 5s，可配置），调用 TaskExecutorEngine 在线程池中执行。任务提交后会即时触发一次轮询，消除等待延迟。 Worker 模式：SuperAsyncWorkerEngine 定期 HTTP 轮询 /v1/worker/poll，抢到任务后在本机线程池执行，结果通过 /v1/worker/complete 回写。支持批量抢锁（一次 HTTP 拉取多条任务）。 定时任务：JobSchedulerEngine 定期扫描 scheduled_jobs 表（默认 10s，可配置），触达时间的任务会生成对应的 async_task。 快速开始 1. 环境准备 Java 21+ Maven 3.8+ PostgreSQL 14+（本地测试可用 Docker 一键启动） # 启动 PostgreSQL docker run -d --name superasync-pg \\ -e POSTGRES_DB=superasync \\ -e POSTGRES_USER=superasync \\ -e POSTGRES_PASSWORD=superasync \\ -p 5432:5432 postgres:16-alpine 2. 编译安装 git clone https://github.com/caixy-plus/super-async.git cd super-async mvn clean install -DskipTests 3. 启动 Server cd super-async-server mvn spring-boot:run Server 默认启动在 http://localhost:8080，自动执行 Flyway 迁移创建表结构。\n4. 运行性能测试 cd super-async-benchmark mvn spring-boot:run 测试完成后会在控制台输出 Markdown 格式的性能报告。\n接入指南 Server 本地模式 在业务服务中引入 super-async-server，通过 @TaskHandler 注解注册本地执行器：\nimport com.superasync.annotation.TaskHandler; import com.superasync.dto.TaskContext; import com.superasync.dto.TaskResult; import org.springframework.stereotype.Component; @Component public class OrderTaskHandler { @TaskHandler(\u0026#34;ORDER_PAYMENT\u0026#34;) public TaskResult handlePayment(TaskContext ctx) { String orderId = ctx.getPayload(); // 执行业务逻辑 return TaskResult.ok(\u0026#34;paid\u0026#34;); } } 提交任务：\nimport com.superasync.dto.TaskRequest; import com.superasync.dto.Priority; import com.superasync.service.TaskDispatcher; @Service public class OrderService { @Autowired private TaskDispatcher taskDispatcher; public void createOrder(String orderId) { TaskRequest request = TaskRequest.builder() .taskType(\u0026#34;ORDER_PAYMENT\u0026#34;) .taskKey(\u0026#34;order_\u0026#34; + orderId) .payload(orderId) .priority(Priority.HIGH) .delay(Duration.ofSeconds(30)) // 30s 后执行 .timeout(Duration.ofMinutes(5)) .maxRetry(3) .build(); taskDispatcher.submit(request); } } Worker 远程模式 在独立 Worker 服务中引入 super-async-sdk：\n1. 配置 application.yml：\nsuperasync: worker: enabled: true worker-id: worker-node-1 server-url: http://localhost:8080 core-pool-size: 16 poll-interval-ms: 3000 tags: - PAYMENT_WORKER 2. 编写 Worker 处理器：\nimport com.superasync.dto.TaskContext; import com.superasync.dto.TaskResult; import com.superasync.worker.annotation.SuperAsyncWorker; import org.springframework.stereotype.Component; @Component public class PaymentWorker { @SuperAsyncWorker(\u0026#34;ORDER_PAYMENT\u0026#34;) public TaskResult handle(TaskContext ctx) { // 执行业务逻辑 return TaskResult.ok(\u0026#34;done\u0026#34;); } } 3. 提交时指定 workerTag：\nTaskRequest request = TaskRequest.builder() .taskType(\u0026#34;ORDER_PAYMENT\u0026#34;) .taskKey(\u0026#34;order_\u0026#34; + orderId) .payload(orderId) .workerTag(\u0026#34;PAYMENT_WORKER\u0026#34;) // 指定由该标签的 Worker 执行 .build(); taskDispatcher.submit(request); 性能测试报告 测试环境：MacBook Pro (Apple Silicon, 8C), Java 21, PostgreSQL 16 (Docker)\n测试结果 简单任务延迟测试 (Worker模式-手动驱动) 指标 数值 平均延迟 253.00 ms P50 延迟 245 ms P95 延迟 434 ms P99 延迟 489 ms 简单任务吞吐量测试 (本地模式-手动驱动) 指标 数值 平均延迟 34.30 ms P50 延迟 33 ms P95 延迟 54 ms P99 延迟 76 ms 吞吐量 3937 tasks/s 万级任务吞吐量测试 (本地模式-手动驱动) 指标 数值 提交任务数 10,000 完成任务数 10,000 失败任务数 0 总耗时 1.93 s 吞吐量 5186.72 tasks/s 平均延迟 348.42 ms P50 延迟 376 ms P95 延迟 483 ms P99 延迟 493 ms 最大延迟 702 ms 结果分析 本地模式延迟：通过即时调度（eager poll），任务提交后毫秒级触发 pollAndDispatch，P50 达到 33ms，具备百毫秒级调度能力。 Worker 模式延迟：通过批量抢锁（一次 HTTP 拉取 10 条任务），HTTP 往返次数减少 90%，P50 达到 245ms。 万级吞吐：1 分钟内提交 10,000 条任务，系统在 1.93 秒内全部完成，峰值吞吐达 5186 tasks/s，零失败。 模块说明 super-async/ ├── super-async-sdk/ # 客户端 SDK + Worker 运行时 │ ├── SuperAsyncClient # HTTP 客户端（提交任务、注册定时任务） │ ├── SuperAsyncWorkerEngine # Worker 轮询与执行引擎 │ └── @SuperAsyncWorker # Worker 处理器注解 ├── super-async-server/ # 调度服务端 │ ├── TaskPollingScheduler # 本地任务轮询调度器 │ ├── TaskExecutorEngine # 本地任务执行引擎 │ ├── JobSchedulerEngine # 定时任务调度引擎 │ ├── WorkflowEngine # DAG 工作流引擎 │ └── REST API # 任务管理 + Worker 通信接口 └── super-async-benchmark/ # 性能测试与接入示例 ├── BenchmarkOrchestrator # 多场景测试编排器 ├── BenchmarkTaskController# 双模式任务处理器示例 └── BenchmarkReport # 性能指标与报告生成 开源协议 本项目基于 Apache License 2.0 开源。\n注意：SuperAsync 目前处于积极开发阶段，API 可能在正式 1.0 发布前发生变动。生产环境使用前建议进行充分压测与容错验证。\n","date":"2026-05-13T00:00:00Z","permalink":"/posts/super-async/","title":"SuperAsync - 通用异步任务调度平台"}]