Session Log — 关 session 前写摘要

用户要在结束本次 chat 之前留下可检索记录，避免「几天前改过什么但找不到对应 session」。 chat 侧边栏只能按标题/时间浏览，这个归档 + 索引是刻意为之的可搜索层；检索用 session-search，本 skill 只负责写入。

你的任务：回顾当前对话，写一份结构化 session 摘要到全局归档目录，并生成 suggested_chat_title。

平台：时间解析（session_times.py）与 upsert（session_resolve.py）支持 Cursor、 Claude Code 和 Codex；脚本会自动识别 transcript 格式。存量回填（session_backfill.py） 仍仅支持 Cursor。

0. 执行边界与效率

• session-log 只做归档；不要顺带 commit、补文档或重跑项目测试，除非用户明确同时要求。
• 第一轮并行收集 transcript 时间、Git 事实、template、index 和已有 target；不要逐项串行读取。
• session_times.py 返回 fallback: false 时直接采用，不再人工重扫 transcript。
• resolve 后集中写归档、更新 index、register 映射，避免为每个字段单开工具轮次。

1. 确定项目

按优先级：

1. 用户 @ 的路径所在项目（含 CLAUDE.md / AGENTS.md 的子目录根）
2. 从 cwd 向上找最近的 CLAUDE.md、AGENTS.md 或 git 根
3. 多项目并列时，以主要改动最多的那个为准；不确定则问用户

记为 {PROJECT}（绝对路径）。元信息字段：

日志目录（全局，固定）：~/_sxg/llm_session_log/

不存在则创建。归档按机器独立（~ 各自解析），本 skill 只写本机归档。 各项目下的 _sxg/session_log/ 已废弃，勿再写入。

2. 收集事实（先读再写，不要编造）

从当前对话提取：

• 用户原始目标 / 问题演变
• 实际完成的工作（含文件路径、行为变化）
• 关键决策、踩坑、未竟事项
• 用户明确说「以后再做」的内容

若 {PROJECT} 是 git 仓库，运行：

git -C "{PROJECT}" log --oneline -15
git -C "{PROJECT}" status -sb

把本 session 相关的 commit 写进摘要（hash + 一行说明）。无关的旧 commit 不要堆。

3. 时间与 upsert 解析（必须先跑脚本）

禁止用执行 /session-log 的当前时刻填时间。用户可能隔几小时或几天才来整理归档。

先把适合当前 shell 的 Python 3 调用前缀记为 {PYTHON_CMD}，并实际运行 --version 验证； PowerShell 调用绝对路径时前缀包含 &，WindowsApps 占位程序不算可用。Codex Desktop 的 PATH 没有 Python 时，用 workspace dependencies 返回的 bundled Python 绝对路径。脚本只依赖标准库。

3.1 时间 — session_times.py

从当前 SKILL.md 的目录解析为 {SKILL_DIR}，不要猜客户端安装根：

{PYTHON_CMD} "{SKILL_DIR}/scripts/session_times.py" --transcript "{当前 session transcript 的绝对路径}" --save-temp

transcript 路径（按优先级）：

1. system 注入的当前 transcript 绝对路径
2. --uuid {uuid}（Codex 优先用已设置的 CODEX_THREAD_ID）自动查找 Cursor agent-transcripts/、Claude ~/.claude/projects/**/*.jsonl 或 Codex $CODEX_HOME/sessions/**/rollout-*-{uuid}.jsonl

Codex 查找必须按 rollout 文件名精确匹配 UUID，禁止全文 grep；subagent transcript 即使正文带 root UUID 也不能冒充 root session。

保留输出 JSON（含 session_id、date、time、filename_ts、started_at、 last_active_at、logged_at）。--save-temp 让脚本自己把同一份 JSON 写进操作系统临时 目录（Python tempfile，三平台通用），路径在输出的 times_json_path 字段，记为 {TIMES_JSON_PATH}。

{TIMES_JSON_PATH} 只能在操作系统临时目录或 ~/_sxg/llm_session_log/，绝不能写进项目树 或 Git 候选 / worktree：不要用 shell 重定向、Write 工具或手写文件落到 cwd。生产卡的候选里 多出一个未跟踪文件，交付 saga 会判脏树拒绝落位并反复重试（TODOHUB-291 实撞 .tmp_session_times.json，删掉后才自动恢复）。session_resolve.py 对落在 Git 工作树里的 --times-json 直接报 times_json_inside_git_worktree 并退出——撞到就删掉那个文件，改用 --save-temp 重跑。

3.2 命名（先定 slug，再 resolve）

suggested_chat_title 日期前缀用 session 开始日（date 的 YYMMDD）。

3.3 Upsert — session_resolve.py

{PYTHON_CMD} "{SKILL_DIR}/scripts/session_resolve.py" --uuid "{session_id}" --times-json "{TIMES_JSON_PATH}" --project "{project}" --slug "{slug}"

