轻量控制台 Archiloss/dsh-lite

dsh-lite · 给慢链路做的轻量控制台

官方控制台在手机 + 中继链路上要几十秒才出一个列表；这个版本首屏 27 KB（gzip 11 KB）、列表 16 KB、单次往返 1 个请求。
代价是只做四件事：看会话列表、读全文对话、发消息、新建会话。

它解决的是一个具体问题

前提：智能体跑在常开的 Mac 上，人在外面用手机看/发消息，中间走的是内网穿透或自建中继（Tailscale DERP、frp、SSH 隧道都算）。

这种链路的典型数字：RTT 0.4~3s、带宽 5~15 KB/s。在这个条件下，完整控制台打不开，原因不是「网页大」：

| 卡点 | 实测 |
| 会话列表接口一次返回全部会话 | 456 个会话 = 1.35 MB，本地跑 0.4~1.1s，中继上几十秒 |
| 一次开屏几十个 API 调用 | 每个一次往返，0.4~3s，串起来就是分钟级 |
| 中继是 TCP 套 TCP | 堆并发不加速，只会一起变慢 |
| 前端整包 | HTML + JS ≈ 0.9 MB（gzip 0.53 MB），弱网首屏解析都费劲 |

所以这份实现做的事只有一句：把重活挪到靠近后端的一侧，手机只收「这一屏要的信息」。

| 指标 | 官方控制台 | dsh-lite |
| 首屏 HTML/JS | ≈ 0.9 MB | 27 KB（gzip 11 KB；单文件、零外部请求） |
| 会话列表（显示 60 条） | 1.35 MB（官方一次取全量，456 个会话） | ≈ 16 KB（实测 15.7 KB） |
| 单条会话详情 | 5~50 KB，正文截断到 120 字 | ≤ 24 KB（单轮超限会截断并标注），全文（按轮次分页） |
| 一次开屏请求数 | 几十个 | 2 个（列表 + 链路徽章） |

30 秒看到界面（不需要装任何东西）

python3 demo.py # 假数据后端，零依赖
打开 http://127.0.0.1:8702/lite/

demo.py 提供与真后端同名的接口，数据全是假的（假会话、假回复、假审批），用来看界面 / 截图 / 讲方案。
真接 DSH 用 lite_server.py。

真接上去（3 步）

前置：本机能跑 DSH 的 Web 服务，且你能拿到一个能过鉴权的 RPC 入口（下称 DSH_BASE）。
如果网关需要 Cookie，常见做法是在本地起一个改写 Header / 注入 Cookie 的回环代理（本项目不处理凭据）。

1) 起轻量服务
DSH_BASE=http://127.0.0.1:19389 LITE_PORT=8702 python3 lite_server.py

2) 自测（本机）
curl -s localhost:8702/api/sessions?limit=3

3) 挂到你的远程入口（示例：tailscale serve） tailscale serve --bg --set-path /lite http://127.0.0.1:8702

然后在手机上打开 https://<你的域名>/lite/。

⚠️ 路径必须以 /lite/ 结尾。页面里用的是相对路径，/lite（少一条斜杠）会把请求发到上一级去；服务端会把 /lite 302 到 /lite/，前端也按 pathname 目录拼 BASE，两头都兜住了。

界面能力

- 会话列表：标题 / 轮数 / 是否运行中 / 最后一轮摘要（60 字），一次请求看完
- 全文对话：从本机 transcript 读完整正文（不是 API 的 120 字预览），点「看更早」往后翻是累加
- 发消息：最多 3 次尝试（网络类错误才重试）、按 requestId 去重（重试不会发两遍，但你真的想再发一遍同样的内容不会被吞）、失败不清空输入框
- 新建会话：建在正确的 workspace 里，建完直接进、光标落输入框
- 速览模式：把每轮截到 200 字，慢链路兜底
- 待审批提示：只提示「有 N 项在等你批准」并给出官方入口（批准本身必须回官方控制台，见限制）
- 链路徽章：直连 / 中继、已传多少 KB，一眼判断「现在快不快」

设计要点（可直接搬到别的「弱网后台」上）

1. 服务端聚合，客户端只渲染一屏。列表在服务端裁剪 + 排序 + 附带摘要；前端不再二次请求。
2. 真源选磁盘，不选 API。会话正文从本机 transcript（zstd JSONL）读，API 的预览字段只做兜底。
3. 路由全部后缀匹配。挂 /lite、挂 /、带不带前缀都能用（很多反向代理会剥前缀）。
4. 列表页与会话页的滚动规则必须分开：列表永远回顶；会话页贴最新一轮。两者共用同一份 scrollY 会导致「一返回就看到最老的会话」。
5. 「落在最新一条」要扛住异步布局：徽章晚到、输入框长高、字体度量都会把刚贴底的视图顶偏几十到一百多像素。
做法不是滚一次，而是给一个短时间窗口持续纠偏（用户一滚就停），只在对话页生效。
6. 失败要留痕：所有上游错误写一行日志（方法 / 错误码 / 说明），手机上的 toast 只说人话。
7. 界面刷新绝不能冒充业务失败：finally 里独立 try，否则「发送成功但刷新报错」会被显示成「发送失败」，诱导用户重复发。
8. 缓存键要包含维度：列表缓存存全量、返回时切 limit。把「已切好的结果」塞进缓存，会让任何一次小 limit 请求污染所有人一分钟。
9. 页脚显示构建版本：远程排障第一问是「你看到的是哪一版」，比「你刷新了吗」有效。

细节见 docs/why-and-how.md，19 条踩过的坑逐条列在 docs/pitfalls.md。

配置

| 环境变量 | 默认 | 说明 |
| LITE_PORT | 8702 | 监听端口（也可用第一个命令行参数） |
| DSH_BASE | http://127.0.0.1:19389 | 上游 RPC 网关地址 |
| DSH_HOME | ~/.dsh | DSH 数据目录（读 storages/workspace.json、sessions/*） |
| LITE_LOG | <脚本目录>/lite.err.log | 诊断日志 |
| LITE_TZ | 本机时区 | 发送消息时带的 clientTimeZone |
| TS_BIN | tailscale | 链路徽章用；找不到就自动降级为「未知」 |
| LITE_HOSTS | 空（不校验） | 允许的 Host（逗号分隔）。挂到域名后面时建议设上，防 DNS rebinding 读历史 |

只监听 127.0.0.1（不对外暴露），对外由你的中继/反向代理负责鉴权。

接口速查（逆向所得，非官方，随时可能变）

所有请求 POST /api/<method>，信封：

{"type":"client-request","rpcId":"<uuid>","method":"session/list","payload":{"args":{"_request":{}}}}

| 方法 | args 形状 | 用途 |
| session/list | {"_request":{}} | 全部会话（很大，服务端缓存 60s） |
| session/projections | {"request":{"sessionId":"session-…"}} | 单会话投影（turnOutline 只有 120 字预览） |
| session/prompt | {"request":{requestId,sessionId,mode:"queue",content:[{type:"text",text}],clientTimeZone}} | 发消息 |
| session/create | {"request":{"workspaceId":"<uuid>","sessionId":"session-<uuid4>"}} | 新建会话 |
| workspace/archiveSession | {"request":{"sessionId":"…","stopActivity":false}} | 归档（≠删除，可逆） |

字段集是严格 schema：多一个字段报 body is not JSON（别被这个报错误导，其实是字段名不对）。详见 docs/protocol.md。

自测

python3 lite_e2e.py http://127.0.0.1:8702/lite/ # 51 项（真实后端）：真机尺寸/溢出/交互/失败路径/归档
python3 lite_e2e.py --no-send # 跳过"真发一轮模型"
python3 lite_e2e.py http://127.0.0.1:8702/lite/ --demo # 48 项（demo 后端，不需要 DSH）

E2E 用无头 Chrome + CDP 驱动真实页面，覆盖：390×844 无横向溢出、无 JS 异常、列表/详情/翻页累加、新建会话（连点只建 1 个、cwd 正确、发第一句真收到回复）、发送失败给人话且不丢字、界面刷新报错不冒充失败、返回列表回顶、测试会话自动归档不污染真实列表。

无头 Chrome 在部分沙箱环境里会崩（sandbox initialization failed），要放宽文件沙箱再跑。

限制（先说清，别期待它做全能）

- 只做四件事：列表、读全文、发消息、新建。文件浏览、终端、插件、审批面板都没有。
- 审批无法在 lite 里点：审批通道走 WebSocket（/api/remote.mux），本项目只用 REST；遇到审批只能回官方控制台。
- 强绑定 DSH：接口形状、transcript 格式、workspace 账本都是 DSH 的。方法论可以搬，代码要改。
- 依赖本机能读到 $DSH_HOME：会话正文来自磁盘，不是远端服务。
- 不处理鉴权：假定 DSH_BASE 已经是一个「能过鉴权的入口」。
- 安全边界：写接口只接受 POST，sessionId 做格式校验（防目录穿越），可选 LITE_HOSTS 白名单防 DNS rebinding。
但它自己没有登录态——暴露到公网前请在反代层加鉴权。

目录

lite_server.py 轻量服务（聚合/裁剪/转发/去重/日志） lite.html 单文件前端（零外部依赖、深色浅色自适应、手机优先） transcript.py 读本机会话记录（zstd JSONL → 按轮分组，滤掉注入的系统消息） demo.py 假数据后端（看界面/截图用） lite_e2e.py CDP E2E（51 项） tools/shot.py 手机尺寸截图 deploy/ launchd 与反向代理模板 docs/ 为什么这么做 / 踩坑清单 / 接口速查 README.en.md 英文版（双语仓库：两份内容必须同步改）

License

MIT © 2026 Archiloss