侧栏电话 lucagiftzek/dsh-phone

dsh-phone

在 DSH 侧边栏里收发短信、拨打电话、查看实时语音信箱、使用 Telegram，通话音频走你自己的服务器。

从 npm 安装：dsh plugin --profile web add @lucagiftzek/dsh-phone，或从 GitHub 安装：dsh plugin --profile web add github:lucagiftzek/dsh-phone。

dsh plugin --profile web add dsh-better-sidebar # the tab host, skip if installed
dsh plugin --profile web add @lucagiftzek/dsh-phone
or from GitHub: dsh plugin --profile web add github:lucagiftzek/dsh-phone
restart dsh web, then run phone-hookd and connect your provider (see Install)

The Phone tab with an SMS thread

截图来自带示例数据的演示 DSH 实例。

DeepSeek Harness Web 图形界面里的一部电话。它给侧边栏（dsh-better-sidebar）加一个 Phone 标签页，你可以在里面：

- 发短信：短信会话，收发消息，投递状态，MMS 图片，分段计数（GSM-7 / Unicode）。
- 打电话：在浏览器里拨出和接听，静音，键盘（DTMF），通话记录。通话音频默认走你的服务器（「Via server」：一条加密 wss 连接直连 DSH 源站，所以在屏蔽 WebRTC 的网络上也能用，浏览器不跟任何第三方通信）；Direct（通过 Twilio Voice SDK 用 WebRTC 直连 Twilio）一键即可切换。Test audio 按钮可以在不拨号的情况下检测网络。
- 用一个开关选择来电怎么找到你：
- Live：来电响这个浏览器（也可以再响一部手机，手机必须按 1，免得它自己的语音信箱把电话抢走）。未接来电转入语音信箱。
- Voicemail：所有来电都进语音信箱。对方说话时你能看到实时转写，还能Pick up（热接听），就像 iOS 的 Live Voicemail。
- Do not disturb：来电进语音信箱，不响铃、不提示、不通知。星标联系人仍然可以响铃。可选自动回复短信。
- 语音信箱：问候语（口述或音频文件），录音存在你的服务器上，最终转写由本地 Whisper 端点完成（希腊语效果好，免费）或用 Mistral Voxtral，录音随后从服务商删除。
- 联系人：姓名、星标（可突破 DND）、拉黑（直接拒接）。
- 智能体工具，让模型能操作电话：phone_status、phone_set_mode、phone_sms_threads、phone_sms_thread、phone_sms_send、phone_calls、phone_voicemails、phone_contacts、phone_call_say，以及只读的 phone_doctor。发送短信或发起语音提醒通话，总是先返回草稿，需要 confirm: true 才执行。
- 全部配置都在 DSH 设置 > 电话里完成（或标签页里的齿轮图标）：线路、凭据、webhook、语音信箱、通知、智能体权限。应用到 Twilio 会创建 API key 和 TwiML App，把每个号码的语音与短信 webhook 指向你的服务器，然后用一份状态清单逐项做端到端验证。

dsh-phone 在设计上不绑定服务商。Twilio 是第一个适配器（已完成，在真实线路上测过）。接下来：任何 SIP 账号或中继，通过你服务器上的中继接入（比如本地 VoIP 服务商提供的现有固话），然后是兼容 Twilio 的 SignalWire，再往后是 Telnyx、Vonage、Plivo 和短信网关。SIP 账号（现有固话）可以通过 Asterisk 中继以桥接模式接入：docs/RELAY.md。所有选项、每项设置背后的标准（SIP、WebRTC、SRTP、编解码器、DTMF、E.164、短信编码）以及该选哪种方案，见 docs/PROVIDERS.md。

各部分如何协作

Browser (DSH web UI) Your server Twilio
─────────────────── ─────────── ──────
Phone tab + call overlay ──/dsh-phone/api──▶ dsh-web: dsh-phone plugin ──unix socket──▶ phone-hookd ◀──signed webhooks── voice + SMS
(behind your login) (gated) settings, tools, gates (0600) SQLite, TwiML, ──REST──────────▶ calls, SMS,
Twilio Voice SDK ◀════════════════════════ WebRTC media ═══════════════════════════════════ recordings, recordings
local Whisper

