agent.planner
=============

.. py:module:: agent.planner

.. autoapi-nested-parse::

   方案调整功能：改天数、添加/移除景点并重新求解。



Functions
---------

.. autoapisummary::

   agent.planner.adjust_plan_days
   agent.planner.add_poi_to_plan
   agent.planner.remove_poi_from_plan


Module Contents
---------------

.. py:function:: adjust_plan_days(spots_dict: dict[int, backend.typedefs.SpotDict], cost_matrix: numpy.ndarray, dist_matrix: numpy.ndarray, new_n_days: int) -> dict

   调整方案天数，保持景点不变，用新 n_days 重新规划。

   Args:
       spots_dict: 景点字典（与 run_planning 格式一致）。
       cost_matrix: np.ndarray 成本矩阵。
       dist_matrix: np.ndarray 距离矩阵（仅接收，不参与求解，用于矩阵一致性维护）。
       new_n_days: 新的行程天数。

   Returns:
       dict: cluster_and_solve 返回的 result，含 "type": "solution"。


.. py:function:: add_poi_to_plan(spots_dict: dict[int, backend.typedefs.SpotDict], cost_matrix: numpy.ndarray, dist_matrix: numpy.ndarray, routes: list) -> dict

   向方案添加新景点并重新求解（矩阵已由调用方展开）。

   Args:
       spots_dict: 景点字典（含新 POI，矩阵已对应展开）。
       cost_matrix: 展开后的成本矩阵（ndarray）。
       dist_matrix: 展开后的距离矩阵（ndarray，仅接收，不参与求解）。
       routes: 当前方案的路径列表（仅用于获取天数）。

   Returns:
       dict: 与 adjust_plan_days 格式一致的新方案。


.. py:function:: remove_poi_from_plan(spots_dict: dict[int, backend.typedefs.SpotDict], cost_matrix: numpy.ndarray, dist_matrix: numpy.ndarray, routes: list, poi_name: str) -> dict

   从方案中移除指定景点并重新求解。

   Args:
       spots_dict: 景点字典。
       cost_matrix: np.ndarray 成本矩阵。
       dist_matrix: np.ndarray 距离矩阵（仅接收，用于矩阵一致性维护，不参与求解）。
       routes: 当前方案的路径列表。
       poi_name: 要移除的景点名称。

   Returns:
       dict: 与 adjust_plan_days 格式一致的新方案。

   Raises:
       ValueError: 未在 spots 中找到名称为 poi_name 的景点。