VC 分享 on 代码随手记

cc-gateway - 多平台远程驱动智能体 CLI 的网关

Sat, 16 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/cc-gateway

cc-gateway 是一个用 Rust 编写的网关工具，让你通过 飞书/Lark、Telegram、QQ 聊天机器人或浏览器 WebUI，远程驱动运行在本机上的多种智能体 CLI —— Claude Code、Cursor、Pi、OpenCode 等。

本次大更新：从最初"飞书 + 本地 CLI 控制 Claude"，进化为 多平台接入 + 多智能体可插拔 的网关，并新增聊天隔离、配对放行与 WebUI 仪表盘。

功能特性

远程控制: 用手机上的聊天机器人操作本机智能体
多平台: 飞书/Lark、Telegram、QQ 官方机器人，可同时启用任意组合
多智能体: 可插拔后端（claude、cursor、pi、opencode 等），用 /agents 按聊天指定默认智能体
聊天隔离: 每个聊天/频道独立子进程，消息互不串线
配对放行: 可在 WebUI 中批准新聊天后再允许使用（建议开启）
WebUI: 浏览器管理会话、配对、设置与实时事件
目录工具: /ll（飞书为交互卡片，Telegram/QQ/WebUI 为文本列表）
守护进程: start / stop / restart / log，端口绑定保证单实例

架构设计

用户 (飞书/Lark) <--> cc-gateway 守护进程 <--> 本地智能体 CLI
用户 (Telegram) <--> cc-gateway 守护进程 <--> claude / cursor / pi / …
用户 (QQ) <--> cc-gateway 守护进程
用户 (WebUI) <--> cc-gateway 守护进程

网关以子进程方式拉起各 provider CLI，并桥接聊天消息。不同智能体使用各自的通信协议：

智能体	协议
Claude Code	stream-json（stdio）
Cursor / OpenCode	ACP
Pi	JSON-RPC

快速开始

安装

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/caixy-plus/cc-gateway/main/install.sh | sh

安装过程会执行 cc-gateway init、重启守护进程，并输出文档链接。

Windows

irm https://raw.githubusercontent.com/caixy-plus/cc-gateway/main/scripts/install-irm.ps1 | iex

从源码构建

git 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。按需启用机器人：

平台	配置项
飞书 / Lark	`feishu.enabled`、`app_id`、`app_secret`
Telegram	`telegram.enabled`、`bot_token`
QQ	`qq.enabled`、`app_id`、`app_secret`、`sandbox`

将 default_dir 设为远程用户可浏览的工作区根目录（如 ~/Workspace）。多个平台可同时运行。

启动与使用

cc-gateway start # 启动守护进程
cc-gateway webui # 打开 WebUI（配对、设置、会话）
cc-gateway stop # 停止

配对后，在 WebUI 输入框或飞书/Telegram/QQ 中用 /agent 即可开始对话。

命令参考

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 及已接入的机器人中可用（若开启配对须先放行）：

命令	说明
`/help`	显示命令列表
`/quit`	结束当前智能体会话
`/cd <路径>`	更改工作目录
`/cd_default`	恢复为 `default_dir`
`/agent [provider] [参数...]`	启动或重启智能体会话
`/agents [provider]`	设置本频道默认智能体
`/agent-history [n]`	列出最近会话；按序号恢复
`/pwd`	显示当前工作目录
`/ll`	选择目录（飞书卡片 / 文本列表）
`/mkdir <名称>`	创建目录
`/show-thinking` / `/hide-thinking`	开关 Thinking 输出
`/stop` / `/clear` / `/status` / `/esc`	控制当前生成（视平台支持）

执行 /agent 后，普通文本会转发给智能体；网关命令仍可使用。/quit 结束当前会话。

技术栈

组件	技术
语言	Rust 2021 Edition
异步运行时	Tokio
CLI 框架	Clap v4
HTTP / WebSocket	Reqwest（rustls） / Tokio-Tungstenite
序列化	Serde + Prost（protobuf）
持久化	SQLite（rusqlite，内置打包）
并发状态	DashMap（聊天隔离）
可插拔后端	async-trait
日志	Tracing

飞书配置

前往飞书开放平台创建应用
启用"机器人"能力
添加 im.message.receive_v1 事件，选择 WebSocket 长连接模式
将 app_id 和 app_secret 复制到配置文件中
将应用安装到工作区

更多机器人（Telegram / QQ）与配置细节见仓库 docs/ 下的中英双语文档。项目采用 MIT 协议开源，由 Cai Xin Yun 开发。

