用途：在 pi 的会话日志中查找历史运行内容，包括短语、工具调用、思考段落和字段，替代临时性的 grep 或 Python 排查。
主要能力：提供文件级全文检索，结果按仓库目录分组，每个文件给出命中次数和该会话的 UTC 时间戳跨度；提供 --json 结构化查询，要求至少指定一个过滤器（--role / --tool / --field），可加模式作为最后一个位置参数，空字符串表示匹配全部；--show N 可在文件模式下为每个命中文件输出 N 条片段。每条事件行显示时间戳、角色、事件类型、工具名（工具调用时）和截断的内容片段。
使用方式：先确认会话根目录，默认是 ~/.pi/agent/sessions，也可用 echo "$PI_SESSION_FILE" 查看当前会话位置，或用 --root DIR 指定自定义根目录。基本检索命令为 python scripts/pi-session-search.py "pattern"；结构化查询示例如 python scripts/pi-session-search.py --json --role assistant "pattern"、python scripts/pi-session-search.py --json --tool subagent --field "model=" ""。定位到文件后可用 grep -n "pattern" <文件> 查看上下文。
适用场景：需要回溯某次会话中是否出现某段文本、某个工具调用参数或某个模型名，或想了解会话日志格式时。
限制与注意：--json 必须带至少一个过滤器；输出有上限，应通过过滤器或 --show N 收窄而非扩大扫描范围。会话目录名以 -- 开头，ls -d */ 等方式可能将其误当选项，建议使用脚本或带 ./ 或 -- 分隔符的 find/rg。JSONL 每行一个事件，类型包括 session、message、model_change、thinking_level_change、custom_message 等；工具调用在 assistant 的 content[] 中 type 为 "toolCall"，工具结果作为独立事件由 message.role == "toolResult" 承载。日志规模可达数百个文件、约 150 MB，全量 Python 扫描需数秒，纯文本检索 rg 更快。其他如平台、收费等信息暂未提供。