🐛 完善贡献者指南与编辑器未保存导航保护

.gitignore

@@ -34,17 +34,19 @@ CHANGELOG.md
 package-lock.json
 yarn.lock
 
+# AI 工具本地工作目录(会话状态、计划、worktree、构建产物副本，体积可达 GB 级)
 .claude
-
 .codex
-
 .omc
+# 不带尾斜杠：linked worktree 里的 .dev-kit 是符号链接，`.dev-kit/` 只匹配真目录会漏掉它
+.dev-kit
+.superpowers/
+docs/superpowers/
+docs/specs/
 
 test-results
 playwright-report
+.vitest-reports/
 
 # 一次性功能验证脚本(见 docs/verification.md)，不提交、不进 CI
 e2e/scratch/
-
-superpowers
-.omc

.prettierignore

@@ -3,8 +3,12 @@ package-lock.json
 pnpm-lock.yaml
 yarn.lock
 
-# Claude Code
+# Agent tooling working dirs
 .claude
+.codex
+.dev-kit/
+.omc/
+.superpowers/
 
 # Docs & examples
 *.md
@@ -14,4 +18,8 @@ example/
 dist/
 playwright-report/
 test-results/
+.vitest-reports/
 coverage/
+
+# 一次性验证脚本(见 docs/verification.md)，随写随删，不参与仓库格式门禁
+e2e/scratch/

AGENTS.md

@@ -1,51 +1,24 @@
 # Repository Guidelines
 
 This file provides guidance to AI coding agents (Claude Code, etc.) when working with code in this repository.
+It holds only the engineering principles and the architecture quick-map; the concrete "how" belongs to the docs
+below. `CLAUDE.md` merely `@import`s this file — don't split guidance between the two. Link the owning doc
+instead of copying its content here.
 
