a4agent版本更新说明

本文章以流水线式记录 a4agent（0.3.x 及之前名为 a4api，0.4.0 起更名）从 0.1.0 到当前版本（0.4.0）的完整演进过程：按版本从新到旧逐版本列出新增功能（feat）、问题修复（fix）与行为变化，并标注每个版本引入的能力所对应的功能文档，方便按版本追溯功能来源。

1. 版本演进总览

2. 版本明细

0.4.0 — 品牌 a4api 更名 a4agent（2026-09-26）

• 变更（破坏性变更，均自动迁移）：产品更名 a4api → a4agent（A for Agent），安装包、可执行文件、开始菜单/桌面快捷方式、界面标题与页脚全部启用新名称；托管仓库同步更名为 eogee/a4agent（Gitee / GitHub / GitCode，旧地址自动重定向）
• 新增：数据目录自动迁移——首次启动把 %APPDATA%\a4api\ 整体迁入 %APPDATA%\a4agent\（含本地模型引擎等大文件），目录被占用时退化为关键文件逐项拷贝，数据不丢；库文件 a4api.db → a4agent.db
• 新增：外部配置托管前缀 a4api_p<id> → a4a_p<id>——切换服务商时写入新前缀条目，并一并清理 Claude Code / Codex / dsh / zcode 配置中的旧 a4api_p* 遗留条目，不留孤儿配置
• 变更：环境变量前缀 A4API_* → A4AGENT_*，读取侧新旧双认（脚本与 CI 平滑过渡）
• 变更：日志迁至 ~/.a4agent/logs/a4agent.log（旧目录保留不删，应用内反馈在无新日志时仍可附带旧日志）；更新器 User-Agent 同步为 a4agent-updater/1.0
• 变更：更新器清单地址指向更名后仓库，安装包资产查找兼容旧 a4api-setup-* 前缀；清单验签命名空间保持不变（跨版本更新协议不受更名影响）
• 变更：安装器 AppId 不变、程序目录迁至 Programs\a4agent（UsePreviousAppDir=no），检测到新旧两个版本安装包同时存在时刹停确认，安装后自动清理旧程序目录与旧快捷方式
• 兼容：v0.3.x 的「检查更新」可直接发现并升级到本版本——本次 Release 同时提供 a4agent-setup-*.exe 与兼容旧更新链的 a4api-setup-*.exe 两种文件名（字节一致）

对应文档：安装升级与卸载、数据目录与日志说明、自动更新。

0.3.3 — junction skill 修复 + WinError 448 根治（2026-09-25）

• 修复：技能管理中目录联接（junction / 软链接）形式的 skill 被误拒操作——点「预览 / 打开 / 删除」时报「该路径不在任何已知 skill 存放区中」。原因：操作前的归属校验用 Path.resolve() 把 junction 解析到真实目标路径，与发现流程（不解析链接）口径不一致；现改用不解析链接、不访问文件系统的纯字符串归一化，与发现流程同视角。删除只移走链接本身，链接指向的真实目录不受影响，回收站恢复后链接原样接回
• 修复：Windows 11 24H2「不受信任的装入点」间歇性 WinError 448 导致预览接口 500、前端误报「not valid JSON」——归属校验链路不再访问文件系统，从结构上消除 448 触发条件；前端统一响应解析，非 JSON 错误响应（如 500 纯文本）直接显示真实内容与 HTTP 状态码
• 其他：logo / favicon 资源更新

对应文档：技能管理。

0.3.2 — 应用内反馈直达邮箱 + 版本与更新弹窗（2026-09-24）

• 新增：应用内「问题反馈」——点击页脚「问题反馈」打开反馈弹窗，Bug 报告 / 功能需求两类，支持附带截图（最多 10 张、单张不超过 1MB）与选填联系方式；反馈先落本地库留档（feedback / feedback_images 表）再尽力直接邮件送达开发者邮箱，emailed 标志记录送达结果，网络不通时仅入库、内容不丢；自动采集环境信息（版本 / 系统 / 运行模式），可选附带应用日志尾部；SMTP 凭据存本地私有文件（不入库），未配置时反馈仅入库留档
• 新增：「版本与更新」弹窗——点击页脚版本号弹出：当前版本、完整更新日志（随包内嵌 changelog，由发布流程自动同步）、检查更新按钮与 GitHub Releases 直链
• 改进：全新 logo（应用图标、网页 favicon 与页脚标识全面换新）；GitHub Issue 结构化模板（Bug 报告 / 功能需求表单化，与应用内反馈互补）；代理状态接口响应带上应用版本号，便于排查远端代理场景的版本错配
• 其他：数据库新增 feedback / feedback_images 两张表（启动自动建表）

