a4agent v0.4.2

a4agent v0.4.2

重要修复

应用内更新后应用「消失」问题（建议受影响用户手动重装本版）

• 修复 v0.4.0 → v0.4.1 应用内更新后安装目录被清空的问题：安装器在「同目录升级」场景误判为改名迁移，收尾清理时把刚装好的新版一并删除，表现为更新完成后提示找不到 a4agent、桌面快捷方式失效
• 判断依据已改为归一化路径比较（去除尾部反斜杠），同目录升级不再触发清理；真正的改名迁移（v0.3.x → 新版）行为不变
• 受过此问题影响的用户：应用已被删除、无法收到本更新提示，请到 Release 页 下载 a4agent-setup-0.4.2.exe 重新安装一次即可；配置与数据存于 %APPDATA%\a4agent，全程未受影响
• 顺带修复：升级安装的开始菜单组名沿用旧 a4api 组的问题（UsePreviousGroup=no），并清理旧组残留

更新下载提速约 20 倍

• 安装包下载由「GitHub 优先、失败才回退 Gitee」的串行模式，改为双镜像并行竞速、快者胜出：此前国内访问 GitHub 资产常只有 ~0.1 MB/s 且因「能连上」永不回退，整个安装包磨在慢源上（实测约 40 分钟）
• 现在慢源/挂源自动落败并提前收手（领先超过 8MB 即判胜），进度条始终显示领先者；实测竞速命中 Gitee 约 1.9 MB/s，全程 21MB 约 11 秒

其他

• README「自动更新与安全」章节同步竞速下载说明

校验

• 安装包：a4agent-setup-0.4.2.exe（21,080,503 字节）
• SHA256：149351F7086EF2E15E7D1C57AA22165930A52B408BCE47DF416926183E007B01

a4agent v0.4.1

a4agent v0.4.1

本地模型（llama.cpp）

引擎升级至 llama.cpp b11370

• 引擎版本 b10919 → b11370（上游 2026-10-03 发布），带来 llama-server 原生 System One 决策模型端点 /v1/systemone
• 接入信息卡片与 connect 接口新增决策模型端点展示，局域网接入第三方客户端时一目了然
• CUDA 引擎包随上游 13.4 更名：cuda133 → cuda134，旧配置标识自动映射，已配置用户无需任何调整
• 引擎包资产名与体积按上游 Release 页核对更新

其他

• 更新器 User-Agent 同步为 a4agent-updater/1.0
• 全新定稿品牌图标：前端页头/Favicon 与程序图标、安装器资源统一替换
• README：联系方式统一移至文末章节

校验

• 安装包：a4agent-setup-0.4.1.exe（21,077,562 字节）
• SHA256：7B446BD8DEEDD2B5053DADF55ECA03BBEE18AB3936DF805199DA2478D048DF30

a4agent v0.4.0

a4agent v0.4.0

品牌

a4api 正式更名为 a4agent

• 产品更名为 a4agent（A for Agent）：安装包、可执行文件、开始菜单/桌面快捷方式、界面标题与页脚全部启用新名称
• 数据自动迁移：首次启动新版时，旧 %APPDATA%\a4api\ 数据目录（配置方案、供应商、备份、本地模型设置）整体迁入 %APPDATA%\a4agent\，无需任何手工操作；极端情况下目录被占用时自动退化为逐项拷贝，数据不丢
• 外部配置无缝接管：切换服务商时写入 Claude Code / Codex / dsh / zcode 配置的托管条目前缀由 a4api_p<id> 统一升级为 a4a_p<id>，切换时自动清理旧前缀条目，不留孤儿配置
• 老版本更新链路不受影响：v0.3.x 的「检查更新」仍可正常发现并升级到本版本（本次 Release 同时提供 a4agent-setup-*.exe 与兼容旧版的 a4api-setup-*.exe 两种文件名）
• 托管仓库同步更名为 eogee/a4agent（Gitee / GitHub / GitCode），旧地址自动重定向
• 日志目录迁至 ~/.a4agent/logs/a4agent.log（旧目录保留不删，应用内反馈在无新日志时仍可附带旧日志）

改进

• 环境变量前缀 A4API_* → A4AGENT_*，旧变量名仍可识别（脚本/CI 平滑过渡）
• 更新器支持按新旧两种安装包名匹配清单资产

校验

• 安装包：a4agent-setup-0.4.0.exe（20,748,981 字节）
• SHA256：C2A7C26FCC713132EBFACF90DC3DF1E8073C9BF823B9870DAF32ABED4A3DA8A0
• 兼容资产：a4api-setup-0.4.0.exe（与上者字节一致，供 v0.3.x 老版本自动更新）

a4api v0.3.3

a4api v0.3.3

修复

技能管理：目录链接（junction）skill 被误拒操作

• 部分用户把 skill 以目录联接（junction / 软链接）形式放进工具的全局目录（例如 Codex 端 video-use 是指向仓库真实目录的链接），点「预览 / 打开 / 删除」时弹出「该路径不在任何已知 skill 存放区中，拒绝操作」
• 原因：操作前的归属校验使用 Path.resolve()，会把 junction 解析到真实目标路径，与发现流程（不解析链接，链接就是一个普通子目录）口径不一致，导致路径被误判
• 现在归属校验改用不解析链接、不访问文件系统的纯字符串归一化，与发现流程同视角；junction skill 可正常预览 / 打开 / 删除，且删除只移走链接本身，链接指向的真实目录不受影响，回收站恢复后链接原样接回

技能管理：预览报「not valid JSON」的真实原因被掩盖

• 部分用户机器上存在 Windows 11 24H2 的「不受信任装入点」，归属校验中一处未加容错的 resolve() 会间歇性抛出 WinError 448，后端未捕获返回 500；前端又把「JSON 解析失败」当错误信息弹出（Unexpected token 'I', "Internal S"... is not valid JSON），真实原因被掩盖
• 归属校验链路已不再访问文件系统，从结构上消除 448 触发条件；前端统一响应解析，非 JSON 错误响应（如 500 纯文本）直接显示真实内容与 HTTP 状态码，不再出现令人困惑的 JSON 解析报错

改进

• logo / favicon 资源更新（页面缓存戳刷新至 20260925）

校验

• 安装包：a4api-setup-0.3.3.exe
• SHA256：480104F1BD7EFF2F095D4BCFAC415394C03649CC54EC33D8CF4989622474A8E7

a4api v0.3.2

a4api v0.3.2

新增

应用内「问题反馈」：直达开发者邮箱

• 点击页脚「问题反馈」打开反馈弹窗，Bug 报告 / 功能需求两类，支持附带截图（最多 10 张、单张 ≤1MB）与选填联系方式
• 反馈先落本地库留档（feedback / feedback_images 表），再尽力直接邮件送达开发者邮箱，截图以附件随行；emailed 标志记录送达结果，网络不通时仅入库、内容不丢
• 自动采集环境信息（版本 / 系统 / 运行模式），可选附带应用日志尾部，免去手写复现环境
• SMTP 凭据存本地私有文件（不入库）；未配置时反馈仅入库留档，不影响提交

「版本与更新」弹窗

• 点击页脚版本号弹出「版本与更新」：当前版本、完整更新日志（随包内嵌 changelog）、检查更新按钮与 GitHub Releases 直链
• 更新日志由发布流程自动同步（release_body.md → 随包内嵌），应用内展示与 Release 页保持一致
• 弹窗固定尺寸、内容区内部滚动，任何窗口大小下保持垂直居中

改进

• 全新 logo：应用图标、网页 favicon 与页脚标识全面换新
• GitHub Issue 结构化模板：Bug 报告 / 功能需求表单化；与应用内反馈互补——应用内提交会自动带齐环境信息
• 代理状态接口响应带上应用版本号，便于排查远端代理场景的版本错配

校验

• 安装包：a4api-setup-0.3.2.exe
• SHA256：884CA25D4CDB8A67126C5EB0CF50E15A7F8B8408C5E808592310CB3541203809

a4api v0.3.1

a4api v0.3.1

修复

技能管理 / MCP 管理页一直「加载中…」（v0.3.0 回归）

• 根因：v0.3.0 合并「本地模型」时，llama.js 对 tab(main-tab) 的重复注册覆盖了 app.js 的监听器——layui 对同一 filter 的 element.on 是覆盖式注册（后注册替换先注册），导致技能/MCP 两个页签的懒加载回调永远不触发
• 修复：app.js 保持唯一注册位置，tab 切换改派发 main-tab-changed 自定义事件，llama.js 改听该事件；技能管理、MCP 管理、本地模型三个页签全部恢复正常

技能发现接口偶发 500（Windows 11 24H2「不受信任的装入点」）

• ~/.codex/skills 等目录下的 junction（如指向项目目录的 video-use）会被 Windows 11 24H2 安全防护间歇性拒绝遍历（WinError 448），该错误码不在 pathlib 的可忽略名单里，直接把整个发现接口炸成 500
• 现在扫描对单个无法访问的目录记警告并跳过，不再影响整体；同类防护覆盖了技能读取、路径校验与迁移冲突扫描
• 该 junction 在被 Windows 拦截期间会临时从列表消失、放行后自动恢复，属预期行为

新增

技能迁移支持「自选项目文件夹」

