@@ -15,17 +15,9 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work.
15151616## Map
171718-- Core TS: `src/`, `ui/`, `packages/`
19-- Bundled plugins: `extensions/`
20-- Public SDK: `src/plugin-sdk/*`
21-- Channel internals: `src/channels/*`
22-- Plugin loader/contracts: `src/plugins/*`
23-- Gateway protocol: `src/gateway/protocol/*`
24-- Docs: `docs/`
25-- Apps: `apps/`, `Swabble/`
26-- Installers: sibling `../openclaw.ai`
27-28-Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/`, `src/gateway/`, `src/gateway/protocol/`, `src/agents/`, `test/helpers/`, `test/helpers/channels/`, `docs/`, `ui/`, `scripts/`.
18+- Core TS: `src/`, `ui/`, `packages/`; plugins: `extensions/`; SDK: `src/plugin-sdk/*`; channels: `src/channels/*`; loader: `src/plugins/*`; protocol: `src/gateway/protocol/*`; docs/apps: `docs/`, `apps/`, `Swabble/`.
19+- Installers: sibling `../openclaw.ai`.
20+- Scoped guides exist in: `extensions/`, `src/{plugin-sdk,channels,plugins,gateway,gateway/protocol,agents}/`, `test/helpers*/`, `docs/`, `ui/`, `scripts/`.
29213022## Architecture
3123@@ -48,19 +40,14 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/`
48404941- Runtime: Node 22+. Keep Node + Bun paths working.
5042- Install: `pnpm install` (keep Bun lock/patches aligned if touched).
51-- CLI: `pnpm openclaw ...` or `pnpm dev`
52-- Build: `pnpm build`
53-- Smart gate: `pnpm check:changed`; explain with `pnpm changed:lanes --json`; staged preview `pnpm check:changed --staged`.
54-- Prod sweep: `pnpm check` (prod type/lint/guards, no tests).
55-- Tests: `pnpm test`; changed `pnpm test:changed`; serial `pnpm test:serial`; coverage `pnpm test:coverage`.
56-- Extension tests: `pnpm test:extensions` / `pnpm test extensions` / `pnpm test extensions/<id>`.
43+- CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`.
44+- Smart gate: `pnpm check:changed`; explain `pnpm changed:lanes --json`; staged preview `pnpm check:changed --staged`.
45+- Prod sweep: `pnpm check`; tests: `pnpm test`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`.
46+- Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/<id>`.
5747- Targeted tests: `pnpm test <path-or-filter> [vitest args...]`; never raw `vitest`.
58-- Shard timings: `.artifacts/vitest-shard-timings.json`; disable `OPENCLAW_TEST_PROJECTS_TIMINGS=0`.
59-- Format: `pnpm format:check` / `pnpm format`.
60-- Typecheck: `pnpm tsgo`, `pnpm tsgo:prod`, `pnpm check:test-types`/`pnpm tsgo:test`, `pnpm tsgo:all`; profile `pnpm tsgo:profile [...]`.
61-- Type policy: use `tsgo`; do not add `tsc --noEmit`, `typecheck`, `check:types`. `tsc` only for declaration/package-boundary emit gaps.
62-- Lint: `pnpm lint`, `pnpm lint:core`, `pnpm lint:extensions`, `pnpm lint:scripts`, `pnpm lint:apps`, `pnpm lint:all`.
63-- Local heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`.
48+- Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); do not add `tsc --noEmit`, `typecheck`, `check:types`.
49+- Format/lint: `pnpm format:check`/`pnpm format`; `pnpm lint*` lanes.
50+- Heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`.
6451- Local first. Use repo `pnpm` lanes before Blacksmith/Testbox. Remote only for parity-only failures, secrets/services, or explicit ask.
65526653## GitHub / CI
@@ -112,17 +99,13 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/`
11299113100## Tests
114101115-- Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`.
116-- Example models: `sonnet-4.6`, `gpt-5.4`.
102+- Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`; example models `sonnet-4.6`, `gpt-5.4`.
117103- Clean timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` safe.
118-- Hot tests: avoid per-test `vi.resetModules()` + heavy imports. Prefer static/`beforeAll` imports + direct state reset.
119-- Measure first: `pnpm test:perf:imports <file>`, `pnpm test:perf:hotspots --limit N`.
120-- Seam depth: unit-test pure helpers/contracts; one integration smoke per boundary.
121-- Mock expensive seams directly: scanners, manifests, package registries, fs crawls, provider SDKs, network/process launch.
122-- Prefer injection over module mocks; if mocking modules, mock narrow local `*.runtime.ts`, not broad barrels.
123-- Share fixtures/builders. Do not recreate temp/plugin workspaces per case unless isolation needs it.
124-- Delete duplicate assertions. Assert behavior that can regress here.
125-- Avoid broad `importOriginal()` / `openclaw/plugin-sdk/*` partial mocks; add narrow runtime seam.
104+- Hot tests: avoid per-test `vi.resetModules()` + heavy imports. Measure with `pnpm test:perf:imports <file>` / `pnpm test:perf:hotspots --limit N`.
105+- Seam depth: pure helper/contract unit tests; one integration smoke per boundary.
106+- Mock expensive seams directly: scanners, manifests, registries, fs crawls, provider SDKs, network/process launch.
107+- Prefer injection; if module mocking, mock narrow local `*.runtime.ts`, not broad barrels or `openclaw/plugin-sdk/*`.
108+- Share fixtures/builders; delete duplicate assertions; assert behavior that can regress here.
126109- Do not edit baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval.
127110- Test workers max 16. Memory pressure: `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`.
128111- Live: `OPENCLAW_LIVE_TEST=1 pnpm test:live`; verbose `OPENCLAW_LIVE_TEST_QUIET=0`.
@@ -161,17 +144,14 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/`
161144- Before simulator/emulator testing, check real iOS/Android devices.
162145- "restart iOS/Android apps" = rebuild/reinstall/relaunch, not kill/launch.
163146- SwiftUI: Observation (`@Observable`, `@Bindable`) over new `ObservableObject`.
164-- Mac gateway: use app or `openclaw gateway restart/status --deep`; no ad-hoc tmux gateway. Rebuild mac app locally.
165-- Mac logs: `./scripts/clawlog.sh`.
147+- Mac gateway: use app or `openclaw gateway restart/status --deep`; no ad-hoc tmux gateway. Logs: `./scripts/clawlog.sh`.
166148- Version bump touches: `package.json`, `apps/android/app/build.gradle.kts`, `apps/ios/version.json` + `pnpm ios:version:sync`, macOS `Info.plist`, `docs/install/updating.md`. Appcast only for Sparkle release.
167-- iOS Team ID: `security find-identity -p codesigning -v`; fallback `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.
168149- Mobile LAN pairing: plaintext `ws://` loopback-only. Private-network `ws://` needs `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`; Tailscale/public use `wss://` or tunnel.
169150- A2UI hash `src/canvas-host/a2ui/.bundle.hash`: generated; ignore unless running `pnpm canvas:a2ui:bundle`; commit separately.
170151171152## Ops / Footguns
172153173-- Remote install docs: `docs/install/exe-dev.md`, `docs/install/fly.md`, `docs/install/hetzner.md`.
174-- Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`.
154+- Remote install docs: `docs/install/{exe-dev,fly,hetzner}.md`. Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`.
175155- Rebrand/migration/config warnings: run `openclaw doctor`.
176156- Never edit `node_modules`.
177157- Local-only `.agents` ignores: `.git/info/exclude`, not repo `.gitignore`.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。