# QuickAI

**Repository Path**: panda26/QuickAI

## Basic Information

- **Project Name**: QuickAI
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickAI (Go / Wails 版)

全局 AI 文本处理工具：**选中文字 → 快捷键 → 预设 Prompt → 指定模型 → 结果回填**。

单 exe 分发（约 12 MB），无 Python / Node 运行时依赖。基于 **Wails v3**（v3.0.0-beta.18）。

## 功能

- **全局快捷键**触发动作（`RegisterHotKey`，冲突时报错不静默，被占用的键自动跳过）
- **菜单模式**：`menu_hotkey` 在鼠标处弹出动作菜单（↑↓ 选择 / Enter 执行 / Esc 关闭）
- **取词**：模拟 Ctrl+C 读剪贴板（按键间隔注入，兼容浏览器/IDE/PDF）；失败自动**回退读剪贴板旧内容**；再失败弹窗提示**手动填写原文后重试**
- **原文框可编辑**：临时编辑、手动粘贴后点「重试」即可重跑
- **设置面板**（托盘「设置…」）：
  - 快捷键 / 提示词 / 模型 / Provider（含 API 格式）在线修改，保存即生效（热键热重载）
  - 按 Esc 关闭弹窗：开/关
  - 失焦自动隐藏：开/关
  - 弹窗位置：跟随鼠标 / 上次关闭位置
  - 上下文轮数（history）
- **流式输出**（chat_completions 协议默认开启）
- **错误全透出**：HTTP 状态码、API 错误体直接显示在结果窗
- 托盘常驻 + 单实例锁 + 替换（写剪贴板 + Ctrl+V）

## 日志

日志文件：**exe 同目录下的 `quickai.log`**（便携式，与 config.yaml/overrides.json 在一起）。
记录启动流程、热键注册/触发、取词来源、每次 LLM 请求的 provider/model/协议/耗时、完整错误。排查问题先看这个文件。
（exe 目录不可写时自动回退到 `%USERPROFILE%\.quickai\quickai.log`。）

## 取词与剪贴板

- **剪贴板备份升级（P1）**：取词前对剪贴板做**全格式快照**（文本/图片/文件列表）并在取词后还原——此前只备份文本，剪贴板里是图片时会被取词覆盖丢失
- **多格式读取**：`GetClipboardContent` 绑定按 图片 > 文件 > 文本 优先级返回结构化内容（图片归一化为 PNG，文件返回路径列表），为剪贴板管理（docs/clipmgr-plan.md）和多模态输入打底
- **剪贴板历史（P2，默认关闭）**：`config.yaml` 加 `clipboard_manager: {enabled: true}` 开启。本地记录复制内容（文本/图片/文件路径），bbolt 落盘 + 缩略图，条数/磁盘/TTL 三重上限，图钉置顶豁免清理；隐私：自身写入过滤 + 前台窗口排除名单 + 托盘可暂停。数据目录：配置目录下 `clipdata/`，删目录即清空历史

## 三种 API 协议

Provider 增加 `api_format` 字段（缺省 `chat_completions`）：

| api_format | 协议 | 端点 | 鉴权头 |
|---|---|---|---|
| `chat_completions` | OpenAI Chat Completions | `{base_url}/chat/completions` | `Authorization: Bearer` |
| `anthropic` | Anthropic Messages | `{base_url}/v1/messages`（base 含 `/v1` 自动去重） | `x-api-key` + `anthropic-version` |
| `responses` | OpenAI Responses | `{base_url}/responses` | `Authorization: Bearer` |

OpenAI / OpenRouter / SiliconFlow / Ollama 等均走 `chat_completions`；Anthropic 官方或其兼容网关走 `anthropic`。

## 配置

`config.yaml`（providers / models / 全局项）+ `prompts.yaml`（actions，可选，同名 action 覆盖）。
`api_key` 支持 `${ENV_VAR}` 引用。完整示例见 [configs/](configs/)。

