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

​
数据根目录

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

​
目录结构

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

​
关键文件

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

​
会话数据

会话位于 agent/sessions/<编码后的工作目录>/，每个会话使用一个 JSONL 文件，包含消息、工具调用、输出以及上下文摘要。使用 /session 查看当前文件的准确路径。 会话目录覆盖顺序为 --session-dir > config.toml 的 sessionDir。每条记录包含 id / parentId，当前位置为活跃叶子；压缩摘要、分支摘要、工具调用和输出都保存在同一文件中。空输入框 ↑ / ↓ 浏览当前会话的提交记录。 会话树和输入历史的使用见会话与上下文。不要直接编辑会话内部记录。

​
内置工具缓存

rg（ripgrep）和 fd 按需下载到 ~/.stepcode/agent/bin/，Windows 对应 rg.exe / fd.exe。查找顺序为注入的自定义路径 > 已下载的本地副本 > 系统 PATH。 内容搜索的回退顺序为 ripgrep > git grep（搜索路径位于 Git 仓库时）> POSIX grep，全部不可用时报错。 删除该缓存后，下次使用可能重新下载。受限网络环境中请先检查系统 PATH 和下载访问权限。

​
日志

  • logs/：运行日志，排查启动、连接或工具错误时优先查看。
  • telemetry/：遥测缓冲，与会话记录分开保存。
日志可能含错误详情和环境信息。分享前请审查，不能将日志默认视为不含敏感内容。 本地存储不限制数据外发：模型调用、MCP、插件和部署会按操作需要访问外部服务。

​
项目级数据

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

​
清理数据

清理前退出 Step Code，并备份仍需使用的配置和会话。 删除项目 .stepcode/ 也会删除其中的配置、任务和自定义资源，不应将其当作纯缓存处理。

​
下一步