copilot-python 0.1.0__py3-none-any.whl

copilot_python/__init__.py

@@ -0,0 +1,27 @@
+from copilot_wrapper import (
+    CopilotAuthenticationError,
+    CopilotClient,
+    CopilotError,
+    CopilotTimeoutError,
+    DEFAULT_GITHUB_OAUTH_CLIENT_ID,
+    DeviceFlowInfo,
+    GitHubOAuthDeviceFlow,
+    OpenAI,
+    ask_copilot,
+    create_client,
+    login_device_flow,
+)
+
+__all__ = [
+    "CopilotAuthenticationError",
+    "CopilotClient",
+    "CopilotError",
+    "CopilotTimeoutError",
+    "DEFAULT_GITHUB_OAUTH_CLIENT_ID",
+    "DeviceFlowInfo",
+    "GitHubOAuthDeviceFlow",
+    "OpenAI",
+    "ask_copilot",
+    "create_client",
+    "login_device_flow",
+]

copilot_python/__main__.py

@@ -0,0 +1,5 @@
+from copilot_wrapper.__main__ import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copilot_python/cli.py

@@ -0,0 +1,3 @@
+from copilot_wrapper.cli import build_parser, main
+
+__all__ = ["build_parser", "main"]

copilot_python/client.py

@@ -0,0 +1 @@
+from copilot_wrapper.client import *

