import json
from typing import Any, Dict, List, Union


def 精准_键_取值_层级(
    数据对象: Union[Dict[str, Any], List[Any], str, bytes, bytearray],
    层级: int,
    目标键: str,
    *,
    递归向下: bool = True,
) -> List[Any]:
    """
    在指定结构层级（depth）处检索目标键对应的值集合。

    本函数基于结构层级模型遍历嵌套的 dict / list 数据，
    通过“绝对层级”而非显式路径的方式定位查询起点，
    并收集目标键在指定范围内出现的所有值。

    层级定义：
        - 根节点定义为第 0 层。
        - 进入 dict 的 value 时，层级增加 1。
        - 进入 list 的 element 时，层级增加 1。
        - list 本身不具备键，仅作为结构容器参与层级计算。

    查询规则：
        - 当 递归向下 为 False 时：
            仅在命中层级的节点本身尝试获取目标键，
            且仅当节点类型为 dict 时才可能命中。
        - 当 递归向下 为 True 时：
            以命中层级的节点作为起点，向下递归遍历其
            所有子结构，收集任意层级中出现的目标键值。

    Args:
        数据对象:
            待解析的数据结构，支持 dict、list，
            以及可被解析为 JSON 的 str、bytes、bytearray。
        层级:
            目标结构层级，非负整数，用于确定查询起始节点集合。
        目标键:
            需要检索的键名，仅对 dict 类型节点生效。
        递归向下:
            是否在命中层级后继续向下递归搜索目标键。

    Returns:
        list:
            所有匹配到的目标键对应的值列表；
            若未命中或发生异常，则返回空列表。
    """

    try:
        if 层级 < 0:
            return []

        # 1) JSON 字符串解析
        if isinstance(数据对象, (str, bytes, bytearray)):
            数据对象 = json.loads(数据对象)

        # 2) 取出指定层级的所有节点（作为起点们）
        起点们 = _按层级取节点们(数据对象, 层级)
        if not 起点们:
            return []

        # 3) 在起点们上执行“取键”逻辑
        结果: List[Any] = []
        for 节点 in 起点们:
            if 递归向下:
                _递归收集_键值(节点, 目标键, 结果)
            else:
                if isinstance(节点, dict) and 目标键 in 节点:
                    结果.append(节点[目标键])
        return 结果
    except Exception:
        return []


def _按层级取节点们(root: Any, 目标层级: int) -> List[Any]:
    """返回结构中恰好位于目标层级的所有节点。"""
    if 目标层级 == 0:
        return [root]

    当前层节点: List[Any] = [root]
    当前层级 = 0

    while 当前层节点 and 当前层级 < 目标层级:
        下一层: List[Any] = []

        for 节点 in 当前层节点:
            if isinstance(节点, dict):
                下一层.extend(list(节点.values()))
            elif isinstance(节点, list):
                下一层.extend(节点)
            # 其他类型（str/int/None...）没有下一层，跳过

        当前层节点 = 下一层
        当前层级 += 1

    return 当前层节点 if 当前层级 == 目标层级 else []


def _递归收集_键值(节点: Any, 目标键: str, 收集: List[Any]) -> None:
    """深度优先递归，收集所有匹配的键值。"""
    if isinstance(节点, dict):
        if 目标键 in 节点:
            收集.append(节点[目标键])
        for v in 节点.values():
            _递归收集_键值(v, 目标键, 收集)
    elif isinstance(节点, list):
        for el in 节点:
            _递归收集_键值(el, 目标键, 收集)