对应文档：安装升级与卸载、自动更新、数据目录与日志说明。

0.3.1 — 技能迁移自选项目文件夹 + 安装器刹停确认（2026-09-21）

• 修复：技能管理 / MCP 管理 / 本地模型页签一直「加载中…」（v0.3.0 回归）——合并「本地模型」时 llama.js 对同一 filter 的 layui element.on 重复注册覆盖了 app.js 的监听器；现保持唯一注册位置，页签切换改派发 main-tab-changed 自定义事件
• 修复：~/.codex/skills 等目录下的 junction 被 Windows 11 24H2「不受信任的装入点」防护间歇性拒绝遍历（WinError 448），技能发现接口偶发 500——扫描对单个无法访问的目录记警告并跳过，不再影响整体（0.3.3 进一步从结构上消除）
• 新增：技能迁移支持「自选项目文件夹」——目标项目无需事先存在任何 skill，.{tool}/skills 目录缺失时自动逐级创建；桌面端直接调用系统原生目录选择框（pywebview），浏览器调试模式退化为输入路径；从自选路径迁出（作为源端）同样支持；与既有保护完全兼容（非法路径整体预校验、源=目标跳过、同名旧版先入回收站）
• 新增：安装器运行中服务刹停确认——运行安装包/卸载程序时检测到应用正在运行（主界面或后台代理），弹中文确认框：确认后一键刹停全部相关服务再继续（优雅终止 3 秒 → 强制结束 → 最多再等 10 秒，杀不掉明确报错中止）；静默安装（应用内更新触发）自动按确认处理
• 改进：接口错误可观测——桌面打包版接口 500 的堆栈此前完全不可见，现沿 root logger 落盘到日志文件

对应文档：技能管理、安装升级与卸载。

0.3.0 — 完整合并 a4agent：本地大模型推理控制台（2026-09-17）

• 新增：「本地模型」页签——把 llama.cpp 的 llama-server 封装为一键启动的 OpenAI 兼容 API 服务，装哪个引擎、选哪个模型、给什么参数全程可视化；与「API 切换」组合即得 Claude Code 完全离线方案
• 首次配置向导五步（获取引擎 → 检测硬件 → 选择模型目录 → 选择默认模型 → 服务端口）：nvidia-smi + 注册表双路枚举显卡（厂商 / 显存 / 驱动），按显存档位推荐推理预设（上下文长度、KV 缓存量化、MTP 投机解码）
• 引擎自动获取：按显卡下载 llama.cpp 官方预编译引擎（Vulkan / CUDA 12.4 / CUDA 13.3 / CPU，钉定固定版本、二进制可复现），CUDA 主包与 cudart 运行库自动解压合并、原子换入；支持离线安装；检测到旧版已下载的引擎时自动接管，免重复下载
• 模型库：多目录扫描 .gguf，解析大小 / 量化级别 / 原生上下文 / MTP 层，一键设为默认模型；显存溢出两档预警
• 服务运行：运行状态机（启动中 / 运行中 / 失败 / 已停止）+ 实时日志滚动；4 分钟健康检查；端口占用 / 引擎缺失 / 进程崩溃明确报错；运行就绪后定时内存裁剪
• 推理参数可视化：上下文长度、KV 缓存（f16/q8_0/q4_0）、Flash Attention、GPU 层数、MTP 步数（自动探测引擎新 spec 与旧 --mtp 两种写法）、附加参数逃生舱
• API Key 鉴权：一键生成 sk- 随机密钥，局域网开放时建议开启；局域网开放切换（0.0.0.0）；接入页给出 Base URL / Chat 地址 / curl / openai SDK 示例
• 「接入配置方案」：一键创建指向本地服务的配置方案，到「配置方案」页切换即可让四端用上本地模型，与云上 API 无缝互切
• 新增：浏览器调试入口 dev_server.py——与已安装版共享同一份数据，先在浏览器验证再打包，免装快迭代
• 测试：从 172 例增至 212 例（GGUF 合成二进制解析、预设边界、驱动降级推荐、解压路径穿越防护、进程命令行拼装、运行时管理器等）

