VibeSMS

把 Android 手机变成 Agent 可调用的短信与来电终端。用户使用一个 Key 接入自己的 SIM，设备将事件可靠上传到 sms.shareapi.ai，Agent 再基于同一 Key 隔离读取。

仓库与许可边界

本仓库采用分目录授权，不是一个整体开源项目：

Android Terminal：Apache-2.0 开源，见 android/LICENSE。
VibeSMS Agent Skill：Apache-2.0 开源，见 skills/vibesms/LICENSE。
服务端、Web 控制台、部署与运维代码（包括 server/、deploy/、bin/、根目录 Docker 配置）：保留商业许可，未经单独书面授权不得复制、修改、分发或提供托管服务，见 LICENSE。

客户端和 Skill 可以独立使用、修改和分发；若要部署或改造 VibeSMS 服务端，请联系维护者获取商业授权。完整目录边界见 docs/REPOSITORY_LICENSING.md。

当前版本已提供无账户 Key 接入、后台额度控制的前台自动签发、人工申请与一次性激活码兜底、用户 Key 收件箱、关键词过滤的飞书机器人 Webhook 转发、按号码与 SIM 隔离的 Agent Inbox/OTP API、VibeSMS Skill，以及带离线队列和主动心跳的专用 Android Terminal。产品定义见 docs/VIBESMS_PRODUCT.md。

Public Beta：仅限接入你自己拥有或获授权管理的 Android 手机与 SIM；VibeSMS 不提供共享号码池，也不面向批量注册、转售或绕过第三方平台规则。请在申请前阅读数据与隐私说明。

当前范围

Android 端：VibeSMS Terminal 采集入站短信和来电事件，支持双卡、持久化离线队列、自动补发、主动心跳和经授权 ADB 的自动安装绑定。
服务端：Python 标准库 + SQLite，无第三方运行依赖。
能力：自动签发额度开关、每设备限领、站内 Key 申请、一次性激活码兑换、用户 Key 签发/轮换/禁用、Key 登录收件箱、飞书 Webhook 与关键词过滤、持久化投递重试、Android 首次绑定、设备独立上传密钥、Agent 隔离查询、OTP 长轮询、事件去重、主动心跳和响应式管理页面。
暂不包含：主动发短信、远程接听、MDM、集群调度和高可用。

Android APK

VibeSMS Android Terminal v0.4.9 使用正式发布密钥签名，并通过 GitHub Releases 分发：

可以在 APK 内手工输入 Key、选择 SIM 并连接；也可以安装 VibeSMS Skill，把 Key 保存为本机 VIBESMS_KEY Secret，再让 Agent 对已解锁且获得 ADB 授权的 USB 手机执行自动安装、权限配置、SIM 绑定和在线验证。Android 端使用 Android Keystore 加密保存已绑定的 Key 和设备上传凭据，便于显示 Key 并直接打开 Web 收件箱。

源码：github.com/guanxiong/VibeSMS
云端入口：sms.shareapi.ai
数据与隐私说明：sms.shareapi.ai/privacy
Key 收件箱：sms.shareapi.ai/inbox
申请测试 Key：sms.shareapi.ai/apply
兑换激活码：sms.shareapi.ai/activate

本地启动

mkdir -p config data
cp .env.example config/local.env
# 修改 config/local.env 中的 GATEWAY_TOKEN，并把 DB 路径改成 data/gateway.db
./bin/run-server

打开 http://127.0.0.1:8787 查看公开项目主页；用户使用 Key 登录 http://127.0.0.1:8787/inbox/ 查看自己号码的短信与来电；管理控制台位于 http://127.0.0.1:8787/admin/，使用 config/local.env 中的管理员账号登录。服务健康检查：

curl http://127.0.0.1:8787/api/health

已通过 USB 连接手机时，再执行：

./bin/connect-usb-device

手机端详细配置见 docs/SMSFORWARDER_SETUP.md。当前真机验收状态见 docs/REAL_DEVICE_ACCEPTANCE.md。生产 HTTPS 部署与新增设备见 docs/PRODUCTION_DEPLOYMENT.md。

Docker 部署

cp .env.example .env
# 设置强随机 GATEWAY_TOKEN
docker compose up -d --build

Compose 会使用 Caddy 自动提供 HTTPS，并且不直接暴露应用的 8787 端口。管理页面会弹出 Basic Auth 登录框。

仓库结构

server/              HTTP API、SQLite 存储与 Web 资源
  static/site/       公开项目主页
  static/admin/      需认证的管理控制台
deploy/              HTTPS、反向代理、备份与 DNS 运维配置
android/             VibeSMS Terminal 原生 Android 工程
bin/                 本地启动、设备接入和凭据签发脚本
docs/                产品、部署、Android 配置与验收文档
tests/               服务端与访问边界自动化测试
skills/vibesms/      可安装的 VibeSMS Agent Skill 与零依赖客户端

运行时的 config/local.env、data/ 与测试 APK 均被 Git 忽略，不进入公开仓库。

API

POST /api/v1/events：Android 事件入口，需要 X-Gateway-Token。
POST /api/v1/devices/heartbeat：设备心跳入口，需要 X-Gateway-Token。
GET /api/v1/events：事件列表，可使用 type、device_id、limit 过滤，需要管理员认证。
GET /api/v1/devices：设备在线状态，需要管理员认证。
GET/POST /api/v1/admin/devices：查看设备凭据元数据或生成独立 Token，需要管理员认证。
GET/POST /api/v1/admin/keys：列出或签发用户 Key，需要管理员认证。
POST /api/v1/admin/keys/{key_id}/{rotate|disable|unbind}：管理用户 Key，需要管理员认证。
POST /api/v1/key-requests：提交邮箱、本人手机号和用途；有自动名额时立即返回只显示一次的 Key，否则进入人工队列。
GET /api/v1/onboarding/status：返回自动签发剩余额度和当前匿名设备是否已领取。
GET/POST /api/v1/admin/onboarding-settings：管理员启停自动签发并设置剩余名额。
GET/POST /api/v1/admin/campaigns：管理员创建、列出、启停推广活动，并由活动代码生成公开申请链接。
GET /api/v1/admin/acquisition-funnel：按推广活动汇总申请、Key 签发、绑定、24 小时首次心跳和首个事件；仅管理员可读，不返回短信内容或个人标识。
POST /api/v1/activations/redeem：用一次性激活码和手机号兑换用户 Key，无需认证，Key 明文仅返回一次。
GET/POST /api/v1/admin/{key-requests|activation-codes}：查看申请、签发激活码；POST /api/v1/admin/activation-codes/{id}/disable 作废未使用激活码，均需要管理员认证。
POST /api/v1/bindings：用户 Key 首次绑定设备与 SIM，返回仅显示一次的设备 Token。
GET /api/v1/status：查询当前 Key 的终端状态与事件游标。
GET /api/v1/inbox：按当前 Key 隔离读取短信与来电。
GET /api/v1/otp/wait：等待当前 Key 对应号码的新验证码，最长 60 秒。
GET/POST /api/v1/webhooks/feishu：使用当前用户 Key 查看或保存飞书机器人地址、关键词与启用状态；查询不返回完整 Webhook 地址。
POST /api/v1/webhooks/feishu/test：向已配置的飞书机器人发送不含真实短信的测试消息。
POST /api/v1/webhooks/feishu/delete：删除当前 Key 的飞书配置和投递记录。
GET /api/health：健康检查和统计。

Agent Skill

使用开放 Agent Skills CLI 一键安装到 Codex、Claude Code、Cursor、GitHub Copilot、OpenCode 等客户端：

npx skills add guanxiong/VibeSMS --skill vibesms -g -y

也可以通过 GitHub CLI 的原生 Agent Skill 支持安装：

gh skill install guanxiong/VibeSMS

Skill 源码位于 skills/vibesms。安装后把用户 Key 保存为 VIBESMS_KEY Secret，再让 Agent 自动配置 USB 手机、检查终端、读取短信/来电或等待验证码：

export VIBESMS_KEY='vbs_live_...'
python3 skills/vibesms/scripts/vibesms.py status
python3 skills/vibesms/scripts/vibesms.py wait-otp --after-id 0 --timeout 60
python3 skills/vibesms/scripts/setup_android.py --sim-slot 1

生产使用时先通过 status 捕获游标，再触发外部短信，最后用该游标等待验证码，避免误读旧消息。不要把 Key 写入提示词、代码或 Git。

测试

python3 -m unittest -v

License

本仓库采用分目录授权：Android Terminal 与 VibeSMS Agent Skill 为 Apache-2.0；服务端及其部署、运维代码为商业/专有许可。详见 LICENSE 与目录授权说明。

VibeSMS

At a glance

README

VibeSMS

仓库与许可边界

当前范围

Android APK

本地启动

Docker 部署

仓库结构

API

Agent Skill

测试

License

Comments (0)