dsh-bridge-gateway 0.2.2 → 0.3.0

package/docs/qq-usage.md

@@ -30,11 +30,11 @@ QQ Bot 使用 WebSocket 接收事件，需要配置 Intents（事件订阅）：
 - **GROUP_AT_MESSAGE_CREATE**（群聊 @提及）：`1 << 25`（与私聊同属 `GROUP_AND_C2C_EVENT`）
 - **INTERACTION_CREATE**（互动事件）：`1 << 26`
 
-> dsh-bridge 默认已开启以上三个 intents，支持私聊、群聊和按钮交互，无需额外配置。
+> dsh-bridge-gateway 默认已开启以上三个 intents，支持私聊、群聊和按钮交互，无需额外配置。
 
 ## 快速开始
 
-### 1. 启动 dsh-bridge
+### 1. 启动 dsh-bridge-gateway
 
 ```bash
 # 安装最新版本
@@ -54,7 +54,7 @@ dsh web
 - **ClientSecret**：应用的 ClientSecret（密钥不会回传浏览器，留空表示沿用已保存密钥）
 
 点击"保存并连接"，系统会自动：
-1. 保存凭证到 `$DSH_HOME/dsh-bridge/config.json`
+1. 保存凭证到 `$DSH_HOME/dsh-bridge-gateway/config.json`
 2. 获取 Access Token（自动刷新，TTL 7200s）
 3. 连接 WebSocket Gateway
 4. 开始接收消息事件
@@ -117,7 +117,7 @@ AI 生成过程中，QQ 会显示机器人的"正在输入"状态：
 
 ### 6. 指令面板与自定义菜单（v2.2.0）
 
-连接成功后，dsh-bridge 会自动为你的机器人配置：
+连接成功后，dsh-bridge-gateway 会自动为你的机器人配置：
 
 > **⚠️ 重要提示**（2026-08-20 确认）：
 > - **自定义菜单、指令面板、消息按钮是 2026-08-12 刚上线的新功能**（[官方变更记录](https://bot.qq.com/wiki/develop/api-v2/changelog.html)）
@@ -239,7 +239,7 @@ await gateway.sendMarkdown(
 
 按钮类型（`action.type`）：
 - `0` — 跳转按钮（`action.data` 为 URL）
-- `1` — 回调按钮（触发 `INTERACTION_CREATE` 事件）✅ dsh-bridge 快捷按钮使用此类型
+- `1` — 回调按钮（触发 `INTERACTION_CREATE` 事件）✅ dsh-bridge-gateway 快捷按钮使用此类型
 - `2` — 指令按钮（用户点击后自动发送 `action.data` 作为消息）
 
 按钮样式（`render_data.style`）：
@@ -290,7 +290,7 @@ await gateway.sendMedia(
 
 ### Token 自动刷新
 
-Access Token 有效期为 7200 秒（2 小时），dsh-bridge 会在过期前 5 分钟自动刷新，无需手动处理。
+Access Token 有效期为 7200 秒（2 小时），dsh-bridge-gateway 会在过期前 5 分钟自动刷新，无需手动处理。
 
 ### 消息去重
 

package/docs/wechat-usage.md

@@ -1,6 +1,6 @@
 # 微信 Bot 使用说明
 
-> dsh-bridge 的微信 Bot（ClawBot / iLink）让你**直接在微信里**与你的 DeepSeek Harness agent 对话、控制和审批——无需公网、无需隧道，走腾讯官方 iLink Bot API。
+> dsh-bridge-gateway 的微信 Bot（ClawBot / iLink）让你**直接在微信里**与你的 DeepSeek Harness agent 对话、控制和审批——无需公网、无需隧道，走腾讯官方 iLink Bot API。
 
 扫码登录微信个人号后，发消息就能驱动 agent；`/` 开头的命令管理会话、切换工作区、审批权限。会话与工作区信息跨重启持久化，不会丢。
 

package/lib/auth/brand-assets.js

@@ -0,0 +1,131 @@
+// lib/auth/brand-assets.js
+// ---------------------------------------------------------------------------
+// DSH 官方品牌资产（唯一来源，供远程登录页与 PWA 图标共用）
+// ---------------------------------------------------------------------------
+// 为什么单独成模块：登录页是服务端模板字符串，PWA 图标是另一处常量，两边都要
+// 用同一枚鲸鱼标。收敛到这里之后，DSH 升级导致资产变化时只需改一处。
+//
+// 资产出处（本机 DSH 安装包，均为 MIT 许可）：
+//   FISH_LOGO_PATH / FISH_LOGO_VIEWBOX
+//     @deepseek-ai/dsh-client-ui-primitives  lib/index.js  (~line 5394)
+//   HERO_SWIM_UP_PATH / HERO_SWIM_DOWN_PATH
+//     @deepseek-ai/dsh-client-ui-conversation lib/client.js (~line 16127)
+//     —— 会话首页 Hero 的鲸鱼"游动"关键帧，与主标同 viewBox
+//   DSH favicon（50×50 鲸鱼，仅作形态核对参考，未直接内联）
+//     @deepseek-ai/dsh-web-frontend  dist/favicon.svg
+//
+// 重新提取方式（DSH 升级后核对）：
+//   node -e "const p=require.resolve('@deepseek-ai/dsh-client-ui-primitives/lib/index.js'); ..."
+//   或在安装目录直接 grep：
+//     grep -o 'const FISH_LOGO_PATH = "[^"]*"' <primitives>/lib/index.js
+//     grep -o 'const HERO_SWIM_UP_PATH = "[^"]*"'   <conversation>/lib/client.js
+//
+// 提取时的一致性校验（sha256 前 16 位，防止静默替换）：
+//   FISH_LOGO_PATH      5bee701f39229e6d
+//   HERO_SWIM_UP_PATH   714b02df1872534c
+//   HERO_SWIM_DOWN_PATH b4b0b82c16ae0314
+//
+// 体积实测：三帧合计 9042 字符 / gzip 3187 字节。登录页内联可接受。
+// 商标提示：鲸鱼标与字标是 DeepSeek 商标。代码 MIT 可复用，但本插件是第三方
+// 网关，登录页须避免造成"官方产品"的印象（见 login-template.js 页脚声明）。
+// ---------------------------------------------------------------------------
+
+/** 鲸鱼标原生 viewBox（宽高比 23.16 : 17.04）。 */
+export const FISH_LOGO_VIEWBOX = { width: 23.16, height: 17.04 };
+
+/** 鲸鱼剪影路径（静态帧）。 */
+export const FISH_LOGO_PATH = 'M22.9168 1.43018C22.6713 1.31018 22.5658 1.53918 22.4223 1.65519C22.3733 1.69269 22.3318 1.74169 22.2903 1.78669C21.9317 2.1697 21.5127 2.42121 20.9657 2.39121C20.1657 2.34621 19.4827 2.59771 18.8787 3.20973C18.7502 2.45521 18.3236 2.0047 17.6746 1.71569C17.3351 1.56568 16.9916 1.41518 16.7536 1.08867C16.5876 0.856163 16.5421 0.597155 16.4591 0.341647C16.4061 0.187643 16.3536 0.0301382 16.1761 0.00363739C15.9836 -0.0263635 15.9081 0.135141 15.8326 0.270145C15.5306 0.822162 15.4136 1.43018 15.4251 2.0462C15.4516 3.43174 16.0366 4.53527 17.1991 5.3203C17.3311 5.4103 17.3651 5.5003 17.3236 5.63181C17.2441 5.90231 17.1501 6.16482 17.0671 6.43533C17.0141 6.60784 16.9351 6.64584 16.7501 6.57033C16.1121 6.30383 15.5611 5.90931 15.074 5.4328C14.2475 4.63328 13.5 3.75075 12.568 3.05973C12.349 2.89822 12.13 2.74822 11.9034 2.60522C10.9524 1.68169 12.028 0.923165 12.277 0.833162C12.5375 0.739159 12.3675 0.41615 11.5259 0.42015C10.6844 0.42365 9.91439 0.705658 8.93286 1.08117C8.78935 1.13767 8.63835 1.17867 8.48384 1.21267C7.59332 1.04367 6.66829 1.00617 5.70226 1.11517C3.88321 1.31768 2.43016 2.1777 1.36213 3.64575C0.0790928 5.4103 -0.222916 7.41536 0.146595 9.50642C0.535106 11.7105 1.66014 13.535 3.38869 14.9616C5.18125 16.4406 7.24581 17.1657 9.60138 17.0266C11.0319 16.9441 12.6245 16.7526 14.421 15.2321C14.874 15.4576 15.3496 15.5476 16.1381 15.6151C16.7456 15.6716 17.3306 15.5851 17.7836 15.4911C18.4931 15.3411 18.4441 14.6841 18.1876 14.5636C16.1081 13.595 16.5646 13.9891 16.1496 13.67C17.2061 12.42 18.8202 10.1979 19.3182 7.17235C19.3672 6.83834 19.4297 6.36783 19.4222 6.09732C19.4182 5.93231 19.4562 5.86831 19.6447 5.84931C20.1657 5.78931 20.6712 5.64681 21.1357 5.3913C22.4833 4.65528 23.0268 3.44624 23.1548 1.9972C23.1738 1.77569 23.1508 1.54668 22.9168 1.43018ZM11.1749 14.4736C9.15936 12.889 8.18184 12.3675 7.77832 12.39C7.40081 12.4125 7.46881 12.8445 7.55182 13.126C7.63882 13.404 7.75182 13.5955 7.91033 13.8396C8.01983 14.0011 8.09533 14.2411 7.80083 14.4216C7.15181 14.8231 6.02327 14.2866 5.97027 14.2601C4.65673 13.4865 3.5587 12.4655 2.78467 11.069C2.03715 9.72493 1.60314 8.28289 1.53164 6.74384C1.51264 6.37233 1.62214 6.24082 1.99215 6.17332C2.47916 6.08332 2.98118 6.06432 3.46769 6.13582C5.52476 6.43633 7.27581 7.35586 8.74385 8.8129C9.58188 9.64243 10.2159 10.634 10.8689 11.6025C11.5634 12.631 12.3105 13.611 13.262 14.4146C13.598 14.6961 13.866 14.9101 14.1225 15.0681C13.349 15.1546 12.058 15.1731 11.1749 14.4746L11.1749 14.4736ZM12.141 8.25988C12.141 8.09488 12.273 7.96338 12.439 7.96338C12.4765 7.96338 12.5105 7.97088 12.541 7.98188C12.5825 7.99688 12.6205 8.01938 12.6505 8.05338C12.7035 8.10588 12.7335 8.18088 12.7335 8.25988C12.7335 8.42489 12.6015 8.55639 12.4355 8.55639C12.2695 8.55639 12.141 8.42489 12.141 8.25988ZM15.1415 9.79893C14.949 9.87793 14.7565 9.94544 14.5715 9.95294C14.2845 9.96794 13.9715 9.85143 13.8015 9.70893C13.5375 9.48742 13.3485 9.36342 13.2695 8.97691C13.2355 8.8119 13.2545 8.55639 13.2845 8.40989C13.3525 8.09438 13.277 7.89187 13.0545 7.70787C12.8735 7.55786 12.643 7.51636 12.39 7.51636C12.2955 7.51636 12.209 7.47486 12.1445 7.44136C12.039 7.38886 11.9519 7.25735 12.035 7.09585C12.0615 7.04335 12.19 6.91584 12.22 6.89334C12.5635 6.69784 12.9595 6.76184 13.326 6.90834C13.6655 7.04735 13.9225 7.30236 14.292 7.66287C14.6695 8.09838 14.7375 8.21838 14.9525 8.54539C15.1225 8.8009 15.277 9.06341 15.3831 9.36392C15.4471 9.55142 15.3641 9.70493 15.1415 9.79893Z';
+
+/** 游动关键帧：向上摆尾。 */
+export const HERO_SWIM_UP_PATH = 'M22.403 0.567C22.145 0.477 22.068 0.718 21.939 0.85C21.895 0.893 21.86 0.947 21.824 0.997C21.515 1.421 21.13 1.721 20.591 1.77C19.829 1.867 19.221 2.244 18.712 2.958C18.535 2.227 18.116 1.839 17.516 1.626C17.203 1.506 16.887 1.379 16.663 1.064C16.508 0.839 16.462 0.581 16.383 0.329C16.332 0.176 16.283 0.02 16.121 -0.002C15.944 -0.029 15.875 0.133 15.805 0.269C15.52 0.822 15.408 1.43 15.42 2.046C15.449 3.432 16.031 4.532 17.202 5.274C17.337 5.356 17.374 5.445 17.335 5.582C17.261 5.862 17.169 6.134 17.086 6.413C17.032 6.59 16.952 6.63 16.764 6.558C16.118 6.301 15.562 5.909 15.074 5.433C14.248 4.633 13.5 3.751 12.568 3.06C12.349 2.898 12.13 2.748 11.903 2.605C10.952 1.682 12.028 0.923 12.277 0.833C12.537 0.739 12.367 0.416 11.526 0.42C10.684 0.424 9.914 0.706 8.933 1.081C8.789 1.138 8.638 1.179 8.484 1.213C7.593 1.044 6.668 1.006 5.702 1.115C3.883 1.318 2.43 2.178 1.362 3.646C0.079 5.41 -0.223 7.415 0.147 9.506C0.535 11.71 1.66 13.535 3.389 14.962C5.181 16.441 7.246 17.166 9.601 17.027C11.032 16.944 12.624 16.753 14.421 15.232C14.874 15.458 15.35 15.548 16.138 15.615C16.746 15.672 17.331 15.585 17.784 15.491C18.493 15.341 18.444 14.684 18.188 14.564C16.108 13.595 16.565 13.989 16.15 13.67C17.206 12.42 18.82 10.198 19.363 7.086C19.421 6.709 19.484 6.171 19.469 5.866C19.458 5.681 19.493 5.604 19.681 5.556C20.199 5.412 20.691 5.172 21.125 4.806C22.366 3.824 22.758 2.554 22.708 1.1C22.7 0.878 22.649 0.654 22.403 0.567ZM11.175 14.451C9.159 12.726 8.182 12.088 7.778 12.067C7.401 12.047 7.469 12.505 7.552 12.807C7.639 13.103 7.752 13.313 7.91 13.581C8.02 13.758 8.095 14.01 7.801 14.16C7.152 14.487 6.023 13.806 5.97 13.772C4.657 12.85 3.559 11.766 2.785 10.369C2.037 9.025 1.603 7.583 1.532 6.044C1.513 5.672 1.622 5.541 1.992 5.473C2.479 5.383 2.981 5.364 3.468 5.436C5.525 5.736 7.276 6.675 8.744 8.323C9.582 9.299 10.216 10.425 10.869 11.496C11.563 12.592 12.31 13.603 13.262 14.414C13.598 14.696 13.866 14.91 14.123 15.068C13.349 15.154 12.058 15.167 11.175 14.452L11.175 14.451ZM12.141 8.26C12.141 8.095 12.273 7.963 12.439 7.963C12.476 7.963 12.511 7.971 12.541 7.982C12.582 7.997 12.62 8.019 12.65 8.053C12.704 8.106 12.733 8.181 12.733 8.26C12.733 8.425 12.601 8.556 12.435 8.556C12.27 8.556 12.141 8.425 12.141 8.26ZM15.142 9.799C14.949 9.878 14.757 9.945 14.572 9.953C14.284 9.968 13.972 9.851 13.802 9.709C13.537 9.487 13.348 9.363 13.27 8.977C13.236 8.812 13.255 8.556 13.284 8.41C13.352 8.094 13.277 7.892 13.055 7.708C12.873 7.558 12.643 7.516 12.39 7.516C12.296 7.516 12.209 7.475 12.145 7.441C12.039 7.389 11.952 7.257 12.035 7.096C12.062 7.043 12.19 6.916 12.22 6.893C12.563 6.698 12.96 6.762 13.326 6.908C13.665 7.047 13.922 7.302 14.292 7.663C14.669 8.098 14.738 8.218 14.953 8.545C15.123 8.801 15.277 9.063 15.383 9.364C15.447 9.551 15.364 9.705 15.142 9.799Z';
+
+/** 游动关键帧：向下摆尾。 */
+export const HERO_SWIM_DOWN_PATH = 'M23.271 2.216C23.039 2.071 22.91 2.287 22.755 2.388C22.703 2.42 22.656 2.464 22.61 2.505C22.214 2.848 21.771 3.054 21.225 2.956C20.412 2.784 19.68 2.919 19.005 3.435C18.92 2.663 18.493 2.157 17.808 1.798C17.446 1.621 17.08 1.449 16.83 1.111C16.656 0.872 16.611 0.612 16.524 0.354C16.469 0.198 16.414 0.039 16.223 0.009C16.017 -0.024 15.936 0.137 15.856 0.271C15.539 0.822 15.418 1.43 15.429 2.046C15.454 3.432 16.041 4.538 17.196 5.36C17.325 5.456 17.356 5.547 17.312 5.674C17.229 5.936 17.134 6.191 17.051 6.454C16.999 6.623 16.921 6.659 16.738 6.58C16.107 6.306 15.56 5.909 15.074 5.433C14.248 4.633 13.5 3.751 12.568 3.06C12.349 2.898 12.13 2.748 11.903 2.605C10.952 1.682 12.028 0.923 12.277 0.833C12.537 0.739 12.367 0.416 11.526 0.42C10.684 0.424 9.914 0.706 8.933 1.081C8.789 1.138 8.638 1.179 8.484 1.213C7.593 1.044 6.668 1.006 5.702 1.115C3.883 1.318 2.43 2.178 1.362 3.646C0.079 5.41 -0.223 7.415 0.147 9.506C0.535 11.71 1.66 13.535 3.389 14.962C5.181 16.441 7.246 17.166 9.601 17.027C11.032 16.944 12.624 16.753 14.421 15.232C14.874 15.458 15.35 15.548 16.138 15.615C16.746 15.672 17.331 15.585 17.784 15.491C18.493 15.341 18.444 14.684 18.188 14.564C16.108 13.595 16.565 13.989 16.15 13.67C17.206 12.42 18.82 10.198 19.278 7.246C19.318 6.948 19.375 6.534 19.371 6.293C19.371 6.145 19.411 6.092 19.597 6.098C20.113 6.109 20.619 6.051 21.096 5.891C22.503 5.375 23.169 4.232 23.448 2.804C23.49 2.586 23.491 2.356 23.271 2.216ZM11.175 14.49C9.159 13.005 8.182 12.567 7.778 12.621C7.401 12.673 7.469 13.087 7.552 13.354C7.639 13.619 7.752 13.797 7.91 14.024C8.02 14.175 8.095 14.406 7.801 14.609C7.152 15.063 6.023 14.63 5.97 14.609C4.657 13.941 3.559 12.965 2.785 11.569C2.037 10.225 1.603 8.783 1.532 7.244C1.513 6.872 1.622 6.741 1.992 6.673C2.479 6.583 2.981 6.564 3.468 6.636C5.525 6.936 7.276 7.843 8.744 9.163C9.582 9.888 10.216 10.783 10.869 11.679C11.563 12.659 12.31 13.617 13.262 14.415C13.598 14.696 13.866 14.91 14.123 15.068C13.349 15.155 12.058 15.177 11.175 14.491L11.175 14.49ZM12.141 8.26C12.141 8.095 12.273 7.963 12.439 7.963C12.476 7.963 12.511 7.971 12.541 7.982C12.582 7.997 12.62 8.019 12.65 8.053C12.704 8.106 12.733 8.181 12.733 8.26C12.733 8.425 12.601 8.556 12.435 8.556C12.27 8.556 12.141 8.425 12.141 8.26ZM15.142 9.799C14.949 9.878 14.757 9.945 14.572 9.953C14.284 9.968 13.972 9.851 13.802 9.709C13.537 9.487 13.348 9.363 13.27 8.977C13.236 8.812 13.255 8.556 13.284 8.41C13.352 8.094 13.277 7.892 13.055 7.708C12.873 7.558 12.643 7.516 12.39 7.516C12.296 7.516 12.209 7.475 12.145 7.441C12.039 7.389 11.952 7.257 12.035 7.096C12.062 7.043 12.19 6.916 12.22 6.893C12.563 6.698 12.96 6.762 13.326 6.908C13.665 7.047 13.922 7.302 14.292 7.663C14.669 8.098 14.738 8.218 14.953 8.545C15.123 8.801 15.277 9.063 15.383 9.364C15.447 9.551 15.364 9.705 15.142 9.799Z';
+
+/**
+ * 品牌资产来源与校验信息。
+ *
+ * `checksums` 是提取时的 sha256 前 16 位，**由测试真实校验**（见
+ * test/login-page-branding.test.mjs 的"品牌资产校验和"用例）—— 否则注释里的
+ * "防止静默替换"就是一句空头支票。
+ */
+export const BRAND_ASSET_SOURCE = {
+  package: '@deepseek-ai/dsh-client-ui-primitives',
+  conversationPackage: '@deepseek-ai/dsh-client-ui-conversation',
+  license: 'MIT',
+  viewBox: '0 0 23.16 17.04',
+  checksums: {
+    fish: '5bee701f39229e6d',
+    swimUp: '714b02df1872534c',
+    swimDown: 'b4b0b82c16ae0314',
+  },
+};
+
+/**
+ * 渲染内联鲸鱼标 SVG。
+ *
+ * 动效说明：用 SVG SMIL `<animate>` 做路径变形，而不是 CSS/JS 动画。
+ * 原因 —— SMIL 在 Chrome 100（本插件的浏览器下限，见 client/build.mjs 的
+ * target: ['chrome100']）上原生可用，不需要 polyfill、不产生 JS 错误；
+ * DSH 会话首页的 HeroFish 用的也是这套。`begin="indefinite"` 让动画默认不跑，
+ * 由调用方在聚焦/悬停/提交时通过 beginElement() 触发。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.size=48] 宽度 px，高度按 viewBox 比例自动换算
+ * @param {string} [opts.fill='currentColor'] 填充色
+ * @param {boolean} [opts.swim=true] 是否输出游动关键帧。
+ *        三帧 `values` 里起始帧要重复三次，净成本约 16KB（占整页 41%）。
+ *        留这个开关是为了让"要不要为动效付这 16KB"成为一行可回退的决定，
+ *        当前登录页取 true；有测试钉住这个体积差。
+ * @returns {string} 内联 SVG 字符串
+ */
+export function whaleSvg({ size = 48, fill = 'currentColor', swim = true } = {}) {
+  const height = (size * FISH_LOGO_VIEWBOX.height / FISH_LOGO_VIEWBOX.width).toFixed(2);
+  const animate = swim
+    ? `<animate id="dsh-whale-swim" attributeName="d" begin="indefinite" dur="1.6s" repeatCount="indefinite" calcMode="spline" keyTimes="0;0.35;0.55;0.75;1" keySplines="0.45 0 0.55 1;0.45 0 0.55 1;0.45 0 0.55 1;0.45 0 0.55 1" values="${FISH_LOGO_PATH};${HERO_SWIM_UP_PATH};${FISH_LOGO_PATH};${HERO_SWIM_DOWN_PATH};${FISH_LOGO_PATH}"></animate>`
+    : '';
+  return `<svg class="whale" width="${size}" height="${height}" viewBox="0 0 ${FISH_LOGO_VIEWBOX.width} ${FISH_LOGO_VIEWBOX.height}" fill="none" aria-hidden="true" focusable="false"><path d="${FISH_LOGO_PATH}" fill="${fill}">${animate}</path></svg>`;
+}
+
+/** PWA 图标尺寸与配色（对齐 DSH 暗色 token，固定值，不做参数化）。 */
+const PWA_ICON_SIZE = 512;
+// 底色用 DSH 业务蓝（--dsw-alias-state-business-primary 亮色档，与登录页 CTA 同色）。
+// 为什么不用 DSH 暗色画布 #151517：那是接近纯黑的底，在深色桌面/深色启动器上
+// 图标会和背景糊成一块"光板"（2026-10-16 用户在华为 Mate 80 上实测反馈）。
+// 蓝色在深浅两种桌面上都能立住，且仍是 DSH 的品牌色。
+const PWA_ICON_BG = '#4176e6';
+const PWA_ICON_FG = '#ffffff';
+const PWA_ICON_RADIUS = 128;
+const PWA_ICON_WHALE_WIDTH = 300;
+
+/**
+ * 渲染 PWA / 主屏图标 SVG（512×512，蓝底 + 居中鲸鱼）。
+ *
+ * 与登录页同源同一枚鲸鱼 —— 此前这里是一个蓝色机器人脸，导致手机主屏图标
+ * 与登录页、DSH 本体三方品牌不一致。
+ *
+ * 两种形态（PWA manifest 的 purpose 决定用哪个）：
+ *   - `any`（默认）：自带圆角底，浏览器/启动器原样展示；
+ *   - `maskable`：**满幅方底、无圆角**。启动器会按自己的形状（圆形/水滴/方形）
+ *     裁切 maskable 图标，自带圆角会被裁掉一半、边缘露出透明 → 必须满幅。
+ *     鲸鱼宽度 300/512 = 59%，落在 maskable 要求的中心 80% 安全圆内。
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.maskable=false] 是否输出满幅 maskable 形态
+ * @returns {string} SVG 字符串
+ */
+export function pwaIconSvg({ maskable = false } = {}) {
+  const scale = PWA_ICON_WHALE_WIDTH / FISH_LOGO_VIEWBOX.width;
+  const h = FISH_LOGO_VIEWBOX.height * scale;
+  const tx = (PWA_ICON_SIZE - PWA_ICON_WHALE_WIDTH) / 2;
+  const ty = (PWA_ICON_SIZE - h) / 2;
+  const rect = maskable
+    ? `<rect width="${PWA_ICON_SIZE}" height="${PWA_ICON_SIZE}" fill="${PWA_ICON_BG}"/>`
+    : `<rect width="${PWA_ICON_SIZE}" height="${PWA_ICON_SIZE}" rx="${PWA_ICON_RADIUS}" fill="${PWA_ICON_BG}"/>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${PWA_ICON_SIZE} ${PWA_ICON_SIZE}">
+  ${rect}
+  <g transform="translate(${tx.toFixed(2)} ${ty.toFixed(2)}) scale(${scale.toFixed(4)})">
+    <path d="${FISH_LOGO_PATH}" fill="${PWA_ICON_FG}"/>
+  </g>
+</svg>`;
+}