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 本地大模型推理等能力。本文章为文档库入口,概述项目定位、功能全景、安装与快速开始,并给出全部功能文档的导航。
源码仓库
- a4agent 源码(GitHub),本项目主仓库,可查看源码、提交 Issue 或参与贡献。
- a4agent 镜像(Gitee)与镜像(GitCode),国内访问镜像。
- a4agent 发行版(Release)下载地址页面提供安装包下载与各版本 SHA256 校验值。
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 编程工具并接管管理,第一个有价值的动作是「下发一个无头任务,让它带着你的技能在后台跑」。四步上手:
九端工具自动发现] --> 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
- 打开应用:双击安装包完成安装(见第 2 节),启动后进入主界面;「技能管理」与「MCP 管理」页签会自动列出已装各端(Claude Code、Codex、dsh、ZCode、pi、Qoder、OpenCode、WorkBuddy、TRAE)已有的全局与项目级条目,没装的端不显示、互不影响;
- 管一下技能:在「技能管理」页查看聚合卡片,把某端的 skill 跨端迁移(源端保留)或点「一键适配全部端」补齐到九端;MCP 管理同理,支持从零新建与 JSON 批量导入;
- 下发第一个任务:在「任务下发」页选目标端(七端无头:Claude Code、Codex、ZCode、Qoder、dsh、pi、OpenCode)、按需勾选技能(最多 20 个,运行前自动注入工作目录)与工作目录,输入任务描述后下发——下发即返回,任务在后台执行,关窗也不中断;
- 收结果:任务结束弹桌面横幅;手机装 ntfy App 并订阅话题后(见通知提醒),手机也会收到推送,还能直接在手机上作答提问与审批权限。
需要定时执行?任务下发页把「执行计划」切到「按计划循环」,按间隔 / 每天固定时刻 / 每周选定几天 / 仅一次创建循环任务。有两台电脑?「设备」页一次确认配对后,可远程下发命令、全屏截屏与传输文件(见设备互联)。至于给 Claude Code / Codex 一键切换服务商,属于进阶用法,见配置方案与一键切换。
4. 工作原理
4.1 架构分层
八页签] 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 流水线式演进 |
评论