Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
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.tsindex 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: BrowserExtensionJobPayloif (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.tsindex 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.tsindex 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.mdindex 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 扩展,不要反复重试。