# -*- coding: utf-8 -*-
"""
知识拉取工具
Agent 通过 host.get_knowledge(name) 按需获取完整知识正文。
构造函数接收 host（LifecycleHost 或类似含 get_knowledge 方法的对象），
因此不在 register_builtins() 中无参注册，而在 main.py 中 _HOST 创建后注册。
"""
from typing import Any, Dict

from .base import Tool


class KnowledgeFetchTool(Tool):
    """知识拉取工具：Agent 按需获取完整知识正文。

    依赖 host（LifecycleHost），通过 host.get_knowledge(name) 查询已加载知识。
    host 为 None 时返回「知识库未加载」错误，不抛异常。
    """

    def __init__(self, host=None):
        self._host = host

    @property
    def name(self) -> str:
        """工具名称"""
        return "knowledge_fetch"

    @property
    def description(self) -> str:
        """工具功能描述"""
        return "按需拉取完整知识正文。参数 name 为知识名称（见注入的索引行）。"

    @property
    def parameters(self) -> Dict[str, Any]:
        """工具参数 JSON Schema"""
        return {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "知识名称（kebab-case，与索引行一致）",
                }
            },
            "required": ["name"],
        }

    def execute(self, name: str) -> Dict[str, Any]:
        """执行知识拉取，返回结果字典。

        Args:
            name: 知识名称

        Returns:
            success=True 时含 name/level/category/content/tags；success=False 时含 error
        """
        if self._host is None:
            return {"success": False, "error": "知识库未加载"}

        knowledge = self._host.get_knowledge(name)
        if knowledge is None:
            return {"success": False, "error": f"未找到知识: {name}"}

        # 记录使用（供 KnowledgeCurator 跟踪生命周期）
        self._host.bump_knowledge_use(name)

        return {
            "success": True,
            "name": knowledge.name,
            "level": knowledge.level,
            "category": knowledge.category,
            "content": knowledge.content,
            "tags": knowledge.tags,
        }
