mixtiles-monthly

每月自动化照片到 Mixtiles 管道。从 WhatsApp 群组收集照片，利用视觉筛选最佳照片，构建多照片 Mixtiles 购物车链接并将其发送。当需要每月 Mixtiles 订单时、当被要求“运行每月图块”、“收集图块的家庭照片”或每月 cron 触发器时使用。

# Mixtiles Monthly Pipeline

Automatically collect the best family photos from a WhatsApp group each month, curate them, and generate a ready-to-order Mixtiles cart link.

## Configuration

These environment variables control the pipeline. Set them before running:

| Variable | Description | Default |
|----------|-------------|---------|
| `MIXTILES_GROUP_JID` | WhatsApp group JID to collect photos from | *(required)* |
| `MIXTILES_SEND_TO` | Where to send the cart link (group JID or phone number) | Same as `MIXTILES_GROUP_JID` |
| `MIXTILES_PHOTO_COUNT` | How many photos to select | `4` |
| `MIXTILES_TILE_SIZE` | Tile size for the order | `RECTANGLE_12X16` |

## Pipeline Steps

### Step 1: Collect Photos

Calculate the date range for last month and download all photos from the group:

```bash
# Calculate first day of last month
YEAR_MONTH=$(date -v-1m +%Y-%m)  # macOS
AFTER_DATE="${YEAR_MONTH}-01"
OUTPUT_DIR=~/mixtiles-queue/${YEAR_MONTH}

# Run the collection script
bash <skill-dir>/scripts/collect-photos.sh "$MIXTILES_GROUP_JID" "$AFTER_DATE" "$OUTPUT_DIR"
```

The script outputs a JSON manifest on stdout with `{id, sender, timestamp, filepath}` for each downloaded photo.

### Step 2: Curate with Vision

Read each downloaded photo using your vision capability. For each photo, evaluate:

**Include if:**
- Real family/life moment (people, gatherings, milestones, kids, travel, pets)
- Good image quality (clear, well-lit, in focus)
- Unique scene (not a near-duplicate of another photo)

**Exclude if:**
- Screenshot, meme, forwarded image, or link preview
- Blurry, too dark, or very low quality
- Near-duplicate of a better version already selected
- Text-heavy image (WhatsApp forwards, news articles)
- Promotional content or ads

### Step 3: Select Top Photos

From the curated set, pick the top `$MIXTILES_PHOTO_COUNT` photos (default: 4). Prioritize:
1. People and faces (especially kids, family gatherings)
2. Milestone moments (birthdays, first steps, graduations)
3. Travel and experiences
4. Variety — don't pick 4 photos from the same event if there are others

If fewer than `$MIXTILES_PHOTO_COUNT` good photos exist, use whatever passes curation.

### Step 4: Build Multi-Photo Cart

Use the mixtiles-it skill's script with the `--batch` flag:

```bash
MIXTILES_CART_SCRIPT="$(find ~/.openclaw/workspace/skills/mixtiles-it/scripts -name 'mixtiles-cart.py')"

python3 "$MIXTILES_CART_SCRIPT" \
  --batch <photo1> <photo2> <photo3> <photo4> \
  --size "${MIXTILES_TILE_SIZE:-RECTANGLE_12X16}"
```

This uploads each photo to Cloudinary and outputs a single Mixtiles cart URL with all photos.

### Step 5: Send the Link

Send the cart link to the target chat:

```bash
SEND_TO="${MIXTILES_SEND_TO:-$MIXTILES_GROUP_JID}"

wacli send text \
  --to "$SEND_TO" \
  --message "Your monthly tiles are ready! Here are the best ${MIXTILES_PHOTO_COUNT:-4} photos from last month. Tap to customize and order: $CART_URL"
```

## Error Handling

- If `collect-photos.sh` finds 0 photos: report that no images were found for the period and skip the pipeline.
- If fewer photos pass curation than `MIXTILES_PHOTO_COUNT`: use all that passed — even 1 photo is worth sending.
- If Cloudinary upload fails for a photo: skip that photo, continue with the rest.
- If `wacli send` fails: print the cart URL so the user can send it manually.

## Manual Trigger

To run the pipeline outside the monthly schedule:

> Run the mixtiles-monthly skill: collect photos from the family group for the past month, curate the best ones, build a multi-photo cart link, and send it.

---

## 中文说明

# Mixtiles 每月管道

