mcpField
L
log-session

log-session

github.com/gtrabancoAgent 工作流2289 次安装今天更新
代码仓库

关于 log-session

log-session 是用于记录工作会话目标、决策和后续步骤的 Agent 技能，将叙述背景与经 Git 核实的事实结合，并要求追加日志后提交。

主要功能

  1. 01以追加方式记录会话
  2. 02核实会话的 Git 事实
  3. 03生成并提交日志条目
  4. 04提供恢复工作的指引
  5. 05支持其他 Agent 的工作流

适用场景

  1. 01清除 Agent 会话前保存上下文
  2. 02在暂停时记录决策和后续步骤
  3. 03帮助团队成员从项目日志恢复工作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gtrabanco/agentic-workflow --skill log-session

安装后在 Claude Code 中输入/log-session确认已加载。

详细介绍

会话日志

记录工作会话的缘由和后续计划——这些上下文单靠 git 历史永远无法留存。提交说明了改了什么；会话日志则说明你当时想做什么、做了哪些决定，以及下次该从哪里继续。

刻意保持低成本（qwen3.6/reasoning_config: none——不限量；NaN 集群模型没有令牌计数器，因此这项技能消耗的是字节，而非配额）：进行结构化摘要，而非判断。绝不能调用昂贵的模型。

回合约定——结束回合前核对

✓ The entry was APPENDED to docs/LOGS.md (file edited, not just drafted) with accurate git facts
✓ `bun scripts/session-close.mjs close` RAN and exited 0 (or 2, with the leftover paths named) — the entry is committed, not left riding along
✓ No past entry was edited
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

准备结束回合，但仍有任何一项未勾选？回合就尚未完成——先完成缺失项（能力较弱的模型会漏掉文档末尾的职责；因此特意把这份清单放在最前面）。

何时使用

  • 执行 /clear 前（或 Agent 的等效上下文重置操作前）——你即将清除上下文；先记录下来。
  • 当天关闭 Agent 前。
  • 在自然的停顿点——例如功能做到一半暂停，或有一段你希望之后能在没有上下文的情况下接续的工作。
  • 长时间会话结束后，尤其是其中有多个值得记住的决定时。

这是对 template/ 提供的轻量自动日志钩子的手动、详尽补充（参见 template/.claude/）。钩子会在每次退出时免费记录机械性事实；而在你需要时，这项技能会写下经过深思熟虑的记录。

步骤 0 — 了解项目（始终先做）

根据 Agent 指南中的工作流约定和文档地图，找到会话日志。默认路径：docs/LOGS.md。如果文档地图指定了其他位置，就使用该位置。如果日志文件尚不存在，就按照 template/docs/LOGS.md 中的结构（简短的标题和下方的条目格式）创建，并说明这一点。

如果存在会话开始标记（由模板的 SessionStart 钩子写入的 .claude/.session-*.start），请读取它，以精确界定会话范围——其中包含会话开始时的 HEAD SHA 和开始时间。

流程

  1. 确定会话边界。

    • 如果存在标记，会话范围为 marker_sha..HEAD，以及所有未提交的工作。
    • 否则，以你自己的对话上下文为准，确定本次会话中发生的事情，并通过近期提交的 git log 和未提交更改的 git status / git diff --stat 进行佐证。

  2. 收集机械事实（用 git 快速完成）：

    • 分支（git branch --show-current），
    • 本次会话的提交（git log --oneline <since>..HEAD），
    • 修改的文件（git diff --stat <since>..HEAD + 未提交更改）。

  3. 撰写叙述——这是只有你能补充的部分：

    • **摘要：**用 1–3 句话说明本次会话旨在完成什么，以及实际完成了什么。
    • **决策：**记录不显而易见的选择及其理由（否则这些理由会丢失）。链接相关文档/问题。
    • **下一步：**具体的后续步骤——要运行的命令、尚未完成的事项或待解答的问题。写清楚，让刚接手的读者确切知道从哪里继续。
    • **状态词须经代码托管平台核实。**写入任何 PR/问题的状态声明前，都要在同一轮中通过代码托管平台进行核实（gh pr view <N> --json state,mergedAt）。如果日志记录的状态与平台不符，就是错误记录，下一次审查还得追查（修复 #157 的 F14）。写实际状态：“PR #N 仍处于开放状态，等待人工合并”。

  4. 生成条目——机械事实（时间戳、分支、提交数和范围、修改的文件）会自动计算：

    bun scripts/session-close.mjs render --summary "<what this session did>" \
  --decisions "<key choices + why>" --next "<the concrete next step>"

    它不会写入任何内容：使用编辑工具将其输出追加到 docs/LOGS.md 末尾（仅追加，按时间顺序）。没有实际内容时，省略 --decisions / --next——脚本会删除对应行，而不会输出空行。用户提供的备注会放在摘要前面。

  5. 结束会话——提交条目并证明工作区干净：

    bun scripts/session-close.mjs close

    除非 docs/LOGS.md 有追加内容（重写或截断日志不算会话条目），否则脚本会拒绝执行；脚本会将该文件作为唯一文件提交，提交信息为 docs(log): <the appended summary>，并报告所有仍未提交的路径：工作区干净时退出码为 0，列出的遗留更改仍未提交时为 2，拒绝执行时为 1。不要仅为日志条目创建 PR，也绝不要在这里运行 git add -A——否则可能会把并行对话中的工作一并纳入日志提交。

