session-evidence

用途

session-evidence 是一个本地会话提取工具，用于从本地 Cursor 或 Codex 的会话历史中提取转录片段、工件（artifacts）和来源信息（provenance）。其核心命令形式为：

sessions analyze --provider cursor|codex --include-turns --extract-only

该工具的设计原则是将“提取”与“解读”分开：先报告提取出的事实，再单独标注任何解读。

主要能力

• 从 Cursor 或 Codex 的本地会话历史中提取转录片段、工件和会话 ID。
• 支持按时间范围（--days）、工作区（--workspace）、元数据查询（--query）和用户轮次文本（--turn-query）进行筛选。
• --turn-query 可重复使用，多个词之间为 OR 语义，matchedQueries 会记录命中的确切词。
• --extract-only 用于调查场景，避免索引元数据淹没匹配的轮次。
• 支持表格输出和 JSON 输出（--format json），JSON 便于将提取的证据交给其他智能体。
• 可检查 matches、matchedQueries、artifacts、sessionId 和 turnIndex 等字段。
• 当片段不足时，可用 sessions cursor show <sessionId> 或 sessions codex show <sessionId> 打开源会话。

使用方式

工作流

1. 从窄范围开始：在扫描转录证据前，先选择 --days、--workspace、--query 或可重复的 --turn-query。
2. 使用 --turn-query 搜索用户轮次文本。
3. 调查时使用 --extract-only，避免索引元数据淹没匹配轮次。
4. 先扫描表格输出，用 --evidence-limit 保持表格精简。
5. 将证据交给其他智能体时使用 --format json。
6. 检查 matches、matchedQueries、artifacts、sessionId 和 turnIndex。
7. 仅在片段不足时打开源会话。
8. 先报告提取出的事实，再单独标注解读。

模式

• 定向查找：--extract-only --turn-query <term> 返回匹配的用户轮次，不含索引分析部分。
• 相关词：重复 --turn-query，匹配使用 OR 语义，matchedQueries 记录命中的确切词。
• 广泛扫描：省略 --turn-query 可获得分组模式，适用于尚不知道搜索词的场景。
• 元数据过滤：--query 用于标题、ID、工作区或首个用户查询，不搜索全部转录轮次。
• 诊断：仅当 worker/subagent 会话是问题的一部分时，才添加 --include-automation。

命令示例

近期工作区扫描：

sessions analyze --provider cursor --include-turns --extract-only --days 30 --workspace /path/to/repo

使用 Codex 历史：

sessions codex reindex
sessions analyze --provider codex --include-turns --extract-only --turn-query "verify"

查找提及验证的轮次：

sessions analyze --provider cursor --include-turns --extract-only --turn-query "verify"

查找 how-to 问题：

sessions analyze --provider cursor --include-turns --extract-only --turn-query "how to" --days 30

查找相关确切词：

sessions analyze --provider cursor --include-turns --extract-only --turn-query "verify" --turn-query "validate" --turn-query "check"

JSON 交接：

sessions analyze --provider cursor --include-turns --extract-only --turn-query "review" --format json

小表格预览：

sessions analyze --provider cursor --include-turns --extract-only --turn-query "review" --evidence-limit 5

参数说明

• --query 按索引元数据过滤会话：标题、ID、工作区或首个用户查询。
• --turn-query 搜索用户轮次转录文本。
• 运行 --include-turns 而不带 --days、--workspace、--query 或 --turn-query 时，会扫描所有匹配的缓存转录并打印警告。

适用场景

• 转录查找：查找匹配某词的用户轮次、显示重复请求的片段。
• 工作流与技能审计：例如判断规划或审查工作流是否路由到预期技能、哪些技能在 90 天内零调用。
• 提取出现的文件、命令、PR、分支、计划或 URL。
• 确定应打开哪些会话 ID 和轮次索引以获取更多上下文。
• 判断哪些请求信息在片段中缺失，需要 sessions cursor show 或 sessions codex show。

限制与注意事项

• 建议使用确切词和短语；若某短语返回零匹配，可尝试同一类别中的相邻词。
• 使用可重复的 --turn-query 处理同义词，而不是扩大到模糊或语义搜索。
• 用 --evidence-limit 保持表格输出精简；JSON 保留完整的 matches 和 artifact 数组供智能体交接。
• 对 1-2 个最相关匹配使用 sessions cursor show <sessionId> 或 sessions codex show <sessionId>，而不是打开每个结果。
• Codex 索引以 ~/.codex/state_5.sqlite 为事实来源，仅当根 DB 缺失时才回退到 ~/.codex/sqlite/state_5.sqlite。
• Codex 元数据/证据可能使用 DB 首个用户消息清理开头注入的首轮前言；当原始 rollout 转录保真度重要时，使用 sessions codex show <sessionId>。
• 将模式仅视为重复出现的提示，不要将输出视为推荐。
• 保持隐私边界：对敏感片段进行摘要；不要引用密钥、令牌或私有转录文本。

输出解读

• matches：扁平的 turn-query 命中，含片段、工件和来源。
• matchedQueries：匹配该用户轮次的确切查询词。
• patterns：分组后的广泛扫描证据；将 support 视为重复出现，而非重要性。
• artifacts：提取的路径、命令、PR、分支、计划和 URL。
• turnIndex：完整转录轮次索引，包括助手和工具轮次。
• --evidence-limit：限制表格匹配行和模式示例/工件；不会截断 JSON matches。

报告内容

应包含：运行的命令、使用的过滤器、匹配的片段、发现的工件、会话 ID / 轮次索引、缺失的上下文。

参考资料

• 工作流与技能审计：references/audit-examples.md。
• 探索轮次查询：references/turn-queries.md。
• 协调器夹具（如 planning-workflow/references/routing.md）定义预期路由。