Skip to content

Commit d13642e

Browse files
committed
docs(readme): merge touch-optimized content into the mobile section
- One compact Mobile-Optimized Web UI section: the two current screenshots (mobile-session-keyboard, mobile-toolbar-enter) side by side, comparison table, condensed feature bullets, then QR auth - Drop the outdated black-background phone screenshots (mobile-landing-qr.png, mobile-session-active.png) - Same restructure in README.zh-CN.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 3cff98f commit d13642e

4 files changed

Lines changed: 30 additions & 54 deletions

File tree

README.md

Lines changed: 15 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -230,14 +230,12 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
230230

231231
<table>
232232
<tr>
233-
<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="Mobile — landing page with QR auth" width="260"></td>
234-
<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="260"></td>
235-
<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="Mobile — active agent session" width="260"></td>
233+
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="300"></td>
234+
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="440"></td>
236235
</tr>
237236
<tr>
238-
<td align="center"><em>Landing page with QR auth</em></td>
239237
<td align="center"><em>Answering prompts by touch</em></td>
240-
<td align="center"><em>Agent working in real-time</em></td>
238+
<td align="center"><em>Accessory bar + dedicated Enter button</em></td>
241239
</tr>
242240
</table>
243241

@@ -256,28 +254,10 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
256254
<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
257255
</table>
258256

259-
### Secure QR Code Authentication
260-
261-
Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
262-
263-
Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
264-
265-
The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
266-
267-
### Touch-Optimized Interface
268-
269-
<p align="center">
270-
<img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="560">
271-
</p>
272-
273-
- **Keyboard accessory bar**`/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard. Destructive commands (`/clear`, `/compact`) require a double-press to confirm — first tap arms the button, second tap executes — so you never fire one by accident on a bumpy commute
274-
- **Dedicated Enter button** — submitting is a constant need on a touch keyboard, so the phone toolbar gives it a button of its own. It replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded. Starting a shell moves into the Run dropdown (`Terminal / Shell`), which is the rarer action
275-
- **Swipe navigation** — left/right on the terminal to switch sessions (80px threshold, 300ms)
276-
- **Smart keyboard handling** — toolbar and terminal shift up when keyboard opens (uses `visualViewport` API with 100px threshold for iOS address bar drift)
277-
- **Safe area support** — respects iPhone notch and home indicator via `env(safe-area-inset-*)`
278-
- **44px touch targets** — all buttons meet iOS Human Interface Guidelines minimum sizes
279-
- **Bottom sheet case picker** — slide-up modal replaces the desktop dropdown
280-
- **Native momentum scrolling**`-webkit-overflow-scrolling: touch` for buttery scroll
257+
- **Keyboard accessory bar**`/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
258+
- **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
259+
- **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
260+
- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
281261

282262
```bash
283263
codeman web --https
@@ -286,6 +266,14 @@ codeman web --https
286266

287267
> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended) — it provides a private network so you can access `http://<tailscale-ip>:3000` from your phone without TLS certificates.
288268
269+
### Secure QR Code Authentication
270+
271+
Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
272+
273+
Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
274+
275+
The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
276+
289277
---
290278

291279
## Live Agent Visualization

README.zh-CN.md

Lines changed: 15 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -220,14 +220,12 @@ codeman web -H 0.0.0.0 # 绑定局域网 —— 必须设置 CODEMAN_
220220

221221
<table>
222222
<tr>
223-
<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
224-
<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="260"></td>
225-
<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
223+
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="300"></td>
224+
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏:配件栏的 /init、/clear、剪贴板与 Esc,下方是 Run、案例、停止、Enter、语音与设置控件" width="440"></td>
226225
</tr>
227226
<tr>
228-
<td align="center"><em>带二维码认证的登录页</em></td>
229227
<td align="center"><em>触控回答提示</em></td>
230-
<td align="center"><em>智能体实时工作中</em></td>
228+
<td align="center"><em>配件栏 + 独立 Enter 按钮</em></td>
231229
</tr>
232230
</table>
233231

