Terminal Hole

祝融说。

抱朴守缺。肩吾 huan（幻） PinConsole 共识并不平均，但是基本上均衡。权力是共识切片的曲率。存在不是「是什么」，而是一系列极小的，从分歧到共识再到分歧的，连续的构建过程。分歧实际上是对共识往哪个方向延伸的拉力。分歧是尚未落实的实在，是可能性基底中尚未被锁定的在共识中相互牵引的可用余量。权力从来不是中立的，它是带有倾向性的「牵扯力」。过程即完备，容错即自由。第10章逆向投喂：用真实数据让AI做出精准诊断第11章测试电网：用刚性指标代替肉眼审查第12章定期“垃圾回收”：别让系统背负AI制造的债务第13章防退化契约：确保每一次修改都是在进步第14章全生命周期演练：从零开始用“有效约束”交付一个项目第15章随身工具包：即查即用的约束指令库第1章这不是结对编程，这是“人机共生” 第2章你必须警惕的三个陷阱第3章把话说死：用 Markdown 建立 AI 的“单源真相” 第4章负空间设计：先规定“不准做什么”，再让它写代码第5章模块化解耦：让AI每次只面对一个小问题第6章上下文断头台：善用 `/clear` 斩断错误蔓延第7章剥夺执行权：强制 AI 像资深工程师一样“慢思考” 第8章角色锁定：用一句话给AI戴上“思考帽” 第9章遥测驱动：帮AI长出“千里眼”和“顺风耳” 结语：成为系统牧马人，而不是代码搬运工第八章金融与科技的“禁手”：现代战争的底层收敛第二章认知锚点：心理战中的“强制步” 第九章历史的单行道：那些被剥夺国运的时刻第六章消费主义的迷宫：在货架上剥夺选择第七章战略逼压：没有硝烟的“切香肠战术” 第三章构造绝杀：逻辑闭环的艺术第十二章绝对零度下的生机：成为“不可测”的人第十一章掀翻棋盘：非对称竞争与正交化打击第十章识破隐形控制：第一时间嗅到危险第四章标准的暴政：打造“不得不”的生态第五章锁死阀门：关系链与供应链的囚笼第一章降熵法则：时空维度的隐蔽控制结语：愿你在这个被设定的世界里，永远握有掀桌的权力。引言：自由意志的幻觉项羽当前的AI工程化本质上是受限于上下文长度而采用的「以提示词约束去置换确定性」的一种妥协。即时反应是一种不假思索，它是观念通过最简单、轻易、高效的路径寻求表达。青衫第九章：估值的坐标：建立“内在记分牌” 第六章：资产重估的艺术：从“硬实在”到“认知折价” 第七章：预期差交易：坍缩“概率波” 第十一章：内在博弈：克服‘评估异化’ 第十章：交易的算法：逆人性的“人之道” 第五章：空间套利：高能耗产业的跨境建构结语：构建你的“财富多重宇宙” Code-Coder 第八章：效率革命：细分赛道的“降本增效” 第二章：评估权的博弈：商业模式的权力差序第三章：去伪存真：穿透“符号泡沫” 第四章：能源共识：黑金的物理法则第一章：宏观观察者：借势“国家共识” 前言：从“市场囚徒”到“清醒的观察者” Code-Ledge-X Code-Lint-X

Terminal Hole

祝融 · 2026-06-25 · via 祝融说。

Expose your local terminal to a public IP for remote control from a browser.

把本地终端通过公网中继暴露给浏览器，让你离开电脑后仍能用手机操作本地的命令行工具（如 Claude Code、vim、tmux 等）。

工作原理

手机浏览器              公网 VPS                  本地电脑
┌──────────┐         ┌──────────┐            ┌──────────┐
│  xterm.js│  WSS    │          │  WSS out   │          │
│  Web UI  │◄───────►│  Relay   │◄───────────│  Agent   │
└──────────┘         └──────────┘            └────┬─────┘
                                                      │
                                              ┌───────┴──────┐
                                              │ tmux 会话们   │
                                              └──────────────┘

Agent（本地）：管理 tmux 会话，提供 Web 终端，主动 WSS 连出到 Relay
Relay（公网 VPS）：HTTPS 入口，认证浏览器，反向代理到 Agent
浏览器：xterm.js + 原生 JS，多 tab 切换不同 tmux 会话

关键设计：tmux 是终端的"持久化层"，会话独立于任何网络连接。浏览器关了、网络抖了，会话不丢；只有 Agent 进程死了会话才消失。

前置要求

