Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

docs: agent-ready onboarding — skills, contributing guide, entry-file consolidation

luolei897545ae88da
diff --git a/.claude/skills/add-stats-dimension/SKILL.md b/.claude/skills/add-stats-dimension/SKILL.md
new file mode 100644
index 0000000..5cbb18d
--- /dev/null
+++ b/.claude/skills/add-stats-dimension/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: add-stats-dimension
+description: Checklist for adding or changing a statistics table/dimension in the collector. Use whenever touching SQLite schema, traffic write paths, retention, ClickHouse parity, or stats query APIs — several places must change together or data silently drifts.
+---
+
+# Add / Change a Stats Dimension
+
+The stats pipeline has one write implementation but several coupled registries. Missing any step below produces silent data loss or drift — none of it fails loudly. Work through the checklist in order.
+
+## 1. Schema (single source of truth)
+
+- Add the `CREATE TABLE` / `CREATE INDEX` statements to `apps/collector/src/database/schema.ts` (`SCHEMA` + `INDEXES`). Nothing else creates tables.
+- Existing databases only get `IF NOT EXISTS` DDL from schema.ts. Column additions and index drops need an explicit migration in `apps/collector/src/modules/db/db.ts` `init()` (see the `ALTER TABLE ... ADD COLUMN` and `DROP INDEX IF EXISTS` precedents there).
+- Do NOT add expression indexes on `(total_download + total_upload)` — hot queries filter by `backend_id` first, so the planner never uses them (verified with EXPLAIN QUERY PLAN); they only amplify writes.
+
+## 2. Write path (exactly one)
+
+- All traffic writes go through `batchUpdateTrafficStats` in `apps/collector/src/database/repositories/traffic-writer.repository.ts`. `updateTrafficStats` is a thin wrapper over it — never add a second write implementation.
+- Add your aggregation map in the batch loop and the upsert in the appropriate transaction group. The whole flush is one outer transaction; keep it that way (a partial commit + buffer retry double-counts).
+- CSV-style association columns (`ips`, `rules`, `chains`, `domains`) must dedupe with the delimiter-aware pattern — bare `INSTR(list, value)` treats `a.com` as present when `aa.com` is:
+
+```sql
+INSTR(',' || col || ',', ',' || @value || ',') > 0
+```
+
+- Respect `reduceWrites` semantics: detail tables are skipped when ClickHouse is the read source (`shouldReduceSqliteWrites` in `modules/stats/stats-write-mode.ts`). Decide whether your table is "core" (always written) or "detail" (skippable) and place it in the matching branch.
+
+## 3. Rule naming contract (if the dimension involves rules)
+
+- Rule stats key on the **top-level policy group** (last chain hop) for multi-hop chains — `buildRuleName` in `src/shared/utils/rule-name.ts` is the only place this logic lives. The frontend matches these names against gateway rule targets (`rule.proxy`), so changing the key breaks the flow graph and rule matching (this regressed once in v1.3.9; see `docs/dev/deep-review-2026-07.md`).
+
+## 4. Retention
+
+- Register cleanup in `apps/collector/src/modules/cleanup/cleanup.service.ts` + `config.repository.ts`. Minute-level tables follow `connectionLogsDays` (default 7d); hourly tables follow `hourlyStatsDays` (default 30d). `hourly_dim_stats` backs all >6h range queries — never tie it to the minute cutoff.
+- Cumulative `*_stats` tables currently have no retention; if your table is a cross-product (rule×ip style), consider a `last_seen`-based cap from day one.
+
+## 5. Backend deletion
+
+- Add the table to the explicit delete list in `deleteBackendData` (`apps/collector/src/database/repositories/backend.repository.ts`). `PRAGMA foreign_keys` is OFF, so the declared `ON DELETE CASCADE` never fires — forgetting this leaves orphan rows forever.
+
+## 6. ClickHouse parity (if the data is queryable over ranges)
+
+- Writer: `apps/collector/src/modules/clickhouse/clickhouse.writer.ts`
+- Reader: `apps/collector/src/modules/clickhouse/clickhouse.reader.ts` — the SQLite and CH implementations of the same query must return the same shape and semantics (time format, windows). Routing lives in `modules/stats/stats.service.ts` (`*WithRouting` methods).
+
+## 7. Types and API
+
+- Shared response types go in `packages/shared` (both apps consume them; never fork the type locally).
+- Time keys are UTC ISO slices: minute `YYYY-MM-DDTHH:MM:00`, hour `YYYY-MM-DDTHH:00:00` (`toMinuteKey`/`toHourKey` in `base.repository.ts`). Don't introduce local-time keys.
+
+## 8. Tests
+
+- Add a Vitest case in `apps/collector` exercising the batch write + read-back (see `traffic-writer.test.ts` for patterns, `src/__tests__/helpers.ts` for DB setup), then run the `verify-changes` skill.
diff --git a/.claude/skills/agent-probe-dev/SKILL.md b/.claude/skills/agent-probe-dev/SKILL.md
new file mode 100644
index 0000000..3c4b421
--- /dev/null
+++ b/.claude/skills/agent-probe-dev/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: agent-probe-dev
+description: Develop, test and ship the Go agent probe (apps/agent) — build/test commands, protocol versioning, the nekoagent service wrapper, and constraints of router environments (OpenWrt/tmpfs). Use for any change under apps/agent.
+---
+
+# Agent Probe Development (apps/agent)
+
+The agent is a Go binary deployed on routers/servers. It polls the local gateway (mihomo/Surge) and reports to the collector over **HTTP** (gzip JSON POST to `/api/agent/report|heartbeat|config|policy-state`) — not WebSocket.
+
+## Layout
+
+- `main.go` — entrypoint, flag parsing
+- `internal/agent/runner.go` — main loop: report/heartbeat/config-sync tickers, pending queue, retry batch
+- `internal/gateway/` — mihomo & Surge API clients
+- `internal/config/config.go` — flags, `AgentProtocolVersion`
+- `nekoagent` — POSIX-sh service manager wrapper (install/upgrade/systemd/procd/launchd)
+- `install.sh` — curl-pipe installer
+
+## Verify
+
+```bash
+cd apps/agent
+go vet ./... && go build ./... && go test ./...
+sh -n nekoagent && sh -n install.sh # shell syntax gate — both scripts must parse with POSIX sh
+```
+
+## Hard rules
+
+1. **Protocol versioning.** Payload shape changes require bumping `AgentProtocolVersion` (Go) AND the collector's minimum accepted version (agent auth in `apps/collector/src/modules/app/app.ts`); the collector rejects too-old agents with HTTP 426 + structured error. The Go structs and the collector's TS payload types are mirrored by hand — change both sides in one commit.
+2. **Data-loss protections are contracts:** single in-flight retry batch, `requestId` idempotency dedup, counter-regression handling (gateway restart counts current value as new traffic), bounded pending queue with `dropped` accounting. Don't weaken these when refactoring the loop.
+3. **Router constraints.** Target environments include OpenWrt/BusyBox: `nekoagent` must stay POSIX sh (no bashisms), `/tmp` is tmpfs (RAM) — clean up temp dirs (accumulate EXIT traps, don't overwrite them), and network calls in shell must carry timeouts + retries (`curl --connect-timeout 10 --max-time 120 --retry 3`).
+4. **Self-replacement.** Never overwrite a running script/binary in place — download to a sibling `.tmp`/`.new` path and `mv` (same-filesystem rename) so the running inode survives.
+5. **Service management.** systemd unit: `StartLimitIntervalSec/Burst` belong in `[Unit]`, not `[Service]`. procd (OpenWrt) respawn has a finite retry budget — treat "cannot start" as exit non-zero so supervisors behave correctly.
+
+## Release
+
+Tag-driven, independent from the main product: `git tag agent-vX.Y.Z && git push origin agent-vX.Y.Z` → `.github/workflows/agent-release.yml` publishes multi-arch binaries (~1 min). The binary version comes from the tag via ldflags — no version file. Full flow: `docs/agent/release.en.md`.
+
+Known deferred issues and their context live in `docs/dev/deep-review-2026-07.md` (agent P0/P1 section) — check it before starting a fix batch so related items ship together.
diff --git a/.claude/skills/db-conventions/SKILL.md b/.claude/skills/db-conventions/SKILL.md
new file mode 100644
index 0000000..9efc4f5
--- /dev/null
+++ b/.claude/skills/db-conventions/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: db-conventions
+description: Data-layer invariants for the collector — SQLite patterns, transactions, time keys, backendId isolation, ClickHouse read/write topology. Use when writing queries, touching repositories, or debugging data drift.
+---
+
+# Data Layer Conventions (apps/collector)
+
+## Invariants (breaking any of these has bitten us before)
+
+1. **One write path.** All traffic stats go through `batchUpdateTrafficStats` (`database/repositories/traffic-writer.repository.ts`); the whole flush is a single outer transaction (inner `db.transaction()` calls degrade to savepoints). Never commit table groups independently — a mid-flush failure plus buffer retry double-counts.
+2. **Rule name = policy group.** For multi-hop chains the aggregation key is the last chain hop (the user's policy group), produced only by `buildRuleName` (`shared/utils/rule-name.ts`). Rule type + payload (`RuleSet(foo)`) is the key only for single-hop DIRECT/REJECT chains. The web flow graph and gateway-rule matching depend on this.
+3. **Delimiter-aware CSV dedup.** Comma-list columns dedupe with `INSTR(',' || col || ',', ',' || @v || ',')` — bare `INSTR` substring-matches (`a.com` inside `aa.com`) and silently drops values. Lists are capped at `LENGTH > 4000`.
+4. **UTC time keys.** Minute `YYYY-MM-DDTHH:MM:00`, hour `YYYY-MM-DDTHH:00:00`, via `toMinuteKey`/`toHourKey` (`base.repository.ts`). No local-time truncation.
+5. **backendId isolation everywhere.** Every stats table, query, and cache key is scoped by `backend_id`. `PRAGMA foreign_keys` is OFF — deleting a backend relies on the explicit table list in `deleteBackendData`; new tables must be added there.
+6. **Range routing.** Range queries route by span in `resolveFactTable` (`base.repository.ts`): ≤6h → `minute_dim_stats`, >6h → `hourly_dim_stats`. Retention must respect this: hourly dim tables follow `hourlyStatsDays`, minute tables follow `connectionLogsDays`.
+
+## SQLite usage
+
+- better-sqlite3, synchronous — long scans and big transactions block the event loop shared with WS ingest. Cap query result sets (`LIMIT`), use `Map` merges instead of nested `findIndex`, and prefer prepared statements cached on the instance for hot paths.
+- WAL mode with tuned pragmas is set in `modules/db/db.ts` `init()` (env-tunable: `SQLITE_CACHE_MB`, `SQLITE_WAL_AUTOCHECKPOINT_PAGES`, `SQLITE_BUSY_TIMEOUT_MS`).
+- Migrations are ad-hoc in `init()` — idempotent (`IF NOT EXISTS` / try-catch ALTER / app_config flags for one-time data migrations, see `database/rule-name-cleanup.ts` as the reference pattern).
+
+## ClickHouse topology
+
+Read/write behavior is controlled by env flags — keep them coherent:
+
+| Flag | Meaning |
+|---|---|
+| `CH_WRITE_ENABLED` | Write traffic batches to ClickHouse |
+| `STATS_QUERY_SOURCE` | `sqlite` (default) / `clickhouse` / `auto` — read routing |
+| `CH_ONLY_MODE=1` | Skip SQLite stats writes entirely (requires healthy CH writer) |
+| `CH_STRICT_STATS=1` | Fail instead of silently falling back to SQLite reads |
+
+Guard rails already enforced in code (`modules/stats/stats-write-mode.ts`): reduced SQLite writes require reads to actually prefer ClickHouse — don't bypass `shouldReduceSqliteWrites`/`shouldSkipSqliteStatsWrites` with ad-hoc env checks. When adding a range query, implement BOTH the SQLite repository method and the `clickhouse.reader.ts` counterpart with identical semantics, and route via a `*WithRouting` method in `stats.service.ts`.
+
+## Partial-failure contract
+
+`BatchBuffer.flush` returns per-group outcomes (`detailOk`/`aggOk`); the realtime store is only cleared for the groups that durably persisted. When touching flush/clear logic, preserve this contract — it is the data-loss protection added in v1.3.9.
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
new file mode 100644
index 0000000..610f77f
--- /dev/null
+++ b/.claude/skills/release/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: release
+description: Cut and publish a Neko Master release — main product (Docker, v* tags) or Go agent (agent-v* tags). Use when bumping versions, writing CHANGELOG entries, tagging, or verifying CI artifacts.
+---
+
+# Release Process
+
+Two independent release lines, both driven entirely by git tags:
+
+| Line | Tag | CI workflow | Artifact |
+|---|---|---|---|
+| Main product | `vX.Y.Z` | `.github/workflows/docker-build.yml` | Multi-arch Docker image (Docker Hub + GHCR), ~20 min |
+| Agent probe | `agent-vX.Y.Z` | `.github/workflows/agent-release.yml` | Multi-arch agent binaries, ~1 min |
+
+`agent-v*` does not build Docker images. The agent binary version is injected at build time from the tag via ldflags — there is no version file to bump for the agent.
+
+## Main product release
+
+1. **Version**: bump `version` in the **root** `package.json` only (apps/* keep their own independent versions; the root field is the single source of truth).
+2. **Changelog**: add a dated section to BOTH `CHANGELOG.md` (Chinese) and `CHANGELOG.en.md` (English), Keep-a-Changelog style (`## [X.Y.Z] - YYYY-MM-DD`, `### 修复/Fixed`, `### 优化/Changed`). Link issue/PR numbers as reference-style links at the section end. Credit external contributors by handle.
+3. **Env docs**: any new environment variable must be documented in `.env.example` before release.
+4. **Test gates** (all must pass):
+
+```bash
+pnpm --filter @neko-master/collector exec tsc --noEmit
+pnpm --filter @neko-master/collector test
+pnpm --filter @neko-master/web exec tsc --noEmit
+pnpm --filter @neko-master/web exec next build
+```
+
+5. **Ship**:
+
+```bash
+git push origin main
+git tag -a vX.Y.Z -m "<one-line summary>"
+git push origin vX.Y.Z
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "<highlights + upgrade notes>"
+```
+
+6. **Verify CI**: `gh run list --limit 3` → the tag-branch "Build and Push Docker Image" run must end `completed/success`. Multi-arch builds can exceed 20 minutes; poll rather than assume.
+
+## Agent release
+
+See `docs/agent/release.en.md` for full details. Short form:
+
+```bash
+cd apps/agent && go vet ./... && go test ./... && sh -n nekoagent && sh -n install.sh
+git tag agent-vX.Y.Z && git push origin agent-vX.Y.Z
+```
+
+Keep `AgentProtocolVersion` (Go, `internal/config/config.go`) and the collector's minimum accepted protocol version in sync when the payload changes — the collector rejects too-old agents with HTTP 426.
+
+## Conventions
+
+- Also check `docs/release-checklist.md` (pre-release validation for combined product+agent releases).
+- Upgrade notes in the release body must call out any automatic startup migration so operators aren't surprised by one-time log output.
+- Commit messages follow conventional-commit style (`fix(scope): ...`, `release: vX.Y.Z — ...`).
diff --git a/.claude/skills/ui-conventions/SKILL.md b/.claude/skills/ui-conventions/SKILL.md
new file mode 100644
index 0000000..8e6e968
--- /dev/null
+++ b/.claude/skills/ui-conventions/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: ui-conventions
+description: Frontend change conventions for apps/web — i18n (bilingual keys), dark mode (the highest-frequency rework source), theming inline SVG/chart colors, loading/empty/error states. Use for any UI change.
+---
+
+# UI Conventions (apps/web)
+
+## i18n — every user-facing string, both locales
+
+- Framework: `next-intl`, locales `zh` (default) and `en`. Message files: `apps/web/messages/{zh,en}.json` — a key added to one file MUST be added to the other in the same commit.
+- Components use `useTranslations('namespace')`. Never hardcode user-facing strings — including chart tooltips, `title` attributes, and aria-labels (historically the most-missed spots).
+- Utility functions that produce display text (`formatDuration` style) must not embed English words; return structured data and translate in the component.
+
+## Dark mode — check on every visual change
+
+This is the project's highest-frequency rework source. Rules:
+
+1. **Never a lone light class.** Every `bg-*-50/100`, `text-*-500/600`, `border-*-200` needs a `dark:` counterpart. Grep your diff for `bg-white|bg-.*-50|text-gray-` before committing.
+2. **Prefer theme tokens** over palette classes where one exists: `bg-background`, `bg-popover`, `text-muted-foreground`, `border-border` (defined in `app/globals.css` for both themes).
+3. **Inline SVG / chart colors can't use Tailwind** — define both palettes and switch on `resolvedTheme`:
+
+```tsx
+const { resolvedTheme } = useTheme(); // next-themes
+const palette = resolvedTheme === "dark" ? DARK_COLORS : LIGHT_COLORS;
+```
+
+Precedents: `components/features/countries/world-traffic-map.tsx` (MAP_THEME), `components/features/rules/rule-chain-flow.tsx`. Recharts axis ticks should use `fill: "currentColor"` or CSS variables, not hex grays.
+
+4. Badge/status color sets: copy an existing complete set (e.g. the health badge classes in `app/[locale]/dashboard/components/header/index.tsx`) rather than writing light-only classes.
+
+## Three states, always
+
+Every data view needs loading (skeleton), empty, and **error** states. Error must be visible and actionable (retry button) — `return null` on error is a known anti-pattern here (see the chain-flow retry card in `rule-chain-flow.tsx` for the reference implementation). Route-level failures are caught by `app/[locale]/error.tsx` / `app/global-error.tsx`; heavy visualizations should still fail locally, not blank the page.
+
+## Data layer
+
+- Server state via React Query; query keys are centralized in `lib/stats-query-keys.ts` — never inline ad-hoc keys.
+- The stats WebSocket (`lib/websocket.ts`) tags pushes with `backendId` and the hook drops mismatched messages — preserve this when touching the message path (prevents cross-backend cache bleed on backend switch).
+- Custom `memo` comparators must compare **every** prop the component renders from (a missed prop froze the Active Policy whitelist once — include new props in the comparator when you add them).
+
+## Components
+
+- shadcn/ui (`new-york`) + Tailwind v4 + lucide-react. Base primitives in `components/ui/` — reuse before creating; use the Radix `Dialog` for modals (no hand-rolled fixed overlays — they lose Esc/focus-trap behavior).
+- Aesthetic bar: modern SaaS quality; avoid flat "admin panel" layouts. Search and other high-frequency entries should be prominent (icon inside input, clear affordances).
diff --git a/.claude/skills/verify-changes/SKILL.md b/.claude/skills/verify-changes/SKILL.md
new file mode 100644
index 0000000..572289a
--- /dev/null
+++ b/.claude/skills/verify-changes/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: verify-changes
+description: Verify a code change in this repo before committing or opening a PR. Use after editing collector (backend), web (frontend), shared package, or the Go agent — picks the minimal sufficient check set per touched area.
+---
+
+# Verify Changes
+
+Run the smallest check set that covers what you touched. All commands run from the repo root unless noted.
+
+## By touched area
+
+### apps/collector (backend)
+
+```bash
+pnpm --filter @neko-master/collector exec tsc --noEmit
+pnpm --filter @neko-master/collector test
+```
+
+Single test file / case (much faster while iterating):
+
+```bash
+pnpm --filter @neko-master/collector test -- src/modules/auth/auth.service.test.ts
+pnpm --filter @neko-master/collector test -- -t "should validate token format"
+```
+
+Lint (CI-relevant; `console.log` is forbidden in collector source — use `console.info/warn/error`):
+
+```bash
+pnpm --filter @neko-master/collector lint
+```
+
+### apps/web (frontend)
+
+```bash
+pnpm --filter @neko-master/web exec tsc --noEmit
+pnpm --filter @neko-master/web lint
+```
+
+For production-impacting changes (new routes, error boundaries, next.config, i18n files) also run the full build — it catches what tsc alone misses:
+
+```bash
+pnpm --filter @neko-master/web exec next build
+```
+
+### packages/shared
+
+Shared types are consumed by both apps — verify both compile:
+
+```bash
+pnpm --filter @neko-master/shared build
+pnpm --filter @neko-master/collector exec tsc --noEmit
+pnpm --filter @neko-master/web exec tsc --noEmit
+```
+
+### apps/agent (Go probe)
+
+```bash
+cd apps/agent
+go vet ./... && go build ./... && go test ./...
+sh -n nekoagent && sh -n install.sh
+```
+
+## Checklist before commit
+
+- [ ] Checks above pass for every touched area
+- [ ] New behavior has a test (collector uses Vitest; see `src/__tests__/helpers.ts` for `createTestDatabase()` / `createTestBackend()`)
+- [ ] UI changes: both locales translated and dark mode checked (see the `ui-conventions` skill)
+- [ ] DB writes/schema touched: run the `add-stats-dimension` / `db-conventions` checklists
+
+Note: `.husky/pre-push` runs collector `tsc --noEmit` + web `build` when pushing to `main` — running them yourself first avoids a slow failed push.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..d5a56be
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,5 @@
+# Copilot Instructions
+
+All repo guidance lives in [AGENTS.md](../AGENTS.md) — commands, code conventions, key contracts, and the project map. Follow it.
+
+Task-specific workflow guides (plain Markdown, tool-agnostic) are in [`.claude/skills/`](../.claude/skills/): `verify-changes`, `add-stats-dimension`, `release`, `ui-conventions`, `db-conventions`, `agent-probe-dev`. Consult the matching guide before changes to stats/schema, UI, releases, or the Go agent.
diff --git a/.gitignore b/.gitignore
index 06a5c6e..43fe309 100644
--- a/.gitignore
+++ b/.gitignore
@@ -62,5 +62,7 @@ next-env.d.ts
# AI dev logs
.specstory/
-.claude/
+# .claude is ignored except for shared project skills
+.claude/*
+!.claude/skills/
.refactoring_docs/
diff --git a/AGENTS.md b/AGENTS.md
index dcd3037..c4c2c6c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# AGENTS.md
-Guidance for coding agents working in this monorepo.
+Guidance for coding agents working in this monorepo. This file is the single source of truth for agent guidance — `CLAUDE.md` and `.github/copilot-instructions.md` are thin pointers to it.
## Scope and Priorities
@@ -8,6 +8,19 @@ Guidance for coding agents working in this monorepo.
2. Follow direct user instructions over this file when they conflict.
3. Keep changes minimal, targeted, and consistent with existing code.
+## Skills (task-specific workflow guides)
+
+Reusable process checklists live in `.claude/skills/*/SKILL.md` (plain Markdown — usable by any tool; Claude Code loads them automatically). Consult the matching one BEFORE starting these task types:
+
+| Skill | When to use |
+|---|---|
+| [`verify-changes`](./.claude/skills/verify-changes/SKILL.md) | After any edit — minimal check set per touched area |
+| [`add-stats-dimension`](./.claude/skills/add-stats-dimension/SKILL.md) | Any schema / stats-table / write-path change (several registries must change together) |
+| [`release`](./.claude/skills/release/SKILL.md) | Version bumps, CHANGELOG, tagging, CI verification |
+| [`ui-conventions`](./.claude/skills/ui-conventions/SKILL.md) | Any UI change — i18n, dark mode, three-state views |
+| [`db-conventions`](./.claude/skills/db-conventions/SKILL.md) | Queries, repositories, ClickHouse topology, debugging data drift |
+| [`agent-probe-dev`](./.claude/skills/agent-probe-dev/SKILL.md) | Anything under `apps/agent` (Go probe) |
+
## Repository Overview
- Package manager: `pnpm` (workspace monorepo).
@@ -15,9 +28,52 @@ Guidance for coding agents working in this monorepo.
- Main apps:
- `apps/web`: Next.js 16 + React 19 frontend.
- `apps/collector`: Fastify + WebSocket + SQLite backend service.
+ - `apps/agent`: Go probe deployed on routers/servers (reports to the collector over HTTP).
- Shared package:
- `packages/shared`: shared TypeScript types and utility functions.
+## Project Map (key files)
+
+```
+apps/collector/src/
+ database/schema.ts # ALL table/index DDL (single source of truth)
+ database/repositories/
+ traffic-writer.repository.ts # THE traffic write path (batchUpdateTrafficStats)
+ base.repository.ts # time keys, range routing (resolveFactTable), chain parsing
+ rule.repository.ts # rule stats + chain-flow DAG queries
+ backend.repository.ts # backend CRUD + deleteBackendData table list
+ config.repository.ts # retention deletes, app_config
+ shared/utils/rule-name.ts # buildRuleName — the rule naming contract
+ modules/collector/ # gateway WS clients + BatchBuffer (30s flush)
+ modules/realtime/realtime.store.ts # in-memory deltas between flushes
+ modules/websocket/websocket.server.ts # web-client WS: subscriptions, broadcast, backpressure
+ modules/stats/stats.service.ts # SQLite/ClickHouse read routing (*WithRouting)
+ modules/clickhouse/ # CH writer/reader/config (parity with SQLite reads)
+ modules/app/app.ts # Fastify composition root + agent ingest endpoints
+apps/web/
+ lib/api.ts, lib/websocket.ts # HTTP client + stats WS hook (backendId-tagged pushes)
+ lib/stats-query-keys.ts # centralized React Query keys
+ messages/{zh,en}.json # i18n — every key in BOTH files
+ components/features/ # domain components (rules/, countries/, backend/, stats/)
+ app/[locale]/dashboard/ # main dashboard route
+apps/agent/
+ internal/agent/runner.go # main loop, retry/idempotency
+ nekoagent # POSIX-sh service manager (install/upgrade/systemd/procd)
+docs/
+ architecture(.en).md # system architecture
+ agent/ # probe docs (user-facing)
+ dev/ # internal analysis reports (not authoritative)
+```
+
+## Key Contracts (violating these has caused real regressions)
+
+1. **Rule naming**: multi-hop chains aggregate under the top-level policy group (last chain hop); only `buildRuleName` implements this. The web flow graph and gateway-rule matching key on it (regressed in v1.3.9 — see `docs/dev/deep-review-2026-07.md`).
+2. **One traffic write path**: `batchUpdateTrafficStats`, one atomic outer transaction. Never add a parallel write implementation.
+3. **Schema changes are multi-registry**: schema.ts + migration + retention + `deleteBackendData` + ClickHouse writer/reader parity + shared types (checklist: `add-stats-dimension` skill).
+4. **CSV column dedup** uses the delimiter-aware `INSTR(','||col||',', ','||@v||',')` pattern — never bare `INSTR`.
+5. **i18n + dark mode**: every user-facing string in both `messages/{zh,en}.json`; every light-palette Tailwind class has a `dark:` counterpart; inline SVG/chart colors switch on `resolvedTheme`.
+6. **Agent protocol**: payload changes bump `AgentProtocolVersion` (Go) and the collector's minimum in the same commit.
+
## Environment and Toolchain
- Node.js: project docs target Node 22.
@@ -168,14 +224,10 @@ Guidance for coding agents working in this monorepo.
- Frontend-only changes: run web lint; also run web build for production-impacting changes.
- Cross-package changes: run `pnpm lint` and `pnpm build` before final handoff when feasible.
-## Cursor/Copilot Rules Check
+## Related Entry Files
-- Checked for Cursor rules:
- - `.cursor/rules/` -> not found
- - `.cursorrules` -> not found
-- Checked for Copilot instructions:
- - `.github/copilot-instructions.md` -> not found
-- If any of these files are added later, treat them as additional mandatory guidance.
+- `CLAUDE.md` (Claude Code) and `.github/copilot-instructions.md` (Copilot) are thin pointers to this file — keep them that way; add new guidance HERE, not there.
+- No `.cursor/rules/` or `.cursorrules` currently exist; if added later, they must also defer to this file.
## Agent Working Notes
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..675a238
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,12 @@
+# CLAUDE.md
+
+All repo guidance lives in [AGENTS.md](./AGENTS.md) — commands, conventions, key contracts, and the project map. Read it first.
+
+Reusable workflows are packaged as skills in [`.claude/skills/`](./.claude/skills/) (Claude Code loads them automatically):
+
+- `verify-changes` — minimal check set per touched area
+- `add-stats-dimension` — coupled-registry checklist for schema/stats changes
+- `release` — tag-driven release lines (v* Docker / agent-v* binaries)
+- `ui-conventions` — i18n, dark mode, three-state views
+- `db-conventions` — data-layer invariants (SQLite/ClickHouse)
+- `agent-probe-dev` — Go probe development and constraints
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f6a597b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Contributing to Neko Master
+
+**English** | [中文](./CONTRIBUTING.zh.md)
+
+Thanks for contributing! This guide covers the development workflow for humans; if you develop with an AI coding tool (Claude Code, Copilot, Cursor, Codex, ...), point it at [AGENTS.md](./AGENTS.md) — it holds the full conventions, key contracts, and task-specific workflow guides ([`.claude/skills/`](./.claude/skills/)).
+
+## Development setup
+
+- Node.js 22, pnpm; Go 1.22+ only if you touch `apps/agent`.
+
+```bash
+pnpm install
+pnpm dev # starts web (3000) + collector (3001/3002)
+```
+
+Monorepo layout: `apps/web` (Next.js frontend), `apps/collector` (Fastify + SQLite backend), `apps/agent` (Go probe), `packages/shared` (shared types).
+
+## Before you open a PR
+
+Run the checks for the areas you touched (details: [`verify-changes` skill](./.claude/skills/verify-changes/SKILL.md)):
+
+```bash
+pnpm --filter @neko-master/collector exec tsc --noEmit
+pnpm --filter @neko-master/collector test
+pnpm --filter @neko-master/web exec tsc --noEmit
+pnpm --filter @neko-master/web exec next build # for production-impacting web changes
+cd apps/agent && go vet ./... && go test ./... # for agent changes
+```
+
+Requirements:
+
+- **Tests**: new backend behavior needs a Vitest case (helpers in `apps/collector/src/__tests__/helpers.ts`).
+- **i18n**: user-facing strings go through `next-intl` with keys in BOTH `apps/web/messages/zh.json` and `en.json`.
+- **Dark mode**: check every visual change in both themes — light-only Tailwind classes are the most common review comment.
+- **Schema/stats changes**: follow the [`add-stats-dimension`](./.claude/skills/add-stats-dimension/SKILL.md) checklist — several registries must change together.
+- **New env vars**: document them in `.env.example`.
+
+## Commits and PRs
+
+- Conventional-commit style: `fix(collector): ...`, `feat(web): ...`, `docs: ...`.
+- Keep PRs focused; explain the user-visible effect and how you verified it.
+- English for code identifiers, comments, and commit messages; docs are bilingual where a `.zh.md` counterpart exists.
+
+## Releases (maintainers)
+
+Tag-driven: `vX.Y.Z` builds Docker images, `agent-vX.Y.Z` builds agent binaries. Full flow: [`release` skill](./.claude/skills/release/SKILL.md) and [docs/release-checklist.md](./docs/release-checklist.md).
+
+## Reporting issues
+
+Use the issue templates; include your deployment method (Docker/compose), version, gateway type (mihomo/Surge/OpenClash), and relevant collector logs.
diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md
new file mode 100644
index 0000000..89a0a54
--- /dev/null
+++ b/CONTRIBUTING.zh.md
@@ -0,0 +1,50 @@
+# 为 Neko Master 做贡献
+
+[English](./CONTRIBUTING.md) | **中文**
+
+感谢你的贡献!本文面向人类开发者;如果你使用 AI 编码工具(Claude Code、Copilot、Cursor、Codex 等)开发,请让它先读 [AGENTS.md](./AGENTS.md)——完整的规范、关键契约和任务级流程指南([`.claude/skills/`](./.claude/skills/))都在那里。
+
+## 开发环境
+
+- Node.js 22、pnpm;只有改 `apps/agent` 才需要 Go 1.22+。
+
+```bash
+pnpm install
+pnpm dev # 启动 web (3000) + collector (3001/3002)
+```
+
+Monorepo 结构:`apps/web`(Next.js 前端)、`apps/collector`(Fastify + SQLite 后端)、`apps/agent`(Go 探针)、`packages/shared`(共享类型)。
+
+## 提 PR 之前
+
+按改动范围运行检查(详见 [`verify-changes` skill](./.claude/skills/verify-changes/SKILL.md)):
+
+```bash
+pnpm --filter @neko-master/collector exec tsc --noEmit
+pnpm --filter @neko-master/collector test
+pnpm --filter @neko-master/web exec tsc --noEmit
+pnpm --filter @neko-master/web exec next build # 影响生产构建的前端改动
+cd apps/agent && go vet ./... && go test ./... # 探针改动
+```
+
+要求:
+
+- **测试**:后端新行为需要 Vitest 用例(测试工具见 `apps/collector/src/__tests__/helpers.ts`)。
+- **i18n**:所有面向用户的文案走 `next-intl`,key 必须同时加进 `apps/web/messages/zh.json` 和 `en.json`。
+- **暗色模式**:每个视觉改动都要在两种主题下检查——只写亮色 Tailwind class 是最高频的 review 意见。
+- **schema / 统计改动**:按 [`add-stats-dimension`](./.claude/skills/add-stats-dimension/SKILL.md) 清单执行——多处注册点必须同步修改。
+- **新增环境变量**:必须写进 `.env.example`。
+
+## Commit 与 PR
+
+- 约定式提交:`fix(collector): ...`、`feat(web): ...`、`docs: ...`。
+- PR 保持聚焦;说明用户可见的效果和你的验证方式。
+- 代码标识符、注释、commit message 一律英文;有 `.zh.md` 对应文件的文档保持双语。
+
+## 发版(维护者)
+
+由 tag 驱动:`vX.Y.Z` 构建 Docker 镜像,`agent-vX.Y.Z` 构建探针二进制。完整流程见 [`release` skill](./.claude/skills/release/SKILL.md) 与 [docs/release-checklist.md](./docs/release-checklist.md)。
+
+## 反馈问题
+
+使用 issue 模板;请附上部署方式(Docker/compose)、版本号、网关类型(mihomo/Surge/OpenClash)和相关 collector 日志。
diff --git a/README.md b/README.md
index bfe9a18..ef6d47f 100644
--- a/README.md
+++ b/README.md
@@ -991,6 +991,10 @@ Contributions are welcome!
- 💡 [Request Feature](https://github.com/foru17/neko-master/issues/new)
- 🔧 [Contribute Code](https://github.com/foru17/neko-master/pulls)
+Before opening a PR, read [CONTRIBUTING.md](./CONTRIBUTING.md) (workflow, checks, i18n/dark-mode requirements).
+
+**Developing with an AI coding tool?** (Claude Code, Copilot, Cursor, Codex, ...) Point it at [AGENTS.md](./AGENTS.md) — conventions, key contracts, and the project map — plus the task-specific workflow guides in [`.claude/skills/`](./.claude/skills/). Claude Code picks both up automatically.
+
## 📄 License
[MIT](LICENSE) © [foru17](https://github.com/foru17)
diff --git a/README.zh.md b/README.zh.md
index 372d492..0edb3a7 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -972,6 +972,18 @@ neko-master/
- **国际化**: next-intl(中/英)
- **部署**: Docker + Docker Compose
+## 🤝 参与贡献
+
+欢迎贡献!
+
+- 🐛 [提交 Bug](https://github.com/foru17/neko-master/issues/new)
+- 💡 [功能建议](https://github.com/foru17/neko-master/issues/new)
+- 🔧 [贡献代码](https://github.com/foru17/neko-master/pulls)
+
+提 PR 前请阅读 [CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md)(开发流程、检查项、i18n/暗色模式要求)。
+
+**使用 AI 编码工具开发?**(Claude Code、Copilot、Cursor、Codex 等)让它先读 [AGENTS.md](./AGENTS.md)——编码规范、关键契约与项目地图——以及 [`.claude/skills/`](./.claude/skills/) 里的任务级流程指南。Claude Code 会自动加载两者。
+
## 📄 许可证
MIT License © 2024 [foru17](https://github.com/foru17)
diff --git a/docs/README.en.md b/docs/README.en.md
index 7f6aae0..0cef1fd 100644
--- a/docs/README.en.md
+++ b/docs/README.en.md
@@ -2,6 +2,12 @@
[中文](./README.zh.md) | **English**
+## For Developers & AI Tools
+
+- [AGENTS.md](../AGENTS.md) — single source of truth for coding conventions, key contracts, and the project map (Claude Code / Copilot entry files point here)
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — development workflow, PR requirements ([中文](../CONTRIBUTING.zh.md))
+- [Skills](../.claude/skills/) — task-specific workflow guides: `verify-changes`, `add-stats-dimension`, `release`, `ui-conventions`, `db-conventions`, `agent-probe-dev`
+
## Architecture
- [System Architecture](./architecture.en.md) — end-to-end architecture, data flow, module design, ClickHouse integration
diff --git a/docs/README.md b/docs/README.md
index 7f6aae0..0cef1fd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,6 +2,12 @@
[中文](./README.zh.md) | **English**
+## For Developers & AI Tools
+
+- [AGENTS.md](../AGENTS.md) — single source of truth for coding conventions, key contracts, and the project map (Claude Code / Copilot entry files point here)
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — development workflow, PR requirements ([中文](../CONTRIBUTING.zh.md))
+- [Skills](../.claude/skills/) — task-specific workflow guides: `verify-changes`, `add-stats-dimension`, `release`, `ui-conventions`, `db-conventions`, `agent-probe-dev`
+
## Architecture
- [System Architecture](./architecture.en.md) — end-to-end architecture, data flow, module design, ClickHouse integration
diff --git a/docs/README.zh.md b/docs/README.zh.md
index bbaae01..983df4c 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -2,6 +2,12 @@
**中文** | [English](./README.md)
+## 开发者与 AI 工具
+
+- [AGENTS.md](../AGENTS.md) — 编码规范、关键契约与项目地图的唯一事实源(Claude Code / Copilot 入口文件均指向它)
+- [CONTRIBUTING.zh.md](../CONTRIBUTING.zh.md) — 开发流程与 PR 要求([English](../CONTRIBUTING.md))
+- [Skills](../.claude/skills/) — 任务级流程指南:`verify-changes`、`add-stats-dimension`、`release`、`ui-conventions`、`db-conventions`、`agent-probe-dev`
+
## 架构
- [系统架构](./architecture.md) — 端到端架构、数据流、模块设计、ClickHouse 集成
diff --git a/docs/dev/README.md b/docs/dev/README.md
new file mode 100644
index 0000000..e41d1ef
--- /dev/null
+++ b/docs/dev/README.md
@@ -0,0 +1,8 @@
+# Internal Development Reports
+
+Point-in-time analysis and review documents produced during development. They record the reasoning behind past decisions and known issues — **they are not authoritative documentation** and may describe code that has since changed. For current conventions and contracts, see [AGENTS.md](../../AGENTS.md) and the skills in [`.claude/skills/`](../../.claude/skills/).
+
+| Document | What it is |
+|---|---|
+| [deep-review-2026-07.md](./deep-review-2026-07.md) | Project-wide deep review (architecture / probe / DB / performance / frontend / UX) with P0–P3 findings; source of the v1.3.10 fix batch and the outstanding improvement backlog |
+| clickhouse-*.md, review-refactor-clickhouse-branch.md | Analysis and review series from the ClickHouse integration work |
diff --git a/docs/research/README.md b/docs/research/README.md
new file mode 100644
index 0000000..4d07ff8
--- /dev/null
+++ b/docs/research/README.md
@@ -0,0 +1,3 @@
+# Research Notes
+
+Model/tool evaluation notes written during development. Informational only — not product documentation.
diff --git a/docs/superpowers/README.md b/docs/superpowers/README.md
new file mode 100644
index 0000000..4386eab
--- /dev/null
+++ b/docs/superpowers/README.md
@@ -0,0 +1,3 @@
+# Planning Artifacts
+
+Design specs and implementation plans drafted before building features (e.g. the network diagnostics module). Snapshots of intent at planning time — the shipped implementation may differ. Not authoritative documentation.