session_resolve.py 读完 --times-json 立即删掉该文件（第一次运行即消费，重跑 resolve 要 先重跑 session_times.py --save-temp）；后续步骤用的时间字段取自 3.1 已保留的输出。

session_times.py 会按 transcript 自动区分 Cursor / Claude / Codex； session_resolve.py 的 UUID upsert 逻辑三端共用。若 fallback: true，才允许人工核对并填写时间。

4. 写文件

路径：以 resolve 的 target_path 为准（不要自行拼新文件名）。

create：按 references/template.md 新建；frontmatter 必须含 session_id。

update：

1. Read 现有 md
2. 保留 session_id、date（开始日不变）
3. 更新 time、last_active_at、logged_at、summary、正文各节
4. 禁止 rename 文件
5. 文件末尾若有 ## Vault 精选 一节，原样保留在末尾——它由 zettel-distill 维护， session-log 不写、不删、不改（见 references/template.md 末尾说明）

5. 更新 index

行格式：

| {date} | {project} | [{session_title}]({target_file}) | {一行 summary} | `{suggested_chat_title}` |

index「日期」= session 开始日。

6. 登记映射

写入成功后运行：

{PYTHON_CMD} "{SKILL_DIR}/scripts/session_resolve.py" --register --uuid "{session_id}" --file "{target_file}" --started-at "{started_at}" --chat-title "{suggested_chat_title}"

维护 ~/_sxg/llm_session_log/.session_map.json（勿手改）。--chat-title 是 Claude Code Desktop --ccd-pending 补历史遗留标题（见第 7 步）的数据来源，所有客户端都带上，无害。

7. 回复用户

若本次在 Git 候选 / worktree 里收口（尤其生产卡：交付后系统直接落位上线），把卡移入 in_review、或结束会话交给派发器触发交付 saga 之前，先跑 git -C "{候选树}" status --short 确认输出为空；有残留就删掉或 commit 进候选再交付，不留给 saga 撞脏树。

第 4–6 步全部成功后，再用简短中文告知：

1. 新建或更新同一条，以及路径
2. date / time 来源；若 fallback 则说明
3. 检索：~/_sxg/llm_session_log/index.md；不够时 agent 用 session-search
4. 处理 suggested_chat_title：
   • 宿主提供直接修改当前 task/thread 标题的工具时，调用该工具；Codex Desktop 通常为 codex_app__set_thread_title，省略 threadId 以定位当前 task。工具返回成功后只需告知 用户“任务已重命名为 {suggested_chat_title}”，不要再输出 /rename 或要求用户操作。 Claude Code Desktop 是例外，见下一条。

   • Claude Code Desktop（mcp__ccd_session_mgmt__* 工具可见；deferred 时先用 ToolSearch 加载 set_session_title）：调用 set_session_title(session_id="self", title="{suggested_chat_title}") 直接改当前 session（app ≥ 1.32352 支持）。 session_id 必须传字面量 "self"：传自己的 local_* id 会被拒（"Refusing to rename the current session from within itself"），经 subagent 转发或改 claude-code-sessions 注册 JSON 同样无效，不要再试。成功后告知用户已重命名。 再顺手运行

     {PYTHON_CMD} "{SKILL_DIR}/scripts/session_resolve.py" --ccd-pending --uuid "{session_id}"

     对输出 pending 中的每项调用 set_session_title，补上历史遗留未改名的其他 session（用户手动改过的标题会自动跳过）。

   • 只有当前客户端已明确识别为 Claude、Cursor 或 Codex CLI/TUI，且确认该 surface 支持 /rename 时，才在回复最后一行单独输出 /rename {suggested_chat_title}。 Claude/Cursor 环境若已安装 Stop hook auto_rename_on_stop.py，会经 tmux send-keys 自动执行；Codex CLI/TUI 可由用户执行。
   • Codex Desktop 的工具缺失、失败或结果含糊时，不回滚已成功归档，不输出它不支持的 /rename；明确说未完成重命名，并给出标题供用户在 UI 手动修改。
   • 未知客户端只给标题建议，不假定它支持 slash command；直接标题工具不可见并不能证明 /rename 可用。不得声称已改好。

不要继续写无关代码，除非用户接着提新任务。

8. 与 handoff / 项目 changelog 的边界

若用户既要关 session 又要交接，先完成 session-log，再询问是否另跑 /handoff。

9. 存量回填（一次性）

脚本 scripts/session_backfill.py：从 Cursor transcript 写入记录反查 uuid，注入 session_id 并生成 .session_map.json。

python3 ~/.cursor/skills/session-log/scripts/session_backfill.py          # 预览
python3 ~/.cursor/skills/session-log/scripts/session_backfill.py --apply  # 写入

同一 chat 重复归档会先合并（见脚本内 MERGE_GROUPS），再回填。

存量 backfill 仅支持并测试 Cursor。