From 8525a8eeb9c87ce571a6ce5eb82e0e733a1aa1d7 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:50:03 +0900
Subject: [PATCH 01/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3?=
 =?UTF-8?q?=E8=BF=87=E6=9C=9F=E6=9E=B6=E6=9E=84/=E6=B5=8B=E8=AF=95/i18n=20?=
 =?UTF-8?q?=E4=BA=8B=E5=AE=9E=E5=B9=B6=E8=A7=A3=E5=86=B3=E8=B7=A8=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E6=94=BF=E7=AD=96=E5=86=B2=E7=AA=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AGENTS.md/copilot-instructions.md/architecture*.md: 用 Repo<T>/DAO<T>/OPFSRepo 后端分类
  替换"新实体一律 Repo<T>"的过期普遍规则；架构速览补充 agent/、extension/、queue.ts；
  新增 docs/references/architecture-agent.md 覆盖 Agent 子系统（工具注册表、LLM 工具循环、
  后台会话/子代理/定时任务生命周期、存储后端、跨 context 委派边界）
- architecture-build.md: rspack entry 补上 common、json.worker
- architecture-gm-api.md: 明确 sendMessage vs connect 的选择依据与 DOM/linter 落点路径
- develop.md: 记录 toast.ts 对 no-restricted-imports 的完整豁免（同时覆盖 Sonner 与 Radix）
- verification.md: 补充"何时可跳过本指南"、按比例的前置检查、TDD 例外与 bug 复现的同步、
  可见的 report.md 创建步骤、双主题验证注意事项
- verification-debugging.md: 补充 Firefox 无独立 Offscreen 页面的调试提示
- design-patterns.md: 移除过期的固定 locale 数与未经测量的百分比断言
- translation.md/src/locales/README.md: 记录 i18n-usage.test.ts 的真实扫描范围与盲区；
  修正 i8next 拼写；翻译工作流去重指向 translation.md
- DOC-MAINTENANCE.md: 扩大到全部 tracked agent/contributor Markdown，新增
  baseline/working-diff/final-tree 区分、政策一致性检查、隐私扫描、批量编辑建议
- packages/{message,filesystem,cloudscript}/README.md: 修正过期/模糊的实现描述
- 删除未被引用且已过期的 src/pages/options/routes/Setting/Setting/i18nKeys.md 迁移快照

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/copilot-instructions.md               |  21 ++-
 AGENTS.md                                     |  19 +-
 docs/DOC-MAINTENANCE.md                       |  97 ++++++++++-
 docs/README.md                                |   6 +-
 docs/architecture.md                          |  28 ++-
 docs/design.md                                |   2 +-
 docs/develop.md                               |   6 +
 docs/pull-request.md                          |  17 +-
 docs/references/architecture-agent.md         | 125 ++++++++++++++
 docs/references/architecture-build.md         |  10 +-
 docs/references/architecture-data.md          |  71 ++++++--
 docs/references/architecture-gm-api.md        |  27 ++-
 docs/references/architecture-services.md      |  53 +++++-
 docs/references/design-components.md          |   3 +-
 docs/references/design-patterns.md            |   9 +-
 docs/references/design-tokens.md              |   2 +-
 docs/references/develop-testing.md            |   8 +-
 docs/references/verification-debugging.md     |   7 +
 .../verification-report-template.md           |   4 +
 docs/translation.md                           |   9 +
 docs/verification.md                          |  72 ++++++--
 packages/cloudscript/README.md                |  12 +-
 packages/filesystem/README.md                 |  17 +-
 packages/message/README.md                    |  23 ++-
 src/locales/README.md                         |   9 +-
 src/pages/options/routes/Setting/i18nKeys.md  | 163 ------------------
 26 files changed, 558 insertions(+), 262 deletions(-)
 create mode 100644 docs/references/architecture-agent.md
 delete mode 100644 src/pages/options/routes/Setting/i18nKeys.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 661d44371..c36abade4 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -10,10 +10,10 @@ ScriptCat is a sophisticated browser extension that executes user scripts with a
 
 ### Core Components
 - **Service Worker** (`src/service_worker.ts`) - Main background process handling script management, installations, and chrome APIs
-- **Offscreen** (`src/offscreen.ts`) - Isolated background environment for running background/scheduled scripts
-- **Sandbox** (`src/sandbox.ts`) - Secure execution environment inside offscreen for script isolation
+- **Offscreen** (`src/offscreen.ts`) - Isolated background environment for running background/scheduled scripts on Chrome. Firefox MV3 has no separate Offscreen document; `EventPageOffscreenManager` (`src/app/service/offscreen/event_page_manager.ts`) runs the same logic inside the DOM-capable background event page instead.
+- **Sandbox** (`src/sandbox.ts`) - Secure execution environment for background/scheduled scripts only (no page context); isolated via `with(arguments[0])`
 - **Content Scripts** (`src/content.ts`) - Injected into web pages to execute user scripts
-- **Inject Scripts** (`src/inject.ts`) - Runs in page context with access to page globals
+- **Inject Scripts** (`src/inject.ts`) - Runs in page context with access to page globals, including `unsafeWindow`
 
 ### Message Passing System
 ScriptCat uses a sophisticated message passing architecture (`packages/message/`):
@@ -22,7 +22,7 @@ ScriptCat uses a sophisticated message passing architecture (`packages/message/`
 - **CustomEventMessage** - CustomEvent-based communication between content/inject scripts
 - **MessageQueue** - Cross-environment event broadcasting system
 
-Key pattern: All communication flows through Service Worker → Offscreen → Sandbox for background scripts, or Service Worker → Content → Inject for page scripts.
+Key pattern: background scripts flow Service Worker → Offscreen → Sandbox; page scripts flow Service Worker → Content → Inject. Other paths exist alongside this: UI pages talk to the Service Worker directly, `MessageQueue` broadcasts across contexts outside the request/reply chain, and Agent storage (OPFS/Dexie) is read/written without going through this message flow.
 
 ### Script Execution Flow
 1. **Page Scripts**: Service Worker registers with `chrome.userScripts` → injected into pages
@@ -33,15 +33,14 @@ Key pattern: All communication flows through Service Worker → Offscreen → Sa
 
 ### Path Aliases
 ```typescript
-"@App": "./src/"
-"@Packages": "./packages/"
-"@Tests": "./tests/"
+import x from "@App/service_worker";   // -> src/service_worker
+import y from "@Packages/message";     // -> packages/message
+import z from "@Tests/utils";          // -> tests/utils
 ```
 
 ### Repository Pattern
-All data access uses DAO classes extending `Repo<T>` base class:
+Persistence is a small backend taxonomy, not one base class: `Repo<T>` (`chrome.storage.local`, e.g. `ScriptDAO`, `ResourceDAO`, `SubscribeDAO`), `DAO<T>` (Dexie/IndexedDB, e.g. `LoggerDAO`), `OPFSRepo` (OPFS-backed data, e.g. `AgentChatRepo`, `SkillRepo`), and a few custom repositories (e.g. `TrashScriptDAO`) where none of those fit. See [`docs/references/architecture-data.md`](../docs/references/architecture-data.md) for the full inventory and entity-decision recipe.
 ```typescript
-// Example: ScriptDAO, ResourceDAO, SubscribeDAO
 export class ScriptDAO extends Repo<Script> {
   public save(val: Script) { return super._save(val.uuid, val); }
 }
@@ -136,10 +135,10 @@ pnpm run coverage      # Generate coverage reports
 - Use `pnpm run dev:noMap` for incognito window development
 - Background script changes require extension reload
 - Message passing debugging available in service worker console
-- Sandbox script execution isolated from page context - use `unsafeWindow` for page access
+- Sandbox (background/scheduled scripts) has no page context; page-context access via `unsafeWindow` is only available to Inject/page scripts
 
 ## File Structure Patterns
-- Tests co-located with source files (`.test.ts` suffix)
+- Tests co-located with source files (`.test.ts` / `.test.tsx` suffix), plus end-to-end specs under `e2e/*.spec.ts`
 - Template files use `.tpl` extension for build-time processing
 - Configuration files use factory pattern for environment-specific setup
 
diff --git a/AGENTS.md b/AGENTS.md
index 9f01f3530..c2828762f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,10 +25,12 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working
 > (`src/locales/<locale>/*.json` namespace files, per-language docs, UI copy, or test snapshots), you must first
 > read that guide and follow the matching `docs/references/terminology-<locale>.md` if it exists.
 
-> **Before adding, editing, reorganizing, or reviewing any contributor doc (this file or `docs/*`), read
+> **Before adding, editing, reorganizing, or reviewing any tracked agent/contributor Markdown — this file,
+> `docs/*`, `.github/*.md`, package-local READMEs, and source-local READMEs — read
 > [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md)** — keep the doc set organized (links resolve, index
-> current, no duplication) and every claim factually true against the current branch (*if you can't grep it on
-> this branch, don't claim it*).
+> current, no duplication, no cross-document policy conflicts) and every claim factually true against the current
+> branch (*if you can't grep it on this branch, don't claim it*). That guide owns the full checklist; don't copy
+> it into this always-loaded file.
 
 > **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — this
 > repo's PR description structure and evidence rules.
@@ -53,9 +55,9 @@ isn't universal, that's called out in the item itself.
 - **Fix root causes, not symptoms — refactor over patch.** No `as any` / `// @ts-ignore` / try-catch swallow / defensive skips to make errors disappear (宁愿重构也不要打补丁). If a test fails, fix the code, not the test — the narrow exceptions (a wrong test contract; a test that never carried value) are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
 - **Confirm before you fix.** Before touching a reported bug, reproduce it and confirm it actually exists — never fix from assumption. Capture the reproduction, then fix, **in that order** (确定 bug 存在 → 写测试或记录验证证据 → 修复); how to reproduce and what counts as capture are in [`docs/verification.md`](docs/verification.md) and the TDD entry below.
 - **TDD/BDD first, for changes that alter observable behavior.** Write failing tests **before** implementing new or changed behavior, using BDD-style Chinese `describe`/`it` titles. Two narrow exceptions — neither a blanket file/task category — are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#when-tdd-doesnt-apply). (Runner, mocks, and how to run tests are in `docs/develop.md`.)
-- **SOLID, high cohesion & low coupling — applied to the existing extension points.** `Repo<T>` for new entities, `Group.on(...)` for new messages. Inject `Group` / `IMessageQueue` / DAOs via constructor; don't `new` them inside methods. Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
+- **SOLID, high cohesion & low coupling — applied to the existing extension points.** Pick a persistence backend by matching an existing entity with the same needs, not by defaulting to one pattern: `Repo<T>` backs `chrome.storage.local`, `DAO<T>` backs Dexie/IndexedDB, `OPFSRepo` backs OPFS-stored data, and a custom repository (e.g. `TrashScriptDAO`) is only for cases none of those fit. For messages, use `Group.on(...)`. Context services still take `Group` / `IMessageQueue` / DAOs via constructor injection; the Agent subsystem also mixes in plain core modules and service-worker composition with narrower injected interfaces — don't force every new class into the same constructor shape. Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
 - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime.
-- **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction.
+- **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. Don't remove or narrow currently supported behavior just to simplify a fix — only do so when the task or an already-verified contract explicitly calls for that change.
 - **No dead code or `// removed` markers** — git remembers. Delete unused code outright.
 
 ## Architecture
@@ -92,9 +94,10 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 `ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔ Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome), `CustomEventMessage` (CustomEvent — Content ↔ Inject), `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers
-- Services in `src/app/service/<context>/` — split by execution context. Constructor-injected `Group`, `IMessageQueue`, DAOs.
-- DAOs in `src/app/repo/` extend `Repo<T>` (chrome.storage + cache): `ScriptDAO`, `ValueDAO`, `ResourceDAO`, `PermissionDAO`, `SubscribeDAO`.
-- **GM API** split across content / SW / offscreen, each a `GMApi` (content built on `GM_Base`; SW — permission verify, cross-origin; offscreen — DOM-dependent background-script APIs); values via `ValueService`.
+- Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/` — split by execution context, constructor-injected `Group`/`IMessageQueue`/DAOs) plus **cross-cutting subsystems** (`agent/` — see below; `extension/`; `queue.ts`). Full inventory and the "adding a service" recipe: [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
+- Persistence is a small backend taxonomy, not one pattern: `Repo<T>` (`chrome.storage.local`), `DAO<T>` (Dexie/IndexedDB), `OPFSRepo` (OPFS-backed data), and a few custom repositories where none of those fit. Full inventory and the entity-decision recipe: [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
+- **GM API** split across content / SW / offscreen, each a `GMApi` (content built on `GM_Base`; SW — permission verify, cross-origin; offscreen — DOM-dependent background-script APIs); values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
+- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five runtime contexts, not a sixth context: `core/` (provider-agnostic tool loop, model context, tool registry), `service_worker/` (chat/task/skill/MCP services, composed into `ServiceWorkerManager`), plus content-side CAT/GM API and offscreen/sandbox delegation for skill-script execution. Details: [`docs/architecture.md`](docs/architecture.md).
 
 ### Browser Extension APIs (MV3)
 `chrome.userScripts` (page injection), Offscreen API (DOM in background), Declarative Net Request (intercepts `.user.js` URLs to trigger install flow).
diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
index 990b64a11..69a35e753 100644
--- a/docs/DOC-MAINTENANCE.md
+++ b/docs/DOC-MAINTENANCE.md
@@ -1,12 +1,16 @@
 # Documentation Maintenance & Fact-Check Guide
 
-> **Read this before adding, editing, reorganizing, or reviewing any contributor doc** (`AGENTS.md`,
-> `docs/*`). It has two jobs: keep the doc set **organized** (links resolve, index current, no duplication)
-> and keep every claim **factually true against the current branch**.
+> **Read this before adding, editing, reorganizing, or reviewing any tracked agent/contributor Markdown** —
+> `AGENTS.md`, everything under `docs/*`, `.github/*.md`, and every package-local or source-local `README.md`.
+> Don't work off a fixed file list: run `git ls-files '*.md'` to discover the current set, including hidden
+> `.github` docs and READMEs that live next to source (e.g. `src/locales/README.md`,
+> `packages/*/README.md`). This guide has three jobs: keep the doc set **organized** (links resolve, index
+> current, no duplication), keep every claim **factually true against the current branch**, and keep
+> **cross-document policy consistent** (no two docs giving conflicting rules for the same situation).
 
 ## Why this exists
 
-The contributor docs describe a living codebase, so two failure modes recur:
+The contributor docs describe a living codebase, so several failure modes recur:
 
 - **Stale facts** — a class is renamed, a count changes, a file moves; the doc keeps the old value. Real
   examples caught in review: docs named the offscreen GM API `OffscreenGMApi` (no such class — it is `GMApi`),
@@ -14,6 +18,12 @@ The contributor docs describe a living codebase, so two failure modes recur:
 - **Branch leakage** — work that only lives on a feature branch gets documented as if it ships on `main`.
   Example: a subsystem committed only on a feature branch (not on `main`) gets written into `main`'s
   quick-map, misleading readers into expecting code that is not there.
+- **Policy conflict** — two docs state the same rule with different conditions (e.g. one says a TDD failing
+  test is unconditional, another defines an exception for it). An agent that reads only one of them then
+  follows a rule the other doc already narrowed or overturned.
+- **Stale-after-resolution** — code and docs change in the same PR, or a conflict gets resolved during rebase,
+  and the fact-check was only ever run against an old `HEAD`. The claim looks verified but was never checked
+  against the tree that actually ships.
 
 **Rule of thumb: if you can't `git grep` it in the committed code on this branch, don't claim it.** Verify with
 git-aware commands (`git grep`, `git ls-files`, `git ls-tree`) — never a plain `rg`/`ls`, which also match
@@ -21,6 +31,59 @@ git-aware commands (`git grep`, `git ls-files`, `git ls-tree`) — never a plain
 `main` will masquerade as shipped (this is exactly how a feature-branch-only subsystem sneaks into a `main` doc).
 Aspirational / feature-branch content belongs in that branch's docs, or is clearly marked as planned.
 
+## Baseline tree, working diff, proposed final tree
+
+A fact-check against a single snapshot isn't enough when code and docs change together:
+
+- **Baseline tree** — the committed state you started from (`git rev-parse HEAD`).
+- **Working diff** — your uncommitted changes, both code and docs, on top of the baseline.
+- **Proposed final tree** — what will actually exist after your change lands, including any rebase or
+  conflict resolution.
+
+If code and docs are changing in the same PR, checking only the old `HEAD` misses facts the working diff is
+about to introduce or remove. After a rebase, merge, or conflict resolution, re-run the fact-check against the
+**resolved final tree**, not your last pre-conflict result — conflict resolution can silently reintroduce a
+stale fact or drop a doc update.
+
+## Policy-consistency check
+
+Beyond individual facts, check that a rule stated in one doc doesn't contradict the same rule stated
+elsewhere. For every rule you touch or that a fact-check reveals, identify: **owner** (which doc holds the
+canonical version), **trigger** (when it applies), **action** (what to do), **exception** (documented
+carve-outs), **fallback** (what to do when the exception applies), **evidence** (how compliance is checked),
+**stop condition** (when the rule no longer applies). Search for absolute language that tends to hide an
+undocumented exception or a stale blanket rule:
+
+```bash
+git grep -n -Ei 'always|never|all |must|必须|绝不|所有' -- AGENTS.md .github/*.md docs/*.md docs/references/*.md
+git grep -n -Ei 'TDD|failing test|committed test|fix the code|自动化.*不可' -- '*.md'
+```
+
+Every hit is a review-queue entry, not an automatic rewrite — confirm whether the absolute wording is actually
+correct (some are intentional non-negotiables) before loosening it, and confirm a downstream doc's exception
+survives when you touch the upstream rule it narrows.
+
+## Lint / config documentation depth
+
+When a doc describes an ESLint rule, tsconfig setting, or similar config-driven behavior, record the
+**files/ignores/overrides that produce the effective result**, not just the rule name — a rule can be globally
+`"error"` and then `"off"` for a specific file glob, and only listing the rule name hides that. Verify against
+`eslint.config.mjs` (or the relevant config file) directly; don't infer scope from the rule name alone.
+
+## Batch edits: verify small, then scale
+
+For a mechanical, repeatable change across many files (heading rename, link format, boilerplate insert),
+validate the change on one representative file or a small batch first and check the diff before scaling up.
+This is advice for genuinely mechanical batch tooling — it is not a mandatory process for every small,
+one-off edit.
+
+## Privacy / sanitization gate
+
+Before committing or opening a PR, check the final diff and PR body for local absolute paths, home-directory
+shortcuts, `file://` URIs, temp-directory paths, private attachment names, and other identifying information
+that shouldn't leave the contributor's machine. This check needs human judgment — this guide's own examples
+of sanitization patterns can otherwise look like matches — so don't rely on a blind automated strip.
+
 ## Doc set & responsibilities (don't duplicate — cross-link)
 
 | Doc | Owns |
@@ -33,11 +96,14 @@ Aspirational / feature-branch content belongs in that branch's docs, or is clear
 | [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md). |
 | [`cloud-sync.md`](./cloud-sync.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
-| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules + fact-check / anti-drift discipline. |
+| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules, fact-check / anti-drift discipline, and policy-consistency checks — for every tracked agent/contributor Markdown file, not just `AGENTS.md` + `docs/*`. |
 | [`README.md`](./README.md) | The index that points to all of the above. |
+| `.github/copilot-instructions.md` | Copilot-specific entry point and any genuine tool-specific differences; shared facts (architecture, commands, testing, design, translation, PR mechanics) route to the owning doc above instead of being copied. |
+| Package-local `README.md` (e.g. `packages/message/README.md`, `packages/filesystem/README.md`) | That package's purpose, boundaries, entry points, and local gotchas — not a duplicate of repo-wide architecture or coding policy. |
 
 When you move a fact, move it to the doc that **owns** it and cross-link — never copy the same fact into two
-places, or they drift apart.
+places, or they drift apart. To discover the current full set instead of relying on this table alone, run
+`git ls-files '*.md'`.
 
 ## Checklist 1 — Organization (every doc change)
 
@@ -111,8 +177,27 @@ for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs
 done
 ```
 
+Link integrity is a **best-effort signal**, not a proof of correctness: the shell pipeline above skips fenced
+and inline code, but it doesn't resolve reference-style links, complex Markdown link destinations, or GitHub's
+full heading-anchor slug rules. A clean run means no missing link *targets* were found — it does not mean every
+anchor fragment or every link's intent has been verified. Check changed fragment links by hand (or by rendering
+the page), especially around CJK text, punctuation, and duplicate-heading auto-suffixes (`#foo-1`). Only add an
+anchor when the link text explicitly points at one particular section; a link meant to reference the whole
+document should stay a file-level link without a fragment.
+
+Duplicate headings (exact or near-duplicate H1/H2 text across files) are a **review queue item, not an
+auto-fix**: check inbound links and whether the duplication is actually confusing before renaming or merging
+a heading — an external deep link into that heading breaks if you rename it without a compatibility anchor.
+
 ## When you find a discrepancy
 
 Fix the **doc** to match the code — the code on this branch is the source of truth. The exception: if the code
 itself is wrong (a real bug), fix the code and say so in the PR. Either way, never silently drop a check you
 couldn't satisfy — surface it in the PR description so a reviewer can confirm.
+
+## Honest completion claims
+
+Only say "full scan", "verified", or "all fixed" when the scope and evidence actually cover that claim — i.e.
+you ran the check against every file the claim implies, on the proposed final tree. A more accurate summary is
+usually narrower: which docs got a fact/policy audit and what evidence backs it, versus which docs (e.g.
+localized/user-facing/security docs) only got a structural check or were intentionally left unchanged.
diff --git a/docs/README.md b/docs/README.md
index ea3e0190d..17b969e26 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,21 +6,21 @@
 
 | 文档 | 说明 |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源(`CLAUDE.md` 仅导入它)。 |
+| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源 —— 但仅相对 `CLAUDE.md`(其仅导入它)成立;`.github/copilot-instructions.md` 是 Copilot 的独立入口,与本文件共享的事实需在两边都改动时做一致性核对(parity review)。 |
 | [`develop.md`](./develop.md) | 开发规范:命令、目录结构、编码风格、UI/主题、i18n、提交/PR 流程;测试机制(含 Vitest 性能)拆到 [`references/develop-testing.md`](./references/develop-testing.md)。**写代码前先读。** |
 | [`pull-request.md`](./pull-request.md) | PR 描述指南:代理与贡献者使用的详细章节、按变更类型取舍规则、验证与审查信息要求。 |
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |
 | [`verification.md`](./verification.md) | 功能验证指南:用一次性 scratch 脚本驱动真实扩展做端到端验证(不跑全量 E2E、不加永久用例);报告模板拆到 [`references/verification-report-template.md`](./references/verification-report-template.md),调试 FAQ 拆到 [`references/verification-debugging.md`](./references/verification-debugging.md)。**验证改动是否真正跑通时读。** |
 | [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)。 |
 | [`cloud-sync.md`](./cloud-sync.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
-| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、一键校验脚本。**改/审文档前先读。** |
+| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、跨文档政策一致性核对、隐私清理、以及在 resolved final tree 上的复核方法,覆盖全部 tracked 的 agent/contributor Markdown(不止 `AGENTS.md` + `docs/*`,还包括 `.github/*.md`、package-local README)。**改/审文档前先读。** |
 
 ## 翻译 / Translation
 
 | 文档 | 说明 |
 | --- | --- |
 | [`translation.md`](./translation.md) | 翻译 / 本地化指南(单一信息源):术语与修改规则、工作流、提取翻译提示词。**翻译前先读。** |
-| [`translation.md` 术语规范表](./translation.md#各语言术语规范--per-locale-terminology) | 9 个语言地区的术语与界面文案规范 `terminology-<locale>.md`(en-US / zh-CN / zh-TW / ja-JP / ru-RU / de-DE / vi-VN / tr-TR / pt-BR)。 |
+| [`translation.md` 术语规范表](./translation.md#各语言术语规范--per-locale-terminology) | 当前 locale 清单与对应 `terminology-<locale>.md` 的 canonical table —— 数量与列表以该表为准,本索引不重复维护一份固定副本。 |
 
 ## 贡献指南 / Contributing
 
diff --git a/docs/architecture.md b/docs/architecture.md
index cbe6f5f7a..de5448672 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,10 +16,11 @@
 - [The Five Contexts (Process Model)](#the-five-contexts-process-model)
 - [Message Passing](#message-passing)
 - [Service layer](./references/architecture-services.md)
-- [Data layer (Repo<T> + DAOs)](./references/architecture-data.md)
+- [Data layer (backend taxonomy: Repo\<T\> / DAO\<T\> / OPFSRepo)](./references/architecture-data.md)
 - [GM API system](./references/architecture-gm-api.md)
 - [Script execution](./references/architecture-execution.md)
 - [Build pipeline & manifest](./references/architecture-build.md)
+- [Agent subsystem](./references/architecture-agent.md)
 - [Extending ScriptCat — Recipes](#extending-scriptcat--recipes)
 - [Testing the Internals](#testing-the-internals)
 
@@ -204,6 +205,22 @@ mock ([`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock)) is
 
 ---
 
+## Agent Subsystem
+
+The Agent subsystem (`src/app/service/agent/`) is an AI-agent layer built **on top of** the five contexts
+above — it is not a sixth execution context. `AgentService` is assembled inside `ServiceWorkerManager`
+(`src/app/service/service_worker/index.ts`) from a set of narrower services (chat, task, skill, model, MCP,
+background session, sub-agent, compact, DOM automation, OPFS); a content-side `CAT.agent.*` API
+(`src/app/service/content/gm_api/cat_agent.ts`) exposes conversations to user scripts; offscreen and sandbox
+are used for skill-script execution the same way regular background/scheduled scripts are. The UI (chat/task
+pages) and userscript-driven conversations share the same streaming/tool-loop boundary in
+`core/tool_registry.ts` / `service_worker/tool_loop_orchestrator.ts` — there is one tool loop, not a separate
+implementation per caller. Full write-up, including the global vs. per-session tool registries, LLM
+streaming/retry/compact flow, background-session/sub-agent/scheduled-task lifecycle, storage backend choices,
+and the page/offscreen/sandbox delegation boundaries: [`references/architecture-agent.md`](./references/architecture-agent.md).
+
+---
+
 ## Extending ScriptCat — Recipes
 
 Map a change onto the existing extension points instead of inventing new structure:
@@ -212,7 +229,8 @@ Map a change onto the existing extension points instead of inventing new structu
   its `init()`, and call it from the other context with a `Client`. No new transport, no new wiring.
 - **A new broadcast event.** `this.mq.publish("myTopic", payload)` where state changes; `this.mq.subscribe(...)`
   wherever it matters. Use this, not RPC, for "X changed" notifications.
-- **A new persisted entity.** Subclass `Repo<T>` (see [data layer](./references/architecture-data.md#adding-an-entity-is-tiny)),
+- **A new persisted entity.** Pick a backend by matching an existing entity with the same data-size/query/lifecycle
+  needs — `Repo<T>`, `DAO<T>`, or `OPFSRepo` (see [data layer](./references/architecture-data.md#adding-an-entity)),
   construct it in the manager, expose ops via `group.on`.
 - **A new service.** Constructor-inject `Group` + `IMessageQueue` + DAOs; register handlers in `init()`;
   instantiate it in the relevant manager with its own `group("name")` (see [service layer](./references/architecture-services.md)).
@@ -230,8 +248,10 @@ premature abstraction.
 - **Unit (Vitest + happy-dom).** Co-locate `*.test.ts` next to source. `chrome.*` is mocked via
   [`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock) (`tests/vitest.setup.ts`); message-bus
   behavior uses `MockMessage`. Run one file: `pnpm test -- --run path/to/file.test.ts`.
-- **TDD first.** Write the failing test before the implementation. When a test fails, fix the code — don't edit
-  the test to pass.
+- **TDD.** See [AGENTS.md § Engineering Principles](../AGENTS.md#engineering-principles) for the write-failing-
+  test-first principle and [develop-testing.md § When TDD doesn't apply](./references/develop-testing.md#when-tdd-doesnt-apply)
+  for the narrow exceptions — this section only covers architecture-specific test mechanics, not the policy
+  itself.
 - **E2E (Playwright).** `e2e/*.spec.ts`, one worker, real Chromium. `pnpm run test:e2e` (first run:
   `pnpm run test:e2e:install`).
 - **Before a PR:** lint + the relevant suite — owned by [references/develop-testing.md](./references/develop-testing.md) → *Testing*.
diff --git a/docs/design.md b/docs/design.md
index c293ceb52..6fe767093 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -10,7 +10,7 @@
 
 | Owned here | Owned elsewhere |
 | --- | --- |
-| Color-token values, semantics, usage → [`tokens.md`](./references/design-tokens.md) | The hard rules that mandate them (no hard-coded colors, hover via pseudo-classes, `cn()` / CVA / `lucide`) → [`DEVELOP.md` UI section](./develop.md) |
+| Color-token values, semantics, usage → [`tokens.md`](./references/design-tokens.md) | The hard rules that mandate them (no hard-coded colors, hover via pseudo-classes, `cn()` / CVA / `lucide`) → [`DEVELOP.md` UI section](./develop.md#ui) |
 | Theming mechanism, `dark:` usage | Commands, structure, coding style, testing, i18n, commit/PR → [`DEVELOP.md`](./develop.md) |
 | Component palette, variants, selection guidance → [`components.md`](./references/design-components.md) | Process model, message passing, service layers, internals → [`ARCHITECTURE.md`](./architecture.md) |
 | Layout shell, responsive patterns, **layering (z-index)**, motion, state patterns, **accessibility** → [`patterns.md`](./references/design-patterns.md); **elevation (shadows)** → [`tokens.md`](./references/design-tokens.md#elevation-shadows); page recipe (this doc) | — |
diff --git a/docs/develop.md b/docs/develop.md
index af3fe0c49..e974bd645 100644
--- a/docs/develop.md
+++ b/docs/develop.md
@@ -68,6 +68,12 @@ Two conventions are enforced via built-in rules in `eslint.config.mjs`: `no-rest
 the `radix-ui` pattern of `no-restricted-imports`, and `no-restricted-syntax` — not `require-last-error-check`,
 and not the `sonner` pattern of `no-restricted-imports`.
 
+`src/pages/components/ui/toast.ts` has an override that turns `no-restricted-imports` **entirely off** for that
+one file — not just the `sonner` half of it. That means this file is also exempt from the `@radix-ui/react-*`
+restriction, since both bans live on the same rule; this is the one place in `src/pages/**` allowed to import
+`sonner`'s `toast` directly (it's the wrapper `notify` is built on) and a single-package `@radix-ui/react-*`
+import, should it ever need one. Any other file still gets both restrictions.
+
 Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` —
 `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so
 `async` JSX handlers are allowed), and `await-thenable`, all `error` — to catch missing `await`s and promises
diff --git a/docs/pull-request.md b/docs/pull-request.md
index bac8c4953..3ef4475d7 100644
--- a/docs/pull-request.md
+++ b/docs/pull-request.md
@@ -1,6 +1,12 @@
 # Pull Request Description Guide
 
-This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context.
+This guide owns the **PR body**: structure, evidence, and reviewer-handoff expectations. It does not own
+commit message or PR title rules — those live in
+[develop.md § Commit & Pull Request Guidelines](./develop.md#commit--pull-request-guidelines) (gitmoji prefix,
+single-purpose commits). Start from the human-facing template at
+[`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains
+lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when
+the change needs more context.
 
 Whatever headings you use, this guide's checklist and evidence expectations still apply — `## Summary` /
 `## Test plan` headings don't exempt a PR from them. Use the structure below; its sections are
@@ -64,3 +70,12 @@ For non-trivial changes, make the description useful for review:
 - `已知限制` records unsupported cases, explicit scope boundaries, and follow-up work.
 - `建议审查重点` lists concrete behaviors or risks reviewers should verify.
 - `验证` lists exact commands and concise results, including known warnings or why a check was not run.
+
+## Documentation-only PRs
+
+For a PR that only changes Markdown, `验证` should reflect what a doc change actually needs, not an unrelated
+full code test suite: a fact check against the final tree, a relative-link/actual-anchor check, a
+cross-document policy-consistency check, and a privacy/sanitization scan (see
+[`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md)). Before writing "all fixed" or "fully verified," re-review your
+own final diff and any nearby location sharing the same root cause — but only claim the scope you actually
+scanned; don't imply full-repo coverage you didn't perform.
diff --git a/docs/references/architecture-agent.md b/docs/references/architecture-agent.md
new file mode 100644
index 000000000..cc666a1d0
--- /dev/null
+++ b/docs/references/architecture-agent.md
@@ -0,0 +1,125 @@
+# Agent Subsystem
+
+> Deep-dive companion to [`../architecture.md`](../architecture.md). The Agent subsystem is an AI-agent layer
+> that runs **on top of** the five existing runtime contexts (service worker, content, inject, offscreen,
+> sandbox) — it is not a sixth context. Its code lives under
+> [`src/app/service/agent/`](../../src/app/service/agent/), split into a context-agnostic `core/` and a
+> `service_worker/` composition layer, plus a content-side API surface and offscreen/sandbox delegation
+> described below.
+
+## Service-worker composition
+
+[`AgentService`](../../src/app/service/agent/service_worker/agent.ts) is constructed once in
+[`ServiceWorkerManager`](../../src/app/service/service_worker/index.ts) (`new AgentService(this.api.group("agent"),
+this.offscreenSend, resource)`) and composes the narrower services below rather than being one large class.
+Each sub-service takes only the dependencies it needs — not a single `Group`/`IMessageQueue`/DAO triple applied
+uniformly:
+
+| Service | File | Responsibility |
+| --- | --- | --- |
+| `AgentChatService` | `chat_service.ts` | Chat request lifecycle: builds the system prompt, wires a per-request `SessionToolRegistry`, delegates the tool loop to the orchestrator. |
+| `TaskService` | `task_service.ts` | CRUD + scheduling for `AgentTask` (cron-like triggers), runs tasks through the same tool-loop orchestrator. |
+| `SkillService` | `skill_service.ts` | Skill install/update/list from `.md` or `.zip` sources (`parseSkillMd`/`parseSkillZip`), backed by `SkillRepo`. |
+| `AgentModelService` | `model_service.ts` | Model config CRUD and default/summary-model selection, backed by `AgentModelRepo`. |
+| `MCPService` | `mcp.ts` | Manages `MCPClient` connections per configured server and registers/unregisters their tools on the shared `ToolRegistry`. |
+| `BackgroundSessionManager` | `background_session_manager.ts` | Tracks running background conversations (streaming state, listeners, pending `ask_user` prompts) so a UI can reattach to an in-flight session. |
+| `SubAgentService` | `sub_agent_service.ts` | Runs a sub-agent conversation through the shared tool loop with a type-scoped tool exclusion list. |
+| `AgentCompactService` | `compact_service.ts` | Summarizes/compacts long conversation history via a dedicated compact prompt. |
+| `AgentDomService` | `dom.ts` / `dom_cdp.ts` | Page automation: `dom.ts` drives `chrome.scripting.executeScript` (default mode); `dom_cdp.ts` drives `chrome.debugger` CDP (trusted mode) for screenshots/clicks/navigation. |
+| `AgentOPFSService` | `opfs_service.ts` | Serves `CAT.agent.opfs` requests from both content scripts (no Blob support) and offscreen (Blob support), dispatched on whether the caller has a `sender`. |
+
+Message actions are namespaced under the `agent` group (`this.api.group("agent")`), the same RPC pattern
+`architecture.md` describes for other services — the difference here is internal composition, not the wiring
+into `Group`/`Server`.
+
+## Tool registries
+
+[`ToolRegistry`](../../src/app/service/agent/core/tool_registry.ts) is the **global** registry: tools it holds
+persist for the process lifetime and are classified by `ToolSource` — `builtin` (permanent, e.g.
+`web_fetch`/`web_search`/`opfs_*`/`tab_*`), `mcp` (from an `MCPService`-managed server), `skill` (skill
+meta-tools: `load_skill`, `execute_skill_script`, `read_reference`), `session` (registered per conversation:
+task tools, `ask_user`, `sub_agent`, `execute_script`), and `script` (user-script-supplied tools passed through
+`conv.chat`, dispatched via a callback rather than stored in the map).
+
+[`SessionToolRegistry`](../../src/app/service/agent/core/session_tool_registry.ts) wraps a read-only reference
+to the global `ToolRegistry` with its own per-session `Map`. This exists because registering a same-named
+builtin tool (task tools, `ask_user`, `sub_agent`) directly on the global registry would let concurrent
+sessions clobber each other's closures — a session-scoped tool needs to stay bound to its own
+`conversationId`/`sendEvent`. `getDefinitions()` merges session tools over parent tools (session shadows
+parent); `execute()` builds the merged map and delegates to `parent.executeTools()` so shared behavior (e.g.
+attachment persistence) isn't duplicated. A session's tools are reclaimed by garbage collection when the
+session ends — no explicit `unregister` loop is required.
+
+## LLM call: streaming, retry, compact, tool loop
+
+[`ToolLoopOrchestrator`](../../src/app/service/agent/service_worker/tool_loop_orchestrator.ts) drives one
+conversation turn: call the model, execute any tool calls the model requested, feed results back, and repeat
+until the model stops calling tools or `maxIterations` is hit. It depends on injected `callLLM` and
+`autoCompact` functions (rather than importing a concrete client) so tests can substitute spies.
+[`retry_utils.ts`](../../src/app/service/agent/service_worker/retry_utils.ts) classifies retryable failures —
+HTTP 429, 5xx, or network errors, explicitly excluding 4xx client errors — and applies exponential backoff,
+aborting immediately if the caller's `AbortSignal` fires. Context-window overflow triggers auto-compaction
+(`compact_service.ts` / `core/compact_prompt.ts`) before the loop continues. Provider-specific request/response
+shaping lives under `core/providers/` (`anthropic.ts`, `openai.ts`, `registry.ts`), keeping the orchestrator
+provider-agnostic.
+
+## Background session, sub-agent, and scheduled task lifecycle
+
+- **Background session** — `BackgroundSessionManager` keeps a `RunningConversation` (streaming buffer, tool
+  calls so far, pending `ask_user` state, abort controller) alive independent of whether a UI is currently
+  listening, so a popup/options page can attach, detach, and reattach to the same in-flight run.
+- **Sub-agent** — `SubAgentService` runs a nested conversation through the same `callLLMWithToolLoop` contract
+  as the top-level chat, but resolves an exclusion list via `resolveSubAgentType`/`getExcludeToolsForType`
+  (`core/sub_agent_types.ts`) so a sub-agent type doesn't get tools it shouldn't (e.g. spawning further
+  sub-agents).
+- **Scheduled task** — `TaskService` persists `AgentTask` definitions (`AgentTaskRepo`) and run records
+  (`AgentTaskRunRepo`), computing next-fire times via `core/task_scheduler.ts` and `pkg/utils/cron`; the
+  service worker's `chrome.alarms` handler (`agentTaskScheduler`, wired in
+  `src/app/service/service_worker/index.ts`) calls `agent.onSchedulerTick()` to drive due tasks through the
+  same tool loop as interactive chat.
+
+## Storage backends
+
+The Agent subsystem does not use one persistence pattern; pick by data shape, matching
+[`architecture-data.md`](./architecture-data.md):
+
+- `Repo<T>` (`chrome.storage.local`) — `AgentModelRepo` (small config objects), `AgentTaskRepo` (task
+  definitions).
+- `OPFSRepo` (Origin Private File System) — `AgentChatRepo` (conversation history, can grow large and holds
+  attachments), `AgentTaskRunRepo` (task run history), `SkillRepo` (skill `.md`/script bundles).
+- `MCPServerRepo` (`Repo<T>`) — MCP server configs.
+
+## Page / offscreen / sandbox delegation and permission boundaries
+
+- **Content (`src/app/service/content/gm_api/cat_agent.ts`)** exposes the `CAT.agent.*` API to user scripts —
+  `ConversationInstance` wraps a conversation and dispatches tool-call handlers registered by the calling
+  script. This is a distinct API family from the traditional GM API (see
+  [`architecture-gm-api.md`](./architecture-gm-api.md)); it does not follow the four-step `@GMContext.API`
+  recipe used for GM grants.
+- **DOM automation** runs from the service worker: default mode via `chrome.scripting.executeScript`
+  (`dom.ts`), "trusted" mode via `chrome.debugger` CDP (`dom_cdp.ts`) for actions default mode can't do
+  (screenshots, low-level input). CDP attaches the debugger to a tab and carries the extra permission/user
+  -visible-banner implications that come with `chrome.debugger`.
+- **OPFS access** is dispatched by caller: `AgentOPFSService.handleOPFSApi` checks whether the request has a
+  `sender` (content script, no Blob support) or came over `postMessage` (offscreen, Blob support) and adjusts
+  behavior accordingly, rather than assuming one execution context.
+- **Skill scripts** execute through `core/skill_script_executor.ts`, delegating to the Sandbox the same way
+  regular background/scheduled scripts do (see [`architecture-execution.md`](./architecture-execution.md)) —
+  the Agent subsystem doesn't introduce a parallel script-execution path.
+
+## Tests
+
+Every listed file has a co-located `*.test.ts` (e.g. `agent.test.ts`, `chat.test.ts`, `mcp.test.ts`,
+`skill.test.ts`, `sub_agent_service.test.ts`, `tool_registry.test.ts`) following the same Vitest conventions as
+the rest of the codebase — see [`../references/develop-testing.md`](./develop-testing.md).
+
+## Extending the Agent subsystem
+
+- **New tool** — add it under `core/tools/`, register it with the appropriate `ToolSource` (`builtin` at
+  startup, `session` inside the relevant service's session setup), and give it a `ToolExecutor`. Don't register
+  session-scoped tools on the global `ToolRegistry` — use `SessionToolRegistry` so sessions can't clobber each
+  other.
+- **New MCP-backed tool** — goes through `MCPService`, not manual registration; it already handles connecting,
+  naming (`mcp_<server>_<tool>`), and cleanup.
+- **New sub-agent type** — extend `core/sub_agent_types.ts` with its exclusion list rather than special-casing
+  it in `SubAgentService`.
diff --git a/docs/references/architecture-build.md b/docs/references/architecture-build.md
index 64f29ea00..f27d5128a 100644
--- a/docs/references/architecture-build.md
+++ b/docs/references/architecture-build.md
@@ -8,10 +8,14 @@
 
 ```
 context bundles : service_worker · offscreen · sandbox · content · inject · scripting
+shared          : common (pre-React bootstrap, e.g. early theme init — see src/pages/common.ts)
 UI pages (React): popup · options · install · batchupdate · confirm · import
-workers         : editor.worker · ts.worker (Monaco) · linter.worker
+workers         : editor.worker · ts.worker · json.worker (Monaco) · linter.worker
 ```
 
+For the exact current set, check [`rspack.config.ts`](../../rspack.config.ts)'s `entry` block directly — this
+list is a snapshot and can drift when an entry is added or removed.
+
 Output goes to `dist/ext/src/[name].js` (cleaned each build). Notable behavior:
 
 - **Path aliases** mirror `tsconfig.json`: `@App → src`, `@Packages → packages` (the `@Tests → tests` alias is
@@ -33,10 +37,10 @@ dist/ext/
 ├── manifest.json                 # version-stamped, browser-specialized at pack time
 ├── assets/  _locales/
 └── src/
-    ├── service_worker.js content.js inject.js scripting.js offscreen.js sandbox.js
+    ├── service_worker.js content.js inject.js scripting.js offscreen.js sandbox.js common.js
     ├── popup.html/.js options.html/.js install.html/.js …
     ├── offscreen.html sandbox.html
-    └── lib_*.js  editor.worker.js ts.worker.js linter.worker.js
+    └── lib_*.js  editor.worker.js ts.worker.js json.worker.js linter.worker.js
 ```
 
 ### Manifest (MV3)
diff --git a/docs/references/architecture-data.md b/docs/references/architecture-data.md
index 171041664..93993e9ab 100644
--- a/docs/references/architecture-data.md
+++ b/docs/references/architecture-data.md
@@ -1,9 +1,19 @@
-# Data layer (Repo<T> + DAOs)
+# Data layer (backend taxonomy)
 
-## The Data Layer (`Repo<T>` + DAOs)
+## The Data Layer
 
-Persistence is a thin generic over `chrome.storage.local` with an optional in-memory cache, in
-[`src/app/repo/repo.ts`](../../src/app/repo/repo.ts).
+Persistence in `src/app/repo/` is **not one generic base class** — it's a small taxonomy of backends, each
+suited to a different shape of data. Pick by matching an existing entity with the same size/query/lifecycle
+needs (see [Adding an entity](#adding-an-entity) below), not by defaulting to `Repo<T>` for everything:
+
+| Backend | Backs | Use for | Base file |
+| --- | --- | --- | --- |
+| `Repo<T>` | `chrome.storage.local` | Small config/metadata objects, optionally cached in memory | [`repo.ts`](../../src/app/repo/repo.ts) |
+| `DAO<T>` | Dexie (IndexedDB) | Data needing indexed queries (`where`/pagination) | [`dao.ts`](../../src/app/repo/dao.ts) |
+| `OPFSRepo` | Origin Private File System | Larger JSON blobs / files that don't fit a key-value store (Agent chat history, skills) | [`opfs_repo.ts`](../../src/app/repo/opfs_repo.ts) |
+| Custom repository | Purpose-built | Only when none of the above fit (e.g. `TrashScriptDAO`) | e.g. [`trash_script.ts`](../../src/app/repo/trash_script.ts) |
+
+### `Repo<T>`
 
 ### `Repo<T>`
 
@@ -35,19 +45,58 @@ Design notes:
 - **Storage errors are logged, not thrown** — `chrome.runtime.lastError` is checked and reads continue, since
   a transient storage hiccup should not crash the worker.
 
-### The DAOs
+### Repository inventory
 
-| DAO | File | Entity | Notes |
+Names ending in `DAO` don't all share one base class — check which backend before copying a pattern.
+
+**`Repo<T>` (`chrome.storage.local`)**
+
+| Repo | File | Entity | Notes |
 |---|---|---|---|
 | `ScriptDAO` | [`scripts.ts`](../../src/app/repo/scripts.ts) | `Script` (metadata) | Cached; companion `ScriptCodeDAO` stores source separately to keep metadata reads small; dedup via `searchExistingScript` |
 | `ValueDAO` | [`value.ts`](../../src/app/repo/value.ts) | `Value` (GM storage) | Keyed by storage name (per-script or shared `@storageName`) |
 | `ResourceDAO` | [`resource.ts`](../../src/app/repo/resource.ts) | `Resource` (`@require`/`@resource`) | Overrides `joinKey` to hash URLs; `CompiledResourceDAO` caches compiled deps with a version namespace |
 | `PermissionDAO` | [`permission.ts`](../../src/app/repo/permission.ts) | `Permission` | Composite key `<uuid>:<permission>:<value>` |
 | `SubscribeDAO` | [`subscribe.ts`](../../src/app/repo/subscribe.ts) | `Subscribe` | Keyed by feed URL |
-| `FaviconDAO`, `LocalStorageDAO`, `ExportDAO` | `src/app/repo/*.ts` | misc | Same `Repo<T>` pattern |
-| `LoggerDAO` | [`logger.ts`](../../src/app/repo/logger.ts) | `Logger` | Extends `DAO<T>` (Dexie/IndexedDB), **not** `Repo<T>` — logs need indexed queries |
+| `FaviconDAO`, `LocalStorageDAO`, `ExportDAO`, `TempStorageDAO` | `src/app/repo/*.ts` | misc | Same `Repo<T>` pattern |
+| `AgentModelRepo` | [`agent_model.ts`](../../src/app/repo/agent_model.ts) | `AgentModelConfig` | Agent model configs — small, no indexed query need |
+| `AgentTaskRepo` | [`agent_task.ts`](../../src/app/repo/agent_task.ts) | `AgentTask` | Scheduled agent task definitions |
+| `MCPServerRepo` | [`mcp_server_repo.ts`](../../src/app/repo/mcp_server_repo.ts) | `MCPServerConfig` | MCP server configs |
+
+**`DAO<T>` (Dexie/IndexedDB)**
+
+| DAO | File | Entity | Notes |
+|---|---|---|---|
+| `LoggerDAO` | [`logger.ts`](../../src/app/repo/logger.ts) | `Logger` | Logs need indexed queries (`where`/pagination) that `Repo<T>`'s prefix scan doesn't give you |
+
+**`OPFSRepo` (Origin Private File System)**
+
+| Repo | File | Entity | Notes |
+|---|---|---|---|
+| `AgentChatRepo` | [`agent_chat.ts`](../../src/app/repo/agent_chat.ts) | conversation metadata + messages | Can grow large and holds attachments; stored under `agents/conversations/` |
+| `AgentTaskRunRepo` | [`agent_task.ts`](../../src/app/repo/agent_task.ts) | task run history | Companion to `AgentTaskRepo` for run records |
+| `SkillRepo` | [`skill_repo.ts`](../../src/app/repo/skill_repo.ts) | skill `.md`/script bundles | Stored under `agents/skills/` |
+
+**Custom repository (neither of the above fits)**
+
+| Repo | File | Notes |
+|---|---|---|
+| `TrashScriptDAO` | [`trash_script.ts`](../../src/app/repo/trash_script.ts) | Purpose-built for the trash/restore flow; doesn't extend `Repo<T>` or `DAO<T>` |
+
+This list is a snapshot — for the current exact set, run `git grep -n -E 'class [A-Za-z0-9_]*(DAO|Repo)' --
+src/app/repo`.
+
+### Adding an entity
+
+Don't default to `Repo<T>`. Decide by the same questions the existing choices above answer:
+
+- **Data size and shape** — small config object → `Repo<T>`; larger blob/file-like data → `OPFSRepo`.
+- **Query pattern** — need indexed `where`/pagination queries → `DAO<T>` (Dexie); simple get/set/prefix-scan →
+  `Repo<T>`.
+- **Lifecycle** — matches an existing entity's access pattern closely → copy that entity's backend, not a
+  generic template.
 
-### Adding an entity is tiny
+Only once you've picked `Repo<T>` (the common case for small config-shaped entities) does this shape apply:
 
 ```ts
 export interface MyEntity { id: string; data: Record<string, unknown>; createtime: number; }
@@ -59,4 +108,6 @@ export class MyEntityDAO extends Repo<MyEntity> {
 }
 ```
 
-Then create it in the manager (`enableCache()` if hot), and expose operations via `group.on(...)`.
+Then create it in the manager (`enableCache()` if hot), and expose operations via `group.on(...)`. For `DAO<T>`
+or `OPFSRepo`, follow the nearest existing entity of that backend instead (e.g. `LoggerDAO` for Dexie,
+`AgentChatRepo`/`SkillRepo` for OPFS) — their construction and access patterns differ from `Repo<T>`.
diff --git a/docs/references/architecture-gm-api.md b/docs/references/architecture-gm-api.md
index 19bae745b..399fabd3a 100644
--- a/docs/references/architecture-gm-api.md
+++ b/docs/references/architecture-gm-api.md
@@ -56,10 +56,25 @@ work.
 
 ### Adding a GM API (sketch)
 
-1. Add the method to the content `GMApi` with `@GMContext.API({ alias: "GM.foo" })`; for sync APIs return
-   directly, for async ones forward via `sendMessage`/`connect`.
-2. If it needs privilege (network, cookies, tabs), add the handler on the SW `GMApi` with
+1. Add the method to the content `GMApi` with `@GMContext.API({ alias: "GM.foo" })`.
+2. **Pick the transport by shape, not by habit** — check the nearest existing API of the same shape before
+   choosing:
+   - **Single request/reply** (a value lookup, a one-shot action) → `sendMessage`.
+   - **Streaming/progress, a large response, or a persistent bidirectional exchange** (e.g.
+     `GM_xmlhttpRequest`'s chunked response above) → `connect()` (`MessageConnect`).
+3. If it needs privilege (network, cookies, tabs), add the handler on the SW `GMApi`
+   ([`src/app/service/service_worker/gm_api/`](../../src/app/service/service_worker/gm_api)) with
    `@PermissionVerify.API(...)`.
-3. If it needs DOM, route through the offscreen GM API instead.
-4. Register the `@grant` so the linter and the context builder recognize it (see
-   [`packages/eslint`](../../packages/eslint)).
+4. If it needs DOM, route through the offscreen GM API instead:
+   [`src/app/service/offscreen/gm_api.ts`](../../src/app/service/offscreen/gm_api.ts).
+5. Register the `@grant` so the linter and the context builder recognize it — grant/compat data lives in
+   [`packages/eslint/linter-config.ts`](../../packages/eslint/linter-config.ts) (not just "the `eslint` package"
+   generally; that package also ships unrelated compat tables like `compat-headers.js`).
+
+### Agent/CAT API is a separate family
+
+The Agent subsystem's `CAT.agent.*` surface (`src/app/service/content/gm_api/cat_agent.ts` — see
+[`architecture-agent.md`](./architecture-agent.md)) is exposed alongside the traditional GM API but does not
+go through `@GMContext.API`/`@grant`/`@PermissionVerify.API`: it has its own service/permission path. Don't
+fold a new Agent-facing API into the four-step recipe above without first checking whether it's a GM API
+(script-facing, grant-gated) or an Agent API (conversation-facing, its own registration).
diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 2c2797bd3..6f48c9ab0 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -2,24 +2,34 @@
 
 ## The Service Layer
 
-Services live under `src/app/service/<context>/` — **split by the context they run in** — and hold the domain
-logic. They are deliberately "dumb plumbing on the outside, smart logic on the inside": construction is pure DI,
-wiring happens once in a manager, and message handlers are registered in `init()`.
+`src/app/service/` holds two kinds of things, not one uniform pattern:
+
+- **Context services** — `content/`, `offscreen/`, `sandbox/`, `service_worker/` — split by the runtime context
+  they execute in. They are deliberately "dumb plumbing on the outside, smart logic on the inside": construction
+  is pure DI, wiring happens once in a manager, and message handlers are registered in `init()`.
+- **Cross-cutting subsystems** — `agent/` (see [`architecture-agent.md`](./architecture-agent.md); spans all
+  five contexts rather than living in one) and `extension/` (extension-wide environment helpers, e.g.
+  `extension_env.ts`) — plus `queue.ts` (the shared `MessageQueue` wiring used across contexts).
 
 ```
 src/app/service/
-├── service_worker/   script.ts · value.ts · resource.ts · runtime.ts · popup.ts · subscribe.ts
-│                     synchronize.ts · system.ts · permission_verify.ts · clipboard.ts · download.ts
-│                     gm_api/ (SW-side GM handlers) · index.ts (ServiceWorkerManager)
+├── agent/            cross-cutting: core/ (provider-agnostic) + service_worker/ (composed services) —
+│                     see architecture-agent.md
+├── extension/         extension_env.ts (cross-cutting environment helpers)
+├── queue.ts           shared MessageQueue wiring
+├── service_worker/    representative entry points: script.ts · value.ts · resource.ts · runtime.ts ·
+│                      popup.ts · subscribe.ts · synchronize.ts · system.ts · permission_verify.ts ·
+│                      clipboard.ts · download.ts · gm_api/ (SW-side GM handlers) · index.ts (ServiceWorkerManager)
+│                      — for the exact current set, run `git ls-tree --name-only HEAD src/app/service/service_worker/`
 ├── content/          script_runtime.ts · script_executor.ts · exec_script.ts · create_context.ts · gm_api/
-├── offscreen/        background-script runner, gm_api, event_page_manager.ts
+├── offscreen/        background-script runner, gm_api.ts, event_page_manager.ts, html_extractor.ts
 └── sandbox/          runtime.ts (background/scheduled eval + cron)
 ```
 
 ### The DI pattern
 
-Every service takes its collaborators through the constructor — never `new`s them internally. A representative
-signature ([`script.ts`](../../src/app/service/service_worker/script.ts)):
+Every context service takes its collaborators through the constructor — never `new`s them internally. A
+representative signature ([`script.ts`](../../src/app/service/service_worker/script.ts)):
 
 ```ts
 class ScriptService {
@@ -71,3 +81,28 @@ value.init(runtime, popup);   // late-bound cross deps resolved after constructi
 The `group("name")` call is what gives each service its action prefix (`resource/*`, `value/*`, `script/*`, …)
 on the single `serviceWorker` `Server`. Other contexts have their own managers (`OffscreenManager`,
 `SandboxManager`, `ScriptRuntime` for content/inject) following the same shape.
+
+### Agent composition is different — by design
+
+The standard `Group` / `IMessageQueue` / DAO constructor triple above applies to context services. The Agent
+subsystem's sub-services (`AgentChatService`, `TaskService`, `SkillService`, `AgentModelService`, `MCPService`,
+etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed by `AgentService` instead of each
+independently owning a `Group`, and each takes only the narrower interface it actually needs (e.g.
+`AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService` takes a small
+`SubAgentOrchestrator` interface). When adding to the Agent subsystem, follow the pattern of the nearest
+existing sub-service rather than the SW context-service triple above.
+
+## Adding a service
+
+First decide what you're adding:
+
+- **A context service** (owned by exactly one of `content/`, `offscreen/`, `sandbox/`, `service_worker/`) —
+  follow the DI pattern and manager wiring above; copy the nearest existing service in that context.
+- **An Agent/core component or cross-cutting subsystem** — copy the nearest existing file under
+  `agent/core/` or `agent/service_worker/` and follow its narrower-interface style (see
+  [`architecture-agent.md`](./architecture-agent.md)), or extend `extension/` for extension-wide environment
+  concerns.
+
+Guessing the wrong shape (e.g. forcing a full `Group`/`IMessageQueue`/DAO constructor onto an Agent
+sub-service) creates an adapter sandwich the codebase doesn't otherwise have — copy the nearest neighbor
+instead of the generic template.
diff --git a/docs/references/design-components.md b/docs/references/design-components.md
index 6f4ec4f6e..ff154719d 100644
--- a/docs/references/design-components.md
+++ b/docs/references/design-components.md
@@ -2,7 +2,7 @@
 
 ## Component palette & usage
 
-The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/components/ui/) — `new-york` style, CSS variables enabled, no class prefix (`components.json`). Icons are always `lucide-react`; class merging is always `cn()` ([`src/pkg/utils/cn.ts`](../../src/pkg/utils/cn.ts)); variants are always CVA — these are the [`DEVELOP.md` UI section](../develop.md) hard rules, not repeated here. This section is "what exists and how to choose."
+The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/components/ui/) — `new-york` style, CSS variables enabled, no class prefix (`components.json`). Icons are always `lucide-react`; class merging is always `cn()` ([`src/pkg/utils/cn.ts`](../../src/pkg/utils/cn.ts)); variants are always CVA — these are the [`DEVELOP.md` UI section](../develop.md#ui) hard rules, not repeated here. This section is "what exists and how to choose."
 
 ### Primitives & shared composites
 
@@ -27,6 +27,7 @@ The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/compo
 | `toggle.tsx` / `toggle-group.tsx` | Toggle button / toggle group (base of `SegmentedControl`) |
 | `label.tsx` | Form label |
 | `progress.tsx` | Progress bar — `default` / `top` / `indeterminate` variants |
+| `slider.tsx` | Range slider |
 | `skeleton.tsx` | Loading-placeholder block |
 | `sonner.tsx` | Global toast container |
 | `use-hover-menu.ts` | Helper hook for hover-triggered menus |
diff --git a/docs/references/design-patterns.md b/docs/references/design-patterns.md
index 79cd808e3..8e06d3b68 100644
--- a/docs/references/design-patterns.md
+++ b/docs/references/design-patterns.md
@@ -55,7 +55,14 @@ Script list and Logger can hold thousands of rows. Keep large lists responsive:
 
 ### Text expansion (i18n)
 
-Copy is translated into 8 locales and German/Russian run ~30% longer than English. Layouts must **flex or truncate, never clip**: let labels wrap or `truncate` with a `title`/tooltip, give buttons/badges `min-w` room instead of fixed widths, and don't pin a control's width to its English string. Verify a long-locale on the tightest screens (mobile cards, the ActionBar). RTL is **not** a target for the current locale set.
+Copy is translated into the locale set [`translation.md`](../translation.md#各语言术语规范--per-locale-terminology)
+currently lists — don't hardcode a locale count here, it drifts. There's no maintained measurement of how much
+longer any given locale runs versus English, so don't cite a fixed percentage; instead pick an actual long
+string from the current locale resources as your test fixture. Layouts must **flex or truncate, never clip**:
+let labels wrap or `truncate` with a `title`/tooltip, give buttons/badges `min-w` room instead of fixed widths,
+and don't pin a control's width to its English string. Verify with a real long-locale fixture on the tightest
+screens (mobile cards, the ActionBar). RTL is not a target for the current locale set and product scope — reconfirm
+both before treating it as settled if either changes.
 
 ---
 
diff --git a/docs/references/design-tokens.md b/docs/references/design-tokens.md
index 09c614a53..5557dea81 100644
--- a/docs/references/design-tokens.md
+++ b/docs/references/design-tokens.md
@@ -7,7 +7,7 @@
 **Usage:**
 - Background `bg-<token>`, text `text-<token>`, border `border-<token>`, focus ring `ring-ring`.
 - Opacity modifiers compose directly: `bg-primary-background/90` (solid primary hover), `ring-destructive/20`, `bg-input/30`.
-- **Never hard-code a color value** — see Constraint 1 and [`DEVELOP.md` UI section](../develop.md). For dark-only tweaks use the `dark:` variant.
+- **Never hard-code a color value** — see Constraint 1 and [`DEVELOP.md` UI section](../develop.md#ui). For dark-only tweaks use the `dark:` variant.
 
 ### Base surfaces & text
 
diff --git a/docs/references/develop-testing.md b/docs/references/develop-testing.md
index fc4c1c6aa..070e9af73 100644
--- a/docs/references/develop-testing.md
+++ b/docs/references/develop-testing.md
@@ -1,18 +1,18 @@
 # Testing
 
 > The **TDD/BDD-first principle** (write failing tests before implementation; fix code not tests) lives in
-> [`AGENTS.md`](../../AGENTS.md) → *Engineering Principles*. This section is the mechanics.
+> [AGENTS.md § Engineering Principles](../../AGENTS.md#engineering-principles). This section is the mechanics.
 
 Vitest + happy-dom. Per-test budgets live in `vitest.config.ts` per project: non-UI projects (`fast`,
 `isolated`) use 340ms; the `ui` project (`src/pages/**/*.test.{ts,tsx}` — React renders, including
 `renderHook` tests in `.ts` files) uses 850ms because a render + interaction case genuinely costs 100–200ms
 solo under coverage and worker parallelism multiplies that (fake-timer countdown cases have been observed at
 ~630ms under full local load). Don't pass `--test-timeout` on the CLI — it would override every project's
-budget at once. Chrome APIs mocked via
-`@Packages/chrome-extension-mock` (`tests/vitest.setup.ts`). `MockMessage` available for message-system tests.
+budget at once. Chrome APIs are mocked via
+`@Packages/chrome-extension-mock` (`tests/vitest.setup.ts`). `MockMessage` is available for message-system tests.
 `happy-dom` is patched via `patches/` (see `pnpm-workspace.yaml` `patchedDependencies`) to build its
 invalid-selector `DOMException` lazily — the upstream eager construction captures a deep stack on every
-`matches()`/`querySelector()` call and cost ~15% of TSX suite time.
+`matches()`/`querySelector()` call and costs ~15% of TSX suite time.
 
 - Co-locate `*.test.ts`/`*.test.tsx` next to source (or place in `tests`).
 - BDD-style Chinese `describe`/`it` titles. Use `describe.concurrent()` / `it.concurrent()` where independent.
diff --git a/docs/references/verification-debugging.md b/docs/references/verification-debugging.md
index fa3fc6d4f..c50b3d0ff 100644
--- a/docs/references/verification-debugging.md
+++ b/docs/references/verification-debugging.md
@@ -12,6 +12,13 @@ model in [`ARCHITECTURE.md`](../architecture.md)):
 | Background / scheduled script, DOM-needing GM APIs | **Offscreen** — `dist/ext/src/offscreen.html` context |
 | Cron scheduling, `with`-sandboxed execution | **Sandbox** — `dist/ext/src/sandbox.html` context |
 
+**Firefox note.** Firefox MV3 has no separate Offscreen document — there is no `offscreen.html` to inspect.
+`EventPageOffscreenManager` runs offscreen-equivalent logic (background/scheduled-script DOM work) inside the
+DOM-capable background event page instead, so look there for those logs on Firefox. The Sandbox iframe is
+still a separate execution boundary on both browsers. See
+[architecture.md § Chrome vs Firefox: the offscreen split](../architecture.md#chrome-vs-firefox-the-offscreen-split)
+for the full picture.
+
 In a scratch script, capture the page console (`page.on("console", …)`), take screenshots
 (`await page.screenshot({ path: "test-results/verify/<scenario>/screenshots/…png" })`), and write any manual
 notes to `test-results/verify/<scenario>/`. Playwright's automatic failure artifacts also go under
diff --git a/docs/references/verification-report-template.md b/docs/references/verification-report-template.md
index 0ead5e653..6d028a2e0 100644
--- a/docs/references/verification-report-template.md
+++ b/docs/references/verification-report-template.md
@@ -4,6 +4,10 @@ Before running the browser, create a short verification record in the scenario d
 `test-results/verify/<scenario>/report.md`. Keep the reusable template headings in English, but write the actual
 record content in the user's language. Update it as the run proceeds instead of filling it in only at the end.
 
+**The snippet below is a filled *example* of the `## Evidence Index` shape** — it shows what a completed one
+looks like, not a second section to add. The full template further down has its own `## Evidence Index`
+heading; use that one heading and fill it following this example's shape.
+
 ```md
 ## Evidence Index
 
diff --git a/docs/translation.md b/docs/translation.md
index 7a2ac5683..08d21e951 100644
--- a/docs/translation.md
+++ b/docs/translation.md
@@ -52,6 +52,15 @@
 - 为满足部分扩展市场要求，`chrome.i18n` 语言文件位于 `src/assets/_locales`。
 - i18n 方案的实现细节见 [`src/locales/README.md`](../src/locales/README.md)。
 
+### 自动化检查的真实范围
+
+[`src/locales/i18n-usage.test.ts`](../src/locales/i18n-usage.test.ts) 会扫描 `src/pages` 与
+`src/app/service/service_worker` 目录下非测试文件中双引号字面量的 `t()` / `i18n.t()` 调用，并按 `zh-CN`
+resources 解析对应 key 是否存在；动态/插值 key、`defaultValue` 内联回退，以及无法识别的 namespace 会被跳过,
+不计入检查范围。它**只**证明代码引用的 key 在 `zh-CN` 中存在，**不能**证明其他 locale 的 key 是否完整、
+译文措辞是否准确、或术语是否符合对应 `terminology-<locale>.md`——这些仍需人工或专项核对，不要把“测试通过”当成
+“翻译已核对”的证据。
+
 ## 提取翻译提示词 / Extract-translation prompt
 
 将 React 文件中的中文提取为 i18next key 时使用：
diff --git a/docs/verification.md b/docs/verification.md
index 81db6718c..757ab5f37 100644
--- a/docs/verification.md
+++ b/docs/verification.md
@@ -7,15 +7,33 @@
 > scripts and local-only evidence — kept out of Git and never deleted as part of a run; cleanup is the user's call.
 >
 > **What this is NOT.** It is *not* the test-suite reference. The mechanics of Vitest unit tests and the
-> permanent Playwright E2E suite live in [`DEVELOP.md`](./develop.md) → *Testing*; the TDD-first principle and
-> engineering rules live in [`../AGENTS.md`](../AGENTS.md). Read those for writing committed tests.
+> permanent Playwright E2E suite live in [develop.md § Testing](./develop.md#testing); the TDD-first principle
+> and engineering rules live in [AGENTS.md § Engineering Principles](../AGENTS.md#engineering-principles). Read
+> those for writing committed tests.
+
+## When to skip this guide
+
+This guide is **workflow routing**, not a TDD blanket exception — it applies when a change needs the built
+extension, real Chrome APIs, or cross-context behavior to observe. Skip it (and rely on typecheck + the
+relevant committed test instead) for:
+
+- Doc-only, comment-only, or type-only changes with no runtime behavior to observe.
+- Pure logic that a targeted unit test already exercises completely (a parser, a utility function, a reducer) —
+  write/run that test instead of driving a browser for it.
+- Any change fully reproducible and provable by a targeted committed test without the built extension.
+
+If you're unsure whether a change needs the built extension, the deciding question is: *does this depend on
+cross-context wiring or a real browser API that a unit test can't exercise?* If no, a targeted unit test is
+the whole verification; don't reach for this guide's scratch-script workflow just to "be thorough."
 
 ## The one rule: verification ≠ growing the E2E suite
 
 The full E2E suite is **heavy** (two-phase browser launch, real network fetches, multi-minute timeouts). When
 you only want to *check that a feature works*, do not pay that cost and do not leave anything behind:
 
-- ❌ **Never** run the whole suite (`pnpm run test:e2e`) just to verify one thing.
+- ❌ **Never** run the whole suite (`pnpm run test:e2e`) just to verify one thing *during casual verification*.
+  This rule scopes this guide's workflow — it is not a release/CI policy; CI and pre-release gates run the full
+  suite as their own separate, deliberate check.
 - ❌ **Never** add a permanent `e2e/*.spec.ts` as part of casual verification.
 - ✅ Write a **throwaway scratch script** under `e2e/scratch/` (git-ignored), run it, and keep any evidence local.
 
@@ -35,15 +53,23 @@ Choose the reproduction method by what the bug depends on: a failing unit test f
 bugs; this guide's scratch-script workflow (above) when it depends on the built extension, browser APIs, or
 cross-context behavior.
 
-## Prerequisite gate (cheap signals first)
+## Prerequisite gate (cheap signals first, proportional to risk)
 
-Driving a browser is the *last* check, not the first. Confirm the cheap signals are green before you build:
+Driving a browser is the *last* check, not the first. Confirm the cheap signals are green before you build —
+but scale which signals proportionally, not mechanically:
 
 ```bash
-pnpm run typecheck      # tsc --noEmit
-pnpm test               # Vitest unit tests (or target one file, see DEVELOP.md)
+pnpm run typecheck                        # tsc --noEmit — always
+pnpm test -- --run path/to/file.test.ts   # targeted unit test(s) for the change — the default
+pnpm test                                 # full Vitest suite — only when the change is broad/risky,
+                                           # touches shared code, or a repo gate/CI requires it
 ```
 
+Typecheck plus the targeted relevant test is the default prerequisite — it is not a requirement to run the
+full Vitest suite before every scratch verification. Run the broader suite when the change's blast radius
+isn't confirmed to be local (shared utilities, config, public interfaces) or when project policy requires it
+for the change type.
+
 Green unit tests do **not** mean the feature works — they mean the units you tested behave. Cross-context wiring
 (Service Worker ↔ Content ↔ Inject ↔ Offscreen ↔ Sandbox) and real Chrome APIs only exercise in a loaded
 extension. That gap is exactly what this guide closes.
@@ -97,9 +123,13 @@ sanitize them before saving evidence.
 
 Embed screenshots inline with `![alt](screenshots/…png)` plus a caption line, so `report.md` renders as a visual
 record you can skim without opening files. Link videos, logs, and resources instead — markdown can't inline them.
-Never list bare links: every item carries a short note explaining what it proves and how to read it. Before running
-the browser, create the record following the Evidence Index shape in the
-[verification record template](./references/verification-report-template.md).
+Never list bare links: every item carries a short note explaining what it proves and how to read it.
+
+### Create `report.md` before you run the browser
+
+Before running the browser, create `test-results/verify/<scenario>/report.md` following the Evidence Index
+shape in the [verification record template](./references/verification-report-template.md). Fill it in as you
+go — don't reconstruct the run from memory afterward.
 
 ### Minimal template (drive a UI page)
 
@@ -237,6 +267,20 @@ discards the DOM event and calls the same message). State the substitution in `r
 
 > Hit a failure or a hang? See [debugging & common gotchas](./references/verification-debugging.md).
 
+### Verifying a UI change across light/dark theme
+
+The theme is stored in `localStorage` under the key `lightMode` with value `"light"` / `"dark"` / `"auto"`
+(see [`src/pages/components/theme-provider.tsx`](../src/pages/components/theme-provider.tsx) and
+[`src/pages/common.ts`](../src/pages/common.ts), which reads the same key during pre-render to avoid a theme
+flash). Setting this key **before** the page's own scripts run — e.g. via Playwright's `context.addInitScript`
+— is what makes the theme apply on first paint instead of flashing the default and then switching.
+
+Before relying on this in a scratch script, confirm it actually behaves that way for an `chrome-extension://`
+page in your Playwright setup — `addInitScript` timing relative to an extension page's own bootstrap can differ
+from a normal web page, so verify with a quick throwaway run rather than assuming it. Once confirmed for a
+scenario, capture one screenshot per theme (`light` and `dark`) as separate evidence — a single theme's
+screenshot doesn't demonstrate the other renders correctly.
+
 ## Step 4 — Report honestly
 
 Verification only counts if the result is reported as observed (this mirrors the engineering principle: evidence
@@ -247,8 +291,12 @@ before assertions).
 - If it fails or you could not verify a path, **say that plainly** with the console/output — do not soften it,
   do not claim success you did not see.
 - If you were **reproducing a bug**, state plainly whether it reproduced. If it did, the failing observation
-  (error, assertion diff, error screenshot) *is* the evidence — record it and move on to the failing-test → fix
-  cycle. If it did not reproduce, say so and note what you tried, instead of implying the bug is gone.
+  (error, assertion diff, error screenshot) *is* the evidence. In the general case, promote it into a committed
+  failing test before fixing (the failing-test → fix cycle). Under
+  [develop-testing.md § When TDD doesn't apply](./references/develop-testing.md#when-tdd-doesnt-apply)'s
+  infeasible-automated-coverage exception, keep this scratch reproduction as the evidence instead — fix the
+  code, then re-run the *same* reproduction script to confirm it now passes. If it did not reproduce, say so
+  and note what you tried, instead of implying the bug is gone.
   - Two honest framings for the scratch assertion: assert the **desired** behavior (the scratch stays *red* and
     directly shows the gap), or assert the **current buggy contract** (the scratch passes *green* while the bug
     is present, giving a deterministic re-runnable record) and note that the fix must flip it. Pick one and say
diff --git a/packages/cloudscript/README.md b/packages/cloudscript/README.md
index 9e7707a74..d1eac53ee 100644
--- a/packages/cloudscript/README.md
+++ b/packages/cloudscript/README.md
@@ -1,3 +1,13 @@
-# 脚本上云
+# Cloud Script Export
 
+将单个脚本连同其数据打包为可独立执行的归档，而不是同步到远端云存储 —— 与 `packages/filesystem` 的云同步是两回事,
+不要混淆。
+
+`CloudScriptFactory`（[`factory.ts`](./factory.ts)）目前只有一个 target：`local`
+（[`local.ts`](./local.ts)）。它把脚本源码、`GM_*` values、cookies 和一份 `config.js` 元数据打进一个 zip,
+附带 `package.json`/`utils.js`/`index.js`（模板见 `src/template/cloudcat-package/`），产出一个可在本地用
+Node 直接运行的可执行包，供脚本迁移或离线执行使用 —— 不涉及任何远端上传。
+
+云端同步/备份（WebDAV、OneDrive、Google Drive、Dropbox、百度网盘、S3）由
+[`packages/filesystem`](../filesystem/README.md) 提供，语义细节见 [`docs/cloud-sync.md`](../../docs/cloud-sync.md)。
 
diff --git a/packages/filesystem/README.md b/packages/filesystem/README.md
index 5152ad5ee..7f9f1d641 100644
--- a/packages/filesystem/README.md
+++ b/packages/filesystem/README.md
@@ -1,8 +1,15 @@
 # 文件系统
 
-用于同步和备份至云端
+可插拔的 `FileSystem` 抽象（[`filesystem.ts`](./filesystem.ts) / [`factory.ts`](./factory.ts)），用于脚本同步与备份。
+当前 provider（见对应目录）：
 
-- zip
-- webdav
-- 百度网盘
-- onedrive
+- WebDAV（`webdav/`）
+- OneDrive（`onedrive/`）
+- Google Drive（`googledrive/`）
+- Dropbox（`dropbox/`）
+- 百度网盘（`baidu/`）
+- S3（`s3/`）
+- Zip（`zip/`）—— 同一个 `FileSystem` 抽象的归档/本地备份实现，不是远端 provider，导出为本地 zip 文件而非同步到云端。
+
+云同步的详细语义（同步文件、状态合并、错误分类、重试策略）见 [`docs/cloud-sync.md`](../../docs/cloud-sync.md)，
+不在本 README 重复。
diff --git a/packages/message/README.md b/packages/message/README.md
index 6ebb01776..7e15272ea 100644
--- a/packages/message/README.md
+++ b/packages/message/README.md
@@ -1,16 +1,21 @@
 # 消息
 
-对扩展内消息交互的抽象
+跨 context（service_worker / content / inject / offscreen / sandbox）消息交互的抽象层。按调用形态选择传输方式：
 
-主要会有以下几种类型的消息：
+- **单次 request/reply**（调用一次拿一次结果，例如大多数 GM API、扩展页面对 service_worker 的一次性调用）——
+  使用 `sendMessage`（`Server`/`Group`/`Client` 的 RPC 封装）。
+- **流式/进度/长响应，或需要持续双向交换**（例如需要分块返回大响应的 GM API、需要多次调用/多次结果的场景）——
+  使用 `connect()`（`MessageConnect`）建立持久连接。
+- **广播**（service_worker/offscreen 触发的状态变化需要通知所有页面）——使用 `MessageQueue` 的
+  `publish`/`subscribe`，而不是上面两种点对点方式。
 
-- 从脚本发起的GM请求，需要层层传递到service_worker/offscreen进行处理，有的GM只需要进行一次调用获取一次结果，有的需要进行
-  多次调用获取多次结果，使用connect的方式实现
-- 从service_worker/offscreen发起的请求，类似消息队列，其它页面进行监听，触发后广播给所有页面，使用sendMessage方式实现
-- 从扩展页面发起的请求，需要传递到service_worker/offscreen进行处理，如果只是单次调用，获取一次结果，使用sendMessage方式实现，如果需要
-  多次调用获取多次结果，使用connect方式实现
+Service Worker → Offscreen 在 Chrome 与 Firefox 上走不同路径（Chrome 使用
+`ServiceWorkerMessageSend`/`clients.matchAll()`；Firefox 用 `EventPageOffscreenManager` 替代真实的 offscreen
+document），细节见
+[`docs/architecture.md` § Chrome vs Firefox: the offscreen split](../../docs/architecture.md#chrome-vs-firefox-the-offscreen-split)。
 
 ## 注意点
 
-- service_worker和offscreen之间可以使用postMessage的方式进行通信，避免同时监听message与connect导致冲突的问题
-- service_worker会变为不活动的状态，尽量避免与service_worker建立长连接
+- service_worker 和 offscreen 之间可以使用 postMessage 的方式进行通信，避免同时监听 message 与 connect 导致冲突的问题。
+- service_worker 会在空闲后进入不活动状态；与它建立的 `connect()` 长连接会在此时中断，因此需要长连接的场景要考虑
+  重连/状态恢复，而不是假定连接一直存活——这不是禁止在 service_worker 上使用 `connect`，只是需要为其生命周期设计容错。
diff --git a/src/locales/README.md b/src/locales/README.md
index 8f7839594..f8954d47a 100644
--- a/src/locales/README.md
+++ b/src/locales/README.md
@@ -25,11 +25,13 @@ for example:
 
 ### Help Us Translate
 
-Translation files are located in `src/locales`, organized by namespace. If you're interested in helping translate, please submit a PR directly.
+For the translation workflow, terminology rules, and per-locale checklist, see
+[`docs/translation.md`](../../docs/translation.md) — this file only covers the i18n implementation, not the
+contribution workflow.
 
 # i18n 方案
 
-i18n 使用[i8next](https://www.i18next.com/)实现，之所以不是用`chrome.i18n`的原因是该方案不支持动态切换语言。但是为了某些扩展市场的要求，我们还是在`src/assets/_locales`目录下添加了`chrome.i18n`的语言文件。
+i18n 使用[i18next](https://www.i18next.com/)实现，之所以不是用`chrome.i18n`的原因是该方案不支持动态切换语言。但是为了某些扩展市场的要求，我们还是在`src/assets/_locales`目录下添加了`chrome.i18n`的语言文件。
 
 ## 语言文件
 
@@ -50,4 +52,5 @@ i18n 使用[i8next](https://www.i18next.com/)实现，之所以不是用`chrome.
 
 ### 帮助我们翻译
 
-翻译文件位于 `src/locales` 目录下，按命名空间划分。如果您有兴趣帮助翻译，请直接提交 PR。
+翻译工作流、术语规则与逐语言检查清单见 [`docs/translation.md`](../../docs/translation.md)——本文件只覆盖 i18n
+实现机制，不重复维护贡献流程。
diff --git a/src/pages/options/routes/Setting/i18nKeys.md b/src/pages/options/routes/Setting/i18nKeys.md
deleted file mode 100644
index c57054faa..000000000
--- a/src/pages/options/routes/Setting/i18nKeys.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# 设置页 i18n key 映射
-
-设置页所有 key 的 `t(...)` 引用形式。`defaultNS` 为 `common`，其他命名空间需带前缀。
-
-## 全集 key → namespace:key
-
-### 通用 (General)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `language` | `settings:language` |
-| `select_interface_language` | `settings:select_interface_language` |
-| `general` | `settings:general` |
-
-### 界面 (Interface)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `interface_settings` | `settings:interface_settings` |
-| `extension_icon_badge` | `settings:extension_icon_badge` |
-| `display_type` | `settings:display_type` |
-| `badge_type_none` | `settings:badge_type_none` |
-| `badge_type_run_count` | `settings:badge_type_run_count` |
-| `badge_type_script_count` | `settings:badge_type_script_count` |
-| `extension_icon_badge_type` | `settings:extension_icon_badge_type` |
-| `background_color` | `settings:background_color` |
-| `badge_background_color_desc` | `settings:badge_background_color_desc` |
-| `text_color` | `settings:text_color` |
-| `badge_text_color_desc` | `settings:badge_text_color_desc` |
-| `script_menu` | `settings:script_menu` |
-| `display_right_click_menu` | `settings:display_right_click_menu` |
-| `display_right_click_menu_desc` | `settings:display_right_click_menu_desc` |
-| `expand_count` | `settings:expand_count` |
-| `auto_collapse_when_exceeds` | `settings:auto_collapse_when_exceeds` |
-| `favicon_service` | `settings:favicon_service` |
-| `favicon_service_scriptcat` | `settings:favicon_service_scriptcat` |
-| `favicon_service_google` | `settings:favicon_service_google` |
-| `favicon_service_duckduckgo` | `settings:favicon_service_duckduckgo` |
-| `favicon_service_icon-horse` | `settings:favicon_service_icon-horse` |
-| `favicon_service_local` | `settings:favicon_service_local` |
-| `favicon_service_desc` | `settings:favicon_service_desc` |
-
-### 同步 (Sync)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `script_sync` | `settings:script_sync` |
-| `enable_script_sync_to` | `settings:enable_script_sync_to` |
-| `backup_to` | `settings:backup_to` |
-| `sync_delete` | `settings:sync_delete` |
-| `sync_delete_desc` | `settings:sync_delete_desc` |
-| `save` | `save` (common) |
-| `save_success` | `save_success` (common) |
-
-### 更新 (Update)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `update` | `update` (common) |
-| `script_update_check_frequency` | `settings:script_update_check_frequency` |
-| `script_auto_update_frequency` | `settings:script_auto_update_frequency` |
-| `never` | `settings:never` |
-| `6_hours` | `settings:6_hours` |
-| `12_hours` | `settings:12_hours` |
-| `every_day` | `settings:every_day` |
-| `every_week` | `settings:every_week` |
-| `update_disabled_scripts` | `settings:update_disabled_scripts` |
-| `silent_update_non_critical_changes` | `settings:silent_update_non_critical_changes` |
-| `control_script_update_behavior` | `settings:control_script_update_behavior` |
-
-### 运行时 (Runtime)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `runtime` | `logs:runtime` |
-| `enable_background` | `settings:enable_background` (object) |
-| `storage_api` | `editor:storage_api` |
-| `use_file_system` | `editor:use_file_system` |
-| `open_directory` | `editor:open_directory` |
-| `not_set` | `editor:not_set` |
-| `in_use` | `editor:in_use` |
-| `storage_error` | `editor:storage_error` |
-| `settings` | `settings` (common) |
-| `reset` | `reset` (common) |
-
-### 安全 (Security)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `security` | `settings:security` |
-| `blacklist_pages` | `settings:blacklist_pages` |
-| `blacklist_pages_desc` | `settings:blacklist_pages_desc` |
-| `blacklist_placeholder` | `settings:blacklist_placeholder` |
-| `expression_format_error` | `settings:expression_format_error` |
-
-### 开发者 (Developer)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `development_tools` | `settings:development_tools` |
-| `enable_eslint` | `settings:enable_eslint` |
-| `check_script_code_quality` | `settings:check_script_code_quality` |
-| `eslint_rules` | `settings:eslint_rules` |
-| `custom_eslint_rules_config` | `settings:custom_eslint_rules_config` |
-| `enter_eslint_rules` | `settings:enter_eslint_rules` |
-| `eslint_rules_reset` | `editor:eslint_rules_reset` |
-| `eslint_rules_saved` | `editor:eslint_rules_saved` |
-| `eslint_config_format_error` | `editor:eslint_config_format_error` |
-| `editor_config` | `editor:editor_config` |
-| `editor_config_reset` | `editor:editor_config_reset` |
-| `editor_config_saved` | `editor:editor_config_saved` |
-| `editor_config_format_error` | `editor:editor_config_format_error` |
-| `editor_config_description` | `editor:editor_config_description` |
-| `editor_type_definition` | `editor:editor_type_definition` |
-| `editor_type_definition_reset` | `editor:editor_type_definition_reset` |
-| `editor_type_definition_saved` | `editor:editor_type_definition_saved` |
-| `editor_type_definition_description` | `editor:editor_type_definition_description` |
-
----
-
-## 新增到 settings.json 的 key（规则 3）
-
-以下 8 个 key 在 new-ui 任何命名空间均不存在，已从 v1.4 `translation.json` 迁移到 7 个 `src/locales/<locale>/settings.json`：
-
-| key | 位置 |
-|-----|------|
-| `badge_type_none` | `settings:badge_type_none` |
-| `badge_type_run_count` | `settings:badge_type_run_count` |
-| `badge_type_script_count` | `settings:badge_type_script_count` |
-| `script_menu` | `settings:script_menu` |
-| `display_right_click_menu` | `settings:display_right_click_menu` |
-| `display_right_click_menu_desc` | `settings:display_right_click_menu_desc` |
-| `expand_count` | `settings:expand_count` |
-| `auto_collapse_when_exceeds` | `settings:auto_collapse_when_exceeds` |
-
-## 映射到现有命名空间的 key（规则 2 — 不重复迁移）
-
-| key | 现有 namespace:key |
-|-----|-------------------|
-| `save` | `common:save` → `t("save")` |
-| `save_success` | `common:save_success` → `t("save_success")` |
-| `update` | `common:update` → `t("update")` |
-| `settings` | `common:settings` → `t("settings")` |
-| `reset` | `common:reset` → `t("reset")` |
-| `runtime` | `logs:runtime` → `t("logs:runtime")` |
-| `storage_api` | `editor:storage_api` → `t("editor:storage_api")` |
-| `use_file_system` | `editor:use_file_system` → `t("editor:use_file_system")` |
-| `open_directory` | `editor:open_directory` → `t("editor:open_directory")` |
-| `not_set` | `editor:not_set` → `t("editor:not_set")` |
-| `in_use` | `editor:in_use` → `t("editor:in_use")` |
-| `storage_error` | `editor:storage_error` → `t("editor:storage_error")` |
-| `eslint_rules_reset` | `editor:eslint_rules_reset` → `t("editor:eslint_rules_reset")` |
-| `eslint_rules_saved` | `editor:eslint_rules_saved` → `t("editor:eslint_rules_saved")` |
-| `eslint_config_format_error` | `editor:eslint_config_format_error` → `t("editor:eslint_config_format_error")` |
-| `editor_config` | `editor:editor_config` → `t("editor:editor_config")` |
-| `editor_config_reset` | `editor:editor_config_reset` → `t("editor:editor_config_reset")` |
-| `editor_config_saved` | `editor:editor_config_saved` → `t("editor:editor_config_saved")` |
-| `editor_config_format_error` | `editor:editor_config_format_error` → `t("editor:editor_config_format_error")` |
-| `editor_config_description` | `editor:editor_config_description` → `t("editor:editor_config_description")` |
-| `editor_type_definition` | `editor:editor_type_definition` → `t("editor:editor_type_definition")` |
-| `editor_type_definition_reset` | `editor:editor_type_definition_reset` → `t("editor:editor_type_definition_reset")` |
-| `editor_type_definition_saved` | `editor:editor_type_definition_saved` → `t("editor:editor_type_definition_saved")` |
-| `editor_type_definition_description` | `editor:editor_type_definition_description` → `t("editor:editor_type_definition_description")` |

From d6f33294c87948b72fb0217e647982691ade16ee Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Sun, 19 Jul 2026 23:27:23 +0900
Subject: [PATCH 02/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E5=B8=B8=E9=A9=BB=E6=96=87=E6=A1=A3=E5=86=97=E4=BD=99=E3=80=81?=
 =?UTF-8?q?Agent=20=E6=96=87=E6=A1=A3=E9=94=99=E8=AF=AF=E6=A0=87=E8=AF=86?=
 =?UTF-8?q?=E7=AC=A6=E4=B8=8E=E4=B8=8D=E5=8F=AF=E5=AE=A1=E8=AE=A1=E7=9A=84?=
 =?UTF-8?q?=E6=80=A7=E8=83=BD=E6=95=B0=E5=AD=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review (#1616 review comment)：

- .github/copilot-instructions.md: 缩减为纯 router + Copilot 专属规则（中文 review、
  全量 diff review），共享架构/命令/测试内容改为链接 AGENTS.md，消除与常驻文档的重复
- AGENTS.md: 精简 Service & Data Layers 与 SOLID 条目的内联细节，改为更短的指针链接，
  降低常驻文件的 token 增长
- docs/develop.md: 修正 toast.ts override 的措辞——只有 Sonner 例外是有意的，Radix
  限制仍是约定但当前未被 harness 覆盖，不应读作"允许导入 Radix 单包"
- docs/references/architecture-agent.md:
  - 修正三处错误 class 名（ChatService、AgentTaskService、CompactService，
    而非 AgentChatService/TaskService/AgentCompactService）
  - 修正 retry 排除条件的精确描述（只排除 400/401/403/404，不是全部 4xx）
  - 修正导航实现归属（chrome.tabs，在 dom.ts 中，与 trusted 模式无关）并澄清
    dom_cdp.ts 是 dom.ts 调用的 helper 而非独立服务
  - 修正测试覆盖声称，改为要求现场核对 test 清单而非假设完整覆盖
- docs/references/architecture-data.md: 删除重复的 `Repo<T>` heading
- docs/DOC-MAINTENANCE.md: link-integrity 脚本改用 `git ls-files '*.md'` 动态发现，
  而不是遗漏 .github/package README 与新增 reference 的固定列表；架构 owner 行补上
  architecture-agent.md
- docs/README.md: 索引补上 architecture-agent.md
- docs/references/develop-testing.md: 删除不可审计的 "~15%" 性能数字，改为要求
  同环境实测
- packages/cloudscript/README.md: 修正导出包并非解压即可运行——package.json 声明了
  外部依赖 scriptcat-nodejs，需要先 npm install

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/copilot-instructions.md       | 194 ++++----------------------
 AGENTS.md                             |  10 +-
 docs/DOC-MAINTENANCE.md               |  10 +-
 docs/README.md                        |   2 +-
 docs/develop.md                       |  13 +-
 docs/references/architecture-agent.md |  48 +++++--
 docs/references/architecture-data.md  |   2 -
 docs/references/develop-testing.md    |   5 +-
 packages/cloudscript/README.md        |   6 +-
 9 files changed, 89 insertions(+), 201 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index c36abade4..49fe962a8 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,170 +1,30 @@
-# ScriptCat Development Guide
+# ScriptCat — Copilot Instructions
 
-## Code Review
-
-When performing a code review, respond in Chinese.
-
-## Architecture Overview
-
-ScriptCat is a sophisticated browser extension that executes user scripts with a unique multi-process architecture:
-
-### Core Components
-- **Service Worker** (`src/service_worker.ts`) - Main background process handling script management, installations, and chrome APIs
-- **Offscreen** (`src/offscreen.ts`) - Isolated background environment for running background/scheduled scripts on Chrome. Firefox MV3 has no separate Offscreen document; `EventPageOffscreenManager` (`src/app/service/offscreen/event_page_manager.ts`) runs the same logic inside the DOM-capable background event page instead.
-- **Sandbox** (`src/sandbox.ts`) - Secure execution environment for background/scheduled scripts only (no page context); isolated via `with(arguments[0])`
-- **Content Scripts** (`src/content.ts`) - Injected into web pages to execute user scripts
-- **Inject Scripts** (`src/inject.ts`) - Runs in page context with access to page globals, including `unsafeWindow`
-
-### Message Passing System
-ScriptCat uses a sophisticated message passing architecture (`packages/message/`):
-- **ExtensionMessage** - Chrome extension runtime messages between service worker/content/pages
-- **WindowMessage** - PostMessage-based communication between offscreen/sandbox
-- **CustomEventMessage** - CustomEvent-based communication between content/inject scripts
-- **MessageQueue** - Cross-environment event broadcasting system
-
-Key pattern: background scripts flow Service Worker → Offscreen → Sandbox; page scripts flow Service Worker → Content → Inject. Other paths exist alongside this: UI pages talk to the Service Worker directly, `MessageQueue` broadcasts across contexts outside the request/reply chain, and Agent storage (OPFS/Dexie) is read/written without going through this message flow.
-
-### Script Execution Flow
-1. **Page Scripts**: Service Worker registers with `chrome.userScripts` → injected into pages
-2. **Background Scripts**: Service Worker → Offscreen → Sandbox execution
-3. **Scheduled Scripts**: Cron-based execution in Sandbox environment
-
-## Key Development Patterns
-
-### Path Aliases
-```typescript
-import x from "@App/service_worker";   // -> src/service_worker
-import y from "@Packages/message";     // -> packages/message
-import z from "@Tests/utils";          // -> tests/utils
-```
-
-### Repository Pattern
-Persistence is a small backend taxonomy, not one base class: `Repo<T>` (`chrome.storage.local`, e.g. `ScriptDAO`, `ResourceDAO`, `SubscribeDAO`), `DAO<T>` (Dexie/IndexedDB, e.g. `LoggerDAO`), `OPFSRepo` (OPFS-backed data, e.g. `AgentChatRepo`, `SkillRepo`), and a few custom repositories (e.g. `TrashScriptDAO`) where none of those fit. See [`docs/references/architecture-data.md`](../docs/references/architecture-data.md) for the full inventory and entity-decision recipe.
-```typescript
-export class ScriptDAO extends Repo<Script> {
-  public save(val: Script) { return super._save(val.uuid, val); }
-}
-```
-
-### Service Layer Structure
-Services follow a consistent pattern with dependency injection:
-```typescript
-export class ExampleService {
-  constructor(
-    private group: Group,           // Message handling group
-    private messageQueue: IMessageQueue,  // Event broadcasting (MessageQueue's interface)
-    private dataDAO: DataDAO        // Data access
-  ) {}
-  
-  init() {
-    this.group.on("action", this.handleAction.bind(this));
-  }
-}
-```
-
-### Script Compilation & Sandboxing
-User scripts are compiled with sandbox context isolation:
-- `compileScriptCode()` - Wraps scripts with error handling and context binding
-- `compileInjectScript()` - Creates window-mounted functions for inject scripts
-- Sandbox uses `with(arguments[0])` for controlled variable access
-
-## Technology Stack
-
-- **React 19** - Component framework with automatic runtime
-- **shadcn/ui** - UI component library built on Radix UI
-- **Tailwind CSS** - Utility-first CSS framework for styling
-- **Rspack** - Fast bundler (Webpack alternative) with SWC
-- **TypeScript** - Type-safe development
-
-
-## Development Workflows
-
-### Build & Development
-```bash
-pnpm run dev           # Development with source maps
-pnpm run dev:noMap     # Development without source maps (needed for incognito)
-pnpm run build         # Production build
-pnpm run pack          # Create browser extension packages
-```
-
-### Testing
-```bash
-pnpm test              # Run all tests with Vitest
-pnpm run coverage      # Generate coverage reports
-```
+> **This file only holds Copilot-specific behavior and a router.** Architecture, coding conventions, commands,
+> and testing mechanics are owned by [`../AGENTS.md`](../AGENTS.md) and the docs it routes to
+> (`docs/develop.md`, `docs/architecture.md`, `docs/references/*`, `docs/verification.md`, `docs/design.md`,
+> `docs/translation.md`). Read those before reviewing or writing code — don't rely on a second, separately
+> maintained copy of them here; when this file and one of those docs disagree, the owning doc wins and this
+> file should be corrected to match.
 
-**Testing Patterns:**
-- Uses Vitest with happy-dom environment
-- Chrome extension APIs mocked via `@Packages/chrome-extension-mock`
-- Message system testing with `MockMessage` classes
-- Sandbox testing validates script isolation
-
-### Code Organization
-- **Monorepo structure** with packages in `packages/` (message, filesystem, etc.)
-- **Feature-based organization** in `src/app/service/` by environment
-- **Shared utilities** in `src/pkg/` for cross-cutting concerns
-- **Type definitions** in `src/types/` with global declarations
-
-### Browser Extension Specifics
-- **Manifest V3** with service worker background
-- **User Scripts API** for script injection (Chrome/Edge)
-- **Offscreen API** for DOM access in background contexts  
-- **Declarative Net Request** for script installation interception
-
-## Critical Integration Points
-
-### Script Installation Flow
-1. URL patterns trigger declarative net request rules
-2. Service Worker opens install page with cached script data
-3. Install page validates and processes script metadata
-4. Scripts registered with appropriate execution environment
-
-### GM API Implementation
-- Split across Content, Service Worker, and Offscreen contexts (each a `GMApi` in its own module)
-- Permission verification via `PermissionVerify` service
-- Value storage abstracted through `ValueService`
-- Cross-origin requests handled in service worker context
-
-### Resource Management
-- `ResourceService` handles script dependencies (@require, @resource)
-- Content Security Policy handling for external resources
-- Caching layer via `Cache` class with automatic expiration
-
-## Debug & Development Notes
-
-- Use `pnpm run dev:noMap` for incognito window development
-- Background script changes require extension reload
-- Message passing debugging available in service worker console
-- Sandbox (background/scheduled scripts) has no page context; page-context access via `unsafeWindow` is only available to Inject/page scripts
-
-## File Structure Patterns
-- Tests co-located with source files (`.test.ts` / `.test.tsx` suffix), plus end-to-end specs under `e2e/*.spec.ts`
-- Template files use `.tpl` extension for build-time processing
-- Configuration files use factory pattern for environment-specific setup
-
-## Language
-- The code is developed and maintained by developers based in Mainland China.
-- Comments should preferably be written in Simplified Chinese.
-- The user interface supports multiple languages, with English set as the default for global users.
-
-## PR Review Policy
-
-When performing Pull Request (PR) reviews, Copilot must always conduct a **comprehensive and independent review** of the entire PR content.
-
-- **Full Review Every Time**  
-  Always review **all modified files** in every PR, regardless of previous reviews or user comments. Even during re-reviews, treat the PR as new and **do not rely on prior review states**.
-
-- **No Skipping of Files**  
-  Do not skip or ignore any text-based file types (including `.md`, `.json`, `.yml`, `.toml`, `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.). Every file that is changed must be fully examined.
-
-- **Reference as Context Only**  
-  PR descriptions, commit messages, or user discussions serve only as **reference context**. The review must focus primarily on the **actual code and file changes**.
-
-- **Infer Intent from Code Changes**  
-  Always attempt to **infer the purpose and intent** of the changes directly from the modified content, rather than relying solely on user statements or PR titles.
-
-- **Critical Thinking Requirement**  
-  For each change, Copilot should assess correctness, consistency, and maintainability — ensuring that logic, style, and architectural impact align with project standards.
+## Code Review
 
-- **Independent Verification**  
-  Do not assume unchanged files or previously reviewed sections are safe; verify all code paths potentially affected by the modifications.
+- Respond in Chinese when performing a code review (用中文回复代码审查意见).
+- Conduct a **comprehensive and independent review** of the entire PR every time:
+  - **Full review every time** — review all modified files regardless of previous reviews or comments; treat
+    re-reviews as new, not relying on prior review state.
+  - **No skipping files** — examine every changed file regardless of type (`.md`, `.json`, `.yml`, `.toml`,
+    `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.).
+  - **PR descriptions/commit messages/discussion are reference context only** — the review's conclusions must
+    be grounded in the actual code and file changes, inferring intent from the diff itself.
+  - **Independent verification** — don't assume an unchanged file or a previously reviewed section is safe;
+    verify code paths potentially affected by the current changes.
+
+## Minimal fallback (only if this surface can't reliably follow the link above)
+
+ScriptCat is a Manifest V3 browser extension (TypeScript + React 19 + Rspack, pnpm) that runs
+Tampermonkey-compatible userscripts across five isolated contexts — Service Worker, Content, Inject, Offscreen,
+Sandbox — communicating over `packages/message`. If you cannot load `AGENTS.md`, treat any architecture,
+persistence-pattern, or service-shape claim you're tempted to state here as unverified, and prefer asking the
+reviewer to confirm against `AGENTS.md` / `docs/architecture.md` over inventing a summary — this file is not
+the source of truth for those facts and must not re-accumulate a parallel copy of them.
diff --git a/AGENTS.md b/AGENTS.md
index c2828762f..a225a4d93 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,7 +55,7 @@ isn't universal, that's called out in the item itself.
 - **Fix root causes, not symptoms — refactor over patch.** No `as any` / `// @ts-ignore` / try-catch swallow / defensive skips to make errors disappear (宁愿重构也不要打补丁). If a test fails, fix the code, not the test — the narrow exceptions (a wrong test contract; a test that never carried value) are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
 - **Confirm before you fix.** Before touching a reported bug, reproduce it and confirm it actually exists — never fix from assumption. Capture the reproduction, then fix, **in that order** (确定 bug 存在 → 写测试或记录验证证据 → 修复); how to reproduce and what counts as capture are in [`docs/verification.md`](docs/verification.md) and the TDD entry below.
 - **TDD/BDD first, for changes that alter observable behavior.** Write failing tests **before** implementing new or changed behavior, using BDD-style Chinese `describe`/`it` titles. Two narrow exceptions — neither a blanket file/task category — are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#when-tdd-doesnt-apply). (Runner, mocks, and how to run tests are in `docs/develop.md`.)
-- **SOLID, high cohesion & low coupling — applied to the existing extension points.** Pick a persistence backend by matching an existing entity with the same needs, not by defaulting to one pattern: `Repo<T>` backs `chrome.storage.local`, `DAO<T>` backs Dexie/IndexedDB, `OPFSRepo` backs OPFS-stored data, and a custom repository (e.g. `TrashScriptDAO`) is only for cases none of those fit. For messages, use `Group.on(...)`. Context services still take `Group` / `IMessageQueue` / DAOs via constructor injection; the Agent subsystem also mixes in plain core modules and service-worker composition with narrower injected interfaces — don't force every new class into the same constructor shape. Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
+- **SOLID, high cohesion & low coupling — applied to the existing extension points.** Persistence is a small backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / a few custom repos), not one pattern to default to — pick by matching an existing entity with the same needs; see [`docs/references/architecture-data.md`](docs/references/architecture-data.md#adding-an-entity). For messages, use `Group.on(...)`. Not every service takes the same constructor shape — context services vs. the Agent subsystem differ; see [`docs/references/architecture-services.md`](docs/references/architecture-services.md#adding-a-service). Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
 - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime.
 - **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. Don't remove or narrow currently supported behavior just to simplify a fix — only do so when the task or an already-verified contract explicitly calls for that change.
 - **No dead code or `// removed` markers** — git remembers. Delete unused code outright.
@@ -94,10 +94,10 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 `ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔ Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome), `CustomEventMessage` (CustomEvent — Content ↔ Inject), `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers
-- Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/` — split by execution context, constructor-injected `Group`/`IMessageQueue`/DAOs) plus **cross-cutting subsystems** (`agent/` — see below; `extension/`; `queue.ts`). Full inventory and the "adding a service" recipe: [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
-- Persistence is a small backend taxonomy, not one pattern: `Repo<T>` (`chrome.storage.local`), `DAO<T>` (Dexie/IndexedDB), `OPFSRepo` (OPFS-backed data), and a few custom repositories where none of those fit. Full inventory and the entity-decision recipe: [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
-- **GM API** split across content / SW / offscreen, each a `GMApi` (content built on `GM_Base`; SW — permission verify, cross-origin; offscreen — DOM-dependent background-script APIs); values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
-- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five runtime contexts, not a sixth context: `core/` (provider-agnostic tool loop, model context, tool registry), `service_worker/` (chat/task/skill/MCP services, composed into `ServiceWorkerManager`), plus content-side CAT/GM API and offscreen/sandbox delegation for skill-script execution. Details: [`docs/architecture.md`](docs/architecture.md).
+- Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/`) plus **cross-cutting subsystems** (`agent/`, `extension/`, `queue.ts`) — not one uniform shape. Details, inventory, "adding a service": [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
+- Persistence is a backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / custom), not one pattern. Details, inventory, "adding an entity": [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
+- **GM API** split across content / SW / offscreen, each a `GMApi`; values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
+- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five contexts, not a sixth. Full write-up: [`docs/references/architecture-agent.md`](docs/references/architecture-agent.md).
 
 ### Browser Extension APIs (MV3)
 `chrome.userScripts` (page injection), Offscreen API (DOM in background), Declarative Net Request (intercepts `.user.js` URLs to trigger install flow).
diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
index 69a35e753..b9f5b6bac 100644
--- a/docs/DOC-MAINTENANCE.md
+++ b/docs/DOC-MAINTENANCE.md
@@ -93,7 +93,7 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 | [`pull-request.md`](./pull-request.md) | Detailed PR description structure and guidance for agents and contributors; the human-facing template remains lightweight. |
 | [`design.md`](./design.md) | The design system: theme mechanism, shadcn component selection, new-page recipe; tokens split to [`references/design-tokens.md`](./references/design-tokens.md), component palette to [`references/design-components.md`](./references/design-components.md), layout/motion/state/a11y patterns to [`references/design-patterns.md`](./references/design-patterns.md). |
 | [`verification.md`](./verification.md) | Lightweight end-to-end functional verification — throwaway scratch scripts driving the real built extension; report template split to [`references/verification-report-template.md`](./references/verification-report-template.md), debugging FAQ to [`references/verification-debugging.md`](./references/verification-debugging.md). |
-| [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md). |
+| [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md), [`references/architecture-agent.md`](./references/architecture-agent.md). |
 | [`cloud-sync.md`](./cloud-sync.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules, fact-check / anti-drift discipline, and policy-consistency checks — for every tracked agent/contributor Markdown file, not just `AGENTS.md` + `docs/*`. |
@@ -163,14 +163,16 @@ echo "== eslint (project rule in eslint-rules/ vs userscript config in packages/
 git ls-files eslint-rules/; git grep -l "require-last-error-check" -- eslint.config.mjs; git ls-files packages/eslint/linter-config.ts
 ```
 
-Link integrity — confirm every relative markdown link in the core docs resolves:
+Link integrity — confirm every relative markdown link resolves, across **every tracked Markdown file**
+(`git ls-files '*.md'`), not a fixed list that silently misses new files (`.github/*.md`, package/source
+READMEs, a newly added `docs/references/*.md`):
 
 ```bash
-for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/pull-request.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do
+git ls-files '*.md' | while IFS= read -r doc; do
   # the sed pipeline drops fenced code blocks and inline code spans first, so illustrative sample
   # links inside ```md snippets or `single-backtick` text (e.g. references/verification-report-template.md's
   # screenshot/resource examples, verification.md's "Evidence location" spans) aren't false-flagged as broken
-  sed '/^```/,/^```/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^https?:|^#' | while read -r link; do
+  sed '/^```/,/^```/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^https?:|^#' | while IFS= read -r link; do
     target="$(dirname "$doc")/${link%%#*}"
     [ -e "$target" ] && echo "ok     $doc → $link" || echo "BROKEN $doc → $link"
   done
diff --git a/docs/README.md b/docs/README.md
index 17b969e26..1603ed352 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,7 +11,7 @@
 | [`pull-request.md`](./pull-request.md) | PR 描述指南:代理与贡献者使用的详细章节、按变更类型取舍规则、验证与审查信息要求。 |
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |
 | [`verification.md`](./verification.md) | 功能验证指南:用一次性 scratch 脚本驱动真实扩展做端到端验证(不跑全量 E2E、不加永久用例);报告模板拆到 [`references/verification-report-template.md`](./references/verification-report-template.md),调试 FAQ 拆到 [`references/verification-debugging.md`](./references/verification-debugging.md)。**验证改动是否真正跑通时读。** |
-| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)。 |
+| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)、[`references/architecture-agent.md`](./references/architecture-agent.md)(Agent 子系统)。 |
 | [`cloud-sync.md`](./cloud-sync.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、跨文档政策一致性核对、隐私清理、以及在 resolved final tree 上的复核方法,覆盖全部 tracked 的 agent/contributor Markdown(不止 `AGENTS.md` + `docs/*`,还包括 `.github/*.md`、package-local README)。**改/审文档前先读。** |
 
diff --git a/docs/develop.md b/docs/develop.md
index e974bd645..1141043a4 100644
--- a/docs/develop.md
+++ b/docs/develop.md
@@ -69,10 +69,15 @@ the `radix-ui` pattern of `no-restricted-imports`, and `no-restricted-syntax` 
 and not the `sonner` pattern of `no-restricted-imports`.
 
 `src/pages/components/ui/toast.ts` has an override that turns `no-restricted-imports` **entirely off** for that
-one file — not just the `sonner` half of it. That means this file is also exempt from the `@radix-ui/react-*`
-restriction, since both bans live on the same rule; this is the one place in `src/pages/**` allowed to import
-`sonner`'s `toast` directly (it's the wrapper `notify` is built on) and a single-package `@radix-ui/react-*`
-import, should it ever need one. Any other file still gets both restrictions.
+one file — not just the `sonner` half of it. Only the `sonner` exception is intentional: this is the one place
+in `src/pages/**` allowed to import `sonner`'s `toast` directly (it's the wrapper `notify` is built on). The
+file happens to also lose the `@radix-ui/react-*` restriction as a side effect of the rule being off wholesale
+— it does not currently import from `@radix-ui/react-*` (or `radix-ui`) at all, and the merged-package
+convention still applies to it in spirit; `eslint-rules/harness.test.mjs`'s Radix case only exercises
+`dialog.tsx`, so a Radix-restricted import landing in `toast.ts` would not be caught by lint today. Don't read
+this override as "Radix single-package imports are permitted here" — treat it as a lint gap this file
+currently doesn't exploit, and prefer narrowing the override to the `sonner` import specifically (or adding a
+`toast.ts` case to the harness) over relying on the blanket `off`. Any other file still gets both restrictions.
 
 Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` —
 `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so
diff --git a/docs/references/architecture-agent.md b/docs/references/architecture-agent.md
index cc666a1d0..366141479 100644
--- a/docs/references/architecture-agent.md
+++ b/docs/references/architecture-agent.md
@@ -17,17 +17,20 @@ uniformly:
 
 | Service | File | Responsibility |
 | --- | --- | --- |
-| `AgentChatService` | `chat_service.ts` | Chat request lifecycle: builds the system prompt, wires a per-request `SessionToolRegistry`, delegates the tool loop to the orchestrator. |
-| `TaskService` | `task_service.ts` | CRUD + scheduling for `AgentTask` (cron-like triggers), runs tasks through the same tool-loop orchestrator. |
+| `ChatService` | `chat_service.ts` | Chat request lifecycle: builds the system prompt, wires a per-request `SessionToolRegistry`, delegates the tool loop to the orchestrator. |
+| `AgentTaskService` | `task_service.ts` | CRUD + scheduling for `AgentTask` (cron-like triggers), runs tasks through the same tool-loop orchestrator. |
 | `SkillService` | `skill_service.ts` | Skill install/update/list from `.md` or `.zip` sources (`parseSkillMd`/`parseSkillZip`), backed by `SkillRepo`. |
 | `AgentModelService` | `model_service.ts` | Model config CRUD and default/summary-model selection, backed by `AgentModelRepo`. |
 | `MCPService` | `mcp.ts` | Manages `MCPClient` connections per configured server and registers/unregisters their tools on the shared `ToolRegistry`. |
 | `BackgroundSessionManager` | `background_session_manager.ts` | Tracks running background conversations (streaming state, listeners, pending `ask_user` prompts) so a UI can reattach to an in-flight session. |
 | `SubAgentService` | `sub_agent_service.ts` | Runs a sub-agent conversation through the shared tool loop with a type-scoped tool exclusion list. |
-| `AgentCompactService` | `compact_service.ts` | Summarizes/compacts long conversation history via a dedicated compact prompt. |
-| `AgentDomService` | `dom.ts` / `dom_cdp.ts` | Page automation: `dom.ts` drives `chrome.scripting.executeScript` (default mode); `dom_cdp.ts` drives `chrome.debugger` CDP (trusted mode) for screenshots/clicks/navigation. |
+| `CompactService` | `compact_service.ts` | Summarizes/compacts long conversation history via a dedicated compact prompt. |
+| `AgentDomService` | `dom.ts` (+ `dom_cdp.ts` helpers) | Page automation — see below for the default-vs-trusted split. |
 | `AgentOPFSService` | `opfs_service.ts` | Serves `CAT.agent.opfs` requests from both content scripts (no Blob support) and offscreen (Blob support), dispatched on whether the caller has a `sender`. |
 
+(Class names verified via `git grep -n "export class" -- src/app/service/agent/service_worker/` — re-run that
+before relying on a name here, since these are exactly the kind of detail that drifts.)
+
 Message actions are namespaced under the `agent` group (`this.api.group("agent")`), the same RPC pattern
 `architecture.md` describes for other services — the difference here is internal composition, not the wiring
 into `Group`/`Server`.
@@ -56,9 +59,12 @@ session ends — no explicit `unregister` loop is required.
 conversation turn: call the model, execute any tool calls the model requested, feed results back, and repeat
 until the model stops calling tools or `maxIterations` is hit. It depends on injected `callLLM` and
 `autoCompact` functions (rather than importing a concrete client) so tests can substitute spies.
-[`retry_utils.ts`](../../src/app/service/agent/service_worker/retry_utils.ts) classifies retryable failures —
-HTTP 429, 5xx, or network errors, explicitly excluding 4xx client errors — and applies exponential backoff,
-aborting immediately if the caller's `AbortSignal` fires. Context-window overflow triggers auto-compaction
+[`retry_utils.ts`](../../src/app/service/agent/service_worker/retry_utils.ts)'s `isRetryableError` matches an
+error message containing `429`, a `5xx` code, or a network-ish signal (`network`/`fetch`/`ECONNRESET`), then
+excludes it if the message also matches `400`, `401`, `403`, or `404` — it does not blanket-exclude every 4xx
+status, just those four specific codes (other 4xx codes simply don't match the retry-trigger pattern in
+practice unless their message happens to contain one of the trigger substrings). `withRetry` then applies
+exponential backoff, aborting immediately if the caller's `AbortSignal` fires. Context-window overflow triggers auto-compaction
 (`compact_service.ts` / `core/compact_prompt.ts`) before the loop continues. Provider-specific request/response
 shaping lives under `core/providers/` (`anthropic.ts`, `openai.ts`, `registry.ts`), keeping the orchestrator
 provider-agnostic.
@@ -72,7 +78,7 @@ provider-agnostic.
   as the top-level chat, but resolves an exclusion list via `resolveSubAgentType`/`getExcludeToolsForType`
   (`core/sub_agent_types.ts`) so a sub-agent type doesn't get tools it shouldn't (e.g. spawning further
   sub-agents).
-- **Scheduled task** — `TaskService` persists `AgentTask` definitions (`AgentTaskRepo`) and run records
+- **Scheduled task** — `AgentTaskService` persists `AgentTask` definitions (`AgentTaskRepo`) and run records
   (`AgentTaskRunRepo`), computing next-fire times via `core/task_scheduler.ts` and `pkg/utils/cron`; the
   service worker's `chrome.alarms` handler (`agentTaskScheduler`, wired in
   `src/app/service/service_worker/index.ts`) calls `agent.onSchedulerTick()` to drive due tasks through the
@@ -96,10 +102,16 @@ The Agent subsystem does not use one persistence pattern; pick by data shape, ma
   script. This is a distinct API family from the traditional GM API (see
   [`architecture-gm-api.md`](./architecture-gm-api.md)); it does not follow the four-step `@GMContext.API`
   recipe used for GM grants.
-- **DOM automation** runs from the service worker: default mode via `chrome.scripting.executeScript`
-  (`dom.ts`), "trusted" mode via `chrome.debugger` CDP (`dom_cdp.ts`) for actions default mode can't do
-  (screenshots, low-level input). CDP attaches the debugger to a tab and carries the extra permission/user
-  -visible-banner implications that come with `chrome.debugger`.
+- **DOM automation** runs from the service worker through a single `AgentDomService` (`dom.ts`), which handles
+  every action (`navigate`, `readPage`, `screenshot`, `click`, `fill`, `scroll`, `waitFor`, `executeScript`,
+  tab monitoring). Navigation and tab bookkeeping always go through `chrome.tabs` (`navigate`, `update`,
+  `create`, `query`), independent of mode. For `click`/`fill`/`screenshot`/monitoring, `AgentDomService` picks
+  between two implementations: default mode drives them via `chrome.scripting.executeScript`, while "trusted"
+  mode delegates to CDP helpers imported from `dom_cdp.ts` (`cdpClick`, `cdpFill`, `cdpScreenshot`,
+  `cdpStartMonitor`/`cdpStopMonitor`/`cdpPeekMonitor`) for real synthetic input (`isTrusted: true`) via
+  `chrome.debugger`. CDP attaches the debugger to a tab and carries the extra permission/user-visible-banner
+  implications that come with `chrome.debugger` — `dom_cdp.ts` is a helper module `dom.ts` calls into, not an
+  independent service with its own request path.
 - **OPFS access** is dispatched by caller: `AgentOPFSService.handleOPFSApi` checks whether the request has a
   `sender` (content script, no Blob support) or came over `postMessage` (offscreen, Blob support) and adjusts
   behavior accordingly, rather than assuming one execution context.
@@ -109,9 +121,15 @@ The Agent subsystem does not use one persistence pattern; pick by data shape, ma
 
 ## Tests
 
-Every listed file has a co-located `*.test.ts` (e.g. `agent.test.ts`, `chat.test.ts`, `mcp.test.ts`,
-`skill.test.ts`, `sub_agent_service.test.ts`, `tool_registry.test.ts`) following the same Vitest conventions as
-the rest of the codebase — see [`../references/develop-testing.md`](./develop-testing.md).
+Test file names in `service_worker/` don't all mirror their source file 1:1 — some group by behavior instead
+(e.g. `background.test.ts` covers `background_session_manager.ts`, `retry.test.ts` covers `retry_utils.ts`,
+`autocompact.test.ts` covers the compaction trigger path). At the time of writing, `agent.ts`, `task_service.ts`,
+`compact_service.ts`, and `model_service.ts` don't have an obviously corresponding test file by name — don't
+infer full coverage from this table; run `git ls-tree --name-only HEAD src/app/service/agent/service_worker/ |
+grep test` for the current test inventory and compare it against the source list above before relying on
+either "it's tested" or "it's untested." `core/` follows the same co-located `*.test.ts` convention and the
+same caveat applies. Vitest conventions generally: see
+[`../references/develop-testing.md`](./develop-testing.md).
 
 ## Extending the Agent subsystem
 
diff --git a/docs/references/architecture-data.md b/docs/references/architecture-data.md
index 93993e9ab..4eeeba92a 100644
--- a/docs/references/architecture-data.md
+++ b/docs/references/architecture-data.md
@@ -15,8 +15,6 @@ needs (see [Adding an entity](#adding-an-entity) below), not by defaulting to `R
 
 ### `Repo<T>`
 
-### `Repo<T>`
-
 ```ts
 export abstract class Repo<T> {
   useCache = false;
diff --git a/docs/references/develop-testing.md b/docs/references/develop-testing.md
index 070e9af73..034fd47a5 100644
--- a/docs/references/develop-testing.md
+++ b/docs/references/develop-testing.md
@@ -12,7 +12,10 @@ budget at once. Chrome APIs are mocked via
 `@Packages/chrome-extension-mock` (`tests/vitest.setup.ts`). `MockMessage` is available for message-system tests.
 `happy-dom` is patched via `patches/` (see `pnpm-workspace.yaml` `patchedDependencies`) to build its
 invalid-selector `DOMException` lazily — the upstream eager construction captures a deep stack on every
-`matches()`/`querySelector()` call and costs ~15% of TSX suite time.
+`matches()`/`querySelector()` call, which is measurably slower at TSX-suite scale. No specific percentage is
+tracked here since it isn't tied to a reproducible command/environment; if you need a number, measure
+before/after this patch in the same environment using the JSON-report method below rather than trusting a
+historical figure.
 
 - Co-locate `*.test.ts`/`*.test.tsx` next to source (or place in `tests`).
 - BDD-style Chinese `describe`/`it` titles. Use `describe.concurrent()` / `it.concurrent()` where independent.
diff --git a/packages/cloudscript/README.md b/packages/cloudscript/README.md
index d1eac53ee..83a6417c3 100644
--- a/packages/cloudscript/README.md
+++ b/packages/cloudscript/README.md
@@ -5,8 +5,10 @@
 
 `CloudScriptFactory`（[`factory.ts`](./factory.ts)）目前只有一个 target：`local`
 （[`local.ts`](./local.ts)）。它把脚本源码、`GM_*` values、cookies 和一份 `config.js` 元数据打进一个 zip,
-附带 `package.json`/`utils.js`/`index.js`（模板见 `src/template/cloudcat-package/`），产出一个可在本地用
-Node 直接运行的可执行包，供脚本迁移或离线执行使用 —— 不涉及任何远端上传。
+附带 `package.json`/`utils.js`/`index.js`（模板见 `src/template/cloudcat-package/`）。`package.json` 声明了外部
+依赖 `scriptcat-nodejs`，因此产出的包**不是**解压后即可直接 `node index.js` 运行 —— 需要先在解压目录执行
+`npm install`（安装 `scriptcat-nodejs`）,再 `npm run run`（等价于 `node index.js`），供脚本迁移或离线执行使用,
+不涉及任何远端上传。
 
 云端同步/备份（WebDAV、OneDrive、Google Drive、Dropbox、百度网盘、S3）由
 [`packages/filesystem`](../filesystem/README.md) 提供，语义细节见 [`docs/cloud-sync.md`](../../docs/cloud-sync.md)。

From dc5cf9800cb66f9ee22c2aad97d8fca14a1129e2 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Sun, 19 Jul 2026 23:50:24 +0900
Subject: [PATCH 03/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20Agent?=
 =?UTF-8?q?=20DOM=20=E6=96=87=E6=A1=A3=E7=9A=84=20default/trusted=20?=
 =?UTF-8?q?=E4=BA=8C=E5=88=86=E6=B3=95=E4=B8=8E=20link-checker=20=E7=9A=84?=
 =?UTF-8?q?=20mailto=20=E8=AF=AF=E6=8A=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review 第二轮 (issuecomment-5016140703)：

- architecture-agent.md: screenshot() 不受 trusted 选项控制（selector 截图/后台 tab
  优先用 CDP，前台 tab 用 captureVisibleTab）；tab monitoring 始终走 CDP，没有
  非 CDP 路径；只有 click/fill 真正按 trusted 分支。逐条核对 dom.ts 后重写该段，
  不再把四类动作统一套进 default/trusted 二选一模型
- DOC-MAINTENANCE.md: link-integrity 脚本的排除模式补上 mailto: 与 app:（原来只排除
  https?:/#，导致 3 处合法的 mailto: 链接被误报 BROKEN），并让 fenced-block 剔除同时
  处理 ``` 与 ~~~；已验证修正后跑出 0 条 BROKEN，且对手动注入的无效链接仍能正确报错

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/DOC-MAINTENANCE.md               |  9 +++++----
 docs/references/architecture-agent.md | 26 ++++++++++++++++++--------
 2 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
index b9f5b6bac..88c39fa4d 100644
--- a/docs/DOC-MAINTENANCE.md
+++ b/docs/DOC-MAINTENANCE.md
@@ -169,10 +169,11 @@ READMEs, a newly added `docs/references/*.md`):
 
 ```bash
 git ls-files '*.md' | while IFS= read -r doc; do
-  # the sed pipeline drops fenced code blocks and inline code spans first, so illustrative sample
-  # links inside ```md snippets or `single-backtick` text (e.g. references/verification-report-template.md's
-  # screenshot/resource examples, verification.md's "Evidence location" spans) aren't false-flagged as broken
-  sed '/^```/,/^```/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^https?:|^#' | while IFS= read -r link; do
+  # the sed pipeline drops fenced code blocks (``` and ~~~) and inline code spans first, so illustrative
+  # sample links inside ```md/~~~md snippets or `single-backtick` text (e.g.
+  # references/verification-report-template.md's screenshot/resource examples, verification.md's
+  # "Evidence location" spans) aren't false-flagged as broken
+  sed '/^```/,/^```/d; /^~~~/,/^~~~/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^(https?:|mailto:|#|app:)' | while IFS= read -r link; do
     target="$(dirname "$doc")/${link%%#*}"
     [ -e "$target" ] && echo "ok     $doc → $link" || echo "BROKEN $doc → $link"
   done
diff --git a/docs/references/architecture-agent.md b/docs/references/architecture-agent.md
index 366141479..65b1d12c6 100644
--- a/docs/references/architecture-agent.md
+++ b/docs/references/architecture-agent.md
@@ -104,14 +104,24 @@ The Agent subsystem does not use one persistence pattern; pick by data shape, ma
   recipe used for GM grants.
 - **DOM automation** runs from the service worker through a single `AgentDomService` (`dom.ts`), which handles
   every action (`navigate`, `readPage`, `screenshot`, `click`, `fill`, `scroll`, `waitFor`, `executeScript`,
-  tab monitoring). Navigation and tab bookkeeping always go through `chrome.tabs` (`navigate`, `update`,
-  `create`, `query`), independent of mode. For `click`/`fill`/`screenshot`/monitoring, `AgentDomService` picks
-  between two implementations: default mode drives them via `chrome.scripting.executeScript`, while "trusted"
-  mode delegates to CDP helpers imported from `dom_cdp.ts` (`cdpClick`, `cdpFill`, `cdpScreenshot`,
-  `cdpStartMonitor`/`cdpStopMonitor`/`cdpPeekMonitor`) for real synthetic input (`isTrusted: true`) via
-  `chrome.debugger`. CDP attaches the debugger to a tab and carries the extra permission/user-visible-banner
-  implications that come with `chrome.debugger` — `dom_cdp.ts` is a helper module `dom.ts` calls into, not an
-  independent service with its own request path.
+  tab monitoring) and delegates to CDP helpers imported from `dom_cdp.ts` (`cdpClick`, `cdpFill`,
+  `cdpScreenshot`, `cdpStartMonitor`/`cdpStopMonitor`/`cdpPeekMonitor`) where it needs `chrome.debugger`.
+  `dom_cdp.ts` is a helper module `dom.ts` calls into, not an independent service with its own request path.
+  The default-vs-trusted split is **not uniform across actions** — check each one:
+  - **Navigation and tab bookkeeping** (`navigate`, `update`, `create`, `query`) always go through
+    `chrome.tabs`, never CDP.
+  - **`click`/`fill`** genuinely branch on the caller's `trusted` option: default mode drives them via
+    `chrome.scripting.executeScript`, "trusted" mode delegates to CDP for real synthetic input
+    (`isTrusted: true`), falling back to the non-trusted path if the CDP call fails.
+  - **`screenshot`** has its own logic independent of any `trusted` flag: a `selector`-scoped capture always
+    uses CDP; a background (non-active) tab tries CDP first and falls back to `chrome.tabs.captureVisibleTab`
+    on failure; an active tab with no selector uses `chrome.tabs.captureVisibleTab` directly.
+  - **Tab monitoring** (`startMonitor`/`stopMonitor`/`peekMonitor`) is unconditionally CDP-based — there is no
+    non-CDP path for it at all.
+
+  CDP attaches the debugger to a tab and carries the extra permission/user-visible-banner implications that
+  come with `chrome.debugger`; how often that applies depends on which action you're looking at, not a single
+  binary "default vs. trusted mode" switch.
 - **OPFS access** is dispatched by caller: `AgentOPFSService.handleOPFSApi` checks whether the request has a
   `sender` (content script, no Blob support) or came over `postMessage` (offscreen, Blob support) and adjusts
   behavior accordingly, rather than assuming one execution context.

From 70c546678d42e1dbf7654a5ecede09ece035a620 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Mon, 20 Jul 2026 00:06:00 +0900
Subject: [PATCH 04/11] =?UTF-8?q?=F0=9F=93=84=20=E6=B6=88=E9=99=A4=20servi?=
 =?UTF-8?q?ce-shape=20=E9=85=8D=E6=96=B9=E8=87=AA=E7=9B=B8=E7=9F=9B?=
 =?UTF-8?q?=E7=9B=BE=E5=B9=B6=E4=BF=AE=E6=AD=A3=E5=89=A9=E4=BD=99=E9=94=99?=
 =?UTF-8?q?=E8=AF=AF=20class=20=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review 第三轮 (issuecomment-5016202376)：

- docs/architecture.md: "A new service" recipe 不再规定统一 `Group + IMessageQueue +
  DAOs` constructor；改为先判断 context/Agent/cross-cutting 类别，再链接
  architecture-services.md#adding-a-service 的决策路径
- docs/references/architecture-services.md:
  - 修正遗漏的错误 class 名（`ChatService`、`AgentTaskService`，而非
    `AgentChatService`/`TaskService`——上一轮只改了 architecture-agent.md，
    漏改本文件里的同一处引用）
  - 明确 context services 的依赖集合本身也会随服务变化（ResourceService 只需
    (Group, mq)，PopupService 需要五个参数），"Group + IMessageQueue + DAOs"
    是构造器注入原则的简写，不是固定参数清单

已核对 `git grep` 确认仓库内不再有 `AgentChatService`/`AgentCompactService`/裸
`TaskService` 的残留引用。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/architecture.md                     |  7 +++++--
 docs/references/architecture-services.md | 17 ++++++++++-------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index de5448672..afc1d8f9d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -232,8 +232,11 @@ Map a change onto the existing extension points instead of inventing new structu
 - **A new persisted entity.** Pick a backend by matching an existing entity with the same data-size/query/lifecycle
   needs — `Repo<T>`, `DAO<T>`, or `OPFSRepo` (see [data layer](./references/architecture-data.md#adding-an-entity)),
   construct it in the manager, expose ops via `group.on`.
-- **A new service.** Constructor-inject `Group` + `IMessageQueue` + DAOs; register handlers in `init()`;
-  instantiate it in the relevant manager with its own `group("name")` (see [service layer](./references/architecture-services.md)).
+- **A new service.** First decide what kind: a context service (owned by one of `content/`, `offscreen/`,
+  `sandbox/`, `service_worker/`), an Agent/core component, or another cross-cutting subsystem — these do
+  **not** share one constructor shape. Then copy the nearest existing service of that kind. See
+  [service layer § Adding a service](./references/architecture-services.md#adding-a-service) for the decision
+  path; don't default to a `Group` + `IMessageQueue` + DAOs constructor for everything.
 - **A new GM API.** Decorate the method with `@GMContext.API` on the content side, add a privileged/offscreen
   handler if needed, register the `@grant` (see [GM API system](./references/architecture-gm-api.md#adding-a-gm-api-sketch)).
 
diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 6f48c9ab0..5d01b8f11 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -84,13 +84,16 @@ on the single `serviceWorker` `Server`. Other contexts have their own managers (
 
 ### Agent composition is different — by design
 
-The standard `Group` / `IMessageQueue` / DAO constructor triple above applies to context services. The Agent
-subsystem's sub-services (`AgentChatService`, `TaskService`, `SkillService`, `AgentModelService`, `MCPService`,
-etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed by `AgentService` instead of each
-independently owning a `Group`, and each takes only the narrower interface it actually needs (e.g.
-`AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService` takes a small
-`SubAgentOrchestrator` interface). When adding to the Agent subsystem, follow the pattern of the nearest
-existing sub-service rather than the SW context-service triple above.
+Context services take their collaborators through the constructor and register handlers in `init()` (the DI
+pattern above), but the *exact* dependency set still varies per service — `ResourceService` takes only
+`(Group, mq)`, `PopupService` takes `(Group, mq, runtime, scriptDAO, systemConfig)` — so "`Group` +
+`IMessageQueue` + DAOs" is a shorthand for "constructor-injected, no internal `new`," not a fixed parameter
+list to copy verbatim. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
+`AgentModelService`, `MCPService`, etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed
+by `AgentService` instead of each independently owning a `Group`, and each takes only the narrower interface
+it actually needs (e.g. `AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService`
+takes a small `SubAgentOrchestrator` interface). When adding to the Agent subsystem, follow the pattern of the
+nearest existing sub-service rather than a context service's constructor shape.
 
 ## Adding a service
 

From 7d3e6da5dea032b421d6f262fed012d32b748425 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Mon, 20 Jul 2026 00:24:47 +0900
Subject: [PATCH 05/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20conte?=
 =?UTF-8?q?xt=20service=20=E6=9E=84=E9=80=A0=E8=A7=84=E5=88=99=E7=9A=84?=
 =?UTF-8?q?=E4=B8=89=E5=A4=84=E7=BB=9D=E5=AF=B9=E8=A1=A8=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review 第四轮 (issuecomment-5016264308)：

architecture-services.md 把 context service 描述成统一的 "pure DI"、"never new
internally"、"no work in constructor"，但 ResourceService 会以字段初始化器内部
创建 ResourceDAO 并在 constructor body 里做 logger/cache 初始化；SubscribeService
同样内部创建 SubscribeDAO 与 ScriptDAO。三处绝对表述改为：共享/外部拥有的
collaborator 通常经 constructor 注入；service 本地专用的 DAO/helper 是否内部
`new` 因 service 而异（举 ResourceService/SubscribeService 为反例）；init() 用于
handler 注册、跨 service 订阅及依赖完整 object graph 的 late wiring，而非"constructor
不能做任何事"。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/references/architecture-services.md | 46 ++++++++++++++++--------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 5d01b8f11..072d798bb 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -5,8 +5,10 @@
 `src/app/service/` holds two kinds of things, not one uniform pattern:
 
 - **Context services** — `content/`, `offscreen/`, `sandbox/`, `service_worker/` — split by the runtime context
-  they execute in. They are deliberately "dumb plumbing on the outside, smart logic on the inside": construction
-  is pure DI, wiring happens once in a manager, and message handlers are registered in `init()`.
+  they execute in. Shared or externally-owned collaborators (other services, the message `Group`, DAOs another
+  service also needs) are typically constructor-injected; whether a service also constructs its own *local*
+  DAO/helper internally varies per service — see below. Manager-level wiring happens once, and message
+  handlers/cross-service subscriptions are registered in `init()`.
 - **Cross-cutting subsystems** — `agent/` (see [`architecture-agent.md`](./architecture-agent.md); spans all
   five contexts rather than living in one) and `extension/` (extension-wide environment helpers, e.g.
   `extension_env.ts`) — plus `queue.ts` (the shared `MessageQueue` wiring used across contexts).
@@ -26,10 +28,11 @@ src/app/service/
 └── sandbox/          runtime.ts (background/scheduled eval + cron)
 ```
 
-### The DI pattern
+### The DI pattern — and its real variance
 
-Every context service takes its collaborators through the constructor — never `new`s them internally. A
-representative signature ([`script.ts`](../../src/app/service/service_worker/script.ts)):
+Shared collaborators (the `Group`, `IMessageQueue`, another service, a DAO owned elsewhere) come in through the
+constructor rather than being reached for via a singleton/import. A representative signature
+([`script.ts`](../../src/app/service/service_worker/script.ts)):
 
 ```ts
 class ScriptService {
@@ -51,11 +54,24 @@ class ScriptService {
 }
 ```
 
-Two consequences worth internalizing:
-
-- **Depend on narrow interfaces** (`IMessageQueue`, not `MessageQueue`) so tests can pass `MockMessage`.
-- **No work in the constructor.** Handler registration and subscriptions belong in `init()`, called by the
-  manager after the whole graph is built (this avoids ordering hazards between mutually dependent services).
+But **don't over-read this as "never `new` internally, constructor never does work"** — several services break
+both of those:
+
+- [`ResourceService`](../../src/app/service/service_worker/resource.ts) constructs its own `ResourceDAO` as a
+  field initializer (`resourceDAO: ResourceDAO = new ResourceDAO()`) and does real setup in the constructor
+  body (`this.logger = LoggerCore.logger().with(...)`, `this.resourceDAO.enableCache()`).
+- [`SubscribeService`](../../src/app/service/service_worker/subscribe.ts) likewise self-constructs
+  `SubscribeDAO` and `ScriptDAO` as field initializers, alongside constructor-injecting `Group`, `mq`, and
+  `ScriptService`.
+
+The actual rule: a DAO/helper that's **local to one service** and nobody else needs is fine to construct
+internally; a DAO/service that's **shared across services** (like the `scriptDAO` passed into `ScriptService`
+above) gets injected so every owner points at the same instance and tests can substitute it. `init()` is where
+handler registration, cross-service subscriptions, and any wiring that depends on the *whole* object graph
+being built go — not a blanket "no work in the constructor" rule; a constructor doing local, self-contained
+setup (logger, own-DAO cache flag) is normal. Depend on narrow interfaces (`IMessageQueue`, not
+`MessageQueue`) so tests can pass `MockMessage`. Check the nearest existing service before assuming either
+extreme.
 
 ### Wiring: `ServiceWorkerManager`
 
@@ -84,11 +100,11 @@ on the single `serviceWorker` `Server`. Other contexts have their own managers (
 
 ### Agent composition is different — by design
 
-Context services take their collaborators through the constructor and register handlers in `init()` (the DI
-pattern above), but the *exact* dependency set still varies per service — `ResourceService` takes only
-`(Group, mq)`, `PopupService` takes `(Group, mq, runtime, scriptDAO, systemConfig)` — so "`Group` +
-`IMessageQueue` + DAOs" is a shorthand for "constructor-injected, no internal `new`," not a fixed parameter
-list to copy verbatim. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
+Context services take *shared* collaborators through the constructor and register handlers in `init()` (the DI
+pattern above), but the exact dependency set — and whether a service also self-constructs a local DAO/helper —
+varies per service (see the `ResourceService`/`SubscribeService` examples above); "`Group` + `IMessageQueue` +
+DAOs" is shorthand for "shared collaborators come in via constructor," not a fixed parameter list or a ban on
+any internal construction. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
 `AgentModelService`, `MCPService`, etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed
 by `AgentService` instead of each independently owning a `Group`, and each takes only the narrower interface
 it actually needs (e.g. `AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService`

From 09fe390e7c27d60a1cfb8299433c6ced4f5c209c Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Mon, 20 Jul 2026 05:53:59 +0900
Subject: [PATCH 06/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20servi?=
 =?UTF-8?q?ce=20reference=20=E5=89=A9=E4=BD=99=E7=9A=84=206=20=E5=A4=84?=
 =?UTF-8?q?=E4=BA=8B=E5=AE=9E=E9=94=99=E8=AF=AF=EF=BC=88queue.ts=E3=80=81D?=
 =?UTF-8?q?AO=20=E5=85=B1=E4=BA=AB=E5=81=87=E8=AE=BE=E3=80=81MockMessage?=
 =?UTF-8?q?=20=E7=94=A8=E9=80=94=E3=80=81=E7=A4=BA=E4=BE=8B=E5=A4=B1?=
 =?UTF-8?q?=E7=9C=9F=E3=80=81manager=20=E6=9E=84=E9=80=A0=E4=B8=8E?=
 =?UTF-8?q?=E8=B7=A8=20context=20=E5=81=87=E8=AE=BE=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review (#pullrequestreview-4731038208)：

- queue.ts 只定义 MessageQueue payload/type（如 TInstallScript、TDeleteScript），
  不是 wiring 本身——实现在 packages/message/message_queue.ts，各入口/manager 自行
  实例化。已修正两处（quick map 描述 + 目录树注释）。
- 删除"跨 service 使用的 DAO 必须注入并共享同一实例"的推导：ScriptService 与
  SubscribeService 各自构造 SubscribeDAO，SubscribeService 也自建 ScriptDAO 而非复用
  manager 传给其他 service 的 scriptDAO。改为"是否共享实例按 cache/lifetime/测试替换
  需求个案决定，以最近邻实现为准"。
- 修正 MockMessage 误用：它实现的是 Message transport（用于测试中构造
  Server/Group），不是 IMessageQueue 的替身；测试传给 service 的仍是真实
  MessageQueue（个别方法用 vi.fn() mock）。
- ScriptService 示例 constructor 补注释说明并非空 body，handler 数量改成
  "many more"（原 "~20 more" 与实际 31 个不符且会漂移），并提示用 git grep 现查。
- ServiceWorkerManager 的"每个 service 都拿 Group + 共享 mq"说法改正：LogService
  无 mq，AgentService 也无 mq（拿 offscreenSend）；示例代码补上两者的真实构造签名。
- 删除 OffscreenManager/SandboxManager/ScriptRuntime "遵循同一 shape" 的说法，改为
  说明三者只是角色相似(wire deps + register handlers)，构造/依赖形状互不相同，
  ScriptRuntime 还有其他两者没有的 contentInit()/externalMessage()。

以上均已对照实际源码（script.ts、resource.ts、subscribe.ts、log.ts、agent.ts、
offscreen/index.ts、sandbox/index.ts、content/script_runtime.ts、
packages/message/mock_message.ts、script.test.ts）逐条核实。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/references/architecture-services.md | 74 ++++++++++++++++--------
 1 file changed, 50 insertions(+), 24 deletions(-)

diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 072d798bb..77f923e19 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -11,14 +11,17 @@
   handlers/cross-service subscriptions are registered in `init()`.
 - **Cross-cutting subsystems** — `agent/` (see [`architecture-agent.md`](./architecture-agent.md); spans all
   five contexts rather than living in one) and `extension/` (extension-wide environment helpers, e.g.
-  `extension_env.ts`) — plus `queue.ts` (the shared `MessageQueue` wiring used across contexts).
+  `extension_env.ts`) — plus `queue.ts` (shared `MessageQueue` **payload/type** definitions, e.g.
+  `TInstallScript`, `TDeleteScript` — not the `MessageQueue` implementation itself, which lives in
+  [`packages/message/message_queue.ts`](../../packages/message/message_queue.ts) and is instantiated per
+  entry point/manager).
 
 ```
 src/app/service/
 ├── agent/            cross-cutting: core/ (provider-agnostic) + service_worker/ (composed services) —
 │                     see architecture-agent.md
 ├── extension/         extension_env.ts (cross-cutting environment helpers)
-├── queue.ts           shared MessageQueue wiring
+├── queue.ts           shared MessageQueue payload/type definitions (not the implementation)
 ├── service_worker/    representative entry points: script.ts · value.ts · resource.ts · runtime.ts ·
 │                      popup.ts · subscribe.ts · synchronize.ts · system.ts · permission_verify.ts ·
 │                      clipboard.ts · download.ts · gm_api/ (SW-side GM handlers) · index.ts (ServiceWorkerManager)
@@ -43,41 +46,56 @@ class ScriptService {
     private readonly valueService: ValueService,
     private readonly resourceService: ResourceService,
     private readonly scriptDAO: ScriptDAO      // data access
-  ) {}
+  ) {
+    // local setup omitted here — see below: the real constructor does real work
+  }
 
   init() {
     this.group.on("getAllScripts", this.getAllScripts.bind(this));
     this.group.on("install", this.installScript.bind(this));
     this.group.on("enable", this.enableScript.bind(this));
-    // … ~20 more handlers
+    // … many more handlers
   }
 }
 ```
 
-But **don't over-read this as "never `new` internally, constructor never does work"** — several services break
-both of those:
+That's a trimmed illustration, not a literal copy of `script.ts` — don't infer an exact handler count from it
+(counts drift; check `git grep -c "this.group.on" src/app/service/service_worker/script.ts` for the current
+one) or assume the constructor body is empty.
+
+**Don't over-read the constructor as "never `new` internally, constructor never does work."** Several services
+break both of those:
 
+- [`ScriptService`](../../src/app/service/service_worker/script.ts) itself: alongside the injected
+  `scriptDAO`, it self-constructs `ScriptCodeDAO`, `LocalStorageDAO`, `CompiledResourceDAO`, `TrashScriptDAO`,
+  and `SubscribeDAO` as field initializers, and its real constructor body sets up a logger, enables caching on
+  two of those DAOs, and builds a `ScriptUpdateCheck` helper.
 - [`ResourceService`](../../src/app/service/service_worker/resource.ts) constructs its own `ResourceDAO` as a
-  field initializer (`resourceDAO: ResourceDAO = new ResourceDAO()`) and does real setup in the constructor
-  body (`this.logger = LoggerCore.logger().with(...)`, `this.resourceDAO.enableCache()`).
-- [`SubscribeService`](../../src/app/service/service_worker/subscribe.ts) likewise self-constructs
-  `SubscribeDAO` and `ScriptDAO` as field initializers, alongside constructor-injecting `Group`, `mq`, and
-  `ScriptService`.
-
-The actual rule: a DAO/helper that's **local to one service** and nobody else needs is fine to construct
-internally; a DAO/service that's **shared across services** (like the `scriptDAO` passed into `ScriptService`
-above) gets injected so every owner points at the same instance and tests can substitute it. `init()` is where
-handler registration, cross-service subscriptions, and any wiring that depends on the *whole* object graph
-being built go — not a blanket "no work in the constructor" rule; a constructor doing local, self-contained
-setup (logger, own-DAO cache flag) is normal. Depend on narrow interfaces (`IMessageQueue`, not
-`MessageQueue`) so tests can pass `MockMessage`. Check the nearest existing service before assuming either
-extreme.
+  field initializer and does real setup in the constructor body (logger, `enableCache()`).
+- [`SubscribeService`](../../src/app/service/service_worker/subscribe.ts) self-constructs `SubscribeDAO` *and*
+  `ScriptDAO` as field initializers, alongside constructor-injecting `Group`, `mq`, and `ScriptService`.
+
+**There is no "shared DAO type ⇒ same instance" invariant to rely on.** `ScriptService` builds its own
+`SubscribeDAO`; `SubscribeService` builds a *separate* `SubscribeDAO` instance, and its own `ScriptDAO` rather
+than reusing the `scriptDAO` the manager passes to `ScriptService`/`RuntimeService`/`PopupService`. Whether a
+given service injects a shared instance or builds its own is decided case by case — by caching needs, lifetime,
+and whether tests need to substitute it — not by a rule you can apply mechanically. Check the nearest existing
+service for the pattern it actually uses before assuming either "always inject" or "always self-construct."
+
+**`MockMessage` is not an `IMessageQueue` substitute.** It implements the lower-level `Message` transport
+(used to build a `Server`/`Group` for RPC in tests, e.g. `new Server("test", new MockMessage(...))`); the
+`IMessageQueue` a service receives is still a real `MessageQueue` instance in tests (`new MessageQueue()`),
+with individual methods like `publish` swapped for a spy (`vi.fn()`) when a test needs to assert on it. If you
+need a lightweight `IMessageQueue` fake, write one against that narrow interface — don't reach for
+`MockMessage`, which solves a different problem.
 
 ### Wiring: `ServiceWorkerManager`
 
 [`src/app/service/service_worker/index.ts`](../../src/app/service/service_worker/index.ts) is the composition
-root for the SW context. It builds DAOs, hands each service its own `group("name")` namespace and the shared
-`mq`, then calls `init()`:
+root for the SW context. It creates a `group("name")` namespace **for the services that need one** and passes
+the shared `mq` **to the services that need pub/sub** — not every service gets both: `LogService` is
+constructed with `(group, systemConfig)` and no `mq`, and `AgentService` is constructed with
+`(group, this.offscreenSend, resource)`, no `mq` at all. Then it calls `init()` on the services that have one:
 
 ```ts
 const scriptDAO = new ScriptDAO();
@@ -91,12 +109,20 @@ const runtime  = new RuntimeService(systemConfig, this.api.group("runtime"), thi
                                     value, script, resource, scriptDAO, localStorageDAO); runtime.init();
 const popup    = new PopupService(this.api.group("popup"), this.mq, runtime, scriptDAO, systemConfig); popup.init();
 value.init(runtime, popup);   // late-bound cross deps resolved after construction
+const log      = new LogService(this.api.group("log"), systemConfig); log.init();              // no mq
+const agent    = new AgentService(this.api.group("agent"), this.offscreenSend, resource); agent.init(); // no mq
 // … synchronize, subscribe, system
 ```
 
 The `group("name")` call is what gives each service its action prefix (`resource/*`, `value/*`, `script/*`, …)
-on the single `serviceWorker` `Server`. Other contexts have their own managers (`OffscreenManager`,
-`SandboxManager`, `ScriptRuntime` for content/inject) following the same shape.
+on the single `serviceWorker` `Server`. Other contexts have their own composition roots
+(`OffscreenManager`, `SandboxManager`, `ScriptRuntime` for content/inject) that play a similar
+"wire dependencies, register handlers" role, but they are **not** built to the same dependency/initialization
+shape as `ServiceWorkerManager` or each other: `OffscreenManager`'s constructor wraps a `WindowMessage` +
+`Server` + `ServiceWorkerClient` into a shared base class; `SandboxManager` builds its own `Server` and hands
+it to a single `Runtime`; and `ScriptRuntime` (content/inject) additionally owns lifecycle methods the others
+don't have, such as `contentInit()` and `externalMessage()`. Read each manager's own file rather than assuming
+it mirrors `ServiceWorkerManager`.
 
 ### Agent composition is different — by design
 

From a310dc809a765ba3727d008d8036dbb74dce9ae7 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Mon, 20 Jul 2026 06:21:55 +0900
Subject: [PATCH 07/11] =?UTF-8?q?=F0=9F=93=84=20=E6=B6=88=E9=99=A4?=
 =?UTF-8?q?=E4=B8=BB=E6=9E=B6=E6=9E=84=E9=A1=B5=E4=B8=8E=20service=20refer?=
 =?UTF-8?q?ence=20=E4=B9=8B=E9=97=B4=E6=AE=8B=E7=95=99=E7=9A=84=E7=BB=9F?=
 =?UTF-8?q?=E4=B8=80=20constructor/init()=20=E6=96=AD=E8=A8=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review (#pullrequestreview-4731478283)：

- docs/architecture.md: "Services are constructor-injected" 一条仍称所有 service 统一
  接收 Group/IMessageQueue/DAO 并在 init() 注册 handler，与 architecture-services.md
  已列出的 LogService/AgentService/ScriptRuntime 反例矛盾。改为陈述依赖与 lifecycle
  因 context/subsystem 而异，链接到 service reference 而不是自己重新枚举统一形状。
- docs/references/architecture-services.md:
  - handler/subscription 注册不再绝对写成发生在 init()：补充 ScriptRuntime.contentInit()
    在 content 入口 init() 之前单独注册 runtime/addElement handler 的反例，
    "Agent composition" 段同样改措辞。
  - MessageQueue 实现的实例化范围从过宽的"per entry point/manager"改为准确列出实际
    实例化点：service_worker.ts、offscreen/base.ts、src/pages/store/global.ts
    （UI 页面订阅广播）；content/inject/sandbox 均不实例化，并给出可复核的
    git grep 命令。
  - DAO 共享 vs 自建的原因不再写成已证实的实现事实（源码只证明是 case-by-case），
    改为规范性决策指南（cache ownership/lifetime/test substitution 是决策时应考虑的
    因素，不是每个现有实例背后已记录的理由）。

已用 git grep 确认仓库内不再有 "Services are constructor-injected"/"receive their...Group"/
"register message handlers in an...init" 等统一措辞残留。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/architecture.md                     | 10 +++++--
 docs/references/architecture-services.md | 36 ++++++++++++++++--------
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index afc1d8f9d..aa98f6d6f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -40,9 +40,13 @@ Three ideas explain almost everything in the codebase:
 - **One message layer, several transports.** [`packages/message`](../packages/message) abstracts
   `chrome.runtime`, `postMessage`, and DOM `CustomEvent` behind a single RPC + pub/sub API, so services are
   written against interfaces (`Server`/`Group`/`Client`/`IMessageQueue`), not raw browser APIs.
-- **Services are constructor-injected.** Domain logic lives in services that receive their `Group`,
-  `IMessageQueue`, and DAOs through the constructor and register message handlers in an `init()` method. This
-  is what makes the system testable with the mock message bus.
+- **Domain logic lives in services, wired explicitly.** Shared collaborators (a `Group`, `IMessageQueue`,
+  another service, a DAO owned elsewhere) typically come in through the constructor; message handlers and
+  subscriptions are registered through an explicit lifecycle method — commonly `init()`, though content and
+  Agent code have their own equivalents. The exact dependency set and lifecycle shape vary by service and
+  context — see [service layer](./references/architecture-services.md) for the real variance and the
+  exceptions, rather than assuming one uniform constructor/`init()` template. This explicit-wiring style is
+  what makes the system testable with the mock message bus.
 
 ```
                                 ┌───────────────────────────────────────────────┐
diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 77f923e19..1af411585 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -8,13 +8,22 @@
   they execute in. Shared or externally-owned collaborators (other services, the message `Group`, DAOs another
   service also needs) are typically constructor-injected; whether a service also constructs its own *local*
   DAO/helper internally varies per service — see below. Manager-level wiring happens once, and message
-  handlers/cross-service subscriptions are registered in `init()`.
+  handlers/subscriptions are registered through an explicit lifecycle method — commonly `init()`, but not
+  always: content additionally has `contentInit()` (`ScriptRuntime` registers `runtime/addElement` there,
+  called by the content entry point before `init()`), and Agent code has its own equivalents (see
+  [`architecture-agent.md`](./architecture-agent.md)). Check the specific file, don't assume `init()` is the
+  only place registration happens.
 - **Cross-cutting subsystems** — `agent/` (see [`architecture-agent.md`](./architecture-agent.md); spans all
   five contexts rather than living in one) and `extension/` (extension-wide environment helpers, e.g.
   `extension_env.ts`) — plus `queue.ts` (shared `MessageQueue` **payload/type** definitions, e.g.
   `TInstallScript`, `TDeleteScript` — not the `MessageQueue` implementation itself, which lives in
-  [`packages/message/message_queue.ts`](../../packages/message/message_queue.ts) and is instantiated per
-  entry point/manager).
+  [`packages/message/message_queue.ts`](../../packages/message/message_queue.ts) and is instantiated by the
+  contexts that actually need pub/sub — currently Service Worker
+  ([`src/service_worker.ts`](../../src/service_worker.ts)), Offscreen
+  ([`src/app/service/offscreen/base.ts`](../../src/app/service/offscreen/base.ts)), and UI pages subscribing
+  to broadcasts ([`src/pages/store/global.ts`](../../src/pages/store/global.ts)) — not content, inject, or
+  sandbox, which don't instantiate it. Run `git grep -n "new MessageQueue" -- src packages` for the current
+  set rather than trusting this list to stay exhaustive.
 
 ```
 src/app/service/
@@ -77,10 +86,12 @@ break both of those:
 
 **There is no "shared DAO type ⇒ same instance" invariant to rely on.** `ScriptService` builds its own
 `SubscribeDAO`; `SubscribeService` builds a *separate* `SubscribeDAO` instance, and its own `ScriptDAO` rather
-than reusing the `scriptDAO` the manager passes to `ScriptService`/`RuntimeService`/`PopupService`. Whether a
-given service injects a shared instance or builds its own is decided case by case — by caching needs, lifetime,
-and whether tests need to substitute it — not by a rule you can apply mechanically. Check the nearest existing
-service for the pattern it actually uses before assuming either "always inject" or "always self-construct."
+than reusing the `scriptDAO` the manager passes to `ScriptService`/`RuntimeService`/`PopupService`. The
+existing choices are case-by-case, not governed by one rule — don't assume either "always inject" or "always
+self-construct." When you're deciding for a new service, weigh cache ownership (does another service need the
+same in-memory cache state?), lifetime (does it need to outlive this service?), and test substitution (does a
+test need to swap it for a fake?) — but that's design guidance for your decision, not a documented reason
+behind each existing instance; check the nearest existing service for the pattern it actually uses.
 
 **`MockMessage` is not an `IMessageQueue` substitute.** It implements the lower-level `Message` transport
 (used to build a `Server`/`Group` for RPC in tests, e.g. `new Server("test", new MockMessage(...))`); the
@@ -126,11 +137,12 @@ it mirrors `ServiceWorkerManager`.
 
 ### Agent composition is different — by design
 
-Context services take *shared* collaborators through the constructor and register handlers in `init()` (the DI
-pattern above), but the exact dependency set — and whether a service also self-constructs a local DAO/helper —
-varies per service (see the `ResourceService`/`SubscribeService` examples above); "`Group` + `IMessageQueue` +
-DAOs" is shorthand for "shared collaborators come in via constructor," not a fixed parameter list or a ban on
-any internal construction. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
+Context services take *shared* collaborators through the constructor and register handlers through an explicit
+lifecycle method (the DI pattern above — commonly `init()`, sometimes another one like content's
+`contentInit()`), but the exact dependency set — and whether a service also self-constructs a local
+DAO/helper — varies per service (see the `ResourceService`/`SubscribeService` examples above); "`Group` +
+`IMessageQueue` + DAOs" is shorthand for "shared collaborators come in via constructor," not a fixed parameter
+list or a ban on any internal construction. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
 `AgentModelService`, `MCPService`, etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed
 by `AgentService` instead of each independently owning a `Group`, and each takes only the narrower interface
 it actually needs (e.g. `AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService`

From 2ca376838919bb397725b77661b89868ab0a317b Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Mon, 20 Jul 2026 06:41:59 +0900
Subject: [PATCH 08/11] =?UTF-8?q?=F0=9F=93=84=20=E6=B6=88=E9=99=A4=20archi?=
 =?UTF-8?q?tecture.md=20=E6=B5=8B=E8=AF=95=E6=AE=B5/=E5=9B=BE=E6=B3=A8/rec?=
 =?UTF-8?q?ipe=20=E4=B8=AD=E9=87=8D=E5=A4=8D=E5=87=BA=E7=8E=B0=E7=9A=84?=
 =?UTF-8?q?=E5=B7=B2=E5=90=A6=E5=AE=9A=E8=AF=B4=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 PR review comment (issuecomment-5017464125)：

- Testing the Internals: 测试段仍写 "message-bus behavior uses MockMessage" 并称
  service 统一经 constructor 收 IMessageQueue/DAO、用 MockMessage 构造 service ——
  这是本 PR 第五轮刚在 architecture-services.md 修正过的同一误解在另一处重现。
  已核对 mock_message.ts/script.test.ts 拆成两层：MockMessage 只是 Server/Group
  的 transport fake；service 的 IMessageQueue 依赖测试中用真实 MessageQueue（个别
  方法 spy）或窄 fake，不是 MockMessage。
- Big Picture 图注："MessageQueue ... broadcasts ... across ALL contexts" 与本 PR
  刚确立的实例化边界矛盾，改为准确指向"当前只有 SW/Offscreen/UI pages 会实例化"。
- "A new persisted entity" recipe 仍统一要求"construct in manager, expose via
  group.on"；已核对 AgentModelService（内部默认 new AgentModelRepo()）与
  AgentChatRepo（模块级 singleton `agentChatRepo`）两个反例，改为按 backend +
  subsystem 找最近邻，只有真正由 context composition root 拥有且需要 RPC 暴露时
  才走 manager/group.on。
- architecture-services.md 里建议的 `git grep -n "new MessageQueue"` 命令会误命中
  MessageQueueGroup 与测试文件；已验证换成
  `git grep -n -E 'new MessageQueue\s*\(' -- src packages | grep -vE '\.(test|spec)\.[cm]?[jt]sx?:'`
  精确返回三处生产实例化点（service_worker.ts、offscreen/base.ts、
  pages/store/global.ts）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/architecture.md                     | 33 ++++++++++++++++++------
 docs/references/architecture-services.md |  7 +++--
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index aa98f6d6f..6be72a274 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -73,7 +73,9 @@ Three ideas explain almost everything in the codebase:
                           │  Server("inject")     │         │  Server("sandbox")        │
                           └──────────────────────┘         └──────────────────────────┘
 
-         MessageQueue (pub/sub) broadcasts state changes across ALL contexts.
+         MessageQueue (pub/sub) broadcasts state changes among the contexts that instantiate it — currently
+         Service Worker, Offscreen, and UI pages (see architecture-services.md for the exact list); content,
+         inject, and sandbox don't hold a MessageQueue instance.
 ```
 
 ---
@@ -234,8 +236,15 @@ Map a change onto the existing extension points instead of inventing new structu
 - **A new broadcast event.** `this.mq.publish("myTopic", payload)` where state changes; `this.mq.subscribe(...)`
   wherever it matters. Use this, not RPC, for "X changed" notifications.
 - **A new persisted entity.** Pick a backend by matching an existing entity with the same data-size/query/lifecycle
-  needs — `Repo<T>`, `DAO<T>`, or `OPFSRepo` (see [data layer](./references/architecture-data.md#adding-an-entity)),
-  construct it in the manager, expose ops via `group.on`.
+  needs — `Repo<T>`, `DAO<T>`, or `OPFSRepo` (see [data layer](./references/architecture-data.md#adding-an-entity))
+  — then copy the nearest entity of that *same backend, in the same subsystem* for ownership and construction:
+  they don't all follow "construct in the manager, expose via `group.on`." Some context-service `Repo<T>`
+  entities do (e.g. `scriptDAO` built in `ServiceWorkerManager` and exposed through RPC); some Agent entities
+  don't — `AgentModelService` constructs its own `AgentModelRepo` internally by default rather than taking one
+  from a manager, and `AgentChatRepo` is a module-level singleton (`export const agentChatRepo = ...`) imported
+  directly rather than manager-constructed or exposed via `group.on`. Only route through the manager +
+  `group.on` when the entity is genuinely owned by a context composition root and needs to be reachable over
+  RPC.
 - **A new service.** First decide what kind: a context service (owned by one of `content/`, `offscreen/`,
   `sandbox/`, `service_worker/`), an Agent/core component, or another cross-cutting subsystem — these do
   **not** share one constructor shape. Then copy the nearest existing service of that kind. See
@@ -253,8 +262,14 @@ premature abstraction.
 ## Testing the Internals
 
 - **Unit (Vitest + happy-dom).** Co-locate `*.test.ts` next to source. `chrome.*` is mocked via
-  [`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock) (`tests/vitest.setup.ts`); message-bus
-  behavior uses `MockMessage`. Run one file: `pnpm test -- --run path/to/file.test.ts`.
+  [`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock) (`tests/vitest.setup.ts`). For the
+  message layer, keep the two pieces separate: `MockMessage` fakes the `Message` **transport** for `Server`/
+  `Group` RPC tests (`new Server("test", new MockMessage(...))`); a service's `IMessageQueue` dependency is
+  tested with a real `MessageQueue` instance (`new MessageQueue()`, with individual methods like `publish`
+  swapped for a spy when a test needs to assert on it) or a narrow fake written against `IMessageQueue` — not
+  `MockMessage`, which solves a different problem (see
+  [architecture-services.md](./references/architecture-services.md) for the detailed distinction). Run one
+  file: `pnpm test -- --run path/to/file.test.ts`.
 - **TDD.** See [AGENTS.md § Engineering Principles](../AGENTS.md#engineering-principles) for the write-failing-
   test-first principle and [develop-testing.md § When TDD doesn't apply](./references/develop-testing.md#when-tdd-doesnt-apply)
   for the narrow exceptions — this section only covers architecture-specific test mechanics, not the policy
@@ -263,6 +278,8 @@ premature abstraction.
   `pnpm run test:e2e:install`).
 - **Before a PR:** lint + the relevant suite — owned by [references/develop-testing.md](./references/develop-testing.md) → *Testing*.
 
-The DI + interface design is what makes this tractable: because services receive `IMessageQueue` and DAOs by
-constructor, a test builds a service with `MockMessage` and an in-memory DAO and exercises handlers directly,
-with no browser.
+The DI + interface design is what makes this tractable: because many services take `IMessageQueue`/DAOs
+through the constructor (dependency set varies — see [architecture-services.md](./references/architecture-services.md)),
+a test builds a service with a real `MessageQueue` (or a narrow fake) and an in-memory DAO and exercises
+handlers directly, with no browser. `MockMessage` is for the separate case of testing `Server`/`Group` RPC
+routing, not for standing in as a service's `IMessageQueue`.
diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 1af411585..9c7ca8d81 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -22,8 +22,11 @@
   ([`src/service_worker.ts`](../../src/service_worker.ts)), Offscreen
   ([`src/app/service/offscreen/base.ts`](../../src/app/service/offscreen/base.ts)), and UI pages subscribing
   to broadcasts ([`src/pages/store/global.ts`](../../src/pages/store/global.ts)) — not content, inject, or
-  sandbox, which don't instantiate it. Run `git grep -n "new MessageQueue" -- src packages` for the current
-  set rather than trusting this list to stay exhaustive.
+  sandbox, which don't instantiate it. Run
+  `git grep -n -E 'new MessageQueue\s*\(' -- src packages | grep -vE '\.(test|spec)\.[cm]?[jt]sx?:'` for
+  the current set rather than trusting this list to stay exhaustive — a plain `"new MessageQueue"` search also
+  matches `new MessageQueueGroup(...)` in `packages/message/message_queue.ts` and every test file that
+  constructs its own instance, neither of which are production instantiation sites.
 
 ```
 src/app/service/

From 515489ed394778e84650bf29237f2daa19d5e231 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Mon, 20 Jul 2026 17:03:11 +0800
Subject: [PATCH 09/11] =?UTF-8?q?=F0=9F=93=84=20=E9=AA=8C=E8=AF=81?=
 =?UTF-8?q?=E6=8A=A5=E5=91=8A=E6=A8=A1=E6=9D=BF=EF=BC=9A=E8=AF=81=E6=8D=AE?=
 =?UTF-8?q?=E5=86=85=E5=B5=8C=E8=80=8C=E9=9D=9E=E9=93=BE=E6=8E=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

报告是给人读来判断实现是否正确的，所以截图、视频、日志、资源都直接嵌进
report.md：视频用 <video> 并配上运行中截下的关键帧（video 既不可跳读，
也不是每个 viewer 都能播），日志与短 fixture 用代码块贴出决定结论的那几行。
仅归档/二进制/超大日志保留裸链接。
---
 .../verification-report-template.md           | 67 ++++++++++++++++---
 docs/verification.md                          | 17 +++--
 2 files changed, 67 insertions(+), 17 deletions(-)

diff --git a/docs/references/verification-report-template.md b/docs/references/verification-report-template.md
index 6d028a2e0..c757bd18d 100644
--- a/docs/references/verification-report-template.md
+++ b/docs/references/verification-report-template.md
@@ -8,7 +8,12 @@ record content in the user's language. Update it as the run proceeds instead of
 looks like, not a second section to add. The full template further down has its own `## Evidence Index`
 heading; use that one heading and fill it following this example's shape.
 
-```md
+This record exists so a reader can judge whether the implementation is correct, so **evidence is embedded, not
+linked**: scrolling `report.md` top to bottom should show the pixels and the deciding log lines without opening
+a single side file. A bare link is the fallback for artifacts that genuinely cannot render inline (archives,
+binaries, multi-megabyte logs), and it carries a note saying what it holds.
+
+~~~md
 ## Evidence Index
 
 ### Screenshots
@@ -16,24 +21,49 @@ heading; use that one heading and fill it following this example's shape.
 ![Options root](screenshots/options-root.png)
 The script list page rendered and the view toggle is visible, proving the `/` route mounted successfully.
 
-![Settings](screenshots/settings.png)
-The settings page shell and content are visible, proving `/settings` did not render blank or crash during mount.
+| Light | Dark |
+| --- | --- |
+| ![Settings light](screenshots/settings-light.png) | ![Settings dark](screenshots/settings-dark.png) |
+
+The settings shell renders in both themes with readable contrast, proving `/settings` mounted and picked up the
+theme tokens rather than falling back to one palette.
 
 ### Videos
 
-- [videos/page@abc.webm](videos/page@abc.webm) — Full page-viewport recording from the script list to the
-  settings page; review it for the navigation and final stable state.
+<video src="videos/page@abc.webm" controls width="720"></video>
+
+Full page-viewport recording from the script list to the settings page; watch it for the navigation and the
+final stable state.
+
+Same run, decisive moments as stills — a video is neither skimmable nor playable in every viewer:
+
+![Before navigation](screenshots/nav-01-list.png)
+The script list before the click; the settings entry is enabled.
+
+![After navigation](screenshots/nav-02-settings.png)
+The settings page after the click; the route changed and the content painted.
 
 ### Logs
 
-- [console.log](console.log) — Browser console output captured during the run; confirms whether unexpected errors
-  appeared.
+The lines the verdict rests on:
+
+```text
+[verify] options url = chrome-extension://<id>/src/options.html#/settings
+[verify] script count after import = 3
+```
+
+Full capture: [console.log](console.log) — no unexpected errors appeared during the run.
 
 ### Resources
 
-- [resources/import.yaml](resources/import.yaml) — Input file used by the import verification; keep it to
-  reproduce the import flow.
+`resources/import.yaml` — the input the import verification consumed:
+
+```yaml
+scripts:
+  - name: demo-script
+    source: https://example.com/demo.user.js
 ```
+~~~
 
 Use this shape:
 
@@ -85,7 +115,7 @@ Use this shape:
 
 ## Evidence Index
 
-Embed screenshots inline, link videos / logs / resources, and annotate every item — see the shape above.
+Embed every artifact inline and annotate what it proves — see the shape above.
 ```
 
 Fill `Result` at the end — the honest verdict, per *Step 4 — Report honestly* in [`verification.md`](../verification.md).
@@ -101,3 +131,20 @@ Keep the checklist factual:
 - Check items only after the corresponding command/assertion has actually passed.
 - If a step is blocked, leave its checkbox unchecked and add a concrete entry under `Blockers`: what failed,
   where it failed, and what evidence was captured.
+
+Keep the evidence embedded:
+
+- **Screenshots** — `![alt](screenshots/….png)` plus a caption line stating what it proves. Put paired shots
+  (before/after, light/dark) in a two-column table so the comparison is one glance, not two scrolls.
+- **Videos** — `<video src="videos/….webm" controls width="720"></video>`. This renders as a player only in
+  viewers that allow inline HTML, and a recording is slow to review either way, so capture the deciding moments
+  as `page.screenshot()` calls *during* the run and embed those stills next to the video. The stills, not the
+  recording, are what carries the verdict.
+- **Logs** — paste the lines the verdict rests on into a fenced block, then link the full capture for the rest.
+  A link alone forces the reader to reconstruct which line mattered.
+- **Resources** — paste short text fixtures (YAML/JSON/userscript) inline in a fenced block. Link only what is
+  large or binary, and say what it contains.
+- Sanitize tokens, cookies, and real credentials *before* pasting log or resource content inline — embedding
+  puts it in front of every reader.
+- Keep every path relative to `report.md`. The scenario directory, not `report.md` alone, is the unit you hand
+  to a reviewer; moving the file out of it breaks every embed.
diff --git a/docs/verification.md b/docs/verification.md
index 757ab5f37..a040d4e87 100644
--- a/docs/verification.md
+++ b/docs/verification.md
@@ -117,13 +117,16 @@ Use `resources/` for any extra local inputs or outputs needed to understand or r
 - mock API responses, fixture JSON/YAML, import/export files, generated ZIPs, or downloaded artifacts
 - temporary HTML pages, saved network payloads, or before/after data snapshots
 
-Reference these resources from `report.md` with relative links such as `[Import file](resources/import.yaml)` or
-`[Mock response](resources/provider-response.json)`. Keep secrets and real credentials out of the resource directory;
-sanitize them before saving evidence.
-
-Embed screenshots inline with `![alt](screenshots/…png)` plus a caption line, so `report.md` renders as a visual
-record you can skim without opening files. Link videos, logs, and resources instead — markdown can't inline them.
-Never list bare links: every item carries a short note explaining what it proves and how to read it.
+Surface these resources in `report.md` — short text fixtures pasted into a fenced block, anything large or
+binary as a relative link such as `[Exported backup](resources/backup.zip)`. Keep secrets and real credentials
+out of the resource directory; sanitize them before saving evidence, and again before pasting any of it inline.
+
+`report.md` is read to decide whether the implementation is correct, so embed the evidence instead of linking
+it: screenshots as `![alt](screenshots/….png)`, videos as `<video src="videos/….webm" controls width="720">`
+alongside stills of the deciding moments, and the log lines or short fixtures that carry the verdict as fenced
+blocks. Scrolling the report should be enough to reach a verdict without opening a side file. Keep a bare link
+only for what cannot render inline — archives, binaries, a full log capture — and never list one bare: every
+item carries a short note explaining what it proves and how to read it.
 
 ### Create `report.md` before you run the browser
 

From bea6d2bdfbf19115c9f213e2e1d8f70866f118dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Mon, 20 Jul 2026 17:18:26 +0800
Subject: [PATCH 10/11] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20revie?=
 =?UTF-8?q?w=20=E5=8F=91=E7=8E=B0=E7=9A=84=E6=9E=B6=E6=9E=84=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E4=BA=8B=E5=AE=9E=E9=94=99=E8=AF=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CAT.agent.* 并非「不走 @GMContext.API/@grant/@PermissionVerify.API」：
  cat_agent.ts 用 @GMContext.API({follow})、gm_agent.ts 用 @PermissionVerify.API、
  compat-grant.js 里五个 CAT.agent.* 都是注册过的 grant。改写为「同一套注册路径，
  区别在点号 grant + follow/dotAlias + connect() 流式」，两处重复表述一并修正。
- grant/compat 表在 packages/eslint/compat-grant.js，不在 linter-config.ts
  （后者只有 rules/globals/env）。
- 配方已是 5 步，删掉残留的「four-step recipe」措辞。
- 工具名按 name: 字段更正：sub_agent.ts 注册为 agent，tab_tools.ts 无 tab_* 前缀。
- architecture.md 传输表 MessageQueue 行的「All contexts」与本文件 76-78 行
  刚确立的实例化边界矛盾，改为 SW/Offscreen/UI 页面。
---
 docs/architecture.md                   |  2 +-
 docs/references/architecture-agent.md  | 21 +++++++++++++--------
 docs/references/architecture-gm-api.md | 21 +++++++++++++--------
 3 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 6be72a274..6edb0f766 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -146,7 +146,7 @@ communication styles** over **several transports**.
 | `CustomEventMessage` | [`custom_event_message.ts`](../packages/message/custom_event_message.ts) | Content ↔ Inject | DOM `CustomEvent` dispatch (bypasses page tampering) |
 | `WindowMessage` | [`window_message.ts`](../packages/message/window_message.ts) | Offscreen ↔ Sandbox | `window.postMessage` |
 | `ServiceWorkerMessageSend` | [`window_message.ts`](../packages/message/window_message.ts) | SW → Offscreen (Chrome) | `clients.matchAll()` + `postMessage` |
-| `MessageQueue` | [`message_queue.ts`](../packages/message/message_queue.ts) | All contexts (broadcast) | `chrome.runtime.sendMessage` + local `EventEmitter3` |
+| `MessageQueue` | [`message_queue.ts`](../packages/message/message_queue.ts) | Broadcast among the contexts that instantiate it — SW, Offscreen, UI pages | `chrome.runtime.sendMessage` + local `EventEmitter3` |
 | `MockMessage` | [`mock_message.ts`](../packages/message/mock_message.ts) | Tests | in-memory `EventEmitter3` |
 
 All transports implement the small `Message` / `MessageSend` / `MessageConnect` interfaces in
diff --git a/docs/references/architecture-agent.md b/docs/references/architecture-agent.md
index 65b1d12c6..3055d3ddb 100644
--- a/docs/references/architecture-agent.md
+++ b/docs/references/architecture-agent.md
@@ -39,14 +39,19 @@ into `Group`/`Server`.
 
 [`ToolRegistry`](../../src/app/service/agent/core/tool_registry.ts) is the **global** registry: tools it holds
 persist for the process lifetime and are classified by `ToolSource` — `builtin` (permanent, e.g.
-`web_fetch`/`web_search`/`opfs_*`/`tab_*`), `mcp` (from an `MCPService`-managed server), `skill` (skill
-meta-tools: `load_skill`, `execute_skill_script`, `read_reference`), `session` (registered per conversation:
-task tools, `ask_user`, `sub_agent`, `execute_script`), and `script` (user-script-supplied tools passed through
-`conv.chat`, dispatched via a callback rather than stored in the map).
+`web_fetch`/`web_search`/`opfs_*`/the tab tools such as `list_tabs`/`open_tab`), `mcp` (from an
+`MCPService`-managed server), `skill` (skill meta-tools: `load_skill`, `execute_skill_script`,
+`read_reference`), `session` (registered per conversation: task tools, `ask_user`, `agent`, `execute_script`),
+and `script` (user-script-supplied tools passed through `conv.chat`, dispatched via a callback rather than
+stored in the map).
+
+Tool names don't always match their source file — the sub-agent tool defined in `sub_agent.ts` registers as
+`agent`, and `tab_tools.ts` registers `get_tab_content`/`list_tabs`/`open_tab`/`close_tab`/`activate_tab` with
+no shared prefix. Read the `name:` field, not the filename.
 
 [`SessionToolRegistry`](../../src/app/service/agent/core/session_tool_registry.ts) wraps a read-only reference
 to the global `ToolRegistry` with its own per-session `Map`. This exists because registering a same-named
-builtin tool (task tools, `ask_user`, `sub_agent`) directly on the global registry would let concurrent
+builtin tool (task tools, `ask_user`, `agent`) directly on the global registry would let concurrent
 sessions clobber each other's closures — a session-scoped tool needs to stay bound to its own
 `conversationId`/`sendEvent`. `getDefinitions()` merges session tools over parent tools (session shadows
 parent); `execute()` builds the merged map and delegates to `parent.executeTools()` so shared behavior (e.g.
@@ -99,9 +104,9 @@ The Agent subsystem does not use one persistence pattern; pick by data shape, ma
 
 - **Content (`src/app/service/content/gm_api/cat_agent.ts`)** exposes the `CAT.agent.*` API to user scripts —
   `ConversationInstance` wraps a conversation and dispatches tool-call handlers registered by the calling
-  script. This is a distinct API family from the traditional GM API (see
-  [`architecture-gm-api.md`](./architecture-gm-api.md)); it does not follow the four-step `@GMContext.API`
-  recipe used for GM grants.
+  script. It registers through the same `@GMContext.API` / `@PermissionVerify.API` / `@grant` path as the
+  traditional GM API, with dotted grant names and `connect()`-based chat streaming — see
+  [`architecture-gm-api.md`](./architecture-gm-api.md) for the differences that matter when adding one.
 - **DOM automation** runs from the service worker through a single `AgentDomService` (`dom.ts`), which handles
   every action (`navigate`, `readPage`, `screenshot`, `click`, `fill`, `scroll`, `waitFor`, `executeScript`,
   tab monitoring) and delegates to CDP helpers imported from `dom_cdp.ts` (`cdpClick`, `cdpFill`,
diff --git a/docs/references/architecture-gm-api.md b/docs/references/architecture-gm-api.md
index 399fabd3a..8f4f6db68 100644
--- a/docs/references/architecture-gm-api.md
+++ b/docs/references/architecture-gm-api.md
@@ -67,14 +67,19 @@ work.
    `@PermissionVerify.API(...)`.
 4. If it needs DOM, route through the offscreen GM API instead:
    [`src/app/service/offscreen/gm_api.ts`](../../src/app/service/offscreen/gm_api.ts).
-5. Register the `@grant` so the linter and the context builder recognize it — grant/compat data lives in
-   [`packages/eslint/linter-config.ts`](../../packages/eslint/linter-config.ts) (not just "the `eslint` package"
-   generally; that package also ships unrelated compat tables like `compat-headers.js`).
+5. Register the `@grant` so the linter and the context builder recognize it — the grant/compat map lives in
+   [`packages/eslint/compat-grant.js`](../../packages/eslint/compat-grant.js) (not just "the `eslint` package"
+   generally; that package also ships unrelated compat tables like `compat-headers.js`, and
+   `linter-config.ts` holds the ESLint `rules`/`globals`/`env` config, no grant data).
 
-### Agent/CAT API is a separate family
+### Agent/CAT API is the same recipe with dotted grants
 
 The Agent subsystem's `CAT.agent.*` surface (`src/app/service/content/gm_api/cat_agent.ts` — see
-[`architecture-agent.md`](./architecture-agent.md)) is exposed alongside the traditional GM API but does not
-go through `@GMContext.API`/`@grant`/`@PermissionVerify.API`: it has its own service/permission path. Don't
-fold a new Agent-facing API into the four-step recipe above without first checking whether it's a GM API
-(script-facing, grant-gated) or an Agent API (conversation-facing, its own registration).
+[`architecture-agent.md`](./architecture-agent.md)) goes through the *same* registration path as the
+traditional GM API: `@GMContext.API` on the content side
+([`cat_agent.ts`](../../src/app/service/content/gm_api/cat_agent.ts)), `@PermissionVerify.API` on the SW side
+([`gm_agent.ts`](../../src/app/service/service_worker/gm_api/gm_agent.ts)), and a registered grant in
+[`compat-grant.js`](../../packages/eslint/compat-grant.js). What differs is the naming and transport
+shape — the grant is dotted (`CAT.agent.conversation`) and bound with `follow:` rather than `alias:`, the SW
+handlers set `dotAlias: false`, and conversation chat streams over `connect()` instead of `sendMessage`. Copy
+the nearest existing `CAT.agent.*` method rather than a `GM_*` one.

From a2e0035cc0ba543162b9a1b3b74e6d1e3b9dd4ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Mon, 20 Jul 2026 17:22:38 +0800
Subject: [PATCH 11/11] =?UTF-8?q?=F0=9F=93=9D=20=E6=B3=A8=E9=87=8A?=
 =?UTF-8?q?=E9=87=8C=E7=9A=84=E4=BC=9A=E8=AF=9D=E7=BA=A7=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E6=94=B9=E7=94=A8=E7=9C=9F=E5=AE=9E=E6=B3=A8=E5=86=8C=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

task/sub_agent 是模块简写，grep 不到；实际注册名是 create_task
（task_tools.ts）与 agent（sub_agent.ts:26）。仅改注释，无行为变更。
---
 src/app/service/agent/core/session_tool_registry.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/app/service/agent/core/session_tool_registry.ts b/src/app/service/agent/core/session_tool_registry.ts
index 1cea9f7d3..9d0f8186f 100644
--- a/src/app/service/agent/core/session_tool_registry.ts
+++ b/src/app/service/agent/core/session_tool_registry.ts
@@ -14,7 +14,7 @@ import type {
  *
  * 架构动机：
  * 原来的 ToolRegistry 是全局共享 Map，会话间 registerBuiltin 同名工具会互相覆盖闭包，
- * 导致并发会话的 task/ask_user/sub_agent 绑定到错误的 conversationId/sendEvent。
+ * 导致并发会话的 create_task/ask_user/agent 等会话级工具绑定到错误的 conversationId/sendEvent。
  *
  * 本类持有 parent: ToolRegistry 只读引用 + 自己的 sessionTools Map。
  * - register()：只写入 sessionTools（不污染 parent）