agent-webview 0.1.3__tar.gz → 0.1.4__tar.gz

{agent_webview-0.1.3 → agent_webview-0.1.4}/.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python: ["3.10", "3.13"]
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           python-version: ${{ matrix.python }}
@@ -34,7 +34,7 @@ jobs:
   release-check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           python-version: "3.13"

{agent_webview-0.1.3 → agent_webview-0.1.4}/.github/workflows/publish.yml

@@ -11,7 +11,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.release.tag_name }}
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
@@ -19,7 +19,7 @@ jobs:
           python-version: "3.13"
       - run: python scripts/release_check.py
       - run: uv build --out-dir dist
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: python-package
           path: dist/
@@ -34,7 +34,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package
           path: dist/

{agent_webview-0.1.3 → agent_webview-0.1.4}/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-10-30
+
+### Security
+
+- 用兼容 Python 3.10 的 portalocker 替换存在已知漏洞的 filelock，保留控制器互斥锁；更新锁定的 certifi。
+
+### Added
+
+- 新增 `PUT /v1/sessions/{id}/proxy`，已打开的单窗口代理会话可更换上游，保留窗口、Cookie 和页面状态。
+- 单窗口代理支持独立的用户名密码字段和 HTTP Basic 认证。
+- 代理状态增加版本、可修改标识和认证标识；可用预期版本防止并发更新覆盖。
+- 增加真实窗口切换冒烟测试 `scripts/smoke_proxy_switch.py`。
+
+### Changed
+
+- 单窗口代理经本机转发入口连接上游；切换时断开旧连接，不自动刷新页面或重放请求，不回退直连。
+- 后台出口查询丢弃旧版本结果。全局代理仍不可修改，无代理会话保留原行为。
+
 ## [0.1.3] - 2026-09-25
 
 ### Changed

{agent_webview-0.1.3 → agent_webview-0.1.4}/CONTRIBUTING.md

@@ -8,10 +8,14 @@ uv run ruff check src tests
 uv run mypy
 uv run pytest
 uv run python scripts/smoke_service.py
+uv run python scripts/smoke_proxy_switch.py
 ```
 
 代码注释、日志、调试输出和用户可见错误使用简短中文。提交应保持通用，不加入
 特定网站选择器、账号流程或应用专属假设。
 
+代理切换冒烟测试使用两个本机模拟代理和虚构域名，不需要真实代理账密或付费资源。
+应分别在支持的原生 WebView 平台验证窗口状态保留；仅单元测试通过不能证明原生路由生效。
+
 提交前请确认没有加入 Cookie、Token、Storage State、HAR、请求日志、运行信息文件
 或真实服务域名。

{agent_webview-0.1.3 → agent_webview-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-webview
-Version: 0.1.3
+Version: 0.1.4
 Summary: A hidden pywebview browser controlled through an agent-friendly HTTP debugging API.
 Project-URL: Homepage, https://github.com/Yuv96/agent-webview
 Project-URL: Repository, https://github.com/Yuv96/agent-webview.git
@@ -28,9 +28,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Debuggers
 Requires-Python: >=3.10
 Requires-Dist: fastapi<1,>=0.115
-Requires-Dist: filelock<4,>=3.16
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: portalocker<4,>=3.2
 Requires-Dist: psutil<8,>=6.1
 Requires-Dist: pydantic<3,>=2.9
 Requires-Dist: pyobjc-framework-network>=10; sys_platform == 'darwin'
@@ -45,7 +45,7 @@ Requires-Dist: pip-audit<3,>=2.9; extra == 'dev'
 Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
 Requires-Dist: pytest<10,>=8.3; extra == 'dev'
 Requires-Dist: ruff<1,>=0.12; extra == 'dev'
-Requires-Dist: twine<7,>=6; extra == 'dev'
+Requires-Dist: twine<8,>=6; extra == 'dev'
 Provides-Extra: linux-gtk
 Requires-Dist: pywebview[gtk]<7,>=6.2.1; (sys_platform == 'linux') and extra == 'linux-gtk'
 Provides-Extra: linux-qt
@@ -219,6 +219,7 @@ with httpx.Client(
 | `GET` | `/v1/sessions` | 列出会话和进程信息 |
 | `GET` | `/v1/sessions/{id}` | 获取窗口、句柄和进程状态 |
 | `GET` | `/v1/sessions/{id}/proxy` | 查询代理配置、出口 IP 和归属地 |
+| `PUT` | `/v1/sessions/{id}/proxy` | 为已打开的单窗口代理会话切换上游代理 |
 | `DELETE` | `/v1/sessions/{id}` | 销毁会话 |
 | `POST` | `/v1/sessions/{id}/navigate` | 导航到新地址 |
 | `POST` | `/v1/sessions/{id}/javascript/evaluate` | 执行表达式并返回结果 |
@@ -260,8 +261,42 @@ session = client.post(
 ```
 
 全局代理优先于创建请求中的窗口代理，保证该控制器下的所有窗口使用同一代理。
