FAQ EN

🌐 Language / 语言: 中文 · English

FAQ

This page collects the most common questions about installation, configuration, usage, and Agent connection. If your issue isn't covered here, feel free to report it on GitHub Discussions or Issues (every issue is replied to within 24 hours).

← Back to Wiki Home · Related: Installation & Quick Start · Agent Service · Configuration

---

Installation & Loading

Q: The extension icon doesn't show after loading? Make sure "Developer mode" is enabled in chrome://extensions/ and that you selected the correct extension directory (the unzipped folder, or the dist/ from a source build).

Q: The side panel won't open? Your browser version must be >= 114; older versions don't support the Side Panel API. Please upgrade Chrome / Edge / Chromium.

Q: The built filenames contain hashes? scripts/fix-build.js automatically renames hashed filenames to fixed names — no manual handling or reload needed.

Q: How do Chrome users install it? Download ai-helper-*.zip from GitHub Releases, unzip it, enable developer mode in chrome://extensions/, and click "Load unpacked". Or build from source and load dist/.

---

Configuration & Models

Q: Which API address should I fill in? Any OpenAI-compatible endpoint works, e.g. DeepSeek or various compatible gateways. A DeepSeek preset is built in by default.

Q: How do I switch between multiple model providers? Save multiple config profiles (endpoint / key / model list), then in the side panel pick the provider first and the model second.

Q: How do I enable image recognition? In the options page "Image Recognition" tab, enable the global switch; you can optionally configure a separate Vision API Base / Key / Model (if not set, the main config is reused).

Q: Do 40+ tools consume a lot of tokens? Several token optimizations are built in and need no configuration: tool pre-selection uses one lightweight API call to narrow the 40+ built-in tools down to 5–10 relevant ones, and repeated tool calls within a single reasoning run hit the result cache instead of consuming again.

Q: Does the reflection system slow things down? Reflection is off by default (master switch). When enabled, it decides whether to revise / re-run based on thresholds, which adds extra calls but improves answer quality. You can enable only post-reflection if you like.

---

Usage

Q: Tool calls don't take effect? Check whether the corresponding tool is enabled in the options page; some tools need specific site permissions; Agent tools must be paired and connected first.

Q: How do I upload files for Q&A? Paste or drag files directly into the input area; PDF / Word / Excel / text and more are supported. With an Agent, files are uploaded to the working directory first; otherwise it falls back to browser-side extraction.

Q: How do I let the AI read the current web page? Type @, then in the "Web page" tab of the popup selector, choose the target tab to inject the page content as conversation context.

Q: How do I import / export conversations? Click the "Export" button below the side panel input; you can batch-export multiple sessions to .aihelper.json. Import is done via the file picker (both new and legacy formats are supported).

Q: How do I add MCP tools? Options page → "Toolbox" tab → Add MCP server → fill in the command and arguments → Connect. The tool is auto-registered into the system and synced before each reasoning run.

Q: What scheduling rules do scheduled tasks support? Three kinds: one-time (after N minutes / at a specific time), interval (e.g. 30m / 2h / 1d), and Cron expressions (5-field). All can bind page context, and results are written to a designated host session.

Q: What if the browser closes mid-way through a long task? ReAct automatically saves a Checkpoint after each reasoning round. Interrupted task cards show a "Continue" button — click it to append a description and resume. Checkpoints are auto-cleaned after 7 days.

Q: How am I notified when a task finishes? When the side panel that started the task isn't visible (e.g. you're browsing other pages), a desktop notification pops up on completion or failure — click it to open the side panel. You're also reminded when the AI needs confirmation or clarification. Scheduled-task notifications always pop up. The related switches live in the "Basic Settings" tab, all on by default.

---

Agent Service

Q: How do I connect the local Agent?

# Global install (recommended)
npm install -g ai-helper-agent && aha start -b
# Or start locally
cd agent && npm install && npm start

Then enter the 6-digit pairing code shown in the terminal in the "Agent" tab of the extension options page.

Q: Agent command execution fails? Make sure the Agent service is running (ai-helper-agent status), and check whether allowedPaths in ~/.ai-helper-agent/config.json includes the target path.

