a4agent(0.4.0 起由 a4api 更名而来)是「九端 AI 编程工具管理台 + 本地大模型推理控制台」:为 Claude Code、Codex、dsh(DeepSeek Harness)、ZCode、pi、Qoder、OpenCode、WorkBuddy 与 TRAE 提供统一的技能管理与 MCP 管理,把七端(除 WorkBuddy 与 TRAE)的无头任务下发与手机 / 桌面通知提醒做进同一应用,0.7.0 起进一步内置 CrossDevice 设备互联(局域网设备一次确认配对、远程命令 / 截屏 / 文件传输),同时保留给 Claude Code 和 Codex 一键切换服务商、llama.cpp 本地大模型推理等能力。本文章为文档库入口,概述项目定位、功能全景、安装与快速开始,并给出全部功能文档的导航。

源码仓库

1. 项目简介

1.1 项目定位

维度 说明
项目名称 a4agent(0.4.0 起由 a4api 更名,数据与配置自动迁移)
产品形态 Windows 桌面应用(pywebview 窗口,本地渲染,可离线使用)
适用对象 Claude Code、Codex、dsh(DeepSeek Harness)、ZCode、pi、Qoder、OpenCode、WorkBuddy、TRAE
核心能力 九端技能 / MCP 管理(TRAE 的 MCP 为只读发现)、七端无头任务下发(支持循环计划与任务级技能)、手机推送与桌面横幅通知、跨设备互联(CrossDevice:发现 / 配对 / 远程命令 / 截屏 / 文件传输)、两端(Claude Code / Codex)服务商一键切换、协议翻译代理、本地大模型推理控制台(引擎按后端安装与切换)、配置安全写入、应用自更新
技术栈 Python FastAPI + SQLAlchemy/SQLite + LayUI 前端 + PyInstaller/Inno Setup 分发
运行环境 Windows 10 / 11,64 位;每用户安装,免管理员权限
开源协议 MIT
当前版本 0.7.2(详见版本更新说明)
源码地址 GitHub、Gitee、GitCode

1.2 功能全景

功能 一句话说明 详细文档
技能管理 九端 skill 发现、非破坏跨端迁移、自选项目文件夹、一键补齐、回收站 技能管理
MCP 管理 九端 MCP server 发现(TRAE 只读)、一键安装与批量导入、跨端迁移(传输矩阵校验)、快照回收站 MCP管理
任务下发 七端无头执行任务:下发即返回、三步预检、队列轮询、循环计划、任务级技能、产出留档、关窗不杀任务(0.5.0 起) 任务下发
通知提醒 手机推送(ntfy)与桌面横幅两条通道,手机上作答提问与审批权限(0.6.0 起) 通知提醒
设备互联 CrossDevice 局域网设备自动发现、一次确认配对、远程命令 / 截屏 / 文件传输(0.7.0 起) 设备互联
本地模型推理控制台 llama.cpp 引擎自动获取(按后端分目录安装、设置页可切换后端)、模型库、一键启动 OpenAI 兼容本地服务(0.3.0 起) 本地模型推理控制台
配置方案与一键切换 卡片化管理「服务商+Key+模型+目标」组合,点击即切换(目标仅 Claude Code 与 Codex) 配置方案与一键切换
服务商管理与预置模板 7 个预置模板开箱即用,支持自定义端点与搜索 服务商管理与预置模板
本地翻译代理 Anthropic / Responses 到 Chat Completions 的实时翻译与透传 本地翻译代理
Claude Code 目标 合并式写入 settings.json,支持进程探测与一键重启 ClaudeCode目标切换
Codex 目标 写 config.toml 与模型目录,原生直连或代理转发 Codex目标切换
dsh 目标(已移交) 0.1.4 至 0.5.0 曾代管,0.5.1 起移交给 dsh 自带配置界面 dsh目标切换
安全设计 DPAPI 加密、备份原子写、CORS 白名单、配对信任边界、日志隐私 安全设计
自动更新 签名清单验签、双镜像竞速下载、防降级的一键升级 自动更新
安装升级与卸载 每用户安装包、覆盖升级保留数据、a4api 无缝迁移 安装升级与卸载
数据目录与日志 数据库、备份、任务产出、通知配置与环境变量覆盖全清单 数据目录与日志说明
版本更新说明 0.1.0 至 0.7.2 流水线式演进记录 版本更新说明

安装与使用的图文教程可参考一键切换DeepSeek Harness等Agent模型服务API 教程,无头任务的整体机制可参考让Agent后台自主执行任务no-tty与headless模式教程,本文档库侧重功能机制与参考查询。

2. 安装

2.1 下载安装

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

2.2 使用前置条件

条件 说明
Windows 10 / 11 64 位 唯一支持的桌面平台
目标工具按需安装 要切 Claude Code 就装 Claude Code,Codex 同理;技能 / MCP / 任务 / 通知按实际接入的端按需安装,互不影响
各家 API Key 在对应服务商控制台申请;本地 LLM Studio 等本地推理不需要
通知提醒(可选) 手机装 ntfy App 并订阅话题;数据敏感时可改用自建 ntfy 服务

