Agent/agent/goal/tool.py

"""
Goal 工具 - 计划管理

提供 goal 工具供 LLM 管理执行计划。
"""

from typing import Optional, List, TYPE_CHECKING

if TYPE_CHECKING:
    from agent.goal.models import GoalTree
    from agent.execution.protocols import TraceStore


async def goal_tool(
    tree: "GoalTree",
    store: Optional["TraceStore"] = None,
    trace_id: Optional[str] = None,
    add: Optional[str] = None,
    reason: Optional[str] = None,
    done: Optional[str] = None,
    abandon: Optional[str] = None,
    focus: Optional[str] = None,
) -> str:
    """
    管理执行计划。

    Args:
        tree: GoalTree 实例
        store: TraceStore 实例（用于推送事件）
        trace_id: 当前 Trace ID
        add: 添加目标（逗号分隔多个）。添加到当前 focus 的 goal 下作为子目标。
        reason: 创建理由（逗号分隔多个，与 add 一一对应）
        done: 完成当前目标，值为 summary
        abandon: 放弃当前目标，值为原因
        focus: 切换焦点到指定内部 id

    Returns:
        更新后的计划状态文本
    """
    changes = []

    # 1. 处理 abandon（先处理，因为可能需要在 add 新目标前放弃旧的）
    if abandon is not None:
        if not tree.current_id:
            return "错误：没有当前目标可以放弃"
        goal = tree.abandon(tree.current_id, abandon)
        display_id = tree._generate_display_id(goal)
        changes.append(f"已放弃: {display_id}. {goal.description}")

        # 推送事件
        if store and trace_id:
            print(f"[DEBUG] goal_tool: calling store.update_goal for abandon: goal_id={goal.id}")
            await store.update_goal(trace_id, goal.id, status="abandoned", summary=abandon)
        else:
            print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")

    # 2. 处理 done
    if done is not None:
        if not tree.current_id:
            return "错误：没有当前目标可以完成"
        goal = tree.complete(tree.current_id, done)
        display_id = tree._generate_display_id(goal)
        changes.append(f"已完成: {display_id}. {goal.description}")

        # 推送事件
        if store and trace_id:
            print(f"[DEBUG] goal_tool: calling store.update_goal for done: goal_id={goal.id}")
            await store.update_goal(trace_id, goal.id, status="completed", summary=done)
        else:
            print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")

        # 检查是否有级联完成的父目标
        if goal.parent_id:
            parent = tree.find(goal.parent_id)
            if parent and parent.status == "completed":
                parent_display_id = tree._generate_display_id(parent)
                changes.append(f"自动完成: {parent_display_id}. {parent.description}（所有子目标已完成）")

    # 3. 处理 focus（在 add 之前，这样 add 可以添加到新焦点下）
    if focus is not None:
        # focus 参数可以是内部 ID 或显示 ID
        # 先尝试作为内部 ID 查找
        goal = tree.find(focus)

        # 如果找不到，尝试根据显示 ID 查找
        if not goal:
            # 通过遍历所有 goal 查找匹配的显示 ID
            for g in tree.goals:
                if tree._generate_display_id(g) == focus:
                    goal = g
                    break

        if not goal:
            return f"错误：找不到目标 {focus}"

        tree.focus(goal.id)
        display_id = tree._generate_display_id(goal)
        changes.append(f"切换焦点: {display_id}. {goal.description}")

    # 4. 处理 add
    if add is not None:
        descriptions = [d.strip() for d in add.split(",") if d.strip()]
        if descriptions:
            # 解析 reasons（与 descriptions 一一对应）
            reasons = None
            if reason:
                reasons = [r.strip() for r in reason.split(",")]
                # 如果 reasons 数量少于 descriptions，补空字符串
                while len(reasons) < len(descriptions):
                    reasons.append("")

            # 添加到当前焦点下（如果有焦点），否则添加到顶层
            parent_id = tree.current_id
            new_goals = tree.add_goals(descriptions, reasons=reasons, parent_id=parent_id)

            # 推送事件
            if store and trace_id:
                print(f"[DEBUG] goal_tool: calling store.add_goal for {len(new_goals)} new goals")
                for goal in new_goals:
                    await store.add_goal(trace_id, goal)
            else:
                print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")

            if parent_id:
                parent_display_id = tree._generate_display_id(tree.find(parent_id))
                changes.append(f"在 {parent_display_id} 下添加 {len(new_goals)} 个子目标")
            else:
                changes.append(f"添加 {len(new_goals)} 个顶层目标")

            # 如果没有焦点且添加了目标，自动 focus 到第一个新目标
            if not tree.current_id and new_goals:
                tree.focus(new_goals[0].id)
                display_id = tree._generate_display_id(new_goals[0])
                changes.append(f"自动切换焦点: {display_id}")

    # 返回当前状态
    result = []
    if changes:
        result.append("## 更新")
        result.extend(f"- {c}" for c in changes)
        result.append("")

    result.append("## Current Plan")
    result.append(tree.to_prompt())

    return "\n".join(result)


def create_goal_tool_schema() -> dict:
    """创建 goal 工具的 JSON Schema"""
    return {
        "name": "goal",
        "description": """管理执行计划。

- add: 添加目标（逗号分隔多个）。添加到当前 focus 的 goal 下作为子目标。
- reason: 创建理由（逗号分隔多个，与 add 一一对应）。说明为什么要做这些目标。
- done: 完成当前目标，值为 summary
- abandon: 放弃当前目标，值为原因（会触发 context 压缩）
- focus: 切换焦点到指定 id（可以是内部 ID 或显示 ID）

示例：
- goal(add="分析代码, 实现功能, 测试", reason="了解现有结构, 完成需求, 确保质量") - 添加顶层目标
- goal(focus="2", add="设计接口, 实现代码", reason="明确API规范, 编写核心逻辑") - 切换到目标2，并添加子目标
- goal(done="发现用户模型在 models/user.py") - 完成当前目标
- goal(abandon="方案A需要Redis，环境没有", add="实现方案B", reason="使用现有技术栈") - 放弃当前并添加新目标

注意：内部 ID 是纯自增数字（"1", "2", "3"），显示 ID 是带层级的（"1", "2.1", "2.2"）。
focus 参数可以使用任意格式的 ID。
reason 应该与 add 的目标数量一致，如果数量不一致，缺少的 reason 将为空。
""",
        "parameters": {
            "type": "object",
            "properties": {
                "add": {
                    "type": "string",
                    "description": "添加目标（逗号分隔多个）。添加到当前 focus 的 goal 下作为子目标。"
                },
                "reason": {
                    "type": "string",
                    "description": "创建理由（逗号分隔多个，与 add 一一对应）。说明为什么要做这些目标。"
                },
                "done": {
                    "type": "string",
                    "description": "完成当前目标，值为 summary"
                },
                "abandon": {
                    "type": "string",
                    "description": "放弃当前目标，值为原因"
                },
                "focus": {
                    "type": "string",
                    "description": "切换焦点到指定 goal id（可以是内部 ID 或显示 ID）"
                }
            },
            "required": []
        }
    }