Prime Agent 会话机制全解JSONL 树状存储、/tree 分支导航与 /fork、/clone 工作流【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent本文基于 Prime Agent 官方文档 sessions.md 及其配套源码系统讲解其会话Session体系从~/.prime/agent/sessions/下的 JSONL 树状存储、--continue/--resume/--fork启动参数到交互模式下的/tree原地分支、/fork与/clone派生新文件以及分支摘要branch summary机制。读完后你将能熟练恢复、命名、分叉长期会话并基于源码理解其底层SessionManagerAPI 与文件结构。会话存储与 CLI 入口Prime Agent 将每段对话自动保存为会话文件目的是支持继续之前的工作、从更早的轮次分叉以及回顾此前尝试过的路径。会话文件统一存放在~/.prime/agent/sessions/目录下每个会话是一个 JSONLJSON Lines文件内部按树结构组织条目。存储目录由 config.ts 中的getSessionsDir()决定从源码看它是agentDir下的sessions子目录// packages/coding-agent/src/config.ts export function getSessionsDir(agentDir: string getAgentDir()): string { ... return join(agentDir, sessions); }启动参数决定了会话的生命周期行为prime-agent --continue # 继续最近一次会话可简写 -c prime-agent --resume [path|id] # 浏览历史会话或直接恢复指定会话可简写 -r prime-agent --no-session # 临时模式不落盘保存 prime-agent --fork path|id # 把会话文件或部分会话 ID 派生fork为新会话这些参数在 args.ts 中解析支持--resumepath|id的等号写法帮助文案定义在 command-registry.ts 中。需要注意一个适用限制从 daemon-command.ts 的源码看daemon 托管的会话始终会被持久化--no-session仅适用于普通非 daemon启动模式传给 daemon 会话时会直接报错。进入交互模式后两个最常用的诊断命令/session显示当前会话文件路径、会话 ID 和消息数/usage显示 token 用量、费用与上下文占用。完整的 JSONL 文件格式与SessionManagerAPI 见 Session Format 文档。会话命令一览命令说明/resume浏览并选择历史会话/new开启新会话/name name设置当前会话的显示名/session显示会话信息文件、ID、消息数/usage显示 token、费用与上下文用量/tree在当前会话树中导航/fork从某条更早的用户消息创建新会话/clone把当前活动分支复制为新会话/compact [prompt]摘要旧上下文详见 Compaction/export [file]将会话导出为 HTML/share上传为私有 GitHub gist生成可分享的 HTML 链接恢复与删除会话/resume会为当前项目打开一个交互式会话选择器prime-agent --resume在启动时打开同一个选择器而prime-agent --resume path|id则直接恢复指定会话。两个实用细节ID 容错输入无效 ID 时如果存在足够接近的候选Prime Agent 会给出最近的无歧义会话 ID 作为提示。实现位于 session-resolver.tsfindClosestSessionId()用编辑距离Levenshtein比较规范化后的 ID 前后缀并要求距离不超过 ID 长度的 1/5 且唯一最优才给出建议歧义匹配会抛出SessionSelectorAmbiguousError列出所有候选。选择器解析顺序resolveSessionPath()先按路径特征包含/、\或以.jsonl结尾识别路径然后依次在本项目会话中精确匹配 ID、在全局会话中精确匹配、在本项目部分前缀匹配、最后全局部分匹配全部失败才报SessionSelectorNotFoundError。选择后带初始提示先用--分隔选择会话后即可直接发送提示词prime-agent --resume -- continue this work会话选择器中的快捷键直接输入文本搜索CtrlP 切换路径显示CtrlS 切换排序模式CtrlN 过滤出已命名的会话CtrlR 重命名CtrlD 删除并二次确认。删除的安全保障当系统安装了trashCLI 时Prime Agent 优先通过它删除会话文件而不是永久删除。从 session-file-actions.ts 看删除逻辑是先尝试trash失败再回退到unlink返回值中会标明实际使用的方法trash或unlinkagents-view-mode.ts 据此显示Session moved to trash或Session deleted。此外你也可以直接删除~/.prime/agent/sessions/下对应的.jsonl文件来移除会话。命名会话使用/name name为当前会话设置人类可读的名称/name Refactor auth module命名后的会话在/resume与prime-agent --resume的选择器中更容易被找到。底层实现是追加一条session_info类型的树条目见下文会话文件结构选择器显示会话名而不是首条消息扩展也可以通过pi.setSessionName()以编程方式设置。用 /tree 分支会话以树存储每个条目都有id和parentId当前所在位置即活动叶子active leaf。/tree让你跳到树中任意历史位置并从那里继续而无需创建新文件。典型形态示例├─ user: Hello, can you help... │ └─ assistant: Of course! I can... │ ├─ user: Lets try approach A... │ │ └─ assistant: For approach A... │ │ └─ user: That worked... ← active │ └─ user: Actually, approach B... │ └─ assistant: For approach B...树控制键位键动作↑/↓在可见条目间导航←/→翻页上/下Ctrl←/Ctrl→ 或 Alt←/Alt→折叠/展开或在分支段之间跳转ShiftL为选中条目设置或清除标签labelShiftT切换标签时间戳显示Enter选中条目Escape/CtrlC取消CtrlO循环切换过滤模式过滤模式共有五种default、no-tools、user-only、labeled-only、all。默认过滤模式通过 Settings 中的treeFilterMode配置。从源码看settings-manager.ts 将其声明为default | no-tools | user-only | labeled-only | all默认user-only而 tree-selector.ts 实现了 CtrlO 的前向循环default → no-tools → user-only → labeled-only → all → default以及 labeled-only 与 default 的快速互切。选中行为选中用户消息或自定义消息时把叶子移动到该消息的父节点将该消息文本放入编辑器你可以编辑后重新提交从而创建一个新的分支。选中assistant、工具、compaction 或其他非用户条目时把叶子移动到该条目编辑器保持为空你可以从该点继续对话。选中根用户消息会把叶子重置为空会话并把原始提示词放入编辑器相当于从头再来一次。/tree、/fork 与 /clone 的取舍三者都能从历史位置继续但产物与视角不同功能/tree/fork/clone产物同一个会话文件新会话文件新会话文件视图完整树用户消息选择器当前活动分支典型用途原地探索多种替代方案从更早的提示词开启新会话在继续之前先复制一份当前工作分支摘要可选切换分支时可生成摘要无无想保留多种替代方案就使用/tree想要独立的会话文件就用/fork或/clone。源码侧的对应关系/fork//clone派生的新会话文件其头部的parentSession字段会记录来源会话路径SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)还支持从其他项目 fork见 session-manager.ts 第 2349 行附近的静态方法。createBranchedSession(leafId)实例方法负责把当前分支抽取为独立的新会话文件供 fork/clone 使用。分支摘要Branch Summaries当你在/tree中从一个分支切换到另一个分支时Prime Agent 可以为你离开的分支生成一段摘要并把它附着在新位置。这样既保留了被放弃路径上的重要上下文又避免了整条分支的完整重放。选择提示出现时三选一不生成摘要no summary使用默认提示词生成摘要用自定义的关注点说明生成摘要。对应地SessionManager.branchWithSummary(entryId, summary, ...)会追加一条branch_summary类型的树条目记录fromId分支来源条目与摘要文本。摘要生成内部机制与扩展钩子参见 Compaction。会话文件结构JSONL 树与条目类型会话文件每行一个 JSON 对象除首行头header外所有条目都继承统一的树骨架interface SessionEntryBase { type: string; id: string; // 8 位十六进制 ID parentId: string | null; // 父条目 ID首个条目为 null timestamp: string; // ISO 时间戳 }首行是会话头记录版本、会话 UUID、工作目录cwd由/fork、/clone或newSession({ parentSession })创建的会话还会带parentSession字段{type:session,version:3,id:uuid,timestamp:2024-12-03T14:00:00.000Z,cwd:/path/to/project} {type:session,version:3,id:uuid,timestamp:2024-12-03T14:00:00.000Z,cwd:/path/to/project,parentSession:/path/to/original/session.jsonl}版本演进v1 为线性条目序列加载时自动迁移v2 引入id/parentId树结构v3 将hookMessage角色更名为custom扩展体系统一。当前版本常量CURRENT_SESSION_VERSION 3定义在 session-manager.ts旧版本会话加载时自动迁移到 v3。会话文件包含的条目类型与 session-manager.ts 中导出的接口一一对应包括条目类型说明message对话消息message字段为AgentMessageuser / assistant / toolResult / bashExecution / custom 等model_change会话中切换模型时记录thinking_level_change切换思考/推理等级时记录service_tier_change切换服务商服务等级时记录compaction上下文压缩摘要 firstKeptEntryIdtokensBeforebranch_summary/tree切换分支时生成的被放弃分支摘要label用户书签targetId指向被标记条目label置空即清除session_info会话元数据如/name设置的显示名custom/custom_message扩展状态不进 LLM 上下文/ 扩展注入消息进上下文child_usage_attributedRLM 子代理用量归并到父消息的记账条目不进入模型上下文session_state/agent_status/git_statedaemon 生命周期状态、agents 视图状态摘要、仓库状态快照均为记账条目上下文构建规则buildSessionContext()session-manager.ts 第 2097 行附近从当前叶子向根回溯产出送给 LLM 的消息列表收集路径上的所有条目提取当前模型与思考等级设置若路径上存在CompactionEntry先输出摘要再输出firstKeptEntryId到压缩点之间的消息然后是压缩点之后的消息把BranchSummaryEntry与CustomMessageEntry转换为对应消息格式记账类条目用量归并、会话状态、agent 状态、git 状态等在构建上下文时被忽略。最小解析示例import { readFileSync } from fs; const lines readFileSync(session.jsonl, utf8).trim().split(\n); for (const line of lines) { const entry JSON.parse(line); switch (entry.type) { case session: console.log(Session v${entry.version ?? 1}: ${entry.id}); break; case message: console.log([${entry.id}] ${entry.message.role}); break; case compaction: console.log([${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized); break; case branch_summary: console.log([${entry.id}] Branch from ${entry.fromId}); break; case label: console.log([${entry.id}] Label ${entry.label} on ${entry.targetId}); break; } }SessionManager API 速览编程式操作会话时核心方法分组如下完整签名见 Session Format静态创建create(cwd, sessionDir?)、open(path, sessionDir?)、continueRecent(cwd, sessionDir?)、inMemory(cwd?)不持久化对应--no-session的场景、forkFrom(sourcePath, targetCwd, sessionDir?)静态列举list(cwd, sessionDir?, callbacks?)列举某项目会话listAll(callbacks?, sessionDir?)跨项目列举实例管理newSession({ parentSession? })、setSessionFile(path)、createBranchedSession(leafId)树导航getLeafId()、getBranch(fromId?)、getTree()、branch(entryId)把叶子移到更早条目、resetLeaf()、branchWithSummary(entryId, summary, ...)追加均返回条目 IDappendMessage、appendModelChange、appendCompaction、appendLabelChange、appendSessionInfo、appendCustomEntry等上下文与信息buildSessionContext()、getEntries()、getHeader()、getSessionName()、getCwd()、isPersisted()等。该 API 的行为有大量测试覆盖可参考 session-manager 测试目录 与 compaction.test.ts、interactive-mode-resume-command.test.ts 等用例。小结Prime Agent 的会话机制由三层组成磁盘上扁平存放的 JSONL 树文件~/.prime/agent/sessions/、基于id/parentId的原地分支导航/tree 分支摘要以及派生独立文件的能力/fork、/clone、SessionManager.forkFrom。理解活动叶子和buildSessionContext()的回溯规则后你就能在长任务中自由回退、对比多条路线并通过trashCLI 安全地管理会话生命周期。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prime Agent 会话机制全解：JSONL 树状存储、/tree 分支导航与 /fork、/clone 工作流
Prime Agent 会话机制全解JSONL 树状存储、/tree 分支导航与 /fork、/clone 工作流【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent本文基于 Prime Agent 官方文档 sessions.md 及其配套源码系统讲解其会话Session体系从~/.prime/agent/sessions/下的 JSONL 树状存储、--continue/--resume/--fork启动参数到交互模式下的/tree原地分支、/fork与/clone派生新文件以及分支摘要branch summary机制。读完后你将能熟练恢复、命名、分叉长期会话并基于源码理解其底层SessionManagerAPI 与文件结构。会话存储与 CLI 入口Prime Agent 将每段对话自动保存为会话文件目的是支持继续之前的工作、从更早的轮次分叉以及回顾此前尝试过的路径。会话文件统一存放在~/.prime/agent/sessions/目录下每个会话是一个 JSONLJSON Lines文件内部按树结构组织条目。存储目录由 config.ts 中的getSessionsDir()决定从源码看它是agentDir下的sessions子目录// packages/coding-agent/src/config.ts export function getSessionsDir(agentDir: string getAgentDir()): string { ... return join(agentDir, sessions); }启动参数决定了会话的生命周期行为prime-agent --continue # 继续最近一次会话可简写 -c prime-agent --resume [path|id] # 浏览历史会话或直接恢复指定会话可简写 -r prime-agent --no-session # 临时模式不落盘保存 prime-agent --fork path|id # 把会话文件或部分会话 ID 派生fork为新会话这些参数在 args.ts 中解析支持--resumepath|id的等号写法帮助文案定义在 command-registry.ts 中。需要注意一个适用限制从 daemon-command.ts 的源码看daemon 托管的会话始终会被持久化--no-session仅适用于普通非 daemon启动模式传给 daemon 会话时会直接报错。进入交互模式后两个最常用的诊断命令/session显示当前会话文件路径、会话 ID 和消息数/usage显示 token 用量、费用与上下文占用。完整的 JSONL 文件格式与SessionManagerAPI 见 Session Format 文档。会话命令一览命令说明/resume浏览并选择历史会话/new开启新会话/name name设置当前会话的显示名/session显示会话信息文件、ID、消息数/usage显示 token、费用与上下文用量/tree在当前会话树中导航/fork从某条更早的用户消息创建新会话/clone把当前活动分支复制为新会话/compact [prompt]摘要旧上下文详见 Compaction/export [file]将会话导出为 HTML/share上传为私有 GitHub gist生成可分享的 HTML 链接恢复与删除会话/resume会为当前项目打开一个交互式会话选择器prime-agent --resume在启动时打开同一个选择器而prime-agent --resume path|id则直接恢复指定会话。两个实用细节ID 容错输入无效 ID 时如果存在足够接近的候选Prime Agent 会给出最近的无歧义会话 ID 作为提示。实现位于 session-resolver.tsfindClosestSessionId()用编辑距离Levenshtein比较规范化后的 ID 前后缀并要求距离不超过 ID 长度的 1/5 且唯一最优才给出建议歧义匹配会抛出SessionSelectorAmbiguousError列出所有候选。选择器解析顺序resolveSessionPath()先按路径特征包含/、\或以.jsonl结尾识别路径然后依次在本项目会话中精确匹配 ID、在全局会话中精确匹配、在本项目部分前缀匹配、最后全局部分匹配全部失败才报SessionSelectorNotFoundError。选择后带初始提示先用--分隔选择会话后即可直接发送提示词prime-agent --resume -- continue this work会话选择器中的快捷键直接输入文本搜索CtrlP 切换路径显示CtrlS 切换排序模式CtrlN 过滤出已命名的会话CtrlR 重命名CtrlD 删除并二次确认。删除的安全保障当系统安装了trashCLI 时Prime Agent 优先通过它删除会话文件而不是永久删除。从 session-file-actions.ts 看删除逻辑是先尝试trash失败再回退到unlink返回值中会标明实际使用的方法trash或unlinkagents-view-mode.ts 据此显示Session moved to trash或Session deleted。此外你也可以直接删除~/.prime/agent/sessions/下对应的.jsonl文件来移除会话。命名会话使用/name name为当前会话设置人类可读的名称/name Refactor auth module命名后的会话在/resume与prime-agent --resume的选择器中更容易被找到。底层实现是追加一条session_info类型的树条目见下文会话文件结构选择器显示会话名而不是首条消息扩展也可以通过pi.setSessionName()以编程方式设置。用 /tree 分支会话以树存储每个条目都有id和parentId当前所在位置即活动叶子active leaf。/tree让你跳到树中任意历史位置并从那里继续而无需创建新文件。典型形态示例├─ user: Hello, can you help... │ └─ assistant: Of course! I can... │ ├─ user: Lets try approach A... │ │ └─ assistant: For approach A... │ │ └─ user: That worked... ← active │ └─ user: Actually, approach B... │ └─ assistant: For approach B...树控制键位键动作↑/↓在可见条目间导航←/→翻页上/下Ctrl←/Ctrl→ 或 Alt←/Alt→折叠/展开或在分支段之间跳转ShiftL为选中条目设置或清除标签labelShiftT切换标签时间戳显示Enter选中条目Escape/CtrlC取消CtrlO循环切换过滤模式过滤模式共有五种default、no-tools、user-only、labeled-only、all。默认过滤模式通过 Settings 中的treeFilterMode配置。从源码看settings-manager.ts 将其声明为default | no-tools | user-only | labeled-only | all默认user-only而 tree-selector.ts 实现了 CtrlO 的前向循环default → no-tools → user-only → labeled-only → all → default以及 labeled-only 与 default 的快速互切。选中行为选中用户消息或自定义消息时把叶子移动到该消息的父节点将该消息文本放入编辑器你可以编辑后重新提交从而创建一个新的分支。选中assistant、工具、compaction 或其他非用户条目时把叶子移动到该条目编辑器保持为空你可以从该点继续对话。选中根用户消息会把叶子重置为空会话并把原始提示词放入编辑器相当于从头再来一次。/tree、/fork 与 /clone 的取舍三者都能从历史位置继续但产物与视角不同功能/tree/fork/clone产物同一个会话文件新会话文件新会话文件视图完整树用户消息选择器当前活动分支典型用途原地探索多种替代方案从更早的提示词开启新会话在继续之前先复制一份当前工作分支摘要可选切换分支时可生成摘要无无想保留多种替代方案就使用/tree想要独立的会话文件就用/fork或/clone。源码侧的对应关系/fork//clone派生的新会话文件其头部的parentSession字段会记录来源会话路径SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)还支持从其他项目 fork见 session-manager.ts 第 2349 行附近的静态方法。createBranchedSession(leafId)实例方法负责把当前分支抽取为独立的新会话文件供 fork/clone 使用。分支摘要Branch Summaries当你在/tree中从一个分支切换到另一个分支时Prime Agent 可以为你离开的分支生成一段摘要并把它附着在新位置。这样既保留了被放弃路径上的重要上下文又避免了整条分支的完整重放。选择提示出现时三选一不生成摘要no summary使用默认提示词生成摘要用自定义的关注点说明生成摘要。对应地SessionManager.branchWithSummary(entryId, summary, ...)会追加一条branch_summary类型的树条目记录fromId分支来源条目与摘要文本。摘要生成内部机制与扩展钩子参见 Compaction。会话文件结构JSONL 树与条目类型会话文件每行一个 JSON 对象除首行头header外所有条目都继承统一的树骨架interface SessionEntryBase { type: string; id: string; // 8 位十六进制 ID parentId: string | null; // 父条目 ID首个条目为 null timestamp: string; // ISO 时间戳 }首行是会话头记录版本、会话 UUID、工作目录cwd由/fork、/clone或newSession({ parentSession })创建的会话还会带parentSession字段{type:session,version:3,id:uuid,timestamp:2024-12-03T14:00:00.000Z,cwd:/path/to/project} {type:session,version:3,id:uuid,timestamp:2024-12-03T14:00:00.000Z,cwd:/path/to/project,parentSession:/path/to/original/session.jsonl}版本演进v1 为线性条目序列加载时自动迁移v2 引入id/parentId树结构v3 将hookMessage角色更名为custom扩展体系统一。当前版本常量CURRENT_SESSION_VERSION 3定义在 session-manager.ts旧版本会话加载时自动迁移到 v3。会话文件包含的条目类型与 session-manager.ts 中导出的接口一一对应包括条目类型说明message对话消息message字段为AgentMessageuser / assistant / toolResult / bashExecution / custom 等model_change会话中切换模型时记录thinking_level_change切换思考/推理等级时记录service_tier_change切换服务商服务等级时记录compaction上下文压缩摘要 firstKeptEntryIdtokensBeforebranch_summary/tree切换分支时生成的被放弃分支摘要label用户书签targetId指向被标记条目label置空即清除session_info会话元数据如/name设置的显示名custom/custom_message扩展状态不进 LLM 上下文/ 扩展注入消息进上下文child_usage_attributedRLM 子代理用量归并到父消息的记账条目不进入模型上下文session_state/agent_status/git_statedaemon 生命周期状态、agents 视图状态摘要、仓库状态快照均为记账条目上下文构建规则buildSessionContext()session-manager.ts 第 2097 行附近从当前叶子向根回溯产出送给 LLM 的消息列表收集路径上的所有条目提取当前模型与思考等级设置若路径上存在CompactionEntry先输出摘要再输出firstKeptEntryId到压缩点之间的消息然后是压缩点之后的消息把BranchSummaryEntry与CustomMessageEntry转换为对应消息格式记账类条目用量归并、会话状态、agent 状态、git 状态等在构建上下文时被忽略。最小解析示例import { readFileSync } from fs; const lines readFileSync(session.jsonl, utf8).trim().split(\n); for (const line of lines) { const entry JSON.parse(line); switch (entry.type) { case session: console.log(Session v${entry.version ?? 1}: ${entry.id}); break; case message: console.log([${entry.id}] ${entry.message.role}); break; case compaction: console.log([${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized); break; case branch_summary: console.log([${entry.id}] Branch from ${entry.fromId}); break; case label: console.log([${entry.id}] Label ${entry.label} on ${entry.targetId}); break; } }SessionManager API 速览编程式操作会话时核心方法分组如下完整签名见 Session Format静态创建create(cwd, sessionDir?)、open(path, sessionDir?)、continueRecent(cwd, sessionDir?)、inMemory(cwd?)不持久化对应--no-session的场景、forkFrom(sourcePath, targetCwd, sessionDir?)静态列举list(cwd, sessionDir?, callbacks?)列举某项目会话listAll(callbacks?, sessionDir?)跨项目列举实例管理newSession({ parentSession? })、setSessionFile(path)、createBranchedSession(leafId)树导航getLeafId()、getBranch(fromId?)、getTree()、branch(entryId)把叶子移到更早条目、resetLeaf()、branchWithSummary(entryId, summary, ...)追加均返回条目 IDappendMessage、appendModelChange、appendCompaction、appendLabelChange、appendSessionInfo、appendCustomEntry等上下文与信息buildSessionContext()、getEntries()、getHeader()、getSessionName()、getCwd()、isPersisted()等。该 API 的行为有大量测试覆盖可参考 session-manager 测试目录 与 compaction.test.ts、interactive-mode-resume-command.test.ts 等用例。小结Prime Agent 的会话机制由三层组成磁盘上扁平存放的 JSONL 树文件~/.prime/agent/sessions/、基于id/parentId的原地分支导航/tree 分支摘要以及派生独立文件的能力/fork、/clone、SessionManager.forkFrom。理解活动叶子和buildSessionContext()的回溯规则后你就能在长任务中自由回退、对比多条路线并通过trashCLI 安全地管理会话生命周期。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
