From 3749d5c2de72362c248df686687d0974662e58e8 Mon Sep 17 00:00:00 2001
From: developer <dev@health.com>
Date: Sat, 4 Apr 2026 22:56:34 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=B8=AE=E5=8A=A9?=
 =?UTF-8?q?=E6=8C=89=E9=92=AE=E5=92=8C=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=E5=BC=B9=E6=A1=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 css/style.css | 62 +++++++++++++++++++++++++++++++++++++++
 index.html    | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++
 js/app.js     | 16 +++++++++++
 3 files changed, 158 insertions(+)

diff --git a/css/style.css b/css/style.css
index 6ecb9a2..772b6c5 100644
--- a/css/style.css
+++ b/css/style.css
@@ -1713,6 +1713,68 @@ body::before {
     to { opacity: 0; transform: translateX(40px); }
 }
 
+/* ═══════════════ 帮助弹框 ═══════════════ */
+
+.help-btn {
+    margin-left: 4px;
+    opacity: 0.6;
+}
+.help-btn:hover {
+    opacity: 1;
+}
+
+.help-section {
+    margin-bottom: 18px;
+}
+.help-section:last-child {
+    margin-bottom: 0;
+}
+.help-section h4 {
+    font-size: 14px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    color: var(--text-primary);
+}
+.help-section ul,
+.help-section ol {
+    padding-left: 20px;
+    font-size: 13px;
+    color: var(--text-secondary);
+    line-height: 1.8;
+}
+.help-section li {
+    margin-bottom: 2px;
+}
+.help-section code {
+    background: rgba(0,245,212,0.1);
+    color: var(--accent-cyan);
+    padding: 1px 6px;
+    border-radius: 4px;
+    font-size: 12px;
+}
+.help-section kbd {
+    background: rgba(255,255,255,0.08);
+    border: 1px solid rgba(255,255,255,0.15);
+    border-radius: 4px;
+    padding: 1px 6px;
+    font-size: 12px;
+    font-family: inherit;
+}
+
+.help-shortcuts {
+    width: 100%;
+    font-size: 13px;
+    border-collapse: collapse;
+}
+.help-shortcuts td {
+    padding: 4px 8px;
+    border-bottom: 1px solid var(--border-glass);
+}
+.help-shortcuts td:first-child {
+    width: 140px;
+    text-align: center;
+}
+
 /* ═══════════════ 知识库管理 ═══════════════ */
 
 .modal-lg {
diff --git a/index.html b/index.html
index c06cb5c..1071d78 100644
--- a/index.html
+++ b/index.html
@@ -21,6 +21,12 @@
             <span class="logo">🦙</span>
             <span class="app-title">Metona Ollama</span>
             <span class="app-version">v2.2.0</span>
+            <button class="icon-btn help-btn" id="btnHelp" title="使用帮助">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/>
+                    <line x1="12" y1="17" x2="12.01" y2="17"/>
+                </svg>
+            </button>
         </div>
         <div class="header-right">
             <div class="conn-status pending" id="connStatus" title="连接状态">
@@ -234,6 +240,80 @@
     </div>
 </div>
 
+<!-- ═══════════════ 帮助模态框 ═══════════════ -->
+<div class="modal-overlay" id="helpModal" style="display:none;">
+    <div class="modal">
+        <div class="modal-header">
+            <h3>📖 使用帮助</h3>
+            <button class="icon-btn" id="btnCloseHelp">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
+                </svg>
+            </button>
+        </div>
+        <div class="modal-body">
+            <div class="help-section">
+                <h4>🚀 快速开始</h4>
+                <ol>
+                    <li>确保 Ollama 已启动（默认 <code>http://127.0.0.1:11434</code>）</li>
+                    <li>顶部下拉框选择一个模型</li>
+                    <li>输入消息，按 <kbd>Enter</kbd> 发送，<kbd>Shift+Enter</kbd> 换行</li>
+                </ol>
+            </div>
+            <div class="help-section">
+                <h4>💬 聊天功能</h4>
+                <ul>
+                    <li><strong>流式回复</strong> — 实时打字效果，随时点 ■ 停止</li>
+                    <li><strong>Think 推理</strong> — 🧠 按钮开启深度思考（需模型支持）</li>
+                    <li><strong>上下文长度</strong> — 设置中调整 <code>num_ctx</code>，越大记忆越长</li>
+                    <li><strong>系统提示词</strong> — 设置中开启，定义 AI 的角色和行为</li>
+                </ul>
+            </div>
+            <div class="help-section">
+                <h4>📎 文件与图片</h4>
+                <ul>
+                    <li><strong>📷 上传图片</strong> — 图标按钮上传，模型需支持 Vision</li>
+                    <li><strong>📄 上传文件</strong> — 支持 50+ 种文本/代码格式，单文件 ≤500KB</li>
+                    <li>文件内容自动以代码块格式发送给模型分析</li>
+                </ul>
+            </div>
+            <div class="help-section">
+                <h4>📚 知识库 (RAG)</h4>
+                <ul>
+                    <li>点击顶部 📚 按钮打开知识库管理</li>
+                    <li>创建集合 → 选择嵌入模型（推荐 <code>nomic-embed-text</code> 等）</li>
+                    <li>上传文档，自动分块并生成向量索引</li>
+                    <li>开启 RAG 检索后，聊天时自动检索相关文档注入回答</li>
+                </ul>
+            </div>
+            <div class="help-section">
+                <h4>🕐 历史记录</h4>
+                <ul>
+                    <li>所有会话自动保存到浏览器本地（IndexedDB）</li>
+                    <li>点击 🕐 按钮查看、搜索、恢复历史会话</li>
+                    <li>支持导出 <code>.metona</code> 加密备份文件</li>
+                </ul>
+            </div>
+            <div class="help-section">
+                <h4>⚙️ 设置</h4>
+                <ul>
+                    <li><strong>服务地址</strong> — 修改 Ollama API 端点</li>
+                    <li><strong>释放显存</strong> — 卸载当前模型，释放 GPU 内存</li>
+                    <li><strong>跨域问题</strong> — 启动 Ollama 时设置 <code>OLLAMA_ORIGINS="*"</code></li>
+                </ul>
+            </div>
+            <div class="help-section">
+                <h4>⚡ 快捷键</h4>
+                <table class="help-shortcuts">
+                    <tr><td><kbd>Enter</kbd></td><td>发送消息</td></tr>
+                    <tr><td><kbd>Shift + Enter</kbd></td><td>换行</td></tr>
+                    <tr><td><kbd>Esc</kbd></td><td>关闭弹窗</td></tr>
+                </table>
+            </div>
+        </div>
+    </div>
+</div>
+
 <!-- ═══════════════ 知识库管理模态框 ═══════════════ -->
 <div class="modal-overlay" id="kbModal" style="display:none;">
     <div class="modal modal-lg">
diff --git a/js/app.js b/js/app.js
index 3aa69fe..a61e66f 100644
--- a/js/app.js
+++ b/js/app.js
@@ -20,6 +20,19 @@ import { initHistoryModal, closeHistoryModal } from './components/history-modal.
 import { initKBModal } from './components/kb-modal.js';
 import { initVectorStore } from './rag.js';
 
+function initHelpModal() {
+    const helpModal = document.querySelector('#helpModal');
+    document.querySelector('#btnHelp').addEventListener('click', () => {
+        helpModal.style.display = '';
+    });
+    document.querySelector('#btnCloseHelp').addEventListener('click', () => {
+        helpModal.style.display = 'none';
+    });
+    helpModal.addEventListener('click', (e) => {
+        if (e.target === helpModal) helpModal.style.display = 'none';
+    });
+}
+
 console.log('[Metona] 模块化版本 v2.2.0 ' + new Date().toISOString());
 
 // ── 会话管理 ──
@@ -91,6 +104,7 @@ async function init() {
         initSettingsModal();
         initHistoryModal();
         initKBModal();
+        initHelpModal();
 
         // 5. 绑定全局事件
         bindGlobalEvents();
@@ -162,6 +176,8 @@ function bindGlobalEvents() {
             closeSettingsModal();
             closeHistoryModal();
             closeLightbox();
+            document.querySelector('#helpModal').style.display = 'none';
+            document.querySelector('#kbModal').style.display = 'none';
         }
     });