chat-history

聊天历史提取器

从 Claude Code 会话历史记录（~/.claude/projects/）中提取用户输入，并将其整理到项目的 .chats 目录中，按日期保存为 Markdown 文件。

何时使用此技能

在用户希望执行以下操作时使用此技能：

• 提取会话历史记录，从 Claude Code 会话中提取
• 记录对话，以供日后参考
• 创建指令日志，并按日期整理
• 导出用户输入，从 .jsonl 会话文件中导出
• 维护变更日志，记录与 Claude 的交互

工作原理

Claude Code 将会话数据以 .jsonl 文件的形式存储在 ~/.claude/projects/{project-path-encoded}/ 中。每个文件包含以下消息：

• type: "user" - 用户消息
• userType: "external" - 外部用户（非系统或 Agent）
• message.content - 实际消息内容

此技能会提取有意义的用户指令（过滤掉系统命令、工具结果和会话续接消息），并按日期整理到 .chats/{YYYYMMDD}.md 文件中。

指令

步骤 1：确定项目会话目录

会话目录根据当前工作目录路径生成：

• 将路径中的 / 替换为 -
• 在前面加上 -
• 位置：~/.claude/projects/{encoded-path}/

# Example: /Users/tchen/projects/tubi/titc
# Becomes: -Users-tchen-projects-tubi-titc
# Full path: ~/.claude/projects/-Users-tchen-projects-tubi-titc/

步骤 2：按日期查找会话文件

列出会话文件，并按修改日期筛选：

# List all main session files (excluding agent-* files) for a specific date
ls -la ~/.claude/projects/{project-dir}/*.jsonl | grep "Dec 25" | grep -v agent-

步骤 3：提取用户输入

使用 jq 从 jsonl 文件中提取用户消息：

cat {session-file}.jsonl | jq -r '
  select(.type == "user" and .userType == "external" and (.isMeta | not)) |
  .message.content |
  if type == "string" then . else empty end
' | grep -v "^Caveat:" \
  | grep -v "^<command" \
  | grep -v "^<local-command" \
  | grep -v "^This session is being continued" \
  | grep -v "^<user-prompt-submit-hook>" \
  | grep -v "^Analysis:" \
  | grep -v "^$"

步骤 4：创建或更新 .chats 文件

按照以下格式在 .chats/ 目录中创建 Markdown 文件：

# Instructions

## {task title}

{user instruction}

## {another task title}

{another user instruction}

步骤 5：提交更改

创建或更新聊天文件后，使用以下命令提交：

git add .chats/*.md
git commit -m "docs(chats): add session history for {date range}"

文件格式

每个 .chats/{YYYYMMDD}.md 文件应：

• 以 # Instructions 标题开头
• 使用 ## 标记每项主要任务或指令
• 包含实际的用户输入文本
• 将相关指令归到同一标题下
• 保留代码块和格式

输出示例

.chats/20251225.md：

# Instructions

## implement feature X

based on @specs/feature-x.md implement all phases entirely

commit the code and test

## fix bug Y

investigate why component Z is not working

use sub agents to analyze the issue in parallel

筛选规则

包含：

• 用户的直接指令和请求
• 关于代码库的问题
• 任务说明和要求

排除：

• 系统命令（<command-name>、<local-command-stdout>）
• 会话续接消息
• 工具结果和 Agent 回复
• 钩子通知（<user-prompt-submit-hook>）
• 空行和注意事项消息

工作流摘要

1. 获取当前工作目录
2. 计算编码后的项目路径
3. 查找会话目录：~/.claude/projects/{encoded-path}/
4. 按日期列出会话
5. 对于每个包含会话的日期：
   • 从所有会话中提取用户输入
   • 创建 .chats/{YYYYMMDD}.md
   • 使用描述性标题整理输入
6. 如果 .chats/ 目录不存在，则创建该目录
7. 可选：提交更改

辅助脚本

可以使用以下 bash 代码片段快速查找项目会话目录：

# Get encoded project path
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^|/|' | sed 's|^/|-|')
SESSION_DIR="$HOME/.claude/projects/$PROJECT_PATH"

# Check if exists
if [ -d "$SESSION_DIR" ]; then
    echo "Session directory: $SESSION_DIR"
    echo "Sessions by date:"
    ls -la "$SESSION_DIR"/*.jsonl 2>/dev/null | grep -v agent- | awk '{print $6, $7}' | sort -u
else
    echo "No session directory found for this project"
fi

注意事项

• 名为 agent-*.jsonl 的会话文件属于子 Agent 会话，通常不包含直接的用户输入
• 主会话文件采用 UUID 格式的名称（例如，01e78099-de0e-4424-845c-518638c8241e.jsonl）
• .message.content 字段可以是字符串（用户文本）或数组（工具结果）
• 提交前始终确认提取的内容合理