From fa1cd11fc9b3fe46b771357e898e3c82ff4cb9db Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:19:18 +0900 Subject: [PATCH 1/8] docs: agent found dependencies missing in local but don't know how to fix --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 64ed8efcd..cdcc89301 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,10 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. +## Local Coding Environment +* Run `pnpm install` if dependencies are absent, invalid or stale. +* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. + ## Route the task before acting | Before you… | Read | From 6aadf84916699f12e1a4739ca145944542306928 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:26:20 +0900 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=84=20=E7=BB=9F=E4=B8=80=E6=9C=AC?= =?UTF-8?q?=E5=9C=B0=E4=BE=9D=E8=B5=96=E5=AE=89=E8=A3=85=E6=8C=87=E5=BC=95?= =?UTF-8?q?=E4=B8=8E=E9=A1=B9=E7=9B=AE=E8=84=9A=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cdcc89301..c38853b3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ duplicating its rules. ## Local Coding Environment * Run `pnpm install` if dependencies are absent, invalid or stale. -* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. +* Run `pnpm run test:e2e:install` if Playwright Chromium is absent or stale. ## Route the task before acting From 10a82064035263fccb4acde0bf603dfcefd9060c Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:36:44 +0900 Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=93=84=20clarify=20agent=20dependency?= =?UTF-8?q?=20setup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cdcc89301..dd681e0d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,21 @@ separate contract. Use [`docs/README.md`](docs/README.md) as the index and follo duplicating its rules. ## Local Coding Environment -* Run `pnpm install` if dependencies are absent, invalid or stale. -* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. + +Before running project commands, make sure the local prerequisites are ready. Treat these as environment +setup steps, not as reasons to change product code: + +1. If `node_modules` is missing or dependencies are invalid or stale, run `pnpm install`. Use the package + manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local + setup. +2. If an end-to-end test reports that the Playwright browser is missing or unusable, run + `pnpm run test:e2e:install` after dependency installation. This is a separate prerequisite from + `pnpm install` and is safe to rerun. +3. Retry the original command after setup. If setup is blocked by network, permission, or tool availability, + report the setup command and relevant error as an environment blocker; do not alter the lockfile or hide the + failure with a workaround. + +The complete command list and test mechanics are owned by [`docs/develop.md`](docs/develop.md). ## Route the task before acting From a99b53485c43f2dad15b78b199150e10d9837bce Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:48:50 +0900 Subject: [PATCH 4/8] =?UTF-8?q?=F0=9F=93=84=20split=20agent=20environment?= =?UTF-8?q?=20recovery=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 27 +++++++++++---------------- docs/develop.md | 13 +++++++++++++ 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dd681e0d5..1f28404f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,22 +5,17 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. -## Local Coding Environment - -Before running project commands, make sure the local prerequisites are ready. Treat these as environment -setup steps, not as reasons to change product code: - -1. If `node_modules` is missing or dependencies are invalid or stale, run `pnpm install`. Use the package - manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local - setup. -2. If an end-to-end test reports that the Playwright browser is missing or unusable, run - `pnpm run test:e2e:install` after dependency installation. This is a separate prerequisite from - `pnpm install` and is safe to rerun. -3. Retry the original command after setup. If setup is blocked by network, permission, or tool availability, - report the setup command and relevant error as an environment blocker; do not alter the lockfile or hide the - failure with a workaround. - -The complete command list and test mechanics are owned by [`docs/develop.md`](docs/develop.md). +## Environment Setup and Recovery + +Before running project commands, resolve missing prerequisites: + +1. Missing, invalid, or stale dependencies: run `pnpm install`. +2. Missing or unusable Playwright Chromium: after dependency installation, run `pnpm run test:e2e:install`. +3. Retry the original command. If setup is blocked by network, permission, or tool availability, report it as + an environment blocker instead of changing product code. + +See [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) for the +package-manager, lockfile, and failure-handling boundaries. ## Route the task before acting diff --git a/docs/develop.md b/docs/develop.md index 5696ca0c7..5f6600a27 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -29,6 +29,19 @@ pnpm run check:i18n # translation key parity (see docs/translation. pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, issues/new prefill ids ``` +### Environment Setup and Recovery + +Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change +product code: + +- Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by + this repository; do not switch to npm/yarn or manually add packages to repair a local setup. +- After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that + Playwright Chromium is missing or unusable. The command is safe to rerun. +- Retry the original command after setup. If network, permission, or tool availability blocks setup, report the + exact command and relevant error as an environment blocker; do not alter the lockfile or hide the failure with + a workaround. + No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs `check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript From af20796559c5796b89ea5c644b47e018f1405843 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:53:42 +0900 Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=93=84=20keep=20environment=20recover?= =?UTF-8?q?y=20in=20its=20owner=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1f28404f5..7e8dfe48b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,23 +5,12 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. -## Environment Setup and Recovery - -Before running project commands, resolve missing prerequisites: - -1. Missing, invalid, or stale dependencies: run `pnpm install`. -2. Missing or unusable Playwright Chromium: after dependency installation, run `pnpm run test:e2e:install`. -3. Retry the original command. If setup is blocked by network, permission, or tool availability, report it as - an environment blocker instead of changing product code. - -See [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) for the -package-manager, lockfile, and failure-handling boundaries. - ## Route the task before acting | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | +| recover from missing dependencies or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | review code or a pull request | [`docs/develop.md`](docs/develop.md) + [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules | | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` | | build or modify a page, dialog, or block | [`docs/design.md`](docs/design.md) — Core Constraints apply to every UI change | From a766c885b668deb2b315deb803f1f65c2f9ccca2 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:56:46 +0900 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=93=84=20cover=20package=20manager=20?= =?UTF-8?q?bootstrap=20recovery?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- docs/develop.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7e8dfe48b..fad091feb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ duplicating its rules. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | -| recover from missing dependencies or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | +| recover from package-manager, dependency, or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | review code or a pull request | [`docs/develop.md`](docs/develop.md) + [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules | | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` | | build or modify a page, dialog, or block | [`docs/design.md`](docs/design.md) — Core Constraints apply to every UI change | diff --git a/docs/develop.md b/docs/develop.md index 5f6600a27..7fa0e0924 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -34,6 +34,9 @@ pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change product code: +- If `pnpm` is unavailable, use the repository-declared package manager through Corepack when `corepack` is + available: run `corepack enable`, then `corepack install`, and verify with `pnpm --version`. If Corepack is also + unavailable or setup fails, report the command and error as an environment blocker; do not switch to npm/yarn. - Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local setup. - After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that From 0a6d1df68a2822d7e6e6f0762ac0ea7c1626b27b Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:00:44 +0900 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=93=84=20preserve=20development=20com?= =?UTF-8?q?mand=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 7fa0e0924..8bbf9b099 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -29,6 +29,17 @@ pnpm run check:i18n # translation key parity (see docs/translation. pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, issues/new prefill ids ``` +No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky +pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs +`check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript +are staged, and also runs `pnpm run test:ci` when committing on `main` or `release/*`. + +`check:issue-templates` guards a contract that is invisible in review: GitHub prefills an issue form from +`issues/new?...` query params keyed by **field id**, so renaming or deleting an id silently breaks every link +using it — including links already shipped in installed builds, which keep sending the old param name. + +After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension. + ### Environment Setup and Recovery Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change @@ -45,17 +56,6 @@ product code: exact command and relevant error as an environment blocker; do not alter the lockfile or hide the failure with a workaround. -No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky -pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs -`check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript -are staged, and also runs `pnpm run test:ci` when committing on `main` or `release/*`. - -`check:issue-templates` guards a contract that is invisible in review: GitHub prefills an issue form from -`issues/new?...` query params keyed by **field id**, so renaming or deleting an id silently breaks every link -using it — including links already shipped in installed builds, which keep sending the old param name. - -After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension. - ### External Access (`external_access/` subsystem) External Access — the user-facing "外部接入 / External Access" feature From 9d7a07dd74d7122fa42f0b7f608ec5d675c0371b Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:45:03 +0900 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=93=84=20route=20project=20commands?= =?UTF-8?q?=20to=20development=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + docs/develop.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index fad091feb..0ca329665 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ duplicating its rules. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | +| run project commands | [`docs/develop.md`](docs/develop.md) | | recover from package-manager, dependency, or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | review code or a pull request | [`docs/develop.md`](docs/develop.md) + [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules | | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` | diff --git a/docs/develop.md b/docs/develop.md index 8bbf9b099..091d7ec0e 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -49,7 +49,9 @@ product code: available: run `corepack enable`, then `corepack install`, and verify with `pnpm --version`. If Corepack is also unavailable or setup fails, report the command and error as an environment blocker; do not switch to npm/yarn. - Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by - this repository; do not switch to npm/yarn or manually add packages to repair a local setup. + this repository; do not switch to npm/yarn or manually add packages to repair a local setup. If `pnpm install` + changes `pnpm-lock.yaml`, stop and report the mismatch; do not commit that lockfile change as environment + recovery. - After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that Playwright Chromium is missing or unusable. The command is safe to rerun. - Retry the original command after setup. If network, permission, or tool availability blocks setup, report the