OrangePi3588Media/AGENTS.md

AGENTS.md

Project Purpose

This repository is a plugin-based C++ video analytics system for RK3588. Development should follow the existing DAG + plugin architecture instead of adding feature-specific shortcuts into the main process.

Build and Verification Constraints

• This repository does not use local cross-compilation in the current workflow.
• Final build, link, runtime verification, and hardware-dependent testing must be executed on the RK3588 target device.
• Do not assume the current workstation can build or run RKNN, RGA, MPP, ZLMediaKit, or full media pipelines.
• Do not run full project builds by default on the current workstation unless the task explicitly requires it and the needed dependencies are confirmed to exist locally.
• Prefer static inspection and targeted platform-independent tests over speculative local builds.
• If a task depends on RK3588-only capabilities, state clearly what was reviewed locally and what still must be verified on the device.
• Do not claim that a hardware-related change is verified unless it was actually built and exercised on RK3588.

Local Development Expectations

• Local work should focus on architecture, plugin boundaries, data structures, configuration, documentation, code review, and platform-independent tests.
• Local build attempts are allowed only when they are clearly useful and do not depend on missing RK3588 runtime libraries or device-only features.
• If local compilation is attempted, keep it scoped to the smallest useful target.
• Do not distort production code to satisfy the local machine environment.
• Do not remove or weaken RK3588-specific paths just because they are not runnable on the current workstation.

Shell Environment Rules

• For agent-run shell commands on this workstation, use PowerShell 7.6 instead of Windows PowerShell 5.1.
• Prefer explicit invocation via C:\Program Files\WindowsApps\Microsoft.PowerShell_7.6.0.0_x64__8wekyb3d8bbwe\pwsh.exe when running commands.
• Do not rely on the system-default powershell.exe resolving to the desired version.

Plugin and Architecture Rules

• New analytics capabilities should be implemented as plugins when they represent pipeline nodes.
• Reuse existing shared frame metadata and plugin interfaces where possible.
• If a new feature introduces a new semantic output type, define an explicit data model instead of encoding it into unrelated existing fields.
• Keep node responsibilities narrow. Detection, tracking, event reasoning, visualization, and alarming should remain separated unless there is a strong architectural reason not to.

Testing and Validation Rules

• Prefer targeted unit tests for platform-independent logic.
• For RK3588-only features, document a device-side validation checklist instead of pretending local validation is sufficient.
• When a test or build cannot run locally because of platform constraints, say so explicitly in the final report.
• Separate validation into two buckets:
  • local code-level validation
  • RK3588 device-side validation
• Do not merge those two buckets into a single vague statement such as "verified" or "tested" without saying where verification happened.

Communication Rules for Agents

• Say what is known from code inspection versus what still requires RK3588 device verification.
• Favor root-cause fixes over environment-specific patches.
• Keep recommendations aligned with the shortest path that preserves the architecture.