weflow-cli 1.7.0 → 1.8.1

package/resources/panel/panel.css

@@ -0,0 +1,415 @@
+/* 面板的样式。刻意不引任何外部资源（CSP 是 default-src 'none'），也没有字体图标。 */
+:root {
+  --bg: #17181c;
+  --panel: #1f2126;
+  --line: #2e3138;
+  --text: #e6e7ea;
+  --dim: #9aa0aa;
+  --accent: #4c8bf5;
+  --warn: #e0a23c;
+  --err: #e5645f;
+  /* 球多大。CSS 拿不到 JS 的值，所以这里是**第二份**——与 `ball-position.cjs` 的
+     `BALL_SIZE`（main.cjs 也从那里取）必须一致，`test/panel-packaging.test.ts` 断言这一点。 */
+  --ball-size: 96px;
+  /* 气泡多大、离球多远、圆角多少。同样是 `ball-position.cjs`（`BUBBLE_SIZE` / `BUBBLE_GAP`）
+     的第二份拷贝：JS 那边用它算窗口矩形，CSS 这边用它排版，两边必须一致——有测试钉住。 */
+  --bubble-width: 420px;
+  /* 气泡的高度**会被页面改**（屏幕不够高时变矮，好让球仍然待在窗口的角上不动），
+     这个值是页面还没说话时的默认。`ball-position.cjs` 的 BUBBLE_SIZE.height 是同一个数。 */
+  --bubble-height: 560px;
+  --bubble-gap: 12px;
+  --bubble-radius: 14px;
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  height: 100%;
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 14px/1.55 -apple-system, "Segoe UI", "Microsoft YaHei", system-ui, sans-serif;
+}
+
+/* 有外壳时窗口是**透明的**：展开后窗口比气泡大一圈，多出来的是球占的那条与它们之间的空隙，
+   那一圈必须能透出桌面（用户要的就是"图标旁边冒出一个气泡"）。所以底色不能再画在 body 上，
+   改由 `#bubble` 自己画。降级那条路（没有 shell，页面铺满整个浏览器窗）照旧用 body 的底色。 */
+html:has(body.shell),
+body.shell { background: transparent; }
+
+body { display: flex; flex-direction: column; }
+
+/* ---------------------------------------------------------------- 对话气泡 */
+
+/* 单独一层：自己的圆角与底色。**不用 `overflow: hidden`**——尾巴是它的子节点，
+   会被一起剪掉；代价只是带底色的那几条要自己圆角（目前只有 header）。 */
+#bubble {
+  position: relative;              /* 尾巴的定位基准 */
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  background: var(--bg);
+}
+
+/* 有外壳时它是屏幕上一块**面板**，钉在窗口里离球最远的那条边上（球在窗口那一角，
+   气泡占剩下的地方）。窗口这一整块的尺寸由主进程一次算好（`bubbleLayout`），
+   页面这边只管"贴哪条边"。 */
+body.shell #bubble {
+  position: fixed;
+  width: var(--bubble-width);
+  min-width: var(--bubble-width);
+  height: var(--bubble-height);
+  border-radius: var(--bubble-radius);
+}
+/* 气泡钉在窗口离球最远的那一侧，竖向与球同边（球贴窗口底 → 气泡也贴底，反之亦然）。
+   窗口整块的尺寸由主进程算（`bubbleLayout`），这里只负责"球在哪一侧、贴哪条边"。 */
+body.shell.bubble-left #bubble { left: 0; }
+body.shell.bubble-right #bubble { right: 0; }
+body.shell.anchor-top #bubble { top: 0; }
+body.shell:not(.anchor-top) #bubble { bottom: 0; }
+
+/* 小尾巴：指向球的一个斜方块。它贴在气泡靠球那条边上，高度对球心——
+   球贴窗口底时球心离底 38px（76 高），尾巴 12 高，所以 bottom: 32px。
+   底色取那一条子元素的 --panel（底对齐时是输入栏，顶对齐时是标题栏，两处同色）。 */
+#tail {
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  background: var(--panel);
+  transform: rotate(45deg);
+}
+body.shell.bubble-left #tail { right: -6px; bottom: 32px; }
+body.shell.bubble-right #tail { left: -6px; bottom: 32px; }
+body.shell.anchor-top #tail { bottom: auto; top: 32px; }
+
+header {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--line);
+  background: var(--panel);
+  -webkit-app-region: drag;          /* Electron 里整条顶栏可以拖窗 */
+}
+
+.brand { font-weight: 600; }
+.status { color: var(--dim); font-size: 12px; }
+
+/* ---------------------------------------------------------------- 悬浮球形态 */
+
+#ball {
+  /* 球**一直在场**（有外壳时，见下面 `body.shell`）：展开成气泡时它不消失、不淡出，
+     就地待着当锚点——用户要的是"这个图标在说话"，说话的人当然不能先撤了。
+     浏览器降级那条路靠这条 `display: none` 永远看不见球（那一侧 `hidden` 属性也还在）。 */
+  display: none;
+  /* 固定尺寸、钉在窗口的某个角上（下面的 shell 规则给角）：**尺寸不跟着窗口长**，
+     否则展开过程中会看到一只被拉成巨型的猫。球形态下窗口就是 76×76，铺满即整窗。 */
+  position: fixed;
+  width: var(--ball-size);
+  height: var(--ball-size);
+  z-index: 2;               /* 压在气泡之上：气泡要从它后面滑出来 */
+  border-radius: 50%;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+  /* **不要在这里写 `-webkit-app-region: drag`**：Windows 上拖拽区会吞掉鼠标事件，
+     页面收不到 click，球就点不开了（实测的故障就是这个）。拖动自己实现，见 renderer.js。 */
+
+  /* 球本身**没有底色**：下面那层 `.glow` 才是"背景"，上面 `.face` 是吉祥物。
+     **换 `mascot.png` 时：内容必须全部落在内切圆里。** 球（连 `.face` 自己）都是
+     `border-radius: 50%`，图会被裁成圆的——而这张图的内容一向是**铺满画布**的
+     （2026-09-27 那版源图 1254²，内容占 98%），直接铺上去，角上的东西就没了：
+     实测绿气泡整块（10,368 个实心像素）落在圆外。所以出图时按
+     「实心像素到内容中心的最远距离 ≤ 0.98 × 半径」缩放，再居中贴到 256²：
+     现图 1226x1247 → 214x218，圆外实心像素 0，占画布 84%x85%。
+     **余量留 2%（不是 0）是有用的**：悬停时球放大到 1.02，那 2% 正好兜住，
+     实测 1.02 倍时圆外只剩 1 个像素；压到 0.98 以下就没地方放这个放大了。
+     （上一版源图 1024²、内容 600x689 时靠"裁到包围盒 + 12% 余量"就够，
+     那是因为它的内容本来只占 59%x67%——**余量是结果，不是规则**。） */
+  background-color: transparent;
+
+  /* 投影跟着猫的轮廓走（不是跟着那个不存在的圆），透明主体靠它跟浅色壁纸分开 */
+  filter: drop-shadow(0 6px 12px rgba(0, 0, 0, .50));
+  /* 回弹曲线（不是 ease）：松手时从压扁弹回原状会**轻微过冲**一下，那就是"弹"的感觉。
+     窗口就是球这么大，过冲出来的那点边缘靠出图时留的 2% 余量兜住。 */
+  transition: transform .16s cubic-bezier(.34, 1.56, .64, 1), filter .16s ease;
+}
+
+body.shell #ball { display: grid; }
+/* 球钉在窗口的**某一个角**上，由气泡在哪一侧、贴哪条边决定（`ball-position.cjs` 的
+   `bubbleLayout` 保证那个角就是球原来所在的位置）。
+   **这条是"球全程不动"的全部**：窗口改大小时，只要球所在的这个角没动，球在屏幕上的位置
+   就不动——哪怕窗口是在页面收到通知之前就变大了。上一版让球按坐标钉、窗口逐帧补间，
+   窗口每改一次大小，球都要等页面把新坐标设回来才回位，那就是用户看到的"闪好多"。 */
+body.shell #ball { right: 0; bottom: 0; }
+body.shell.bubble-right #ball { right: auto; left: 0; }
+body.shell.anchor-top #ball { bottom: auto; top: 0; }
+#ball > span { position: absolute; inset: 0; border-radius: 50%; pointer-events: none; }
+
+#ball .glow {
+  background: none;
+}
+
+/* 光晕**只在有状态时画出来**。做成软边光晕而不是硬边圆盘：硬边就又回到"一只盘子"了，
+   而软边在浅底与深底上都只是"猫身后的一团光"，不需要再靠一圈亮环去定边界。 */
+body.busy #ball .glow,
+body.offline #ball .glow,
+body.quota #ball .glow {
+  background:
+    radial-gradient(circle at 50% 46%,
+      hsl(var(--hue) 82% 58% / .95) 0%,
+      hsl(calc(var(--hue) + 26) 78% 46% / .78) 38%,
+      hsl(calc(var(--hue) + 44) 70% 38% / .32) 62%,
+      transparent 78%);
+}
+
+/* 上面那层：吉祥物本体，形状不变 */
+#ball .face {
+  background-image: url('/panel/mascot.png');
+  background-size: 100%;
+  background-position: center;
+  background-repeat: no-repeat;
+}
+
+/* 三个**真状态**各有一张脸：忙（思考中）、连不上时委屈、额度用完时累。
+   接的全是现成的状态类（`setBallState` 早就挂 busy/offline/quota 了），**不新增状态机**；
+   光晕照旧画——它是"余光能看见"的环境灯，表情是盯着看才见的细节，两者说的是同一件事，
+   一个给余光一个给注视，不重复。
+   **这三条必须写在下面 `ball-happy` 之前**：CSS 同特异性时后写的赢，而"用户正捏着它"
+   比"助手在忙"更该被看见（你捏它的时候它就该笑）。
+
+   `mascot-thinking.png`（2026-09-29 换的，前身叫 `mascot-focus.png`）：`busy` 的含义就是
+   "发出请求、在等回复"（`renderer.js` 的 `ask()` 一进来就挂上），所以这张脸画的是**思考**
+   ——眼神往左上瞟、眉平、嘴是一条平线、爪子搁在下巴上。出图用 `gpt-image-2-ca` 走
+   `/images/edits`（拿 `mascot.png` 当底，只改表情），再按上面那套参数归一化：
+   内容框 171x212、最远实心距离 125.2（上限 125.4）、**圆外实心像素 0**。
+   第一版提示词出的是"发愁"（嘴向下弯、眉压低），与 `sorry` 那张撞情绪，所以提示词里
+   明确写了"不是难过、不是发愁"。 */
+body.busy #ball .face { background-image: url('/panel/mascot-thinking.png'); }
+body.offline #ball .face { background-image: url('/panel/mascot-sorry.png'); }
+body.quota #ball .face { background-image: url('/panel/mascot-tired.png'); }
+
+/* 被捏一下时的脸：眯眼笑。**硬切，不做淡入** —— 换表情本来就是一帧的事，淡入反而像
+   "图片正在加载"。两张图是用**同一套裁剪与缩放参数**从同一张源图生成的（实测差异只有
+   3.5% 的像素，全部落在眼睛那一条上），所以切的时候脸不会跳、尺寸也不变。
+   改 `background-image` 只此一处，`.face` 的基础规则仍在上面那条里。 */
+body.ball-happy #ball .face {
+  background-image: url('/panel/mascot-happy.png');
+}
+
+/* 色相流动 —— 现在只在**忙碌**时跑（空闲时那一层根本不画）。
+   8 秒一圈由 `body.busy` 那条给；色相本身只是被 `drift` 驱动的数值。 */
+@property --hue { syntax: '<number>'; inherits: true; initial-value: 224; }
+#ball { --hue: 224; }
+@keyframes drift {
+  0%   { --hue: 224; }        /* 蓝 */
+  25%  { --hue: 268; }        /* 紫 */
+  50%  { --hue: 316; }        /* 品红 */
+  75%  { --hue: 190; }        /* 青 */
+  100% { --hue: 224; }
+}
+
+/* **空闲时球后面什么都没有**（2026-09-26 改）。
+
+   这一层原来一直亮着，那是用户当初要的"会变动的背景"。但两个代价在用过之后才显出来：
+   球背后永远有一圈彩色圆盘，**"这张图是透明的"这件事根本看不出来**；而它同时兼着状态灯，
+   一直亮着就等于没有状态灯——离线、忙碌、额度用完，球长得都一样。
+
+   现在：**静止 = 只有猫，亮起来 = 有话说**。这是那条需求的**范围缩小，不是取消**——
+   色相流动还在，只是改在忙碌时发生（下面那条）。 */
+
+/* ---------------------------------------------------------------- 状态 */
+
+/* 正在想事情：光晕变亮、转得快，并且轻轻呼吸。
+   这一条的用处不只是好看——球收起来的时候，此前**完全看不出它在干活**。 */
+body.busy #ball .glow {
+  /* 8 秒转一圈色相（不是 3 秒）：呼吸的节奏交给 1.5s，色相再快就变成闪了 */
+  animation: drift 8s linear infinite, breathe 1.5s ease-in-out infinite;
+}
+@keyframes breathe {
+  0%, 100% { transform: scale(1); opacity: 1; }
+  50% { transform: scale(1.08); opacity: .82; }
+}
+
+/* 连不上 / 出错：换成暖色并停住流动——不动的东西才会被注意到 */
+body.offline #ball { --hue: 12; }
+body.offline #ball .glow { animation: none; opacity: .9; }
+
+/* 今天的额度用完了：琥珀色 */
+body.quota #ball { --hue: 38; }
+body.quota #ball .glow { animation: none; opacity: .85; }
+
+/* 系统说"减少动态效果"就照办：停掉所有流动，只留静止的光晕。
+   展开/收起那两段也一起停（下面那几条，**写在原来那条之后**——测试盯的是这一段开头
+   240 个字符里就有 `animation: none`，把新规则插在前面会把它挤出窗口）。 */
+@media (prefers-reduced-motion: reduce) {
+  #ball .glow,
+  body.busy #ball .glow { animation: none; }
+  body.mode-chat #bubble { animation: none; }
+  body.mode-chat.closing #bubble { animation: none; opacity: 0; }
+  #ball { transition: none; }
+  /* 形变也要停。只关 transition 的话，悬停/按下会**瞬间**跳到放大/压扁的形状，
+     那看起来更像故障而不是"少动一点"。 */
+  #ball:hover, #ball:active { transform: none; }
+}
+
+/* 悬停：微微放大 + 阴影加深 + 提亮 —— 三样一起才够"这里能点"。
+   **放大只敢到 1.02**：出图按"实心像素最远点 ≤ 0.98 × 半径"缩放（见 `.face` 那段），
+   1.02 倍时圆外只剩 1 个像素（实测），再大就开始削掉猫的外缘。 */
+#ball:hover { transform: scale(1.02); filter: drop-shadow(0 8px 16px rgba(0, 0, 0, .58)) brightness(1.08); }
+/* 按下：压扁。**只往小里做** —— 放大或位移会把内容顶出窗口、被窗口边裁掉。 */
+#ball:active { transform: scale(.92); }
+
+/* 球形态：把气泡整个藏掉，窗口缩回球那么大（96x96，主进程那边做）。
+   底色早就不是 body 的了（见上面 `body.shell` 那两条）——气泡自己画，窗口是透明的。 */
+body.mode-ball #bubble { display: none; }
+/* 球形态下不许出现滚动条：busy 的呼吸动画会 scale(1.08)，
+   溢出的那点内容会在球那 96x96 的窗口里长出滚动条（实测：右侧冒出上下箭头）。 */
+body.mode-ball { overflow: hidden; }
+
+/* 对话形态（有外壳时）才显示"收起" */
+body.mode-chat #collapse { display: inline-block; }
+
+/* header 顶在气泡的圆角上，得自己把上面两个角修圆（气泡那层没开 overflow: hidden，
+   开了会把尾巴剪掉）。只有它需要：下面几层的底边不是气泡的底边（footer 才是，而它没有底色）。 */
+body.shell header { border-radius: var(--bubble-radius) var(--bubble-radius) 0 0; }
+
+/* 展开时气泡淡进来。放在**稳定态那个类**上（不是临时的过渡类）：只要页面变成对话形态
+   就播一次——第一次打开、从球展开、托盘展开都算，它本来就是"气泡出现了"这件事。
+   **这段动画是全部动效**：窗口那边主进程是一次到位的，不逐帧改大小——透明窗口每 resize
+   一次 DWM 就要重新合成一次，用户实测"闪好多才弹出"就是这么来的。这里只动 opacity 与
+   transform，合成器直接做，不重新布局、不改窗口。
+   `transform-origin` 取球那一侧：气泡看起来是从球那儿"长出来"的，而不是凭空出现。
+   **不给 `main` 加 transform**：`#log` 是滚动容器，加位移会多出一个包含块。 */
+/* 原点取球心那一侧：球贴窗口底时球心离底 38px（球 76 高），贴顶时离顶 38px */
+body.mode-chat #bubble {
+  transform-origin: right calc(100% - 38px);
+  animation: bubble-in .2s cubic-bezier(.2, .8, .2, 1) both;
+}
+body.mode-chat.bubble-right #bubble { transform-origin: left calc(100% - 38px); }
+body.mode-chat.anchor-top #bubble { transform-origin: right 38px; }
+body.mode-chat.bubble-right.anchor-top #bubble { transform-origin: left 38px; }
+@keyframes bubble-in {
+  from { opacity: 0; transform: scale(.94); }
+  to   { opacity: 1; transform: none; }
+}
+
+/* 收起：先把气泡淡掉（**窗口这会儿还是大的**，所以这 130ms 真看得见），主进程等这段时间
+   过去再缩窗口，缩完才通知页面把气泡摘掉（`display: none`）。顺序不能反：提前摘掉就成了
+   "啪"地消失，晚摘掉就会在球那 96x96 的窗口里露出一条气泡的边。
+   **这里用 animation 而不是 transition**：上面那条 `bubble-in` 带着 `both` 填充，而动画在
+   层叠里**压过**过渡——写 `opacity: 0` 会被它一直覆盖着，收起时看着就像没反应。
+   两条都是动画时，靠"更靠后的选择器 + 更高的特指度"（多一个 `.closing`）取胜。 */
+body.mode-chat.closing #bubble { animation: bubble-out .13s ease both; }
+@keyframes bubble-out {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+.ghost {
+  margin-left: auto;
+  background: transparent;
+  color: var(--dim);
+  border: 1px solid var(--line);
+  padding: 2px 10px;
+  font-weight: 400;
+  -webkit-app-region: no-drag;
+}
+.ghost:hover { color: var(--text); }
+
+main {
+  flex: 1;
+  overflow-y: auto;
+  padding: 12px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.turn { max-width: 92%; white-space: pre-wrap; word-break: break-word; }
+.turn.me { align-self: flex-end; background: var(--accent); color: #fff; padding: 7px 11px; border-radius: 12px 12px 2px 12px; }
+.turn.it { align-self: flex-start; background: var(--panel); padding: 7px 11px; border-radius: 12px 12px 12px 2px; }
+.turn.sys { align-self: center; color: var(--dim); font-size: 12px; text-align: center; }
+.turn.err { align-self: stretch; border: 1px solid var(--err); color: var(--err); padding: 7px 11px; border-radius: 10px; }
+.turn.pending { color: var(--dim); font-style: italic; }
+
+/* 助手回答下的复制按钮。**常显**而不是 hover 才出现：这是个常驻小窗，
+   鼠标常常不在它上面，hover 等于没有。做得很淡，不跟正文抢注意力。 */
+.turn .copy {
+  display: block;
+  margin-top: 6px;
+  padding: 1px 7px;
+  font: inherit;
+  font-size: 11px;
+  color: var(--dim);
+  background: transparent;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  cursor: pointer;
+}
+.turn .copy:hover { color: var(--text); border-color: var(--dim); }
+
+/* ---------------------------------------------------------------- 还没聊过时的开头 */
+
+.empty {
+  margin: auto 0;                 /* 垂直居中一点，不要贴着顶 */
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 8px 2px;
+}
+.empty-title { font-weight: 600; }
+.empty-sub { color: var(--dim); font-size: 12px; margin-bottom: 6px; }
+
+/* 例子做成扁平的胶囊按钮：全局 button 那套（蓝底、大内边距）在这儿太重了 */
+.chip {
+  background: transparent;
+  border: 1px solid var(--line);
+  color: var(--text);
+  font-weight: 400;
+  font-size: 13px;
+  padding: 5px 12px;
+  border-radius: 999px;
+}
+.chip:hover { border-color: var(--accent); color: #fff; }
+
+form {
+  display: flex;
+  gap: 8px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--line);
+  background: var(--panel);
+}
+
+textarea {
+  flex: 1;
+  resize: none;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--bg);
+  color: var(--text);
+  font: inherit;
+}
+textarea:focus { outline: none; border-color: var(--accent); }
+
+button {
+  padding: 0 16px;
+  border: 0;
+  border-radius: 8px;
+  background: var(--accent);
+  color: #fff;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+button:disabled { opacity: .45; cursor: default; }
+
+footer {
+  padding: 6px 14px 10px;
+  color: var(--dim);
+  font-size: 12px;
+}
+footer .warn { color: var(--warn); }

package/resources/panel/preload.cjs

@@ -0,0 +1,79 @@
+/**
+ * 渲染进程与主进程之间**唯一**的那道缝。
+ *
+ * 刻意只暴露三件事，而且全是窗口层面的：**没有凭据、没有端口、没有文件系统、没有 URL**。
+ * 页面自己用 `fetch('/api/...')` 跟守护进程说话（相对路径 + HttpOnly cookie），
+ * 不需要经过主进程，所以也就没有理由把凭据递给它。
+ *
+ * 订阅只开**一个**，而且通道名**写死在这里**：风险从来不是"能收推送"，而是
+ * "渲染进程能决定通道名"——那等于把整条 IPC 面交出去。所以不给通用的 `on(name, cb)`。
+ */
+const { contextBridge, ipcRenderer } = require('electron')
+
+contextBridge.exposeInMainWorld('weflowPanel', {
+  /**
+   * 'ball' 收成小球，'chat' 展开成对话窗。
+   *
+   * `opts.animate === false` 表示"别做动画，直接到位"——页面读 `prefers-reduced-motion`
+   * 之后传进来。**为什么让页面来读**：那个媒体查询只有渲染进程有，主进程这边没有等价 API；
+   * 而窗口几何的补间在主进程，CSS 管不着它。默认是**动画**（不传就是动画）。
+   */
+  setMode: (mode, opts) => ipcRenderer.invoke('panel:setMode',
+    mode === 'chat' ? 'chat' : 'ball',
+    { animate: !opts || opts.animate !== false }),
+  /** 'window' 只关窗（助手继续跑），'assistant' 连助手一起停 */
+  quit: (what) => ipcRenderer.invoke('panel:quit', what === 'assistant' ? 'assistant' : 'window'),
+  /**
+   * 拖拽。**为什么不是 `-webkit-app-region: drag`**：在 Windows 上拖拽区会**吞掉鼠标事件**，
+   * 页面收不到 click——球就点不开了（这正是实测到的故障）。所以拖拽改成自己实现：
+   * 主进程记下按下时的窗口位置与指针位置，移动时按差值 setPosition。
+   */
+  dragStart: (x, y) => ipcRenderer.invoke('panel:dragStart', { x, y }),
+  dragMove: (x, y) => ipcRenderer.invoke('panel:dragMove', { x, y }),
+  dragEnd: () => ipcRenderer.invoke('panel:dragEnd'),
+
+  /**
+   * 右键快速回复：把名单交给主进程去弹**原生菜单**，返回用户选中的那个名字（没选就是 null）。
+   *
+   * 为什么菜单要由主进程弹：原生菜单画在窗口外面，所以球形态那 76x76 的窗口不用先展开成
+   * 对话窗——而"点右键顺手把窗口弹出来"正是用户不要的那一下。
+   * 名单在这里**收窄**：只要字符串、去掉空的、最多 20 个（主进程那侧还会再去一次重）。
+   */
+  openQuickMenu: (labels) => ipcRenderer.invoke('panel:quickMenu',
+    (Array.isArray(labels) ? labels : [])
+      .filter((name) => typeof name === 'string' && name.trim())
+      .map((name) => name.trim())
+      .slice(0, 20)),
+
+  /** 主进程侧的实际状态，供界面显示"关窗后助手还在跑"这类事实 */
+  info: () => ipcRenderer.invoke('panel:info'),
+  /**
+   * 凭据失效时请主进程换一张（重读端点文件 + 刷新 cookie + 重载）。
+   *
+   * 页面**看不到 token**，也不该看到——所以这件事只能由主进程做，页面只负责触发。
+   * 助手没在跑、或 token 本来就没变时它**不重载**，返回一个 code 让页面自己决定怎么说。
+   */
+  repair: () => ipcRenderer.invoke('panel:repair'),
+  /**
+   * 主进程把窗口切成了球形态/气泡形态时通知页面。**通道名是常量，不由调用方给**。
+   *
+   * 载荷在这里**收窄**过再交出去：`mode` 只认 'ball'/'chat'，`side` 只认 'left'/'right'，
+   * `anchorY` 只认 'top'/'bottom'，`bubbleHeight` 夹进 1..10000，`fadeMs` 夹进 0..2000，
+   * `done` 只认布尔。跟通道名同一个道理——不把主进程给的东西原样透传。
+   */
+  onMode: (cb) => {
+    if (typeof cb !== 'function') return
+    const clampInt = (value, max, min = 0) => {
+      const n = Math.round(Number(value))
+      return Number.isFinite(n) ? Math.min(Math.max(n, min), max) : min
+    }
+    ipcRenderer.on('panel:mode', (_event, payload) => cb({
+      mode: payload && payload.mode === 'ball' ? 'ball' : 'chat',
+      side: payload && payload.side === 'right' ? 'right' : 'left',
+      anchorY: payload && payload.anchorY === 'top' ? 'top' : 'bottom',
+      bubbleHeight: clampInt(payload && payload.bubbleHeight, 10000, 1),
+      fadeMs: clampInt(payload && payload.fadeMs, 2000),
+      done: !!(payload && payload.done),
+    }))
+  },
+})