a4agent 是纯本地工具，所有运行时数据都落在你自己的磁盘上：SQLite 数据库、配置备份、本地模型推理配置与引擎、代理状态、更新缓存与日志。清楚每个文件的位置与角色，排查问题、迁移机器或彻底清理时才有的放矢。本文章给出安装版与开发模式两套目录的完整清单、数据库表结构、各类状态文件说明，以及可用于测试的路径覆盖环境变量。

1. 目录总览

1.1 安装版（打包运行）

路径 内容
%APPDATA%\a4agent\a4agent.db SQLite 主数据库：服务商、配置方案、切换日志、备份记录、技能与 MCP 回收站、应用内反馈留档
%APPDATA%\a4agent\backups\ 各端配置文件的切换前自动备份，滚动保留最近 5 份
%APPDATA%\a4agent\proxy.json 本地翻译代理状态文件（端口、PID、token）
%APPDATA%\a4agent\update_state.json 更新状态：忽略的版本、已下载待安装标记
%APPDATA%\a4agent\updates\<版本>\ 已下载并通过校验的更新安装包
%APPDATA%\a4agent\skills_recycle\<name>.<时间戳>\ 技能回收站：被删除 skill 的副本，30 天内可恢复
%APPDATA%\a4agent\mcp_recycle\<name>.<时间戳>\ MCP 回收站：被替换/删除 server 的配置片段快照（env/headers 经 DPAPI 加密），30 天内可恢复
%APPDATA%\a4agent\projects.json 技能管理：项目根目录列表
%APPDATA%\a4agent\llama_config.json 本地模型：推理配置（引擎包、模型目录、推理参数、服务端口等，自 0.3.0 起）
%APPDATA%\a4agent\engine\ 本地模型：llama.cpp 引擎文件（llama-server.exe 等，体积数百 MB 级，自 0.3.0 起）
~\.a4agent\logs\a4agent.log 运行日志（0.4.0 起路径；旧版 ~\.a4api\logs\ 目录保留不删）

1.2 开发模式（源码运行）

开发模式下数据根切换为项目内 backend/database/，子结构相同（a4agent.db、backups/、proxy.json），日志位置不变；两套环境互不干扰。

graph LR A[a4agent 运行模式] --> B{是否打包运行?} B -->|是
安装版| C[%APPDATA%\a4agent] B -->|否
源码调试| D[backend/database] C --> E[(a4agent.db)] C --> F[backups 备份] C --> G[proxy.json 代理状态] C --> H[update_state.json 更新状态] C --> L[llama_config.json + engine
本地模型配置与引擎] D --> E2[(a4agent.db)] D --> F2[backups 备份] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#fdebd0,stroke:#b7950b,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#fdebd0,stroke:#b7950b,stroke-width:2px style H fill:#fdebd0,stroke:#b7950b,stroke-width:2px style L fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E2 fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F2 fill:#fadbd8,stroke:#c0392b,stroke-width:2px

2. 数据库表结构

a4agent.db 共十张表（随技能管理、MCP 管理与应用内反馈逐步增加）：

表 字段 说明
providers id, name(唯一), api_base, api_type, native_responses, is_custom, created_at 服务商；预置模板 is_custom 为假且随版本同步
configurations id, name, provider_id(外键), api_key_encrypted, model, targets, max_tokens, is_active, created_at 配置方案；密钥为 DPAPI 加密后的 base64
switch_logs id, config_id, switch_time, status(success/failed), detail 每次切换一条记录
backups id, config_id, backup_time, file_path 备份动作记录
skill_migrations id, skill_name, source_tool, source_scope, source_project, source_path, target_tool, target_scope, target_project, status, detail, migrate_time 技能迁移日志（source×target 一对一条）
skill_trash id, skill_name, dir_name, tool, scope, project, original_path, trash_path, trash_time 技能回收站：记录被删除 skill 的原位与回收站路径
mcp_migrations id, server_name, transport, source_tool, source_scope, source_project, source_path, target_tool, target_scope, target_project, status, detail, migrate_time MCP server 迁移日志（自 0.2.2 起）
mcp_trash id, server_name, tool, scope, project, original_path, trash_path, trash_time MCP 回收站：被替换/删除 server 的配置片段快照（自 0.2.2 起）
feedback id, type, content, contact, environment, log_tail, emailed, created_at 应用内反馈留档：Bug 报告 / 功能需求、截图引用与送达状态（自 0.3.2 起）
feedback_images id, feedback_id(外键), stored_path, created_at 反馈截图：最多 10 张、单张不超过 1MB（自 0.3.2 起）