• 迁移对话框新增自选项目文件夹目标：目标项目无需事先存在任何 skill（哪怕只有 Agent 工作记录），.{tool}/skills 目录缺失时自动逐级创建
• 桌面端直接调用系统原生目录选择框（pywebview），浏览器调试模式退化为输入路径
• 与既有保护完全兼容：非法路径整体预校验拦截、源=目标自动跳过、同名旧版先入回收站；从自选路径迁出（作为源端）同样支持

安装器运行中服务刹停确认

• 运行安装包/卸载程序时检测到 a4api 正在运行（主界面或后台代理），弹中文确认框：确认后一键刹停全部相关服务再继续，拒绝则中止安装
• 刹停策略：优雅终止 3 秒 → 强制结束 → 最多再等 10 秒；杀不掉明确报错中止，绝不留半装状态
• 静默安装（应用内更新触发）自动按确认处理，不再弹框卡住

改进

• 接口错误可观测：桌面打包版此前接口 500 的堆栈完全不可见（uvicorn 默认日志不落盘、窗口化程序无 stderr）；现改为沿 root logger 落盘，异常堆栈写入 ~/.a4api/logs/a4api.log

校验

• 安装包：a4api-setup-0.3.1.exe
• SHA256：DB729E1E0989BF13779DC2120EA2B5FC5EFEB5F74AB116B294165E5FDEF5673D

a4api v0.3.0

a4api v0.3.0

重磅：完整合并 a4agent，新增「本地模型」推理控制台

把 llama.cpp 的 llama-server 封装为一键启动的 OpenAI 兼容 API 服务——装哪个引擎、选哪个模型、给什么参数，全程可视化操作。与「API 切换」组合，即得 Claude Code 完全离线方案。

首次配置向导

• 硬件检测与预设推荐：nvidia-smi + 注册表双路枚举显卡（厂商 / 显存 / 驱动），按显存档位推荐推理预设（上下文长度、KV 缓存量化、MTP 投机解码）
• 引擎自动获取：按显卡自动下载 llama.cpp 官方预编译引擎（Vulkan / CUDA 12.4 / CUDA 13.3 / CPU，钉定 b10919，二进制可复现），CUDA 主包与 cudart 运行库自动解压合并、原子换入；支持离线安装；已装旧版 a4agent 时自动接管其引擎，免重复下载
• 模型库：多目录扫描 .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 无缝互切

交互细节

• pywebview 原生文件夹 / 文件选择对话框（添加模型目录、浏览 mmproj），浏览器模式自动退化为手动输入
• 全局统一的 layui primary 复选框皮肤与品牌色单选；运行日志与推理设置卡片等高布局

其他

• 新增浏览器调试入口 dev_server.py（uv run python dev_server.py）：与已安装版共享同一份数据（%APPDATA%\a4api），先在浏览器验证再打包，免装快迭代
• 测试从 172 例增至 212 例（GGUF 合成二进制解析、预设边界、驱动降级推荐、解压路径穿越防护、进程命令行拼装、运行时管理器等）

校验

• 安装包：a4api-setup-0.3.0.exe
• SHA256：CBC5CE69CB2A0E52F2453FCC825883609448824D312FF4A1CB9E16108FC28E36
• 建议下载后核对校验值，确保文件完整未被篡改。

a4api v0.2.3

a4api v0.2.3

更新内容

新增：MCP 安装与 JSON 批量导入

• 安装 MCP：可在任意应用端（Claude Code / Codex / dsh / ZCode）从零新建 server——选择目标应用（写入该应用全局配置）+ 传输类型（stdio / http / sse，按目标端能力自动过滤，如 Codex 仅 stdio），填写命令 / 参数 / 环境变量或地址 / 请求头。
• JSON 批量导入：把已有的 MCP 配置片段直接粘贴进来（兼容「mcpServers」顶层、名称作键的 server 字典、单对象三种格式），一次装多个，逐条独立——单条失败（同名冲突、目标端不支持该传输等）不中断其余，并逐条报告成功/失败。
• 安装走各端原生渲染与原子写（目标同名已存在会明确拒绝，可改用迁移或先删除），既有 server 与其它配置键原样保留；安装后立即出现在卡片列表，并自动匹配功能介绍。
• 全新 server 可附带简介（description），功能介绍可用：自定义说明、配置内 carry 简介、内置简介库自动匹配（按 server 名/命令关键词）、npm 联动解析。

修复

• 修复 layui layer 在 type:1 内联内容时关闭按钮被放进 .layui-layer-content 的渲染怪癖，弹窗关闭按钮归位到标题栏。

文档与测试

• README「安装 MCP」章节更新：改为任意应用表述 + 补充 JSON 批量导入说明。
• test_mcp_manager.py 新增 JSON 导入解析（三格式兼容 / 非法输入）、批量安装与部分失败、API 路由用例。

