yangyl/cold_display_guard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
490b3089d2c4cc7ef060d6ea2365709c2d390590
cold_display_guard/AGENTS.md

9.7 KiB
Raw Blame History

Cold Display Guard Agent Instructions

Repository Snapshot

  • Root purpose: cold-display-guard monitors refrigerated display food batches, tracks dwell time per configured display zone, and records disposal compliance events.
  • Backend: Python 3.11+ package in src/cold_display_guard, using only the standard library for application code.
  • Frontend: Vite + vanilla JavaScript management console in web/.
  • Data/storage: JSONL runtime outputs under logs/ by default; configuration is TOML in config/example.toml.
  • Runtime services:
    • Management API: 127.0.0.1:19080, routes under /api/manage/*.
    • Web console: 127.0.0.1:23000, Vite proxies /api to the management API.
    • Runtime monitor: RTSP frame sampling through ffmpeg, writing events and diagnostics JSONL.
  • Deployment: Docker/Compose files are present; containers mount config/ and logs/, use Asia/Shanghai, and prefer China-accessible package/image mirrors.

Repository Map

  • src/cold_display_guard/engine.py: pure batch state machine and compliance event generation.
  • src/cold_display_guard/models.py: domain dataclasses and observation parsing.
  • src/cold_display_guard/config.py: TOML loading, saving, calibration merge, and path resolution.
  • src/cold_display_guard/manage_api.py: standard-library HTTP management API and RTSP snapshot capture.
  • src/cold_display_guard/main.py: long-running RTSP monitor that connects frame capture, vision detection, engine, and JSONL sinks.
  • src/cold_display_guard/frame_source.py: ffmpeg raw RGB frame capture.
  • src/cold_display_guard/vision.py: heuristic ROI occupancy and trash-motion detection.
  • src/cold_display_guard/cli.py: JSONL observation CLI for deterministic engine processing.
  • web/src/main.js and web/src/styles.css: management console UI.
  • scripts/: local launch scripts for API, web, and runtime services.
  • deploy/, Dockerfile, web/Dockerfile: container deployment artifacts.
  • tests/: unittest coverage for engine, CLI, config, management summary/config behavior, and vision heuristics.
  • docs/plans/, task_plan.md, progress.md, findings.md: existing planning and project-history artifacts.

Core Domain Rules

  • The reliable business unit is a display-zone batch, not an individual food item.
  • Default layout is 2 rows by 4 columns with zone IDs r1c1 through r2c4; layout and polygons are configurable.
  • A batch starts when a zone changes from empty to occupied.
  • A batch ends when a zone changes from occupied to empty.
  • Count decreases keep the same batch active and emit batch_count_changed.
  • Count increases before the zone clears are mixed-batch violations and emit mixed_batch_violation.
  • Removal before max_dwell_seconds emits batch_consumed.
  • Removal at or after max_dwell_seconds emits batch_pending_disposal and waits for trash confirmation.
  • A trash deposit within trash_confirmation_seconds emits batch_discarded.
  • No trash deposit before the deadline emits missing_disposal_violation.
  • Any new occupied zone while an overdue batch is pending disposal emits overdue_return_violation.
  • The current vision layer reports binary 0/1 occupancy per zone; it does not count individual items.
  • The detector learns an empty baseline from the first configured frames. If food is already present at startup, it may become baseline until the image changes.

Change Rules

  • Keep BatchEngine deterministic and free of camera, file, HTTP, subprocess, or wall-clock dependencies.
  • Add or update focused tests when changing business rules, event names, event payloads, observation parsing, config formatting, or path resolution.
  • Keep the observation contract stable: ts, zone_counts, and trash_deposit or trash_deposit_count.
  • If event names or payload shapes change, update engine tests, CLI tests, runtime code, management summary behavior, frontend rendering, and README examples together.
  • Keep ROI and polygon coordinates normalized to 0.0..1.0; clamp or validate inputs at config/API boundaries.
  • Keep manage_api.py as a small standard-library HTTP service unless the user explicitly asks to introduce a web framework.
  • Preserve explicit ffmpeg timeout and error reporting behavior in frame_source.py and snapshot capture.
  • Treat RTSP URLs, camera credentials, captured frames, and logs as sensitive operational data. Do not paste secrets into new docs, commits, or test fixtures.
  • Do not commit generated runtime data such as logs/, captured snapshots, Vite dist/, Python caches, or ad hoc diagnostics.
  • Frontend changes should preserve the current Vite single-page app, /api/manage/* backend contract, and 23000/19080 local development split.
  • Deployment changes must keep README commands, scripts, ports, env vars, compose volumes, Docker health checks, and config paths aligned.
  • Be careful with mirror settings in Dockerfiles; they are intentional for the expected deployment network.

Local Commands

  • Full Python test suite:
    • PYTHONPATH=src python3 -m unittest discover -s tests -v
  • Targeted Python tests:
    • PYTHONPATH=src python3 -m unittest tests/test_engine.py -v
    • PYTHONPATH=src python3 -m unittest tests/test_config.py -v
    • PYTHONPATH=src python3 -m unittest tests/test_manage_api.py -v
    • PYTHONPATH=src python3 -m unittest tests/test_vision.py -v
    • PYTHONPATH=src python3 -m unittest tests/test_cli.py -v
  • Management API:
    • scripts/run_manage_api.sh
    • Health check: curl http://127.0.0.1:19080/api/manage/health
  • Web console:
    • scripts/run_web.sh
    • Build check: cd web && pnpm build
  • Runtime monitor:
    • scripts/run_runtime.sh
    • One-frame smoke test when RTSP and ffmpeg are available: PYTHONPATH=src python3 -m cold_display_guard.main --config config/example.toml --once
  • Compose config check:
    • docker compose --env-file deploy/cold-display-guard.env -f deploy/docker-compose.yml config

Validation Matrix

  • Engine or domain behavior: run the targeted engine/CLI tests first, then the full Python test suite.
  • Config or calibration behavior: run tests/test_config.py, tests/test_manage_api.py, then the full Python test suite.
  • Vision or RTSP capture behavior: run tests/test_vision.py; use the one-frame runtime smoke test only when camera access and ffmpeg are available.
  • Management API changes: run management API tests and, when practical, start scripts/run_manage_api.sh and hit /api/manage/health.
  • Frontend changes: run cd web && pnpm build; if API interactions changed, also run or inspect the management API route behavior.
  • Deployment changes: run the compose config check and verify Dockerfile/package mirror choices, ports, volumes, and health checks.
  • Documentation-only changes: verify the documented paths, commands, ports, and business rules against the current files before reporting completion.

Workflow

  • Read the relevant source and tests before editing; this project has tight coupling between business rules, event payloads, README examples, and UI summaries.
  • Prefer small, surgical changes that preserve the current architecture.
  • For non-trivial work, update or add planning notes in the existing project style (docs/plans/, task_plan.md, progress.md, or findings.md) only when useful for handoff or explicitly requested.
  • Keep the final response grounded in verification evidence: say exactly which commands were run, or say when a validation step was skipped because it requires RTSP, Docker, network, or another external dependency.

Workflow Orchestration

  • Default to a plan-first workflow for any non-trivial task, especially work with 3+ steps or architecture decisions.
  • Write the implementation plan to tasks/todo.md as a checklist before editing, and include verification steps rather than implementation steps alone.
  • Start non-trivial work from a detailed spec so execution ambiguity is reduced before code or document changes begin.
  • If execution diverges from the expected path, stop and re-plan instead of pushing ahead on stale assumptions.
  • Prefer subagents for research, exploration, and parallel analysis whenever that helps keep the main context clean.
  • Keep each subagent focused on a single line of investigation.
  • Do not mark work complete without verification; run the relevant tests, inspect the pertinent logs, and compare before/after behavior when the change affects runtime behavior.
  • For non-trivial changes, pause and assess whether there is a simpler or more elegant design before settling on a fix; avoid both hacky patches and unnecessary over-engineering.
  • Treat bug reports and CI failures as end-to-end fix tasks: investigate logs, error output, and failing tests directly, and close the loop without asking the user for avoidable operational detail.

Task Management

  • Use tasks/todo.md as the default task tracker: write the plan first, verify the plan before implementation, and keep progress updated as checklist items complete.
  • Record a high-level explanation of meaningful changes as the work proceeds.
  • Add and maintain a review/results section in tasks/todo.md so verification outcomes and follow-up findings are captured in the same place as the plan.

Lessons

  • At the start of each session, review any task-relevant entries in tasks/lessons.md before beginning implementation work.
  • After each user correction, update tasks/lessons.md with the mistake pattern and at least one concrete, executable prevention rule.
  • Continue refining those lessons until the failure pattern stops recurring.

Core Principles

  • Simplicity first: prefer the smallest change that fully solves the problem.
  • No laziness: trace issues to root cause and avoid temporary fixes that would fail a senior-engineer review.
  • Minimal impact: only change the code, docs, and configuration that are necessary for the task.