对应文档：本地模型推理控制台、配置方案与一键切换。

0.2.3 — MCP 一键安装与功能介绍（2026-09-03）

• 新增：「安装 MCP」支持从零新建 server——选择目标应用（Claude Code / Codex / dsh / ZCode，写入该应用全局配置）+ 传输类型（stdio / http / sse，按目标端能力自动过滤，如 Codex 仅 stdio），填写命令/参数/环境变量或地址/请求头
• 新增：粘贴 JSON 批量导入安装——把已有 MCP 配置片段直接粘进来（兼容「mcpServers」顶层、名称作键的 server 字典、单对象三种格式），一次装多个、逐条独立：单条失败（同名冲突、目标端不支持该传输等）不中断其余，并逐条报告成功/失败
• 新增：MCP 卡片「功能介绍」——自动识别常用 server（内置简介库 + npx 包实时查询 npm registry，均有缓存与失败兜底），也支持手工维护说明（本地持久化、跨端共享、留空即清除）
• 改进：MCP 安装 UI 重构、server 命名修正

对应文档：MCP管理。

0.2.2 — ZCode 四端接入 + MCP server 四端管理（2026-09-02）

• 新增：应用目标新增 ZCode（zcode）——ZCode 原生支持 anthropic 与 openai-compatible 两种 provider kind，切换时直连上游写入 ~/.zcode/cli/config.json 与 ~/.zcode/v2/config.json 两份配置（provider 以 a4api_p<id> 命名托管（0.4.0 起前缀升级为 a4a_p<id>）、保留用户手工条目与 hooks，顶层 model 格式为 <provider_id>/<model>，v2 补齐模型元数据）；不受服务商协议限制、无需本地翻译代理（Anthropic 类型服务商也可选 ZCode 目标）；状态接口返回 ZCode 当前生效模型
• 新增：技能管理由三端扩展为四端——新增 ZCode 全局级 ~/.zcode/skills 与项目级 .zcode/skills 目录，发现 / 聚合标注 / 迁移 / 一键适配四端 / 回收站全链路支持
• 新增：MCP server 四端管理模块——自动发现 Claude Code / Codex / dsh / ZCode 的全局与项目级 MCP server 并聚合标注（「已在 N 端存在」），详情中 env / headers 一律脱敏（只回显键名）
• 新增：MCP 跨端迁移按传输能力矩阵严格校验（Claude Code / ZCode 支持 stdio/sse/http，Codex 仅 stdio，dsh 支持 stdio/streamable-http 且无项目级），不兼容组合整对失败并留日志、不静默降级；目标端同名 server 先快照进回收站再写入，写入前自动备份目标配置文件
• 新增：MCP 回收站与迁移日志——被替换 / 删除的 server 配置片段快照进回收站（30 天内可恢复 / 彻底删除），快照中 env / headers 用 DPAPI 加密落盘、恢复时解密写回；每次迁移写入 McpMigration 日志可追溯
• 修复：同一配置文件多个 server 连续迁移时去重误跳过的问题
• 其他：数据库新增 mcp_migrations / mcp_trash 两张表（启动自动建表）；前端新增「MCP 管理」页签

对应文档：配置方案与一键切换、服务商管理与预置模板、本地翻译代理、技能管理、MCP管理、安全设计、数据目录与日志说明。

0.1.5 — dsh 统一代理透传 + 新增 OpenCodeGo 模板（2026-08-18）

• 变更：dsh 从「直连上游」改为统一经本地翻译代理的 /chat/completions 透传端点连接上游——代理把上游流式分片中 tool_calls 的 null 字段归一为省略键，规避 dsh 适配器把工具名与 ID 覆盖为空导致 unknown tool "" 的问题（如 opencode zen 等上游以 null 填充后续分片）
• 新增：预置模板 OpenCodeGo-openai（https://opencode.ai/zen/go/v1，OpenAI 兼容，走本地翻译代理），与 DeepSeek / 智谱 / OpenRouter / 本地 LLM Studio 并列，开箱即用
• 变更：dsh 配置写入时 baseURL 指向本地代理、凭证写入代理鉴权 token（真实上游 Key 由代理持有，不落盘明文）；切换后 watcher 热加载，新会话即生效
• 其他：Codex 与 dsh 目标徽章配色调整；发布页补充 v0.1.5 安装包 SHA256 校验值

对应文档：dsh目标切换、服务商管理与预置模板、本地翻译代理。

0.2.0 — 三端技能管理（2026-08-22）

• 新增：「技能管理」页与 /skills 接口簇（discover / migrate / delete / trash / trash 恢复 / trash 删除 / content / open / project-roots），实现三端 skill 发现、迁移、回收站
• 发现：自动扫描三端全局根与各项目的根（项目根列表持久化到 projects.json），以 frontmatter name 为唯一标识聚合去重并标注「已在 N 端存在」；Codex 全局根的 .system/ 等保留目录跳过
• 迁移：跨端迁移为非破坏复制（源端保留），目标端同名旧版先移入回收站再写入，绝不静默覆盖；每次迁移写入 SkillMigration 日志可追溯
• 一键适配三端：项目视图内一键把该项目全部 skill 按缺失端补齐到三端，弹窗预览迁移计划，迁移带进度条并临时锁定页面其他操作
• 回收站：删除的 skill 移入回收站，30 天内可恢复原位或彻底删除，过期惰性清理；恢复冲突（原位置已存在同名目录）拦截
• 前端新增技能管理页：全局/项目视图、迁移弹窗、SKILL.md 预览、回收站/迁移日志弹窗、项目根目录配置

对应文档：技能管理。

0.2.1 — dsh 凭证 refs 布局修复 + 遗留 max_tokens 回退（2026-08-23）

• 修复：dsh 凭证写入布局。build_dsh_credentials 此前把 DEEPSEEK_API_KEY 写到 .credentials.yaml 顶层，而 dsh 要求 version-1 布局（顶层仅允许 version / refs / records），导致切换后 dsh 因顶层未知键拒绝启动（unknown top-level key）；现在固定输出 {version: 1, refs: {...}}，DEEPSEEK_API_KEY 写入 refs 下，旧版扁平文档自动并入 refs 迁移，records 段（如 OAuth 记录）原样保留
• 修复：max_tokens 历史遗留回退。切换时既有 maxTokens 恰为 dsh 适配器默认 256000 视为历史遗留（并非用户手动选择），回落安全默认 131072（实测 Console Go 限 [1,131072]，超限被 400 [1210] 打回）；显式填写仍最优先
• 测试：更新 test_config_manager / test_switch 回归用例，后端测试 117 个全部通过

对应文档：dsh目标切换、配置方案与一键切换。

0.1.4 — dsh 目标一键切换与 max_tokens 输出上限（2026-08-14）

• 新增：配置方案支持第三个应用目标 dsh（DeepSeek Harness）——切换时写入 ~/.dsh/settings.yaml 的 llm-deepseek 与 agent-default-model 段及 .credentials.yaml 凭证，其余段落原样保留
• 新增：dsh 目标的 max_tokens 单次输出上限字段——显式填写优先，其次保留用户手动值，兜底安全值 131072，规避 dsh 适配器默认 256000 超出多数上游上限被直接打回 INVALID_REQUEST
• 特性：dsh 配置文件被 watcher 热加载，切换后新会话即生效、无需重启；两个文件切换前均自动备份

对应文档：dsh目标切换、配置方案与一键切换。

0.1.3 — tool 响应重排修复 Codex 重连 400 + 429 退避（2026-08-11）

• 修复：tool 响应消息顺序错乱导致 Codex 重连上游报 400——代理对工具响应消息做重排后再转发
• 新增：透传上游 429 限流响应连同 Retry-After 头原样回传，客户端可正确退避重试

对应文档：本地翻译代理、Codex目标切换。

0.1.2 — 更新清单并行拉取 + 残缺 tool_call 过滤（2026-08-11）

• 优化：更新清单改为 GitHub 与 Gitee 并行拉取，先到先用，缩短检查更新耗时；更新说明支持 Markdown 渲染
• 修复：对话历史中残缺的 tool_call 记录会被部分上游拒绝（400），代理在转发前过滤此类残缺项
• 其他：应用内更新说明的链接与引用块样式对齐设计规范