规范的职责划分——本技能负责的部分（功能 66，D2）

有意设置两种记录方式；两者互不照搬：

  • docs/LOGS.md（本技能）是团队人工日志——记录会话旨在完成什么、做出了哪些决定，以及后续从哪里继续。它随 git 一同流转，因此队友或全新克隆的仓库都能在没有本地状态的情况下读取。
  • Engram（mem_session_summary，以及该单元的 unit/<NN-slug>/doc 主题）是按单元 ID 索引的本地决策和易错点记录，由 unit-lane 和 execute-phase 在单元边界处写入。它保留在本机。

Engram 不会照搬此日志，此日志也不会照搬 Engram：团队记忆随 git 流转，Agent 回忆保留在本地。在此记录团队日志部分；协议部分（边界、回忆顺序、降级处理）位于工作通道的记忆参考文档 ../unit-lane/references/MEMORY.md 中。

规范

  • 绝不为此使用昂贵的模型。 这是摘要任务；在集群计划中，qwen3.6（reasoning_config: none → 零思考令牌）是合理的上限，而 hooks 会免费完成机械化操作。
  • 不要编造事实。 决策和后续步骤必须来自实际会话（你的上下文 + git），而不是听起来合理的填充内容。如果某个部分没有真实内容，就省略那一行，不要凑数。
  • 只追加，绝不重写。 以往条目是历史记录——不要编辑或“整理”它们。理由与不重写已交付功能的规划文档相同。
  • 只用一个文件，只追加。 不要把会话日志分散到多个文件中。

可移植性（Claude Code 以外的 Agent）

工作流是约定；Claude Code 功能只是便利工具。如果 Agent 缺少某项功能，就使用备用方案——绝不要跳过该功能所支持的步骤：

  • 没有 Claude Code hooks——模板的自动日志 hooks（SessionStart 标记、SessionEnd 条目）不会在其他 Agent 上运行，因此不会有标记文件，也不会自动生成条目：此技能是唯一的日志撰写者。每次会话结束前都要运行此技能，并且仅用 git 界定会话（Process 步骤 1 中无标记文件的路径）。
  • 没有 /clear——在触发条件和收尾部分中，都将其理解为你的 Agent 的上下文重置／新对话等效操作。
  • 没有按技能设置的 model:／effort:——意图不变：为此使用最便宜的可用模型。这是摘要任务，而非判断任务。在 NaN 上，集群模型（qwen3.6、gemma4）没有令牌计数器——设置 reasoning_config: none，这样追加条目不会消耗思考令牌。

与其他技能的关系

  • 与 template/ 的 SessionEnd hook（免费、机械化；在 /clear 和退出时自动运行）以及选择启用的 SessionStart 恢复 hook（重新注入上一条目以恢复上下文）相辅相成。此技能负责撰写内容丰富的手动条目。
  • 与 execute-phase 的按功能划分的 progress.md 配合使用：它记录单个功能内部的进度；会话日志则是跨功能的——记录本次会话中你处理的所有内容，跨越功能和修复。
  • 不属于 PR 门禁——它是工作记忆辅助工具，不是合并产物。

完成条件

  • 已在 docs/LOGS.md 中追加新条目，至少包含 Summary 和 Next。

  • 机械事实（分支、提交、文件）与 git 记录相符。

  • 已打印收尾的 → Next: 区块：

    → Next: /clear (or your agent's context reset) is now safe — the session is captured
  · resume later → the command named in the entry's **Next** line

评论

支持 Markdown