feat: initialize managed portal

managed/people_flow_project/docs/plans/2026-04-07-people-flow-design.md

@@ -0,0 +1,66 @@
+# People Flow Design
+
+## Goal
+
+Build a standalone project under `Documents/人流检测/people_flow_project` that analyzes street videos and produces:
+
+- unique people-flow counts
+- one mutually exclusive age bucket per counted person
+- one mutually exclusive gender bucket per counted person
+- annotated videos plus machine-readable summaries
+
+## Approved Decisions
+
+- Runtime target: Linux with NVIDIA GPU
+- Entry points: both single-video mode and batch-directory mode
+- Count logic: one `track_id` is counted once when it crosses a configured line
+- Age buckets:
+  - `minor`: age `< 18`
+  - `adult`: age `18-59`
+  - `senior`: age `>= 60`
+- Gender buckets:
+  - `male`
+  - `female`
+- Unknown face attributes:
+  - If a counted person does not yield a reliable face result, count that person only in `total_people`
+  - Also increment `unknown_attributes`
+
+## Architecture
+
+The pipeline uses Ultralytics YOLO for person detection and tracking, then DeepFace for face attribute analysis. Person tracking and counting stay separate from attribute inference so the demographic model can be replaced later without touching the counting core.
+
+The application stores votes per `track_id`. When the video finishes, each counted track is resolved to at most one final age bucket and one final gender bucket by majority voting.
+
+## Modules
+
+- `main.py`: CLI parsing and mode dispatch
+- `src/people_flow/config.py`: config loading and overrides
+- `src/people_flow/tracking.py`: track extraction from YOLO results
+- `src/people_flow/counting.py`: line-crossing logic and unique counting
+- `src/people_flow/attributes.py`: DeepFace integration and voting
+- `src/people_flow/io_utils.py`: video, JSON, and CSV output helpers
+- `src/people_flow/pipeline.py`: process orchestration
+
+## Outputs
+
+For each video:
+
+- annotated MP4
+- JSON summary
+
+For batch runs:
+
+- one CSV summary with one row per video
+
+## Error Handling
+
+- Missing dependencies should raise clear installation guidance.
+- If a video cannot be opened, fail that video with a readable error.
+- If face inference fails for a sample, continue processing and treat that sample as unavailable.
+- If no video files are found in batch mode, fail fast with a clear message.
+
+## Limitations
+
+- Age and gender quality depend on clear, sufficiently large faces.
+- Street scenes with strong occlusion, side views, masks, or low light will increase `unknown_attributes` and lower reliability.
+- The default line is a placeholder and should be adjusted per camera view.

managed/people_flow_project/docs/plans/2026-04-07-people-flow-implementation.md

