pyfnos

飞牛fnOS的Python SDK。

注意：这个SDK非官方提供。

项目信息

• 源代码仓库: https://github.com/Timandes/pyfnos
• 问题追踪: GitHub Issues

上手

import asyncio
import argparse

def on_message_handler(message):
    """消息回调处理函数"""
    print(f"收到消息: {message}")


async def login_with_twofa(client, args):
    result = await client.login(args.user, args.password)
    if result.get("twofaRequired"):
        code = args.code or input("请输入 6 位两步验证码: ")
        result = await client.submit_twofa_code(code, trust_device=args.trust_device)
    elif result.get("twofaSetupRequired"):
        raise RuntimeError("该账号需要先绑定两步验证后才能继续登录")
    return result


async def main():
    # 解析命令行参数
    parser = argparse.ArgumentParser(description='Fnos客户端')
    parser.add_argument('--user', type=str, required=True, help='用户名')
    parser.add_argument('--password', type=str, required=True, help='密码')
    parser.add_argument('-e', '--endpoint', type=str, default='your-custom-endpoint.com:5666', help='服务器地址 (默认: your-custom-endpoint.com:5666)')
    parser.add_argument('--code', type=str, help='6位两步验证码；不提供时从终端读取')
    parser.add_argument('--trust-device', action='store_true', help='请求服务器信任当前设备')
    parser.add_argument('--use-ssl', action='store_true', help='使用 SSL/WSS 连接')
    parser.add_argument('--skip-ssl-verify', type=lambda x: x.lower() == 'true', default=True, help='跳过 SSL 证书验证 (默认: True)')

    args = parser.parse_args()

    client = FnosClient()

    # 设置消息回调
    client.on_message(on_message_handler)

    # 连接到服务器（必须指定endpoint）
    # 可选参数：use_ssl=True 使用 WSS 连接，skip_ssl_verify=False 验证证书
    await client.connect(args.endpoint, use_ssl=args.use_ssl, skip_ssl_verify=args.skip_ssl_verify)

    # 登录
    result = await login_with_twofa(client, args)
    print("登录结果:", result)

    # 发送请求
    await client.request_payload("user.info", {})
    print("已发送请求，等待响应...")
    # 等待一段时间以接收响应
    await asyncio.sleep(5)

    # 演示重连功能（手动方式）
    await client.close()  # 先关闭连接
    print("连接已关闭，尝试重连...")
    await client.connect(args.endpoint, use_ssl=args.use_ssl, skip_ssl_verify=args.skip_ssl_verify)  # 重新连接（现在会等待连接完成）
    result = await login_with_twofa(client, args)  # 重新登录
    print("重连登录结果:", result)

    # 关闭连接
    await client.close()

# 运行异步主函数
if __name__ == "__main__":
    asyncio.run(main())

两步验证登录

如果账号已开启两步验证，login() 会先返回挑战信息，而不是完整登录凭据：

result = await client.login(user, password)

if result.get("twofaRequired"):
    result = await client.submit_twofa_code("123456", trust_device=False)

if result.get("twofaSetupRequired"):
    raise RuntimeError("该账号需要先绑定两步验证后才能继续登录")

只有最终响应中包含 token 和 secret 后，SDK 才会保存登录态并允许后续 API 请求。trust_device=True 会请求服务器信任当前设备，后续是否免验证码由 fnOS 服务端决定。

也可以直接运行两步验证示例：

uv run examples/twofa_login.py --user myuser --password mypassword -e my-server.com:5666

参考

命令行参数

示例程序支持以下命令行参数：

• --user: 用户名（必填）
• --password: 密码（必填）
• -e, --endpoint: 服务器地址（可选，默认为 your-custom-endpoint.com:5666）
  • 支持协议前缀：wss://host:port 或 ws://host:port
• --use-ssl: 使用 SSL/WSS 连接（可选，默认不使用）
• --skip-ssl-verify: 跳过 SSL 证书验证（可选，默认为 True）

运行示例

可以使用 uv 工具来运行 examples 目录下的示例程序：

# 基本语法
uv run examples/<示例文件名>.py --user <用户名> --password <密码> [-e <服务器地址>] [--code <验证码>] [--trust-device]

# 示例：运行user.py示例
uv run examples/user.py --user myuser --password mypassword -e my-server.com:5666

示例程序说明

下表列出了 examples 目录中各个示例程序的功能说明：

示例中的用户名密码登录已统一支持两步验证。账号需要验证码时，程序会提示输入；也可以通过 --code 123456 直接传入验证码。

SSL/WSS 连接示例

如果服务器使用 HTTPS/WSS 协议，可以通过以下方式连接：

# 方式1：使用 wss:// 前缀
uv run examples/user.py --user myuser --password mypassword -e wss://my-server.com:5667

# 方式2：使用 --use-ssl 参数
uv run examples/user.py --user myuser --password mypassword -e my-server.com:5667 --use-ssl

# 禁用证书验证跳过（验证服务器证书）
uv run examples/user.py --user myuser --password mypassword -e wss://my-server.com:5667 --skip-ssl-verify false