Imported from ooooooooooooooooooop/personal-ai (skills/find-session/SKILL.md). Install upstream with npx skills add ooooooooooooooooooop/personal-ai --skill find-session. Copyright stays with the author.

快速定位与跟踪 DSH 会话

用于用户要求"按对话名/标题找会话""跟踪某个对话""查看某次会话内容或 token 消耗"时。统一入口是本 Skill 包内脚本 scripts/find_session.py（相对本 Skill 目录），不临场另写遍历逻辑。

路径提示：Skill 包在 ~/.dsh/skills/find-session/（仓库源在 skills/find-session/）。以下命令均假设当前目录为本 Skill 目录，或把 scripts/find_session.py 换成绝对路径 ~/.dsh/skills/find-session/scripts/find_session.py。

触发边界

• 适用：按标题关键词搜索会话、按正文关键词搜索会话、读取某会话消息内容、查看会话 token/时间统计、按项目或时间范围过滤。
• 不适用：修改/删除会话、DSH 内部状态变更、跨设备同步。这些不得套用本 Skill。

数据源与固定事实

• 索引：~/.dsh/storages/session_projcache.json（title/cwd/createdAt/sessionStats/tokenUsage）。
• 内容：~/.dsh/sessions/<项目>/<session>/session.jsonl.zstd（多帧 zstd，必须流式解压，单帧 decompress 只解第一帧）。
• 正文搜索默认只扫最近 30 个会话（全量解压 200+ 会话慢），需要全量时加 --full。

固定执行

1. 标题搜索（快，走索引）：

   python scripts/find_session.py <关键词>                # 列出匹配会话（按时间倒序）
   python scripts/find_session.py <关键词> --content      # 搜索后直接读最新匹配会话内容

2. 正文全文搜索（慢，需解压）：

   python scripts/find_session.py --grep <关键词>          # 默认最近 30 个会话
   python scripts/find_session.py --grep <关键词> --full   # 全量扫描

3. 按会话 id 操作：

   python scripts/find_session.py --id <session-id>        # 读取消息内容
   python scripts/find_session.py --id <id> --stats        # token/时间统计

4. 过滤与排序（标题/正文搜索均生效）：

   python scripts/find_session.py <关键词> --project 桌面    # 按项目路径过滤
   python scripts/find_session.py <关键词> --since 2026-08-01 --until 2026-08-31
   python scripts/find_session.py <关键词> --sort tokens     # time|tokens|turns
   python scripts/find_session.py <关键词> --max 5           # 结果条数上限

输出与失败报告

• 输出完整 token 消耗（未缓存输入 + 缓存读 + 输出 + 缓存写），来自 tokenUsage.totals，不用单一 decodeTokens。
• 搜索无匹配时报告"无匹配会话"，不以空结果冒充成功；会话文件缺失时给出明确提示。
• 只读操作，不改动任何会话数据。

验证

• 每次使用后核对：搜索关键词是否命中预期会话、token 统计是否与 ~/.dsh/storages/session_projcache.json 中 tokenUsage.totals 一致。
• 改动脚本后回归：至少跑一次标题搜索、一次 --grep 正文搜索、一次 --id --stats，确认三项路径输出正常。

脚本是唯一入口：

• find_session.py（skill 包内自带，随 Skill 同步）