@@ -0,0 +1,128 @@
+# People Flow Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a standalone Python project that counts unique line crossings in street videos and adds track-level age/gender summaries.
+
+**Architecture:** Use Ultralytics YOLO to detect and track persons frame by frame, then run DeepFace on sampled person crops to infer face attributes. Keep counting, tracking, and attribute voting in separate modules so the demographic backend can be swapped later.
+
+**Tech Stack:** Python, Ultralytics YOLO, OpenCV, DeepFace, PyYAML, pandas
+
+---
+
+### Task 1: Scaffold the project
+
+**Files:**
+- Create: `README.md`
+- Create: `requirements.txt`
+- Create: `pyproject.toml`
+- Create: `configs/default_config.yaml`
+- Create: `docs/plans/2026-04-07-people-flow-design.md`
+
+**Step 1: Write the initial files**
+
+Add installation instructions, runtime expectations, and default settings.
+
+**Step 2: Verify structure**
+
+Run: `find . -maxdepth 3 | sed -n '1,120p'`
+Expected: project files and directories exist.
+
+**Step 3: Commit**
+
+This workspace is not a git repository. Skip the commit step unless the user later initializes git here.
+
+### Task 2: Build the CLI and config loader
+
+**Files:**
+- Create: `main.py`
+- Create: `src/people_flow/__init__.py`
+- Create: `src/people_flow/config.py`
+- Create: `src/people_flow/models.py`
+
+**Step 1: Implement argument parsing**
+
+Support `video` and `batch` subcommands, config overrides, output directory selection, and line overrides.
+
+**Step 2: Implement config loading**
+
+Load YAML defaults and merge CLI overrides into typed dataclasses.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall main.py src`
+Expected: compile succeeds without syntax errors.
+
+### Task 3: Implement tracking and counting
+
+**Files:**
+- Create: `src/people_flow/tracking.py`
+- Create: `src/people_flow/counting.py`
+
+**Step 1: Extract tracked `person` detections**
+
+Convert YOLO result objects into simple track observations with `track_id`, bounding box, confidence, and center point.
+
+**Step 2: Implement line-cross counting**
+
+Count one crossing per track by monitoring the sign change of the track center relative to the configured line.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall src`
+Expected: compile succeeds.
+
+### Task 4: Implement attribute voting and output helpers
+
+**Files:**
+- Create: `src/people_flow/attributes.py`
+- Create: `src/people_flow/io_utils.py`
+
+**Step 1: Integrate DeepFace**
+
+Sample person crops, run `age` and `gender` analysis, normalize labels, and store per-track votes.
+
+**Step 2: Implement output helpers**
+
+Write JSON summaries, CSV summaries, and draw overlays onto frames.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall src`
+Expected: compile succeeds.
+
+### Task 5: Implement the processing pipeline
+
+**Files:**
+- Create: `src/people_flow/pipeline.py`
+
+**Step 1: Build the main loop**
+
+Open the video, run YOLO tracking on frames, update counters, sample attributes, draw overlays, and save artifacts.
+
+**Step 2: Build batch mode**
+
+Discover supported video files recursively and run the same pipeline per file, then write `outputs/batch_summary.csv`.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall main.py src`
+Expected: compile succeeds.
+
+### Task 6: Final verification
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Smoke-check the CLI**
+
+Run: `python3 main.py --help`
+Expected: help text shows the `video` and `batch` commands.
+
+**Step 2: Document limitations**
+
+Make sure README notes Python version constraints and face-quality limitations.
+
+**Step 3: Commit**
+
+Skip commit because this workspace is not a git repository.

managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights-design.md

@@ -0,0 +1,17 @@
+# Portable DeepFace Weights Design
+
+**Goal:** Make DeepFace reuse bundled project weights regardless of where the project directory is unpacked.
+
+**Problem:** The current native launcher sets `DEEPFACE_HOME` to a project-local `.deepface` directory. DeepFace then appends its own `.deepface/weights` segment, so runtime lookup becomes `PROJECT_ROOT/.deepface/.deepface/weights`, which bypasses the bundled `weights/deepface` directory and triggers redundant downloads.
+
+**Approach Options:**
+
+1. Copy bundled weights into the current user's default `~/.deepface/weights` directory before startup.
+   This matches DeepFace's default lookup behavior and avoids hard-coded absolute paths. It works whether the project lives under `/home/x/people`, `/home/xiaozheng/people`, or any other directory.
+
+2. Keep using `DEEPFACE_HOME` and reshape the project-local directory tree to match DeepFace's nested expectations.
+   This avoids duplicating files but is more fragile and easier to break when DeepFace internals change.
+
+**Recommendation:** Use option 1. Update the native setup and launcher scripts to sync `weights/deepface/*.h5` into `~/.deepface/weights` and stop overriding `DEEPFACE_HOME`.
+
+**Validation:** Confirm the RTSP process starts without downloading `retinaface.h5`, `age_model_weights.h5`, or `gender_model_weights.h5`, and verify the launcher still works after changing only the project root path.

managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights.md