两点一致性保证：连接级开启 PRAGMA foreign_keys=ON 外键约束；删除服务商时若其下还有配置方案会被拒绝（见服务商管理与预置模板）。

3. 备份目录

每次写入目标配置前，原文件先复制进 backups\，命名规则与滚动策略：

备份文件名 对应原文件
settings.<时间戳>.json.bak ~/.claude/settings.json
codex.config.<时间戳>.toml.bak ~/.codex/config.toml
dsh.settings.<时间戳>.yaml.bak ~/.dsh/settings.yaml
dsh.credentials.<时间戳>.yaml.bak ~/.dsh/.credentials.yaml
zcode.cli.<时间戳>.json.bak ~/.zcode/cli/config.json
zcode.v2.<时间戳>.json.bak ~/.zcode/v2/config.json
mcp.<文件名>.<时间戳>.bak MCP 迁移/写入前备份的目标配置文件（如 mcp.config.toml.<时间戳>.bak、mcp.cordis.patch.yml.<时间戳>.bak）

每类独立排序，超出最近 5 份的旧备份自动删除；手动回滚把对应 .bak 复制回原路径即可，操作见配置方案与一键切换第 5 节。

4. 状态文件

文件 写入者 角色
proxy.json 本地翻译代理进程 声明监听端口、PID 与鉴权 token，主程序凭它与代理建立联系；内容过期时主程序会按端口反查真实占用进程自愈
update_state.json 更新模块 记录被忽略的版本号与已下载待安装标记，原子写入防损坏

两个文件都可以安全地随数据目录一起删除：前者会在下次需要代理时重建，后者只损失「忽略此版本」记忆。

5. 日志

日志固定写在 ~\.a4agent\logs\a4agent.log，与数据目录分离：

  • 默认只记时间、级别与摘要信息，不记录任何请求或响应内容；
  • 排查代理转发问题时，可设置环境变量 A4AGENT_PROXY_DEBUG 开启完整请求头、请求体与上游响应的调试日志，用完关闭；
  • 提交问题反馈时请附上日志相关片段（报错前后即可），并先脱敏，见安装升级与卸载的反馈指引。

6. 路径覆盖环境变量

全部路径都可用环境变量覆盖，主要用于自动化测试与特殊部署。0.4.0 起前缀统一为 A4AGENT_，旧前缀 A4API_* 的变量名在读取侧仍被识别（脚本与 CI 平滑过渡）：

