tian 29d9ef5d0d refactor: 项目结构梳理 - 设备端/管理端对称布局

仓库结构:
  edge/     设备端（原根目录设备端代码整体移入）
  control/  管理端（清理后）
  docs/     文档（PRD 移入 design/）
  README.md 根导航（新增）

清理:
- control/.brainstorm 临时草稿删除
- control 根级重复文档(API表/PRD_04)并入 docs/design/
- control/plan.md -> docs/implementation/control-plan.md
- control/safesightd-linux-arm64 二进制取消版本控制(.gitignore)
- edge/transform 模型转换产物归入 models/，onnx/pt 大源文件取消跟踪(.gitignore)
- Readme.md(PRD) -> docs/design/PRD_Product_v1.2.md（避开 README 大小写冲突）

更新:
- 根 README.md 导航、docs/README.md 文档索引
- deployment.md/检查表路径加 edge/ 前缀
- .gitignore 重写（edge/control 分区规则）

2026-08-02 11:39:54 +08:00

3.4 KiB

Raw Blame History

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.

3.4 KiB Raw Blame History