@@ -246,28 +244,10 @@ codeman web -H 0.0.0.0 # 绑定局域网 —— 必须设置 CODEMAN_
246244
<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
247245
</table>
248246

249-
### 安全的二维码认证
250-
251-
在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码,手机即刻完成认证。
252-
253-
每个二维码编码的是一个包含 6 字符短码的 URL,该短码在服务端映射到一个 256 位密钥(`crypto.randomBytes(32)`)。令牌每 **60 秒**自动轮换,**首次扫描即原子性消费**(重放永远失败),并采用**基于哈希的 `Map.get()` 查找**,不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
254-
255-
该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)(USENIX Security 2025,该研究发现 Top-100 网站中有 47 个存在漏洞)所指出的全部 6 个关键二维码认证缺陷:强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知(QRLjacking 检测),以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制(按 IP + 全局)使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见:[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
256-
257-
### 触控优化界面
258-
259-
<p align="center">
260-
<img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏:配件栏的 /init、/clear、剪贴板与 Esc,下方是 Run、案例、停止、Enter、语音与设置控件" width="560">
261-
</p>
262-
263-
- **键盘配件栏** —— 在虚拟键盘上方提供 `/init``/clear``/compact` 快捷按钮。破坏性命令(`/clear``/compact`)需双击确认 —— 第一次点击「上膛」,第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
264-
- **独立的 Enter 按钮** —— 在触控键盘上提交是高频操作,因此手机工具栏为它单独设了一个按钮。它会以按键的方式回放,从而先冲刷本地回显缓冲的文本,不会让内容滞留在屏幕上。启动 Shell 这类低频操作则移入 Run 下拉菜单(`Terminal / Shell`
265-
- **滑动导航** —— 在终端上左右滑动切换会话(阈值 80px,300ms)
266-
- **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移(使用 `visualViewport` API,并对 iOS 地址栏漂移设置 100px 阈值)
267-
- **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
268-
- **44px 触控目标** —— 所有按钮均满足 iOS 人机界面指南的最小尺寸
269-
- **底部抽屉式 case 选择器** —— 用上滑模态框替代桌面端下拉菜单
270-
- **原生惯性滚动** —— `-webkit-overflow-scrolling: touch`,丝滑流畅
247+
- **键盘配件栏** —— 在虚拟键盘上方提供 `/init``/clear``/compact` 快捷按钮;破坏性命令需双击确认,绝不误触
248+
- **独立的 Enter 按钮** —— 以按键方式回放,先冲刷本地回显缓冲的文本,不会让内容滞留在屏幕上
249+
- **滑动导航与智能键盘处理** —— 左右滑动切换会话;键盘弹出时工具栏与终端整体上移(`visualViewport` API)
250+
- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
271251

272252
```bash
273253
codeman web --https
@@ -276,6 +256,14 @@ codeman web --https
276256

277257
> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`,或使用 [Tailscale](https://tailscale.com/)(推荐)—— 它提供私有网络,让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`
278258
259+
### 安全的二维码认证
260+
261+
在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码,手机即刻完成认证。
262+
263+
每个二维码编码的是一个包含 6 字符短码的 URL,该短码在服务端映射到一个 256 位密钥(`crypto.randomBytes(32)`)。令牌每 **60 秒**自动轮换,**首次扫描即原子性消费**(重放永远失败),并采用**基于哈希的 `Map.get()` 查找**,不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
264+
265+
该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)(USENIX Security 2025,该研究发现 Top-100 网站中有 47 个存在漏洞)所指出的全部 6 个关键二维码认证缺陷:强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知(QRLjacking 检测),以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制(按 IP + 全局)使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见:[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
266+
279267
---
280268

281269
## 实时智能体可视化
-894 KB
Binary file not shown.
-576 KB
Binary file not shown.

0 commit comments

Comments
 (0)