> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据路径

了解配置、凭据、会话和项目资源的存放位置，以便备份、迁移和排查问题。

## 数据根目录

| 系统      | 默认目录                       |
| ------- | -------------------------- |
| macOS   | `/Users/<用户名>/.stepcode`   |
| Linux   | `/home/<用户名>/.stepcode`    |
| Windows | `C:\Users\<用户名>\.stepcode` |

本文中的 `~` 表示用户主目录，Agent 配置子目录为 `~/.stepcode/agent`。`.step-harness` 已退役，不再写入；启动时仅读取旧凭据做一次性迁移。

## 目录结构

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
~/.stepcode/
├── config.toml
├── auth.json
├── models.json
├── .credentials.json
├── device-id
├── models-store.json
├── bin/
├── logs/
├── marketplaces/
├── telemetry/
└── agent/
    ├── AGENTS.md
    ├── prompts/
    ├── skills/
    ├── agents/
    ├── themes/
    ├── extensions/
    ├── sessions/
    ├── trust.json
    ├── bin/
    ├── npm/
    └── git/
```

部分目录在首次使用对应功能时才创建。`bin/` 保存主程序和运行资源，`agent/bin/` 保存托管的搜索工具。

## 关键文件

| 文件                  | 内容                                              |
| ------------------- | ----------------------------------------------- |
| `config.toml`       | 全局设置和 MCP 服务器声明                                 |
| `auth.json`         | API Key 与 OAuth 凭据；密钥值支持 `!command` 与 `$VAR` 取值 |
| `models.json`       | 自定义模型和覆盖设置，打开 `/model` 时热重载                     |
| `.credentials.json` | MCP OAuth 令牌，键由服务器名称加竖线组成，原子写入                  |
| `models-store.json` | 模型目录缓存                                          |
| `agent/trust.json`  | 项目信任记录                                          |

凭据文件应限制为当前用户可读写。POSIX 环境使用 `0600` 权限；Windows 应检查对应账户的文件访问权限。不要将整个数据目录提交到 Git 或上传到公共网盘。

## 会话数据

会话位于 `agent/sessions/<编码后的工作目录>/`，每个会话使用一个 JSONL 文件，包含消息、工具调用、输出以及上下文摘要。使用 `/session` 查看当前文件的准确路径。

会话目录覆盖顺序为 `--session-dir` > `config.toml` 的 `sessionDir`。每条记录包含 `id` / `parentId`，当前位置为活跃叶子；压缩摘要、分支摘要、工具调用和输出都保存在同一文件中。空输入框 ↑ / ↓ 浏览当前会话的提交记录。

会话树和输入历史的使用见[会话与上下文](/docs/zh/step-code/guides/sessions)。不要直接编辑会话内部记录。

## 内置工具缓存

`rg`（ripgrep）和 `fd` 按需下载到 `~/.stepcode/agent/bin/`，Windows 对应 `rg.exe` / `fd.exe`。查找顺序为注入的自定义路径 > 已下载的本地副本 > 系统 PATH。

内容搜索的回退顺序为 ripgrep > `git grep`（搜索路径位于 Git 仓库时）> POSIX `grep`，全部不可用时报错。

删除该缓存后，下次使用可能重新下载。受限网络环境中请先检查系统 PATH 和下载访问权限。

## 日志

* `logs/`：运行日志，排查启动、连接或工具错误时优先查看。
* `telemetry/`：遥测缓冲，与会话记录分开保存。

日志可能含错误详情和环境信息。分享前请审查，不能将日志默认视为不含敏感内容。

本地存储不限制数据外发：模型调用、MCP、插件和部署会按操作需要访问外部服务。

## 项目级数据

| 位置                                                 | 内容            |
| -------------------------------------------------- | ------------- |
| `.stepcode/config.toml`                            | 项目配置，需要项目信任   |
| `.stepcode/cron/tasks.json`                        | 持久定时任务        |
| `.stepcode/workflows/runs/`                        | workflow 运行记录 |
| `.stepcode/agents/`、`skills/`、`themes/`、`plugins/` | 项目自定义资源       |
| `.stepcode/plans/`                                 | Plan 模式会话文件   |
| `.stepcode/npm/`                                   | 项目范围安装的 npm 包 |

可共享的配置和资源可按团队约定纳入版本管理；运行记录、缓存、私有路径和凭据应排除。不要直接将整个 `.stepcode/` 目录加入 Git。

## 清理数据

清理前退出 Step Code，并备份仍需使用的配置和会话。

| 需求        | 操作                                    |
| --------- | ------------------------------------- |
| 重置配置      | 备份后移除 `config.toml`                   |
| 清理会话      | 删除不再需要的 `agent/sessions/` 内容          |
| 清理日志      | 删除旧的 `logs/` 文件                       |
| 重新下载搜索工具  | 移除 `agent/bin/` 中对应工具                 |
| 退出模型登录    | 使用 `/logout`                          |
| 清除 MCP 授权 | `step mcp logout <名称>`                |
| 清理遥测缓冲    | 删除 `telemetry/`；这不会自动关闭遥测设置           |
| 刷新模型缓存    | 备份后移除 `models-store.json`             |
| 彻底清理      | 备份后删除 Step Code 专用的数据目录，并清理安装器 PATH 项 |

删除项目 `.stepcode/` 也会删除其中的配置、任务和自定义资源，不应将其当作纯缓存处理。

## 下一步

* [配置文件](/docs/zh/step-code/configuration/files)
* [会话与上下文](/docs/zh/step-code/guides/sessions)
* [环境变量](/docs/zh/step-code/configuration/environment)