环境变量 覆盖对象
A4AGENT_DATA_DIR 运行时数据根目录（数据库、备份等整体搬家）
A4AGENT_SETTINGS_PATH Claude Code 的 settings.json 完整路径
A4AGENT_CODEX_CONFIG_PATH Codex 的 config.toml 完整路径
A4AGENT_CODEX_CATALOG_PATH Codex 模型目录 models.json 完整路径
A4AGENT_DSH_SETTINGS_PATH dsh 的 settings.yaml 完整路径
A4AGENT_DSH_CREDENTIALS_PATH dsh 的 .credentials.yaml 完整路径
DSH_HOME dsh 数据目录（影响上面两个 dsh 文件的默认定位）
A4AGENT_ZCODE_HOME ZCode 数据目录（影响下方 zcode 文件的默认定位，自 0.2.2 起）
A4AGENT_ZCODE_CLI_CONFIG_PATH ZCode 的 cli/config.json 完整路径
A4AGENT_ZCODE_V2_CONFIG_PATH ZCode 的 v2/config.json 完整路径
A4AGENT_CLAUDE_SKILLS_PATH Claude Code 全局 skill 根（可覆盖 ~/.claude/skills）
A4AGENT_CODEX_SKILLS_PATH Codex 全局 skill 根（可覆盖 ~/.codex/skills）
A4AGENT_DSH_SKILLS_PATH dsh 全局 skill 根（可覆盖 ~/.dsh/skills）
A4AGENT_ZCODE_SKILLS_PATH ZCode 全局 skill 根（可覆盖 ~/.zcode/skills）
A4AGENT_CLAUDE_MCP_PATH Claude Code 全局 MCP 配置文件（可覆盖 ~/.claude.json）
A4AGENT_DSH_MCP_PROFILE MCP 管理使用的 dsh profile 名（默认 web）
A4AGENT_DSH_MCP_PATCH_PATH dsh MCP 所在的 cordis.patch.yml 完整路径
A4AGENT_PROXY_DEBUG 开启代理调试日志（非路径，行为开关）

7. 旧版数据迁移

数据目录经历两段自动迁移，全程无需手工干预（迁移失败不阻塞启动）：

graph LR A[api-switch 时代
%APPDATA%\api-switch] -->|一次性迁移| B[a4api 时代
%APPDATA%\a4api] B -->|0.4.0 起整目录改名迁入| C[a4agent 时代
%APPDATA%\a4agent] style A fill:#fadbd8,stroke:#c0392b,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
  • api-switch → a4api：前身 api-switch 的数据目录为 %APPDATA%\api-switch\（数据库 api_switch.db），旧库不存在新库时复制为 a4api.db，旧的 backups\ 与 proxy.json 一并搬入；
  • a4api → a4agent（0.4.0 起）：首次启动把 %APPDATA%\a4api\ 整目录改名迁入 %APPDATA%\a4agent\（含本地模型引擎等大文件），目录被占用时退化为关键文件逐项拷贝，数据不丢；库文件 a4api.db → a4agent.db，开发态仅做库文件改名；日志目录随之迁至 ~\.a4agent\logs\，旧目录保留不删。

老用户升级后配置方案与密钥无缝延续，见版本更新说明。

8. 常见问题

问：如何把 a4agent 搬到另一台电脑？

答：API Key 密文与 Windows 用户绑定，直接拷贝数据库在新机上解不开。正确做法是在新机重装应用后重建配置方案（服务商模板会自动播种，只需重填 Key）；备份文件如需带走，注意它们是明文配置，含真实 Key 时妥善保管。

问：能直接用 SQLite 工具编辑 a4agent.db 吗？

答：技术上可以读，但不建议写——界面层有名称唯一性、外键保护等校验，绕开界面改库可能制造出界面无法处理的脏数据。需要批量调整时优先通过界面操作。

问：想彻底重置 a4agent 怎么做？

答：退出应用后删除整个数据目录（安装版 %APPDATA%\a4agent\，开发版 backend/database/），再启动即得到全新环境：数据库重建、模板重新播种；~/.a4agent/logs/ 日志如需一并清掉可单独删除。

问：updates 目录里的安装包能删吗？

答：能。那是已下载的历史安装包缓存，删除后不影响任何功能，只是若再点「立即更新」需要重新下载对应版本。

问：engine 目录能删吗？会再占多少空间？

答：engine\ 是本地模型功能下载的 llama.cpp 引擎文件（数百 MB 级）。不用本地模型功能时可以删除释放空间，下次使用时向导会提示重新下载或离线安装；删除不影响 API 切换、技能与 MCP 管理等其他功能。