Configuration EN

🌐 Language / 语言: 中文 · English

Configuration

This page lists all configuration items in the AI Helper options page and their defaults. Entry point: right-click the extension icon → "Options", or extension details page → "Extension options".

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

---

Options Page Tabs at a Glance

The options page has 8 tabs, with a global Save Configuration button at the bottom (shared by all tabs); reflection and completion-verification settings now live inside the Reasoning tab:

Tab	Contents
Basic	UI language, UI theme (Light / Dark / System), provider profiles, API base / key / model, image recognition, system prompt, completion feedback (sound / confetti / desktop notifications), message timestamps, side panel scope
Reasoning	ReAct loop parameters, execution log, streaming output; reflection switches and objective completion-verification switches
Toolbar	Text-selection floating toolbar management
Agent	Local Agent pairing connection
Voice	Local speech input: master switch, language, streaming / final-pass models, dependency detection and one-click install, model scan and import
Toolbox	MCP Server and Skill management
Knowledge Base	RAG knowledge base and Embedding configuration
Memory	Long-term memory vectors (embedding source, dimensions, query prefix, index status and rebuild) + browsing and managing memory entries

---

Basic Settings

UI Language

• UI Language: Chinese / English switch dropdown; takes effect immediately.

UI Theme

Parameter	Default	Description
UI Theme	Light	A segmented Light / Dark / System control that switches instantly and syncs across every surface (storage key appTheme); System flips live with the OS prefers-color-scheme; also cycle Light → Dark → System from the side panel's top "More" menu. PDF / Word / HTML exports always stay a white-background, black-text light paper regardless of dark mode

Provider Profiles

Save multiple provider configuration profiles; each profile independently remembers the API base URL, API key, and model list, and takes effect immediately after switching:

• + New: create a brand-new profile
• Save As: save the current configuration as a new profile
• Rename / Delete: manage existing profiles

The API base URL, key, and model below belong to the current profile and are saved and linked together with it.

API Connection

Parameter	Description
API Base URL	Select from the dropdown (18 built-in mainstream platform presets) or enter manually; supports "+ Add URL" to save custom addresses (with optional label/note)
API Key	OpenAI-compatible API key (required), with show / hide toggle
Model Name	Presets deepseek-v4-pro / deepseek-v4-flash; supports "+ Add Model" (with optional context window size — 128K=128000, 200K=200000, 1M=1000000; leave empty to auto-infer) and "⟳ Fetch from API" to pull the current provider's model list

Built-in API base presets (China): DeepSeek, Tencent Hunyuan, Alibaba Bailian (Qwen), Baidu Qianfan (ERNIE), Volcano Ark (Doubao), Zhipu GLM, Moonshot (Kimi), StepFun, MiniMax, iFlytek Spark, Baichuan, SiliconFlow; Overseas / Aggregators: OpenAI, Anthropic Claude, Google Gemini, OpenRouter, Groq, Mistral.

Image Recognition

Parameter	Description
Enable image recognition	Master switch; when on, images can be sent to a multimodal model from the side panel
Image API Base	Independent API URL; leave empty to use the base model config
Image API Key	Independent API key (optional); leave empty to use the base model config
Image Model	A multimodal vision model name; leave empty to use the base model's name

System Prompt

• System Prompt: define the AI assistant's behavior and role (optional; leave empty for the default), with a one-click "Reset to default" button.

Completion Feedback & Desktop Notifications

Parameter	Default	Description
Play completion sound	off	Ascending "ding-dong" on success, descending "dong-ding" on failure; not played on user-initiated cancel
Play confetti animation	off	Played only when an answer completes successfully; not on failure or cancel
Desktop notification on task completion / failure	on	Shown only when the side panel is not visible; success notifications auto-dismiss, failures stay until manually closed; click to open the side panel
Desktop notification on scheduled-task completion / failure	on	Scheduled tasks run in the background with no other alert channel, so they always pop up when the switch is on
Remind me when the AI needs confirmation or clarification	on	A desktop reminder pops up while the reasoning loop is waiting on your action; no interruption while the side panel is visible; click to open the side panel

Message Timestamp

