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(plugins): 新增 browserExtension 能力,宿主承接随包浏览器扩展桥接

Dash7a6ab0ebab58
diff --git a/apps/desktop/resources/system-skills/cindy-plugin-creator/SKILL.md b/apps/desktop/resources/system-skills/cindy-plugin-creator/SKILL.md
index d0de4ad0c3..bc9b96d180 100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/SKILL.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/SKILL.md
@@ -65,6 +65,7 @@ Use for the UI surfaces and interactions the plugin actually exposes; mobile pag
- [插件轻提示与未读角标 notify / badge(§4.9)](references/plugin-notifications.md)
- [插件目录选择 pick(§4.14)](references/plugin-directory-picker.md)
- [插件面板预览 preview(§4.15)](references/plugin-panel-preview.md)
+- [插件随包浏览器扩展 browserExtension(§4.23)](references/plugin-browser-extension.md)
- [插件确认弹窗 confirm(§4.18)](references/plugin-confirm-dialog.md)
- [插件推荐任务(§4.21)](references/plugin-recommendations.md)
diff --git a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-browser-extension.md b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-browser-extension.md
new file mode 100644
index 0000000000..a616b11ba6
--- /dev/null
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-browser-extension.md
@@ -0,0 +1,72 @@
+## 4.23 随包浏览器扩展(browserExtension 能力)
+
+插件随包携带一个 Chrome / Edge 扩展(翻译、字幕、页面读取之类"住在用户浏览器里"的功能)时,
+由 **Cindy 承接扩展的连接**:配对、身份绑定、作业分发、站点策略守门、结果脱敏都在宿主,插件
+不再自带接线进程。在身份卡声明:
+
+```json
+"browserExtension": {
+ "protocol": "cindy-browser-extension/3",
+ "extensionIds": ["dmbhhhdijpeaibfeocdcjhfefkgpkeef"],
+ "nativeHost": { "name": "com.example.browser", "binary": "native-host/bin" },
+ "pageControl": true
+}
+```
+
+- `extensionIds` 是全部知情面:只有这些扩展能连上宿主桥接(商店版、Edge 版、开发版各一条),
+ 装入时逐条展示并钉死;新增 id 要发新版本并重新确认权限。
+- `nativeHost` 可选:首次配对用的 Native Messaging host。宿主把 `<binary>/<platform>-<arch>/`
+ 下的二进制复制到本机私有目录并向各浏览器注册;二进制由你随包提供并签名。
+- `pageControl: true` 表示扩展实现**页面控制契约**(tabs / navigate / snapshot / extract / act),
+ 用户在设置 →「自动操作」选「我的浏览器」后,Agent 的 `browser` 工具会经它操作用户正在用的
+ 浏览器。只做翻译/字幕通道的扩展不要声明它。
+
+运行期两条管子:
+
+```js
+// 插件 → 宿主:向扩展投递作业、推送站点策略与配对身份、回传转交结果
+const status = await cindy.send({ type: 'browser-extension-request', kind: 'status' });
+if (!status.ok && status.errorCode) {
+ // 旧宿主不认识这个槽:回落到你自己的接线进程,不要把拒绝当作已连接
+}
+await cindy.send({ type: 'browser-extension-request', kind: 'setPolicy', policy });
+await cindy.send({ type: 'browser-extension-request', kind: 'setTrustedClients', clients: paired });
+const result = await cindy.send({
+ type: 'browser-extension-request',
+ kind: 'act',
+ action: 'extract',
+ payload,
+});
+
+// 宿主 → 插件:扩展发起的请求(翻译、字幕…)转交给你处理
+cindy.onHostMessage(async (msg) => {
+ if (msg.type !== 'event' || msg.name !== 'browser-extension-relay') return;
+ const { id, clientId, request } = msg;
+ await cindy.send({
+ type: 'browser-extension-request',
+ kind: 'relayProgress',
+ id,
+ progress: { stage: 'model' },
+ });
+ const result = await handle(
+ clientId,
+ request,
+ async () =>
+ (await cindy.send({ type: 'browser-extension-request', kind: 'relayActive', id })).active ===
+ true,
+ );
+ await cindy.send({ type: 'browser-extension-request', kind: 'relayResult', id, result });
+});
+```
+
+规则与红线:
+
+- **站点策略归你**:读取默认开放公网、交互按站点授权、本机与私网一律拒绝。你保存并在启动
+ 与每次变更时 `setPolicy` 推给宿主;宿主缓存到用户私有目录并在每个作业上强制,新授权必须经
+ `cindy.confirm` 真实确认。
+- **作业一次送达**:已送达的作业不会重投;结果 `execution` 为 `unknown` 时要让 Agent 核对
+ 页面,不能当成功或未执行报告。
+- **宿主代码不认识你**:桥接只按声明工作,不会为某个插件写特例;需要线协议之外的能力,先提
+ Cindy 改动,不要在扩展里绕过。
+- **向下兼容**:旧宿主没有这个槽,`status` 返回 `errorCode`;插件必须保留自带接线进程的降级
+ 路径(或明确提示升级 Cindy),不能让已装用户的功能消失。
diff --git a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
index ad1c8cf396..d3aacd5cc2 100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
@@ -158,7 +158,7 @@ node secretBindings key、setup kv key——都不能使用 `__proto__`、`const
v3 直接用顶层字段声明插件贡献项与自主 Host 能力,不再有 `slots`。带详单的字段是 `tools`、`cindy`、
`agent`、`panel`、`mainView`、`taskView`、`card`、`subscribe`、`network`、`node`、`preview`、
-`skill`;布尔能力写成字面量 `true`:`notify`、`badge`、`confirm`、`fs`、
+`browserExtension`、`skill`;布尔能力写成字面量 `true`:`notify`、`badge`、`confirm`、`fs`、
`library`、`deviceSync`、`sessionContext`、`pick`、`workspace`。不用的字段直接省略。
`deviceSync` 的声明与调用约定见 [§4.10.2 同账号电脑间的插件资料同步](plugin-files-and-library.md#4102-同账号电脑间的插件资料同步)。
邮件插件声明 `mail: true`,调用 Cindy 内置 `cindyMail.register(adapter)`
diff --git a/apps/desktop/src/main/browser-extension/__tests__/bridge.test.ts b/apps/desktop/src/main/browser-extension/__tests__/bridge.test.ts
new file mode 100644
index 0000000000..6dfb6f2f74
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/__tests__/bridge.test.ts
@@ -0,0 +1,706 @@
+/**
+ * bridge.test — 浏览器扩展桥接的线协议回归(从插件时期的协议测试迁入宿主)。
+ *
+ * 测试价值
+ * - 生产入口与可观察结果:BrowserExtensionBridge 的真实 HTTP 监听 + act/setPolicy/relay*
+ * 方法;扩展看到的 /health、/poll、/ack、/authorize、/result、/learning/* 状态码与载荷。
+ * - Bug/规则依据:插件 my-browser 0.4.x 的桥接合同(一次送达、unknown 不重投、撤销等待
+ * 派发、结果脱敏、官方身份须 native 绑定);桥接迁入宿主后这些合同必须逐条保持。
+ * - 现有覆盖缺口:宿主此前没有这条链路。
+ * - 最小失败输入:见各用例(重复 ack、撤销后的 /authorize、带凭证的 tabs URL 等)。
+ * - tier:unit(真实回环 socket,端口 0,无外部进程);实测耗时约 1 秒。
+ */
+
+import crypto, { webcrypto } from 'node:crypto';
+import http from 'node:http';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { BrowserExtensionBridge, type BrowserExtensionRelayNotice } from '../bridge';
+import {
+ checkBrowserExtensionPolicy,
+ defaultBrowserExtensionPolicy,
+ normalizeBrowserExtensionHost,
+ normalizeBrowserExtensionPolicy,
+ redactBrowserUrl,
+ validateBrowserExtensionJob,
+} from '../policy';
+
+const EXT_ID = 'a'.repeat(32);
+const STORE_ID = 'b'.repeat(32);
+const WIRE = '0.4.13';
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const bridges: BrowserExtensionBridge[] = [];
+afterEach(async () => {
+ await Promise.all(bridges.splice(0).map((b) => b.close()));
+});
+
+async function credential() {
+ const pair = await webcrypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, false, [
+ 'sign',
+ 'verify',
+ ]);
+ const jwk = await webcrypto.subtle.exportKey('jwk', pair.publicKey);
+ const publicJwk = { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y, ext: false };
+ const publicKey = Buffer.from(JSON.stringify(publicJwk)).toString('base64url');
+ const sign = async (challenge: string) =>
+ Buffer.from(
+ await webcrypto.subtle.sign(
+ { name: 'ECDSA', hash: 'SHA-256' },
+ pair.privateKey,
+ new TextEncoder().encode(challenge),
+ ),
+ ).toString('base64url');
+ return { publicKey, publicJwk, sign };
+}
+
+interface ClientOptions {
+ browser?: 'chrome' | 'edge' | 'safari';
+ extensionId?: string;
+ origin?: string;
+ paired?: boolean;
+ native?: boolean;
+}
+
+async function fixture(
+ options: ConstructorParameters<typeof BrowserExtensionBridge>[0] extends infer O
+ ? Partial<O>
+ : never = {},
+) {
+ const relays: BrowserExtensionRelayNotice[] = [];
+ const nativeToken = 'd'.repeat(64);
+ const bridge = new BrowserExtensionBridge({
+ ghostId: 'my-browser',
+ installedVersion: '0.5.0',
+ extensionIds: [EXT_ID, STORE_ID],
+ nativeToken,
+ ports: [0],
+ pollTimeout: 20,
+ connectWait: 0,
+ jobTimeout: 200,
+ onRelay: (n) => relays.push(n),
+ ...options,
+ });
+ bridges.push(bridge);
+ const status = await bridge.status();
+ if (!status.ok) throw new Error('bridge did not start');
+ const url = 'http://127.0.0.1:' + status.port;
+ const pinned: Array<{ id: string; origin: string; extensionId: string; publicKey: string }> = [];
+ async function client(opts: ClientOptions = {}) {
+ const browser = opts.browser ?? 'chrome';
+ const extensionId = opts.extensionId ?? EXT_ID;
+ const origin = opts.origin ?? 'chrome-extension://' + extensionId;
+ const id = crypto.randomUUID();
+ const key = await credential();
+ let session: string | undefined;
+ const headers = (extra: Record<string, string> = {}) => ({
+ 'X-My-Browser-Extension': extensionId,
+ 'X-My-Browser-Origin': origin,
+ 'X-My-Browser-Client': id,
+ 'X-My-Browser-Version': WIRE,
+ 'X-My-Browser-Family': browser,
+ 'X-My-Browser-Key': key.publicKey,
+ ...(session ? { 'X-My-Browser-Session': session } : {}),
+ ...extra,
+ });
+ const request = async (route: string, body?: unknown, extra: Record<string, string> = {}) => {
+ const r = await fetch(url + route, {
+ method: body === undefined ? 'GET' : 'POST',
+ headers: headers(extra),
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+ });
+ // 线协议回复是松散 JSON,测试按字段断言;用 any 保留与扩展侧同样的读取方式。
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ return { status: r.status, ...(await r.json()) } as { status: number; [key: string]: any };
+ };
+ const record = { id, origin, extensionId, publicKey: JSON.stringify(key.publicJwk) };
+ const pair = async () => {
+ pinned.push(record);
+ bridge.setTrustedClients([...pinned]);
+ };
+ if (opts.paired) await pair();
+ const health = async () => {
+ let r = await request('/health');
+ if (r.challenge)
+ r = await request('/health', undefined, {
+ 'X-My-Browser-Proof': await key.sign(r.challenge),
+ });
+ if (opts.native !== false && r.native_binding_required) {
+ await fetch(url + '/native/bind', {
+ method: 'POST',
+ headers: { Authorization: 'Bearer ' + nativeToken },
+ body: JSON.stringify({ clientId: id, origin, publicKey: key.publicKey }),
+ });
+ r = await request('/health');
+ if (r.challenge)
+ r = await request('/health', undefined, {
+ 'X-My-Browser-Proof': await key.sign(r.challenge),
+ });
+ }
+ session = r.session;
+ return r;
+ };
+ const signed = async (route: string, body?: unknown, extra: Record<string, string> = {}) => {
+ const challenge = await request('/learning/challenge');
+ const method = body === undefined ? 'GET' : 'POST';
+ const serialized = body === undefined ? '' : JSON.stringify(body);
+ const digest = Buffer.from(
+ await webcrypto.subtle.digest('SHA-256', new TextEncoder().encode(serialized)),
+ ).toString('base64url');
+ const proof = await key.sign(
+ challenge.challenge + '\\n' + method + '\\n' + route + '\\n' + digest,
+ );
+ return request(route, body, {
+ ...extra,
+ 'X-My-Browser-Learning-Challenge': challenge.challenge,
+ 'X-My-Browser-Proof': proof,
+ });
+ };
+ const useSession = (value: string | undefined) => {
+ session = value;
+ };
+ return { id, origin, extensionId, request, health, pair, signed, useSession, key };
+ }
+ /** 配对好的默认客户端:已 health、已 poll 一次(建立长轮询等待)。 */
+ async function ready() {
+ const c = await client({ paired: true });
+ await c.health();
+ await c.request('/poll');
+ return c;
+ }
+ return { bridge, url, client, ready, relays, nativeToken };
+}
+
+describe('policy · 站点策略与 URL 脱敏(与扩展侧同判据)', () => {
+ it('默认策略开放公网读写;本机/私网/带凭证地址一律拒绝;主机名规范化', () => {
+ const p = defaultBrowserExtensionPolicy();
+ expect(checkBrowserExtensionPolicy(p, 'text', 'https://example.test').ok).toBe(true);
+ expect(checkBrowserExtensionPolicy(p, 'click', 'https://example.test').ok).toBe(true);
+ expect(normalizeBrowserExtensionPolicy(p)).toEqual(p);
+ p.read.block = ['blocked.test'];
+ for (const url of [
+ 'https://blocked.test',
+ 'https://child.blocked.test',
+ 'http://127.0.0.2',
+ 'http://2130706433',
+ 'http://[::1]',
+ 'http://[::ffff:127.0.0.1]',
+ 'http://[fc00::1]',
+ 'http://[fe80::1]',
+ 'http://10.2.3.4',
+ 'http://192.168.1.2',
+ 'http://localhost.',
+ 'file:///etc/passwd',
+ 'https://a:[email protected]',
+ ]) {
+ expect(checkBrowserExtensionPolicy(p, 'text', url).ok, url).toBe(false);
+ }
+ expect(checkBrowserExtensionPolicy(p, 'text', 'https://[2606:4700:4700::1111]/').ok).toBe(true);
+ p.interact.allow = ['example.test', 'blocked.test'];
+ expect(checkBrowserExtensionPolicy(p, 'click', 'https://sub.example.test').ok).toBe(true);
+ expect(checkBrowserExtensionPolicy(p, 'click', 'https://example.test.evil.test').ok).toBe(
+ false,
+ );
+ expect(checkBrowserExtensionPolicy(p, 'click', 'https://blocked.test')).toMatchObject({
+ error: 'READ_BLOCKED',
+ });
+ expect(normalizeBrowserExtensionHost(' WWW.Example.test ')).toBe('www.example.test');
+ expect(normalizeBrowserExtensionHost('*.example.test')).toBe('example.test');
+ expect(normalizeBrowserExtensionHost('=example.test')).toBe('=example.test');
+ for (const bad of [
+ 'com',
+ 'https://example.test',
+ 'example.test/path',
+ 'example.test:443',
+ '*',
+ '127.0.0.1',
+ ]) {
+ expect(() => normalizeBrowserExtensionHost(bad)).toThrow();
+ }
+ expect(() =>
+ normalizeBrowserExtensionPolicy({ read: { block: 'example.test' }, interact: { allow: [] } }),
+ ).toThrow();
+ });
+
+ it('提取属性是封闭集合;载荷校验保留空文本与空选项', () => {
+ for (const attr of ['href', 'src', 'datetime', 'title', 'alt', 'aria-label', 'role']) {
+ expect(() =>
+ validateBrowserExtensionJob('extract', {
+ url: 'https://example.test',
+ fields: { value: { selector: 'p', attr } },
+ }),
+ ).not.toThrow();
+ }
+ for (const attr of ['data-csrf-token', 'nonce', 'value', 'outerHTML', 'onclick', 'HREF']) {
+ expect(() =>
+ validateBrowserExtensionJob('extract', {
+ url: 'https://example.test',
+ fields: { value: { selector: 'p', attr } },
+ }),
+ ).toThrow();
+ }
+ expect(() =>
+ validateBrowserExtensionJob('type', {
+ url: 'https://example.test',
+ selector: 'input',
+ text: '',
+ }),
+ ).not.toThrow();
+ expect(() =>
+ validateBrowserExtensionJob('select', {
+ url: 'https://example.test',
+ selector: 'select',
+ values: [],
+ }),
+ ).not.toThrow();
+ expect(() =>
+ validateBrowserExtensionJob('extract', { url: 'https://example.test', fields: {} }),
+ ).toThrow();
+ });
+
+ it('URL 脱敏抹掉 OAuth code、重置令牌、fragment 令牌与 Basic Auth,保留普通深路径', () => {
+ const code = '11111111-1111-4111-8111-111111111111';
+ const token = '33333333-3333-4333-8333-333333333333';
+ expect(redactBrowserUrl(`https://example.test/callback?q=cats&code=${code}`)).not.toContain(
+ code,
+ );
+ expect(redactBrowserUrl(`https://example.test/callback?q=cats&code=${code}`)).toMatch(/q=cats/);
+ expect(
+ redactBrowserUrl(`https://example.test/#access_token=${token}&token_type=bearer`),
+ ).not.toContain(token);
+ expect(
+ redactBrowserUrl(
+ `https://example.test/reset/${encodeURIComponent(encodeURIComponent(code))}`,
+ ),
+ ).not.toContain(code);
+ expect(redactBrowserUrl(`https://${code}:${token}@example.test/private`)).toBe(
+ 'https://example.test/private',
+ );
+ expect(
+ redactBrowserUrl(`https://example.test/cb?next=${encodeURIComponent('/reset/' + code)}`),
+ ).not.toContain(code);
+ expect(redactBrowserUrl('https://example.test/commit/' + 'a'.repeat(40))).toBe(
+ 'https://example.test/commit/' + 'a'.repeat(40),
+ );
+ expect(redactBrowserUrl('https://example.test/cb?page=2&sort=name')).toBe(
+ 'https://example.test/cb?page=2&sort=name',
+ );
+ expect(redactBrowserUrl('https://example.test/#/home')).toBe('https://example.test/#/home');
+ expect(redactBrowserUrl('not a url')).toBe('not a url');
+ });
+});
+
+describe('bridge · 连接与身份', () => {
+ it('冷启动并发 status 只开一个监听;未连接时动作快速失败', async () => {
+ const { bridge } = await fixture();
+ const statuses = await Promise.all(Array.from({ length: 8 }, () => bridge.status()));
+ expect(new Set(statuses.map((s) => (s.ok ? s.port : -1))).size).toBe(1);
+ expect(statuses[0]).toMatchObject({ ok: true, extension_connected: false });
+ const result = await bridge.act('text', { url: 'https://example.test' });
+ expect(result).toMatchObject({ error: 'EXTENSION_DISCONNECTED', execution: 'not_executed' });
+ });
+
+ it('回环 HTTP 拒绝网页、预检、改绑 Host、旧会话与任意端点', async () => {
+ const { url, ready } = await fixture();
+ const c = await ready();
+ expect((await fetch(url + '/health')).status).toBe(403);
+ expect((await c.request('/health', undefined, { Origin: 'https://example.test' })).status).toBe(
+ 403,
+ );
+ const rebound = await new Promise<number>((resolve) => {
+ const req = http.get(
+ url + '/health',
+ { headers: { Host: 'example.test', 'X-My-Browser-Extension': EXT_ID } },
+ (res) => {
+ res.resume();
+ resolve(res.statusCode ?? 0);
+ },
+ );
+ req.on('error', () => resolve(0));
+ });
+ expect(rebound).toBe(403);
+ expect(
+ (
+ await fetch(url + '/health', {
+ method: 'OPTIONS',
+ headers: { 'X-My-Browser-Extension': EXT_ID },
+ })
+ ).status,
+ ).toBe(403);
+ expect((await c.request('/poll', undefined, { 'X-My-Browser-Session': 'old' })).status).toBe(
+ 409,
+ );
+ expect((await c.request('/act', { action: 'click' })).status).toBe(404);
+ });
+
+ it('官方扩展经 native 绑定后无需手工配对即可认证;伪造调用方不能自称官方', async () => {
+ const { bridge, client } = await fixture();
+ for (const extensionId of [EXT_ID, STORE_ID]) {
+ const browser = await client({ extensionId });
+ const unsigned = await browser.request('/health');
+ expect(unsigned.session).toBeUndefined();
+ const status = await bridge.status();
+ expect(status.ok && status.clients.find((c) => c.id === browser.id)?.identitySupported).toBe(
+ true,
+ );
+ expect((await browser.request('/poll')).status).toBe(409);
+ const first = await browser.health();
+ expect(first.pairing_required).toBe(false);
+ expect(first.session).toBeTruthy();
+ expect(first.plugin).toBe('my-browser');
+ expect(first.installedVersion).toBe('0.5.0');
+ expect((await browser.request('/learning/challenge')).status).toBe(200);
+ bridge.setTrustedClients([]);
+ expect((await browser.request('/poll')).status).toBe(200);
+ expect((await browser.health()).session).toBe(first.session);
+ }
+ const forged = await client({ native: false });
+ const health = await forged.health();
+ expect(health.session).toBeUndefined();
+ expect(health.native_binding_required).toBe(true);
+ expect((await forged.request('/poll')).status).toBe(409);
+ expect((await forged.request('/native/bind', { clientId: forged.id })).status).toBe(403);
+ const status = await bridge.status();
+ expect(status.ok && status.extension_connected).toBe(true);
+ expect(bridge.connectedClients().some((c) => c.id === forged.id)).toBe(false);
+ });
+
+ it('未知 Chromium 扩展身份不会被静默信任;Safari 身份需经显式配对', async () => {
+ const { bridge, client } = await fixture();
+ const unknown = await client({ browser: 'edge', extensionId: 'z'.repeat(32) });
+ expect((await unknown.health()).pairing_required).toBe(true);
+ const status = await bridge.status();
+ expect(status.ok && status.clients[0].identitySupported).toBe(false);
+ const safari = await client({
+ browser: 'safari',
+ extensionId: 'com.example.browser.Extension',
+ origin: 'safari-web-extension://' + crypto.randomUUID(),
+ });
+ expect((await safari.health()).pairing_required).toBe(true);
+ await safari.pair();
+ const r = await safari.health();
+ expect(r.pairing_required).toBe(false);
+ expect(r.session).toBeTruthy();
+ bridge.setTrustedClients([]);
+ expect((await safari.request('/poll')).status).toBe(409);
+ });
+
+ it('Chrome 与 Edge 作业绑定到各自连接;多连接且未指定 browser 时绝不猜', async () => {
+ const { bridge, client } = await fixture();
+ const chrome = await client();
+ const edge = await client({ browser: 'edge', extensionId: STORE_ID });
+ await chrome.health();
+ await edge.health();
+ expect(await bridge.act('text', { url: 'https://example.test' })).toMatchObject({
+ error: 'BROWSER_REQUIRED',
+ });
+ const done = bridge.act('text', { url: 'https://example.test', browser: edge.id });
+ expect((await chrome.request('/poll')).job).toBeNull();
+ const { job } = await edge.request('/poll');
+ expect(job).toBeTruthy();
+ expect((await chrome.request('/ack', { id: job.id })).status).toBe(409);
+ expect((await edge.request('/ack', { id: job.id })).ok).toBe(true);
+ expect(
+ (await chrome.request('/result', { id: job.id, result: { ok: true, text: 'wrong' } })).status,
+ ).toBe(409);
+ await edge.request('/result', {
+ id: job.id,
+ result: { ok: true, url: 'https://example.test', text: 'correct' },
+ });
+ const r = await done;
+ expect(r).toMatchObject({ text: 'correct', browser: edge.id, untrusted_content: true });
+ expect((r.timing as { totalMs: number }).totalMs).toBeGreaterThanOrEqual(0);
+ });
+});
+
+describe('bridge · 作业生命周期', () => {
+ it('poll/ack/result 真实往返;重复 ack 被拒', async () => {
+ const { bridge, ready } = await fixture();
+ const c = await ready();
+ const promise = bridge.act('text', { url: 'https://example.test' });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ expect(job.id).toMatch(/^[0-9a-f-]{36}$/);
+ expect(job.action).toBe('text');
+ expect((await c.request('/ack', { id: job.id })).ok).toBe(true);
+ expect((await c.request('/ack', { id: job.id })).status).toBe(409);
+ await c.request('/result', {
+ id: job.id,
+ result: { ok: true, url: 'https://example.test', text: 'Hello' },
+ });
+ expect((await promise).text).toBe('Hello');
+ const status = await bridge.status();
+ expect(status.ok && status.pending).toBe(0);
+ });
+
+ it('已确认的交互超时记为 unknown 且绝不重投;未确认的过期作业不能再执行', async () => {
+ const { bridge, ready } = await fixture({ jobTimeout: 80 });
+ const c = await ready();
+ const resultPromise = bridge.act('click', { url: 'https://example.test', selector: 'button' });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ await c.request('/ack', { id: job.id });
+ expect((await resultPromise).execution).toBe('unknown');
+ expect((await c.request('/poll')).job).toBeNull();
+ expect((await c.request('/result', { id: job.id, result: { ok: true } })).status).toBe(409);
+ const queued = await bridge.act('text', { url: 'https://example.test' });
+ expect(queued.execution).toBe('not_executed');
+ const promise = bridge.act('text', { url: 'https://example.test' });
+ await sleep(5);
+ const delivered = (await c.request('/poll')).job;
+ expect((await promise).execution).toBe('not_executed');
+ expect((await c.request('/ack', { id: delivered.id })).status).toBe(409);
+ });
+
+ it('送达后撤销权限:ack 被拒、不留排队作业;重新授权也不能复活', async () => {
+ const { bridge, ready } = await fixture();
+ const c = await ready();
+ const p = defaultBrowserExtensionPolicy();
+ p.interact.allow = ['example.test'];
+ await bridge.setPolicy(p);
+ const promise = bridge.act('click', { url: 'https://example.test', selector: 'button' });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ await bridge.setPolicy({ read: { block: [] }, interact: { allow: [], block: [] } });
+ expect((await promise).execution).toBe('not_executed');
+ expect((await c.request('/ack', { id: job.id })).status).toBe(409);
+ for (const blocked of ['example.test', 'redirect.test']) {
+ await bridge.setPolicy(defaultBrowserExtensionPolicy());
+ const pending = bridge.act('click', { url: 'https://example.test', selector: 'button' });
+ await sleep(5);
+ const delivered = (await c.request('/poll')).job;
+ await c.request('/ack', { id: delivered.id });
+ expect(
+ (await c.request('/authorize', { id: delivered.id, url: 'https://redirect.test' })).ok,
+ ).toBe(true);
+ await bridge.setPolicy({ ...defaultBrowserExtensionPolicy(), read: { block: [blocked] } });
+ const result = await pending;
+ expect(result).toMatchObject({ error: 'READ_BLOCKED', execution: 'unknown' });
+ await bridge.setPolicy(defaultBrowserExtensionPolicy());
+ expect(
+ (await c.request('/authorize', { id: delivered.id, url: 'https://redirect.test' })).status,
+ ).toBe(409);
+ expect((await c.request('/result', { id: delivered.id, result: { ok: true } })).status).toBe(
+ 409,
+ );
+ }
+ });
+
+ it('撤销等待最终文档派发结束并丢弃其结果;丢失的派发不能报告为撤销成功', async () => {
+ const { bridge, ready } = await fixture({ jobTimeout: 2000 });
+ const c = await ready();
+ const pending = bridge.act('click', { url: 'https://example.test', selector: 'button' });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ await c.request('/ack', { id: job.id });
+ expect(
+ (await c.request('/authorize', { id: job.id, url: 'https://example.test', dispatch: true }))
+ .ok,
+ ).toBe(true);
+ let saved = false;
+ const save = bridge
+ .setPolicy({ ...defaultBrowserExtensionPolicy(), read: { block: ['example.test'] } })
+ .then((r) => {
+ saved = true;
+ return r;
+ });
+ await sleep(25);
+ expect(saved).toBe(false);
+ expect(
+ (await c.request('/authorize', { id: job.id, url: 'https://example.test', dispatch: true }))
+ .status,
+ ).toBe(403);
+ expect(await bridge.act('text', { url: 'https://example.test' })).toMatchObject({
+ error: 'READ_BLOCKED',
+ });
+ await c.request('/result', { id: job.id, result: { ok: true, text: 'must not escape' } });
+ expect((await save).ok).toBe(true);
+ const result = await pending;
+ expect(result).toMatchObject({ error: 'READ_BLOCKED', execution: 'unknown' });
+ expect(result.text).toBeUndefined();
+
+ const { bridge: lost, ready: readyLost } = await fixture({ jobTimeout: 100 });
+ const l = await readyLost();
+ const lostPending = lost.act('click', { url: 'https://example.test', selector: 'button' });
+ await sleep(5);
+ const lostJob = (await l.request('/poll')).job;
+ await l.request('/ack', { id: lostJob.id });
+ await l.request('/authorize', { id: lostJob.id, url: 'https://example.test', dispatch: true });
+ const policy = { ...defaultBrowserExtensionPolicy(), read: { block: ['example.test'] } };
+ expect(await lost.setPolicy(policy)).toMatchObject({
+ ok: false,
+ error: 'REVOCATION_UNCONFIRMED',
+ execution: 'unknown',
+ applied: true,
+ });
+ expect(await lost.setPolicy(policy)).toMatchObject({ error: 'REVOCATION_UNCONFIRMED' });
+ expect(
+ (await l.request('/result', { id: lostJob.id, result: { ok: false, execution: 'unknown' } }))
+ .status,
+ ).toBe(409);
+ expect(await lost.setPolicy(policy)).toMatchObject({ error: 'REVOCATION_UNCONFIRMED' });
+ expect((await l.request('/result', { id: lostJob.id, result: { ok: true } })).status).toBe(409);
+ expect((await lost.setPolicy(policy)).ok).toBe(true);
+ expect((await lostPending).execution).toBe('unknown');
+ });
+
+ it('被阻止站点的标签与跳转到被阻止站点的内容由宿主脱敏,不依赖扩展过滤', async () => {
+ const { bridge, ready } = await fixture();
+ const c = await ready();
+ await bridge.setPolicy({
+ ...defaultBrowserExtensionPolicy(),
+ read: { block: ['blocked.test'] },
+ });
+ async function roundtrip(action: string, result: unknown) {
+ const p = bridge.act(action, action === 'tabs' ? {} : { url: 'https://example.test' });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ await c.request('/ack', { id: job.id });
+ await c.request('/result', { id: job.id, result });
+ return p;
+ }
+ const r = await roundtrip('tabs', {
+ tabs: [
+ { id: 1, url: 'https://blocked.test', title: 'private' },
+ {
+ id: 2,
+ url: 'https://example.test?code=11111111-1111-4111-8111-111111111111',
+ title: 'public',
+ },
+ ],
+ });
+ const tabs = r.tabs as Array<Record<string, unknown>>;
+ expect(tabs[0]).toEqual({ id: 1, redacted: true });
+ expect(tabs[1].title).toBe('public');
+ expect(tabs[1].url).not.toContain('11111111');
+ const redirected = await roundtrip('text', {
+ ok: true,
+ url: 'https://blocked.test',
+ text: 'private',
+ });
+ expect(redirected).toMatchObject({ error: 'REDIRECT_BLOCKED' });
+ expect(redirected.text).toBeUndefined();
+ });
+
+ it('提取结果的最终预算覆盖脱敏后的增长;__proto__ 字段按自有属性保留', async () => {
+ const { bridge, ready } = await fixture({ jobTimeout: 3000 });
+ const c = await ready();
+ const url =
+ 'https://example.test/?' + Array.from({ length: 15 }, (_, i) => 'token' + i + '=x').join('&');
+ const record = Object.fromEntries(Array.from({ length: 30 }, (_, i) => ['field' + i, url]));
+ expect(url.length * 30).toBeLessThan(6000);
+ expect(redactBrowserUrl(url).length * 30).toBeGreaterThan(6000);
+ const promise = bridge.act('extract', {
+ url: 'https://example.test',
+ fields: { link: 'a' },
+ multiple: true,
+ });
+ await sleep(5);
+ const { job } = await c.request('/poll');
+ await c.request('/ack', { id: job.id });
+ await c.request('/result', {
+ id: job.id,
+ result: {
+ ok: true,
+ url: 'https://example.test',
+ truncated: false,
+ records: [record, record],
+ count: 2,
+ },
+ });
+ const result = await promise;
+ const values = (result.records as Array<Record<string, string | null>>).flatMap((row) =>
+ Object.values(row),
+ );
+ expect(values.reduce((n, v) => n + (v?.length || 0), 0)).toBeLessThanOrEqual(6000);
+ expect(result.truncated).toBe(true);
+ expect(values.every((v) => v === null || v === redactBrowserUrl(url))).toBe(true);
+ const single = bridge.act('extract', {
+ url: 'https://example.test',
+ fields: { text: 'p' },
+ maxChars: 256,
+ });
+ await sleep(5);
+ const next = (await c.request('/poll')).job;
+ await c.request('/ack', { id: next.id });
+ await c.request('/result', {
+ id: next.id,
+ result: {
+ ok: true,
+ record: JSON.parse('{"__proto__":"kept","text":"' + 't'.repeat(300) + '","missing":null}'),
+ },
+ });
+ const bounded = await single;
+ const row = bounded.record as Record<string, unknown>;
+ expect(Object.hasOwn(row, '__proto__')).toBe(true);
+ expect((row as { text: string }).text.length).toBe(252);
+ expect(bounded.truncated).toBe(true);
+ });
+});
+
+describe('bridge · 转交请求(翻译/字幕)', () => {
+ it('转交请求必须由配对密钥签名;去重、进度投影、取消与策略撤销都按合同', async () => {
+ const { bridge, ready, relays } = await fixture();
+ const c = await ready();
+ const job = {
+ id: crypto.randomUUID(),
+ request: { op: 'translate', text: 'hello', source: { url: 'https://example.test/' } },
+ };
+ expect(
+ (await c.request('/learning/start', job, { Origin: 'https://example.test' })).status,
+ ).toBe(403);
+ expect((await c.request('/learning/start', job)).status).toBe(403);
+ expect((await c.signed('/learning/start', job)).ok).toBe(true);
+ await c.signed('/learning/start', job);
+ expect(relays).toHaveLength(1);
+ expect(relays[0]).toMatchObject({
+ id: job.id,
+ clientId: c.id,
+ request: { op: 'translate', text: 'hello' },
+ });
+ // 改动请求体后旧证明失效。
+ const challenge = await c.request('/learning/challenge');
+ const body = { id: crypto.randomUUID(), request: { op: 'config' } };
+ const digest = Buffer.from(
+ await webcrypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(body))),
+ ).toString('base64url');
+ const proof = await c.key.sign(challenge.challenge + '\\nPOST\\n/learning/start\\n' + digest);
+ expect(
+ (
+ await c.request(
+ '/learning/start',
+ { ...body, request: { op: 'config', text: 'tampered' } },
+ { 'X-My-Browser-Learning-Challenge': challenge.challenge, 'X-My-Browser-Proof': proof },
+ )
+ ).status,
+ ).toBe(403);
+ expect(bridge.relayActive(job.id).active).toBe(true);
+ bridge.relayProgress(job.id, { stage: 'model', attempt: 2, prompt: 'must not escape' });
+ const progress = (await c.signed('/learning/result', { id: job.id })).progress;
+ expect(progress).toMatchObject({ stage: 'model', attempt: 2 });
+ expect(progress.prompt).toBeUndefined();
+ bridge.relayProgress(job.id, { stage: 'untrusted arbitrary text' });
+ expect((await c.signed('/learning/result', { id: job.id })).progress.stage).toBe('model');
+ expect(bridge.relayResult(job.id, { ok: true, translations: ['你好'] })).toEqual({ ok: true });
+ expect(await c.signed('/learning/result', { id: job.id })).toMatchObject({
+ done: true,
+ result: { translations: ['你好'] },
+ });
+ await bridge.setPolicy({ read: { block: ['example.test'] }, interact: { allow: [] } });
+ expect(bridge.relayActive(job.id).active).toBe(false);
+ expect((await c.signed('/learning/result', { id: job.id })).status).toBe(403);
+ const config = { id: crypto.randomUUID(), request: { op: 'config' } };
+ await c.signed('/learning/start', config);
+ await c.signed('/learning/cancel', { id: config.id });
+ expect(bridge.relayResult(config.id, { ok: true }).ok).toBe(false);
+ expect(
+ (await c.signed('/learning/start', { id: 'bad', request: { op: 'config' } })).status,
+ ).toBe(400);
+ expect(
+ (await c.signed('/learning/start', { id: crypto.randomUUID(), request: { op: 'nope' } }))
+ .status,
+ ).toBe(400);
+ });
+});
diff --git a/apps/desktop/src/main/browser-extension/__tests__/native-binding.test.ts b/apps/desktop/src/main/browser-extension/__tests__/native-binding.test.ts
new file mode 100644
index 0000000000..24b3d8142c
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/__tests__/native-binding.test.ts
@@ -0,0 +1,152 @@
+/**
+ * native-binding.test — Native Messaging 注册(从插件时期迁入宿主)的文件系统契约。
+ *
+ * 测试价值
+ * - 生产入口与可观察结果:createNativeBinding().install/close;浏览器 profile 里的 host
+ * manifest 内容、私有连接文件的权限、关闭时只删自己的令牌。
+ * - 规则依据:docs/dev-rules/credentials-and-local-storage.md(私有授权不进扩展、不进清单、
+ * 0600);协议兼容规则「注册文件布局与插件时期相同」。
+ * - 现有覆盖缺口:新模块。
+ * - 最小失败输入:注册目录是符号链接;二进制缺失;同端口被另一实例接管后关闭。
+ * - tier:unit(临时目录);实测耗时 < 1 秒。
+ */
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createNativeBinding } from '../native-binding';
+
+const EXT = 'a'.repeat(32);
+const dirs: string[] = [];
+afterEach(async () => {
+ await Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+async function fixture() {
+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-native-binding-'));
+ dirs.push(dir);
+ const binaryDir = path.join(dir, 'pkg', 'native-host', 'bin');
+ await fs.mkdir(path.join(binaryDir, 'darwin-arm64'), { recursive: true });
+ await fs.writeFile(
+ path.join(binaryDir, 'darwin-arm64', 'cindy-browser-native'),
+ 'fixture executable',
+ );
+ const profile = path.join(dir, 'profile');
+ await fs.mkdir(profile);
+ return { dir, binaryDir, profile, root: path.join(dir, 'native') };
+}
+
+describe('native-binding', () => {
+ it('registers only allowed origins; the private authority never enters the browser manifest', async () => {
+ const { binaryDir, profile, root } = await fixture();
+ const n = createNativeBinding({
+ hostName: 'com.example.browser',
+ binaryDir,
+ root,
+ profiles: [profile],
+ platform: 'darwin',
+ arch: 'arm64',
+ });
+ expect(await n.install(18819, [EXT])).toEqual({ ok: true });
+ const manifest = JSON.parse(
+ await fs.readFile(
+ path.join(profile, 'NativeMessagingHosts', 'com.example.browser.json'),
+ 'utf8',
+ ),
+ );
+ expect(manifest).toMatchObject({
+ name: 'com.example.browser',
+ type: 'stdio',
+ allowed_origins: ['chrome-extension://' + EXT + '/'],
+ path: path.join(root, 'cindy-browser-native'),
+ });
+ expect(JSON.stringify(manifest)).not.toContain(n.token);
+ expect((await fs.stat(path.join(root, 'connections', '18819.json'))).mode & 0o777).toBe(0o600);
+ expect((await fs.stat(root)).mode & 0o777).toBe(0o700);
+ expect(await fs.readFile(path.join(root, 'cindy-browser-native'), 'utf8')).toBe(
+ 'fixture executable',
+ );
+ expect(n.status()).toBe('ready');
+ await n.close();
+ await expect(fs.access(path.join(root, 'connections', '18819.json'))).rejects.toThrow();
+ });
+
+ it('closing one binding keeps another instance authority on the same reused port', async () => {
+ const { binaryDir, profile, root } = await fixture();
+ const opts = {
+ hostName: 'com.example.browser',
+ binaryDir,
+ root,
+ profiles: [profile],
+ platform: 'darwin' as const,
+ arch: 'arm64',
+ };
+ const a = createNativeBinding(opts);
+ const b = createNativeBinding(opts);
+ await a.install(18819, [EXT]);
+ await b.install(18819, [EXT]);
+ await a.close();
+ expect(
+ JSON.parse(await fs.readFile(path.join(root, 'connections', '18819.json'), 'utf8')).token,
+ ).toBe(b.token);
+ await b.close();
+ });
+
+ it('Windows registration uses only current-user fixed registry keys and argv', async () => {
+ const { dir, binaryDir } = await fixture();
+ await fs.mkdir(path.join(binaryDir, 'win32-x64'), { recursive: true });
+ await fs.writeFile(path.join(binaryDir, 'win32-x64', 'cindy-browser-native.exe'), 'fixture');
+ const run = vi.fn(async () => undefined);
+ const n = createNativeBinding({
+ hostName: 'com.example.browser',
+ binaryDir,
+ root: path.join(dir, 'native'),
+ platform: 'win32',
+ arch: 'x64',
+ env: { SystemRoot: 'C:\\Windows' },
+ run,
+ });
+ expect((await n.install(18819, [EXT])).ok).toBe(true);
+ expect(run).toHaveBeenCalledTimes(3);
+ for (const [, args, opts] of run.mock.calls as unknown as Array<
+ [string, string[], { windowsHide: boolean }]
+ >) {
+ expect(args[0]).toBe('ADD');
+ expect(args[1]).toMatch(/^HKCU\\Software\\/);
+ expect(args.at(-1)).toBe('/f');
+ expect(opts.windowsHide).toBe(true);
+ }
+ await n.close();
+ });
+
+ it('fails closed when the executable is absent or the registration directory is a symlink', async () => {
+ const { dir, binaryDir, profile } = await fixture();
+ const link = path.join(dir, 'link');
+ await fs.symlink(profile, link);
+ const linked = createNativeBinding({
+ hostName: 'com.example.browser',
+ binaryDir,
+ root: link,
+ profiles: [profile],
+ platform: 'darwin',
+ arch: 'arm64',
+ });
+ expect(await linked.install(18819, [EXT])).toMatchObject({
+ ok: false,
+ error: 'NATIVE_BINDING_UNAVAILABLE',
+ });
+ expect(linked.status()).toBe('unavailable');
+ const missing = createNativeBinding({
+ hostName: 'com.example.browser',
+ binaryDir: path.join(dir, 'nowhere'),
+ root: path.join(dir, 'native2'),
+ profiles: [profile],
+ platform: 'darwin',
+ arch: 'arm64',
+ });
+ expect(await missing.install(18819, [EXT])).toMatchObject({ ok: false, reason: 'ENOENT' });
+ });
+});
diff --git a/apps/desktop/src/main/browser-extension/bridge.ts b/apps/desktop/src/main/browser-extension/bridge.ts
new file mode 100644
index 0000000000..ae6ecb0012
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/bridge.ts
@@ -0,0 +1,1261 @@
+/**
+ * 浏览器扩展桥接(宿主侧):在 127.0.0.1 的一段固定端口上承接随包浏览器扩展的
+ * 长轮询连接,负责配对、身份绑定、作业分发、站点策略守门、结果脱敏,以及把
+ * 扩展发起的转交请求(翻译、字幕等)交给声明 browserExtension 的插件处理。
+ *
+ * 线协议 `cindy-browser-extension/3`(协议号 3,签名线合同 0.4.13)原样沿用插件
+ * 时期的合同,已装扩展不需要更新即可连到宿主:
+ *
+ * GET /health 握手:身份、版本、挑战/证明、会话
+ * GET /poll 长轮询取作业(20 秒)
+ * POST /ack /authorize /result 作业生命周期(已送达 → 已确认 → 已授权 → 结果)
+ * GET /learning/challenge 转交请求的一次性挑战
+ * POST /learning/start|result|cancel 扩展发起、查询、取消转交请求
+ * POST /native/bind Native Messaging host 代为绑定官方扩展身份
+ *
+ * 安全不变量(与插件时期逐条相同):
+ * - 只有扩展 origin 能连:自定义头 + 无 CORS,网页、预检、改绑 Host 一律 403;
+ * - 官方扩展 id 首次出现必须经 native host 绑定公钥,HTTP 调用方不能自称官方;
+ * - 作业一次送达绝不重投;已确认未完成的作业只能是 unknown,不能按成功或未执行报告;
+ * - 策略撤销对在途作业生效:未授权直接作废,已进入 DOM 派发的等待派发结束再丢弃结果;
+ * - 每个 URL 交给模型前都经 redactBrowserUrl;读取结果标 untrusted_content。
+ */
+
+import http from 'node:http';
+import crypto from 'node:crypto';
+
+import {
+ checkBrowserExtensionPolicy,
+ defaultBrowserExtensionPolicy,
+ isBrowserExtensionInteractAction,
+ isBrowserExtensionReadAction,
+ normalizeBrowserExtensionPolicy,
+ redactBrowserUrl,
+ validateBrowserExtensionJob,
+ type BrowserExtensionAction,
+ type BrowserExtensionJobPayload,
+ type BrowserExtensionPolicy,
+} from './policy.js';
+import {
+ RELAY_PROGRESS_STAGES,
+ RELAY_TIMING,
+ relayRequestTimeout,
+ validateRelayRequest,
+ type RelayRequest,
+} from './relay-protocol.js';
+
+export const BROWSER_EXTENSION_PROTOCOL_NUMBER = 3;
+/** 签名线合同版本;扩展与宿主各自发布不改变认证合同。 */
+export const BROWSER_EXTENSION_WIRE_VERSION = '0.4.13';
+/** 兼容的扩展端口段:0.3.x / 0.4.x 扩展只扫 18810–18819(新扩展再扫到 18909)。 */
+export const BROWSER_EXTENSION_DEFAULT_PORTS: readonly number[] = Array.from(
+ { length: 10 },
+ (_, i) => 18810 + i,
+);
+
+const LEGACY_WIRE_VERSIONS = [
+ '0.4.0',
+ '0.4.1',
+ '0.4.2',
+ '0.4.3',
+ '0.4.4',
+ '0.4.5',
+ '0.4.6',
+ '0.4.7',
+ '0.4.8',
+ '0.4.9',
+ '0.4.10',
+ '0.4.11',
+ '0.4.12',
+];
+
+export type BrowserExtensionExecution = 'not_executed' | 'executed' | 'unknown';
+
+export interface BrowserExtensionFailure {
+ ok: false;
+ error: string;
+ message: string;
+ execution: BrowserExtensionExecution;
+ [key: string]: unknown;
+}
+
+export type BrowserExtensionJobResult = { ok: boolean; [key: string]: unknown };
+
+export interface BrowserExtensionTrustedClient {
+ id: string;
+ origin: string;
+ extensionId: string;
+ publicKey?: string;
+}
+
+export interface BrowserExtensionClientInfo {
+ id: string;
+ browser: 'chrome' | 'edge' | 'safari';
+ version: string | null;
+ protocolVersion: string;
+ connected: boolean;
+ trusted: boolean;
+ identitySupported: boolean;
+ nativeBindingRequired: boolean;
+ origin: string;
+ extensionId: string;
+ publicKey?: string;
+}
+
+export interface BrowserExtensionBridgeStatus {
+ ok: true;
+ version: string;
+ protocol: number;
+ port: number;
+ extension_connected: boolean;
+ extension_ids: string[];
+ policy: BrowserExtensionPolicy;
+ pending: number;
+ clients: BrowserExtensionClientInfo[];
+}
+
+export interface BrowserExtensionRelayNotice {
+ id: string;
+ clientId: string;
+ request: RelayRequest;
+}
+
+export interface BrowserExtensionBridgeOptions {
+ /** 声明本能力的插件 id;/health 的 plugin 字段(扩展据此确认连对了宿主)。 */
+ ghostId: string;
+ /** 插件版本;/health 的 installedVersion(扩展设置页展示)。 */
+ installedVersion: string;
+ /** 允许连接的扩展 id(身份卡 browserExtension.extensionIds)。 */
+ extensionIds: readonly string[];
+ /** Native Messaging host 的私有授权令牌(64 位 hex);缺省表示没有 native 绑定。 */
+ nativeToken?: string;
+ /** 扩展发起的转交请求到达时回调(宿主转交给插件)。 */
+ onRelay?: (notice: BrowserExtensionRelayNotice) => void;
+ ports?: readonly number[];
+ pollTimeout?: number;
+ connectWait?: number;
+ jobTimeout?: number;
+ now?: () => number;
+ log?: {
+ info: (msg: string, meta?: Record<string, unknown>) => void;
+ warn: (msg: string, meta?: Record<string, unknown>) => void;
+ };
+}
+
+interface Client {
+ id: string;
+ origin: string;
+ extensionId: string;
+ browser: 'chrome' | 'edge' | 'safari';
+ version: string;
+ installedVersion: string | null;
+ seen: number;
+ publicKey: string | null;
+ authenticated: boolean;
+ challenge: { value: string; expires: number; publicKey: string } | null;
+ session: string | null;
+ trusted: boolean;
+}
+
+type JobState = 'queued' | 'delivered' | 'acknowledged';
+
+interface Job {
+ id: string;
+ action: BrowserExtensionAction;
+ payload: BrowserExtensionJobPayload;
+ clientId: string;
+ state: JobState;
+ resolve: (result: BrowserExtensionJobResult) => void;
+ created: number;
+ timer?: ReturnType<typeof setTimeout>;
+ authorizedUrl?: string;
+ dispatchSettled?: Promise<boolean>;
+ settleDispatch?: (finished: boolean) => void;
+ revoked?: { error: string; message: string };
+}
+
+interface RelayItem {
+ id: string;
+ clientId: string;
+ payload: RelayRequest;
+ created: number;
+ expiresAt: number;
+ result: unknown;
+ retired?: boolean;
+ progress: {
+ stage: string;
+ attempt: number;
+ receivedChars?: number;
+ startedAt: number;
+ updatedAt: number;
+ };
+}
+
+const failure = (
+ error: string,
+ message: string,
+ execution: BrowserExtensionExecution = 'not_executed',
+): BrowserExtensionFailure => ({ ok: false, error, message, execution });
+
+const isHttp = (value: unknown): value is string =>
+ typeof value === 'string' && /^https?:\/\//i.test(value);
+const FIELD_VALUE_MAX = 4000;
+
+export class BrowserExtensionBridge {
+ private policy: BrowserExtensionPolicy = defaultBrowserExtensionPolicy();
+ private pins: BrowserExtensionTrustedClient[] = [];
+ private readonly nativeBindings = new Map<string, string>();
+ private server: http.Server | null = null;
+ private starting: Promise<void> | null = null;
+ private port = 0;
+ private readonly unconfirmedDispatches = new Map<
+ string,
+ { clientId: string; action: BrowserExtensionAction; url?: string; authorizedUrl?: string }
+ >();
+ private unconfirmedOverflow = false;
+ private readonly jobs = new Map<string, Job>();
+ private readonly clients = new Map<string, Client>();
+ private readonly waiting = new Map<string, () => void>();
+ private readonly relays = new Map<string, RelayItem>();
+ private readonly relayChallenges = new Map<string, { clientId: string; expiresAt: number }>();
+ private readonly knownIds: Set<string>;
+ private readonly now: () => number;
+
+ constructor(private readonly options: BrowserExtensionBridgeOptions) {
+ this.knownIds = new Set(options.extensionIds);
+ this.now = options.now ?? Date.now;
+ }
+
+ get listeningPort(): number {
+ return this.port;
+ }
+
+ // ── 身份判据 ────────────────────────────────────────────────────────────
+
+ private compatible(version: string): boolean {
+ return (
+ version === BROWSER_EXTENSION_WIRE_VERSION ||
+ LEGACY_WIRE_VERSIONS.includes(version) ||
+ /^0\.3\.\d+$/.test(version)
+ );
+ }
+
+ private live(c: Client): boolean {
+ return this.now() - c.seen < 35000;
+ }
+
+ private sameIdentity(p: BrowserExtensionTrustedClient | undefined, c: Client): boolean {
+ return !!p && p.id === c.id && p.origin === c.origin && p.extensionId === c.extensionId;
+ }
+
+ private pairedCredential(c: Client): boolean {
+ return this.pins.some(
+ (p) => this.sameIdentity(p, c) && !!c.publicKey && p.publicKey === c.publicKey,
+ );
+ }
+
+ private official(c: Client): boolean {
+ return c.origin === 'chrome-extension://' + c.extensionId && this.knownIds.has(c.extensionId);
+ }
+
+ private approved(c: Client): boolean {
+ return this.official(c) || this.pins.some((p) => this.sameIdentity(p, c));
+ }
+
+ /** 新官方身份需要 native 绑定 + 证明;已保存的配对身份无需 native host 或重新批准。 */
+ private boundCredential(c: Client): boolean {
+ return (
+ this.pairedCredential(c) ||
+ (this.official(c) && this.nativeBindings.get(c.id) === c.publicKey)
+ );
+ }
+
+ private authenticatedCredential(c: Client): boolean {
+ return !!c.publicKey && c.authenticated && this.boundCredential(c);
+ }
+
+ private sessionReady(c: Client): boolean {
+ return (
+ c.trusted &&
+ (c.version !== BROWSER_EXTENSION_WIRE_VERSION
+ ? this.pins.some((p) => this.sameIdentity(p, c))
+ : this.authenticatedCredential(c))
+ );
+ }
+
+ private connected(): Client[] {
+ return [...this.clients.values()].filter(
+ (c) => this.sessionReady(c) && this.live(c) && this.compatible(c.version),
+ );
+ }
+
+ private publicClient(c: Client): BrowserExtensionClientInfo {
+ return {
+ id: c.id,
+ browser: c.browser,
+ version: c.installedVersion,
+ protocolVersion: c.version,
+ connected: this.sessionReady(c) && this.live(c) && this.compatible(c.version),
+ trusted: this.sessionReady(c),
+ identitySupported: this.approved(c),
+ nativeBindingRequired: this.official(c) && !this.boundCredential(c),
+ origin: c.origin,
+ extensionId: c.extensionId,
+ ...(c.publicKey ? { publicKey: c.publicKey } : {}),
+ };
+ }
+
+ private normalizePublicKey(value: unknown): string | null {
+ if (typeof value !== 'string' || value.length > 2048) return null;
+ try {
+ const decoded = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) as Record<
+ string,
+ unknown
+ > | null;
+ if (
+ decoded?.kty !== 'EC' ||
+ decoded?.crv !== 'P-256' ||
+ typeof decoded.x !== 'string' ||
+ typeof decoded.y !== 'string' ||
+ Object.keys(decoded).some((k) => !['kty', 'crv', 'x', 'y', 'ext'].includes(k))
+ ) {
+ return null;
+ }
+ return JSON.stringify({
+ kty: 'EC',
+ crv: 'P-256',
+ x: decoded.x,
+ y: decoded.y,
+ ext: decoded.ext !== false,
+ });
+ } catch {
+ return null;
+ }
+ }
+
+ private verifyProof(publicKey: string | null, challenge: unknown, proof: unknown): boolean {
+ if (
+ !publicKey ||
+ typeof challenge !== 'string' ||
+ typeof proof !== 'string' ||
+ proof.length > 256
+ )
+ return false;
+ try {
+ const key = crypto.createPublicKey({ key: JSON.parse(publicKey), format: 'jwk' });
+ return crypto.verify(
+ 'sha256',
+ Buffer.from(challenge),
+ { key, dsaEncoding: 'ieee-p1363' },
+ Buffer.from(proof, 'base64url'),
+ );
+ } catch {
+ return false;
+ }
+ }
+
+ // ── 结果脱敏 ────────────────────────────────────────────────────────────
+
+ private redactFields(record: Record<string, unknown>): {
+ record: Record<string, unknown>;
+ dropped: boolean;
+ } {
+ let out: Record<string, unknown> | null = null;
+ let dropped = false;
+ for (const [key, value] of Object.entries(record)) {
+ if (!isHttp(value)) continue;
+ let clean: string | null = redactBrowserUrl(value);
+ if (clean.length > FIELD_VALUE_MAX) {
+ clean = null;
+ dropped = true;
+ }
+ if (clean === value) continue;
+ out = out || { ...record };
+ out[key] = clean;
+ }
+ return { record: out || record, dropped };
+ }
+
+ /** 交给模型前的最后一道门:页面 URL、标签页、链接与提取字段里的凭证全部抹掉,并按预算截断。 */
+ private redactResult(result: Record<string, unknown>, maxChars = 6000): Record<string, unknown> {
+ const out: Record<string, unknown> = { ...result };
+ if (typeof out.url === 'string') out.url = redactBrowserUrl(out.url);
+ if (Array.isArray(out.tabs)) {
+ out.tabs = out.tabs.map((t: { redacted?: boolean; url?: unknown }) =>
+ t && !t.redacted && typeof t.url === 'string' ? { ...t, url: redactBrowserUrl(t.url) } : t,
+ );
+ }
+ if (Array.isArray(out.links)) {
+ out.links = out.links.map((l: { url?: unknown }) =>
+ l && typeof l.url === 'string' ? { ...l, url: redactBrowserUrl(l.url) } : l,
+ );
+ }
+ let remaining = maxChars;
+ const boundRecord = (entry: unknown): unknown => {
+ if (!entry || typeof entry !== 'object') return entry;
+ const r = this.redactFields(entry as Record<string, unknown>);
+ let truncated = r.dropped;
+ const bounded: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(r.record)) {
+ let finalValue: unknown = value;
+ if (typeof value === 'string') {
+ const limit = Math.min(remaining, FIELD_VALUE_MAX);
+ if (value.length > limit) {
+ finalValue = isHttp(value) ? null : value.slice(0, limit);
+ truncated = true;
+ }
+ remaining -= (finalValue as string | null)?.length || 0;
+ }
+ // 字段名由调用方控制,包括 "__proto__":按自有属性写入,不污染原型。
+ Object.defineProperty(bounded, key, {
+ value: finalValue,
+ enumerable: true,
+ writable: true,
+ configurable: true,
+ });
+ }
+ if (truncated) out.truncated = true;
+ return bounded;
+ };
+ if (Array.isArray(out.records)) out.records = out.records.map(boundRecord);
+ if (out.record) out.record = boundRecord(out.record);
+ return out;
+ }
+
+ // ── 作业生命周期 ────────────────────────────────────────────────────────
+
+ private finish(job: Job, result: Record<string, unknown>, browserFinished = false): void {
+ if (!this.jobs.has(job.id)) return;
+ clearTimeout(job.timer);
+ this.jobs.delete(job.id);
+ if (job.dispatchSettled && !browserFinished) {
+ // 历史不是可运行的工作:只保留有界的授权元数据,不保留载荷文本与结果承诺。
+ if (this.unconfirmedDispatches.size >= 128) {
+ this.unconfirmedDispatches.delete(this.unconfirmedDispatches.keys().next().value as string);
+ this.unconfirmedOverflow = true; // 忘记身份不是完成的证据。
+ }
+ this.unconfirmedDispatches.set(job.id, {
+ clientId: job.clientId,
+ action: job.action,
+ url: job.payload.url,
+ authorizedUrl: job.authorizedUrl,
+ });
+ }
+ job.settleDispatch?.(browserFinished);
+ const safe = this.redactResult(result, job.payload.maxChars || 6000);
+ const timing = (safe.timing && typeof safe.timing === 'object' ? safe.timing : {}) as Record<
+ string,
+ unknown
+ >;
+ job.resolve({
+ ...safe,
+ browser: job.clientId,
+ timing: { ...timing, totalMs: this.now() - job.created },
+ ...(isBrowserExtensionReadAction(job.action) && job.action !== 'tabs'
+ ? { untrusted_content: true }
+ : {}),
+ } as BrowserExtensionJobResult);
+ }
+
+ private jobFailure(job: Job, error: string, message: string): BrowserExtensionFailure {
+ return failure(
+ error,
+ message,
+ job.state === 'acknowledged' && job.action !== 'tabs' ? 'unknown' : 'not_executed',
+ );
+ }
+
+ private take(
+ clientId: string,
+ ): { id: string; action: string; payload: BrowserExtensionJobPayload } | null {
+ for (const job of this.jobs.values()) {
+ if (job.state !== 'queued' || job.clientId !== clientId) continue;
+ const gate = checkBrowserExtensionPolicy(this.policy, job.action, job.payload.url);
+ if (!gate.ok) {
+ this.finish(job, gate as unknown as Record<string, unknown>);
+ continue;
+ }
+ job.state = 'delivered'; // 丢失的作业绝不重投。
+ return { id: job.id, action: job.action, payload: job.payload };
+ }
+ return null;
+ }
+
+ // ── HTTP ────────────────────────────────────────────────────────────────
+
+ private send(res: http.ServerResponse, value: unknown, status = 200): void {
+ if (res.destroyed || res.writableEnded) return;
+ const data = JSON.stringify(value);
+ res.writeHead(status, {
+ 'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Content-Length': Buffer.byteLength(data),
+ });
+ res.end(data);
+ }
+
+ private async readBody(
+ req: http.IncomingMessage,
+ ): Promise<{ raw: string; value: Record<string, unknown> }> {
+ const chunks: Buffer[] = [];
+ let bytes = 0;
+ for await (const c of req) {
+ const chunk = c as Buffer;
+ bytes += chunk.length;
+ if (bytes > 512000) throw new Error('Too large');
+ chunks.push(chunk);
+ }
+ const raw = Buffer.concat(chunks).toString('utf8');
+ const value = JSON.parse(raw || '{}') as unknown;
+ return {
+ raw,
+ value:
+ value && typeof value === 'object' && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : {},
+ };
+ }
+
+ private header(req: http.IncomingMessage, name: string): string | undefined {
+ const value = req.headers[name];
+ return typeof value === 'string' ? value : undefined;
+ }
+
+ private async route(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+ // 自定义头在网页上会触发预检;永不开启 CORS,/health 也不例外。
+ const hostHeader = req.headers.host;
+ if (req.url === '/native/bind') {
+ // 这份授权只存在于 native host 的私有连接文件里,不是浏览器头、公开清单值或 /health 结果。
+ const expected = this.options.nativeToken;
+ const supplied = this.header(req, 'authorization');
+ if (
+ req.method !== 'POST' ||
+ hostHeader !== '127.0.0.1:' + this.port ||
+ req.headers.origin ||
+ typeof expected !== 'string' ||
+ expected.length !== 64 ||
+ typeof supplied !== 'string' ||
+ Buffer.byteLength(supplied) !== 71 ||
+ !crypto.timingSafeEqual(Buffer.from(supplied), Buffer.from('Bearer ' + expected))
+ ) {
+ return this.send(res, failure('FORBIDDEN', 'Native binding required.'), 403);
+ }
+ const b = (await this.readBody(req)).value;
+ const c = this.clients.get(String(b.clientId));
+ if (
+ !c ||
+ !this.official(c) ||
+ !c.authenticated ||
+ c.origin !== b.origin ||
+ this.normalizePublicKey(b.publicKey) !== c.publicKey
+ ) {
+ return this.send(
+ res,
+ failure('FORBIDDEN', 'Binding does not match the authenticated profile.'),
+ 403,
+ );
+ }
+ this.nativeBindings.set(c.id, c.publicKey as string);
+ return this.send(res, { ok: true });
+ }
+ const extensionId = this.header(req, 'x-my-browser-extension');
+ const origin = this.header(req, 'x-my-browser-origin') || 'chrome-extension://' + extensionId;
+ const id = this.header(req, 'x-my-browser-client');
+ if (
+ hostHeader !== '127.0.0.1:' + this.port ||
+ req.method === 'OPTIONS' ||
+ !/^[a-zA-Z0-9._-]{1,200}$/.test(extensionId || '') ||
+ !/^[a-f0-9-]{36}$/.test(id || '') ||
+ !(
+ origin === 'chrome-extension://' + extensionId ||
+ /^safari-web-extension:\/\/[a-zA-Z0-9.-]+$/.test(origin)
+ ) ||
+ (req.headers.origin && req.headers.origin !== origin)
+ ) {
+ return this.send(res, failure('FORBIDDEN', 'Only an extension origin can connect.'), 403);
+ }
+ const clientId = id as string;
+ let client = this.clients.get(clientId);
+ if (client && (client.origin !== origin || client.extensionId !== extensionId)) {
+ return this.send(
+ res,
+ failure('IDENTITY_CHANGED', 'Reconnect with the correct browser profile.'),
+ 403,
+ );
+ }
+ if (req.method === 'GET' && req.url === '/health') {
+ for (const [key, c] of this.clients) {
+ if (
+ this.now() - c.seen > 180000 &&
+ ![...this.jobs.values()].some((j) => j.clientId === key)
+ ) {
+ this.clients.delete(key);
+ this.nativeBindings.delete(key);
+ }
+ }
+ if (!client && this.clients.size >= 16)
+ return this.send(
+ res,
+ failure('TOO_MANY_BROWSERS', 'Close unused browser connections.'),
+ 429,
+ );
+ const keyHeader = this.header(req, 'x-my-browser-key');
+ const publicKey =
+ keyHeader === undefined ? client?.publicKey || null : this.normalizePublicKey(keyHeader);
+ const proof = this.header(req, 'x-my-browser-proof') ?? null;
+ const familyHeader = this.header(req, 'x-my-browser-family');
+ const family = (['chrome', 'edge', 'safari'] as const).find((f) => f === familyHeader);
+ const installedHeader = this.header(req, 'x-my-browser-installed-version') || '';
+ const installedVersion = /^\d{1,5}\.\d{1,5}\.\d{1,5}$/.test(installedHeader)
+ ? installedHeader
+ : null;
+ if (!client) {
+ client = {
+ id: clientId,
+ origin,
+ extensionId: extensionId as string,
+ browser: family ?? 'chrome',
+ version: '',
+ installedVersion,
+ seen: this.now(),
+ publicKey: null,
+ authenticated: false,
+ challenge: null,
+ session: null,
+ trusted: false,
+ };
+ }
+ client.browser = family ?? client.browser;
+ client.version = String(this.header(req, 'x-my-browser-version') || '').slice(0, 30);
+ client.installedVersion = installedVersion;
+ client.seen = this.now();
+ if (keyHeader !== undefined && publicKey !== client.publicKey) {
+ client.publicKey = publicKey;
+ client.authenticated = false;
+ client.challenge = null;
+ client.session = null;
+ }
+ if (
+ publicKey &&
+ client.challenge &&
+ client.challenge.expires > this.now() &&
+ client.challenge.publicKey === publicKey &&
+ this.verifyProof(publicKey, client.challenge.value, proof)
+ ) {
+ client.authenticated = true;
+ }
+ client.challenge = publicKey
+ ? {
+ value: crypto.randomBytes(32).toString('base64url'),
+ expires: this.now() + 10000,
+ publicKey,
+ }
+ : null;
+ client.trusted = this.approved(client);
+ this.clients.set(clientId, client);
+ const authRequired = client.version === BROWSER_EXTENSION_WIRE_VERSION;
+ const sessionAllowed = this.sessionReady(client);
+ const nativeRequired = this.official(client) && authRequired && !this.boundCredential(client);
+ if (sessionAllowed && !client.session) client.session = crypto.randomUUID();
+ return this.send(res, {
+ ok: true,
+ plugin: this.options.ghostId,
+ protocol: BROWSER_EXTENSION_PROTOCOL_NUMBER,
+ version: this.compatible(client.version) ? client.version : BROWSER_EXTENSION_WIRE_VERSION,
+ installedVersion: this.options.installedVersion,
+ extensionId,
+ clientId,
+ pairing_required: !sessionAllowed,
+ native_binding_required: nativeRequired,
+ auth_required: authRequired,
+ capabilities: sessionAllowed && authRequired ? ['learning-v1', 'learning-auth-v2'] : [],
+ ...(client.challenge ? { challenge: client.challenge.value } : {}),
+ ...(sessionAllowed ? { session: client.session } : {}),
+ });
+ }
+ if (
+ !client ||
+ !this.sessionReady(client) ||
+ !client.session ||
+ !this.live(client) ||
+ !this.compatible(client.version) ||
+ this.header(req, 'x-my-browser-session') !== client.session
+ ) {
+ return this.send(
+ res,
+ failure('SESSION_CHANGED', 'Reconnect the Cindy browser extension.'),
+ 409,
+ );
+ }
+ client.seen = this.now();
+ if (req.url === '/learning/challenge' && req.method === 'GET') {
+ if (!this.authenticatedCredential(client))
+ return this.send(
+ res,
+ failure(
+ 'PAIRING_REQUIRED',
+ 'Reconnect the Cindy browser extension before starting learning.',
+ ),
+ 403,
+ );
+ for (const [key, item] of this.relayChallenges)
+ if (this.now() > item.expiresAt) this.relayChallenges.delete(key);
+ const value = crypto.randomBytes(32).toString('base64url');
+ this.relayChallenges.set(value, { clientId, expiresAt: this.now() + 10000 });
+ return this.send(res, { ok: true, challenge: value });
+ }
+ let relayBody: Record<string, unknown> = {};
+ let relayRaw = '';
+ if (req.method === 'POST' && req.url?.startsWith('/learning/')) {
+ const parsed = await this.readBody(req);
+ relayBody = parsed.value;
+ relayRaw = parsed.raw;
+ }
+ if (req.url?.startsWith('/learning/')) {
+ const challenge = this.header(req, 'x-my-browser-learning-challenge') ?? '';
+ const proof = this.header(req, 'x-my-browser-proof') ?? '';
+ const pending = this.relayChallenges.get(challenge);
+ const bodyDigest = crypto.createHash('sha256').update(relayRaw).digest('base64url');
+ const payload = challenge + '\\n' + req.method + '\\n' + req.url + '\\n' + bodyDigest;
+ const valid =
+ pending?.clientId === clientId &&
+ pending.expiresAt > this.now() &&
+ this.authenticatedCredential(client) &&
+ this.normalizePublicKey(this.header(req, 'x-my-browser-key')) === client.publicKey &&
+ this.verifyProof(client.publicKey, payload, proof);
+ if (!valid)
+ return this.send(
+ res,
+ failure(
+ 'PAIRING_REQUIRED',
+ 'Reconnect the Cindy browser extension before starting learning.',
+ ),
+ 403,
+ );
+ this.relayChallenges.delete(challenge);
+ }
+ if (req.method === 'POST' && req.url === '/learning/start') {
+ const b = relayBody;
+ if (typeof b.id !== 'string' || !/^[a-f0-9-]{36}$/.test(b.id))
+ return this.send(res, failure('INVALID_ID', 'Invalid request.'), 400);
+ for (const [key, item] of this.relays)
+ if (this.now() > item.expiresAt) this.relays.delete(key);
+ const previous = this.relays.get(b.id);
+ if (previous?.clientId === clientId && previous.retired)
+ return this.send(
+ res,
+ failure('REQUEST_EXPIRED', 'The completed result is no longer retained.'),
+ 404,
+ );
+ if (previous) {
+ return this.send(
+ res,
+ previous.clientId === clientId
+ ? { ok: true, id: b.id }
+ : failure('INVALID_ID', 'Request belongs to another profile.'),
+ previous.clientId === clientId ? 200 : 403,
+ );
+ }
+ const running = [...this.relays.values()].filter((x) => !x.result);
+ if (
+ this.relays.size >= 4096 ||
+ running.length >= 64 ||
+ running.filter((x) => x.clientId === clientId).length >= 4
+ ) {
+ return this.send(res, failure('BUSY', 'Wait for the current requests.'), 429);
+ }
+ let payload: RelayRequest;
+ try {
+ payload = validateRelayRequest(b.request);
+ } catch {
+ return this.send(res, failure('INVALID_INPUT', 'Check the selected text or file.'), 400);
+ }
+ if (payload.source.url) {
+ const gate = checkBrowserExtensionPolicy(this.policy, 'text', payload.source.url);
+ if (!gate.ok) return this.send(res, gate, 403);
+ payload.source.url = redactBrowserUrl(payload.source.url);
+ }
+ // 已完成的结果另计上限;淘汰时留一张小回执,重放旧 id 绝不重新提交模型。
+ const completed = [...this.relays.values()].filter((x) => x.result && !x.retired);
+ while (completed.length >= 64) {
+ const old = completed.shift() as RelayItem;
+ old.retired = true;
+ old.payload = { op: old.payload.op, source: old.payload.source };
+ old.result = { ok: false, error: 'REQUEST_EXPIRED' };
+ }
+ const created = this.now();
+ const item: RelayItem = {
+ id: b.id,
+ clientId,
+ payload,
+ created,
+ expiresAt: created + relayRequestTimeout(payload) + RELAY_TIMING.transport,
+ result: null,
+ progress: { stage: 'accepted', startedAt: created, updatedAt: created, attempt: 1 },
+ };
+ this.relays.set(b.id, item);
+ try {
+ this.options.onRelay?.({ id: b.id, clientId, request: payload });
+ } catch (err) {
+ this.options.log?.warn('browser extension relay handler threw', {
+ err: err instanceof Error ? err.message : String(err),
+ });
+ }
+ return this.send(res, { ok: true, id: b.id });
+ }
+ if (
+ req.method === 'POST' &&
+ (req.url === '/learning/result' || req.url === '/learning/cancel')
+ ) {
+ const b = relayBody;
+ const item = this.relays.get(String(b.id));
+ if (!item || item.clientId !== clientId)
+ return this.send(
+ res,
+ failure('REQUEST_EXPIRED', 'Request expired. Check the page before trying again.'),
+ 404,
+ );
+ if (req.url === '/learning/cancel') {
+ this.relays.delete(item.id);
+ return this.send(res, { ok: true });
+ }
+ const gate = item.payload.source.url
+ ? checkBrowserExtensionPolicy(this.policy, 'text', item.payload.source.url)
+ : { ok: true as const };
+ if (!gate.ok) {
+ this.relays.delete(item.id);
+ return this.send(res, gate, 403);
+ }
+ return this.send(
+ res,
+ item.result
+ ? { ok: true, done: true, result: item.result }
+ : { ok: true, done: false, progress: item.progress },
+ );
+ }
+ if (req.method === 'GET' && req.url === '/poll') {
+ const job = this.take(clientId);
+ if (job) return this.send(res, { job });
+ if (this.waiting.has(clientId))
+ return this.send(res, failure('BUSY', 'This profile is already polling.'), 429);
+ const cleanup = () => {
+ clearTimeout(timer);
+ if (this.waiting.get(clientId) === waiter) this.waiting.delete(clientId);
+ };
+ const waiter = () => {
+ cleanup();
+ this.send(res, { job: this.take(clientId) });
+ };
+ const timer = setTimeout(waiter, this.options.pollTimeout ?? 20000);
+ this.waiting.set(clientId, waiter);
+ res.on('close', cleanup);
+ return;
+ }
+ if (req.method !== 'POST' || !['/ack', '/authorize', '/result'].includes(req.url ?? '')) {
+ return this.send(res, failure('NOT_FOUND', 'Unknown endpoint.'), 404);
+ }
+ const b = (await this.readBody(req)).value;
+ const jobId = String(b.id);
+ const job = this.jobs.get(jobId);
+ // 迟到的完成只消除不确定性,绝不复活或返回过期结果。
+ if (req.url === '/result' && this.unconfirmedDispatches.get(jobId)?.clientId === clientId) {
+ const result = b.result as { execution?: unknown } | undefined;
+ if (
+ result &&
+ typeof result === 'object' &&
+ !Array.isArray(result) &&
+ result.execution !== 'unknown'
+ )
+ this.unconfirmedDispatches.delete(jobId);
+ return this.send(res, failure('JOB_EXPIRED', 'The operation result expired.'), 409);
+ }
+ if (
+ !job ||
+ job.clientId !== clientId ||
+ job.state !== (req.url === '/ack' ? 'delivered' : 'acknowledged')
+ ) {
+ return this.send(res, failure('JOB_EXPIRED', 'Do not execute this job.'), 409);
+ }
+ if (job.revoked && req.url !== '/result')
+ return this.send(res, this.jobFailure(job, job.revoked.error, job.revoked.message), 403);
+ if (req.url === '/ack' || req.url === '/authorize') {
+ const gate = checkBrowserExtensionPolicy(
+ this.policy,
+ job.action,
+ req.url === '/authorize' ? b.url : job.payload.url,
+ );
+ if (!gate.ok) {
+ const result = this.jobFailure(job, gate.error, gate.message);
+ this.finish(job, result);
+ return this.send(res, result, 403);
+ }
+ if (req.url === '/ack') job.state = 'acknowledged';
+ else {
+ job.authorizedUrl = typeof b.url === 'string' ? b.url : undefined;
+ // 文档已准备执行:撤销必须等待这次派发结束;单独作废结果并不能阻止 DOM。
+ if (b.dispatch === true && !job.dispatchSettled) {
+ job.dispatchSettled = new Promise((resolve) => {
+ job.settleDispatch = resolve;
+ });
+ }
+ }
+ return this.send(res, { ok: true, policy: this.policy });
+ }
+ let result: Record<string, unknown> = job.revoked
+ ? this.jobFailure(job, job.revoked.error, job.revoked.message)
+ : (b.result as Record<string, unknown>);
+ if (!result || typeof result !== 'object' || Array.isArray(result)) {
+ result = this.jobFailure(
+ job,
+ 'INVALID_RESULT',
+ 'Invalid browser result. Verify before retrying.',
+ );
+ }
+ if (job.action === 'tabs' && !result.error) {
+ const tabs = (Array.isArray(result.tabs) ? result.tabs : []).slice(0, 100) as Array<
+ Record<string, unknown>
+ >;
+ result = {
+ ...result,
+ ok: true,
+ tabs: tabs.map((t) => {
+ if (checkBrowserExtensionPolicy(this.policy, 'text', t.url).ok) return t;
+ const row: Record<string, unknown> = { id: t.id, redacted: true };
+ if (['loading', 'complete', 'unloaded'].includes(t.status as string))
+ row.status = t.status;
+ if (['ADDRESS_UNVERIFIED', 'TAB_ACCESS_FAILED'].includes(t.error as string))
+ row.error = t.error;
+ if (
+ t.error === 'ADDRESS_UNVERIFIED' &&
+ [
+ 'LOCAL_ADDRESS',
+ 'NAVIGATION_UNOBSERVED',
+ 'RESPONSE_UNOBSERVED',
+ 'PEER_ADDRESS_MISSING',
+ 'PEER_NOT_PUBLIC',
+ 'DOCUMENT_CHANGED',
+ 'DOCUMENT_UNAVAILABLE',
+ ].includes(t.reason as string)
+ ) {
+ row.reason = t.reason;
+ }
+ return row;
+ }),
+ };
+ } else if (
+ !result.error &&
+ result.url &&
+ !checkBrowserExtensionPolicy(this.policy, job.action, result.url).ok
+ ) {
+ result = this.jobFailure(
+ job,
+ 'REDIRECT_BLOCKED',
+ 'No content returned from a blocked destination.',
+ );
+ }
+ if (
+ result.error &&
+ !['not_executed', 'executed', 'unknown'].includes(result.execution as string)
+ ) {
+ result = { ...result, execution: this.jobFailure(job, '', '').execution };
+ }
+ const browserFinished =
+ !!b.result &&
+ typeof b.result === 'object' &&
+ !Array.isArray(b.result) &&
+ (b.result as { execution?: unknown }).execution !== 'unknown';
+ this.finish(job, result, browserFinished);
+ return this.send(res, { ok: true });
+ }
+
+ // ── 生命周期 ────────────────────────────────────────────────────────────
+
+ async start(): Promise<void> {
+ if (this.server) return;
+ if (this.starting) return this.starting;
+ this.starting = (async () => {
+ // 保持监听在兼容扩展扫描的十个端口内:绑到段外会让旧扩展在插件/扩展交错更新期间永久断连。
+ for (const candidate of this.options.ports ?? BROWSER_EXTENSION_DEFAULT_PORTS) {
+ const srv = http.createServer((req, res) => {
+ this.route(req, res).catch(() =>
+ this.send(res, failure('INVALID_REQUEST', 'Invalid bridge request.'), 400),
+ );
+ });
+ srv.requestTimeout = 30000;
+ srv.headersTimeout = 10000;
+ try {
+ await new Promise<void>((resolve, reject) => {
+ srv.once('error', reject);
+ srv.listen(candidate, '127.0.0.1', resolve);
+ });
+ this.server = srv;
+ const address = srv.address();
+ this.port = typeof address === 'object' && address ? address.port : candidate;
+ this.options.log?.info('browser extension bridge listening', {
+ port: this.port,
+ ghostId: this.options.ghostId,
+ });
+ return;
+ } catch (e) {
+ srv.close();
+ if ((e as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw e;
+ }
+ }
+ throw Object.assign(new Error('All browser extension loopback ports are occupied.'), {
+ code: 'BRIDGE_PORTS_BUSY',
+ });
+ })();
+ try {
+ await this.starting;
+ } finally {
+ this.starting = null;
+ }
+ }
+
+ private startFailure(e: unknown): BrowserExtensionFailure {
+ const code = (e as NodeJS.ErrnoException)?.code;
+ return failure(
+ code === 'BRIDGE_PORTS_BUSY'
+ ? 'BRIDGE_PORTS_BUSY'
+ : code === 'EACCES' || code === 'EPERM'
+ ? 'BRIDGE_LISTEN_DENIED'
+ : 'BRIDGE_START_FAILED',
+ e instanceof Error ? e.message : String(e),
+ );
+ }
+
+ /** 插件推送(或宿主恢复)站点策略;在途作业按新策略撤销,DOM 派发中的等其结束。 */
+ async setPolicy(
+ input: unknown,
+ ): Promise<
+ { ok: true; policy: BrowserExtensionPolicy } | (BrowserExtensionFailure & { applied?: true })
+ > {
+ this.policy = normalizeBrowserExtensionPolicy(input);
+ const dispatches: Array<Promise<boolean>> = [];
+ for (const job of [...this.jobs.values()]) {
+ // 撤销同时作用于原请求与其重定向目标:只按后者判会让被阻止的请求悄悄活着。
+ const original = checkBrowserExtensionPolicy(this.policy, job.action, job.payload.url);
+ const gate =
+ original.ok && job.authorizedUrl
+ ? checkBrowserExtensionPolicy(this.policy, job.action, job.authorizedUrl)
+ : original;
+ if (!gate.ok) {
+ if (job.dispatchSettled) {
+ job.revoked = gate;
+ dispatches.push(job.dispatchSettled);
+ } else {
+ this.finish(job, this.jobFailure(job, gate.error, gate.message));
+ }
+ }
+ }
+ const completed = await Promise.all(dispatches);
+ const uncertain = [...this.unconfirmedDispatches.values()].some(
+ (job) =>
+ !checkBrowserExtensionPolicy(this.policy, job.action, job.url).ok ||
+ (job.authorizedUrl &&
+ !checkBrowserExtensionPolicy(this.policy, job.action, job.authorizedUrl).ok),
+ );
+ if (completed.some((finished) => !finished) || uncertain || this.unconfirmedOverflow) {
+ return {
+ ...failure(
+ 'REVOCATION_UNCONFIRMED',
+ 'Permissions are applied, but an earlier browser action did not confirm completion. Check the page before continuing.',
+ 'unknown',
+ ),
+ applied: true,
+ };
+ }
+ return { ok: true, policy: this.policy };
+ }
+
+ getPolicy(): BrowserExtensionPolicy {
+ return this.policy;
+ }
+
+ setTrustedClients(clients: unknown): { ok: true } {
+ if (!Array.isArray(clients) || clients.length > 16) throw new Error('Invalid paired browsers.');
+ this.pins = clients.filter(
+ (c): c is BrowserExtensionTrustedClient =>
+ !!c &&
+ typeof c === 'object' &&
+ typeof (c as BrowserExtensionTrustedClient).id === 'string' &&
+ typeof (c as BrowserExtensionTrustedClient).origin === 'string' &&
+ typeof (c as BrowserExtensionTrustedClient).extensionId === 'string',
+ );
+ for (const c of this.clients.values()) c.trusted = this.approved(c);
+ return { ok: true };
+ }
+
+ private relayItem(id: string): { item: RelayItem; valid: boolean } | null {
+ const item = this.relays.get(id);
+ if (!item) return null;
+ const client = this.clients.get(item.clientId);
+ const valid =
+ !!client?.trusted &&
+ this.now() <= item.expiresAt &&
+ (!item.payload.source.url ||
+ checkBrowserExtensionPolicy(this.policy, 'text', item.payload.source.url).ok);
+ return { item, valid };
+ }
+
+ relayActive(id: string): { ok: true; active: boolean } {
+ const found = this.relayItem(id);
+ return { ok: true, active: !!found && found.valid && !found.item.result };
+ }
+
+ relayProgress(id: string, progress: unknown): { ok: true } | BrowserExtensionFailure {
+ const found = this.relayItem(id);
+ if (!found || !found.valid) return failure('REQUEST_CANCELLED', 'Request no longer active.');
+ const item = found.item;
+ const p = (progress && typeof progress === 'object' ? progress : {}) as {
+ stage?: unknown;
+ attempt?: unknown;
+ receivedChars?: unknown;
+ };
+ if (!item.result && (RELAY_PROGRESS_STAGES as readonly unknown[]).includes(p.stage)) {
+ const previous = item.progress;
+ const attempt = Number.isInteger(p.attempt)
+ ? Math.min(3, Math.max(1, p.attempt as number))
+ : previous.attempt || 1;
+ const stage = p.stage as string;
+ item.progress = {
+ stage,
+ attempt,
+ ...(Number.isSafeInteger(p.receivedChars) && (p.receivedChars as number) >= 0
+ ? { receivedChars: p.receivedChars as number }
+ : {}),
+ startedAt: previous.startedAt || item.created,
+ updatedAt:
+ previous.stage === stage && previous.attempt === attempt
+ ? previous.updatedAt
+ : this.now(),
+ };
+ }
+ return { ok: true };
+ }
+
+ relayResult(id: string, result: unknown): { ok: true } | BrowserExtensionFailure {
+ const found = this.relayItem(id);
+ if (!found || !found.valid) return failure('REQUEST_CANCELLED', 'Request no longer active.');
+ if (!found.item.result) {
+ found.item.result = result;
+ found.item.expiresAt = this.now() + RELAY_TIMING.resultRetention;
+ }
+ return { ok: true };
+ }
+
+ async status(): Promise<BrowserExtensionBridgeStatus | BrowserExtensionFailure> {
+ try {
+ await this.start();
+ } catch (e) {
+ return this.startFailure(e);
+ }
+ return {
+ ok: true,
+ version: this.options.installedVersion,
+ protocol: BROWSER_EXTENSION_PROTOCOL_NUMBER,
+ port: this.port,
+ extension_connected: this.connected().length > 0,
+ extension_ids: [...this.knownIds],
+ policy: this.policy,
+ pending: this.jobs.size,
+ clients: [...this.clients.values()]
+ .filter((c) => this.live(c))
+ .map((c) => this.publicClient(c)),
+ };
+ }
+
+ /** 当前已连接(会话就绪、存活、协议兼容)的扩展连接。 */
+ connectedClients(): BrowserExtensionClientInfo[] {
+ return this.connected().map((c) => this.publicClient(c));
+ }
+
+ /** 向扩展投递一个页面作业;按策略守门、绑定连接、一次送达、超时即 unknown。 */
+ async act(action: unknown, payloadInput: unknown = {}): Promise<BrowserExtensionJobResult> {
+ try {
+ await this.start();
+ } catch (e) {
+ return this.startFailure(e);
+ }
+ let payload: BrowserExtensionJobPayload;
+ try {
+ payload = validateBrowserExtensionJob(action, payloadInput);
+ } catch (e) {
+ return failure('INVALID_ARGS', e instanceof Error ? e.message : 'Invalid browser action.');
+ }
+ const kind = action as BrowserExtensionAction;
+ const gate = checkBrowserExtensionPolicy(this.policy, kind, payload.url);
+ if (!gate.ok) return gate;
+ const until = this.now() + (this.options.connectWait ?? 6000);
+ while (!this.connected().length && this.now() < until)
+ await new Promise((r) => setTimeout(r, 100));
+ const candidates = this.connected();
+ const client = payload.browser
+ ? candidates.find((c) => c.id === payload.browser)
+ : candidates.length === 1
+ ? candidates[0]
+ : null;
+ if (!client) {
+ return {
+ ...failure(
+ candidates.length > 1 && !payload.browser ? 'BROWSER_REQUIRED' : 'EXTENSION_DISCONNECTED',
+ candidates.length > 1
+ ? 'Choose a browser connection id; never guess the account/profile.'
+ : 'Open Cindy Chrome settings to install, enable or reconnect the extension.',
+ ),
+ clients: candidates.map((c) => this.publicClient(c)),
+ };
+ }
+ if (this.jobs.size >= 16) return failure('BRIDGE_BUSY', 'Wait for browser tasks to finish.');
+ return new Promise((resolve) => {
+ const job: Job = {
+ id: crypto.randomUUID(),
+ action: kind,
+ payload,
+ clientId: client.id,
+ state: 'queued',
+ resolve,
+ created: this.now(),
+ };
+ job.timer = setTimeout(
+ () =>
+ this.finish(
+ job,
+ this.jobFailure(
+ job,
+ 'BROWSER_TIMEOUT',
+ 'Verify an unknown operation; it will not be replayed.',
+ ),
+ ),
+ this.options.jobTimeout ?? 45000,
+ );
+ this.jobs.set(job.id, job);
+ this.waiting.get(client.id)?.();
+ });
+ }
+
+ async close(): Promise<void> {
+ this.relays.clear();
+ for (const job of [...this.jobs.values()])
+ this.finish(
+ job,
+ this.jobFailure(
+ job,
+ 'BRIDGE_STOPPED',
+ 'Check the page before repeating an interrupted action.',
+ ),
+ );
+ for (const waiter of [...this.waiting.values()]) waiter();
+ if (this.server) {
+ const s = this.server;
+ this.server = null;
+ s.closeAllConnections();
+ await new Promise<void>((r) => s.close(() => r()));
+ this.port = 0;
+ }
+ }
+}
+
+/** 一个插件只能有一份桥接;动作是否为交互由线协议判定(用于 execution 归类)。 */
+export const isBrowserExtensionInteraction = isBrowserExtensionInteractAction;
diff --git a/apps/desktop/src/main/browser-extension/native-binding.ts b/apps/desktop/src/main/browser-extension/native-binding.ts
new file mode 100644
index 0000000000..d87355423e
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/native-binding.ts
@@ -0,0 +1,184 @@
+/**
+ * 浏览器扩展的 Native Messaging 绑定(宿主侧):把插件包内的平台二进制复制到
+ * Cindy 的私有目录,向各 Chromium 浏览器注册 host manifest,并在
+ * `connections/<port>.json` 写入桥接的私有授权令牌。令牌只给本机的 native host
+ * 读,不进扩展、不进插件 KV、不进 /health 结果。
+ *
+ * 文件布局与插件时期完全相同(`<App Support>/Cindy/browser-native/`),已安装
+ * 用户升级后无需重新配对;插件与宿主交错更新期间,两份注册写的是同一份清单。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export interface NativeBindingOptions {
+ /** 注册名(身份卡 browserExtension.nativeHost.name)。 */
+ hostName: string;
+ /** 包内平台二进制目录:`<binaryDir>/<platform>-<arch>/cindy-browser-native[.exe]`。 */
+ binaryDir: string;
+ platform?: NodeJS.Platform;
+ arch?: string;
+ home?: string;
+ env?: NodeJS.ProcessEnv;
+ /** 覆盖私有目录(测试用)。 */
+ root?: string;
+ /** 覆盖浏览器 profile 目录清单(测试用)。 */
+ profiles?: string[];
+ run?: (
+ file: string,
+ args: string[],
+ options: { windowsHide: boolean; timeout: number },
+ ) => Promise<unknown>;
+}
+
+export type NativeBindingState = 'preparing' | 'ready' | 'unavailable';
+
+export interface NativeBinding {
+ readonly token: string;
+ install(
+ port: number,
+ extensionIds: readonly string[],
+ ): Promise<{ ok: true } | { ok: false; error: 'NATIVE_BINDING_UNAVAILABLE'; reason: string }>;
+ close(): Promise<void>;
+ status(): NativeBindingState;
+}
+
+export function nativeBindingRoot(
+ platform: NodeJS.Platform,
+ home: string,
+ env: NodeJS.ProcessEnv,
+): string {
+ const base =
+ platform === 'darwin'
+ ? path.join(home, 'Library/Application Support')
+ : platform === 'win32'
+ ? env.LOCALAPPDATA || path.join(home, 'AppData/Local')
+ : path.join(home, '.local/share');
+ return path.join(base, 'Cindy', 'browser-native');
+}
+
+export function createNativeBinding(options: NativeBindingOptions): NativeBinding {
+ const platform = options.platform ?? process.platform;
+ const arch = options.arch ?? process.arch;
+ const home = options.home ?? os.homedir();
+ const env = options.env ?? process.env;
+ const root = options.root ?? nativeBindingRoot(platform, home, env);
+ const token = crypto.randomBytes(32).toString('hex');
+ const run = options.run ?? (promisify(execFile) as NativeBindingOptions['run']);
+ let config: string | null = null;
+ let state: NativeBindingState = 'preparing';
+
+ async function privateDirectory(dir: string): Promise<void> {
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+ const stat = await fs.lstat(dir);
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('NATIVE_PATH_UNSAFE');
+ if (platform !== 'win32') await fs.chmod(dir, 0o700);
+ }
+
+ async function atomic(file: string, data: string | Buffer, mode = 0o600): Promise<void> {
+ const tmp = file + '.' + crypto.randomUUID() + '.tmp';
+ try {
+ await fs.writeFile(tmp, data, { flag: 'wx', mode });
+ await fs.rename(tmp, file);
+ } finally {
+ await fs.rm(tmp, { force: true });
+ }
+ }
+
+ async function install(port: number, extensionIds: readonly string[]) {
+ try {
+ await privateDirectory(root);
+ await privateDirectory(path.join(root, 'connections'));
+ const binaryName = 'cindy-browser-native' + (platform === 'win32' ? '.exe' : '');
+ const source = path.join(options.binaryDir, platform + '-' + arch, binaryName);
+ const binary = path.join(root, binaryName);
+ // 内容相同时不替换正在运行的 Windows 映像。
+ const content = await fs.readFile(source);
+ const old = await fs.readFile(binary).catch(() => null);
+ if (!old?.equals(content)) await atomic(binary, content, 0o700);
+ const manifest = {
+ name: options.hostName,
+ description: 'Cindy browser automatic key binding',
+ path: binary,
+ type: 'stdio',
+ allowed_origins: extensionIds.map((id) => 'chrome-extension://' + id + '/'),
+ };
+ if (platform === 'win32') {
+ const file = path.join(root, options.hostName + '.json');
+ await atomic(file, JSON.stringify(manifest));
+ const reg = path.join(env.SystemRoot || env.WINDIR || 'C:\\Windows', 'System32', 'reg.exe');
+ for (const vendor of [
+ 'Google\\Chrome',
+ 'Microsoft\\Edge',
+ 'BraveSoftware\\Brave-Browser',
+ ]) {
+ await run!(
+ reg,
+ [
+ 'ADD',
+ 'HKCU\\Software\\' + vendor + '\\NativeMessagingHosts\\' + options.hostName,
+ '/ve',
+ '/t',
+ 'REG_SZ',
+ '/d',
+ file,
+ '/f',
+ ],
+ { windowsHide: true, timeout: 10000 },
+ );
+ }
+ } else {
+ const profiles =
+ options.profiles ??
+ (platform === 'darwin'
+ ? [
+ 'Google/Chrome',
+ 'Google/Chrome for Testing',
+ 'Chromium',
+ 'Microsoft Edge',
+ 'BraveSoftware/Brave-Browser',
+ ].map((p) => path.join(home, 'Library/Application Support', p))
+ : [
+ 'google-chrome',
+ 'google-chrome-for-testing',
+ 'chromium',
+ 'microsoft-edge',
+ 'BraveSoftware/Brave-Browser',
+ ].map((p) => path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), p)));
+ for (const profile of profiles) {
+ const dir = path.join(profile, 'NativeMessagingHosts');
+ await privateDirectory(dir);
+ await atomic(path.join(dir, options.hostName + '.json'), JSON.stringify(manifest));
+ }
+ }
+ config = path.join(root, 'connections', port + '.json');
+ await atomic(config, JSON.stringify({ token }));
+ state = 'ready';
+ return { ok: true as const };
+ } catch (e) {
+ state = 'unavailable';
+ const code = (e as NodeJS.ErrnoException)?.code;
+ const reason =
+ code && ['EACCES', 'EPERM', 'ENOENT', 'EROFS', 'EBUSY'].includes(code)
+ ? code
+ : (e as Error)?.message === 'NATIVE_PATH_UNSAFE'
+ ? 'NATIVE_PATH_UNSAFE'
+ : 'INSTALL_FAILED';
+ return { ok: false as const, error: 'NATIVE_BINDING_UNAVAILABLE' as const, reason };
+ }
+ }
+
+ async function close(): Promise<void> {
+ if (!config) return;
+ const data = await fs.readFile(config, 'utf8').catch(() => '');
+ // 只删自己写的授权;同端口被另一实例接管时保留它的令牌。
+ if (data === JSON.stringify({ token })) await fs.rm(config, { force: true });
+ config = null;
+ }
+
+ return { token, install, close, status: () => state };
+}
diff --git a/apps/desktop/src/main/browser-extension/policy.ts b/apps/desktop/src/main/browser-extension/policy.ts
new file mode 100644
index 0000000000..15f87f826a
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/policy.ts
@@ -0,0 +1,554 @@
+/**
+ * 浏览器扩展站点策略(宿主侧实现)。
+ *
+ * 与扩展内的 policy 实现是同一套语义:扩展在页面侧再查一遍,宿主在分发作业前
+ * 查一遍,两侧都必须对同一 URL 给出同样的结论。改动任何判据时两侧一起改。
+ *
+ * - READ 动作默认开放公网,INTERACT 动作按 interact.allow / block 守门;
+ * - 只接受无内嵌凭证的公网 http(s) URL,本机与私网地址一律拒绝(扩展不是
+ * 内网入口;Browser Use 的专用浏览器才允许本机可达的内网);
+ * - 交给模型之前的每个 URL 都过 redactUrl:OAuth code、重置令牌、implicit-flow
+ * fragment 与 Basic Auth userinfo 不离开本机。
+ */
+
+export const BROWSER_EXTENSION_READ_ACTIONS = [
+ 'tabs',
+ 'navigate',
+ 'snapshot',
+ 'extract',
+ 'text',
+ 'content',
+] as const;
+export const BROWSER_EXTENSION_INTERACT_ACTIONS = [
+ 'click',
+ 'type',
+ 'press',
+ 'select',
+ 'hover',
+ 'scroll',
+] as const;
+export const BROWSER_EXTENSION_EXTRACT_ATTRIBUTES = [
+ 'href',
+ 'src',
+ 'datetime',
+ 'title',
+ 'alt',
+ 'aria-label',
+ 'role',
+] as const;
+
+export type BrowserExtensionReadAction = (typeof BROWSER_EXTENSION_READ_ACTIONS)[number];
+export type BrowserExtensionInteractAction = (typeof BROWSER_EXTENSION_INTERACT_ACTIONS)[number];
+export type BrowserExtensionAction = BrowserExtensionReadAction | BrowserExtensionInteractAction;
+
+export interface BrowserExtensionPolicy {
+ read: { block: string[] };
+ interact: { allow: string[]; block: string[] };
+}
+
+export interface BrowserExtensionPolicyDenial {
+ ok: false;
+ error: string;
+ message: string;
+ host?: string;
+ execution: 'not_executed';
+}
+
+export type BrowserExtensionPolicyVerdict =
+ { ok: true; host?: string } | BrowserExtensionPolicyDenial;
+
+export function isBrowserExtensionReadAction(
+ action: unknown,
+): action is BrowserExtensionReadAction {
+ return (BROWSER_EXTENSION_READ_ACTIONS as readonly unknown[]).includes(action);
+}
+
+export function isBrowserExtensionInteractAction(
+ action: unknown,
+): action is BrowserExtensionInteractAction {
+ return (BROWSER_EXTENSION_INTERACT_ACTIONS as readonly unknown[]).includes(action);
+}
+
+export function defaultBrowserExtensionPolicy(): BrowserExtensionPolicy {
+ return { read: { block: [] }, interact: { allow: ['*'], block: [] } };
+}
+
+export function normalizeBrowserExtensionHost(value: unknown): string {
+ if (typeof value !== 'string') throw new Error('Enter a domain, for example example.test.');
+ const text = value.trim().toLowerCase();
+ const exact = text.startsWith('=');
+ const raw = exact ? text.slice(1) : text.replace(/^\*\./, '');
+ if (/^\[[0-9a-f:.]+\]$/.test(raw)) {
+ const host = new URL('https://' + raw).hostname;
+ if (isLocalBrowserHost(host)) throw new Error('Local and private addresses are not supported.');
+ return (exact ? '=' : '') + host;
+ }
+ if (!raw || /[\s/@:?#\\]/.test(raw))
+ throw new Error('Enter a domain only, without a URL, port or path.');
+ const host = new URL('https://' + raw).hostname;
+ // eslint-disable-next-line no-control-regex
+ if (host !== raw && !/[^\x00-\x7f]/.test(raw)) throw new Error('Invalid domain.');
+ if (
+ host.length > 253 ||
+ !host.includes('.') ||
+ host.endsWith('.') ||
+ host.split('.').some((part) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(part))
+ ) {
+ throw new Error('Invalid domain.');
+ }
+ if (isLocalBrowserHost(host)) throw new Error('Local and private addresses are not supported.');
+ return (exact ? '=' : '') + host;
+}
+
+function publicLiteral(ip: string): boolean {
+ if (/^\d+\.\d+\.\d+\.\d+$/.test(ip)) {
+ const [a, b] = ip.split('.').map(Number);
+ return (
+ a !== 0 &&
+ a !== 10 &&
+ a !== 127 &&
+ a < 224 &&
+ !(a === 169 && b === 254) &&
+ !(a === 172 && b >= 16 && b <= 31) &&
+ !(a === 192 && b === 168) &&
+ !(a === 100 && b >= 64 && b <= 127)
+ );
+ }
+ try {
+ const host = new URL('http://[' + ip + ']/').hostname.slice(1, -1);
+ const [first, second] = host.split(':').map((x) => parseInt(x || '0', 16));
+ return (
+ first >= 0x2000 &&
+ first <= 0x3fff &&
+ first !== 0x2002 &&
+ first !== 0x3fff &&
+ !(first === 0x2001 && (second < 0x200 || second === 0xdb8))
+ );
+ } catch {
+ return false;
+ }
+}
+
+export function isLocalBrowserHost(host: string): boolean {
+ if (
+ host === 'localhost' ||
+ host.endsWith('.localhost') ||
+ host.endsWith('.local') ||
+ host.endsWith('.internal')
+ ) {
+ return true;
+ }
+ const ip =
+ host.startsWith('[') && host.endsWith(']')
+ ? host.slice(1, -1)
+ : host.includes(':')
+ ? host
+ : /^\d+\.\d+\.\d+\.\d+$/.test(host)
+ ? host
+ : null;
+ if (ip) return !publicLiteral(ip);
+ return !host.includes('.');
+}
+
+export function browserExtensionHostMatches(host: string, pattern: string): boolean {
+ return (
+ pattern === '*' ||
+ (pattern.startsWith('=')
+ ? host === pattern.slice(1)
+ : host === pattern || host.endsWith('.' + pattern))
+ );
+}
+
+export function normalizeBrowserExtensionPolicy(input: unknown): BrowserExtensionPolicy {
+ const p = input as {
+ read?: { block?: unknown };
+ interact?: { allow?: unknown; block?: unknown };
+ } | null;
+ if (!p || !p.read || !p.interact)
+ throw new Error('Invalid policy. Reload settings before saving.');
+ const list = (items: unknown, wildcard = false): string[] => {
+ if (!Array.isArray(items) || items.length > 200)
+ throw new Error('Each policy list must contain at most 200 domains.');
+ return [
+ ...new Set(
+ items.map((h) => (wildcard && h === '*' ? '*' : normalizeBrowserExtensionHost(h))),
+ ),
+ ];
+ };
+ return {
+ read: { block: list(p.read.block) },
+ interact: { allow: list(p.interact.allow, true), block: list(p.interact.block ?? []) },
+ };
+}
+
+export function checkBrowserExtensionPolicy(
+ policy: BrowserExtensionPolicy,
+ action: unknown,
+ url: unknown,
+): BrowserExtensionPolicyVerdict {
+ const deny = (error: string, message: string, host?: string): BrowserExtensionPolicyDenial => ({
+ ok: false,
+ error,
+ message,
+ ...(host !== undefined ? { host } : {}),
+ execution: 'not_executed',
+ });
+ if (!isBrowserExtensionReadAction(action) && !isBrowserExtensionInteractAction(action)) {
+ return deny('INVALID_ACTION', 'Choose a supported browser action.');
+ }
+ if (action === 'tabs') return { ok: true };
+ let u: URL;
+ try {
+ u = new URL(String(url));
+ } catch {
+ return deny('INVALID_URL', 'Provide a full HTTP or HTTPS URL.');
+ }
+ if (
+ !['http:', 'https:'].includes(u.protocol) ||
+ u.username ||
+ u.password ||
+ isLocalBrowserHost(u.hostname.replace(/\.$/, ''))
+ ) {
+ return deny(
+ 'URL_NOT_ALLOWED',
+ 'Only public HTTP/HTTPS URLs without embedded credentials are supported.',
+ );
+ }
+ const host = u.hostname.toLowerCase().replace(/\.$/, '');
+ if (policy.read.block.some((p) => browserExtensionHostMatches(host, p))) {
+ return deny(
+ 'READ_BLOCKED',
+ 'This site is on the read block list. Review the site policy in plugin settings.',
+ host,
+ );
+ }
+ if (
+ isBrowserExtensionInteractAction(action) &&
+ (!policy.interact.allow.some((p) => browserExtensionHostMatches(host, p)) ||
+ policy.interact.block.some((p) => browserExtensionHostMatches(host, p)))
+ ) {
+ return deny(
+ 'INTERACT_NOT_ALLOWED',
+ 'Ask the user to allow this exact site before clicking, typing or searching.',
+ host,
+ );
+ }
+ return { ok: true, host };
+}
+
+export interface BrowserExtensionJobPayload {
+ url?: string;
+ browser?: string;
+ limit?: number;
+ maxChars?: number;
+ waitMs?: number;
+ host?: string;
+ selector?: string;
+ from?: string;
+ ref?: string;
+ text?: string;
+ key?: string;
+ waitFor?: string;
+ emptySelector?: string;
+ after?: string;
+ values?: string[];
+ fields?: Record<string, string | { selector: string; attr?: string }>;
+ multiple?: boolean;
+ submit?: boolean;
+ [key: string]: unknown;
+}
+
+/** 校验一个作业载荷(与扩展侧 validate 同判据);非法时抛出人话错误。 */
+export function validateBrowserExtensionJob(
+ action: unknown,
+ input: unknown = {},
+): BrowserExtensionJobPayload {
+ if (!isBrowserExtensionReadAction(action) && !isBrowserExtensionInteractAction(action)) {
+ throw new Error('Unsupported browser action.');
+ }
+ const payload = (
+ input && typeof input === 'object' && !Array.isArray(input) ? input : {}
+ ) as BrowserExtensionJobPayload;
+ if (action !== 'tabs' && (typeof payload.url !== 'string' || payload.url.length > 8192)) {
+ throw new Error('Provide a full URL of at most 8192 characters.');
+ }
+ if (
+ payload.browser != null &&
+ (typeof payload.browser !== 'string' || payload.browser.length > 128)
+ ) {
+ throw new Error('Invalid browser connection id.');
+ }
+ if (
+ payload.limit != null &&
+ (!Number.isInteger(payload.limit) || payload.limit < 1 || payload.limit > 100)
+ ) {
+ throw new Error('Limit must be 1–100.');
+ }
+ if (
+ payload.maxChars != null &&
+ (!Number.isInteger(payload.maxChars) || payload.maxChars < 256 || payload.maxChars > 30000)
+ ) {
+ throw new Error('maxChars must be 256–30000.');
+ }
+ if (
+ payload.waitMs != null &&
+ (!Number.isInteger(payload.waitMs) || payload.waitMs < 0 || payload.waitMs > 15000)
+ ) {
+ throw new Error('waitMs must be 0–15000.');
+ }
+ if (payload.host != null) normalizeBrowserExtensionHost(payload.host);
+ for (const key of [
+ 'selector',
+ 'from',
+ 'ref',
+ 'text',
+ 'key',
+ 'waitFor',
+ 'emptySelector',
+ 'after',
+ ] as const) {
+ const value = payload[key];
+ if (
+ value != null &&
+ (typeof value !== 'string' || value.length > (key === 'text' ? 16000 : 2000))
+ ) {
+ throw new Error('Invalid ' + key + '.');
+ }
+ }
+ if (
+ ['click', 'type', 'select', 'hover'].includes(action as string) &&
+ !payload.ref &&
+ !payload.selector
+ ) {
+ throw new Error('Provide a fresh snapshot ref or CSS selector.');
+ }
+ if (action === 'type' && typeof payload.text !== 'string') {
+ throw new Error('Typing requires text (an empty string clears the field).');
+ }
+ if (action === 'press' && !payload.key) throw new Error('Provide the key to press.');
+ if (
+ action === 'select' &&
+ (!Array.isArray(payload.values) ||
+ payload.values.length > 100 ||
+ payload.values.some((v) => typeof v !== 'string' || v.length > 2000))
+ ) {
+ throw new Error('Provide an array of option values.');
+ }
+ if (action === 'extract') {
+ const fields = payload.fields;
+ if (
+ !fields ||
+ typeof fields !== 'object' ||
+ Array.isArray(fields) ||
+ !Object.keys(fields).length ||
+ Object.keys(fields).length > 30
+ ) {
+ throw new Error('Extract requires 1–30 fields.');
+ }
+ // 与扩展侧同判据:字段名不得含控制字符。
+ // eslint-disable-next-line no-control-regex
+ if (Object.keys(fields).some((k) => !k || k.length > 32 || /[\x00-\x1f]/.test(k))) {
+ throw new Error('Field names must contain 1–32 printable characters.');
+ }
+ for (const spec of Object.values(fields)) {
+ const invalid =
+ typeof spec === 'string'
+ ? !spec || spec.length > 2000
+ : !spec ||
+ typeof spec.selector !== 'string' ||
+ !spec.selector ||
+ spec.selector.length > 2000 ||
+ (spec.attr != null &&
+ !(BROWSER_EXTENSION_EXTRACT_ATTRIBUTES as readonly string[]).includes(spec.attr));
+ if (invalid) {
+ throw new Error(
+ 'Each field needs a CSS selector; attr may only be href, src, datetime, title, alt, aria-label or role.',
+ );
+ }
+ }
+ if (payload.after != null && !payload.multiple)
+ throw new Error('after requires multiple records.');
+ }
+ return payload;
+}
+
+// ── URL 脱敏(与扩展侧逐字同判据)──────────────────────────────────────────
+
+const CREDENTIAL_WORDS = new Set([
+ 'code',
+ 'token',
+ 'secret',
+ 'key',
+ 'apikey',
+ 'password',
+ 'passwd',
+ 'pwd',
+ 'pass',
+ 'session',
+ 'sessionid',
+ 'sid',
+ 'state',
+ 'nonce',
+ 'auth',
+ 'authorization',
+ 'signature',
+ 'sig',
+ 'otp',
+ 'pin',
+ 'ticket',
+ 'assertion',
+ 'saml',
+ 'sso',
+ 'reset',
+ 'invite',
+ 'verifier',
+ 'challenge',
+ 'access',
+ 'refresh',
+ 'bearer',
+ 'unlock',
+ 'recover',
+ 'recovery',
+ 'magic',
+ 'invitation',
+ 'activation',
+ 'verification',
+ 'credential',
+ 'credentials',
+]);
+const CONTEXT_WORDS = new Set([
+ 'reset',
+ 'verify',
+ 'verification',
+ 'confirm',
+ 'confirmation',
+ 'activate',
+ 'activation',
+ 'invite',
+ 'magic',
+ 'auth',
+ 'authenticate',
+ 'authorize',
+ 'unlock',
+ 'recover',
+ 'recovery',
+ 'password',
+ 'passcode',
+ 'signin',
+ 'signup',
+ 'login',
+ 'callback',
+ 'redirect',
+ 'token',
+]);
+const MAX_DECODE_PASSES = 4;
+const CREDENTIAL_MIN_LENGTH = 16;
+
+function normalizeEncoding(text: string): string {
+ let current = text;
+ for (let i = 0; i < MAX_DECODE_PASSES; i++) {
+ let next: string;
+ try {
+ next = decodeURIComponent(current);
+ } catch {
+ break;
+ }
+ if (next === current) break;
+ current = next;
+ }
+ return current;
+}
+
+const words = (text: string): string[] =>
+ text
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+ .toLowerCase()
+ .split(/[^a-z0-9]+/)
+ .filter(Boolean);
+
+const credentialKey = (key: string): boolean => {
+ const decoded = normalizeEncoding(key);
+ const parts = words(decoded.replace(/([a-z])([0-9])/g, '$1 $2'));
+ return parts.length > 0 && parts.some((word) => CREDENTIAL_WORDS.has(word));
+};
+
+const opaque = (value: string): boolean =>
+ value.length >= 32 && /^[A-Za-z0-9._~+/=-]+$/.test(value);
+
+function redactSegments(path: string): string {
+ const segments = path.split('/');
+ let context = false;
+ let changed = false;
+ for (let i = 0; i < segments.length; i++) {
+ const decoded = normalizeEncoding(segments[i]);
+ const parts = words(decoded);
+ if (parts.some((word) => CONTEXT_WORDS.has(word))) {
+ context = true;
+ const remainder = parts.filter((word) => !CONTEXT_WORDS.has(word)).join('');
+ if (remainder.length >= CREDENTIAL_MIN_LENGTH) {
+ segments[i] = 'REDACTED';
+ changed = true;
+ }
+ continue;
+ }
+ if (context && decoded.length >= CREDENTIAL_MIN_LENGTH) {
+ segments[i] = 'REDACTED';
+ changed = true;
+ }
+ }
+ return changed ? segments.join('/') : path;
+}
+
+function sanitizeNested(decoded: string): string {
+ if (/^https?:\/\//i.test(decoded)) return redactBrowserUrl(decoded);
+ if (decoded.startsWith('/')) return redactSegments(decoded);
+ return decoded;
+}
+
+/** 交给模型前的最后一道门:页面 URL、标签页 URL、链接与提取字段里的凭证都在这里抹掉。 */
+export function redactBrowserUrl<T>(raw: T): T;
+export function redactBrowserUrl(raw: unknown): unknown {
+ if (typeof raw !== 'string') return raw;
+ let u: URL;
+ try {
+ u = new URL(raw);
+ } catch {
+ return raw;
+ }
+ let changed = false;
+ if (u.username || u.password) {
+ u.username = '';
+ u.password = '';
+ changed = true;
+ }
+ for (const [key, value] of [...u.searchParams]) {
+ const decoded = normalizeEncoding(value);
+ if (credentialKey(key) || opaque(decoded)) {
+ u.searchParams.set(key, 'REDACTED');
+ changed = true;
+ continue;
+ }
+ const nested = sanitizeNested(decoded);
+ if (nested !== decoded) {
+ u.searchParams.set(key, nested);
+ changed = true;
+ }
+ }
+ const fragment = u.hash ? u.hash.slice(1) : '';
+ if (fragment && normalizeEncoding(fragment).includes('=')) {
+ u.hash = '#REDACTED';
+ changed = true;
+ } else if (fragment) {
+ const redacted = redactSegments(fragment);
+ if (redacted !== fragment) {
+ u.hash = '#' + redacted;
+ changed = true;
+ }
+ }
+ const redactedPath = redactSegments(u.pathname);
+ if (redactedPath !== u.pathname) {
+ u.pathname = redactedPath;
+ changed = true;
+ }
+ return changed ? u.href : raw;
+}
diff --git a/apps/desktop/src/main/browser-extension/relay-protocol.ts b/apps/desktop/src/main/browser-extension/relay-protocol.ts
new file mode 100644
index 0000000000..bb711bfa78
--- /dev/null
+++ b/apps/desktop/src/main/browser-extension/relay-protocol.ts
@@ -0,0 +1,256 @@
+/**
+ * 扩展发起的转交请求(线协议里的 `/learning/*` 通道):宿主只负责形状校验、
+ * 超时预算和排队上限,业务处理(翻译、字幕、生词本)由声明 browserExtension
+ * 的插件完成。判据与扩展侧 learning-core 保持一致:宿主拒绝的请求,扩展侧
+ * 本来也不会发;宿主放行的请求,插件再按业务校验一次。
+ */
+
+export const RELAY_TIMING = Object.freeze({
+ model: 240_000,
+ cancel: 15_000,
+ queue: 30_000,
+ transport: 30_000,
+ resultRetention: 330_000,
+});
+
+const OPERATIONS = new Set([
+ 'translate',
+ 'explain',
+ 'summary',
+ 'conversation',
+ 'save',
+ 'list',
+ 'remove',
+ 'review',
+ 'import',
+ 'preferences',
+ 'config',
+ 'task',
+ 'subtitles',
+ 'subtitle-document',
+ 'subtitle-cache-clear',
+]);
+
+const MODEL_OPERATIONS = new Set([
+ 'subtitles',
+ 'subtitle-document',
+ 'translate',
+ 'explain',
+ 'summary',
+ 'conversation',
+ 'task',
+]);
+
+const BASE_LANGUAGES = [
+ 'auto',
+ 'en',
+ 'zh-CN',
+ 'zh-TW',
+ 'ja',
+ 'ko',
+ 'fr',
+ 'de',
+ 'es',
+ 'it',
+ 'pt',
+ 'ru',
+ 'ar',
+ 'hi',
+ 'th',
+ 'vi',
+];
+const ISO_LANGUAGES =
+ 'aa ab ae af ak am an ar as av ay az ba be bg bh bi bm bn bo br bs ca ce ch co cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr fy ga gd gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is it iu ja jv ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln lo lt lu lv mg mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny oc oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg si sk sl sm sn so sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ty ug uk ur uz ve vi vo wa wo xh yi yo za zu'.split(
+ ' ',
+ );
+const LANGUAGES = new Set([...BASE_LANGUAGES, ...ISO_LANGUAGES]);
+
+const CUSTOM_TARGET_RE = /^custom:[\p{L}\p{M}][\p{L}\p{M}\p{N} ()’'·-]{0,79}$/u;
+
+export interface RelaySource {
+ url: string;
+ title: string;
+ time?: number;
+}
+
+export interface RelayRequest {
+ op: string;
+ source: RelaySource;
+ [key: string]: unknown;
+}
+
+function validTarget(value: unknown): value is string {
+ return (
+ typeof value === 'string' &&
+ ((LANGUAGES.has(value) && value !== 'auto') || CUSTOM_TARGET_RE.test(value))
+ );
+}
+
+function string(value: unknown, max: number, required = false): string {
+ if (typeof value !== 'string' || value.length > max || (required && !value.trim()))
+ throw new Error('INVALID_INPUT');
+ return value;
+}
+
+function source(value: unknown): RelaySource {
+ if (!value || typeof value !== 'object') return { url: '', title: '' };
+ const raw = value as { url?: unknown; title?: unknown; time?: unknown };
+ const url = string(raw.url ?? '', 8192);
+ const title = string(raw.title ?? '', 500);
+ if (url && !/^https?:$/.test(new URL(url).protocol)) throw new Error('INVALID_SOURCE');
+ const time = raw.time;
+ if (
+ time !== undefined &&
+ (typeof time !== 'number' || !Number.isFinite(time) || time < 0 || time > 864000)
+ ) {
+ throw new Error('INVALID_TIME');
+ }
+ return {
+ url: url ? new URL(url).href : '',
+ title,
+ ...(time === undefined ? {} : { time: time as number }),
+ };
+}
+
+interface SubtitleWord {
+ text: string;
+ start: number;
+ end: number;
+ breakBefore: boolean;
+}
+
+/** 校验转交请求;非法时抛出 Error(code)。返回值只含校验过的字段。 */
+export function validateRelayRequest(input: unknown): RelayRequest {
+ const raw = (input && typeof input === 'object' ? input : null) as Record<string, unknown> | null;
+ if (!raw || typeof raw.op !== 'string' || !OPERATIONS.has(raw.op))
+ throw new Error('INVALID_OPERATION');
+ const out: RelayRequest = { op: raw.op, source: source(raw.source) };
+ if (raw.target !== undefined) {
+ if (!validTarget(raw.target)) throw new Error('INVALID_LANGUAGE');
+ out.target = raw.target;
+ }
+ if (raw.language !== undefined) {
+ if (typeof raw.language !== 'string' || !LANGUAGES.has(raw.language))
+ throw new Error('INVALID_LANGUAGE');
+ out.language = raw.language;
+ }
+ const editorial = raw.op === 'subtitles' && raw.editorial === true;
+ const limits: Array<[string, number]> = [
+ ['text', 20000],
+ ['translation', 20000],
+ ['context', raw.op === 'subtitle-document' || editorial ? 8000 : 4000],
+ ['query', 200],
+ ['scenario', 1000],
+ ['instruction', 4000],
+ ];
+ for (const [key, max] of limits) if (raw[key] !== undefined) out[key] = string(raw[key], max);
+ const text = out.text as string | undefined;
+ if (
+ ['translate', 'explain', 'summary', 'conversation', 'save', 'task'].includes(out.op) &&
+ !text?.trim() &&
+ !raw.texts
+ ) {
+ throw new Error('EMPTY_TEXT');
+ }
+ if (raw.texts !== undefined) {
+ if (
+ out.op !== 'translate' ||
+ !Array.isArray(raw.texts) ||
+ !raw.texts.length ||
+ raw.texts.length > 24
+ ) {
+ throw new Error('INVALID_BATCH');
+ }
+ const texts = raw.texts.map((x) => string(x, 4000, true));
+ if (texts.join('').length > 20000) throw new Error('BATCH_TOO_LARGE');
+ out.texts = texts;
+ }
+ if (out.op === 'subtitle-document' && !text?.trim()) throw new Error('EMPTY_TEXT');
+ if (out.op === 'subtitles') {
+ out.editorial = editorial;
+ const wordsRaw = raw.words;
+ if (!Array.isArray(wordsRaw) || !wordsRaw.length || wordsRaw.length > (editorial ? 360 : 240))
+ throw new Error('INVALID_BATCH');
+ const words: SubtitleWord[] = wordsRaw.map(
+ (w: { text?: unknown; start?: unknown; end?: unknown; breakBefore?: unknown }, i) => {
+ const wordText = string(w?.text, 500, true);
+ const start = w?.start;
+ const end = w?.end;
+ const previousEnd = (wordsRaw[i - 1] as { end?: unknown } | undefined)?.end;
+ if (
+ typeof start !== 'number' ||
+ typeof end !== 'number' ||
+ !Number.isFinite(start) ||
+ !Number.isFinite(end) ||
+ start < 0 ||
+ end <= start ||
+ end > 864000 ||
+ (i > 0 && (typeof previousEnd !== 'number' || start < previousEnd - 0.001))
+ ) {
+ throw new Error('INVALID_TIME');
+ }
+ return { text: wordText, start, end, breakBefore: w?.breakBefore === true };
+ },
+ );
+ if (words.map((w) => w.text).join('').length > 12000) throw new Error('BATCH_TOO_LARGE');
+ out.words = words;
+ if (raw.nextStart !== undefined) {
+ const nextStart = raw.nextStart;
+ if (
+ typeof nextStart !== 'number' ||
+ !Number.isFinite(nextStart) ||
+ nextStart < words[words.length - 1].end ||
+ nextStart > 864000
+ ) {
+ throw new Error('INVALID_TIME');
+ }
+ out.nextStart = nextStart;
+ }
+ }
+ if (raw.id !== undefined) out.id = string(raw.id, 100, true);
+ if (['remove', 'review', 'task'].includes(out.op) && !out.id) throw new Error('INVALID_ID');
+ if (out.op === 'task' && !/^[a-f0-9-]{36}$/.test(out.id as string)) throw new Error('INVALID_ID');
+ if (out.op === 'review') {
+ if (!['again', 'hard', 'good', 'easy'].includes(raw.rating as string))
+ throw new Error('INVALID_RATING');
+ out.rating = raw.rating;
+ }
+ if (out.op === 'import') {
+ if (!Array.isArray(raw.entries) || raw.entries.length > 500)
+ throw new Error('IMPORT_TOO_LARGE');
+ out.entries = raw.entries.map((entry) =>
+ validateRelayRequest({ ...(entry as object), op: 'save' }),
+ );
+ }
+ if (out.op === 'list') {
+ out.offset = Number.isInteger(raw.offset) && (raw.offset as number) >= 0 ? raw.offset : 0;
+ out.limit = Number.isInteger(raw.limit) ? Math.min(100, Math.max(1, raw.limit as number)) : 50;
+ out.due = raw.due === true;
+ }
+ return out;
+}
+
+/** 一个转交请求允许吊多久:模型类请求按尝试次数预留两槽调度时间,其余只留传输预算。 */
+export function relayRequestTimeout(request: RelayRequest): number {
+ if (!MODEL_OPERATIONS.has(request.op)) return RELAY_TIMING.transport;
+ const attempts =
+ request.op === 'subtitles' ? (request.editorial ? 2 : 3) : request.op === 'translate' ? 2 : 1;
+ return (
+ attempts * (2 * (RELAY_TIMING.model + RELAY_TIMING.cancel) + RELAY_TIMING.queue) +
+ RELAY_TIMING.transport
+ );
+}
+
+export const RELAY_PROGRESS_STAGES = [
+ 'accepted',
+ 'opening-task',
+ 'submitting-task',
+ 'stopping',
+ 'cache',
+ 'queued',
+ 'waiting-previous',
+ 'model',
+ 'generating',
+ 'validating',
+ 'saving',
+] as const;
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/browserExtensionSlot.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/browserExtensionSlot.test.ts
new file mode 100644
index 0000000000..fc288459f2
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/__tests__/browserExtensionSlot.test.ts
@@ -0,0 +1,371 @@
+/**
+ * browserExtensionSlot.test — 浏览器扩展槽(browserExtension)的假 deps 单测。
+ *
+ * 测试价值
+ * - 生产入口与可观察结果:GhostBrowserExtensionSlot.reconcile / handleRequest / getPageControl;
+ * 桥接按插件启停、native host 注册、策略持久化与恢复、转交事件投递与离线回退。
+ * - 规则依据:docs/dev-rules/plugin-security-and-authoring.md(能力声明即授权边界;
+ * 停用/卸载即休眠)与 2026-10-27 桥接迁入宿主的决定(翻译等转交必须到达插件)。
+ * - 现有覆盖缺口:新槽。
+ * - 最小失败输入:未声明能力的插件发请求;策略文件存在但桥接未恢复;逻辑页离线且拉起失败。
+ * - tier:unit(假桥接、临时目录);实测耗时 < 1 秒。
+ */
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+ BrowserExtensionBridgeOptions,
+ BrowserExtensionRelayNotice,
+} from '../../browser-extension/bridge';
+import { defaultBrowserExtensionPolicy } from '../../browser-extension/policy';
+import type { InstalledGhost } from '../../../shared/ghost';
+import { GhostBrowserExtensionSlot, type BrowserExtensionSlotDeps } from '../browserExtensionSlot';
+
+const CHROME_ID = 'a'.repeat(32);
+
+function extGhost(
+ options: {
+ id?: string;
+ enabled?: boolean;
+ declare?: boolean;
+ pageControl?: boolean;
+ nativeHost?: boolean;
+ version?: string;
+ } = {},
+): InstalledGhost {
+ const id = options.id ?? 'ext-ghost';
+ return {
+ manifest: {
+ schemaVersion: 3,
+ id,
+ name: 'Ext Ghost',
+ version: options.version ?? '1.0.0',
+ entry: 'main.js',
+ ...(options.declare !== false
+ ? {
+ browserExtension: {
+ protocol: 'cindy-browser-extension/3',
+ extensionIds: [CHROME_ID],
+ ...(options.nativeHost !== false
+ ? { nativeHost: { name: 'com.example.browser', binary: 'native-host/bin' } }
+ : {}),
+ ...(options.pageControl !== false ? { pageControl: true as const } : {}),
+ },
+ }
+ : {}),
+ },
+ dir: `/fake/${id}`,
+ instanceKey: `_root__${id}`,
+ enabled: options.enabled ?? true,
+ approval: { state: 'approved', revision: 1 },
+ } as unknown as InstalledGhost;
+}
+
+class FakeBridge {
+ started = false;
+ closed = false;
+ listeningPort = 0;
+ policy = defaultBrowserExtensionPolicy();
+ calls: Array<[string, unknown[]]> = [];
+ constructor(readonly options: BrowserExtensionBridgeOptions) {}
+ async start() {
+ this.started = true;
+ this.listeningPort = 18810;
+ }
+ async close() {
+ this.closed = true;
+ }
+ async status() {
+ return {
+ ok: true as const,
+ version: '0',
+ protocol: 3,
+ port: this.listeningPort,
+ extension_connected: true,
+ extension_ids: [CHROME_ID],
+ policy: this.policy,
+ pending: 0,
+ clients: [],
+ };
+ }
+ connectedClients() {
+ return [];
+ }
+ async act(action: unknown, payload: unknown) {
+ this.calls.push(['act', [action, payload]]);
+ return { ok: true, text: 'hello' };
+ }
+ async setPolicy(policy: unknown) {
+ this.calls.push(['setPolicy', [policy]]);
+ this.policy = policy as typeof this.policy;
+ return { ok: true as const, policy: this.policy };
+ }
+ setTrustedClients(clients: unknown) {
+ this.calls.push(['setTrustedClients', [clients]]);
+ return { ok: true as const };
+ }
+ relayActive(id: string) {
+ this.calls.push(['relayActive', [id]]);
+ return { ok: true as const, active: true };
+ }
+ relayProgress(id: string, progress: unknown) {
+ this.calls.push(['relayProgress', [id, progress]]);
+ return { ok: true as const };
+ }
+ relayResult(id: string, result: unknown) {
+ this.calls.push(['relayResult', [id, result]]);
+ return { ok: true as const };
+ }
+ emitRelay(notice: BrowserExtensionRelayNotice) {
+ this.options.onRelay?.(notice);
+ }
+}
+
+const dirs: string[] = [];
+afterEach(async () => {
+ await Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+async function makeSlot(
+ overrides: Partial<BrowserExtensionSlotDeps> = {},
+ ghosts: InstalledGhost[] = [extGhost()],
+) {
+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-browser-extension-slot-'));
+ dirs.push(dir);
+ const bridges: FakeBridge[] = [];
+ const natives: Array<{
+ token: string;
+ install: ReturnType<typeof vi.fn>;
+ close: ReturnType<typeof vi.fn>;
+ status: () => 'ready';
+ }> = [];
+ const sent: Array<[string, unknown]> = [];
+ const deps: BrowserExtensionSlotDeps = {
+ getGhost: (id) => ghosts.find((g) => g.instanceKey === id || g.manifest.id === id) ?? null,
+ sendToGhost: vi.fn((ghostId, payload) => {
+ sent.push([ghostId, payload]);
+ return true;
+ }),
+ policyDir: () => dir,
+ ownerScopeKey: () => 'owner-a',
+ createBridge: (options) => {
+ const bridge = new FakeBridge(options);
+ bridges.push(bridge);
+ return bridge as unknown as ReturnType<NonNullable<BrowserExtensionSlotDeps['createBridge']>>;
+ },
+ createNativeBinding: () => {
+ const native = {
+ token: 'f'.repeat(64),
+ install: vi.fn(async () => ({ ok: true as const })),
+ close: vi.fn(async () => undefined),
+ status: () => 'ready' as const,
+ };
+ natives.push(native);
+ return native;
+ },
+ ...overrides,
+ };
+ const slot = new GhostBrowserExtensionSlot(deps);
+ // 桥接就绪链里有真实文件读取(恢复策略),给几个事件循环周期让它落定。
+ const settle = () => new Promise((r) => setTimeout(r, 25));
+ return { slot, deps, bridges, natives, sent, dir, ghosts, settle };
+}
+
+describe('browserExtensionSlot · 桥接随花名册启停', () => {
+ it('已启用且声明能力的插件各开一份桥接并注册 native host;停用即关;换版即重建', async () => {
+ const ghosts = [
+ extGhost(),
+ extGhost({ id: 'plain', declare: false }),
+ extGhost({ id: 'off', enabled: false }),
+ ];
+ const { slot, bridges, natives, settle } = await makeSlot({}, ghosts);
+ slot.reconcile(ghosts);
+ await settle();
+ expect(bridges).toHaveLength(1);
+ expect(bridges[0].options).toMatchObject({
+ ghostId: 'ext-ghost',
+ installedVersion: '1.0.0',
+ extensionIds: [CHROME_ID],
+ nativeToken: 'f'.repeat(64),
+ });
+ expect(bridges[0].started).toBe(true);
+ expect(natives[0].install).toHaveBeenCalledWith(18810, [CHROME_ID]);
+ expect(slot.getPageControl()).toMatchObject({ ghostId: 'ext-ghost', pluginName: 'Ext Ghost' });
+ // 幂等:同一份花名册不重建。
+ slot.reconcile(ghosts);
+ await settle();
+ expect(bridges).toHaveLength(1);
+ // 换版:关旧开新。
+ const upgraded = [extGhost({ version: '1.1.0' })];
+ slot.reconcile(upgraded);
+ await settle();
+ expect(bridges[0].closed).toBe(true);
+ expect(natives[0].close).toHaveBeenCalledOnce();
+ expect(bridges).toHaveLength(2);
+ expect(bridges[1].options.installedVersion).toBe('1.1.0');
+ // 停用:关掉,不再提供页面控制。
+ slot.reconcile([extGhost({ version: '1.1.0', enabled: false })]);
+ await settle();
+ expect(bridges[1].closed).toBe(true);
+ expect(slot.getPageControl()).toBeNull();
+ });
+
+ it('没有 pageControl 的声明只做通道,不成为 Browser Use 执行端', async () => {
+ const ghosts = [extGhost({ pageControl: false, nativeHost: false })];
+ const { slot, bridges, natives, settle } = await makeSlot({}, ghosts);
+ slot.reconcile(ghosts);
+ await settle();
+ expect(bridges).toHaveLength(1);
+ expect(bridges[0].options.nativeToken).toBeUndefined();
+ expect(natives).toHaveLength(0);
+ expect(slot.getPageControl()).toBeNull();
+ });
+});
+
+describe('browserExtensionSlot · 管子上行', () => {
+ it('未声明能力 / 未启用的插件一律 PERMISSION_DENIED;桥接未就绪 HOST_NOT_READY', async () => {
+ const ghosts = [
+ extGhost(),
+ extGhost({ id: 'plain', declare: false }),
+ extGhost({ id: 'off', enabled: false }),
+ ];
+ const { slot } = await makeSlot({}, ghosts);
+ expect(await slot.handleRequest('_root__plain', { kind: 'status' })).toMatchObject({
+ ok: false,
+ errorCode: 'PERMISSION_DENIED',
+ });
+ expect(await slot.handleRequest('_root__off', { kind: 'status' })).toMatchObject({
+ ok: false,
+ errorCode: 'PERMISSION_DENIED',
+ });
+ expect(await slot.handleRequest('_root__ext-ghost', { kind: 'status' })).toMatchObject({
+ ok: false,
+ errorCode: 'HOST_NOT_READY',
+ });
+ });
+
+ it('status / act / setPolicy / setTrustedClients / relay* 原样转给桥接;策略落盘并在重启后恢复', async () => {
+ const { slot, bridges, dir, ghosts, settle } = await makeSlot();
+ slot.reconcile(ghosts);
+ await settle();
+ const id = '_root__ext-ghost';
+ expect(await slot.handleRequest(id, 'nope')).toMatchObject({
+ ok: false,
+ errorCode: 'INVALID_REQUEST',
+ });
+ expect(await slot.handleRequest(id, { kind: 'status' })).toMatchObject({
+ ok: true,
+ port: 18810,
+ host: true,
+ nativeBinding: 'ready',
+ });
+ expect(
+ await slot.handleRequest(id, {
+ kind: 'act',
+ action: 'text',
+ payload: { url: 'https://example.test' },
+ }),
+ ).toMatchObject({ ok: true, text: 'hello' });
+ expect(bridges[0].calls.at(-1)).toEqual(['act', ['text', { url: 'https://example.test' }]]);
+ expect(
+ await slot.handleRequest(id, { kind: 'setPolicy', policy: { read: { block: 'bad' } } }),
+ ).toMatchObject({ ok: false, errorCode: 'INVALID_REQUEST' });
+ const policy = {
+ read: { block: ['blocked.test'] },
+ interact: { allow: ['example.test'], block: [] },
+ };
+ expect(await slot.handleRequest(id, { kind: 'setPolicy', policy })).toMatchObject({
+ ok: true,
+ policy,
+ });
+ expect(
+ JSON.parse(await fs.readFile(path.join(dir, encodeURIComponent(id) + '.json'), 'utf8')),
+ ).toEqual({ version: 1, policy });
+ expect(await slot.handleRequest(id, { kind: 'setTrustedClients', clients: [] })).toEqual({
+ ok: true,
+ });
+ expect(await slot.handleRequest(id, { kind: 'relayActive', id: 'r1' })).toEqual({
+ ok: true,
+ active: true,
+ });
+ expect(
+ await slot.handleRequest(id, {
+ kind: 'relayProgress',
+ id: 'r1',
+ progress: { stage: 'model' },
+ }),
+ ).toEqual({ ok: true });
+ expect(
+ await slot.handleRequest(id, { kind: 'relayResult', id: 'r1', result: { ok: true } }),
+ ).toEqual({ ok: true });
+ expect(await slot.handleRequest(id, { kind: 'relayResult' })).toMatchObject({
+ ok: false,
+ errorCode: 'INVALID_REQUEST',
+ });
+ expect(await slot.handleRequest(id, { kind: 'mystery' })).toMatchObject({
+ ok: false,
+ errorCode: 'INVALID_REQUEST',
+ });
+ // 重启(新槽、同目录):先恢复上次策略再 start。
+ const again = await makeSlot({ policyDir: () => dir });
+ again.slot.reconcile(again.ghosts);
+ await again.settle();
+ expect(again.bridges[0].calls[0]).toEqual(['setPolicy', [policy]]);
+ expect(again.bridges[0].started).toBe(true);
+ });
+});
+
+describe('browserExtensionSlot · 转交扩展请求', () => {
+ it('在线直接投递;离线先拉起再投递;仍失败则回 PLUGIN_UNAVAILABLE 给扩展', async () => {
+ let online = true;
+ const wake = vi.fn(async () => {
+ online = true;
+ return true;
+ });
+ const { slot, bridges, sent, ghosts, settle, deps } = await makeSlot({
+ sendToGhost: vi.fn((ghostId, payload) => {
+ if (!online) return false;
+ sent.push([ghostId, payload]);
+ return true;
+ }),
+ wake,
+ });
+ slot.reconcile(ghosts);
+ await settle();
+ const notice = {
+ id: 'req-1',
+ clientId: 'client-1',
+ request: { op: 'translate', source: { url: '', title: '' }, text: 'hi' },
+ };
+ bridges[0].emitRelay(notice);
+ await settle();
+ expect(sent).toHaveLength(1);
+ expect(sent[0][0]).toBe('_root__ext-ghost');
+ expect(sent[0][1]).toMatchObject({
+ type: 'event',
+ name: 'browser-extension-relay',
+ id: 'req-1',
+ clientId: 'client-1',
+ request: notice.request,
+ });
+ online = false;
+ bridges[0].emitRelay({ ...notice, id: 'req-2' });
+ await settle();
+ expect(wake).toHaveBeenCalledOnce();
+ expect(sent).toHaveLength(2);
+ online = false;
+ wake.mockResolvedValueOnce(false);
+ bridges[0].emitRelay({ ...notice, id: 'req-3' });
+ await settle();
+ expect(sent).toHaveLength(2);
+ expect(bridges[0].calls.at(-1)).toEqual([
+ 'relayResult',
+ ['req-3', { ok: false, error: 'PLUGIN_UNAVAILABLE' }],
+ ]);
+ expect(deps.sendToGhost).toHaveBeenCalled();
+ });
+});
diff --git a/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts b/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts
new file mode 100644
index 0000000000..1ea4b29985
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/browserExtensionSlot.ts
@@ -0,0 +1,378 @@
+/**
+ * browserExtensionSlot.ts — 浏览器扩展槽(browserExtension,2026-10-27)。
+ * ---------------------------------------------------------------------------
+ * 插件随包携带一个浏览器扩展时,由宿主承接扩展的连接:为每个**已装、启用、声明
+ * browserExtension** 的插件各开一份本机桥接(BrowserExtensionBridge),复制并注册
+ * 它的 Native Messaging host,把扩展发起的请求(翻译、字幕…)经管子转交给插件,
+ * 并把插件的作业、策略与配对身份推送转给桥接。声明 pageControl 的扩展同时成为
+ * Browser Use 的「我的浏览器」执行端(user-browser 后端经 getPageControl 取桥接)。
+ *
+ * 安全模型:
+ * - 资格审:已装、启用、声明 browserExtension;停用/卸载/换版即关桥接,在途作业
+ * 按 BRIDGE_STOPPED 作废,不留排队作业;
+ * - 身份:允许连接的扩展 id 来自身份卡(装入时展示并钉死),宿主代码里不出现任何
+ * 具体插件名;native host 的授权令牌只写本机私有连接文件;
+ * - 策略归插件:站点策略由插件保存并推送(setPolicy),宿主只缓存、持久化到
+ * owner 私有目录并在每个作业上强制;宿主重启后先恢复上次策略再接受连接,
+ * 没有策略时按线协议默认值(读开放公网、交互开放,本机/私网拒绝);
+ * - 转交请求只投递给声明该扩展的插件(沙箱内处理),宿主不解释其业务内容。
+ *
+ * 纯逻辑 + 依赖注入(规则 14):ghost 查询、管子投递、目录与桥接工厂在
+ * cindy-brain/index.ts 组装时注入。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+ BrowserExtensionBridge,
+ type BrowserExtensionBridgeOptions,
+ type BrowserExtensionRelayNotice,
+} from '../browser-extension/bridge.js';
+import {
+ createNativeBinding,
+ type NativeBinding,
+ type NativeBindingOptions,
+} from '../browser-extension/native-binding.js';
+import {
+ defaultBrowserExtensionPolicy,
+ normalizeBrowserExtensionPolicy,
+ type BrowserExtensionPolicy,
+} from '../browser-extension/policy.js';
+import {
+ ghostInstallApprovalToken,
+ type GhostPipeBrowserExtensionResult,
+ type InstalledGhost,
+} from '../../shared/ghost.js';
+import { installedGhostStoragePart } from '../../shared/pluginIdentity.js';
+import type { UserBrowserPageControl } from '../mcp-integrations/browser-backend/user-browser-backend.js';
+
+export interface BrowserExtensionSlotDeps {
+ getGhost(id: string): InstalledGhost | null;
+ /** 把转交事件投到插件逻辑页;false = 逻辑页不在线。 */
+ sendToGhost(ghostId: string, payload: unknown): boolean;
+ /** 逻辑页不在线时拉起它(订阅网关同款);缺省不拉起。 */
+ wake?(ghostId: string): Promise<boolean>;
+ /** 策略缓存目录(owner 私有);切换账号后目录变化,桥接按新目录重启。 */
+ policyDir(): string;
+ /** 当前数据所有者标识;变化时所有桥接重建(策略不跨账号)。 */
+ ownerScopeKey(): string;
+ createBridge?(options: BrowserExtensionBridgeOptions): BrowserExtensionBridge;
+ createNativeBinding?(options: NativeBindingOptions): NativeBinding;
+ now?(): number;
+ log?: {
+ info: (msg: string, meta?: Record<string, unknown>) => void;
+ warn: (msg: string, meta?: Record<string, unknown>) => void;
+ };
+}
+
+interface Entry {
+ instanceId: string;
+ signature: string;
+ ghost: InstalledGhost;
+ bridge: BrowserExtensionBridge;
+ native: NativeBinding | null;
+ ready: Promise<void>;
+ closing: boolean;
+}
+
+function fail(
+ errorCode: Extract<GhostPipeBrowserExtensionResult, { ok: false }>['errorCode'],
+ message: string,
+): GhostPipeBrowserExtensionResult {
+ return { ok: false, errorCode, message };
+}
+
+function entrySignature(ghost: InstalledGhost, ownerScopeKey: string): string {
+ return JSON.stringify([
+ ownerScopeKey,
+ ghost.dir,
+ ghost.manifest.version,
+ ghostInstallApprovalToken(ghost.approval),
+ ghost.manifest.browserExtension,
+ ]);
+}
+
+/** 浏览器扩展槽:按插件启停桥接 → 转交扩展请求 → 承接插件的作业/策略推送 → 提供页面控制桥接。 */
+export class GhostBrowserExtensionSlot {
+ private readonly entries = new Map<string, Entry>();
+ private disposed = false;
+
+ constructor(private readonly deps: BrowserExtensionSlotDeps) {}
+
+ /** 装/卸/启停/换版广播后调用;幂等,只对发生变化的插件启停桥接。 */
+ reconcile(ghosts: InstalledGhost[]): void {
+ if (this.disposed) return;
+ const ownerScopeKey = this.deps.ownerScopeKey();
+ const wanted = new Map<string, InstalledGhost>();
+ for (const ghost of ghosts) {
+ if (!ghost.enabled || !ghost.manifest.browserExtension) continue;
+ wanted.set(installedGhostStoragePart(ghost), ghost);
+ }
+ for (const [instanceId, entry] of this.entries) {
+ const ghost = wanted.get(instanceId);
+ if (!ghost || entrySignature(ghost, ownerScopeKey) !== entry.signature)
+ void this.stop(instanceId);
+ }
+ for (const [instanceId, ghost] of wanted) {
+ if (!this.entries.has(instanceId)) this.start(instanceId, ghost, ownerScopeKey);
+ }
+ }
+
+ private start(instanceId: string, ghost: InstalledGhost, ownerScopeKey: string): void {
+ const needs = ghost.manifest.browserExtension!;
+ const native = needs.nativeHost
+ ? (this.deps.createNativeBinding ?? createNativeBinding)({
+ hostName: needs.nativeHost.name,
+ binaryDir: path.join(ghost.dir, needs.nativeHost.binary),
+ })
+ : null;
+ const bridge = (this.deps.createBridge ?? ((options) => new BrowserExtensionBridge(options)))({
+ ghostId: ghost.manifest.id,
+ installedVersion: ghost.manifest.version,
+ extensionIds: needs.extensionIds,
+ ...(native ? { nativeToken: native.token } : {}),
+ onRelay: (notice) => void this.relay(instanceId, notice),
+ ...(this.deps.now ? { now: this.deps.now } : {}),
+ ...(this.deps.log ? { log: this.deps.log } : {}),
+ });
+ const entry: Entry = {
+ instanceId,
+ signature: entrySignature(ghost, ownerScopeKey),
+ ghost,
+ bridge,
+ native,
+ ready: Promise.resolve(),
+ closing: false,
+ };
+ entry.ready = (async () => {
+ const saved = await this.readPolicy(instanceId);
+ if (saved) {
+ try {
+ await bridge.setPolicy(saved);
+ } catch (err) {
+ this.deps.log?.warn('browser extension saved policy rejected; using defaults', {
+ instanceId,
+ error: errorText(err),
+ });
+ }
+ }
+ await bridge.start();
+ if (native) {
+ const installed = await native.install(bridge.listeningPort, needs.extensionIds);
+ if (!installed.ok)
+ this.deps.log?.warn('browser extension native binding unavailable', {
+ instanceId,
+ reason: installed.reason,
+ });
+ }
+ this.deps.log?.info('browser extension bridge ready', {
+ instanceId,
+ port: bridge.listeningPort,
+ pageControl: needs.pageControl === true,
+ });
+ })().catch((err) => {
+ this.deps.log?.warn('browser extension bridge failed to start', {
+ instanceId,
+ error: errorText(err),
+ });
+ });
+ this.entries.set(instanceId, entry);
+ }
+
+ private async stop(instanceId: string): Promise<void> {
+ const entry = this.entries.get(instanceId);
+ if (!entry || entry.closing) return;
+ entry.closing = true;
+ this.entries.delete(instanceId);
+ await entry.ready;
+ await entry.bridge.close();
+ await entry.native?.close();
+ this.deps.log?.info('browser extension bridge stopped', { instanceId });
+ }
+
+ async dispose(): Promise<void> {
+ this.disposed = true;
+ await Promise.all([...this.entries.keys()].map((id) => this.stop(id)));
+ }
+
+ // ── 转交:扩展 → 插件 ────────────────────────────────────────────────────
+
+ private async relay(instanceId: string, notice: BrowserExtensionRelayNotice): Promise<void> {
+ const entry = this.entries.get(instanceId);
+ if (!entry) return;
+ const payload = {
+ type: 'event',
+ name: 'browser-extension-relay',
+ id: notice.id,
+ clientId: notice.clientId,
+ request: notice.request,
+ ts: (this.deps.now ?? Date.now)(),
+ };
+ let delivered = this.deps.sendToGhost(instanceId, payload);
+ if (!delivered && this.deps.wake) {
+ try {
+ delivered =
+ (await this.deps.wake(instanceId)) && this.deps.sendToGhost(instanceId, payload);
+ } catch (err) {
+ this.deps.log?.warn('browser extension relay wake failed', {
+ instanceId,
+ error: errorText(err),
+ });
+ }
+ }
+ if (!delivered) {
+ this.deps.log?.warn('browser extension relay undeliverable; plugin logic page offline', {
+ instanceId,
+ id: notice.id,
+ });
+ entry.bridge.relayResult(notice.id, { ok: false, error: 'PLUGIN_UNAVAILABLE' });
+ }
+ }
+
+ // ── 管子上行:插件 → 桥接 ────────────────────────────────────────────────
+
+ private entryFor(
+ ghostId: string,
+ ): { ok: true; entry: Entry } | { ok: false; result: GhostPipeBrowserExtensionResult } {
+ const ghost = this.deps.getGhost(ghostId);
+ if (!ghost?.enabled || !ghost.manifest.browserExtension) {
+ return {
+ ok: false,
+ result: fail(
+ 'PERMISSION_DENIED',
+ '插件未申请浏览器扩展能力(browserExtension),或当前未启用',
+ ),
+ };
+ }
+ const entry = this.entries.get(installedGhostStoragePart(ghost)) ?? this.entries.get(ghostId);
+ if (!entry)
+ return { ok: false, result: fail('HOST_NOT_READY', '浏览器扩展桥接尚未就绪;稍后重试') };
+ return { ok: true, entry };
+ }
+
+ async handleRequest(ghostId: string, payload: unknown): Promise<GhostPipeBrowserExtensionResult> {
+ const gate = this.entryFor(ghostId);
+ if (!gate.ok) return gate.result;
+ if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+ return fail('INVALID_REQUEST', 'browser-extension-request 载荷必须是对象');
+ const req = payload as Record<string, unknown>;
+ const { entry } = gate;
+ await entry.ready;
+ try {
+ switch (req.kind) {
+ case 'status': {
+ const status = await entry.bridge.status();
+ if (!status.ok) return { ...status, errorCode: 'HOST_NOT_READY' };
+ return {
+ ...status,
+ host: true,
+ nativeBinding: entry.native ? entry.native.status() : 'unavailable',
+ };
+ }
+ case 'act':
+ return (await entry.bridge.act(
+ req.action,
+ req.payload ?? {},
+ )) as GhostPipeBrowserExtensionResult;
+ case 'setPolicy': {
+ let policy: BrowserExtensionPolicy;
+ try {
+ policy = normalizeBrowserExtensionPolicy(req.policy);
+ } catch (err) {
+ return fail('INVALID_REQUEST', errorText(err));
+ }
+ const applied = await entry.bridge.setPolicy(policy);
+ if (applied.ok || applied.applied === true)
+ await this.writePolicy(entry.instanceId, policy);
+ return applied as GhostPipeBrowserExtensionResult;
+ }
+ case 'setTrustedClients':
+ try {
+ return entry.bridge.setTrustedClients(req.clients);
+ } catch (err) {
+ return fail('INVALID_REQUEST', errorText(err));
+ }
+ case 'relayActive':
+ if (typeof req.id !== 'string') return fail('INVALID_REQUEST', 'relayActive 需要 id');
+ return entry.bridge.relayActive(req.id);
+ case 'relayProgress':
+ if (typeof req.id !== 'string') return fail('INVALID_REQUEST', 'relayProgress 需要 id');
+ return entry.bridge.relayProgress(
+ req.id,
+ req.progress,
+ ) as GhostPipeBrowserExtensionResult;
+ case 'relayResult':
+ if (typeof req.id !== 'string') return fail('INVALID_REQUEST', 'relayResult 需要 id');
+ return entry.bridge.relayResult(req.id, req.result) as GhostPipeBrowserExtensionResult;
+ default:
+ return fail(
+ 'INVALID_REQUEST',
+ `未知的 browser-extension-request kind ${JSON.stringify(req.kind)}`,
+ );
+ }
+ } catch (err) {
+ this.deps.log?.warn('browser extension request failed', {
+ ghostId,
+ kind: req.kind,
+ error: errorText(err),
+ });
+ return fail('INTERNAL', errorText(err));
+ }
+ }
+
+ // ── 页面控制:Browser Use 的「我的浏览器」执行端 ─────────────────────────
+
+ getPageControl(): UserBrowserPageControl | null {
+ for (const entry of this.entries.values()) {
+ if (entry.ghost.manifest.browserExtension?.pageControl === true) {
+ return {
+ bridge: entry.bridge,
+ ghostId: entry.ghost.manifest.id,
+ pluginName: entry.ghost.manifest.name,
+ };
+ }
+ }
+ return null;
+ }
+
+ // ── 策略持久化 ──────────────────────────────────────────────────────────
+
+ private policyFile(instanceId: string): string {
+ return path.join(this.deps.policyDir(), encodeURIComponent(instanceId) + '.json');
+ }
+
+ private async readPolicy(instanceId: string): Promise<BrowserExtensionPolicy | null> {
+ try {
+ const raw = JSON.parse(await fs.readFile(this.policyFile(instanceId), 'utf8')) as {
+ version?: unknown;
+ policy?: unknown;
+ };
+ if (raw?.version !== 1) return null;
+ return normalizeBrowserExtensionPolicy(raw.policy);
+ } catch {
+ return null;
+ }
+ }
+
+ private async writePolicy(instanceId: string, policy: BrowserExtensionPolicy): Promise<void> {
+ try {
+ const file = this.policyFile(instanceId);
+ await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+ const tmp = file + '.tmp';
+ await fs.writeFile(tmp, JSON.stringify({ version: 1, policy }), { mode: 0o600 });
+ await fs.rename(tmp, file);
+ } catch (err) {
+ this.deps.log?.warn('browser extension policy not persisted', {
+ instanceId,
+ error: errorText(err),
+ });
+ }
+ }
+}
+
+function errorText(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+export { defaultBrowserExtensionPolicy };
diff --git a/apps/desktop/src/main/cindy-brain/forgeGuide.ts b/apps/desktop/src/main/cindy-brain/forgeGuide.ts
index edaa7f35b0..d2703e15b8 100644
--- a/apps/desktop/src/main/cindy-brain/forgeGuide.ts
+++ b/apps/desktop/src/main/cindy-brain/forgeGuide.ts
@@ -27,6 +27,7 @@ import nodeWorker from '../../../resources/system-skills/cindy-plugin-creator/re
import sessionContext from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-session-context.md?raw';
import directoryPicker from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-directory-picker.md?raw';
import panelPreview from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-panel-preview.md?raw';
+import browserExtension from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-browser-extension.md?raw';
import bundledSkillsLegacy from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-bundled-skills-legacy.md?raw';
import workspaceSessions from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-workspace-sessions.md?raw';
import confirmDialog from '../../../resources/system-skills/cindy-plugin-creator/references/plugin-confirm-dialog.md?raw';
@@ -67,6 +68,7 @@ export const FORGE_GUIDE = [
sessionContext,
directoryPicker,
panelPreview,
+ browserExtension,
bundledSkillsLegacy,
workspaceSessions,
confirmDialog,
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 5b931c58a3..50b670f9e2 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -417,6 +417,7 @@ import {
import { GhostPickSlot } from './pickSlot.js';
import { recordGhostPickedDir, relocateGhostPickedDirs } from './pickGrantsStore.js';
import { GhostPreviewSlot } from './previewSlot.js';
+import { GhostBrowserExtensionSlot } from './browserExtensionSlot.js';
import { broadcastTaskViewOpen, GhostTaskViewSlot } from './taskViewSlot.js';
import { GhostScheduleSlot, isMainShellWindowUrl } from './scheduleSlot.js';
import { GhostWorkspaceSlot, type WorkspaceSessionService } from './workspaceSlot.js';
@@ -4032,6 +4033,31 @@ async function syncMivoLibraryExtraDirFromSlot(
return result;
}
+let browserExtensionSlotSingleton: GhostBrowserExtensionSlot | null = null;
+
+/**
+ * 浏览器扩展槽单例(browserExtension):桥接启停、转交、策略缓存都在
+ * GhostBrowserExtensionSlot;这里只注入 ghost 查询、管子投递、拉起与 owner 私有目录。
+ * 装/卸/启停/换版经 broadcastGhostsChanged 触发 reconcile。
+ */
+export function getGhostBrowserExtensionSlot(): GhostBrowserExtensionSlot {
+ if (!browserExtensionSlotSingleton) {
+ browserExtensionSlotSingleton = new GhostBrowserExtensionSlot({
+ getGhost: findGhostForInstanceId,
+ sendToGhost: (ghostId, payload) => sendToGhostLogic(ghostId, payload),
+ wake: async (ghostId) => {
+ const ghost = findGhostForInstanceId(ghostId);
+ if (!ghost) return false;
+ return (await getGhostRuntime().spawn(ghost)).ok;
+ },
+ policyDir: () => ownerScopedUserDataPath('browser-extension'),
+ ownerScopeKey: () => activeOwnerScopeKey(),
+ log,
+ });
+ }
+ return browserExtensionSlotSingleton;
+}
+
let previewSlotSingleton: GhostPreviewSlot | null = null;
/** 插件预览开页通道(main → 全窗口 renderer;右侧栏开 web-browser 标签)。 */
@@ -8647,6 +8673,7 @@ export function registerGhostIpc(): void {
app.on('before-quit', () => {
runtime.destroyAll();
getGhostNodeRuntimeBroker().destroyAll();
+ void getGhostBrowserExtensionSlot().dispose();
});
onQuit('plugin-downloads', async () => {
await pluginDownloads.stopAndWait();
@@ -9043,6 +9070,11 @@ export function registerGhostIpc(): void {
if (type === 'preview-request') {
return getGhostPreviewSlot().handleRequest(id, payload);
}
+ // browser-extension-request = 浏览器扩展槽(browserExtension):插件向自己的扩展
+ // 投递作业、推送站点策略/配对身份、回传转交结果;资格审与桥接在 browserExtensionSlot。
+ if (type === 'browser-extension-request') {
+ return getGhostBrowserExtensionSlot().handleRequest(id, payload);
+ }
// task-view-request = 在任务右侧栏打开 / 聚焦插件自己的任务页(taskView 槽):
// 只承载包内页面,不收网址;落点解析在 taskViewSlot,落地在 renderer。
if (type === 'task-view-request') {
@@ -10412,6 +10444,8 @@ function broadcastGhostsChanged(
if (!opts?.projectionOnly) {
getGhostSetupManifestTracker().note(ghosts);
sweepRevokedGhostUnread(ghosts, rosterAuthoritative);
+ // 浏览器扩展桥接跟着花名册走:启用即开、停用/卸载/换版即关。
+ getGhostBrowserExtensionSlot().reconcile(ghosts);
}
const visible = ghosts
.filter((ghost) => isGhostAvailableForActiveSession(ghost.manifest.id))
diff --git a/apps/desktop/src/main/maker-host/built-in-skills.ts b/apps/desktop/src/main/maker-host/built-in-skills.ts
index e407ccfdd5..9fb1e728eb 100644
--- a/apps/desktop/src/main/maker-host/built-in-skills.ts
+++ b/apps/desktop/src/main/maker-host/built-in-skills.ts
@@ -25,7 +25,7 @@ const VERSIONS_DIRECTORY = '.versions';
const ACTIVE_BUNDLE_LINK = '.active';
const BUILT_IN_SKILL_MUTATION_WAIT_MS = 5_000;
/** Increment whenever shipped built-in Skill bytes change between releases. */
-export const BUILT_IN_SKILLS_BUNDLE_VERSION = 23;
+export const BUILT_IN_SKILLS_BUNDLE_VERSION = 24;
const PLUGIN_CREATOR_FIRST_BUNDLE_VERSION = 13;
export interface BuiltInSkillDescriptor {
diff --git a/apps/desktop/src/renderer/features/plugin/lib/permissionItemIcon.ts b/apps/desktop/src/renderer/features/plugin/lib/permissionItemIcon.ts
index eb340bdff4..69ab7ea4ad 100644
--- a/apps/desktop/src/renderer/features/plugin/lib/permissionItemIcon.ts
+++ b/apps/desktop/src/renderer/features/plugin/lib/permissionItemIcon.ts
@@ -1,4 +1,4 @@
-import { AppWindow, Bot, Cpu, FileCode2, FilePen, FolderOpen, FolderPlus, Globe, GraduationCap, KeyRound, LayoutTemplate, Library, MapPin, Megaphone, MessageCircleQuestion, PanelLeft, PanelRight, Radio, Sparkles, Terminal, Wrench, type LucideIcon } from 'lucide-react';
+import { AppWindow, Bot, Cpu, FileCode2, FilePen, FolderOpen, FolderPlus, Globe, GraduationCap, KeyRound, LayoutTemplate, Library, MapPin, Megaphone, MessageCircleQuestion, PanelLeft, PanelRight, Puzzle, Radio, Sparkles, Terminal, Wrench, type LucideIcon } from 'lucide-react';
import type { GhostPermissionItem } from '../../../../shared/ghost';
@@ -23,6 +23,7 @@ const PERMISSION_ICON: Record<GhostPermissionItem['kind'], LucideIcon> = {
'session-context': MapPin,
pick: FolderOpen,
preview: AppWindow,
+ 'browser-extension': Puzzle,
skill: GraduationCap,
workspace: FolderPlus,
};
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 20e794740b..2415a901d3 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -5274,7 +5274,7 @@
},
"browserBackend": {
"title": "Automation browser target",
- "description": "Pick which browser the agent actually drives during automation. Login state is independent between the two modes.",
+ "description": "Pick which browser the agent drives by default during automation. Sign-ins are independent across the three targets; an explicit choice in a task wins.",
"defaultTag": "Default",
"resetToDefault": "Reset to default",
"toggleFailed": "Failed to switch browser target",
@@ -5286,13 +5286,16 @@
"hostUnavailable": "the embedded browser interface is not ready or its connection was lost",
"startFailed": "the replacement controller could not start",
"statusFailed": "the controller status check failed",
- "recoveryFailed": "the control connection could not be rebuilt"
+ "recoveryFailed": "the control connection could not be rebuilt",
+ "extensionDisconnected": "no browser extension is connected (install and enable the Cindy Chrome plugin and its extension)"
},
"reconnect": "Reconnect Browser",
"recover": "Recover Browser",
"recovering": "Recovering Browser…",
"recovered": "Embedded browser reconnected",
- "recoverFailed": "Failed to recover the embedded browser. Review the reason and try again."
+ "recoverFailed": "Failed to recover the embedded browser. Review the reason and try again.",
+ "userBrowserReady": "Your browser is connected: the agent can operate the browser you are using.",
+ "userBrowserError": "Your browser is unavailable: {{reason}}."
},
"rsbWebview": {
"title": "Sidebar embedded browser",
@@ -5301,6 +5304,10 @@
"external": {
"title": "Standalone external browser",
"description": "Agent drives a dedicated Chrome window (vendored Playwright)."
+ },
+ "userBrowser": {
+ "title": "My browser",
+ "description": "Agent operates the Chrome / Edge you are using through the Cindy extension, with your sign-ins. No screenshots, network reads or arbitrary scripts."
}
},
"android": {
@@ -7360,6 +7367,9 @@
"sessionContextDetail": "Shares only location facts (session ID and project folder path) while it works for the current session — no file contents, and no file access is granted.",
"preview": "Can open preview pages from the sites below in the sidebar browser",
"previewDetail": "Only the sites listed below can be opened; every page it opens is attributed to this plugin.",
+ "browserExtension": "Lets its bundled browser extension connect to Cindy",
+ "browserExtensionDetail": "Only the extensions listed below can connect, over the local loopback address; Cindy hands requests the extension makes to this plugin.",
+ "browserExtensionPageControlDetail": "Only the extensions listed below can connect. The extension also implements page control: with “My browser” selected, the agent can read and operate pages in the browser you are using, within the plugin's site permissions.",
"nodeChildSpawn": "Its Node program can ask the host to start declared sub-processes from its package",
"nodeChildSpawnDetail": "Only JS files declared inside its own package can be started (same local permissions as the main program); arbitrary commands cannot be executed. Sub-processes are closed together when the plugin is disabled or exits.",
"skill": "Adds the skill \"{{name}}\" to your AI assistants",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index c9d64370c3..5b219ba2a1 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -5242,7 +5242,7 @@
},
"browserBackend": {
"title": "自動操作のブラウザ対象",
- "description": "エージェントが実際に操作するブラウザを選択します。ログイン状態は 2 つのモード間で独立しています。",
+ "description": "自動操作でエージェントが既定で操作するブラウザを選びます。3 つの対象のログイン状態は独立しており、タスクで明示した場合はそちらが優先されます。",
"defaultTag": "デフォルト",
"resetToDefault": "デフォルトに戻す",
"toggleFailed": "ブラウザ対象の切り替えに失敗しました",
@@ -5254,13 +5254,16 @@
"hostUnavailable": "内蔵ブラウザー画面の準備ができていないか、接続が切れています",
"startFailed": "新しい制御プロセスを起動できませんでした",
"statusFailed": "制御プロセスの状態確認に失敗しました",
- "recoveryFailed": "制御接続を再構築できませんでした"
+ "recoveryFailed": "制御接続を再構築できませんでした",
+ "extensionDisconnected": "接続中のブラウザ拡張がありません(Cindy Chrome プラグインと拡張をインストール・有効化してください)"
},
"reconnect": "内蔵ブラウザを再接続",
"recover": "内蔵ブラウザを復旧",
"recovering": "内蔵ブラウザを復旧中…",
"recovered": "内蔵ブラウザを再接続しました",
- "recoverFailed": "内蔵ブラウザの復旧に失敗しました。理由を確認して再試行してください。"
+ "recoverFailed": "内蔵ブラウザの復旧に失敗しました。理由を確認して再試行してください。",
+ "userBrowserReady": "自分のブラウザが接続済み:エージェントは使用中のブラウザを操作できます。",
+ "userBrowserError": "自分のブラウザを利用できません:{{reason}}。"
},
"rsbWebview": {
"title": "サイドバー内蔵ブラウザ",
@@ -5269,6 +5272,10 @@
"external": {
"title": "独立した外部ブラウザ",
"description": "エージェントは専用の Chrome ウィンドウを操作します(vendored Playwright)。"
+ },
+ "userBrowser": {
+ "title": "自分のブラウザ",
+ "description": "エージェントは Cindy 拡張経由で使用中の Chrome / Edge をログイン状態のまま操作します。スクリーンショット、ネットワーク読み取り、任意スクリプトは非対応です。"
}
},
"android": {
@@ -7328,6 +7335,9 @@
"sessionContextDetail": "現在のセッションのために動作するときだけ、場所の情報(セッション ID とプロジェクトフォルダのパス)を伝えます。ファイルの内容は含まれず、ファイルへのアクセス権も与えられません。",
"preview": "以下のサイトのプレビューページをサイドバーのブラウザで開けます",
"previewDetail": "開けるのは下に列挙されたサイトだけです。ページを開くたびに、どのプラグインが開いたかが表示されます。",
+ "browserExtension": "同梱のブラウザ拡張を Cindy に接続できます",
+ "browserExtensionDetail": "接続できるのは下に列挙された拡張だけです。接続はローカルのループバックアドレス経由で、拡張からの要求は Cindy がこのプラグインに引き渡します。",
+ "browserExtensionPageControlDetail": "接続できるのは下に列挙された拡張だけです。この拡張はページ操作も実装しており、「自分のブラウザ」を選ぶと、エージェントはプラグインのサイト権限の範囲内で使用中のブラウザのページを読み取り・操作できます。",
"nodeChildSpawn": "Node プログラムは、パッケージ内で申告済みのサブプロセスの起動をホストに依頼できます",
"nodeChildSpawnDetail": "起動できるのは自身のパッケージ内で申告済みの JS ファイルだけです(メインプログラムと同じローカル権限)。任意のコマンドは実行できません。プラグインの無効化や終了時にはサブプロセスも一緒に閉じられます。",
"skill": "AI アシスタントにスキル「{{name}}」を追加します",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index b5c597adfe..b986a093f6 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -5242,7 +5242,7 @@
},
"browserBackend": {
"title": "자동화 브라우저 대상",
- "description": "에이전트가 실제로 제어할 브라우저를 선택합니다. 두 모드는 로그인 상태가 서로 독립적입니다.",
+ "description": "자동화 시 에이전트가 기본으로 제어할 브라우저를 선택합니다. 세 대상의 로그인 상태는 서로 독립적이며, 작업에서 명시하면 그 선택이 우선합니다.",
"defaultTag": "기본",
"resetToDefault": "기본값으로 재설정",
"toggleFailed": "브라우저 대상 전환에 실패했습니다",
@@ -5254,13 +5254,16 @@
"hostUnavailable": "내장 브라우저 화면이 준비되지 않았거나 연결이 끊어졌습니다",
"startFailed": "새 제어 프로세스를 시작하지 못했습니다",
"statusFailed": "제어 프로세스 상태 확인에 실패했습니다",
- "recoveryFailed": "제어 연결을 다시 구성하지 못했습니다"
+ "recoveryFailed": "제어 연결을 다시 구성하지 못했습니다",
+ "extensionDisconnected": "연결된 브라우저 확장이 없습니다 (Cindy Chrome 플러그인과 확장을 설치하고 활성화하세요)"
},
"reconnect": "내장 브라우저 다시 연결",
"recover": "내장 브라우저 복구",
"recovering": "내장 브라우저 복구 중…",
"recovered": "내장 브라우저가 다시 연결되었습니다",
- "recoverFailed": "내장 브라우저 복구에 실패했습니다. 오류 원인을 확인하고 다시 시도하세요."
+ "recoverFailed": "내장 브라우저 복구에 실패했습니다. 오류 원인을 확인하고 다시 시도하세요.",
+ "userBrowserReady": "내 브라우저가 연결되었습니다: 에이전트가 사용 중인 브라우저를 조작할 수 있습니다.",
+ "userBrowserError": "내 브라우저를 사용할 수 없습니다: {{reason}}."
},
"rsbWebview": {
"title": "사이드바 내장 브라우저",
@@ -5269,6 +5272,10 @@
"external": {
"title": "독립 외부 브라우저",
"description": "에이전트가 전용 Chrome 창을 제어합니다 (vendored Playwright)."
+ },
+ "userBrowser": {
+ "title": "내 브라우저",
+ "description": "에이전트가 Cindy 확장을 통해 사용 중인 Chrome / Edge를 로그인 상태 그대로 조작합니다. 스크린샷, 네트워크 읽기, 임의 스크립트는 지원하지 않습니다."
}
},
"android": {
@@ -7328,6 +7335,9 @@
"sessionContextDetail": "현재 세션을 위해 작동할 때만 위치 정보(세션 ID와 프로젝트 폴더 경로)를 전달합니다. 파일 내용은 포함되지 않으며 파일 접근 권한도 부여되지 않습니다.",
"preview": "아래 사이트의 미리보기 페이지를 사이드바 브라우저에서 열 수 있습니다",
"previewDetail": "아래에 나열된 사이트만 열 수 있으며, 페이지를 열 때마다 어떤 플러그인이 열었는지 표시됩니다.",
+ "browserExtension": "함께 제공되는 브라우저 확장을 Cindy에 연결할 수 있습니다",
+ "browserExtensionDetail": "아래에 나열된 확장만 연결할 수 있으며, 연결은 로컬 루프백 주소를 통해 이루어집니다. 확장이 보낸 요청은 Cindy가 이 플러그인에 전달합니다.",
+ "browserExtensionPageControlDetail": "아래에 나열된 확장만 연결할 수 있습니다. 이 확장은 페이지 제어도 구현하므로 「내 브라우저」를 선택하면 에이전트가 플러그인의 사이트 권한 범위 안에서 사용 중인 브라우저의 페이지를 읽고 조작할 수 있습니다.",
"nodeChildSpawn": "Node 프로그램이 패키지에 신고된 하위 프로세스 시작을 호스트에 요청할 수 있습니다",
"nodeChildSpawnDetail": "자신의 패키지 안에 신고된 JS 파일만 시작할 수 있으며(메인 프로그램과 동일한 로컬 권한), 임의의 명령은 실행할 수 없습니다. 플러그인이 비활성화되거나 종료되면 하위 프로세스도 함께 종료됩니다.",
"skill": "AI 어시스턴트에 스킬 \"{{name}}\"을(를) 추가합니다",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 3d5d09cb94..6537830437 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -5242,7 +5242,7 @@
},
"browserBackend": {
"title": "浏览器自动化目标",
- "description": "选择 Agent 自动化操作时实际控制哪个浏览器。两种模式登录态相互独立。",
+ "description": "选择 Agent 自动化操作时默认控制哪个浏览器。三种目标的登录态相互独立;任务里明确指定时按指定来。",
"defaultTag": "默认",
"resetToDefault": "恢复默认",
"toggleFailed": "切换浏览器目标失败",
@@ -5254,13 +5254,16 @@
"hostUnavailable": "内置浏览器界面尚未就绪或连接已中断",
"startFailed": "浏览器连接未能启动",
"statusFailed": "无法检查浏览器连接状态",
- "recoveryFailed": "控制连接未能重建"
+ "recoveryFailed": "控制连接未能重建",
+ "extensionDisconnected": "没有已连接的浏览器扩展(安装并启用 Cindy Chrome 插件与扩展)"
},
"reconnect": "重新连接浏览器",
"recover": "恢复浏览器",
"recovering": "正在恢复浏览器…",
"recovered": "内置浏览器已重新连接",
- "recoverFailed": "恢复内置浏览器失败,请根据错误原因重试"
+ "recoverFailed": "恢复内置浏览器失败,请根据错误原因重试",
+ "userBrowserReady": "我的浏览器已连接:Agent 可以操作你正在使用的浏览器。",
+ "userBrowserError": "我的浏览器不可用:{{reason}}。"
},
"rsbWebview": {
"title": "侧边栏内置浏览器",
@@ -5269,6 +5272,10 @@
"external": {
"title": "独立外置浏览器",
"description": "Agent 操作 {{appName}} 专用的独立 Chrome 窗口(vendored Playwright)。"
+ },
+ "userBrowser": {
+ "title": "我的浏览器",
+ "description": "Agent 通过 Cindy 扩展直接操作你正在使用的 Chrome / Edge,登录态现成;不支持截图、网络读取和任意脚本。"
}
},
"android": {
@@ -7328,6 +7335,9 @@
"sessionContextDetail": "只在它为当前任务干活时告知位置信息(任务编号与项目文件夹路径),不包含文件内容,也不因此获得文件访问权。",
"preview": "可在右侧栏浏览器中打开以下网站的预览页面",
"previewDetail": "只能打开下方列出的网站;每次打开都会提示是哪个插件打开的。",
+ "browserExtension": "可让它自带的浏览器扩展连接到 Cindy",
+ "browserExtensionDetail": "只有下方列出的扩展能连接;连接经本机回环地址,由 Cindy 把扩展发起的请求转交给这个插件。",
+ "browserExtensionPageControlDetail": "只有下方列出的扩展能连接。该扩展还实现页面控制:选择「我的浏览器」后,Agent 可经它读取和操作你正在使用的浏览器页面,受插件的站点权限约束。",
"nodeChildSpawn": "Node 程序可请宿主再启动包内申报过的子进程",
"nodeChildSpawnDetail": "只能启动它自己包里申报过的 JS 文件(与主程序同样的本机权限),不能执行任意命令;插件停用或退出时子进程一并关闭。",
"skill": "为 AI 助手添加技能「{{name}}」",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index cb08e66e30..94c70791da 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -5242,7 +5242,7 @@
},
"browserBackend": {
"title": "瀏覽器自動化目標",
- "description": "選擇 Agent 自動化操作時實際控制哪個瀏覽器。兩種模式登入態相互獨立。",
+ "description": "選擇 Agent 自動化操作時預設控制哪個瀏覽器。三種目標的登入態相互獨立;任務裡明確指定時按指定來。",
"defaultTag": "預設",
"resetToDefault": "恢復預設",
"toggleFailed": "切換瀏覽器目標失敗",
@@ -5254,13 +5254,16 @@
"hostUnavailable": "內建瀏覽器介面尚未就緒或連線已中斷",
"startFailed": "瀏覽器連線未能啟動",
"statusFailed": "無法檢查瀏覽器連線狀態",
- "recoveryFailed": "控制連線未能重建"
+ "recoveryFailed": "控制連線未能重建",
+ "extensionDisconnected": "沒有已連線的瀏覽器擴充功能(安裝並啟用 Cindy Chrome 插件與擴充功能)"
},
"reconnect": "重新連線瀏覽器",
"recover": "恢復瀏覽器",
"recovering": "正在恢復瀏覽器…",
"recovered": "內建瀏覽器已重新連線",
- "recoverFailed": "恢復內建瀏覽器失敗,請根據錯誤原因重試"
+ "recoverFailed": "恢復內建瀏覽器失敗,請根據錯誤原因重試",
+ "userBrowserReady": "我的瀏覽器已連線:Agent 可以操作你正在使用的瀏覽器。",
+ "userBrowserError": "我的瀏覽器無法使用:{{reason}}。"
},
"rsbWebview": {
"title": "側邊欄內建瀏覽器",
@@ -5269,6 +5272,10 @@
"external": {
"title": "獨立外接瀏覽器",
"description": "Agent 操作 {{appName}} 專用的獨立 Chrome 視窗(vendored Playwright)。"
+ },
+ "userBrowser": {
+ "title": "我的瀏覽器",
+ "description": "Agent 透過 Cindy 擴充功能直接操作你正在使用的 Chrome / Edge,登入態現成;不支援截圖、網路讀取和任意指令碼。"
}
},
"android": {
@@ -7328,6 +7335,9 @@
"sessionContextDetail": "只在它為當前任務幹活時告知位置資訊(任務編號與專案資料夾路徑),不包含檔案內容,也不因此獲得檔案訪問權。",
"preview": "可在右側欄瀏覽器中開啟以下網站的預覽頁面",
"previewDetail": "只能開啟下方列出的網站;每次開啟都會提示是哪個插件開啟的。",
+ "browserExtension": "可讓它自帶的瀏覽器擴充功能連線到 Cindy",
+ "browserExtensionDetail": "只有下方列出的擴充功能能連線;連線經本機回環位址,由 Cindy 把擴充功能發起的請求轉交給這個插件。",
+ "browserExtensionPageControlDetail": "只有下方列出的擴充功能能連線。該擴充功能還實作頁面控制:選擇「我的瀏覽器」後,Agent 可經它讀取和操作你正在使用的瀏覽器頁面,受插件的站點權限約束。",
"nodeChildSpawn": "Node 程式可請宿主再啟動包內申報過的子處理程序",
"nodeChildSpawnDetail": "只能啟動它自己包裡申報過的 JS 檔案(與主程式同樣的本機權限),不能執行任意命令;插件停用或退出時子處理程序一併關閉。",
"skill": "為 AI 助手新增技能「{{name}}」",
diff --git a/apps/desktop/src/shared/__tests__/ghost.test.ts b/apps/desktop/src/shared/__tests__/ghost.test.ts
index 632615e003..50078cb521 100644
--- a/apps/desktop/src/shared/__tests__/ghost.test.ts
+++ b/apps/desktop/src/shared/__tests__/ghost.test.ts
@@ -4976,3 +4976,73 @@ describe('ghostPermissionProjectionFingerprint', () => {
);
});
});
+
+describe('ghost · browserExtension 槽(2026-10-27 浏览器扩展经宿主桥接连接)', () => {
+ const base = {
+ schemaVersion: 3, minCindyVersion: '0.1.0', id: 'ext-ghost', name: 'Ext Ghost', version: '1.0.0', entry: 'main.js',
+ };
+ const chromeId = 'a'.repeat(32);
+ const edgeId = 'b'.repeat(32);
+ const good = {
+ protocol: 'cindy-browser-extension/3',
+ extensionIds: [chromeId, edgeId],
+ nativeHost: { name: 'com.example.browser', binary: 'native-host/bin' },
+ pageControl: true,
+ };
+ const withNeeds = (browserExtension: unknown) => validateGhostManifest({ ...base, browserExtension });
+
+ it('协议、扩展 id、native host 与 pageControl 都按合同校验;未知扩展字段原样保留', () => {
+ const ok = withNeeds({ ...good, future: { mode: 1 } });
+ expect(ok.ok, JSON.stringify(ok)).toBe(true);
+ if (!ok.ok) return;
+ expect(ok.manifest.browserExtension).toEqual({ ...good, future: { mode: 1 } });
+ expect(validateGhostManifest(ok.manifest)).toEqual(ok);
+ // 没有 native host、没有 pageControl 也是合法的纯通道声明。
+ expect(withNeeds({ protocol: good.protocol, extensionIds: [chromeId] }).ok).toBe(true);
+ for (const bad of [
+ 'string',
+ {},
+ { ...good, protocol: 'cindy-browser-extension/4' },
+ { ...good, extensionIds: [] },
+ { ...good, extensionIds: ['not-an-id'] },
+ { ...good, extensionIds: ['A'.repeat(32)] },
+ { ...good, extensionIds: [chromeId, chromeId] },
+ { ...good, extensionIds: Array.from({ length: 9 }, (_, i) => String.fromCharCode(97 + i).repeat(32)) },
+ { ...good, nativeHost: 'com.example.browser' },
+ { ...good, nativeHost: { name: 'Com.Example', binary: 'native-host/bin' } },
+ { ...good, nativeHost: { name: 'com.example.browser', binary: '../outside' } },
+ { ...good, pageControl: false },
+ { ...good, pageControl: 'yes' },
+ ]) {
+ expect(withNeeds(bad).ok, JSON.stringify(bad)).toBe(false);
+ }
+ });
+
+ it('装入前展示为一项权限;页面控制用单独说明;id 子集与去掉页面控制是收权,新增 id 是扩权', () => {
+ const reviewed = withNeeds(good);
+ expect(reviewed.ok).toBe(true);
+ if (!reviewed.ok) return;
+ expect(ghostPermissionItems(reviewed.manifest)).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ key: 'browser-extension', kind: 'browser-extension', labelKey: 'browserExtension',
+ detailKey: 'browserExtensionPageControlDetail', detail: `${chromeId}\n${edgeId}`,
+ }),
+ ]),
+ );
+ const channelOnly = withNeeds({ protocol: good.protocol, extensionIds: [chromeId] });
+ if (!channelOnly.ok) throw new Error('fixture');
+ expect(ghostPermissionItems(channelOnly.manifest)).toEqual(
+ expect.arrayContaining([expect.objectContaining({ key: 'browser-extension', detailKey: 'browserExtensionDetail' })]),
+ );
+ expect(unreviewedGhostPermissionItems(reviewed.manifest, undefined, channelOnly.manifest)).toEqual([]);
+ const expanded = withNeeds({ ...good, extensionIds: [chromeId, edgeId, 'c'.repeat(32)] });
+ if (!expanded.ok) throw new Error('fixture');
+ expect(unreviewedGhostPermissionItems(reviewed.manifest, undefined, expanded.manifest).map((item) => item.key)).toEqual(['browser-extension']);
+ const controlAdded = withNeeds({ ...good });
+ if (!controlAdded.ok) throw new Error('fixture');
+ expect(unreviewedGhostPermissionItems(channelOnly.manifest, undefined, controlAdded.manifest).map((item) => item.key)).toEqual(['browser-extension']);
+ // 既有安装基线已批准页面控制时,市场清单收窄也不算扩权。
+ expect(unreviewedGhostPermissionItems(channelOnly.manifest, reviewed.manifest, controlAdded.manifest)).toEqual([]);
+ });
+});
diff --git a/apps/desktop/src/shared/ghost.ts b/apps/desktop/src/shared/ghost.ts
index e685e0d542..f35787d9a0 100644
--- a/apps/desktop/src/shared/ghost.ts
+++ b/apps/desktop/src/shared/ghost.ts
@@ -1086,6 +1086,37 @@ export const GHOST_PREVIEW_LOOPBACK_HOSTS: ReadonlySet<string> = new Set([
'[::1]',
]);
+/** browserExtension 槽:当前宿主实现的扩展线协议标识(协议 3,签名线合同 0.4.13)。 */
+export const GHOST_BROWSER_EXTENSION_PROTOCOL = 'cindy-browser-extension/3';
+/** browserExtension 槽:允许连接的扩展 id 条数上限(商店版、Edge 版、开发版各一条足矣)。 */
+export const GHOST_BROWSER_EXTENSION_MAX_IDS = 8;
+/** Chromium 扩展 id:32 位 a–p 字母(公钥 SHA-256 前 128 位的映射)。 */
+export const GHOST_BROWSER_EXTENSION_ID_RE = /^[a-p]{32}$/;
+/** Native Messaging host 名:Chrome 要求小写字母、数字、下划线,点分段。 */
+export const GHOST_BROWSER_EXTENSION_NATIVE_HOST_RE = /^[a-z0-9_]+(?:\.[a-z0-9_]+)*$/;
+
+/**
+ * browserExtension 槽详单(2026-10-27):插件随包携带一个浏览器扩展,由宿主
+ * 在本机回环地址承接扩展的连接(配对、身份绑定、作业分发、请求转交),插件
+ * 不再自带接线进程。extensionIds 是本能力的全部知情面:只有这些扩展 id 能
+ * 连上宿主桥接;插件详情逐条展示。声明 pageControl 的扩展同时实现页面控制
+ * 契约,Browser Use 可把它作为「我的浏览器」执行端。
+ */
+export interface GhostBrowserExtensionNeeds {
+ /** 线协议标识;当前宿主只实现 GHOST_BROWSER_EXTENSION_PROTOCOL。 */
+ protocol: typeof GHOST_BROWSER_EXTENSION_PROTOCOL;
+ /** 允许连接的扩展 id(1–8 条;商店版、Edge 版、开发版)。 */
+ extensionIds: string[];
+ /**
+ * 首次配对用的 Native Messaging host(可选):name 为注册名,binary 为包内
+ * 平台二进制目录(`<binary>/<platform>-<arch>/cindy-browser-native[.exe]`),
+ * 由宿主复制到本机私有目录并向各浏览器注册。
+ */
+ nativeHost?: { name: string; binary: string };
+ /** 扩展实现页面控制契约;Browser Use 据此把它列为用户浏览器执行端。 */
+ pageControl?: true;
+}
+
/** skill 槽:单插件最多捆绑的 Agent Skill 数(范围越小越好,同 preview 精神)。 */
export const GHOST_SKILL_MAX_ITEMS = 4;
/** skill 槽:SKILL.md 单文件字节上限。打包与装入两侧共用,避免契约漂移。 */
@@ -1582,6 +1613,11 @@ export interface GhostManifest {
* 打开预览标签页的域名白名单。
*/
preview?: GhostPreviewNeeds;
+ /**
+ * 浏览器扩展能力:插件随包的浏览器扩展经宿主本机桥接连接 Cindy,
+ * 允许连接的扩展 id 在装入时钉死。
+ */
+ browserExtension?: GhostBrowserExtensionNeeds;
/**
* 随包捆绑的 Agent Skills 清单。
* 启用时由 Cindy 私有入口加载到本地 Claude Code、Codex 与 Pi,不写用户共享目录;字段不参与
@@ -1935,6 +1971,7 @@ export interface GhostPermissionItem {
| 'session-context'
| 'pick'
| 'preview'
+ | 'browser-extension'
| 'skill'
| 'workspace';
/** i18n key 后缀,消费方拼 `settings.ghosts.perm.<labelKey>`。 */
@@ -2328,6 +2365,19 @@ export function ghostPermissionItems(manifest: GhostManifest): GhostPermissionIt
detail: manifest.preview.hosts.join('\n'),
});
}
+ // browserExtension 槽:允许连接的扩展 id 逐行列出;实现页面控制契约的扩展
+ // 用单独说明告知用户「Agent 可经它操作你正在用的浏览器」。
+ if (manifest.browserExtension) {
+ items.push({
+ key: 'browser-extension',
+ kind: 'browser-extension',
+ labelKey: 'browserExtension',
+ detailKey: manifest.browserExtension.pageControl === true
+ ? 'browserExtensionPageControlDetail'
+ : 'browserExtensionDetail',
+ detail: manifest.browserExtension.extensionIds.join('\n'),
+ });
+ }
for (const tool of manifest.tools ?? []) {
items.push({
key: `tool:${tool.name}`,
@@ -2734,6 +2784,9 @@ export function unreviewedGhostPermissionItems(
const previewApproved =
previewWithinCap(reviewed) ||
(previouslyInstalled !== undefined && previewWithinCap(previouslyInstalled));
+ const browserExtensionApproved =
+ ghostBrowserExtensionWithinCap(reviewed, actual) ||
+ (previouslyInstalled !== undefined && ghostBrowserExtensionWithinCap(previouslyInstalled, actual));
const nodeSecretsApproved =
ghostNodeSecretAuthorizationWithinCap(reviewed, actual) ||
(previouslyInstalled !== undefined &&
@@ -2760,6 +2813,9 @@ export function unreviewedGhostPermissionItems(
// preview 的展示 detail 包含完整 hosts;真实包删减 host 是收权,不应因
// detail 字符串变化被反判成新增能力。新增或替换 host 仍会保留为未审查项。
!(item.key === 'preview' && previewApproved) &&
+ // browserExtension 的展示 detail 是完整 id 清单;删减 id、去掉页面控制或
+ // 去掉 native host 都是收权,新增 id、新增页面控制仍保留为未审查项。
+ !(item.key === 'browser-extension' && browserExtensionApproved) &&
// Network host 的展示 key 带声明模式;通配域收窄为具体域或更窄通配域
// 仍是收权,实际覆盖关系由专用上限比较守住。
!networkHostApproved(item) &&
@@ -2772,6 +2828,26 @@ export function unreviewedGhostPermissionItems(
);
}
+/**
+ * 市场清单对浏览器扩展能力的授权上限:真实包的扩展 id 必须是已审查清单的子集,
+ * 页面控制与 native host 只能收窄不能新增(binary 路径是包内安装细节,不算权限)。
+ */
+export function ghostBrowserExtensionWithinCap(
+ reviewed: GhostManifest,
+ actual: GhostManifest,
+): boolean {
+ const actualNeeds = actual.browserExtension;
+ if (actualNeeds === undefined) return true;
+ const cap = reviewed.browserExtension;
+ if (cap === undefined) return false;
+ if (!actualNeeds.extensionIds.every((id) => cap.extensionIds.includes(id))) return false;
+ if (actualNeeds.pageControl === true && cap.pageControl !== true) return false;
+ if (actualNeeds.nativeHost !== undefined && cap.nativeHost?.name !== actualNeeds.nativeHost.name) {
+ return false;
+ }
+ return true;
+}
+
/** 市场清单对 Node Worker 凭证注入与配置引导的授权上限。 */
export function ghostNodeSecretAuthorizationWithinCap(
reviewed: GhostManifest,
@@ -4900,6 +4976,68 @@ function validateGhostManifestInput(value: unknown, preserveHistoricalTasks: boo
};
}
+ // browserExtension 槽详单(v3 直接字段,v2 没有对应 slot):允许连接的扩展 id
+ // 是全部知情面,装入时钉死;协议标识必须是当前宿主实现的版本,未来协议由
+ // 新宿主识别后再放行,不按名字猜。
+ let browserExtension: GhostBrowserExtensionNeeds | undefined;
+ if (raw.browserExtension !== undefined) {
+ if (!isPlainObject(raw.browserExtension)) {
+ return { ok: false, reason: 'browserExtension 详单必须是对象(如 { "protocol": "cindy-browser-extension/3", "extensionIds": [...] })' };
+ }
+ const needsRaw = raw.browserExtension as Record<string, unknown>;
+ if (needsRaw.protocol !== GHOST_BROWSER_EXTENSION_PROTOCOL) {
+ return { ok: false, reason: `browserExtension.protocol 必须是 ${JSON.stringify(GHOST_BROWSER_EXTENSION_PROTOCOL)}` };
+ }
+ if (!Array.isArray(needsRaw.extensionIds) || needsRaw.extensionIds.length === 0) {
+ return { ok: false, reason: 'browserExtension.extensionIds 必须是非空数组(允许连接的扩展 id)' };
+ }
+ if (needsRaw.extensionIds.length > GHOST_BROWSER_EXTENSION_MAX_IDS) {
+ return { ok: false, reason: `browserExtension.extensionIds 最多 ${GHOST_BROWSER_EXTENSION_MAX_IDS} 条` };
+ }
+ const seenExtensionIds = new Set<string>();
+ for (const id of needsRaw.extensionIds) {
+ if (typeof id !== 'string' || !GHOST_BROWSER_EXTENSION_ID_RE.test(id)) {
+ return { ok: false, reason: `browserExtension.extensionIds 含不合法扩展 id ${JSON.stringify(id)}` };
+ }
+ if (seenExtensionIds.has(id)) {
+ return { ok: false, reason: `browserExtension.extensionIds 含重复扩展 id ${JSON.stringify(id)}` };
+ }
+ seenExtensionIds.add(id);
+ }
+ let nativeHost: GhostBrowserExtensionNeeds['nativeHost'];
+ if (needsRaw.nativeHost !== undefined) {
+ if (!isPlainObject(needsRaw.nativeHost)) {
+ return { ok: false, reason: 'browserExtension.nativeHost 必须是对象(如 { "name": "com.example.browser", "binary": "native-host/bin" })' };
+ }
+ const nativeRaw = needsRaw.nativeHost as Record<string, unknown>;
+ if (
+ typeof nativeRaw.name !== 'string' ||
+ nativeRaw.name.length > 128 ||
+ !GHOST_BROWSER_EXTENSION_NATIVE_HOST_RE.test(nativeRaw.name)
+ ) {
+ return { ok: false, reason: 'browserExtension.nativeHost.name 必须是点分小写字母、数字、下划线的 Native Messaging host 名' };
+ }
+ if (!isPortableGhostRelativePath(nativeRaw.binary)) {
+ return { ok: false, reason: 'browserExtension.nativeHost.binary 必须是包内相对路径(平台二进制目录)' };
+ }
+ nativeHost = {
+ ...unknownDeclarationFields(nativeRaw, ['name', 'binary']),
+ name: nativeRaw.name,
+ binary: nativeRaw.binary,
+ };
+ }
+ if (needsRaw.pageControl !== undefined && needsRaw.pageControl !== true) {
+ return { ok: false, reason: 'browserExtension.pageControl 只能省略或为字面量 true' };
+ }
+ browserExtension = {
+ ...unknownDeclarationFields(needsRaw, ['protocol', 'extensionIds', 'nativeHost', 'pageControl']),
+ protocol: GHOST_BROWSER_EXTENSION_PROTOCOL,
+ extensionIds: needsRaw.extensionIds as string[],
+ ...(nativeHost !== undefined ? { nativeHost } : {}),
+ ...(needsRaw.pageControl === true ? { pageControl: true as const } : {}),
+ };
+ }
+
// skill 槽详单:与 slots 含 'skill' **严格成对**(有槽必有详单——捆绑了什么
// 技能是本能力的全部知情面)。name/description 与 SKILL.md 的逐字一致性在
// 打包(packGhostDir)与装入(GhostManager.parse)两侧另行强制,这里只管
@@ -6252,6 +6390,7 @@ function validateGhostManifestInput(value: unknown, preserveHistoricalTasks: boo
...(routineEvents !== undefined ? { routineEvents } : {}),
...(network !== undefined ? { network } : {}),
...(preview !== undefined ? { preview } : {}),
+ ...(browserExtension !== undefined ? { browserExtension } : {}),
...(skill !== undefined ? { skill } : {}),
...(manual !== undefined ? { manual } : {}),
...(slots.includes('notify') ? { notify: true as const } : {}),
@@ -6962,6 +7101,56 @@ export type GhostPipePreviewResult =
message: string;
};
+/**
+ * 上行:browserExtension 槽——插件经宿主桥接与自己的浏览器扩展通讯。
+ * - status:连接与安装状态(不读页面);
+ * - act:向扩展投递一个页面作业(action + payload 的形状由线协议定义,
+ * 宿主按站点策略守门后分发,结果脱敏后返回);
+ * - setPolicy / setTrustedClients:插件把自己保存的站点策略与配对身份
+ * 推给宿主(策略由插件拥有,宿主缓存并在每个作业上强制);
+ * - relayActive / relayProgress / relayResult:插件处理完宿主转交的扩展
+ * 请求(翻译、字幕等)后回传进度与结果。
+ */
+export type GhostPipeBrowserExtensionRequest =
+ | { type: 'browser-extension-request'; kind: 'status' }
+ | { type: 'browser-extension-request'; kind: 'act'; action: string; payload?: Record<string, unknown> }
+ | { type: 'browser-extension-request'; kind: 'setPolicy'; policy: unknown }
+ | { type: 'browser-extension-request'; kind: 'setTrustedClients'; clients: unknown[] }
+ | { type: 'browser-extension-request'; kind: 'relayActive'; id: string }
+ | { type: 'browser-extension-request'; kind: 'relayProgress'; id: string; progress: unknown }
+ | { type: 'browser-extension-request'; kind: 'relayResult'; id: string; result: unknown };
+
+/**
+ * browserExtension 槽结构化返回。槽级拒绝带 errorCode;作业与状态结果沿用线
+ * 协议自己的 `{ ok, error, message, execution }` 形状,原样交给插件工具结果。
+ */
+export type GhostPipeBrowserExtensionResult =
+ | { ok: true; [key: string]: unknown }
+ | {
+ ok: false;
+ errorCode?: 'PERMISSION_DENIED' | 'INVALID_REQUEST' | 'HOST_NOT_READY' | 'INTERNAL';
+ error?: string;
+ message: string;
+ execution?: 'not_executed' | 'executed' | 'unknown';
+ [key: string]: unknown;
+ };
+
+/**
+ * 下行:宿主桥接收到扩展发起的请求(翻译、字幕等),转交给声明 browserExtension
+ * 的插件处理;插件用 relayActive / relayProgress / relayResult 回传。
+ */
+export interface GhostPipeBrowserExtensionRelay {
+ type: 'event';
+ name: 'browser-extension-relay';
+ /** 请求 id(扩展生成的 uuid;回传时原样带回)。 */
+ id: string;
+ /** 发起请求的扩展连接 id。 */
+ clientId: string;
+ /** 线协议校验后的请求载荷。 */
+ request: unknown;
+ ts: number;
+}
+
/**
* 任务页开页结果(`cindy.taskView`)。成功时带上实际落点任务:请求不指定任务时
* 主机落到台前任务,插件据此把自己的业务状态(如设备)绑定到该任务。
@@ -8218,6 +8407,7 @@ export type GhostMessageHookData = { sessionId: string; text: string; model?: st
*/
export type GhostPipeEventPush =
| GhostPipeDownloadProgress
+ | GhostPipeBrowserExtensionRelay
| {
type: 'event';
name: GhostDidEventName;
diff --git a/docs/dev-rules/plugin-security-and-authoring.md b/docs/dev-rules/plugin-security-and-authoring.md
index d5995c9744..743f4206c0 100644
--- a/docs/dev-rules/plugin-security-and-authoring.md
+++ b/docs/dev-rules/plugin-security-and-authoring.md
@@ -127,7 +127,16 @@ Library 请求同时绑定迁移代次和安装批准,根解析、排队及开
`minCindyVersion`。Manifest schema 不设置统一的 Cindy 版本下限;具体版本只属于插件包元数据。
v3 **没有** `slots`;
`tools`、`card`、`panel`、`mainView`、`taskView`、`subscribe`、`skill`、`cindy`、`agent`、`node`、`network`、
- `preview` 等顶层字段本身就是插件贡献项或自主 Host 能力的直接声明。
+ `preview`、`browserExtension` 等顶层字段本身就是插件贡献项或自主 Host 能力的直接声明。
+- `browserExtension` 是宿主承接随包浏览器扩展连接的直接字段(2026-10-27 由 Cindy Chrome
+ 插件自带接线进程迁入宿主):`protocol` 必须是当前宿主实现的 `cindy-browser-extension/3`,
+ `extensionIds` 是允许连接的扩展 id(装入时逐条展示并钉死),可选 `nativeHost{name,binary}`
+ 由宿主复制包内平台二进制并注册 Native Messaging,可选 `pageControl: true` 表示扩展实现
+ 页面控制契约、可作为 Browser Use 的「我的浏览器」执行端。宿主代码里不得出现具体插件名
+ 或专有协议:桥接按声明启停(`cindy-brain/browserExtensionSlot.ts`),扩展发起的请求经
+ `browser-extension-relay` 事件转交给声明插件,插件经 `browser-extension-request` 投递作业、
+ 推送站点策略与配对身份。站点策略归插件所有,宿主只缓存到 owner 私有目录并在每个作业上
+ 强制;新增 id 或新增 `pageControl` 视为权限变多,删减视为收权。
- 无配置的布尔能力只接受字面量 `true`:`notify`、`badge`、`confirm`、`fs`、`library`、
`sessionContext`、`pick`、`workspace`。不用就省略,写 `false` 是无效清单。
- `card: {}` 与 `agent: {}` 分别表示基础卡片能力和由真实用户点击触发 Agent 回合;
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index f2ba8cd0eb..ee5ac12e01 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -92,6 +92,23 @@ Pi 只改写副本首行的 session ID 与 cwd,使其指向接收端工作目
新增 Renderer IPC 仅本机宿主使用,不进入 device-link 通用 invoke/push 白名单;跨设备
复用既有插件页面资源与密封设置链。正文详见 [插件规则](plugin-security-and-authoring.md#宿主统一模型选择器新增接口尚未发布)。
+## 浏览器扩展桥接迁入宿主
+
+随包浏览器扩展的本机桥接从插件自带的 Node 接线进程迁入宿主(`main/browser-extension/bridge.ts`)。
+线协议 `cindy-browser-extension/3`(协议号 3、签名线合同 0.4.13、回环端口 18810–18819、
+`/health` `/poll` `/ack` `/authorize` `/result` `/learning/*` `/native/bind`)逐字不变:已装的
+扩展 0.3.x / 0.4.x 不用更新即可连到宿主;`/health` 的 `plugin` 字段改为声明插件的 id(Cindy
+Chrome 仍是 `my-browser`)。Native Messaging 的注册文件布局(`<App Support>/Cindy/browser-native/`
+与各浏览器 profile 的 `NativeMessagingHosts/<name>.json`)与插件时期相同,已配对用户升级后无需
+重新配对。
+
+宿主只在已装、启用且 v3 清单声明 `browserExtension` 的插件存在时启动桥接;旧版插件不声明,宿主
+不占端口,插件自带接线进程照旧工作,用户升级宿主不会断连。插件新版声明后由宿主接线,插件停止
+自带监听,交错更新期间两边都写同一份 Native Messaging 清单。管子新增上行 `browser-extension-request`
+与下行事件 `browser-extension-relay`;旧宿主对未知上行类型返回错误,插件须按运行时能力探测降级到
+自带接线进程,不得把拒绝当作已连接。Browser Use 的 `BackendKind` 新增 `user-browser`:旧设置文件
+的 `kind` 原样读取,未知值仍回落 `external`;回退旧版本时该值被当作默认处理,不丢其它偏好。
+
## 接受已保存的伙伴模型
既有 `local-db:bots:update` 可选接收 `acceptSavedModelSelectionVersion`(读取到的正整数