3. 快速开始

安装完成后不需要任何配置步骤——a4agent 会自动发现本机已装的 AI 编程工具并接管管理,第一个有价值的动作是「下发一个无头任务,让它带着你的技能在后台跑」。四步上手:

graph LR A[打开应用
九端工具自动发现] --> B[技能 / MCP 管理
查看迁移或一键补齐] B --> C[任务下发
选端选技能填任务] C --> D{勾选执行计划?} D -->|是| E[按间隔或时刻
循环执行] D -->|否| F[立即入队
后台执行] E --> G[桌面横幅 / 手机推送
收到结果] F --> G 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:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#fdebd0,stroke:#b7950b,stroke-width:2px
  1. 打开应用:双击安装包完成安装(见第 2 节),启动后进入主界面;「技能管理」与「MCP 管理」页签会自动列出已装各端(Claude Code、Codex、dsh、ZCode、pi、Qoder、OpenCode、WorkBuddy、TRAE)已有的全局与项目级条目,没装的端不显示、互不影响;
  2. 管一下技能:在「技能管理」页查看聚合卡片,把某端的 skill 跨端迁移(源端保留)或点「一键适配全部端」补齐到九端;MCP 管理同理,支持从零新建与 JSON 批量导入;
  3. 下发第一个任务:在「任务下发」页选目标端(七端无头:Claude Code、Codex、ZCode、Qoder、dsh、pi、OpenCode)、按需勾选技能(最多 20 个,运行前自动注入工作目录)与工作目录,输入任务描述后下发——下发即返回,任务在后台执行,关窗也不中断;
  4. 收结果:任务结束弹桌面横幅;手机装 ntfy App 并订阅话题后(见通知提醒),手机也会收到推送,还能直接在手机上作答提问与审批权限。

需要定时执行?任务下发页把「执行计划」切到「按计划循环」,按间隔 / 每天固定时刻 / 每周选定几天 / 仅一次创建循环任务。有两台电脑?「设备」页一次确认配对后,可远程下发命令、全屏截屏与传输文件(见设备互联)。至于给 Claude Code / Codex 一键切换服务商,属于进阶用法,见配置方案与一键切换。

4. 工作原理

4.1 架构分层

graph LR A[pywebview 桌面窗口] --> B[LayUI 前端
八页签] 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 运行时
本地大模型推理服务] C --> N[task_runner / loop_scheduler
无头任务与循环计划] C --> O[phone / hooks
通知与会话交互] C --> T[devices
CrossDevice 设备互联] E --> G[Claude settings.json] E --> H[Codex config.toml] F --> L[OpenAI 兼容上游] M --> P[OpenAI 兼容本地 API
llama-server] N --> Q[七端 CLI 无头进程] O --> R[ntfy 手机推送] O --> S[WinRT 桌面横幅] T --> U[CrossDevice node
被控端守护进程] U --> V[局域网设备
命令 / 截屏 / 文件] 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 N fill:#ffecd6,stroke:#e67e22,stroke-width:2px style O fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style T fill:#fadbd8,stroke:#c0392b,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style L fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style P fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style Q fill:#fdebd0,stroke:#b7950b,stroke-width:2px style R fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style S fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style U fill:#ffecd6,stroke:#e67e22,stroke-width:2px style V fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
  • 前端:LayUI 构建的本地页面,随包内置、离线可用,由后端统一托管;八个页签为配置方案、供应商管理、技能管理、MCP 管理、本地模型、任务下发、通知提醒、设备(0.7.0 起新增设备页,循环任务并入任务下发页、不再单设页签);顶栏提供「中 / EN」中英双语切换(默认跟随系统语言,0.6.4 起);页脚提供「问题反馈」(直达开发者邮箱,支持截图)与「版本与更新」弹窗;
  • 后端:FastAPI 提供 /api/v1 的 providers / configs / switch / skills / mcp / llama / tasks / loops / phone / desktop / devices / removal / feedback / fs / update 接口簇,Pydantic 强校验输入,CORS 仅放行本机;
  • 存储:单文件 SQLite,密钥经 DPAPI 加密入库,外键约束防孤儿数据;
  • 代理:需要协议翻译时拉起独立进程,仅监听 127.0.0.1 并以随机 token 鉴权;
  • 本地模型:llama.cpp llama-server 进程由推理控制台托管,产出 OpenAI 兼容接口供配置方案接入;
  • 任务与通知:任务下发走后台线程池与子进程,关窗后仍常驻;循环计划由常驻调度器按 once / interval / daily / weekly 四种类型触发;通知走 ntfy 与 WinRT 原生横幅两条独立通道;
  • 设备互联:应用首启自动拉起本机被控端 node 守护进程(安装包内嵌 CrossDevice 运行时),局域网设备经 UDP 广播自动发现、一次确认配对后可远程执行命令、截屏与文件传输。

5. 源码结构