copilot_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: copilot-python
+Version: 0.1.0
+Summary: A Python wrapper for GitHub Copilot and GitHub Models using the official openai SDK.
+Author: copilot-python contributors
+License: MIT License
+        
+        Copyright (c) 2026 copilot-python contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: github,copilot,cli,wrapper,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.30.0
+Dynamic: license-file
+
+# copilot-python
+
+一個使用官方 `openai` 套件實作的 GitHub Copilot / GitHub Models 包裝庫。
+
+## 功能
+
+- 直接使用官方 `openai.OpenAI`
+- 支援 GitHub OAuth Device Flow 取得 Token
+- 支援手動提供 Fine-grained PAT / API Key
+- 支援 Windows / macOS / Linux
+
+## 前置需求
+
+若使用 GitHub Models，常見端點為：
+
+- `https://models.github.ai/inference`
+- 或你的 OpenAI 相容代理端點
+
+**內建 OAuth Client ID**：本庫已內建公開的 GitHub OAuth App client_id，可直接使用 OAuth Device Flow，無需額外設定。
+
+## 安裝本庫
+
+```bash
+pip install .
+```
+
+或直接安裝依賴：
+
+```bash
+pip install openai
+```
+
+## 快速開始
+
+### 1. 手動提供 API Key / Token
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://models.github.ai/inference",
+    api_key="github_pat_xxxxxxxxx",
+)
+
+response = client.chat.completions.create(
+    messages=[
+        {"role": "system", "content": "你是一個有用的助手。"},
+        {"role": "user", "content": "請解釋什麼是量子糾纏。"},
+    ],
+    model="gpt-4o",
+    temperature=1,
+    max_tokens=4096,
+    top_p=1,
+)
+
+print(response.choices[0].message.content)
+```
+
+### 2. 使用 CLI 命令取得 Token（推薦）
+
+最簡單的方式是使用命令列工具：
+
+```bash
+copilot-python login
+```
+
+這會開啟瀏覽器進行 GitHub 授權，並輸出 access token。
+
+### 3. 程式碼中使用 OAuth Device Flow
+
+```python
+from openai import OpenAI
+from copilot_python import login_device_flow
+
+# 使用內建 client_id，無需額外提供
+token = login_device_flow()
+
+client = OpenAI(
+    base_url="https://models.github.ai/inference",
+    api_key=token,
+)
+```
+
+### 4. 使用 `CopilotClient`
+
+```python
+from copilot_python import CopilotClient
+
+client = CopilotClient(api_key="github_pat_xxxxxxxxx")
+
+reply = client.ask(
+    "如何寫一個 HTTP 伺服器？",
+    model="gpt-4o",
+    system_prompt="你是一個有用的助手。",
+)
+print(reply.choices[0].message.content)
+```
+
+## 建議 Token 類型
+
+常見情境：
+
+- OAuth token：`gho_...`
+- Fine-grained PAT：`github_pat_...`
+- GitHub App user-to-server token：`ghu_...`
+- 視服務而定，可能需要 `models` 或 `Copilot Requests` 權限
+
+## 命令列工具
+
+### 取得 Token
+
+```bash
+copilot-python login
+```
+
+這會：
+1. 顯示 GitHub 裝置授權連結
+2. 自動開啟瀏覽器（可用 `--no-open-browser` 停用）
+3. 等待授權完成
+4. 輸出 access token 到 stdout
+
+完整選項：
+
+```bash
+copilot-python login [--client-id CLIENT_ID] [--scope SCOPE] [--no-open-browser]
+```
+
+## 主要 API
+
+### `login_device_flow()`
+
+程式碼中走 GitHub OAuth Device Flow，回傳 access token。
+
+```python
+from copilot_python import login_device_flow
+
+# 使用內建 client_id
+token = login_device_flow()
+
+# 或自訂 client_id 和 scope
+token = login_device_flow(
+    client_id="你的 client_id",
+    scope="repo user",
+)
+```
+
+### `create_client()`
+
+建立已填入 `base_url` 與 `api_key` 的官方 `OpenAI` client。
+
+```python
+from copilot_python import create_client
+
+client = create_client(base_url="https://models.github.ai/inference", api_key="...")
+```
+
+### `ask_copilot()`
+
+最方便的單次呼叫入口，回傳官方 SDK 的 completion 物件。
+
+```python
+ask_copilot(
+    prompt,
+    *,
+    model,
+    api_key=None,
+    token=None,
+    base_url="https://models.github.ai/inference",
+    system_prompt=None,
+)
+```
+
+### `CopilotClient.ask()`
+
+適合重複呼叫時使用。
+
+## 例外
+
+- `CopilotError`
+- `CopilotAuthenticationError`
+- `CopilotHTTPError`
+- `CopilotTimeoutError`
+
+## 注意事項
+
+1. 這個專案現在是 **基於官方 `openai` SDK** 呼叫 OpenAI 相容聊天 API。
+2. 已內建 GitHub OAuth App client_id，可直接使用 `copilot-python login` 或 `login_device_flow()`。
+3. `base_url` 可指向 GitHub Models 或其他 OpenAI 相容端點。
+4. 若手動提供 PAT，請確認 Token 權限符合目標服務需求。
+5. OAuth Device Flow 的 `scope` 參數取決於你使用的 GitHub OAuth App，內建的 client_id 支援標準 OAuth scopes（如 `repo`, `user` 等）。
+
+## 相容性
+
+舊命令 `copilot-wrapper login` 和舊導入 `from copilot_wrapper import ...` 仍保留向後相容。
+
+## 測試
+
+```bash
+python -m unittest discover -s tests -v
+```

copilot_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+copilot_python/__init__.py,sha256=PqvArCBFbGmkqd_9WVnEXWws5nbFZ27YWG_AUp02Q8U,590
+copilot_python/__main__.py,sha256=UPUNG8l4dNYQ_PQpzsDt_KRe2jvE_1bPKMwMR3w7wuc,103
+copilot_python/cli.py,sha256=oDh4A9OIx9EbuGDUl5TohtHDIvPv01donIxdJEMJJis,88
+copilot_python/client.py,sha256=iiRl2fEGZm3jkeiyvyG-YZHHq2o6aqayLMn-7cadc6I,36
+copilot_python-0.1.0.dist-info/licenses/LICENSE,sha256=JQq3rndxy3V0ZL4hr0m6LjUhhwpS8mgbo9O-zbuhVNg,1105
+copilot_wrapper/__init__.py,sha256=zlnJxyOgOkX4QsC7IxcGA_3Na_7rBU_XI5ltG42j5lA,584
+copilot_wrapper/__main__.py,sha256=XfpjOGon2rVfLtuGychbmZ8s9aEMV4F1pVLAZEJa-OA,83
+copilot_wrapper/cli.py,sha256=bb6cRm80Ue5Jh91Qpt50ZbOtmmrncTXkkijNpuxeNoo,2134
+copilot_wrapper/client.py,sha256=55tcpfGIjsZkFFo5D0atRpCaabCSSIVuJAI-BXhSuu0,10016
+copilot_python-0.1.0.dist-info/METADATA,sha256=BHV6Fh-3kVgG4kHZHgggx-J7DEzoqiZi-pZ8EMlwRIA,6452
+copilot_python-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+copilot_python-0.1.0.dist-info/entry_points.txt,sha256=Wq1Te-18aIC4yVTh9YI2tZ2Z4RKuQ_qec9LRTshjKbk,102
+copilot_python-0.1.0.dist-info/top_level.txt,sha256=h4iccI36DtPcza6z7co3Reo30pYszpr6W9j6wgqLLL4,31
+copilot_python-0.1.0.dist-info/RECORD,,

copilot_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

copilot_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+copilot-python = copilot_python.cli:main
+copilot-wrapper = copilot_wrapper.cli:main

copilot_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 copilot-python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

copilot_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+copilot_python
+copilot_wrapper

copilot_wrapper/__init__.py

@@ -0,0 +1,27 @@
+from .client import (
+    CopilotClient,
+    CopilotError,
+    CopilotAuthenticationError,
+    DEFAULT_GITHUB_OAUTH_CLIENT_ID,
+    DeviceFlowInfo,
+    GitHubOAuthDeviceFlow,
+    OpenAI,
+    CopilotTimeoutError,
+    ask_copilot,
+    create_client,
+    login_device_flow,
+)
+
+__all__ = [
+    "CopilotClient",
+    "CopilotError",
+    "CopilotAuthenticationError",
+    "DEFAULT_GITHUB_OAUTH_CLIENT_ID",
+    "DeviceFlowInfo",
+    "GitHubOAuthDeviceFlow",
+    "OpenAI",
+    "CopilotTimeoutError",
+    "ask_copilot",
+    "create_client",
+    "login_device_flow",
+]

copilot_wrapper/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copilot_wrapper/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .client import DEFAULT_GITHUB_OAUTH_CLIENT_ID, GitHubOAuthDeviceFlow
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    login_parser = subparsers.add_parser("login", help="Run GitHub OAuth Device Flow and print the token.")
+    login_parser.add_argument(
+        "--client-id",
+        default=os.environ.get("GITHUB_OAUTH_CLIENT_ID") or DEFAULT_GITHUB_OAUTH_CLIENT_ID,
+        help="GitHub OAuth App client ID. Defaults to the built-in public client ID, or can be overridden via GITHUB_OAUTH_CLIENT_ID.",
+    )
+    login_parser.add_argument(
+        "--scope",
+        default=None,
+        help="Optional GitHub OAuth scope, e.g. read:user.",
+    )
+    login_parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="HTTP request timeout in seconds.",
+    )
+    login_parser.add_argument(
+        "--no-open-browser",
+        action="store_true",
+        help="Do not open the browser automatically.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "login":
+        return _run_login(args)
+
+    parser.error("Unknown command.")
+    return 2
+
+
+def _run_login(args: argparse.Namespace) -> int:
+    flow = GitHubOAuthDeviceFlow(
+        client_id=args.client_id,
+        scope=args.scope,
+        timeout=args.timeout,
+    )
+    device_flow = flow.start()
+
+    print(f"Verification URL: {device_flow.verification_uri}", file=sys.stderr)
+    print(f"User Code: {device_flow.user_code}", file=sys.stderr)
+    print("完成授權後，token 會輸出到 stdout。", file=sys.stderr)
+
+    if not args.no_open_browser:
+        import webbrowser
+
+        webbrowser.open(device_flow.verification_uri)
+
+    token = flow.poll(device_flow)
+    print(token)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copilot_wrapper/client.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+from openai import OpenAI as _OpenAI
+
+
+DEFAULT_BASE_URL = "https://models.github.ai/inference"
+DEFAULT_GITHUB_OAUTH_CLIENT_ID = "Ov23liZUzHJhxMU267Fs"
+DEVICE_CODE_URL = "https://github.com/login/device/code"
+ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token"
+DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+OpenAI = _OpenAI
+
+
+class CopilotError(RuntimeError):
+    """Base exception for this package."""
+
+
+class CopilotAuthenticationError(CopilotError):
+    """Raised when authentication is missing or rejected."""
+
+
+class CopilotTimeoutError(CopilotError):
+    """Raised when a network request times out."""
+
+
+@dataclass(frozen=True)
+class DeviceFlowInfo:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    expires_in: int
+    interval: int
+
+
+def create_client(
+    *,
+    api_key: Optional[str] = None,
+    token: Optional[str] = None,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = 180.0,
+    **kwargs: Any,
+) -> OpenAI:
+    resolved_api_key = api_key or token or _get_token_from_environment()
+    if not resolved_api_key:
+        raise CopilotAuthenticationError(
+            "未提供 `api_key`。請手動傳入，或設定 `COPILOT_GITHUB_TOKEN`、`GITHUB_TOKEN`、`GH_TOKEN`。"
+        )
+
+    return OpenAI(
+        base_url=base_url,
+        api_key=resolved_api_key,
+        timeout=timeout,
+        **kwargs,
+    )
+
+
+class CopilotClient:
+    """Thin wrapper around the official `openai.OpenAI` client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 180.0,
+        **kwargs: Any,
+    ) -> None:
+        self.client = create_client(
+            api_key=api_key,
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+            **kwargs,
+        )
+
+    @property
+    def chat(self) -> Any:
+        return self.client.chat
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        top_p: Optional[float] = None,
+        **extra_body: Any,
+    ) -> Any:
+        if not isinstance(prompt, str) or not prompt.strip():
+            raise ValueError("`prompt` 必須是非空字串。")
+
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+
+        return self.client.chat.completions.create(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            **extra_body,
+        )
+
+
+class GitHubOAuthDeviceFlow:
+    """Implements GitHub OAuth Device Flow using only the standard library."""
+
+    def __init__(
+        self,
+        *,
+        client_id: str = DEFAULT_GITHUB_OAUTH_CLIENT_ID,
+        scope: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if not client_id:
+            raise ValueError("`client_id` 不能為空。")
+        self.client_id = client_id
+        self.scope = scope
+        self.timeout = timeout
+
+    def start(self) -> DeviceFlowInfo:
+        payload = {"client_id": self.client_id}
+        if self.scope:
+            payload["scope"] = self.scope
+
+        request = urllib.request.Request(
+            DEVICE_CODE_URL,
+            data=urllib.parse.urlencode(payload).encode("utf-8"),
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            method="POST",
+        )
+        data = _request_json(request, timeout=self.timeout)
+        return DeviceFlowInfo(
+            device_code=str(data["device_code"]),
+            user_code=str(data["user_code"]),
+            verification_uri=str(data["verification_uri"]),
+            expires_in=int(data["expires_in"]),
+            interval=int(data.get("interval", 5)),
+        )
+
+    def poll(self, device_flow: DeviceFlowInfo) -> str:
+        deadline = time.time() + device_flow.expires_in
+        interval = device_flow.interval
+
+        while time.time() < deadline:
+            payload = {
+                "client_id": self.client_id,
+                "device_code": device_flow.device_code,
+                "grant_type": DEVICE_GRANT_TYPE,
+            }
+            request = urllib.request.Request(
+                ACCESS_TOKEN_URL,
+                data=urllib.parse.urlencode(payload).encode("utf-8"),
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                method="POST",
+            )
+            response = _request_json(request, timeout=self.timeout)
+
+            access_token = response.get("access_token")
+            if access_token:
+                return str(access_token)
+
+            error = str(response.get("error", ""))
+            if error == "authorization_pending":
+                time.sleep(interval)
+                continue
+            if error == "slow_down":
+                interval = int(response.get("interval", interval + 5))
+                time.sleep(interval)
+                continue
+            if error in {"expired_token", "token_expired"}:
+                raise CopilotAuthenticationError("裝置授權碼已過期，請重新發起 OAuth Device Flow。")
+            if error == "access_denied":
+                raise CopilotAuthenticationError("使用者已拒絕授權。")
+            if error:
+                raise CopilotAuthenticationError(f"OAuth Device Flow 失敗：{error}")
+
+            time.sleep(interval)
+
+        raise CopilotTimeoutError("等待 OAuth Device Flow 授權逾時。")
+
+    def authorize(self, *, open_browser: bool = True, print_instructions: bool = True) -> str:
+        device_flow = self.start()
+        if print_instructions:
+            print(
+                f"請前往 {device_flow.verification_uri} 並輸入驗證碼 {device_flow.user_code} 完成授權。"
+            )
+        if open_browser:
+            webbrowser.open(device_flow.verification_uri)
+        return self.poll(device_flow)
+
+
+def login_device_flow(
+    *,
+    client_id: str = DEFAULT_GITHUB_OAUTH_CLIENT_ID,
+    scope: Optional[str] = None,
+    timeout: float = 30.0,
+    open_browser: bool = True,
+    print_instructions: bool = True,
+) -> str:
+    flow = GitHubOAuthDeviceFlow(client_id=client_id, scope=scope, timeout=timeout)
+    return flow.authorize(open_browser=open_browser, print_instructions=print_instructions)
+
+
+def ask_copilot(
+    prompt: str,
+    *,
+    model: str,
+    api_key: Optional[str] = None,
+    token: Optional[str] = None,
+    base_url: str = DEFAULT_BASE_URL,
+    system_prompt: Optional[str] = None,
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    top_p: Optional[float] = None,
+    timeout: float = 180.0,
+    default_headers: Optional[Mapping[str, str]] = None,
+    **extra_body: Any,
+) -> Any:
+    client = CopilotClient(
+        api_key=api_key or token,
+        base_url=base_url,
+        timeout=timeout,
+        default_headers=default_headers,
+        **extra_body.pop("client_options", {}),
+    )
+    return client.ask(
+        prompt,
+        model=model,
+        system_prompt=system_prompt,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        top_p=top_p,
+        **extra_body,
+    )
+
+
+def _get_token_from_environment() -> Optional[str]:
+    for name in ("COPILOT_GITHUB_TOKEN", "GITHUB_TOKEN", "GH_TOKEN"):
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def _request_json(request: urllib.request.Request, *, timeout: float) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8")
+    except TimeoutError as exc:
+        raise CopilotTimeoutError("網路請求逾時。") from exc
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        payload = _safe_load_json(body)
+        message = _extract_error_message(payload) or body or f"HTTP {exc.code}"
+        raise CopilotAuthenticationError(message) from exc
+    except urllib.error.URLError as exc:
+        raise CopilotError(f"網路連線失敗：{exc.reason}") from exc
+
+    return _safe_load_json(raw)
+
+
+def _safe_load_json(raw: str) -> dict[str, Any]:
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CopilotError("伺服器回應不是有效的 JSON。") from exc
+    if isinstance(data, dict):
+        return data
+    raise CopilotError("伺服器回應不是有效的 JSON 物件。")
+
+
+def _extract_error_message(payload: dict[str, Any]) -> str:
+    error = payload.get("error")
+    if isinstance(error, dict):
+        message = error.get("message")
+        if isinstance(message, str):
+            return message
+    if isinstance(error, str):
+        return error
+    message = payload.get("message")
+    if isinstance(message, str):
+        return message
+    error_description = payload.get("error_description")
+    if isinstance(error_description, str):
+        return error_description
+    return ""