Q: How do I run the Agent in the background? Use ai-helper-agent start -b or aha start -b for background daemon mode. Use ai-helper-agent stop to stop it, and ai-helper-agent status to check its status.

Q: Does the Agent log its operations? Yes. All file reads/writes, command executions, and security events are recorded in audit logs at ~/.ai-helper-agent/logs/ in JSON Lines format, keeping up to 30 log files (a single file over 10MB is auto-cleaned). Queryable via /api/logs.

Q: What's the security policy for command execution? Three tiers: blacklist (e.g. rm -rf /) is always blocked; graylist (e.g. sudo, npm install -g) requires confirmation; whitelist regular commands pass through directly. See Agent Service → Security Mechanisms.

Q: Can deleted files be recovered? Yes. Deletions on the Agent side are soft deletes by default; files go to ~/.ai-helper-agent/.trash/ and are kept for 7 days. Restore via the agent_trash tool or /api/trash/restore.

Q: How do I update the Agent? Online update is supported: calling /api/agent/update runs npm install -g ai-helper-agent@latest and auto-restarts (with a 90s timeout guard). You can also manually run npm install -g ai-helper-agent@latest.

---

Knowledge Base (RAG)

Q: How do I use the local knowledge base? First enable RAG in the options page and make sure the Agent-side RAG dependencies are available (the extension offers one-click install if missing). Then import documents in the knowledge-base panel and ask questions in the side panel to get answers with citations.

Q: Which formats does the knowledge base support? .txt .md .json .csv .html / PDF / Word / PPT / Excel, with three import methods: text, file, and URL.

Q: Where is the data stored? Is it uploaded? The knowledge base is stored in ~/.ai-helper-agent/rag/ (overridable with AI_HELPER_RAG_ROOT); indexes and files stay on your machine and are not uploaded.

Q: What vector model is used by default? The local model Xenova/bge-small-zh-v1.5 (512-dim, run locally via @huggingface/transformers); you can also connect any OpenAI-compatible vector service.

Q: Is retrieval purely vector-based? No. It uses hybrid retrieval: vector similarity + keyword-hit boosting; when searching across libraries, the topK quota is split evenly across libraries.

---

Voice Input (Local STT)

Q: Why is there no 🎤 button in the side panel? Voice input needs all three of dependency + models + switch. If any is missing the button stays hidden instead of failing after a click. Open Options → Voice and see which one is missing: install the dependency, scan or import a model pack, then confirm the master switch is on. See Voice Input (Local STT).

Q: Clicking 🎤 says there is no microphone permission. Chromium cannot show the prompt in side panel or popup form. Go to Options → Voice → "Grant permission" and allow it once in the tab page; when unauthorized the recorder strip also shows a "Grant permission" button.

Q: Is my audio uploaded? No. Recognition runs entirely inside the local Agent with ONNX models — audio is never uploaded and never written to disk, and the result is only inserted into the input, never sent automatically.

Q: I copied a model pack but it says the pack is invalid. The model directory expects one pack per sub-directory, each with a manifest.json (schema / id / kind / files / modelFile / tokensFile, …). The Options page now shows the concrete reason (missing fields, missing files, sha256_mismatch); fix it and hit "Scan" again.

Q: Why does it take seconds to show text after I stop? That is the offline final-pass model recomputing the whole take for higher quality and punctuation. Install only the streaming model if you prefer speed over punctuation and number normalization — the final pass runs on a worker thread, so the Agent stays responsive while you wait.

Q: What happens if I talk too long? The cap is 5 minutes by default. At the limit recording stops and the full audio is finalized, so nothing you said is lost; the strip shows "recording limit reached, transcribing…".

---

Other

Q: Is my data uploaded to third parties? No. Open-source MIT; config, sessions, and knowledge-base indexes can all be stored locally; model calls happen only at the LLM API endpoint you configured.

Q: Which browsers are supported? Chrome / Edge / Chromium 114+.

Q: How do I contribute? Read the Architecture Overview to get started. PRs are welcome — you can also start with a good first issue.

---