162 lines
7.9 KiB
Markdown
162 lines
7.9 KiB
Markdown
# grok-glance
|
||
|
||
给 [grok](https://github.com/xai-org/grok-build) 终端会话加一个浏览器遥控台：镜像正在跑的 TUI，从网页里发 prompt、打断 turn、批准工具调用。终端不会交出控制权，两边同时可用。
|
||
|
||
一个 Go 二进制，前端编进去，一个端口，没有数据库。
|
||
|
||
```
|
||
你的机器 任何能打开浏览器的地方
|
||
┌─────────────────────────┐ ┌──────────────────┐
|
||
│ grok TUI（newgrok） │ │ │
|
||
│ │ │ │ │
|
||
│ └── /rc ══ WSS ═╪══▶ glance ══ WSS ══▶ 浏览器 │
|
||
└─────────────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
grok 主动连出来。glance 可以跑在你能访问的地方，跑 grok 的那台机器不必开端口、不必做内网穿透。
|
||
|
||
## 必须搭配 newgrok
|
||
|
||
glance 自己不会跑 agent。`/rc` 桥在 [iceBear67/newgrok](https://github.com/iceBear67/newgrok) 里：那是 `xai-org/grok-build` 的补丁工作流，远程控制是其中的 `0003` / `0004` 两个补丁。
|
||
|
||
**这两边是同一个功能。** 官方上游没有 `/rc`，单独用本仓库或单独用未打补丁的 grok 都连不上。线格式改一边，另一边也要改。
|
||
|
||
| 仓库 | 职责 |
|
||
|---|---|
|
||
| [iceBear67/newgrok](https://github.com/iceBear67/newgrok) | 打过补丁的 grok TUI；在会话里敲 `/rc`，作为 ACP Agent 拨出 |
|
||
| 本仓库 | 自托管控制面：鉴权、会话列表、把 ACP 转成网页 UI |
|
||
|
||
## 依赖
|
||
|
||
- Go 1.24+
|
||
- Node.js（构建嵌入的前端；`make build` 会跑 `npm`）
|
||
- 一台已经按 [newgrok 的 README](https://github.com/iceBear67/newgrok#快速开始) 编译好的 grok（`make setup && make apply && make build`）
|
||
|
||
## 快速开始
|
||
|
||
### 1. 编译并启动 glance
|
||
|
||
```sh
|
||
make build
|
||
bin/glance serve --addr 127.0.0.1:7717 --insecure-cookie
|
||
```
|
||
|
||
首次启动会在 stderr 打出一条一次性 bootstrap URL（同时写到 `~/.grok/glance/bootstrap.token`）。打开它，扫二维码，输入一个 TOTP 验证码。登记成功后这个 token 立刻作废。
|
||
|
||
`--insecure-cookie` 去掉 cookie 的 `Secure`，好让纯 HTTP 的 localhost 能登录。非回环地址会直接拒绝这个 flag。生产环境把 glance 放在终止 TLS 的反代后面，不要加这个 flag。
|
||
|
||
### 2. 给这台 grok 发一把 API key
|
||
|
||
另开一个终端：
|
||
|
||
```sh
|
||
bin/glance apikey add laptop
|
||
```
|
||
|
||
明文 `glance_sk_…` 只显示这一次，磁盘上只留 SHA-256。命令还会打出一段给 `~/.grok/config.toml` 用的配置。
|
||
|
||
### 3. 在跑 grok 的机器上写配置
|
||
|
||
把上一步打印的内容写进 `~/.grok/config.toml`：
|
||
|
||
```toml
|
||
[remote_control]
|
||
url = "ws://127.0.0.1:7717/api/acp/agent"
|
||
api_key = "glance_sk_…"
|
||
```
|
||
|
||
glance 不在本机时，把 `url` 换成它的地址（TLS 后面用 `wss://…`）。key 也可以不写进文件，改用环境变量：
|
||
|
||
| 配置项 | 环境变量 | 说明 |
|
||
|---|---|---|
|
||
| `url` | `GROK_RC_URL` | glance 的 agent WebSocket |
|
||
| `api_key` | `GROK_RC_API_KEY` | `glance apikey add` 打出来的那把 |
|
||
| `auto_start` | `GROK_RC_AUTO_START` | `true` 则会话一开始就连，不必敲 `/rc` |
|
||
| `replay_buffer` | — | 重连时回放的帧数，默认 2048 |
|
||
|
||
环境变量优先于配置文件；空字符串当作没设置。
|
||
|
||
### 4. 在 grok 里打开遥控
|
||
|
||
按 newgrok 的方式启动 TUI（一般是仓库里的 `make run`），进入一个会话后：
|
||
|
||
```
|
||
/rc
|
||
```
|
||
|
||
也可以 `/rc on`、`/rc off`、`/rc status`。终端里应出现已连接的系统提示，**TUI 本身继续能用**——这是整件事情的前提。
|
||
|
||
然后打开 glance 的网页（默认 `http://127.0.0.1:7717`），用验证器里的 6 位码登录。会话列表里出现刚连上的 grok 即可遥控。
|
||
|
||
## 用的时候会怎样
|
||
|
||
- 浏览器发的 prompt 会出现在终端里，两边一起流式输出。
|
||
- 需要批准的工具调用、`ask_user_question`、退出 plan mode：终端和浏览器同时弹出。谁先答谁算数，另一边的卡片自己收起来。
|
||
- 浏览器里的 **Stop** 是真正的 `session/cancel`，会话日志会记成 `client:glance`，不是模拟按 Esc。
|
||
- glance 挂了、网络断了、进程被杀，终端不受影响。`/rc` 桥在自己的任务里退避重连；遥控不能把本地会话一起带走。
|
||
|
||
同一把 API key 重连会顶掉上一条连接。两台 grok 共用一把 key 会互相抢槽位，每台各发一把。
|
||
|
||
## 命令
|
||
|
||
```
|
||
glance serve [flags] 跑服务器
|
||
glance apikey add <name> 给一台 grok 签发 key
|
||
glance apikey list
|
||
glance apikey rm <id-or-name>
|
||
glance bootstrap 再打一次 setup token（仅未登记时）
|
||
glance version
|
||
```
|
||
|
||
`serve` 的 flag：
|
||
|
||
| Flag | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `--addr` | `127.0.0.1:7717` | 监听地址。默认只绑回环，对外暴露必须是有意识的 |
|
||
| `--dir` | `~/.grok/glance` | 状态目录 |
|
||
| `--insecure-cookie` | 关 | 纯 HTTP localhost 用；非回环地址禁止 |
|
||
|
||
## 状态与恢复
|
||
|
||
持久化的只有无法重算的东西，写在 `~/.grok/glance/state.json`（`0600`）：TOTP 密钥、cookie 签名密钥、API key 的哈希。对话历史是每条 agent 内存里的环形缓冲（4096 帧），刷新页面会回放，**重启服务器不会**。
|
||
|
||
验证器丢了：删掉 `state.json`，重新登记。没有别的找回方式。这会同时作废所有 API key 和已签发的 cookie。`glance bootstrap` 在已经登记过后会拒绝再发 token。
|
||
|
||
`~/.grok/glance/` 里还有 `secret.key` 和 `hook.secret`，那是别的东西用的，不要动。
|
||
|
||
登录失败全局限流（5 分钟 8 次）。用过的 TOTP 步进会烧掉，同一个 30 秒窗口里登两次，第二次会失败——这是防重放，不是故障。
|
||
|
||
## 部署注意
|
||
|
||
glance 是带壳 agent 的遥控台。能通过鉴权的人可以批准任意工具调用。
|
||
|
||
- 默认只听 `127.0.0.1`。要暴露出去，放在终止 TLS 的反代后面。
|
||
- 自己不终止 TLS。公网上开 `--insecure-cookie` 等于把 session cookie 明文送出去。
|
||
- 没有多用户、没有角色、没有审计日志、没有按 key 分权限。
|
||
- Cookie 名是 `__Host-glance`：浏览器强制 `Secure` + `Path=/` + 不许设 `Domain`。改其中任何一项，浏览器会静默丢掉 cookie，看起来像登录坏了。
|
||
|
||
## 开发
|
||
|
||
```sh
|
||
make build # 前端，再编二进制 → bin/glance
|
||
make server # 只编 Go，沿用上次的前端
|
||
make web # 只编前端
|
||
make check # go vet + go test + tsc --noEmit
|
||
make dev # Go + Vite 热更新 → http://localhost:5173
|
||
```
|
||
|
||
`//go:embed` 在编译期解析，所以 **`go build` 打进去的永远是上次 `make web` 的产物**。改了 UI 却没出现在 `bin/glance` 里，就是这个原因。`vite build` 会清空 `web/dist/`，连 `.gitkeep` 一起删；`make web` / `make clean` 会补回来，裸跑 `npm run build` 不会。干净 clone 缺这个文件时，`go build` 会报一个难看的 embed 错误。
|
||
|
||
前端开发用 `make dev`：Vite 把 `/api` 代理到 Go。`__Host-glance` 是 `SameSite=Strict`，跨源发不出去。拿 Vite UI 直接打 Go 的 7717 端口，会表现为莫名其妙的鉴权失败。
|
||
|
||
不编 Rust、只调 UI 时，用 `cmd/fakeagent`：它按真桥一样拨 agent socket，演一段带真实 `session/request_permission` 的回合。
|
||
|
||
```sh
|
||
bin/glance serve --insecure-cookie &
|
||
make fakeagent KEY=glance_sk_…
|
||
```
|
||
|
||
这证明不了真桥说的是同一种方言。动过桥、交互路径或线格式之后，按 [ARCHITECTURE.md](ARCHITECTURE.md) 的设计说明和仓库里的端到端清单，对着一台真的 newgrok 跑一遍。
|
||
|
||
设计上为什么是这个形状——grok 当拨出方、角色对终端是反的、浏览器不直接讲 ACP、交互两边抢答——见 [ARCHITECTURE.md](ARCHITECTURE.md)。
|