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。

browser: "My browser" uses Chrome's debugger on demand for PDF and recipe adapters

Dash9245a49502db
diff --git a/apps/desktop/src/main/browser-extension/policy.ts b/apps/desktop/src/main/browser-extension/policy.ts
index 0c09fd4a8e..3f30e6c6ea 100644
--- a/apps/desktop/src/main/browser-extension/policy.ts
+++ b/apps/desktop/src/main/browser-extension/policy.ts
@@ -24,6 +24,8 @@ export const BROWSER_EXTENSION_READ_ACTIONS = [
'requests',
'responseBody',
'wait',
+ 'pdf',
+ 'debuggerAccess',
] as const;
export const BROWSER_EXTENSION_INTERACT_ACTIONS = [
'click',
@@ -40,7 +42,10 @@ export const BROWSER_EXTENSION_INTERACT_ACTIONS = [
'drag',
'dialog',
'resize',
+ 'cdp',
] as const;
+/** Actions that address no page: listing tabs, and checking or granting the on-demand debugger. */
+const UNADDRESSED_ACTIONS: readonly unknown[] = ['tabs', 'debuggerAccess'];
export const BROWSER_EXTENSION_EXTRACT_ATTRIBUTES = [
'href',
'src',
@@ -210,7 +215,7 @@ export function checkBrowserExtensionPolicy(
if (!isBrowserExtensionReadAction(action) && !isBrowserExtensionInteractAction(action)) {
return deny('INVALID_ACTION', 'Choose a supported browser action.');
}
- if (action === 'tabs') return { ok: true };
+ if (UNADDRESSED_ACTIONS.includes(action)) return { ok: true };
let u: URL;
try {
u = new URL(String(url));
@@ -268,7 +273,7 @@ export interface BrowserExtensionJobPayload {
const TAB_ADDRESSED_ACTIONS = [
'focus', 'close', 'screenshot', 'console', 'requests', 'responseBody',
- 'evaluate', 'clickCoords', 'drag', 'dialog', 'resize', 'wait',
+ 'evaluate', 'clickCoords', 'drag', 'dialog', 'resize', 'wait', 'pdf', 'cdp',
];
/** 与扩展侧同判据:对齐专用浏览器后新增动作的参数。 */
@@ -322,6 +327,17 @@ function validateParityPayload(action: string, payload: BrowserExtensionJobPaylo
if (files.reduce((n, f) => n + (f.data as string).length, 0) > 40_000_000)
throw new Error('Upload files must total at most about 30 MB.');
}
+ if (action === 'cdp') {
+ if (!['begin', 'end', 'events', 'command'].includes(payload.op as string))
+ throw new Error('cdp op must be begin, end, events or command.');
+ if (payload.op === 'command' && (typeof payload.method !== 'string' || !/^[A-Za-z]+\.[A-Za-z]+$/.test(payload.method)))
+ throw new Error('cdp command needs a protocol method such as Network.getCookies.');
+ if (
+ payload.params != null &&
+ (typeof payload.params !== 'object' || Array.isArray(payload.params) || JSON.stringify(payload.params).length > 1_000_000)
+ )
+ throw new Error('cdp params must be an object of at most 1 MB.');
+ }
for (const key of ['timeMs', 'timeoutMs'] as const)
if (payload[key] != null && !finite(payload[key], 0, 120000)) throw new Error(key + ' must be 0–120000.');
if (payload.loadState != null && !['load', 'domcontentloaded', 'networkidle'].includes(payload.loadState as string))
@@ -341,7 +357,7 @@ export function validateBrowserExtensionJob(
const payload = (
input && typeof input === 'object' && !Array.isArray(input) ? input : {}
) as BrowserExtensionJobPayload;
- if (action !== 'tabs' && (typeof payload.url !== 'string' || payload.url.length > 8192)) {
+ if (!UNADDRESSED_ACTIONS.includes(action) && (typeof payload.url !== 'string' || payload.url.length > 8192)) {
throw new Error('Provide a full URL of at most 8192 characters.');
}
if (
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
index 890525057b..f007d336fb 100644
--- 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
@@ -463,20 +463,20 @@ describe('UserBrowserBackend · 读取与动作', () => {
).toEqual([]);
});
- it('能力表按扩展版本给出:0.4.42 起完整,旧版只有基础能力', () => {
- expect(extensionSupportsParity('0.4.42')).toBe(true);
+ it('能力表按扩展版本给出:0.4.43 起完整,旧版只有基础能力', () => {
+ expect(extensionSupportsParity('0.4.43')).toBe(true);
expect(extensionSupportsParity('0.5.0')).toBe(true);
- expect(extensionSupportsParity('0.4.41')).toBe(false);
+ expect(extensionSupportsParity('0.4.42')).toBe(false);
expect(extensionSupportsParity(null)).toBe(false);
expect(userBrowserCapabilities(fakeControl().control)).toBe(USER_BROWSER_CAPABILITIES);
- expect(userBrowserCapabilities(fakeControl({ version: '0.4.42' }).control)).toBe(
+ expect(userBrowserCapabilities(fakeControl({ version: '0.4.43' }).control)).toBe(
USER_BROWSER_PARITY_CAPABILITIES,
);
expect(userBrowserCapabilities(null)).toBe(USER_BROWSER_CAPABILITIES);
});
it('新版扩展:open 开到后台窗口并按 tabId 寻址,不再逐次列标签页', async () => {
- const fake = fakeControl({ version: '0.4.42' });
+ const fake = fakeControl({ version: '0.4.43' });
fake.responses.set('open', (payload) => ({
ok: true,
tabId: 42,
@@ -505,13 +505,14 @@ describe('UserBrowserBackend · 读取与动作', () => {
});
it('新版扩展:截图、控制台、网络、弹窗、切换与关闭映射成标签页作业', async () => {
- const fake = fakeControl({ version: '0.4.42' });
+ const fake = fakeControl({ version: '0.4.43' });
fake.responses.set('screenshot', () => ({
ok: true,
tabId: 7,
mimeType: 'image/png',
data: 'iVBORw0KGgo=',
bytes: 8,
+ note: 'Only the visible area was captured.',
}));
fake.responses.set('console', () => ({ ok: true, messages: [{ level: 'log', text: 'x' }] }));
fake.responses.set('requests', () => ({ ok: true, requests: [{ url: 'https://example.test/api' }] }));
@@ -521,9 +522,9 @@ describe('UserBrowserBackend · 读取与动作', () => {
const base = { url: 'https://example.test/a', browser: 'client-aaaaaaaa', tabId: 7 };
expect(await call(b, { action: 'screenshot', targetId: 't1', fullPage: true })).toMatchObject({
ok: true,
- data: { mimeType: 'image/png', data: 'iVBORw0KGgo=', note: expect.stringContaining('可视区域') },
+ data: { mimeType: 'image/png', data: 'iVBORw0KGgo=', note: expect.stringContaining('visible area') },
});
- expect(fake.jobs.at(-1)).toEqual(['screenshot', { ...base, type: 'png' }]);
+ expect(fake.jobs.at(-1)).toEqual(['screenshot', { ...base, type: 'png', fullPage: true }]);
expect(await call(b, { action: 'console', targetId: 't1' })).toMatchObject({
data: { messages: [{ level: 'log', text: 'x' }] },
});
@@ -549,7 +550,7 @@ describe('UserBrowserBackend · 读取与动作', () => {
});
it('新版扩展:脚本、坐标、拖拽、调整大小、双击与等待都交给扩展', async () => {
- const fake = fakeControl({ version: '0.4.42' });
+ const fake = fakeControl({ version: '0.4.43' });
let polls = 0;
fake.responses.set('evaluate', (payload) =>
payload.fn === '() => ready'
@@ -600,7 +601,7 @@ describe('UserBrowserBackend · 读取与动作', () => {
try {
const file = pathMod.join(root, 'a.png');
await fsp.writeFile(file, Buffer.from([1, 2, 3]));
- const fake = fakeControl({ version: '0.4.42' });
+ const fake = fakeControl({ version: '0.4.43' });
fake.responses.set('upload', () => ({ ok: true, files: [{ name: 'a.png', size: 3 }] }));
const b = backend(fake.control, async () => [root]);
await call(b, { action: 'tabs' });
@@ -630,4 +631,72 @@ describe('UserBrowserBackend · 读取与动作', () => {
await fsp.rm(root, { recursive: true, force: true });
}
});
+
+ it('按需调试:PDF 交给扩展;未授权时告诉模型请用户在已打开的说明页里确认', async () => {
+ const fake = fakeControl({ version: '0.4.43' });
+ let granted = false;
+ fake.responses.set('pdf', () =>
+ granted
+ ? { ok: true, mimeType: 'application/pdf', data: 'JVBERg==', bytes: 4 }
+ : { ok: false, error: 'DEBUGGER_NOT_ALLOWED', message: 'needs debugger', grantPageOpened: true },
+ );
+ const b = backend(fake.control);
+ await call(b, { action: 'tabs' });
+ expect(await call(b, { action: 'pdf', targetId: 't1' })).toMatchObject({
+ ok: false,
+ message: expect.stringContaining('已在用户的 Chrome 里打开说明页'),
+ });
+ expect(fake.jobs.at(-1)).toEqual([
+ 'pdf',
+ { url: 'https://example.test/a', browser: 'client-aaaaaaaa', tabId: 7 },
+ ]);
+ granted = true;
+ expect(await call(b, { action: 'pdf', targetId: 't1' })).toMatchObject({
+ ok: true,
+ data: { mimeType: 'application/pdf', data: 'JVBERg==' },
+ });
+ });
+
+ it('配方协议会话:按需接上调试,事件随结果回传,结束即断开', async () => {
+ const fake = fakeControl({ version: '0.4.43' });
+ fake.responses.set('cdp', (payload) => {
+ if (payload.op === 'command' && payload.method === 'Network.getCookies')
+ return { ok: true, result: { cookies: [{ name: 'sid' }] }, events: [] };
+ if (payload.op === 'command')
+ return {
+ ok: true,
+ result: {},
+ events: [
+ ['Network.requestWillBeSent', { requestId: 'r1', request: { url: 'https://example.test/api', method: 'GET' } }],
+ ['Network.responseReceived', { requestId: 'r1', response: { status: 200, headers: {} } }],
+ ],
+ };
+ if (payload.op === 'events')
+ return { ok: true, events: [['Network.loadingFailed', { requestId: 'r1' }]] };
+ return { ok: true };
+ });
+ const b = backend(fake.control);
+ await call(b, { action: 'tabs' });
+ const scope = { targetId: 't1', __mcpSessionId: 's1' };
+ const begun = await call(b, { action: 'recipeCommand', ...scope, recipeCommand: { method: 'Cindy.begin' } });
+ const sessionId = (begun.data as { sessionId: string }).sessionId;
+ expect(fake.jobs.at(-1)).toEqual([
+ 'cdp',
+ { url: 'https://example.test/a', browser: 'client-aaaaaaaa', tabId: 7, op: 'begin' },
+ ]);
+ await call(b, { action: 'recipeCommand', ...scope, recipeCommand: { method: 'Cindy.captureStart', sessionId, params: { pattern: '/api' } } });
+ expect(
+ await call(b, { action: 'recipeCommand', ...scope, recipeCommand: { method: 'Network.getCookies', sessionId, params: {} } }),
+ ).toMatchObject({ ok: true, data: { cookies: [{ name: 'sid' }] } });
+ const read = await call(b, { action: 'recipeCommand', ...scope, recipeCommand: { method: 'Cindy.captureRead', sessionId } });
+ expect(read).toMatchObject({
+ ok: true,
+ data: { entries: [{ url: 'https://example.test/api', responseStatus: 200, captureComplete: true }] },
+ });
+ await call(b, { action: 'recipeCommand', ...scope, recipeCommand: { method: 'Cindy.end', sessionId } });
+ expect(fake.jobs.at(-1)).toEqual([
+ 'cdp',
+ { url: 'https://example.test/a', browser: 'client-aaaaaaaa', tabId: 7, op: 'end' },
+ ]);
+ });
});
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
index a5a68fb13a..a6d85f7314 100644
--- 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
@@ -7,8 +7,10 @@
* - 用哪个浏览器是用户的选择,所以能力与专用浏览器对齐(扩展 0.4.42 起):截图、
* 上传、页面脚本、控制台、网络、弹窗、坐标与拖拽都可用。底线是不打扰用户自己的
* 使用:新页面开在 Cindy 自己的后台窗口,不抢焦点,不切换用户正在看的标签页;
- * - 只有 debugger 才能做的(导出 PDF、可信输入、原始协议命令)仍明确拒绝并指向专用
- * 浏览器,绝不悄悄换目标;旧版扩展只有基础读取与交互,同样明确拒绝并提示更新;
+ * - 只有 debugger 才能做的(导出 PDF、整页/元素/后台标签截图、配方适配器的原始协议命令)
+ * 按需使用:用户在扩展里授权一次后,扩展只在这些动作期间临时接上调试(Chrome 会显示
+ * 提示条),做完即断开;未授权时明确告诉模型请用户开启,绝不悄悄换目标。旧版扩展只有
+ * 基础读取与交互,同样明确拒绝并提示更新;
* - 每个作业都经桥接按插件保存的站点策略守门,结果脱敏后才回到这里。
*
* 寻址:这里维护 targetId ↔ {连接, tabId, url} 的映射。新版扩展按 tabId 寻址;
@@ -17,6 +19,7 @@
import fs from 'node:fs/promises';
import path from 'node:path';
+import { RecipeBrowserSessions } from '@cindy/browser-control-runtime';
import { buildDomReadSource } from '@cindy/browser-control-runtime/dom-read';
import type {
BrowserExtensionBridge,
@@ -73,8 +76,8 @@ export const USER_BROWSER_CAPABILITIES = Object.freeze({
rawProtocol: false,
});
-/** 扩展从这个版本起与专用浏览器对齐;只有需要 debugger 的 pdf 与可信输入仍不提供。 */
-export const USER_BROWSER_PARITY_VERSION = '0.4.42';
+/** 扩展从这个版本起与专用浏览器对齐;pdf 与原始协议按需借用 debugger(需用户授权一次)。 */
+export const USER_BROWSER_PARITY_VERSION = '0.4.43';
export const USER_BROWSER_PARITY_CAPABILITIES = Object.freeze({
evaluate: true,
screenshot: true,
@@ -82,12 +85,12 @@ export const USER_BROWSER_PARITY_CAPABILITIES = Object.freeze({
upload: true,
dialog: true,
console: true,
- pdf: false,
+ pdf: true,
focus: true,
close: true,
trustedInput: false,
pointer: true,
- rawProtocol: false,
+ rawProtocol: true,
});
export function extensionSupportsParity(version: string | null | undefined): boolean {
@@ -168,6 +171,7 @@ const TAB_ACTION_LABEL: Partial<Record<BackendRequest['action'], string>> = {
responseBody: '读取网络响应',
dialog: '处理原生弹窗',
upload: '上传文件',
+ pdf: '导出 PDF',
};
const NOT_CONFIGURED_MESSAGE =
@@ -180,6 +184,9 @@ 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 readonly recipeSessions = new RecipeBrowserSessions();
+ /** 配方会话 id → 取回扩展缓存的网络事件(事件随每条命令回传,读取抓包前再取一次)。 */
+ private readonly recipePumps = new Map<string, () => Promise<void>>();
private nextAlias = 1;
private disposed = false;
@@ -205,6 +212,7 @@ export class UserBrowserBackend implements BrowserBackend {
async dispose(): Promise<void> {
this.disposed = true;
+ this.recipeSessions.dispose();
this.targets.clear();
}
@@ -242,13 +250,12 @@ export class UserBrowserBackend implements BrowserBackend {
case 'requests':
case 'responseBody':
case 'dialog':
+ case 'pdf':
return this.handleTabAction(req);
case 'upload':
return this.handleUpload(req);
- case 'pdf':
- return unsupported(req.action, '导出 PDF(需要浏览器调试权限)');
case 'recipeCommand':
- return unsupported(req.action, '原始协议命令(OpenCLI 适配器)');
+ return this.handleRecipeCommand(req);
default:
return actionFailed(
req.action,
@@ -355,7 +362,14 @@ export class UserBrowserBackend implements BrowserBackend {
error === 'EXTENSION_DISCONNECTED' || error === 'BRIDGE_PORTS_BUSY'
? 'BROWSER_RUNTIME_UNAVAILABLE'
: 'BROWSER_RUNTIME_ACTION_FAILED',
- message: `${error}:${message}`,
+ message:
+ error === 'DEBUGGER_NOT_ALLOWED'
+ ? `${error}:这一步需要 Chrome 的调试功能,用户还没有允许。${
+ job.grantPageOpened === true
+ ? '扩展已在用户的 Chrome 里打开说明页'
+ : '说明页刚才已经打开过'
+ },请告诉用户在那里点「开启」(Chrome 会请用户确认一次;使用时 Chrome 顶部会短暂显示调试提示),确认后再重试。用户拒绝就不要重试,也不要自行改用其他浏览器。`
+ : `${error}:${message}`,
data: {
error,
...(typeof execution === 'string' ? { execution } : {}),
@@ -987,12 +1001,14 @@ export class UserBrowserBackend implements BrowserBackend {
if (!this.parity(gate.control, record.clientId))
return outdated(req.action, TAB_ACTION_LABEL[req.action] ?? req.action);
let extra: Record<string, unknown> = {};
- let note: string | undefined;
switch (req.action) {
case 'screenshot':
- extra = { type: req.type === 'jpeg' ? 'jpeg' : 'png' };
- if (req.fullPage || req.ref || req.element)
- note = '用户浏览器只能截取可视区域:这是当前视口的截图;需要页面其他部分时先滚动再截。';
+ // 整页、元素与用户窗口里的后台标签由扩展按需借用调试完成;未授权时扩展退回可视区域并说明。
+ extra = {
+ type: req.type === 'jpeg' ? 'jpeg' : 'png',
+ ...(req.fullPage ? { fullPage: true } : {}),
+ ...(req.ref ? { ref: req.ref } : {}),
+ };
break;
case 'requests':
extra = {
@@ -1028,12 +1044,13 @@ export class UserBrowserBackend implements BrowserBackend {
note: '只在标签页所在窗口内切到前台,不抢窗口焦点。',
});
case 'screenshot':
+ case 'pdf':
return actionOk(req.action, {
...base,
mimeType: job.mimeType,
data: job.data,
bytes: job.bytes,
- ...(note ? { note } : {}),
+ ...(job.note ? { note: job.note } : {}),
});
case 'console':
return actionOk(req.action, {
@@ -1062,6 +1079,78 @@ export class UserBrowserBackend implements BrowserBackend {
}
}
+ /**
+ * 配方适配器的原始协议命令:扩展按需接上调试(需用户授权一次),会话结束或闲置即断开。
+ * 网络事件缓存在扩展里,随每条命令的结果回传;读取抓包前再主动取一次。
+ */
+ private async handleRecipeCommand(req: BackendRequest): Promise<BackendResult> {
+ const command = req.recipeCommand;
+ if (!command || !req.targetId)
+ return actionFailed(
+ req.action,
+ 'recipeCommand requires an explicit targetId and command',
+ 'BROWSER_RUNTIME_INVALID_REQUEST',
+ );
+ 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;
+ const record = located.record;
+ const control = gate.control;
+ if (!this.parity(control, record.clientId)) return outdated(req.action, '配方适配器的浏览器协议命令');
+ const sessionKey = (req as { __mcpSessionId?: unknown }).__mcpSessionId;
+ const scope = JSON.stringify([
+ typeof sessionKey === 'string' ? sessionKey : '',
+ req.profile ?? '',
+ record.targetId,
+ ]);
+ if (command.method !== 'Cindy.begin') {
+ if (command.method === 'Cindy.captureRead')
+ await this.recipePumps.get(command.sessionId ?? '')?.();
+ return actionOk(
+ req.action,
+ await this.recipeSessions.call(scope, command.sessionId ?? '', command.method, command.params),
+ );
+ }
+ const begun = await this.pageJob(control, record, 'cdp', { op: 'begin' });
+ if (!begun.ok) return this.failureResult(req.action, begun);
+ const listeners = new Set<(method: string, params: Record<string, unknown>) => void>();
+ const closers = new Set<() => void>();
+ const deliver = (job: BrowserExtensionJobResult) => {
+ const events = Array.isArray(job.events) ? (job.events as Array<[string, Record<string, unknown>]>) : [];
+ for (const [method, params] of events) for (const listener of listeners) listener(method, params);
+ if (!job.ok && (job.error === 'DEBUGGER_DETACHED' || job.error === 'TAB_CLOSED'))
+ for (const close of [...closers]) close();
+ };
+ let sessionId = '';
+ sessionId = this.recipeSessions.begin(scope, {
+ send: async (method, params) => {
+ const job = await this.pageJob(control, record, 'cdp', {
+ op: 'command',
+ method,
+ params: params ?? {},
+ });
+ deliver(job);
+ if (!job.ok) throw new Error(`${String(job.error)}:${String(job.message ?? '')}`);
+ return job.result;
+ },
+ subscribe: (listener) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+ },
+ onClose: (listener) => {
+ closers.add(listener);
+ return () => closers.delete(listener);
+ },
+ dispose: () => {
+ this.recipePumps.delete(sessionId);
+ void this.pageJob(control, record, 'cdp', { op: 'end' }).catch(() => {});
+ },
+ });
+ this.recipePumps.set(sessionId, async () => deliver(await this.pageJob(control, record, 'cdp', { op: 'events' })));
+ return actionOk(req.action, { sessionId });
+ }
+
/** 上传:按会话允许的目录解析本地文件,读成字节交给扩展放进页面的文件输入框。 */
private async handleUpload(req: BackendRequest): Promise<BackendResult> {
const gate = this.control(req.action);
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 e1d709f74c..5d8c99f999 100644
--- a/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md
+++ b/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md
@@ -84,11 +84,11 @@
- 仅此模式支持:`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 不启停它。`open` 的新页面开在 Cindy 自己的后台窗口里,不抢焦点;用户自己的标签页只在任务需要时操作,不要关闭、重排或切换它们。截图、`evaluate`、`requests` / `responseBody`、上传、原生弹窗、`focus` / `close`、坐标点击、拖拽与 `resize` 都可用,但有这些差别:
- - 截图只截可视区域(无 `fullPage` / 元素截图);用户窗口里的后台标签页无法截图,先 `open` 到 Cindy 窗口再截;`resize` 只作用于 Cindy 自己的窗口。
+- **`data.backend === "user-browser"` = 用户正在使用的浏览器(经 Cindy 扩展)**:页面活在用户自己的 Chrome / Edge 里,带着用户本人的登录态;Cindy 不启停它。`open` 的新页面开在 Cindy 自己的后台窗口里,不抢焦点;用户自己的标签页只在任务需要时操作,不要关闭、重排或切换它们。截图、`evaluate`、`requests` / `responseBody`、上传、原生弹窗、`focus` / `close`、坐标点击、拖拽、`resize`、`pdf` 与配方都可用,但有这些差别:
+ - 有些动作借用 Chrome 的调试功能,需要用户允许一次:`pdf`、整页 / 元素截图、截取用户窗口里的后台标签页、读 Cookie 或抓网络请求的配方。`pdf` 与配方第一次需要时报 `DEBUGGER_NOT_ALLOWED`,扩展同时在用户的 Chrome 里打开说明页;请用户在那里点「开启」,确认后再重试,用户拒绝就不要重试。使用期间 Chrome 顶部会短暂显示调试提示。未允许时截图退回可视区域并在 `note` 里说明。`resize` 只作用于 Cindy 自己的窗口。
- 点击、坐标与拖拽是合成事件(非可信输入),个别要求可信输入的站点会忽略;页面 CSP 禁止脚本时 `evaluate` 报 `EVAL_BLOCKED_BY_PAGE`,改用 snapshot / extract。
- 控制台从第一次 `console` 调用开始捕获;`requests` 来自页面资源计时(无方法与请求头);`responseBody` 以页面身份重新请求该地址;`dialog` 预先应答页面下一个 alert / confirm / prompt,已经弹出的原生弹窗需要用户自己处理。
- - 不支持:导出 PDF、需要适配器(原始协议命令)的配方、`saveResource` 与语义 `query`。`status.data.updateNote` 出现时说明扩展是旧版,只有基础读取与交互,请用户更新 Cindy 扩展。遇到不支持的操作先告诉用户,由用户决定是否改用专用浏览器,**不要自行 setBackend 切换**。
+ - 不支持:`saveResource` 与语义 `query`。`status.data.updateNote` 出现时说明扩展是旧版,只有基础读取与交互,请用户更新 Cindy 扩展。遇到不支持的操作先告诉用户,由用户决定是否改用专用浏览器,**不要自行 setBackend 切换**。
- 站点策略归 Cindy Chrome 插件:读取默认开放,交互按站点授权(作业报 `INTERACT_NOT_ALLOWED` 时用该插件的 `browser_policy` 工具请求授权,需用户确认)。`profile` 是浏览器连接 id(一个浏览器用户配置一条),多条连接时必须指定,不要猜账号。
- 页面跳转后旧 ref 失效(报 `STALE_REF`),先 `snapshot` 再继续;旧版扩展按 URL 寻址,跳转会报 `PAGE_CHANGED`,`navigate` 也可能落在另一个标签页并返回新的 targetId。`status.data.connected === false` 时请用户在自己的浏览器里安装并启用 Cindy 扩展,不要反复重试。