Session Profiler 用于分析和调试 Hermes 会话，把一条 Hermes 主会话转写记录连同其子智能体转写记录，转换为可分析产物。所有操作都应通过随附的封装脚本进行，以保证环境一致并记住最近解析的工作目录。
SP="$SKILL/scripts/sp"
需要先把 SKILL 解析为该技能所在目录。如果不可用，则使用本文件旁边 scripts/sp 的绝对路径。
一、主要能力
Session Profiler 可以查找和检查会话、解析会话、生成可读概况，并进一步缩小调查范围。Hermes 将 rollout 记录存放在 ${HERMES_HOME:-~/.hermes}/sessions/YYYY/MM/DD/rollout-*.jsonl，归档记录存放在 archived_sessions/。Hermes 子智能体的 rollout 会在 session_meta 中递归标识其父线程。
查找和检查会话： $SP projects $SP list [--provider hermes] [--n 20] $SP list --project-dir "${HERMES_HOME:-$HOME/.hermes}/sessions" $SP find <session-id-prefix> $SP info <session-id-or-path>
解析会话后再分析。对仍在活动的会话需要重新运行解析。 $SP parse <session-id-or-main-jsonl-path>
该命令会打印并记住其工作目录，写出 events.parquet、events.csv 和 agents.json。可以用全局 --data-dir <dir> 或 SESSION_DATA_DIR 覆盖已记住的目录。
先从可读的 profile 开始，再缩小调查范围： $SP brief $SP agent-summary $SP costs $SP slowest-tools --n 20 [--agent <id-or-name>] $SP tool-breakdown [--agent <id-or-name>] $SP inference-vs-tool $SP errors $SP turns $SP timeline 2026-07-08T19:14:00Z --window 120 $SP events [--agent main] [--tool Bash] [--grep rebase] [--since 2026-07-08] [--n 30] [--long]
向人解释某个会话时，优先使用 brief。它会写出 brief.md，包含会话标题指标、突出的慢路径或失败、prompt 轨迹或目录式故事线，以及智能体记分板。在 brief 指出值得关注的区域后，再用表格命令回答具体问题。
如需临时 pandas 分析，设置 SESSION_DATA_DIR，把 scripts/ 加入 PYTHONPATH，并在封装脚本的 venv 中使用 from session_profiler.dataset import load; df = load()。
二、汇总会话并保留经验
$SP toc --dry-run $SP toc $SP review
使用 toc --dry-run 检查经过净化、去除垃圾内容后的摘要。toc 会构建本地按时间顺序的目录，写出 toc.json 与 toc.md，不调用外部智能体 CLI。将 toc.md 展示给用户以帮助定位。review 会写出 review.md，包含关于失败调用、慢路径、活跃时间构成、委派和估算成本的确定性观察。应把这些观察转化为对 prompt、工具批处理、预检检查或子智能体分工的具体修改建议；不要声称 profiler 会自动改变智能体行为。
三、构建并打开追踪
$SP trace $SP open
在 Perfetto 中加载生成的 trace.json.gz。自上而下阅读：Session overview 展示整个运行，Table of contents 在存在 toc.json 时展示故事线，每个智能体的工作时间线展示推理与工具，prompt trail 标记用户轮次，usage tokens + cost 展示累计计数。点击某个 slice 可检查净化后的输入输出预览、时长、并发、失败状态、token 数量和估算成本。
四、解释规则
应信任以下推导结果，而不是从原始行重新计算：
对转写式 JSONL，按 API message.id 对 usage 去重：内容块记录会重复不断增长的 usage 快照，因此只保留最终快照一次。对 Hermes，每个 token_count 事件消费一次 last_token_usage，并将 cached_input_tokens 视为 input token 的子集。
跨智能体汇总 token。子智能体 token 用量位于子智能体转写记录中，而不是父转写记录中。
在同一转写记录中，从一个 tool_use 到其匹配的 tool_result 来测量某个工具。把共享同一条 assistant 消息的多个 tool use 视为并发。
对同一个 message ID，从第一条到最后一 条 assistant 记录来测量推理。不要把人的空闲时间当作推理。
每个子智能体的墙钟运行时间，从其自身转写记录中的第一到最后一个时间戳来测量，而不是从父级的 spawn 工具跨度来测量。
活跃时间总量是各跨度之和，不是墙钟时间。并发的工具和智能体可能使累计活跃时间超过经过的墙钟时间。
所有美元金额都应标注为估算。Hermes 在模型已知时使用特定模型的公开 API 费率，包括定价文档记录的长上下文乘数。订阅、额度、优先处理、工具费用和协商费率可能不同；未知模型会标记为不可用，而不是猜测。
五、隐私与故障处理
将转写记录和追踪视为敏感数据。预览会遮盖较长的不透明 token 和常见的认证/cookie 头，但仍可能包含源代码、prompt、路径、个人数据或密钥。共享前请先审查，只在会话所有者会共享的范围内共享。
全程预期使用 UTC 时间戳。
如果解析仍在增长的转写记录，请在最终分析前立即重新运行解析。
如果依赖引导失败，请报告 uv 或 pip 错误，让用户修复本地网络/包配置。不要把机器特定的代理设置加入本技能。
如果 toc 无法从解析数据构建目录，请保留解析数据和分析结果；使用 toc --dry-run 作为会话摘要，并说明缺失了哪些时间戳或事件。