技能使用指南

session-logs（会话日志）Skill 是什么？怎样用 jq 检索历史对话？

session-logs（会话日志）Skill 能让你用 jq 与 rg 直接检索 AI 助手的完整历史对话，按角色提取原文、跨会话搜关键字、汇总每日成本与工具调用次数。本文详解技能定位、安装前提、8 步使用指南、竞品对比与典型场景，帮你把旧对话变成可查询的数据资产，开发者与效率工具用户都适用，点开看完整教程。

会话日志Skillsession-logs
8 个章节 约 17 分钟阅读 AI 智能生成

会话日志Skill：用 jq 与 rg 把历史对话变成可查询的数据资产

核心结论速览

  • 它是什么：session-logs（会话日志Skill）是一个面向 AI 助手自身会话记录的检索与分析技能，把存放在 ~/.otto/agents/<agentId>/sessions/ 下的 JSONL 对话文件，变成用 jq 和 rg 就能随时查询的结构化数据。
  • 解决什么问题：当对话变长后被移出内存、或用户需要引用"上一次/父对话"里的内容时，模型容易"失忆"；这个技能让助手能主动回到磁盘上的完整历史中去找原话。
  • 怎么用：不需要写代码，用自然语言提出"帮我在上个会话里找关于 X 的讨论"，助手就会组装出对应的 jq / rg 命令执行并汇总结果。
  • 技术门槛：只依赖两个命令行工具 jq 与 rg，无需数据库、无需服务端。
  • 额外收益：内置成本统计、消息计数、工具调用分布等查询模板，可以用来复盘"我在 AI 上花了多少钱、都让它干了什么"。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 会话日志Skill
技能英文名 session-logs
技能 ID 13569
图标标识 📜
运行时依赖 jq、rg（ripgrep）两个命令行二进制

它到底解决什么问题

在长期使用 AI 助手的过程中，会产生一条完整的时间线：每一次提问、每一次模型回复、每一次工具调用。但当单次上下文窗口被塞满、或者用户切换到新的会话继续讨论时，早期内容就被"移出内存"了。此时用户一句"我们上次说的那个接口方案是什么来着？“，模型往往只能回答"抱歉，我看不到之前的对话”。

会话日志Skill 的价值就在于：它知道历史对话被存到了磁盘的哪里、以什么格式存放、以及用什么命令能最快把想要的那几句原文捞出来。它不是一个"记忆增强插件"，而是把"翻旧账"这件事变成了一条可复现的检索路径。

安装前的准备

根据技能元数据，本技能只需要两个可执行程序存在于系统 PATH 中：

  1. jq —— 用于解析 JSONL 中的每一行 JSON 对象，做筛选、聚合、求和；
  2. rg（ripgrep）—— 用于在多个会话文件中快速做关键字全文搜索。

在 macOS / Linux 上通常通过各自的包管理器安装这两个工具；Windows 用户建议在 WSL 或 Git Bash 环境下使用。具体的安装命令以官方说明为准，本技能本身不包含额外的安装脚本。

