Agent/agent/tools/builtin/goal.py

"""
Goal 工具 - 执行计划管理

提供 LLM 可调用的 goal 工具，用于管理执行计划（GoalTree）。
"""

from typing import Optional


# 全局 GoalTree 引用（由 AgentRunner 注入）
_current_goal_tree = None


def set_goal_tree(tree):
    """设置当前 GoalTree（由 AgentRunner 调用）"""
    global _current_goal_tree
    _current_goal_tree = tree


def get_goal_tree():
    """获取当前 GoalTree"""
    return _current_goal_tree


def goal(
    add: Optional[str] = None,
    done: Optional[str] = None,
    abandon: Optional[str] = None,
    focus: Optional[str] = None,
) -> str:
    """
    管理执行计划。

    参数:
        add: 添加目标（逗号分隔多个）。添加到当前 focus 的 goal 下作为子目标。
        done: 完成当前目标，值为 summary
        abandon: 放弃当前目标，值为原因（会触发 context 压缩）
        focus: 切换焦点到指定 id（可以是内部 ID 或显示 ID）

    示例:
        goal(add="分析代码, 实现功能, 测试") - 添加顶层目标
        goal(focus="2", add="设计接口, 实现代码") - 切换到目标2，并添加子目标
        goal(done="发现用户模型在 models/user.py") - 完成当前目标
        goal(abandon="方案A需要Redis，环境没有", add="实现方案B") - 放弃当前并添加新目标

    注意: 内部 ID 是纯自增数字（"1", "2", "3"），显示 ID 是带层级的（"1", "2.1", "2.2"）。
    focus 参数可以使用任意格式的 ID。

    返回:
        str: 更新后的计划状态文本
    """
    from agent.goal.tool import goal_tool

    tree = get_goal_tree()
    if tree is None:
        return "错误：GoalTree 未初始化"

    return goal_tool(
        tree=tree,
        add=add,
        done=done,
        abandon=abandon,
        focus=focus
    )