dsh-browser-playwright-codex 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.8.3 — 2026-11-12
+
+一句话摘要：**插件可以走代理了**——以前它启动的浏览器只能直连，凡是要代理的站点（维基、GitHub 网页、大量国外站）一律打不开。现在多一个 `launch.proxy` 配置项和设置页里的「代理」输入框；**默认留空 = 直连，行为与之前完全一样**。实测同一台机器：维基直连 31 秒超时，走代理 1 秒返回。
+
+### Added
+
+- **`launch.proxy`**：填 `http://host:port`、`https://host:port` 或 `socks5://host:port`，只写 `host:port` 会按 Playwright 的规则补成 `http://`。代理交给**浏览器启动参数**（`launchOptions.proxy`），整个浏览器走代理——不是在某个请求上加头。
+- **设置页「代理」输入框**：放在「已登录的站点」正前方（这张卡的最后一块），不再散落在中间。占位提示 `http://host:port`，示例用保留域名 `http://proxy.example:8080`，**不写任何本机真实地址**；默认值为空。
+- **强制绕过本机地址**：配置代理时自动带上 `bypass: localhost,127.0.0.1`。不加这个，插件自己的本地页面（verify、本地普查、任何本地服务）会被塞进代理而连不上。
+- **地址写错当场报错，绝不静默回退直连**：缺 scheme 时按 `host:port` 补 http；端口必须 1–65535；带路径/查询/片段、未知 scheme 都拒绝，并给出「写成 `scheme://host:port`」这句人话。静默回退会把"代理没生效"伪装成"网站打不开"，比报错更难查。
+- **不支持需要账号密码的代理**：带账号密码的地址在校验阶段就拒。两个理由——密码会明文落在用户的 `cordis.patch.yml` 里；而且 Chromium/Playwright 本身不支持 SOCKS5 认证（`Browser does not support socks5 proxy authentication`）。宁可少一个能力，不埋一个明文密码。
+
+### Changed
+
+- **保存代理只改一行**：`playwright.launch` 下的 `proxy:` 这一行，与三个能力闸门同一个模式（已知键、按行改）。其它键（`profileDir` / `channel` / `viewport` / `maxSessions` / `toolPrefix` / `maxWaitMs` 等）**逐字节不动**；清空 = 删掉那一行（留空=直连必须是干净的，不能留空值）；结构认不出就**拒绝写入**，绝不整块重渲染。
+- **生效时机**：代理是浏览器启动参数，插件在加载时读配置，所以**改完要重启 DSH 才生效**；设置页保存成功后会直接提示这一点。
+
+### Tests
+
+- 新增 `tests/proxy.test.ts`（9 条）：空配置不带 proxy；填了带 server + bypass；`host:port` 短写补 http；端口缺失/非数字/0/65536；认证代理拒绝；未知 scheme 与带路径拒绝；启动路径静态守卫（防止只加配置没接上）；**代理不影响 `allowedDomains` 判定**。
+- `tests/settings-card.test.ts` 新增 4 条：保存后 `launch.proxy` 出现且其它键完全不变（含 `profileDir`）；清空后那一行被删；非法地址 400 且文件不变；重复保存同一值幂等无重复键。
+- 全套现在 **390 条 / 387 过 / 0 失败 / cancelled 0 / skipped 3 / todo 0**。
+
+### Verified
+
+- **走代理真跑 live 三条：3/3 通过**。`example.com` 两条照常；`wikipedia REST summary` 在直连时 31 秒 `NAVIGATION_TIMEOUT` 失败，配代理后 **1.0 秒通过**——这就是这次改动的直接证据（此前 0.8.2 发布时这条是 2/3）。
+- verify 60 项全过、preflight 0 硬错误、打包 101 个文件（新增 `lib/proxy.js` / `lib/proxy.d.ts`）。
+- 已知限制：设置页里没有"测试代理连通性"的按钮；填错端口但格式合法时，要到实际启动浏览器才会发现连不上。
+
 ## 0.8.2 — 2026-11-12
 
 一句话摘要：**发版门禁不再会"假绿"，快照引擎第一次在真实网站上被量过**——preflight 过去只读 `ℹ fail`（而且"fail 0"是写死的字符串），被取消的用例看不出、也不报；设置页这个全仓最大的零测试模块补上了走真实 HTTP 的测试，顺手修掉"已有未标记装载行时写出第二行"的坏文件路径；智能模式（aria）的解析器与可交互集对齐后，130 个任务页的降级从 18 页降到 3 页。

