工具接口设计：让 Agent 用得好，比让 Agent 用得上更难

# 粒度太细的工具设计
tools = [
    "get_file_list",           # 获取目录文件列表
    "read_file",               # 读取单个文件
    "get_function_names",      # 获取文件中的函数名
    "get_function_body",       # 获取特定函数的代码
    "get_function_calls",      # 获取函数内的调用关系
]

# 粒度太粗的工具
def analyze_codebase(query: str) -> str:
    """分析整个代码库，回答关于代码的任何问题"""
    # 把整个代码库塞进模型，让它自己找

# 第一层：便捷函数，覆盖 80% 的常见场景
@tool
def find_symbol(name: str, symbol_type: str = "any") -> dict:
    """
    在代码库中搜索符号（函数、类、变量）的定义位置。
    这是查找代码定义的首选方法。

    参数：
    - name: 符号名称，支持模糊匹配
    - symbol_type: "function" | "class" | "variable" | "any"

    返回符号的文件路径、行号、完整签名。
    如果找到多个匹配，返回最可能的前 3 个结果。
    """
    ...

# 第二层：底层函数，处理便捷函数覆盖不到的情况
@tool
def search_in_file(file_path: str, pattern: str,
                   context_lines: int = 3) -> dict:
    """
    在指定文件中搜索文本模式。

    仅当 find_symbol 无法找到目标时使用此工具。
    支持正则表达式。
    """
    ...

# 返回了太多噪音
def get_pull_request(pr_number: int) -> dict:
    response = github_api.get(f"/pulls/{pr_number}")
    return response.json()  # 返回 GitHub API 的完整响应，60+ 个字段

# Agent 实际需要的
def get_pull_request(pr_number: int) -> dict:
    response = github_api.get(f"/pulls/{pr_number}")
    data = response.json()
    return {
        "number": data["number"],
        "title": data["title"],
        "state": data["state"],          # open / closed / merged
        "author": data["user"]["login"],
        "created_at": data["created_at"],
        "body": data["body"][:500],      # 截断过长的描述
        "files_changed": data["changed_files"],
        "additions": data["additions"],
        "deletions": data["deletions"],
        "labels": [l["name"] for l in data["labels"]],
    }

def search_documents(query: str, limit: int = 5) -> dict:
    results = vector_db.search(query, limit=limit)
    total_count = vector_db.count(query)

    return {
        "query": query,
        "total_matches": total_count,     # 告诉 Agent 总共找到多少
        "returned": len(results),          # 告诉 Agent 返回了多少
        "results": [
            {
                "title": r.title,
                "snippet": r.snippet,
                "relevance_score": round(r.score, 3),  # 相关度
                "source": r.source,
                "last_updated": r.updated_at,          # 时效性
            }
            for r in results
        ],
        # 引导 Agent 做出正确判断
        "note": (
            f"找到 {total_count} 条匹配，返回了相关度最高的 {len(results)} 条。"
            f"{'如果结果不满足需求，可以调整查询关键词。' if total_count == 0 else ''}"
        )
    }

def read_file(path: str, max_lines: int = 200) -> dict:
    with open(path) as f:
        lines = f.readlines()

    total_lines = len(lines)
    returned_lines = lines[:max_lines]
    was_truncated = total_lines > max_lines

    return {
        "path": path,
        "total_lines": total_lines,
        "content": "".join(returned_lines),
        "truncated": was_truncated,
        # 如果被截断，告诉 Agent 还剩多少，以及如何获取剩余内容
        "truncation_note": (
            f"文件共 {total_lines} 行，已返回前 {max_lines} 行。"
            f"如需查看后续内容，请使用 read_file_range(path, "
            f"start_line={max_lines+1}) 获取。"
        ) if was_truncated else None
    }

# 这些错误信息对 Agent 几乎没有帮助
raise Exception("操作失败")
raise Exception("无效输入")
raise ValueError("参数错误")
return {"error": True, "message": "Something went wrong"}

class ToolError(Exception):
    def __init__(self, code: str, message: str,
                 context: dict = None, suggestion: str = None):
        self.code = code
        self.message = message
        self.context = context or {}
        self.suggestion = suggestion
        super().__init__(self.to_agent_message())

    def to_agent_message(self) -> str:
        parts = [f"[{self.code}] {self.message}"]
        if self.context:
            parts.append(f"上下文：{self.context}")
        if self.suggestion:
            parts.append(f"建议：{self.suggestion}")
        return "\n".join(parts)


# 实际使用
def query_database(sql: str, database: str) -> dict:
    if database not in AVAILABLE_DATABASES:
        raise ToolError(
            code="DATABASE_NOT_FOUND",
            message=f"数据库 '{database}' 不存在",
            context={
                "requested": database,
                "available": list(AVAILABLE_DATABASES.keys())
            },
            suggestion=(
                f"可用的数据库为：{list(AVAILABLE_DATABASES.keys())}。"
                f"请检查数据库名称是否正确，注意大小写。"
            )
        )

    try:
        result = db.execute(sql)
    except SyntaxError as e:
        raise ToolError(
            code="SQL_SYNTAX_ERROR",
            message="SQL 语句存在语法错误",
            context={"sql": sql, "error_detail": str(e)},
            suggestion=(
                "请检查 SQL 语法。常见问题：缺少引号、括号不匹配、"
                "列名或表名错误。可以先用 get_schema() 确认表结构。"
            )
        )
    except PermissionError:
        raise ToolError(
            code="PERMISSION_DENIED",
            message=f"当前凭证无权查询数据库 '{database}'",
            context={"database": database, "operation": "SELECT"},
            suggestion=(
                "此操作需要更高权限。如果你认为应该有此权限，"
                "请联系管理员，或尝试使用只读副本数据库 'readonly_replica'。"
            )
        )

TOOL_FAILURE_HANDLING = """
工具调用失败时的处理策略：
- DATABASE_NOT_FOUND：检查数据库名称，使用返回的可用列表重试
- SQL_SYNTAX_ERROR：修正 SQL 语法后重试，可先调用 get_schema() 确认表结构
- PERMISSION_DENIED：换用权限更低的只读工具，或停止并告知用户
- RATE_LIMITED：等待 5 秒后重试，最多重试 3 次
- TIMEOUT：将任务拆分成更小的查询重试
"""

# 有状态的 API：对 Agent 不友好
client = DatabaseClient()
client.connect(host, port)        # Agent 需要记住连接状态
client.authenticate(user, passwd) # Agent 需要记住认证状态
result = client.query(sql)        # 只有前两步都完成才有效

# 无状态的 API：对 Agent 友好
result = query_database(
    sql=sql,
    connection={"host": host, "port": port},
    auth={"user": user, "password": passwd}
)

# 显式状态管理
def start_analysis(config: dict) -> dict:
    """启动分析任务，返回任务 ID"""
    task_id = create_task(config)
    return {
        "task_id": task_id,
        "status": "running",
        "note": f"使用 get_analysis_status('{task_id}') 查询进度"
    }

def get_analysis_status(task_id: str) -> dict:
    """查询分析任务的进度和结果"""
    task = get_task(task_id)
    return {
        "task_id": task_id,
        "status": task.status,  # running / completed / failed
        "progress": task.progress,
        "result": task.result if task.status == "completed" else None,
        "error": task.error if task.status == "failed" else None,
    }