Pocket Term v2（pocket-term-2）

pocket-term-2 是一个自托管的手机端聊天式客户端：把 herdr（agent 会话管理器）里运行的 AI 编程 agent（如 Claude Code）会话变成手机上的会话列表和消息气泡，让开发者不用打开整屏 Web 终端，也能在手机上查看进度、回消息、收通知。

A self-hosted, mobile-first chat UI for your herdr AI coding-agent fleet (e.g. Claude Code) — browse panes as chat bubbles, reply safely, and get optional Web Push alerts from your phone.

• 给谁：在电脑/服务器上用 herdr 跑多个 AI 编程 agent、想在手机上盯进度的开发者。
• 解决什么：手机上看整屏终端难用，也不知道哪个 agent 在等你回复。
• 怎么做到：本机 Node bridge 读取 herdr Unix socket 和 Claude Code JSONL，手机浏览器打开 SPA。

pocket-term-2 是 pocket-term 产品线的第二个产品版本：把 herdr agent 舰队做成适合手机使用的会话客户端。你可以在手机上浏览会话列表、进入 pane 查看消息气泡、查看状态和未读提示，而不必打开一整屏共享终端。

本版本支持页内通知、可选 Web Push、受保护的消息发送、图片附件、Markdown 附件预览和 HTML 附件沙箱预览。

本 README 是中文主文档。命令、API 路径、环境变量、协议字段、技术名词和许可证名称保留原文，便于直接复制和核对。

快速开始

Agent 请先阅读 SKILL.md 并按其中流程执行。部署者只需要决定端口、是否配置公网入口，以及是否启用 Web Push。

前置条件：

• Linux（systemd 可选）
• Node.js >= 20
• 已安装并运行 herdr（Unix socket 默认 $HOME/.config/herdr/herdr.sock）
• 可选：Claude Code（启用 Tier A 消息气泡）

git clone -b v2 https://github.com/ythx-101/pocket-term.git pocket-term-2 && cd pocket-term-2

路径 A：systemd 安装

bash scripts/install.sh --port 7690

路径 B：无 systemd，直接运行

npm ci && node server.js

然后打开 http://127.0.0.1:7690/herd/。

bridge 只监听 127.0.0.1。手机访问需要经过你自己的反向代理或隧道（例如 Cloudflare Tunnel + Access，hostname 用 term.example.com 占位），示例见下方「cloudflared ingress 示例」和 docs/ops.md。

冒烟检查（PT2_PANE 请设为你自己的 pane id，脚本默认值是作者环境的 id）：

PT2_PANE=<你的 pane id> PT2_BASE=http://127.0.0.1:7690 ./scripts/smoke.sh

机器可验证的安装、检查和卸载步骤见 AGENTS.md。

功能概览

• 会话与消息：查看 herdr 会话、Tier A transcript 气泡、Tier B 屏幕流、SSE 实时更新和未读状态。
• 受保护发送：同源校验、body 限制、按 pane 限流、pane 存在性检查，以及 PT2_READONLY 紧急只读开关。
• 附件：图片上传/预览；Markdown 仅以安全 DOM 节点渲染；HTML 使用白名单清洗、空 sandbox 和独立预览窗口。
• 通知：可选 Web Push；未配置 Push 时，页面通知和会话徽标仍然可用。

使用示例

1. 打开 /herd/。
2. 在会话列表中查看各 pane 的 工作中 / 等你回复 状态与未读提示。
3. 点进 pane：有 Claude Code transcript 时显示 Tier A 气泡，否则显示 Tier B 屏幕流。
4. 发送消息（同源校验 + 按 pane 限流；设置 PT2_READONLY=1 时禁用发送）。
5. 发送图片、Markdown 或 HTML 附件并预览。
6. 可选：配置并开启 Web Push 通知。

curl -s http://127.0.0.1:7690/herd/api/state | head -c 200

适用场景与同类方案对比

适合：

• 用 herdr 管理多个 AI 编程 agent 的开发者。
• 想在手机上查看进度、回复简短消息。
• 愿意自行配置反向代理/隧道和访问控制。

不适合：

• 不使用 herdr 的场景。
• 需要完整终端操作。
• 需要公网直连、但不想配置反向代理。

架构