每月自动从 WhatsApp 群组收集最佳家庭照片，进行筛选，并生成可直接下单的 Mixtiles 购物车链接。

## 配置

以下环境变量控制该管道。运行前请设置好：

| 变量 | 说明 | 默认值 |
|----------|-------------|---------|
| `MIXTILES_GROUP_JID` | 用于收集照片的 WhatsApp 群组 JID | *（必填）* |
| `MIXTILES_SEND_TO` | 购物车链接发送目标（群组 JID 或电话号码） | 同 `MIXTILES_GROUP_JID` |
| `MIXTILES_PHOTO_COUNT` | 要选择的照片数量 | `4` |
| `MIXTILES_TILE_SIZE` | 订单的图块尺寸 | `RECTANGLE_12X16` |

## 管道步骤

### 步骤 1：收集照片

计算上个月的日期范围，并下载群组中的所有照片：

```bash
# Calculate first day of last month
YEAR_MONTH=$(date -v-1m +%Y-%m)  # macOS
AFTER_DATE="${YEAR_MONTH}-01"
OUTPUT_DIR=~/mixtiles-queue/${YEAR_MONTH}

# Run the collection script
bash <skill-dir>/scripts/collect-photos.sh "$MIXTILES_GROUP_JID" "$AFTER_DATE" "$OUTPUT_DIR"
```

该脚本在标准输出上输出一个 JSON 清单，其中为每张已下载照片提供 `{id, sender, timestamp, filepath}`。

### 步骤 2：用视觉能力筛选

使用你的视觉能力读取每张已下载的照片。对每张照片进行评估：

**包含的条件：**
- 真实的家庭/生活瞬间（人物、聚会、里程碑、孩子、旅行、宠物）
- 良好的图像质量（清晰、光线充足、对焦准确）
- 独特的场景（不与另一张照片几乎重复）

**排除的条件：**
- 截图、表情包、转发图片或链接预览
- 模糊、过暗或质量极低
- 与已选的更佳版本几乎重复
- 文字密集的图像（WhatsApp 转发、新闻文章）
- 推广内容或广告

### 步骤 3：选出最佳照片

从筛选后的集合中，挑选出排名前 `$MIXTILES_PHOTO_COUNT` 的照片（默认：4 张）。优先考虑：
1. 人物和面孔（尤其是孩子、家庭聚会）
2. 里程碑时刻（生日、第一次走路、毕业）
3. 旅行和体验
4. 多样性——如果还有其他照片，不要从同一场活动中选 4 张

如果合格的好照片少于 `$MIXTILES_PHOTO_COUNT` 张，则使用所有通过筛选的照片。

### 步骤 4：构建多照片购物车

使用 mixtiles-it 技能的脚本，并带上 `--batch` 标志：

```bash
MIXTILES_CART_SCRIPT="$(find ~/.openclaw/workspace/skills/mixtiles-it/scripts -name 'mixtiles-cart.py')"

python3 "$MIXTILES_CART_SCRIPT" \
  --batch <photo1> <photo2> <photo3> <photo4> \
  --size "${MIXTILES_TILE_SIZE:-RECTANGLE_12X16}"
```

这会将每张照片上传到 Cloudinary，并输出一个包含所有照片的单一 Mixtiles 购物车 URL。

### 步骤 5：发送链接

将购物车链接发送到目标聊天：

```bash
SEND_TO="${MIXTILES_SEND_TO:-$MIXTILES_GROUP_JID}"

wacli send text \
  --to "$SEND_TO" \
  --message "Your monthly tiles are ready! Here are the best ${MIXTILES_PHOTO_COUNT:-4} photos from last month. Tap to customize and order: $CART_URL"
```

## 错误处理

- 如果 `collect-photos.sh` 找到 0 张照片：报告该时段未找到图片并跳过该管道。
- 如果通过筛选的照片少于 `MIXTILES_PHOTO_COUNT`：使用所有通过的照片——即使只有 1 张也值得发送。
- 如果某张照片 Cloudinary 上传失败：跳过该照片，继续处理其余照片。
- 如果 `wacli send` 失败：打印购物车 URL，以便用户手动发送。

## 手动触发

如需在每月计划之外运行该管道：

> 运行 mixtiles-monthly 技能：从家庭群组收集过去一个月的照片，筛选出最佳的照片，构建多照片购物车链接，并发送它。