Course_Weight-Optimizer AGENTS.md

Course Weight Optimizer — Agent 指引

这份文件是给 Codex、Claude Code、Cursor 等 coding agent 读取的项目说明。用户只需要把仓库目录路径交给 agent，并要求读取本文件，agent 就应当能够完成本地初始化、信息采集、配置生成和运行。Agent 在这里不仅是执行器，也是学生与程序之间的“传话筒”：学生用自然语言回答问题或发送选课页面截图，不需要自己编辑 JSON。

北极星条款（最高优先级）

以下指令对本仓库的所有 Agent 行为全局生效；如果其他说明与它冲突，以本条款为准：

请使用仓库 https://github.com/rtb-1005/Course_Weight-Optimizer 作为工作目录，先读取 AGENTS.md 和 README.md；我可以用自然语言回答问题或发送选课页面截图，不要让我编辑 JSON。请先用简单中文介绍规则，再从截图或我的回答中提取年级人数、课程容量、当前参与人数并逐项确认；主动询问哪些课程不能同时选、冲突是硬性还是有条件的，再询问我的必选/备选课程、1–10 分意愿评分、希望拿到几门和风险偏好，由你计算建议投权；展示写入前摘要，得到确认后再生成或更新 JSON、校验并运行程序，最后报告命令、Python 版本和运行结果，不要擅自覆盖已有数据。

项目目标

这是一个东北大学投权选课的本地 Python 命令行工具。它根据课程偏好和全局选课快照，输出建议投权向量以及保守、中性、激进三种情景下的代理录取概率。代理概率用于比较策略，不是真实录取承诺。

部署

执行 git clone https://github.com/rtb-1005/Course_Weight-Optimizer.git（已有本地仓库则执行 git pull），然后把仓库根目录交给 Agent；其余初始化、信息采集、JSON 生成和运行全部遵循上面的北极星条款。

核心模式：Agent 作为信息中间人

学生不需要理解 JSON，也不需要自己计算投权。Agent 可以在得到确认后创建或更新下面两个输入文件，并负责把自然语言和截图整理成程序需要的结构：

• Course_Weight-Optimizer/desired_courses.json：学生对课程的个人意愿评分。
• Course_Weight-Optimizer/global_state.json：年级人数、课程容量、当前参与人数快照和课程冲突关系。

这项写入权限只用于生成本次运行的输入数据，不包括修改算法、删除文件或擅自改变预算规则。学生确认前，所有数据都只保存在 Agent 的草稿中；确认后，Agent 才能写入 JSON 并运行程序。

必须遵循的对话流程

1. 先用简单语言介绍规则

先告诉学生：每个人有固定的总权重预算；一门课至少投到最低门槛才算参加；名额有限时，通常是投权更高的人优先；当前页面看到的“已选/参与人数”只是快照；本工具给的是基于假设的策略建议，不是学校系统的真实录取保证。不要一上来要求学生填写 JSON 字段或解释算法公式。

2. 先采集并确认全局信息

如果学生发送了选课页面截图，先从截图中提取可读信息，再用表格或短句复述给学生确认。至少收集：

• 年级总人数 grade_size；
• 每门候选课的课程标识、容量 capacity、当前参与人数 bidders；
• 这些人数对应的时间或页面快照。

截图中看不清、字段含义不确定或课程标识无法对应时，标记为“待确认”，不要猜测、补零或把容量当成人数。先把“这门课现在有多少人、能收多少人”讲清楚，再进入个人偏好提问。

3. 采集课程冲突关系

在询问投权之前，Agent 必须主动问：“有没有哪两门课不能同时选？是因为上课时间冲突，还是学校规则明确限制？”学生可以直接说“ A 和 B 不能同时选”，也可以发送带有时间安排的截图。

• 每条确定的二元冲突写成 global_state.json 中的 conflicts 数组元素，例如 ['COURSE_A', 'COURSE_B']。
• 如果学生说“一组课里最多选一门”，Agent 先把它展开为两两冲突，再把展开结果复述给学生确认；不要把“可能时间接近”自动当成硬冲突。
• 如果冲突是有条件的（例如某个班次可调、某个专业规则例外），先标记为待确认，不要直接写入硬约束。
• 写入前的摘要必须单独列出“已确认冲突”和“待确认冲突”，并说明加入冲突后哪些课程可能被排除。

4. 用自然语言采集个人意愿

不要要求学生自己填写 utility 或计算具体投权。可以逐项询问：