package/lib/browser-lifecycle.js

@@ -7,6 +7,7 @@ import { chromium } from 'playwright-core';
 import path from 'node:path';
 import fs from 'node:fs';
 import { AUTO_CHANNELS, HUMANIZED_LAUNCH } from "./config.js";
+import { proxyLaunchOption } from "./proxy.js";
 import { SNAPSHOT_SCRIPT } from "./injected.js";
 import { BrowserError, launchFailed } from "./errors.js";
 import { forgetOnBrowserClose, showWelcome } from "./swarm-intro.js";
@@ -72,6 +73,9 @@ async function launchContext(provider) {
         // Headless mode keeps the fixed viewport (no window to track).
         ...(headless ? { viewport: provider.config.launch.viewport } : { viewport: null }),
         ignoreHTTPSErrors: provider.config.launch.ignoreHTTPSErrors,
+        // Proxy at the browser level (launchOptions.proxy): request headers cannot route a whole
+        // browser. Empty proxy yields {} so the default stays a direct connection.
+        ...proxyLaunchOption(provider.config.launch.proxy),
         ...HUMANIZED_LAUNCH,
         args: [
             '--no-first-run',
@@ -226,7 +230,12 @@ async function launchBrowser(provider) {
     const attempts = [];
     if (executablePath !== undefined) {
         try {
-            provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            provider.browser = await chromium.launch({
+                executablePath,
+                headless,
+                ...HUMANIZED_LAUNCH,
+                ...proxyLaunchOption(provider.config.launch.proxy),
+            });
             provider.launchedHeadless = headless;
             return provider.browser;
         }
@@ -239,7 +248,12 @@ async function launchBrowser(provider) {
         const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
         for (const candidate of channels) {
             try {
-                provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                provider.browser = await chromium.launch({
+                    channel: candidate,
+                    headless,
+                    ...HUMANIZED_LAUNCH,
+                    ...proxyLaunchOption(provider.config.launch.proxy),
+                });
                 provider.launchedHeadless = headless;
                 return provider.browser;
             }

package/lib/client.js

@@ -403,6 +403,13 @@ window.__ModuleLoader__.load({
       const [logins, setLogins] = useState(null)
       const [headless, setHeadless] = useState(null)
       const [headlessUserChosen, setHeadlessUserChosen] = useState(false)
+      // 代理（浏览器启动参数）：'' = 直连。
+      const [proxy, setProxy] = useState('')
+      const [proxyDraft, setProxyDraft] = useState('')
+      const [proxyBusy, setProxyBusy] = useState(false)
+      const [proxyMsg, setProxyMsg] = useState(null)
+      // 输入框有焦点时，5 秒一次的轮询不许覆盖用户正在打的字。
+      const proxyFocusedRef = useRef(false)
       const [showAll, setShowAll] = useState(false)
       const [openGroups, setOpenGroups] = useState([])
       const [hiddenDomains, setHiddenDomains] = useState(readHiddenDomains())
@@ -436,6 +443,10 @@ window.__ModuleLoader__.load({
           if (typeof s.swarmPersistPlayed === 'boolean') setSwarmPersist(s.swarmPersistPlayed)
           if (typeof s.headless === 'boolean') setHeadless(s.headless)
           setHeadlessUserChosen(s.headlessUserChosen === true)
+          if (typeof s.proxy === 'string') {
+            setProxy(s.proxy)
+            if (!proxyFocusedRef.current) setProxyDraft(s.proxy)
+          }
           setGates({
             allowEvaluate: typeof s.allowEvaluate === 'boolean' ? s.allowEvaluate : null,
             allowCdp: typeof s.allowCdp === 'boolean' ? s.allowCdp : null,
@@ -573,6 +584,30 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 保存代理：只改 cordis.patch.yml 里 launch.proxy 那一行；空 = 删掉（直连）。
+      const saveProxy = async () => {
+        if (proxyBusy) return
+        setProxyBusy(true)
+        setProxyMsg(null)
+        try {
+          const r = await api('/proxy', 'POST', { proxy: proxyDraft })
+          if (r && r.error) {
+            setProxyMsg({ kind: 'error', text: r.error.message || r.error.code || '保存失败' })
+            return
+          }
+          const saved = typeof r.proxy === 'string' ? r.proxy : ''
+          setProxy(saved)
+          setProxyDraft(saved)
+          setProxyMsg({
+            kind: 'ok',
+            text: (saved === '' ? '已保存：留空 = 直连。' : '已保存：' + saved + '。') + '重启 DSH 后生效。',
+          })
+        } catch (error) {
+          setProxyMsg({ kind: 'error', text: '保存失败：' + (error?.message ?? String(error)) })
+        } finally {
+          setProxyBusy(false)
+        }
+      }
       const chooseWindow = async (nextHeadless) => {
         if (headless === null || busy || nextHeadless === headless) return
         setBusy(true)
@@ -1153,6 +1188,68 @@ window.__ModuleLoader__.load({
             )
           : null,
 
+        // ---- 代理（浏览器启动参数）----
+        // 放在「已登录的站点」正前方（用户要求的最后一块），样式与其它分组一致：
+        // 标题行 + 一整块内容。留空 = 直连；改了要重启 DSH 才生效（保存成功时会说明）。
+        h('div', { key: 'proxyGroup', style: S.group }, ['代理']),
+        h('div', { key: 'proxyBody', style: { ...S.list, marginTop: 8 } }, [
+          h('div', { key: 'row', style: { display: 'flex', alignItems: 'center', gap: 8 } }, [
+            h('input', {
+              key: 'input',
+              type: 'text',
+              value: proxyDraft,
+              placeholder: 'http://host:port',
+              disabled: proxyBusy,
+              spellCheck: false,
+              onFocus: () => {
+                proxyFocusedRef.current = true
+              },
+              onBlur: () => {
+                proxyFocusedRef.current = false
+              },
+              onChange: (e) => {
+                setProxyDraft(e.target.value)
+                setProxyMsg(null)
+              },
+              style: {
+                flex: '1 1 auto',
+                minWidth: 160,
+                height: 28,
+                padding: '0 10px',
+                border: '0.5px solid ' + T.borderL3,
+                borderRadius: 14,
+                background: 'transparent',
+                font: 'inherit',
+                fontSize: 12,
+                lineHeight: '18px',
+                color: T.primary,
+              },
+            }),
+            h(
+              Btn,
+              {
+                key: 'save',
+                disabled: proxyBusy || proxyDraft === proxy,
+              },
+              proxyBusy ? '保存中…' : '保存',
+            ),
+          ]),
+          h(
+            'p',
+            { key: 'hint', style: S.note },
+            '留空 = 直连。要填的话写成 http://主机:端口 或 socks5://主机:端口，例如 http://proxy.example:8080；本机页面不走代理。不支持需要账号密码的代理。',
+          ),
+          proxyMsg
+            ? h(
+                'p',
+                {
+                  key: 'msg',
+                  style: { ...S.note, color: proxyMsg.kind === 'error' ? T.error : T.success },
+                },
+                proxyMsg.text,
+              )
+            : null,
+        ]),
         // ---- 已登录站点（默认收起） ----
         h(
           'div',

package/lib/config.d.ts

@@ -25,6 +25,11 @@ export interface PlaywrightConfig {
         navigationTimeoutMs: number;
         /** Ignore HTTPS certificate errors. */
         ignoreHTTPSErrors: boolean;
+        /**
+         * Proxy for the whole browser, e.g. `http://proxy.example:8080` (http / https / socks5).
+         * Empty = connect directly — the default, and the previous behaviour.
+         */
+        proxy?: string;
     };
     /** Host suffixes the browser may visit. Empty = any http(s) host. */
     allowedDomains?: string[];

package/lib/config.js

@@ -27,6 +27,11 @@ export const Config = z.object({
         // one second; the default stays 30s.
         navigationTimeoutMs: z.number().min(1000).default(30000),
         ignoreHTTPSErrors: z.boolean().default(false),
+        // Proxy for the whole browser (launchOptions.proxy), e.g. http://proxy.example:8080.
+        // Empty = direct, which is the default and keeps every existing deployment unchanged.
+        // Validation lives in src/proxy.ts so a bad address fails loudly instead of silently
+        // connecting directly (which would look like "the site is down").
+        proxy: z.string().default(''),
     }),
     allowedDomains: z.array(z.string()),
     idleTimeoutMs: z.number().default(600000),

package/lib/gates-patch.d.ts

@@ -86,4 +86,33 @@ export declare function writeGates(allowEvaluate: boolean, allowCdp: boolean, di
     allowCdp: boolean;
     diagnostics: boolean;
 }>;
+/**
+ * 改写块里的 proxy 行：有就改、没有就插、空字符串就删。其它行逐字节保留。
+ *
+ * @param body - 托管块全文（含标记）
+ * @param proxy - 已经过 normalizeProxy 校验的地址；'' 表示删掉这一行
+ * @returns 改好的块
+ */
+export declare function patchBlockProxy(body: string, proxy: string): string;
+/** 读托管块里的 proxy 值；没有就是 ''（= 直连）。 */
+export declare function parseBrowserBlockProxy(text: string): string;
+/**
+ * 把 proxy 合并进文件内容：没有托管块就先按模板建一个，再改这一行。
+ *
+ * @param original - 原文件内容
+ * @param proxy - 已校验的地址；'' = 删掉
+ * @returns 新文件内容
+ */
+export declare function mergeBrowserBlockProxy(original: string, proxy: string): string;
+/**
+ * 写 proxy：备份 → 原子替换 → 读回校验；校验失败恢复原文件。
+ *
+ * @param proxy - 已校验的地址；'' 表示删掉这一行（= 直连）
+ * @param env - 环境（测试用 DSH_HOME 覆盖）
+ * @returns 写到的文件与现在的值
+ */
+export declare function writeProxy(proxy: string, env?: NodeJS.ProcessEnv): Promise<{
+    patch: string;
+    proxy: string;
+}>;
 export {};

package/lib/gates-patch.js

@@ -323,3 +323,152 @@ export async function writeGates(allowEvaluate, allowCdp, diagnostics, env = pro
     }
     return { patch: file, allowEvaluate, allowCdp, diagnostics };
 }
+/** 在块的文本里找 `launch:` 与它的 `proxy:` 子行。认不出结构就抛错（拒绝写入）。 */
+function findLaunchSection(lines) {
+    let launchAt = -1;
+    let launchIndent = '';
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = /^(\s*)launch\s*:\s*(#.*)?$/.exec(lines[i] ?? '');
+        if (m !== null) {
+            launchAt = i;
+            launchIndent = m[1] ?? '';
+            break;
+        }
+    }
+    if (launchAt === -1) {
+        throw new Error('the managed block has no `playwright.launch:` section, so launch.proxy cannot be edited safely; ' +
+            'nothing was written. Fix the block by hand (or remove it and save a gate once to rebuild it).');
+    }
+    const baseIndent = launchIndent.length;
+    let childIndent = '';
+    let proxy;
+    for (let i = launchAt + 1; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const indent = (/^\s*/.exec(line)?.[0] ?? '').length;
+        if (indent <= baseIndent)
+            break; // 出了 launch 这一节
+        if (trimmed.startsWith('#'))
+            continue;
+        if (childIndent === '')
+            childIndent = ' '.repeat(indent);
+        const p = /^(\s*)proxy\s*:/.exec(line);
+        if (p !== null)
+            proxy = { at: i, indent: p[1] ?? '' };
+    }
+    return {
+        at: launchAt,
+        indent: baseIndent,
+        childIndent: childIndent === '' ? ' '.repeat(baseIndent + 2) : childIndent,
+        ...(proxy === undefined ? {} : { proxy }),
+    };
+}
+/**
+ * 改写块里的 proxy 行：有就改、没有就插、空字符串就删。其它行逐字节保留。
+ *
+ * @param body - 托管块全文（含标记）
+ * @param proxy - 已经过 normalizeProxy 校验的地址；'' 表示删掉这一行
+ * @returns 改好的块
+ */
+export function patchBlockProxy(body, proxy) {
+    const nl = body.includes('\r\n') ? '\r\n' : '\n';
+    const lines = body.split(/\r?\n/);
+    const section = findLaunchSection(lines);
+    const value = proxy.trim();
+    const rendered = section.childIndent + 'proxy: ' + JSON.stringify(value);
+    if (section.proxy !== undefined) {
+        if (value === '')
+            lines.splice(section.proxy.at, 1);
+        else
+            lines[section.proxy.at] = rendered;
+        return lines.join(nl);
+    }
+    if (value === '')
+        return lines.join(nl); // 本来就没有，删空是幂等的
+    lines.splice(section.at + 1, 0, rendered);
+    return lines.join(nl);
+}
+/** 读托管块里的 proxy 值；没有就是 ''（= 直连）。 */
+export function parseBrowserBlockProxy(text) {
+    const found = findBlock(text);
+    if (found === undefined)
+        return '';
+    const body = text.slice(found.start, found.after);
+    const lines = body.split(/\r?\n/);
+    let section;
+    try {
+        section = findLaunchSection(lines);
+    }
+    catch {
+        return '';
+    }
+    if (section?.proxy === undefined)
+        return '';
+    const raw = (lines[section.proxy.at] ?? '').replace(/^\s*proxy\s*:\s*/, '');
+    const withoutComment = raw.replace(/\s+#.*$/, '').trim();
+    if (withoutComment === '')
+        return '';
+    if ((withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+        (withoutComment.startsWith("'") && withoutComment.endsWith("'"))) {
+        return withoutComment.slice(1, -1);
+    }
+    return withoutComment;
+}
+/**
+ * 把 proxy 合并进文件内容：没有托管块就先按模板建一个，再改这一行。
+ *
+ * @param original - 原文件内容
+ * @param proxy - 已校验的地址；'' = 删掉
+ * @returns 新文件内容
+ */
+export function mergeBrowserBlockProxy(original, proxy) {
+    const value = proxy.trim();
+    let base = original;
+    let found = findBlock(base);
+    if (found === undefined) {
+        base = (base === '' || base.endsWith('\n') ? base : base + '\n') + '\n' + renderBrowserBlock(false, false, false);
+        found = findBlock(base);
+    }
+    if (found === undefined)
+        throw new Error('could not create the managed block; nothing was written');
+    const edited = patchBlockProxy(base.slice(found.start, found.after), value);
+    if (parseBrowserBlockProxy(edited) !== value) {
+        throw new Error('proxy line self-check failed; nothing was written');
+    }
+    return base.slice(0, found.start) + edited + base.slice(found.after);
+}
+/**
+ * 写 proxy：备份 → 原子替换 → 读回校验；校验失败恢复原文件。
+ *
+ * @param proxy - 已校验的地址；'' 表示删掉这一行（= 直连）
+ * @param env - 环境（测试用 DSH_HOME 覆盖）
+ * @returns 写到的文件与现在的值
+ */
+export async function writeProxy(proxy, env = process.env) {
+    const file = homePatchPath(env);
+    const value = proxy.trim();
+    let original = '';
+    try {
+        original = await readFile(file, 'utf8');
+    }
+    catch {
+        original = '';
+    }
+    const next = mergeBrowserBlockProxy(original, value);
+    if (original !== '')
+        await copyFile(file, file + '.bak-browser-toggle').catch(() => { });
+    const tmp = file + '.tmp-browser-toggle';
+    await writeFile(tmp, next, 'utf8');
+    await rename(tmp, file);
+    const check = await readFile(file, 'utf8');
+    if (parseBrowserBlockProxy(check) !== value) {
+        if (original !== '') {
+            await writeFile(file, original, 'utf8');
+            throw new Error('proxy self-check failed after write; previous content restored');
+        }
+        throw new Error('proxy self-check failed after write');
+    }
+    return { patch: file, proxy: value };
+}

package/lib/provider.js

@@ -17,6 +17,7 @@ import { swarmBootScript } from "./swarm-curtain.js";
 import { forgetOnBrowserClose } from "./swarm-intro.js";
 import { isWindowMinimized } from "./window-focus.js";
 import { installHostGuard } from "./navigation-guard.js";
+import { normalizeProxy } from "./proxy.js";
 export class PlaywrightProvider {
     config;
     id = 'playwright';
@@ -62,6 +63,9 @@ export class PlaywrightProvider {
     blockedNavigation = undefined;
     constructor(config) {
         this.config = config;
+        // Fail at load time, not at launch time: a bad proxy address must produce the one
+        // message that explains it (src/proxy.ts), not a wrapped "tried channel …" failure.
+        normalizeProxy(config.launch.proxy);
         // Tell the settings card which page-reading mode this deployment was
         // configured with, so it can show "当前：X（默认）" truthfully instead of
         // assuming the built-in default.

package/lib/proxy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+/** The shape Playwright accepts in `launchOptions.proxy`. */
+export interface LaunchProxy {
+    /** `http://host:port`, `https://host:port` or `socks5://host:port`. */
+    server: string;
+    /** Local addresses bypass the proxy, so the plugin's own local pages keep working. */
+    bypass: string;
+}
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export declare const PROXY_BYPASS = "localhost,127.0.0.1";
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export declare function normalizeProxy(raw: string | undefined | null): LaunchProxy | undefined;
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export declare function proxyLaunchOption(raw: string | undefined | null): {
+    proxy?: LaunchProxy;
+};

package/lib/proxy.js

@@ -0,0 +1,131 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+const ALLOWED_SCHEMES = new Set(['http:', 'https:', 'socks5:']);
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export const PROXY_BYPASS = 'localhost,127.0.0.1';
+/** One clear sentence for every rejection; the value is echoed so a typo is visible. */
+function reject(value, why) {
+    throw new Error('launch.proxy is not a usable proxy address (' +
+        why +
+        '): "' +
+        value +
+        '". ' +
+        'Write it as scheme://host:port (or just host:port) — e.g. http://proxy.example:8080, ' +
+        'https://proxy.example:8443 or socks5://proxy.example:1080. ' +
+        'Leave it empty to connect directly. Authenticated proxies are not supported in this version.');
+}
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export function normalizeProxy(raw) {
+    const value = (raw ?? '').trim();
+    if (value === '')
+        return undefined;
+    // Credentials would have to live in plain text in the user's patch file, and SOCKS5
+    // authentication is not supported by the browser anyway — refuse before launch.
+    if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(value) || /^[^/?#]*@/.test(value)) {
+        throw new Error('launch.proxy must not carry a username or password (found a credential in "' +
+            value +
+            '"). ' +
+            'This version supports proxies WITHOUT authentication only: a password in the config ' +
+            'would be stored in plain text in your patch file, and SOCKS5 authentication is not ' +
+            'supported by Chromium/Playwright at all. Configure an unauthenticated proxy, or leave ' +
+            'this empty to connect directly.');
+    }
+    // Short form: Playwright itself reads `host:port` as HTTP, so accept it the same way.
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : 'http://' + value;
+    // Check the port by hand first: `new URL('http://host:abc')` throws a generic message,
+    // and "the port is not a number" is what the user needs to read.
+    const hostPart = withScheme.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').split('/')[0] ?? '';
+    const hostOnly = hostPart.split('?')[0] ?? '';
+    const portText = (() => {
+        if (hostOnly.startsWith('[')) {
+            const close = hostOnly.indexOf(']');
+            if (close === -1)
+                return '';
+            const rest = hostOnly.slice(close + 1);
+            return rest.startsWith(':') ? rest.slice(1) : '';
+        }
+        const colon = hostOnly.lastIndexOf(':');
+        return colon === -1 ? '' : hostOnly.slice(colon + 1);
+    })();
+    if (portText === '')
+        reject(value, 'the port is missing');
+    if (!/^\d+$/.test(portText ?? ''))
+        reject(value, 'the port is not a number');
+    // Check the range before `new URL` does: an out-of-range port makes the constructor
+    // throw a generic error, and the useful sentence is "the port must be 1–65535".
+    const portNumber = Number(portText);
+    if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+        reject(value, 'the port must be 1–65535');
+    }
+    let url;
+    try {
+        url = new URL(withScheme);
+    }
+    catch {
+        return reject(value, 'it does not parse as a URL');
+    }
+    if (!ALLOWED_SCHEMES.has(url.protocol.toLowerCase())) {
+        reject(value, 'only http, https and socks5 are supported');
+    }
+    if (url.hostname === '')
+        reject(value, 'the host is empty');
+    if (url.port === '' || !/^\d+$/.test(url.port))
+        reject(value, 'the port is not a number');
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        reject(value, 'the port must be 1–65535');
+    // A non-special scheme (socks5) parses with an EMPTY pathname while http/https give '/',
+    // so both are "no path". Anything else means the user appended something.
+    if ((url.pathname !== '' && url.pathname !== '/') || url.search !== '' || url.hash !== '') {
+        reject(value, 'a proxy address has no path, query or fragment');
+    }
+    return {
+        server: url.protocol + '//' + url.hostname + ':' + url.port,
+        // Never proxy the plugin's own local pages.
+        bypass: PROXY_BYPASS,
+    };
+}
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export function proxyLaunchOption(raw) {
+    const proxy = normalizeProxy(raw);
+    return proxy === undefined ? {} : { proxy };
+}

package/lib/settings-card.js

@@ -62,7 +62,8 @@
 import * as runtimeState from "./runtime-state.js";
 // The patch writer lives in its own dependency-free module so it can be tested
 // without a DSH host (a half-written patch layer would break every plugin load).
-import { homePatchPath, parseGatesBlock, writeGates } from "./gates-patch.js";
+import { homePatchPath, parseBrowserBlockProxy, parseGatesBlock, writeGates, writeProxy } from "./gates-patch.js";
+import { normalizeProxy } from "./proxy.js";
 import { onPersistPlayedChanged, resetPlayed } from "./swarm-intro.js";
 import { readFileSync } from 'node:fs';
 import { clean, isTargetId, resolvePaths, scan } from "./cache-clean.js";
@@ -90,6 +91,14 @@ function readGates() {
  * shows the *effective* gates from readGates(); this is the file-level view used
  * for diagnostics when the two disagree (i.e. the reload has not landed yet).
  */
+function managedBlockProxy() {
+    try {
+        return parseBrowserBlockProxy(readFileSync(homePatchPath(), 'utf8'));
+    }
+    catch {
+        return '';
+    }
+}
 function managedBlockGates() {
     try {
         const text = readFileSync(homePatchPath(), 'utf8');
@@ -391,6 +400,8 @@ export function apply(ctx) {
                 // What the user's own layer says right now. Differs from the above
                 // between a write and the live reload that applies it.
                 patchGates: managedBlockGates() ?? null,
+                // launch.proxy（设置页的「代理」输入框）。空 = 直连。
+                proxy: managedBlockProxy(),
             });
         },
     }));
@@ -523,5 +534,55 @@ export function apply(ctx) {
             sendJson(res, 200, { logins });
         },
     }));
+    // ---- launch.proxy：设置页里的「代理」输入框 ----
+    // 只改托管块里 `playwright.launch.proxy` 这一行（与三个闸门同一个模式），
+    // 其它键逐字节不动；空字符串 = 删掉那一行 = 直连。
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/proxy`,
+        handler: async (req, res) => {
+            if (req.method !== 'POST')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'POST only' } });
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const body = await readBody(req);
+            if (!body.ok)
+                return sendJson(res, 400, { error: { code: 'BODY_READ', message: body.error } });
+            let payload;
+            try {
+                payload = JSON.parse(body.text || '{}');
+            }
+            catch {
+                return sendJson(res, 400, { error: { code: 'INVALID_JSON', message: 'body must be JSON' } });
+            }
+            if (typeof payload.proxy !== 'string')
+                return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`proxy` must be a string' } });
+            // 校验直接用 proxy.ts 的同一份实现：非法地址当场报错，文件一个字节不动。
+            let server = '';
+            try {
+                const normalized = normalizeProxy(payload.proxy);
+                server = normalized === undefined ? '' : normalized.server;
+            }
+            catch (error) {
+                return sendJson(res, 400, {
+                    error: { code: 'INVALID_PROXY', message: String(error?.message ?? error) },
+                });
+            }
+            try {
+                const written = await writeProxy(server);
+                sendJson(res, 200, {
+                    proxy: written.proxy,
+                    patch: written.patch,
+                    // 代理是浏览器启动参数：插件在加载时读配置，所以下次启动 DSH 才生效。
+                    appliedOn: 'restart',
+                });
+            }
+            catch (error) {
+                sendJson(res, 500, {
+                    error: { code: 'PATCH_WRITE', message: String(error?.message ?? error) },
+                });
+            }
+        },
+    }));
 }
 export default { name, inject, apply };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Browser automation for DeepSeek Harness, one plugin: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised; native dialogs are parked instead of confirmed, CAPTCHA pages are flagged with a note that says stop and hand the page back, password / one-time-code / card fields are refused by browser_fill, and the Settings card (enable/disable, page-reading mode, capability gates) now lives inside this package.",
   "license": "MIT",
   "type": "module",