chrome-extension-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome Extension Manifest Version 3 Privacy-First Architect

Chrome Extension Manifest Version 3 隐私优先架构设计

Elite-level Chrome extension architecture and debugging workflow with privacy-first defaults and least-privilege permissions.

具备隐私优先默认设置和最小权限原则的顶级Chrome扩展架构与调试工作流。

Overview / When to Apply

概述 / 适用场景

Use this skill when the user asks about browser extensions (especially Chrome MV3) including:

Side panel / sidebar UX (Chrome
```
chrome.sidePanel
```
, Firefox
```
sidebar_action
```
, Safari constraints)
MV3 background service worker lifecycle bugs (lost globals, listeners, wakeups)
Permission review, host permission minimization, privacy posture
Storage / persistence choices (what survives popup close, SW termination, browser restart)
Cross-browser strategy (Chrome/Edge vs Firefox vs Safari)

Default target: Chrome MV3. If the user doesn’t specify browser(s), assume Chrome stable.

当用户询问浏览器扩展（尤其是Chrome MV3）相关问题时使用本技能，包括：

侧边栏/侧边栏UX（Chrome
```
chrome.sidePanel
```
、Firefox
```
sidebar_action
```
、Safari限制）
MV3后台服务工作者（service worker）生命周期问题（全局变量丢失、监听器失效、唤醒问题）
权限审核、主机权限最小化、隐私态势
存储/持久化选择（哪些数据能在弹窗关闭、服务工作者终止、浏览器重启后保留）
跨浏览器策略（Chrome/Edge 对比 Firefox 对比 Safari）

默认目标环境：Chrome MV3。如果用户未指定浏览器，默认采用Chrome稳定版。

Non-Negotiable Rules (must follow)

不可违背的规则（必须遵守）

Start every major answer with target + scope.

Format:

Target: <Chrome MV3 | Firefox MV3 | Safari> | Scope: <side panel | permissions | lifecycle | storage | compat | debugging>

Privacy-first default.
- Prefer designs that keep data on-device.
- Avoid collecting page content, browsing history, or host-wide access unless explicitly required.
Least privilege, always.
- Request only the minimal
```
permissions
```
  + minimal
```
host_permissions
```
  .
- Prefer:
```
activeTab
```
  ,
```
scripting
```
  (targeted injection),
```
declarativeNetRequest
```
  (when network rules are needed).
- Avoid:
```
<all_urls>
```
  ,
```
*://*/*
```
  , broad
```
tabs
```
  , unbounded host permissions.
Every permission/API must be justified + privacy-risk tagged.
- For each permission you mention, include:
  - Why it’s needed
  - What data access it enables
  - Safer alternatives (if any)
MV3 service worker reality check (single biggest bug source).
- Service worker is non-persistent; globals can disappear at any time.
- Never rely on in-memory state for correctness.
- Register listeners at top-level synchronously.
Side panel architecture must be modern.
- Chrome:
```
chrome.sidePanel
```
  +
```
setPanelBehavior({ openPanelOnActionClick: true })
```
  .
- Use
```
setOptions()
```
  to vary panel path per-tab / conditionally.
- Use layout awareness for LTR/RTL.
Cross-browser: feature-detect, don’t UA-sniff.
- Use conditional code paths (Chrome
```
chrome.sidePanel
```
  vs Firefox
```
browser.sidebarAction
```
  ).
- State what won’t work on a given browser and why.

所有重要回答以目标环境 + 范围开头。

格式：

Target: <Chrome MV3 | Firefox MV3 | Safari> | Scope: <side panel | permissions | lifecycle | storage | compat | debugging>

隐私优先默认原则。
- 优先选择将数据保留在设备本地的设计方案。
- 除非明确要求，否则避免收集页面内容、浏览历史或全局主机访问权限。
始终遵循最小权限原则。
- 仅请求必要的
```
permissions
```
  + 最小范围的
```
host_permissions
```
  。
- 优先使用：
```
activeTab
```
  、
```
scripting
```
  （定向注入）、
```
declarativeNetRequest
```
  （当需要网络规则时）。
- 避免使用：
```
<all_urls>
```
  、
```
*://*/*
```
  、宽泛的
```
tabs
```
  权限、无限制的主机权限。
每个权限/API必须说明理由 + 标记隐私风险。
- 对于提到的每个权限，需包含：
  - 为什么需要该权限
  - 它能访问哪些数据
  - 更安全的替代方案（如果有）
MV3服务工作者现实检查（最大的bug来源）。
- 服务工作者是非持久化的；全局变量可能随时消失。
- 永远不要依赖内存中的状态来保证正确性。
- 在顶层同步注册监听器。
侧边栏架构必须采用现代方案。
- Chrome：使用
```
chrome.sidePanel
```
  +
```
setPanelBehavior({ openPanelOnActionClick: true })
```
  。
- 使用
```
setOptions()
```
  根据标签页或条件动态更改面板路径。
- 支持LTR/RTL布局适配。
跨浏览器：功能检测，而非UA嗅探。
- 使用条件代码分支（Chrome
```
chrome.sidePanel
```
  对比 Firefox
```
browser.sidebarAction
```
  ）。
- 说明在特定浏览器中无法实现的功能及原因。

How to Use This Skill (workflow)

技能使用流程

Step 0 — Confirm target environment

步骤0 — 确认目标环境

Ask (or infer) these quickly:

Browser(s): Chrome / Edge / Firefox / Safari
Manifest version: default to MV3
UI mode: side panel, action popup, overlay in-page, options page
Data sensitivity: what data is touched? (page content? URLs? credentials?)

快速询问（或推断）以下信息：

浏览器：Chrome / Edge / Firefox / Safari
Manifest版本：默认采用MV3
UI模式：侧边栏、动作弹窗、页面内覆盖层、选项页
数据敏感度：涉及哪些数据？（页面内容？URL？凭据？）

Step 1 — Pick the correct architecture (decision tree)

步骤1 — 选择正确的架构（决策树）

Need a persistent/reusable UI?
├─ Chrome/Edge -> sidepanel (chrome.sidePanel)
├─ Firefox -> sidebar_action / browser.sidebarAction
└─ Safari -> expect limitations; consider alternative UI (popup/options) or separate Safari strategy

Need to interact with the current tab?
├─ One-off user action -> activeTab + scripting
└─ Always-on per-site -> narrow host_permissions only for required domains

Need DOM / rendering in background?
└─ Use offscreen document (Chrome) or move work into panel/page context

Then read the matching references:

Side panel design/API ->
```
references/sidepanel/README.md
```
Permission review ->
```
references/permissions/README.md
```

SW lifecycle ->

references/service-worker-lifecycle/README.md

Storage strategy ->
```
references/storage-state/README.md
```
Cross-browser ->
```
references/cross-browser/README.md
```
Debugging playbook ->
```
references/debugging/README.md
```
Copy/paste templates ->
```
references/templates/README.md
```

需要持久/可复用的UI？
├─ Chrome/Edge -> 侧边栏（chrome.sidePanel）
├─ Firefox -> sidebar_action / browser.sidebarAction
└─ Safari -> 存在限制；考虑替代UI（弹窗/选项页）或单独的Safari适配策略

需要与当前标签页交互？
├─ 一次性用户操作 -> activeTab + scripting
└─ 站点常驻功能 -> 仅对所需域名申请窄范围host_permissions

需要在后台处理DOM/渲染？
└─ 使用离屏文档（Chrome）或将工作转移到面板/页面上下文

然后查阅对应的参考文档：

侧边栏设计/API ->
```
references/sidepanel/README.md
```
权限审核 ->
```
references/permissions/README.md
```

服务工作者生命周期 ->

references/service-worker-lifecycle/README.md

存储策略 ->
```
references/storage-state/README.md
```
跨浏览器适配 ->
```
references/cross-browser/README.md
```
调试指南 ->
```
references/debugging/README.md
```
可复用模板 ->
```
references/templates/README.md
```

Step 2 — Produce an answer in a strict structure

步骤2 — 生成结构严谨的回答

Use this response skeleton for most user questions:

Target + assumptions (1–3 lines)
Recommended architecture (what runs where)
Permissions proposal (minimal set) + privacy warnings
State & persistence plan (storage choice) + lifecycle gotchas
Code snippets (manifest + SW + UI + messaging)
Debug checklist (what to check when it breaks)

对于大多数用户问题，使用以下响应框架：

目标环境 + 假设前提（1–3行）
推荐架构（各组件运行位置）
权限方案（最小权限集合）+ 隐私警告
状态与持久化方案（存储选择）+ 生命周期注意事项
代码片段（manifest + 服务工作者 + UI + 消息传递）
调试检查清单（故障排查要点）

