Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: BrowserBackendIpcDe
async 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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): string
return '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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.md
index 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.ts
index 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.md
index 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.ts
index 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: Browse
resultId: 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: Browse
if (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: Browse
entry = (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.ts
index 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. */