-代理地址支持 `http://` 和 `https://`，暂不支持 SOCKS、用户名密码认证、路径或查询
-参数。Windows 需要 WebView2；macOS 的原生代理能力需要 macOS 14 或更高版本。
+代理地址支持 `http://` 和 `https://`，暂不支持 SOCKS、路径或查询参数。单窗口代理
+支持 HTTP Basic 账密认证：创建请求中同时传入 `proxy_username`、`proxy_password`，
+不要把账密拼进 `proxy` URL。Windows 需要 WebView2；macOS 需要 macOS 14 或更高版本。
+
+### 在已打开窗口中切换代理
+
+创建时配置了单窗口 `proxy` 的会话，可以保持窗口、Cookie、页面 JS 状态和输入内容，
+通过以下接口切换上游，不会自动刷新页面：
+
+```python
+current = client.get(f"/v1/sessions/{session_id}/proxy").raise_for_status().json()
+changed = client.put(
+    f"/v1/sessions/{session_id}/proxy",
+    json={
+        "proxy": "http://127.0.0.1:7891",
+        "proxy_username": proxy_username,
+        "proxy_password": proxy_password,
+        "expected_revision": current["revision"],
+    },
+).raise_for_status().json()
+```
+
+不需要认证时省略两个账密字段；省略会清除旧认证，不会继承旧密码。
+`expected_revision` 可选，指定时版本不匹配返回 `409`，避免并发切换相互覆盖。
+`proxy` 必填，不接受 `null`，不会隐式切换为直连。
+
+响应沿用 `ProxyStatus`，增加 `revision`（从 0 开始）、`mutable`、`authenticated`。
+成功响应表示上游已替换，`state=checking`，出口信息异步更新；它不保证上游已经连通。
+未配置代理、使用全局代理或已经关闭的窗口不支持此操作，返回 `409`。
+全局代理仍保持不可修改。状态、标题和代理事件不返回用户名或密码。
+
+单窗口会话通过仅监听 `127.0.0.1` 的固定入口连接上游。切换会断开所有旧 HTTP
+连接和 CONNECT 隧道，包括 WebSocket 或正在传输的请求；新请求使用新上游。
+组件不自动重试被中断的提交，也不在认证或连接失败时回退直连。
+调用方应在关键提交结束后切换；Cookie 保留不代表目标网站一定接受换 IP 后的登录态。
+这项能力不负责购买、提取或自动续期代理 IP。
 
 窗口会立即加载目标页面。出口 IP 与归属地由后台线程通过固定的第三方服务查询，
 不会等待查询结束才放行 WebView。查询成功后，可见窗口标题会变为类似：
@@ -292,7 +327,9 @@ if proxy["state"] == "active":
 - `active`：固定查询服务已通过该代理成功返回出口 IP 和归属地。
 - `unavailable`：本次查询没有结果；页面继续正常工作，该状态本身不能断定代理失败。
 
-查询完成时也会产生 `proxy` 事件，可通过现有事件长轮询接口监听。查询服务地址固定
+切换应用时产生包含 `revision` 和无账密 `server` 的 `changed` 代理事件；
+旧版本的后台查询结果不会覆盖新版本状态。查询完成时也会产生 `proxy` 事件，
+可通过现有事件长轮询接口监听。查询服务地址固定
 在实现内部，不接受 CLI 或 HTTP API 覆盖。
 
 ## 🔎 页面观测