校验

• 安装包：a4api-setup-0.2.3.exe
• SHA256：584745240A5C48918A59D70B4342922B8F70A2B72FA943FDF895599711CDB0E2
• 建议下载后核对校验值，确保文件完整未被篡改。

a4api v0.2.2

a4api v0.2.2

更新内容

新增：ZCode（智谱 Agentic 开发环境）全量适配，四端统一管理

• API 切换：新增 zcode 目标。ZCode 原生支持 Anthropic / OpenAI 两种协议，切换时直连写入 CLI（~/.zcode/cli/config.json）与桌面端（~/.zcode/v2/config.json）两份配置，无需本地翻译代理、不受服务商协议限制；provider 条目以 a4api_p<id> 托管、切换时整体替换旧条目并保留用户手工添加的 provider，hooks 等其它键原样保留。
• 技能管理：三端 → 四端，纳入 ZCode（全局 ~/.zcode/skills / 项目级 <项目>/.zcode/skills），发现、聚合标注、跨端迁移、「一键适配四端」补齐、回收站全链路支持。
• MCP 管理：新增 zcode 端（~/.zcode/cli/config.json / 项目 .zcode/config.json 的 mcp.servers，支持 stdio / sse / http），传输能力矩阵、快照回收站与脱敏机制全覆盖。

新增：MCP 四端管理模块

• 自动发现 Claude Code、Codex、dsh、ZCode 的全局与项目级 MCP server 并聚合标注；跨端迁移按传输能力矩阵严格校验（claude/zcode 支持 stdio/sse/http，codex 仅 stdio，dsh 支持 stdio/streamable-http 且无项目级），不兼容组合整对失败并留日志、不静默降级。
• 目标端同名 server 先快照进回收站再写入；快照中的 env / headers 用 DPAPI 加密落盘、恢复时解密；发现与预览接口对敏感字段一律脱敏，API 永不回传明文。
• ZCode 端 schema 严格（未知键会被丢弃），写入只输出其规范字段（type/command/args/cwd/env/url/headers/enabled/timeoutMs）。

修复：MCP 迁移同配置多 server 去重误跳过

• 同一配置文件内多个 server 迁移到同一目标时，旧去重键只含文件路径不含 server 名，第二个 server 会被误跳过；现按「server 名 + 源路径 + 目标」去重，整批迁移正确完成。

文档

• README 重构：叙事重心转为「四端技能 / MCP 管理中枢」，技能管理与 MCP 管理各成章节（含四端目录位置表与传输能力矩阵），API 切换弱化为独立简章节；开发文档与技能手动测试文档同步更新至四端。

测试

• 新增/更新 zcode 与 MCP 四端用例（切换双配置写入、协议自由、托管条目替换、技能存取、MCP 发现/迁移/传输矩阵/schema），后端测试套件 141 个全部通过。

校验

• 安装包：a4api-setup-0.2.2.exe
• SHA256：A3C6BD2F5D1F08D97840558D7D7CB2B96CF1A9E7BFA47F4DF4CA1C75907C24D5
• 建议下载后核对校验值，确保文件完整未被篡改。

a4api v0.2.1

a4api v0.2.1

更新内容

修复：dsh 目标切换后 .credentials.yaml 被写坏、dsh 无法启动

• 切换含 dsh 目标的配置时，DEEPSEEK_API_KEY 曾被写到凭证文档顶层，而 dsh 要求 version-1 布局（顶层仅允许 version / refs / records），导致 dsh 启动即报 unknown top-level key "DEEPSEEK_API_KEY" 拒绝引导。
• 现在固定输出 {"version": 1, "refs": {...}} 布局：DEEPSEEK_API_KEY 写入 refs 下；输入若为旧版扁平文档（凭证散在顶层）自动并入 refs 迁移；records 段（如 OAuth 记录）原样保留。

修复：切换后 dsh 请求被上游以 max_tokens 超限打回（400 [1210]）

• 未显式填写 max_tokens 时，文件里遗留的 dsh 适配器默认值 256000 曾被当作"手动设置"一路带到新上游；实测 Console Go 等上游仅接受 [1, 131072]，超限直接 400。
• 现在既有 maxTokens 恰为适配器默认 256000 时视为历史遗留，回落安全默认 131072；用户显式填写的值仍然最优先。

测试

• 新增/更新回归用例（凭证 version-1 布局与旧扁平迁移、records 保留、遗留 256000 重置），后端测试套件 117 个全部通过。

校验

• 安装包：a4api-setup-0.2.1.exe
• SHA256：69CC25AD3F8A143E35673867268A5960054CBF19D2C999F8FB518515C3BF5429
• 建议下载后核对校验值，确保文件完整未被篡改。