zcode-pro 0.17.2 → 0.18.0

package/src/inject/features/settings-dialog.js

@@ -15,12 +15,18 @@ function openExternal(url) {
 // 检查更新 → 升级（helper 后台任务，轮询进度，输出取最后一行、超长省略中间）→
 // 进行中可停止；关弹窗不中断升级，重开恢复显示。endpoint 为 /headroom 或 /rtk，
 // metaRefresh 在升级完成后刷新各面板自己的版本行与配置。
-function makeUpgradeControls({ endpoint, metaRefresh }) {
+function makeUpgradeControls({ endpoint, metaRefresh, idleText }) {
   const L = t();
   const state = h('span', { class: 'min-w-0 flex-1 truncate text-left text-ui-xs/relaxed text-foreground-subtle' });
-  // 失败原因在状态行直显红字（toast 只有 5 秒且易被弹窗遮挡）
+  // 失败原因在状态行直显红字（toast 只有 5 秒且易被弹窗遮挡）。
+  // idleText：空闲（无检查/升级活动）时该槽位显示调用方给的文本——rtk/headroom
+  // 面板用它显示本体位置；一旦有活动（检查中/下载进度/结果），活动文本顶替位置
+  const hasIdle = () => typeof idleText === 'function';
   const setState = (text, kind = '') => {
-    state.textContent = text;
+    const shown = text || (hasIdle() ? (idleText() || '') : '');
+    // 「 · 」前缀：与前面的版本行无缝拼成「插件 x · rtk y · 状态/路径」一行；
+    // 错误信息不加前缀——它是独立提示，拼在版本行后会读成版本的一部分
+    state.textContent = shown ? (kind === 'error' ? shown : ` · ${shown}`) : '';
     state.className = 'min-w-0 flex-1 truncate text-left text-ui-xs/relaxed '
       + (kind === 'error' ? 'text-destructive' : 'text-foreground-subtle');
   };
@@ -129,6 +135,8 @@ function makeUpgradeControls({ endpoint, metaRefresh }) {
     const res = await rpc(endpoint + '/upgrade');
     if (res.ok && res.upgrade && res.upgrade.running) pollStart();
   })();
+  // 初始化为空闲态（有 idleText 时即显示位置等空闲文本）
+  setState('');
   return { btn, state, stop: stopPoll };
 }
 
@@ -323,7 +331,7 @@ export function openSettingsDialog() {
       const runPluginsUpdate = async () => {
         pluginsBtn.disabled = true;
         pluginsStatusLine.textContent = L.pluginsUpdating;
-        const res = await rpc('/plugins/update', { method: 'POST', body: { installMissing: true } });
+        const res = await rpc('/plugins/update', { method: 'POST', body: {} });
         pluginsBtn.disabled = false;
         if (!res.ok) {
           pluginsStatusLine.textContent = '';
@@ -376,7 +384,8 @@ export function openSettingsDialog() {
       const paneVision = h('div', { role: 'tabpanel', class: 'mt-4', style: 'display:none' });
       const paneRtk = h('div', { role: 'tabpanel', class: 'mt-4', style: 'display:none' });
       const paneHeadroom = h('div', { role: 'tabpanel', class: 'mt-4', style: 'display:none' });
-      const panes = { features: paneFeatures, styles: paneStyles, perf: panePerf, agents: paneAgents, proxy: paneProxy, sync: paneSync, vision: paneVision, headroom: paneHeadroom, rtk: paneRtk };
+      const paneDebug = h('div', { role: 'tabpanel', class: 'mt-4', style: 'display:none' });
+      const panes = { features: paneFeatures, styles: paneStyles, perf: panePerf, agents: paneAgents, proxy: paneProxy, sync: paneSync, vision: paneVision, headroom: paneHeadroom, rtk: paneRtk, debug: paneDebug };
       const tabDefs = [
         ['features', L.tabFeatures],
         ['styles', L.tabStyles],
@@ -387,6 +396,9 @@ export function openSettingsDialog() {
         ['vision', L.tabVision],
         ['headroom', L.tabHeadroom],
         ['rtk', L.tabRtk],
+        // “调试”标签页只对开发模式生效的用户显示（配置开关或 ZCODEPRO_DEV=1），
+        // 普通用户不可见
+        ...(config.devMode === true || config.devActive === true ? [['debug', L.tabDebug]] : []),
       ];
       const tablist = h('div', { role: 'tablist', 'aria-orientation': 'horizontal', class: 'zcodepro-tablist mt-4' });
       const renderTabs = () => tablist.replaceChildren(...tabDefs.map(([id, label]) =>
@@ -483,6 +495,7 @@ export function openSettingsDialog() {
         styleCell(L.rowGapName, L.rowGapDesc, 'rowGap'),
         styleCell(L.userLineHeightName, L.userLineHeightDesc, 'userLineHeight', { min: 1, max: 3, step: 0.05, unit: 'x' }),
         styleCell(L.lineHeightName, L.lineHeightDesc, 'lineHeight', { min: 1, max: 3, step: 0.05, unit: 'x' }),
+        styleCell(L.thinkingLineHeightName, L.thinkingLineHeightDesc, 'thinkingLineHeight', { min: 1, max: 3, step: 0.05, unit: 'x' }),
         styleCell(L.codeLineHeightName, L.codeLineHeightDesc, 'codeLineHeight', { min: 1, max: 3, step: 0.05, unit: 'x' }),
         styleCell(L.listSpacingName, L.listSpacingDesc, 'listSpacing'),
         styleCell(L.listItemSpacingName, L.listItemSpacingDesc, 'listItemSpacing'),
@@ -635,6 +648,12 @@ export function openSettingsDialog() {
       const proxyTestBtn = btnSmall(L.proxyTest, () => { void runProxyTest(); }, 'shrink-0');
       const runProxyTest = async () => {
         if (proxyTesting) return;
+        // 空地址不发请求（等网络超时才报「检测失败」的体验太差），立即提示
+        if (!proxyInput.value.trim()) {
+          proxyTestState.className = 'mt-2 text-ui-xs/relaxed text-amber-500';
+          proxyTestState.textContent = L.proxyTestEmpty;
+          return;
+        }
         proxyTesting = true;
         proxyTestBtn.disabled = true;
         proxyTestBtn.textContent = L.proxyTesting;
@@ -655,6 +674,39 @@ export function openSettingsDialog() {
         proxyTestState.className = 'mt-2 text-ui-xs/relaxed ' + (allOk ? 'text-foreground-subtle' : 'text-amber-500');
         proxyTestState.textContent = `${res.proxy}：${parts.join(' · ')}`;
       };
+      // 代理生效范围（即时保存，每个开关只改自己那项）：插件市场更新与插件依赖
+      // 软件默认开，同步默认关——国内网盘直连即可，代理停了同步会跟着失败
+      const persistProxyScope = async (partial) => {
+        const res = await rpc('/config', { method: 'POST', body: { proxyScopes: partial } });
+        if (!res.ok) {
+          showToast(L.failed + ': ' + errText(res), 'error');
+          return false;
+        }
+        if (res.config && res.config.proxyScopes) config.proxyScopes = res.config.proxyScopes;
+        return true;
+      };
+      const proxyScopeWrap = h('div');
+      const renderProxyScopes = () => {
+        const sc = config.proxyScopes || {};
+        proxyScopeWrap.replaceChildren(
+          settingRow(L.proxyScopePlugins, L.proxyScopePluginsDesc, sc.plugins !== false, async () => {
+            const next = !(sc.plugins !== false);
+            if (await persistProxyScope({ plugins: next })) sc.plugins = next;
+            renderProxyScopes();
+          }),
+          settingRow(L.proxyScopeDeps, L.proxyScopeDepsDesc, sc.deps !== false, async () => {
+            const next = !(sc.deps !== false);
+            if (await persistProxyScope({ deps: next })) sc.deps = next;
+            renderProxyScopes();
+          }),
+          settingRow(L.proxyScopeSync, L.proxyScopeSyncDesc, sc.sync === true, async () => {
+            const next = !(sc.sync === true);
+            if (await persistProxyScope({ sync: next })) sc.sync = next;
+            renderProxyScopes();
+          }),
+        );
+      };
+      renderProxyScopes();
       paneProxy.append(
         h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.proxyDesc),
         h('div', { class: 'mt-3 flex items-center gap-2' },
@@ -663,6 +715,7 @@ export function openSettingsDialog() {
           proxyTestBtn),
         h('p', { class: 'mt-2 text-ui-xs/relaxed text-foreground-subtle' }, L.proxyHint),
         proxyTestState,
+        h('div', { class: 'mt-3 divide-y divide-border rounded-xl border border-border' }, proxyScopeWrap),
       );
 
       // “性能”：空闲项目内存回收（开关 + 两个时长）。idleReclaimStartupMinutes
@@ -712,8 +765,10 @@ export function openSettingsDialog() {
 
       // “同步”：把 ZCode Pro 设置与模型设置手动备份到 WebDAV / 从 WebDAV 恢复
       // （交互参考 Tampermonkey：URL/登录/密码 + 手动触发，无自动同步）。仅 WebDAV
-      // 一种后端且本就只在点击时传输，不设“类型/禁用”下拉。表单显式保存；
-      // 同步内容开关即时保存；下载会覆盖本机，先弹二次确认
+      // 一种后端且本就只在点击时传输，不设“类型/禁用”下拉。表单显式保存（旁有
+      // 「测试」用当前表单值验证连通）；同步内容开关即时保存；下载先弹云端版本
+      // 列表（固定名 = 最新 + 带时间戳的历史），任选一个导入，导入会覆盖本机、
+      // 先弹二次确认
       const savedSync = (config.sync && typeof config.sync === 'object') ? config.sync
         : { url: '', dir: 'zcode-pro', login: '', password: '', include: { zcodepro: true, model: true }, lastPushAt: null, lastPullAt: null };
       const syncInputCls = 'h-8 w-full rounded-lg border border-border bg-input px-2.5 text-ui-sm text-foreground outline-none transition-shadow placeholder:text-foreground-subtle focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/40';
@@ -761,6 +816,44 @@ export function openSettingsDialog() {
           syncCheckDirty();
         }
       };
+      // 「测试」：用表单当前值（先测再存）验证 WebDAV：连接与凭据 → 上传目录
+      // （缺则自动建，等同上传时的行为）→ 文件列表；结果仿“代理”标签页的检测，
+      // 一行显示各步耗时与云端备份文件数
+      const syncTestState = h('p', { class: 'mt-2 text-ui-xs/relaxed text-foreground-subtle' });
+      let syncTesting = false;
+      const syncTestBtn = btnSmall(L.syncTest, () => { void runSyncTest(); }, 'shrink-0');
+      const runSyncTest = async () => {
+        if (syncTesting) return;
+        // 没填 URL 不发请求（等超时才报“测试失败”的体验太差），立即提示
+        if (!syncUrlInput.value.trim()) {
+          syncTestState.className = 'mt-2 text-ui-xs/relaxed text-amber-500';
+          syncTestState.textContent = L.syncTestEmpty;
+          return;
+        }
+        syncTesting = true;
+        syncTestBtn.disabled = true;
+        syncTestBtn.textContent = L.syncTesting;
+        syncTestState.textContent = '';
+        syncTestState.className = 'mt-2 text-ui-xs/relaxed text-foreground-subtle';
+        const res = await rpc('/sync/test', { method: 'POST', body: { sync: syncFormValues() } });
+        syncTesting = false;
+        syncTestBtn.disabled = false;
+        syncTestBtn.textContent = L.syncTest;
+        if (!res.ok) {
+          syncTestState.className = 'mt-2 text-ui-xs/relaxed text-destructive';
+          syncTestState.textContent = L.syncTestFailed + ': ' + errText(res);
+          return;
+        }
+        const stepName = { connect: L.syncTestStepConnect, dir: L.syncTestStepDir, list: L.syncTestStepList };
+        const parts = (res.targets || []).map((t) =>
+          `${stepName[t.step] || t.step} ${t.ok ? '✓' + (t.ms != null ? ' ' + t.ms + 'ms' : '') : '✗ ' + (t.error || t.httpCode || '')}`.trim());
+        const allOk = (res.targets || []).length > 0 && (res.targets || []).every((t) => t.ok);
+        let host = syncUrlInput.value.trim();
+        try { host = new URL(host).host; } catch { /* 非法输入保留原文 */ }
+        syncTestState.className = 'mt-2 text-ui-xs/relaxed ' + (allOk ? 'text-foreground-subtle' : 'text-amber-500');
+        syncTestState.textContent = `${host}：${parts.join(' · ')}`
+          + (allOk && res.fileCount != null ? `（${L.syncTestFilesFound.replace('{n}', res.fileCount)}）` : '');
+      };
       // 坚果云推荐行：外链经宿主 openExternal 打开系统浏览器（无该能力时只出纯文字）
       const JIANGUO_HELP = 'https://help.jianguoyun.com/?p=2064';
       const syncRecLine = h('p', { class: 'mt-1 text-ui-xs/relaxed text-foreground-subtle' });
@@ -798,61 +891,199 @@ export function openSettingsDialog() {
         );
       };
       renderSyncInclude();
-      // 上次操作时间 + 上传/下载按钮；下载覆盖本机，需二次确认
+      // 上次操作时间 + 上传/下载按钮；上传固定名与历史版本双写，下载弹云端版本列表
       const fmtSyncTime = (ts) => (ts ? new Date(ts).toLocaleString() : L.syncNever);
       const syncStatusLine = h('div', { class: 'text-ui-xs/relaxed text-foreground-subtle' });
       const renderSyncStatus = (s) => {
         syncStatusLine.textContent = `${L.syncLastPush} ${fmtSyncTime(s.lastPushAt)} · ${L.syncLastPull} ${fmtSyncTime(s.lastPullAt)}`;
       };
       renderSyncStatus(savedSync);
-      const syncUploadBtn = btnSmall(L.syncUpload, () => { void runSyncDirection('push'); }, 'shrink-0', 'primary');
-      const syncDownloadBtn = btnSmall(L.syncDownload, () => { confirmSyncDownload(); }, 'shrink-0');
-      const confirmSyncDownload = () => {
+      const syncUploadBtn = btnSmall(L.syncUpload, () => { void runSyncPush(); }, 'shrink-0', 'primary');
+      const syncDownloadBtn = btnSmall(L.syncDownload, () => { openSyncVersionPicker(); }, 'shrink-0');
+      // 「从云端下载」先弹版本列表（备份管理器的样子）：列出云端目录里的备份文件
+      // （固定名 = 最新一版 + 带时间戳的历史），每行可导入到本机 / 从云端删除 /
+      // 另存到本机磁盘；导入按文件名前缀决定覆盖哪一项，不受“同步内容”勾选影响
+      const openSyncVersionPicker = () => {
         openDialog({
-          title: L.syncConfirmTitle,
-          description: L.syncConfirmDesc,
-          width: 'sm:max-w-md',
-          onMount: ({ body: confirmBody, close: closeConfirm }) => {
-            confirmBody.append(
-              dialogFooter(
-                btnSecondary(L.cancel, () => closeConfirm()),
-                btnPrimary(L.syncConfirmGo, () => { closeConfirm(); void runSyncDirection('pull'); }, 'min-w-24'),
-              ),
-            );
+          title: L.syncPickTitle,
+          description: L.syncPickDesc,
+          width: 'max-w-2xl',
+          dismissOnOutside: false,
+          onMount: async ({ body: pickBody, content, close: closePicker }) => {
+            // 标题栏 ✕（设置弹窗同款）；h2 也是拖拽把手，✕ 上要拦住 mousedown 冒泡
+            const titleEl = content && content.firstElementChild;
+            if (titleEl && titleEl.tagName === 'H2') {
+              titleEl.classList.add('flex', 'w-full', 'items-center', 'justify-between');
+              titleEl.replaceChildren(
+                h('span', { class: 'flex min-w-0 items-center' }, L.syncPickTitle),
+                h('button', {
+                  type: 'button',
+                  class: 'zcodepro-close',
+                  title: L.close,
+                  'aria-label': L.close,
+                  onMousedown: (e) => { e.stopPropagation(); },
+                  onClick: () => { closePicker(); },
+                }, '✕'),
+              );
+            }
+            const listWrap = h('div', { class: 'space-y-1' });
+            pickBody.append(listWrap);
+            const fmtSize = (n) => {
+              if (!Number.isFinite(n) || n <= 0) return '';
+              return n >= 1048576 ? (n / 1048576).toFixed(2) + ' MB' : Math.max(1, Math.round(n / 1024)) + ' KB';
+            };
+            const setStatus = (el) => { listWrap.replaceChildren(el); };
+            const setRowBusy = (btns, busy) => { for (const b of btns) b.disabled = busy; };
+            const versionRow = (f) => {
+              // 固定名（zcodepro.json / model.json）不含时间戳段，始终是最新一版；
+              // 归属哪项同步内容由分组标题说明，行内不再重复
+              const isLatest = !/-\d{4}-\d{2}-\d{2}T/.test(f.name);
+              const importBtn = btnSmall(L.syncVerImport, () => { confirmImport(f, rowBtns, importBtn); }, 'shrink-0');
+              const deleteBtn = btnSmall(L.syncVerDelete, () => { confirmDelete(f, rowBtns, isLatest); }, 'shrink-0');
+              const saveBtn = btnSmall(L.syncVerSave, () => { void exportVersion(f, rowBtns, saveBtn); }, 'shrink-0');
+              const rowBtns = [importBtn, deleteBtn, saveBtn];
+              return h('div', { class: 'flex items-center gap-3 rounded-xl border border-border px-3 py-2' },
+                h('div', { class: 'min-w-0 flex-1' },
+                  h('div', { class: 'flex min-w-0 items-center gap-1.5' },
+                    h('span', { class: 'truncate font-mono text-ui-xs text-foreground', title: f.name }, f.name),
+                    ...(isLatest ? [h('span', { class: 'shrink-0 rounded border border-border px-1.5 text-ui-xs text-foreground-subtle' }, L.syncVerLatest)] : [])),
+                  h('div', { class: 'mt-0.5 text-ui-xs/relaxed text-foreground-subtle' },
+                    [fmtSize(f.size), f.lastModified ? new Date(f.lastModified).toLocaleString() : ''].filter(Boolean).join(' · '))),
+                h('div', { class: 'flex shrink-0 items-center gap-1.5' }, importBtn, deleteBtn, saveBtn));
+            };
+            const loadList = async () => {
+              setStatus(h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.syncPickLoading));
+              const res = await rpc('/sync/versions', { method: 'POST', body: {} });
+              if (!res.ok) {
+                setStatus(h('p', { class: 'text-ui-sm text-destructive' }, L.failed + ': ' + errText(res)));
+                return;
+              }
+              const files = res.files || [];
+              if (!files.length) {
+                setStatus(h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.syncPickEmpty));
+                return;
+              }
+              // 按同步内容分组排列：组标题下固定名（最新）放最上面，历史版本按
+              // 时间新→旧往下——两组文件多了也不会按时间交错混排
+              const parts = [];
+              for (const [prefix, label] of [['zcodepro', L.syncIncludeZcp], ['model', L.syncIncludeModel]]) {
+                const group = files.filter((f) => f.name === `${prefix}.json` || f.name.startsWith(`${prefix}-`));
+                if (!group.length) continue;
+                const latest = group.find((f) => f.name === `${prefix}.json`);
+                const history = group.filter((f) => f !== latest)
+                  .sort((a, b) => ((b.lastModified || 0) - (a.lastModified || 0)) || b.name.localeCompare(a.name));
+                parts.push(h('div', { class: 'px-1 pt-2 text-ui-xs font-medium text-foreground-subtle' },
+                  `${label}${isZhLocale() ? '（' : ' ('}${group.length}${isZhLocale() ? '）' : ')'}`));
+                for (const f of [latest, ...history]) {
+                  if (f) parts.push(versionRow(f));
+                }
+              }
+              listWrap.replaceChildren(...parts);
+            };
+            // 导入沿用原有的覆盖确认文案，并注明选中的是哪个文件
+            const confirmImport = (f, rowBtns, importBtn) => {
+              openDialog({
+                title: L.syncConfirmTitle,
+                width: 'sm:max-w-md',
+                onMount: ({ body: confirmBody, close: closeConfirm }) => {
+                  confirmBody.append(
+                    h('p', { class: 'mb-2 truncate font-mono text-ui-xs text-foreground-subtle', title: f.name }, f.name),
+                    h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.syncConfirmDesc),
+                    dialogFooter(
+                      btnSecondary(L.cancel, () => closeConfirm()),
+                      btnPrimary(L.syncConfirmGo, () => { closeConfirm(); void importVersion(f, rowBtns, importBtn); }, 'min-w-24'),
+                    ),
+                  );
+                },
+              });
+            };
+            const importVersion = async (f, rowBtns, importBtn) => {
+              setRowBusy(rowBtns, true);
+              importBtn.textContent = L.syncVerImporting;
+              const res = await rpc('/sync/version/apply', { method: 'POST', body: { file: f.name } });
+              setRowBusy(rowBtns, false);
+              importBtn.textContent = L.syncVerImport;
+              if (!res.ok) {
+                showToast(L.failed + ': ' + errText(res), 'error');
+                return;
+              }
+              closePicker();
+              renderSyncStatus(res.sync || {});
+              // 该版本已落到本机：刷新弹窗内开关显示，并让常驻功能立即按新配置生效
+              clearConfigCache();
+              window.dispatchEvent(new CustomEvent('zcodepro:config-changed'));
+              Object.assign(config, await getConfig(true));
+              refreshRows();
+              renderToolbarSwitch();
+              const names = (res.applied || [])
+                .map((k) => (k === 'model' ? L.syncIncludeModel : L.syncIncludeZcp))
+                .join(isZhLocale() ? '、' : ', ');
+              showToast(names ? `${L.syncDownloaded}（${names}）` : L.syncDownloaded, 'success');
+            };
+            const confirmDelete = (f, rowBtns, isLatest) => {
+              openDialog({
+                title: L.syncVerDeleteTitle,
+                width: 'sm:max-w-md',
+                onMount: ({ body: confirmBody, close: closeConfirm }) => {
+                  confirmBody.append(
+                    h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' },
+                      L.syncVerDeleteDesc,
+                      h('span', { class: 'font-mono' }, f.name)),
+                    // 删“最新”文件会让旧版 zcode-pro 失去下载入口，多提醒一句
+                    ...(isLatest ? [h('p', { class: 'mt-2 text-ui-xs/relaxed text-amber-500' }, L.syncVerDeleteLatestNote)] : []),
+                    dialogFooter(
+                      btnSecondary(L.cancel, () => closeConfirm()),
+                      btnPrimary(L.syncVerDelete, () => { closeConfirm(); void deleteVersion(f, rowBtns); }, 'min-w-24'),
+                    ),
+                  );
+                },
+              });
+            };
+            const deleteVersion = async (f, rowBtns) => {
+              setRowBusy(rowBtns, true);
+              const res = await rpc('/sync/version/delete', { method: 'POST', body: { file: f.name } });
+              setRowBusy(rowBtns, false);
+              if (!res.ok) {
+                showToast(L.failed + ': ' + errText(res), 'error');
+                return;
+              }
+              showToast(L.syncVerDeleted, 'success');
+              void loadList();
+            };
+            const exportVersion = async (f, rowBtns, saveBtn) => {
+              setRowBusy(rowBtns, true);
+              saveBtn.textContent = L.syncVerSaving;
+              // 宿主会弹系统目录选择器选保存位置；用户取消时不作提示
+              const res = await rpc('/sync/version/export', { method: 'POST', body: { file: f.name } });
+              setRowBusy(rowBtns, false);
+              saveBtn.textContent = L.syncVerSave;
+              if (!res.ok) {
+                if (res.code !== 'export-cancelled') showToast(L.failed + ': ' + errText(res), 'error');
+                return;
+              }
+              showToast(`${L.syncVerSaved} ${res.path}`, 'success');
+            };
+            void loadList();
           },
         });
       };
-      const runSyncDirection = async (direction) => {
+      // 上传：云端固定名（最新）与时间戳历史版本由服务端一并写入云端；下载期间按钮也
+      // 禁用（列表在变，选了也会过期）
+      const runSyncPush = async () => {
         syncUploadBtn.disabled = true;
         syncDownloadBtn.disabled = true;
-        const btn = direction === 'push' ? syncUploadBtn : syncDownloadBtn;
-        const idleText = btn.textContent;
-        btn.textContent = direction === 'push' ? L.syncUploading : L.syncDownloading;
-        const res = await rpc('/sync/run', { method: 'POST', body: { direction } });
+        const idleText = syncUploadBtn.textContent;
+        syncUploadBtn.textContent = L.syncUploading;
+        const res = await rpc('/sync/run', { method: 'POST', body: { direction: 'push' } });
         syncUploadBtn.disabled = false;
         syncDownloadBtn.disabled = false;
-        btn.textContent = idleText;
+        syncUploadBtn.textContent = idleText;
         if (!res.ok) {
           showToast(L.failed + ': ' + errText(res), 'error');
           return;
         }
         renderSyncStatus(res.sync || {});
-        if (direction === 'pull') {
-          // 云端配置已落到本机：刷新弹窗内开关显示，并让常驻功能立即按新配置生效
-          clearConfigCache();
-          window.dispatchEvent(new CustomEvent('zcodepro:config-changed'));
-          Object.assign(config, await getConfig(true));
-          refreshRows();
-          renderToolbarSwitch();
-        }
-        // 下载 toast 标明本次覆盖了哪几项（两项独立成文件，可能只覆盖了一项）
-        if (direction === 'push') showToast(L.syncUploaded, 'success');
-        else {
-          const names = (res.applied || [])
-            .map((k) => (k === 'model' ? L.syncIncludeModel : L.syncIncludeZcp))
-            .join(isZhLocale() ? '、' : ', ');
-          showToast(names ? `${L.syncDownloaded}（${names}）` : L.syncDownloaded, 'success');
-        }
+        showToast(L.syncUploaded, 'success');
       };
       paneSync.append(
         h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.syncDesc),
@@ -865,7 +1096,8 @@ export function openSettingsDialog() {
             h('div', { class: 'min-w-0' },
               h('p', { class: 'text-ui-xs/relaxed text-foreground-subtle' }, L.syncFormHint),
               syncRecLine),
-            syncSaveBtn)),
+            h('div', { class: 'flex shrink-0 items-center gap-1.5' }, syncSaveBtn, syncTestBtn))),
+        syncTestState,
         h('div', { class: 'mt-2 divide-y divide-border rounded-xl border border-border' }, syncIncludeWrap),
         h('div', { class: 'mt-2 flex items-center justify-between gap-2 rounded-xl border border-border p-2' },
           h('div', { class: 'min-w-0' }, syncStatusLine),
@@ -873,6 +1105,48 @@ export function openSettingsDialog() {
         h('p', { class: 'mt-2 text-ui-xs/relaxed text-foreground-subtle' }, L.syncHint),
       );
 
+      // “调试”：开发模式开关 + 重载按钮。重载 = 构建 → 换新启动器进程（新 helper
+      // 代码与新注入脚本）→ 各 ZCode 窗口检测到换代自动整页刷新重新注入；
+      // ZCode 本体与所有会话不受影响，不用重启 ZCode
+      const persistDevMode = async (v) => {
+        const res = await rpc('/config', { method: 'POST', body: { devMode: v } });
+        if (!res.ok) {
+          showToast(L.failed + ': ' + errText(res), 'error');
+          return false;
+        }
+        if (res.config) config.devMode = res.config.devMode;
+        return true;
+      };
+      const devReloadBtn = btnSmall(L.devReload, () => { void runDevReload(); }, 'shrink-0', 'primary');
+      const runDevReload = async () => {
+        devReloadBtn.disabled = true;
+        devReloadBtn.textContent = L.devReloading;
+        // 旧进程应答后即退出，fetch 可能中断，成败都进入下面的兜底刷新
+        try { await rpc('/dev/reload', { method: 'POST', body: {} }); } catch { /* ignore */ }
+        // 兜底：正常情况下新启动器注入时本页会自动刷新；2 秒没动静（交接失败）
+        // 就自己刷新，宁可多刷一次也不能停在旧代码 + 失效 token 上
+        setTimeout(() => { try { location.reload(); } catch { /* ignore */ } }, 2000);
+      };
+      const devModeWrap = h('div');
+      const renderDevPane = () => {
+        const dev = config.devMode === true;
+        devModeWrap.replaceChildren(
+          h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.devModeDesc),
+          h('div', { class: 'mt-3 divide-y divide-border rounded-xl border border-border' },
+            settingRow(L.devMode, L.devModeRowDesc, dev, async () => {
+              if (await persistDevMode(!dev)) renderDevPane();
+            }),
+            ...(dev ? [h('div', { class: 'flex items-center justify-between gap-2 px-2 py-1.5' },
+              h('div', { class: 'min-w-0' },
+                h('div', { class: 'text-ui-sm font-medium text-foreground' }, L.devReload),
+                h('div', { class: 'mt-0.5 text-ui-xs/relaxed text-foreground-subtle' }, L.devReloadDesc)),
+              devReloadBtn)] : []),
+          ),
+        );
+      };
+      renderDevPane();
+      paneDebug.append(devModeWrap);
+
       // “视觉代理”：编辑 ~/.zcode/zcode-vision.json（zcode-vision 插件与 /vision-* 命令共用同一文件）。
       // 代理列表顺序即执行链；结构性改动（开关/模式/排序/删增）即时保存，文本输入防抖保存。
       // 注意：保存时链按全部代理重建——若用 /vision-chain 配过子集链，会被这里覆盖（两套入口语义如此，面板以列表为准）。
@@ -915,7 +1189,55 @@ export function openSettingsDialog() {
         style: 'display:none',
       });
       const visionInputCls = 'h-8 w-full rounded-lg border border-border bg-input px-2.5 text-ui-sm text-foreground outline-none transition-shadow placeholder:text-foreground-subtle focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/40';
+      // 未装插件时的一键安装卡（与 Headroom 面板同款交互）：helper 单插件安装，
+      // 装完 onInstalled 原地恢复面板。rtk/vision 面板共用。
+      const pluginInstallCard = (pluginName, onInstalled) => {
+        const installBtn = btnSmall(L.headroomInstall, () => { void runInstall(); }, 'shrink-0');
+        const installState = h('div', { class: 'mt-0.5 truncate text-ui-xs/relaxed text-foreground-subtle' });
+        const runInstall = async () => {
+          installBtn.disabled = true;
+          installBtn.textContent = L.headroomInstalling;
+          installState.textContent = '';
+          const res = await rpc('/plugins/update', { method: 'POST', body: { name: pluginName } });
+          if (!res.ok) {
+            installBtn.disabled = false;
+            installBtn.textContent = L.headroomInstall;
+            showToast(L.pluginsUpdateFailed + ': ' + errText(res), 'error');
+            return;
+          }
+          if (onInstalled) await onInstalled();
+          showToast(L.pluginInstallDone.replaceAll('{name}', pluginName), 'success');
+        };
+        return h('div', { class: 'mt-3 flex items-center justify-between gap-2 rounded-xl border border-border p-2' },
+          h('div', { class: 'min-w-0' },
+            h('div', { class: 'text-ui-sm font-medium text-foreground' }, L.pluginInstallCardTitle.replaceAll('{name}', pluginName)),
+            h('div', { class: 'mt-0.5 text-ui-xs/relaxed text-foreground-subtle' }, L.pluginInstallCardDesc),
+            installState),
+          installBtn);
+      };
+
       const renderVision = () => {
+        if (!visionRes.ok) {
+          paneVision.replaceChildren(
+            h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.visionDesc),
+            h('p', { class: 'mt-2 text-ui-sm text-destructive' }, L.visionLoadFailed + ': ' + errText(visionRes)),
+          );
+          return;
+        }
+        // 插件未装优先显示安装卡——判断只看钩子（visionRes.hook），与配置文件是否存在无关：
+        // 配置是钩子消费的，没钩子就没功能；老用户卸载插件后 ~/.zcode/zcode-vision.json 仍在，
+        // 若按配置存在与否分流会误入完整配置界面而毫无「未安装」提示
+        if (!visionRes.hook) {
+          paneVision.replaceChildren(
+            h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.visionDesc),
+            pluginInstallCard('zcode-vision', async () => {
+              const meta = await rpc('/vision');
+              if (meta.ok) Object.assign(visionRes, meta);
+              renderVision();
+            }),
+          );
+          return;
+        }
         if (!visionCfg) {
           const initBtn = btnSmall(L.visionAddProxy, async () => {
             const res = await rpc('/vision', { method: 'POST', body: { config: VISION_DEFAULT_CFG } });
@@ -925,6 +1247,10 @@ export function openSettingsDialog() {
           paneVision.replaceChildren(
             h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.visionDesc),
             ...(visionRes.ok ? [] : [h('p', { class: 'mt-2 text-ui-sm text-destructive' }, L.visionLoadFailed + ': ' + errText(visionRes))]),
+            // 信息卡（仅版本行；配置未建，启用开关随配置出现）
+            h('div', { class: 'mt-3 rounded-xl border border-border p-2' },
+              h('div', { class: 'flex flex-wrap items-center gap-2' },
+                h('span', { class: 'shrink-0 whitespace-nowrap text-ui-xs/relaxed text-foreground-subtle' }, `插件 ${visionRes.pluginVersion || '—'}`))),
             h('div', { class: 'mt-3 flex justify-end' }, initBtn),
           );
           return;
@@ -1046,17 +1372,22 @@ export function openSettingsDialog() {
         });
         paneVision.replaceChildren(
           h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.visionDesc),
-          // 链模式 + 两个开关合到一行（顶部已有简介，开关不再单占一块、不带描述）
+          // 信息卡：插件版本 + 启用图片识别开关（与 rtk/headroom 面板同款式）
+          h('div', { class: 'mt-3 rounded-xl border border-border p-2' },
+            h('div', { class: 'flex flex-wrap items-center gap-2' },
+              h('span', { class: 'shrink-0 whitespace-nowrap text-ui-xs/relaxed text-foreground-subtle' }, `插件 ${visionRes.pluginVersion || '—'}`),
+              h('div', { class: 'ml-auto' },
+                settingRow(L.visionEnabled, '', visionCfg.enabled !== false, async () => {
+                  visionCfg.enabled = !(visionCfg.enabled !== false);
+                  await persistVision();
+                  renderVision();
+                })))),
+          // 链模式 + 强制拦截开关合到一行（启用开关已上移信息卡）
           h('div', { class: 'mt-3 flex flex-wrap items-center gap-x-4 gap-y-1.5 rounded-xl border border-border p-1' },
             h('span', { class: 'ml-1.5 shrink-0 text-ui-sm font-medium text-foreground' }, L.visionMode),
             modeBtn('fallback', L.visionModeFallback, L.visionModeFallbackDesc),
             modeBtn('pipeline', L.visionModePipeline, L.visionModePipelineDesc),
             h('div', { class: 'ml-auto flex items-center gap-4' },
-              settingRow(L.visionEnabled, '', visionCfg.enabled !== false, async () => {
-                visionCfg.enabled = !(visionCfg.enabled !== false);
-                await persistVision();
-                renderVision();
-              }),
               settingRow(L.visionForceIntercept, '', visionCfg.forceIntercept !== false, async () => {
                 visionCfg.forceIntercept = !(visionCfg.forceIntercept !== false);
                 await persistVision();
@@ -1122,15 +1453,20 @@ export function openSettingsDialog() {
         return res.ok;
       };
       const rtkInputCls = 'h-8 w-full rounded-lg border border-border bg-input px-2.5 text-ui-sm text-foreground outline-none transition-shadow placeholder:text-foreground-subtle focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/40';
-      // rtk 本体（GitHub Releases 下载替换）的版本行与升级控件，渲染函数外创建一次
+      // rtk 本体（GitHub Releases 下载替换）的版本行与升级控件，渲染函数外创建一次。
+      // 信息卡单行：版本行 + 弹性状态槽（空闲显示本体位置，检查更新/升级时被活动
+      // 日志顶替，见 makeUpgradeControls 的 idleText）+ 检查更新按钮 + 启用开关
       const rtkVersionLine = h('span', { class: 'shrink-0 whitespace-nowrap text-ui-xs/relaxed text-foreground-subtle' });
+      let rtkLocText = '';
       const renderRtkVersion = (meta) => {
-        const v = meta.version || 'rtk';
-        rtkVersionLine.textContent = meta.binPath ? `${v} · ${meta.binPath}` : v;
+        const v = String(meta.version || '').replace(/^rtk\s+/i, '').trim();
+        rtkVersionLine.textContent = `插件 ${meta.pluginVersion || '—'}${v ? ` · rtk ${v}` : ''}`;
+        rtkLocText = meta.binPath || '';
       };
       renderRtkVersion(rtkRes);
       const rtkUp = makeUpgradeControls({
         endpoint: '/rtk',
+        idleText: () => rtkLocText,
         metaRefresh: async () => {
           const meta = await rpc('/rtk');
           if (meta.ok) {
@@ -1143,15 +1479,50 @@ export function openSettingsDialog() {
       rtkUpgradePollStop = rtkUp.stop;
       // 版本/路径/检查更新 + 启用 rtk 压缩开关合到一行（开关靠右，顶部已有简介不带描述）
       const rtkSwitchRow = h('div');
-      const rtkVersionCard = h('div', { class: 'mt-3 flex items-center gap-2 rounded-xl border border-border p-2' },
-        rtkVersionLine, rtkUp.state, rtkUp.btn, rtkSwitchRow);
+      const rtkVersionCard = h('div', { class: 'mt-3 flex flex-wrap items-center gap-2 rounded-xl border border-border p-2' },
+        rtkVersionLine, rtkUp.state, rtkUp.btn,
+        h('div', { class: 'ml-auto shrink-0' }, rtkSwitchRow));
       const rtkBody = h('div');
-      // 简介置顶（与 Headroom 面板一致），其下版本卡（含启用 rtk 压缩开关），再下白名单
+      // 插件未装时的一键安装行（本体未装另有提示行），装完原地撤下
+      const rtkPluginRow = h('div');
+      const renderRtkPluginRow = () => {
+        rtkPluginRow.replaceChildren(...(rtkRes.hook ? [] : [
+          pluginInstallCard('rtk', async () => {
+            const meta = await rpc('/rtk');
+            if (meta.ok) {
+              Object.assign(rtkRes, meta);
+              // 版本行 span 与 rtkCfg 都是弹窗打开时的未装态快照，装完必须重算/重建
+              renderRtkVersion(meta);
+              // rtkCfg 整体重建（未装态时内置清单为空，不重建则白名单区块渲染旧空清单）
+              rtkCfg = {
+                installed: meta.installed !== false,
+                version: meta.version || '',
+                binPath: meta.binPath || '',
+                mode: meta.mode === 'off' ? 'off' : 'hint',
+                whitelist: Array.isArray(meta.whitelist) ? [...meta.whitelist] : [],
+                builtinGit: Array.isArray(meta.builtinGit) ? [...meta.builtinGit] : [],
+                builtinPlain: Array.isArray(meta.builtinPlain) ? [...meta.builtinPlain] : [],
+              };
+            }
+            renderRtkPluginRow();
+            renderRtk();
+          }),
+        ]));
+      };
+      renderRtkPluginRow();
+      // 简介置顶（与 Headroom 面板一致），其下插件安装卡，再下版本卡（含启用 rtk 压缩开关），再下白名单
       paneRtk.append(
         h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.rtkDesc),
+        rtkPluginRow,
         rtkVersionCard,
         rtkBody);
       const renderRtk = () => {
+        // 插件未装：只显示安装卡，隐藏版本卡与全部设置项（与 vision/headroom 未装时一致）
+        if (rtkRes.ok && !rtkRes.hook) {
+          rtkVersionCard.style.display = 'none';
+          rtkBody.replaceChildren();
+          return;
+        }
         rtkVersionCard.style.display = rtkCfg && rtkCfg.installed ? '' : 'none';
         if (!rtkCfg) {
           rtkBody.replaceChildren(
@@ -1195,7 +1566,45 @@ export function openSettingsDialog() {
         rtkBody.replaceChildren(
           ...(rtkCfg.installed
             ? []
-            : [h('p', { class: 'text-ui-sm text-amber-500' }, L.rtkNotInstalled)]),
+            : [h('div', { class: 'flex items-center gap-2' },
+                h('p', { class: 'min-w-0 flex-1 text-ui-sm text-amber-500' }, L.rtkNotInstalled),
+                // 一键安装本体：与“检查更新”同一条 helper 升级管线（未装则装到 ~/.local/bin）
+                (() => {
+                  const b = btnSmall(L.rtkInstallBin, () => { void run(); }, 'shrink-0');
+                  const run = async () => {
+                    b.disabled = true;
+                    b.textContent = L.headroomInstalling;
+                    const res = await rpc('/rtk', { method: 'POST', body: { upgrade: true } });
+                    if (!res.ok) {
+                      b.disabled = false;
+                      b.textContent = L.rtkInstallBin;
+                      showToast(L.failed + ': ' + errText(res), 'error');
+                      return;
+                    }
+                    const done = await new Promise((resolve) => {
+                      const iv = setInterval(async () => {
+                        const s = await rpc('/rtk/upgrade');
+                        if (s.ok && s.upgrade && !s.upgrade.running) { clearInterval(iv); resolve(s.upgrade); }
+                      }, 1200);
+                      // 超时也要 resolve：否则按钮永久停在“安装中…”
+                      setTimeout(() => { clearInterval(iv); resolve(null); }, 10 * 60 * 1000);
+                    });
+                    if (done && !done.error && done.version) {
+                      const meta = await rpc('/rtk');
+                      if (meta.ok) {
+                        Object.assign(rtkRes, meta);
+                        rtkCfg = { ...rtkCfg, installed: meta.installed !== false, version: meta.version || '', binPath: meta.binPath || '' };
+                      }
+                      showToast(L.rtkBinInstalled, 'success');
+                      renderRtk();
+                    } else {
+                      b.disabled = false;
+                      b.textContent = L.rtkInstallBin;
+                      showToast((done && done.error) || L.headroomInstallRetry, 'error');
+                    }
+                  };
+                  return b;
+                })())]),
           h('div', { class: 'mt-2 rounded-xl border border-border p-2' },
             h('div', { class: 'text-ui-sm font-medium text-foreground' }, L.rtkWhitelistTitle),
             h('p', { class: 'mt-1 text-ui-xs/relaxed text-foreground-subtle' }, L.rtkWhitelistDesc),
@@ -1243,15 +1652,18 @@ export function openSettingsDialog() {
       // 可整面重渲染：未装插件时显示安装卡，安装成功后原地恢复完整面板。
       // 版本行与本体升级控件（pip 通道）在渲染函数外创建一次，重渲染时复用同一组节点
       const hrVersionLine = h('span', { class: 'shrink-0 whitespace-nowrap text-ui-xs/relaxed text-foreground-subtle' });
+      let hrLocText = '';
+      // 启用开关（与 rtk 面板同款，版本卡右上角）：开 = ZCode 供应商走 headroom，
+      // 关 = 直连上游；只改供应商地址，不动代理进程（headroom 可被其他程序共用）
+      const hrSwitchRow = h('div');
       const renderHrVersion = (meta) => {
-        const parts = [];
-        if (meta.pluginVersion) parts.push(`${L.headroomVersionPlugin} ${meta.pluginVersion}`);
-        if (meta.version) parts.push(`${L.headroomVersionBin} ${meta.version}`);
-        hrVersionLine.textContent = parts.length ? parts.join(' · ') : `${L.headroomVersionPlugin} —`;
+        hrVersionLine.textContent = `插件 ${meta.pluginVersion || '—'}${meta.version ? ` · headroom ${meta.version}` : ''}`;
+        hrLocText = meta.binPath || '';
       };
       renderHrVersion(headroomRes);
       const hrUp = makeUpgradeControls({
         endpoint: '/headroom',
+        idleText: () => hrLocText,
         metaRefresh: async () => {
           const meta = await rpc('/headroom');
           if (meta.ok) {
@@ -1278,7 +1690,7 @@ export function openSettingsDialog() {
             installBtn.disabled = true;
             installBtn.textContent = L.headroomInstalling;
             installState.textContent = '';
-            const res = await rpc('/plugins/update', { method: 'POST', body: { name: 'headroom', installMissing: true } });
+            const res = await rpc('/plugins/update', { method: 'POST', body: { name: 'headroom' } });
             if (!res.ok) {
               installBtn.disabled = false;
               installBtn.textContent = L.headroomInstall;
@@ -1289,6 +1701,8 @@ export function openSettingsDialog() {
             if (meta.ok) Object.assign(headroomRes, meta);
             if (headroomRes.hook) {
               showToast(L.headroomInstalled, 'success');
+              // 版本行 span 在弹窗打开时按未装态算过一次，装完必须重算
+              renderHrVersion(headroomRes);
               renderHeadroomPane();
             } else {
               installBtn.disabled = false;
@@ -1312,16 +1726,65 @@ export function openSettingsDialog() {
         const hrRun = async (reqBody, warn) => {
           if (hrBusy) return false;
           hrBusy = true;
-          const res = await rpc('/headroom', { method: 'POST', body: reqBody });
-          hrBusy = false;
+          const action = reqBody && reqBody.action;
+          const isStart = action === 'start' || action === 'restart';
+          const isStop = action === 'stop';
+          // 生命周期按钮：点击瞬间就显示等待提示 + 计时（不等 RPC 返回——
+          // RPC 里 helper 要杀/拉进程，期间 3-10 秒界面不能毫无反应）
+          // RPC 先发出（不等返回——期间界面要显示等待反馈）
+          const rpcDone = rpc('/headroom', { method: 'POST', body: reqBody });
+          let timerIv = null;
+          if (isStart || isStop) {
+            const wantUp = isStart;
+            const msg = action === 'restart' ? L.hrRestarting : isStart ? L.hrStarting : L.hrStopping;
+            const doneMsg = isStart ? L.hrStarted : L.hrStopped;
+            const timeoutMs = isStart ? 90 * 1000 : 30 * 1000;
+            const t0 = Date.now();
+            const timerSpan = h('span', { class: 'text-ui-sm text-foreground-subtle/70' }, msg + ' (0s)');
+            hrStatusLine.replaceChildren(timerSpan);
+            timerIv = setInterval(() => {
+              timerSpan.textContent = msg + ` (${Math.round((Date.now() - t0) / 1000)}s)`;
+            }, 1000);
+            // RPC 完成后进入轮询（RPC 执行实际的 stop/start，可能要 3-10 秒）。
+            // 轮询出结果前 hrBusy 一直占着：期间再点开关或按钮直接忽略，否则
+            // 每次点击都会重发 start、把计时和启动流程从头来过
+            void (async () => {
+              const kick = await rpcDone;
+              if (!kick.ok) return; // 失败由主流程提示并复位
+              while (Date.now() - t0 < timeoutMs) {
+                await new Promise((r) => setTimeout(r, 2000));
+                const st = await rpc('/headroom/status');
+                if (!st.ok) continue;
+                const up = !!(st.status && st.status.up);
+                if (up === wantUp) {
+                  clearInterval(timerIv);
+                  hrBusy = false;
+                  await hrRefresh();
+                  showToast(doneMsg, isStart ? 'success' : undefined);
+                  return;
+                }
+              }
+              clearInterval(timerIv);
+              hrBusy = false;
+              if (isStart) showToast(L.hrStartTimeout, 'error');
+              void hrRefresh();
+            })();
+          }
+          const res = await rpcDone;
           if (!res.ok) {
+            if (timerIv) clearInterval(timerIv);
+            hrBusy = false;
             showToast(L.failed + ': ' + errText(res), 'error');
+            void hrRefresh();
             return false;
           }
           if (res.config) Object.assign(hrCfg, res.config);
           if (warn) showToast(warn);
-          // backend/power 动作会重启代理，稍等其就绪再刷状态，避免闪现“未运行”
-          setTimeout(() => { void hrRefresh(); }, 1200);
+          // 非生命周期动作（backend/power）：稍等后刷一次
+          if (!isStart && !isStop) {
+            hrBusy = false;
+            setTimeout(() => { void hrRefresh(); }, 1200);
+          }
           return true;
         };
         // 状态值本地化：钩子输出的是 auto/cpu/ac/ok 等内部值，面板显示成人话
@@ -1360,6 +1823,23 @@ export function openSettingsDialog() {
           hrHintLine.textContent = s.saverHint || '';
           hrHintLine.style.display = s.saverHint ? '' : 'none';
         };
+        // 启用开关不走 hrRun：与代理进程无关，点击即时生效，也不受生命周期等待锁影响
+        const renderHrUsageSwitch = () => {
+          const usageOn = !!(headroomRes.usage && headroomRes.usage.enabled);
+          hrSwitchRow.replaceChildren(
+            settingRow(L.pluginEnable, '', usageOn, async () => {
+              const next = !usageOn;
+              const res = await rpc('/headroom', { method: 'POST', body: { usage: next } });
+              if (!res.ok) {
+                showToast(L.failed + ': ' + errText(res), 'error');
+                return;
+              }
+              if (res.usage) headroomRes.usage = res.usage;
+              renderHrUsageSwitch();
+              if (next && !res.changed && !(res.usage && res.usage.enabled)) showToast(L.hrUsageNone);
+            }));
+        };
+        renderHrUsageSwitch();
         const hrRefreshBtn = btnSmall(L.headroomRefresh, () => { void hrRefresh(); });
         const hrStartBtn = btnSmall(L.headroomStart, () => { void hrRun({ action: 'start' }); });
         const hrRestartBtn = btnSmall(L.headroomRestart, () => { void hrRun({ action: 'restart' }); });
@@ -1453,14 +1933,60 @@ export function openSettingsDialog() {
         };
         updateHrPwrHint();
 
+        // 本体未装：一键安装（pip 全新安装通道，helper 同一条升级任务管线）；
+        // 装完刷新 meta 并整面重渲染（版本行、本体状态、代理控制全部就位）
+        const hrInstallBinBtn = (() => {
+          const b = btnSmall(L.hrInstallBin, () => { void run(); }, 'shrink-0');
+          let busy = false;
+          const run = async () => {
+            if (busy) return;
+            busy = true;
+            b.disabled = true;
+            b.textContent = L.headroomInstalling;
+            const res = await rpc('/headroom', { method: 'POST', body: { upgrade: true } });
+            if (!res.ok) {
+              b.disabled = false;
+              b.textContent = L.hrInstallBin;
+              showToast(L.failed + ': ' + errText(res), 'error');
+              busy = false;
+              return;
+            }
+            // pip 下载大包可持续数分钟，轮询后台任务到结束（超时 resolve，避免按钮卡死）
+            const done = await new Promise((resolve) => {
+              const iv = setInterval(async () => {
+                const s = await rpc('/headroom/upgrade');
+                if (s.ok && s.upgrade && !s.upgrade.running) { clearInterval(iv); resolve(s.upgrade); }
+              }, 2000);
+              setTimeout(() => { clearInterval(iv); resolve(null); }, 12 * 60 * 1000);
+            });
+            busy = false;
+            if (done && !done.error && done.version) {
+              const meta = await rpc('/headroom');
+              if (meta.ok) {
+                renderHrVersion(meta);
+                Object.assign(headroomRes, meta);
+              }
+              showToast(L.hrBinInstalled, 'success');
+              renderHeadroomPane();
+            } else {
+              b.disabled = false;
+              b.textContent = L.hrInstallBin;
+              showToast((done && done.error) || L.headroomInstallRetry, 'error');
+            }
+          };
+          return b;
+        })();
+
         paneHeadroom.append(
           h('p', { class: 'text-ui-sm/relaxed text-foreground-subtle' }, L.headroomDesc),
           ...(headroomRes.installed === false
-            ? [h('p', { class: 'mt-2 text-ui-sm text-amber-500' }, L.headroomBinMissing)]
+            ? [h('div', { class: 'mt-2 flex items-center gap-2' },
+                h('p', { class: 'min-w-0 flex-1 text-ui-sm text-amber-500' }, L.headroomBinMissing),
+                hrInstallBinBtn)]
             : []),
-          h('div', { class: 'mt-3 flex items-center justify-between gap-2 rounded-xl border border-border p-2' },
-            h('div', { class: 'flex min-w-0 items-center gap-2' }, hrVersionLine, hrUp.state),
-            hrUp.btn),
+          h('div', { class: 'mt-3 flex flex-wrap items-center gap-2 rounded-xl border border-border p-2' },
+            hrVersionLine, hrUp.state, hrUp.btn,
+            h('div', { class: 'ml-auto shrink-0' }, hrSwitchRow)),
           h('div', { class: 'mt-2 rounded-xl border border-border p-2' },
             h('div', { class: 'flex flex-wrap items-center justify-between gap-2' },
               h('span', { class: 'text-ui-sm font-medium text-foreground' }, L.headroomStatusTitle),
@@ -1497,6 +2023,7 @@ export function openSettingsDialog() {
         paneVision,
         paneHeadroom,
         paneRtk,
+        paneDebug,
       );
     },
   });