agent.commentator

规划评语生成器：规则模板 + LLM 润色预留。

规则注册表 RULES 仅需在列表中添加函数，即可自动参与评语生成。

Attributes

RULES

Functions

check_wait(solution, spots, cost_mat)	等待惩罚超过阈值时提醒早到。
check_late(solution, spots, cost_mat)	迟到惩罚超过阈值时提醒安排太满。
check_density(solution, spots, cost_mat)	单日景点过多时提醒行程紧凑。
check_distance(solution, spots, cost_mat)	单日路程过长时提醒注意交通时间。
check_normal(solution, spots, cost_mat)	兜底：一切正常时给出正面评语。
polish_with_llm(→ str)	LLM 润色评语（预留）。
generate_commentary(→ str)	遍历规则注册表生成评语，取前两条非空结果拼接。

Module Contents

agent.commentator.check_wait(solution, spots, cost_mat)

等待惩罚超过阈值时提醒早到。

Args:

solution: 求解结果，含 wait/late/routes 等。 spots: 景点字典。 cost_mat: 距离矩阵（km）。

Returns:

str | None: 超过 50 分钟等待时返回提醒文本，否则 None。

agent.commentator.check_late(solution, spots, cost_mat)

迟到惩罚超过阈值时提醒安排太满。

Args:

solution: 求解结果。 spots: 景点字典。 cost_mat: 距离矩阵。

Returns:

str | None: 超过 50 分钟迟到惩罚时返回提醒文本，否则 None。

agent.commentator.check_density(solution, spots, cost_mat)

单日景点过多时提醒行程紧凑。

Args:

solution: 求解结果，含 routes 路径列表。 spots: 景点字典。 cost_mat: 距离矩阵。

Returns:

str | None: 存在超过 5 个景点的天数时返回提醒，否则 None。

agent.commentator.check_distance(solution, spots, cost_mat)

单日路程过长时提醒注意交通时间。

Args:

solution: 求解结果，含 routes 路径列表。 spots: 景点字典。 cost_mat: 距离矩阵（km）。

Returns:

str | None: 存在超过 50km 的天数时返回提醒，否则 None。

agent.commentator.check_normal(solution, spots, cost_mat)

兜底：一切正常时给出正面评语。

Args:

solution: 求解结果。 spots: 景点字典。 cost_mat: 距离矩阵。

Returns:

str: 固定正面评语。

agent.commentator.RULES

agent.commentator.polish_with_llm(text: str, enabled: bool = False) → str

LLM 润色评语（预留）。

Args:

text: 原始评语文本。 enabled: 是否启用 LLM 润色，默认关闭。

Returns:

str: 原文本（润色功能暂未实现）。

agent.commentator.generate_commentary(solution: dict, spots: dict, cost_mat: numpy.ndarray) → str

遍历规则注册表生成评语，取前两条非空结果拼接。

Args:

solution: solve_groups 返回的结果，含 routes/total_cost/wait/late 等。 spots: 景点字典。 cost_mat: 距离矩阵（km）。

Returns:

拼接后的评语文本。