用途：在 pi 的历史会话日志中查找内容，替代零散的 grep/python 排查方式。日志默认位于 ~/.pi/agent/sessions，可用 echo "$PI_SESSION_FILE" 确认当前会话文件，其目录的父目录即根目录。
主要能力：一是全文文件级搜索，运行 python scripts/session-search.py "pattern"（相对本技能目录），输出按仓库目录分组的命中列表，每个文件带命中次数和覆盖该会话的 UTC 时间戳，文件名以 UTC 时间戳前缀排序（最新在后）；空报告表示无命中。二是结构化查询，--json 需至少一个过滤条件（--role / --tool / --field），模式作为最后一个位置参数（"" 匹配全部），例如 python scripts/session-search.py --json --role assistant "pattern"、--json --role assistant --tool subagent ""、--json --tool subagent --field "model=" ""、--json --tool subagent "sensenova-6.8"；每条事件行打印时间戳、角色、事件类型、工具名（工具调用时）和截断的内容片段。三是文件模式可用 --show 5 "pattern" 控制每个命中文件的片段数。
使用方式：确定根目录后先做全文搜索，再用 --json 加过滤条件回答结构化问题，最后用 grep -n "pattern" <会话文件> 深入查看命中上下文。
限制与注意：会话目录以 -- 开头（编码 cwd，如 --C--Users-Hue-Repos-foo--），ls -d */、for f in $(ls -d */)、du /20.jsonl 会误解析为选项，应使用脚本或带显式 ./ 或 -- 分隔符的 find/rg。JSONL 每行一个事件，类型含 session、message、custom_message 等；message 事件体为 message.role 加 message.content[]（text/thinking/toolCall/toolResult 部分），工具调用位于 assistant content[] 中 type 为 toolCall 的部分。规模为数百个 JSONL 文件、约 150 MB，全量 Python 扫描需数秒，纯文本用 rg 更快。输出有上限，应通过过滤条件或 --show N 收窄而非扩大扫描。Python 可正确输出中文（PYTHONUTF8 生效），无需额外包装代码。