- phone-hookd（daemon/hookd.mjs）是一个小型 Node 服务，掌管数据库，与服务商通信。它有两个监听器：
- 一个公开监听器（127.0.0.1:3098，只以 https://<host>/phone-hook/ 暴露），接收服务商 webhook。每个请求都必须带有效的 X-Twilio-Signature，否则返回 403。
- 一个私有 unix socket（~/.dsh/phone/hookd.sock，权限 0600），只给插件用。
它故意跑在 web UI 之外：UI 重启时，来电仍能进语音信箱，短信仍能收到。
- 插件（lib/index.js）跑在 dsh-web 里。它注册设置、智能体工具和 /dsh-phone/api/，每个请求先过与 dsh-mail / dsh-hpc 相同的四道关卡（loopback 对端、同源信任围栏、短期能力 token、harness 会话 cookie），再转发到 socket。它还在本地提供 Voice SDK（不走 CDN）。
- 浏览器端（src/client.jsx，构建到 lib/client.js）每个页面启动一个电话服务：实时事件（SSE）、Twilio Device、WebAudio 铃声、浏览器通知，以及来电、通话中、实时语音信箱和 toast 的浮层，无论打开哪个标签页都可见。

安装

前置要求：DSH web 加 dsh-better-sidebar、Node 22.5+（用于 node:sqlite）、一个 Twilio 账号（带语音 + SMS 号码），以及一个公网 HTTPS 主机名，反向代理能把它路由到回环端口。

git clone https://github.com/lucagiftzek/dsh-phone && cd dsh-phone
npm install && npm run build && npm test

1. the daemon (edit YOUR_USER, the node path and the repo path first)
sudo install -m 644 deploy/dsh-phone-hookd.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now dsh-phone-hookd

2. the public webhook route: send ONLY /phone-hook/ to 127.0.0.1:3098, without your login
middleware (see deploy/traefik-phone-hook.yml for a Traefik example)

3. the plugin, in your DSH web profile: link the checkout (the daemon runs from it too)
dsh plugin --profile web add link:$PWD # then restart dsh web

只装插件（守护进程跑在别处时，用来提供 Phone 标签页和智能体工具）：从 npm 装 dsh plugin --profile web add @lucagiftzek/dsh-phone，或从 GitHub 装 dsh plugin --profile web add github:lucagiftzek/dsh-phone。包内声明了 dsh.bundle，所以 dsh plugin add 会把它列进配置档的 bundles。

然后打开 Settings > Phone：把账号 SID 和 auth token 填进输入框，或写进 KEY=value 格式的凭据文件（TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN；默认 ~/.config/twilio/credentials），把你的号码加为一条线路（或从「Numbers on the Twilio account」里选），填好公网 webhook 基础 URL，点 Save，再点 Apply to Twilio。检查清单应该全部变绿，浏览器完成注册，来电就能响铃。

通话音频：Via server（默认）或 Direct

选 Via server 时，浏览器采集麦克风（回声消除、噪声抑制、自动增益全开），在 AudioWorklet 里编码成 G.711 mu-law，再通过一条 wss socket 把 20 ms 的音频块发到 DSH 源站（/dsh-phone/api/io，默认每条消息 40 ms，双向各约 70 kbit/s）；远端音频经过一个小型自适应抖动缓冲播放。不加载 Twilio SDK、CDN、STUN 或 TURN。phone-hookd 把这条 socket 桥接到通话上：

- SIP 线路（Asterisk 中继）：hookd 通过 AMI 发起一个 AudioSocket 通道，进入生成的 context，由它套用该线路的目标策略并拨号到服务商。Asterisk 与 hookd 之间的音频始终走 127.0.0.1。不涉及 Twilio。
- Twilio 线路，以及你在这里接听的每一通来电：建立一条双向 Twilio Media Stream（<Connect><Stream>，mu-law 8 kHz）到 wss://<host>/phone-hook/s，只接受带有效 X-Twilio-Signature（针对 wss URL 校验）且带一次性 ticket（绑定到 CallSid）的请求。来电通过事件流让 Phone 标签页响铃，同时主叫方听到服务器播放的回铃音；未接或拒接的来电照旧转到语音信箱，对进行中的语音信箱点 Pick up 也一样能用。
- 每次通话的音频统计（路由、双向数据包与字节数、抖动、首帧音频时间、结束原因）都会随通话记录行一起存下来，所以遇到无声通话可以直接从服务端排查。除了你本来就有的语音留言，不会多记录任何东西。
- 限制：同时最多 audio.maxCalls（默认 2）路通话、audio.maxTests（2）个测试；浏览器 socket 断开后，通话会保留 15 s，等标签页重连。

在 Phone 标签页里按浏览器选择路由（Keypad、「Call audio」），或用 audio.route 设置默认值。

设置（命名空间 dsh-phone）

