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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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/.gitignoreindex 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.mdindex 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 Notesdiff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 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 constraintsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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 integrationdiff --git a/docs/README.md b/docs/README.mdindex 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 integrationdiff --git a/docs/README.zh.md b/docs/README.zh.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.