a4agent（0.4.0 起由 a4api 更名而来）是「四端 AI 编程工具管理台 + 本地大模型推理控制台」：为 Claude Code、Codex、dsh（DeepSeek Harness）与 ZCode 提供统一的技能管理、MCP 管理与服务商一键切换，并把 llama.cpp 封装为一键启动的本地大模型推理服务。本文章为文档库入口，概述项目定位、功能全景、安装与快速开始，并给出全部功能文档的导航。

切换能力上，a4agent 通过可视化界面管理「服务商 + API Key + 模型 + 应用目标」组合，一键写入 ~/.claude/settings.json、~/.codex/config.toml、~/.dsh/settings.yaml 与 ~/.zcode/cli/config.json；内置的本地翻译代理把 Anthropic 与 OpenAI Responses 协议实时翻译为 Chat Completions，让各端都能使用任意 OpenAI 兼容上游（ZCode 原生支持双协议、直连上游）；本地模型与切换能力组合，即得 Claude Code 完全离线方案。

源码仓库

1. 项目简介

1.1 项目定位

维度 说明
项目名称 a4agent（0.4.0 起由 a4api 更名，数据与配置自动迁移）
产品形态 Windows 桌面应用（pywebview 窗口，本地渲染，可离线使用）
适用对象 Claude Code、Codex、dsh（DeepSeek Harness）、ZCode，可任意组合多目标
核心能力 四端技能/MCP 管理、服务商一键切换、协议翻译代理、本地大模型推理控制台、配置安全写入、应用自更新
技术栈 Python FastAPI + SQLAlchemy/SQLite + LayUI 前端 + PyInstaller/Inno Setup 分发
运行环境 Windows 10 / 11，64 位；每用户安装，免管理员权限
开源协议 MIT
当前版本 0.4.0（详见版本更新说明）
源码地址 GitHub、Gitee、GitCode

1.2 功能全景

功能 一句话说明 详细文档
技能管理 四端 skill 发现、非破坏迁移、自选项目文件夹、一键适配、回收站 技能管理
MCP 管理 四端 MCP server 发现、一键安装与批量导入、跨端迁移（传输矩阵校验）、回收站 MCP管理
配置方案与一键切换 卡片化管理「服务商+Key+模型+目标」组合，点击即切换 配置方案与一键切换
服务商管理与预置模板 7 个预置模板开箱即用，支持自定义端点与搜索 服务商管理与预置模板
本地模型推理控制台 llama.cpp 引擎自动获取、模型库、一键启动 OpenAI 兼容本地服务（0.3.0 起） 本地模型推理控制台
本地翻译代理 Anthropic / Responses 到 Chat Completions 的实时翻译与透传 本地翻译代理
Claude Code 目标 合并式写入 settings.json，支持进程探测与一键重启 ClaudeCode目标切换
Codex 目标 写 config.toml 与模型目录，原生直连或代理转发 Codex目标切换
dsh 目标 写 settings.yaml 与凭证文件，热加载新会话生效 dsh目标切换
ZCode 目标 写 cli/v2 两份配置，原生双协议直连上游（0.2.2 起） 配置方案与一键切换
安全设计 DPAPI 加密、备份原子写、CORS 白名单、日志隐私 安全设计
自动更新 签名清单验签、双源下载、防降级的一键升级 自动更新
安装升级与卸载 每用户安装包、覆盖升级保留数据、a4api 无缝迁移 安装升级与卸载
数据目录与日志 数据库、备份、状态文件与环境变量覆盖全清单 数据目录与日志说明
版本更新说明 0.1.0 至 0.4.0 流水线式演进记录 版本更新说明

安装与使用的图文教程可参考一键切换DeepSeek Harness等Agent模型服务API 教程，本文档库侧重功能机制与参考查询。

2. 安装

2.1 下载安装

从 Release 页面下载最新 a4agent-setup-<版本>.exe，双击按向导完成：每用户安装、全程无需管理员权限，自动创建开始菜单与桌面快捷方式。首次运行如遇 SmartScreen 提示，点「更多信息 → 仍要运行」即可（未做商业代码签名属正常现象）。细节与常见拦路虎见安装升级与卸载。

2.2 使用前置条件

条件 说明
Windows 10 / 11 64 位 唯一支持的桌面平台
目标工具按需安装 要切 Claude Code 就装 Claude Code，Codex、dsh、ZCode 同理；四者互不影响
各家 API Key 在对应服务商控制台申请；本地 LLM Studio 等本地推理不需要

3. 快速开始

以「给 Claude Code 换上 DeepSeek 官方接口」为例，三步完成：

graph LR A[供应商管理页
确认预置模板] --> B[新增配置方案
选服务商填 Key 定模型] B --> C[卡片上点切换
勾选目标 claude] C --> D{需要立即生效?} D -->|是| E[一键重启
Claude Code] D -->|否| F[下次启动自然生效] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px
  1. 选模板建方案：「供应商管理」页签里预置了 DeepSeek、智谱、OpenRouter、OpenCodeGo、本地 LLM Studio 七个模板；回到「配置方案」页新增一个方案，选服务商、粘贴 API Key、填写模型名（如 deepseek-chat）、勾选应用目标；
  2. 一键切换：在卡片上点「切换」，工具自动备份原配置并把新组合写入目标文件；当前生效的卡片会高亮标识；
  3. 重启目标工具：Claude Code 可勾选一键重启，Codex 手动重开，dsh 无需任何操作（热加载），ZCode 重启或新建会话后生效。