| 键 | 默认值 | 含义 |
| publicBaseUrl | 空（必填） | Twilio 调用的地址，例如 https://your-host/phone-hook。必须能访问到 phone-hookd 的公开监听端口。 |
| trustedHosts | [] | 浏览器访问 UI 时使用的公开主机名（回环地址始终受信任）。 |
| identity | owner | 发起振铃的浏览器客户端身份。 |
| defaultCountry | 空 | 为没写国家码的号码补前缀（+30）。 |
| lines[] | [] | { id, label, provider: twilio, number, numberSid, sms, voice, enabled } |
| twilio. | 空 | accountSid、authToken、apiKeySid、apiKeySecret、twimlAppSid、edge、credentialsFile。留空的字段会回退到凭据文件，再回退到 Apply 创建的内容（~/.dsh/phone/provisioned.json，0600）。 |
| incoming. | 实时，25 s | defaultMode、ringSeconds、forwardTo、dndBypassStarred、rejectAnonymous |
| voicemail. | 开 | 问候语文本 / 语音 / 语言 / 音频 URL、maxSeconds、liveTranscript（+ liveLanguage、liveEngine、liveModel）、transcriber（local、mistral、off）、localUrl + localCredentialsFile（KEY=value，含 TTS_BASE_URL、TTS_API_KEY）用于本地 Whisper 端点、deleteFromProvider |
| sms.dndAutoReply | 空 | DND 开启期间，对每个发送方每 12 h 发送一次。 |
| notifications. | 全开 | sound、browser、toasts |
| agent. | 全开 | allowSms、allowCalls、allowModeChange |
| audio. | 服务端 | route（server 或 direct）、maxCalls（2）、maxTests（2）、packetMs（20、40、60）、jitterMinMs / jitterMaxMs（40 / 400）、testSeconds（30）、audioSocketPort（9093，回环）、ringbackTone（eu、us、uk，空 = 由线路号码决定） |

来电模式本身是运行时状态（标签页里的开关，或 phone_set_mode），所以切换它永远不会改写你的设置文件。incoming.defaultMode 只对全新数据库生效。

费用（Twilio，2026 年末）

服务器线路上的通话走 Twilio 线路时，按普通 PSTN 通话加 Media Streams 计费（每分钟 0.0044 USD）；服务器线路上的 SIP 线路通话完全不经过 Twilio。浏览器直拨按 Twilio Client 分钟数加 PSTN 段计费；SMS 按段计费（希腊语小写属于 Unicode：每段 70 个字符）；实时语音留言转写使用 Twilio 实时转写（约每分钟 0.027 USD，仅限语音留言）；最终转写在本地完成，免费；录音下载后会从 Twilio 删除，因此没有存储费用。

说明

- 加拿大长号不属于 US A2P 10DLC；发往美国手机的短信仍可能被过滤。发往希腊和欧盟的短信可用，但每段费用更高。
- 希腊语实时转写：把 voicemail.liveLanguage 设为 el-GR，把 voicemail.liveModel 设为 chirp_2。最终转写（本地 Whisper）会自动识别语言。
- 首次通话会请求麦克风权限。后台通知请在状态清单里点 Allow。

Telegram

服务器上的 Telegram 账号，在 Phone 标签页里有独立分区：聊天、群组和频道、照片、语音消息（由语音留言引擎转写）和文件、频道帖子、服务器音频线路上的 1:1 语音通话，以及 telegram_ 智能体工具，浏览器只与 DSH 源通信。Go 守护进程（telegramd/，通过 gotd/td 走 MTProto）在私有 unix socket 后面持有该账号。

简要安装步骤（详见 docs/TELEGRAM.md）：

1. 在 Telegram 应用里先开启两步验证（云密码和恢复邮箱），再做其他事。
2. 在 https://my.telegram.org（API development tools）创建你自己的 API 凭据，写入 ~/.dsh/phone/telegram/api.env（0600），内容为 TELEGRAM_API_ID=... 和 TELEGRAM_API_HASH=...，或在 Settings 里填写。绝不要使用示例或公开的 api_id。
3. 构建并启动 telegramd（deploy/dsh-telegramd.service 是示例 unit），然后在 Settings、Phone、Telegram 里登录：二维码（Telegram 应用，Settings，Devices，Link Desktop Device）或登录码，再输入云密码。

条款提醒：Telegram 会监视通过第三方 API 客户端登录的账号，刷屏或发垃圾信息会导致账号被封。因此智能体工具只写入已有会话或白名单聊天，并带速率限制、审计日志和紧急开关；启用智能体发送前，请阅读 docs/TELEGRAM.md 里的「Rules for automated use」。在你自己的账号上使用，风险自负。