一键安装的通用步骤

  1. 打开技能入口：在你所使用的 AI 助手客户端/平台的"技能市场""插件中心"或"Skills"面板中，搜索技能英文名 session-logs 或技能 ID 13569；
  2. 确认依赖：安装界面通常会显示该技能的 requires.bins 为 ["jq","rg"]，若检测不到这两个命令，先按上一步装好再继续；
  3. 一键启用：点击安装/启用按钮，技能描述会被注入到助手的系统提示中，此后模型在遇到"引用历史对话"的诉求时会自动触发它；
  4. 验证是否生效：在对话中直接问一句"帮我列出最近几个会话文件以及它们的大小"，如果助手开始执行形如 for f in ~/.otto/agents/<agentId>/sessions/*.jsonl; do ... done 的命令并返回日期与体积列表，说明技能已正常工作。

需要提醒的是：具体的安装命令、市场链接与入口位置随平台版本变化，请以官方说明为准；本技能本身不开设账号、不产生订阅费用。

该技能的主要功能和特点

  • 定位精准的触发逻辑：技能被明确限定在"用户询问之前的聊天、父对话、或不在内存文件中的历史上下文"时使用，避免每次对话都去扫盘，造成无谓开销。
  • 掌握完整的存储结构知识：它清楚 sessions.json 是"会话键 → 会话 ID"的索引文件，清楚每个 <session-id>.jsonl 是逐行追加的对话记录，也清楚每一行里 type、timestamp、message.role、message.content[] 的层级关系。
  • 只取人类可读内容：通过 select(.type == "text") 过滤掉思考过程与工具调用噪声，只把真正的对话文本捞出来，避免把整段 JSON 倾倒给用户。
  • 多会话批量检索：借助 rg -l 可以一次性在所有 .jsonl 文件中定位包含某个短语的会话，先缩小范围再精读。
  • 自带"成本与用量"分析能力：可以按会话或按天聚合 message.usage.cost.total，输出每日花费；也能统计消息数、用户轮次、助手轮次、首末时间戳。
  • 工具调用画像：通过抽取 type=="toolCall" 的 name 字段并 sort | uniq -c | sort -rn，能一眼看出某次会话中哪个工具被调用最多。
  • 对大体量文件友好：技能明确提示"大型会话可能几 MB，使用 head / tail 进行采样"，避免一次性把巨型文件读进上下文。
  • 可追溯删除记录：被删除的会话保留 .deleted.<timestamp> 后缀，仍可被检索到，不会因为"删了"就彻底断线。

和"直接翻聊天记录窗口"这类普通做法相比，它的差异在于：可批量、可聚合、可精确过滤、可跨会话。窗口里只能靠肉眼往上滚，而它能一次扫描几十个会话文件、按角色筛选、按关键字命中、并按成本汇总。

如何使用该技能？

整体使用方式是"自然语言提需求 → 技能组装命令 → 返回结果"。你不需要自己背命令，但了解命令长什么样，能帮你把需求描述得更准。

第 1 步：确认会话目录位置

会话日志位于 ~/.otto/agents/<agentId>/sessions/，其中 <agentId> 取自系统提示 Runtime 行中的 agent=<id> 值。如果你的环境里有多个 agent，务必先确认当前用的是哪一个，否则会去错误的目录里翻找。

第 2 步：先"看一眼目录"，建立全局印象

直接说："帮我按日期和大小列出所有会话文件。"助手会执行：

for f in ~/.otto/agents/<agentId>/sessions/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  size=$(ls -lh "$f" | awk '{print $5}')
  echo "$date $size $(basename $f)"
done | sort -r

输出是"日期 + 体积 + 文件名"的倒序列表，便于你判断该深入哪个会话。

第 3 步：按日期锁定目标会话

说："找出 2026-01-06 那天的会话。"对应命令：

for f in ~/.otto/agents/<agentId>/sessions/*.jsonl; do
  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
done

第 4 步：提取"我当时是怎么问的"

说："把这个会话里我问过的问题全部列出来。"对应命令：

jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl

输出是一段段纯文本的用户发言，非常适合回顾自己当初的需求演变。

第 5 步：在助手回复中搜关键字

说："在这个会话的助手回复里搜 ‘缓存’ 相关的内容。"对应命令：

jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg -i "keyword"

第 6 步：跨所有会话找一句话

如果记不清是哪次聊的，直接说："在所有会话里搜 ‘phrase’ 这个词。"助手会执行：

rg -l "phrase" ~/.otto/agents/<agentId>/sessions/*.jsonl

先返回命中的文件路径，再对命中文件做第 5 步的精读，这是效率最高的"两段式检索"。

第 7 步：做一次用量与成本复盘

  • 单会话总成本：jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
  • 每日成本汇总：按天取 timestamp，逐文件求和后交给 awk 聚合，最终输出"日期 + 美元金额"的排行。
  • 会话画像：用 jq -s 一次性得到 messages 总数、user 轮次、assistant 轮次、first/last 时间戳。
  • 工具使用细分：jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.jsonl | sort | uniq -c | sort -rn。

第 8 步：用"低噪音"模式快速预览

如果你只想要干净的对话流、不想要任何元数据，可以用技能给出的快速纯文本提示：

jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ~/.otto/agents/<agentId>/sessions/<id>.jsonl | rg 'keyword'

这一步把"类型过滤 + 文本提取 + 关键字命中"压缩成一条管道，是日常最常用的形态。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
会话日志Skill（session-logs） 面向 AI 助手自身会话数据的检索与分析技能 用 jq/rg 检索 JSONL、按角色过滤、成本聚合、工具调用统计 需具备 jq 与 rg；对话式触发，无需写代码 回顾历史对话、复盘用量成本、定位旧方案原文 优势：零服务端、数据全在本地、查询模板齐全；不足：仅在具备该技能运行时的平台内生效，需熟悉 JSONL 结构才能自定义复杂查询
客户端内置的聊天记录搜索 通用产品的历史消息搜索框 关键字模糊匹配、按时间浏览 零门槛，开箱即用 快速找某句话 优势：最简单；不足：无法按角色/成本/工具调用聚合，无法跨多个会话做结构化统计，超长会话容易搜不全
通用日志分析平台（ELK / 日志检索类服务） 面向服务端日志的集中式检索 全文索引、可视化看板、告警 需部署与维护、需数据接入 大规模生产日志分析 优势：检索性能与可视化强；不足：对"个人对话记录"这种小体量场景过重，接入成本高、有数据外发顾虑
直接 cat / grep 手翻文件 最原始的本地排查手段 文本打印、简单匹配 零依赖（仅需 shell） 单文件快速查看 优势：无需安装任何东西；不足：JSONL 每行嵌套结构，原始输出噪声极大，无法按 role 过滤，也无法求和聚合

从对比可以看出，会话日志Skill 的生态位非常清晰：它介于"聊天窗口搜索"和"专业日志平台"之间——比前者多了结构化聚合能力，比后者少了部署与接入成本，特别适合"个人或小团队的 AI 使用复盘"这一细分场景。

该技能的典型应用场景与实际体验情况

场景一：独立开发者回顾旧方案，避免重复设计

痛点：一周前和助手讨论过某个数据表结构，方案细节已从上下文中消失，重新推演要花半小时。使用方式：先 rg -l 搜表名定位会话文件，再用用户消息提取命令把当时的提问全部列出，最后精读助手回复的命中段落。实际体验：整个过程两三条命令即可完成，上手难度低，只要记得关键词，找回原文的成功率很高。注意事项：关键词尽量选唯一性强的名词（如字段名、函数名），避免用"配置""问题"这类高频词。

场景二：团队负责人做 AI 成本复盘

痛点：月底想解释"这个月在 AI 上的花费为什么涨了"，但账单只有一个总数，看不到明细分布。使用方式：跑一次每日成本摘要，得到"日期 → 金额"的清单；再对高消耗日期的会话做工具使用细分，看是不是某个自动化流程在反复调用工具。实际体验：效果直观，通常能在一两张表内定位到异常来源。注意事项：message.usage.cost.total 使用 // 0 兜底，说明部分记录可能缺失该字段，汇总时不要假设每条消息都有成本值。

场景三：产品/运营核对"AI 到底说过什么"

痛点：用户反馈"你们助手之前承诺过 X"，需要快速核实原话。使用方式：跨所有会话 rg 关键字，命中后按 message.role 分别提取用户侧与助手侧文本，对比确认。实际体验：证据链完整，因为技能说明中明确日志是"只追加的 JSONL"，历史记录不会被后续编辑覆盖。注意事项：只筛选 type=="text"，思考过程与工具调用不计入，这恰好也是"对用户可见内容"的边界。

场景四：排查一次"工具调用风暴"

痛点：某次会话响应特别慢，怀疑是工具被反复调用。使用方式：对该会话执行工具使用细分，sort | uniq -c | sort -rn 直接给出调用次数排行。实际体验：几分钟内就能看清调用结构。注意事项：会话文件可能有几 MB，建议先 head 采样确认文件规模，再决定是全量解析还是分段处理。

整体上手评价：对于熟悉命令行的开发者，几乎零学习成本；对于非技术用户，只要用自然语言描述需求即可，由助手代为组装命令，同样可用。最容易踩的坑是 <agentId> 用错目录，建议每次任务开始时先确认一次路径。

该技能能为用户带来的价值

效率层面：把"翻聊天记录"从分钟级的肉眼滚动，变成秒级的命令命中。以一次跨 30 个会话文件的检索为例，人工翻找往往需要十几分钟且容易漏，而 rg -l 一次扫描即可给出精确文件列表。

门槛层面：jq 的语法对多数人是劝退项——多层 select、.[] 展开、-s 聚合求和都有学习曲线。技能把这些常见诉求固化成可直接套用的命令模板，用户只需说清意图，等于把"JSON 查询能力"外包给了助手。

决策层面：成本与用量数据让"是否值得继续这样用 AI"从感觉变成数字。每日成本汇总、单会话总成本、消息与轮次统计，构成了一个最小可用的 AI 使用仪表盘。

长期价值：会话日志是只追加的、带时间戳的、可被程序读取的资产。今天做的检索模板，明天、下个月依然适用；随着会话数量增长，这份"可查询的个人知识库"价值会持续放大，而不是像上下文窗口那样用完即忘。

风险控制层面：所有数据保存在本地目录、由本地命令处理，不涉及把对话内容上传给第三方分析服务，对注重隐私的用户更友好。

常见问题 FAQ

Q1：这个技能怎么安装？需要收费吗？

A：在平台的技能市场/插件中心搜索 session-logs 或技能 ID 13569，点击安装或启用即可。安装前请确保系统里已有 jq 和 rg 两个命令，它们是本技能唯一的运行时依赖。技能本身不涉及订阅费用，安装入口与具体命令请以官方说明为准。

Q2：我不会写 jq 命令，还能用它吗？

A：完全可以。这个技能的触发条件是"用户询问之前的聊天、父对话或历史上下文"，你只需要用自然语言提需求，例如"帮我在上周的会话里找关于缓存的讨论"，助手会自行组装并执行对应命令，再把结果转述给你。会一点命令的好处是能把需求描述得更精确。

Q3：它和聊天窗口里的搜索框有什么区别？

A：窗口搜索通常是"关键字模糊匹配"，而这个技能可以按 message.role 区分用户与助手、只提取 type=="text" 的可读文本、跨多个会话文件批量定位，还能对成本、消息数、工具调用次数做聚合统计。简单说：搜索框回答"有没有这句话"，它回答"这句话在哪个会话、谁说的、那次会话花了多少钱、调了哪些工具"。

Q4：适合谁用？

A：三类人最受益——需要频繁回溯旧方案的开发者；想复盘 AI 使用成本与使用模式的团队负责人；以及需要核实"AI 曾说过什么"的产品与运营人员。如果你只是偶尔用一次 AI、从不需要引用历史对话，那么不安装它也不影响日常使用。

Q5：会话被删除了还能查到吗？

A：技能说明中提到，被删除的会话会保留 .deleted.<timestamp> 后缀，因此仍可能被检索到。但这属于残留文件，是否长期保留取决于所在平台的清理策略，不建议把它当作合规意义上的归档手段。另外，日志为只追加结构，历史消息不会被后续编辑覆盖。