@@ -364,8 +401,8 @@ Cookie 快照和运行信息文件都应按敏感数据处理，不应提交到
 - 控制器重启不会恢复仍在运行的 worker 会话。
 - DOM `click()` 不等同于操作系统级鼠标事件。
 - 当前不提供截图接口，因为 pywebview 没有统一的跨后端页面截图 API。
-- 该项目可以把 WebView 流量转交给已有代理，但本身不是代理服务器，也不是完整的
-  浏览器自动化框架。
+- 单窗口代理包含本机转发入口，仅用于当前会话；本项目不提供公共代理服务或代理
+  IP 资源，也不是完整的浏览器自动化框架。
 
 公共兼容范围和版本规则见
 [API 稳定性说明](https://github.com/Yuv96/agent-webview/blob/main/docs/api-stability.md)。

{agent_webview-0.1.3 → agent_webview-0.1.4}/README.md

@@ -165,6 +165,7 @@ with httpx.Client(
 | `GET` | `/v1/sessions` | 列出会话和进程信息 |
 | `GET` | `/v1/sessions/{id}` | 获取窗口、句柄和进程状态 |
 | `GET` | `/v1/sessions/{id}/proxy` | 查询代理配置、出口 IP 和归属地 |
+| `PUT` | `/v1/sessions/{id}/proxy` | 为已打开的单窗口代理会话切换上游代理 |
 | `DELETE` | `/v1/sessions/{id}` | 销毁会话 |
 | `POST` | `/v1/sessions/{id}/navigate` | 导航到新地址 |
 | `POST` | `/v1/sessions/{id}/javascript/evaluate` | 执行表达式并返回结果 |
@@ -206,8 +207,42 @@ session = client.post(
 ```
 
 全局代理优先于创建请求中的窗口代理，保证该控制器下的所有窗口使用同一代理。
-代理地址支持 `http://` 和 `https://`，暂不支持 SOCKS、用户名密码认证、路径或查询
-参数。Windows 需要 WebView2；macOS 的原生代理能力需要 macOS 14 或更高版本。
+代理地址支持 `http://` 和 `https://`，暂不支持 SOCKS、路径或查询参数。单窗口代理
+支持 HTTP Basic 账密认证：创建请求中同时传入 `proxy_username`、`proxy_password`，
+不要把账密拼进 `proxy` URL。Windows 需要 WebView2；macOS 需要 macOS 14 或更高版本。
+
+### 在已打开窗口中切换代理
+
+创建时配置了单窗口 `proxy` 的会话，可以保持窗口、Cookie、页面 JS 状态和输入内容，
+通过以下接口切换上游，不会自动刷新页面：
+
+```python
+current = client.get(f"/v1/sessions/{session_id}/proxy").raise_for_status().json()
+changed = client.put(
+    f"/v1/sessions/{session_id}/proxy",
+    json={
+        "proxy": "http://127.0.0.1:7891",
+        "proxy_username": proxy_username,
+        "proxy_password": proxy_password,
+        "expected_revision": current["revision"],
+    },
+).raise_for_status().json()
+```
+
+不需要认证时省略两个账密字段；省略会清除旧认证，不会继承旧密码。
+`expected_revision` 可选，指定时版本不匹配返回 `409`，避免并发切换相互覆盖。
+`proxy` 必填，不接受 `null`，不会隐式切换为直连。
+
+响应沿用 `ProxyStatus`，增加 `revision`（从 0 开始）、`mutable`、`authenticated`。
+成功响应表示上游已替换，`state=checking`，出口信息异步更新；它不保证上游已经连通。
+未配置代理、使用全局代理或已经关闭的窗口不支持此操作，返回 `409`。
+全局代理仍保持不可修改。状态、标题和代理事件不返回用户名或密码。
+
+单窗口会话通过仅监听 `127.0.0.1` 的固定入口连接上游。切换会断开所有旧 HTTP
+连接和 CONNECT 隧道，包括 WebSocket 或正在传输的请求；新请求使用新上游。
+组件不自动重试被中断的提交，也不在认证或连接失败时回退直连。
+调用方应在关键提交结束后切换；Cookie 保留不代表目标网站一定接受换 IP 后的登录态。
+这项能力不负责购买、提取或自动续期代理 IP。
 
 窗口会立即加载目标页面。出口 IP 与归属地由后台线程通过固定的第三方服务查询，
 不会等待查询结束才放行 WebView。查询成功后，可见窗口标题会变为类似：
@@ -238,7 +273,9 @@ if proxy["state"] == "active":
 - `active`：固定查询服务已通过该代理成功返回出口 IP 和归属地。
 - `unavailable`：本次查询没有结果；页面继续正常工作，该状态本身不能断定代理失败。
 
-查询完成时也会产生 `proxy` 事件，可通过现有事件长轮询接口监听。查询服务地址固定
+切换应用时产生包含 `revision` 和无账密 `server` 的 `changed` 代理事件；
+旧版本的后台查询结果不会覆盖新版本状态。查询完成时也会产生 `proxy` 事件，
+可通过现有事件长轮询接口监听。查询服务地址固定
 在实现内部，不接受 CLI 或 HTTP API 覆盖。
 
 ## 🔎 页面观测
@@ -310,8 +347,8 @@ Cookie 快照和运行信息文件都应按敏感数据处理，不应提交到
 - 控制器重启不会恢复仍在运行的 worker 会话。
 - DOM `click()` 不等同于操作系统级鼠标事件。
 - 当前不提供截图接口，因为 pywebview 没有统一的跨后端页面截图 API。
-- 该项目可以把 WebView 流量转交给已有代理，但本身不是代理服务器，也不是完整的
-  浏览器自动化框架。
+- 单窗口代理包含本机转发入口，仅用于当前会话；本项目不提供公共代理服务或代理
+  IP 资源，也不是完整的浏览器自动化框架。
 
 公共兼容范围和版本规则见
 [API 稳定性说明](https://github.com/Yuv96/agent-webview/blob/main/docs/api-stability.md)。

{agent_webview-0.1.3 → agent_webview-0.1.4}/README_EN.md

@@ -171,6 +171,7 @@ Once the service is running, open the `docs_url` from the runtime file or visit
 | `GET` | `/v1/sessions` | List sessions and process information |
 | `GET` | `/v1/sessions/{id}` | Read window, handle, and process state |
 | `GET` | `/v1/sessions/{id}/proxy` | Read proxy configuration, exit IP, and location |
+| `PUT` | `/v1/sessions/{id}/proxy` | Change the upstream proxy for an open per-window proxy session |
 | `DELETE` | `/v1/sessions/{id}` | Destroy a session |
 | `POST` | `/v1/sessions/{id}/navigate` | Navigate to another URL |
 | `POST` | `/v1/sessions/{id}/javascript/evaluate` | Evaluate an expression and return its value |
@@ -216,9 +217,47 @@ session = client.post(
 
 The global proxy takes precedence over a per-window value so that every window
 under that controller uses the same route. Proxy URLs may use `http://` or
-`https://`. SOCKS, username/password authentication, paths, and query strings
-are not currently supported. Windows requires WebView2, and native proxy
-configuration on macOS requires macOS 14 or later.
+`https://`. SOCKS, paths, and query strings are not supported. Per-window proxies
+support HTTP Basic credentials: supply both `proxy_username` and `proxy_password`
+on creation, rather than embedding credentials in the URL. Windows requires
+WebView2; macOS requires macOS 14 or later.
+
+### Change an open window's proxy
+
+Sessions created with a per-window `proxy` can switch upstreams while preserving
+the window, cookies, JavaScript state, and unfinished inputs. No page reload occurs:
+
+```python
+current = client.get(f"/v1/sessions/{session_id}/proxy").raise_for_status().json()
+changed = client.put(
+    f"/v1/sessions/{session_id}/proxy",
+    json={
+        "proxy": "http://127.0.0.1:7891",
+        "proxy_username": proxy_username,
+        "proxy_password": proxy_password,
+        "expected_revision": current["revision"],
+    },
+).raise_for_status().json()
+```
+
+Omit both credential fields for an unauthenticated upstream; omission clears
+previous credentials. Optional `expected_revision` rejects concurrent changes
+with `409` when the revision differs. `proxy` is required and cannot be `null`;
+the operation never implicitly enables a direct connection.
+
+`ProxyStatus` adds `revision` (starting at 0), `mutable`, and `authenticated`.
+A successful update means the upstream was replaced; `state=checking` while
+exit lookup runs asynchronously. It does not guarantee upstream connectivity.
+Unconfigured, globally proxied, or closed windows return `409`. Global proxies
+remain immutable. Status, titles, and proxy events never return credentials.
+
+Each per-window proxy uses a fixed loopback relay bound to `127.0.0.1`. Switching
+closes every old HTTP connection and CONNECT tunnel, including WebSockets and
+in-flight requests. New requests use the new upstream. Interrupted submissions
+are not automatically retried, and authentication/connection failure never falls
+back to direct networking. Switch after critical submissions finish. Preserved
+cookies do not guarantee that a website accepts a changed login IP. The component
+does not purchase, extract, or automatically renew proxy IPs.
 
 The target page starts loading immediately. A background thread queries a
 fixed third-party service through the proxy for its exit IP and location; page
@@ -255,7 +294,9 @@ waits only on that status request, never on the WebView. States mean:
 - `unavailable`: this lookup produced no result. The page continues normally,
   and this state alone does not prove the proxy failed.
 
-Completion also emits a `proxy` event through the existing event stream. The
+Applying a switch emits a `changed` proxy event with `revision` and a credential-free
+`server`. Stale lookups cannot overwrite the current revision. Completion also
+emits a `proxy` event through the existing event stream. The
 lookup service URL is fixed internally and cannot be overridden through the
 CLI or HTTP API.
 
@@ -342,8 +383,9 @@ browser cookies. Keep it within these boundaries:
 - DOM `click()` is not equivalent to an operating-system mouse event.
 - Screenshots are not currently exposed because pywebview has no uniform
   cross-backend page screenshot API.
-- This project can route WebView traffic to an existing proxy, but it is not a
-  proxy server or a complete browser automation framework.
+- Per-window proxies include a local relay for that session only. This project
+  does not provide a public proxy service, proxy IP inventory, or a complete
+  browser automation framework.
 
 See the
 [API stability policy](https://github.com/Yuv96/agent-webview/blob/main/docs/api-stability.md)

{agent_webview-0.1.3 → agent_webview-0.1.4}/SECURITY.md

@@ -19,3 +19,8 @@
 
 代理会话会把出口 IP 发送给内置的第三方归属地查询服务。全局代理地址会记录在权限
 受限的运行信息文件中；不要共享该文件。
+
+单窗口代理账密通过受令牌保护的 API 传入，创建时保存在权限受限的 worker 配置中；
+后续切换账密只保留在进程内存，不进入状态响应或代理事件。窗口使用随机本机端口
+转发到上游，端口不面向外部网络；本机其他进程仍属于可信边界。HTTP Basic 仅编码
+认证数据；需要保护到上游的传输时应使用 `https://` 代理，组件会验证其 TLS 证书。

{agent_webview-0.1.3 → agent_webview-0.1.4}/pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 ]
 dependencies = [
     "fastapi>=0.115,<1",
-    "filelock>=3.16,<4",
+    "portalocker>=3.2,<4",
     "httpx>=0.28,<1",
     "platformdirs>=4.3,<5",
     "psutil>=6.1,<8",
@@ -58,7 +58,7 @@ dev = [
     "pytest-cov>=6,<8",
     "pytest>=8.3,<10",
     "ruff>=0.12,<1",
-    "twine>=6,<7",
+    "twine>=6,<8",
 ]
 linux-gtk = [
     "pywebview[gtk]>=6.2.1,<7; sys_platform == 'linux'",

agent_webview-0.1.4/scripts/smoke_proxy_switch.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import base64
+import json
+import os
+import socketserver
+import subprocess
+import sys
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from threading import Thread
+
+import httpx
+from smoke_service import free_port, stop_process, wait_until
+
+from agent_webview.proxy_relay import _read_headers
+
+
+@contextmanager
+def test_proxy(label: str):
+    expected = b"Basic " + base64.b64encode(f"test:{label}".encode())
+    requests = []
+
+    class Handler(socketserver.BaseRequestHandler):
+        def handle(self):
+            self.request.settimeout(5)
+            try:
+                header, _ = _read_headers(self.request)
+                if b"Proxy-Authorization: " + expected not in header:
+                    self.request.sendall(
+                        b"HTTP/1.1 407 Proxy Authentication Required\r\nContent-Length: 0\r\n\r\n"
+                    )
+                    return
+                method, destination, _ = header.split(b"\r\n")[0].split(b" ")
+                if method == b"CONNECT":
+                    if destination != b"proxy-switch.invalid:80":
+                        self.request.sendall(
+                            b"HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n\r\n"
+                        )
+                        return
+                    self.request.sendall(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+                    header, _ = _read_headers(self.request)
+                requests.append(header)
+                path = header.split(b"\r\n")[0].split(b" ")[1]
+                if b"/identity" in path:
+                    body = label.encode()
+                    mime = b"text/plain"
+                else:
+                    body = b'<html><head><title>Proxy test</title></head><body><input id="draft"><div id="marker">original</div></body></html>'
+                    mime = b"text/html"
+                self.request.sendall(
+                    b"HTTP/1.1 200 OK\r\nConnection: close\r\nCache-Control: no-store\r\nContent-Type: "
+                    + mime
+                    + b"\r\nContent-Length: "
+                    + str(len(body)).encode()
+                    + b"\r\n\r\n"
+                    + body
+                )
+            except (OSError, ValueError):
+                return
+
+    server = socketserver.ThreadingTCPServer(("127.0.0.1", 0), Handler)
+    server.daemon_threads = True
+    thread = Thread(
+        target=server.serve_forever, kwargs={"poll_interval": 0.05}, daemon=True
+    )
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_address[1]}", requests
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(2)
+
+
+def main():
+    with (
+        tempfile.TemporaryDirectory(prefix="webview-proxy-smoke-") as name,
+        test_proxy("first") as (first, first_requests),
+        test_proxy("second") as (second, second_requests),
+    ):
+        root = Path(name)
+        runtime_file = root / "controller.json"
+        log_file = root / "controller.log"
+        port = free_port()
+        with log_file.open("w") as output:
+            process = subprocess.Popen(
+                [
+                    sys.executable,
+                    "-m",
+                    "agent_webview",
+                    "--port",
+                    str(port),
+                    "--data-dir",
+                    str(root / "data"),
+                    "--runtime-dir",
+                    str(root / "runtime"),
+                    "--runtime-file",
+                    str(runtime_file),
+                ],
+                stdout=output,
+                stderr=subprocess.STDOUT,
+                creationflags=subprocess.CREATE_NEW_PROCESS_GROUP
+                if os.name == "nt"
+                else 0,
+            )
+        try:
+            wait_until(runtime_file.exists, timeout=20, message="控制器启动超时")
+            token = json.loads(runtime_file.read_text())["token"]
+            with httpx.Client(
+                base_url=f"http://127.0.0.1:{port}",
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=55,
+                trust_env=False,
+            ) as client:
+                response = client.post(
+                    "/v1/sessions",
+                    json={
+                        "url": "http://proxy-switch.invalid/",
+                        "visible": False,
+                        "proxy": first,
+                        "proxy_username": "test",
+                        "proxy_password": "first",  # pragma: allowlist secret
+                    },
+                )
+                response.raise_for_status()
+                initial = response.json()
+                path = f"/v1/sessions/{initial['session_id']}"
+
+                def ready():
+                    result = client.get(path)
+                    result.raise_for_status()
+                    window = result.json().get("window") or {}
+                    return window.get("ready")
+
+                wait_until(ready, timeout=40, message="窗口页面加载超时")
+
+                def evaluate(code):
+                    result = client.post(
+                        path + "/javascript/evaluate",
+                        json={"code": code, "timeout": 10},
+                    )
+                    result.raise_for_status()
+                    return result.json()["value"]
+
+                assert (
+                    evaluate("fetch('/identity', {cache:'no-store'}).then(r=>r.text())")
+                    == "first"
+                )
+                evaluate(
+                    "(() => { document.cookie='smoke=preserved; path=/'; window.marker=42; document.querySelector('#draft').value='unfinished'; return true; })()"
+                )
+                before = client.get(path).json()
+                changed = client.put(
+                    path + "/proxy",
+                    json={
+                        "proxy": second,
+                        "proxy_username": "test",
+                        "proxy_password": "second",  # pragma: allowlist secret
+                        "expected_revision": 0,
+                    },
+                )
+                changed.raise_for_status()
+                assert changed.json()["revision"] == 1
+                assert changed.json()["mutable"] is True
+                assert (
+                    evaluate("fetch('/identity', {cache:'no-store'}).then(r=>r.text())")
+                    == "second"
+                )
+                assert evaluate(
+                    "({cookie:document.cookie, marker:window.marker, draft:document.querySelector('#draft').value})"
+                ) == {
+                    "cookie": "smoke=preserved",
+                    "marker": 42,
+                    "draft": "unfinished",
+                }
+                after = client.get(path).json()
+                assert before["pid"] == after["pid"]
+                assert before["window_id"] == after["window_id"]
+                assert (
+                    before["window"]["native_window_id"]
+                    == after["window"]["native_window_id"]
+                )
+                assert first_requests and second_requests
+                response = client.delete(path)
+                response.raise_for_status()
+        except Exception:
+            print(log_file.read_text()[-4000:], file=sys.stderr)
+            raise
+        finally:
+            stop_process(process)
+    print(
+        "真实窗口代理切换通过：账密验证、出口路径切换、Cookie、JS 状态和未提交输入均保留"
+    )
+
+
+if __name__ == "__main__":
+    main()

{agent_webview-0.1.3 → agent_webview-0.1.4}/src/agent_webview/__init__.py

@@ -1,3 +1,3 @@
 """Agent 控制的 pywebview 调试服务。"""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{agent_webview-0.1.3 → agent_webview-0.1.4}/src/agent_webview/cli.py

@@ -12,8 +12,8 @@ from typing import Any
 
 import structlog
 import uvicorn
-from filelock import FileLock, Timeout
 from platformdirs import PlatformDirs
+from portalocker import Lock, LockException
 
 from agent_webview.controller_api import create_controller_app
 from agent_webview.cookies import SnapshotStore
@@ -73,13 +73,14 @@ def _base_url(host: str, port: int) -> str:
 @contextmanager
 def _claim_runtime_file(path: Path) -> Iterator[None]:
     ensure_private_parent(path.parent)
-    lock = FileLock(f"{path}.lock")
+    lock_path = Path(f"{path}.lock")
+    lock = Lock(lock_path, mode="a", timeout=0)
     try:
         lock.acquire(timeout=0)
-    except Timeout as error:
+    except LockException as error:
         raise RuntimeFileInUseError("运行信息文件已被其他服务占用") from error
-    restrict_file_permissions(Path(lock.lock_file))
     try:
+        restrict_file_permissions(lock_path)
         yield
     finally:
         lock.release()

{agent_webview-0.1.3 → agent_webview-0.1.4}/src/agent_webview/controller_api.py

@@ -27,6 +27,7 @@ from agent_webview.models import (
     JavaScriptRequest,
     NavigateRequest,
     ProxyStatus,
+    ProxyUpdateRequest,
     SessionCreateRequest,
     SessionDescription,
     SessionDestroyResponse,
@@ -137,6 +138,10 @@ def create_controller_app(manager: SessionManager, token: str) -> FastAPI:
     def destroy_session(session_id: str) -> dict[str, Any]:
         return manager.destroy(session_id)
 
+    @router.put("/sessions/{session_id}/proxy", response_model=ProxyStatus)
+    def update_proxy(session_id: str, request: ProxyUpdateRequest) -> dict[str, Any]:
+        return call(session_id, "PUT", "/v1/proxy", body=request.model_dump())
+
     @router.post("/sessions/{session_id}/window/show", response_model=WindowStatus)
     def show_window(session_id: str) -> dict[str, Any]:
         return call(session_id, "POST", "/v1/window/show")