@@ -0,0 +1,51 @@
+# Portable DeepFace Weights Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the native RTSP bundle reuse bundled DeepFace weights from any unpack location without extra downloads.
+
+**Architecture:** Remove the custom `DEEPFACE_HOME` override from the native runtime path. Before setup and launch, copy the bundled DeepFace weight files from `weights/deepface/` into the current user's default `~/.deepface/weights/` directory so DeepFace resolves them through its own standard path logic.
+
+**Tech Stack:** Bash, DeepFace, native Python virtual environment, offline wheelhouse bundle
+
+---
+
+### Task 1: Fix native setup and launcher paths
+
+**Files:**
+- Modify: `run_rtsp.sh`
+- Modify: `setup_native_venv.sh`
+- Modify: `README_NATIVE.md`
+
+**Step 1: Update `run_rtsp.sh`**
+
+Remove the `DEEPFACE_HOME` override. Create `"$HOME/.deepface/weights"` and copy bundled `.h5` files from `"$PROJECT_ROOT/weights/deepface"` into that directory before starting the Python process.
+
+**Step 2: Update `setup_native_venv.sh`**
+
+After dependency installation, create `"$HOME/.deepface/weights"` and copy bundled `.h5` files into it so the environment is ready before the first run.
+
+**Step 3: Update native documentation**
+
+Explain that bundled weights are staged into `~/.deepface/weights` automatically and that the project path itself can move without breaking the weight lookup.
+
+### Task 2: Sync and verify on the Ubuntu target
+
+**Files:**
+- Modify: remote copies of the files above under `/home/x/people/people_flow_project`
+
+**Step 1: Sync the changed files to `192.168.5.154`**
+
+Copy the updated launcher, setup script, and documentation.
+
+**Step 2: Stage bundled weights into the target user's home directory**
+
+Run the updated setup logic or equivalent copy command and verify `~/.deepface/weights` contains the expected `.h5` files.
+
+**Step 3: Restart RTSP and inspect logs**
+
+Restart the RTSP job and confirm the log no longer shows downloads from `deepface_models/releases`.
+
+**Step 4: Commit**
+
+Skip commit unless explicitly requested by the user.

managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle-design.md

@@ -0,0 +1,81 @@
+# Lightweight Native Bundle Design
+
+**Date:** 2026-04-08
+
+**Goal:** Deliver a lightweight native deployment bundle for Ubuntu 24.04 x86_64 that includes project code, required weights, a single editable RTSP run script, and a small setup path on the target host without bundling a full Python environment in the archive.
+
+## Scope
+
+- Target host: `xiaozheng@192.168.5.154`
+- Target path: `/home/x/people/people_flow_project`
+- Bundle contents:
+  - project code
+  - YOLO weight
+  - DeepFace weights
+  - one editable run script
+  - setup and usage documentation
+- Exclude the virtual environment from the compressed bundle to keep size down.
+
+## Deployment Model
+
+The target host already has:
+
+- Ubuntu 24.04 x86_64
+- Python 3.12
+- Docker available, but Docker is intentionally not used here
+- NVIDIA driver and CUDA-capable GPU
+
+The bundle will therefore rely on:
+
+1. a project-local `.venv` created on the target host
+2. host driver compatibility for GPU wheels
+3. project-relative weight paths so no external downloads are needed
+
+## User Editing Surface
+
+The main operator interface is a single shell script:
+
+- `run_rtsp.sh`
+
+The user edits only:
+
+- `RTSP_URL`
+- `OUTPUT_DIR`
+
+The script activates `.venv`, points to the native x86 config, and runs the RTSP pipeline.
+
+## Config Strategy
+
+Add a dedicated native x86 config file with:
+
+- `yolo.model_path` pointing to the local `weights/yolo11n.pt`
+- RTSP timing settings
+- output defaults for RTSP mode
+
+This avoids modifying the existing Jetson-oriented config and keeps host deployment deterministic.
+
+## Setup Strategy
+
+Provide a small setup script that:
+
+- creates `.venv`
+- upgrades pip/setuptools/wheel
+- installs CUDA-enabled PyTorch wheels
+- installs TensorFlow, `tf-keras`, and application dependencies
+
+The setup script keeps the archive light while still making the target directory self-contained after one install step.
+
+## Bundle Output
+
+On the target host, create a compressed archive such as:
+
+- `/home/x/people/people_flow_project_native_bundle_2026-04-08.tar.gz`
+
+The archive will exclude `.venv` so it stays close to the size of code plus weights.
+
+## Success Criteria
+
+- The target host contains a runnable native project directory
+- `run_rtsp.sh` is the only file the operator needs to edit for RTSP URL and output directory
+- All required weights are present locally
+- The lightweight tarball is created successfully

managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle.md

