> ## Documentation Index
> Fetch the complete documentation index at: https://ophel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查 — 常见问题逐步修复指南

> Ophel Atlas 最常见问题的逐步修复方法：面板不显示、大纲为空、提示词队列卡住、Firefox 重启等。

export const ShortcutLegend = ({lang = "en"}) => {
  const isZh = lang === "zh";
  return <div className="ophel-shortcut-legend" role="note">
      <div className="ophel-shortcut-legend-title">
        {isZh ? "跨平台按键说明" : "Cross-platform key mapping"}
      </div>
      <div className="ophel-shortcut-legend-body">
        {isZh ? <>
            文档中的快捷键会同时显示 Windows/Linux 与 Mac 写法：
            <code>Ctrl</code> 对应 <code>Command</code>，
            <code>Alt</code> 对应 <code>Option</code>。唯一例外是提示词发送，
            <code>Ctrl+Enter</code> 在 Mac 上也使用 <code>Ctrl+Enter</code>。
          </> : <>
            Shortcuts show both Windows/Linux and Mac keys: <code>Ctrl</code> maps
            to <code>Command</code>, and <code>Alt</code> maps to
            <code>Option</code>. Prompt submit is the only exception:
            <code>Ctrl+Enter</code> remains <code>Ctrl+Enter</code> on Mac.
          </>}
      </div>
    </div>;
};

export const Shortcut = ({combo, mac, sameOnMac = false}) => {
  const keyLabels = {
    arrowup: {
      win: "Up",
      mac: "↑"
    },
    arrowdown: {
      win: "Down",
      mac: "↓"
    },
    arrowleft: {
      win: "Left",
      mac: "←"
    },
    arrowright: {
      win: "Right",
      mac: "→"
    },
    up: {
      win: "Up",
      mac: "↑"
    },
    down: {
      win: "Down",
      mac: "↓"
    },
    left: {
      win: "Left",
      mac: "←"
    },
    right: {
      win: "Right",
      mac: "→"
    },
    esc: {
      win: "Esc",
      mac: "Esc"
    },
    escape: {
      win: "Esc",
      mac: "Esc"
    },
    enter: {
      win: "Enter",
      mac: "Enter"
    },
    shift: {
      win: "Shift",
      mac: "⇧"
    },
    backslash: {
      win: "\\",
      mac: "\\"
    }
  };
  const modifierLabels = {
    ctrl: {
      win: "Ctrl",
      mac: "⌘"
    },
    control: {
      win: "Ctrl",
      mac: "⌘"
    },
    cmd: {
      win: "Ctrl",
      mac: "⌘"
    },
    command: {
      win: "Ctrl",
      mac: "⌘"
    },
    alt: {
      win: "Alt",
      mac: "⌥"
    },
    option: {
      win: "Alt",
      mac: "⌥"
    },
    shift: {
      win: "Shift",
      mac: "⇧"
    }
  };
  const normalizeToken = token => String(token || "").trim();
  const formatKey = (token, platform) => {
    const normalized = normalizeToken(token);
    const key = normalized.toLowerCase();
    const mapped = keyLabels[key];
    if (mapped) return mapped[platform];
    if (normalized.length === 1) return normalized.toUpperCase();
    return normalized;
  };
  const formatCombo = (value, platform) => String(value || "").split("+").map(normalizeToken).filter(Boolean).map(token => {
    const mapped = modifierLabels[token.toLowerCase()];
    return mapped ? mapped[platform] : formatKey(token, platform);
  }).join(platform === "mac" ? "" : "+");
  const windowsLabel = formatCombo(combo, "win");
  const macLabel = sameOnMac ? windowsLabel : mac || formatCombo(combo, "mac");
  const title = windowsLabel === macLabel ? windowsLabel : `Windows/Linux: ${windowsLabel}; Mac: ${macLabel}`;
  return <span className="ophel-shortcut" title={title}>
      <code>{windowsLabel}</code>
      {windowsLabel !== macLabel && <>
          <span className="ophel-shortcut-separator"> / </span>
          <code>{macLabel}</code>
        </>}
    </span>;
};

