agent-termbridge
v0.1.32
Published
Cross-machine terminal-agent bridge — run Claude Code / Codex on one machine and drive it from anywhere through your own relay (node-pty + WebSocket, optional password + self-signed wss).
Maintainers
Readme
termbridge
跨机器共用一台 Agent 终端台:既能用 node-pty 在宿主机(如 Mac mini)新建任意终端程序,
也会自动发现本机 Herdr 的全部 workspace/pane,并通过 Herdr API 直接进入现有 Agent。所有会话
经 relay 转发,让任何网络下的终端客户端凭一个 hostId attach。
本 README 是索引。真正的详细文档在
docs/,未来的技术方案 / 修改方案 / 修复方案也都落在那里。先读 docs/architecture.md。
前置
- Node ≥ 18、
pnpm(部署 Cloudflare relay 需要 Node ≥ 22) - macOS 需 Xcode Command Line Tools(
node-pty预编译产物相关)
安装
pnpm install # postinstall 会自动修好 node-pty 的 spawn-helper 可执行位推荐:扫码连接 Termbridge Cloud
默认不需要同一局域网、私有 VPN、VPS 或 Cloudflare 账号。Mac 和手机都只向官方 Cloudflare
中继建立出站 wss 连接:
tb cloudflare pair # 首次自动生成专属房间;以后重显同一个配对二维码
tb host enable # 后台启动电脑端,并在以后登录 macOS 时自动启动在 Android App 的 Connection settings 中点 Scan pairing QR 扫码即可。二维码内含连接密钥、
当前 Mac 的稳定匿名 ID 和显示名称,请按密码保管;需要再次显示时仍运行 tb cloudflare pair。
每台新 Mac 都可以直接执行这两条命令,手机分别扫码后会保存为多个可切换 profile,不需要先传
connection.uri。如果明确希望多台 Mac 共用同一个 Cloudflare 房间,再使用下面的连接码导入方式。
自签名 WSS Relay 的二维码还会携带 SHA-256 证书指纹;扫描另一台电脑会新增一个顶部 Tab,不会替换已有配对;同一 Mac 重复扫码按 ID 去重。长按 Tab
可重新连接或从手机取消配对。每次执行不带配对码的 tb cloudflare use 都会创建一个新房间,
也可以作为独立 Tab 与旧房间并存。把另一台电脑加入同一房间可运行:
tb cloudflare use tb1_<第一台电脑显示的连接码>
tb host随后 App 顶部可在多台 Mac 间切换;离线 Mac 会保留 Tab,明确选择它时不会悄悄跳到另一台。 Host ID 首次由物理 MAC 派生为不可逆短哈希并持久化,网络变化或重启不会改变。官方中继会按密钥哈希分配独立 Durable Object,密钥不放 进 URL;传输使用 WSS,但中继并非端到端加密,终端内容会在 Worker 内解密并转发。
全局命令 tb
npm 包同时提供 tb 和 termbridge 两个命令。
# 守护进程(在 Mac mini 上跑一次)
tb # 起 relay + host;默认入口(env PORT 默认 7400)
tb surf # 显式写法,与 tb serve 相同
tb serve # 显式写法;同时启用 Host 上已配置的云端语音服务
# Cloudflare Host:无参数仍是前台模式;子命令管理 macOS 后台服务
tb host # 前台运行,Ctrl-C 停止
tb host start # 放入后台,仅当前登录会话
tb host enable # 后台运行,并启用登录后自动启动
tb host restart # 重新读取最新 pair、代理和 shell 环境
tb host status # 看 PID、后台状态、登录启动和日志路径
tb host logs -f # 持续看后台日志
tb host stop # 停止后台 Host
tb host disable # 取消登录启动,不停止当前 Host
tb host doctor --fix # 检查并修复 node-pty spawn-helper 权限
# 每台 Host 独立的 Relay 网络路线(手机长按该 Host 标签也会修改同一配置)
tb network # 查看这台 Mac 当前策略和是否命中代理环境
tb network system # 跟随系统/HTTP(S)_PROXY(默认)
tb network direct # TB 忽略应用层代理;系统级 VPN 仍可能接管流量
tb host restart # 从本机 CLI 改完后,立即让后台 Host 重拨
# 让直接运行的 codex / claude 自动进入 Herdr,随即能被 TB 远程控制
tb init # 安装 PATH shim,并刷新 Herdr 官方 integration
tb init status # 查看状态
tb init uninstall # 恢复(修改 shell rc 前会自动备份)
# 会话(任意机器,命令都很短)
tb new claude # 开一个 claude 会话(自动套你的 proxy 命令)
tb new codex # 开一个 codex 会话
tb new # 不带参数 → 弹菜单选 agent
tb new -- <command...> # 开一个原始命令会话
tb ls # 列 TB 自建 PTY + 自动发现的 Herdr pane
tb context list # 按优先级列 Host 持久化的 Agent 上下文
tb context search 语音 # 搜索之前 Agent 的摘要与最近执行上下文
tb context show herdr:w7:p2 # 查看一个 Agent 的已捕获上下文
tb 1 # 按序号接入(= tb sess-1)
tb 'herdr:wA:p1' # 直接进入现有 Herdr pane(id 取自 tb ls)
tb kill 1 # 杀会话
# agent 预设(在 host 上的配置,免手动编辑 JSON)
tb info # 看 host、shell、relay/中转,以及每个 agent 到底跑什么命令
tb set claude "proxy && claude --dangerously-skip-permissions" # 定义/改预设
tb rm claude # 删预设
# 高级:用自己的 VPS 跨网
tb middle serve # 在服务器上跑 relay(端口 8001)
tb middle set <vps-ip> # 本机(client / Mac mini)改连这个中转
tb middle # 看当前中转(tb middle unset 取消)
# 高级:部署到自己的 Cloudflare 账号
tb cloudflare login # 首次使用时通过浏览器登录 Cloudflare
tb cloudflare deploy # 部署、写入加密 secret,并自动切换 middle URL
tb cloudflare pair # 首次创建官方房间或重显当前 relay 的 App 配对二维码
# 密码(锁住中转,HMAC 挑战应答,密码不过线;三端设同一个)
tb secret set # 隐藏输入设 1–256 字符密码(写进 ~/.termbridge/settings.json,chmod 600)
tb secret # 看状态(只显 set/none,绝不回显明文;tb secret unset 取消)
# 流量加密:自签 wss(无需域名,IP 写进证书,两端固定指纹)
tb middle cert <vps-ip> # 在服务器上生成自签证书 + 打印 SHA-256 指纹
tb middle pin <fingerprint> # 各端固定该指纹(再 tb middle set wss://<vps-ip>:8001)new claude 里的 claude 映射到真实命令,存在 host 的
~/.termbridge/config.json(tb surf 首次自动生成,默认已是你的 proxy 命令)。
不确定在跑什么就 tb info:
{
"shell": "zsh",
"agents": {
"claude": "proxy && claude --dangerously-skip-permissions",
"codex": "proxy && codex"
}
}全局 Brain 与百炼
Android 首页的 Global conversation 会把自然语言交给 Host 上的 Brain,再由 Brain 选择已配置的
Codex / Claude 等 coding agent。Host 检测到 DASHSCOPE_API_KEY 时默认使用阿里云百炼;没有 Key
时使用本地确定性路由。自然语言不会回退到 shell 执行。
Host 同时维护 ~/.termbridge/context.json(权限 0600):它持续收集每个 TB/Herdr Agent 的
workspace、状态、最近回复与近期终端上下文,并保留已消失 pane 的摘要历史。每次 Global dispatch
会先把完整当前 roster、每个 Agent ID 与各自近期上下文一次性给 Brain 规划器。规划器可以返回现有
herdr:workspace:pane ID,Host 会通过 Herdr API 原生派发并跟踪 Working → Done;也可以选择启动
全新的 Codex / Claude。随后执行 Agent 同样会收到最近完成任务、语义相关执行片段和最近 Global 对话,
第一轮回答不需要先搜索。排序优先匹配任务身份/自然语言语义,再考虑正在运行、刚完成和时间,
因此“刚才那个”“为什么没有语音了”可优先关联最近的 voice/TTS Agent。需要更深证据时,Agent 可用
tb ls、tb context search、tb context show 查询同一份 Host 权威状态,而不应把 Codex 自己的
sub-agent tree 当作 TB Agent roster。可用 TB_CONTEXT_REFRESH_MS 调整默认 5 秒采集周期,或用
TB_CONTEXT_STATE 改变本机索引路径。
Android 的 Voice 模式默认接入火山引擎豆包实时语音 3.0(Seeduplex,模型 1.2.6.1),也可在
Voice settings 中切回百炼 qwen3.5-omni-flash-realtime:先读三段
短句完成本人声纹录入;之后手机使用 arm64 版 Silero VAD + CAMPPlus 在本地判断“有人说话且是本人”,
通过后才把 16 kHz PCM 经现有 relay 流给 Host。Qwen3.5 Omni 是持续通话的主 Brain,直接返回
24 kHz 流式 PCM;每段本地 VAD 判定结束的语音会自动成为一个 Call 回合,不需要再说“发送”。Brain
可通过 inspect_workspace 的 overview、recent、tasks、agent 视图查询真实执行状态,通过 continue_agent
继续指定 Herdr/TB 会话,或用 dispatch_agent 把新任务交给本地 Codex/Claude Code。调用工具时手机
会播放短提示音并显示工具的开始、完成或失败过程。Host 会在通话开始时注入结构化的 Agent roster、
最近完成事件、最近结果和 Global 上下文;运行中的新变化通过 inspect_workspace
等工具即时刷新,不把整段旧终端输出当成当前事实。
Voice settings 可按 Call 选择 自动 / 阿里云百炼 / 火山引擎;首次使用默认火山引擎,自动模式也会在
火山配置可用时优先选择火山,否则回退百炼。通话左上角显示实际命中的服务、
模型与连接耗时,回复开始后显示本轮首响耗时;两条链路共用同一端侧采音、Global 上下文、Execution
Fork 和工具 UI,适合做公平 A/B。Android 诊断可实时看 adb logcat -s TermBridgeVoice,或导出
adb shell run-as com.termbridge.android cat files/diagnostics/voice-events.jsonl;Host 对应日志位于
~/.termbridge/logs/voice-events.jsonl。日志不保存音频、转写正文、Prompt、图片或云端凭据。
工具在 Host 注册时可以同时提供可选的 ui(result);有 UI 的一次工具结果会变成一张紧凑的 Android
原生卡片,结果项各占一行。卡片在 Call 界面即时显示,并持久化到 Global 时间线,因此挂断或重连后仍
可浏览;询问单个“最新”结果时只请求一项。没有 UI 的工具照常执行,不产生卡片。带 sessionId 的行
可进入对应 Terminal,返回后仍是原来的 Global Chat。对模型仍只暴露标准工具定义,UI 只接受 Host
生成的固定卡片协议(5 种类型、最多 8 条),不会渲染模型生成的任意界面;Voice 只简短确认结果已显示,
不逐条朗读列表。
Global Brain 的文字与 Voice 共用同一套注册工具。其中只读的 workspace_files(action, path) 聚合工具用 list 浏览项目目录、read
读取文本文件,path=@memory 读取 TermBridge Memory。普通路径相对于 TB_BRAIN_FILES_ROOT(默认
~/code),Host 会限制返回大小并拒绝路径穿越、二进制文件、密钥和常见凭据文件。文件修改、测试和
Shell 操作仍必须交给本地 Agent,云端 Voice 模型不会获得任意 Mac 文件系统权限。
Global 的文字输入与 Call 是并列入口,不再使用 Text/Voice 模式开关:Call 按钮发起通话,挂断只结束
当前通话并回到同一条时间线,不改变输入偏好或清空未发送文字。“发送”关键字只用于普通语音输入/听写
模式,不参与 Call。Call 会申请独占的临时音频焦点,并使用
Android 通信音频链路的 AEC/降噪;Host 把已播出的 Brain 文本保留在短期回声窗口内。播放期间检测到声音后会先完成端侧
声纹和云端转录,命中刚播出的回声就丢弃,确认是真实用户插话才停止当前音频并切换到下一轮。
这样录音可以始终保持开启,又不会把扬声器回灌当成用户继续对话。Voice settings
可选择 1×、1.25×、1.5×、2×、2.5× 或 3× 的本地播放速度;波形使用 3 倍输入增益与
attack/release 平滑。挂断会退出 Voice 状态并清空 Call 临时字幕;普通消息朗读也通过 Host 上的百炼
在线 TTS,不回落到 Android 系统音色。旧版 ASR → Brain → TTS 消息仍保留为协议兼容路径。
Host 使用本机 ~/.termbridge/memory.md 保存跨会话的用户偏好和项目决策。每次建立新的百炼 Realtime
Call 时,Host 读取最多 6000 字符的 Memory 快照,并随 session.update.instructions 注入一次;同一
Call 的后续回合复用云端会话上下文,不重复上传文件。派发给本地 Codex/Claude 或继续已有 Agent 时,
只告诉它 Memory 路径,由 Agent 使用自身 FS 能力按需读写,不注册额外 Memory 工具。Memory 不应保存
密码、API Key、Token 或短暂的 Agent 状态。可用 TB_BRAIN_MEMORY 覆盖默认文件路径。
声纹向量使用 Android Keystore 加密,只放在 APP 私有且禁止备份的存储中;百炼 API Key 始终只保留在
Host 进程环境。Global 文字对话默认由 qwen3.8-flash 直接回答,不再把每条消息交给本地 Codex;只有百炼明确调用
continue_agent 或 dispatch_agent 时才触发本地执行。未配置 AK 时 Global 会明确不可用,不回退为本地对话模型。
未通过声纹的音频不会发往 Host。当前本地模型运行包面向 arm64-v8a Android 手机。
export DASHSCOPE_API_KEY='你的百炼 API Key'
tb host
# 可选
export TB_BRAIN_MODEL=qwen3.8-flash
export DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export TB_BRAIN_ASR_MODEL=qwen3-asr-flash
export TB_BRAIN_ASR_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
export TB_VOICE_TTS_MODEL=qwen3-tts-flash
export TB_VOICE_TTS_VOICE=Cherry
export TB_VOICE_REALTIME_MODEL=qwen3-asr-flash-realtime
export TB_VOICE_REALTIME_URL=wss://dashscope.aliyuncs.com/api-ws/v1/realtime
export TB_VOICE_OMNI_MODEL=qwen3.5-omni-flash-realtime
export TB_VOICE_OMNI_URL=wss://dashscope.aliyuncs.com/api-ws/v1/realtime
export TB_VOICE_OMNI_VOICE=Tina # 可选;不设置则使用模型默认音色
export TB_BRAIN_PROVIDER=bailian # 默认值;不支持 local 对话回退
# 实时 Call 默认优先火山 Seeduplex;Global 文字和 Execution Fork 仍用上面的百炼配置
# 可显式设为 bailian 切回百炼,或设为 auto 保持火山优先、百炼兜底
export TB_VOICE_PROVIDER=auto
export VOLCENGINE_S2S_API_KEY='火山豆包语音控制台中的 API Key'
export TB_VOICE_VOLCENGINE_MODEL=1.2.6.1
export TB_VOICE_VOLCENGINE_SPEAKER=zh_female_vv_jupiter_bigtts
# 旧版 O2.0 兼容配置(没有新版 API Key 时才使用)
# export VOLCENGINE_S2S_APP_ID='旧版语音 APP ID'
# export VOLCENGINE_S2S_ACCESS_TOKEN='旧版语音 Access Token'
# export TB_VOICE_VOLCENGINE_MODEL=1.2.1.1
# export TB_VOICE_VOLCENGINE_END_SMOOTH_WINDOW_MS=1400
# 发起一次真实但低用量的百炼文字对话 + 工具调用请求
pnpm test:bailian
pnpm test:voice
pnpm test:voice-realtime
pnpm test:voice-omni
pnpm test:voice-host-e2e # 经当前 relay/Host 验证转写、回复音频及可选 Agent 派发API Key 只从 Host 进程环境读取,不会进入 App、Brain 状态文件或 relay。若使用其他地域的百炼 Key,
需同时设置对应地域的 HTTP 与 Realtime 地址。新业务空间优先使用
wss://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime;旧 DashScope 域名当前仍兼容。
每次 Omni 响应的模型、文本/音频 Token、输入/输出时长和列表价估算会追加到
~/.termbridge/voice-usage.jsonl(权限 0600);Android 的 Voice settings 会显示当前 Mac 汇总的
实时估算费用、响应次数与输入/输出时长。该值按返回 token 与公开单价估算,实际账单仍以百炼控制台
为准,官方账单通常有数分钟延迟且需要 Console/费用中心权限,普通模型 API Key 不能读取财务账单。
火山直连凭据同样只保留在 Host;当前火山公开文档没有给出稳定的 S2S-O 后付费 Token 单价,因此
本地账本会记录其 Token 与时长,但不会把它伪装成可靠的费用估算。完整接入边界见
ADR-0012。
本机一分钟验证
tb surf # 终端 A:守护进程
tb new claude # 终端 B:直接进 claude(本机默认连 localhost:7400,免配)
# Ctrl-C 中断终端里的程序;Ctrl-] 打开连接菜单,d 断开、Enter/c 继续
# 断开保留宿主会话;之后 tb ls / tb 1 再回来自动接管 Codex / Claude
tb init 不修改 Codex、Claude 的安装文件,也不依赖它们某个内部版本。它在 shell 的 PATH 最前
安装两个指向同一透明 dispatcher 的符号链接:交互式 codex / claude 会在当前目录创建 Herdr workspace、启动 Agent
并 attach;Termbridge host 随即通过 Herdr API 发现该 pane。--help、--version、Codex exec、
Claude --print、管道和脚本调用会直接执行 PATH 后方的真实程序。Agent 更新或重装后无需重建
链接;每次启动都重新解析当前 PATH 中的 tb 和真实 Agent 入口,不复制 Agent 程序、不缓存其版本路径。
包管理器目录只在 PATH 找不到 Agent 时作为后备,避免旧的 PNPM_HOME 把已升级的入口切回旧版。
再次运行 tb init 会顺便更新 Herdr 官方 integration。Herdr 不可用时也会安全直通原命令。
直接进入 Herdr
tb host / tb surf 启动时默认探测 ~/.config/herdr/herdr.sock,一次 snapshot 导入当前
全部 workspace、tab、pane 和 agent 状态。tb ls 中 source=Herdr 的项目可由 CLI、Android
或 iOS 直接进入。CLI 使用 Herdr 的 terminal session control 原生终端流,经 TB Relay
转发 ANSI、原始输入和窗口尺寸,保留真实光标位置与可见性。中文和多行粘贴直接传给终端,
Ctrl-C 中断程序;Ctrl-] 打开连接菜单,按 d 断开,Enter/c 返回。连接重试时 Ctrl-C 也会先打开菜单。
断开只释放当前控制连接,原 Herdr 会话继续运行,不会自动抢占已有控制者。
CLI 和 Host 需要升级至 0.1.24 或以上;现有 Relay 原样转发,无需随此升级。Host 上的 Herdr 必须支持
herdr terminal session control。缺少支持时会明确报错。手机客户端继续使用
pane.read / pane.send_input 的移动呈现与输入适配。
tb ls
tb 'herdr:w4:p3'Herdr pane 的布局与生命周期由 Herdr 管理。普通断开不关闭 pane;显式 tb kill 会关闭目标会话。可用 TB_HERDR=off 禁用发现,或用 TB_HERDR_SOCKET=/path/to/herdr.sock
指定 socket。
其他远程 / 跨网方式
推荐直接使用上面的 tb cloudflare use。如果明确要走局域网或 Tailscale,也可以让客户端的
RELAY_URL 指向宿主可达地址:
RELAY_URL=ws://<mac-mini-ip>:7400 tb ls
RELAY_URL=ws://<mac-mini-ip>:7400 tb new claude不想每次写 RELAY_URL、又要任意网络可达:用你自己的服务器当中转——VPS 上
tb middle serve(relay,端口 8001),Mac mini 和客户端各 tb middle set <vps-ip>
一次即可(host 拨出、client 拨入,两端都不用端口转发;三端断线每 3s 自动重连):
# 在 VPS 上: tb middle serve
tb middle set <vps-ip> # 本机改连中转(写进 ~/.termbridge/settings.json)
tb new claude # 之后照常用,自动走中转公网中转记得加密码(HMAC 挑战应答,密码不过线):三端 tb secret set 设同一个,或
relay 用 TB_SECRET=… tb middle serve。没正确密码的连接在 hello 前就被拒,tb info 末尾
auth on/off 可查。
# 在 VPS 上: TB_SECRET='很长的口令…' tb middle serve
tb secret set # Mac mini + 客户端各设同一个密码
tb middle cert <vps-ip> # 可选:自签 wss 加密内容,两端再 tb middle pin <指纹>只有一个宿主时不用指定它;多个宿主用 tb @<hostId> ... 选。详见
docs/deploy.md。(密码只解决「谁能连」、不加密内容;要内容加密用自签 wss——
tb middle cert <ip> 生成证书、两端 tb middle pin <指纹>,无需域名。)
不使用官方中继时可以运行 tb cloudflare deploy。它部署一份属于你 Cloudflare 账号的 Worker,使用
Durable Object 协调多个 Mac mini 与手机客户端的 WebSocket,并启用 WebSocket Hibernation。
命令会生成/复用本机共享密码,以 encrypted secret 写入 Worker,再将 wss://…workers.dev
自动保存为 middle;secret 缺失时 Worker 会拒绝连接。详见
docs/cloudflare.md。
仓库内脚本(免装全局,等价)
pnpm surf # = tb surf
pnpm tb … # = tb …(如 pnpm tb ls)
pnpm relay # 单独起 relay
pnpm host # 单独起 host
pnpm test # typecheck + 单元 + Workers runtime + 集成测试Android app
独立 Android 客户端在 android/:包含 session list、New、进入已有
READY / ACTIVE session、扫码配对,以及基于 xterm.js 的完整移动端终端。构建、连接和模拟器测试
说明见 android/README.md。
Android 还可以在全局 Connection settings 中配对 TermBridge Watch。手表自动继承手机当前的 Mac profile,可选择加密蓝牙网关、Wi-Fi 直连或自动切换;它不要求 profile 必须来自 Cloudflare。 配对、安全边界、流量与语音格式见 docs/watch-companion.md。
Amazfit T-Rex 3 的 Zepp OS 版本位于 watch/zepp-os-termbridge/:首屏是按
紧急程度和时间排序的通知工作箱与 Global 语音,完整 Agent 列表放在二级页。通知详情可获取真实摘要、
检查后重试、继续、停止、稍后 30 分钟,或把准确会话接力到手机;待批准事项只允许接力,不在手表上直接
执行有后果的批准。Android 的 Watch Hub 负责配对码、通知路由、连接诊断和动作/语音回执历史。
macOS 菜单栏控制中心位于 macos/TermBridgeControlCenter/,直接读取
Host 的权威 Agent 上下文,显示需要关注/运行/完成状态,并可打开准确的 Herdr 或 PTY 会话。
iOS app
独立 SwiftUI 客户端在 ios/:同样支持 session list、New、进入已有
READY / ACTIVE session,以及内置 xterm.js 的完整 PTY。Shared secret 存 Apple
Keychain;构建和连接说明见 ios/README.md。
测试
pnpm test启动真实 relay+host,端到端断言核心保证(round-trip / 持久 / 重接 / agent 预设 / 多 viewer /
CLI 二进制 / 中转设置 / 密码鉴权 / 自签 wss + 指纹固定)。详见 docs/testing.md。
(我每次改完代码会用 test-termbridge skill 跑这套。)
包结构
| 包 | 作用 |
|----|------|
| @termbridge/protocol | 二进制分帧 + relay 信封 + 消息 schema |
| @termbridge/settings | 本地设置(中转地址 + 共享密码);resolveRelayUrl 优先级 + HMAC 助手 |
| @termbridge/brain | 全局对话状态、百炼规划与 coding agent 安全路由 |
| @termbridge/voice | BYOK 云端 ASR/TTS;默认百炼 Qwen3-ASR + Qwen3-TTS |
| @termbridge/relay | 会合/转发服务器(中转:tb middle serve);可选密码鉴权 |
| @termbridge/cloudflare-relay | Durable Object + WebSocket Hibernation 公网中转 |
| @termbridge/host | TB PTY 会话管理 + Herdr socket API 适配 + 广播 |
| @termbridge/cli | attach 客户端 + 统一 termbridge 调度 |
| android/ | 原生 Android session 管理与 xterm.js PTY 客户端 |
| ios/ | SwiftUI session 管理、Keychain 安全设置与 xterm.js PTY 客户端 |
细节见 docs/architecture.md。
文档
- 架构 — 三角色 / 拓扑 / 时序 / 反向工具注入 / 安全 / 技术栈
- 线协议 — 帧格式 / relay 信封 / 控制消息 / 不变量
- Mac mini 部署 — relay+host 常驻、跨网(Tailscale)、launchd、怎么跑带 proxy/别名的 agent
- Cloudflare 中转 — 一键部署、认证模型、费用与排错
- 手表 companion — Android 配对、BLE/Wi-Fi 语音、安全与流量边界
- 测试 — 跑法、覆盖、如何加场景
- 排错 — posix_spawnp / 信封 / 端口 / 全局命令
- 线路图 — P0–P4 与现状
- 决策记录 — ADR;技术/修改/修复方案落这里
Install the macOS App from the CLI (0.1.26+)
tb app install # download and verify the official signed App into ~/Applications
tb app status # installed version and path
tb app open # open the installed AppCurrently supports macOS 13+ on Apple Silicon, matching the website artifact. Installation validates the website's pinned Sparkle feed/archive signatures, SHA-256, app identity, developer team and Gatekeeper assessment. Existing apps are backed up when replaced; running apps must first be quit normally, or updated through their own Settings. No administrator password or Host restart is required. New Mac App installations can install the CLI and create phone pairing from Settings.
