镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/trajectories.md ↗

轨迹文件

Agent 工作的大块正文(模型请求与响应、工具调用与结果、大日志)不再写进 SQLite 的行里,而是按运行追加到 JSONL 轨迹文件。SQLite 只保留状态、计费、每个文件一条入口,以及已有行上指向单条记录的定位串。设计与取舍见 issue #436。

文件

文件在数据库同目录的 trajectories/ 下,随 bot-data 卷一起备份;目录 0700、文件 0600,只有服务用户可读。

文件不加密。写入前照旧脱敏:工具请求和结果经任务的 Redactor,模型请求和响应同样;会话原先用 SecretBox 加密的操作和模型快照,新记录也以明文写进文件。

凭据命中与日志字段过滤分别处理:私钥、已知令牌前缀、JWT、带密码的 URL、明确的密码字段和形似令牌的 Bearer/Basic 或 token 赋值仍会脱敏。普通的 “bearer token”“basic validation”、函数表达式、纯数字配置与格式化 JSON 不因字面关键词被拒绝或改写。管理输入、命令和记忆只根据实际凭据命中拒绝;日志仍可移除私密推理等内部字段,字段过滤和 JSON 格式变化不作为输入敏感的依据。

每行是一个 JSON 对象:

{"seq":1,"at":"2026-11-12T08:00:00.000Z","type":"tool_result","id":"<记录 id>","prev":null,"data":{}}

blob

大块、会被复用的值按内容存一次:blobs/sha256/<前两位>/<sha256>(与 trajectories/ 同在数据库目录,0600),写入时先 fdatasync 再原子改名,读取时核对哈希。目前用于任务输入 tasks.input 里的 files(PR 改动文件及补丁)、snapshot_files、skipped_files(仓库文件清单):JSON 超过 2 KiB 时在库里换成 {"$blob":"<sha256>","bytes":n}。读这三个键的代码经 blobValue 取回原值;其他键和整体拷贝输入再写回的代码不受影响。trajectory_blobs 记录每个项目存过的 blob,同一内容多个项目共用一个文件,最后一个项目删除时文件才删除。

SQLite 里的记录

trajectory_files 每个文件一行:打开文件(写第一行)时插入一次,关闭时更新一次,写入行数、字节数、最后一行哈希和按类型的行数与字节。追加行不写数据库。关闭时同一提交把这些数加到 trajectory_usage(按项目、按类型的累计),存储页读这张表。

需要单独查找的记录在已有行上存定位串 <文件 id>:<偏移>:<长度>:<该行 sha256>,写在本来就要做的那次插入或更新里:

表 定位串列 原正文列现在存什么
task_tools request_ref、result_ref;另有 request_sha256 判断重复调用是否同一请求 请求和结果的表头
role_conversation_operations、service_role_operations 同上 请求为 {}、结果为 NULL(原先加密,不在库里留任何字段)
model_requests request_ref、response_ref request_snapshot、response_snapshot 为 NULL
task_logs content_ref(只给运行中超过 2 KiB 的日志) 日志的表头

表头只留顶层(以及下一层对象里)不超过 256 字符的标量,日志的 detail 保留到 8000 字符(更长时保留首尾),所以按 type、code、phase_key、workspace_id、error、tree_sha 等字段的现有查询照常工作。需要全文的读者统一经 src/storage/payloads.ts:有定位串读文件,没有就读旧列,所以迁移前后读到的内容相同。

task_history 里由触发器写的 operation(task_tools 插入和状态变化)和 runtime_log 快照随之只含表头和定位串;按 task_tools:<id>、task_logs:<id>、task_history:<id>、model_requests:<id>:request|response 解析证据时,从文件重建出与原快照逐字节相同的内容。task_tools 的更新触发器只在 state 变化时触发。

写入顺序、崩溃与校验

先写文件行,再提交指向它的数据库更新;重复调用要重放的工具结果在提交前 fdatasync。进程在两者之间停止,文件里多出一行没有任何行引用的记录,读者不会看到它;数据库从不指向没写出的字节。

运行结束(endRun)时关闭它的文件;文件 30 分钟没有追加也会关闭;正常停机关闭所有文件。进程异常停止后留下的未关闭入口,由服务开始监听后的后台封口任务处理:截掉不完整的尾行、校验整条链,再写入行数、字节和最后哈希。

读单条记录按定位串读出该行,核对长度、换行和 sha256;读整个文件时校验每行的 seq、prev,并与关闭时记录的行数、字节和最后哈希比对。被截断报 trajectory_truncated,被改动报 trajectory_corrupt;证据和控制台显示为不可用的记录。重复调用要重放的结果校验不通过时,任务以 trajectory_unreadable 停止,不重新执行这次调用。

