oma-recap

AI 工具对话历史摘要

分析指定时间段的 AI 工具对话历史，并生成主题化工作总结。

调度

目标

收集指定日期或时间段的 AI 工具对话历史，并将其综合为按主题和项目组织的回顾，保存为 Markdown 文件。

意图特征

• 用户要求生成每日回顾、每周／每月总结、站会笔记、工作日志、工具使用模式分析或 AI 对话历史分析。
• 用户希望按工作内容对对话历史分组，而不是查看原始时间顺序日志。

适用场景

• 总结一天或一段时间内的工作活动
• 了解多个 AI 工具之间的整体工作流程
• 分析不同会话之间的工具切换模式
• 准备每日站会、每周回顾或工作日志

不适用场景

• 基于 Git 提交的代码变更回顾 → 使用 oma retro
• 实时监控 Agent → 使用 oma dashboard terminal
• 生产力指标 → 使用 oma stats get

预期输入

• 日期、相对日期、时间段或工具筛选条件
• 通过 oma recap --json 或备用来源获取的对话历史
• 期望的每日或多日回顾范围

预期输出

• 保存至 .agents/results/recap/{date}.md 或范围命名文件的 Markdown 回顾
• TL;DR、概览、主题／项目、杂项或副项目，以及工具使用模式
• 使用已配置的响应语言向用户展示摘要

依赖项

• oma recap --json
• 可选的 Claude 备用历史记录：~/.claude/history.jsonl
• 控制语言行为的 .agents/oma-config.yaml

控制流特性

• 根据日期解析、时间段长度、可用工具历史记录，以及每日或多日输出格式进行分支处理
• 读取本地历史数据并写入 Markdown 回顾文件
• 按内容而非工具进行分组

结构流程

入口

1. 解析请求的日期或时间段。
2. 收集规范化的对话历史。
3. 确定采用每日还是多日输出结构。

阶段

1. PREPARE：确定时间范围和工具筛选条件。
2. ACQUIRE：通过 CLI 或备用来源收集历史记录；在可用时保留任务完成的证据。
3. REASON：按内容分组，并根据证据将每项任务分类为已请求、进行中或已完成。
4. ACT：按要求的格式编写 Markdown 回顾。
5. VERIFY：检查每项完成声明是否都有直接证据，然后检查分组、语言和输出路径。
6. FINALIZE：保存并显示摘要。

转换

• 如果未指定日期，则通过 --date 使用今天（单独使用 --window 时表示以当前时间为结束点的滚动时间段，不与日历周期对齐）。
• 如果时间段为 3 天或更长，则按项目而非日期顺序分组。
• 如果 CLI 不可用，则仅使用 Claude 备用来源，并报告覆盖范围限制。
• 如果任务低于阈值，则将其归入杂项或副项目。

故障与恢复

• 如果无法获取历史记录，则报告缺失的数据来源和请求范围。
• 如果时间戳含义不明确，则使用已配置的时区并说明采用的假设。
• 如果提取的数据稀少，则生成简要回顾并注明覆盖范围有限。

退出

• 成功：回顾文件已生成，并显示摘要。
• 部分成功：明确说明缺失的工具／历史记录或仅使用备用来源的覆盖范围。

逻辑操作

操作

操作	SSL 原语	证据
解析日期／时间段	INFER	自然语言日期规则
收集历史记录	CALL_TOOL	oma recap --json 或 jq 备用方案
读取提取的记录	READ	对话历史
对主题／项目分组和分类	INFER	时间／内容规则，以及提示词、进度、完成情况、收据或产物证据
验证输出格式	VALIDATE	每日或多日模板
编写回顾	WRITE	.agents/results/recap/
报告摘要	NOTIFY	显示的回顾

工具与资源

• oma recap --json
• 用于 Claude 历史记录的 jq 备用方案
• Markdown 输出模板

标准命令路径

oma recap --date YYYY-MM-DD --json
oma recap --window 7d --json
oma recap --json  # rolling last 24h, not "today"

资源范围

范围	资源目标
LOCAL_FS	对话历史记录和回顾输出文件
PROCESS	oma recap、jq、日期命令
USER_DATA	对话提示词和项目活动
MEMORY	主题分组和摘要笔记

前置条件

• 可以确定请求的时间范围。
• 至少有一个可用的历史记录来源。

影响和副作用

• 在 .agents/results/recap/ 下写入回顾 Markdown 文件。
• 读取本地对话历史数据。

防护规则

1. 证据状态：提示词只能证明请求，不能证明结果。只有存在明确的完成／结果消息、回执或支持所述结果的产物时，才能将工作标记为已完成。有进展证据时标记为进行中；否则标记为已请求。不得根据工具调用或经过的时间推断工作已完成。
2. 必须包含 TL;DR：列出有依据的前 3 项成果。只有符合证据状态规则时才能使用“已完成”；否则应如实概述已请求或进行中的工作。包含项目名称和状态／结果。不得包含工具名称或不必要的细节。
3. 概览：在 TL;DR 之后描述工作流程。以“I”为主语开头，并保留证据状态。
4. 每日回顾：按时间段主题分组（15 分钟以上）。其余内容归入“杂项”。
5. 多日回顾（3 天以上）：按项目分节，并按活动量排序。写成冲刺报告，而非每日记录。
6. 每个主题／项目列出 2-4 个要点：仅保留简洁的核心内容。不要罗列每一步。
7. 按内容划分主题：根据实际工作内容分组，而非根据工具分组。
8. 时间范围（仅限每日回顾）：（上午/下午/晚上 HH:MM~HH:MM）。上午：12:00，下午：12:0018:00，晚上：18:00~。
9. 保存结果：将 Markdown 写入 .agents/results/recap/。
10. 回复语言：遵循 .agents/oma-config.yaml 中配置的 language 设置。
11. 不得使用长破折号：用逗号、句号或括号代替“—”（长破折号）。

