herdr-web
浏览器里的终端，用来跑 herdr。一个 Go 二进制，前端嵌在里面，
手机也能用。
语音投稿是主功能：在平板上说话打字，说错的字框选重说就改掉，改完整段投进 agent 的输入行。
手机上够用，平板横屏 211 列 —— 那是个工位。
┌─────────────────────────────────────────────┐
│ 面板一览 文件 改动 对话 ... 设置 │ 顶栏：放哪几个自己拖
├─────────────────────────────────────────────┤
│ │
│ herdr 的 pane，和电脑上一模一样 │
│ │
├─────────────────────────────────────────────┤
│ 说完的一整段话... [ 投稿 ] │ 发件箱：一行，回车就投
│ [键盘][^B][Ctrl][Esc][方向]...横滑... │ 快捷键条：手机没有 Ctrl 键
└─────────────────────────────────────────────┘
装
npm install -g @bysir/herdr-web # 有 node 最省事，升级也交给它
herdr-web # 只听 127.0.0.1
没有 node（服务器上常见）：
curl -fsSL https://raw.githubusercontent.com/zbysir/herdr-web/master/install.sh | sh
装到 ~/.local/bin，强制校验 sha256 —— 这东西后面挂着一个登录 shell。
Windows 没有原生版，在 WSL 里装（浏览器里那个终端要一个真 PTY）。go install 也能装，
但装出来的没有前端（前端产物不入版本库）。
安卓 App（可选，测试版）：从 Releases 下
herdr-web_<版本>.apk 装到手机上，打开填你自己那台 herdr-web 的地址，再用配对码或 passkey 登录。
它只是个壳，服务端照上面那样装。新版 APK 直接覆盖安装就能升级。
→ 从源码装、换安装目录、装指定版本：使用说明 · 装
用
手机 / 平板连进来：
HERDR_WEB_HOST=0.0.0.0 herdr-web
启动横幅里有一个一次性配对码和它的二维码，手机扫一下就进去了。一台设备配一次 ——
凭据在 HttpOnly cookie 里，换 Wi-Fi、换网段、重启都不用重来。连上之后自动敲 herdr。
地址栏里加一段路径就是另一个 herdr session：/work 敲的是 herdr --session work，
两个书签就是两套工作现场，关掉浏览器再回来还在。
herdr-web pair # 再出一个一次性配对码 + 二维码
herdr-web devices # 列出已配对设备
herdr-web revoke <id> # 踢掉某台（all = 全部），下一个请求立刻 401
不想开浏览器、想在另一台电脑的原生终端里用：
herdr-web connect https://你的域名 # 第一次：浏览器里刷 passkey 批准，或输配对码；/work 同上
它配出来的也是一台普通设备（设备页里看得见、踢得掉），每天的重验同样靠 passkey（在浏览器里批准一下），
网络僵住时行首按 ~. 断开。
→ 管理页、session 命名规则、连上敲什么、connect：使用说明 · 第一次跑
能干什么
| |
|---|
| 发件箱 | 底下那一行输入框，说完一整段投进 agent 的输入行。回车就投，⇧↵ 换行；截图直接 ⌘V，手机上拍照 / 录像传过去接成路径 |
| 快捷键条 | 手机没有 Ctrl 键，herdr 的 ctrl+b 前缀全靠它。键自己配（按键谱 / 图标 / 弹出组 / 钉住不跟着滑），方向键按住连发 |
| 面板一览 | 一张 pane 列表，点一行跳过去并铺满全屏。agent 停下来等你回答时，顶栏上点一个红点 |
| 对话 | 把 agent 自己写的会话记录读成一条对话流，代替那一屏 TUI —— 手机上读它比读 TUI 舒服得多 |
| 文件 | agent 说「图生成在 /tmp/plot-3.png」，点那行路径就能看。图直接看，md 渲染成文档，文本能就地改 |
| 改动 | git diff 在手机终端里基本读不了：这儿能折行、按词高亮，一次改动的全部文件是一条连续的流。只读 |
| 手机和平板 | 触屏手势整套接管（滑动 = 滚轮上报、长按 = 拖 pane 边框），底部面板能挪到右边，横竖屏各一套排布 |
| 装成 app | PWA：独立窗口、没有地址栏和工具条，白送好几行终端 |
| 安卓 App（测试版） | 界面同网页，补上网页做不到的：agent 跑完 / 等你回答弹系统通知、通知栏和桌面小部件一览；局域网自动直连，地址不变，出门自动走中继（左上角点：绿 = 直连、蓝 = 中继）；音量键当 ↑ / ↓。APK 在 Releases 里 |
| 本地端口 | agent 起的 http://localhost:7830，在 https://7830.你的域名 上打开，先过登录；终端和对话里这种链接点了直接过去 |
→ 每一件具体怎么用：使用说明 · 能干什么
配
配置只有一个来源：环境变量（没有配置文件，命令行标志只有一个 --web）。几套常见的：
herdr-web # 1. 纯本机（默认），明文 http
HERDR_WEB_HOST=0.0.0.0 herdr-web # 2. 局域网的手机 / 平板，自签 TLS + 二维码
HERDR_WEB_ONCONNECT= herdr-web # 3. 别自动进 herdr，留在 shell 里
# 4. 从公网连：走云端中继（VPS 上跑 dialhome，只转密文，TLS 在本机终止）
# 中继是独立项目 https://github.com/zbysir/dialhome（镜像 ghcr.io/zbysir/dialhome），网页后台里出邀请码
# `relay join` 一条命令注册 + 装成服务（下面前两项它替你加），证书配置带在同一行：
# HERDR_WEB_ACME_DNS=cloudflare HERDR_WEB_CLOUDFLARE_DNS_API_TOKEN=... herdr-web relay join https://relay.example.com mac.h.example.com <邀请码>
HERDR_WEB_RELAY_URL=https://relay.example.com HERDR_WEB_RELAY_HOST=mac.h.example.com \
HERDR_WEB_ACME_DNS=cloudflare HERDR_WEB_CLOUDFLARE_DNS_API_TOKEN=... herdr-web
# 5. 在 4 的基础上，把本地端口代理出来：http://127.0.0.1:7830 → https://7830.mac.h.example.com
# DNS 上加一条 *.mac.h.example.com 通配记录，证书会多签一个 *.mac.h.example.com
HERDR_WEB_PORT_DOMAIN=mac.h.example.com
主口（默认 7788）只服务本地网络：对端不是本机 / 私网一律 403，没有开关能打开。公网只走
中继 —— VPS 上只见密文，被拿下也看不到终端。frp / 反代解密那条路（PUBLIC_PORT、TLS=proxy）
2026-10-23 下线了，见 DEPLOY.md。
→ 四十多个变量的完整表：使用说明 · 配置
常驻 · 更新
herdr-web service install # macOS → launchd，Linux → systemd user unit，开机自启
herdr-web update # 查 + 升（怎么升看当初是怎么装的）
配置是 install 那一刻从当前 shell 抄进去的。改配置 = 带着要改的那几项重新 install（幂等），已装的那份里其余 HERDR_WEB_* 会沿用。
→ 常驻 · 更新
安全
这东西等于一个 HTTP 上的 shell，门是按这个前提设计的：
- 一台设备配一次：一次性配对码换一份 per-device 凭据，服务端只存 sha256；
- 凭据绑设备不绑 IP，换网不掉线；URL 里没有秘密（
?pair= 进来就换成 cookie 再 302 洗掉）；
- 配对码只能由坐在机器前的人产生 —— 网页上任何路径都不出码，那是唯一的带外因子；
- 暴露出去又没 TLS 就拒绝启动；Host 白名单挡 DNS rebinding，三道挡 CSRF，猜码指数退避 + 封锁；
- passkey 是第二因子，服务端只存公钥；
- 公网只走自己的中继，中继只转密文：TLS 在本机解开，VPS 上没有证书私钥、设备表和 passkey，
DNS 上的 CAA 记录锁死「证书只有本机能签」—— 中继整台被拿下也只能断网；
- 本地端口在单独的子域名上：被代理的是 agent 的页面，拿不到主站凭据；要先过登录，设备撤销当场失效。
→ 威胁模型、每条为什么这么设计：SECURITY.md
文档
MIT。