语音通话使用 ntgcalls（libntgcalls，LGPL-3.0）。它不在本仓库内：telegramd/scripts/fetch-ntgcalls.sh 会下载固定版本（v3.0.5）并校验其 sha256，go build -tags ntgcalls（cgo）会动态链接它，因此你可以用自己的构建替换该库。不加构建标签时，telegramd 以纯 Go 构建，通话会报告引擎缺失；聊天、媒体和转写两种方式都能用。

安全

见 docs/SECURITY.md。简单说：唯一免认证的路径是做过签名校验的 webhook 前缀，由加固过的守护进程提供，这个进程永远不碰 Web UI；任何读接口都不会返回密钥；智能体发消息和打电话默认关闭，且先出草稿。

开发

npm test # signature (Twilio's published vector), JWT, TwiML, E.164, segments, settings, store
npm run build # src/client.jsx -> lib/client.js (verified before it replaces the live file)

出问题时

- 让你的智能体加载 phone-doctor 技能（随插件放在 skills/phone-doctor/）。插件启动时会把它注册到技能服务，所以 dsh web 重启后就能看到。如果你的 DSH 没列出它，手动复制一次：P=$(node -p "require('path').dirname(require.resolve('dsh-phone/package.json',{paths:[(process.env.DSH_HOME||require('os').homedir()+'/.dsh')+'/profiles/web']}))"); mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills" && cp -r "$P/skills/phone-doctor" "${DSH_HOME:-$HOME/.dsh}/skills/"（见 docs/TROUBLESHOOTING.md）。
- 一次调用完成自检：GET /dsh-phone/api/doctor（访问规则和其他读路由一样），或用只读的智能体工具 phone_doctor。它会报告配置模式、线路、服务商凭据（已设置还是缺失，绝不返回具体值）、公开 webhook URL（是否已设置）、钩子守护进程是否在其私有 socket 上应答、SIP 账号注册情况，以及媒体服务器配置。它从不调用服务商，从不拨打电话或发送短信；检查失败时会带上 PHONE_ 错误码和提示。故障排查指南第 0 节里的只读命令可以手动得到同样的信息。
- 每个错误都带稳定的 code，守护进程日志行也以它开头：docs/ERRORS.md。

MIT 协议。Twilio Voice SDK 是 Apache-2.0，从 node_modules 提供，不入库。libntgcalls（可选，用于 Telegram 通话）是 LGPL-3.0，由脚本拉取并动态链接，不入库。

同一作者的其他插件

全部开源，运行在 DeepSeek Harness 0.2.x 上（其中几个也支持 0.1.5）。

| 插件 | 作用 |
| dsh-artifacts | 一个 Artifacts 标签页，列出智能体产出的文件并就地预览，另带模板库，智能体可以用也可以扩展 |
| dsh-mail | 邮件客户端和智能体邮件工具：IMAP、POP3、SMTP 和 OAuth2 账号，定时发送和批量发送，并处理退订 |
| dsh-note-keeper | 侧边栏里的 Obsidian 兼容 Markdown 笔记，支持搜索、图谱、语音笔记与转写、OCR 和客户端加密 |
| dsh-phone（就是本仓库） | 短信与通话（Twilio、经 Asterisk 的 SIP），通话音频走你自己的服务器，支持实时语音信箱和 Telegram |
| dsh-voice | 朗读、听写和语言感知语音，接入 23 个 TTS 与 STT 服务商，支持按语言路由和逐词高亮 |
| dsh-orchestrator | 智能体集群与任务编排：一个 Orchestrate 标签页、orch_ 工具、runner、服务商卡片和机器 API |
| dsh-workspace-rail | 工作区优先的侧边栏：置顶会话、以文件夹呈现的项目、实时 Recents、搜索和未读标记 |
| DSH-Idle-Watchdog | 空闲会话提醒，外加一个带鉴权的 HTTP API，可向任意会话投递提示词 |
| dsh-plugin-updates | 更新检查器，只推荐你当前运行的 DSH 核心能加载的版本 |
| dsh-subagent-tiering | 子代理默认使用父模型的更便宜同级模型，除非智能体指定了路由 |
| dsh-fs-reobserve | 智能体自己跑完 shell 命令后，不再出现自己造成的文件过期错误 |
| dsh-request-image-cap | 把发给模型的每张图片压到像素上限内，修复多图请求报错 |
| dsh-seal | DSH 前面的加密通道：一个 Go 反向代理加一个 service worker，封住 DSH 的全部浏览器流量 |

作者 Luca Tzekos，他还做了 Job Opportunities API：雇主直招的职位数据，每个字段都带可自行核验的来源，免费阅读，也提供 API。如果 dsh-phone 对你有用，给本仓库点个 star，或者去看看 jobopportunitiesapi.org，就是最好的感谢。