```yaml
# config.yaml
timeout: 60
menu_hotkey: ctrl+alt+a

providers:
  openrouter:
    base_url: https://openrouter.ai/api/v1
    api_key: ${OPENROUTER_API_KEY}
  anthropic:
    base_url: https://api.anthropic.com
    api_key: ${ANTHROPIC_API_KEY}
    api_format: anthropic      # ← 指定协议
  ollama:
    base_url: http://127.0.0.1:11434/v1
    api_key: ollama

models:
  fast: {provider: openrouter, model: openai/gpt-4o-mini}
  sonnet: {provider: anthropic, model: claude-sonnet-4-5}
```

```yaml
# prompts.yaml
actions:
  翻译:
    hotkey: ctrl+alt+t
    model: sonnet          # 引用 models 别名；或 provider+model_name
    history: 3             # 携带最近 3 轮上下文（缺省 0 = 单发）
    system: |
      You are a professional translator...
```

## 开发

```bash
wails3 task dev      # 开发模式（热重载）
build.bat            # 构建（wails3 task windows:build：前端构建 → syso → go build，自动取最新 git tag 注入版本号）
go test ./...        # 单元测试（llm / config / app / updater）
```

构建体系说明（Wails v3）：

- `Taskfile.yml` + `build/Taskfile.yml` + `build/windows/Taskfile.yml` 定义任务链；
- `wails3 generate bindings -d frontend/bindings -ts` 生成 TS 绑定（Go 侧 `App` 以 Service 注册）；
- 托盘使用 v3 内置 `SystemTray`（已移除 `getlantern/systray` 依赖）。

## 版本与升级

- 版本号取自 git tag（`build.bat` 构建时通过 `-ldflags` 注入；无 tag 时为 `dev`）。
- **自动发布**：`release.bat 1.0.0.4`（或 `release.ps1`）一条命令完成 打 tag → 构建 → 生成更新日志 → 创建 Gitee Release → 上传 `QuickAI.exe`。前提：工作区干净；已设置 `GITEE_TOKEN` 环境变量（Gitee 私人令牌，勾 `projects` 权限，**只放环境变量，不入库**）。只有新 tag 触发发布，普通提交推送不受影响。
- 应用启动时后台静默检查 [Gitee 最新 Release](https://gitee.com/panda26/QuickAI/releases)（tag 即版本号，按数字段比较）；有新版本时主窗口顶部出现提示条，用户点击「一键更新」后下载（带进度）→ 自动替换 exe 并重启，旧程序备份为 `QuickAI.exe.old`。设置面板也可手动「检查更新」。
- 离线或检查失败只记日志，不打扰使用；`dev` 构建不会收到升级提示。

运行：`QuickAI.exe -config <配置目录>`，或设置 `QUICKAI_CONFIG` 环境变量；默认读 exe 同级目录下的 `config.yaml` / `prompts.yaml`。
**首次运行**若找不到 `config.yaml`，会自动在同目录生成一份可用的模板配置（不覆盖已有文件），应用照常启动；之后可编辑该文件或在设置面板里调整。

## 目录

```
main.go                  入口：配置加载、单实例锁、Wails v3 应用/窗口创建
internal/config/         YAML 配置：api_format、${ENV} 展开、双文件合并、快捷键冲突校验
internal/llm/            三协议客户端（Chat Completions / Anthropic / Responses）+ 流式 + 会话历史
internal/system/         Win32：RegisterHotKey、剪贴板、SendInput 取词/粘贴、单实例锁
internal/app/            编排：托盘（v3 SystemTray）、动作分发、事件桥接、Service 绑定
frontend/                Vue3 + TS：结果窗（原文可编辑）+ 动作菜单；绑定在 frontend/bindings/
build/                   Taskfile 构建任务 + Windows 资源（图标/manifest/info.json）
configs/                 config.example 示例
docs/clipmgr-plan.md     剪贴板管理功能方案（待实施）
```

## 与 Python 版的差异

- 热键从低级钩子换成 `RegisterHotKey`：被占用时**启动即报错**，不再静默抢注
- 对话历史 / 流式 / 取词回退 / 取词失败手填 / 设置面板为新增能力
- 窗口为 WebView2 渲染；关闭 = 隐藏（常驻托盘）
- 拖动弹窗：按住标题栏拖动（无边框窗口 CSS `--wails-draggable`）