不会做RAG、agent的本地数据管理？都来学Claude Code！附深度拆解

Zilliz Planet

1285人浏览 · 2026-02-24 15:22:18

Zilliz Planet · 2026-02-24 15:22:18 发布

企业级场景中，无论是做RAG还是agent，我们都会面临一个问题：出于数据隐私以及合规要求，数据必须保留在本地。但传统的本地存储方案往往存在数据隔离性差、崩溃易丢数据、配置管理混乱、操作不可撤销等问题。

Claude Code 通过一套精心设计的存储体系，系统性地解决了这些痛点。

以下为核心思路的太长不看版：

多项目隔离问题：路径编码的项目目录 + Session文件独立存储 → 不同项目数据物理隔离，无交叉干扰；

数据丢失问题：JSONL流式追加写入 + 每条消息实时持久化 → 崩溃时仅可能丢失最后一行未写入数据，损失最小化；

对话追溯问题：uuid+parentUuid消息链 + 完整消息类型（thinking/tool_use/summary） → 可回溯每一轮交互的上下文、工具调用逻辑；

操作不可撤销问题：file-history-snapshot前置备份 + 哈希存储原始内容 + 快捷键撤销 → 支持一键回滚代码修改，无风险；

配置灵活度问题：三级配置体系（全局→本地→项目） + 权限优先级（deny>ask>allow） → 兼顾统一管理与局部定制，同时保障安全；

功能扩展问题：plugins + skills三级架构 → 支持插件、Skill的灵活扩展，适配不同开发场景。

下文是Claude Code 存储架构的核心逻辑、实现方案的详细拆解。

01 设计背景：本地 AI 编程助手的存储痛点

对于本地化运行的 AI 编程工具而言，数据存储需要兼顾多维度需求：

多项目隔离：开发者通常同时维护多个项目，会话数据若混存会导致溯源困难、管理混乱；

数据安全性：AI 对话过程中的实时交互数据（如代码修改、工具调用记录）若未实时持久化，程序崩溃易造成数据丢失；

可追溯性：复杂的编程对话包含多轮交互和工具调用，需要完整的上下文链路支撑回溯和问题定位；

操作可恢复性：AI 自动修改代码后，若效果不符合预期，需支持快速撤销回滚；

配置灵活性：不同机器、不同项目可能有差异化的权限、插件配置，需兼顾全局统一和局部定制。

针对这些痛点，Claude Code 确立了四大核心设计原则，作为整个存储架构的底层指导。

02 核心设计原则：构建可靠、可管的存储体系

Claude Code的存储架构围绕以下四大原则展开

1. 按项目隔离：解决多项目数据混存问题

将Session（会话）数据严格按项目路径组织，每个项目的会话数据独立存储，避免不同项目的交互记录相互干扰，同时方便按项目维度管理、清理数据。

2. 实时持久化：解决崩溃丢数据问题

采用JSONL（JSON Lines）格式存储核心会话数据，支持流式追加写入，每条消息生成后立即落地，即使程序崩溃也仅能最大程度保障数据完整性。

3. 可追溯：解决上下文链路断裂问题

通过消息链结构（uuid + parentUuid）串联所有交互记录，支持完整的对话回溯和问题定位。

4. 可恢复：解决操作不可撤销问题

基于file-history-snapshot（文件历史快照）机制，在修改文件前自动备份原始内容，降低误操作风险。

03 全局目录搭建思路

Claude Code的所有本地数据集中存储在用户主目录下，核心分为以下两部分

（1）~/.claude.json 完整示例如下

{
"projects": {
"/Users/xxx/my-project": {
"mcpServers": {
"jarvis-tasks": {
"type": "stdio",
"command": "python",
"args": ["/path/to/run_mcp.py"]
}
}
}
},
"recentPrompts": [
"Fix the bug in auth module",
"Add unit tests"
]
}

（2）claude完整目录结构如下：

