FAQ

常见问题

本页汇总安装、配置、使用、Agent 连接中的高频问题。如果这里没有解决你的问题，欢迎到 GitHub Discussions 或 Issues 反馈（每个 issue 24 小时内回复）。

← 返回 Wiki 首页 · 相关内容：安装与快速开始 · 代理服务 · 配置说明

---

安装与加载

Q：扩展加载后图标不显示？ 确保 chrome://extensions/ 中「开发者模式」已开启，并选择了正确的扩展目录（解压后的文件夹，或源码构建的 dist/）。

Q：侧边栏打不开？ 浏览器版本需 >= 114，低版本不支持 Side Panel API。请升级 Chrome / Edge / Chromium。

Q：构建后文件名带有 hash？ scripts/fix-build.js 会自动将 hash 文件名重命名为固定文件名，无需手动处理或重新加载。

Q：Chrome 用户如何安装？ 从 GitHub Releases 下载 ai-helper-*.zip，解压后在 chrome://extensions/ 开启开发者模式并「加载已解压的扩展程序」。或使用源码构建后加载 dist/。

---

配置与模型

Q：应该填哪个 API 地址？ 任意 OpenAI 兼容端点均可，例如 DeepSeek、以及各类兼容网关。默认内置 DeepSeek 预设。

Q：如何切换多个模型厂商？ 保存多套配置档案（端点 / Key / 模型列表），在侧边栏中先选厂商、再选模型即可。

Q：如何开启图片识别？ 在选项页「图片识别」Tab 中开启全局开关，可选配独立的 Vision API Base / Key / Model（不配则复用主配置）。

Q：工具很多会不会占用大量 Token？ 系统内置多项 Token 优化，无需手动配置：工具预筛选先用一次轻量 API 调用，从 40+ 个内建工具中筛出 5–10 个相关的；单次推理内的重复工具调用会命中结果缓存，不会重复消耗。

Q：反思系统会不会拖慢速度？ 反思默认总开关关闭。开启后按阈值决定是否修订 / 重跑，会带来额外调用，但能提升答案质量。可按需只开后置反思。

---

使用相关

Q：工具调用不生效？ 检查选项页中对应工具是否启用；部分工具需要特定网站权限；Agent 工具需要先完成配对连接。

Q：如何上传文件进行问答？ 直接粘贴或拖拽文件到输入区域，支持 PDF / Word / Excel / 文本等格式。有 Agent 时优先上传至工作目录，否则自动降级为浏览器端提取。

Q：如何让 AI 读取当前网页？ 输入 @，在弹出的选择器「网页」Tab 中选中目标标签页，即可将页面内容注入为对话上下文。

Q：如何导入 / 导出对话？ 侧边栏输入框下方点击「导出」按钮，可选择多个会话批量导出为 .aihelper.json；导入通过文件选择器完成（兼容新版与旧版格式）。

Q：如何添加 MCP 工具？ 选项页 →「工具箱」Tab → 添加 MCP 服务器 → 填写命令和参数 → 连接。工具会自动注册到系统中，每次推理前自动同步。

Q：定时任务支持哪些调度规则？ 一次性（多少分钟后 / 指定时间点）、间隔（如 30m / 2h / 1d）、Cron 表达式（5 段式）三种，均可绑定网页上下文，结果写入指定宿主会话。

Q：长任务中途关闭了浏览器怎么办？ ReAct 每轮推理后自动保存 Checkpoint。中断的任务消息卡片会显示「继续执行」按钮，点击即可追加描述并恢复执行。Checkpoint 保存 7 天后自动清理。

Q：任务完成时如何收到提醒？ 当发起任务的侧边栏不可见时（例如你正在浏览其他页面），任务完成或失败会弹出桌面通知，点击即可打开侧边栏；AI 需要你确认或澄清时也会提醒。定时任务的完成通知则总是弹出。相关开关位于选项页「基础」标签，默认全部开启。

---

代理服务（Agent）

Q：如何连接本地 Agent？

# 全局安装（推荐）
npm install -g ai-helper-agent && aha start -b
# 或本地启动
cd agent && npm install && npm start

然后在扩展选项页「Agent」标签页中输入终端显示的 6 位配对码。

Q：Agent 命令执行失败？ 确认代理服务正在运行（ai-helper-agent status），检查 ~/.ai-helper-agent/config.json 中的 allowedPaths 是否包含目标路径。

Q：如何让 Agent 在后台运行？ 使用 ai-helper-agent start -b 或 aha start -b 后台启动模式。可用 ai-helper-agent stop 停止，ai-helper-agent status 查看状态。

Q：Agent 操作有日志记录吗？ 有。所有文件读写、命令执行、安全事件都会记录审计日志，位于 ~/.ai-helper-agent/logs/，JSON Lines 格式，最多保留 30 个日志文件（单个文件超过 10MB 自动清理）。可通过 /api/logs 查询。

Q：命令执行的安全策略是怎样的？ 三级安全：黑名单（如 rm -rf /）始终拦截；灰名单（如 sudo、npm install -g）需确认；白名单常规命令直接放行。详见 代理服务 → 安全机制。

Q：删除的文件能恢复吗？ 能。Agent 端删除默认为软删除，文件进入 ~/.ai-helper-agent/.trash/，保留 7 天。可通过 agent_trash 工具或 /api/trash/restore 恢复。

Q：如何更新 Agent？ 支持在线更新：调用 /api/agent/update 会执行 npm install -g ai-helper-agent@latest 并自动重启（90s 超时保护）。也可手动 npm install -g ai-helper-agent@latest。

---

知识库（RAG）

Q：如何使用本地知识库？ 先在选项页启用 RAG，并确保 Agent 端 RAG 依赖可用（缺失时插件端提供一键安装）。然后在知识库面板导入文档，在侧边栏提问即可返回带引用的答案。

Q：知识库支持哪些格式？ .txt .md .json .csv .html / PDF / Word / PPT / Excel，支持文本、文件、URL 三种导入方式。

Q：数据存储在哪里？会不会上传？ 知识库存储于 ~/.ai-helper-agent/rag/（可用 AI_HELPER_RAG_ROOT 覆盖），索引与文件均保存在本机，不上传。

Q：默认用什么向量模型？ 默认使用本地模型 Xenova/bge-small-zh-v1.5（512 维，经 @huggingface/transformers 本地运行），也可接入任意 OpenAI 兼容向量服务。

Q：检索是纯向量吗？ 不是。采用混合检索：向量相似度 + 关键词命中抬分；跨库检索时 topK 配额按库均分。

---

语音输入（本地 STT）

Q：侧边栏为什么没有 🎤 按钮？ 语音需要「依赖 + 模型 + 开关」三项同时就绪，任一未满足时按钮会直接隐藏（避免点下去才报错）。打开选项页「语音」Tab 看是哪一项没就绪：依赖未安装就点一键安装，模型未就绪就扫描或导入模型包，最后确认总开关已打开。详见 语音输入（本地 STT）。

Q：点 🎤 提示没有麦克风权限？ 侧边栏 / 弹窗形态里 Chromium 不允许弹授权框。到选项页「语音」Tab 点「去授权」，在标签页里允许一次即可；未授权时录音条里也会出现「去授权」按钮。

Q：语音识别会把录音上传吗？ 不会。识别完全在本地 Agent 里跑 ONNX 模型，音频不上传、也不写盘；结果只写进输入框，不会自动发送。

Q：插入了模型包，为什么显示「模型包非法」？ 模型目录要求「一目录一模型」，目录内必须有 manifest.json（schema / id / kind / files / modelFile / tokensFile 等）。配置页现在会直接显示具体原因（字段缺失 / 文件不存在 / sha256_mismatch），修好后重新点「扫描」即可。

Q：松手后要等好几秒才出文字？ 这是离线定稿模型在对整段音频重算（质量更高、带标点）。想更快可以只装流式模型，代价是标点与数字规整变差。定稿跑在独立 worker 线程，等待期间代理依然响应。

Q：说太长了会怎样？ 单次上限默认 5 分钟；到上限时自动停录并用整段音频定稿，不会丢掉已说的内容，录音条显示「已达单次录音时长上限，正在转写…」。

---

其他

Q：数据会上传到第三方吗？ 不会。开源 MIT，配置、会话、知识库索引均可保存在本机；仅在你配置的 LLM API 端点处发生模型调用。

Q：支持哪些浏览器？ Chrome / Edge / Chromium 114+。

Q：如何参与贡献？ 阅读 架构总览 后即可上手。欢迎提交 PR，也欢迎从 good first issue 开始。