下表中的 ~ 表示当前系统用户目录。桌面界面是首选配置入口；直接编辑文件适合开发、诊断和受控迁移。
全局路径
| 路径 | 内容 |
|---|---|
~/.vetta/agent/settings.json | Coding Agent 全局设置 |
~/.vetta/agent/models.json | 自定义 Provider 和模型覆盖 |
~/.vetta/agent/auth.json | 登录、OAuth 或手动凭证记录 |
~/.vetta/agent/mcp.json | MCP 服务配置 |
~/.vetta/agent/sessions/ | 按安全 cwd 组织的会话文件 |
~/.vetta/abilities.json | 已安装能力索引 |
~/.vetta/skills/ | 用户级技能 |
~/.vetta/scene/ | 用户级场景 |
~/.vetta/plugins/ | 用户级插件 |
可以使用 VETTA_CODING_AGENT_DIR 覆盖 Agent 目录，但宿主、sidecar 和迁移工具必须使用同一值，避免会话和配置分裂。
项目路径
| 路径 | 内容 |
|---|---|
<cwd>/AGENTS.md | 项目长期指令，供项目会话自动加载 |
<cwd>/.vetta/settings.json | 覆盖全局 Agent 设置 |
<cwd>/.vetta/skills/ | 项目级技能 |
<cwd>/.vetta/extensions/ | 项目级 Coding Agent Extension |
项目设置中的相对路径相对于 .vetta/settings.json 所在目录解析。项目级配置优先于全局配置。
修改和迁移原则
- 优先通过 Vetta 设置页修改，确保运行时校验和关联状态同步。
- 手工编辑前退出相关活动会话，避免与正在写入的进程冲突。
- 不让两个进程同时写同一个会话文件。
- 迁移时保留目录结构和文件名，不只复制单个会话正文。
- 删除前分清原始资料、整理结果、会话历史和产物，它们的保留语义不同。