---
name: chat-history-extractor
description: Extract and render chat history from OpenClaw session URLs. Use when user provides a URL like https://claw1.kekouen.cn/chat?session=agent%3Ac108-v1-1811%3Amain containing a session key. The skill parses the URL, finds the corresponding chat JSONL file, and generates a JS data file for rendering. Also provide template HTML for visualizing the conversation with timing metrics.
---

# Chat History Extractor

## Workflow

### Step 1: Parse URL and Extract Session Key

From URL like `https://claw1.kekouen.cn/chat?session=agent%3Ac108-v1-1811%3Amain`:

1. URL-decode the `session` query parameter
2. The decoded session key is `agent:c108-v1-1811:main`

### Step 2: Find Session JSONL File

Session files are stored at:
```
/root/.openclaw/agents/{agentId}/sessions/sessions.json
```

For session key `agent:c108-v1-1811:main`:
- Agent ID: `c108-v1-1811`
- Session file: `/root/.openclaw/agents/c108-v1-1811/sessions/sessions.json`

Look up the session key in `sessions.json` to find the `sessionFile` path (e.g., `5bee9664-7b72-4efd-8dc1-e8bf125c6b9c.jsonl`).

### Step 3: Parse JSONL and Build Conversation Pairs

The JSONL contains message events. Parse them with this logic:

1. Filter for `type == "message"` events
2. For each user message, collect ALL consecutive assistant messages until the next user message
3. Combine multiple AI responses into one reply per user message
4. Skip `toolResult` events (they're tool outputs, not user/AI messages)

**Important pairing rules:**
- A user message pairs with the first assistant message that follows
- If the assistant sends multiple messages before the next user message, merge ALL of them into one AI reply
- AI messages with empty text content (just tool calls) should be skipped
- Use `toolResult` to skip over intermediate tool outputs

### Step 4: Generate JS Data File

Output a JS file with this structure:

```javascript
const chatData = {
  "session": "session-name",
  "session_id": "uuid",
  "total_pairs": N,
  "initiator": "who started this conversation",
  "conversations": [
    {
      "user": "full user message text",
      "user_time": "2026-05-14 18:11:56",
      "ai": "full AI reply (merged if multiple messages)",
      "ai_time": "2026-05-14 18:12:18"
    },
    ...
  ]
};
```

### Step 5: Render with Template HTML

Use the template at `assets/chat-history-template.html` to render the conversation.

Copy the template to the output directory alongside the JS file. The template supports:
- Displaying conversation pairs
- Computing and showing three timing metrics per pair:
  - **课程流逝** (elapsed time since first message)
  - **回复耗时** (AI response time = AI time - user time)
  - **间隔耗时** (gap to next user message)
- Rich visual styling with color-coded timing badges

## Usage Example

User provides: `https://claw1.kekouen.cn/chat?session=agent%3Ac108-v1-1811%3Amain`

1. Extract session key: `agent:c108-v1-1811:main`
2. Find JSONL at: `/root/.openclaw/agents/c108-v1-1811/sessions/5bee9664-7b72-4efd-8dc1-e8bf125c6b9c.jsonl`
3. Parse and generate: `聊天记录.js`
4. Copy template: `聊天记录.html`
5. User opens `聊天记录.html` to view the rendered conversation