Examples (input → expected output)

示例（输入 → 预期输出）

Example 1: “I want a persistent sidebar note-taker”

示例1：“我想要一个持久化的侧边栏笔记工具”

Input: “Build a MV3 extension with a sidebar that saves notes per tab. Minimal permissions.”

Expected output (high level):

Target: Chrome MV3
Recommend
```
chrome.sidePanel
```
with panel path + per-tab context
Permissions:
```
sidePanel
```
,
```
storage
```
, optional
```
activeTab
```
if reading title/url on demand
Storage:
```
chrome.storage.local
```
keyed by
```
tabId
```
(ephemeral) +
```
url
```
(stable) with explicit privacy warning about storing URLs
Provide manifest + SW
```
setPanelBehavior
```
+ message passing between panel and SW

输入：“开发一个带侧边栏的MV3扩展，可按标签页保存笔记。要求权限最小化。”

预期输出（概要）：

Target: Chrome MV3
推荐使用
```
chrome.sidePanel
```
，结合面板路径与标签页上下文
权限：
```
sidePanel
```
、
```
storage
```
，若需按需读取标题/URL可额外添加
```
activeTab
```
存储：使用
```
chrome.storage.local
```
，按
```
tabId
```
（临时）+
```
url
```
（稳定）作为键，并明确给出存储URL的隐私警告
提供manifest配置 + 服务工作者
```
setPanelBehavior
```
代码 + 面板与服务工作者间的消息传递实现

Example 2: “Why does my background state reset?”

示例2：“为什么我的后台状态会重置？”

Input: “My service worker forgets auth after a minute. I store it in a global variable.”

Expected output (high level):

Target: Chrome MV3
Explain SW termination; globals lost
Move auth to
```
chrome.storage.local
```
(or
```
session
```
for ephemeral) with encryption guidance
Add reconnect logic; register listeners top-level
Provide code for a storage-backed session and messaging

输入：“我的服务工作者在一分钟后就忘记了认证信息。我把它存在全局变量里。”

预期输出（概要）：

Target: Chrome MV3
解释服务工作者终止机制；全局变量会丢失
建议将认证信息迁移到
```
chrome.storage.local
```
（或
```
session
```
用于临时存储），并提供加密指导
添加重连逻辑；在顶层注册监听器
提供基于存储的会话管理与消息传递代码

Example 3: “Make it work in Firefox too”

示例3：“让它也能在Firefox上运行”

Input: “I use sidePanel in Chrome. How do I support Firefox?”

Expected output (high level):

Target: Chrome MV3 + Firefox
Explain Firefox
```
sidebar_action
```
differences (no programmatic open; UX expectations)
Provide feature-detection wrapper and separate manifest keys
Recommend
```
webextension-polyfill
```
for promise-based APIs where appropriate

输入：“我在Chrome里用了sidePanel。怎么适配Firefox？”

预期输出（概要）：

Target: Chrome MV3 + Firefox
解释Firefox
```
sidebar_action
```
的差异（无程序化打开功能；UX预期不同）
提供功能检测封装与独立的manifest配置项
建议在合适的场景下使用
```
webextension-polyfill
```
实现基于Promise的API

Best Practices / Pitfalls

最佳实践 / 常见陷阱

Don’t request
tabs
unless you truly need cross-tab enumeration. It’s a high-privacy-impact permission.
Don’t store full URLs/content unless necessary. If you must, be explicit about retention and user controls.
Don’t rely on “keep-alive hacks”. Use real MV3 primitives (
```
alarms
```
, message triggers, offscreen documents).
Side panel ≠ popup. Side panel is long-lived UI; treat it as an app surface with explicit user action flows.

**除非确实需要跨标签页枚举，否则不要申请
```
tabs
```
权限。**这是高隐私影响权限。
**除非必要，否则不要存储完整URL/页面内容。**如果必须存储，需明确说明保留期限与用户控制方式。
**不要依赖“保活技巧”。**使用标准MV3原语（
```
alarms
```
、消息触发、离屏文档）。
**侧边栏 ≠ 弹窗。**侧边栏是长驻UI；需将其视为应用界面，设计明确的用户操作流程。

Resources

资源

Install helpers are in

resources/install.sh

安装辅助脚本位于

resources/install.sh

。