a4api版本更新说明

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

1. 版本演进总览

2. 版本明细

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> 命名托管、保留用户手工条目与 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 首个发行版，能力全集：

• 新增：配置方案卡片化管理（新增、编辑、删除、一键切换、当前生效高亮），服务商管理与预置模板自动播种
• 新增：Claude Code 与 Codex 双应用目标——写 ~/.claude/settings.json（合并式更新、原子写入、自动备份滚动保留）与 ~/.codex/config.toml（托管 a4api_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）页面下载新版 a4api-setup-*.exe 覆盖安装即可，建议核对发布页提供的 SHA256 校验值；
• 升级前应用会自动停止后台翻译代理并清理旧文件，避免文件占用导致覆盖失败；
• 运行数据（数据库、配置备份）保留在 %APPDATA%\a4api\，覆盖升级后配置方案与加密密钥完整可用，无需重新配置；
• 0.2.2 起新增 ZCode 目标与 MCP 管理：目标工具需已安装 ZCode 桌面端与相应 MCP 配置才会出现在发现结果中；新增的 mcp_migrations / mcp_trash 表由数据库启动自动建表，无需手工处理；
• 旧版 api-switch 的数据目录会在新版首次启动时一次性自动迁移；
• 预发布版本仅当当前运行版本也是预发布时才会提示，正式版用户不会收到试验性推送。

4. 版本检查与更新方式

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