round-robin-allocator

SKILL.md

---
name: round-robin-allocator
version: 1.0.1
description: >
  均匀轮转分配工具。将 N 个对象在 T 个轮次中，按比例分配 K 种选项，
  并通过贪心算法 + 迭代优化，尽量让每个对象每轮获得不同选项，最大化覆盖率。
tags: [分配, 算法, 可视化, 贪心, 轮转, allocation, greedy]
---

# 均匀轮转分配工具（Round-Robin Allocator）

## 一句话说明

> 给 N 个「对象」，在 T 个「轮次」中，按比例把 K 种「选项」分配出去，
> 并让每个对象每轮尽量拿到不同的选项。

典型场景：
- 33 个项目组，每周轮换 5 套方案，持续 4 周
- 100 名学生，每月分配 4 种学习策略，持续 6 个月
- 50 个广告位，每天按比例投放 3 种素材，持续 7 天

---

## 使用方式

### 方式 1：AI 对话（最自然）

直接告诉 AI：

```
我有 33 个项目，4 个周期，5 套方案，比例是 7:8:10:3:5，帮我做均匀轮转分配
```

AI 会自动调用本工具，生成分配结果并提供三种输出。

---

### 方式 2：命令行（普适，非 WorkBuddy 专属）

```bash
# 一行描述，自动解析
python scripts/main.py --input "33个项目，4个周期，5套方案，比例7:8:10:3:5"

# 自定义术语
python scripts/main.py --input "100名学生，6个月，4种策略，比例1:1:1:2" \
    --obj 学生 --slot 月 --option 策略

# 指定输出目录
python scripts/main.py --input "..." --outdir ./output/

# 交互式（逐步引导）
python scripts/main.py

# 不自动打开浏览器
python scripts/main.py --input "..." --no-open
```

---

## 输入格式说明（自动解析支持）

工具能识别多种描述方式，**不限定"项目/方案/周"**，理解逻辑即可：

| 描述示例 | 说明 |
|---------|------|
| `33个项目，4个周期，5套方案，比例7:8:10:3:5` | 中文，带比例 |
| `20 items, 3 rounds, 4 options, ratio 1:1:2:1` | 英文 |
| `N=50 T=6 K=3 ratios=1,2,1` | 键值对格式 |
| `33 4 5 7 8 10 3 5` | 纯数字（顺序：N T K r1 r2…） |
| `100名学生，每月（共6个月）分4种策略，策略权重2:1:1:1` | 自然语言 |

---

## 输出文件

每次运行生成三个文件（默认输出到当前目录）：

| 文件 | 格式 | 内容 |
|------|------|------|
| `allocation_result.md` | Markdown | 分配明细表 + 轮次分布统计 |
| `allocation_result.csv` | CSV | 机器可读数据，可导入 Excel |
| `allocation_result.html` | HTML | 可交互热力表格 + 分布图表（自动在浏览器打开） |

---

## AI 调用指引

当用户提出分配类需求时，AI 按以下流程调用：

### 步骤 1：识别意图与提取参数

识别关键词：轮转/分配/每轮/周期/覆盖/方案/选项 等

尝试从用户输入中解析：
- **N**：对象数量（项目/学生/用户/商品…）
- **T**：轮次数量（周/月/阶段…）
- **K**：选项数量（方案/策略/类型/颜色…）
- **ratios**：各选项比例

### 步骤 2：调用命令

```bash
# 工作目录切换到输出目标，然后：
python ~/.workbuddy/skills/round-robin-allocator/scripts/main.py \
    --input "<用户描述>" \
    --obj "<对象术语>" \
    --slot "<轮次术语>" \
    --option "<选项术语>" \
    --outdir "<输出目录>" \
    --no-open
```

### 步骤 3：展示结果

1. 读取 `allocation_result.md`，直接输出 Markdown 表格
2. 告知用户 CSV 和 HTML 文件路径
3. 用 `preview_url` 工具预览 HTML（WorkBuddy 环境）

### 步骤 4：交互优化（可选）

询问用户是否需要：
- 调整比例重新分配
- 更换术语重新命名
- 导出特定格式

---

## 算法说明

核心三阶段：

1. **配额生成**（Hamilton 大余数法）：按比例为每轮计算各选项的配额数，确保总和精确等于 N。
2. **贪心分配**：优先为覆盖率最低的对象分配"尚未出现过"的选项，最大化覆盖多样性。
3. **迭代优化**：对有重复选项的对象，尝试将重复选项替换为未覆盖选项（只要配额允许），直到无法继续改善。

**理论上限**：当 T ≥ K 时，所有对象均可实现 100% 覆盖。  
当 T < K 时，最高覆盖率 = T/K。

---

## 文件结构

```
round-robin-allocator/
├── SKILL.md              # 本文件
├── _meta.json            # Skill 元数据
└── scripts/
    ├── allocator.py      # 核心算法（纯标准库）
    ├── main.py           # CLI 入口（交互 + 一行解析 + 多格式输出）
    └── visualizer.py     # HTML 可视化生成器
```

---

## 依赖

- **Python ≥ 3.8**，仅使用标准库（`csv`, `json`, `re`, `pathlib`, `argparse`…）
- **无需安装任何第三方包**
- HTML 可视化使用 Chart.js（CDN），离线时表格正常显示，图表不可用

---

## 示例输出（Markdown 表格片段）

| 对象ID | 轮次1 | 轮次2 | 轮次3 | 轮次4 | 覆盖率 |
|--------|-------|-------|-------|-------|--------|
| 1      | 选项3 | 选项1 | 选项2 | 选项5 | 100%   |
| 2      | 选项2 | 选项4 | 选项1 | 选项3 | 100%   |
| 3      | 选项1 | 选项2 | 选项3 | 选项4 | 100%   |
| …      | …     | …     | …     | …     | …      |