对应文档：自动更新、本地翻译代理。

0.1.1 — Codex developer 角色映射修复（2026-08-11）

• 修复：Codex 请求中的 developer 角色被部分上游拒绝（400），翻译时统一映射为 system 角色

对应文档：Codex目标切换。

0.1.0 — 首个公开发行版（2026-08-09）

a4api（0.4.0 起更名 a4agent）首个发行版，能力全集：

• 新增：配置方案卡片化管理（新增、编辑、删除、一键切换、当前生效高亮），服务商管理与预置模板自动播种
• 新增：Claude Code 与 Codex 双应用目标——写 ~/.claude/settings.json（合并式更新、原子写入、自动备份滚动保留）与 ~/.codex/config.toml（托管 a4api_p* 服务商条目（0.4.0 起前缀升级为 a4a_p*）、维护 models.json 模型目录）
• 新增：本地翻译代理独立进程——Anthropic /v1/messages 翻译为 Chat Completions 接入 Claude Code；Responses 协议翻译让 Codex 对接智谱 GLM 等 Chat Completions 上游；仅监听 127.0.0.1、随机 token 鉴权、应用退出后仍存活
• 新增：Codex 原生 Responses 直连开关（DeepSeek 官方上游免代理）与服务商名称实时搜索
• 新增：API Key 使用 Windows DPAPI 加密存储，接口永不回显明文；CORS 白名单、单实例互斥、切换日志等加固
• 新增：统一日志体系与自动化测试（加解密、配置生成、协议翻译、更新器回归）
• 新增：应用自更新——Ed25519 签名清单验签、GitHub/Gitee 双源下载、SHA256 校验、防降级，确认后拉起安装器完成升级
• 新增：Inno Setup 每用户安装包分发（免 UAC），打包自动生成多尺寸图标

对应文档：项目总览与快速开始、ClaudeCode目标切换、Codex目标切换、本地翻译代理、安全设计、自动更新。

3. 升级说明

• 从发行版（Release）页面下载新版 a4agent-setup-*.exe 覆盖安装即可，建议核对发布页提供的 SHA256 校验值；
• 从 a4api（v0.3.x 及更早）升级到 0.4.0+：产品已更名 a4agent，直接安装新版即可——首次启动会把 %APPDATA%\a4api\ 数据自动迁入 %APPDATA%\a4agent\，安装器把程序目录从 Programs\a4api 迁到 Programs\a4agent 并清理旧快捷方式；此前写入各工具配置的 a4api_p* 托管条目会在下次切换时自动替换为 a4a_p*，环境变量 A4API_* 旧名仍可识别，全程无需手工干预；v0.3.x 的「检查更新」也能直接升级到新版（Release 提供兼容旧更新链的 a4api-setup-*.exe 文件名资产）；
• 升级前应用会自动停止后台翻译代理并清理旧文件，避免文件占用导致覆盖失败；运行安装包时若检测到应用正在运行，会先弹确认框一键刹停相关服务（0.3.1 起）；
• 运行数据（数据库、配置备份）保留在 %APPDATA%\a4agent\，覆盖升级后配置方案与加密密钥完整可用，无需重新配置；
• 0.2.2 起新增 ZCode 目标与 MCP 管理：目标工具需已安装 ZCode 桌面端与相应 MCP 配置才会出现在发现结果中；新增的 mcp_migrations / mcp_trash 表由数据库启动自动建表，无需手工处理；
• 0.3.0 起新增「本地模型」推理控制台：首次使用会进入五步配置向导，已下载过引擎的旧版安装会自动接管引擎目录，无需重复下载；
• 旧版 api-switch 的数据目录会在新版首次启动时一次性自动迁移；
• 预发布版本仅当当前运行版本也是预发布时才会提示，正式版用户不会收到试验性推送。

4. 版本检查与更新方式

应用在启动时会静默检查更新，也可随时点顶部「检查更新」手动触发：发现新版本后弹窗展示版本号与更新说明（由签名清单携带，篡改即拒收），确认后后台下载并显示进度、可取消；校验通过再次确认即停止代理、退出应用并拉起 Inno Setup 安装向导完成升级；不需要的版本可选择「忽略此版本」。机制细节见自动更新。