session-debrief

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

执行模型 — 必须遵守

在启动 Agent 之前，必须使用 AskUserQuestion 两次。 先询问目标，再询问时间范围。然后使用已确定的参数启动 Agent。

---

步骤 1 — 询问目标

使用 AskUserQuestion 并准确提供以下三个选项：

你要使用哪种分析模式？

1. 交接文档 — 为接手这项工作的下一位开发者或 Claude 会话提供全面背景。提取每项决策、文件、命令、注意事项、未完成事项和后续步骤。必要时分块并合并，以确保内容完整。
2. 错误取证 — 完整列出发生过的所有警告、错误、弃用提示、失败命令和异常，尤其是 Claude 已注意到但忽略或搁置的问题。提供完整原文细节以及文件路径和命令。
3. 时间顺序摘要 — 按发生顺序详细概述所有事件的技术时间线：每项决策、变更、问题、发现和结果。尽可能简洁，同时涵盖最多事件。

---

步骤 2 — 询问时间范围

使用 AskUserQuestion 询问：

应纳入多长时间范围内的会话？

• 48 小时（默认值 — 最近 2 天）
• 1 周（168 小时）
• 1 个月（720 小时）
• 自定义 — 输入任意自然语言，例如“3 天”“2 周”“5 小时”“从周一开始”

将用户的回答换算成小时，用于 --since <N>：

• “3 天” → 72
• “2 周” → 336
• “5 小时” → 5
• “从周一开始” → 计算从现在到上一个周一的小时数

---

步骤 3 — 启动 Agent

Agent(
  description: "Session analysis - Goal <N>: <name>",
  prompt: "Run session analysis for the current project. Execute:

    bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \\
      --goal <1|2|3> \\
      --since <hours> \\
      --verbose

  Print all output exactly as-is. Do not filter or summarize.
  If the command fails, show the full error and suggest troubleshooting.",
  run_in_background: true
)

不要添加 --shots — 它仅适用于旧版 50-perspectives 模式。

Agent 返回后，直接向用户呈现输出，不要另行总结 — debrief LLM 的输出就是结果。

---

会话盲点 — 参考

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

三种目标

目标 1：交接文档

内容最全面的输出模式。提取下一位开发者或 AI 会话继续工作所需的一切信息，无需再提问。

输出结构：

• 已完成的工作 — 每项已完成的任务、文件和命令（详尽列出）
• 当前状态 — 当前可正常运行的内容，以及已修改的内容
• 未完成／已损坏 — 未完成事项、未解决的错误、搁置的工作
• 关键决策与理由 — 说明为何采用这种做法
• 关键注意事项与背景 — 不明显的事实、变通方法、潜在陷阱
• 后续步骤（按优先级排序） — 下一次会话开始时可执行的具体操作

如果提取的历史记录超出脚本的硬编码预算（890K 个字符，约 243K 个 token；参见“配置”），脚本会在轮次边界处分割内容，使用 debrief LLM 分析每个分块，然后在一次综合调用中合并各部分分析结果。只有当各部分本身太大、无法合并时，才会分别输出。三种目标都采用相同的分块方式。

目标 2：错误取证

列出所有警告、错误和异常 — 尤其是 Claude 处理后便继续进行的问题。

每项发现均包含：

• 确切的轮次编号
• 触发原因（导致问题的命令／工具）
• 涉及的文件／路径
• 完整的错误原文（不得改述）
• 解决状态：UNRESOLVED / PARTIAL / RESOLVED
• Claude 的处理方式（已注意到？已忽略？已搁置？）

目标 3：时间顺序摘要

详细的技术时间线：每个重要事件对应一条要点，并按发生顺序排列。

• 阶段明确时按阶段分组
• 用 ⚠ 标记未解决的错误
• 记录决策及其理由
• 以 关键成果 结尾（最重要的 3–7 项结果）

---

会话的发现方式

该脚本会自动查找当前项目（根据工作目录推断）在指定时间范围内修改的所有会话：

1. 扫描 ~/.claude/projects/<project-key>/ 中的 .jsonl 文件
2. 包含在 --since 时间范围内修改的文件
3. 对于每个会话，沿父级链追溯（续接会话），以获取完整上下文
4. 按时间顺序排序（从最早到最新），确保叙述连贯

项目键是将绝对路径中的 / 替换为 - 后得到的字符串。例如：/Users/<you>/eon/cc-skills → -Users-<you>-eon-cc-skills

---

脚本调用参考

# Focused goal mode — recommended
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48         # Handoff: last 48 hours
  --goal 2 --since 168        # Error forensics: last week
  --goal 3 --since 720        # Summary: last month

# Debug: show extracted payload without calling the LLM
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48 --dry --verbose

# Override project dir (if auto-detection fails)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 2 --since 48 --project-dir ~/.claude/projects/-Users-foo-myrepo

# Skip parent chain tracing (faster, current window only)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 3 --since 48 --no-chain

# Legacy 50-perspectives mode (single session UUID)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  <session-uuid>

---

配置

设置	来源	默认值
LLM API 密钥	DEBRIEF_LLM_API_KEY（或 SUB2API_KEY）环境变量；否则使用运维人员的自主管理保险库：vault get cc-skills-tools-sub2api api_key	必填
LLM 端点	DEBRIEF_LLM_API_URL 环境变量，或 ${XDG_CONFIG_HOME:-~/.config}/cc-skills/debrief.env 中的 DEBRIEF_LLM_API_URL= 行	必填，无默认值
模型	DEBRIEF_LLM_MODEL 环境变量（未设置该变量；实际上是硬编码的）	claude-sonnet-5[1m]
最大输出 token 数	硬编码	每次调用 16384 个
上下文预算	硬编码	890K 个字符（约 243K 个 token）
默认时间范围	--since	48 小时
会话链式追溯	使用 --no-chain 禁用	已启用

---

查找最近的会话（手动）

# Sessions for current project (key = cwd with / replaced by -)
ls -lt ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl 2>/dev/null | head -10

# All projects, most recent first
ls -lt ~/.claude/projects/*/*.jsonl 2>/dev/null | head -20

---

故障排除

问题	原因	解决方法
Cannot determine project dir	当前工作目录不是已知项目	使用 --project-dir ~/.claude/projects/<key>
No sessions found	时间范围内没有会话	增大 --since（例如，使用 --since 336 表示 2 周）
could not resolve the debrief LLM key	环境中没有密钥，且密钥库查找失败	导出 DEBRIEF_LLM_API_KEY，或使用 vault set cc-skills-tools-sub2api api_key 保存一次
no LLM endpoint configured (exit 78)	未设置 DEBRIEF_LLM_API_URL	导出该变量，或将其添加到 ~/.config/cc-skills/debrief.env
context window exceeds	单个会话过大	使用 --dry --verbose 检查大小；尝试使用 --no-chain
输出分成多个 PART 部分到达	部分分析过大，无法合并	这是预期行为——每个部分涵盖一定范围的轮次

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。——编辑前，找到此 SKILL.md 的规范路径。
1. 出了什么问题？——修复导致问题的指令。
2. 哪些地方比预期更顺利？——将其纳入推荐实践。
3. 哪些内容出现偏差？——修复与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。——添加演进日志条目，注明触发原因、修复内容和证据。

切勿拖延。下一次调用会继承你留下的一切。