流程

1. 确定日期

根据用户的自然语言输入，确定目标日期或时间范围。默认为今天。

确定规则：

• 相对日期（今天、昨天、前天等）→ 计算 --date YYYY-MM-DD
• 指定日期（月+日或完整日期）→ 转换为 --date YYYY-MM-DD
• 相对星期（上周一、本周五等）→ 计算日期
• 时间段（本周、过去 3 天、过去 2 周等）→ 转换为 --window Nd
• 未指定日期 → 使用今天，转换为 --date YYYY-MM-DD（单独使用 --window 1d 表示以当前时间为终点的滚动 24 小时时间段，而非自然日）
• CLI 的窗口上限为 30 天（超过的值会被截短并显示警告）。请求的时间段被截短时，须在回顾中说明

2. 收集数据

通过 CLI 提取规范化的对话历史记录。

# Today (calendar day, all tools)
oma recap --date $(date +%F) --json

# Last 24 hours (rolling window ending now)
oma recap --json

# Time window (rolling, ends now; capped at 30d)
oma recap --window 7d --json

# Specific date
oma recap --date 2026-04-10 --json

# Tool filter (supported: grok, claude, codex, gemini, qwen, cursor, antigravity)
oma recap --tool claude,codex --json

未安装 CLI 时的备用方案：仅通过内联 jq 处理 Claude 历史记录：

# Uses the system timezone; export TZ=<zone> first to override, and state the
# timezone assumption in the recap (per the Failure and recovery rules).
TARGET_DATE=$(date +%Y-%m-%d)
# macOS/BSD date: advance the calendar date, then parse both local midnights.
next_date=$(date -j -v+1d -f "%Y-%m-%d %H:%M:%S" "${TARGET_DATE} 12:00:00" +%Y-%m-%d)
start_ts=$(date -j -f "%Y-%m-%d %H:%M:%S" "${TARGET_DATE} 00:00:00" +%s)000
end_ts=$(date -j -f "%Y-%m-%d %H:%M:%S" "${next_date} 00:00:00" +%s)000
# Linux/GNU date alternatives (replace all three lines above):
# next_date=$(date -d "${TARGET_DATE} 12:00:00 tomorrow" +%Y-%m-%d)
# start_ts=$(date -d "${TARGET_DATE} 00:00:00" +%s)000
# end_ts=$(date -d "${next_date} 00:00:00" +%s)000
# Do not add a fixed 24 hours: DST calendar days can have 23 or 25 hours.

jq -r --argjson start "$start_ts" --argjson end "$end_ts" '
  select(.timestamp >= $start and .timestamp < $end and .display != null and .display != "") |
  {
    time: (.timestamp / 1000 | localtime | strftime("%H:%M")),
    project: (.project | split("/") | .[-1]),
    prompt: (.display | gsub("\n"; " ") | if length > 150 then .[0:150] + "..." else . end)
  }
' ~/.claude/history.jsonl

3. 主题分析与分组

阅读所有提取的数据，并按以下标准进行分析：

分组规则：

• 只有工作时长达到15 分钟以上（依据时间戳间隔和提示词数量）时，才归类为单独主题
• 将同一主题的连续提示词合并为一个主题
• 将不足 15 分钟的任务归入“杂项”部分
• 按工作内容分组，而非按工具分组

跨工具分析：

• 在同一时间段使用多个工具时，记录工作流程
• 示例：“在 Antigravity 中设计 -> 在 Claude 中实现 -> 在 Codex 中审查”
• 根据工具切换模式提炼见解

从每个主题中提取：

• 执行的核心工作
• 做出的关键决策
• 使用的工具组合
• 产出的成果（文档、代码、配置等）

4. 输出格式

将结果保存到 .agents/results/recap/{date}.md，并同时显示。

使用 resources/output-formats.md 中的 Markdown 模板：

• 每日格式（1d 或指定日期）：TL;DR → 概览 → 按时间段划分的主题 → 其他 → 工具使用模式。
• 多日格式（3d+）：采用以项目为主线的冲刺报告结构；对于小型工作（少于 30 个提示词），使用“副项目”部分；遵循同一文件中的多日分组规则。

响应语言遵循 .agents/oma-config.yaml 中的 language 设置。

5. 保存结果

保存到 .agents/results/recap/{date}.md。 对于时间范围，使用 {start-date}~{end-date}.md 格式。

# Example paths
.agents/results/recap/2026-04-12.md
.agents/results/recap/2026-04-06~2026-04-12.md

参考资料

• 输出格式模板：resources/output-formats.md
• Recap CLI：oma recap --json
• 输出目录：.agents/results/recap/
• 语言配置：.agents/oma-config.yaml
• Claude 回退历史记录：~/.claude/history.jsonl