a4api

四端 AI 编程工具管理台：为 Claude Code、Codex、dsh（DeepSeek Harness）与 ZCode（智谱 Agentic 开发环境） 提供统一的技能管理（Skill）、MCP 管理与 API 服务商切换。所有操作通过可视化界面完成，无需手动编辑配置文件。

技能管理

四个工具均使用同一套技能格式（<skill-name>/SKILL.md 目录 + frontmatter name/description），因此 a4api 可以把它们当作一种资源统一管理。

发现与聚合

• 自动扫描四端全局与项目级技能目录，以 frontmatter name 为唯一标识做聚合标注：同名技能跨端存在时自动标记「已在 N 端存在」。
• 项目根目录列表可配置（默认扫描 C:\ProgramMine），只收录含至少一个 skill 的项目。
• Codex 全局的保留目录（.system/ 等点开头目录）自动跳过，不视为用户技能。

跨端迁移与「一键适配四端」

• 任意一端的 skill 可迁移到任意目标端（全局或任意项目），迁移为非破坏复制：源端永久保留。
• 目标端已存在同名技能（frontmatter name 或目录名任一命中）时，旧版自动移入回收站而非静默覆盖。
• 「一键适配四端」：一键把项目内全部 skill 按其缺失的端一次补齐，先弹计划清单再执行，带进度条并临时锁定页面，防止中途误操作。
• 每次迁移写入迁移日志（时间、Skill、源、目标、结果），全程可追溯。

回收站

• 删除的 skill 移入回收站，30 天内可恢复原位或彻底删除；恢复时原位置被占用会明确报错，绝不覆盖。
• 过期条目在下次访问回收站时惰性清理，并在返回结果中提示本次清理数量。

四端技能目录

ZCode 官方还识别跨工具兼容目录 ~/.agents/skills 与 <项目>/.agents/skills；a4api 统一托管到 .zcode 前缀，与其它端保持一致。迁移到 ZCode 的 skill 会被 ZCode 客户端真实读取。

MCP 管理

四端的 MCP server 都写在各自的配置文件里，a4api 把它们归一为统一视图（name / transport / command / args / env / url / headers）管理。

发现与聚合

• 自动发现四端全局与项目级 MCP server，同名 server 跨端聚合标注（「已在 N 端存在」）。
• 详情中 env / headers 一律脱敏（只回显键名），API 永不回传明文密钥。
• 项目级自动识别：Claude Code .mcp.json、Codex .codex/config.toml、ZCode .zcode/config.json。

跨端迁移与传输能力矩阵

• 任意端的 server 可迁移到任意目标端；目标端已有同名 server 时先快照进回收站再写入，写入前自动备份目标配置文件。
• 迁移按传输能力矩阵严格校验，不兼容的组合整对失败并留日志，不静默降级：

dsh 与 ZCode 的细节：dsh 的 MCP server 挂在 @deepseek-ai/dsh-mcp-client 插件条目下，重写时保留其它非管理条目；dsh 无项目级 MCP。ZCode 配置 schema 严格（未知键会被丢弃），a4api 只写其规范字段（type/command/args/cwd/env/url/headers/enabled/timeoutMs），迁移到 ZCode 的 server 会被客户端自动连接。

回收站与安全

• 被替换/删除的 server 配置片段快照进回收站（30 天内可恢复）；快照中的 env / headers 用 DPAPI 加密落盘，恢复时解密写回。
• 每次迁移写入日志；发现、预览、回收站接口对敏感字段全程脱敏。

API 服务商切换

在以上管理能力之外，a4api 也可为四端一键切换服务商、模型与 API Key：

• Claude Code：Anthropic 协议直连，或经内置本地翻译代理把请求实时翻译为 OpenAI Chat Completions 转发给 OpenAI 兼容服务商（代理仅监听 127.0.0.1、随机 token 鉴权，工具退出后仍存活）。
• Codex：OpenAI Responses 协议写入 ~/.codex/config.toml；上游原生支持 Responses（如 DeepSeek）时直连，否则经本地代理翻译转发。
• dsh：经本地代理 /chat/completions 透传连接上游（顺带归一上游流式分片中的 null 字段，规避 dsh 适配器把工具名覆盖为空的问题），配置热加载、新会话即生效。
• ZCode：原生支持 Anthropic / OpenAI 两种协议，直连写入 CLI 与桌面端两份配置（provider 条目以 a4api_p<id> 托管、保留手工条目），无需本地代理。

切换前自动备份目标配置文件（滚动保留最近 5 份）并原子写入；API Key 使用 Windows DPAPI 加密存储，接口永不回显明文。

预置服务商模板

启动时自动写入并按模板定义同步，可增删改：