@@ -0,0 +1,66 @@
+# Lightweight Native Bundle Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Produce a lightweight native deployment bundle for Ubuntu 24.04 x86_64 with code, weights, one editable RTSP run script, and a local venv setup path.
+
+**Architecture:** Keep all code and weights inside the project directory, add one native config and two helper scripts, then create the venv on the target host instead of bundling it into the archive.
+
+**Tech Stack:** Python 3.12, venv, PyTorch GPU wheels, TensorFlow, DeepFace, shell scripts
+
+---
+
+### Task 1: Add native deployment files
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/configs/native_x86_config.yaml`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/run_rtsp.sh`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/setup_native_venv.sh`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README_NATIVE.md`
+
+**Step 1: Add a native x86 config**
+
+- Point YOLO to the local project weight path.
+- Keep RTSP behavior aligned with the current project.
+
+**Step 2: Add a single editable RTSP launcher**
+
+- Put `RTSP_URL` and `OUTPUT_DIR` at the top of the file.
+- Run the project with `.venv/bin/python`.
+
+**Step 3: Add a setup script**
+
+- Create `.venv`
+- Install GPU-enabled PyTorch
+- Install TensorFlow and project requirements
+
+### Task 2: Deploy to the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Sync the updated project**
+
+- Replace the target project directory while preserving weights if needed.
+
+**Step 2: Ensure weights are in project-relative paths**
+
+- Verify YOLO and DeepFace weights under `weights/`.
+
+### Task 3: Validate and bundle
+
+**Files:**
+- No code changes required
+
+**Step 1: Run setup on the target host**
+
+- Execute the setup script.
+
+**Step 2: Validate the RTSP CLI**
+
+- Run `./.venv/bin/python main.py rtsp --help`.
+
+**Step 3: Create the lightweight tarball**
+
+- Exclude `.venv`
+- Keep code, scripts, configs, docs, and weights

managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse-design.md

@@ -0,0 +1,46 @@
+# Offline Wheelhouse Design
+
+**Date:** 2026-04-08
+
+**Goal:** Add an offline Python dependency bundle for Ubuntu 24.04 x86_64 with Python 3.12 and NVIDIA GPU support so the project can be installed on similar machines without re-downloading PyTorch, TensorFlow, and application wheels.
+
+## Scope
+
+- Target platform: Ubuntu 24.04 x86_64
+- Python version: 3.12
+- GPU runtime: NVIDIA, using CUDA-enabled PyTorch wheels
+- Bundle type: project code + weights + `wheelhouse/`
+- Setup behavior: prefer offline wheels when present, fall back to network otherwise
+
+## Approach
+
+Add a dedicated wheelhouse build script that downloads:
+
+- `pip`, `setuptools`, `wheel`
+- `numpy<2`
+- CUDA-enabled `torch` and `torchvision`
+- `tensorflow[and-cuda]==2.16.1`
+- `tf-keras==2.16.0`
+- project requirements and their transitive dependencies
+
+Store the wheels inside `wheelhouse/` under the project root.
+
+Update the native setup script so it:
+
+1. creates `.venv`
+2. upgrades installer tooling from `wheelhouse/` when available
+3. installs PyTorch and TensorFlow from local wheels when available
+4. installs project requirements from local wheels when available
+5. falls back to online indexes only if the wheelhouse is missing
+
+## Bundle Layout
+
+- `weights/`
+- `wheelhouse/`
+- `setup_native_venv.sh`
+- `build_wheelhouse.sh`
+- `run_rtsp.sh`
+
+## Tradeoff
+
+This increases the lightweight bundle size, but it removes repeat dependency downloads on future hosts. The user explicitly asked for an offline dependency pack, so this is the right tradeoff now.

managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse.md

