企业官网建设流程全解析

Gajae-Code 会话管理实战：/tree 分支导航、会话恢复与存储安全完整指南

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code

Gajae-Code 是一个终端里的 AI 编程助手，它的会话管理是新手最容易忽略、却最影响日常效率的能力：用/tree分支导航在历史对话中"时光倒流"，用--continue/--resume快速恢复上次的工作现场，并用严格的存储安全边界保护你的会话数据。这篇实战指南带你从零理解这三件事，全部基于官方文档与源码整理，无需任何前置经验。

一、为什么会话是一棵"树"而不是一条"线"？

传统聊天工具的历史是一条直线，而 Gajae-Code 的会话底层是一棵树。它的存储模型非常简单，理解这一点后面全都会懂：

• 会话文件是追加式 JSONL（每行一个 JSON 对象），只追加、不重写；
• 每条记录都有id和parentId两个指针，天然构成树形结构；
• 运行时用一根leafId指针标记"当前对话停在哪"；
• 分支导航只是移动指针，绝不修改历史——你换条路走，原来的路还完好无损。

这就是为什么你可以大胆回退、反复尝试：树上新长出的分支不会"删掉"旧分支。完整的数据模型与迁移机制见官方文档 docs/session.md，架构设计详见 docs/session-tree-plan.md。

二、/tree 分支导航：一键回到任意历史节点

/tree打开的是交互式会话树选择器，让你跳到当前会话文件内的任意一条记录，并从那里继续对话。

如何打开会话树

命令路由逻辑在 packages/coding-agent/src/modes/controllers/input-controller.ts，树选择器的导航、过滤与搜索实现在 packages/coding-agent/src/modes/components/tree-selector.ts。

树选择器怎么用：方向键、搜索与过滤

打开后是纯键盘操作，上手成本极低：

• ↑/↓移动，Enter选中，Esc关闭；
• 直接敲字即搜索（空格分词、不区分大小写、全部命中才保留）；
• Ctrl+O循环切换 5 种过滤模式，Alt+D/T/U/L/A直达指定模式：

选中不同节点，会发生什么？

这是新手最容易迷惑的地方，规则其实很直观：

• 选中一条用户消息：指针回到该消息的上一节点，且消息原文自动填入输入框——你可以改一改再重发，等于"重写历史"；
• 选中助手/工具等节点：指针直接停在该节点，从它继续；
• 选中当前位置：什么都不做，直接关闭。

两个进阶技巧 🌳

1. 给关键节点打标签：在树里用Shift+L给某条记录命名（如milestone），之后按Alt+L只显示打标签的节点，实现"书签式"快速跳转。标签是追加式存储，清空即删除。
2. 离开分支时留一张"小抄"：开启branchSummary.enabled后，切换前可选Summarize，系统会把被放弃路径的对话压缩成一条branch_summary挂在新位置——旧路没白走，精华被保留。

一个标准工作流：/tree→ 选中早期某条用户消息 → 选No summary→ 修改预填文本 → 重新发送。新分支就在同一会话文件里长出来，当前分支一点不丢。完整参考见 docs/tree.md。

三、会话恢复实战：--continue、--resume 与 /resume 怎么选

三个入口，覆盖三种场景：

1.--continue：接着刚才的聊

启动时执行gjc --continue，解析顺序很贴心：

1. 先读终端面包屑（每个终端窗口记住自己上次在聊哪个会话）；
2. 面包屑失效时，回退到该目录下最近修改的会话；
3. 一个都没有就新建会话。

2.--resume：精确恢复指定会话

• 不带值：弹出交互式会话选择器（列表按修改时间倒序，⭐ 收藏的排在最前，支持模糊搜索、Ctrl+S星标）；
• 带 ID 前缀或路径：直接定位；如果匹配到的是其他项目的会话，会询问是否 fork 到当前项目，绝不悄悄混用。

3./resume：会话中途切换

正在对话时输入/resume，打开选择器换到另一个会话文件。切换过程会先中止进行中的生成、冲刷未落盘写入，再重建消息、模型与思考级别，并发出session_before_switch/session_switch钩子事件供扩展拦截。

选择器实现见 packages/coding-agent/src/cli/session-picker.ts，运行时切换逻辑在 packages/coding-agent/src/session/agent-session.ts。恢复机制全细节参考 docs/session-switching-and-recent-listing.md。

四、会话存储安全边界：数据在哪，谁能碰

理解存储位置与保护机制，才能放心把长期项目交给它管理。

存储布局

• 会话文件：~/.gjc/agent/sessions/v2-<项目标识摘要>/<时间戳>_<会话ID>.jsonl——目录名由工作区的规范身份摘要派生，同一项目的不同路径写法（如符号链接别名）会归到同一作用域；
• 大对象外置：会话里超过 1KB 的 base64 图片会被移出正文，以blob:sha256:<hash>引用，实体存入~/.gjc/agent/blobs/，正文超限还会截断并留痕；
• 终端面包屑：~/.gjc/agent/terminal-sessions/下每终端一个指针文件，支撑--continue。

上图为项目内置的会话统计产出，可以看到长期会话中read/search类工具消耗了绝大多数 token——正因如此，截断与 blob 外置这类数据规模控制对存储可靠性很关键。

安全边界到底保护什么 🔒

官方文档把边界讲得非常诚实：

• 受管目录与文件强制owner-only 权限（目录 0700 / 文件 0600），拒绝符号链接、拒绝畸形绑定，校验失败一律失败关闭（fail closed）而不是猜测；
• 目录迁移采用copy-retain默认策略：旧布局会话被复制进 v2 作用域并保留原件，冲突、身份变化、不安全文件树时直接放弃迁移；
• 明确声明：这是一道本地存储完整性边界，不是认证、授权或加密，也防不住恶意并发的本地攻击者——会话目录本身仍需由你自行保护。

--session-dir是显式覆盖项，属于操作者主动选择。完整安全说明见 docs/session.md 的 Security boundary 章节，存储抽象实现在 packages/coding-agent/src/session/session-storage.ts 与 packages/coding-agent/src/session/blob-store.ts。

五、一张表分清 /tree 与 /fork

两者都"从历史分叉"，但边界完全不同：

/fork不会修改工作区文件，也不会创建 Git 分支或 worktree，源会话保持原样。操作矩阵与事件钩子全览见 docs/session-operations-export-share-fork-resume.md。

六、上手与关键模块索引

想动手体验，先获取代码仓库：

git clone https://gitcode.com/gh_mirrors/ga/gajae-code

按 docs/install.md 完成安装后，建议练习顺序：--continue恢复昨天会话 →/tree回退重发一条早期提示 →Shift+L给当前节点打标签 →/fork从某条提示派生独立分支。

掌握/tree的指针语义、三种恢复方式和存储安全边界，你就能把 Gajae-Code 当作一个"可回退、可分叉、可长期保存"的协作伙伴，而不只是一个一次性聊天窗口。

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code