模板命名遵循「服务商-协议」约定：同一服务商可能同时提供 Anthropic 与 OpenAI 兼容两套接口，因此预置两条记录（如 DeepSeek-anthropic / DeepSeek-openai）。原生 Responses：勾选后 Codex 直接连接上游 /responses 接口，无需本地翻译代理；DeepSeek 官方原生支持 OpenAI Responses（仅 deepseek-v4-flash 模型）。内置模板在升级时会按模板定义自动同步，自定义服务商不受影响。

下载、安装与使用

下载安装

从 发行版（Release） 页面下载安装包 a4api-setup-*.exe：

• 下载地址：https://github.com/eogee/a4api/releases （选择最新版本）
• 系统要求：Windows 10/11 64 位
• 建议核对下载页提供的 SHA256 校验值，确保文件完整未被篡改

安装包采用每用户安装（免 UAC）：双击运行后按向导安装到当前用户目录，全程无需管理员权限。安装完成后自动创建开始菜单与桌面快捷方式，并可在「设置 → 应用」中卸载。

运行

1. 安装完成后，从开始菜单或桌面快捷方式启动 a4api
2. 首次安装/运行时若出现 Windows SmartScreen 提示，点击「更多信息 → 仍要运行」即可（应用未做商业代码签名，属正常现象，不影响功能）
3. 界面四个页签：配置方案（API 切换）、供应商管理、技能管理、MCP 管理

数据与隐私

• 运行时数据（数据库、配置备份）写入 %APPDATA%\a4api\，日志写入 ~/.a4api/logs/
• API Key 使用 Windows DPAPI 加密存储，与当前 Windows 用户绑定
• 修改前自动备份原配置文件（~/.claude/settings.json / ~/.codex/config.toml / ~/.dsh/settings.yaml / ~/.dsh/.credentials.yaml / ~/.zcode/cli/config.json / ~/.zcode/v2/config.json 等，滚动保留最近 5 份）

常见问题

• 杀毒软件报毒：PyInstaller 打包的程序偶被安全软件误报，请添加信任或排除；可将样本提交给对应厂商申诉误报
• 升级：直接运行新版 a4api-setup-*.exe 覆盖安装即可，数据与配置（%APPDATA%\a4api\）会保留；升级前会自动停止后台翻译代理并清理旧文件
• 卸载：在「设置 → 应用」中卸载；程序文件会移除，运行数据（数据库、配置备份）保留在 %APPDATA%\a4api\，如需彻底清除请手动删除该目录
• 反馈问题：请附上 ~/.a4api/logs/a4api.log 日志，便于定位

提交 Issue 要求

提交 Issue 前请确认以下信息，缺失可能导致问题无法定位：

1. 明确类型：Bug 报告 / 功能建议 / 使用疑问，选择对应标签，便于分流处理
2. 环境信息（必填）：
   • a4api 版本号（发行版页面标注的版本）
   • 目标应用：Claude Code / Codex / dsh / ZCode / 其他
   • 服务商与模型：如 DeepSeek、智谱 GLM 等
3. 复现步骤：从打开应用到出现问题的完整操作路径，越具体越好；尽量写明「做了什么 → 实际结果 → 预期结果」
4. 日志：附上 ~/.a4api/logs/a4api.log 的相关片段（不要整份粘贴，可截取报错前后内容）
5. 报错信息与截图：界面报错文案、终端输出、异常截图一并附上
6. 隐私红线：切勿在 Issue 中粘贴 API Key、模型密钥等敏感信息；如日志可能含敏感内容，请先脱敏
7. 排查先行：提交前先自查——重启应用、确认 API Key 有效、确认本机能访问上游服务、确认无代理/杀软干扰

提交前请先搜索是否已有相同 Issue，避免重复提交。

自动更新与安全

发布新版本到 GitHub/Gitee 后，应用会在启动时静默检查或点顶部「检查更新」时发现更新，经你确认后下载安装包并显示进度，下载校验通过后再次确认即可运行安装器完成升级；也可选择「忽略此版本」。

更新源与校验（防 MITM / 防伪造）

• 双源下载：安装包优先从 GitHub、不可达时回退 Gitee（同一 SHA256 验证两个镜像地址）。
• 更新清单签名：发布侧用 Ed25519 私钥签名 latest.json（版本、更新说明、安装包 SHA256 等字段），应用内置对应公钥验签；任何字段异常或签名不符，清单直接作废、不弹更新提示。URL 不入签名，因此 GitHub/Gitee 两份清单字节一致、共用同一签名，URL 指向的内容由被签名的 SHA256 绑死。
• 完整性校验：安装包边下边算 SHA256，与签名过的清单比对通过才落盘（存于 %APPDATA%\a4api\updates\<版本>\）；点击「立即更新」时会对磁盘文件再次校验才启动安装器。
• 传输白名单：仅 HTTPS，且每次重定向逐跳校验主机白名单（github.com / gitee.com / 两个 *.githubusercontent.com 对象存储域 / *.gitee.com），拦截跳转到任意域名。
• 防降级：候选版本需严格高于当前版本；低于清单 min_version（过旧需完整安装包）时拒绝；预发布版本仅当当前运行版本也是预发布时才提示。
• 尺寸上限：清单 512KB、安装包 300MB，超限拒绝；下载只写入用户数据目录，不信任系统临时目录。