-> **Note:** This is the single source of truth relative to `CLAUDE.md` — `CLAUDE.md` only contains `@AGENTS.md`
-> and re-imports this file; don't split guidance between the two, put it here. Detailed guidance beyond
-> engineering principles and the architecture map is owned by the docs linked below (see
-> [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md)'s ownership table) — cross-link them, don't duplicate
-> their content here.
+**Read before you act.** [`docs/README.md`](docs/README.md) indexes the full doc set.
 
-> **Before writing any code, read [`docs/develop.md`](docs/develop.md)** — the development spec (commands,
-> project structure, coding style, UI & theme rules, testing mechanics, i18n, and the commit/PR workflow). This
-> file keeps only the non-negotiable engineering principles and the architecture map; the concrete "how" lives
-> in that same guide, and deep internals in [`docs/architecture.md`](docs/architecture.md).
-
-> **To manually verify a feature actually works, read [`docs/verification.md`](docs/verification.md)** — drive
-> the real built extension end-to-end with one-shot throwaway scratch scripts (not the committed test suite).
-
-> **Before building or modifying any page, dialog, or block, read [`docs/design.md`](docs/design.md)** — the
-> design system: color tokens, component palette, layout/motion/state patterns, and the new-page recipe. Its
-> Core Constraints apply to every UI change, not just new ones.
-
-> **Before any translation/localization work, read [`docs/translation.md`](docs/translation.md)** —
-> the single source of truth for translation. Whenever you add or change localized content
-> (`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 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, 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.
-
-> **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture,
-> translation, contributing, localized READMEs).
+| Before you… | Read |
+| --- | --- |
+| write any code | [`docs/develop.md`](docs/develop.md) |
+| build or modify any page, dialog, or block | [`docs/design.md`](docs/design.md) — its Core Constraints apply to *every* UI change, not only new pages |
+| add or change localized content | [`docs/translation.md`](docs/translation.md) — plus the matching `docs/references/terminology-<locale>.md` when one exists |
+| add, edit, reorganize, or review any tracked contributor Markdown (this file, `docs/*`, `.github/*.md`, package- and source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — *if you can't grep it on this branch, don't claim it* |
+| open or update a pull request | [`docs/pull-request.md`](docs/pull-request.md) |
+| manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — a throwaway scratch script against the built extension, not the committed suite |
 
 ## Project Overview
 
-ScriptCat — Manifest V3 browser extension that runs Tampermonkey-compatible user scripts. TypeScript + React 19 + Rspack. Package manager is **pnpm** (preinstall enforces).
-
-> **UI stack.** The presentation layer (`src/pages/`) is built with **shadcn/ui + Tailwind CSS v4** on
-> **React 19** (migrated from Arco Design + UnoCSS). The concrete UI/theme rules live in
-> [`docs/develop.md`](docs/develop.md); the design system (color tokens, components, layout/motion/state
-> patterns, new-page recipe) lives in [`docs/design.md`](docs/design.md).
+ScriptCat — Manifest V3 browser extension that runs Tampermonkey-compatible user scripts. TypeScript + React 19 + Rspack. Package manager is **pnpm** (preinstall enforces). The presentation layer (`src/pages/`) is **shadcn/ui + Tailwind CSS v4** (migrated from Arco Design + UnoCSS).
 
 ## Engineering Principles
 
@@ -63,9 +36,8 @@ isn't universal, that's called out in the item itself.
 
 ## Architecture
 
-> **Deep dive:** [`docs/architecture.md`](docs/architecture.md) — the human-facing internals guide for
-> contributors working on ScriptCat core: process model, message passing, service/data layers, GM API system,
-> script execution, and the build pipeline, with "how to extend" recipes. The section below is the quick map.
+Quick map only — the internals guide and its "how to extend" recipes are in
+[`docs/architecture.md`](docs/architecture.md).
 
 ### Multi-Process Model
 
@@ -107,7 +79,4 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 
 `message/` (with mocks), `filesystem/` (WebDAV, cloud drive providers, zip export — see [`docs/cloud-sync.md`](docs/cloud-sync.md)), `cloudscript/`, `eslint/` (userscript lint config — `eslint-plugin-userscripts`-based `defaultConfig` for the in-app editor), `chrome-extension-mock/`.
 
-> The project's own custom ESLint rules (`eslint-rules/` at the repo root, wired in `eslint.config.mjs` —
-> **not** `packages/eslint/`, which is the unrelated userscript lint config) are documented in
-> [`docs/develop.md`](docs/develop.md#eslint-custom-rules): exact rule names, scopes, and which are covered by
-> `eslint-rules/harness.test.mjs`.
+The project's *own* custom ESLint rules live in `eslint-rules/` at the repo root, **not** in `packages/eslint/`; both are documented in [`docs/develop.md`](docs/develop.md#eslint-custom-rules).

docs/DOC-MAINTENANCE.md

@@ -88,22 +88,24 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 
 | Doc | Owns |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | Engineering principles + architecture quick-map. Single source of truth; `CLAUDE.md` only `@import`s it. |
-| [`develop.md`](./develop.md) | The concrete "how": commands, structure, style, i18n, commit/PR; testing (design, cleanup policy, mechanics) split to [`references/develop-testing.md`](./references/develop-testing.md). |
-| [`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), [`references/architecture-agent.md`](./references/architecture-agent.md). |
+| [`../AGENTS.md`](../AGENTS.md) | Engineering principles + architecture quick-map. `CLAUDE.md` only `@import`s it. |
+| [`develop.md`](./develop.md) | The concrete "how": commands, structure, style, i18n, commit/PR. Testing → [`references/develop-testing.md`](./references/develop-testing.md). |
+| [`pull-request.md`](./pull-request.md) | The PR body: structure and evidence rules. The human-facing template stays lightweight. |
+| [`design.md`](./design.md) | The design system; tokens, component palette, and layout/motion/state/a11y patterns → the three `references/design-*.md`. |
+| [`verification.md`](./verification.md) | *When* to drive the real built extension, where its evidence goes, how to report honestly. Not the harness — link to `e2e/README.md`, don't restate fixtures/isolation/env vars. |
+| [`../e2e/README.md`](../e2e/README.md) | The harness itself: the two tracks and their configs, isolation, fixture/helper inventory, protocol mocks, `E2E_*` variables, artifact paths. |
+| [`architecture.md`](./architecture.md) | Deep internals; subsystem deep-dives → the six `references/architecture-*.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. |
-| [`external-access-guide.md`](./external-access-guide.md) | End-user how-to for External Access: install sctl, enable, enroll once (`sctl connect`), write/source-read policies, three-tier decisions, tool table, CLI verbs, worked examples. Security rationale lives in the sctl repo's `docs/threat-model.md`/`docs/protocol.md` — link, don't duplicate. `external-access-guide_zh-CN.md` is its zh-CN translation — keep in sync via [`translation.md`](./translation.md), don't fork content. |
-| [`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. |
+| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: organization rules, fact-check / anti-drift discipline, policy-consistency checks — across every tracked contributor Markdown, not just `AGENTS.md` + `docs/*`. |
+| [`README.md`](./README.md) | The reader-facing index: what each doc contains and when to read it. |
+| `.github/copilot-instructions.md` | Copilot-specific entry point and genuine tool-specific differences only; shared facts 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. To discover the current full set instead of relying on this table alone, run
+This table records **ownership boundaries** — which doc a given fact belongs in. It is deliberately *not* the
+index; [`README.md`](./README.md) holds the per-doc contents and "read before X" triggers, so don't restate one
+inside the other. When you move a fact, move it to the doc that owns it and cross-link — never copy it into two
+places, or they drift apart. To discover the current full set rather than relying on this table, run
 `git ls-files '*.md'`.
 
 ## Checklist 1 — Organization (every doc change)

docs/README.md

@@ -10,18 +10,17 @@
 | [`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)。**做页面/对话框/区块前先读。** |
+| [`../e2e/README.md`](../e2e/README.md) | E2E 测试台手册:两条赛道(committed smoke / gitignored scratch)、浏览器与 profile 隔离、fixtures 与 helper 清单、协议 mock、`E2E_*` 环境变量、产物与失败排查路径。**跑 / 写 E2E 或一次性验证脚本前先读。** |
 | [`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)(构建管线)、[`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)。**改/审文档前先读。** |
 
 ## 外部接入 / External Access
 
-内置于所有构建、**默认关闭**,从扩展设置开启;经伴随二进制 [`sctl`](https://github.com/scriptscat/sctl)(WebSocket daemon,默认 `127.0.0.1:8643`)通信,不新增浏览器权限、无 native-messaging 主机与安装器。信任扁平:接入(enrollment)一次建立长期密钥 K,CLI 与所有 MCP agent 都继承信任,不再逐客户端配对/scope/撤销。
-
 | 文档 | 说明 |
 | --- | --- |
-| [`external-access-guide.md`](./external-access-guide.md) | 使用指南:安装 sctl、启用外部接入、一次性接入(`sctl connect` 带外配对码)、写操作/源码读取两条策略、三档决策(拒绝/允许/本会话允许)的实操步骤,附 MCP 工具表、CLI 动词与真实用例。**想实际用起来先读这份。**中文版见 [`external-access-guide_zh-CN.md`](./external-access-guide_zh-CN.md)。 |
+| [官网外部接入指南](https://docs.scriptcat.org/docs/use/external-access/) | 面向用户的安装、接入、权限、命令行、MCP、审计和排障指南；由 `scriptcat.org` 统一维护中文、英文和俄文版本。 |
 | [`sctl` 仓库 `docs/protocol.md`](https://github.com/scriptscat/sctl/blob/main/docs/protocol.md) | 扩展↔daemon 的 JSON-RPC 2.0、握手、能力协商、错误码和阻塞语义。权威 schema 与生成器位于 sctl；本仓库只消费 [`external_access/generated/`](../src/app/service/service_worker/external_access/generated/) 产物。 |
 | [`sctl` 仓库 `docs/threat-model.md`](https://github.com/scriptscat/sctl/blob/main/docs/threat-model.md) | 威胁模型:两个信任锚点(长期密钥 K + 0600 控制令牌)、扁平信任的取舍、Origin 白名单、攻击面与对策、写路径人工审批 + TOCTOU、落盘凭据一览。 |