AI 指导棋 (ai-gobang)

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/ai-gobang

AI 指导棋是一款面向围棋爱好者的智能教学应用。

核心体验是：用户与 AI 对弈或自战解说时，获得像人类高段棋手一样的实时指导、赛后复盘和互动问答。

技术亮点

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 和贡献。

Brain Think (头脑风暴)

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/brain-think

app_plat OAuth + 脑池 AI API 的端到端验证应用。

子项目	说明
`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=…&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 && ./mvnw spring-boot:run & # :8080
cd ../frontend && npm run dev & # :3000

brain-think 需要 frontend 跑起来——它承载补齐的 /auth/login 和 /oauth/authorize 同意页（已在 app_plat 中创建）。

2. 控制台注册 OAuth 应用

浏览器打开 http://localhost:3000/console/applications：

应用名：brain-think
redirect_uris：必须包含 brainthink://callback
创建后记下 clientId / clientSecret

3. 脑池 API Key

脑池目前仅校验 naochi.api-keys 配置（默认包含 dev-key-2024），开发期可直接用默认值；生产可通过控制台 /console/api-keys 创建后再把它加到 app_plat 的 application.yml 里。

跑 brain-think

服务端

cd server
export PLATFORM_CLIENT_ID=<填上>
export PLATFORM_CLIENT_SECRET=<填上>
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 → {"code":0,"data":{"status":"UP"}}

客户端

编辑 client/lib/config.dart，把 kOAuthClientId 改为上一步注册得到的 clientId。

cd client
flutter pub get
flutter run -d macos # 或 windows / iOS / Android

Android 模拟器：把 kBrainThinkBaseUrl 与 kPlatformWebBase 中的 localhost 换成 10.0.2.2。

端到端验证

brain-think 启动 → SplashPage → LoginPage（嵌入 WebView 加载 /oauth/authorize）
WebView 跳到 app_plat 登录页，输入账号密码
回到同意页，点"同意授权"
WebView URL 变成 brainthink://callback?code=…，被拦截
自动跳到 ChatPage
输入"你好"，2~5 秒收到 AI 回复

单点验证（cURL）

server/README.md 的"故障排查"可对照排错。最小手动 cURL 链：

# A) 登录拿 user JWT（app_plat）
USER_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/user/auth/login \
 -H 'Content-Type: application/json' \
 -d '{"email":"alice@example.com","password":"yourpass"}' | jq -r '.data.accessToken')

# B) 拿 code
CODE=$(curl -s "http://localhost:8080/api/v1/oauth/authorize?client_id=$CID&redirect_uri=brainthink://callback&scope=read&state=test" \
 -H "Authorization: Bearer $USER_TOKEN" | jq -r '.data.code')

# C) 换 token
curl -X POST http://localhost:8080/api/v1/oauth/token \
 -H 'Content-Type: application/json' \
 -d "{\"clientId\":\"$CID\",\"clientSecret\":\"$CSE\",\"code\":\"$CODE\",\"grantType\":\"authorization_code\"}"

# D) 脑池
curl -X POST http://localhost:8080/api/v1/brain/chat/completions \
 -H 'X-API-Key: dev-key-2024' -H 'Content-Type: application/json' \
 -d '{"model":"mimo-v2-pro","messages":[{"role":"user","content":"hi"}]}'

app_plat 这次顺手补齐

文件	内容
`frontend/src/app/auth/login/page.tsx`	用户登录页（OAuth 同意页未登录时跳转过来）
`frontend/src/app/oauth/authorize/page.tsx`	OAuth 同意页（替后端做 302 跳到 redirect_uri）

Extreme Metronome - 极致全平台节拍器

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/metronome

微秒级精度节拍器 | 一套代码 · 五端覆盖 | 零漂移计时

功能预览

特性	说明
微秒级精度	Stopwatch 绝对时间戳补偿，长期运行零漂移
六端全覆盖	iOS / Android / Web / Windows / macOS 一套代码
感官同步	UI 闪烁先于音频，利用人脑听觉滞后实现物理级对齐
音效池	5 套音效原子切换，内置音量标准化补偿
防御式编程	全局 null 检查、过期回调检测、资源自动释放

支持的平台

iOS	Android	macOS	Windows	Web
✅	✅	✅	✅	✅*

Web 需首次点击解锁音频（浏览器自动播放策略限制）

快速开始

安装

下载对应平台的安装包：

macOS: 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 浏览器有自动播放限制，首次打开会显示 “TAP TO START” 解锁界面，点击屏幕任意位置即可启用节拍音效。

架构设计

┌─────────────────────────────────────────────┐
│ 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 中显式声明。

音频规格

要求	规格
格式	16-bit PCM WAV
采样率	44100 Hz
启动延迟	0 ms

常见问题

Q: Windows 没有声音？

检查日志是否包含以下输出：

[AudioService] [Windows] 初始化音频引擎...
[AudioService] [Windows] 成功加载音效包

Q: Web 没有声音？

确认显示 “TAP TO START” 界面
点击屏幕任意位置解锁音频
查看日志 [AudioService] Web 初始化完成

贡献

欢迎提交 Issue 和 Pull Request！

许可协议

本项目基于 MIT License 开源。

iKindle - 电子书阅读平台

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/ikindle

iKindle 是一个功能完整的电子书阅读平台，支持电子书管理、多端阅读、书架管理、订单支付与数据同步。

技术架构

组件	技术栈
后端	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<T> 格式：

{
 "code": 200,
 "message": "success",
 "data": { ... },
 "timestamp": 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 应用

测试账号

系统启动后自动种子数据：

管理员: admin / admin123
普通用户: test / test123

技术亮点

QueryDSL: 类型安全的动态查询，避免 SQL 拼接
MapStruct: 编译期 DTO/Entity 转换，零反射开销
统一响应: ApiResponse<T> 包装所有 API 返回
JWT 认证: 无状态认证，支持移动端和 Web 端
多端同步: SyncTask 实现阅读进度跨设备同步
权限控制: @PreAuthorize 注解实现方法级权限校验

项目采用 MIT 协议开源，由 Cai Xin Yun 开发。

PortProcess - 跨平台端口管理工具

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/PortProcess

PortProcess 是一款基于 Flutter 构建的跨平台端口管理工具，支持 macOS、Windows 和 Linux。

功能特性

实时进程监控 - 自动列出所有绑定端口的本地进程
智能搜索 - 按端口号、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 自动构建：

git tag v1.0.0
git push origin v1.0.0

项目采用 MIT 协议开源，由 Cai Xin Yun 开发。

SuperAsync - 通用异步任务调度平台

Wed, 13 May 2026 00:00:00 +0000

项目地址: https://github.com/caixy-plus/super-async

通用异步任务调度平台 —— 高吞吐、低延迟、可水平扩展的分布式任务调度与执行框架。

项目介绍

SuperAsync 是一个面向生产环境的通用异步任务调度平台，支持两种执行模式：

Server 本地模式：调度器与执行器同进程，适合单机高吞吐场景。
Worker 远程模式：调度器通过 HTTP 向独立 Worker 分发任务，支持水平扩展。

核心特性：

PostgreSQL + 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 迁移创建表结构。

4. 运行性能测试

cd super-async-benchmark
mvn spring-boot:run

测试完成后会在控制台输出 Markdown 格式的性能报告。

接入指南

Server 本地模式

在业务服务中引入 super-async-server，通过 @TaskHandler 注解注册本地执行器：

import com.superasync.annotation.TaskHandler;
import com.superasync.dto.TaskContext;
import com.superasync.dto.TaskResult;
import org.springframework.stereotype.Component;

@Component
public class OrderTaskHandler {

 @TaskHandler("ORDER_PAYMENT")
 public TaskResult handlePayment(TaskContext ctx) {
 String orderId = ctx.getPayload();
 // 执行业务逻辑
 return TaskResult.ok("paid");
 }
}

提交任务：

import 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("ORDER_PAYMENT")
 .taskKey("order_" + 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：

1. 配置 application.yml：

superasync:
 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 处理器：

import 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("ORDER_PAYMENT")
 public TaskResult handle(TaskContext ctx) {
 // 执行业务逻辑
 return TaskResult.ok("done");
 }
}

3. 提交时指定 workerTag：

TaskRequest request = TaskRequest.builder()
 .taskType("ORDER_PAYMENT")
 .taskKey("order_" + orderId)
 .payload(orderId)
 .workerTag("PAYMENT_WORKER") // 指定由该标签的 Worker 执行
 .build();
taskDispatcher.submit(request);

性能测试报告

测试环境：MacBook Pro (Apple Silicon, 8C), Java 21, PostgreSQL 16 (Docker)

测试结果

简单任务延迟测试 (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 开源。

注意：SuperAsync 目前处于积极开发阶段，API 可能在正式 1.0 发布前发生变动。生产环境使用前建议进行充分压测与容错验证。