Skip to content

valkryhx/google_adk_agent / skills/ciri_session_manager

ciri_session_manager

Verified

查询和导出 Ciri ADK Session 内容的工具。支持查询指定 Session 或最新 Session 的完整对话记录,导出为 JSON 格式,列出最近 Session 列表,以及全局搜索关键词。使用场景:(1) 需要查看某个 Session 的对话历史,(2) 需要将 Session 内容导出为 JSON 分享给他人,(3) 需要列出最近的 Session 列表,(4) 需要在所有 Session 中搜索特定关键词。

FileKindSize
SKILL.mdskill md8.0 KB
scripts/query_and_export_session.pyscript11.9 KB
tools.pyscript15.0 KB
---
name: ciri_session_manager
description: 查询和导出 Ciri ADK Session 内容的工具。支持查询指定 Session 或最新 Session 的完整对话记录,导出为 JSON 格式,列出最近 Session 列表,以及全局搜索关键词。使用场景:(1) 需要查看某个 Session 的对话历史,(2) 需要将 Session 内容导出为 JSON 分享给他人,(3) 需要列出最近的 Session 列表,(4) 需要在所有 Session 中搜索特定关键词。
---

# Ciri Session Manager

## 概述

Ciri Session Manager 是一个用于查询和导出 ADK Session 内容的工具。它可以:

1. **查询 Session 内容**:查看指定 Session ID 或最新 Session 的完整对话记录
2. **导出为 JSON**:将 Session 内容导出为结构化的 JSON 文件,便于分享和存档
3. **列出 Session**:显示最近的 Session 列表
4. **全局搜索**:在所有 Session 的历史消息中搜索特定关键词

该工具基于 `src/adk_agent/inspect_session.py` 的核心逻辑,专为 Session 查询和导出场景优化。

## 工具函数

本技能通过 `tools.py` 提供了以下可直接调用的工具函数:

### 1. `list_sessions(limit=10, db_path=None)`
列出最近的 Session 列表。

**参数:**
- `limit`: 返回的 Session 数量(默认 10)
- `db_path`: 数据库路径(可选,默认自动推导)

**返回:**
```python
{
    "success": True,
    "count": 5,
    "sessions": [
        {
            "id": 311,
            "app_name": "dynamic_expert",
            "user_id": "user_001",
            "session_id": "session_xxx",
            "session_metadata": "...",
            "created_at": "2026-03-18 03:05:21.702067"
        }
    ]
}
```

### 2. `get_latest_session(db_path=None)`
获取最新的 Session ID。

**返回:**
```python
{"success": True, "session_id": "session_xxx"}
```

### 3. `query_session(session_id, with_response=False, db_path=None)`
查询指定 Session 的完整对话内容。

**参数:**
- `session_id`: Session ID
- `with_response`: 是否显示工具响应内容
- `db_path`: 数据库路径(可选)

**返回:**
```python
{
    "success": True,
    "session_id": "session_xxx",
    "message_count": 62,
    "messages": [
        {
            "id": 94699,
            "role": "user",
            "timestamp": "2026-03-18 03:10:45.375782",
            "text": "[Text]: ...",
            "content": {...}
        }
    ]
}
```

### 4. `export_session_to_json(session_id, output_path, include_raw=True, db_path=None)`
将指定 Session 导出为 JSON 文件。

**参数:**
- `session_id`: Session ID
- `output_path`: 输出文件路径
- `include_raw`: 是否包含原始 event_json 数据
- `db_path`: 数据库路径(可选)

**返回:**
```python
{
    "success": True,
    "message": "成功导出 62 条消息",
    "output_path": "/path/to/output.json",
    "message_count": 62
}
```

### 5. `export_latest_session_to_json(output_path, include_raw=True, db_path=None)`
导出最新 Session 为 JSON 文件。

**参数:**
- `output_path`: 输出文件路径
- `include_raw`: 是否包含原始 event_json 数据
- `db_path`: 数据库路径(可选)

**返回:**
同上

## 命令行工具

除了工具函数外,本技能还提供命令行工具 `scripts/query_and_export_session.py`:

### 1. 查询最新 Session

默认情况下,查询最新的 Session 内容:

```bash
python scripts/query_and_export_session.py
```

### 2. 查询指定 Session

通过 `--session-id` 参数指定要查询的 Session ID:

```bash
python scripts/query_and_export_session.py --session-id <SESSION_ID>
```

### 3. 导出 Session 为 JSON

将 Session 内容导出为 JSON 文件:

```bash
# 导出最新 Session
python scripts/query_and_export_session.py --output session_export.json

# 导出指定 Session
python scripts/query_and_export_session.py --session-id <SESSION_ID> --output session_export.json

# 导出时不包含原始 event_json(仅保留结构化内容)
python scripts/query_and_export_session.py --session-id <SESSION_ID> --output session_export.json --no-raw
```

### 4. 列出最近 Session

列出最近的 N 个 Session:

```bash
python scripts/query_and_export_session.py --list 10
```

### 5. 全局搜索关键词

在所有 Session 的历史消息中搜索特定关键词:

```bash
python scripts/query_and_export_session.py --search "关键词"
```

**示例**:
```bash
# 搜索包含"小伙计"的所有消息
python scripts/query_and_export_session.py --search "小伙计"

# 搜索包含"601919"的所有消息
python scripts/query_and_export_session.py --search "601919"
```

### 6. 显示工具响应内容

如果需要查看工具调用(如 bash/sql)的完整响应:

```bash
python scripts/query_and_export_session.py --session-id <SESSION_ID> --with-response
```

### 7. 指定数据库路径

如果数据库不在默认位置,可以指定:

```bash
python scripts/query_and_export_session.py --db /path/to/adk_sessions_port_8000.db
```

## 使用场景

### 场景 1: 分享 Session 对话

用户想要将某个 Session 的对话内容分享给他人:

**方式一:使用工具函数**
```python
from tools import export_session_to_json
result = export_session_to_json("session_xxx", "session_export.json")
```

**方式二:使用命令行**
```bash
python scripts/query_and_export_session.py --session-id session_xxx --output session_export.json
```

### 场景 2: 排查问题

需要查看某个 Session 的完整对话历史以排查问题:

**方式一:使用工具函数**
```python
from tools import list_sessions, query_session
sessions = list_sessions(10)  # 列出最近 10 个 Session
session_data = query_session("session_xxx", with_response=True)  # 查询详细内容
```

**方式二:使用命令行**
```bash
python scripts/query_and_export_session.py --list 10
python scripts/query_and_export_session.py --session-id session_xxx --with-response
```

### 场景 3: 存档 Session

需要将 Session 内容存档:

**方式一:使用工具函数**
```python
from tools import export_latest_session_to_json
result = export_latest_session_to_json("archive/session_20260318.json")
```

**方式二:使用命令行**
```bash
python scripts/query_and_export_session.py --output archive/session_20260318.json
```

### 场景 4: 全局搜索关键词

需要在所有历史对话中查找特定内容:

**方式一:使用命令行**
```bash
# 搜索所有包含"小伙计"的消息
python scripts/query_and_export_session.py --search "小伙计"

# 搜索所有包含"601919"的消息
python scripts/query_and_export_session.py --search "601919"
```

**说明**:
- 搜索会遍历所有 Session 的 `event_json` 字段
- 默认返回最近 15 条匹配记录
- 支持使用 `--with-response` 显示工具响应的详细内容


## 输出格式

导出的 JSON 文件包含以下结构:

```json
{
  "session_id": "xxx-xxx-xxx",
  "exported_at": "2026-03-18 11:10:45",
  "message_count": 10,
  "messages": [
    {
      "id": 1,
      "role": "user",
      "timestamp": "2026-03-18 11:00:00",
      "content": {
        "parts": [...]
      },
      "raw_event_json": {...}  // 仅在未使用 --no-raw 时包含
    }
  ]
}
```

## 数据库位置

默认数据库路径:
- 项目根目录下的 `sqlite_db/adk_sessions_port_8000.db`

如果自动推导失败,可以手动指定 `--db` 参数。

## 依赖

- Python 3.7+
- sqlite3(Python 内置)
- json(Python 内置)
- argparse(Python 内置)

## 注意事项

1. **当前 Session**:如果不指定 `--session-id`,默认使用最新的 Session
2. **输出目录**:如果输出路径包含不存在的目录,会自动创建
3. **编码**:所有输出文件使用 UTF-8 编码
4. **权限**:确保对数据库文件和输出目录有读写权限

## 文件结构

```
ciri_session_manager/
├── SKILL.md              # 技能说明文档
├── tools.py              # 工具函数定义(包含 get_tools 入口)
└── scripts/
    └── query_and_export_session.py  # 命令行工具
```

## 依赖

- Python 3.7+
- sqlite3(Python 内置)
- json(Python 内置)
- argparse(Python 内置)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall