round-robin-allocator

> 给 N 个「对象」，在 T 个「轮次」中，按比例把 K 种「选项」分配出去，

> 并让每个对象每轮尽量拿到不同的选项。

核心能力

• 自然语言解析：支持中英文混合描述（如「33个项目，4个月，5套方案，比例7:8:10:3:5」）
• Hamilton 配额 + 贪心分配：精确按比例计算配额，最大化覆盖多样性，迭代优化消除重复
• 四种后处理模式：ID排序 / 随机打乱 / 均匀分布 / 自定义月间重复比例
• 确认表 + 配置系统：代码强制钩子流程，支持跳过确认、默认模式持久化
• 多种输出：Markdown 明细表 + HTML 热力图表（含 3D 散点图）+ CSV 可选导出
• 补全机制：缺参数时不会编造或推断，通过选项 9 自然语言补充

> 📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

渐进式文件索引

| 文件 | 说明 |

|------|------|

| references/usage.md | 详细使用指南（确认表/菜单/后处理/配置/输出） |

| references/algorithm.md | 分配算法与后处理算法说明 |

| references/antipatterns.md | 反模式与常见错误 |

| references/faq.md | FAQ 与排错指导 |

| references/changelog.md | 更新日志 |

使用方式

AI 对话

场景 1：标准分配（等分比例）

用户：我有 33 个项目，4 个月，5 套方案，比例是 7:8:10:3:5
计算报告：已解析参数 N=33, T=4, K=5, 比例=7:8:10:3:5
结果：输出分配明细表 + 热力图表（含分布统计和 3D 散点图）

场景 2：均匀分布（避免集中）

用户：12 个学生，6 周，3 个课题，比例 4:4:4，用 fair 模式
计算报告：已解析参数 N=12, T=6, K=3, 比例=4:4:4, 模式=fair
输出结果：每周 3 个课题均匀分配，每个学生前两周不重复，热力图显示覆盖平衡

命令行

python scripts/main.py --input "33个项目，4个月，5套方案，比例7:8:10:3:5"
python scripts/main.py --input "..." --mode fair
python scripts/main.py --input "..." --no-confirm

→ 详见 references/usage.md

限制与边界

| 约束项 | 说明 |

|--------|------|

| 输入规模 | 建议 N ≤ 1000 个对象，T ≤ 52 轮，K ≤ 20 种选项。超过会降低性能 |

| 比例约束 | 比例之和必须等于 N。不指定比例则默认等分 |

| 参数缺失 | N/K/T 缺任意一个无法执行，工具不会自动推断 |

| 运行环境 | 脚本需 Python ≥ 3.8，仅标准库。HTML 可视化图表依赖 CDN（Chart.js + Plotly.js）|

| 后处理范围 | 后处理只影响分配显示顺序，不影响配额计算的正确性 |

触发场景

正向触发：

• 用户需要均匀轮转分配：将 N 个对象在 T 个轮次中分配 K 种方案
• 需求涉及配额/覆盖/轮转/方案分配
• 需要调整重复事件的月间分布

否定条件：

• 简单问答、闲聊、问候
• 用户明确说"不分配"

文件结构

round-robin-allocator/
├── SKILL.md              # 入口文档
├── _meta.json            # 元数据
├── references/           # 渐进式文档
│   ├── usage.md          #   使用指南
│   ├── algorithm.md      #   算法说明
│   └── changelog.md      #   更新日志
└── scripts/
    ├── allocator.py      # 核心算法（纯标准库）
    ├── main.py           # CLI 入口
    └── visualizer.py     # HTML 生成器

依赖

• Python ≥ 3.8，仅标准库
• HTML 可视化：Chart.js + Plotly.js（CDN 加载）

> 详见 反模式

> 详见 FAQ