# Time Window Sampler

> 时间窗口采样算子。读取JSONL时间序列记录，按指定时间窗口分组后在每个窗口内均匀抽取样本。 当用户提到按天抽样、按小时抽样、周期性抽样、时间窗口采样等需求时使用此skill。 即使用户没有明确说出"时间窗口采样"，只要任务涉及按时间粒度分组后抽样，就应该使用此skill。 不负责时间字段清洗、时间聚合统计或异常检测。

- Skill: `cas-bigdatalab/time-window-sampler` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cas-bigdatalab/time-window-sampler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cas-bigdatalab/time-window-sampler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cas-bigdatalab (https://skillmd.com/u/cas-bigdatalab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cas-bigdatalab/time-window-sampler

---


# TimeWindowSampler - 时间窗口采样算子

## 功能概述

按照时间窗口对数据进行采样，每个窗口内均匀抽取指定数量的样本。支持按天、小时、月、周等时间粒度，适用于时间序列数据的周期性抽样。

## 触发条件

当用户请求以下任务时，应使用此skill：
- 按天抽样
- 按小时抽样
- 周期性抽样
- 时间窗口采样
- 按时间粒度分组后抽样

## 核心参数说明

### 必需参数
- `--input`：输入JSONL文件路径
- `--output`：输出JSONL文件路径
- `--time_field`：时间字段名
- `--window_size`：窗口大小（如 `1d`、`2h`、`1m`、`1w`）

### 可选参数
- `--time_format`：时间格式字符串
- `--sample_per_window`：每个窗口采样数量，默认 `1`
- `--log_file`：日志文件路径

## 输入文件格式

输入文件必须是JSONL，每行一个JSON对象，且至少包含时间字段。时间字段应能被脚本识别为日期时间字符串。

## 使用方法

```bash
python scripts/run_time_window_sampler.py --input data.jsonl --output sampled.jsonl --time_field event_time --window_size 1d --sample_per_window 2
```

## 输出示例

```jsonl
{"id": 1, "event_time": "2025-06-01 00:15:00", "_time_window": "2025-06-01", "_window_sample_index": 0}
{"id": 7, "event_time": "2025-06-01 06:15:00", "_time_window": "2025-06-01", "_window_sample_index": 1}
```

## 环境要求

- Python 3.10+
- 标准库 `datetime`

## 注意事项

- 无法解析时间字段的记录会被跳过
- `_time_window` 标记窗口起点标签
- `_window_sample_index` 标记窗口内抽样顺序