baa-conductor

commit

7d4f292

parent

daf1574

author

im_wower

date

2026-03-22 11:41:27 +0800 CST

Vendor baa-firefox into plugin subdirectory

1@@ -2604,7 +2604,7 @@ Scope：
2 - Firefox 插件集成文档
3 - 浏览器状态协议
4 
5-这部分可以落在独立仓库里，但协议应该在这里先定义清楚。
6+这部分现在统一收口在本仓库的 Firefox 插件子目录里，但协议仍然在这里定义清楚。
7 
8 ## 35.10 Task J: Status API 与基础 UI
9 

1@@ -27,6 +27,8 @@ apps/
2   conductor-daemon/
3   status-api/
4   worker-runner/
5+plugins/
6+  baa-firefox/
7 packages/
8   auth/
9   checkpointing/

1@@ -40,4 +40,4 @@ npx --yes pnpm install
2 - 当前仍然采用“内网走 Tailscale `100.x`，外网走二级域名”
3 - 当前仍不依赖 MagicDNS 名称
4 - `README.md`、`DESIGN.md`、根配置文件仍视为热点文件，非任务必要不要碰
5-- `T-026` 是跨仓库任务，目标仓库为 `/Users/george/code/baa/baa-firefox`
6+- `T-026` 在当时是跨仓库任务；当前 Firefox 插件代码已经收口到本仓库子目录 `plugins/baa-firefox/`

1@@ -62,7 +62,7 @@
2 - `README.md`、`DESIGN.md`、根配置文件应避免多人同时修改
3 - `ops/launchd/**` 已合入，当前主线已经产出 app 级 `dist/index.js`
4 - `apps/conductor-daemon/package.json` 与 `apps/status-api/package.json` 的构建脚本已在第三波整合时收口
5-- `baa-firefox` 的 `T-026` 已单独合入其仓库 `main`
6+- Firefox 插件代码现已收口到本仓库子目录 `plugins/baa-firefox/`
7 
8 ## 后续汇总规则
9 

 1@@ -1,5 +1,11 @@
 2 # Firefox Control Protocol
 3 
 4+当前 Firefox 插件实现代码已经直接收口到本仓库子目录：
 5+
 6+- [`../../plugins/baa-firefox/`](../../plugins/baa-firefox/)
 7+
 8+这里保留协议和控制面约定文档；具体实现以 `plugins/baa-firefox/` 为准。
 9+
10 本文档定义 `baa-firefox` 与 `baa-conductor` control API 之间的最小协议。
11 
12 目标：
13@@ -10,7 +16,6 @@
14 
15 非目标：
16 
17-- 不在本仓库实现 Firefox 插件代码
18 - 不定义完整 UI 视觉稿
19 - 不让浏览器成为调度真相来源
20 

1@@ -0,0 +1,2 @@
2+node_modules/
3+.DS_Store

  1@@ -0,0 +1,436 @@
  2+# BAA Firefox MVP Plan
  3+
  4+## Goal
  5+
  6+Build the smallest Firefox extension MVP that proves this model works:
  7+
  8+- one always-open controller page inside the extension
  9+- one real top-level AI tab
 10+- manual login only
 11+- automatic discovery of API endpoints, auth headers, and streaming events
 12+- a long-lived WebSocket from the controller page to `baa-server`
 13+- no DOM parsing as the primary path
 14+
 15+The first platform should be `claude.ai` only. After it works, generalize.
 16+
 17+## Non-Goals
 18+
 19+Do not solve these in MVP:
 20+
 21+- multi-platform support
 22+- multiple tabs per platform
 23+- multiple accounts
 24+- multi-window coordination
 25+- iframe embedding
 26+- full request execution from server into the AI tab
 27+- automatic login
 28+- deep DOM automation
 29+- generic worker/websocket interception
 30+- polished UI
 31+
 32+## Core Decision
 33+
 34+Do not keep the main WebSocket in `background.js`.
 35+
 36+Instead:
 37+
 38+- `controller.html` stays open in a normal browser tab
 39+- `controller.js` owns the WebSocket and the runtime state
 40+- `background.js` becomes thin bootstrap and helper logic only
 41+
 42+Reason:
 43+
 44+- Firefox MV3 background lifetime is the main risk
 45+- a visible extension page is simpler than trying to keep a background context alive
 46+- the controller page can directly use WebExtension APIs needed for MVP
 47+
 48+## MVP Architecture
 49+
 50+### 1. Controller Page
 51+
 52+One extension page acts as the control tower.
 53+
 54+Responsibilities:
 55+
 56+- open and keep track of the single AI tab
 57+- connect to `baa-server` over WS
 58+- receive browser-side events from content scripts
 59+- persist minimal state to `storage.local`
 60+- surface simple status: connected, tab exists, credentials seen, endpoints count
 61+
 62+The controller page should be opened manually at first.
 63+
 64+Later, background can auto-open it on startup if needed.
 65+
 66+### 2. Real AI Tab
 67+
 68+Use one real top-level tab:
 69+
 70+- `https://claude.ai`
 71+
 72+Requirements:
 73+
 74+- user logs in manually
 75+- no specific chat URL required
 76+- the root app page is enough
 77+
 78+The tab is the real browser surface that carries:
 79+
 80+- cookies
 81+- session
 82+- same-origin rules
 83+- anti-bot browser context
 84+
 85+### 3. Content Script Bridge
 86+
 87+Inject a lightweight content script into the AI tab.
 88+
 89+Responsibilities:
 90+
 91+- receive `CustomEvent`s from the page context
 92+- forward them to the controller page or background
 93+
 94+This is the bridge between:
 95+
 96+- privileged extension code
 97+- page MAIN world instrumentation
 98+
 99+### 4. MAIN World Interceptor