~/.claude/
├── settings.json                    # 全局设置（权限、插件、清理周期）
├── settings.local.json              # 本地设置（机器特定，不提交Git）
├── history.jsonl                    # 命令历史记录
│
├── projects/                        # 📁 Session 数据（按项目组织，核心目录）
│   └── -Users-xxx-project/          # 路径编码后的项目目录
│       ├── {session-id}.jsonl       # 主会话数据（JSONL格式）
│       └── agent-{agentId}.jsonl    # 子代理会话数据
│
├── session-env/                     # Session 环境变量
│   └── {session-id}/                # 按Session ID隔离
│
├── skills/                          # 📁 用户级 Skills（全局可用）
│   └── mac-mail/
│       └── SKILL.md
│
├── plugins/                         # 📁 插件管理
│   ├── config.json                  # 插件全局配置
│   ├── installed_plugins.json       # 已安装插件列表
│   ├── known_marketplaces.json      # 市场源配置
│   ├── cache/                       # 插件缓存
│   └── marketplaces/
│       └── anthropic-agent-skills/
│           ├── .claude-plugin/
│           │   └── marketplace.json
│           └── skills/
│               ├── pdf/
│               ├── docx/
│               └── frontend-design/
│
├── todos/                           # 任务列表存储
│   └── {session-id}-*.json          # 关联Session的任务文件
│
├── file-history/                    # 文件编辑历史（按内容hash存储）
│   └── {content-hash}/              # 哈希命名的文件备份目录
│
├── shell-snapshots/                 # Shell 状态快照
├── plans/                           # Plan Mode 计划存储
├── local/                           # 本地工具/node_modules
│   └── claude                       # Claude CLI 可执行文件
│   └── node_modules/                # 本地依赖
│
├── statsig/                         # 特性开关缓存
├── telemetry/                       # 遥测数据
└── debug/                           # 调试日志

04 Claude Code配置文件层级设计

为兼顾全局统一配置和局部定制需求，Claude Code设计了三级配置体系，优先级从高到低依次为：项目级配置 > 本地配置 > 全局配置。

┌─────────────────────────────────────────┐
│           项目级配置                      │  优先级最高
│    项目/.claude/settings.json            │  项目专属，覆盖其他配置
├─────────────────────────────────────────┤
│           本地配置                        │  机器特定，不提交版本控制
│    ~/.claude/settings.local.json         │  覆盖全局配置
├─────────────────────────────────────────┤
│           全局配置                        │  优先级最低
│    ~/.claude/settings.json               │  基础默认配置
└─────────────────────────────────────────┘

各配置文件完整示例如下：

（1） ~/.claude/settings.json（全局设置）

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**)", "Bash(npm:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Edit", "Write"]
  },
  "enabledPlugins": {
    "document-skills@anthropic-agent-skills": true
  },
  "cleanupPeriodDays": 30
}

（2） ~/.claude/settings.local.json（机器特定，不提交版本控制）

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(docker:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

（3）项目/.claude/settings.json（项目专属）

{
  "permissions": {
    "allow": ["Bash(pytest:*)"]
  }
}

整体的配置合并与权限规则如下：

合并规则：最终配置 = 全局配置 + 本地配置覆盖 + 项目配置覆盖（后加载的配置覆盖先加载的同字段）；

权限优先级：deny > ask > allow > 默认行为（严格遵循，保障操作安全）。

05 Session数据存储：核心交互数据的持久化设计

Session是Claude Code最核心的数据，存储了所有对话历史和上下文，其设计直接决定了数据可靠性和可追溯性。

（1）存储思路：按项目路径编码隔离

存储路径：~/.claude/projects/ + 路径编码后的项目目录；

路径编码规则：将 /、空格、~ 替换为 -；

示例

/Users/bill/My Project → -Users-bill-My-Project

（2）存储格式：JSONL的优势与示例

Session数据采用JSONL（JSON Lines）格式，而非普通JSON，核心原因如下：

JSONL格式完整示例

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

使用JSONL，让每个消息独立一行的核心价值在于：

实时持久化：每条消息生成后立即写入文件，无延迟；
崩溃恢复：已写入的消息不会因后续错误或崩溃丢失；
高效读写：追加写入无需读取历史数据，读写效率高。

（3）Session JSONL数据结构（完整消息类型与示例）

Session文件包含多种消息类型，每种类型承担特定职责：

用户消息完整示例如下

{
"type": "user",
"uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"parentUuid": null,
"sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
"timestamp": "2026-01-05T10:00:00.000Z",
"message": {
"role": "user",
"content": "分析一下这个项目的架构"
},
"cwd": "/Users/xxx/project",
"gitBranch": "main",
"version": "2.0.76"
}

助手消息完整示例（含工具调用与token使用）如下

{
"type": "assistant",
"uuid": "e684816e-f476-424d-92e3-1fe404f13212",
"parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"message": {
"role": "assistant",
"model": "claude-opus-4-5-20251101",
"content": [
{
"type": "thinking",
"thinking": "用户想了解项目架构，我需要先查看目录结构..."
},
{
"type": "text",
"text": "让我先看一下项目结构。"
},
{
"type": "tool_use",
"id": "toolu_01ABC",
"name": "Bash",
"input": {"command": "ls -la"}
}
],
"usage": {
"input_tokens": 1500,
"output_tokens": 200,
"cache_read_input_tokens": 50000
}
}
}

