不用下载 App，你的 AI 助手也能一键装进手机 —— LightClaw ACE PWA 体验指南

一、什么是 PWA？为什么 LightClaw ACE 要做成 App

PWA（Progressive Web App） 是一种让网页拥有原生应用体验的技术标准。简单来说：它让你的浏览器里的网页"升级"成了手机桌面上的独立 App——有自己的图标、启动画面、独立窗口，甚至在弱网环境下也能打开。

LightClaw 作为你的私有 AI 助手，使用场景天然适合"随时唤起、快速对话"。但每次都要打开浏览器 → 输入地址 → 等加载……体验断层太明显。

有了 PWA，LightClaw 就是你桌面上的一个 App：

一句话：零下载、零安装包、零应用商店审核——你的 AI 助手直接住进手机桌面。

二、30 秒安装：把 LightClaw 装进你的主屏幕

前提条件

• LightClaw 已部署并可访问（本地或云服务器均可）

• 推荐启用 HTTPS（lightclaw run --ssl），Chrome 在 HTTPS 下才会触发原生安装弹窗

Android / 桌面 Chrome

访问 LightClaw Dashboard 后，你会在页面顶部看到一个 「安装」按钮：

1. 点击「安装」

2. Chrome 弹出原生安装确认对话框 → 点击「安装」

3. 完成！LightClaw 图标出现在桌面 / 应用列表

💡 提示：如果没看到安装按钮，Chrome 可能还没触发 beforeinstallprompt 事件。只需正常使用几分钟，Chrome 会自动在地址栏显示安装图标。也可以点击地址栏右侧的 ⋮ 菜单 → 「安装 LightClaw」。

iPhone / iPad（iOS Safari）

iOS Safari 不支持 beforeinstallprompt，但 LightClaw 内置了专属的 iOS 引导流程——首次在 Safari 中访问时，底部会自动弹出引导卡片：

三步完成安装：

1. 点击底部工具栏的 分享按钮（方框 + 向上箭头）

2. 向下滚动，点击 「添加到主屏幕」

3. 点击右上角 「添加」

安装完成后，主屏幕上出现 LightClaw 图标，打开后是全屏独立窗口，没有 Safari 的地址栏和导航条，和原生 App 无异。

macOS / Windows 桌面端

Chrome / Edge 桌面浏览器同样支持 PWA 安装：

• Chrome：地址栏最右侧会出现一个 ⬇ 安装图标，或者通过菜单 → 「安装 LightClaw...」

• Edge：地址栏出现 ⊞ 应用安装图标

安装后，LightClaw 会以独立窗口运行，拥有自己的任务栏图标和窗口管理，Alt+Tab 可直接切换。

三、五大原生体验亮点

⚡ 亮点一：秒开加载

LightClaw 使用 Service Worker 将 SPA Shell（HTML/JS/CSS）和关键资源预缓存。打开 App 时无需等待网络，核心界面毫秒级呈现。

代码语言：TXT自动换行AI代码解释

首次访问：        网络 ──────────────────► 渲染 PWA 安装后再次打开：缓存 ──► 渲染（同时后台更新）

🎨 亮点二：沉浸式全屏

display: standalone 模式下，浏览器 UI（地址栏、标签栏、底部工具栏）全部消失。整个屏幕都是你的 AI 对话界面——特别适合手机端的沉浸式对话体验。

状态栏颜色还会跟随 LightClaw 的深色/浅色主题自动切换：

🌐 亮点三：离线回退

断网了？不会白屏。LightClaw 内置了品牌化的离线页面，显示「当前处于离线状态」并提供「重新连接」按钮，体验如同原生 App 的网络错误页。

🔄 亮点四：静默更新，手动确认

LightClaw 采用 Prompt 更新模式——新版本会在后台静默下载，但绝不会在你对话到一半时强制刷新。下载完成后，底部弹出优雅的更新提示：

✨ 新版本已就绪 [立即更新] ✕

你可以选择立即更新，或关闭提示稍后再说。对话安全零中断。

📱 亮点五：多设备同步体验

PWA 不限平台——同一个 LightClaw 服务，在你的手机、平板、笔记本、台式机上都能安装为独立 App。数据通过同一个后端实时同步，真正的一个 AI 助手，覆盖所有设备。

四、技术揭秘：LightClaw PWA 做了什么

本节面向开发者和技术爱好者，非技术读者可跳过。

4.1 构建配置

LightClaw 使用 vite-plugin-pwa + Workbox 构建 Service Worker：

展开 代码语言：TypeScript自动换行AI代码解释

// vite.config.ts VitePWA({   registerType: "prompt",       // 手动控制更新时机   injectRegister: false,        // SW 注册由代码手动控制   manifest: false,              // 使用静态 manifest.json   workbox: {     globPatterns: ["index.html", "assets/*.{js,css,woff2}"],     navigateFallback: "/index.html",     navigateFallbackDenylist: [/^/api/, /^/ws/],     clientsClaim: true,     skipWaiting: true,   }, })

4.2 五层缓存策略

4.3 安装提示的工程细节

Chrome 的 beforeinstallprompt 事件可能在 React 挂载之前就触发。LightClaw 通过模块加载时同步注册监听器解决了这个时序问题：

展开 代码语言：TypeScript自动换行AI代码解释

// main.tsx 第一行 import "./pwa-prompt";  // 同步捕获 beforeinstallprompt // pwa-prompt.ts window.addEventListener("beforeinstallprompt", (e) => {   e.preventDefault();   _deferredPrompt = e;  // 存入模块变量   _notify();            // 通知 React 组件 });

React 组件通过 useSyncExternalStore 订阅这个模块变量，零丢失、零延迟。

4.4 PWA 诊断工具

LightClaw 内置了一个 /pwa-debug 调试页面，10 项自动检查帮你排查安装问题：

检查项包括：HTTPS 状态、SW 注册状态、manifest.json 可访问性、beforeinstallprompt 捕获状态、standalone 模式检测等。支持一键复制诊断报告，方便反馈问题。

五、常见问题排查

Q1：Chrome 没有弹出安装提示

Chrome 触发安装提示需要满足以下条件：

• 站点通过 HTTPS 访问（或 localhost）

• 存在有效的 manifest.json（name、icons、start_url、display: standalone）

• 已注册 Service Worker 且正在控制页面

• 用户有一定的「参与度」（非首次访问）

解决方法：

1. 确保用 lightclaw run --ssl 启动

2. 正常使用几分钟，关闭后稍后重新访问

3. 访问 https://你的地址/pwa-debug 查看诊断结果

Q2：安装按钮出现过但消失了

用户曾点击过「不安装」，按钮会被隐藏。

解决方法：访问 /pwa-debug → 点击「清除"不安装"标记」→ 刷新页面。

Q3：iOS 上没有自动弹出安装引导

• 必须使用 Safari 浏览器（微信/支付宝内置浏览器不支持 PWA）

• 如果之前关闭过引导，会记录在 localStorage 中

• 访问 /pwa-debug → 清除标记后重新访问

Q4：已安装但打开还是浏览器标签页

检查是否从桌面图标启动（而非在浏览器中输入 URL）。只有从桌面图标启动才会以 standalone 模式运行。

Q5：更新后页面没有变化

LightClaw 使用 Prompt 模式更新。如果底部出现了「新版本已就绪」banner，点击「立即更新」即可。如果没有出现，可以手动清除浏览器缓存或在 DevTools → Application → Service Workers 中点击 Update。

快速参考卡