From 70fcc142be837f83b35eff5c32b119b1adf5e83e Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 8 Aug 2026 09:45:34 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=84=20=E6=BE=84=E6=B8=85=20Agent?= =?UTF-8?q?=20=E6=96=87=E6=A1=A3=E8=81=8C=E8=B4=A3=E4=B8=8E=E5=AE=A1?= =?UTF-8?q?=E6=9F=A5=E9=97=A8=E6=A7=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 70 ++++++++++++++++++++++----------- AGENTS.md | 34 +++++++++++----- 2 files changed, 70 insertions(+), 34 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 49fe962a8..fbc1c49b2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,30 +1,52 @@ # ScriptCat — Copilot Instructions -> **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. +> **Copilot-specific delta only.** Shared engineering principles and the architecture quick-map are owned by +> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. Read those sources before +> reviewing or writing code. If this file disagrees with an owning document, the owning document wins and this +> file should be corrected rather than expanded into a second source of truth. ## Code Review - 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. +- Perform a **comprehensive, independent review of the entire current diff** every time: + - inspect every changed file, regardless of extension or whether it was reviewed previously; + - use PR descriptions, commit messages, and discussion only as context — conclusions must be grounded in the + current repository state and the actual diff; + - re-check affected code paths instead of assuming unchanged or previously reviewed code is safe. +- Use the architecture map and routed subsystem docs from `AGENTS.md` when a finding depends on repository-specific + behavior. Do not recreate those facts here from memory. + +### Finding gate + +For PR-review findings, focus on defects introduced by the current diff or made newly reachable by it. A +pre-existing defect discovered while tracing an affected code path may still be reported only when it has material +correctness, security, data-loss, reliability, or comparably significant user/developer impact. Label it clearly as +**pre-existing** so the reviewer can separate regression risk from nearby debt; otherwise keep the review scoped to +the change. + +For any finding you report, apply every relevant check below: + +1. **Relation to the change:** state whether the defect is introduced/newly reachable or pre-existing in an affected + path; do not imply the PR caused a defect when it did not. +2. **Concrete trigger or proof path:** state the input/state/browser/context that reaches it, **or** a demonstrable + code path / invariant violation when runtime reproduction is not the appropriate proof (for example a race, + lifecycle violation, resource leak, or security-boundary error). +3. **Concrete impact:** explain the user/developer-visible consequence, not just a stylistic preference or + hypothetical concern. +4. **Located:** point to the smallest useful changed location when the finding is PR-introduced. For a pre-existing + finding, point to the smallest useful affected location when that location is represented in the diff; if the + relevant location is outside the diff, report it in the review summary instead of attaching it to an unrelated + changed line. +5. **Distinct:** do not create a second finding for the same root cause unless the separate location needs an + independent fix. +6. **Actionable:** make clear which behavior or contract must be restored without prescribing an unrelated refactor. + +If a repository-specific assumption is needed to support a finding and it cannot be verified from the owning +docs/code, **do not submit it as a finding**. If the uncertainty is still useful to the reviewer, put it in the review +summary as an explicit question or unverified assumption and identify the canonical source that would resolve it. + +## Minimal fallback when linked instructions are unavailable + +Do **not** invent or retain a parallel architecture/coding summary here. Limit work to facts that are directly +verifiable from the current diff and files, avoid structural recommendations that depend on unavailable +repository policy, and explicitly state which canonical instruction source could not be loaded. diff --git a/AGENTS.md b/AGENTS.md index 8eb928f4d..ea5a6417b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,29 +1,30 @@ # 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. +This is the repo-wide contract for AI coding agents. It owns **engineering principles** and the **architecture quick-map** only. Concrete mechanics belong to the routed docs below. `CLAUDE.md` only imports this file, and `.github/copilot-instructions.md` may add Copilot-specific behavior but must not duplicate shared policy or architecture. -**Read before you act.** [`docs/README.md`](docs/README.md) indexes the full doc set. +Use [`docs/README.md`](docs/README.md) as the document index. When a routed document owns a concern, follow that document and link to it rather than copying its content here. + +## Route the task before acting | Before you… | Read | | --- | --- | | write any code | [`docs/develop.md`](docs/develop.md) | +| change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) — plus the relevant `docs/references/architecture-*.md` deep-dive | | 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-.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 | +For a task that spans several rows, read each applicable owner before performing that part of the task; do not front-load unrelated docs just because they might become relevant later. For a task that fits none of them cleanly, inspect `docs/README.md` and the nearby implementation/tests before inventing a new rule or abstraction. + ## Project Overview 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 -These are non-negotiable, regardless of what `docs/develop.md` says about mechanics — where a principle's scope -isn't universal, that's called out in the item itself. +These are the repo-wide defaults. When a principle links to a narrow, explicit exception in its owning document, that exception is part of the same contract; unrelated or unlinked downstream prose does not silently override the principle. - **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. @@ -36,14 +37,13 @@ isn't universal, that's called out in the item itself. ## Architecture -Quick map only — the internals guide and its "how to extend" recipes are in -[`docs/architecture.md`](docs/architecture.md). +This is an orientation map, not an implementation manual. Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or adding a subsystem. ### Multi-Process Model 5 isolated contexts communicating via message passing: -``` +```text Service Worker (src/service_worker.ts) ├── ExtensionMessage ──────────────→ Content Script (src/content.ts) │ └── CustomEventMessage ──→ Inject Script (src/inject.ts) @@ -64,15 +64,18 @@ Service Worker (src/service_worker.ts) Execution paths: page scripts → `chrome.userScripts`; background → SW → Offscreen → Sandbox; scheduled → cron in Sandbox. ### Message Passing (`packages/message/`) + `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/`) 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` / `DAO` / `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). ### Key Packages @@ -80,3 +83,14 @@ 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 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). + +## Completion checksum + +Before claiming a task is complete, use the applicable owner docs above to verify the final state. This section is a handoff checklist, not a second copy of their mechanics; when a detail matters, the linked owner wins. If an item cannot be checked, report the limitation instead of upgrading the claim to “verified” or “all fixed.” + +- **Owners:** every part of the task was checked against its applicable routed owner; documentation work follows [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md). +- **Evidence:** reproduction, tests, and manual evidence satisfy the applicable rules in [`docs/references/develop-testing.md`](docs/references/develop-testing.md) and [`docs/verification.md`](docs/verification.md), including any explicit exception used. +- **Contract & scope:** the final diff still matches the requested/verified behavior and the scope-discipline principles above; no unrelated compatibility layer or cleanup slipped in. +- **Extension point:** architecture-sensitive changes were checked against [`docs/architecture.md`](docs/architecture.md) and the relevant deep-dive instead of creating a parallel abstraction from memory. +- **Facts:** changed documentation claims were checked using the branch-aware process in [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md), not memory or untracked files. +- **Verification:** the checks required by the applicable owner docs were run, and any environment/tooling blocker is stated explicitly in the completion report or PR. From 223b652f2ddb0a1a117f8d47e79095c0133285c9 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sun, 9 Aug 2026 20:50:10 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20Agent?= =?UTF-8?q?=20=E6=96=87=E6=A1=A3=E8=B7=AF=E7=94=B1=E4=B8=8E=E8=81=8C?= =?UTF-8?q?=E8=B4=A3=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 16 ++++++---------- docs/README.md | 2 +- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fbc1c49b2..8d42cc995 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,20 +1,16 @@ # ScriptCat — Copilot Instructions > **Copilot-specific delta only.** Shared engineering principles and the architecture quick-map are owned by -> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. Read those sources before -> reviewing or writing code. If this file disagrees with an owning document, the owning document wins and this -> file should be corrected rather than expanded into a second source of truth. +> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. For code review, also read +> [`../docs/develop.md`](../docs/develop.md). Read those sources before reviewing or writing code. If this file +> disagrees with an owning document, the owning document wins and this file should be corrected rather than +> expanded into a second source of truth. ## Code Review - Respond in Chinese when performing a code review (用中文回复代码审查意见). -- Perform a **comprehensive, independent review of the entire current diff** every time: - - inspect every changed file, regardless of extension or whether it was reviewed previously; - - use PR descriptions, commit messages, and discussion only as context — conclusions must be grounded in the - current repository state and the actual diff; - - re-check affected code paths instead of assuming unchanged or previously reviewed code is safe. -- Use the architecture map and routed subsystem docs from `AGENTS.md` when a finding depends on repository-specific - behavior. Do not recreate those facts here from memory. +- Re-review the entire current diff independently every time; do not treat prior review results or comments as a + substitute for a fresh review. ### Finding gate diff --git a/docs/README.md b/docs/README.md index f34c011f5..25aff0be5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ | 文档 | 说明 | | --- | --- | -| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源 —— 但仅相对 `CLAUDE.md`(其仅导入它)成立;`.github/copilot-instructions.md` 是 Copilot 的独立入口,与本文件共享的事实需在两边都改动时做一致性核对(parity review)。 | +| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览与 AI coding agent 的共享约定所有者；`CLAUDE.md` 仅导入它，`.github/copilot-instructions.md` 仅保留 Copilot 专属增量。 | | [`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)。**做页面/对话框/区块前先读。** |