（4）消息链结构（完整链路示例）如下

消息通过 uuid（自身唯一标识）和 parentUuid（父消息标识）形成完整链式结构，支持全链路回溯：

file-history-snapshot (messageId: A)
↓
user (uuid: A, parentUuid: null)     ← 用户提问（链路起点）
↓
assistant (uuid: B, parentUuid: A)   ← AI思考 + 文本回复
↓
assistant (uuid: C, parentUuid: B)   ← AI工具调用（如Bash命令）
↓
user (uuid: D, parentUuid: C)        ← 工具执行结果（如Bash输出）
↓
assistant (uuid: E, parentUuid: D)   ← AI基于工具结果继续回复
↓
summary (leafUuid: E)                ← 会话摘要（关联链路终点）

06 file-history-snapshot：实现操作可撤销的核心机制

这是Claude Code保障代码修改可恢复的关键设计，核心逻辑是修改前备份原始内容，撤销时恢复，所有细节如下：

（1）核心定义：什么是Checkpoint，作用如何？

每当用户发送新消息时，Claude Code会自动创建 file-history-snapshot，专门记录「即将被修改的文件的原始内容」，作为撤销操作的数据源：

用户提问 → 创建snapshot（备份原始内容） → Claude修改文件 → 用户不满意 → Esc+Esc撤销
↑                                              ↓
存储原始内容  ←─────────────────────────────── 从snapshot恢复原始内容

（2）完整数据结构示例

{
"type": "file-history-snapshot",
"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"snapshot": {
"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"trackedFileBackups": {
"/path/to/file1.py": "
原始文件内容\ndef hello():\n    print('old')",
"/path/to/file2.js": "// 原始内容..."
},
"timestamp": "2026-01-05T10:00:00.000Z"
},
"isSnapshotUpdate": false
}

（3）关键步骤：备份修改前的内容

trackedFileBackups 存储的是文件修改前的原始内容，而非修改后的内容。这是撤销功能的核心建设思路：

┌──────────────────┐
│  修改前 app.py    │
│  print("old")    │───────→ 备份到 snapshot 的 trackedFileBackups
└──────────────────┘
↓
┌──────────────────┐
│  Claude 修改后    │
│  print("new")    │───────→ 写入磁盘（覆盖原文件）
└──────────────────┘
↓
┌──────────────────┐
│  用户执行撤销    │
│  按下 Esc + Esc  │───────→ 从 snapshot 恢复 "old" 内容到磁盘
└──────────────────┘

（4）完整工作流程

用户发送消息：触发创建空的 file-history-snapshot 记录；
Claude 准备修改文件：系统自动扫描即将修改的文件，将其原始内容备份到 trackedFileBackups；
执行修改操作：Claude 执行 Edit/Write 指令，将修改后的内容写入磁盘；
用户发起撤销：按下 Esc + Esc 快捷键，触发撤销流程；
恢复原始内容：系统从 trackedFileBackups 中读取备份的原始内容，覆盖当前文件，完成撤销。

（5）存储位置与保留策略

快照记录存储：与对应Session绑定，存储在 ~/.claude/projects/-path-to-project/{session-id}.jsonl 中；
文件内容备份：原始文件内容按哈希存储在 ~/.claude/file-history/{content-hash}/ 目录；
默认保留期：30天（与全局 cleanupPeriodDays 配置一致）；
配置方式：可通过 ~/.claude/settings.json 中的 cleanupPeriodDays 字段调整保留天数。

（6）相关命令

07 其他重要目录

（1）plugins/ - 插件管理

~/.claude/plugins/
├── config.json
插件全局配置（如启用/禁用规则）
├── installed_plugins.json
已安装插件列表（含版本、状态）
├── known_marketplaces.json
插件市场源配置（如Anthropic官方市场）
├── cache/
插件下载缓存（避免重复下载）
└── marketplaces/
市场源存储目录
└── anthropic-agent-skills/
官方插件市场
├── .claude-plugin/
│   └── marketplace.json
市场元信息
└── skills/
市场提供的Skills
├── pdf/
PDF处理相关Skill
├── docx/
Word文档处理相关Skill
└── frontend-design/
前端设计相关Skill

（2）skills/ - 分层存储

Skills 按使用范围做分层存储，适配不同场景的功能定制，层级关系如下：