100+
101+Inject a MAIN world script into the AI tab.
102+
103+Responsibilities:
104+
105+- patch `window.fetch`
106+- observe request URL, method, headers, body
107+- observe response status, headers, body
108+- observe SSE chunks if present
109+- emit normalized events through `CustomEvent`
110+
111+This is the primary discovery layer for:
112+
113+- API endpoints
114+- request/response shapes
115+- streaming behavior
116+
117+### 5. Browser-Level Request Observer
118+
119+Use `webRequest` in parallel.
120+
121+Responsibilities:
122+
123+- capture outgoing request headers at browser level
124+- recover auth-related headers not visible from page JS
125+- build a credential snapshot
126+- provide a second signal for endpoint discovery
127+
128+This is the primary source for:
129+
130+- cookies
131+- CSRF-style headers
132+- browser-visible request metadata
133+
134+## Why This MVP Should Work
135+
136+This design avoids the fragile path:
137+
138+- no DOM scraping as the primary integration
139+- no button clicking or selector dependency
140+- no iframe
141+
142+This design keeps the stable path:
143+
144+- real browser tab
145+- real cookies
146+- real request flow
147+- extension-side network observation
148+
149+The working proof for MVP is simple:
150+
151+- the user logs into Claude manually
152+- the extension sees live endpoint traffic
153+- the extension captures auth material
154+- the extension sends these to `baa-server`
155+
156+## Files To Create
157+
158+The repo should start with these files:
159+
160+- `manifest.json`
161+- `controller.html`
162+- `controller.js`
163+- `background.js`
164+- `content-script.js`
165+- `page-interceptor.js`
166+- `README.md`
167+
168+Optional:
169+
170+- `controller.css`
171+
172+## File Responsibilities
173+
174+### `manifest.json`
175+
176+Firefox-targeted MV3 manifest.
177+
178+Include only what MVP needs:
179+
180+- `tabs`
181+- `storage`
182+- `webRequest`
183+- `cookies`
184+- `scripting`
185+- host permissions for `https://claude.ai/*`
186+
187+Register:
188+
189+- `background.js`
190+- `content-script.js`
191+- `page-interceptor.js`
192+- browser action or direct tab page for `controller.html`
193+
194+### `controller.html`
195+
196+Minimal UI only.
197+
198+Must show:
199+
200+- WS connected / disconnected
201+- AI tab exists / missing
202+- credentials seen / missing
203+- number of discovered endpoints
204+- recent log lines
205+
206+One button is enough:
207+
208+- `Open Claude Tab`
209+
210+### `controller.js`
211+
212+Main runtime owner.
213+
214+Responsibilities:
215+
216+- connect WS to `baa-server`
217+- create or recover the Claude tab
218+- maintain `platformTabId`
219+- receive forwarded events
220+- normalize and send them to server
221+- persist last known state
222+
223+State shape can be minimal:
224+
225+```js
226+{
227+  platform: "claude",
228+  tabId: 123,
229+  wsConnected: true,
230+  lastCredentialAt: 0,
231+  endpoints: {},
232+  lastHeaders: {},
233+  lastEvents: []
234+}
235+```
236+
237+### `background.js`
238+
239+Thin only.
240+
241+Responsibilities:
242+
243+- open/focus `controller.html` when extension icon is clicked
244+- optionally relay messages if direct page-to-tab wiring is awkward
245+- nothing long-lived beyond bootstrap
246+
247+No main WS should live here in MVP.
248+
249+### `content-script.js`
250+
251+Bridge only.
252+
253+Responsibilities:
254+
255+- listen for `CustomEvent`s from page context
256+- forward to extension runtime
257+
258+Keep it small.
259+
260+### `page-interceptor.js`
261+
262+MAIN world network observer.
263+
264+Responsibilities:
265+
266+- wrap `fetch`
267+- capture requests
268+- capture error responses
269+- capture streaming events where possible
270+
271+For MVP, patching `fetch` is enough.
272+
273+If Claude moves important traffic elsewhere later, expand after proof.
274+
275+## Message Flow
276+
277+### Browser Startup
278+
279+1. User opens `controller.html`
280+2. `controller.js` connects WS to `baa-server`
281+3. `controller.js` checks for existing Claude tab
282+4. If missing, it opens `https://claude.ai`
283+5. Content script and MAIN world interceptor are active on that tab
284+
285+### Manual Login
286+
287+1. User logs into Claude in the real tab
288+2. Claude app bootstraps and starts making network requests
289+3. `webRequest` captures browser-visible auth headers and cookies
290+4. MAIN world interceptor captures request and response data
291+5. Controller receives both and sends normalized events to `baa-server`
292+
293+### Endpoint Discovery
294+
295+1. MAIN world interceptor sees a request
296+2. URL path is normalized
297+3. Method + normalized path are added to endpoint registry
298+4. Controller sends discovered endpoints to `baa-server`
299+
300+### Credential Snapshot
301+
302+1. `webRequest` sees request headers
303+2. Controller extracts a reduced auth snapshot
304+3. Snapshot is timestamped and stored
305+4. Snapshot is sent to `baa-server`
306+
307+## Data Sent To Server
308+
309+MVP should send only these message types:
310+
311+- `hello`
312+- `endpoint_discovered`
313+- `credential_snapshot`
314+- `network_event`
315+- `sse_event`
316+- `status`
317+
318+Example normalized messages:
319+
320+```json
321+{
322+  "type": "hello",
323+  "clientId": "ff-xxxxxx",
324+  "nodeType": "browser",
325+  "nodeCategory": "proxy",
326+  "nodePlatform": "firefox"
327+}
328+```
329+
330+```json
331+{
332+  "type": "endpoint_discovered",
333+  "platform": "claude",
334+  "method": "POST",
335+  "path": "/api/organizations/{id}/messages"
336+}
337+```
338+
339+```json
340+{
341+  "type": "credential_snapshot",
342+  "platform": "claude",
343+  "headers": {
344+    "cookie": "...",
345+    "x-csrf-token": "...",
346+    "anthropic-client-sha": "..."
347+  },
348+  "ts": 0
349+}
350+```
351+
352+## Minimal Acceptance Criteria
353+
354+MVP is done when all of these are true:
355+
356+- opening `controller.html` establishes a WS connection to `baa-server`
357+- the controller can open or recover exactly one Claude tab
358+- manual login in that tab leads to captured credentials
359+- at least one live Claude API endpoint is discovered automatically
360+- request/response metadata is visible in server logs
361+- SSE chunks are visible if Claude uses streaming on the observed path
362+- closing the Claude tab and reopening it still restores the flow
363+
364+## Build Order
365+
366+Implement in this order:
367+
368+1. `manifest.json`
369+2. `controller.html` + `controller.js`
370+3. thin `background.js`
371+4. `content-script.js`
372+5. `page-interceptor.js`
373+6. `webRequest` credential capture
374+7. WS message normalization to server
375+8. minimal status UI
376+
377+## Scope Cuts If Time Is Tight
378+
379+If the first pass needs to be even smaller, cut these first:
380+
381+- pretty UI
382+- SSE chunk parsing details
383+- background auto-open behavior
384+- storage persistence beyond `tabId` and last headers
385+- endpoint normalization beyond very basic ID replacement
386+
387+Do not cut these:
388+
389+- controller-owned WS
390+- real top-level Claude tab
391+- MAIN world fetch interception
392+- `webRequest` credential capture
393+
394+## Deferred Work After MVP
395+
396+Only after the MVP works:
397+
398+- add active proxy execution from server into the live AI tab
399+- support ChatGPT and Gemini
400+- support multiple windows
401+- support multi-account contexts
402+- add stronger recovery logic
403+- add XHR and worker interception
404+- make the controller page optional by moving some logic back into a more robust runtime model
405+
406+## TODO: SSE 抓取
407+
408+Observed in the current Firefox MVP:
409+
410+- request / credential / endpoint capture works
411+- `POST /api/organizations/{id}/chat_conversations/{id}/completion` is discovered
412+- the current SSE bridge can still report `The operation was aborted` with `0` chunks
413+- this happened in the anonymous `https://claude.ai/new?incognito` flow after a real prompt/response round trip
414+
415+Next work should focus on these items:
416+
417+- reproduce the failure deterministically on both anonymous and logged-in organization chats
418+- verify whether `response.clone().body.getReader()` is racing with Claude's own stream consumption in Firefox
419+- test replacing the current clone-reader approach with a `ReadableStream.tee()` based interception path
420+- keep partial chunk state across boundaries so incomplete `data:` frames are not dropped
421+- include stable conversation identifiers in `sse_event` payloads when the completion URL contains them
422+- distinguish clean stream completion from abort / navigation / page refresh in emitted events
423+- add controller-side logs for first chunk, last chunk, abort reason, and total chunk count
424+- only mark SSE capture as done after a verified chunked response is observed in `baa-server` logs
425+
426+## Final Recommendation
427+
428+Do not over-design beyond this.
429+
430+The first goal is only to prove:
431+
432+- Firefox can keep a controller page open
433+- the controller page can keep a WS open
434+- a real Claude tab can be observed without DOM parsing
435+- endpoints and credentials can be learned and sent to `baa-server`
436+
437+Once that proof exists, the rest of the system can be evolved safely.

  1@@ -0,0 +1,114 @@
  2+# BAA Firefox
  3+
  4+这个目录现在作为 `baa-conductor` 内部插件子目录维护。
  5+
  6+来源说明：
  7+
  8+- 初始代码来自原独立仓库 `baa-firefox`
  9+- 已迁入当前仓库，后续以这里为主写入面
 10+
 11+Firefox MVP for the BAA browser-proxy path.
 12+
 13+## What This Repo Does
 14+
 15+This extension keeps an always-open controller page and one real browser tab per platform.
 16+
 17+It does four things:
 18+
 19+- keeps a WebSocket connection to `baa-server`
 20+- opens or reuses real tabs for `claude.ai`, `chatgpt.com`, and `gemini.google.com`
 21+- discovers live API endpoints from real browser traffic
 22+- captures auth-related request headers and forwards them to `baa-server`
 23+
 24+This MVP is intentionally narrow:
 25+
 26+- manual login only
 27+- one tracked tab per platform
 28+- no iframe
 29+- no DOM automation
 30+- no full remote execution path yet
 31+
 32+## Files
 33+
 34+- `manifest.json` - Firefox MV3 manifest
 35+- `background.js` - opens and keeps the controller tab around
 36+- `controller.html` - always-open management page
 37+- `controller.js` - WS owner, multi-platform tab manager, webRequest capture, message relay
 38+- `content-script.js` - bridge from page events into the extension runtime
 39+- `page-interceptor.js` - MAIN world `fetch` interceptor
 40+- `scripts/run-persistent.sh` - starts Firefox with the persistent `baa-firefox-persistent` profile
 41+- `PLAN.md` - MVP design notes
 42+
 43+## Persistent Startup
 44+
 45+If you already created and logged into the persistent Firefox profile once, start the extension with:
 46+
 47+```bash
 48+./scripts/run-persistent.sh
 49+```
 50+
 51+This launches Firefox with the `baa-firefox-persistent` profile, keeps profile changes, reuses the saved browser login state on this machine, and reloads already-open platform pages so the interceptor is injected immediately.
 52+
 53+Useful overrides:
 54+
 55+- `BAA_FIREFOX_PROFILE` - change the Firefox profile name
 56+- `BAA_FIREFOX_BIN` - change the Firefox binary path
 57+- `BAA_WEB_EXT_BIN` - change the `web-ext` executable
 58+
 59+Example:
 60+
 61+```bash
 62+BAA_FIREFOX_PROFILE=baa-firefox-persistent ./scripts/run-persistent.sh
 63+```
 64+
 65+## How To Load
 66+
 67+1. Open Firefox.
 68+2. Visit `about:debugging#/runtime/this-firefox`.
 69+3. Click `Load Temporary Add-on...`.
 70+4. Choose [manifest.json](/Users/george/code/baa-conductor-main-merge/plugins/baa-firefox/manifest.json).
 71+5. Firefox should open `controller.html` automatically.
 72+
 73+## How To Run
 74+
 75+1. Start `baa-server` so `ws://localhost:9800` is available.
 76+2. Load this extension temporarily.
 77+3. In the controller page, keep the default WS URL or change it.
 78+4. Let the extension open `https://claude.ai/`, `https://chatgpt.com/`, and `https://gemini.google.com/`.
 79+5. Log in manually in the tabs you want to intercept.
 80+6. Use Claude, ChatGPT, or Gemini normally.
 81+7. Watch the controller page and `baa-server` logs for:
 82+   - endpoint discovery
 83+   - credential snapshots
 84+   - network events
 85+   - SSE events
 86+
 87+## Expected MVP Result
 88+
 89+Once the platform tabs start making real requests, the extension should forward:
 90+
 91+- `hello`
 92+- `api_endpoints`
 93+- `credentials`
 94+- `network_log`
 95+- `sse_event`
 96+- `client_log`
 97+
 98+These message shapes match the current `baa-server` browser-side WS handling.
 99+
100+## Limitations
101+
102+- only one tab per platform is tracked
103+- only `fetch` is patched in the page
104+- there is no remote request execution path yet
105+- if Firefox unloads the extension, the session must be re-established
106+- Gemini interception is heuristic because its web app mixes private RPC paths under `/_/`
107+
108+## Next Step
109+
110+After this works end to end, add:
111+
112+- request execution into the live platform tabs
113+- stronger tab recovery
114+- broader network interception
115+- more robust Gemini and SSE coverage

  1@@ -0,0 +1,130 @@
  2+const CONTROLLER_URL = browser.runtime.getURL("controller.html");
  3+const STORAGE_KEY = "baaFirefox.controllerTabId";
  4+const CONTROL_STATE_KEY = "baaFirefox.controlState";
  5+const MODE_BADGES = {
  6+  running: { text: "运行", color: "#1f6f5f" },
  7+  paused: { text: "暂停", color: "#a6512f" },
  8+  draining: { text: "排空", color: "#8b5e34" },
  9+  unknown: { text: "--", color: "#7f7a70" }
 10+};
 11+
 12+async function setControllerTabId(tabId) {
 13+  await browser.storage.local.set({ [STORAGE_KEY]: tabId });
 14+}
 15+
 16+async function getStoredControllerTabId() {
 17+  const data = await browser.storage.local.get(STORAGE_KEY);
 18+  return data[STORAGE_KEY] || null;
 19+}
 20+
 21+async function queryControllerTab() {
 22+  const tabs = await browser.tabs.query({ url: CONTROLLER_URL });
 23+  return tabs[0] || null;
 24+}
 25+
 26+async function ensureControllerTab(options = {}) {
 27+  const { activate = false } = options;
 28+
 29+  let tab = await queryControllerTab();
 30+  if (!tab) {
 31+    const storedId = await getStoredControllerTabId();
 32+    if (storedId) {
 33+      try {
 34+        tab = await browser.tabs.get(storedId);
 35+      } catch (_) {
 36+        tab = null;
 37+      }
 38+    }
 39+  }
 40+
 41+  if (tab) {
 42+    await setControllerTabId(tab.id);
 43+    if (activate) {
 44+      await browser.tabs.update(tab.id, { active: true });
 45+      if (tab.windowId != null) {
 46+        await browser.windows.update(tab.windowId, { focused: true });
 47+      }
 48+    }
 49+    return tab;
 50+  }
 51+
 52+  const created = await browser.tabs.create({
 53+    url: CONTROLLER_URL,
 54+    active: activate
 55+  });
 56+  await setControllerTabId(created.id);
 57+  return created;
 58+}
 59+
 60+function normalizeMode(value) {
 61+  const lower = String(value || "").trim().toLowerCase();
 62+  if (lower === "running" || lower === "paused" || lower === "draining") {
 63+    return lower;
 64+  }
 65+  return "unknown";
 66+}
 67+
 68+async function updateActionBadge(snapshot) {
 69+  const mode = normalizeMode(snapshot?.mode);
 70+  const badge = snapshot?.error ? { text: "ERR", color: "#a6512f" } : MODE_BADGES[mode];
 71+  const modeLabel = mode === "running" ? "运行中" : mode === "paused" ? "已暂停" : mode === "draining" ? "排空中" : "未知";
 72+  const leader = snapshot?.leader ? `\n主控: ${snapshot.leader}` : "";
 73+
 74+  await browser.action.setBadgeText({ text: badge.text });
 75+  await browser.action.setBadgeBackgroundColor({ color: badge.color });
 76+  await browser.action.setTitle({
 77+    title: `BAA Firefox 管理页\n模式: ${modeLabel}${leader}`
 78+  });
 79+}
 80+
 81+async function refreshActionBadgeFromStorage() {
 82+  const data = await browser.storage.local.get(CONTROL_STATE_KEY);
 83+  await updateActionBadge(data[CONTROL_STATE_KEY] || null);
 84+}
 85+
 86+browser.runtime.onInstalled.addListener(() => {
 87+  ensureControllerTab({ activate: true }).catch(() => {});
 88+  refreshActionBadgeFromStorage().catch(() => {});
 89+});
 90+
 91+browser.runtime.onStartup.addListener(() => {
 92+  ensureControllerTab({ activate: false }).catch(() => {});
 93+  refreshActionBadgeFromStorage().catch(() => {});
 94+});
 95+
 96+browser.action.onClicked.addListener(() => {
 97+  ensureControllerTab({ activate: true }).catch(() => {});
 98+});
 99+
100+browser.runtime.onMessage.addListener((message) => {
101+  if (!message || typeof message !== "object") return undefined;
102+
103+  if (message.type === "controller_ready" && Number.isInteger(message.tabId)) {
104+    return setControllerTabId(message.tabId).then(() => ({ ok: true }));
105+  }
106+
107+  if (message.type === "focus_controller") {
108+    return ensureControllerTab({ activate: true }).then((tab) => ({
109+      ok: true,
110+      tabId: tab.id
111+    }));
112+  }
113+
114+  return undefined;
115+});
116+
117+browser.storage.onChanged.addListener((changes, areaName) => {
118+  if (areaName !== "local" || !changes[CONTROL_STATE_KEY]) return;
119+  updateActionBadge(changes[CONTROL_STATE_KEY].newValue || null).catch(() => {});
120+});
121+
122+browser.tabs.onRemoved.addListener((tabId) => {
123+  getStoredControllerTabId().then((storedId) => {
124+    if (storedId !== tabId) return;
125+    setTimeout(() => {
126+      ensureControllerTab({ activate: false }).catch(() => {});
127+    }, 300);
128+  }).catch(() => {});
129+});
130+
131+refreshActionBadgeFromStorage().catch(() => {});

  1@@ -0,0 +1,358 @@
  2+const CONTROL_STATE_KEY = "baaFirefox.controlState";
  3+const CLAUDE_ENTRY_HOSTS = ["claude.ai"];
  4+
  5+const claudeEntryState = {
  6+  host: null,
  7+  shadow: null,
  8+  snapshot: null,
  9+  expanded: false,
 10+  busyAction: null,
 11+  error: ""
 12+};
 13+
 14+function sendBridgeMessage(type, data) {
 15+  browser.runtime.sendMessage({
 16+    type,
 17+    data
 18+  }).catch(() => {});
 19+}
 20+
 21+function isRecord(value) {
 22+  return !!value && typeof value === "object" && !Array.isArray(value);
 23+}
 24+
 25+function isClaudePage() {
 26+  return CLAUDE_ENTRY_HOSTS.some((host) => location.hostname === host || location.hostname.endsWith(`.${host}`));
 27+}
 28+
 29+function normalizeMode(value) {
 30+  const lower = String(value || "").trim().toLowerCase();
 31+  if (lower === "running" || lower === "paused" || lower === "draining") {
 32+    return lower;
 33+  }
 34+  return "unknown";
 35+}
 36+
 37+function formatModeLabel(mode) {
 38+  switch (normalizeMode(mode)) {
 39+    case "running":
 40+      return "运行中";
 41+    case "paused":
 42+      return "已暂停";
 43+    case "draining":
 44+      return "排空中";
 45+    default:
 46+      return "未知";
 47+  }
 48+}
 49+
 50+function normalizeEntrySnapshot(value) {
 51+  if (!isRecord(value)) {
 52+    return {
 53+      mode: "unknown",
 54+      leader: null,
 55+      queueDepth: null,
 56+      activeRuns: null,
 57+      error: "未同步"
 58+    };
 59+  }
 60+
 61+  return {
 62+    mode: normalizeMode(value.mode),
 63+    leader: typeof value.leader === "string" && value.leader.trim() ? value.leader.trim() : null,
 64+    queueDepth: Number.isFinite(value.queueDepth) ? Number(value.queueDepth) : null,
 65+    activeRuns: Number.isFinite(value.activeRuns) ? Number(value.activeRuns) : null,
 66+    error: typeof value.error === "string" && value.error ? value.error : ""
 67+  };
 68+}
 69+
 70+function ensureClaudeEntry() {
 71+  if (!isClaudePage() || claudeEntryState.host || !document.documentElement) return;
 72+
 73+  const host = document.createElement("div");
 74+  host.style.position = "fixed";
 75+  host.style.right = "16px";
 76+  host.style.bottom = "16px";
 77+  host.style.zIndex = "2147483647";
 78+
 79+  const shadow = host.attachShadow({ mode: "open" });
 80+  shadow.innerHTML = `
 81+    <style>
 82+      :host {
 83+        all: initial;
 84+      }
 85+
 86+      .wrap {
 87+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 88+        color: #f5efe2;
 89+      }
 90+
 91+      button {
 92+        font: inherit;
 93+        border: 0;
 94+        cursor: pointer;
 95+      }
 96+
 97+      .toggle {
 98+        display: inline-flex;
 99+        align-items: center;
100+        gap: 8px;
101+        padding: 9px 12px;
102+        border-radius: 999px;
103+        background: rgba(19, 26, 26, 0.92);
104+        color: inherit;
105+        box-shadow: 0 10px 28px rgba(0, 0, 0, 0.22);
106+      }
107+
108+      .toggle strong {
109+        font-size: 12px;
110+        letter-spacing: 0.08em;
111+        text-transform: uppercase;
112+      }
113+
114+      .badge {
115+        padding: 4px 8px;
116+        border-radius: 999px;
117+        font-size: 11px;
118+        line-height: 1;
119+      }
120+
121+      .badge.running {
122+        background: rgba(31, 111, 95, 0.28);
123+        color: #91dbc7;
124+      }
125+
126+      .badge.paused,
127+      .badge.draining {
128+        background: rgba(166, 81, 47, 0.28);
129+        color: #ffd3bf;
130+      }
131+
132+      .badge.unknown {
133+        background: rgba(127, 122, 112, 0.28);
134+        color: #e5dccd;
135+      }
136+
137+      .panel {
138+        margin-top: 10px;
139+        width: 250px;
140+        padding: 12px;
141+        border-radius: 18px;
142+        background: rgba(19, 26, 26, 0.94);
143+        box-shadow: 0 16px 40px rgba(0, 0, 0, 0.24);
144+      }
145+
146+      .hidden {
147+        display: none;
148+      }
149+
150+      .topline,
151+      .meta,
152+      .actions {
153+        display: flex;
154+        align-items: center;
155+        gap: 8px;
156+      }
157+
158+      .topline,
159+      .meta {
160+        justify-content: space-between;
161+      }
162+
163+      .meta {
164+        margin-top: 10px;
165+        color: rgba(245, 239, 226, 0.78);
166+        font-size: 12px;
167+      }
168+
169+      .actions {
170+        margin-top: 12px;
171+        flex-wrap: wrap;
172+      }
173+
174+      .panel-btn {
175+        padding: 8px 10px;
176+        border-radius: 999px;
177+        background: rgba(255, 255, 255, 0.08);
178+        color: inherit;
179+      }
180+
181+      .panel-btn:hover {
182+        background: rgba(255, 255, 255, 0.14);
183+      }
184+
185+      .panel-btn[disabled] {
186+        opacity: 0.6;
187+        cursor: default;
188+      }
189+
190+      .error {
191+        margin-top: 10px;
192+        color: #ffd3bf;
193+        font-size: 12px;
194+        line-height: 1.45;
195+      }
196+    </style>
197+    <div class="wrap">
198+      <button id="baa-toggle" class="toggle" type="button">
199+        <strong>BAA</strong>
200+        <span id="baa-mode-badge" class="badge unknown">未知</span>
201+      </button>
202+      <div id="baa-panel" class="panel hidden">
203+        <div class="topline">
204+          <span id="baa-leader">主控 -</span>
205+          <button id="baa-open-panel" class="panel-btn" type="button">管理页</button>
206+        </div>
207+        <div class="meta">
208+          <span id="baa-queue">队列 -</span>
209+          <span id="baa-runs">运行 -</span>
210+        </div>
211+        <div class="actions">
212+          <button data-action="pause" class="panel-btn" type="button">暂停</button>
213+          <button data-action="resume" class="panel-btn" type="button">恢复</button>
214+          <button data-action="drain" class="panel-btn" type="button">排空</button>
215+        </div>
216+        <div id="baa-error" class="error hidden"></div>
217+      </div>
218+    </div>
219+  `;
220+
221+  claudeEntryState.host = host;
222+  claudeEntryState.shadow = shadow;
223+
224+  shadow.getElementById("baa-toggle").addEventListener("click", () => {
225+    claudeEntryState.expanded = !claudeEntryState.expanded;
226+    renderClaudeEntry();
227+  });
228+
229+  shadow.getElementById("baa-open-panel").addEventListener("click", () => {
230+    browser.runtime.sendMessage({ type: "focus_controller" }).catch(() => {});
231+    claudeEntryState.expanded = false;
232+    renderClaudeEntry();
233+  });
234+
235+  for (const actionButton of shadow.querySelectorAll("[data-action]")) {
236+    actionButton.addEventListener("click", () => {
237+      runClaudeControlAction(actionButton.dataset.action || "").catch(() => {});
238+    });
239+  }
240+
241+  document.documentElement.append(host);
242+  renderClaudeEntry();
243+}
244+
245+function renderClaudeEntry() {
246+  if (!claudeEntryState.shadow) return;
247+
248+  const snapshot = normalizeEntrySnapshot(claudeEntryState.snapshot);
249+  const badge = claudeEntryState.shadow.getElementById("baa-mode-badge");
250+  const panel = claudeEntryState.shadow.getElementById("baa-panel");
251+  const leader = claudeEntryState.shadow.getElementById("baa-leader");
252+  const queue = claudeEntryState.shadow.getElementById("baa-queue");
253+  const runs = claudeEntryState.shadow.getElementById("baa-runs");
254+  const error = claudeEntryState.shadow.getElementById("baa-error");
255+
256+  badge.textContent = formatModeLabel(snapshot.mode);
257+  badge.className = `badge ${snapshot.mode}`;
258+  leader.textContent = `主控 ${snapshot.leader || "-"}`;
259+  queue.textContent = `队列 ${snapshot.queueDepth == null ? "-" : snapshot.queueDepth}`;
260+  runs.textContent = `运行 ${snapshot.activeRuns == null ? "-" : snapshot.activeRuns}`;
261+  panel.classList.toggle("hidden", !claudeEntryState.expanded);
262+
263+  const busy = !!claudeEntryState.busyAction;
264+  for (const button of claudeEntryState.shadow.querySelectorAll(".panel-btn")) {
265+    if (button.id === "baa-open-panel") continue;
266+    button.disabled = busy;
267+  }
268+
269+  const errorText = claudeEntryState.error || snapshot.error;
270+  error.textContent = errorText || "";
271+  error.classList.toggle("hidden", !errorText);
272+}
273+
274+async function loadClaudeEntrySnapshot() {
275+  const data = await browser.storage.local.get(CONTROL_STATE_KEY);
276+  claudeEntryState.snapshot = normalizeEntrySnapshot(data[CONTROL_STATE_KEY]);
277+  renderClaudeEntry();
278+}
279+
280+async function runClaudeControlAction(action) {
281+  if (!action) return;
282+
283+  claudeEntryState.busyAction = action;
284+  claudeEntryState.error = "";
285+  renderClaudeEntry();
286+
287+  try {
288+    const response = await browser.runtime.sendMessage({
289+      type: "control_plane_command",
290+      action,
291+      source: "claude_entry"
292+    });
293+
294+    if (response?.snapshot) {
295+      claudeEntryState.snapshot = normalizeEntrySnapshot(response.snapshot);
296+    }
297+
298+    if (!response?.ok) {
299+      throw new Error(response?.error || `${action} 执行失败`);
300+    }
301+  } catch (error) {
302+    claudeEntryState.error = error.message;
303+  } finally {
304+    claudeEntryState.busyAction = null;
305+    renderClaudeEntry();
306+  }
307+}
308+
309+sendBridgeMessage("baa_page_bridge_ready", {
310+  url: location.href,
311+  source: "content-script"
312+});
313+
314+window.addEventListener("__baa_ready__", (event) => {
315+  sendBridgeMessage("baa_page_bridge_ready", {
316+    ...(event.detail || {}),
317+    url: event.detail?.url || location.href,
318+    source: event.detail?.source || "page-interceptor"
319+  });
320+});
321+
322+window.addEventListener("__baa_net__", (event) => {
323+  sendBridgeMessage("baa_page_network", event.detail);
324+});
325+
326+window.addEventListener("__baa_sse__", (event) => {
327+  sendBridgeMessage("baa_page_sse", event.detail);
328+});
329+
330+window.addEventListener("__baa_proxy_response__", (event) => {
331+  sendBridgeMessage("baa_page_proxy_response", event.detail);
332+});
333+
334+browser.runtime.onMessage.addListener((message) => {
335+  if (!message || typeof message !== "object") return undefined;
336+  if (message.type !== "baa_page_proxy_request") return undefined;
337+
338+  window.dispatchEvent(new CustomEvent("__baa_proxy_request__", {
339+    detail: JSON.stringify(message.data || {})
340+  }));
341+
342+  return undefined;
343+});
344+
345+browser.storage.onChanged.addListener((changes, areaName) => {
346+  if (areaName !== "local" || !changes[CONTROL_STATE_KEY]) return;
347+  claudeEntryState.snapshot = normalizeEntrySnapshot(changes[CONTROL_STATE_KEY].newValue);
348+  renderClaudeEntry();
349+});
350+
351+if (document.readyState === "loading") {
352+  document.addEventListener("DOMContentLoaded", () => {
353+    ensureClaudeEntry();
354+    loadClaudeEntrySnapshot().catch(() => {});
355+  }, { once: true });
356+} else {
357+  ensureClaudeEntry();
358+  loadClaudeEntrySnapshot().catch(() => {});
359+}

  1@@ -0,0 +1,211 @@
  2+:root {
  3+  --bg: #f3efe3;
  4+  --panel: rgba(255, 251, 240, 0.92);
  5+  --ink: #1b1b1b;
  6+  --muted: #625e52;
  7+  --line: rgba(27, 27, 27, 0.14);
  8+  --accent: #1f6f5f;
  9+  --warn: #a6512f;
 10+  --off: #7f7a70;
 11+}
 12+
 13+* {
 14+  box-sizing: border-box;
 15+}
 16+
 17+body {
 18+  margin: 0;
 19+  min-height: 100vh;
 20+  color: var(--ink);
 21+  background:
 22+    radial-gradient(circle at top left, rgba(31, 111, 95, 0.18), transparent 35%),
 23+    radial-gradient(circle at top right, rgba(166, 81, 47, 0.18), transparent 28%),
 24+    linear-gradient(180deg, #faf6ea 0%, var(--bg) 100%);
 25+  font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
 26+}
 27+
 28+.shell {
 29+  max-width: 1120px;
 30+  margin: 0 auto;
 31+  padding: 24px;
 32+}
 33+
 34+.topbar {
 35+  display: flex;
 36+  justify-content: space-between;
 37+  gap: 16px;
 38+  align-items: end;
 39+  margin-bottom: 18px;
 40+}
 41+
 42+.eyebrow {
 43+  margin: 0 0 4px;
 44+  font-size: 12px;
 45+  text-transform: uppercase;
 46+  letter-spacing: 0.18em;
 47+  color: var(--muted);
 48+}
 49+
 50+h1, h2, p {
 51+  margin: 0;
 52+}
 53+
 54+h1 {
 55+  font-size: 42px;
 56+  line-height: 1;
 57+}
 58+
 59+h2 {
 60+  font-size: 18px;
 61+}
 62+
 63+.actions,
 64+.settings {
 65+  display: flex;
 66+  gap: 10px;
 67+  align-items: center;
 68+  flex-wrap: wrap;
 69+}
 70+
 71+.settings {
 72+  margin-bottom: 18px;
 73+  padding: 14px;
 74+  border: 1px solid var(--line);
 75+  border-radius: 18px;
 76+  background: var(--panel);
 77+  backdrop-filter: blur(12px);
 78+}
 79+
 80+label {
 81+  font-size: 13px;
 82+  color: var(--muted);
 83+}
 84+
 85+input,
 86+button {
 87+  font: inherit;
 88+}
 89+
 90+input {
 91+  min-width: 320px;
 92+  padding: 10px 12px;
 93+  border-radius: 999px;
 94+  border: 1px solid var(--line);
 95+  background: rgba(255, 255, 255, 0.72);
 96+  color: var(--ink);
 97+}
 98+
 99+button {
100+  padding: 10px 14px;
101+  border-radius: 999px;
102+  border: 1px solid var(--line);
103+  background: #fffdf6;
104+  color: var(--ink);
105+  cursor: pointer;
106+}
107+
108+button:hover {
109+  border-color: rgba(27, 27, 27, 0.28);
110+}
111+
112+.grid {
113+  display: grid;
114+  grid-template-columns: repeat(4, minmax(0, 1fr));
115+  gap: 14px;
116+  margin-bottom: 18px;
117+}
118+
119+.card,
120+.panel {
121+  border: 1px solid var(--line);
122+  border-radius: 20px;
123+  background: var(--panel);
124+  backdrop-filter: blur(12px);
125+}
126+
127+.card {
128+  padding: 18px;
129+}
130+
131+.label {
132+  font-size: 12px;
133+  letter-spacing: 0.14em;
134+  text-transform: uppercase;
135+  color: var(--muted);
136+}
137+
138+.value {
139+  margin-top: 12px;
140+  font-size: 28px;
141+  line-height: 1;
142+}
143+
144+.value.on {
145+  color: var(--accent);
146+}
147+
148+.value.warn {
149+  color: var(--warn);
150+}
151+
152+.value.off {
153+  color: var(--off);
154+}
155+
156+.meta {
157+  margin-top: 10px;
158+  font-size: 13px;
159+  color: var(--muted);
160+}
161+
162+.panel {
163+  margin-bottom: 18px;
164+  overflow: hidden;
165+}
166+
167+.panel-head {
168+  display: flex;
169+  justify-content: space-between;
170+  align-items: center;
171+  padding: 16px 18px;
172+  border-bottom: 1px solid var(--line);
173+}
174+
175+.code {
176+  margin: 0;
177+  padding: 18px;
178+  min-height: 100px;
179+  max-height: 300px;
180+  overflow: auto;
181+  font-family: ui-monospace, "SFMono-Regular", "Menlo", monospace;
182+  font-size: 12px;
183+  line-height: 1.55;
184+  white-space: pre-wrap;
185+  word-break: break-word;
186+}
187+
188+@media (max-width: 900px) {
189+  .grid {
190+    grid-template-columns: repeat(2, minmax(0, 1fr));
191+  }
192+}
193+
194+@media (max-width: 640px) {
195+  .shell {
196+    padding: 16px;
197+  }
198+
199+  .topbar {
200+    flex-direction: column;
201+    align-items: start;
202+  }
203+
204+  .grid {
205+    grid-template-columns: 1fr;
206+  }
207+
208+  input {
209+    min-width: 0;
210+    width: 100%;
211+  }
212+}

  1@@ -0,0 +1,128 @@
  2+<!doctype html>
  3+<html lang="zh-CN">
  4+<head>
  5+  <meta charset="utf-8">
  6+  <meta name="viewport" content="width=device-width,initial-scale=1">
  7+  <title>BAA Firefox 管理页</title>
  8+  <link rel="stylesheet" href="controller.css">
  9+</head>
 10+<body>
 11+  <main class="shell">
 12+    <section class="topbar">
 13+      <div>
 14+        <p class="eyebrow">BAA Firefox 控制台</p>
 15+        <h1>管理页面</h1>
 16+      </div>
 17+      <div class="actions">
 18+        <button id="focus-controller-btn" type="button">聚焦本页</button>
 19+        <button id="open-claude-btn" type="button">打开 Claude</button>
 20+        <button id="open-chatgpt-btn" type="button">打开 ChatGPT</button>
 21+        <button id="open-gemini-btn" type="button">打开 Gemini</button>
 22+        <button id="reconnect-btn" type="button">重连 WS</button>
 23+      </div>
 24+    </section>
 25+
 26+    <section class="settings">
 27+      <label for="ws-url">BAA WS</label>
 28+      <input id="ws-url" type="text" spellcheck="false">
 29+      <button id="save-ws-btn" type="button">保存</button>
 30+      <label for="control-base-url">控制 API</label>
 31+      <input id="control-base-url" type="text" spellcheck="false" placeholder="http://127.0.0.1:9800">
 32+      <label for="control-token">令牌</label>
 33+      <input id="control-token" type="password" spellcheck="false" placeholder="browser_session token">
 34+      <button id="save-control-btn" type="button">保存控制面配置</button>
 35+      <button id="refresh-control-btn" type="button">刷新状态</button>
 36+      <button id="pause-btn" type="button">暂停</button>
 37+      <button id="resume-btn" type="button">恢复</button>
 38+      <button id="drain-btn" type="button">排空</button>
 39+    </section>
 40+
 41+    <section class="grid">
 42+      <article class="card">
 43+        <p class="label">WS</p>
 44+        <p id="ws-status" class="value off">未连接</p>
 45+        <p id="client-id" class="meta">客户端: -</p>
 46+      </article>
 47+
 48+      <article class="card">
 49+        <p class="label">跟踪标签页</p>
 50+        <p id="tab-status" class="value off">0 / 3</p>
 51+        <p id="tab-meta" class="meta">标签页: -</p>
 52+      </article>
 53+
 54+      <article class="card">
 55+        <p class="label">凭证</p>
 56+        <p id="cred-status" class="value off">0 / 3</p>
 57+        <p id="cred-meta" class="meta">请求头: 0</p>
 58+      </article>
 59+
 60+      <article class="card">
 61+        <p class="label">端点</p>
 62+        <p id="endpoint-count" class="value">0</p>
 63+        <p class="meta">自动探测</p>
 64+      </article>
 65+
 66+      <article class="card">
 67+        <p class="label">自动化模式</p>
 68+        <p id="control-mode" class="value off">未知</p>
 69+        <p id="control-meta" class="meta">未同步</p>
 70+      </article>
 71+
 72+      <article class="card">
 73+        <p class="label">主控</p>
 74+        <p id="leader-value" class="value off">-</p>
 75+        <p id="leader-meta" class="meta">租约: -</p>
 76+      </article>
 77+
 78+      <article class="card">
 79+        <p class="label">队列</p>
 80+        <p id="queue-value" class="value off">-</p>
 81+        <p id="queue-meta" class="meta">排队任务</p>
 82+      </article>
 83+
 84+      <article class="card">
 85+        <p class="label">活动运行</p>
 86+        <p id="runs-value" class="value off">-</p>
 87+        <p id="runs-meta" class="meta">控制面</p>
 88+      </article>
 89+    </section>
 90+
 91+    <section class="panel">
 92+      <div class="panel-head">
 93+        <h2>控制面</h2>
 94+      </div>
 95+      <pre id="control-view" class="code"></pre>
 96+    </section>
 97+
 98+    <section class="panel">
 99+      <div class="panel-head">
100+        <h2>平台状态</h2>
101+      </div>
102+      <pre id="platforms-view" class="code"></pre>
103+    </section>
104+
105+    <section class="panel">
106+      <div class="panel-head">
107+        <h2>最新请求头</h2>
108+      </div>
109+      <pre id="headers-view" class="code"></pre>
110+    </section>
111+
112+    <section class="panel">
113+      <div class="panel-head">
114+        <h2>已发现端点</h2>
115+      </div>
116+      <pre id="endpoints-view" class="code"></pre>
117+    </section>
118+
119+    <section class="panel">
120+      <div class="panel-head">
121+        <h2>日志</h2>
122+      </div>
123+      <pre id="log-view" class="code"></pre>
124+    </section>
125+  </main>
126+
127+  <script src="controller.js"></script>
128+</body>
129+</html>