想同时管 Codex 和 dsh？同一个方案里把目标一起勾上即可——记得这两端要选 OpenAI 兼容类型的服务商；ZCode 则没有协议限制，Anthropic 类型也能直连。

4. 工作原理

4.1 架构分层

graph LR A[pywebview 桌面窗口] --> B[LayUI 前端
配置卡片/供应商管理/技能/MCP/本地模型] B --> C[FastAPI 后端
REST /api/v1] C --> D[(SQLite
a4agent.db)] C --> E[config_manager
合并式读写四端配置] C --> F[proxy_standalone
独立翻译代理进程] C --> K[skill_manager / mcp_manager
四端技能与 MCP 管理] C --> M[llama 运行时
本地大模型推理服务] E --> G[Claude settings.json] E --> H[Codex config.toml] E --> I[dsh settings.yaml] E --> J[ZCode cli/v2 config.json] F --> L[OpenAI 兼容上游] M --> N[OpenAI 兼容本地 API
llama-server] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#fdebd0,stroke:#b7950b,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#fadbd8,stroke:#c0392b,stroke-width:2px style K fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style M fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style I fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style J fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style L fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style N fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px
  • 前端：LayUI 构建的本地页面，随包内置、离线可用，由后端统一托管；页脚提供「问题反馈」（直达开发者邮箱，支持截图）与「版本与更新」弹窗；
  • 后端：FastAPI 提供 /api/v1 的 providers / configs / switch / skills / mcp / llama / feedback / update 接口簇，Pydantic 强校验输入，CORS 仅放行本机；
  • 存储：单文件 SQLite，密钥经 DPAPI 加密入库，外键约束防孤儿数据；
  • 代理：需要协议翻译时拉起独立进程，仅监听 127.0.0.1 并以随机 token 鉴权；
  • 本地模型：llama.cpp llama-server 进程由推理控制台托管，产出 OpenAI 兼容接口供四端接入。

4.2 一次切换发生了什么

点击切换后，后端解密 Key、校验目标与服务商协议匹配、先把方案标记为生效（独立代理据此获知最新上游），随后逐端执行「备份原文件、基于现有内容合并生成、原子写覆盖」，最后记录切换日志并提示各端的生效方式。全流程分步拆解见配置方案与一键切换第 4 节。

5. 源码结构

路径 内容
backend/app/main.py FastAPI 入口：CORS、路由注册、静态资源托管
backend/app/models.py / crud.py / schemas.py ORM 模型、数据库操作、请求响应校验
backend/app/skill_manager.py 四端 skill 发现、迁移、回收站、一键适配
backend/app/mcp_manager.py 四端 MCP server 发现、安装与批量导入、跨端迁移、回收站
backend/app/config_manager.py 四端配置文件的读取、合并式生成、备份与原子写、托管前缀迁移
backend/app/llama/ 本地模型推理控制台：引擎目录、GGUF 解析、硬件检测、预设推荐、进程管理（0.3.0 起）
backend/app/crypto.py Windows DPAPI 加解密
backend/app/openai_proxy.py 协议翻译核心（messages / responses / 透传三类端点）
backend/app/proxy_standalone.py 独立代理进程的生命周期管理
backend/app/updater.py 自更新：签名验签、双源下载、校验与应用
backend/app/mail.py 应用内反馈直邮（SMTP 凭据本地私有文件，0.3.2 起）
backend/app/api/v1/ providers / configs / switch / skills / mcp / llama / feedback / update 接口簇
backend/app/tests/ 加解密、配置生成、协议翻译、技能/MCP 管理、数据迁移、更新器等回归测试
frontend/ LayUI 前端页面与样式（js/llama.js 为本地模型页）
desktop.py / dev_server.py pywebview 桌面入口（含单实例互斥）与浏览器调试入口
build.py / installer.iss PyInstaller 打包与 Inno Setup 安装包脚本

6. 文档导航

文档 说明
项目总览与快速开始 本文档，项目简介与快速上手
配置方案与一键切换 配置方案字段、目标多选与切换全流程
服务商管理与预置模板 预置模板清单、自定义服务商与搭配规则
本地翻译代理 三条协议链路、鉴权与进程生命周期
ClaudeCode目标切换 settings.json 托管字段与一键重启
Codex目标切换 config.toml、models.json 与直连策略
dsh目标切换 settings.yaml、max_tokens 与热加载
技能管理 四端 skill 发现、迁移、回收站
MCP管理 四端 MCP server 发现、安装、迁移、回收站
本地模型推理控制台 llama.cpp 引擎、模型库、本地服务与接入配置方案（0.3.0 起）
安全设计 全部安全机制的索引与设计意图
自动更新 签名、双源、校验与防降级
安装升级与卸载 下载安装、覆盖升级、源码运行与打包
数据目录与日志说明 数据落盘位置与路径覆盖环境变量
版本更新说明 0.1.0 至 0.4.0 流水线式演进