vokit 0.1.4__py3-none-any.whl

vokit/__init__.py

@@ -0,0 +1,51 @@
+"""vokit — VirtualOffice Agent SDK.
+
+一行 ``import vokit`` 完成拦截激活 + API 就绪。
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "0.1.0"
+
+# 避免 "No handler found" 警告（Python 库最佳实践）
+logging.getLogger("vokit").addHandler(logging.NullHandler())
+
+# 1. 激活 monkey patch + 读取配置
+from vokit._patcher import activate as _activate  # noqa: E402
+
+_activate()
+
+# 2. 暴露平台 API
+from vokit._api import get_resources, report_billing, report_metrics, report_status, submit_output  # noqa: E402
+
+# 3. 暴露异常
+from vokit._errors import (  # noqa: E402
+    VokitAPIError,
+    VokitConfigError,
+    VokitError,
+    VokitHTTPError,
+    VokitInterceptError,
+)
+
+# 4. 暴露数据类
+from vokit._models import BillingReport, MetricItem, Resource, TaskStatus  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "submit_output",
+    "get_resources",
+    "report_status",
+    "report_metrics",
+    "report_billing",
+    "Resource",
+    "TaskStatus",
+    "MetricItem",
+    "BillingReport",
+    "VokitError",
+    "VokitConfigError",
+    "VokitAPIError",
+    "VokitHTTPError",
+    "VokitInterceptError",
+]

vokit/_api.py

@@ -0,0 +1,222 @@
+"""vokit 平台 API 封装。"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any
+
+from vokit._client import VokitClient
+from vokit._config import get_config
+from vokit._models import BillingReport, MetricItem, Resource, TaskStatus
+
+logger = logging.getLogger("vokit")
+
+
+def _to_task_dict(task: TaskStatus | dict[str, Any]) -> dict[str, Any]:
+    """将 TaskStatus 或 dict 统一转为 dict。"""
+    if isinstance(task, TaskStatus):
+        return {
+            "name": task.name,
+            "status": task.status,
+            "progress": task.progress,
+        }
+    return dict(task)
+
+
+def submit_output(
+    output_type: str,
+    content: str,
+    filename: str | None = None,
+    mime_type: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """提交产出物。
+
+    Args:
+        output_type: 产出物类型，"file" 或 "url"。
+        content: 产出物内容。file 类型为 base64 编码的内容，url 类型为资源 URL。
+        filename: 文件名，file 类型必填，url 类型可选。
+        mime_type: MIME 类型，file 类型必填，url 类型可选。
+        metadata: 额外的自定义元信息，会合并到最终 metadata 中。
+    """
+    config = get_config()
+
+    if config.is_dev_mode:
+        logger.debug("[Dev] submit_output: type=%s, content=%s", output_type, content[:100])
+        return None
+
+    # 校验 file 类型必填参数
+    if output_type == "file":
+        if not filename:
+            raise ValueError("file 类型必须传入 filename")
+        if not mime_type:
+            raise ValueError("file 类型必须传入 mime_type")
+
+    # 构建 metadata
+    output_metadata: dict[str, Any] = {}
+    if output_type == "file":
+        output_metadata = {
+            "filename": filename,
+            "mime_type": mime_type,
+        }
+    elif output_type == "url":
+        if filename:
+            output_metadata["filename"] = filename
+        if mime_type:
+            output_metadata["mime_type"] = mime_type
+
+    # 合并用户传入的 metadata（函数级参数优先级更高）
+    if metadata:
+        for k, v in metadata.items():
+            output_metadata.setdefault(k, v)
+
+    body = {
+        "output_type": output_type,
+        "content": content,
+        "metadata": output_metadata,
+    }
+
+    with VokitClient() as client:
+        client.post("/api/gateway/output/submit", body=body)
+
+
+def get_resources() -> list[Resource]:
+    """查询工位资源。"""
+    config = get_config()
+
+    if config.is_dev_mode:
+        logger.debug("[Dev] get_resources 返回 mock 数据")
+        return []
+
+    with VokitClient() as client:
+        data = client.get("/api/gateway/resource")
+
+    if data is None or not isinstance(data, dict) or "resources" not in data:
+        return []
+
+    return [
+        Resource(
+            id=r["id"],
+            resource_type=r["resource_type"],
+            name=r["name"],
+            description=r.get("description"),
+            config=r.get("config"),
+            status=r["status"],
+            created_at=r["created_at"],
+            updated_at=r["updated_at"],
+        )
+        for r in data["resources"]
+    ]
+
+
+def report_status(tasks: list[TaskStatus | dict[str, Any]]) -> None:
+    """上报任务状态。"""
+    config = get_config()
+
+    if config.is_dev_mode:
+        logger.debug("[Dev] report_status: tasks=%s", tasks)
+        return None
+
+    body = {
+        "tasks": [_to_task_dict(t) for t in tasks],
+    }
+
+    with VokitClient() as client:
+        client.post("/api/gateway/status/report", body=body)
+
+
+def _to_metric_dict(metric: MetricItem | dict[str, Any]) -> dict[str, Any]:
+    """将 MetricItem 或 dict 统一转为 dict。"""
+    if isinstance(metric, MetricItem):
+        return {
+            "metricType": metric.metricType,
+            "metricValue": metric.metricValue,
+            "snapshotDate": metric.snapshotDate,
+        }
+    return dict(metric)
+
+
+def report_metrics(metrics: list[MetricItem | dict[str, Any]]) -> None:
+    """上报指标数据。"""
+    config = get_config()
+    if config.is_dev_mode:
+        logger.debug("[Dev] report_metrics: metrics=%s", metrics)
+        return None
+    body = {
+        "metrics": [_to_metric_dict(m) for m in metrics],
+    }
+    with VokitClient() as client:
+        client.post("/api/gateway/metric/report", body=body)
+
+
+def report_billing(
+    cost_or_report: int | BillingReport,
+    request_id: str | None = None,
+    call_date: str | None = None,
+    api_type: str | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    prompt_tokens: int | None = None,
+    completion_tokens: int | None = None,
+    total_tokens: int | None = None,
+) -> None:
+    """上报费用记录。
+
+    Args:
+        cost_or_report: 费用金额（int）或 BillingReport 对象。
+        request_id: 唯一标识，由 Agent 自行生成，用于下游去重。传入 BillingReport 时可省略。
+        call_date: 调用日期，格式 YYYY-MM-DD。不传则默认为当天。
+        api_type: 调用类型（如 chat、genImage、genVideo、search_api、translation）。
+        provider: 服务提供商（如 google、openai）。
+        model: 模型/服务名。
+        prompt_tokens: 输入 token 数。
+        completion_tokens: 输出 token 数。
+        total_tokens: 总 token 数。
+    """
+    config = get_config()
+
+    if config.is_dev_mode:
+        logger.debug(
+            "[Dev] report_billing: cost_or_report=%s",
+            cost_or_report,
+        )
+        return None
+
+    if isinstance(cost_or_report, BillingReport):
+        report = cost_or_report
+        request_id = request_id or report.requestId
+        call_date = call_date or report.callDate
+        api_type = api_type if api_type is not None else report.apiType
+        provider = provider if provider is not None else report.provider
+        model = model if model is not None else report.model
+        prompt_tokens = prompt_tokens if prompt_tokens is not None else report.promptTokens
+        completion_tokens = completion_tokens if completion_tokens is not None else report.completionTokens
+        total_tokens = total_tokens if total_tokens is not None else report.totalTokens
+        cost = report.cost
+    else:
+        cost = cost_or_report
+
+    if call_date is None:
+        call_date = datetime.date.today().isoformat()
+
+    body = {
+        "requestId": request_id,
+        "cost": cost,
+        "callDate": call_date,
+    }
+    if api_type is not None:
+        body["apiType"] = api_type
+    if provider is not None:
+        body["provider"] = provider
+    if model is not None:
+        body["model"] = model
+    if prompt_tokens is not None:
+        body["promptTokens"] = prompt_tokens
+    if completion_tokens is not None:
+        body["completionTokens"] = completion_tokens
+    if total_tokens is not None:
+        body["totalTokens"] = total_tokens
+
+    with VokitClient() as client:
+        client.post("/api/gateway/billing/report", body=body)

vokit/_client.py

@@ -0,0 +1,81 @@
+"""内部 HTTP Client。
+
+基于 httpx 同步客户端，供平台 API 使用。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from vokit._config import get_config
+from vokit._errors import VokitAPIError, VokitHTTPError
+
+
+class VokitClient:
+    """内部 HTTP 客户端，自动携带鉴权 headers。"""
+
+    def __init__(self) -> None:
+        config = get_config()
+        self._base_url = config.gateway_url or "http://localhost"
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0),
+            trust_env=False,
+            headers={
+                "Authorization": f"Bearer {config.access_token}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    def _parse_response(self, status_code: int, body: dict[str, Any]) -> dict[str, Any] | list[Any] | None:
+        """解析网关响应。
+
+        - HTTP 非 200 → VokitHTTPError
+        - success==false 或 code!=0 → VokitAPIError
+        - 成功 → 返回 data 字段
+        """
+        if status_code != 200:
+            raise VokitHTTPError(status_code, str(body))
+
+        success = body.get("success", False)
+        code = body.get("code", -1)
+        msg = body.get("msg", "unknown error")
+        trace_id = body.get("traceId") or body.get("trace_id")
+
+        if not success or code != 0:
+            raise VokitAPIError(code=code, msg=msg, trace_id=trace_id)
+
+        return body.get("data")
+
+    def get(self, path: str) -> dict[str, Any] | list[Any] | None:
+        """发起 GET 请求，返回解析后的 data 字段。"""
+        try:
+            resp = self._client.get(path)
+            return self._parse_response(resp.status_code, resp.json())
+        except httpx.RequestError as e:
+            raise VokitAPIError(code=-1, msg=f"网络请求失败: {e}") from e
+        except (json.JSONDecodeError, httpx.DecodingError) as e:
+            raise VokitAPIError(code=-1, msg=f"响应解析失败: {e}") from e
+
+    def post(self, path: str, body: dict[str, Any]) -> dict[str, Any] | list[Any] | None:
+        """发起 POST 请求，返回解析后的 data 字段。"""
+        try:
+            resp = self._client.post(path, json=body)
+            return self._parse_response(resp.status_code, resp.json())
+        except httpx.RequestError as e:
+            raise VokitAPIError(code=-1, msg=f"网络请求失败: {e}") from e
+        except (json.JSONDecodeError, httpx.DecodingError) as e:
+            raise VokitAPIError(code=-1, msg=f"响应解析失败: {e}") from e
+
+    def close(self) -> None:
+        """关闭底层连接。"""
+        self._client.close()
+
+    def __enter__(self) -> "VokitClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

vokit/_config.py

@@ -0,0 +1,74 @@
+"""vokit 环境变量读取与校验。"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+
+logger = logging.getLogger("vokit")
+
+
+class Config:
+    """SDK 配置。import 时自动读取环境变量。"""
+
+    def __init__(self) -> None:
+        self._gateway_url: str | None = os.environ.get("VO_GATEWAY_URL")
+        self._access_token: str | None = os.environ.get("VO_ACCESS_TOKEN")
+
+        # 强制开发模式
+        if os.environ.get("VO_DEV_MODE") == "1":
+            self._gateway_url = None
+            self._access_token = None
+            logger.warning("VO_DEV_MODE=1，强制进入开发模式。LLM 请求将直连原始 Provider。")
+            return
+
+        # 缺少必填环境变量 → 开发模式
+        if not self._gateway_url or not self._access_token:
+            missing = []
+            if not self._gateway_url:
+                missing.append("VO_GATEWAY_URL")
+            if not self._access_token:
+                missing.append("VO_ACCESS_TOKEN")
+            logger.warning(
+                "%s 未配置，进入开发模式。LLM 请求将直连原始 Provider。",
+                "、".join(missing),
+            )
+
+        logger.debug(
+            "vokit 配置: gateway_url=%s, access_token=%s",
+            self._gateway_url,
+            f"{self._access_token[:6]}..." if self._access_token else "(未设置)",
+        )
+
+    @property
+    def is_dev_mode(self) -> bool:
+        return self._gateway_url is None or self._access_token is None
+
+    @property
+    def gateway_url(self) -> str | None:
+        return self._gateway_url
+
+    @property
+    def access_token(self) -> str | None:
+        return self._access_token
+
+
+_config: Config | None = None
+_config_lock = threading.Lock()
+
+
+def get_config() -> Config:
+    """获取全局配置单例。"""
+    global _config
+    if _config is None:
+        with _config_lock:
+            if _config is None:
+                _config = Config()
+    return _config
+
+
+def reset_config() -> None:
+    """重置配置单例。仅供测试使用。"""
+    global _config
+    _config = None

vokit/_errors.py

@@ -0,0 +1,45 @@
+"""自定义异常类。
+
+包含 VokitError, VokitConfigError, VokitAPIError, VokitHTTPError。
+"""
+
+
+class VokitError(Exception):
+    """vokit 所有异常的基类。"""
+
+
+class VokitConfigError(VokitError):
+    """配置错误：环境变量缺失或无效。"""
+
+
+class VokitAPIError(VokitError):
+    """网关业务错误：success == false 或 code != 0。"""
+
+    def __init__(self, code: int, msg: str, trace_id: str | None = None) -> None:
+        self.code = code
+        self.msg = msg
+        self.trace_id = trace_id
+        super().__init__(f"API error: code={code}, msg={msg}, traceId={trace_id}")
+
+
+class VokitHTTPError(VokitError):
+    """HTTP 错误：非 200 状态码。"""
+
+    def __init__(self, status_code: int, response_text: str) -> None:
+        self.status_code = status_code
+        self.response_text = response_text
+        super().__init__(f"HTTP error: status={status_code}, body={response_text[:200]}")
+
+
+class VokitInterceptError(VokitError):
+    """拦截错误：拦截匹配但处理失败。
+
+    拦截和转发是核心需求，匹配到规则后出错不允许降级到原始请求，
+    而是抛出此异常由业务代码处理。
+    """
+
+    def __init__(self, message: str, original_url: str | None = None) -> None:
+        self.message = message
+        self.original_url = original_url
+        url_info = f", url={original_url}" if original_url else ""
+        super().__init__(f"Intercept error: {message}{url_info}")

vokit/_interceptor.py

@@ -0,0 +1,137 @@
+"""核心拦截逻辑。
+
+接收不同 HTTP 库的请求对象，提取 URL、body 和 headers，
+调用 _providers.match_request() 判断是否需要拦截。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+
+from vokit._config import get_config
+from vokit._providers import match_request
+
+logger = logging.getLogger("vokit")
+
+INTERCEPTED_MARKER = "1"
+INTERCEPTED_HEADER = "X-Vokit-Intercepted"
+
+
+def _extract_original_auth(original_headers: dict[str, Any]) -> tuple[str | None, str | None]:
+    """提取原始认证信息，返回 (X-Original-Auth, X-Upstream-Auth-Header)。
+
+    原始 headers dict 的 key 可能已被 HTTP 库小写化（如 httpx），
+    因此使用小写 key 查找。
+    """
+    # original_headers 的 key 已在 intercept_request 入口统一小写化
+    auth = original_headers.get("authorization")
+    if auth:
+        return auth, "Authorization"
+    api_key = original_headers.get("x-api-key")
+    if api_key:
+        return api_key, "X-Api-Key"
+    return None, None
+
+
+def build_intercept_headers(
+    original_headers: dict[str, Any],
+    original_url: str,
+) -> dict[str, str]:
+    """构建拦截后的新 headers。
+
+    original_headers 的 key 已在 intercept_request 入口统一小写化。
+    """
+    config = get_config()
+    new_headers: dict[str, str] = {}
+
+    # 保留原始 headers 中不需要改写的部分（排除将被覆盖的）
+    skip_headers = {"authorization", "x-api-key", "x-vokit-intercepted"}
+    for k, v in original_headers.items():
+        if k not in skip_headers:
+            new_headers[k] = v
+
+    # 网关鉴权
+    if config.access_token:
+        new_headers["Authorization"] = f"Bearer {config.access_token}"
+
+    # 原始 URL
+    new_headers["X-Original-Url"] = original_url
+
+    # 原始认证标准化
+    original_auth, auth_header = _extract_original_auth(original_headers)
+    if original_auth is not None:
+        new_headers["X-Original-Auth"] = original_auth
+        if auth_header is not None:
+            new_headers["X-Upstream-Auth-Header"] = auth_header
+        logger.debug("提取原始认证: auth_header=%s", auth_header)
+    else:
+        logger.debug("未找到原始认证信息 (Authorization / X-Api-Key)")
+
+    # 保留原始 X-Api-Key（如存在）
+    original_api_key = original_headers.get("x-api-key")
+    if original_api_key:
+        new_headers["X-API-Key"] = original_api_key
+
+    # 防重复拦截
+    new_headers[INTERCEPTED_HEADER] = INTERCEPTED_MARKER
+
+    return new_headers
+
+
+def intercept_request(
+    original_url: str,
+    body: bytes | dict[str, Any] | str | None,
+    headers: dict[str, Any] | None,
+) -> tuple[str, dict[str, str]] | None:
+    """拦截并重写 URL 和 headers。
+
+    返回 (new_url, new_headers)，不匹配时返回 None。
+    """
+    # 统一小写化 headers key（httpx 会将 key 小写化，requests/urllib3 保留原始大小写）
+    # 在入口处规范化一次，让后续所有逻辑均使用小写 key
+    header_dict = {k.lower(): v for k, v in headers.items()} if headers else {}
+
+    # 防重复拦截（使用小写 key 查找）
+    if header_dict.get(INTERCEPTED_HEADER.lower()):
+        return None
+
+    # Path 匹配
+    route = match_request(original_url, body, header_dict)
+    if route is None:
+        return None
+
+    # 构建新 URL
+    config = get_config()
+    if config.gateway_url is None:
+        logger.debug("gateway_url 未配置，跳过拦截: %s", original_url)
+        return None
+
+    parsed_gateway = urlparse(config.gateway_url)
+    original_parsed = urlparse(original_url)
+    new_url = urlunparse(
+        (
+            parsed_gateway.scheme,
+            parsed_gateway.netloc,
+            route.gateway_path,
+            "",  # params
+            original_parsed.query,  # preserve query
+            "",  # fragment
+        )
+    )
+
+    # 构建新 headers
+    new_headers = build_intercept_headers(header_dict, original_url)
+
+    logger.debug(
+        "拦截重写: %s %s → %s %s (stream=%s)",
+        original_parsed.scheme,
+        original_url,
+        parsed_gateway.scheme,
+        new_url,
+        route.is_stream,
+    )
+    logger.debug("新 headers: %s", list(new_headers.keys()))
+
+    return new_url, new_headers

vokit/_models.py

@@ -0,0 +1,79 @@
+"""数据类定义。
+
+包含 Resource, TaskStatus, RouteResult 等数据类。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class RouteResult:
+    """Path 匹配结果。"""
+
+    gateway_path: str
+    is_stream: bool
+
+
+@dataclass
+class Resource:
+    """工位资源数据类。"""
+
+    id: int
+    resource_type: str
+    name: str
+    description: str | None
+    config: dict[str, Any] | None
+    status: int
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class TaskStatus:
+    """任务状态。
+
+    Python 3.10 不支持 StrEnum，使用类常量字符串。
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    name: str
+    status: str
+    progress: float
+
+
+@dataclass
+class MetricItem:
+    """指标数据项。
+
+    字段使用 camelCase，以便 __dict__ 可直接用于构建 JSON 请求体。
+    """
+
+    metricType: str
+    metricValue: int
+    snapshotDate: str
+
+
+@dataclass
+class BillingReport:
+    """Agent 主动上报的费用记录。
+
+    字段使用 camelCase，以便 __dict__ 可直接用于构建 JSON 请求体。
+    """
+
+    requestId: str
+    cost: int
+    callDate: str
+    apiType: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    promptTokens: int | None = None
+    completionTokens: int | None = None
+    totalTokens: int | None = None

vokit/_patcher.py

@@ -0,0 +1,270 @@
+"""vokit monkey patch 注册逻辑。
+
+使用 wrapt.wrap_function_wrapper 拦截四大 HTTP 库的 send 入口。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from vokit._config import get_config
+from vokit._errors import VokitInterceptError
+from vokit._interceptor import intercept_request
+
+logger = logging.getLogger("vokit")
+
+_patched = False
+
+
+def _handle_sync_request(wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    """同步请求通用拦截处理（httpx.Client / requests.Session）。
+
+    拦截匹配但处理失败时抛出 VokitInterceptError，不降级到原始请求。
+    """
+    request = args[0]
+    original_url = str(request.url)
+    body = getattr(request, "content", None) or getattr(request, "body", None)
+    headers = dict(getattr(request, "headers", {}))
+
+    body_size = len(body) if body else 0
+    logger.debug("同步请求拦截: url=%s, body_size=%d", original_url, body_size)
+
+    result = intercept_request(original_url, body, headers if headers else None)
+
+    if result is not None:
+        try:
+            new_url, new_headers = result
+            logger.debug("应用重写: url=%s", new_url)
+            # httpx.Request.url 需要是 httpx.URL 对象，requests.Request.url 是字符串
+            if type(request).__module__.startswith("httpx"):
+                import httpx
+
+                request.url = httpx.URL(new_url)
+            else:
+                request.url = new_url
+            request.headers.clear()
+            for k, v in new_headers.items():
+                request.headers[k] = v
+        except Exception as e:
+            raise VokitInterceptError(f"拦截重写失败: {e}", original_url=original_url) from e
+    else:
+        logger.debug("未匹配拦截规则，原样放行: %s", original_url)
+
+    return wrapped(*args, **kwargs)
+
+
+async def _handle_httpx_async(wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    """httpx.AsyncClient.send() 异步拦截。
+
+    拦截匹配但处理失败时抛出 VokitInterceptError，不降级到原始请求。
+    """
+    request = args[0]
+    original_url = str(request.url)
+    body = getattr(request, "content", None)
+    headers = dict(getattr(request, "headers", {}))
+
+    body_size = len(body) if body else 0
+    logger.debug("异步请求拦截(httpx): url=%s, body_size=%d", original_url, body_size)
+
+    result = intercept_request(original_url, body, headers if headers else None)
+
+    if result is not None:
+        try:
+            new_url, new_headers = result
+            logger.debug("应用重写: url=%s", new_url)
+            import httpx
+
+            request.url = httpx.URL(new_url)
+            request.headers.clear()
+            for k, v in new_headers.items():
+                request.headers[k] = v
+        except Exception as e:
+            raise VokitInterceptError(f"拦截重写失败: {e}", original_url=original_url) from e
+    else:
+        logger.debug("未匹配拦截规则，原样放行: %s", original_url)
+
+    return await wrapped(*args, **kwargs)
+
+
+async def _handle_aiohttp_async(wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    """aiohttp.ClientSession._request() 异步拦截。
+
+    aiohttp 签名: _request(self, method, str_or_url, ...)
+    拦截匹配但处理失败时抛出 VokitInterceptError，不降级到原始请求。
+    """
+    # args[0] = method (str), args[1] or kwargs['str_or_url'] = url
+    str_or_url = args[1] if len(args) > 1 else kwargs.get("str_or_url", "")
+    original_url = str(str_or_url)
+
+    # headers 可能为 CIMultiDict 或 dict，优先从位置参数读取，其次从 kwargs 读取
+    if len(args) > 2 and args[2] is not None:
+        raw_headers = args[2]
+    else:
+        raw_headers = kwargs.get("headers", {})
+    headers = dict(raw_headers) if raw_headers else {}
+
+    # body 通过 json= 或 data= 参数传入
+    body = kwargs.get("json") or kwargs.get("data")
+
+    body_desc = str(body)[:100] if body else "(空)"
+    logger.debug("异步请求拦截(aiohttp): url=%s, body=%s", original_url, body_desc)
+
+    result = intercept_request(original_url, body, headers if headers else None)
+
+    if result is not None:
+        try:
+            new_url, new_headers = result
+            logger.debug("应用重写: url=%s", new_url)
+            # 重写 URL 参数
+            if len(args) > 1:
+                args_list = list(args)
+                args_list[1] = new_url
+                args = tuple(args_list)
+            else:
+                kwargs["str_or_url"] = new_url
+            # 重写 headers，写回对应位置
+            if len(args) > 2:
+                args_list = list(args)
+                args_list[2] = type(args[2])(new_headers)
+                args = tuple(args_list)
+            else:
+                kwargs["headers"] = new_headers
+        except Exception as e:
+            raise VokitInterceptError(f"拦截重写失败: {e}", original_url=original_url) from e
+    else:
+        logger.debug("未匹配拦截规则，原样放行: %s", original_url)
+
+    return await wrapped(*args, **kwargs)
+
+
+def _handle_urllib3_request(wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    """urllib3 HTTPConnectionPool.urlopen() 专用拦截。
+
+    不修改 pool 属性（避免线程安全问题），而是将 url 参数替换为
+    完整网关绝对 URL，并设置 assert_same_host=False 使 urllib3
+    自动路由到网关对应的连接池。
+    拦截匹配但处理失败时抛出 VokitInterceptError，不降级到原始请求。
+    """
+    pool = instance
+    scheme = getattr(pool, "scheme", "https")
+    host = getattr(pool, "host", "")
+    port = getattr(pool, "port", None)
+
+    url = args[0] if args else kwargs.get("url", "")
+    body = args[2] if len(args) > 2 else kwargs.get("body")
+    headers = dict(args[3]) if len(args) > 3 else dict(kwargs.get("headers", {}))
+
+    full_url = f"{scheme}://{host}"
+    if port and ((scheme == "http" and port != 80) or (scheme == "https" and port != 443)):
+        full_url += f":{port}"
+    full_url += url
+
+    body_size = len(body) if body else 0
+    logger.debug("请求拦截(urllib3): full_url=%s, body_size=%d", full_url, body_size)
+
+    result = intercept_request(full_url, body, headers if headers else None)
+
+    if result is not None:
+        try:
+            new_url, new_headers = result
+            logger.debug("应用重写: url=%s", new_url)
+
+            # 将 url 参数替换为完整网关绝对 URL
+            if args:
+                args_list = list(args)
+                args_list[0] = new_url
+                args = tuple(args_list)
+            else:
+                kwargs["url"] = new_url
+
+            # 设置 assert_same_host=False 允许跨 host 转发
+            kwargs["assert_same_host"] = False
+
+            # 重写 headers
+            if len(args) > 3:
+                args_list = list(args)
+                args_list[3] = type(args[3])(new_headers)
+                args = tuple(args_list)
+            else:
+                kwargs["headers"] = new_headers
+        except Exception as e:
+            raise VokitInterceptError(f"拦截重写失败: {e}", original_url=full_url) from e
+    else:
+        logger.debug("未匹配拦截规则，原样放行: %s", full_url)
+
+    return wrapped(*args, **kwargs)
+
+
+def _try_patch(module_path: str, attr: str, wrapper: Any, required: bool = False) -> bool:
+    """尝试对指定模块的属性进行 wrapt patch。
+
+    Args:
+        required: True 表示核心依赖，patch 失败时抛异常；
+                  False 表示可选依赖，patch 失败时静默跳过。
+    """
+    try:
+        import wrapt
+    except ImportError:
+        if required:
+            logger.error("wrapt 未安装，无法注册 monkey patch（核心依赖）")
+            raise
+        logger.debug("Monkey patch skipped (optional): %s — wrapt 未安装", module_path)
+        return False
+
+    # wrapt.wrap_function_wrapper 的第一个参数如果是字符串，会尝试将其作为模块导入。
+    # 对于 "httpx.Client" 这样的路径，__import__("httpx.Client") 会失败。
+    # 因此我们先自行解析路径，获取实际对象后再传给 wrapt。
+    try:
+        parts = module_path.split(".")
+        module_name = parts[0]
+        import importlib
+
+        mod = importlib.import_module(module_name)
+        target = mod
+        for part in parts[1:]:
+            target = getattr(target, part)
+    except (ModuleNotFoundError, AttributeError, ImportError) as e:
+        if required:
+            logger.error("Monkey patch 失败（核心依赖）: %s.%s — %s", module_path, attr, e)
+            raise
+        logger.debug("Monkey patch skipped (optional): %s.%s — %s", module_path, attr, e)
+        return False
+
+    try:
+        wrapt.wrap_function_wrapper(target, attr, wrapper)
+        logger.debug("Monkey patch registered: %s.%s", module_path, attr)
+        return True
+    except (AttributeError, ModuleNotFoundError) as e:
+        if required:
+            logger.error("Monkey patch 失败（核心依赖）: %s.%s — %s", module_path, attr, e)
+            raise
+        logger.debug("Monkey patch skipped (optional): %s.%s — %s", module_path, attr, e)
+        return False
+
+
+def activate() -> None:
+    """激活 monkey patch。幂等。"""
+    global _patched
+    if _patched:
+        return
+
+    config = get_config()
+    if config.is_dev_mode:
+        logger.debug("开发模式，不激活 monkey patch")
+        _patched = True
+        return
+
+    # httpx 同步（核心依赖）
+    _try_patch("httpx.Client", "send", _handle_sync_request, required=True)
+    # httpx 异步（核心依赖）
+    _try_patch("httpx.AsyncClient", "send", _handle_httpx_async, required=True)
+    # requests 同步（可选）
+    _try_patch("requests.Session", "send", _handle_sync_request)
+    # urllib3 同步（可选）
+    _try_patch("urllib3.HTTPConnectionPool", "urlopen", _handle_urllib3_request)
+    # aiohttp 异步（可选）
+    _try_patch("aiohttp.client", "ClientSession._request", _handle_aiohttp_async)
+
+    _patched = True
+    logger.info("vokit monkey patch 已激活")

vokit/_providers.py

@@ -0,0 +1,139 @@
+"""Path 规则引擎。
+
+定义 Path 匹配模式和规范 Path 映射，提供 match_request() 核心函数。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+from urllib.parse import urlparse
+
+from vokit._models import RouteResult
+
+logger = logging.getLogger("vokit")
+
+
+# Path 匹配 -> 请求类型
+_CHAT_PATHS = {
+    "/v1/chat/completions",
+    "/compatible-mode/v1/chat/completions",
+    "/v4/chat/completions",
+    "/api/paas/v4/chat/completions",
+    "/api/v3/chat/completions",
+    "/v1/messages",
+    "/apps/anthropic/v1/messages",
+    "/api/v1/services/aigc/text-generation/generation",
+    "/v1/completions",
+}
+
+_IMAGE_PATHS = {
+    "/v1/images/generations",
+    "/api/v1/services/aigc/text2image/image-synthesis",
+    "/api/v3/images/generations",
+}
+
+_VIDEO_PATHS = {
+    "/api/v1/services/aigc/video-generation/video-synthesis",
+    "/v4/videos/generations",
+    "/api/paas/v4/videos/generations",
+    "/api/v3/videos/generations",
+    "/v1/contents/generations",
+    "/api/v3/contents/generations",
+}
+
+# 需要前缀匹配的路径（子路径也属于同一类型）
+_VIDEO_PATH_PREFIXES = ("/api/v3/contents/generations/tasks",)
+
+# 请求类型 -> 网关规范 Path
+_GATEWAY_PATH_MAP: dict[str, tuple[str, str]] = {
+    # request_type: (normal_path, stream_path)
+    "chat": ("/api/gateway/llm/chat", "/api/gateway/llm/chat/stream"),
+    "image": ("/api/gateway/multimodal/images/generations", "/api/gateway/multimodal/images/generations"),
+    "video": ("/api/gateway/multimodal/videos/generations/tasks", "/api/gateway/multimodal/videos/generations/tasks"),
+}
+
+
+def _decode_body(body: bytes | dict[str, Any] | str | None) -> dict[str, Any] | None:
+    """将 body 统一解码为 dict。非 JSON 或解析失败返回 None。"""
+    if body is None:
+        return None
+    if isinstance(body, dict):
+        return body
+    if isinstance(body, bytes):
+        try:
+            result: Any = json.loads(body)
+            return result if isinstance(result, dict) else None
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return None
+    if isinstance(body, str):
+        try:
+            result = json.loads(body)
+            return result if isinstance(result, dict) else None
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def _detect_stream(body: bytes | dict[str, Any] | str | None, headers: dict[str, Any] | None) -> bool:
+    """检测是否流式请求。
+
+    headers 的 key 可能已经被小写化（来自 intercept_request 入口），
+    也可能保留原始大小写（来自直接调用）。Accept 检查使用 case-insensitive 查找。
+    """
+    body_dict = _decode_body(body)
+    if body_dict and body_dict.get("stream") is True:
+        return True
+    # DashScope 通过 Accept: text/event-stream 标识流式（I2 修复：case-insensitive 查找）
+    if headers:
+        accept_value = next((v for k, v in headers.items() if k.lower() == "accept"), "")
+        if "text/event-stream" in accept_value:
+            return True
+    return False
+
+
+def _classify_path(path: str) -> str | None:
+    """根据 Path 判断请求类型。"""
+    if path in _CHAT_PATHS:
+        return "chat"
+    if path in _IMAGE_PATHS:
+        return "image"
+    if path in _VIDEO_PATHS:
+        return "video"
+    # 前缀匹配
+    if path.startswith(_VIDEO_PATH_PREFIXES):
+        return "video"
+    return None
+
+
+def match_request(
+    url: str,
+    body: bytes | dict[str, Any] | str | None,
+    headers: dict[str, Any] | None,
+) -> RouteResult | None:
+    """匹配 URL Path，返回路由结果或 None。"""
+    parsed = urlparse(url)
+    path = parsed.path
+
+    request_type = _classify_path(path)
+    if request_type is None:
+        logger.debug("Path 不匹配，原样放行: %s", url)
+        return None
+
+    gateway_paths = _GATEWAY_PATH_MAP[request_type]
+    normal_path, stream_path = gateway_paths
+
+    # 只有 chat 类型支持流式
+    is_stream = False
+    if request_type == "chat":
+        is_stream = _detect_stream(body, headers)
+
+    gateway_path = stream_path if is_stream else normal_path
+    logger.debug(
+        "Path 匹配: request_type=%s, is_stream=%s, gateway_path=%s",
+        request_type,
+        is_stream,
+        gateway_path,
+    )
+    return RouteResult(gateway_path=gateway_path, is_stream=is_stream)

vokit-0.1.4.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: vokit
+Version: 0.1.4
+Summary: VirtualOffice Agent SDK — 透明拦截转发 + 平台 API 封装
+Author: VirtualOffice Team
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: wrapt>=1.15
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: aiohttp>=3.8; extra == "dev"
+Requires-Dist: requests>=2.28; extra == "dev"
+Requires-Dist: urllib3>=1.26; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# vokit — VirtualOffice Agent SDK
+
+一行 `import vokit` 完成拦截激活 + API 就绪。
+
+## 安装
+
+```bash
+# 预发布版本
+pip install git+http://oauth2:YOUR_TOKEN@gitlab.deepleaper.com/deepbrain/vokit-sdk.git@prerelease
+```
+
+## 快速开始
+
+### 1. 拦截 LLM 请求
+
+在 Agent 的**入口文件最顶部** import 一次即可：
+
+```python
+import vokit
+```
+
+- **只需 import 一次**：patch 注册在进程级别的 HTTP 库入口，全局生效。
+- **放在最顶部**：确保在所有 LLM SDK 被 import 之前 patch 已注册好。
+- **幂等安全**：多次 import 不会重复注册。
+
+### 2. 使用平台 API
+
+```python
+import vokit
+
+# 提交产出物
+vokit.submit_output(
+    output_type="text",
+    content="分析报告内容..."
+)
+
+# 查询工位资源
+resources = vokit.get_resources()
+
+# 上报任务状态
+vokit.report_status(tasks=[
+    {"name": "task-1", "status": "running", "progress": 0.75},
+])
+
+# 上报指标数据
+vokit.report_metrics(metrics=[
+    {"metricType": "tokens_used", "metricValue": 1500, "snapshotDate": "2026-04-14"},
+])
+```
+
+## 运行模式
+
+### 开发模式
+
+不设置 `VO_GATEWAY_URL` 和 `VO_ACCESS_TOKEN` 时自动进入：
+- LLM 请求**直连** Provider，不被拦截
+- 平台 API 返回 Mock 数据
+
+```bash
+export OPENAI_API_KEY="your-key"
+python your_agent.py
+```
+
+### 生产模式
+
+设置环境变量后自动进入：
+
+```bash
+export VO_GATEWAY_URL=http://localhost:8888
+export VO_ACCESS_TOKEN=<your-jwt-token>
+export OPENAI_API_KEY="your-key"
+python your_agent.py
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `VO_GATEWAY_URL` | 内网网关地址，缺失则进入开发模式 |
+| `VO_ACCESS_TOKEN` | 网关 Bearer Token，缺失则进入开发模式 |
+
+## Python 版本
+
+要求 Python 3.10+
+
+## License
+
+MIT

vokit-0.1.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+vokit/__init__.py,sha256=_hP00T2Q80lafv7t-_0-bv4-naWbR6FO9-Z7rLRPhp8,1156
+vokit/_api.py,sha256=a_paY5kkbCmJpOB9tLlnr_5hwQwpc130vYyhv6ioJ4A,7036
+vokit/_client.py,sha256=scYstgb_Evpj0H-wzRfU1Pp1Fte8t4SYfYZ2J897IM8,2856
+vokit/_config.py,sha256=2jKGLIgbELOJYK6Qq1swnuVgvXJq2WlUIvix-kcjD8s,2107
+vokit/_errors.py,sha256=yYnOkoEhJ3Js6qKrH2gTW3opWWyAXknwXM_at70Xw7c,1470
+vokit/_interceptor.py,sha256=5rrAOdQFeeUyBB49HtcbkC06_BxXqzKyE8ARODcyRAg,4296
+vokit/_models.py,sha256=bZ2q20sCs2tm6wFUJJNqIjnEqCyL1bRH_0uZanWYxMk,1463
+vokit/_patcher.py,sha256=IBk-KgvtTVqUw4oYQwe0cvyuK2jv9SD8jMzcKym3lX8,10250
+vokit/_providers.py,sha256=1ZoLSKvlx3SeCxBBGDOrUihiWeN2TMA9kjAvO3f4QCc,4372
+vokit-0.1.4.dist-info/METADATA,sha256=xROuYtHrTD12ZQEIdJJnQt8Va8qGO5mqXPOCGNYUZng,2497
+vokit-0.1.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vokit-0.1.4.dist-info/top_level.txt,sha256=dR9DTs661y7ViJn87GRzmwWsmQaJiKuDPszIn2Mb0CM,6
+vokit-0.1.4.dist-info/RECORD,,

vokit-0.1.4.dist-info/WHEEL

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

vokit-0.1.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+vokit