qq-bot-roost 1.0.8 → 1.0.10

package/README.md

@@ -8,9 +8,9 @@
 
 <img src="https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22.13+">
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
-<img src="https://img.shields.io/badge/tests-813%20passed-brightgreen" alt="测试 813 项">
+<img src="https://img.shields.io/badge/tests-826%20passed-brightgreen" alt="测试 826 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-1.0.8-blueviolet" alt="版本 1.0.8">
+<img src="https://img.shields.io/badge/version-1.0.10-blueviolet" alt="版本 1.0.10">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 <a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -147,6 +147,8 @@ export class QQApi {
     this.seqMap = new Map();
     // 群管内邀开关，由 BotRuntime 按配置同步；默认关
     this.groupInvited = false;
+    // 「发图带空格」兼容开关，由 BotRuntime 按 cfg.media.placeholderSpace 同步；默认关
+    this.mediaPlaceholderSpace = false;
     // 群角色查询缓存：groupOpenid -> { at, value }。bot_state 只有 30 QPM
     this.roleCache = new Map();
     /**
@@ -564,11 +566,15 @@ export class QQApi {
     const up = await this.uploadMedia(scene, target, { fileType, url, fileData });
     if (!up?.file_info) throw new Error('上传成功但未返回 file_info');
     /**
-     * **不要 content。**
+     * **不要在这里传 content。**
      *
      * 官方字段表：`msg_type=7` 时生效的是 `media`，`content` 只在
      * `msg_type=0` 时是全文。以前这里填了一个空格占位，客户端会把
      * 它当成正文，渲染出一块空的文字区（图被挤到一侧）。
+     *
+     * 那个空格现在做成面板「配置 → 发图兼容」的可选开关（默认关）：
+     * 打开后由 `#payload()` 在最终报文里补，这里依旧不带 content，
+     * 免得开关关着时又冒出空格、开着时补两遍。
      */
     const opts = {
       msgType: 7,
@@ -632,6 +638,19 @@ export class QQApi {
     return this.groupInvited;
   }
 
+  /**
+   * 「发图带空格」开关。由 BotRuntime 按 cfg.media.placeholderSpace 初始化，
+   * 面板改动时由 /api/config 同步进来，立即生效、不用重启。
+   *
+   * 只认布尔 true：`"false"` / `0` / `undefined` 一律当关。
+   * 面板配置走 HTTP，字符串 "false" 按真值判断会被读成「开」——
+   * security.trust.enforce 踩过这个坑，这里不重犯。
+   */
+  setMediaPlaceholderSpace(v) {
+    this.mediaPlaceholderSpace = v === true;
+    return this.mediaPlaceholderSpace;
+  }
+
   /** 内邀接口的统一闸门。没开门就抛错，别把请求发出去刷一屏 11253 */
   #needInvite() {
     if (!this.groupInvited) {
@@ -1260,7 +1279,24 @@ export class QQApi {
   }
 
   #payload(opts) {
-    return buildSendPayload(opts, (id) => this.#nextSeq(id));
+    const payload = buildSendPayload(opts, (id) => this.#nextSeq(id));
+    /**
+     * 「发图带空格」兼容开关（默认关，面板「配置 → 发图兼容」）。
+     *
+     * 放在最终报文这一层，是为了**一处覆盖所有发图路径**：
+     * msg.replyImage / replyImageBuffer、api.sendMedia、插件拿到的
+     * ctx.api.sendMedia、以及没有调度器时的 api.sendGroup 兜底，最后都过这里。
+     * 放在 outbound 或 message 层都会漏，还会污染投递账本的正文摘要
+     * （账本把纯空格当「没有正文」，测试也断言富媒体不带 content）。
+     *
+     * 只补「没有正文的富媒体」：
+     *   · msg_type=7 且 content 为空 —— 老版就是在这里塞 ' '
+     *   · 有 text 的图文混排不动，markdown(2) / ark(3) / 卡片(8) 也不动
+     */
+    if (this.mediaPlaceholderSpace && payload.msg_type === 7 && !payload.content) {
+      payload.content = ' ';
+    }
+    return payload;
   }
 
   /**

package/src/bot.js

@@ -200,6 +200,9 @@ export class BotRuntime {
     // 群管内邀开关：api 层有自己的副本，配置变了由面板接口同步过来。
     // mock 的 api 也实现了同名方法，一起同步，方便本地验证插件的群管逻辑
     this.api.setGroupInvited?.(cfg.groupManage?.invited);
+    // 发图带空格：只影响真实 QQApi 的最终报文；mock api 不拼官方报文、
+    // 没实现这个 setter，?. 会直接跳过（演示模式下开关不适用）
+    this.api.setMediaPlaceholderSpace?.(cfg.media?.placeholderSpace);
 
     this.session = new SessionManager({
       stickyMs: Math.max(0, (cfg.session?.stickySec ?? 180) * 1000),

package/src/config.js

@@ -335,6 +335,22 @@ const BOT_DEFAULTS = {
   groupManage: {
     invited: false,
   },
+
+  /**
+   * 富媒体（图片 / 视频 / 语音 / 文件）发送兼容选项。
+   *
+   * `placeholderSpace` 默认 false：只发一张图时，msg_type=7 的 content
+   * 保持空串，QQ 里是一张干净的图（v1.0.6 起的行为）。
+   * 打开后由 `QQApi.#payload()` 给没有正文的富媒体补一个空格，回到
+   * v1.0.6 之前的排版：客户端按图文混排渲染，图外面多一块空白文字区。
+   * 老客户端 / 旧插件依赖那个占位空格时才需要打开。
+   *
+   * 官方对非图片类型的 content 会忽略，所以实际只对图片有观感影响；
+   * 带说明文字的图片（replyImage 的 text）不受影响。
+   */
+  media: {
+    placeholderSpace: false,
+  },
 };
 
 function deepMerge(base, extra) {
@@ -529,6 +545,8 @@ export async function saveBotConfig(id, cfg) {
     gate: cfg.gate ?? { pauseOnStart: false },
     plugins: cfg.plugins,
     groupManage: cfg.groupManage ?? { invited: false },
+    // 脏值（字符串 / 数组 / 旧配置里混进来的东西）一律规范成默认关，别污染配置文件
+    media: { placeholderSpace: cfg.media?.placeholderSpace === true },
   });
 }
 

package/src/message.js

@@ -848,6 +848,9 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
    * 理由是「官方不接受空 content」——那说的是传 `''`，跟不传不是一回事，
    * 结果客户端按图文混排渲染，图外面多出一圈文字区（v1.0.6 修掉）。
    *
+   * 面板「配置 → 发图兼容」把这个空格做成了可选开关：打开后由 api 层在
+   * 最终报文里补回占位空格（老客户端 / 旧插件需要时），这里依旧不带 content。
+   *
    * 发送前会先把攒着的文本 flush 掉，免得「缓冲中的回复」被这条
    * 富媒体消息挤成顺序错乱的两条。
    */

package/src/web/server.js

@@ -1605,6 +1605,24 @@ export async function startWebServer({
             cfg.groupManage = { invited: Boolean(body.groupManage.invited) };
             rt.api?.setGroupInvited?.(cfg.groupManage.invited);
           }
+          /**
+           * 「发图带空格」兼容开关（默认关）。
+           * 严格只认布尔 true：字符串 "false" 按真值判断会被当成「开」，
+           * 和 security.trust.enforce 踩过的是同一个坑。
+           * 同步给 api 实例，勾选后立即生效、不用重启。
+           *
+           * 还要求「对象 + 布尔字段」齐全才写：面板漏传字段、旧版前端、
+           * 或者 body.media 是 [] / {} 时，不该把已经打开的开关静默关掉。
+           */
+          if (
+            body.media &&
+            typeof body.media === 'object' &&
+            !Array.isArray(body.media) &&
+            typeof body.media.placeholderSpace === 'boolean'
+          ) {
+            cfg.media = { placeholderSpace: body.media.placeholderSpace };
+            rt.api?.setMediaPlaceholderSpace?.(cfg.media.placeholderSpace);
+          }
 
           await saveBotConfig(rt.id, cfg);
           log.info('配置已通过面板更新');

package/web/app.js

@@ -606,6 +606,8 @@ function activateTab(name) {
   if (name === 'roles') { loadRoles(); loadPeople(); }
   if (name === 'identity') loadIdentity();
   if (name === 'notify') loadNotify();
+  // 纯展示同步：侧栏 / 底栏高亮、面包屑、抽屉收起。不碰任何数据加载。
+  syncNav(name);
 }
 
 /**
@@ -1070,6 +1072,8 @@ function fillForm(c) {
   f.logLevel.value = c.logLevel || 'info';
 
   f.groupInvited.checked = Boolean(c.groupManage?.invited);
+  // 严格只认 true：老配置文件里没这个字段时保持关闭
+  f.mediaPlaceholderSpace.checked = c.media?.placeholderSpace === true;
 
   /**
    * 插件来源校验开关。`pubkeySet: false` 时必须说清楚「开了也没用」——
@@ -1405,6 +1409,36 @@ document.addEventListener('click', async (e) => {
   }
 });
 
+/* ---------------- 发图兼容：勾选即生效 ---------------- */
+
+/**
+ * 「保存配置」按钮在表单顶部/底部，离这块设置很远，勾完还得滚过去点一下才生效。
+ * 这里跟 `autoSaveIntents` 一个套路：change 时局部 PUT 只提交 media 一个字段，
+ * 后端 `/api/config` 是合并语义，其它配置项不会被这次请求碰。
+ * 不需要防抖——勾一下就是一次，且不会像 intents 那样触发重连。
+ */
+$('#mediaPlaceholderSpace').addEventListener('change', async (e) => {
+  const on = e.target.checked;
+  const tip = $('#mediaSpaceMsg');
+  if (tip) tip.textContent = '正在应用…';
+  try {
+    await api('/api/config', {
+      method: 'PUT',
+      body: JSON.stringify({ media: { placeholderSpace: on } }),
+    });
+    if (tip) {
+      tip.textContent = on ? '已生效：发图会带空格' : '已生效：恢复干净图';
+      setTimeout(() => {
+        if (tip.textContent.startsWith('已生效')) tip.textContent = '';
+      }, 4000);
+    }
+  } catch (err) {
+    // 没保存成功就把勾选退回去，别让用户以为已经开了
+    e.target.checked = !on;
+    if (tip) tip.textContent = '应用失败: ' + err.message;
+  }
+});
+
 $('#cfgForm').addEventListener('submit', async (e) => {
   e.preventDefault();
   const f = e.target;
@@ -1444,6 +1478,10 @@ $('#cfgForm').addEventListener('submit', async (e) => {
     groupManage: {
       invited: f.groupInvited.checked,
     },
+    // 发图兼容：和 groupManage 一样是每台机器人一份，勾选后立即生效
+    media: {
+      placeholderSpace: f.mediaPlaceholderSpace.checked,
+    },
     // 全局设置（config/bot.json），和 webui 一样不写进机器人配置
     security: {
       trust: { enforce: f.trustEnforce.checked },
@@ -4447,3 +4485,208 @@ function connectStream() {
   // 机器人确定后再刷一次：上面那次是抢时间，这次才是准数据
   if (initial) activateTab(initial);
 })();
+
+/* ============================================================
+   响应式导航外观（2026-11-06 重构新增）
+   ------------------------------------------------------------
+   这一整段只做「壳」：高亮、面包屑、抽屉开合、表格标签、theme-color。
+   不调用任何数据加载函数，不改任何 API、轮询或 iframe 逻辑。
+   ============================================================ */
+
+/**
+ * 页签切换后同步各处导航状态。
+ * 由 activateTab() 末尾调用；切机器人 / hashchange 走的也是 activateTab，
+ * 所以不需要额外注册第二套监听。
+ */
+function syncNav(name) {
+  const nav = $('#mainNav');
+  if (!nav) return;
+  const btn = $$('[data-tab]').find(
+    (b) => b.dataset.tab === name && b.classList.contains('tab-item'),
+  );
+  const crumb = $('#navCrumb');
+  if (crumb) {
+    crumb.textContent = btn ? btn.textContent.trim()
+      : (name.startsWith('page:') ? '插件页面' : '概览');
+  }
+  // 停在非高频页时，底栏「更多」给个提示态，免得用户以为没有当前页
+  const more = $('#navMore');
+  if (more) more.classList.toggle('has-active', Boolean(btn) && !btn.hasAttribute('data-primary'));
+  // 切到某个页签时把它所在的折叠组展开，否则用户看不到自己选中了哪一页
+  const group = btn?.closest('.tab-group');
+  if (group?.classList.contains('group-collapsed')) setGroupCollapsed(group, false);
+  // 选完页就把抽屉 / 平板展开态收起来
+  nav.classList.remove('drawer-open', 'expanded');
+  const toggle = $('#navToggle');
+  if (toggle) toggle.setAttribute('aria-expanded', 'false');
+  if (more) more.setAttribute('aria-expanded', 'false');
+}
+
+/* 侧栏偏好：纯外观状态，存 localStorage，不参与任何业务数据 */
+const NAV_COMPACT_KEY = 'roost_nav_compact';
+const NAV_GROUPS_KEY = 'roost_nav_groups';
+
+/** 折叠 / 展开一个分组，并记住选择 */
+function setGroupCollapsed(group, on) {
+  if (!group) return;
+  group.classList.toggle('group-collapsed', on);
+  const key = group.dataset.group;
+  if (!key) return;
+  let list = [];
+  try { list = JSON.parse(localStorage.getItem(NAV_GROUPS_KEY) || '[]'); } catch {}
+  if (!Array.isArray(list)) list = [];
+  const next = on ? [...new Set([...list, key])] : list.filter((x) => x !== key);
+  try { localStorage.setItem(NAV_GROUPS_KEY, JSON.stringify(next)); } catch {}
+}
+
+/** 恢复上次的收起 / 折叠状态；当前页所在组强制展开 */
+function applyNavPrefs() {
+  try {
+    if (localStorage.getItem(NAV_COMPACT_KEY) === '1') {
+      document.body.classList.add('nav-compact');
+    }
+    const list = JSON.parse(localStorage.getItem(NAV_GROUPS_KEY) || '[]');
+    if (Array.isArray(list)) {
+      $$('.app-nav .tab-group').forEach((g) => {
+        if (list.includes(g.dataset.group)) g.classList.add('group-collapsed');
+      });
+    }
+  } catch {}
+  const active = $('.app-nav .tab-item.active')?.closest('.tab-group');
+  if (active) setGroupCollapsed(active, false);
+}
+
+/**
+ * 给表格单元格补 data-label，供窄屏卡片化的 td::before 使用。
+ *
+ * 12 张表的行几乎全是 JS 动态渲染的（app.js 里 80 多处 <td 模板），
+ * 逐处改模板既伤业务代码又容易漏。这里用 MutationObserver 在 tbody
+ * 内容变化时按 thead 的列序自动贴标签，纯展示、零业务侵入。
+ * 空状态行（colspan）不贴，避免卡片上出现一个没有值的字段。
+ */
+function initTableLabels() {
+  const labelsFor = (table) =>
+    [...table.querySelectorAll('thead th')].map((th) => th.textContent.trim());
+
+  const decorate = (tbody) => {
+    const table = tbody.closest('table');
+    if (!table) return;
+    const labels = labelsFor(table);
+    for (const tr of tbody.rows) {
+      Array.from(tr.cells).forEach((td, i) => {
+        if (td.hasAttribute('colspan') || !labels[i]) return;
+        if (!td.dataset.label) td.dataset.label = labels[i];
+      });
+    }
+  };
+
+  const bodies = $$('table tbody');
+  bodies.forEach(decorate);
+  if (typeof MutationObserver === 'undefined') return;
+
+  const mo = new MutationObserver((records) => {
+    for (const r of records) {
+      const t = r.target;
+      if (!t) continue;
+      if (t.tagName === 'TBODY') decorate(t);
+      else if (t.closest) {
+        const tb = t.closest('tbody');
+        if (tb) decorate(tb);
+      }
+    }
+  });
+  // subtree: 业务若往已有 <tr> 里追加 <td>（不是整块 innerHTML 替换）也要补标签
+  bodies.forEach((tb) => mo.observe(tb, { childList: true, subtree: true }));
+}
+
+/** 手机浏览器地址栏跟随深浅色，纯展示，不碰 setTheme() */
+function initThemeColor() {
+  const meta = document.querySelector('meta[name="theme-color"]');
+  if (!meta) return;
+  const apply = () => {
+    meta.setAttribute(
+      'content',
+      document.documentElement.dataset.theme === 'dark' ? '#19120e' : '#f8f5f1',
+    );
+  };
+  apply();
+  if (typeof MutationObserver === 'undefined') return;
+  new MutationObserver(apply).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['data-theme'],
+  });
+}
+
+(function initNavChrome() {
+  const nav = $('#mainNav');
+  if (!nav) return;
+  const toggle = $('#navToggle');
+  const more = $('#navMore');
+  const close = $('#navClose');
+
+  const setOpen = (on) => {
+    // 只挂当前档位对应的 class：同时挂两个，用户拖动窗口跨断点时会残留另一个形态
+    const isPhone = window.matchMedia('(max-width: 720px)').matches;
+    nav.classList.toggle('drawer-open', on && isPhone);
+    nav.classList.toggle('expanded', on && !isPhone);
+    if (toggle) toggle.setAttribute('aria-expanded', String(on));
+    if (more) more.setAttribute('aria-expanded', String(on));
+  };
+
+  toggle?.addEventListener('click', (e) => {
+    e.stopPropagation();
+    if (window.matchMedia('(max-width: 720px)').matches) {
+      // 手机：打开全量抽屉
+      setOpen(!nav.classList.contains('drawer-open'));
+    } else if (window.matchMedia('(min-width: 721px) and (max-width: 1023px)').matches) {
+      // 平板：展开 / 收回 60px 图标条
+      setOpen(!nav.classList.contains('expanded'));
+    } else {
+      // 桌面：收起 / 展开侧栏，记住选择
+      const compact = !document.body.classList.contains('nav-compact');
+      document.body.classList.toggle('nav-compact', compact);
+      try { localStorage.setItem(NAV_COMPACT_KEY, compact ? '1' : '0'); } catch {}
+      toggle.setAttribute('aria-expanded', String(!compact));
+      toggle.title = compact ? '展开侧栏' : '收起侧栏';
+    }
+  });
+
+  // 分组标题点击 = 折叠 / 展开下级菜单（snowluma 那种手风琴）
+  $$('.app-nav .tab-parent').forEach((p) => {
+    p.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const g = p.closest('.tab-group');
+      if (!g) return;
+      // 收起态下点分组图标 = 「我想看这一组」，直接展开侧栏并展开该组
+      if (document.body.classList.contains('nav-compact')
+        && window.matchMedia('(min-width: 1024px)').matches) {
+        document.body.classList.remove('nav-compact');
+        try { localStorage.setItem(NAV_COMPACT_KEY, '0'); } catch {}
+        setGroupCollapsed(g, false);
+        return;
+      }
+      setGroupCollapsed(g, !g.classList.contains('group-collapsed'));
+    });
+  });
+
+  more?.addEventListener('click', (e) => {
+    e.stopPropagation();
+    setOpen(true);
+  });
+  close?.addEventListener('click', (e) => {
+    e.stopPropagation();
+    setOpen(false);
+  });
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') setOpen(false);
+  });
+
+  // 初始化：先恢复偏好，再补一次外观同步（无 hash 时 activateTab 不会被调用）
+  applyNavPrefs();
+  if (toggle) {
+    toggle.title = document.body.classList.contains('nav-compact') ? '展开侧栏' : '收起侧栏';
+  }
+  syncNav(location.hash.slice(1) || 'overview');
+  initTableLabels();
+  initThemeColor();
+})();

package/web/index.html

@@ -2,7 +2,8 @@
 <html lang="zh-CN">
 <head>
 <meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="theme-color" content="#f8f5f1">
 <title>栖 Roost · 控制台</title>
 <!-- 主题脚本必须外置：CSP 的 script-src 'self' 会拦掉内联脚本 -->
 <script src="/theme-boot.js"></script>
@@ -11,6 +12,11 @@
 <body>
 
 <header class="topbar">
+  <button class="nav-toggle" id="navToggle" aria-label="打开导航" aria-expanded="false">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+      <path d="M4 7h16M4 12h16M4 17h16"/>
+    </svg>
+  </button>
   <div class="brand" title="栖 Roost · 倦飞之鸟，终有一栖">
     <span class="logo" aria-hidden="true">栖</span>
     <div>
@@ -42,67 +48,132 @@
     </div>
   </div>
 
-  <nav class="tabs">
-    <button class="tab active" data-tab="overview">概览</button>
-
-    <div class="tab-group" data-group="data">
-      <button class="tab tab-parent" aria-haspopup="true" aria-expanded="false">
-        数据
-        <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-             stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
-          <path d="M6 9l6 6 6-6"/>
+  <!--
+    导航：三档布局共用这一份 DOM，靠 CSS 变形（侧栏 / 图标条 / 底部导航 + 抽屉）。
+    不要复制出第二套 [data-tab] 按钮 —— activateTab() 用 `b === btn` 高亮，
+    重复 data-tab 会导致只有第一处亮。
+    .tab-group / .tab-parent / .tab-menu 三件套和 #pluginPageItems 是
+    closeTabMenus()、loadPluginPages() 的硬依赖，类名与 id 一律不能改。
+  -->
+  <nav class="app-nav" id="mainNav" aria-label="主导航">
+    <div class="nav-head">
+      <span class="nav-brand">栖 <span>Roost</span></span>
+      <button class="nav-close" id="navClose" aria-label="收起导航">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+          <path d="M6 6l12 12M18 6L6 18"/>
         </svg>
       </button>
-      <div class="tab-menu" hidden>
-        <button class="tab-item" data-tab="stats">统计</button>
-        <button class="tab-item" data-tab="events">事件</button>
-        <button class="tab-item" data-tab="reach">可达性</button>
-        <button class="tab-item" data-tab="delivery">投递</button>
-        <button class="tab-item" data-tab="ledger">账本</button>
-        <button class="tab-item" data-tab="logs">日志</button>
-      </div>
     </div>
 
-    <div class="tab-group" data-group="settings">
-      <button class="tab tab-parent" aria-haspopup="true" aria-expanded="false">
-        设置
-        <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-             stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
-          <path d="M6 9l6 6 6-6"/>
-        </svg>
-      </button>
-      <div class="tab-menu" hidden>
-        <button class="tab-item" data-tab="config">配置</button>
-        <button class="tab-item" data-tab="groups">群组</button>
-        <button class="tab-item" data-tab="roles">权限</button>
+    <div class="nav-scroll">
+      <div class="tab-group" data-group="run">
+        <button class="tab tab-parent" data-icon="运" aria-label="运行" aria-haspopup="true" aria-expanded="false">
+          <svg class="nav-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <rect x="3" y="3" width="7" height="7" rx="1.5"/><rect x="14" y="3" width="7" height="7" rx="1.5"/>
+            <rect x="3" y="14" width="7" height="7" rx="1.5"/><rect x="14" y="14" width="7" height="7" rx="1.5"/>
+          </svg>
+          <span class="nav-label">运行</span>
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+               stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M6 9l6 6 6-6"/>
+          </svg>
+        </button>
+        <div class="tab-menu" hidden>
+          <button class="tab-item active" data-tab="overview" data-primary>概览</button>
+          <button class="tab-item" data-tab="stats">统计</button>
+          <button class="tab-item" data-tab="logs" data-primary>日志</button>
+        </div>
       </div>
-    </div>
 
-    <div class="tab-group" data-group="plugins">
-      <button class="tab tab-parent" aria-haspopup="true" aria-expanded="false">
-        插件
-        <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-             stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
-          <path d="M6 9l6 6 6-6"/>
-        </svg>
-      </button>
-      <div class="tab-menu" hidden>
-        <button class="tab-item" data-tab="plugins">插件管理</button>
-        <!-- 插件注册的页面挂到这里，见 loadPluginPages() -->
-        <div class="tab-menu-sep" id="pluginPageSep" hidden></div>
-        <div class="tab-menu-label" id="pluginPageLabel" hidden>插件页面</div>
-        <div class="tab-menu-sub" id="pluginPageItems"></div>
+      <div class="tab-group" data-group="diagnose">
+        <button class="tab tab-parent" data-icon="诊" aria-label="诊断" aria-haspopup="true" aria-expanded="false">
+          <svg class="nav-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M2 12h4l3-7 4 14 3-7h6"/>
+          </svg>
+          <span class="nav-label">诊断</span>
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+               stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M6 9l6 6 6-6"/>
+          </svg>
+        </button>
+        <div class="tab-menu" hidden>
+          <button class="tab-item" data-tab="events">事件</button>
+          <button class="tab-item" data-tab="reach">可达性</button>
+          <button class="tab-item" data-tab="delivery">投递</button>
+          <button class="tab-item" data-tab="ledger">账本</button>
+        </div>
       </div>
-    </div>
 
-    <!-- 身份：QQ号 / 群号 ↔ openid。常用页而不是设置项 -->
-    <button class="tab" data-tab="identity">身份</button>
+      <div class="tab-group" data-group="manage">
+        <button class="tab tab-parent" data-icon="管" aria-label="管理" aria-haspopup="true" aria-expanded="false">
+          <svg class="nav-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M4 6h9M17 6h3M4 12h3M11 12h9M4 18h9M17 18h3"/>
+            <circle cx="15" cy="6" r="2"/><circle cx="9" cy="12" r="2"/><circle cx="15" cy="18" r="2"/>
+          </svg>
+          <span class="nav-label">管理</span>
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+               stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M6 9l6 6 6-6"/>
+          </svg>
+        </button>
+        <div class="tab-menu" hidden>
+          <button class="tab-item" data-tab="config" data-primary>配置</button>
+          <!-- 身份：QQ号 / 群号 ↔ openid。常用页而不是设置项 -->
+          <button class="tab-item" data-tab="identity">身份</button>
+          <button class="tab-item" data-tab="groups">群组</button>
+          <button class="tab-item" data-tab="roles">权限</button>
+          <!-- 通知：SMTP 邮箱配置 + 普通成员自助绑定 -->
+          <button class="tab-item" data-tab="notify">通知</button>
+        </div>
+      </div>
 
-    <!-- 通知：SMTP 邮箱配置 + 普通成员自助绑定。字段参考 BetterGI「设置 → 通知」 -->
-    <button class="tab" data-tab="notify">通知</button>
+      <div class="tab-group" data-group="plugins">
+        <button class="tab tab-parent" data-icon="扩" aria-label="扩展" aria-haspopup="true" aria-expanded="false">
+          <svg class="nav-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M4 4h6v2a2 2 0 1 0 4 0V4h6v6h-2a2 2 0 1 0 0 4h2v6h-6v-2a2 2 0 1 0-4 0v2H4v-6h2a2 2 0 1 0 0-4H4V4z"/>
+          </svg>
+          <span class="nav-label">扩展</span>
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+               stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M6 9l6 6 6-6"/>
+          </svg>
+        </button>
+        <div class="tab-menu" hidden>
+          <button class="tab-item" data-tab="plugins" data-primary>插件管理</button>
+          <!-- 插件注册的页面挂到这里，见 loadPluginPages() -->
+          <div class="tab-menu-sep" id="pluginPageSep" hidden></div>
+          <div class="tab-menu-label" id="pluginPageLabel" hidden>插件页面</div>
+          <div class="tab-menu-sub" id="pluginPageItems"></div>
+        </div>
+      </div>
+
+      <div class="tab-group" data-group="system">
+        <button class="tab tab-parent" data-icon="系" aria-label="系统" aria-haspopup="true" aria-expanded="false">
+          <svg class="nav-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="9"/><path d="M12 11v6M12 7.5h.01"/>
+          </svg>
+          <span class="nav-label">系统</span>
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+               stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M6 9l6 6 6-6"/>
+          </svg>
+        </button>
+        <div class="tab-menu" hidden>
+          <button class="tab-item" data-tab="about">关于</button>
+        </div>
+      </div>
+    </div>
 
-    <button class="tab" data-tab="about">关于</button>
+    <button class="nav-more" id="navMore" aria-label="全部功能" aria-expanded="false">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+        <circle cx="5" cy="12" r="1.4"/><circle cx="12" cy="12" r="1.4"/><circle cx="19" cy="12" r="1.4"/>
+      </svg>
+      <span>更多</span>
+    </button>
   </nav>
+
+  <div class="topbar-spacer"></div>
+  <div class="crumb" id="navCrumb">概览</div>
   <button class="icon-btn" id="btnTheme" title="切换日间 / 夜间" aria-label="切换主题">
     <svg class="ic-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor"
          stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
@@ -517,6 +588,22 @@
         </label>
       </div>
 
+      <div class="box">
+        <div class="box-hd"><h3>发图兼容</h3><span class="hint">默认关闭</span></div>
+        <label class="switch">
+          <input type="checkbox" name="mediaPlaceholderSpace" id="mediaPlaceholderSpace">
+          发图片时带一个空格（v1.0.6 之前的行为）
+        </label>
+        <div class="hint" id="mediaSpaceMsg" style="margin-top:4px"></div>
+        <div class="hint" style="margin-top:8px">
+          只发一张图时，框架本来不带正文，QQ 里就是干净的一张图。打开后会在富媒体消息里
+          补一个空格当正文，回到旧版排版：图片被挤向一侧、外面多出一块空白文字区。<br>
+          可能有奇妙的作用（），<b>勾选后立即生效、不用点保存也不用重启</b>。
+          带说明文字的图片（<code>replyImage(..., { text })</code>）不受影响；
+          视频 / 语音 / 文件的 content 官方会忽略，勾上也没有副作用。
+        </div>
+      </div>
+
       <div class="box">
         <div class="box-hd"><h3>群管能力</h3><span class="hint">禁言 / 撤回已开放；群成员与踢人需官方白名单</span></div>
         <label class="switch">

package/web/style.css

@@ -1425,3 +1425,480 @@ label.switch.small { font-size: 12.5px; color: var(--muted); }
   white-space: nowrap;
   overflow-wrap: anywhere;
 }
