ChatNet 0.1.0__py3-none-any.whl

chatnet/__init__.py

@@ -0,0 +1,5 @@
+"""ChatArch network and campus-network CLI."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

chatnet/cli.py

@@ -0,0 +1,58 @@
+"""CLI entrypoint for chatnet."""
+
+from __future__ import annotations
+
+import click
+from chatstyle import (
+    CommandField,
+    CommandSchema,
+    add_interactive_option,
+    render_success,
+    resolve_command_inputs,
+)
+
+
+HELLO_SCHEMA = CommandSchema(
+    name="hello",
+    fields=(CommandField("name", prompt="name", required=True),),
+)
+
+
+class ChatNetGroup(click.Group):
+    """Top-level group that loads heavier feature groups on demand."""
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        commands = set(super().list_commands(ctx))
+        commands.add("ecnu")
+        return sorted(commands)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if cmd_name == "ecnu":
+            from chatnet.ecnu.cli import cli as ecnu_cli
+
+            return ecnu_cli
+        return super().get_command(ctx, cmd_name)
+
+
+@click.group(cls=ChatNetGroup)
+def main() -> None:
+    """chatnet command line interface."""
+
+
+@main.command()
+@click.argument("name", required=False)
+@add_interactive_option
+def hello(name: str | None, interactive: bool | None) -> None:
+    """Print a greeting with ChatStyle-backed input resolution."""
+
+    values = resolve_command_inputs(
+        schema=HELLO_SCHEMA,
+        provided={"name": name},
+        interactive=interactive,
+        usage="Usage: chatnet hello [NAME]",
+    )
+    render_success(f"Hello, {values['name']}!")
+
+
+if __name__ == "__main__":
+    main()

chatnet/config.py

@@ -0,0 +1,21 @@
+"""ChatEnv configuration schemas provided by ChatNet."""
+
+from __future__ import annotations
+
+from chatenv.fields import BaseEnvConfig, EnvField
+
+
+class ECNUConfig(BaseEnvConfig):
+    """ECNU self-service portal environment variables."""
+
+    _title = "ECNU"
+    _aliases = ["ecnu", "chatnet-ecnu"]
+    _storage_dir = "ECNU"
+
+    ECNU_USERNAME = EnvField("ECNU_USERNAME", desc="ECNU username.")
+    ECNU_PASSWORD = EnvField("ECNU_PASSWORD", desc="ECNU password.", is_sensitive=True)
+    ECNU_COOKIE = EnvField("ECNU_COOKIE", desc="Authenticated ECNU portal Cookie header.", is_sensitive=True)
+    ECNU_BASE_URL = EnvField("ECNU_BASE_URL", default="https://login.ecnu.edu.cn:8800", desc="ECNU portal base URL.")
+
+
+__all__ = ["ECNUConfig"]

chatnet/ecnu/__init__.py

@@ -0,0 +1,5 @@
+"""ECNU self-service portal integration for ChatNet."""
+
+from .portal import BASE_URL, PortalClient
+
+__all__ = ["BASE_URL", "PortalClient"]

chatnet/ecnu/captcha.py

@@ -0,0 +1,183 @@
+"""Optional CAPTCHA recognition helpers for ECNU login automation."""
+
+from __future__ import annotations
+
+import io
+from collections import defaultdict
+from typing import Any
+
+
+def _load_ocr_deps() -> tuple[Any, Any, Any]:
+    try:
+        import ddddocr
+        import numpy as np
+        from PIL import Image
+    except ImportError as exc:
+        raise RuntimeError(
+            'CAPTCHA auto-login requires optional dependencies. Install them with: pip install "ChatNet[captcha]"'
+        ) from exc
+    return ddddocr, np, Image
+
+
+def recognize_captcha_topk(image_bytes: bytes, topk: int = 5, expected_length: int = 4) -> list[str]:
+    ddddocr, _, _ = _load_ocr_deps()
+    ocr = ddddocr.DdddOcr(show_ad=False)
+    variants = build_variants(image_bytes)
+    variant_results = {
+        name: topk_for_variant(ocr, data, expected_length=expected_length)
+        for name, data in variants.items()
+    }
+    aggregate = aggregate_variant_candidates(variant_results, topk=topk)
+    return [row["text"] for row in aggregate]
+
+
+def pil_to_bytes(image: Any) -> bytes:
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def dilate(mask: Any, iterations: int = 1) -> Any:
+    _, np, _ = _load_ocr_deps()
+    out = mask.copy()
+    for _ in range(iterations):
+        padded = np.pad(out, 1, constant_values=False)
+        grown = np.zeros_like(out)
+        for dy in range(3):
+            for dx in range(3):
+                grown |= padded[dy : dy + out.shape[0], dx : dx + out.shape[1]]
+        out = grown
+    return out
+
+
+def erode(mask: Any, iterations: int = 1) -> Any:
+    _, np, _ = _load_ocr_deps()
+    out = mask.copy()
+    for _ in range(iterations):
+        padded = np.pad(out, 1, constant_values=True)
+        shrunk = np.ones_like(out)
+        for dy in range(3):
+            for dx in range(3):
+                shrunk &= padded[dy : dy + out.shape[0], dx : dx + out.shape[1]]
+        out = shrunk
+    return out
+
+
+def closing(mask: Any, iterations: int = 1) -> Any:
+    return erode(dilate(mask, iterations), iterations)
+
+
+def mask_bbox(mask: Any) -> tuple[int, int, int, int] | None:
+    _, np, _ = _load_ocr_deps()
+    ys, xs = np.where(mask)
+    if len(xs) == 0:
+        return None
+    return int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())
+
+
+def build_variants(image_bytes: bytes) -> dict[str, bytes]:
+    _, np, Image = _load_ocr_deps()
+    image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    arr = np.array(image, dtype=np.uint8)
+    mean = arr.mean(axis=2)
+    spread = arr.max(axis=2) - arr.min(axis=2)
+    text_loose = (spread < 40) & (mean > 60)
+    text_tight = (spread < 30) & (mean > 95)
+    text_closed = closing(text_loose, iterations=1)
+    variants = {
+        "original": pil_to_bytes(image),
+        "text_loose": pil_to_bytes(Image.fromarray((text_loose.astype(np.uint8) * 255), mode="L")),
+        "text_tight": pil_to_bytes(Image.fromarray((text_tight.astype(np.uint8) * 255), mode="L")),
+        "text_closed": pil_to_bytes(Image.fromarray((text_closed.astype(np.uint8) * 255), mode="L")),
+    }
+    bbox = mask_bbox(text_closed)
+    if bbox is not None:
+        x1, y1, x2, y2 = bbox
+        crop = Image.fromarray((text_closed[y1 : y2 + 1, x1 : x2 + 1].astype(np.uint8) * 255), mode="L")
+        nearest = getattr(getattr(Image, "Resampling", Image), "NEAREST")
+        variants["text_closed_crop_x6"] = pil_to_bytes(
+            crop.resize((crop.width * 6, crop.height * 6), nearest)
+        )
+    return variants
+
+
+def logsumexp_pair(a: float, b: float) -> float:
+    _, np, _ = _load_ocr_deps()
+    if a == -np.inf:
+        return b
+    if b == -np.inf:
+        return a
+    m = a if a > b else b
+    return float(m + np.log(np.exp(a - m) + np.exp(b - m)))
+
+
+def ctc_prefix_beam_search(
+    probs: Any,
+    digit_indices: list[int],
+    index_to_digit: dict[int, str],
+    beam_size: int = 25,
+    topk: int = 5,
+    expected_length: int = 4,
+    blank_index: int = 0,
+) -> list[dict[str, Any]]:
+    _, np, _ = _load_ocr_deps()
+    beam: dict[str, tuple[float, float]] = {"": (0.0, -np.inf)}
+    for t in range(probs.shape[0]):
+        next_beam: dict[str, tuple[float, float]] = defaultdict(lambda: (-np.inf, -np.inf))
+        for prefix, (p_b, p_nb) in beam.items():
+            total = logsumexp_pair(p_b, p_nb)
+            nb = next_beam[prefix]
+            next_beam[prefix] = (
+                logsumexp_pair(nb[0], total + float(np.log(probs[t, blank_index] + 1e-12))),
+                nb[1],
+            )
+            if len(prefix) > expected_length:
+                continue
+            for idx in digit_indices:
+                digit = index_to_digit[idx]
+                p = float(np.log(probs[t, idx] + 1e-12))
+                last = prefix[-1] if prefix else None
+                if digit == last:
+                    nb = next_beam[prefix]
+                    next_beam[prefix] = (nb[0], logsumexp_pair(nb[1], p_nb + p))
+                    new_prefix = prefix + digit
+                    if len(new_prefix) <= expected_length:
+                        nb2 = next_beam[new_prefix]
+                        next_beam[new_prefix] = (nb2[0], logsumexp_pair(nb2[1], p_b + p))
+                else:
+                    new_prefix = prefix + digit
+                    if len(new_prefix) <= expected_length:
+                        nb2 = next_beam[new_prefix]
+                        next_beam[new_prefix] = (nb2[0], logsumexp_pair(nb2[1], total + p))
+        ranked = sorted(next_beam.items(), key=lambda kv: logsumexp_pair(kv[1][0], kv[1][1]), reverse=True)
+        beam = dict(ranked[:beam_size])
+    finals = []
+    for prefix, (p_b, p_nb) in beam.items():
+        if len(prefix) == expected_length:
+            finals.append({"text": prefix, "logprob": logsumexp_pair(p_b, p_nb)})
+    finals.sort(key=lambda row: row["logprob"], reverse=True)
+    return finals[:topk]
+
+
+def topk_for_variant(ocr: Any, img: bytes, expected_length: int = 4) -> dict[str, Any]:
+    _, np, _ = _load_ocr_deps()
+    result = ocr.classification(img, probability=True)
+    probs = np.array(result["probabilities"], dtype=np.float64)
+    if probs.ndim == 3:
+        probs = probs[:, 0, :]
+    charset = result["charset"]
+    digit_indices = [i for i, ch in enumerate(charset) if ch.isdigit()]
+    index_to_digit = {i: charset[i] for i in digit_indices}
+    candidates = ctc_prefix_beam_search(probs, digit_indices, index_to_digit, expected_length=expected_length)
+    return {"text": result["text"], "confidence": result["confidence"], "candidates": candidates}
+
+
+def aggregate_variant_candidates(variant_results: dict[str, dict[str, Any]], topk: int = 5) -> list[dict[str, Any]]:
+    scores: dict[str, float] = defaultdict(float)
+    support: dict[str, int] = defaultdict(int)
+    for result in variant_results.values():
+        for rank, row in enumerate(result["candidates"]):
+            scores[row["text"]] += row["logprob"]
+            support[row["text"]] += max(0, topk - rank)
+    ranked = sorted(scores, key=lambda text: (support[text], scores[text]), reverse=True)
+    return [{"text": text, "score": scores[text], "support": support[text]} for text in ranked[:topk]]

chatnet/ecnu/cli.py

@@ -0,0 +1,410 @@
+"""Click commands for ECNU self-service portal operations."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+from chatstyle import CommandField, CommandSchema, add_interactive_option, resolve_command_inputs
+from chatenv.fields import BaseEnvConfig
+from chatenv.paths import get_paths
+
+from chatnet.config import ECNUConfig
+from .portal import BASE_URL
+
+LOGIN_SCHEMA = CommandSchema(
+    name="ecnu-login",
+    fields=(
+        CommandField("username", prompt="ECNU username", required=True),
+        CommandField("password", prompt="ECNU password", required=True, sensitive=True),
+        CommandField("captcha", prompt="captcha", required=True),
+    ),
+)
+
+LOGIN_AUTO_SCHEMA = CommandSchema(
+    name="ecnu-login-auto",
+    fields=(
+        CommandField("username", prompt="ECNU username", required=True),
+        CommandField("password", prompt="ECNU password", required=True, sensitive=True),
+    ),
+)
+
+VISITOR_CREATE_SCHEMA = CommandSchema(
+    name="ecnu-visitor-create",
+    fields=(CommandField("remark", prompt="visitor remark", required=True),),
+)
+
+VISITOR_UPDATE_SCHEMA = CommandSchema(
+    name="ecnu-visitor-update",
+    fields=(
+        CommandField("visitor_id", prompt="visitor id", required=True),
+        CommandField("remark", prompt="visitor remark", required=True),
+        CommandField("password", prompt="visitor password", required=True, sensitive=True),
+    ),
+)
+
+VISITOR_ID_SCHEMA = CommandSchema(
+    name="ecnu-visitor-id",
+    fields=(CommandField("visitor_id", prompt="visitor id", required=True),),
+)
+
+
+@click.group(name="ecnu")
+@click.option("--base-url", default=None, help="ECNU portal base URL. Defaults to chatenv ECNU_BASE_URL.")
+@click.option(
+    "--state-file",
+    default=None,
+    help="Session state JSON file. Defaults to $CHATARCH_HOME/cache/chatnet/ecnu-session.json.",
+)
+@click.option("--cookie", default=None, help="Existing authenticated Cookie header. Defaults to chatenv ECNU_COOKIE.")
+@click.option("-e", "--env", "env_profile", default=None, help="Use a named chatenv ECNU profile.")
+@click.option("--env-file", default=None, help="Explicit env file override for ECNU values.")
+@click.option("--timeout", default=20, show_default=True, type=int, help="HTTP timeout in seconds.")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    base_url: str | None,
+    state_file: str | None,
+    cookie: str | None,
+    env_profile: str | None,
+    env_file: str | None,
+    timeout: int,
+) -> None:
+    """ECNU self-service portal helpers."""
+
+    load_chatenv(env_profile=env_profile, env_file=env_file)
+    ctx.obj = {
+        "base_url": base_url or ECNUConfig.ECNU_BASE_URL.value or BASE_URL,
+        "state_file": Path(state_file).expanduser() if state_file else default_state_file(),
+        "cookie": cookie or ECNUConfig.ECNU_COOKIE.value,
+        "timeout": timeout,
+    }
+
+
+@cli.command(name="selftest")
+def selftest() -> None:
+    """Run local parser self-test without network access."""
+
+    from .portal import run_selftest
+
+    echo_json(run_selftest())
+
+
+@cli.command(name="login-init")
+@click.option(
+    "--captcha-path",
+    default=None,
+    help="Where to save the captcha image. Defaults to $CHATARCH_HOME/cache/chatnet/ecnu-login-captcha.png.",
+)
+@click.pass_context
+def login_init(ctx: click.Context, captcha_path: str | None) -> None:
+    """Fetch login page, reset session state, and download captcha."""
+
+    target_path = Path(captcha_path).expanduser() if captcha_path else default_captcha_path()
+    echo_json(call_client(ctx, lambda client: client.login_init(target_path)))
+
+
+@cli.command(name="login")
+@click.option("--username", default=None, help="ECNU username, or set ECNU_USERNAME.")
+@click.option("--password", default=None, help="ECNU password, or set ECNU_PASSWORD.")
+@click.option("--captcha", default=None, help="Captcha text from login-init image.")
+@click.option("--sms-code", default=None, help="SMS code when required by the server.")
+@add_interactive_option
+@click.pass_context
+def login(
+    ctx: click.Context,
+    username: str | None,
+    password: str | None,
+    captcha: str | None,
+    sms_code: str | None,
+    interactive: bool | None,
+) -> None:
+    """Complete login using username, password, and captcha."""
+
+    values = resolve_command_inputs(
+        schema=LOGIN_SCHEMA,
+        provided={
+            "username": username or ECNUConfig.ECNU_USERNAME.value,
+            "password": password or ECNUConfig.ECNU_PASSWORD.value,
+            "captcha": captcha,
+        },
+        interactive=interactive,
+        usage="Usage: chatnet ecnu login --username TEXT --password TEXT --captcha TEXT [-i|-I]",
+    )
+    echo_json(call_client(ctx, lambda client: client.login(values["username"], values["password"], values["captcha"], sms_code=sms_code)))
+
+
+@cli.command(name="login-auto")
+@click.option("--username", default=None, help="ECNU username, or set ECNU_USERNAME.")
+@click.option("--password", default=None, help="ECNU password, or set ECNU_PASSWORD.")
+@click.option("--sms-code", default=None, help="SMS code when required by the server.")
+@click.option(
+    "--captcha-path",
+    default=None,
+    help="Where to save the latest captcha image. Defaults to $CHATARCH_HOME/cache/chatnet/ecnu-login-captcha.png.",
+)
+@click.option("--rounds", default=3, show_default=True, type=int, help="Captcha refresh rounds.")
+@click.option("--topk", default=5, show_default=True, type=int, help="OCR candidates per captcha.")
+@add_interactive_option
+@click.pass_context
+def login_auto(
+    ctx: click.Context,
+    username: str | None,
+    password: str | None,
+    sms_code: str | None,
+    captcha_path: str | None,
+    rounds: int,
+    topk: int,
+    interactive: bool | None,
+) -> None:
+    """Auto-solve captcha with optional OCR dependencies and try login."""
+
+    values = resolve_command_inputs(
+        schema=LOGIN_AUTO_SCHEMA,
+        provided={"username": username or ECNUConfig.ECNU_USERNAME.value, "password": password or ECNUConfig.ECNU_PASSWORD.value},
+        interactive=interactive,
+        usage="Usage: chatnet ecnu login-auto --username TEXT --password TEXT [-i|-I]",
+    )
+    target_path = Path(captcha_path).expanduser() if captcha_path else default_captcha_path()
+    echo_json(
+        call_client(
+            ctx,
+            lambda client: client.login_auto(
+                values["username"],
+                values["password"],
+                sms_code=sms_code,
+                rounds=rounds,
+                topk=topk,
+                captcha_path=target_path,
+            ),
+        )
+    )
+
+
+@cli.command(name="session-info")
+@click.pass_context
+def session_info(ctx: click.Context) -> None:
+    """Show saved session metadata with Cookie values redacted."""
+
+    echo_json(redact_state(make_client(ctx).state))
+
+
+@cli.command(name="cookie-header")
+@click.pass_context
+def cookie_header(ctx: click.Context) -> None:
+    """Print the current Cookie header from state/session."""
+
+    click.echo(make_client(ctx).cookie_header())
+
+
+@cli.command(name="logout")
+@click.pass_context
+def logout(ctx: click.Context) -> None:
+    """Logout and update saved session state."""
+
+    echo_json(call_client(ctx, lambda client: client.logout()))
+
+
+@cli.command(name="home")
+@click.pass_context
+def home(ctx: click.Context) -> None:
+    """Fetch home summary."""
+
+    echo_json(call_client(ctx, lambda client: client.home_summary()))
+
+
+@cli.command(name="user-info")
+@click.pass_context
+def user_info(ctx: click.Context) -> None:
+    """Fetch user information."""
+
+    echo_json(call_client(ctx, lambda client: client.user_info()))
+
+
+@cli.command(name="auth-log")
+@click.option("--start", default=None, help="Start time.")
+@click.option("--end", default=None, help="End time.")
+@click.option("--limit", default=None, type=int, help="Maximum rows to print.")
+@click.pass_context
+def auth_log(ctx: click.Context, start: str | None, end: str | None, limit: int | None) -> None:
+    """Query authentication logs."""
+
+    echo_json(call_client(ctx, lambda client: client.auth_logs(start, end, limit)))
+
+
+@cli.command(name="detail-log")
+@click.option("--start", default=None, help="Start time.")
+@click.option("--end", default=None, help="End time.")
+@click.option("--limit", default=None, type=int, help="Maximum rows to print.")
+@click.pass_context
+def detail_log(ctx: click.Context, start: str | None, end: str | None, limit: int | None) -> None:
+    """Query network detail logs."""
+
+    echo_json(call_client(ctx, lambda client: client.detail_logs(start, end, limit)))
+
+
+@cli.group(name="visitor")
+def visitor_group() -> None:
+    """Visitor account management."""
+
+
+@visitor_group.command(name="list")
+@click.pass_context
+def visitor_list(ctx: click.Context) -> None:
+    """List visitor accounts."""
+
+    echo_json(call_client(ctx, lambda client: client.list_visitors()))
+
+
+@visitor_group.command(name="get")
+@click.option("--id", "visitor_id", default=None, help="Visitor record id.")
+@click.option("--account", default=None, help="Visitor account name.")
+@click.pass_context
+def visitor_get(ctx: click.Context, visitor_id: str | None, account: str | None) -> None:
+    """Get one visitor by id or account."""
+
+    if not visitor_id and not account:
+        raise click.UsageError("Provide either --id or --account.")
+    echo_json(call_client(ctx, lambda client: client.get_visitor(visitor_id=visitor_id, account=account)))
+
+
+@visitor_group.command(name="create")
+@click.option("--remark", default=None, help="Visitor remark, 2-14 Chinese or English letters.")
+@click.option("--dry-run", is_flag=True, help="Print request spec without submitting.")
+@add_interactive_option
+@click.pass_context
+def visitor_create(ctx: click.Context, remark: str | None, dry_run: bool, interactive: bool | None) -> None:
+    """Create a visitor account."""
+
+    values = resolve_command_inputs(
+        schema=VISITOR_CREATE_SCHEMA,
+        provided={"remark": remark},
+        interactive=interactive,
+        usage="Usage: chatnet ecnu visitor create --remark TEXT [-i|-I]",
+    )
+    echo_json(call_client(ctx, lambda client: client.create_visitor(values["remark"], dry_run=dry_run)))
+
+
+@visitor_group.command(name="update")
+@click.option("--id", "visitor_id", default=None, help="Visitor record id.")
+@click.option("--remark", default=None, help="Visitor remark, 2-14 Chinese or English letters.")
+@click.option("--password", default=None, help="New visitor password.")
+@click.option("--dry-run", is_flag=True, help="Print request spec without submitting.")
+@add_interactive_option
+@click.pass_context
+def visitor_update(
+    ctx: click.Context,
+    visitor_id: str | None,
+    remark: str | None,
+    password: str | None,
+    dry_run: bool,
+    interactive: bool | None,
+) -> None:
+    """Update visitor remark and password."""
+
+    values = resolve_command_inputs(
+        schema=VISITOR_UPDATE_SCHEMA,
+        provided={"visitor_id": visitor_id, "remark": remark, "password": password},
+        interactive=interactive,
+        usage="Usage: chatnet ecnu visitor update --id ID --remark TEXT --password TEXT [-i|-I]",
+    )
+    echo_json(
+        call_client(
+            ctx,
+            lambda client: client.update_visitor(
+                values["visitor_id"],
+                values["remark"],
+                values["password"],
+                dry_run=dry_run,
+            ),
+        )
+    )
+
+
+@visitor_group.command(name="delete")
+@click.option("--id", "visitor_id", default=None, help="Visitor record id.")
+@click.option("--dry-run", is_flag=True, help="Print request spec without submitting.")
+@add_interactive_option
+@click.pass_context
+def visitor_delete(ctx: click.Context, visitor_id: str | None, dry_run: bool, interactive: bool | None) -> None:
+    """Delete a visitor account."""
+
+    values = resolve_command_inputs(
+        schema=VISITOR_ID_SCHEMA,
+        provided={"visitor_id": visitor_id},
+        interactive=interactive,
+        usage="Usage: chatnet ecnu visitor delete --id ID [-i|-I]",
+    )
+    echo_json(call_client(ctx, lambda client: client.delete_visitor(values["visitor_id"], dry_run=dry_run)))
+
+
+@visitor_group.command(name="lock")
+@click.option("--id", "visitor_id", default=None, help="Visitor record id.")
+@click.option("--dry-run", is_flag=True, help="Print request spec without submitting.")
+@add_interactive_option
+@click.pass_context
+def visitor_lock(ctx: click.Context, visitor_id: str | None, dry_run: bool, interactive: bool | None) -> None:
+    """Lock a visitor account."""
+
+    values = resolve_command_inputs(
+        schema=VISITOR_ID_SCHEMA,
+        provided={"visitor_id": visitor_id},
+        interactive=interactive,
+        usage="Usage: chatnet ecnu visitor lock --id ID [-i|-I]",
+    )
+    echo_json(call_client(ctx, lambda client: client.lock_visitor(values["visitor_id"], dry_run=dry_run)))
+
+
+def make_client(ctx: click.Context) -> Any:
+    from .portal import PortalClient
+
+    config = ctx.find_root().obj or ctx.obj or {}
+    return PortalClient(
+        base_url=config["base_url"],
+        state_file=config["state_file"],
+        cookie_header=config.get("cookie"),
+        timeout=config["timeout"],
+    )
+
+
+def call_client(ctx: click.Context, func: Callable[[Any], Any]) -> Any:
+    try:
+        return func(make_client(ctx))
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def echo_json(data: Any) -> None:
+    click.echo(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def load_chatenv(env_profile: str | None = None, env_file: str | None = None) -> None:
+    envs_dir = get_paths().envs_dir
+    if env_profile:
+        BaseEnvConfig.load_all_with_override(
+            envs_dir,
+            ECNUConfig.get_profile_env_file(envs_dir, env_profile),
+        )
+        return
+    if env_file:
+        BaseEnvConfig.load_all_with_override(envs_dir, Path(env_file).expanduser())
+        return
+    BaseEnvConfig.load_all(envs_dir)
+
+
+def default_state_file() -> Path:
+    return get_paths().home_dir / "cache" / "chatnet" / "ecnu-session.json"
+
+
+def default_captcha_path() -> Path:
+    return get_paths().home_dir / "cache" / "chatnet" / "ecnu-login-captcha.png"
+
+
+def redact_state(state: dict[str, Any]) -> dict[str, Any]:
+    redacted = dict(state)
+    cookies = redacted.get("cookies")
+    if isinstance(cookies, dict):
+        redacted["cookies"] = {key: "***" for key in cookies}
+    return redacted