@@ -0,0 +1,51 @@
+# Offline Wheelhouse Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a reusable offline wheelhouse for the native x86 bundle and make setup prefer local wheels.
+
+**Architecture:** Keep the native bundle layout, add one build script that downloads all required wheels into `wheelhouse/`, and update the setup script to install from `wheelhouse/` first.
+
+**Tech Stack:** Python 3.12, pip download, wheelhouse, shell scripts
+
+---
+
+### Task 1: Add offline dependency metadata and scripts
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/requirements-native.txt`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/build_wheelhouse.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/setup_native_venv.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README_NATIVE.md`
+
+**Step 1: Add a native requirements file**
+
+- Pin `numpy<2`
+- Include app-level dependencies used by native setup
+
+**Step 2: Add a wheelhouse build script**
+
+- Download installer tools, PyTorch CUDA wheels, TensorFlow wheels, and project wheels
+- Write everything into `wheelhouse/`
+
+**Step 3: Make setup prefer offline wheels**
+
+- Use `--no-index --find-links wheelhouse` when local wheels are available
+- Fall back to online install otherwise
+
+### Task 2: Sync and build the wheelhouse on the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Sync project changes to `192.168.5.154`**
+
+- Preserve existing weights
+
+**Step 2: Run `build_wheelhouse.sh`**
+
+- Populate `/home/x/people/people_flow_project/wheelhouse`
+
+**Step 3: Validate setup behavior**
+
+- Confirm `setup_native_venv.sh` recognizes local wheelhouse

managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging-design.md

@@ -0,0 +1,31 @@
+# RTSP Heartbeat Logging Design
+
+**Date:** 2026-04-08
+
+**Goal:** Add periodic heartbeat logs to the RTSP pipeline so operators can confirm the stream is still being processed during long 30-minute windows.
+
+## Scope
+
+- Keep the existing RTSP counting behavior unchanged.
+- Print one heartbeat line every 60 seconds while the RTSP loop is running.
+- Include the current demographic counts in the heartbeat output.
+- Do not change JSON payload structure or window timing.
+
+## Heartbeat Format
+
+Each heartbeat line should report:
+
+- runtime seconds
+- current window index
+- current window frame count
+- total people in the active window
+- age counts
+- gender counts
+- unknown attributes
+- last processed timestamp
+
+This output is intended for `tail -f` style monitoring and should remain single-line and compact.
+
+## Approach
+
+Reuse the existing live stats helper to avoid recomputing counting rules in a second place. The RTSP loop already knows when each sampled frame is processed, so it can track the last successful processing timestamp and emit a heartbeat when 60 seconds have elapsed since the last log.

managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging.md

