主流Agent文件目录解析
本篇文章主要梳理一下现在主流的Agent框架如何做文件系统管理的，如会话、记忆如何存放，如何做项目隔离等等。
引言
随启随用的成熟Agent框架大大简化了我们的工作流，但其目录结构和文件组织形式却常被忽略，所以本文将针对Claude Code、Codex和Copilot三大主流Vibe Coding Agent框架的文件系统进行简要介绍。
Claude Code
Claude Code的目录分为两种，即全局~/.claude/和项目级.claude/，且项目级配置的优先级高于全局配置。
首先，我们以全局文件目录入手，展示Claude Code的文件目录是如何组织的
~ # 用户目录
├── .claude.json # 自动生成的本地应用状态文件，用于保存登录会话、MCP配置等运行时信息
└── .claude/ # 全局个人配置，跨所有项目生效
├── CLAUDE.md # 全局个人记忆，每次会话与项目CLAUDE.md同时加载冲突时项目级优先
├── settings.json # 全局默认设置包括权限/hooks/模型/env，会被项目级settings.json覆盖
├── keybindings.json # 自定义快捷键映射，启动时加载，文件变更后热重载
├── stats-cache.json # /usage展示的token与费用累计统计缓存，永久保留，不自动清理
├── remote-settings.json # 企业managed settings本地缓存；每次启动刷新，永久保留
├── history.jsonl # 所有会话中输入过的prompt历史，支持上箭头跨会话回调，永久保留
├── .last-cleanup # 记录上次自动清理的时间戳，启动时用于判断是否触发清理任务
├── .last-update-result.json # 记录上次自动更新的结果即成功/失败/版本号，用于显示更新提示
├── settings.json.ds # settings.json的结构说明文件文件，用于IDE做自动补全和校验
├── themes/ # 自定义颜色主题
│ └── <name>.json # 通过/theme创建或手写，/theme <name>切换
├── rules/ # 全局规则
│ └── *.md # 可以随意命名，无paths参数每次启动时加载，有paths匹配文件进入上下文时加载
├── skills/ # 全局个人技能，任意项目中用/<name>调用，或由Claude自动触发
│ └── <name>/ # name为自定义字段
│ ├── SKILL.md # description决定Claude是否自动触发，支持$ARGUMENTS
│ └── [辅助文件] # 与SKILL.md捆绑的参考文档、模板、脚本等，Claude可按需读取
├── commands/ # 单文件命令，旧机制，现已与skills合并，并建议新工作流改用skills
│ └── <name>.md # /<name>调用；同名时skill优先于command
├── agents/ # 用于定义具有独立上下文与工具权限的子Agent
│ └── <name>.md # @<name>手动调用或由Claude自动委派
├── workflows/ # 由Claude生成或用户定义的可执行工作流脚本，用于把多步骤任务自动化成一个命令
│ └── <name>.js # 启动时加载为/<name>命令，会被同名项目级workflow覆盖
├── agent-memory/ # memory:user子代理的跨项目持久记忆
│ └── <name>/ # name与agents中的保持一致
│ └── MEMORY.md # 子Agent自动维护，启动时注入system prompt，注入前200行或25KB
├── output-styles/ # 用于定义回答的语气、结构和表达方式，会话启动时注入system prompt
│ └── *.md # 通过settings.json中的outputStyle字段设置启用
├── plugins/ # 插件市场与已安装插件数据，由claude plugin命令管理，不建议手动编辑
│ ├── config.json # 全局插件配置
│ ├── installed_plugins.json # 已安装插件列表
│ ├── known_marketplaces.json # 插件市场源配置
│ └── marketplaces/ # 已克隆的插件市场内容与插件文件
├── ide/ # IDE集成相关的锁文件与通信文件，供IDE扩展与CLI进程协调使用
├── sessions/ # Desktop应用的会话窗口状态，用于应用重启后恢复多会话面板，CLI不使用此目录
├── cache/ # 通用运行时缓存，存放插件、MCP或其他功能的临时计算结果
├── daemon/ # 后台守护进程的PID与socket文件，用于CLI与IDE插件之间的进程管理与通信协调
├── telemetry/ # 遥测数据缓存，用于记录匿名使用统计与性能指标，用于产品优化，可通过配置关闭
├── statsig/ # 用于产品功能灰度和实验控制的配置缓存，属于产品优化的“开关层”。
├── projects/ # 项目级持久数据存储，包含会话记录与衍生记忆
│ └── <project-path>/ # 以代码库绝对路径命名
│ ├── <session>.jsonl # 完整某次会话记录，默认保留30天，通过cleanupPeriodDays修改
│ ├── <session>/ # 单次会话附属数据目录
│ │ ├── subagents/ # 子代理会话记录，随父session一起清理
│ │ └── tool-results/ # 大型工具输出溢出文件
│ └── memory/ # Claude自动积累维护的项目知识，永久保留
│ ├── MEMORY.md # 记忆索引，每次启动加载前200行或25KB，由Claude自动维护
│ └── <topic>.md # 按主题拆分的记忆文件，如debugging.md，相关任务时按需加载
├── file-history/ # Claude Code修改文件前做的的快照，用于后续/undo回滚
│ └── <session>/ # 按会话存储的文件原始状态，默认保留30天
├── plans/ # 在Plan Mode下生成的任务计划草稿和执行蓝图的存储目录，默认保留30天
├── paste-cache/ # 粘贴内容临时缓存，避免直接塞进对话导致上下文污染或超长问题，默认保留30天
├── image-cache/ # 粘贴/拖入的图像文件缓存，默认保留30天
├── session-env/ # 每会话环境元数据，用于调试与恢复运行上下文，默认保留30天
├── tasks/ # 在执行复杂任务时自动生成的结构化任务拆解列表，默认保留30天
├── shell-snapshots/ # 在执行Bash工具时，对运行环境做的快照，用于异常恢复，正常退出时删除
├── debug/ # --debug或/debug启动时生成的调试日志，默认保留30天
└── backups/ # ~/.claude.json配置迁移前的时间戳备份，默认保留30天
Claude Code的全局目录用于定义跨项目的个人默认行为和工具能力，而项目级目录用于存储单个代码库的专属规则、记忆与执行上下文，项目级目录如下：
MyProject/ # 示例项目根目录
├── CLAUDE.md # 项目总纲领，包含项目说明书、行为约束、工作规范等
├── CLAUDE.local.md # 本地个人偏好，不会被提交至Git
├── .mcp.json # 项目专用MCP服务器配置
├── .worktreeinclude # 指定git worktree新建工作树时需一并复制的文件列表
└── .claude/ # 项目级专属配置目录
├── settings.json # 项目共享设置
├── settings.local.json # 仅本机生效的项目设置覆盖，不会被提交至Git
├── rules/ # 项目专用规则库，功能与全局目录中的类似
├── skills/ # 项目专用技能库，功能与全局目录中的类似
├── agents/ # 项目专用自定义子Agent，功能与全局目录中的类似
├── workflows/ # 项目专用工作流脚本，功能与全局目录中的类似
├── agent-memory/ # 项目级专用子代理记忆库，功能与全局目录中的类似
└── output-styles/ # 项目级输出格式约束，功能与全局目录中的类似
能看到，项目级的目录和全局目录有很多配置是重复的，所以如果在项目级目录中配置，则会覆盖全局目录里面的配置。此外，上述结构可能并不完整。
Codex
相较于Claude Code可以随意配置大模型API的灵活性，Codex更像是一个GPT专用产品，一般都是充值GPT Plus或者Pro使用，当然也有一些手段去强制切换Codex的大模型API，不过需要一些中间件。
Codex的文件目录如下所示：
~/.codex/
├── config.toml # CLI全局配置控制模型工具权限与默认行为
├── auth.json # 存储登录认证信息与访问凭证
├── installation_id # 当前安装实例唯一标识
├── version.json # 当前CLI版本信息
├── cap_sid # 当前能力会话标识用于功能协商
├── history.jsonl # 用户输入历史索引
├── models_cache.json # 模型能力与路由缓存
├── personality_migration # 个性化配置迁移标记
├── sessions/ # 会话事件流按日期存储
│ └── YYYY/
│ └── MM/
│ └── DD/
│ └── rollout-<timestamp>-<uuid>.jsonl # 完整会话日志
├── skills/ # Skills能力包与自定义技能
├── cache/ # 网络请求与资源缓存
├── tmp/ # 临时运行文件
├── .tmp/ # 系统内部临时目录
├── .sandbox # sandbox配置
├── .sandbox-bin # sandbox执行入口
├── .sandbox-secrets # sandbox隔离密钥
├── sandbox-YYYY-MM-DD.log # sandbox运行日志
├── goals_<n>.sqlite # Agent任务规划数据库
├── goals_<n>.sqlite-shm # SQLite共享内存
├── goals_<n>.sqlite-wal # SQLite预写日志
├── memories_<n>.sqlite # 长期记忆数据库
├── state_<n>.sqlite # Agent运行状态数据库
├── state_<n>.sqlite-shm # SQLite共享内存
├── state_<n>.sqlite-wal # SQLite预写日志
├── logs_<n>.sqlite # 结构化日志数据库
├── logs_<n>.sqlite-shm # SQLite共享内存
└── logs_<n>.sqlite-wal # SQLite预写日志
可以明显感觉到，其实Codex不像Claude Code一样，按project划分聊天记录，而是按照session直接划分，且多了sandbox相关文件。
Copilot
Copilot其实还可以细分一下，即Copilot CLI和VSCode Copilot。不过大多数情况下，VSCode Copilot的使用比较多一些。
Copilot CLI和VSCode Copilot的区别不在于能力强弱或能不能做某些事情，而在于交互方式：它们本质上共享同一套模型能力，VSCode Copilot更偏向IDE内的实时编码辅助，即补全、理解、人工逐步确认，而Copilot CLI更偏向终端中的任务驱动式交互，即用自然语言生成并组织命令流程。因此差异主要是使用场景和操作形态，而不是底层能力本身。
这里我们先简单介绍一下Copilot CLI的目录文件组织形式，然后主要介绍VSCode Copilot。
如下是Copilot CLI的目录文件组织形式：
~/.copilot/ # Copilot CLI用户主目录，存放所有配置状态会话与插件数据
├── settings.json # 用户主配置文件，用于模型界面行为和功能偏好设置
├── mcp-config.json # MCP服务器配置文件，用于所有会话共享工具连接配置
├── lsp-config.json # 语言服务器配置文件，用于代码智能提示与补全能力
├── instructions/ # 全局指令目录，用于定义所有会话通用行为规则
│ └── *.instructions.md # 全局指令文件，用于自动加载的长期行为约束
├── agents/ # 全局自定义Agent目录，用于定义可复用任务执行智能体
│ └── *.agent.md # Agent定义文件，用于描述任务规划与执行逻辑
├── skills/ # Skills能力模块目录，用于封装可复用任务能力
│ └── */SKILL.md # Skill定义文件，用于提供结构化任务能力
├── copilot-instructions.md # 全局默认指令文件，用于所有会话基础行为约束
├── extensions/ # CLI扩展目录，用于安装和管理功能扩展
├── hooks/ # 钩子目录，用于在特定生命周期触发自定义脚本
├── permissions-config.json # 权限配置文件，用于记录目录与工具访问授权
├── config.json # 内部状态文件，用于保存运行状态与实验配置
├── session-state/ # 会话状态目录，用于保存每次对话运行过程数据
│ └── <session-id>/ # 单个会话目录，用于存储一次完整交互状态
│ ├── events.jsonl # 会话事件日志文件，用于记录完整交互过程
│ ├── plans/ # 计划目录，用于存放任务执行计划数据
│ └── checkpoints/ # 检查点目录，用于保存阶段性执行状态
├── command-history-state/ # 命令历史目录，用于记录终端输入历史
├── session-store.db # 会话索引数据库，用于跨会话检索与恢复
├── logs/ # 日志目录，用于存放运行调试与错误日志
│ └── *.log # 日志文件，用于记录运行过程与错误信息
├── installed-plugins/ # 插件安装目录，用于存放来自市场或Git的插件
│ ├── <marketplace>/ # 市场插件目录，用于官方插件来源
│ └── _direct/ # 直接安装插件目录，用于Git或URL安装插件
├── plugin-data/ # 插件数据目录，用于存储插件运行时持久化数据
├── ide/ # IDE通信目录，用于VSCode等编辑器连接状态管理
├── mcp-secrets/ # MCP密钥目录，用于存储认证令牌与备用凭证
相比之下，VSCode Copilot的文件目录组织形式就要复杂很多了，它相当于一个扩展，寄生于VSCode的目录里面。
Linux下VSCode的用户配置根目录为~/.config/Code/User/，Windows下为%APPDATA%\Code\User\，我们这里以Windows为例。
首先，我们先看一下VSCode的用户目录，当然不同版本之间可能存在差异：
%APPDATA%\Code\User\ # VSCode用户配置根目录
├── settings.json # 用户全局配置文件用于编辑器行为扩展配置
├── keybindings.json # 自定义快捷键绑定配置文件
├── tasks.json # 任务运行系统配置文件用于脚本执行
├── launch.json # 调试配置文件用于debug运行参数
├── snippets/ # 代码片段目录用于全局代码模板
│ └── *.json # 各语言代码片段定义文件
├── profiles/ # VSCode多配置环境用于隔离开发环境
│ └── <profile-id>/ # 单个profile隔离配置目录
├── globalStorage/ # 扩展全局存储用于跨workspace持久化数据
│ └── github.copilot-chat/ # Copilot Chat扩展全局状态存储
│ ├── chatConfig.json # Chat功能配置缓存
│ ├── models.json # 模型路由配置与可用模型列表
│ ├── state.json # 扩展运行状态缓存
│ └── telemetry/ # 遥测与使用数据记录
├── workspaceStorage/ # 工作区级扩展状态核心存储
│ └── <workspace-hash>/ # 每个项目唯一hash目录
│ ├── state.vscdb # SQLite扩展状态数据库核心文件
│ ├── state.vscdb-wal # SQLite写前日志文件
│ ├── state.vscdb-shm # SQLite共享内存文件
│ ├── workspace.json # 当前workspace元信息用于记录项目路径和结构
│ ├── chatSessions/ # Copilot Chat会话记录目录
│ │ └── *.jsonl # 按事件流记录的对话日志
│ ├── chatEditingSessions/ # Copilot Agent编辑会话记录
│ │ └── *.json # AI多文件修改操作记录
│ ├── GitHub.copilot-chat/ # Copilot工作区索引与缓存目录
│ ├── extensionStorage/ # 其他扩展工作区数据存储
│ ├── history/ # 工作区文件操作历史记录
│ └── backups/ # 自动保存与崩溃恢复文件
├── sync/ # 设置同步本地缓存用于账号同步状态
└── History/ # 恢复上次编辑状态的轻量行为缓存
可以看到，当VSCode打开某个工作区时，会在workspaceStorage目录下生成一个项目目录，然后所有的Copilot对话日志都会放到这个项目目录里面。
此外，VSCode还有远程目录，结构如下：
~/.vscode-server/data/User/ # 远程服务器上的目录
├── workspaceStorage/ # 与本地一致的工作区存储
│ └── <workspace-hash>/ # 项目目录
当用VSCode连接远程服务器目录时，会在本地和远程服务器中，各自生成一个具有相同哈希名字的项目目录。当使用Copilot在远程服务器上对话时，包含local和copilot cli模式，会将对话记录存储在本地的workspaceStorage，而非远端。
VSCode Copilot还有项目级目录，结构如下：
MyProject/.github/copilot/ # Copilot项目级配置目录
├── settings.json # 项目级Copilot行为配置
├── instructions.md # 项目级AI行为指令
└── prompts/ # 预设Prompt
这个项目目录的作用其实和Claude Code的项目目录差不多，都是写给这个项目的一些专属配置。
此外，VSCode Copilot自带Claude Code和Codex的SDK，即使本地没有安装也可以直接使用Claude Code，不过不能切换大模型API，且消耗的是Copilot的额度，最终会将聊天记录保存到~/.claude/projects中。如果通过远程连接，则会创建至远程服务器的.claude文件夹中，如果远程主机上原来没有Claude Code，则会自动创建一个.claude文件夹，用于存储数据。
如果远程服务器上装了Claude Code，那么VSCode能够自动识别Cluade Code在当前项目文件夹中的聊天记录，即VSCode Copilot中的Claude Code SDK和自行安装的Claude Code其实是共用~.claude文件夹的。
值得指出的是，通过claude --resume命令一般看不全所有对话，但是VSCode却能全部列出来。
这里还要分享一个小技巧，如果想在远程服务器上不安装Claude Code的情况下，使用本地VSCode中的Claude Code，且想自己配置大模型API，则需要安装Claude Code For Vscode插件，并在VSCode中的setting->extension->Claude Code中设置setting，具体修改内容可参考如下：
{
"files.autoSave": "afterDelay",
"workbench.startupEditor": "none",
"workbench.colorTheme": "Dark Modern",
"claudeCode.preferredLocation": "panel",
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://xxxx" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "xxxxx" },
{ "name": "ANTHROPIC_MODEL", "value": "mimo-v2.5" },
{ "name": "ANTHROPIC_DEFAULT_SONNET_MODEL","value": "mimo-v2.5"},
{ "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "mimo-v2.5-pro" },
{ "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "mimo-v2.5" }
]
}
这个插件相当于重新安装了一份Claude Code，而没有使用VSCode Copilot中的，不过最终会被VSCode Copilot识别，并自动添加至VSCode Copilot扩展界面中，如下所示：
实际上，这两种方式使用的Claude和Codex功能上并没有区别，只不过一个基于Copilot的额度，一个可以自定义模型API。
References
[1] https://code.claude.com/docs/en/overview
[2] https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference