Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
feat(browser): 新增「我的浏览器」执行端,经扩展操作用户正在使用的浏览器
Dashb36657428c19
diff --git a/apps/desktop/src/main/__tests__/browser-backend-settings-store.test.ts b/apps/desktop/src/main/__tests__/browser-backend-settings-store.test.tsindex 7c5e1bf734..7b78d89f69 100644--- a/apps/desktop/src/main/__tests__/browser-backend-settings-store.test.ts+++ b/apps/desktop/src/main/__tests__/browser-backend-settings-store.test.ts@@ -33,6 +33,11 @@ describe('browser-backend explicit preferences', () => {});describe('browser-backend-settings-store normalize', () => {+ it('accepts the user browser target and falls back to external for unknown kinds', () => {+ expect(__testing.normalize({ kind: 'user-browser' })).toEqual({ kind: 'user-browser', useRealProfile: false });+ expect(__testing.normalize({ kind: 'chrome' })).toEqual({ kind: 'external', useRealProfile: false });+ });+it('defaults useRealProfile to false', () => {expect(__testing.normalize(undefined)).toEqual({kind: 'external',diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.tsindex a387e9f860..d69a14494f 100644--- a/apps/desktop/src/main/bootstrap-electron.ts+++ b/apps/desktop/src/main/bootstrap-electron.ts@@ -756,6 +756,7 @@ import {setMainWindowAccessorForBackend,setEnsureHostForBackend,setIsDetachedForBackend,+ setUserBrowserPageControlProvider,} from './mcp-integrations/browser.js';import { RsbWindowController } from './right-sidebar-window/controller.js';import { resolveRsbHostContextFromSession } from './right-sidebar-window/resolveHostContext.js';@@ -1146,6 +1147,7 @@ import {setGhostNodeRuntimeStartAttemptContextReader,suspendAllGhosts,waitForGhostMutations,+ getGhostBrowserExtensionSlot,} from './cindy-brain/index.js';import { setCodexImageAuthBinding } from './cindy-brain/codexImageAuthBinding.js';import { configureMailAttachmentHost } from './cindy-brain/mailAttachmentUpload.js';@@ -2499,6 +2501,9 @@ setMainWindowAccessorForBackend((op) => {});setEnsureHostForBackend((sessionId) => rsbWindowController.ensureOpenForAutomation({ sessionId }));setIsDetachedForBackend(() => readRsbWindowSettings().detached);+// 「我的浏览器」后端经 browserExtension 插件槽拿页面控制桥接;槽归 cindy-brain,+// 这里倒置依赖,browser.ts 不反向 import 插件基座。+setUserBrowserPageControlProvider(() => getGhostBrowserExtensionSlot().getPageControl());setBrowserSessionUploadRootResolver(async (sessionId) => {try {const meta = await getMakerCore().getSessionMeta(sessionId);diff --git a/apps/desktop/src/main/browser-backend-settings-store.ts b/apps/desktop/src/main/browser-backend-settings-store.tsindex 9a09413974..a5d68e96b6 100644--- a/apps/desktop/src/main/browser-backend-settings-store.ts+++ b/apps/desktop/src/main/browser-backend-settings-store.ts@@ -91,7 +91,7 @@ const DEFAULTS: BrowserBackendSettings = {useRealProfile: false,};-const VALID_KINDS: readonly BackendKind[] = ['external', 'rsb-webview'];+const VALID_KINDS: readonly BackendKind[] = ['external', 'rsb-webview', 'user-browser'];function settingsFilePath(): string {return path.join(app.getPath('userData'), 'browser-backend-settings.json');diff --git a/apps/desktop/src/main/browser-extension/bridge.ts b/apps/desktop/src/main/browser-extension/bridge.tsindex ae6ecb0012..309b26fa3a 100644--- a/apps/desktop/src/main/browser-extension/bridge.ts+++ b/apps/desktop/src/main/browser-extension/bridge.ts@@ -724,7 +724,14 @@ export class BrowserExtensionBridge {this.authenticatedCredential(client) &&this.normalizePublicKey(this.header(req, 'x-my-browser-key')) === client.publicKey &&this.verifyProof(client.publicKey, payload, proof);- if (!valid)+ if (!valid) {+ this.options.log?.warn('browser extension relay signature rejected', {+ url: req.url,+ method: req.method,+ clientId: clientId.slice(0, 8),+ pending: !!pending,+ authenticated: this.authenticatedCredential(client),+ });return this.send(res,failure(@@ -733,6 +740,7 @@ export class BrowserExtensionBridge {),403,);+ }this.relayChallenges.delete(challenge);}if (req.method === 'POST' && req.url === '/learning/start') {@@ -795,6 +803,11 @@ export class BrowserExtensionBridge {progress: { stage: 'accepted', startedAt: created, updatedAt: created, attempt: 1 },};this.relays.set(b.id, item);+ this.options.log?.info('browser extension relay accepted', {+ id: b.id,+ op: payload.op,+ clientId: clientId.slice(0, 8),+ });try {this.options.onRelay?.({ id: b.id, clientId, request: payload });} catch (err) {@@ -817,6 +830,7 @@ export class BrowserExtensionBridge {404,);if (req.url === '/learning/cancel') {+ this.options.log?.info('browser extension relay cancelled', { id: item.id });this.relays.delete(item.id);return this.send(res, { ok: true });}@@ -1141,6 +1155,10 @@ export class BrowserExtensionBridge {if (!found.item.result) {found.item.result = result;found.item.expiresAt = this.now() + RELAY_TIMING.resultRetention;+ this.options.log?.info('browser extension relay answered', {+ id,+ ok: (result as { ok?: unknown } | null)?.ok === true,+ });}return { ok: true };}diff --git a/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts b/apps/desktop/src/main/cindy-brain/browserExtensionSlot.tsindex 1ea4b29985..7ff58dd316 100644--- a/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts+++ b/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts@@ -221,6 +221,11 @@ export class GhostBrowserExtensionSlot {});}}+ if (delivered)+ this.deps.log?.info('browser extension relay delivered to plugin', {+ instanceId,+ id: notice.id,+ });if (!delivered) {this.deps.log?.warn('browser extension relay undeliverable; plugin logic page offline', {instanceId,diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/controller.test.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/controller.test.tsindex fbbb0a594b..9985ef2df0 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/controller.test.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/controller.test.ts@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';import type { BrowserControlRequest, BrowserControlResult } from '@cindy/browser-control-runtime';-import { BrowserBackendController } from '../controller.js';+import { BrowserBackendController, resolveBackendProfile } from '../controller.js';import { createBrowserProfileLifecycleQueue } from '../../browser-real-profile/runtime-stop.js';import type { BackendKind, BrowserBackend } from '../types.js';@@ -285,3 +285,18 @@ describe('BrowserBackendController', () => {expect(second.probeControl).toHaveBeenCalledOnce();});});++describe('resolveBackendProfile', () => {+ // Bug regression, unit: with the user's browser active, the MCP layer used to+ // substitute the managed Chrome profile name for a missing `profile`; the+ // extension backend matched no connection and every tool reported the+ // extension as disconnected.+ it('never substitutes the managed profile for the user browser backend', () => {+ const managed = vi.fn(() => 'Cindy-real');+ expect(resolveBackendProfile('user-browser', undefined, managed)).toBeUndefined();+ expect(resolveBackendProfile('user-browser', 'abc12345', managed)).toBe('abc12345');+ expect(managed).not.toHaveBeenCalled();+ expect(resolveBackendProfile('external', undefined, managed)).toBe('Cindy-real');+ expect(resolveBackendProfile('rsb-webview', 'ignored', managed)).toBe('rsb');+ });+});diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/health-service.test.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/health-service.test.tsindex 52ecc41aea..bc180e5c48 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/health-service.test.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/health-service.test.ts@@ -6,7 +6,7 @@ import { BrowserBackendHealthService } from '../health-service.js';function controller() {return {getCurrentBackendKind: vi.fn(- (): 'external' | 'rsb-webview' => 'rsb-webview',+ (): 'external' | 'rsb-webview' | 'user-browser' => 'rsb-webview',),call: vi.fn(async (request: BrowserControlRequest): Promise<BrowserControlResult> => ({@@ -215,4 +215,18 @@ describe('BrowserBackendHealthService', () => {});expect(ctl.call).not.toHaveBeenCalled();});++ it('reports the user browser as ready only while an extension is connected and never offers recovery', async () => {+ const ctl = controller();+ ctl.getCurrentBackendKind.mockReturnValue('user-browser');+ ctl.call.mockResolvedValueOnce({ ok: true, action: 'status', status: 200, data: { ready: true, connected: true } });+ const service = new BrowserBackendHealthService(ctl, logger());+ await expect(service.getHealth()).resolves.toEqual({ active: 'user-browser', status: 'ready', canRecover: false });+ ctl.call.mockResolvedValueOnce({ ok: true, action: 'status', status: 200, data: { ready: false, connected: false } });+ await expect(service.getHealth()).resolves.toEqual({+ active: 'user-browser', status: 'error', canRecover: false, reason: 'extension-disconnected',+ });+ expect(ctl.restartEmbedded).not.toHaveBeenCalled();+ expect(ctl.probeActiveControl).not.toHaveBeenCalled();+ });});diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/settings-ipc.test.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/settings-ipc.test.tsindex 3c4fb8ccbd..03103c8836 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/settings-ipc.test.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/settings-ipc.test.ts@@ -14,7 +14,7 @@ function buildHandlers() {isOverride: true,useRealProfile: false,})),- setKind: vi.fn(async (kind: 'external' | 'rsb-webview') => kind),+ setKind: vi.fn(async (kind: 'external' | 'rsb-webview' | 'user-browser') => kind),setUseRealProfile: vi.fn(async (enabled: boolean) => enabled),reset: vi.fn(async () => 'external' as const),getHealth: vi.fn(async () => ({diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/user-browser-backend.test.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/user-browser-backend.test.tsnew file mode 100644index 0000000000..2aa0211cd6--- /dev/null+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/__tests__/user-browser-backend.test.ts@@ -0,0 +1,452 @@+/**+ * user-browser-backend.test — 用户浏览器执行端对 BrowserControlRequest 的翻译。+ *+ * 测试价值+ * - 生产入口与可观察结果:UserBrowserBackend.call;MCP 层看到的 status / tabs / open /+ * snapshot / act / extract 数据形状,以及不支持操作的明确拒绝。+ * - 规则依据:2026-10-27 融合决定——扩展权限不扩大、能力不足明确拒绝、不悄悄换浏览器;+ * 扩展按 URL 寻址,页面跳转须报 PAGE_CHANGED 而不是猜新页。+ * - 现有覆盖缺口:新后端。+ * - 最小失败输入:未装页面控制插件;多连接未指定 profile;标签页 URL 与记录不一致;+ * evaluate 不带 domRead。+ * - tier:unit(假桥接);实测耗时 < 1 秒。+ */++import { describe, expect, it, vi } from 'vitest';++import type { BrowserControlRequest } from '@cindy/browser-control-runtime';++import { UserBrowserBackend, type UserBrowserPageControl } from '../user-browser-backend';++type Tab = { id: number; url: string; title?: string; active?: boolean; redacted?: boolean };++function fakeControl(options: { clients?: string[]; tabs?: Record<string, Tab[]> } = {}) {+ const clients = options.clients ?? ['client-aaaaaaaa'];+ const tabs = options.tabs ?? {+ [clients[0]]: [{ id: 7, url: 'https://example.test/a', title: 'A', active: true }],+ };+ const jobs: Array<[string, Record<string, unknown>]> = [];+ const responses = new Map<+ string,+ (payload: Record<string, unknown>) => Record<string, unknown>+ >();+ const bridge = {+ connectedClients: () =>+ clients.map((id) => ({+ id,+ browser: 'chrome',+ version: '0.4.23',+ protocolVersion: '0.4.13',+ connected: true,+ })),+ status: async () => ({+ ok: true,+ port: 18810,+ extension_ids: ['a'.repeat(32)],+ pending: 0,+ clients: clients.map((id) => ({+ id,+ browser: 'chrome',+ version: '0.4.23',+ protocolVersion: '0.4.13',+ connected: true,+ })),+ }),+ act: vi.fn(async (action: string, payload: Record<string, unknown>) => {+ jobs.push([action, payload]);+ const scripted = responses.get(action);+ if (scripted) return scripted(payload);+ if (action === 'tabs') return { ok: true, tabs: tabs[payload.browser as string] ?? [] };+ if (action === 'navigate') return { ok: true, url: payload.url };+ return { ok: true, url: payload.url, execution: 'executed', note: 'dispatched' };+ }),+ };+ const control: UserBrowserPageControl = {+ bridge: bridge as unknown as UserBrowserPageControl['bridge'],+ ghostId: 'my-browser',+ pluginName: 'Cindy Chrome',+ };+ return { control, jobs, responses, tabs };+}++function backend(control: UserBrowserPageControl | null) {+ return new UserBrowserBackend({+ getPageControl: () => control,+ logger: { info: vi.fn(), warn: vi.fn() },+ });+}++const call = (b: UserBrowserBackend, req: Record<string, unknown>) =>+ b.call(req as unknown as BrowserControlRequest);++describe('UserBrowserBackend · 就绪与连接', () => {+ it('没有页面控制插件时 status 如实报告,动作按未配置拒绝', async () => {+ const b = backend(null);+ expect(await call(b, { action: 'status' })).toMatchObject({+ ok: true,+ data: { ready: false, configured: false, backend: 'user-browser' },+ });+ expect(await call(b, { action: 'tabs' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_NOT_CONFIGURED',+ });+ });++ it('扩展未连接时 status 未就绪、start 失败;已连接时列出连接与能力表', async () => {+ const none = fakeControl({ clients: [] });+ const b = backend(none.control);+ expect(await call(b, { action: 'status' })).toMatchObject({+ ok: true,+ data: { ready: false, configured: true, connected: false },+ });+ expect(await call(b, { action: 'start' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_UNAVAILABLE',+ });+ const one = fakeControl();+ const ready = backend(one.control);+ expect(await call(ready, { action: 'status' })).toMatchObject({+ ok: true,+ data: {+ ready: true,+ connected: true,+ plugin: 'my-browser',+ capabilities: { evaluate: false, screenshot: false },+ },+ });+ expect(await call(ready, { action: 'doctor' })).toMatchObject({+ ok: true,+ data: { port: 18810 },+ });+ expect(await call(ready, { action: 'start', proxyServer: 'http://proxy' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST',+ });+ expect(await call(ready, { action: 'profiles' })).toMatchObject({+ ok: true,+ data: { profiles: [{ id: 'client-aaaaaaaa', browser: 'chrome' }] },+ });+ });++ it('多条连接且未指定 profile 时拒绝,不猜账号;profile 前缀可定位连接', async () => {+ const two = fakeControl({+ clients: ['client-aaaaaaaa', 'client-bbbbbbbb'],+ tabs: { 'client-bbbbbbbb': [{ id: 1, url: 'https://b.test/' }] },+ });+ const b = backend(two.control);+ expect(await call(b, { action: 'open', url: 'https://b.test/' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST',+ });+ expect(+ await call(b, { action: 'open', url: 'https://b.test/', profile: 'client-bbbb' }),+ ).toMatchObject({ ok: true, data: { browser: 'client-bbbbbbbb', url: 'https://b.test/' } });+ });+});++describe('UserBrowserBackend · 标签页与寻址', () => {+ it('tabs 映射稳定 targetId 与别名,保留被打码行;open 返回可用 targetId 并记住 label', async () => {+ const fake = fakeControl({+ tabs: {+ 'client-aaaaaaaa': [+ { id: 7, url: 'https://example.test/a', title: 'A', active: true },+ { id: 9, url: '', redacted: true },+ ],+ },+ });+ const b = backend(fake.control);+ const listed = await call(b, { action: 'tabs' });+ expect(listed.ok).toBe(true);+ const tabs = (listed.data as { tabs: Array<Record<string, unknown>> }).tabs;+ expect(tabs[0]).toMatchObject({+ targetId: 'client-a:7',+ suggestedTargetId: 't1',+ tabId: 't1',+ url: 'https://example.test/a',+ title: 'A',+ active: true,+ });+ expect(tabs[1]).toMatchObject({ targetId: 'client-a:9', redacted: true });+ fake.tabs['client-aaaaaaaa'].push({ id: 11, url: 'https://example.test/b', title: 'B' });+ const opened = await call(b, {+ action: 'open',+ url: 'https://example.test/b',+ label: 'checkout',+ });+ expect(opened).toMatchObject({+ ok: true,+ data: {+ targetId: 'client-a:11',+ suggestedTargetId: 'checkout',+ label: 'checkout',+ url: 'https://example.test/b',+ },+ });+ expect(fake.jobs.find(([action]) => action === 'navigate')?.[1]).toMatchObject({+ url: 'https://example.test/b',+ browser: 'client-aaaaaaaa',+ });+ // navigate 可能落到另一个标签页:返回新 targetId 并标明替换。+ fake.tabs['client-aaaaaaaa'].push({ id: 12, url: 'https://example.test/c' });+ const navigated = await call(b, {+ action: 'navigate',+ targetId: 'checkout',+ url: 'https://example.test/c',+ });+ expect(navigated).toMatchObject({+ ok: true,+ data: { targetId: 'client-a:12', replacedTargetId: 'client-a:11' },+ });+ });++ it('标签页在两次调用之间跳转时报 PAGE_CHANGED 并刷新记录;关闭后提示重新选择', async () => {+ const fake = fakeControl();+ const b = backend(fake.control);+ await call(b, { action: 'tabs' });+ fake.tabs['client-aaaaaaaa'][0].url = 'https://example.test/moved';+ const changed = await call(b, { action: 'snapshot', targetId: 't1' });+ expect(changed).toMatchObject({+ ok: false,+ data: { error: 'PAGE_CHANGED', url: 'https://example.test/moved' },+ });+ expect(fake.jobs.some(([action]) => action === 'snapshot')).toBe(false);+ fake.tabs['client-aaaaaaaa'] = [];+ expect(await call(b, { action: 'snapshot', targetId: 't1' })).toMatchObject({+ ok: false,+ message: expect.stringContaining('已关闭'),+ });+ expect(await call(b, { action: 'snapshot', targetId: 'unknown' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST',+ });+ });+});++describe('UserBrowserBackend · 读取与动作', () => {+ it('snapshot 把扩展的元素行转成 ref 表与可读快照', async () => {+ const fake = fakeControl();+ const ref = 'c'.repeat(32);+ fake.responses.set('snapshot', (payload) => ({+ ok: true,+ url: payload.url,+ title: 'A',+ text: 'Hello page',+ elements: `[${ref}] button Submit\n[${'d'.repeat(32)}] a`,+ truncated: false,+ }));+ const b = backend(fake.control);+ await call(b, { action: 'tabs' });+ const snap = await call(b, {+ action: 'snapshot',+ targetId: 'client-a:7',+ selector: 'main',+ maxChars: 512,+ });+ expect(snap).toMatchObject({+ ok: true,+ data: {+ format: 'ai',+ targetId: 'client-a:7',+ url: 'https://example.test/a',+ refs: { [ref]: { role: 'button', name: 'Submit' }, ['d'.repeat(32)]: { role: 'a' } },+ untrusted_content: true,+ },+ });+ const snapshot = (snap.data as { snapshot: string }).snapshot;+ expect(snapshot).toContain('# A');+ expect(snapshot).toContain('Hello page');+ expect(snapshot).toContain(`- button "Submit" [ref=${ref}]`);+ expect(fake.jobs.at(-1)).toEqual([+ 'snapshot',+ {+ url: 'https://example.test/a',+ browser: 'client-aaaaaaaa',+ maxChars: 512,+ selector: 'main',+ },+ ]);+ });++ it('click / type / press / select / wait 翻译成扩展作业;不支持的 kind 明确拒绝', async () => {+ const fake = fakeControl();+ const b = backend(fake.control);+ await call(b, { action: 'tabs' });+ const base = { url: 'https://example.test/a', browser: 'client-aaaaaaaa' };+ expect(+ await call(b, { action: 'act', targetId: 't1', request: { kind: 'click', ref: 'r1' } }),+ ).toMatchObject({ ok: true, data: { kind: 'click', execution: 'executed' } });+ expect(fake.jobs.at(-1)).toEqual(['click', { ...base, ref: 'r1' }]);+ await call(b, {+ action: 'act',+ request: { kind: 'fill', targetId: 't1', selector: 'input', text: 'hi', submit: true },+ });+ expect(fake.jobs.at(-1)).toEqual([+ 'type',+ { ...base, selector: 'input', text: 'hi', submit: true },+ ]);+ await call(b, { action: 'act', targetId: 't1', request: { kind: 'press', key: 'Enter' } });+ expect(fake.jobs.at(-1)).toEqual(['press', { ...base, key: 'Enter' }]);+ await call(b, {+ action: 'act',+ targetId: 't1',+ request: { kind: 'select', selector: 'select', values: ['x'] },+ });+ expect(fake.jobs.at(-1)).toEqual(['select', { ...base, selector: 'select', values: ['x'] }]);+ await call(b, {+ action: 'act',+ targetId: 't1',+ request: { kind: 'wait', selector: '.ready', timeoutMs: 5000 },+ });+ expect(fake.jobs.at(-1)).toEqual([+ 'text',+ { ...base, selector: '.ready', waitFor: '.ready', waitMs: 5000, maxChars: 256 },+ ]);+ expect(+ await call(b, { action: 'act', targetId: 't1', request: { kind: 'wait', timeMs: 1 } }),+ ).toMatchObject({ ok: true, data: { kind: 'wait', waitedMs: 1 } });+ for (const request of [+ { kind: 'click', ref: 'r1', doubleClick: true },+ { kind: 'drag', startRef: 'a', endRef: 'b' },+ { kind: 'evaluate', fn: '() => 1' },+ { kind: 'wait', fn: '() => true' },+ { kind: 'click', query: { role: 'button' } },+ ]) {+ expect(await call(b, { action: 'act', targetId: 't1', request })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST',+ message: expect.stringContaining('专用浏览器'),+ });+ }+ for (const action of [+ 'screenshot',+ 'pdf',+ 'console',+ 'upload',+ 'dialog',+ 'requests',+ 'responseBody',+ 'focus',+ 'close',+ 'recipeCommand',+ ]) {+ expect(await call(b, { action, targetId: 't1' })).toMatchObject({+ ok: false,+ errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST',+ });+ }+ expect(+ fake.jobs.filter(+ ([action]) => !['tabs', 'click', 'type', 'press', 'select', 'text'].includes(action),+ ),+ ).toEqual([]);+ });++ it('声明式读取走扩展 extract:字段映射、结果包装;登录墙检测如实报告不可用', async () => {+ const fake = fakeControl();+ fake.responses.set('extract', (payload) => ({+ ok: true,+ url: payload.url,+ count: 1,+ records: [{ title: 'T', link: 'https://example.test/x' }],+ truncated: false,+ }));+ const b = backend(fake.control);+ await call(b, { action: 'tabs' });+ const extracted = await call(b, {+ action: 'act',+ targetId: 't1',+ request: {+ kind: 'evaluate',+ fn: 'ignored',+ domRead: {+ kind: 'extract',+ extract: {+ from: '.row',+ multiple: true,+ limit: 5,+ fields: { title: 'h3', link: { selector: 'a', type: 'href' }, self: { attr: 'title' } },+ },+ },+ },+ });+ expect(extracted).toMatchObject({+ ok: true,+ data: { result: { ok: true, count: 1, records: [{ title: 'T' }] }, untrusted_content: true },+ });+ expect(fake.jobs.at(-1)).toEqual([+ 'extract',+ {+ url: 'https://example.test/a',+ browser: 'client-aaaaaaaa',+ fields: {+ title: 'h3',+ link: { selector: 'a', attr: 'href' },+ self: { selector: ':self', attr: 'title' },+ },+ from: '.row',+ multiple: true,+ limit: 5,+ maxChars: 6000,+ },+ ]);+ // Bug regression: a whole-page read (`body` / `:scope`, no `from`) came back+ // null because the extension resolves fields against document.body and only+ // knows ':self'; a single-record `from` was ignored for the same reason.+ await call(b, {+ action: 'act',+ targetId: 't1',+ request: {+ kind: 'evaluate',+ fn: 'ignored',+ domRead: {+ kind: 'extract',+ extract: { fields: { page: 'body', self: { selector: ':scope' }, rows: 'tr' } },+ },+ },+ });+ expect(fake.jobs.at(-1)?.[1]).toMatchObject({+ fields: { page: ':self', self: { selector: ':self' }, rows: 'tr' },+ });+ expect(fake.jobs.at(-1)?.[1]).not.toHaveProperty('from');+ await call(b, {+ action: 'act',+ targetId: 't1',+ request: {+ kind: 'evaluate',+ fn: 'ignored',+ domRead: { kind: 'extract', extract: { from: 'main', fields: { text: {} } } },+ },+ });+ expect(fake.jobs.at(-1)?.[1]).toMatchObject({+ selector: 'main',+ fields: { text: { selector: ':self' } },+ });+ expect(fake.jobs.at(-1)?.[1]).not.toHaveProperty('from');+ expect(+ await call(b, {+ action: 'act',+ targetId: 't1',+ request: {+ kind: 'evaluate',+ fn: 'x',+ domRead: { kind: 'extract', extract: { fields: { body: { type: 'html' } } } },+ },+ }),+ ).toMatchObject({ ok: false, errorCode: 'BROWSER_RUNTIME_INVALID_REQUEST' });+ const wall = await call(b, {+ action: 'act',+ targetId: 't1',+ request: { kind: 'evaluate', fn: 'x', domRead: { kind: 'login-wall' } },+ });+ expect(wall).toMatchObject({+ ok: true,+ data: { result: { password: false, code: false, unavailable: true } },+ });+ expect(+ fake.jobs.filter(+ ([action, payload]) =>+ action === 'extract' && (payload.fields as Record<string, unknown>).password,+ ),+ ).toEqual([]);+ });+});diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/controller.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/controller.tsindex ccc0698de9..7afc3d5870 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/controller.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/controller.ts@@ -10,6 +10,8 @@ export interface BrowserBackendControllerOptions {initialKind: BackendKind;externalBackend: BrowserBackend;createRsbBackend: () => BrowserBackend;+ /** 用户浏览器(经扩展)后端工厂;实例无状态可重建,桥接归插件槽所有。缺省 = 该目标不可选。 */+ createUserBrowserBackend?: () => BrowserBackend;/** Save explicit selections inside the existing transition queue. */persistKind?: (kind: BackendKind) => void;logger: ControllerLogger;@@ -84,7 +86,12 @@ export class BrowserBackendController implements BrowserBackend {}private createBackend(kind: BackendKind): BrowserBackend {- const backend = kind === 'external' ? this.opts.externalBackend : this.opts.createRsbBackend();+ const backend =+ kind === 'external'+ ? this.opts.externalBackend+ : kind === 'user-browser'+ ? this.createUserBrowserBackend()+ : this.opts.createRsbBackend();if (backend.kind !== kind) {throw new Error(`browser backend factory returned ${backend.kind} for ${kind}`);}@@ -96,6 +103,12 @@ export class BrowserBackendController implements BrowserBackend {* need the profile queue acquire it inside this operation, matching reset.* Ordinary page calls bypass this lifecycle queue.*/+ private createUserBrowserBackend(): BrowserBackend {+ if (!this.opts.createUserBrowserBackend)+ throw new Error('user browser backend factory not configured');+ return this.opts.createUserBrowserBackend();+ }+runLifecycle<T>(operation: () => Promise<T>): Promise<T> {const result = this.transition.then(operation, operation);const settled = result.then(@@ -111,3 +124,22 @@ export class BrowserBackendController implements BrowserBackend {});}}++/**+ * Resolve the `profile` a browser request addresses for the active backend.+ *+ * - rsb-webview has exactly one profile.+ * - external Chrome falls back to the managed profile when the agent names none.+ * - The user's own browser has no managed profile: `profile` there is an+ * extension connection id chosen by the agent, so the managed Chrome profile+ * name must never be substituted (it would match no connection).+ */+export function resolveBackendProfile(+ kind: BackendKind,+ profile: string | undefined,+ managedProfile: () => string,+): string | undefined {+ if (kind === 'rsb-webview') return 'rsb';+ if (kind === 'user-browser') return profile;+ return profile || managedProfile();+}diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/health-service.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/health-service.tsindex c5b7675482..a2a459907d 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/health-service.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/health-service.ts@@ -165,6 +165,21 @@ export class BrowserBackendHealthService {private async probe(ensureHost = false): Promise<BrowserBackendHealth> {const active = this.controller.getCurrentBackendKind();+ // The user's own browser is reached through the plugin-owned extension+ // bridge: health is "an extension is connected" and nothing here can+ // rebuild that connection, so recovery is never offered.+ if (active === 'user-browser') {+ try {+ const status = await this.controller.call({ action: 'status' });+ const connected = status.ok && (status.data as { connected?: unknown } | undefined)?.connected === true;+ return connected+ ? { active, status: 'ready', canRecover: false }+ : { active, status: 'error', canRecover: false, reason: 'extension-disconnected' };+ } catch (err) {+ this.logger.warn('user browser status probe failed', { err });+ return { active, status: 'error', canRecover: false, reason: 'extension-disconnected' };+ }+ }// External Chrome has a separate availability/recovery UI. This contract// intentionally verifies only the embedded bridge.if (active !== 'rsb-webview') {diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/index.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/index.tsindex 6e6f670dcb..f721c6b572 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/index.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/index.ts@@ -13,6 +13,10 @@ export type {} from './types.js';export { ExternalChromeBackend } from './external-chrome-backend.js';export { BackendRouter } from './router.js';-export { BrowserBackendController, type BrowserBackendControllerOptions } from './controller.js';+export {+ BrowserBackendController,+ resolveBackendProfile,+ type BrowserBackendControllerOptions,+} from './controller.js';export { BrowserBackendHealthService } from './health-service.js';export { RsbWebviewBackend, type RsbWebviewBackendOptions } from './rsb-webview-backend.js';diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/settings-ipc.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/settings-ipc.tsindex ec8eb06948..2a66a4138e 100644--- a/apps/desktop/src/main/mcp-integrations/browser-backend/settings-ipc.ts+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/settings-ipc.ts@@ -39,7 +39,7 @@ export function createBrowserBackendIpcHandlers<Event>(deps: BrowserBackendIpcDeasync setKind(event: Event, payload: unknown) {deps.assertTrusted(event);const obj = requireObject(payload, 'set-kind payload');- const kind = requireEnum(obj.kind, ['external', 'rsb-webview'] as const, 'kind');+ const kind = requireEnum(obj.kind, ['external', 'rsb-webview', 'user-browser'] as const, 'kind');return { ok: true as const, active: await deps.setKind(kind) };},async setUseRealProfile(event: Event, payload: unknown) {diff --git a/apps/desktop/src/main/mcp-integrations/browser-backend/user-browser-backend.ts b/apps/desktop/src/main/mcp-integrations/browser-backend/user-browser-backend.tsnew file mode 100644index 0000000000..2909f7c652--- /dev/null+++ b/apps/desktop/src/main/mcp-integrations/browser-backend/user-browser-backend.ts@@ -0,0 +1,912 @@+/**+ * UserBrowserBackend — 把用户正在使用的浏览器(经随包浏览器扩展)接成 Browser Use+ * 的第三个控制目标。+ *+ * 与另外两个后端的差别:+ * - 页面活在用户自己的 Chrome / Edge 里,带着用户本人的登录态;Cindy 不启停它;+ * - 执行端是扩展在隔离世界里的固定函数,没有 debugger、任意脚本、网络读取、截图、+ * 上传与原生弹窗。不支持的 action 明确拒绝并指向专用浏览器,绝不悄悄换目标;+ * - 每个作业都经桥接按插件保存的站点策略守门(读默认开放公网,交互按站点授权,+ * 本机与私网一律拒绝),结果脱敏后才回到这里。+ *+ * 寻址:扩展当前按精确 URL 寻址标签页,这里维护 targetId ↔ {连接, tabId, url} 的+ * 映射,把 Browser Use 的 targetId / 别名 / label 翻译成作业的 url;页面在+ * 两次调用之间跳转时,扩展报 PAGE_CHANGED,这里刷新映射后原样上报,不猜新页。+ */++import type {+ BrowserExtensionBridge,+ BrowserExtensionClientInfo,+ BrowserExtensionJobResult,+} from '../../browser-extension/bridge.js';+import type { BackendRequest, BackendResult, BrowserBackend } from './types.js';++export interface UserBrowserPageControl {+ bridge: BrowserExtensionBridge;+ ghostId: string;+ pluginName: string;+}++export interface UserBrowserBackendOptions {+ /** 声明 browserExtension.pageControl 的插件桥接;null = 没有这样的插件(或未启用)。 */+ getPageControl(): UserBrowserPageControl | null;+ logger: {+ info(message: string, meta?: unknown): void;+ warn(message: string, meta?: unknown): void;+ };+ now?(): number;+}++interface TargetRecord {+ targetId: string;+ alias: string;+ label?: string;+ clientId: string;+ tabId: number;+ url: string;+ title?: string;+}++export const USER_BROWSER_UNSUPPORTED_HINT =+ '用户浏览器执行端不支持此操作;需要时请明确告知用户并改用 Cindy 专用浏览器(external),不要自行切换。';++/** 用户浏览器执行端的能力表(供 MCP 层在调用前拒绝,与 status 一并告知模型)。 */+export const USER_BROWSER_CAPABILITIES = Object.freeze({+ evaluate: false,+ screenshot: false,+ network: false,+ upload: false,+ dialog: false,+ console: false,+ pdf: false,+ focus: false,+ close: false,+ trustedInput: false,+});++function actionFailed(+ action: BackendRequest['action'],+ message: string,+ errorCode: BackendResult['errorCode'] = 'BROWSER_RUNTIME_ACTION_FAILED',+): BackendResult {+ return { ok: false, action, errorCode, message };+}++function actionOk(action: BackendRequest['action'], data: unknown): BackendResult {+ return { ok: true, action, status: 200, data };+}++function unsupported(action: BackendRequest['action'], what: string): BackendResult {+ return actionFailed(+ action,+ `${what}:${USER_BROWSER_UNSUPPORTED_HINT}`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+}++const NOT_CONFIGURED_MESSAGE =+ '没有已启用的浏览器扩展插件提供页面控制(安装并启用 Cindy Chrome 插件后再选择「我的浏览器」)。';+const DISCONNECTED_MESSAGE =+ '浏览器扩展未连接:请在用户的 Chrome / Edge 中安装并启用 Cindy 扩展,保持 Cindy 运行;连接后重新查询 status。';++const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));++export class UserBrowserBackend implements BrowserBackend {+ readonly kind = 'user-browser' as const;+ private readonly targets = new Map<string, TargetRecord>();+ private nextAlias = 1;+ private disposed = false;++ constructor(private readonly opts: UserBrowserBackendOptions) {}++ async call(request: BackendRequest): Promise<BackendResult> {+ if (this.disposed)+ return actionFailed(+ request.action,+ 'user browser backend disposed',+ 'BROWSER_RUNTIME_UNAVAILABLE',+ );+ try {+ return await this.dispatch(request);+ } catch (err) {+ this.opts.logger.warn('user-browser backend call threw', {+ action: request.action,+ err: err instanceof Error ? err.message : String(err),+ });+ return actionFailed(request.action, err instanceof Error ? err.message : String(err));+ }+ }++ async dispose(): Promise<void> {+ this.disposed = true;+ this.targets.clear();+ }++ // ── 分发 ────────────────────────────────────────────────────────────────++ private async dispatch(req: BackendRequest): Promise<BackendResult> {+ switch (req.action) {+ case 'status':+ return this.handleStatus(req);+ case 'doctor':+ return this.handleStatus(req, true);+ case 'start':+ return this.handleStart(req);+ case 'stop':+ return actionOk(req.action, {+ ready: true,+ backend: this.kind,+ note: '用户浏览器由用户自己启停,Cindy 不关闭它。',+ });+ case 'profiles':+ return this.handleProfiles(req);+ case 'tabs':+ return this.handleTabs(req);+ case 'open':+ case 'navigate':+ return this.handleOpen(req);+ case 'snapshot':+ return this.handleSnapshot(req);+ case 'act':+ return this.handleAct(req);+ case 'focus':+ return unsupported(req.action, '切换活动标签页');+ case 'close':+ return unsupported(req.action, '关闭标签页');+ case 'screenshot':+ return unsupported(req.action, '截图');+ case 'pdf':+ return unsupported(req.action, '导出 PDF');+ case 'console':+ return unsupported(req.action, '读取控制台');+ case 'upload':+ return unsupported(req.action, '上传文件');+ case 'dialog':+ return unsupported(req.action, '处理原生弹窗');+ case 'requests':+ case 'responseBody':+ return unsupported(req.action, '读取网络请求');+ case 'recipeCommand':+ return unsupported(req.action, '原始协议命令(OpenCLI 适配器)');+ default:+ return actionFailed(+ req.action,+ `action '${String(req.action)}' is not supported by the user browser backend`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+ }+ }++ // ── 连接解析 ────────────────────────────────────────────────────────────++ private control(+ action: BackendRequest['action'],+ ): { ok: true; control: UserBrowserPageControl } | { ok: false; result: BackendResult } {+ const control = this.opts.getPageControl();+ if (!control)+ return {+ ok: false,+ result: actionFailed(action, NOT_CONFIGURED_MESSAGE, 'BROWSER_RUNTIME_NOT_CONFIGURED'),+ };+ return { ok: true, control };+ }++ private connectedClients(control: UserBrowserPageControl): BrowserExtensionClientInfo[] {+ return control.bridge.connectedClients();+ }++ /** 选连接:显式 profile(连接 id)优先;只有一条连接时直接用;多条且未指定时拒绝,不猜账号。 */+ private pickClient(+ action: BackendRequest['action'],+ control: UserBrowserPageControl,+ profile: string | undefined,+ ): { ok: true; clientId: string } | { ok: false; result: BackendResult } {+ const clients = this.connectedClients(control);+ if (clients.length === 0)+ return {+ ok: false,+ result: actionFailed(action, DISCONNECTED_MESSAGE, 'BROWSER_RUNTIME_UNAVAILABLE'),+ };+ if (profile) {+ const found = clients.find((c) => c.id === profile || c.id.startsWith(profile));+ if (!found)+ return {+ ok: false,+ result: actionFailed(+ action,+ `未找到浏览器连接 ${profile};用 profiles 查看当前连接`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ ),+ };+ return { ok: true, clientId: found.id };+ }+ if (clients.length === 1) return { ok: true, clientId: clients[0].id };+ return {+ ok: false,+ result: actionFailed(+ action,+ `有 ${clients.length} 个浏览器连接;请用 profile 指定连接 id(见 profiles),不要猜测账号`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ ),+ };+ }++ private failureResult(+ action: BackendRequest['action'],+ job: BrowserExtensionJobResult,+ ): BackendResult {+ const error = typeof job.error === 'string' ? job.error : 'BROWSER_EXTENSION_FAILED';+ const message = typeof job.message === 'string' ? job.message : '浏览器扩展操作失败';+ const execution = job.execution;+ return {+ ok: false,+ action,+ errorCode:+ error === 'EXTENSION_DISCONNECTED' || error === 'BRIDGE_PORTS_BUSY'+ ? 'BROWSER_RUNTIME_UNAVAILABLE'+ : 'BROWSER_RUNTIME_ACTION_FAILED',+ message: `${error}:${message}`,+ data: {+ error,+ ...(typeof execution === 'string' ? { execution } : {}),+ ...(job.clients ? { clients: job.clients } : {}),+ ...(job.reason ? { reason: job.reason } : {}),+ },+ };+ }++ // ── 目标表 ──────────────────────────────────────────────────────────────++ private targetKey(clientId: string, tabId: number): string {+ return `${clientId.slice(0, 8)}:${tabId}`;+ }++ private register(+ clientId: string,+ tab: { id: number; url: string; title?: string },+ label?: string,+ ): TargetRecord {+ const targetId = this.targetKey(clientId, tab.id);+ let record = this.targets.get(targetId);+ if (!record) {+ record = {+ targetId,+ alias: `t${this.nextAlias++}`,+ clientId,+ tabId: tab.id,+ url: tab.url,+ title: tab.title,+ };+ this.targets.set(targetId, record);+ } else {+ record.url = tab.url;+ record.title = tab.title ?? record.title;+ }+ if (label) {+ for (const other of this.targets.values())+ if (other !== record && other.label === label) delete other.label;+ record.label = label;+ }+ return record;+ }++ private resolveTarget(id: string | undefined): TargetRecord | null {+ if (!id) return null;+ const direct = this.targets.get(id);+ if (direct) return direct;+ for (const record of this.targets.values()) {+ if (record.alias === id || record.label === id) return record;+ }+ const prefixed = [...this.targets.values()].filter((record) => record.targetId.startsWith(id));+ return prefixed.length === 1 ? prefixed[0] : null;+ }++ private describe(record: TargetRecord): Record<string, unknown> {+ return {+ targetId: record.targetId,+ suggestedTargetId: record.label ?? record.alias,+ tabId: record.alias,+ ...(record.label ? { label: record.label } : {}),+ url: record.url,+ ...(record.title !== undefined ? { title: record.title } : {}),+ browser: record.clientId,+ };+ }++ /** 扩展按精确 URL 寻址:作业前先核对标签页仍在原 URL,不在就刷新映射并如实报告。 */+ private async locate(+ action: BackendRequest['action'],+ control: UserBrowserPageControl,+ id: string | undefined,+ ): Promise<{ ok: true; record: TargetRecord } | { ok: false; result: BackendResult }> {+ const record = this.resolveTarget(id);+ if (!record) {+ return {+ ok: false,+ result: actionFailed(+ action,+ id+ ? `未知 targetId ${id};先用 tabs 或 open 取得标签页`+ : 'targetId required(用 tabs 列出或 open 打开后再操作)',+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ ),+ };+ }+ const listed = await control.bridge.act('tabs', { browser: record.clientId, limit: 100 });+ if (listed.ok && Array.isArray(listed.tabs)) {+ const current = (+ listed.tabs as Array<{ id?: unknown; url?: unknown; title?: unknown; redacted?: boolean }>+ ).find((t) => t.id === record.tabId);+ if (!current) {+ this.targets.delete(record.targetId);+ return {+ ok: false,+ result: actionFailed(+ action,+ `标签页 ${record.targetId} 已关闭;用 tabs 重新选择`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ ),+ };+ }+ if (current.redacted) {+ return {+ ok: false,+ result: actionFailed(+ action,+ `标签页 ${record.targetId} 当前页面不允许读取(站点策略或本机地址)`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ ),+ };+ }+ if (typeof current.url === 'string' && current.url !== record.url) {+ const previous = record.url;+ record.url = current.url;+ record.title = typeof current.title === 'string' ? current.title : record.title;+ return {+ ok: false,+ result: {+ ...actionFailed(+ action,+ `PAGE_CHANGED:标签页已从 ${previous} 跳转到 ${current.url};先 snapshot 再继续,不要沿用旧 ref`,+ 'BROWSER_RUNTIME_ACTION_FAILED',+ ),+ data: { error: 'PAGE_CHANGED', ...this.describe(record) },+ },+ };+ }+ }+ return { ok: true, record };+ }++ // ── 各 action ───────────────────────────────────────────────────────────++ private async handleStatus(req: BackendRequest, doctor = false): Promise<BackendResult> {+ const control = this.opts.getPageControl();+ if (!control) {+ return actionOk(req.action, {+ ready: false,+ backend: this.kind,+ running: false,+ configured: false,+ message: NOT_CONFIGURED_MESSAGE,+ capabilities: USER_BROWSER_CAPABILITIES,+ });+ }+ const status = await control.bridge.status();+ if (!status.ok) {+ return actionOk(req.action, {+ ready: false,+ backend: this.kind,+ running: false,+ configured: true,+ plugin: control.ghostId,+ error: status.error,+ message: status.message,+ capabilities: USER_BROWSER_CAPABILITIES,+ });+ }+ const clients = status.clients+ .filter((c) => c.connected)+ .map((c) => ({+ id: c.id,+ browser: c.browser,+ version: c.version,+ protocolVersion: c.protocolVersion,+ }));+ return actionOk(req.action, {+ ready: clients.length > 0,+ running: clients.length > 0,+ backend: this.kind,+ configured: true,+ plugin: control.ghostId,+ pluginName: control.pluginName,+ connected: clients.length > 0,+ clients,+ ...(clients.length === 0 ? { message: DISCONNECTED_MESSAGE } : {}),+ capabilities: USER_BROWSER_CAPABILITIES,+ ...(doctor+ ? {+ port: status.port,+ extensionIds: status.extension_ids,+ pending: status.pending,+ targets: this.targets.size,+ }+ : {}),+ });+ }++ private async handleStart(req: BackendRequest): Promise<BackendResult> {+ if (req.proxyServer !== undefined || req.proxyAllowedHostnames !== undefined) {+ return actionFailed(+ req.action,+ '用户浏览器执行端不支持指定代理;需要代理时改用 Cindy 专用浏览器',+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+ }+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const clients = this.connectedClients(gate.control);+ if (clients.length === 0)+ return actionFailed(req.action, DISCONNECTED_MESSAGE, 'BROWSER_RUNTIME_UNAVAILABLE');+ return actionOk(req.action, { ready: true, backend: this.kind, connected: true });+ }++ private handleProfiles(req: BackendRequest): BackendResult {+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const profiles = this.connectedClients(gate.control).map((c) => ({+ id: c.id,+ name: c.id,+ browser: c.browser,+ version: c.version,+ connected: c.connected,+ }));+ return actionOk(req.action, {+ backend: this.kind,+ profiles,+ note: 'profile 是浏览器连接 id;同一浏览器的多个用户配置各是一条连接。它不携带按站点的登录信号。',+ });+ }++ private async handleTabs(req: BackendRequest): Promise<BackendResult> {+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const clients = this.connectedClients(gate.control).filter(+ (c) => !req.profile || c.id === req.profile || c.id.startsWith(req.profile),+ );+ if (clients.length === 0)+ return actionFailed(req.action, DISCONNECTED_MESSAGE, 'BROWSER_RUNTIME_UNAVAILABLE');+ const tabs: Array<Record<string, unknown>> = [];+ const seen = new Set<string>();+ for (const client of clients) {+ const listed = await gate.control.bridge.act('tabs', {+ browser: client.id,+ limit: Math.min(100, Math.max(1, req.limit ?? 50)),+ });+ if (!listed.ok) return this.failureResult(req.action, listed);+ for (const tab of (Array.isArray(listed.tabs) ? listed.tabs : []) as Array<+ Record<string, unknown>+ >) {+ if (typeof tab.id !== 'number') continue;+ if (tab.redacted || typeof tab.url !== 'string') {+ tabs.push({+ targetId: this.targetKey(client.id, tab.id),+ redacted: true,+ browser: client.id,+ ...(tab.status ? { status: tab.status } : {}),+ ...(tab.error ? { error: tab.error } : {}),+ });+ continue;+ }+ const record = this.register(client.id, {+ id: tab.id,+ url: tab.url,+ title: typeof tab.title === 'string' ? tab.title : undefined,+ });+ seen.add(record.targetId);+ tabs.push({+ ...this.describe(record),+ active: tab.active === true,+ ...(tab.status ? { status: tab.status } : {}),+ });+ }+ }+ // 已关闭的标签页从映射里清掉,别名不复用。+ for (const [targetId, record] of this.targets) {+ if (clients.some((c) => c.id === record.clientId) && !seen.has(targetId))+ this.targets.delete(targetId);+ }+ return actionOk(req.action, {+ backend: this.kind,+ tabs,+ note: '这些是用户浏览器里当前打开的标签页;只在需要时操作,不要关闭或重排它们。',+ });+ }++ /** open / navigate:扩展按 URL 复用或新开后台标签页并等待加载;结果映射为 targetId。 */+ private async handleOpen(req: BackendRequest): Promise<BackendResult> {+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const url =+ typeof req.url === 'string'+ ? req.url+ : typeof req.targetUrl === 'string'+ ? req.targetUrl+ : undefined;+ if (!url) return actionFailed(req.action, 'url required', 'BROWSER_RUNTIME_INVALID_REQUEST');+ const existing = req.action === 'navigate' ? this.resolveTarget(req.targetId) : null;+ const picked = this.pickClient(req.action, gate.control, req.profile ?? existing?.clientId);+ if (!picked.ok) return picked.result;+ const navigated = await gate.control.bridge.act('navigate', { url, browser: picked.clientId });+ if (!navigated.ok) return this.failureResult(req.action, navigated);+ const actualUrl = typeof navigated.url === 'string' ? navigated.url : url;+ const listed = await gate.control.bridge.act('tabs', { browser: picked.clientId, limit: 100 });+ const tab =+ listed.ok && Array.isArray(listed.tabs)+ ? (+ listed.tabs as Array<{+ id?: unknown;+ url?: unknown;+ title?: unknown;+ redacted?: boolean;+ }>+ ).find(+ (t) =>+ !t.redacted && typeof t.id === 'number' && (t.url === actualUrl || t.url === url),+ )+ : undefined;+ if (!tab || typeof tab.id !== 'number' || typeof tab.url !== 'string') {+ return {+ ...actionOk(req.action, {+ backend: this.kind,+ url: actualUrl,+ note: '页面已打开,但未能在标签页列表里定位到它;用 tabs 重新选择 targetId。',+ }),+ };+ }+ const record = this.register(+ picked.clientId,+ { id: tab.id, url: tab.url, title: typeof tab.title === 'string' ? tab.title : undefined },+ typeof req.label === 'string' ? req.label : undefined,+ );+ return actionOk(req.action, {+ backend: this.kind,+ ...this.describe(record),+ ...(existing && existing.targetId !== record.targetId+ ? {+ replacedTargetId: existing.targetId,+ note: '扩展按 URL 寻址:导航落在一个(新的或复用的)标签页上,后续请用返回的 targetId。',+ }+ : {}),+ });+ }++ private async handleSnapshot(req: BackendRequest): Promise<BackendResult> {+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const located = await this.locate(req.action, gate.control, req.targetId);+ if (!located.ok) return located.result;+ if (req.frame) return unsupported(req.action, '按 frame 快照');+ const maxChars = Math.min(30000, Math.max(256, req.maxChars ?? 6000));+ const job = await gate.control.bridge.act('snapshot', {+ url: located.record.url,+ browser: located.record.clientId,+ maxChars,+ ...(typeof req.selector === 'string' ? { selector: req.selector } : {}),+ });+ if (!job.ok) return this.failureResult(req.action, job);+ const record = located.record;+ if (typeof job.url === 'string') record.url = job.url;+ if (typeof job.title === 'string') record.title = job.title;+ const refs: Record<string, { role: string; name?: string }> = {};+ const elementLines: string[] = [];+ for (const line of String(job.elements ?? '').split('\n')) {+ const match = /^\[([a-f0-9]{32})\] (\S+) ?(.*)$/.exec(line);+ if (!match) continue;+ const [, ref, role, name] = match;+ refs[ref] = { role, ...(name ? { name } : {}) };+ elementLines.push(`- ${role}${name ? ` "${name}"` : ''} [ref=${ref}]`);+ }+ const text = typeof job.text === 'string' ? job.text : '';+ const lines = [+ ...(record.title ? [`# ${record.title}`] : []),+ ...(text ? text.split('\n') : []),+ ...(elementLines.length ? ['', '## interactive', ...elementLines] : []),+ ];+ const snapshot = lines.join('\n');+ return actionOk(req.action, {+ format: 'ai',+ backend: this.kind,+ targetId: record.targetId,+ url: record.url,+ ...(record.title ? { title: record.title } : {}),+ snapshot,+ refs,+ stats: {+ lines: lines.length,+ chars: snapshot.length,+ refs: Object.keys(refs).length,+ interactive: Object.keys(refs).length,+ },+ truncated: job.truncated === true,+ untrusted_content: true,+ });+ }++ private async handleAct(req: BackendRequest): Promise<BackendResult> {+ const request = req.request;+ if (!request)+ return actionFailed(req.action, 'act requires request', 'BROWSER_RUNTIME_INVALID_REQUEST');+ const gate = this.control(req.action);+ if (!gate.ok) return gate.result;+ const targetId = request.targetId ?? req.targetId;+ if (+ request.kind === 'wait' &&+ typeof request.timeMs === 'number' &&+ !request.selector &&+ !request.loadState &&+ !request.url &&+ !request.textGone &&+ !request.fn+ ) {+ await sleep(Math.min(30000, Math.max(0, request.timeMs)));+ return actionOk(req.action, {+ backend: this.kind,+ kind: 'wait',+ waitedMs: Math.min(30000, Math.max(0, request.timeMs)),+ });+ }+ const located = await this.locate(req.action, gate.control, targetId);+ if (!located.ok) return located.result;+ const record = located.record;+ const bridge = gate.control.bridge;+ const base = { url: record.url, browser: record.clientId };+ switch (request.kind) {+ case 'click':+ case 'hover':+ case 'press':+ case 'select':+ case 'type':+ case 'fill': {+ if (+ request.kind === 'click' &&+ (request.doubleClick ||+ request.button ||+ request.modifiers?.length ||+ request.x !== undefined)+ ) {+ return unsupported(req.action, '双击、右键、修饰键或坐标点击');+ }+ if (request.query) return unsupported(req.action, '语义元素查询(query)');+ if (+ (request.kind === 'type' || request.kind === 'fill') &&+ typeof request.text !== 'string'+ ) {+ return actionFailed(+ req.action,+ 'type/fill requires text',+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+ }+ const kind = request.kind === 'fill' ? 'type' : request.kind;+ const job = await bridge.act(kind, {+ ...base,+ ...(request.ref ? { ref: request.ref } : {}),+ ...(request.selector ? { selector: request.selector } : {}),+ ...(typeof request.text === 'string' ? { text: request.text } : {}),+ ...(request.submit ? { submit: true } : {}),+ ...(request.key ? { key: request.key } : {}),+ ...(request.values ? { values: request.values } : {}),+ });+ if (!job.ok) return this.failureResult(req.action, job);+ if (typeof job.url === 'string') record.url = job.url;+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ kind: request.kind,+ execution: job.execution ?? 'executed',+ url: record.url,+ note: job.note,+ });+ }+ case 'wait':+ return this.handleWait(req, record, bridge);+ case 'evaluate':+ return this.handleDomRead(req, record, bridge);+ case 'clickCoords':+ case 'drag':+ case 'resize':+ case 'saveResource':+ case 'close':+ return unsupported(req.action, `act:${request.kind}`);+ default:+ return actionFailed(+ req.action,+ `unsupported act kind ${String(request.kind)}`,+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+ }+ }++ private async handleWait(+ req: BackendRequest,+ record: TargetRecord,+ bridge: BrowserExtensionBridge,+ ): Promise<BackendResult> {+ const request = req.request!;+ if (request.fn || request.textGone) return unsupported(req.action, 'wait.fn / wait.textGone');+ const timeoutMs = Math.min(30000, Math.max(100, request.timeoutMs ?? 15000));+ const started = (this.opts.now ?? Date.now)();+ if (request.selector) {+ const job = await bridge.act('text', {+ url: record.url,+ browser: record.clientId,+ selector: request.selector,+ waitFor: request.selector,+ waitMs: Math.min(15000, timeoutMs),+ maxChars: 256,+ });+ if (!job.ok) return this.failureResult(req.action, job);+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ kind: 'wait',+ selector: request.selector,+ waitedMs: (this.opts.now ?? Date.now)() - started,+ });+ }+ if (request.loadState) {+ const job = await bridge.act('navigate', { url: record.url, browser: record.clientId });+ if (!job.ok) return this.failureResult(req.action, job);+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ kind: 'wait',+ loadState: request.loadState,+ url: job.url ?? record.url,+ });+ }+ if (request.url) {+ const deadline = started + timeoutMs;+ for (;;) {+ const listed = await bridge.act('tabs', { browser: record.clientId, limit: 100 });+ const current =+ listed.ok && Array.isArray(listed.tabs)+ ? (listed.tabs as Array<{ id?: unknown; url?: unknown }>).find(+ (t) => t.id === record.tabId,+ )+ : undefined;+ if (typeof current?.url === 'string' && current.url.includes(request.url)) {+ record.url = current.url;+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ kind: 'wait',+ url: current.url,+ });+ }+ if ((this.opts.now ?? Date.now)() >= deadline)+ return actionFailed(+ req.action,+ `等待 ${timeoutMs}ms 后标签页仍未到达包含 ${request.url} 的地址`,+ );+ await sleep(250);+ }+ }+ if (typeof request.timeMs === 'number') {+ await sleep(Math.min(30000, Math.max(0, request.timeMs)));+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ kind: 'wait',+ waitedMs: request.timeMs,+ });+ }+ return actionFailed(+ req.action,+ 'wait requires selector、loadState、url 或 timeMs',+ 'BROWSER_RUNTIME_INVALID_REQUEST',+ );+ }++ /** evaluate 只接受声明式读取(extract / login-wall);任意 fn 不进用户浏览器。 */+ private async handleDomRead(+ req: BackendRequest,+ record: TargetRecord,+ bridge: BrowserExtensionBridge,+ ): Promise<BackendResult> {+ const domRead = (+ req.request as { domRead?: { kind?: string; extract?: Record<string, unknown> } }+ ).domRead;+ if (!domRead) return unsupported(req.action, '任意页面脚本(evaluate.fn)');+ if (domRead.kind === 'login-wall') {+ // The extension refuses to read password / one-time-code fields at all (they are sensitive+ // fields), so a declarative probe cannot tell "absent" from "present but withheld". Report+ // the check as unavailable instead of a false negative; the snapshot text still shows the+ // sign-in page to the agent, and the user's own browser normally carries their sign-ins.+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ result: { password: false, code: false, unavailable: true },+ note: '用户浏览器执行端不读取密码/验证码字段,无法做登录墙检测;以快照内容判断是否需要登录。',+ });+ }+ if (domRead.kind !== 'extract' || !domRead.extract)+ return unsupported(req.action, '未知的声明式读取');+ const spec = domRead.extract as {+ from?: string;+ multiple?: boolean;+ limit?: number;+ fields: Record<string, string | { selector?: string; attr?: string; type?: string }>;+ };+ // The MCP contract resolves field selectors against `document` (or the `from`+ // container) and lets a field omit its selector to read the container itself.+ // The extension resolves them against document.body (or the row) and spells the+ // container as ':self'. Translate the document-level spellings so a whole-page+ // read (`body`, `:scope`) is not silently null.+ const mapSelector = (selector: string | undefined): string => {+ const trimmed = selector?.trim();+ if (!trimmed || trimmed === ':scope' || trimmed === ':self') return ':self';+ if (!spec.from && /^(html|body)$/i.test(trimmed)) return ':self';+ return trimmed;+ };+ const fields: Record<string, string | { selector: string; attr?: string }> = {};+ for (const [name, field] of Object.entries(spec.fields)) {+ if (typeof field === 'string') {+ fields[name] = mapSelector(field);+ continue;+ }+ if (field.type === 'html') return unsupported(req.action, 'extract type:"html"');+ const selector = mapSelector(field.selector);+ if (field.type === 'href') fields[name] = { selector, attr: 'href' };+ else if (field.attr) fields[name] = { selector, attr: field.attr };+ else fields[name] = { selector };+ }+ // Single record: `from` is the extension's root (`selector`); it only reads+ // `from` as a row selector in multiple mode.+ const scope = spec.multiple+ ? { multiple: true as const, ...(spec.from ? { from: spec.from } : {}) }+ : spec.from+ ? { selector: spec.from }+ : {};+ const job = await bridge.act('extract', {+ url: record.url,+ browser: record.clientId,+ fields,+ ...scope,+ ...(spec.limit ? { limit: Math.min(100, Math.max(1, spec.limit)) } : {}),+ maxChars: Math.min(30000, Math.max(256, req.maxChars ?? 6000)),+ });+ if (!job.ok) {+ const error = String(job.error ?? '');+ if (error === 'INVALID_ARGS') {+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ result: {+ ok: false,+ error: String(job.message ?? 'invalid extract spec'),+ count: 0,+ records: [],+ },+ });+ }+ return this.failureResult(req.action, job);+ }+ if (typeof job.url === 'string') record.url = job.url;+ const records = spec.multiple+ ? Array.isArray(job.records)+ ? job.records+ : []+ : [job.record ?? {}];+ return actionOk(req.action, {+ backend: this.kind,+ targetId: record.targetId,+ url: record.url,+ result: { ok: true, count: records.length, records },+ ...(job.truncated === true ? { truncated: true } : {}),+ ...(job.cursorFound !== undefined ? { cursorFound: job.cursorFound } : {}),+ untrusted_content: true,+ });+ }+}diff --git a/apps/desktop/src/main/mcp-integrations/browser.ts b/apps/desktop/src/main/mcp-integrations/browser.tsindex 9091ea1ddb..b527ff7ef7 100644--- a/apps/desktop/src/main/mcp-integrations/browser.ts+++ b/apps/desktop/src/main/mcp-integrations/browser.ts@@ -22,6 +22,11 @@ import type { BrowserMcpDeps } from '@cindy/mcps';import { createLogger } from '../logger.js';import { genericOAuthSecretIo } from '../secrets/providerSecretStore.js';import { createRecipeFileBroker } from './browser-backend/rsb-webview-upload-policy.js';+import {+ USER_BROWSER_CAPABILITIES,+ UserBrowserBackend,+ type UserBrowserPageControl,+} from './browser-backend/user-browser-backend.js';import { artifactSessionRoot } from './browser-backend/rsb-webview-artifacts.js';import { extractBrowserAvailability, type BrowserAvailability } from './browser-availability.js';import { loadUserBrowserRecipes, userRecipesDir, type UserRecipesResult } from '../browser-recipes/loader.js';@@ -29,6 +34,7 @@ import { writeUserRecipe, type WriteUserRecipeResult } from '../browser-recipes/import { browserExperienceStore } from '../browser-recipes/experience.js';import {BrowserBackendController,+ resolveBackendProfile,BrowserBackendHealthService,ExternalChromeBackend,RsbWebviewBackend,@@ -322,10 +328,26 @@ const initialKind = readBrowserBackendSettings().kind;* The controller implements `BrowserControlRuntime` (its `.call` matches the* contract verbatim) so @cindy/mcps consumes it as the runtime with no adapter.*/+/**+ * Page-control provider for the user's own browser: the browserExtension plugin+ * slot owns the bridge; bootstrap wires the accessor so this module never+ * imports cindy-brain. Default = no page-control plugin installed.+ */+let userBrowserPageControlProvider: () => UserBrowserPageControl | null = () => null;++export function setUserBrowserPageControlProvider(provider: () => UserBrowserPageControl | null): void {+ userBrowserPageControlProvider = provider;+}++function createUserBrowserBackend(): UserBrowserBackend {+ return new UserBrowserBackend({ getPageControl: () => userBrowserPageControlProvider(), logger });+}+const backendController = new BrowserBackendController({initialKind,externalBackend,createRsbBackend,+ createUserBrowserBackend,persistKind: writeBrowserBackendKind,logger,});@@ -474,6 +496,7 @@ export function getBrowserMcpDeps(): {setBackend(kind: BackendKind): Promise<BackendKind>;supportsResourceDownloads(): boolean;supportsSemanticQueries(): boolean;+ backendCapabilities: NonNullable<BrowserMcpDeps['backendCapabilities']>;logger: typeof logger;getUserRecipes(): Promise<UserRecipesResult>;saveUserRecipe(input: Parameters<typeof writeUserRecipe>[0]): Promise<WriteUserRecipeResult>;@@ -511,8 +534,8 @@ export function getBrowserMcpDeps(): {// the backend split. Swapping the active backend (Phase 5) is invisible from// @cindy/mcps' perspective.getRuntime: () => backendController,- resolveProfile: (profile) => backendController.kind === 'rsb-webview'- ? 'rsb' : profile || activeManagedProfileName(readBrowserBackendSettings().useRealProfile),+ resolveProfile: (profile) => resolveBackendProfile(backendController.kind, profile, () =>+ activeManagedProfileName(readBrowserBackendSettings().useRealProfile)),getBackendScope: () => backendController.getBackendScope(),resolveScreenshot: (result) =>resolveBrowserScreenshot(result, {@@ -521,6 +544,10 @@ export function getBrowserMcpDeps(): {compressInlineImage,supportsResourceDownloads: () => backendController.kind === 'rsb-webview',supportsSemanticQueries: () => backendController.kind === 'rsb-webview',+ // The user's browser is driven by a fixed-function extension: no scripts,+ // screenshots, network reads, uploads or dialogs. The MCP layer refuses+ // those before dispatch instead of letting a page job fail opaquely.+ backendCapabilities: () => (backendController.kind === 'user-browser' ? USER_BROWSER_CAPABILITIES : {}),// 代输入: pause page-state reads on a tab still showing a page where the owner typed a secret.pageReadsRestricted: async ({ profile, targetId }) => {if (!hasSecretPages()) return false;diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.tsindex 8c54d1521f..8dbef45fcb 100644--- a/apps/desktop/src/preload/preload.ts+++ b/apps/desktop/src/preload/preload.ts@@ -6307,13 +6307,13 @@ contextBridge.exposeInMainWorld('electronAPI', {browserBackend: {/** Read current active kind + system default + override flag. */getState: (): Promise<{- active: 'external' | 'rsb-webview';- systemDefault: 'external' | 'rsb-webview';+ active: 'external' | 'rsb-webview' | 'user-browser';+ systemDefault: 'external' | 'rsb-webview' | 'user-browser';isOverride: boolean;useRealProfile: boolean;}> => ipcRenderer.invoke('browser-backend:get-state'),/** Swap the active backend AND persist as user override. */- setKind: (kind: 'external' | 'rsb-webview'): Promise<unknown> =>+ setKind: (kind: 'external' | 'rsb-webview' | 'user-browser'): Promise<unknown> =>ipcRenderer.invoke('browser-backend:set-kind', { kind }),/** Clear user override → follow current system default. */reset: (): Promise<unknown> => ipcRenderer.invoke('browser-backend:reset'),diff --git a/apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx b/apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsxindex 70598c0b85..47d4381267 100644--- a/apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx+++ b/apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx@@ -20,7 +20,7 @@ import type {BrowserBackendHealthReason,} from '../../../shared/browserBackend';-type BackendKind = 'external' | 'rsb-webview';+type BackendKind = 'external' | 'rsb-webview' | 'user-browser';interface BrowserBackendSubsectionProps {active: BackendKind;@@ -41,6 +41,8 @@ function healthReasonKey(reason: BrowserBackendHealthReason | undefined): stringreturn 'settings.computerUse.browserBackend.health.reasons.startFailed';case 'recovery-failed':return 'settings.computerUse.browserBackend.health.reasons.recoveryFailed';+ case 'extension-disconnected':+ return 'settings.computerUse.browserBackend.health.reasons.extensionDisconnected';case 'status-failed':default:return 'settings.computerUse.browserBackend.health.reasons.statusFailed';@@ -58,6 +60,9 @@ export function BrowserBackendSubsection({const { t } = useTranslation();const embeddedHealth =active === 'rsb-webview' && health?.active === 'rsb-webview' ? health : null;+ // 「我的浏览器」只有连接状态可报,没有可恢复的宿主侧控制连接。+ const userBrowserHealth =+ active === 'user-browser' && health?.active === 'user-browser' ? health : null;return (<div className="border-t border-[var(--settings-theme-card-border)]"><div className="cindy-segmented-row px-4 py-[14px]">@@ -80,6 +85,10 @@ export function BrowserBackendSubsection({label: t('settings.computerUse.browserBackend.rsbWebview.title'),},{ value: 'external', label: t('settings.computerUse.browserBackend.external.title') },+ {+ value: 'user-browser',+ label: t('settings.computerUse.browserBackend.userBrowser.title'),+ },]}/></div>@@ -121,6 +130,30 @@ export function BrowserBackendSubsection({</Button></div>) : null}+ {userBrowserHealth ? (+ <div+ className={cn(+ 'flex items-start gap-2 border-t border-[var(--settings-theme-card-border)] px-4 py-[14px] text-12 leading-[1.5]',+ userBrowserHealth.status === 'error'+ ? 'text-[var(--error-fg)]'+ : 'text-[var(--settings-section-desc)]',+ )}+ role={userBrowserHealth.status === 'error' ? 'alert' : 'status'}+ >+ {userBrowserHealth.status === 'error' ? (+ <AlertTriangle size={14} className="mt-0.5 shrink-0" />+ ) : (+ <CheckCircle2 size={14} className="mt-0.5 shrink-0" />+ )}+ <span>+ {userBrowserHealth.status === 'error'+ ? t('settings.computerUse.browserBackend.health.userBrowserError', {+ reason: t(healthReasonKey(userBrowserHealth.reason)),+ })+ : t('settings.computerUse.browserBackend.health.userBrowserReady')}+ </span>+ </div>+ ) : null}</div>);}diff --git a/apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx b/apps/desktop/src/renderer/components/settings/ComputerUseSection.tsxindex c564008b8a..30673054f8 100644--- a/apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx+++ b/apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx@@ -95,7 +95,9 @@ const ACTION_BUTTON_CLASS = cn();const ANDROID_AUTO_DEVICE_VALUE = '__auto__';-function browserBackendHealthFallback(active: 'external' | 'rsb-webview'): BrowserBackendHealth {+function browserBackendHealthFallback(+ active: 'external' | 'rsb-webview' | 'user-browser',+): BrowserBackendHealth {return {active,status: 'error',@@ -430,7 +432,7 @@ export function ComputerUseSection({ workingDir }: ComputerUseSectionProps) {const { value: backendConfig, setValue: setBackendConfig } = backendRead;const browserBackendKind = backendConfig?.active ?? null;const setBrowserBackendKind = useCallback(- (active: 'external' | 'rsb-webview' | null) => {+ (active: 'external' | 'rsb-webview' | 'user-browser' | null) => {setBackendConfig((current) => (current && active ? { ...current, active } : current));},[setBackendConfig],@@ -583,7 +585,7 @@ export function ComputerUseSection({ workingDir }: ComputerUseSectionProps) {// Phase 5: 用户点 segmented chip 切换 backend。乐观更新 + IPC 失败回滚。const handleSelectBackend = useCallback(- async (kind: 'external' | 'rsb-webview') => {+ async (kind: 'external' | 'rsb-webview' | 'user-browser') => {if (browserBackendPending) return;if (browserBackendKind === kind) return;const prev = browserBackendKind;diff --git a/apps/desktop/src/renderer/components/settings/__tests__/ComputerUseSection.browserHealth.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/ComputerUseSection.browserHealth.test.tsxindex 68042842b3..337b445bcc 100644--- a/apps/desktop/src/renderer/components/settings/__tests__/ComputerUseSection.browserHealth.test.tsx+++ b/apps/desktop/src/renderer/components/settings/__tests__/ComputerUseSection.browserHealth.test.tsx@@ -78,7 +78,7 @@ beforeEach(() => {});api.getAndroidStatus.mockResolvedValue(androidUnavailable);api.getBackendState.mockResolvedValue({ active: 'rsb-webview' });- api.setBackendKind.mockImplementation(async (kind: 'external' | 'rsb-webview') => ({+ api.setBackendKind.mockImplementation(async (kind: 'external' | 'rsb-webview' | 'user-browser') => ({active: kind,}));api.recoverBackend.mockResolvedValue({diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.tsindex a19c3db9aa..cf745588c0 100644--- a/apps/desktop/src/renderer/vite-env.d.ts+++ b/apps/desktop/src/renderer/vite-env.d.ts@@ -5506,16 +5506,16 @@ interface ElectronAPI {*/browserBackend: {getState: () => Promise<{- active: 'external' | 'rsb-webview';- systemDefault: 'external' | 'rsb-webview';+ active: 'external' | 'rsb-webview' | 'user-browser';+ systemDefault: 'external' | 'rsb-webview' | 'user-browser';isOverride: boolean;useRealProfile: boolean;}>;- setKind: (kind: 'external' | 'rsb-webview') => Promise<{+ setKind: (kind: 'external' | 'rsb-webview' | 'user-browser') => Promise<{ok: true;- active: 'external' | 'rsb-webview';+ active: 'external' | 'rsb-webview' | 'user-browser';}>;- reset: () => Promise<{ ok: true; active: 'external' | 'rsb-webview' }>;+ reset: () => Promise<{ ok: true; active: 'external' | 'rsb-webview' | 'user-browser' }>;getHealth: () => Promise<BrowserBackendHealth>;recover: () => Promise<BrowserBackendRecoveryResult>;setUseRealProfile: (enabled: boolean) => Promise<{ ok: true; enabled: boolean }>;diff --git a/apps/desktop/src/shared/browserBackend.ts b/apps/desktop/src/shared/browserBackend.tsindex c8d3d5aa72..0e734e6d3e 100644--- a/apps/desktop/src/shared/browserBackend.ts+++ b/apps/desktop/src/shared/browserBackend.ts@@ -1,4 +1,4 @@-export type BrowserBackendKind = 'external' | 'rsb-webview';+export type BrowserBackendKind = 'external' | 'rsb-webview' | 'user-browser';/** Optional profile stores; warning payloads never carry paths or native errors. */export const OPTIONAL_BROWSER_PROFILE_DATABASES = [@@ -76,7 +76,13 @@ export function browserOpenForLoginErrorCodeFromData(}export type BrowserBackendHealthReason =- 'disposing' | 'host-unavailable' | 'start-failed' | 'status-failed' | 'recovery-failed';+ | 'disposing'+ | 'host-unavailable'+ | 'start-failed'+ | 'status-failed'+ | 'recovery-failed'+ /** user-browser:没有已启用的页面控制扩展插件,或扩展尚未连接。 */+ | 'extension-disconnected';export interface BrowserBackendHealth {active: BrowserBackendKind;diff --git a/packages/browser-control-runtime/upstream/MAINTAINING.md b/packages/browser-control-runtime/upstream/MAINTAINING.mdindex 51200a63ff..2cdde6b485 100644--- a/packages/browser-control-runtime/upstream/MAINTAINING.md+++ b/packages/browser-control-runtime/upstream/MAINTAINING.md@@ -138,6 +138,8 @@ host 在 `browser-managed-config.ts` 用 `buildManagedConfig({proxyServer?})`## 5. UI 开关模型(设置 →「自动操作」)+设置里的「浏览器自动化目标」三选一(专用浏览器 / 侧边栏 / 我的浏览器)写 `browser-backend-settings.json` 的 `kind`,是全局默认目标;「我的浏览器」依赖声明 `browserExtension.pageControl` 的插件(见 §9「用户浏览器执行端」)。+浏览器是个 builtin plugin(id `browser`),走 `plugin-registry.ts` 的三层判定:essential → 项目级 override → 内置默认。**内置默认是开**,所以浏览器在所有项目里默认可用;设置里的开关写的是"当前项目的 override"。无项目上下文时开关变灰(`workingDir` 来自最近本地会话的内存单例,见 `renderer/state/lastWorkingDir.ts`)。> ⚠️ **已知限制 — 项目级开关只对 Claude Code 生效,本地 Codex 不生效:** Claude Code 每个会话用真实 `workingDir` 重新求一次 `provider.isEnabled(ctx)`,所以"在 A 项目关掉浏览器"对它有效。本地 Codex 不行——`codexEnvironment.ts` 在**首次 codex spawn** 时就用 `workingDir: ''` 的全局空 ctx 求值一次 `provider.isEnabled(ctx)`(见 `doStart` 里 `serverFactories` 那段),空 `workingDir` 命中不到任何项目级 override、回落到"内置默认开"那一档,并且**冻结**、之后不再 per-session 重判。`ctx.getSessionContext` 虽然在 tool-call 时能拿到真实 `workingDir`,但 gate 不消费它。所以本地 Codex 永远把浏览器当"开",项目级关闭被无视。**TODO:** 在 codex tool-call 时按真实 `workingDir` 重新 gate(而非进程级一次性求值),才能让本地 Codex 也尊重项目级开关。修这块属于敏感的 codex bridge,改前先确认。@@ -224,6 +226,15 @@ pnpm --filter @cindy/browser-control-runtime test # 契约 + SSRF guard- 内置配方仍走现有随应用分发的 L1 目录,个人 L2 覆盖保留;不自动上传个人经验。`itch-search` 是公开网页人工验证后加入的通用例子。- 实现:L2 `experience.ts` / `result-cache.ts` / `tools.ts`,Desktop `browser-recipes/experience.ts`;回归使用真实 MCP 入口与既有 writer 测试。模型用量须与工具文本计量分开,不能把执行器没有新增模型调用说成整个任务零 token。+### 用户浏览器执行端(2026-10-27)++- 第三个 `BackendKind` `user-browser`:`apps/desktop/src/main/mcp-integrations/browser-backend/user-browser-backend.ts` 把 `BrowserControlRequest` 翻译成随包浏览器扩展的页面作业,经 `cindy-brain/browserExtensionSlot.ts` 持有的桥接(`main/browser-extension/bridge.ts`,从 Cindy Chrome 插件的接线进程原样迁入,线协议 `cindy-browser-extension/3` 不变,已装扩展无需更新)投递到用户正在使用的 Chrome / Edge。+- 设置 →「自动操作」三选一:专用浏览器(默认)/ 侧边栏 / 我的浏览器;选哪一个是**默认**目标,Agent 的 `setBackend` 仍是同一个全局持久选择。没有声明 `browserExtension.pageControl` 的插件时该目标 `status.ready === false`,健康面板报 `extension-disconnected`,不提供恢复按钮。+- 能力边界由扩展决定(隔离世界固定函数,无 debugger):只支持 tabs / open / navigate / snapshot / extract / act(click / type / fill / press / hover / select / wait);`deps.backendCapabilities()` 让 MCP 层在派发前拒绝 screenshot / evaluate / requests / upload / dialog / console / pdf / focus / close / 坐标与拖拽,以及需要 guard / evaluate / 适配器 / 网络读取的配方,错误文案要求模型告知用户而不是自行切换。extract 与登录墙检测走 PR #7432 的声明式 `domRead`,不需要任意脚本。+- 寻址:扩展当前按精确 URL 寻址,后端维护 targetId ↔ {连接, tabId, url};作业前用 `tabs` 核对,URL 变化报 `PAGE_CHANGED` 并刷新记录,不猜新页。扩展侧加 tabId / documentId 寻址后这里只需改 `locate`。+- 站点策略归插件:读默认开放公网、交互按站点授权、本机与私网拒绝;宿主缓存在 `ownerScopedUserDataPath('browser-extension')`,每个作业经桥接强制。`cindy_browser` 的免审批前提在该目标下由这套策略补上。+- 回归:`browser-extension/__tests__/bridge.test.ts`(协议)、`cindy-brain/__tests__/browserExtensionSlot.test.ts`(槽)、`browser-backend/__tests__/user-browser-backend.test.ts`(翻译)、`lizi-mcps` 的 capability gating 用例;真实 Chrome 验收用 Google Play 发包案例与插件翻译。+## 10. 相关文档- `README.md` — runtime 包速览 + 安全说明(本目录上一级)。diff --git a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts b/packages/lizi-mcps/src/browser/browserMcpServer.test.tsindex 72d348dffb..7b483bea2a 100644--- a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts+++ b/packages/lizi-mcps/src/browser/browserMcpServer.test.ts@@ -490,7 +490,7 @@ describe('createBrowserMcpServer', () => {});it('switches modes in the same MCP instance and immediately updates backend capabilities', async () => {- let backend: 'external' | 'rsb-webview' = 'external';+ let backend: 'external' | 'rsb-webview' | 'user-browser' = 'external';const switched: string[] = [];const h = await makeHarness({setBackend: async (next) => { switched.push(next); backend = next; return backend; },@@ -1720,3 +1720,60 @@ describe('recipe on-use maintenance', () => {} finally { await next.cleanup(); }});});++describe('browser · backend capability gating (user browser via extension)', () => {+ const caps = () => ({ evaluate: false, screenshot: false, network: false, upload: false, dialog: false, console: false, pdf: false, focus: false, close: false, trustedInput: false });++ it.each([+ { action: 'screenshot', targetId: 't1' },+ { action: 'requests', targetId: 't1' },+ { action: 'upload', targetId: 't1', paths: ['/tmp/x'] },+ { action: 'dialog', targetId: 't1', dialogId: 'd', accept: true },+ { action: 'focus', targetId: 't1' },+ { action: 'act', targetId: 't1', request: { kind: 'evaluate', fn: '() => 1' } },+ { action: 'act', targetId: 't1', request: { kind: 'drag', startRef: 'a', endRef: 'b' } },+ ])('refuses unsupported work before dispatch and points the agent to the user: %j', async (args) => {+ const h = await makeHarness({ backendCapabilities: caps });+ try {+ const result = await h.client.callTool({ name: 'call_tool', arguments: { name: 'browser', args } });+ expect(result.isError).toBe(true);+ expect((result.content as Array<{ text: string }>)[0].text).toContain('不要自行切换');+ expect(h.calls).toEqual([]);+ } finally { await h.cleanup(); }+ });++ it('still routes extract through the declarative DOM read and leaves other backends unaffected', async () => {+ const h = await makeHarness({ backendCapabilities: caps });+ try {+ await h.client.callTool({ name: 'call_tool', arguments: { name: 'browser', args: { action: 'extract', targetId: 't1', extract: { fields: { title: 'h1' } } } } });+ expect(h.calls).toHaveLength(1);+ expect(h.calls[0]).toMatchObject({ action: 'act', request: { kind: 'evaluate', domRead: { kind: 'extract' } } });+ } finally { await h.cleanup(); }+ const open = await makeHarness({ backendCapabilities: () => ({}) });+ try {+ await open.client.callTool({ name: 'call_tool', arguments: { name: 'browser', args: { action: 'screenshot', targetId: 't1' } } });+ expect(open.calls).toHaveLength(1);+ } finally { await open.cleanup(); }+ });++ it('refuses recipes that need guards, scripts or network capture on a backend without them', async () => {+ const recipe: Recipe = {+ id: 'guarded', match: ['example.test'], inputs: {},+ steps: [+ { action: 'navigate', url: 'https://example.test/' },+ { action: 'extract', as: 'rows', guard: { url: 'https://example.test/' }, expect: { minCount: 1 }, extract: { fields: { title: 'h1' } } },+ ],+ output: '{{rows}}',+ } as unknown as Recipe;+ const h = await makeHarness({+ backendCapabilities: caps,+ getUserRecipes: async () => ({ recipes: new Map([[recipe.id, recipe]]), siteGuides: new Map(), version: 'v1' }),+ });+ try {+ const result = await h.client.callTool({ name: 'call_tool', arguments: { name: 'browser', args: { action: 'recipe', recipeId: 'guarded' } } });+ expect(result.isError).toBe(true);+ expect((result.content as Array<{ text: string }>)[0].text).toContain('页面脚本能力');+ expect(h.calls).toEqual([]);+ } finally { await h.cleanup(); }+ });+});diff --git a/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md b/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.mdindex 3e4bf704cd..ebac14a914 100644--- a/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md+++ b/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md@@ -76,20 +76,23 @@大结果返回结构摘要和 `fullResult`,不是完整事实;用 `readResult(resultId,offset,maxChars)` 补读(`nextOffset:null` 表示结束),不猜省略内容或 ref。原文只留当前工具会话最近四份、每份最多 200 万字符;更大结果沿用明确截断,需缩小读取范围。`advisory` 是代码发现的可疑输出,不自动认定业务错误。-#### 两种浏览器模式(先认环境,再谈登录)+#### 三种浏览器目标(先认环境,再谈登录)-宿主用两种后端之一承接本工具,**顶层 action 集合一致**(两边都支持 snapshot / act 各 kind / requests / upload / dialog 等),差别在两处:少数参数级能力只有侧边栏模式有,以及"页面呈现在哪里"。判别依据是 `action: "status"` 返回结果里的 **`data.backend`**(工具结果的外层是 `{ ok, action, status, data }`,`status` 是数字状态码——**别去读 `status.backend`**,那是 undefined):+宿主用三种后端之一承接本工具。专用浏览器与侧边栏**顶层 action 集合一致**(都支持 snapshot / act 各 kind / requests / upload / dialog 等),差别在少数参数级能力与"页面呈现在哪里";用户浏览器(user-browser)只支持页面读取与基本交互,`status.data.capabilities` 列出不支持项。判别依据是 `action: "status"` 返回结果里的 **`data.backend`**(工具结果的外层是 `{ ok, action, status, data }`,`status` 是数字状态码——**别去读 `status.backend`**,那是 undefined):- **`data.backend === "rsb-webview"` = Cindy 侧边栏内置浏览器**:页面活在 Cindy 的会话侧边栏里,不是一个常规浏览器窗口。侧边栏本身可能内嵌在主窗口、也可能被用户开成独立子窗口,`status` **不区分**这两种承载方式——所以请用户看页面时说"Cindy 的侧边栏(若你把侧边栏开成了独立窗口,就是那个窗口)",不要断言窗口存在或不存在。系统默认的自动化后端是独立外置浏览器,不是侧边栏。- 仅此模式支持:`act:saveResource`(托管下载)、以及 `query` 语义元素查询(role / name / text / label / placeholder / testId / css)。在外置模式下用这两个会被 schema 或运行时门控直接拒掉,别当通用能力使。- **`data.backend === "external"` = 独立外置浏览器**:一个专属持久自动化浏览器窗口(profile 显示为 "Cindy")。`act:saveResource` 与语义 `query` 在此模式不可用,元素定位改用 snapshot 的 `ref` 或 `selector`。旧宿主可能省略该字段,不要把缺少模式信息当成已使用内置浏览器。- 此模式的 `status.data.proxy` 报告当前启动路由:`direct`、`proxied`(带脱敏 `server`)或无法确认继承进程路由时的 `unknown`。需要指定代理时必须重新调用 `start` 并检查结果,不要从已有 tab 猜测出口。代理模式下只有 `proxyAllowedHostnames` 列出的公网域名可导航,内网地址不在其中。+- **`data.backend === "user-browser"` = 用户正在使用的浏览器(经 Cindy 扩展)**:页面活在用户自己的 Chrome / Edge 里,带着用户本人的登录态;Cindy 不启停它,也不要关闭或重排用户的标签页。执行端是扩展里的固定函数,**只支持** tabs / open / navigate / snapshot / extract / act(click / type / fill / press / hover / select / wait)。不支持:截图、`evaluate`、`requests` / `responseBody`、上传、原生弹窗、`focus` / `close`、坐标点击与拖拽、需要 guard / evaluate / 适配器的配方。遇到不支持的操作先告诉用户,由用户决定是否改用专用浏览器,**不要自行 setBackend 切换**。+ - 站点策略归 Cindy Chrome 插件:读取默认开放公网,交互按站点授权(作业报 `INTERACT_NOT_ALLOWED` 时用该插件的 `browser_policy` 工具请求授权,需用户确认),本机与私网地址一律拒绝。`profile` 是浏览器连接 id(一个浏览器用户配置一条),多条连接时必须指定,不要猜账号。+ - 扩展按 URL 寻址:页面在两次调用之间跳转会报 `PAGE_CHANGED`,先 `tabs` / `snapshot` 再继续,不沿用旧 ref;`navigate` 可能落在另一个标签页并返回新的 targetId。`status.data.connected === false` 时请用户在自己的浏览器里安装并启用 Cindy 扩展,不要反复重试。`setBackend` 与设置页修改同一个**全局、持久**选择,会影响其他正在使用浏览器的任务,旧模式的操作可能中断。仅按用户明确的模式要求切换,无需重复确认;不要因页面报错自行换模式。切换后重新 `tabs` / `snapshot`,不沿用旧模式的 targetId、ref 或登录态。宿主不支持切换或返回失败时如实说明,不能声称切换成功。-两种模式均允许访问本机网络可达的内网 HTTP(S) 地址。遇到失败按实际连接、DNS、证书或登录错误诊断,不要仅因私有 IP 推断“禁止内网访问”,也不要让用户把内网服务暴露到公网。+专用浏览器与侧边栏允许访问本机网络可达的内网 HTTP(S) 地址;用户浏览器(user-browser)不允许本机与私网地址。遇到失败按实际连接、DNS、证书或登录错误诊断,不要仅因私有 IP 推断“禁止内网访问”,也不要让用户把内网服务暴露到公网。-**两种模式彼此隔离**。侧边栏始终是独立身份。外置浏览器默认也是独立的 `Cindy` profile;仅当用户在设置里打开「使用我的浏览器登录态」且 `status.data.realProfile.applied === true` 时,外置窗口才带着系统 Chrome / Edge / Brave 的登录拷贝(可撤销,Agent 以用户身份访问)。**不要传 `profile`**,不要试图 attach 用户日常使用的 Chrome。+**三种目标彼此隔离**。侧边栏始终是独立身份。外置浏览器默认也是独立的 `Cindy` profile;仅当用户在设置里打开「使用我的浏览器登录态」且 `status.data.realProfile.applied === true` 时,外置窗口才带着系统 Chrome / Edge / Brave 的登录拷贝(可撤销,Agent 以用户身份访问)。专用浏览器与侧边栏**不要传 `profile`**,也不要自行 attach 用户日常使用的 Chrome;要操作用户正在用的浏览器,只能走用户在设置里选的「我的浏览器」(user-browser)目标。#### 登录与登录墙- 操作需要登录态的站点前,导航后先 `action: "snapshot"`(必要时配 `screenshot` 视觉确认)判断是否已登录。**不要**用 `profiles` 判断登录态——它不携带按站点的登录信号。diff --git a/packages/lizi-mcps/src/browser/tools.ts b/packages/lizi-mcps/src/browser/tools.tsindex cd26a31502..eff9d1c9f7 100644--- a/packages/lizi-mcps/src/browser/tools.ts+++ b/packages/lizi-mcps/src/browser/tools.ts@@ -473,6 +473,44 @@ async function screenshotToolResult(};}+/**+ * Refuse what the active backend cannot do before dispatch. The user's own+ * browser is driven by a fixed-function extension (no scripts, screenshots,+ * network reads, uploads, dialogs or trusted input); the hint tells the model+ * to involve the user rather than switch targets on its own.+ */+const BACKEND_SWITCH_HINT = '当前浏览器后端不支持此操作。需要时请明确告知用户并建议改用 Cindy 专用浏览器(setBackend external),不要自行切换。';+function unsupportedByBackend(args: Record<string, unknown>, deps: BrowserMcpDeps): string | undefined {+ const caps = deps.backendCapabilities?.();+ if (!caps) return undefined;+ const action = args.action as string;+ const kind = (args.request as { kind?: string } | undefined)?.kind;+ const deny = (what: string) => `${what}:${BACKEND_SWITCH_HINT}`;+ if (action === 'screenshot' && caps.screenshot === false) return deny('截图');+ if (action === 'pdf' && caps.pdf === false) return deny('导出 PDF');+ if (action === 'console' && caps.console === false) return deny('读取控制台');+ if (action === 'upload' && caps.upload === false) return deny('上传文件');+ if (action === 'dialog' && caps.dialog === false) return deny('处理原生弹窗');+ if ((action === 'requests' || action === 'responseBody') && caps.network === false) return deny('读取网络请求');+ if (action === 'focus' && caps.focus === false) return deny('切换活动标签页');+ if (action === 'close' && caps.close === false) return deny('关闭标签页');+ if (action === 'act' && kind === 'evaluate' && caps.evaluate === false) return deny('任意页面脚本(evaluate)');+ if (action === 'act' && caps.trustedInput === false && (kind === 'clickCoords' || kind === 'drag' || kind === 'resize')) return deny(`act:${kind}`);+ return undefined;+}++/** Recipes that need scripting (guard / evaluate / wait.fn / adapters) or network capture the backend lacks. */+function recipeUnsupportedByBackend(recipe: Recipe, deps: BrowserMcpDeps): string | undefined {+ const caps = deps.backendCapabilities?.();+ if (!caps) return undefined;+ const steps = recipe.steps as Array<{ action: string; guard?: unknown; fn?: unknown }>;+ const needsScript = (recipe as { adapter?: unknown }).adapter !== undefined+ || steps.some((step) => step.action === 'evaluate' || step.guard !== undefined || (step.action === 'wait' && typeof step.fn === 'string'));+ if (needsScript && caps.evaluate === false) return `配方需要页面脚本能力(guard / evaluate / 适配器):${BACKEND_SWITCH_HINT}`;+ if (steps.some((step) => step.action === 'requests' || step.action === 'responseBody') && caps.network === false) return `配方需要读取网络请求:${BACKEND_SWITCH_HINT}`;+ return undefined;+}+// Forwards validated MCP args straight to the runtime. `extract` (MCP-only// sugar) is rewritten in the handler before this is reached, so every `action`// arriving here is a real BrowserControlAction.@@ -552,7 +590,7 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: BrowseresultId: z.string().optional().describe('readResult: 大结果返回的 fullResult.id'),offset: z.number().int().nonnegative().optional().describe('readResult: 原始 JSON 字符偏移'),backend: z- .enum(['external', 'rsb-webview'])+ .enum(['external', 'rsb-webview', 'user-browser']).optional().describe('仅 action=setBackend: 切换全局自动化目标并保存设置; 会影响其他任务,两种模式的登录态与标签页不互通'),proxyServer: z.string().optional().describe(@@ -691,7 +729,7 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse// lifecycle transition as Settings before issuing any new page actions.if (args.action === 'setBackend') {if (!args.backend) {- return errorResult(args.action, 'setBackend requires backend: external or rsb-webview');+ return errorResult(args.action, 'setBackend requires backend: external、rsb-webview 或 user-browser');}if (!deps.setBackend) return errorResult(args.action, '当前宿主不支持切换浏览器模式');const backend = await deps.setBackend(args.backend);@@ -715,6 +753,8 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browseif (args.backend !== undefined) {return errorResult(args.action, 'backend 仅用于 setBackend; 请先切换模式,再操作页面');}+ const unsupported = unsupportedByBackend(args, deps);+ if (unsupported) return errorResult(args.action, unsupported);if (args.proxyServer !== undefined || args.proxyAllowedHostnames !== undefined) {if (args.action !== 'start') {return errorResult(@@ -799,6 +839,8 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browseentry = (await recipeRegistry(deps)).get(args.recipeId);}if (!entry) return errorResult('recipe', `unknown recipe: ${args.recipeId}`);+ const recipeUnsupported = recipeUnsupportedByBackend(entry.recipe, deps);+ if (recipeUnsupported) return errorResult('recipe', recipeUnsupported);if (entry.recipe.validation?.state === 'candidate') {const { validation, ...draft } = entry.recipe;const issue = draftIssue(draft, validation.site) ?? deferredRecipeIssue(draft);diff --git a/packages/lizi-mcps/src/types.ts b/packages/lizi-mcps/src/types.tsindex facbc7baa4..da44724fb9 100644--- a/packages/lizi-mcps/src/types.ts+++ b/packages/lizi-mcps/src/types.ts@@ -647,6 +647,23 @@ export interface ResolvedBrowserScreenshot {mimeType: 'image/png' | 'image/jpeg';}+/** Host-wide automation targets: managed Chrome, sidebar webview, or the user's own browser via extension. */+export type BrowserBackendKind = 'external' | 'rsb-webview' | 'user-browser';++/** Per-backend capability flags consulted before dispatch; keys mirror the host's status payload. */+export interface BrowserBackendCapabilities {+ evaluate?: boolean;+ screenshot?: boolean;+ network?: boolean;+ upload?: boolean;+ dialog?: boolean;+ console?: boolean;+ pdf?: boolean;+ focus?: boolean;+ close?: boolean;+ trustedInput?: boolean;+}+/** Browser automation MCP host deps. Core browser execution is injected by host. */export interface BrowserMcpDeps {/** Local structural observations only; no URLs, scripts, selectors or input values. */@@ -667,7 +684,12 @@ export interface BrowserMcpDeps {/** Shrink the LLM-facing copy to the shared stream-safe byte budget. */compressInlineImage?: CompressInlineImageFn;/** Switch the host-wide, persisted automation target; returns the actual mode. */- setBackend?(backend: 'external' | 'rsb-webview'): Promise<'external' | 'rsb-webview'>;+ setBackend?(backend: BrowserBackendKind): Promise<BrowserBackendKind>;+ /**+ * Capability flags of the active backend (false = the action/kind must be+ * refused before dispatch with a clear hint). Absent → everything allowed.+ */+ backendCapabilities?(): BrowserBackendCapabilities;/** Whether the active backend accepts managed resource downloads. */supportsResourceDownloads?(): boolean;/** Whether the active backend accepts semantic element queries. */