杂项工具 API — 下载、HTTP 请求、代理检查

源码位置：ncatbot/api/misc.py

访问方式：api.misc（与 api.qq / api.github 平级）

---

概述

MiscAPI 提供与平台无关的 HTTP/下载/代理工具。所有带 proxy 参数的方法遵循统一的代理解析逻辑：

1. 显式传入 proxy 参数时使用传入值
2. 省略时自动读取主配置 http_proxy
3. 配置也为空时直连

# 插件中使用
path = await self.api.misc.download_to_file(url, "./downloads")
data = await self.api.misc.download_to_bytes(url)
ok = await self.api.misc.is_proxy_valid()

⚠️ 网络提醒：从 GitHub 下载资源时（包括通过 Attachment.download() / as_bytes() 隐式下载 Release Assets），国内网络可能无法直连。建议开发者在 config.yaml 中配置 http_proxy，或在下载前自行对 GitHub URL 添加镜像前缀（如 ghfast.top）以避免网络阻塞。参见 配置文档 中的 http_proxy 字段。

---

构造

class MiscAPI:
    def __init__(self, config: Config) -> None: ...

MiscAPI 在框架启动时由 BotClient._setup_api() 自动创建并注册，无需手动构造。

---

方法

get_proxy

返回当前主配置中的 http_proxy，无配置时返回 None。

def get_proxy(self) -> str | None

download_to_file

下载 URL 到目录，返回文件路径。

async def download_to_file(
    self,
    url: str,
    dest_dir: str | Path,
    *,
    filename: str | None = None,
    proxy: str | None = None,
) -> Path

参数	类型	默认值	说明
url	str	—	下载地址
dest_dir	str | Path	—	目标目录（不存在时自动创建）
filename	str | None	None	文件名，省略则从 URL 推断
proxy	str | None	None	代理地址，省略则使用主配置 http_proxy

download_to_bytes

下载 URL 到内存，返回原始字节。

async def download_to_bytes(
    self,
    url: str,
    *,
    proxy: str | None = None,
) -> bytes

参数	类型	默认值	说明
url	str	—	下载地址
proxy	str | None	None	代理地址

http_get

异步 GET 请求，返回响应体字节。

async def http_get(
    self,
    url: str,
    *,
    headers: dict | None = None,
    proxy: str | None = None,
    timeout: float = 10.0,
) -> bytes

参数	类型	默认值	说明
url	str	—	请求地址
headers	dict | None	None	额外请求头
proxy	str | None	None	代理地址
timeout	float	10.0	超时秒数

is_proxy_valid

检查代理是否可用。

async def is_proxy_valid(self, proxy: str | None = None) -> bool

参数	类型	默认值	说明
proxy	str | None	None	要检查的代理地址。省略则检查主配置 http_proxy。配置也为空时直接返回 False

---

配置

在 config.yaml 中设置标准 HTTP/SOCKS5 代理：

# 标准 HTTP/SOCKS5 代理（用于 Attachment 下载、MiscAPI 请求等）
http_proxy: "http://127.0.0.1:7890"

也可通过环境变量 HTTP_PROXY 设置。

---

返回：API 参考首页

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)