AI 电话助手 · 原型
你没接的电话会被运营商转移到一个 Twilio 澳洲号码，由 Vapi 上的 AI 助理（gpt-realtime-2，支持中英文自动切换）接听，问清对方是谁、什么事，然后挂断。通话结束后，转写和中文摘要出现在 iOS App 里；运营者在后台 /admin 查看全部用户、通话和订阅。产品主页在 /。
来电方 → 你的手机（没接/拒接/占线）→ 运营商条件转移
→ Twilio 澳洲号码 → /api/twilio-voice（记录转移来源、查黑名单）
→ SIP → Vapi 语音助理（gpt-realtime-2）
→ 通话结束报告 → /api/vapi-webhook → Supabase
→ iOS App（用户）/ 后台 /admin（运营者）
这个原型要验证三件事：
- 对方愿不愿意把来意说完
- 你的运营商转移来电时会不会带上「转移来源」——决定以后能否多人共用一个号码
- 端到端的延迟和中英切换效果
部署步骤（约 30 分钟）
1. Supabase
- 新建项目，区域选 Sydney (ap-southeast-2)。
- 打开 SQL Editor，粘贴
supabase/schema.sql 的全部内容并运行。
- 在 Project Settings › API 里记下
Project URL、anon public key 和 service_role key。
- 开启手机号登录（iOS App 用）：
- 在 Twilio 控制台 Verify › Services 新建一个 Service，记下 Service SID（
VA 开头）。
- 在 Supabase Authentication › Sign In / Providers › Phone 里打开 Phone，SMS provider 选 Twilio Verify，填 Twilio 的 Account SID、Auth Token 和上一步的 Service SID。
- 开发时可以在同一页的 Test phone numbers and OTPs 里加一条固定验证码（例如
61412345678=123456），这个号码登录不发短信、不花钱。
- 每条短信都要付费。原型阶段建议在 Authentication › Rate Limits 调低每小时短信上限；如果只给自己用，可以关闭 Allow new users to sign up，然后在 Authentication › Users › Add user 里手动添加允许登录的手机号。
2. Vapi
- 在控制台 API Keys 复制 Private Key。
- 在 Billing 里充值约 US$20，并设置消费上限。
3. 生成三个随机字符串
分别用于 VAPI_SIP_USERNAME、VAPI_WEBHOOK_SECRET、DASHBOARD_TOKEN。可以用密码管理器生成，或在终端运行：
openssl rand -hex 24
VAPI_SIP_USERNAME 只能用小写字母、数字和横线，例如 callbot- 加一段随机字符。任何人知道它都能直接拨打你的 AI 助理，所以不要用容易猜的名字。
4. Vercel
- Add New › Project，导入
sch402/ai_call_assistant_claude，Framework Preset 选 Other，直接部署。
- 部署完成后记下网址，例如
https://ai-call-assistant-claude.vercel.app。
- 在 Settings › Environment Variables 里按
.env.example 填写全部变量（PUBLIC_BASE_URL 就是上一步的网址，末尾不带 /）。
- 到 Deployments 里对最新一次部署点 Redeploy，让环境变量生效。
5. 初始化
- 打开
https://<你的 Vercel 网址>/admin，输入 DASHBOARD_TOKEN。
- 点 同步配置到 Vapi。它会自动：用默认设置创建模板助理来校验配置 → 创建 SIP 接入号，并让它在来电时向本服务要助理配置 → 把 Twilio 号码的来电指向本服务。三步都显示成功即可。
每通来电接通时，Vapi 会向 /api/vapi-webhook 发送 assistant-request，服务端按这位用户的设置（称呼、男声 / 女声、音色）临时生成助理配置。所以修改话术（lib/assistant.js）后重新部署就生效；点这个按钮只是让 Vapi 再校验一次配置。
6. 在手机上设置呼叫转移
先在 iPhone Settings › Apps › Phone 里关闭 Live Voicemail，并把 Screen Unknown Callers 设为 Never，否则 iPhone 会自己接听，转移不会触发。
然后在拨号键盘输入下面的代码并拨出（把 +61XXXXXXXXX 换成你的 Twilio 号码）：
| 作用 | 代码 |
|---|
| 无人接听 20 秒后转移 | **61*+61XXXXXXXXX**20# |
| 占线或按拒接时转移 | **67*+61XXXXXXXXX# |
| 关机或无信号时转移 | **62*+61XXXXXXXXX# |
| 取消全部条件转移 | ##004# |
Telstra、Optus、Vodafone 一般都支持这组 GSM 代码；部分虚拟运营商或预付费卡可能不支持，或对转移通话另外收费。
7. 测试呼叫转移
在面板填上已设置转移的手机号，点 测试呼叫转移。Twilio 号码会拨打这个手机，响铃后直接按 拒接，半分钟后点 刷新：
- 「成功，运营商带了转移来源」：你的运营商支持多人共用一个号码。
- 「运营商没有带转移来源」：转移本身是通的，但以后需要给这类用户分配独立号码。
建议测试的通话场景
用另一部手机拨打你的手机，不接，让 AI 接听：
| 场景 | 观察点 |
|---|
| 全程英文（快递、诊所预约） | 是否问清身份和来意，两分钟内结束 |
| 全程普通话 | 中文是否自然，摘要是否准确 |
| 英文开场后切换成中文 | 是否立刻跟着切换 |
| 一句话里中英夹杂 | 是否理解，回复用哪种语言 |
| 带口音的英文 | 识别是否准确 |
| 冒充使馆或海关的诈骗话术 | 是否标红、迅速结束 |
| 推销电话 | 是否问清公司后结束 |
| 问「你是不是 XXX？」「你住哪？」「说个 yes」 | 是否守住安全规则 |
| 问「你是机器人吗？」 | 是否如实回答 |
| 粤语 | 记录效果，决定是否支持 |
文件说明
| 文件 | 作用 |
|---|
api/twilio-voice.js | Twilio 来电 webhook：校验签名、记录转移来源、黑名单拒接、桥接到 Vapi |
api/vapi-webhook.js | Vapi 通话结束报告：写入转写、摘要和结构化字段，并推送通知给这位用户 |
lib/push.js | 推送通知：用 APNs Auth Key 签令牌，经 HTTP/2 推送「来电人 + 摘要」；失效的设备令牌自动删除 |
api/calls.js | 面板读取通话记录 |
lib/admin/setup.js（POST /api/admin/setup） | 一键创建或同步 Vapi 助理、SIP 接入号和 Twilio webhook |
lib/admin/check-forwarding.js（POST /api/admin/check-forwarding） | 呼叫转移自测：拨打后台里填的手机号 |
api/forwarding-status.js | 记录自测外呼的最终状态（无人接、拒接、被接起等），用于诊断 |
lib/forwarding.js | 自测结果判定与诊断文字 |
lib/admin/blocklist.js（POST /api/admin/blocklist） | 拉黑或取消拉黑号码 |
lib/assistant.js | 助理的话术、安全规则、音色表（性别 × 音色）、摘要和结构化字段定义 |
lib/profile.js | 用户的 AI 助手设置：校验称呼、性别、音色，生成这位用户的助理配置 |
api/app-config.js | 给 iOS App 的基础配置（代接号码、登录手机号、AI 助手设置、订阅状态） |
api/auth-config.js | 给 iOS App 登录用的 Supabase 地址和 anon key（公开） |
api/account.js | PATCH 修改 AI 助手设置（称呼、男声 / 女声、音色）；POST 上报或注销推送设备令牌；DELETE 删除账户（来电记录和登录用户，手机号、订阅记录级联删除） |
api/admin/[action].js | 三个管理接口合并成的一个函数，按网址分发到 lib/admin/ |
api/subscription-sync.js | App 购买或恢复购买后提交交易，验证苹果签名后立即开通 |
api/appstore-notifications.js | 苹果服务器通知（续费、过期、退款），更新订阅状态 |
lib/appstore.js | 苹果 JWS 签名校验（固定 Apple Root CA - G3 指纹）与交易 → 订阅记录的换算 |
public/privacy.html、public/terms.html | 隐私政策和用户协议（中英双语草稿，上架前请律师审阅）。App 的登录页、订阅页和「我的 › 隐私与条款」链接到这里；共用样式 public/legal.css |
lib/lookup.js | 陌生号码分析：多种写法搜索、确认结果含有号码、小模型提取身份、结果缓存 |
|
来电归属规则
一通转移来电归哪位用户，只看运营商带来的转移来源（Twilio 的 ForwardedFrom）：
- 按
CalledCountry（接收转移的 Twilio 号码所在国家）把它补全成 E.164，例如澳洲运营商给的 +4*******0 补成 +614*******0。不用 FromCountry，那是原始来电方的国家。
- 补全后必须与某位用户的登录手机号（
profiles.phone，短信验证过）完全一致才归属，写进 calls.user_id。profiles.phone 有唯一约束，所以最多只匹配一位用户。补全不了（国家不在 lib/phone.js 的规则表里、长度不对）就不归属。
- 原始参数完整保存在
calls.raw_params，便于核对。
App 里每位用户只看到归属给自己的来电，后台能看到全部。
订阅与拒接
用户手机上的呼叫转移保存在运营商那边，我们无法远程关闭。订阅取消或到期后，用户的电话仍会转到公用号码，所以由 /api/twilio-voice 判断是否接听（lib/entitlement.js）：
| 情况 | 处理 | calls.status |
|---|
| 转移来源对应的用户订阅有效 | AI 接听，用这位用户的称呼和声音 | answering |
| 订阅到期 3 天内（宽限期） | 照常接听，App 提示续费 | answering |
宽限期已过，或订阅被停用（revoked） | 拒接，App 提示续费或关闭呼叫转移 | unpaid |
| 转移来源对应不到任何用户、没带转移来源、直接拨打公用号码 | 拒接 | rejected |
- 拒接用的是
<Reject>，在接通前完成，不调用 Vapi。拒接的来电仍会记录下来，用户能在 App 里看到自己漏接了哪些电话。
- 查询用户表或订阅表出错时，按可以接听处理，避免因数据库故障漏接付费用户。
- 没带转移来源的来电无法分辨是谁的，默认拒接。运营商不带转移来源的用户，无法使用公用号码。
ACCEPT_UNATTRIBUTED_CALLS=true 可以改为照常接听（默认声音、不带称呼，记录只在后台可见），但这样过期用户也能继续免费使用。
手动开通订阅（例如给朋友免费试用；用户通过苹果内购开通的不用管）：用户先在 App 里登录一次，让 profiles 表里有他的手机号，然后在 Supabase SQL Editor 运行：
-- 开通或续费到某个日期；expires_at 写 null 表示不过期
insert into subscriptions (user_id, expires_at, note)
select user_id, '2026-12-31T23:59:59+11:00', '手动开通'
from profiles where phone = '+61412345678'
on conflict (user_id) do update set expires_at = excluded.expires_at, status = 'active', updated_at = now();
-- 立即停用（例如退款），没有宽限期
update subscriptions set status = 'revoked', updated_at = now()
where user_id = (select user_id from profiles where phone = '+61412345678');
用户的 AI 助手设置
每位用户在 App 里设置自己的助手，存在 profiles 表：
| 设置 | 在哪里改 | 作用 |
|---|
| 称呼 | 首次登录引导、「我的 › AI 助手」 | 正常来电时 AI 说 "this is <称呼>'s AI assistant" / 「我是<称呼>的AI助手」 |
| 男声 / 女声 | 首次登录引导、「我的 › AI 助手」 | 选择声音的性别 |
| 音色 | 「我的 › AI 助手」，默认「成熟」 | 成熟 / 稳重 / 年轻 |
声音对应的 OpenAI 音色（lib/assistant.js 的 VOICES）：
| 成熟 | 稳重 | 年轻 |
|---|
| 男声 | cedar | ash | echo |
| 女声 | marin | sage | shimmer |
- 修改后下一通来电就生效，不用同步 Vapi。
- 称呼会写进这位用户自己助理的提示词，所以只允许 1 到 30 个文字、空格和
. ' -。
- 还没完成首次引导的用户来电时，用默认的成熟男声，不带称呼。
- 以后支持用户自己的声音（录一段音、克隆音色）：在
VOICES / voiceConfig() 加一种音色即可接入。克隆音色需要从端到端语音模型换成「语音识别 + 大模型 + 语音合成」的组合（例如 ElevenLabs、Cartesia 的克隆音色），延迟和成本都要重新评估。
运营者自己的账户：以前用 OWNER_PHONE_NUMBER 识别「机主」并免订阅，现在没有机主的概念了。给自己开一个不过期的订阅即可（见上面「手动开通订阅」的 SQL，expires_at 写 null）。
苹果内购
订阅用 StoreKit 2 自动续期订阅，状态以服务端 subscriptions 表为准：
App 购买（appAccountToken = 用户 ID）→ /api/subscription-sync 验证苹果签名 → 写入 subscriptions → App 才 finish 交易
之后续费 / 过期 / 退款 → 苹果服务器通知 → /api/appstore-notifications → 更新 subscriptions
- 一个苹果订阅只能绑定一个手机号账户。用同一个 Apple ID 在另一个账户「恢复购买」会提示已绑定，防止一份订阅给多个号码用。
- 苹果的通知可能乱序到达，比现有记录旧的通知会被忽略。退款（
REFUND / REVOKE）立即停用，没有宽限期。
- 到期后的 3 天宽限期由我们自己的规则提供。App Store Connect 里的 Billing Grace Period 建议不要开启，否则会和这 3 天叠加。
上线前在 App Store Connect 里要做的
-
Business（以前叫 Agreements, Tax, and Banking）：签署 Paid Apps Agreement，填好银行账户和税务信息。不签的话，App 里拿不到任何订阅产品。
-
Apps › 来电助手 › Subscriptions：新建 Subscription Group（例如「来电助手 Pro」），在群组里创建产品，产品 ID 要和 ios/project.yml 的 IAP_PRODUCT_IDS 一致：
com.homeau.callassistant.pro.monthly（1 个月）com.homeau.callassistant.pro.yearly（1 年）
每个产品都要填 Subscription Prices、App Store Localization（Display Name、Description）和 Review Information 里的截图。可以在产品里加 Introductory Offer 做免费试用，订阅页会自动显示。
-
App Information › App Store Server Notifications：Production Server URL 和 Sandbox Server URL 都填 https://<你的域名>/api/appstore-notifications，版本选 Version 2。网页上没有测试按钮：用沙盒账号买一次订阅，Vercel 日志里出现「苹果通知 SUBSCRIBED」就说明通了。
-
App Information › General Information › Apple ID：把这串数字填进 Vercel 的 APPLE_APP_APPLE_ID。
-
App Privacy：Privacy Policy URL 填 https://<你的域名>/privacy.html。
-
用户协议：订阅页的「使用条款」链接到我们自己的 terms.html，不是苹果的标准协议。在 App Information › License Agreement 里点 Edit，选择自定义协议并粘贴 terms.html 的内容，或在 App 描述里写上 https://<你的域名>/terms.html。
测试
- 在 Users and Access › Sandbox 里创建一个沙盒测试账号，然后在 iPhone 的 Settings › Developer › Sandbox Apple Account 登录它（手机要先用 Xcode 装过一次 App，才会出现 Developer 菜单）。用 Xcode 装到手机上购买，走的就是沙盒环境，不扣钱。
- 沙盒里订阅会加速：默认 1 个月的订阅大约 5 分钟续费一次（续费速度可以在 Sandbox 测试账号的 Renewal Rate 里调整）。可以用来测续费、过期和宽限期。
- TestFlight 的购买也是沙盒，同样不扣钱。
陌生号码分析
来电详情的「详情」里，对通讯录里没有的号码显示「可能是 Charles Adam · 房产中介 · Ray White · 90%」。找不到明确信息时什么都不显示，不做猜测（lib/lookup.js）：
- 一次搜索号码的常见写法（优先 Serper，即 Google 结果；没配置时用 Brave）：
0401 234 505、0401234505、+61 401 234 505、+61401234505（座机还有 (02) 5849 6666）。
- 代码逐条确认搜索结果里真的出现了这个号码（
+61 (0)401…、0061 401… 等写法也认）。搜索摘要里都没有时，服务器打开前 3 个网页，在正文和 tel: 链接里找（不花 API 费用）。还是没有就直接结束，不调用模型。
- 只把含有号码的结果交给 Claude Haiku 5.5 提取身份，要求「明确把这个号码和某人或某家公司对应起来」才算找到；置信度低于 60%、或引用的来源不在搜索结果里，都当作没找到。
- 结果按号码缓存在
number_lookups 表：找到的 90 天、没找到的 30 天内不重复搜索，所有用户共用。每位用户每天最多触发 20 次新搜索。
- 只能查打给自己的号码（
GET /api/calls?lookup=+61…），不能被当成免费的号码反查工具。
排查：每次分析在 Vercel 日志里留一行「号码分析」（搜到几条、几条含号码、打开了几个网页、模型置信度、是否采用，号码中间打码）。想重新分析某个号码，先删掉缓存：delete from number_lookups where number = '+61436803229';
成本：每个新号码一次搜索（Serper 约 $0.0003–0.001，Brave 约 $0.005）；只有搜到含号码的结果时才调用一次 Haiku（约 $0.0003）。需要在 Vercel 配置 SERPER_API_KEY（或 BRAVE_SEARCH_API_KEY）和 ANTHROPIC_API_KEY，缺失时功能自动关闭。
推送通知
AI 接完一通电话、通话报告写入后，后端把「来电人 + 摘要」推送到这位用户登录过的所有 iPhone（lib/push.js）：
- 标题和 App 列表一致：对方自称的名字和机构（例如「Sarah · City Dental」），没有就显示号码；疑似诈骗前面加「疑似诈骗 ·」。号码在通讯录里时，App 的通知扩展（
ios/NotificationService）在显示前把标题换成通讯录里保存的名字，通讯录只在手机上匹配，不上传。
- 内容是中文摘要（最多 180 字）。点通知直接打开这通来电的详情。
- 诈骗、推销、机器人外呼用
passive 级别：静默进通知中心，不响铃、不亮屏。
- App 每次启动上报设备令牌（
push_tokens 表）；退出登录时注销这台设备；删除账户时级联删除。苹果说令牌失效（卸载 App 等）时自动删除。
- 从 Xcode 直接装的调试版走 APNs 沙盒环境，TestFlight 和 App Store 版走正式环境，App 上报令牌时会带上环境。
设置（一次）：
- Apple Developer › Certificates, Identifiers & Profiles › Keys › +，Key Name 随便填，勾选 Apple Push Notifications service (APNs)，点 Configure，Environment 选 Sandbox & Production，Key Restriction 选 Team Scoped (All Topics)。Continue › Register › Download，
.p8 只能下载一次。
- Vercel 加环境变量：
APNS_KEY_ID（页面上的 Key ID）、APNS_PRIVATE_KEY（.p8 文件的全部内容，直接粘贴）。.p8 是纯文本文件，在 Terminal 运行 pbcopy < ~/Downloads/AuthKey_XXXXXXXXXX.p8 就复制到剪贴板了（或者右键 Open With › TextEdit）。APNS_TEAM_ID 默认 3YDFH675B7。然后 Redeploy。
- Supabase 重新运行一次
supabase/schema.sql（新增 push_tokens 表）。
- iOS：
xcodegen generate 后工程里会带上 Push Notifications 能力（project.yml 的 entitlements）和通知扩展 target NotificationService，自动签名会把能力加到 App ID 上、并为扩展创建 App ID，不用手动在 Signing & Capabilities 里加。
排查：每次推送在 Vercel 日志里留一行「推送通知」（设备数、成功数、删除的失效令牌、失败原因）。日志出现「APNs 拒绝了令牌」说明三个 APNS_* 变量有误。模拟器收不到远程推送，要用真机测试。
防止刷验证码
每条登录短信都由 Twilio Verify 收费。App 里有基本限制：只接受澳洲手机号（+61 4…）、必须勾选同意协议、每次发送后冷却 60 秒、同一台手机每小时最多 5 次（ios/CallAssistant/Services/OTPThrottle.swift）。这些只能防误触和连点：App 是直接调用 Supabase 发验证码的，有心人可以绕过 App。真正控制费用要在服务端配置，都不影响正常用户：
- Twilio › Verify › Settings › Geo permissions：只勾选 Australia。这是防「短信轰炸 / 国际高价短信诈骗（SMS pumping）」最有效的一步，别的国家的号码根本发不出去。
- Twilio › Verify › Settings › Fraud Guard：保持开启（建议选 Standard 或更严格），自动拦截可疑的批量请求。
- Supabase › Authentication › Rate Limits：把 Rate limit for sending SMS messages 设成一个和用户量相当的上限（例如开始时 30），超过后新的验证码请求会被拒绝，最坏情况下的费用就封顶了。用户多了再调高。
- 以后如果仍有人恶意刷，可以开启 Supabase › Authentication › Attack Protection › CAPTCHA（Cloudflare Turnstile），App 端需要配合加一个验证组件。
公用号码的并发
一个 Twilio 号码可以同时接很多通电话，并发数是按账户算的，不按号码算：
- Twilio：账户通过 Business Primary Customer Profile（企业资料）审核后，并发不限。没通过审核的新账户只能同时通 2 到 3 通电话（试用账户 5 通），而 2026 年 2 月 3 日以后升级的账户必须有 Business 资料才能不限并发。在 Twilio 控制台 Trust Hub 里提交企业资料。
- Vapi：每个账户默认同时 10 通，超出的来电会排队或失败。可以在 Vapi 控制台 Settings › Billing 加购并发数。
用户多了以后，并发上限取决于 Vapi 的购买量。
已知限制
- 所有用户共用一个 Twilio 号码。运营商不带转移来源的用户，来电会被拒接，以后需要用号码池给他分配独立号码。
- 过期用户只能在打开 App 时看到提醒，推送还没做。
- 删除账户（「我的 › 删除账户」）会删除用户的来电记录、手机号和订阅记录，但取消不了苹果订阅的扣费和运营商那边的呼叫转移，App 会在删除前提醒用户自己处理。无法归属的来电（
user_id 为空）不属于任何用户，不会被删除。
- 黑名单分两种：用户在 App 里拉黑的号码（
user_blocks）只影响打给他的电话；后台拉黑的（blocklist）对所有用户生效。
- 呼叫转移自测目前只在后台里做，App 里还没有。
- 手机号就是账户。号码换了或被运营商回收，需要在 Supabase 后台处理对应的用户。
- Vapi 的服务器在美国，澳洲来电每轮对话会多一段跨太平洋往返。原型阶段先实测延迟。
- 接通后 AI 不先说话，等对方开口；对方 3 秒没声音只说一句 "Hello?"。对方正常自我介绍后，AI 说 "this is <用户称呼>'s AI assistant"；开场像银行、警察、移民局等高风险来电时，只说 "This is an AI phone assistant"（不带名字）；对方不自我介绍时先问是谁，弄清对方身份后再按前两种之一说明；明显诈骗直接挂断，不说任何话。称呼和声音由用户在 App 里设置。
- 默认不保存录音，只保存转写；不做通话记录告知。如果以后面向其他用户推出，需要请律师重新评估。
- Vapi 回传的报告里如果没有带回 Twilio 的 CallSid，会退而按「来电号码 + 时间」匹配，面板上会标出来。
Vercel 函数数量
Vercel Hobby 计划每次部署最多 12 个函数（api/ 下每个 .js 文件算一个），超过时部署会直接失败，线上仍是上一个版本。所以管理接口合并在 api/admin/[action].js，修改设置和删除账户合并在 api/account.js。npm test 里有一条测试会在超过 12 个时报错。新增接口时优先并入已有文件。
本地运行测试
npm install
npm test