@@ -0,0 +1,47 @@
+# RTSP Heartbeat Logging Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add one-line RTSP heartbeat logs every 60 seconds so operators can monitor progress during long windows.
+
+**Architecture:** Extend the RTSP loop with lightweight heartbeat state. Reuse the existing live stats builder and print one compact log line every 60 seconds after sampled frames are processed.
+
+**Tech Stack:** Python, dataclasses, OpenCV, existing people-flow pipeline
+
+---
+
+### Task 1: Add heartbeat state and log output
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`
+
+**Step 1: Track heartbeat timing**
+
+- Store the process start time.
+- Store the next heartbeat deadline.
+- Store the last successful processed timestamp.
+
+**Step 2: Print one-line heartbeat logs**
+
+- Reuse current live stats.
+- Include runtime, window index, frame count, totals, demographics, unknown count, and last processed timestamp.
+
+**Step 3: Keep the logging cadence stable**
+
+- Emit at most one heartbeat per 60 seconds.
+- Do not log on every frame.
+
+### Task 2: Validate and synchronize
+
+**Files:**
+- No additional files required
+
+**Step 1: Run compile checks**
+
+Run: `python3 -m compileall main.py src`
+Expected: PASS
+
+**Step 2: Sync to remote host**
+
+- Replace the remote project with the updated local copy.
+- Keep the existing remote backup intact.

managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow-design.md

@@ -0,0 +1,116 @@
+# RTSP Windowed People Flow Design
+
+**Date:** 2026-04-08
+
+**Goal:** Extend the existing people-flow project with an RTSP mode that samples one frame per second from a live stream, computes people-flow and demographics, and writes a JSON summary every 30 minutes while preserving the existing offline video and batch modes.
+
+## Scope
+
+- Keep the existing `video` and `batch` commands unchanged.
+- Add a new `rtsp` command for continuous live-stream processing.
+- Sample one frame per second based on wall-clock time instead of processing every decoded frame.
+- Maintain a 30-minute independent counting window.
+- Write one timestamped JSON file per finished window.
+- Refresh a `latest.json` file on every window flush.
+- Do not save annotated RTSP video by default.
+- Back up the current project before implementation.
+
+## Approach
+
+The current codebase already has reusable counting and attribute aggregation logic. The least risky change is to keep the offline pipeline as-is and add a dedicated RTSP processing path that reuses the same `LineCrossCounter` and `AttributeAggregator` components.
+
+The RTSP path will:
+
+1. Open an RTSP stream with OpenCV.
+2. Read frames continuously.
+3. Run inference only when at least one second has elapsed since the last processed frame.
+4. Accumulate counts inside the current 30-minute window.
+5. Flush a window summary to JSON when the window boundary is reached.
+6. Reset all per-window state and continue into the next window.
+7. Retry the stream connection when the RTSP source drops.
+
+## Data Flow
+
+### Command Layer
+
+- `main.py` adds an `rtsp` subcommand with an `--input` RTSP URL.
+- Existing global arguments such as `--config`, `--output-dir`, `--line`, and `--device` remain shared.
+- RTSP mode disables video writing by default unless explicitly enabled in config later.
+
+### Configuration
+
+Add a new RTSP config section with:
+
+- `sample_interval_seconds`
+- `window_seconds`
+- `reconnect_delay_seconds`
+- `stream_open_timeout_seconds`
+- `idle_sleep_seconds`
+- `output_subdir`
+
+This keeps timing and output behavior configurable without changing code.
+
+### Processing Loop
+
+Each processed frame will:
+
+1. Pass through YOLO tracking.
+2. Extract `person` track observations.
+3. Optionally run DeepFace sampling on eligible tracks.
+4. Update the line-cross counter.
+5. Check whether the active 30-minute window should be flushed.
+
+Skipped frames are decoded only to keep the stream current; they do not go through YOLO or DeepFace.
+
+### Window Boundaries
+
+Each window starts when the RTSP pipeline starts or right after the previous flush. The summary payload includes:
+
+- `source_type`
+- `source`
+- `window_index`
+- `window_start`
+- `window_end`
+- `window_duration_seconds`
+- `total_people`
+- `age_counts`
+- `gender_counts`
+- `unknown_attributes`
+- `tracks`
+
+After flushing:
+
+- The timestamped JSON is written under `windows/`.
+- `latest.json` is overwritten with the same payload.
+- The counting and attribute state is reset.
+
+## Output Layout
+
+For `--output-dir /path/output`, the RTSP outputs live under:
+
+- `/path/output/rtsp_stream/`
+- `/path/output/rtsp_stream/latest.json`
+- `/path/output/rtsp_stream/windows/stats_YYYY-MM-DD_HH-MM-SS.json`
+
+The timestamp in the filename is the window end time.
+
+## Error Handling
+
+- If the RTSP stream cannot be opened, retry after a configurable delay.
+- If frame reads fail mid-stream, release the capture and reconnect.
+- If DeepFace analysis fails on a crop, treat that sample as unknown and keep running.
+- If a window has zero crossings, still write a valid JSON payload with zero counts so downstream consumers can distinguish inactivity from pipeline failure.
+
+## Compatibility
+
+- `video` mode still writes annotated video and a final JSON after full processing.
+- `batch` mode still writes a final CSV summary.
+- Existing config keys remain valid.
+
+## Testing Strategy
+
+- Validate CLI parsing for the new `rtsp` command.
+- Validate config loading with the new RTSP section.
+- Validate that RTSP mode writes windowed JSON payloads and refreshes `latest.json`.
+- Validate that 30-minute windows reset counts instead of accumulating indefinitely.
+- Keep offline mode behavior intact by running `--help` and Python compile checks.

managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow.md

@@ -0,0 +1,131 @@
+# RTSP Windowed People Flow Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add an RTSP mode that samples one frame per second, emits independent 30-minute JSON summaries, and preserves the existing offline video and batch workflows.
+
+**Architecture:** Keep the existing offline pipeline untouched and add a dedicated RTSP pipeline path that reuses the counting and attribute aggregation components. Introduce a small RTSP configuration model and window-summary writer so the stream loop can reconnect, flush windowed JSON files, and reset state cleanly.
+
+**Tech Stack:** Python, OpenCV, Ultralytics YOLO, DeepFace, PyYAML, dataclasses
+
+---
+
+### Task 1: Add RTSP configuration models
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/models.py`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/config.py`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/configs/default_config.yaml`
+
+**Step 1: Add an RTSP config dataclass**
+
+- Add a dataclass with interval, window duration, reconnect delay, idle sleep, and output subdirectory fields.
+- Attach it to `AppConfig`.
+
+**Step 2: Load RTSP config from YAML**
+
+- Update config loading to parse the new section.
+- Keep backward compatibility when the section is absent.
+
+**Step 3: Set sensible defaults in YAML**
+
+- Add `sample_interval_seconds: 1`
+- Add `window_seconds: 1800`
+- Add reconnect and idle sleep defaults.
+
+**Step 4: Run a compile check**
+
+Run: `python3 -m compileall main.py src`
+Expected: PASS
+
+### Task 2: Add the RTSP CLI entrypoint
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/main.py`
+
+**Step 1: Add a new `rtsp` subcommand**
+
+- Accept `--input` as the RTSP URL.
+- Reuse global config and output arguments.
+
+**Step 2: Wire the command to the pipeline**
+
+- Call a new `process_rtsp()` method.
+- Print the output directory and latest JSON path once the command starts.
+
+**Step 3: Verify CLI help**
+
+Run: `python3 main.py rtsp --help`
+Expected: PASS and shows the RTSP input argument.
+
+### Task 3: Implement the RTSP processing loop
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/io_utils.py`
+
+**Step 1: Add RTSP output helpers**
+
+- Add a helper that creates `/rtsp_stream/windows`.
+- Add a helper that writes a timestamped JSON file and refreshes `latest.json`.
+
+**Step 2: Add RTSP window summary generation**
+
+- Reuse the existing summary-building logic, but parameterize it with `source`, `window_start`, and `window_end`.
+- Keep the same count keys and track payload structure.
+
+**Step 3: Add `process_rtsp()`**
+
+- Open the RTSP stream with OpenCV.
+- Reconnect on open/read failures after a delay.
+- Sample one frame per second based on wall-clock time.
+- Reuse YOLO tracking, crossing detection, and DeepFace aggregation on sampled frames only.
+- Flush a JSON summary every 30 minutes.
+- Reset counting and attribute state after each flush.
+
+**Step 4: Keep long-running behavior explicit**
+
+- Do not save annotated RTSP video by default.
+- Ensure zero-count windows still emit JSON.
+
+### Task 4: Preserve offline behavior
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`
+
+**Step 1: Refactor only shared summary code**
+
+- Extract helper methods where useful.
+- Do not change the existing `video`/`batch` outputs or file naming.
+
+**Step 2: Re-run offline CLI smoke tests**
+
+Run: `python3 main.py --help`
+Expected: PASS
+
+Run: `python3 main.py video --help`
+Expected: PASS
+
+Run: `python3 main.py batch --help`
+Expected: PASS
+
+### Task 5: Update docs and validate
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README.md`
+
+**Step 1: Document the new RTSP mode**
+
+- Add example commands.
+- Explain the 1 FPS sampling and 30-minute window JSON behavior.
+
+**Step 2: Run final validation**
+
+Run: `python3 -m compileall main.py src`
+Expected: PASS
+
+Run: `python3 main.py rtsp --help`
+Expected: PASS
+
+Run: `python3 main.py --help`
+Expected: PASS

managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration-design.md

@@ -0,0 +1,79 @@
+# x86 Docker Migration Design
+
+**Date:** 2026-04-08
+
+**Goal:** Package the RTSP people-flow project for direct use on an Ubuntu 24.04 x86_64 host with an NVIDIA RTX 3080 by using Docker, bundled project files, and host-side model weights.
+
+## Scope
+
+- Target host: `xiaozheng@192.168.5.154`
+- Target path: `/home/x/people`
+- Runtime model: Docker with NVIDIA runtime
+- Input source: RTSP
+- Output: JSON window summaries under a mounted host directory
+- Include required model weights on the target host
+
+## Why Docker
+
+The existing remote runtime was built on Jetson ARM64 and cannot be reused on an x86_64 RTX 3080 machine. The target host only has Python 3.12 installed, and a native port would need additional interpreter and CUDA-specific package work. Docker is the most reliable path because it isolates Python dependencies, preserves a reproducible runtime, and matches the user requirement of direct use on a new CUDA-capable machine.
+
+## Packaging Strategy
+
+### Host Layout
+
+The target host will contain:
+
+- `/home/x/people/people_flow_project/`
+- `/home/x/people/people_flow_project/weights/yolo11n.pt`
+- `/home/x/people/people_flow_project/weights/deepface/age_model_weights.h5`
+- `/home/x/people/people_flow_project/weights/deepface/gender_model_weights.h5`
+- `/home/x/people/people_flow_project/weights/deepface/retinaface.h5`
+- `/home/x/people/output/`
+
+### Container Layout
+
+The container will:
+
+- run on Python 3.12
+- install GPU-enabled PyTorch wheels
+- install the application dependencies
+- read YOLO and DeepFace weights from deterministic in-container paths
+- write outputs to a mounted host output directory
+
+The project source will be copied into the image at build time. The host-side `weights/` directory will also be part of the build context so the final image does not need to download weights on first start.
+
+## Runtime Contract
+
+The image is intended to be built once on the target host and then started with a single `docker run` command using `--gpus all`.
+
+The container command will remain the existing CLI:
+
+`python main.py --config ... --output-dir ... --device cuda:0 rtsp --input ...`
+
+## System Adaptation
+
+The target host already has:
+
+- Ubuntu 24.04
+- Docker installed
+- NVIDIA runtime registered in Docker
+
+The adaptation work is therefore limited to:
+
+- adding the project’s Docker packaging files
+- transferring project code and model weights
+- building the image on the target host
+- validating the container entrypoint and GPU runtime path
+
+## Risks
+
+- The target GPU is currently heavily occupied by another process, so a full inference validation may need to avoid competing for memory.
+- DeepFace and TensorFlow increase image size and build time.
+- Network access is required during image build unless a wheel cache is prepared separately.
+
+## Success Criteria
+
+- The target host contains the project and all required weights under `/home/x/people`
+- `docker build` completes successfully
+- The container can run `main.py rtsp --help`
+- The final run command is documented for direct RTSP use

managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration.md

@@ -0,0 +1,77 @@
+# x86 Docker Migration Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the RTSP people-flow project directly usable on Ubuntu 24.04 x86_64 with an RTX 3080 by transferring code and weights and building a Docker image on the target host.
+
+**Architecture:** Use a Docker-based runtime for Python 3.12, GPU-enabled PyTorch, DeepFace, and the existing project CLI. Keep weights in a deterministic project directory and bake them into the image during build so runtime startup does not trigger downloads.
+
+**Tech Stack:** Docker, NVIDIA Container Runtime, Python 3.12, PyTorch, Ultralytics, DeepFace
+
+---
+
+### Task 1: Add Docker packaging files
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/Dockerfile`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/docker-compose.yml`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/.dockerignore`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/scripts/run_rtsp_docker.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README.md`
+
+**Step 1: Define the image build**
+
+- Base the image on Python 3.12.
+- Install required OS packages for OpenCV and ffmpeg.
+- Install GPU-enabled PyTorch and project dependencies.
+- Copy project source and weights into the image.
+
+**Step 2: Add a Docker run wrapper**
+
+- Provide a shell script that accepts RTSP URL and output directory.
+- Use `--gpus all`.
+
+**Step 3: Update the README**
+
+- Document the Docker build and run commands.
+- Document where weights must live if the host directory is rebuilt.
+
+### Task 2: Prepare the project tree for weights
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/weights/.gitkeep`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/weights/deepface/.gitkeep`
+
+**Step 1: Create weight directories**
+
+- Reserve stable paths for YOLO and DeepFace weights.
+
+### Task 3: Transfer the project and weights to the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Copy the project**
+
+- Transfer the project directory to `/home/x/people/people_flow_project`.
+
+**Step 2: Copy YOLO and DeepFace weights**
+
+- Place YOLO and DeepFace weights into the target project `weights/` tree.
+
+### Task 4: Build and validate on the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Build the image**
+
+- Run `docker build` under `/home/x/people/people_flow_project`.
+
+**Step 2: Validate the CLI**
+
+- Run the container with `python main.py rtsp --help`.
+
+**Step 3: Provide the final RTSP run command**
+
+- Document the exact `docker run` invocation for the target host.