+
+/* ============================================================
+   响应式布局重构（2026-11-06）
+   ------------------------------------------------------------
+   三档共用同一份导航 DOM，靠 CSS 变形：
+     ≥1024      固定分组侧栏
+     721–1023   60px 图标条（可展开）
+     ≤720       底部高频 4 项 + 全量抽屉
+   规则一律放文件末尾、用 .app-nav 提高特异性覆盖旧 .tabs 规则，
+   不改 :root 变量名 —— server.js 的 PAGE_THEME 镜像着同一套变量名，
+   改名会让插件页面深浅色失效。
+   ============================================================ */
+
+/* ---------- 顶栏新增件 ---------- */
+.topbar-spacer { flex: 1; min-width: 0; }
+.crumb { font-size: 13px; color: var(--muted); white-space: nowrap; }
+.crumb::before { content: '/'; margin-right: 8px; color: var(--faint); }
+.nav-toggle {
+  display: none; flex: none; place-items: center;
+  width: 40px; height: 40px; padding: 9px;
+  border: 1px solid var(--border); border-radius: 9px;
+  background: var(--panel); color: var(--muted); cursor: pointer;
+}
+.nav-toggle svg { width: 20px; height: 20px; display: block; }
+.nav-close {
+  display: none; place-items: center;
+  width: 40px; height: 40px; padding: 9px;
+  border: 0; background: none; color: var(--muted); cursor: pointer;
+}
+.nav-close svg { width: 20px; height: 20px; display: block; }
+
+/* ---------- 宽屏：固定分组侧栏 ---------- */
+.app-nav {
+  position: fixed; top: 60px; left: 0; bottom: 0; width: 240px; z-index: 30;
+  display: flex; flex-direction: column;
+  background: var(--panel); border-right: 1px solid var(--border);
+  overflow: hidden;
+  transition: width .26s var(--ease);
+}
+.app-nav .nav-head { display: none; }
+.app-nav .nav-scroll { flex: 1; min-height: 0; overflow-y: auto; padding: 14px 10px 20px; }
+/* 滚动条藏起来但保留滚动能力：侧栏那条灰色粗条在窄窗口里很抢眼 */
+.app-nav .nav-scroll { scrollbar-width: none; -ms-overflow-style: none; }
+.app-nav .nav-scroll::-webkit-scrollbar { width: 0; height: 0; display: none; }
+.app-nav .tab-group { position: static; display: block; margin-bottom: 14px; }
+.app-nav .tab-parent {
+  width: 100%; height: auto; padding: 4px 12px 6px;
+  /* 分组全部折叠后侧栏只剩这 5 行标题，11px 太细、撑不住整列；
+     平板展开态共用这条规则。手机抽屉另有显式 11px 覆盖，不受影响。 */
+  font-size: 13px; font-weight: 600; letter-spacing: .02em;
+  /* 折叠后整列只剩这 5 行标题，--faint 太糊；提到 --muted，仍比菜单项 --text-2 弱一档 */
+  color: var(--muted); cursor: pointer; gap: 7px;
+  /* 必须显式左对齐：平板 / 收起态会把 justify-content 改成 center，
+     切回宽屏时若没覆盖，分组标题会飘到中间，和菜单项错位 */
+  justify-content: flex-start;
+}
+.app-nav .tab-parent::after { display: none; }
+/* 收起态用矢量图标，不再用分组首字 */
+.app-nav .tab-parent .nav-ico {
+  display: none; width: 18px; height: 18px; flex: none; opacity: 0;
+  transition: opacity .2s var(--ease);
+}
+.app-nav .tab-parent .nav-label {
+  flex: 0 1 auto; min-width: 0; max-width: 120px; opacity: 1;
+  white-space: nowrap; overflow: hidden;
+  transition: max-width .26s var(--ease), opacity .18s var(--ease);
+}
+
+/*
+ * 桌面分组常驻展开。closeTabMenus() 会给 .tab-menu 设 hidden=true，
+ * 这里用更高特异性覆盖，避免为了「常驻」去改业务侧的下拉开合逻辑。
+ * 代价仅是 aria-expanded 语义不准，不影响任何功能。
+ */
+.app-nav .tab-menu,
+.app-nav .tab-menu[hidden] {
+  display: block; position: static; min-width: 0; padding: 0;
+  border: 0; border-radius: 0; box-shadow: none; animation: none;
+  max-height: 1600px; opacity: 1; overflow: hidden;
+  transition: max-height .26s var(--ease), opacity .18s var(--ease);
+}
+/* 插件页面可能很多，给个上限，别让整个分组把侧栏撑到天上去 */
+.app-nav .tab-menu-sub { max-height: min(52vh, 420px); overflow-y: auto; }
+.app-nav .tab-item {
+  display: block; width: 100%; text-align: left;
+  min-height: 38px; padding: 8px 12px; margin: 1px 0;
+  border-radius: 8px; font-size: 13px; color: var(--text-2);
+}
+.app-nav .tab-item:hover { background: var(--panel-2); color: var(--text); }
+.app-nav .tab-item.active { background: var(--primary-soft); color: var(--primary); font-weight: 600; }
+.app-nav .tab-menu-label { padding: 6px 10px 2px; }
+.app-nav .nav-more { display: none; }
+
+main {
+  margin-left: 240px; max-width: none; padding: 24px 32px 48px;
+  transition: margin-left .26s var(--ease);
+}
+main > .panel { max-width: 1400px; margin-inline: auto; }
+
+/* ---------- 平板：60px 图标条，汉堡可展开 ---------- */
+@media (min-width: 721px) and (max-width: 1023px) {
+  .nav-toggle { display: grid; }
+  .app-nav { width: 60px; }
+  .app-nav .nav-scroll { padding: 10px 6px; }
+  .app-nav .tab-group { margin-bottom: 6px; }
+  .app-nav .tab-parent { height: 44px; padding: 0; justify-content: center; color: var(--muted); }
+  .app-nav .tab-parent .nav-ico { display: block; opacity: 1; }
+  .app-nav .tab-parent .nav-label { max-width: 0; opacity: 0; }
+  .app-nav .tab-parent .chev { display: none; }
+  .app-nav .tab-menu,
+  .app-nav .tab-menu[hidden] { max-height: 0; opacity: 0; pointer-events: none; }
+  main { margin-left: 60px; padding: 20px 20px 40px; }
+
+  .app-nav.expanded { width: 240px; box-shadow: var(--shadow-lg); }
+  .app-nav.expanded .tab-parent { height: auto; padding: 2px 10px 6px; justify-content: flex-start; }
+  .app-nav.expanded .tab-parent .nav-label { max-width: 120px; opacity: 1; }
+  .app-nav.expanded .tab-parent .chev { display: block; }
+  .app-nav.expanded .tab-menu,
+  .app-nav.expanded .tab-menu[hidden] { max-height: 1600px; opacity: 1; pointer-events: auto; }
+}
+
+/* ---------- 手机：底部导航 + 全量抽屉 ---------- */
+@media (max-width: 720px) {
+  .topbar { height: 54px; padding: 0 10px; gap: 8px; flex-wrap: nowrap; }
+  .nav-toggle { display: grid; width: 42px; height: 42px; padding: 10px; }
+  .brand { display: none; }
+  .bot-switch { flex: 1; min-width: 0; }
+  .bot-trigger { width: 100%; }
+  .bot-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .topbar-spacer, .crumb { display: none; }
+  .icon-btn { width: 40px; height: 40px; }
+  .status-pill { padding: 8px 10px; }
+  .status-pill #connText, .status-pill .pill-sep, .status-pill #connAction { display: none; }
+
+  .app-nav {
+    top: auto; bottom: 0; left: 0; right: 0; width: auto;
+    height: calc(58px + env(safe-area-inset-bottom));
+    flex-direction: row; align-items: stretch; z-index: 40;
+    border-right: 0; border-top: 1px solid var(--border);
+    padding-bottom: env(safe-area-inset-bottom);
+  }
+  .app-nav .nav-head { display: none; }
+  .app-nav .nav-scroll {
+    display: flex; flex: 1; min-width: 0; align-items: stretch;
+    padding: 0; overflow: visible;
+  }
+  /* display:contents 让分散在 5 个分组里的高频项直接参与底栏 flex */
+  .app-nav .tab-group,
+  .app-nav .tab-menu,
+  .app-nav .tab-menu[hidden] {
+    display: contents;
+    max-height: none; opacity: 1; overflow: visible; pointer-events: auto;
+  }
+  .app-nav .tab-parent,
+  .app-nav .tab-menu-sep,
+  .app-nav .tab-menu-label,
+  .app-nav .tab-menu-sub { display: none; }
+  .app-nav .tab-item:not([data-primary]) { display: none; }
+  .app-nav .tab-item[data-primary] {
+    display: flex; flex: 1 1 0; min-width: 0; min-height: 0; height: auto;
+    align-items: center; justify-content: center;
+    padding: 6px 2px; margin: 0; border-radius: 0;
+    font-size: 12px; text-align: center;
+    transition: color .18s var(--ease), box-shadow .18s var(--ease);
+  }
+  .app-nav .tab-item[data-primary].active {
+    background: transparent; color: var(--primary);
+    box-shadow: inset 0 2px 0 var(--primary);
+  }
+  .app-nav .nav-more {
+    display: flex; flex: 0 0 58px; flex-direction: column;
+    align-items: center; justify-content: center; gap: 2px;
+    border: 0; background: none; color: var(--muted);
+    font: inherit; font-size: 11px; cursor: pointer;
+  }
+  .app-nav .nav-more svg { width: 18px; height: 18px; }
+  main { margin-left: 0; padding: 14px 12px calc(74px + env(safe-area-inset-bottom)); }
+  main > .panel { max-width: none; }
+
+  /*
+   * .card .v 原本是 white-space:nowrap（宽屏好看），但手机 2 列网格里
+   * grid item 的 min-width:auto 会被「undefined MB」「凭证有效期」这类长值撑开，
+   * 整页 scrollWidth 变大，顶栏右侧按钮和底栏「更多」一起被挤出视口。
+   * 必须 minmax(0,1fr) + 允许换行，双管齐下。
+   */
+  .cards { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .cards > .card { min-width: 0; }
+  .card .v { white-space: normal; overflow-wrap: anywhere; font-size: 17px; }
+  .topbar, .app-nav { max-width: 100vw; }
+  .status-pill { flex: none; }
+  .app-nav .nav-scroll { min-width: 0; overflow: hidden; }
+
+  /* 抽屉：点「更多」后铺满全屏，列出全部分组 */
+  .app-nav.drawer-open {
+    top: 0; height: 100dvh; flex-direction: column;
+  }
+  .app-nav.drawer-open .nav-head {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 10px 12px; border-bottom: 1px solid var(--border);
+  }
+  .nav-brand { font-family: var(--display); font-size: 16px; font-weight: 700; color: var(--text); }
+  .nav-brand span { font-family: var(--sans); font-size: 10px; letter-spacing: .16em; color: var(--muted); }
+  .app-nav.drawer-open .nav-scroll { display: block; overflow-y: auto; padding: 12px 12px 20px; }
+  .app-nav.drawer-open .tab-group,
+  .app-nav.drawer-open .tab-menu,
+  .app-nav.drawer-open .tab-menu[hidden] {
+    display: block; position: static;
+    max-height: none; opacity: 1; overflow: visible; pointer-events: auto;
+  }
+  .app-nav.drawer-open .tab-parent {
+    display: flex; height: auto; padding: 6px 10px;
+    font-size: 11px; color: var(--faint);
+  }
+  .app-nav.drawer-open .tab-parent .nav-ico {
+    display: block; opacity: 1; width: 16px; height: 16px;
+  }
+  .app-nav.drawer-open .tab-parent .nav-label { max-width: 120px; opacity: 1; }
+  .app-nav.drawer-open .tab-item:not([data-primary]),
+  .app-nav.drawer-open .tab-item[data-primary] {
+    display: block; width: 100%; min-height: 44px; padding: 10px 12px;
+    border-radius: 8px; font-size: 14px; text-align: left;
+  }
+  .app-nav.drawer-open .tab-item[data-primary].active { box-shadow: none; background: var(--primary-soft); }
+  .app-nav.drawer-open .tab-menu-sep,
+  .app-nav.drawer-open .tab-menu-label,
+  .app-nav.drawer-open .tab-menu-sub { display: block; }
+  .app-nav.drawer-open .nav-more { display: none; }
+  .nav-close { display: grid; }
+
+  /* ---------- 12 张表全部卡片化 ---------- */
+  .table-wrap { max-height: none; overflow: visible; }
+  table, #tab-ledger table { min-width: 0; width: 100%; table-layout: auto; }
+  thead { display: none; }
+  tbody, tbody tr { display: block; }
+  tbody tr {
+    margin-bottom: 10px; padding: 10px 12px;
+    background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius);
+  }
+  tbody td {
+    display: flex; gap: 10px; align-items: baseline;
+    padding: 4px 0; border: 0; text-align: left;
+  }
+  tbody td::before {
+    content: attr(data-label);
+    flex: 0 0 92px; color: var(--muted); font-size: 12px;
+  }
+  tbody td[colspan]:not(.empty)::before { content: none; }
+  tbody td[colspan] { display: block; text-align: center; padding: 18px 0; }
+  tbody td.num { text-align: left; }
+  /* 账本页原本写死列宽且 table-layout:fixed，窄屏必须一并复位 */
+  #tab-ledger .lg-chat, #tab-ledger .lg-kind, #tab-ledger .lg-num,
+  #tab-ledger .lg-range, #tab-ledger .lg-ops, #tab-ledger .lg-when,
+  #tab-ledger .lg-who {
+    width: auto; white-space: normal; overflow: visible; text-overflow: clip;
+  }
+
+  /* ---------- 弹窗改全屏 sheet ---------- */
+  .modal-mask { align-items: flex-end; }
+  .modal, .modal.wide {
+    width: 100%; max-width: none; max-height: 92dvh;
+    border-radius: 16px 16px 0 0;
+    padding: 18px 16px calc(18px + env(safe-area-inset-bottom));
+  }
+  .pp-body { max-height: none; flex: 1 1 auto; }
+  .modal-actions { flex-wrap: wrap; }
+  .modal-actions > .btn { min-width: 0; flex: 1 1 auto; }
+  .modal-actions > .act-left { margin-right: 0; }
+  .plugin-page { height: calc(100dvh - 170px); min-height: 320px; }
+  .sticky-actions { bottom: calc(58px + env(safe-area-inset-bottom)); }
+}
+
+/* ---------- 触摸设备：达标触控目标（参考 snowluma 的 pointer:coarse 分支） ---------- */
+@media (hover: none) and (pointer: coarse) {
+  .icon-btn, .nav-toggle { width: 44px; height: 44px; }
+  .app-nav .tab-item, .pp-tab, .btn.small { min-height: 44px; }
+  .chip-x { min-width: 36px; min-height: 44px; }
+  .status-pill { min-height: 40px; }
+}
+
+/* ---------- 减少动效 ---------- */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: .01ms !important;
+    transition-duration: .01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ============================================================
+   侧栏交互（2026-11-07）：收起 / 分组折叠
+   ------------------------------------------------------------
+   顶栏汉堡在三档里的职责：
+     ≥1024      收起 / 展开侧栏（状态存 localStorage）
+     721–1023   展开 / 收回图标条
+     ≤720       打开全量抽屉
+   ============================================================ */
+
+/* 汉堡在桌面也常驻，作为「收起侧栏」开关 */
+.nav-toggle { display: grid; }
+
+/* 分组标题可点，chevron 指示折叠态 */
+.app-nav .tab-parent { cursor: pointer; }
+.app-nav .tab-group .tab-parent .chev {
+  display: block; width: 12px; height: 12px; opacity: .55;
+  margin-left: auto;
+  transform: rotate(180deg);
+  transition: transform .18s var(--ease);
+}
+.app-nav .tab-group.group-collapsed .tab-parent .chev { transform: rotate(0deg); }
+
+/*
+ * 折叠态只在侧栏形态生效；手机抽屉始终展开全部分组，
+ * 免得在抽屉里还要先点开分组才能找到页签。
+ */
+@media (min-width: 721px) {
+  .app-nav .tab-group.group-collapsed .tab-menu,
+  .app-nav .tab-group.group-collapsed .tab-menu[hidden] {
+    max-height: 0; opacity: 0; pointer-events: none;
+  }
+}
+
+/* 桌面收起：60px 图标条，复用平板那套 data-icon 首字 */
+@media (min-width: 1024px) {
+  body.nav-compact .app-nav { width: 60px; }
+  body.nav-compact main { margin-left: 60px; }
+  body.nav-compact .app-nav .nav-scroll { padding: 10px 6px; }
+  body.nav-compact .app-nav .tab-group { margin-bottom: 6px; }
+  body.nav-compact .app-nav .tab-parent {
+    height: 44px; padding: 0; justify-content: center; color: var(--muted);
+  }
+  body.nav-compact .app-nav .tab-parent .nav-ico { display: block; opacity: 1; }
+  body.nav-compact .app-nav .tab-parent .nav-label { max-width: 0; opacity: 0; }
+  body.nav-compact .app-nav .tab-parent .chev { display: none; }
+  body.nav-compact .app-nav .tab-menu,
+  body.nav-compact .app-nav .tab-menu[hidden] {
+    max-height: 0; opacity: 0; pointer-events: none;
+  }
+}
+
+/* ---------- 收起 / 折叠的收尾细节 ---------- */
+
+/* 图标条里没地方放折叠箭头，这两条要写在 chevron 通用规则之后才压得住 */
+@media (min-width: 721px) and (max-width: 1023px) {
+  .app-nav:not(.expanded) .tab-group .tab-parent .chev { display: none; }
+}
+@media (min-width: 1024px) {
+  body.nav-compact .app-nav .tab-group .tab-parent .chev { display: none; }
+}
+
+/* 抽屉上滑淡入，别硬邦邦地铺满 */
+@keyframes drawer-in {
+  from { opacity: .55; transform: translateY(14px); }
+  to { opacity: 1; transform: none; }
+}
+.app-nav.drawer-open { animation: drawer-in .24s var(--ease); }
+
+/* 分组标题暗示可点；折叠态不再压暗（整列只剩标题，压暗会糊成一片，
+   折叠状态由 chevron 的旋转方向指示，不靠变淡） */
+.app-nav .tab-parent:hover { color: var(--text-2); }
+
+/* ============================================================
+   过渡打磨（2026-11-07）：把「跳变」换成连续运动
+   ------------------------------------------------------------
+   只追加动效声明，不改任何尺寸 / 颜色 / 布局数值，也不新增 CSS 变量
+   （契约脚本对 cssVarDefs 做双向比对，多一个变量就会 FAIL）。
+
+   对标（§11 调研 + GitHub 动效规范实测 2026-11-07）：
+     · 时长阶梯：hover ≈150ms / 状态切换 200–300ms / drawer·modal·accordion 300–400ms
+       （better-react-web-ui「100/300/500」、skillmd animation.md、motionlint STANDARDS.md）
+     · 曲线只留两条：沿用本文件自带 --ease（强 ease-out，进入 / 展开），
+       drawer / bottom-sheet 用 cubic-bezier(.32,.72,0,1)（iOS 曲线）
+     · 只动 transform / opacity，不再给 height / width 增加动画（布局属性是性能反模式）
+     · 入场 scale 不从 0 起（健康区间 .95–.97），退场比入场快约 20%
+
+   现场三类「生硬」根因：
+     1. 切页是 display:none → block，内容凭空出现；
+     2. 分组折叠用 max-height:1600px → 0，前大半程看不出变化、最后一瞬收完；
+     3. 图标 / 箭头靠 display 切换「啪」地出现，颜色硬切，时长普遍只有 .12–.18s。
+   ============================================================ */
+
+/* 1. 切页：内容轻微上移淡入，不再瞬间闪现。
+      弹窗 DOM 在 </main> 之外、sticky-actions 是 position:sticky，
+      所以动画期间的 transform 不会把 fixed 元素锚到面板上。 */
+@keyframes panel-in {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: none; }
+}
+main > .panel.active {
+  animation: panel-in .3s var(--ease) both;
+}
+
+/* 2. 侧栏收起 / 主区让位：两者必须同一节奏，否则会一先一后地错开 */
+.app-nav { transition: width .34s var(--ease), box-shadow .3s ease; }
+main { transition: margin-left .34s var(--ease); }
+
+/* 3. 分组折叠：高度收拢的同时内容同步上移淡出，盖住 max-height 的空转段 */
+.app-nav .tab-menu,
+.app-nav .tab-menu[hidden] {
+  transition:
+    max-height .36s var(--ease),
+    opacity .24s ease,
+    transform .36s var(--ease);
+  transform-origin: top center;
+}
+@media (min-width: 721px) {
+  .app-nav .tab-group.group-collapsed .tab-menu,
+  .app-nav .tab-group.group-collapsed .tab-menu[hidden] {
+    transform: translateY(-8px);
+    /* 退场比入场快一档：用户已经决定收起，不必等动画慢慢同意 */
+    transition-duration: .28s, .2s, .28s;
+  }
+}
+
+/* 4. 文字 / 图标 / 箭头：颜色不硬切，出现时带一点缩放而不是凭空跳出 */
+@keyframes nav-ico-in {
+  from { opacity: 0; transform: scale(.92); }
+  to   { opacity: 1; transform: none; }
+}
+.app-nav .tab-parent { transition: color .18s ease, opacity .22s ease; }
+.app-nav .tab-item {
+  transition: background-color .2s ease, color .2s ease,
+    opacity .2s ease, box-shadow .2s ease;
+}
+.app-nav .tab-parent .nav-label {
+  transition: max-width .34s var(--ease), opacity .26s ease;
+}
+.app-nav .tab-parent .nav-ico { transition: opacity .26s ease; }
+.app-nav .tab-group .tab-parent .chev {
+  transition: transform .3s var(--ease), opacity .22s ease;
+}
+@media (min-width: 1024px) {
+  body.nav-compact .app-nav .tab-parent .nav-ico {
+    animation: nav-ico-in .3s var(--ease) both;
+  }
+}
+@media (min-width: 721px) and (max-width: 1023px) {
+  .app-nav.expanded .tab-parent .chev {
+    animation: nav-ico-in .3s var(--ease) both;
+  }
+}
+
+/* 5. 手机抽屉：容器淡入上滑，内容再分层入场，不再整块糊上来 */
+@keyframes drawer-in {
+  from { opacity: .35; transform: translateY(22px); }
+  to   { opacity: 1; transform: none; }
+}
+@keyframes drawer-content-in {
+  from { opacity: 0; transform: translateY(14px); }
+  to   { opacity: 1; transform: none; }
+}
+@media (max-width: 720px) {
+  .app-nav.drawer-open {
+    box-shadow: var(--shadow-lg);
+    animation: drawer-in .36s cubic-bezier(.32, .72, 0, 1) both;
+  }
+  .app-nav.drawer-open .nav-head {
+    animation: drawer-content-in .38s var(--ease) .04s both;
+  }
+  .app-nav.drawer-open .nav-scroll {
+    animation: drawer-content-in .42s var(--ease) .08s both;
+  }
+}
+
+/* 6. 弹窗：入场位移看得见；手机改成从底部滑上来的 sheet */
+@keyframes modal-fade { from { opacity: 0 } to { opacity: 1 } }
+@keyframes modal-pop {
+  from { opacity: 0; transform: translateY(14px) scale(.97); }
+  to   { opacity: 1; transform: none; }
+}
+@keyframes sheet-in {
+  from { opacity: .7; transform: translateY(100%); }
+  to   { opacity: 1; transform: none; }
+}
+.modal-mask { animation: modal-fade .24s ease both; }
+.modal { animation: modal-pop .28s var(--ease) both; }
+@media (max-width: 720px) {
+  .modal { animation: sheet-in .36s cubic-bezier(.32, .72, 0, 1) both; }
+}