存储与目录结构参考手册

Ante 将配置与状态持久化保存在本地文件系统中。本页面为 Ante 读取或写入的每个文件系统位置提供完整参考。

目录位置

路径位置	用途说明
`~/.ante/settings.json`	用户偏好设置（模型、提供商、主题、MCP 服务器）
`~/.ante/<name>.settings.json`	通过 `--profile <name>` 或 `ANTE_PROFILE` 选定的完整设置 Profile 文件
`~/.ante/catalog.json`	自定义提供商、OAuth Profile 与凭据 helper
`~/.ante/auth/credentials/`	已存储的凭据，仅所有者可读：`secret/`（API 密钥）、`oauth/`（登录）、`helper/`（helper 输出）。使用 `ante auth` 管理
`~/.ante/AGENTS.md`	注入到每个项目会话中的全局行为指引
`~/.ante/skills/`	用户级全局技能（Skills）
`~/.ante/agents/`	用户级全局子智能体（Sub-agents）
`~/.ante/.system/`	由当前安装的 Ante 版本所管理的内置技能与子智能体
`~/.ante/sessions/<session-id>/`	持久化会话数据（供 `/resume` 和 `--resume` 使用）
`~/.ante/projects/<project-id>/memory/`	各项目的专属自动记忆库
`~/.ante/run/jobs/<proc-id>/`	后台 Bash 任务句柄：`status.json`、`stdout.txt` 和 `stderr.txt`
`~/.ante/run/offline/`	托管路由器的 `router.json` 进程记录和 `presets.ini` 模型预设；保留的路由器靠这些文件供后续启动复用
`~/.ante/run/serve.sock`	`ante serve --sock` 的默认 Unix 套接字；同级的 `serve.sock.lock` 持有宿主的排他锁
系统缓存目录（`~/Library/Caches/ante`、`$XDG_CACHE_HOME/ante`）	WebFetch 超大响应溢出暂存文件
系统临时目录	一次性暂存文件与中间下载数据
`~/.ante/logs/<YYYY-MM-DD>/`	应用程序与崩溃日志，按 UTC 日期归档（`ante.<pid>.log` 与 `ante.<pid>.crash.log`）
`~/.ante/logs/llama-server.log`	本地推理服务器日志
`~/.ante/models/`	本地 GGUF 模型的默认存放目录
`~/.ante/llama.cpp/`	托管的 llama.cpp 运行时安装目录
`~/.ante/offline-config.json`	离线模式引擎、模型与服务端偏好设置
`~/.ante/verified_models.json`	用户可选添加与覆盖的验证本地模型列表
`~/.ante/channels.json`	Slack 与 Discord 机器人网关配置
`~/.ante/versions.json`	缓存的版本更新检查与发布说明状态
`~/.ante/user_input_history.jsonl`	TUI 历史输入提示词记录
`~/.ante/tip_history.json`	加载状态技巧提示的展示历史（删除可重置轮播）
`~/.ante/installation-id`	用于遥测的安装标识（配置遥测时写入；可编辑为 `anon` 等通用名称，或删除重置）
`AGENTS.md`	与全局指引一同注入的项目级行为规范
`.ante/settings.json`	叠加在用户设置之上的项目设置，从会话目录最近的上级目录解析得到
`.ante/`	项目本地配置（技能、子智能体）
`.agents/`, `.claude/`	兼容的项目本地技能/子智能体目录

<project-id> 是项目绝对路径的规范化清理形式。环境变量 ANTE_HOME 可覆盖 ~/.ante 路径。

WebFetch 溢出文件使用系统缓存目录：macOS 为 ~/Library/Caches/ante，Linux 为 $XDG_CACHE_HOME/ante（未设置或不是绝对路径时使用 ~/.cache/ante），Windows 为 %LOCALAPPDATA%/ante。仅在无法解析系统缓存目录时才回退到 $ANTE_HOME/cache；正常情况下，修改 ANTE_HOME 不会移动缓存。超过 48 小时的缓存条目会在后续启动时清理。一次性暂存文件与中间下载使用系统临时目录，不属于 Ante 的 48 小时缓存清理范围。

后台任务目录属于运行中进程的状态而非临时草稿。Ante 绝不会因时长原因清理正在运行的活跃任务；在任务结束后，其目录会保留 24 小时，并在随后的启动中完成回收。

`settings.json`

存储用户偏好设置。所有字段均为可选。

{
  "model": "claude-sonnet-5-5",
  "provider": "anthropic",
  "theme": "default",
  "permission_mode": "strict",
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(rm *)"]
  },
  "channel": "stable",
  "has_completed_onboarding": true,
  "status_line": ["model-name", "current-dir"],
  "model_effort": {
    "claude-sonnet-5-5": "medium",
    "gpt-6.1-sol": "high"
  },
  "provider_model": {
    "anthropic": "claude-sonnet-5-5"
  },
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