路径 内容
backend/app/main.py FastAPI 入口:CORS、路由注册、静态资源托管
backend/app/models.py / crud.py / schemas.py ORM 模型、数据库操作、请求响应校验
backend/app/skill_manager.py 九端 skill 发现、聚合、迁移、回收站、一键补齐(TRAE 内置技能目录不写入不托管)
backend/app/mcp_manager.py 九端 MCP server 发现、安装与批量导入、跨端迁移、快照回收站(TRAE 只读发现)
backend/app/config_manager.py 配置方案与两端(Claude Code / Codex)配置文件的读取、合并式生成、备份与原子写
backend/app/config_io.py 公共配置 IO 层(逐端备份、原子写入,0.5.1 收敛)
backend/app/removal.py / removal_backup.py 0.5.1 移交三端的托管配置清理与清理前永久快照
backend/app/task_engines.py / task_precheck.py / task_runner.py / task_notify.py 无头任务:引擎矩阵、下发前预检、执行器、终态广播(0.5.0 起)
backend/app/loop_schedule.py / loop_scheduler.py 循环任务:四种计划类型校验与常驻调度(once / interval / daily / weekly,0.6.6 起)
backend/app/task_skills.py 任务级技能注入与回收:Windows 目录联接优先、引用计数、结束只删自建目录(0.6.6 起)
backend/app/devices/ CrossDevice 设备互联:node_proc(被控端守护与多实例)、pool(发现池)、node_client(远程命令 / 截屏 / 文件传输)、pair_watcher(配对系统 toast)、store(DPAPI 加密凭据)(0.7.0 起)
backend/app/phone/ 通知提醒:config(话题 / 令牌 / 事件开关)、ntfy(推送客户端)、notifier(统一样式拼装)
backend/app/hooks/ 会话 hook:dispatch(事件路由)、handlers(提问 / 审批 / 完成)、register(挂载到各工具)、deskqueue(桌面弹窗代发)、transcript(最后输出抽取)、dsh 相关(0.6.0 起)
backend/app/win_toast.py / win_toast_native.py 桌面横幅门面与 WinRT 原生 toast(ctypes 直调 COM,零第三方依赖)
backend/app/opencode_client.py / opencode_listen.py OpenCode 服务对接与 SSE 事件监听(0.6.1 起;0.6.6 起服务地址从 service.json 自动发现)
backend/app/workbuddy_listen.py WorkBuddy 会话雷达:读会话记录在提问面板出现时即弹桌面横幅(0.6.4 起)
backend/app/desktop_recovery.py 启动自恢复:实例记录(端口 / PID)、唤回隐藏窗口与清障重启兜底(0.6.4 起)
backend/app/llama/ 本地模型推理控制台:引擎目录(按后端分目录)、GGUF 解析、硬件检测、预设推荐、进程管理(0.3.0 起)
backend/app/disk_roots.py / project_hints.py 项目来源:盘符探测与默认扫描范围、从各工具历史自动发现项目线索(0.6.4 起)
backend/app/crypto.py Windows DPAPI 加解密
backend/app/openai_proxy.py / responses_translator.py / 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 / tasks / loops / phone / desktop / devices / removal / feedback / fs / update
backend/app/tests/ 加解密、配置生成、协议翻译、技能 / MCP、任务与循环、设备互联、通知、更新器等回归测试(44 个模块)
frontend/ LayUI 前端页面与样式(js/tasks.js 任务下发页、js/devices.js 设备页、js/phone.js 通知提醒页、js/llama.js 本地模型页、js/i18n.js 中英双语字典与应用器)
desktop.py / dev_server.py pywebview 桌面入口(单实例互斥、关窗转托盘常驻、二次启动唤回、唤回失败自动清障重启)与浏览器调试入口
build.py / installer.iss PyInstaller 打包与 Inno Setup 安装包脚本(0.7.0 起内嵌 CrossDevice node 运行时,0.7.1 起内嵌 python-embed 解释器)

6. 文档导航

文档 说明
项目总览与快速开始 本文档,项目简介与快速上手
配置方案与一键切换 配置方案字段、目标组合与切换全流程
服务商管理与预置模板 预置模板清单、自定义服务商与搭配规则
本地翻译代理 协议链路、鉴权与进程生命周期
ClaudeCode目标切换 settings.json 托管字段与一键重启
Codex目标切换 config.toml、models.json 与直连策略
dsh目标切换 0.5.1 起已移交 dsh 自带界面,含迁移与历史说明
技能管理 九端 skill 发现、迁移、回收站
MCP管理 九端 MCP server 发现、安装、迁移、回收站(TRAE 只读)
本地模型推理控制台 llama.cpp 引擎、模型库、本地服务与接入配置方案(0.3.0 起)
任务下发 七端无头任务:预检、队列、循环计划、任务级技能、产出与关窗常驻
通知提醒 手机推送与桌面横幅、手机作答与权限审批
设备互联 CrossDevice 设备发现、一次确认配对、远程命令 / 截屏 / 文件传输(0.7.0 起)
安全设计 全部安全机制的索引与设计意图
自动更新 签名、双镜像竞速、校验与防降级
安装升级与卸载 下载安装、覆盖升级、源码运行与打包
数据目录与日志说明 数据落盘位置与路径覆盖环境变量
版本更新说明 0.1.0 至 0.7.2 流水线式演进