Quick Start

安装与快速开始

本页带你从零把 AI Helper 跑起来：安装扩展 → 打开侧边栏 → 配置模型 → （可选）连接本地 Agent → （可选）启用语音输入 → 完成第一个任务。

← 返回 Wiki 首页 · 相关内容：核心功能 · 代理服务 · 配置说明

---

1. 环境要求

项目	要求
浏览器	Chrome / Edge / Chromium 114+（必须支持 Side Panel API）
大模型	任意 OpenAI 兼容 API（默认内置 DeepSeek 预设）
Node.js	仅在使用 源码构建 或 本地 Agent 服务 时需要（>= 18）

---

2. 安装扩展

方式一：扩展商店一键安装（推荐）

• Chrome 用户：访问 Chrome 应用商店，点击「添加至 Chrome」即可。
• Edge 用户：访问 Microsoft Edge 扩展商店，点击「获取」即可。

方式二：下载构建包手动加载（其他 Chromium 浏览器 / 无商店账号）

1. 打开 GitHub Releases，下载最新的 ai-helper-*.zip。
2. 解压到任意文件夹（后续请勿删除）。
3. 打开 chrome://extensions/，打开右上角「开发者模式」。
4. 点击「加载已解压的扩展程序」，选择解压后的文件夹。

方式三：源码构建（开发者）

git clone https://github.com/xiweicheng/ai-helper.git
cd ai-helper
npm install
npm run build      # 生产构建，产物在 dist/

然后在 chrome://extensions/ 中加载 dist/ 文件夹。

---

3. 打开侧边栏

AI Helper 的所有对话都在浏览器**侧边栏（Side Panel）**中进行：

• 按全局快捷键 Ctrl+Shift+Y（macOS 为 Cmd+Shift+Y）；
• 或点击工具栏上的 AI Helper 图标；
• 或右键图标选择「打开侧边栏」。

若侧边栏打不开，请确认浏览器版本 >= 114。

---

4. 配置模型（API Key）

1. 右键扩展图标 →「选项」，或点击扩展详情页的「扩展程序选项」。
2. 进入「基础设置」标签页：

配置项	说明
API Key	你的 OpenAI 兼容 API 密钥
API 地址	API 端点 URL（如 https://api.deepseek.com/v1）
模型名称	从预设中选择（DeepSeek V4 Pro / Flash）或自定义添加
系统提示词	可选，自定义 AI 的角色与行为（含重置按钮）
默认温度	4 档预设：精准严谨 0.2 / 日常通用 0.45 / 思路发散 0.65 / 创意脑暴 0.9

3. 点击保存。

多厂商切换：可保存多套 OpenAI 兼容的配置档案（端点 / Key / 模型列表），在侧边栏中先选厂商、再选模型，两下即可切换。

各配置项的完整说明见 配置说明。

---

5. 发出第一条消息

在侧边栏输入框输入自然语言即可，例如：

• 「总结一下当前这个网页的要点」
• 「帮我在这个页面找到搜索框，输入『AI Helper』并搜索」
• 「把这个页面的表格导出成 Excel」

AI 会自动决定是否需要调用工具，并在执行日志面板中实时展示它的思考与每一步操作。

---

6.（可选）连接本地 Agent 服务

安装本地 Agent 后，AI 才能读写本地文件、执行终端命令、使用 Skill、MCP 扩展和本地知识库。

# 全局安装（推荐）
npm install -g ai-helper-agent
aha start -b                 # 后台守护进程模式启动（aha 是快捷别名）

# 或本地开发模式
cd agent && npm install && npm start

启动后终端会显示一个 6 位配对码。在扩展选项页的「Agent」标签页中填入该配对码即可完成连接。

详见 代理服务。

---

7.（可选）启用本地语音输入

语音输入（本地 STT）依赖本地 Agent 服务，音频不上传、也不写盘。启用需要三段同时就绪，缺一不可：

1. 依赖就绪：ONNX 运行时 + 音频编解码组件。选项页「语音」标签页会显示检测结果，缺失时点「一键安装」（等价于 aha asr install；也可在装 Agent 时加 --with-asr）。
2. 模型就绪：把识别模型包放到 ~/.ai-helper-agent/asr/models/（可点「扫描」或导入模型包），流式模型与定稿模型各选一个。
3. 开关打开：在「语音」标签页打开总开关，并按需选择识别语言（自动 / 中文 / 英文 / 日文 / 韩文 / 粤语）。

三项就绪后，侧边栏输入框右侧会出现 🎤 按钮。首次使用需在标签页里允许一次麦克风（侧边栏形态下 Chromium 不允许弹授权框，选项页提供「去授权」入口）。

录音过程中按 Alt+V 随时收尾，按 Esc 取消；识别出的文字只写进输入框，不会自动发送，你可以先改再发。

完整步骤、模型包结构与接口说明见 语音输入（本地 STT）。

---

8. 开发者：开发模式

npm install
npm run dev        # Vite 开发服务器，带 HMR

在 chrome://extensions/ 中加载项目 dist 文件夹，修改源码后扩展会自动重载。

常用脚本

命令	说明
npm run dev	开发模式（Vite + HMR）
npm run build	生产构建（产物在 dist/）
npm run build:silent	静默构建（仅失败时输出，CI 友好）
npm run lint	ESLint 检查
npm test	单元测试 + E2E 测试

---

9. 下一步

• 想了解都能做什么 → 核心功能
• 想知道有哪些工具可用 → 内建工具参考
• 想用说的代替打字 → 语音输入（本地 STT）
• 想调优推理与反思 → 配置说明
• 想搞懂原理 → 架构总览
• 遇到问题 → 常见问题