export const Icon = ({src, alt}) => <img src={typeof window !== "undefined" && typeof src === "string" && src.startsWith("/images/icons/") && (window.location.pathname === "/docs" || window.location.pathname.startsWith("/docs/")) ? `/docs${src}` : src} alt={alt} width="18" height="18" style={{
  display: "inline-block",
  verticalAlign: "-0.2em",
  margin: "0 0.15em"
}} />;

如果某些功能没有按预期工作，本页提供最常见问题的修复步骤。如果下面没有覆盖你的问题，请在 [GitHub Issues](https://github.com/urzeye/ophel/issues) 中提交报告，附上浏览器版本、扩展版本，以及浏览器控制台中的错误信息。

## 面板没有出现

<img src="https://mintcdn.com/urzeye/AGLEIfLkr4uHH1zd/images/panel/panel-tabs.png?fit=max&auto=format&n=AGLEIfLkr4uHH1zd&q=85&s=141737be3544a5375f83ad741b340b24" alt="Ophel 侧边面板 — 三标签页概览" width="315" height="338" data-path="images/panel/panel-tabs.png" />

在打开支持的 AI 平台时，Ophel 侧边面板应该自动出现。如果没有显示：

<Steps>
  <Step title="确认扩展已启用">
    点击浏览器工具栏中的扩展图标，确认 Ophel Atlas
    已开启。如果被禁用，启用它并刷新页面。
  </Step>

  <Step title="强制刷新页面">
    按 <Shortcut combo="ctrl+shift+r" />{" "}
    强制完整刷新页面。普通刷新有时不会重新初始化 Ophel 面板。
  </Step>

  <Step title="检查是否在支持的网站上">
    Ophel 只在[支持的 15 个平台](/docs/introduction#支持的平台)上激活。确认当前 URL
    属于其中之一。
  </Step>

  <Step title="用快捷键手动打开">
    如果面板之前被关闭了，按{" "}

    <Icon src="/docs/images/icons/keyboard.svg" alt="快捷键图标" />

    {" "}

    <Shortcut combo="alt+p" />

    {" "}

    重新打开，无论浮动按钮是否可见，这个快捷键都能切换面板状态。
  </Step>
</Steps>

## 大纲为空或不更新

<img src="https://mintcdn.com/urzeye/9I8m8P8gSndxcYtq/images/features/outline-zh.png?fit=max&auto=format&n=9I8m8P8gSndxcYtq&q=85&s=1552815538d928dbd0de5155025c0f83" alt="大纲标签页 — 实时会话目录树" width="1280" height="800" data-path="images/features/outline-zh.png" />

<Steps>
  <Step title="手动刷新大纲">
    按{" "}

    <Icon src="/docs/images/icons/refresh.svg" alt="刷新大纲图标" />

    {" "}

    <Shortcut combo="alt+r" /> 强制大纲重新扫描对话。部分 AI 平台异步更新
    DOM，大纲可能需要几秒才能填充。
  </Step>

  <Step title="等待 AI 完成回复">
    大纲在每次 AI 回复完成后重建。如果 AI 仍在生成中，大纲不会更新。
  </Step>

  <Step title="检查自动更新设置">
    前往 **设置 → 功能 →
    大纲**，确认**自动更新**已开启。如果关闭，大纲只在手动按{" "}
    <Shortcut combo="alt+r" /> 时才刷新。
  </Step>
</Steps>

## 大纲不跟踪滚动位置

如果滚动时大纲没有高亮当前阅读的章节：

<Steps>
  <Step title="在设置中启用滚动同步">
    前往 **设置 → 功能 → 大纲**，将**滚动同步**设置为开启状态。
  </Step>
</Steps>

## 浮动按钮消失

<img src="https://mintcdn.com/urzeye/AGLEIfLkr4uHH1zd/images/panel/floating-buttons.png?fit=max&auto=format&n=AGLEIfLkr4uHH1zd&q=85&s=3407c52ae11d8640fe975e95fb507cf6" alt="浮动操作按钮 — 展开与折叠胶囊状态" width="64" height="433" data-path="images/panel/floating-buttons.png" />

浮动快捷按钮 5 秒不操作后会自动折叠成胶囊形状，并没有真的消失——只是最小化了。

<Steps>
  <Step title="将鼠标移近胶囊位置">
    将鼠标移动到胶囊形状约 150px 范围内，按钮会自动展开。
  </Step>

  <Step title="如果胶囊完全不可见">
    按{" "}

    <Icon src="/docs/images/icons/keyboard.svg" alt="快捷键图标" />

    {" "}

    <Shortcut combo="alt+p" /> 打开面板，浮动按钮会随之重新出现。
  </Step>
</Steps>

## 面板遮挡了需要点击的内容

<img src="https://mintcdn.com/urzeye/AGLEIfLkr4uHH1zd/images/panel/ghost-mode.webp?fit=max&auto=format&n=AGLEIfLkr4uHH1zd&q=85&s=a81f47df60ac520403b297f7d57c8800" alt="幽灵穿透模式 — 半透明可点透面板" width="408" height="918" data-path="images/panel/ghost-mode.webp" />

<Steps>
  <Step title="使用幽灵穿透模式临时点透">
    按住 <Shortcut combo="ctrl" /> 约 0.2
    秒，面板变半透明并允许鼠标点透背后内容。松开按键后恢复。
  </Step>

  <Step title="将面板移开或切换到吸附模式">
    拖动面板标题栏移到屏幕另一侧，或切换到**自动吸附**模式（快捷键{" "}

    <Shortcut combo="alt+m" />

    ），让面板贴边隐藏。
  </Step>
</Steps>

## 会话标签页为空

<img src="https://mintcdn.com/urzeye/9I8m8P8gSndxcYtq/images/features/conversation-zh.png?fit=max&auto=format&n=9I8m8P8gSndxcYtq&q=85&s=c2bc6bf0070b1b12f5af62180e5cda2e" alt="会话标签页 — 文件夹与标签列表" width="1280" height="800" data-path="images/features/conversation-zh.png" />

<Steps>
  <Step title="确认 AI 平台侧边栏已加载">
    会话标签页直接从 AI 平台的原生侧边栏读取数据。如果侧边栏尚未加载，Ophel
    没有内容可以显示。
  </Step>

  <Step title="滚动原生侧边栏">
    打开 AI 平台自带的对话列表并向下滚动，触发加载更多条目。加载完成后，Ophel
    的会话标签页会同步更新。
  </Step>
</Steps>

## <Icon src="/docs/images/icons/prompt-queue.svg" alt="提示词队列图标" /> 提示词队列卡住，不发送下一条

<Steps>
  <Step title="确认 AI 是否还在生成">
    确认 AI 已经完成回复（无旋转/加载指示器）。队列在检测到生成完成前不会发送。
  </Step>

  <Step title="强制发送待处理条目">
    如果 AI 平台使用了 Ophel 无法识别的加载动画，队列可能会卡住。按{" "}

    <Icon src="/docs/images/icons/keyboard.svg" alt="快捷键图标" />

    {" "}

    <Shortcut combo="alt+j" />

    {" "}

    打开队列叠加层，然后对需要立即发送的条目使用**强制发送**。
  </Step>
</Steps>

## WebDAV 同步失败

<Steps>
  <Step title="验证服务器地址格式">
    确认 WebDAV 服务器地址以 `https://` 开头，末尾有没有斜杠均可，但必须是 HTTPS 协议。
  </Step>

  <Step title="检查权限">
    WebDAV 依赖可选权限 `<all_urls>`。前往 **设置 → 权限**，确认该权限已授予。
  </Step>

  <Step title="测试连接">
    在 WebDAV 设置页面点击**测试连接**，查看错误提示（通常是 401 凭证错误、404 路径错误或 CORS 错误）。
  </Step>
</Steps>

## Firefox 重启后扩展消失

Firefox 上通过 `about:debugging` 手动临时加载的扩展，在浏览器重启后会失效。

<Steps>
  <Step title="使用 Firefox 附加组件商店版本">
    前往 [Firefox
    附加组件商店](https://addons.mozilla.org/firefox/addon/ophel-ai-chat-enhancer/)
    安装正式版本，支持持久化，不受重启影响。
  </Step>
</Steps>

## 还是无法解决？

1. 在无痕模式（只开启 Ophel）下复现问题
2. 打开浏览器开发者工具（右键 → 检查 → Console），查看是否有报错
3. 携带浏览器版本、扩展版本和控制台输出，在 [GitHub Issues](https://github.com/urzeye/ophel/issues) 页面反馈