删除项目时删除它的轨迹目录和入口,以及它自己的会话轮次文件;一个会话目录可以同时存着多个项目的轮次,只有该会话不再有入口时才删整个目录。清理会话历史时删该会话的轨迹文件。行先删、文件后删,中途停机只会在盘上留下没有入口的字节,不会留下指向已删文件的行;反过来,文件被绕过存储删掉时,启动时和每十分钟一次的孤儿扫描会收走没有文件的活入口并退回用量。按保留期主动删掉文件后的过期入口不算孤儿,扫描既不会删它的行,也不会再扣一次账。控制面的轨迹暂不过期。

manager 账本

manager 把每次 runner 调用的输入和结果写进自己数据卷里的轨迹文件(manager/trajectories.mjs,格式和规则与上文相同):trajectories/<repository_id>/<workspace_id>.jsonl,一个任务工作区一个文件;启动、停止、配置等不属于工作区的调用写进 trajectories/<repository_id>/project.jsonl。任务释放工作区(reap)时关闭它的文件,30 分钟没有追加也会关闭。

operations 每行保留调用的状态、一个小表头(操作 id、generation、请求类型和工作区)、输入的 sha256(input_sha256,判断同一操作 id 的重复调用是否同一请求),以及输入和结果的定位串(input_ref、result_ref),result 为 NULL。结果先写入并 fdatasync,再提交指向它的更新;重复调用从文件重放结果,校验不通过时以 operation_record_unreadable 拒绝,不重新执行。

manager 就绪(恢复完成)之后,后台先封口上次留下的未关闭文件,再按 rowid 分片迁移已结束(completed、interrupted)的旧行,做法与控制面相同,进度在 manager 数据库的 settings.trajectory_migration。仍在运行的调用留给它自己的调用写完。账本行不删除,manager 的轨迹文件也不随项目删除,而是过了保留期后按下文删除。

