a4agent 面向 Windows 10/11 64 位桌面环境分发，普通用户通过安装包图形化安装即可；开发者也可以从源码直接运行。本文章覆盖下载安装、首次运行注意事项、覆盖升级、卸载与数据清理，以及面向开发者的源码运行与打包构建方法。
1. 下载安装
从项目的发行版（Release）页面下载最新安装包 a4agent-setup-<版本>.exe：
| 事项 | 说明 |
|---|---|
| 系统要求 | Windows 10 / 11，64 位 |
| 安装方式 | 每用户安装（免管理员权限），双击按向导完成 |
| 快捷方式 | 自动创建开始菜单与桌面快捷方式 |
| 完整性 | 建议核对发布页提供的 SHA256 校验值后再运行 |
安装包采用每用户模式，全程不需要 UAC 提权；应用本体、前端资源与运行时依赖全部随包内置，安装后可离线使用。
2. 首次运行
- 从开始菜单或桌面快捷方式启动 a4agent；
- 若出现 Windows SmartScreen 提示，点击「更多信息 → 仍要运行」——应用未做商业代码签名，属正常现象，不影响功能；
- 打开界面后选择预置服务商模板，填入 API Key 即可创建配置方案并一键切换，快速路径见项目总览与快速开始。
两个常见提示的处理：
- 杀毒软件报毒：PyInstaller 打包的程序偶被安全软件误报，添加信任或排除即可，也可将样本提交厂商申诉；
- 单实例限制：应用通过系统互斥体保证同时只有一个实例在运行，重复启动不会开出第二个窗口。
此外，运行安装包或卸载程序时若检测到应用正在运行（主界面或后台翻译代理），会弹出中文确认框（自 0.3.1 起）：确认后一键刹停全部相关服务再继续——优雅终止 3 秒、强制结束、最多再等 10 秒，杀不掉会明确报错中止，绝不留下半装状态；拒绝则中止安装。应用内更新触发的静默安装自动按确认处理，不会卡在弹框。
3. 覆盖升级
升级就是用新版安装包再装一遍：
下载新版 a4agent-setup-*.exe → 双击运行 → 向导覆盖安装 → 启动即新版
- 升级前应用会自动停止后台翻译代理并清理旧文件，避免文件占用导致覆盖失败；
- 运行数据（数据库、配置备份）保存在
%APPDATA%\a4agent\，覆盖安装完整保留，无需重新配置； - 更省事的方式是等应用内更新提醒，点几下完成同样的事，机制见自动更新。
3.1 从 a4api 升级（v0.3.x 及更早 → 0.4.0+）
产品自 0.4.0 起由 a4api 更名为 a4agent，老版本用户直接安装新版即可，全部迁移自动完成：
| 迁移项 | 行为 |
|---|---|
| 数据目录 | 首次启动把 %APPDATA%\a4api\ 整体迁入 %APPDATA%\a4agent\（含本地模型引擎等大文件），目录被占用时退化为逐项拷贝，数据不丢 |
| 程序目录 | 安装器把程序目录从 Programs\a4api 迁到 Programs\a4agent，安装后清理旧目录与旧快捷方式 |
| 托管条目前缀 | 此前写入各工具配置的 a4api_p* 条目在下次切换时自动替换为 a4a_p*，不留孤儿配置 |
| 环境变量 | A4API_* 旧名仍可识别，脚本与 CI 无需立即改名 |
两点保障：安装器检测到新旧两个版本同时安装会刹停确认，避免双版本并存；v0.3.x 的「检查更新」也能直接发现并升级到新版（Release 同时提供兼容旧更新链的 a4api-setup-*.exe 文件名资产，字节与新版一致）。
4. 卸载与数据清理
| 动作 | 方法 | 结果 |
|---|---|---|
| 卸载程序 | Windows「设置 → 应用」中卸载 a4agent | 程序文件被移除 |
| 数据保留 | 卸载默认不动 %APPDATA%\a4agent\ |
配置方案、密钥库、备份保留，重装后原样恢复 |
| 彻底清除 | 手动删除 %APPDATA%\a4agent\ 目录 |
所有本地数据（含加密密钥库）一并清除 |
日志位于
~/.a4agent/logs/，卸载后如需彻底清痕可一并删除，目录结构详见数据目录与日志说明。
5. 从源码运行（开发者）
环境要求：Windows 10 以上、Python 3.10、uv 包管理器。
uv sync # 安装依赖
uv run python desktop.py # 启动桌面应用
# 或后端单独调试
uv run uvicorn backend.app.main:app --port 8000
# 浏览器调试入口：与已安装版共享同一份数据，先在浏览器验证再打包
uv run python dev_server.py
开发模式下运行时数据写入项目内 backend/database/，与安装版数据目录互不干扰；测试体系运行 uv run pytest 即可。dev_server.py（自 0.3.0 起）是给界面开发用的浏览器调试入口：不弹桌面窗口，与已安装版共享同一份数据目录，适合先在浏览器里验证界面改动再打包。
6. 打包构建（开发者）
前置条件：编译安装包需要 Inno Setup 6：
winget install --id JRSoftware.InnoSetup -e --accept-source-agreements
三种产物形态：
uv run python build.py # 文件夹版（onedir），输出 dist/a4agent/
uv run python build.py --installer # 文件夹版 + Inno Setup 安装包 dist/a4agent-setup-<版本>.exe
uv run python build.py --onefile # 单 exe（临时分发用）
| 构建细节 | 说明 |
|---|---|
| 版本号 | 默认读取 pyproject.toml 的 [project].version，可用 --version 覆盖 |
| 图标 | 由 Pillow 从源图自动生成多尺寸 ico（缺 Pillow 时跳过图标并提示） |
| 前端资源 | LayUI 等静态资源整体打入包内，运行时由 FastAPI 托管，离线可用 |
| ISCC 定位 | 自动探测 Inno Setup 编译器，也可用 --iscc 显式指定路径 |
源码仓库与目录结构见项目总览与快速开始；安装包脚本
installer.iss定义了每用户安装、快捷方式与卸载入口。
7. 常见问题
问：安装需要管理员权限吗？
答：不需要。采用每用户安装模式，写入范围限于当前用户目录，没有 UAC 弹窗；公司受限环境下通常也能正常安装。
问：升级后界面还是旧版本？
答：确认旧实例已完全退出（含后台翻译代理），重新启动即是新版；若通过应用内更新走完流程会自动完成退出与拉起，手动覆盖安装时请先关闭正在运行的窗口。
问：卸载后重装，之前的配置方案还在吗？
答：在。只要没手动删除 %APPDATA%\a4agent\，重装后所有方案、服务商与加密密钥原样可用；这也是「先卸载再装新版」能当升级用的原因。
问：能同时在开发模式与安装版之间切换使用吗？
答：可以，两者数据库相互独立（开发模式在项目 backend/database/，安装版在 %APPDATA%\a4agent\）；但同一时刻只会有一份生效配置写入 ~/.claude 等目标文件，切换时以最后操作为准。
问：遇到问题怎么反馈最有效？
答：推荐用应用内入口——页脚「问题反馈」直接提交（自 0.3.2 起），支持截图（最多 10 张、单张不超过 1MB）、自动附带版本 / 系统等环境信息与可选日志尾部，直达开发者邮箱；网络不通时反馈会先落本地库留档，不会丢失。也可附上 ~/.a4agent/logs/a4agent.log 日志片段到 GitHub 提 Issue（已配置 Bug 报告 / 功能需求结构化模板）。
问：从 a4api 升级后旧的数据还在吗？
答：在。首次启动新版时数据目录自动迁入 %APPDATA%\a4agent\，配置方案、加密密钥与备份原样可用，详见第 3.1 节与数据目录与日志说明的迁移章节。
举手提问