docs: update agent workflow instructions
This commit is contained in:
129
AGENTS.md
Normal file
129
AGENTS.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user