命名 Profile 文件具有相同的 Schema，但在运行时全量替换 settings.json；它们不会从 settings.json 继承缺失的字段。关于 Profile 机制及完整字段参考，请参阅偏好设置。

项目的 .ante/settings.json 使用同一 Schema，但以叠加方式作用于用户设置文件：只有它显式设置的键会被覆盖。由于它属于仓库内容，只能收紧或固定、不能放宽，因此 permission_mode、permissions.allow、mcp_servers、system_prompt、model、provider 会被丢弃并给出提示。参见项目设置。

已保存的对话

每个 ~/.ante/sessions/<session-id>/ 目录保存可恢复的对话、事件日志与元数据。元数据包含创建时间和最近活动时间；恢复选择器按最近活动时间排序，旧快照缺少该字段时回退到创建时间。分叉会话还记录来源会话 ID forked_from。/resume 显示的大小是 events.jsonl 的文件大小（缺失时为零），并非整个会话目录大小或上下文 Token 数。

回退替换当前历史前，Ante 会在该会话目录的 abandoned/<rwd-id>/dialog.json 与 events.jsonl 中保留放弃的对话和事件日志。这些是保留副本，不会作为独立会话出现在恢复选择器中。仅恢复对话的边界请参阅回退与分叉。

`catalog.json`

在内置目录的基础上添加或修改提供商，并定义 OAuth Profile 与凭据 helper。所有顶层键均为可选。my-provider 键即为传入 --provider 的标识。若键匹配内置预设（如 openai），则逐字段修改该提供商；若为新键则添加提供商。

{
  "providers": {
    "my-provider": {
      "display_name": "My Provider",
      "base_url": "https://api.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:MY_PROVIDER_API_KEY"
    }
  }
}

格式错误的条目会被单独跳过并在启动时报告。同一文件中的其他有效条目仍会正常加载。

完整 Schema、凭据与解析规则请参阅目录参考手册，定制配方请参阅自定义模型目录范例。

`AGENTS.md`

存储智能体的持久化行为指引。~/.ante/AGENTS.md 全局生效，项目 AGENTS.md 作用于该代码仓库。当两者同时存在时，Ante 会在对话之前的会话前导提醒中同时注入两者。

使用指南与优先级规则请参阅 AGENTS.md。

目录结构总览

用户级目录（`~/.ante/`）

~/.ante/
├── settings.json       # 用户偏好设置
├── <name>.settings.json # 命名 Profile 配置文件
├── catalog.json        # 自定义提供商、OAuth Profile、helper
├── auth/credentials/   # 已存储的密钥、登录与 helper 输出（仅所有者可读）
├── AGENTS.md           # 全局行为指引
├── installation-id     # 随机遥测安装标识
├── user_input_history.jsonl # TUI 提示词历史
├── tip_history.json    # 加载提示历史
├── versions.json       # 更新缓存与发布说明状态
├── channels.json       # 机器人网关配置
├── offline-config.json # 离线模式配置
├── verified_models.json # 可选的本地验证模型目录覆盖
├── .system/            # Ante 管理的内置技能与子智能体
├── skills/             # 用户级全局技能
├── agents/             # 用户级全局子智能体
├── sessions/           # 持久化会话（供 /resume 使用）
├── projects/           # 各项目状态数据（记忆等）
│   └── <project-id>/
│       └── memory/
│           └── MEMORY.md
├── run/
│   ├── jobs/
│   │   └── <proc-id>/  # 后台 Bash 状态与输出
│   ├── offline/
│   │   ├── router.json # 路由器 PID、端口及身份信息
│   │   └── presets.ini # 模型加载预设
│   ├── serve.sock      # `ante serve --sock` 监听套接字
│   └── serve.sock.lock # 上述套接字的所有权锁
├── logs/
│   ├── <YYYY-MM-DD>/   # ante.<pid>.log 与崩溃日志
│   └── llama-server.log
├── models/             # 本地 GGUF 模型文件
└── llama.cpp/          # 托管的本地推理引擎

项目级目录

AGENTS.md               # 项目行为指引规范

.ante/
├── settings.json       # 叠加在用户设置之上的项目设置
├── skills/             # 项目专属技能
└── agents/             # 项目专属子智能体

.agents/
├── skills/             # 项目专属技能
└── agents/             # 项目专属子智能体

.claude/
├── skills/             # 项目专属技能（Claude Code 兼容）
└── agents/             # 项目专属子智能体（Claude Code 兼容）

偏好设置 — 完整 settings.json 参考与环境变量列表
目录参考手册 — catalog.json Schema、内置提供商及模型 ID
连接提供商 — 通过 OAuth 或 API 密钥登录
Skills 技能系统 — 技能目录结构
子智能体 — 子智能体目录结构
持久化记忆 — 自动记忆存储格式

目录位置​

settings.json​

已保存的对话​

catalog.json​

AGENTS.md​

目录结构总览​

用户级目录（~/.ante/）​

项目级目录​

相关章节​