浏览器 ──(CF Access)── 反向代理 ──► 127.0.0.1:7690  pocket-term-2 bridge
                                             │
                                             ├─ GET  /herd/            SPA
                                             ├─ GET  /herd/api/state
                                             ├─ GET  /herd/api/pane/:id/messages
                                             ├─ GET  /herd/api/events          (SSE)
                                             ├─ POST /herd/api/seen/:id
                                             ├─ POST /herd/api/upload?target=chat
                                             └─ GET  /herd/api/file?path=
                                             │
                                             ▼
                                        herdr.sock
                                             │
                                             └─ ~/.claude/projects/**.jsonl  (可选 Tier A)

• Tier A：Claude transcript JSONL，在存在 agent_session 时提供真实 user/agent/tool 气泡。
• Tier B：pane.read 屏幕差异，作为任意 pane 的 monospace 流式回退。

HTTP 接口

默认监听地址：PT2_HOST=127.0.0.1、PT2_PORT=7690，可通过环境变量覆盖。

环境变量

本地运行

要求：Node.js >= 20，以及正在运行且 Unix socket 可读的 herdr server。

cd /path/to/pocket-term-2
npm ci
# 可选：
# export PT2_HOST=127.0.0.1 PT2_PORT=7690
# export PT2_HERDR_SOCK=$HOME/.config/herdr/herdr.sock
# export PT2_PROJECTS_ROOT=$HOME/.claude/projects
node server.js
# 打开 http://127.0.0.1:7690/herd/

对运行中的实例执行冒烟检查：

PT2_BASE=http://127.0.0.1:7690 ./scripts/smoke.sh

测试

运行时使用锁定的 web-push 依赖，测试使用 Node 内置 test runner：

npm test
# 或
node --test test/*.test.mjs

默认跳过需要真实 herdr 的 live 测试。启用方式：PT2_LIVE_TESTS=1 PT2_TEST_PANE=<pane_id> npm test（需要 herdr 正在运行）。

可选 Web Push

在部署环境设置 PT2_VAPID_SUBJECT、PT2_VAPID_PUBLIC_KEY 和 PT2_VAPID_PRIVATE_KEY，也可以使用 scripts/install.sh --with-push。使用 scripts/gen-vapid.sh 生成密钥；不要把密钥提交到 Git。浏览器订阅只写入被忽略的 state/push-subscriptions.json。

三项变量不完整时，Web Push 返回 push_not_configured，页面原有 banner/徽标回退逻辑继续工作。Service Worker 位于 /herd/sw.js，作用域为 /herd/，通知直接使用加密 Push payload，不拉取受 Access 保护的 API。

触及 herdr 的 live tests 只使用只读方法：ping、session.snapshot、pane.read 和 events.*。

systemd

Unit 模板是 systemd/pocket-term-2.service.tmpl，包含 __WORKDIR__、__HOME__、__NODE_PATH__、__NODE_BIN__、__USER__、__GROUP__ 等占位符。优先使用：

bash scripts/install.sh --port 7690

部署和回滚流程见 docs/ops.md。

cloudflared ingress 示例

不要提交私有 hostname。下面只是占位模式：

ingress:
  - hostname: term.example.com
    path: ^/herd(/.*)?$
    service: http://127.0.0.1:7690
  - hostname: term.example.com
    path: ^/up$
    service: http://127.0.0.1:7699
  - hostname: term.example.com
    service: http://127.0.0.1:7681
  - service: http_status:404

修改配置后先执行配置校验，再按运维 runbook 重启 tunnel，并检查 /herd/api/state、既有 / 和 /up。

常见问题（FAQ）

pocket-term-2 是什么？和 pocket-term v1（ttyd Web 终端）有什么关系？

v2 是 pocket-term 产品线的新版本，定位从网页终端转为 agent 会话聊天客户端（a mobile chat client for AI coding agents）。v1 不在本分支。

必须用 herdr 吗？能直接连 tmux / 普通 SSH 吗？

必须有 herdr：bridge 通过 herdr 的 Unix socket 读取会话。本项目不直接连接 tmux 或 SSH。

不用 Claude Code 能用吗？

能。没有 Claude Code transcript 时走 Tier B 屏幕流；Tier A 消息气泡需要 Claude Code 的 JSONL。

怎么在手机上访问？安全吗？（mobile access）

bridge 默认只监听 127.0.0.1。手机访问请经反向代理并加访问控制（如 Cloudflare Access）。发送接口有同源校验、限流和只读熔断。

怎么让它只读、防止误发？

设置 PT2_READONLY=1（或 true），发送被禁用。

不配置 Web Push 会怎样？

Web Push 接口返回 push_not_configured，页内通知和会话徽标照常工作。

上传的文件存在哪？

PT2_CHAT_UPLOAD_DIR，默认 /srv/term-uploads。上传有扩展名、大小和路径穿越限制。

如何卸载？

见 AGENTS.md 的「Uninstall」一节。

English summary

Pocket Term v2 (pocket-term-2) is a self-hosted, mobile-first chat UI for AI coding agents (e.g. Claude Code) running in herdr. Requirements: Linux, Node.js >= 20, a running herdr server.

git clone -b v2 https://github.com/ythx-101/pocket-term.git pocket-term-2 && cd pocket-term-2
bash scripts/install.sh --port 7690   # or: npm ci && node server.js
# open http://127.0.0.1:7690/herd/

Features: session list with unread state, chat bubbles (Tier A) and screen stream (Tier B), guarded send with PT2_READONLY kill switch, image/Markdown/HTML attachments, optional Web Push. License: MIT.

许可证

本项目使用 MIT License，详见 LICENSE。

本项目属于 pocket-term 开源产品线（pocket terminal → pocket agent fleet chat）。代码和文档按可发布标准维护，不写入私有域名、token 或本机运行时密钥。