Parameter	Default	Description
Show message timestamp	on	Shows the ask time below the user's question bubble — time-of-day for today, date otherwise

Side Panel Scope

Parameter	Default	Description
Global mode	default	All tabs in the same window share one side panel instance; always visible when switching tabs
Tab-specific mode	—	The side panel is visible only on the tab where it was opened; auto-hides when switching to other tabs
Auto-group tabs	off	Only effective in tab-specific mode; groups tabs that opened the side panel into a colored tab group for easy identification (auto-removed when a tab's side panel is closed or when switching back to global mode)

---

Reasoning (ReAct) Configuration

Controls the behavior of the AI reasoning loop (advanced settings).

Parameter	Default	Range	Description
Loop timeout	4 h	10–1440 min (24 h), 28-stop slider (hourly from 1h)	Max execution time of the whole reasoning loop; drag the slider to change it and it applies on release. Hitting the limit no longer kills the task — tools are disabled for a bounded wrap-up round that produces a "partially completed + what remains" report and keeps the checkpoint for resuming
Sensitive-operation confirmation	on	—	Pops a confirmation dialog when the model performs sensitive operations (tool calls, command execution); when off, all operations pass through directly
Enable execution log	on	—	Shows an "Execution Log" button at the bottom of messages to view detailed API calls and tool executions
Streaming output	on	—	AI replies render character-by-character in real time; agent command execution also streams; turn off to fall back to one-shot output if you hit compatibility issues
Streaming tool cards expanded by default	off	—	When off, tool cards collapse by default showing only title and status; click to expand details

💡 Note: clarification waiting time does not count toward the loop timeout (paused). Loop timeout is the only adjustable timeout on the settings page. The following parameters have no UI controls and use internal fixed values: max iterations 2000 (deterministic fuse against fast no-progress loops), API timeout 5 min (covers connect + response headers only; streaming body reads are guarded by a separate idle timeout), tool timeout 10 min (aligned with the agent-side total budget cap; long-running commands are covered by the dedicated agent_exec value plus automatic detach-to-background), clarification timeout 5 min, API failure retries 3 (exponential backoff, base delay 1s), tool pre-selection off (starts only when the tool count exceeds 10), streaming per-character render delay 30ms.

---

Goal Mode Configuration (inside the Reasoning tab)

Switch	Default	Description
Goal mode	off	Master switch; when on, 🎯 appears to the right of the Tools toggle. With it off the engine neither evaluates nor re-runs and the background refuses to create goals; stored goal scenes are kept and resume once it is on again
Intent detection	on	Deterministic pre-send regex (zero tokens): saying "run this in goal mode" turns the goal on with a revocable toast; goals detected this way never auto-approve sensitive actions

💡 Turn budget (20), time budget (follows the overall loop timeout), stall threshold (3), evaluator failure cap (2) and objective verification (always on) are fixed internal defaults with no UI — users cannot predict the consequences of changing them and a wrong value fails silently. Pressing Resume after the cap grants another 20 attempts.

---

Reflection & Completion Verification Settings (both inside the Reasoning tab)

Switch	Default	Description
Reflection master switch	on	Globally controls all reflection behavior
Post reflection	on	Evaluates final result quality after the reasoning loop; auto-revises or re-runs below the threshold
Subtask reflection	off	Evaluates subtasks of complex tasks individually (advanced feature)
Completion verification	off	Objectively gathers evidence for plan_task sub-task doneCriteria (real DOM / command evidence), complementing the subjective reflection self-scoring
Auto-rerun	off	Revealed only when Completion Verification is on; four gates drive unmet sub-tasks back through re-execution

💡 The reflection and completion-verification sub-switches both live inside the same Reasoning tab panel, toggled via display-based visibility.

💡 Internal fixed defaults (no UI controls): post-reflection quality threshold 7 (1–10, re-run below this), revision threshold 5 (revise directly below this instead of re-running), reflection temperature 0.3, max reflection rounds 1; tool-level reflection has been removed: tool-result quality feedback is now handled by the zero-cost inline "Tool Observation Hint" rule ([Observation Hint]), which appends one rule-based hint when a tool fails, returns nothing, or gets compressed for size.

Enabling reflection increases API call count; weigh the trade-off as needed.

---

Toolbar Configuration

Manage the floating toolbar that appears when selecting text on a web page:

Parameter	Default	Description
Toolbar master switch	on	Globally enable / disable the selection toolbar
Icon-compact mode	off	Show icons only, no text
Tool list	5 built-in	Built-in: AI Search / Explain / Translate / Summarize / Copy; supports drag-to-reorder and prompt editing
Add custom tool	—	Custom tool name (≤10 chars) + system prompt, e.g. "polish, rewrite, code review"
Domain blocklist	empty	After adding a domain (without http/https), the toolbar no longer appears on that domain

---

Agent Configuration

Connect to an Agent service for file read/write, system command execution, conversation memory management, Skill workflows, and MCP protocol extensions.

• Paired Agents: manage multiple paired Agents, one-click connect / switch
• Current active Agent: shows connection status and working directory; expandable details
• Add new Agent: name (auto-fetched if empty), address (default http://127.0.0.1:18910), 6-digit pairing code (shown in the Agent terminal window)

See Agent Service for details.

---

Voice (Local STT) Configuration

The Voice tab requires a connected Agent; microphone permission can only be granted in the options page (tab form) — the side panel cannot show the prompt.

• Enable voice input: master switch (off by default). Turning it off disables both 🎤 and Alt+V in the side panel
• Recognition pacing: Instant / Balanced (default) / Precise; applies to the next recording (see Voice Input)
• Input device: follows the system default unless a specific mic is picked; if it disappears, capture falls back and says so once
• Language: auto / Chinese / English / Japanese / Korean / Cantonese, auto-detect by default
• Streaming / final-pass model: chosen from the scanned online / offline packs; when unset the first usable pack wins per capability (float vs int8 is decided by the pack)
• Dependency status: shows the sherpa-onnx detection result, with one-click install and live progress (polled every 2 s) when missing
• Scan / import models: re-scan ~/.ai-helper-agent/asr/models/ or import a pack from any directory; invalid packs report the concrete reason (missing manifest.json, missing fields, missing files, sha256_mismatch)
• "Grant permission" entry: appears only while the microphone is unauthorized; clicking it shows the prompt in this tab

The 🎤 button appears only when dependency + models + switch are all satisfied, with no need to reopen the panel.

Full setup, model-pack layout and API → Voice Input (Local STT).

---

Toolbox Configuration

The Toolbox tab requires an Agent connection; related action buttons are disabled when disconnected.

MCP Server Management

• MCP master switch: when off, no MCP tools are sent to the AI context
• Search + filter (All / Enabled / Disabled)
• CRUD for MCP Servers; configure startup command, parameters, and environment variables (password input for sensitive values)
• Connect / disconnect, enable / disable

Skill Management

• Skill master switch: when off, no skill content is injected into the AI system prompt
• Search + filter (All / Enabled / Disabled)
• Import skill (JSON file), Reload skill list

---

Knowledge Base (RAG) Configuration

The knowledge base depends on an Agent connection + ready dependencies; a gated guide (including in-place installation guidance) is shown when not ready.

• RAG master switch: globally enable / disable knowledge base retrieval
• Create knowledge base: create a new collection
• Knowledge base cards: edit, import documents, document management, retrieval test, enable / disable, delete; shows document / chunk counts
• Embedding configuration (set when creating / editing a knowledge base):
  • Local mode (local): uses local embedding; no selectable parameters
  • Remote mode (openai-compat): configure an OpenAI-compatible embedding endpoint, API key, model name, and vector dimensions (1–8192); supports "Test connection" verification

---

Memory (Vector Recall) Configuration

Configures the semantic vector source for long-term memory. This tab writes into the Agent-side config.json field memoryEmbedding; the extension reads and writes it over local HTTP.

⚠️ This tab no longer has a separate Save to Agent button: clicking the global Save Configuration button at the page bottom first saves the extension settings, then also commits this tab's config into the Agent. When the Agent is offline this item is skipped, saving only the extension settings.

Requires a connected Agent (a gated guide is shown otherwise). Local model additionally requires the RAG dependency, with in-place installation guidance.

Parameter	Description
Enable semantic recall (master switch)	Off by default. When on, memory retrieval gains a vector-semantic channel; when off or the vector config is unavailable it falls back to the keyword channel. Toggling writes to the agent immediately
Vector index status	Read-only card: indexed n of m, the stored vector fingerprint vs the current config fingerprint, and the active tier; a mismatch shows a "stale" badge with a rebuild hint. Agents without the status endpoint get their own upgrade message
Embedding source	Radio: Remote service (OpenAI-compatible API) (default) / Local model (reuses the RAG dependency and model cache; the first run downloads the model). Local mode hides every remote field below, keeping only the notice and the rebuild action
Endpoint	OpenAI-compatible embedding endpoint, e.g. https://api.openai.com/v1
Model name	Remote embedding model, e.g. BAAI/bge-m3
API Key	Stored keys are never echoed (the agent only returns a hasApiKey flag) and a blank field means "keep", not "clear"; the Clear stored key button appears only when a key exists — clearing stops remote semantic recall at once (falling back to keywords) until a new key is saved
Vector dimensions	May be left blank (1–8192); "Test connectivity" measures the endpoint and fills the value back, and a hand-entered dimension that disagrees with the endpoint is not silently kept
Query prefix (queryPrefix)	Optional; some models need different prefixes for queries vs ingestion (asymmetric retrieval). Blank keeps the embedding provider's default prefix
Test connectivity	Calls the embedding endpoint once with the current form (unsaved draft values included); on success shows {model} returns {dims} dimensions. Local mode needs no test
Save Configuration (global button at the page bottom)	Clicking it also commits this tab into the agent config.json; source / switch / prefix / dimension changes take effect immediately, without restarting the agent. When the agent is offline this item is skipped and only extension settings are saved
Rebuild vector index	Recomputes vectors for every memory with the current config. A confirmation dialog precedes it (measured: about 23 minutes for 41 entries locally, about 2 minutes remote); keep the page open. The result reports indexed count, failed batches and entries exceeding the model token window

💡 Why a rebuild is required: vectors are filed under a fingerprint built from source + model + dimensions + prefix. After a config change old vectors are incomparable, so semantic recall degrades silently (no error, just wrong ranking) — a "stale" badge means the rebuild has not run yet.

💡 Local mode window: the local embedding pipeline truncates silently at 512 tokens, so only the head of an over-long entry is indexed; oversized batches are split automatically, so trust the agent logs for actual timing.

💡 The + button in the side panel memory popup (the history-limit dropdown), or options.html#memory, both open this tab directly. The bottom of the same tab also lets you browse and manage memory entries - see the next section.

---

Memory Entry Management

At the bottom of the same Memory tab you can view and edit the agent-side persisted memory entries (source of truth: ~/.ai-helper-agent/memory/global-memory.json). It removes the black box where high-value memories sit in the system prompt while you can neither see nor fix them: correcting one no longer means asking the model to recall the ID first, and no longer means hand-editing the JSON (which leaves stale vector cache behind pointing at the old entry).

Requires a connected agent. On an agent too old to expose manage the panel says so plainly and asks you to upgrade and restart, instead of spinning on "Loading".

Area	Notes
Entry list	Each row shows a type badge (fact / summary), the content (clamped to two lines, click to expand), importance, the value score, created date, last access with access count, and tags. Low-value candidates get a pale yellow highlight. The list scrolls inside its own height limit, so a long list never stretches the page
Refresh	Re-fetches every entry. The list reads manage → review (a read-only enumeration) and does not record an access, so normal recall from the side panel stays untouched
Search box	Filters content / title / category / tags client side, instantly, without another request
Type filter	All types / Facts / Summaries
Sort	Created (newest first, default) / Importance (high → low) / Value (high → low) / Value (low → high, the cleanup view). Also purely client side, and composes with search and the type filter
Edit	The dialog changes content, importance (1-10) and tags (comma or ideographic-comma separated; clearing the field clears the tags); type and category are read-only. After saving, the agent re-embeds that entry from its new content in the background (only when semantic recall is enabled; failures are logged, never blocking the save)
Delete	Deletes a single entry behind a confirmation; its vector cache is dropped with it. Not recoverable
Low-value banner + Compact now	Lists entries scoring below 10; the button evicts them in bulk after a confirmation naming the count and the threshold, then reports how many facts and summaries were removed

💡 Nothing to do with the bottom "Save" button: editing, deleting and compacting are written to the agent the moment you confirm them - the page-level Save Settings button neither submits nor is needed for them.

💡 The value score is computed by the agent as importance x access frequency x time decay and is read-only here; to raise an entry's ranking, change its importance.

---

Keyboard Shortcuts

Shortcut	Function	Platform
Ctrl+Shift+Y / Cmd+Shift+Y	Global shortcut to open the side panel	Win / Mac
Alt+↑ / Alt+↓	Jump to previous / next question	Win / Mac
Alt+Ctrl/Cmd+↑ / Alt+Ctrl/Cmd+↓	Scroll to top / bottom of the conversation	Win / Mac
Tab (left handle)	Focus the handle and open the question list	Win / Mac
↑ / ↓ / Home / End (in list)	Move between question items, Enter to jump	Win / Mac
Enter / Space (handle)	Pin / unpin the question list	Win / Mac
Alt+S	Full-page screenshot	Win / Mac
Alt+Shift+S	Region screenshot	Win / Mac
Ctrl/Cmd+T	Open / close tool configuration	Win / Mac
Alt+/	Open the shortcut panel	Win / Mac
Alt+N	New session	Win / Mac
Alt+W	Close current session	Win / Mac
Alt+E	Edit the most recent user message	Win / Mac
Enter	Send message	Win / Mac
Shift+Enter	New line	Win / Mac
↑ / ↓	Input history (inside the input box)	Win / Mac
Esc	Clear the input box / collapse the question list (clears search text first)	Win / Mac

---

Data Persistence Strategy

Data type	Storage location	Description
Extension config	chrome.storage.local	API Key, ReAct params, models, image recognition, toolbar, provider profiles, etc.
Chat sessions	IndexedDB (ai-helper-db)	Active sessions + archived sessions
Todo list	IndexedDB (todos) + todoStatsLog	Items plus the last 90 days of completion stats
Session goals	chrome.storage.local.sessionGoals	Goal text / progress / budget / approval; a cold-start mirror only — the checkpoint scene is authoritative
UI prototypes	IndexedDB	Associated by session
Toolbar config	chrome.storage.local	Tool list, ordering, domain blocklist
Input history	chrome.storage.local	Auto-deduplicated
Cross-restart messages	chrome.storage.session	SW restart recovery, background task persistence
Memory vector config	memoryEmbedding inside the agent config.json	Written by the Memory tab; not stored in the extension
Memories and derived vectors	agent memory/ directory (global-memory.json / memory-vectors.json)	Memories are the single source of truth; the vector file can be dropped and rebuilt. The entry manager at the bottom of the Memory tab edits them in place

IndexedDB Database Design

ai-helper-db (v6), eight object stores:

Store	Purpose
sessions	Active sessions (index: updatedAt)
activeSession	Current active session ID
archivedSessions	Archived sessions (index: createdAt)
uiPrototypes	UI prototypes (index: createdAt, sessionId)
tokenStats	Token usage stats (index: timestamp, sessionId)
reactCheckpoints	ReAct Checkpoints (index: updatedAt; 7-day TTL auto-expiry)
bookmarks	Message bookmarks (index: sessionId, createdAt)
scheduledTasks	Scheduled tasks (index: nextRunAt, enabled)

Supports automatic recovery from transaction failures and auto-migration from legacy chrome.storage.local.

---

Config Import / Export

The options page supports exporting the entire configuration to a file, or importing from a file, making it easy to sync or back up across devices.

• Export: optionally include API keys (sensitive — keep the file safe); the exported file contains all configuration except Agent connection info
• Import: preview before importing (export time, item count); two strategies:
  • Merge import: merges with existing config, aligning provider profiles by ID
  • Replace import: completely replaces the existing config