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