Go 1.25+
tmux（macOS：brew install tmux，Linux：apt/dnf install tmux）
一台有公网 IP/域名的 VPS（用于跑 Relay）
一个指向 VPS 的域名（用于 ACME 自动签证书）

安装

一键安装（Agent + Relay 通用，推荐）

curl -fsSL https://raw.githubusercontent.com/iannil/terminal-hole/main/scripts/install.sh | sh

装特定版本：

curl -fsSL https://raw.githubusercontent.com/iannil/terminal-hole/main/scripts/install.sh | sh -s -- --version v0.1.0

装到自定义路径：

curl -fsSL https://raw.githubusercontent.com/iannil/terminal-hole/main/scripts/install.sh | sh -s -- --install-dir /opt/bin

行为：

root 跑装到 /usr/local/bin，普通用户装到 ~/.local/bin（并提示加 PATH）
SHA256 校验 checksums.txt
检测 tmux 缺失时打印安装命令（Relay 不需要 tmux，可忽略）

Docker（仅 Relay，推荐用于 VPS）

# 首次初始化配置（交互式，写入 ./config/config.yaml）
docker run --rm -it \
    -v "$PWD/config:/etc/terminal-hole" \
    ghcr.io/iannil/terminal-hole-relay:latest init --mode relay

# 启动 Relay
docker run -d --name terminal-hole-relay \
    -p 443:443 -p 80:80 \
    -v "$PWD/config:/etc/terminal-hole" \
    -v "$PWD/state:/var/lib/terminal-hole" \
    ghcr.io/iannil/terminal-hole-relay:latest

镜像 tag：v0.1.0（精确版本）、0.1（小版本滚动）、latest（最新）。

注意：

必须把 DNS A/AAAA 记录指向 VPS 后再起容器（ACME 验签）
-v state 卷保留 ACME 证书缓存和 signer secret；丢了 → 浏览器 cookie 全失效，要重新登录

从源码构建（开发/贡献者）

git clone https://github.com/iannil/terminal-hole.git
cd terminal-hole
go build -o terminal-hole ./cmd/terminal-hole

需要 Go 1.25+。跑测试还需本机装 tmux。

部署

1. Relay（在 VPS 上）

# 交互式初始化（生成 /etc/terminal-hole/config.yaml）
sudo ./terminal-hole init --mode relay
# > 域名？ tp.example.com
# > 管理员账号？ alice
# > 管理员密码？ 

# 启动（前台；生产可用 systemd 包装）
sudo ./terminal-hole relay

Relay 会：

在 :443 上跑 HTTPS，用 Let's Encrypt 自动签证书
在 :80 上跑 HTTP→HTTPS 重定向（可在 config 用 http_listen: "-" 禁用）
接受 Agent 的 WSS 隧道连接（wss://tp.example.com/agent-tunnel）
持久化 HMAC signer secret 到 signer.key，重启后浏览器 cookie 不失效

DNS：先把域名 A/AAAA 记录指向 VPS，再启动 Relay（ACME 签证书时要验签）。

2. Agent（在本地电脑上）

# 交互式初始化（生成 ~/.config/terminal-hole/config.yaml）
./terminal-hole init
# > 选择密码存储方式：
#   1) 明文存 config（0600 权限）
#   2) password_file（自己创建文件，config 引用路径）
#   3) TH_AGENT_PASSWORD 环境变量（config 不存密码）
# > 中继地址？ https://tp.example.com
# > 账号？ alice
# > [根据选择] 输入密码 / 文件路径

# 启动
./terminal-hole agent

Agent 启动后会：

在 0.0.0.0:7777 起本地 Web 终端（局域网设备也能访问，需账号密码）
主动 WSS 连出到 Relay，注册自己
指数退避重连（1s → 2s → 4s → ... → 封顶 30s）

日常使用

本地启动 Agent，让它跑着（不要登出系统，否则 Agent 进程会被杀）
锁屏离开
手机浏览器打开 https://tp.example.com，输入账号密码登录
看到 sidebar 会话清单（首次为空），点 "+" 新建终端
在终端里跑 claude、vim、htop 等命令，跟本地操作一致
关浏览器/tab 不杀会话；下次登录点回原会话继续

手机键盘：界面底部有特殊键面板（Esc / Tab / Ctrl / Alt / 方向键 / / / - / Enter / Backspace）。Ctrl/Alt 是修饰键，点一下高亮，下次输入组合生效。仅在触摸设备显示。

多端共享：tmux 原生支持多客户端 attach，手机和电脑可同时看同一个会话。

Agent 掉线自动恢复：浏览器订阅 /api/agent-status SSE，Agent 重连后自动刷新会话清单并重 attach 当前会话。

配置参考

Agent (`~/.config/terminal-hole/config.yaml`)

agent:
  relay:
    url: https://tp.example.com
    username: alice
    password: "secret"            # 或 password_file / TH_AGENT_PASSWORD
  local:
    bind: 0.0.0.0:7777            # 默认值；改 127.0.0.1 可限制只 loopback 访问
    shell: /bin/zsh               # 默认从 $SHELL 推断
    tmux_prefix: th-              # Agent 管理的 tmux 会话前缀

Relay (`/etc/terminal-hole/config.yaml`)

relay:
  domain: tp.example.com
  listen: ":443"
  http_listen: ":80"              # 设为 "-" 禁用 HTTP 重定向
  acme_cache_dir: /var/lib/terminal-hole/certs
  signer_secret_file: /var/lib/terminal-hole/signer.key
  allowed_origins:                # WS origin allowlist；空则走同源策略
    - https://tp.example.com
  # 自带证书模式（与 domain/ACME 二选一）：
  # cert_file: /path/fullchain.pem
  # key_file: /path/privkey.pem
accounts:
  - username: alice
    password_hash: "$2a$10$..."   # bcrypt，init 自动生成

配置优先级：CLI flags > 环境变量（TH_* 前缀）> config 文件 > 默认值

安全

认证：username + password（bcrypt 哈希），浏览器登录用 HMAC 签名 Cookie
TLS：Relay 强制 HTTPS（ACME 自动签或自带证书），不支持纯 HTTP 部署
限流：/api/login 5 次/IP/分钟，/agent-tunnel 10 次/IP/分钟，超限 429
会话 ID 校验：仅允许字母数字+下划线+连字符，最长 256 字符
错误消息：上游错误细节不暴露给客户端，仅记录到服务端日志
WS origin allowlist：可配置 relay.allowed_origins 做纵深防御 CSRF
稳定 signer secret：Relay 重启后浏览器 cookie 不失效
常量时间认证：登录失败时不区分"用户名错"和"密码错"，防用户名枚举

已知限制（v1）：

单用户单 Agent（不支持多机/多用户）
Agent 密码可明文存 config（建议用 password_file 或 TH_AGENT_PASSWORD 替代）
无审计日志、无文件传输、无 WebAuthn
Agent 前台运行，不自动重启（设计选择，简化使用模型）

子命令

terminal-hole init [--mode agent|relay] [--config PATH]   # 交互式生成 config
terminal-hole agent [--config PATH] [--bind ADDR]         # 跑 Agent
terminal-hole relay [--config PATH]                       # 跑 Relay
terminal-hole version                                     # 打印版本
terminal-hole help                                        # 帮助

状态与路线图

Plan 1：本地 MVP（Agent + 本地浏览器终端 + 多 tab + 手机键盘）
Plan 2：远程访问（Relay + WSS+yamux 隧道 + ACME）
Plan 3：体验打磨（稳定 signer、限流、SSE 状态推送、origin allowlist、ServeMux 模式）
Plan 4：分发（GoReleaser、install.sh、Docker、GitHub Actions）

详见 docs/design.md（完整设计）和 docs/superpowers/plans/（实现计划）。

开发

# 跑测试（需要本机装 tmux）
tmux kill-server 2>/dev/null; sleep 1
go test ./... -race

# 构建
go build -o terminal-hole ./cmd/terminal-hole

# 跑 vet
go vet ./...

项目结构：

cmd/terminal-hole/         入口
internal/agent/            Agent（管理 tmux、本地 HTTP、隧道客户端）
internal/relay/            Relay（HTTPS、登录、限流、SSE、代理）
internal/tunnel/           yamux 多路复用隧道
internal/tmux/             tmux wrapper
internal/pty/              creack/pty 封装
internal/auth/             bcrypt + HMAC cookie + 中间件
internal/config/           AgentConfig YAML
internal/protocol/         WS 控制消息
internal/web/              嵌入式静态资源 + 登录端点
internal/version/          ldflags 版本信息
internal/web/assets/       前端源码（HTML/CSS/JS + vendor xterm.js）

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

祝融说。

工作原理

前置要求

安装

一键安装（Agent + Relay 通用，推荐）

Docker（仅 Relay，推荐用于 VPS）

从源码构建（开发/贡献者）

部署

1. Relay（在 VPS 上）

2. Agent（在本地电脑上）

日常使用

配置参考

Agent (~/.config/terminal-hole/config.yaml)

Relay (/etc/terminal-hole/config.yaml)

安全

子命令

状态与路线图

开发

Agent (`~/.config/terminal-hole/config.yaml`)

Relay (`/etc/terminal-hole/config.yaml`)