过期删除(#671)

manager 只在同一操作 id 重复调用时读取保存的结果,这只发生在发起调用的任务仍在运行时(runner 的 journal 也覆盖第一天);控制面在自己的轨迹(task_tools)里另存了同样的请求和结果。所以 manager 的轨迹文件是重复数据,过了保留期就在后台删除(TrajectoryExpiry,manager/trajectories.mjs):

删除文件不会让 manager.sqlite 变小,那是数据库自己的空闲页,见上文。

剩余空间保护

两个服务各自盯着数据所在磁盘的剩余空间(控制面 src/storage/disk.ts,manager manager/disk.mjs,规则相同),statfs 结果最多缓存 10 秒:

存储页

全局设置的「存储」一节(GET /api/storage)只读,列出 bot 用到的每一类存储(#671)。超级管理员看到全部项目和整块数据盘;项目管理员只能进入这一节,只看到自己项目的轨迹和项目电脑。

打开页面只读文件关闭时累加的 trajectory_usage(manager 有自己的一份)、一次 statfs 和控制面每 5 分钟的后台快照,不遍历文件、不扫描数据表,加载时间不随数据量增长。快照给少数未关闭的文件取大小、读数据库头部的 PRAGMA、向 manager 取 GET /v1/storage,并对新扫描到的电脑按任务记录给工作区分类(每次扫描只分类一次);git-cache 和 public-boards 每小时用 du 以最低优先级测一次。manager 在后台测量:每台运行中的电脑每 6 小时一次、同一时间只扫一台,runner 的 storage_scan 以最低优先级对 /workspace 做一遍两层的 du(30 分钟为限,超时或有读不了的目录时标为未扫完),manager 保存最后一次结果(computer_storage);Docker 的镜像与构建缓存每 30 分钟经一次 GET /system/df?type=image&type=build-cache 读一次,容器可写层另用一次 GET /system/df?type=container(超时上限更长,Docker 逐个走容器的可写层);这次读失败或超过 4 MB 响应上限时保留上一次结果,容器那一次失败只让容器一项显示「尚未测量」,镜像与构建缓存照常更新。Docker 的卷不读:/system/df 列的卷里包含已算作项目电脑工作卷、控制面与 manager 数据目录的字节,加进合计会重复计数。迁移期间仍在行里的正文按表给出估计的待检查行数,不按项目细分(那需要扫描表)。

按天数清理

全局设置「存储」一节的「按天数清理」(GET/PUT /api/storage/retention,只有超级管理员;保存时校验范围并记入审计 storage.retention.updated)把各类数据的保留天数放在一处,存在 settings.storage_retention。没设置的类别不过期(#436 的决定),manager 重复正文和任务工作区保持各自的默认值。

设置 默认 范围 删除什么,保留什么
trajectory_days,可按项目覆盖(trajectory_days_by_project) 不过期 1–3650 天 已结束任务和 Manager 分派的轨迹文件,关闭超过天数后删除;文件入口标为过期(expired_at),引用它的行都保留,读出「已过期」(trajectory_expired)。同一次运行的各类记录在同一个文件里,所以按文件整体删除,不按记录类型。任务还没结束(等待重试、有后续任务)时不删;会话的轨迹不删,继续对话时会读之前的轮次。
manager_payload_days 2 天 1–365 天 manager 的重复正文(见上文过期删除),保存时和每日清理时同步给 manager(PUT /v1/storage/retention)。
workspace_finished_days、workspace_failed_days 1 天、7 天 1–365 天 项目电脑上任务结束、失败后的工作区(部署:任务工作区清理),每小时的工作区清理按它们执行。
webhook_payload_days 不过期 7–3650 天 Webhook 投递正文清空,投递记录、状态和请求头保留,另存正文的 sha256、字节数和删除时间;外部执行端还没送达的投递不清。

群聊记录在频道控制台按群设置保留天数,这里只汇总。blob 随项目删除;判断某个 blob 是否还被引用要读遍任务输入(每行约 1 MB),所以不做按天回收。

每日清理在控制面启动 10 分钟后第一次运行,之后每天一次:先把 manager 的天数同步过去,再按项目、按 closed_at 顺序分批删除过期的轨迹文件(每批 50 个,批间暂停;先标记入口、移出计数到 trajectory_usage 的 expired,再在事件循环之外删文件;停机前已标记、文件还在的,下次先删),随后按 received_at 顺序分批清空 Webhook 正文(游标存在 settings.retention_cleanup,处理过的行不再读),最后分批删除 updated_at 超过 30 天的提交检查状态缓存行(commit_checks,每批最多 500 条;Webhook 接收检查事件时也会每 10 分钟顺带裁剪一次超龄行)。每次删了多少文件、多少字节以及裁剪了多少条提交检查记录记在 settings.retention_cleanup,存储页显示。一个文件或一行处理失败(例如文件删不掉)只记入失败数和最近一个错误,留到下次,不影响其他项目和其他类别;外部执行端还没送达而保留的投递正文,其 id 记下来,每次先看一遍,送达后就清。停机时等正在进行的清理在下一步结束。删除项目时,它已过期文件的计数从 expired 一并去掉,项目的计数行全部删除。任务再用到已删除的工具调用结果时,以 operation_result_expired 换新的尝试。

历史数据迁移

升级前写进行里的正文由后台迁移搬进文件(src/storage/migration.ts)。控制面开始监听、封口任务跑完之后才启动,就绪不等它;启动阶段只加列、重建触发器,不读大表的行。

迁移不缩小 SQLite 文件:清出的页留在空闲页里给新行复用。空闲页还给磁盘由服务启动时的压缩和之后的增量回收完成,见部署:启动时压缩数据库。

命令完整输出与模型分页

命令超过 1 MiB 输出后继续执行;成功与失败由 exit_code、timed_out 和 error 决定,truncated 仅表示返回的预览省略了中间内容。runner 只在内存保留固定大小的首尾缓冲,完整输出脱敏后流式写入 journal;控制面按操作 ID 分页复制到轨迹目录的 results/<id>.utf8。SQLite 的 tool_result_files 只保存所有者、来源、长度和来源消息指纹。项目或会话删除时,结果文件随轨迹清理。runner 的原始 journal 由已有保留策略回收,助手电脑的临时 journal 在本轮结束时清理。

模型收到 head、tail、file、bytes、encoding 和读取提示,用 read_tool_result({file, position, length}) 读取原结果;position、length 均为 UTF-8 字节,默认一页 16384 字节、最多 65536 字节,按 next_position 继续直到 eof。边界不足以容纳一个字符时返回范围错误,读取不会重复原命令。小输出保持原有直接返回行为;上下文压缩或批预算收紧仍保留文件引用。存储失败明确返回错误,不提供失效的文件入口。

keep_background: true 返回时服务可能仍在运行,其预览及不可变 file 只覆盖启动请求返回时已经写入的日志,读取提示会明确说明启动快照。服务后续输出继续写入 log_path,需要用同一任务的后续命令读取;读取旧结果文件不会等待服务结束或追踪新增输出。

读取只允许原任务角色或原会话主体使用,并复核当前权限,不需要命令或工作区写权限。撤回或编辑作为结果输入的消息后,该文件不可再读;后续结果仍归同一会话,不因此重建整场会话。隔离运行环境和助手电脑使用各自作用域的输出接口;通用 Pi 在自己的工作区保存相同形状的不可变结果文件,绑定工作区和子会话,工作区清理时一并回收。模型不会获得控制面宿主路径。