更新流程（一次点击走完）

1. 检测到新版本 → 弹窗展示版本号与更新说明（说明内容由签名清单携带，篡改即拒收）。
2. 确认 → 后台下载，前端实时进度；下载中可取消。
3. 校验通过 → 提示「立即更新 / 稍后」。点击立即更新：应用先停掉本地翻译代理、自动退出并释放单实例锁，随后拉起 Inno Setup 安装向导；安装完成后启动的是新版本，配置、数据库与密钥完整保留。

安全设计

• 密钥加密存储：所有 API Key 入库前经 Windows DPAPI（直接调用 crypt32.dll，无第三方依赖）加密，密文 base64 存入 SQLite，与当前 Windows 用户绑定；API 响应永不回显明文。
• 本地翻译代理鉴权：仅绑定 127.0.0.1、端口限定 17890–17899；每次启动生成随机鉴权 token，请求必须匹配否则 401；只在「OpenAI 兼容 + 目标含 Claude/Codex/dsh」时运行，密钥从数据库按当前生效配置解密，不硬编码。
• 配置写入与备份：修改任何目标配置文件前自动备份（滚动保留最近 5 份）；全部采用原子写（临时文件 + fsync + os.replace），崩溃不损坏配置；写入为合并式，用户已有的 hooks / permissions / 其它 env / provider 原样保留。
• 后端 API 防护：CORS 白名单仅放行 localhost / 127.0.0.1 / [::1]；请求体经 Pydantic 严格校验；桌面形态下服务仅暴露本机。
• 数据与文件权限：打包后数据写入 %APPDATA%\a4api\；非 Windows 环境收紧 700/600 权限；.gitignore 排除数据库与运行时数据。
• 并发与一致性：配置激活用进程内互斥锁串行化，异常事务回滚；SQLite 开启外键约束，删除服务商前校验其下配置方案。
• 进程与单实例：Windows 命名互斥体保证单实例运行；重启 Claude Code 前用 CIM 精确匹配进程，避免误杀。
• 日志与隐私：默认不记录任何请求/响应内容；代理调试日志仅当显式设置 A4API_PROXY_DEBUG 时开启。

自动化测试

• test_skill_manager.py：四端 skill 发现聚合、跨端迁移、同名冲突回收、删除→恢复往返、30 天过期清理。
• test_mcp_manager.py：四端 MCP 发现聚合、跨端迁移（含传输能力矩阵约束）、快照回收、env/headers 脱敏与 DPAPI 加密。
• test_switch.py / test_config_manager.py：四端切换写入、协议约束、原子写入不留临时文件。
• test_crypto.py：DPAPI 加解密往返、非法密文返回空。
• test_openai_proxy.py：Anthropic ⇄ OpenAI 协议翻译正确性，含工具 schema 处理回归用例。
• test_updater.py：签名载荷 golden 基准、验签/篡改拒绝、版本比较与防降级、SHA256/尺寸校验、URL 白名单、GitHub→Gitee 回退与 TTL 缓存、本地下载/取消/镜像回退、状态原子读写。

开发

环境要求：Windows 10+，Python 3.10，uv

uv sync                     # 安装依赖
uv run python desktop.py    # 启动桌面应用
# 或后端单独调试
uv run uvicorn backend.app.main:app --port 8000

打包

前置：编译安装包需要 Inno Setup 6（winget install --id JRSoftware.InnoSetup -e --accept-source-agreements）。

uv run python build.py                 # 生成 dist/a4api/（文件夹版 onedir）
uv run python build.py --installer     # 文件夹版 + 编译安装包 dist/a4api-setup-<版本>.exe
uv run python build.py --onefile       # 可选：生成单 exe（临时分发用）

版本号自动取自 pyproject.toml（[project].version），也可用 --version 覆盖；ISCC.exe 自动探测（--iscc 指定路径）。

项目结构

backend/app/       FastAPI 后端（模型、CRUD、配置读写、加密、进程管理）
frontend/          LayUI 前端
desktop.py         pywebview 桌面入口
build.py           打包脚本

运行时数据（数据库、配置备份）写入 backend/database/（开发）或 %APPDATA%\a4api\（打包后）。