video-ai-analysis/agent.md

# Video AI Analysis PoC Agent Instructions

本文件约束后续 AI 在 `/Users/yoilun/AI-train/video-ai-analysis-poc` 中的开发、审查、测试和文档维护行为。任何业务代码修改前必须先阅读并遵守本文件。

## Repository Snapshot

- 项目名称：`video-ai-analysis-poc`。
- 项目目录：`/Users/yoilun/AI-train/video-ai-analysis-poc`。
- 项目目标：实现本地视频文件夹离线批处理分析 PoC。
- 外部模型/参考实现目录：`/Users/yoilun/AI-train/zhengxin-vlm-0413`。
- 参考 VLM 模型：`/Users/yoilun/AI-train/zhengxin-vlm-0413/models/memai-zhengxin-v3-20260413`。
- 测试环境：`ssh xiaozheng@192.168.5.100`，用户说明该环境已有模型。
- 运行目标：Ubuntu 24，单机 NVIDIA RTX 3080 20GB，离线批处理优先吞吐而非低延迟。

## Hard Directory Boundary

`video-ai-analysis-poc` 是本次项目目录。后续代码、配置、计划、文档、测试和输出模板都必须放在这里。

`zhengxin-vlm-0413` 不是本次项目目录，只能作为：

- 已有模型目录。
- 参考实现目录。
- VLM API、prompt、输出解析、部署方式的参考。

默认禁止在 `zhengxin-vlm-0413` 中创建本项目文件或修改业务代码。特别禁止改动、移动、删除或复制：

- `zhengxin-vlm-0413/models/**`
- `zhengxin-vlm-0413/service/config.yaml`
- `zhengxin-vlm-0413/service/config.yaml-bk`
- `zhengxin-vlm-0413/docker/.env`

如果后续确实需要从参考项目复制逻辑，必须复制到本项目目录内，并注明来源和差异。

## Repository Map

当前项目文件：

- `video_ai_analysis_system_plan.md`：前期系统实施方案。
- `agent.md`：本文件，约束后续 AI 工作。
- `task_plan.md`：本次 goal 的阶段计划。
- `findings.md`：代码阅读、约束、关键发现。
- `progress.md`：执行记录、测试结果、bug 循环。
- `docs/project.md`：项目目标、架构、配置、运行方式和风险。
- `memories.md`：主 agent 对用户要求和关键决策的长期记忆。

参考目录关键文件：

- `/Users/yoilun/AI-train/zhengxin-vlm-0413/service/rtsp_service.py`：实时 RTSP 服务入口。
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/service/config.yaml`：现有推理、摄像头、prompt、服务、YOLO 配置，包含敏感信息。
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/shared/vlm_client.py`：VLM 请求构建、OpenAI-compatible API 调用、Action 解析。
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/shared/frame_utils.py`：已有本地视频抽帧辅助函数，但不满足本次完整离线批处理需求。
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/docker/docker-compose.yml`：vLLM 与 RTSP 服务容器编排。

## Current Workflow Batch

```text
[项目: /Users/yoilun/AI-train/video-ai-analysis-poc]
[工作流批次: v1.0 本地视频批处理PoC]
```

派发任何子 agent 时，任务首段必须包含：

```text
[项目: /Users/yoilun/AI-train/video-ai-analysis-poc]
[工作流批次: v1.0 本地视频批处理PoC]
[阶段: 阶段 x <阶段名>]
[角色: <角色名>]
[子agent名称: <从指定名单中选择>]
```

子 agent 名称必须从以下列表选择：

```text
huzenan, jiangzhiyou, linjiayu, hujiarui, wangchiheng, niwenhao,
caiziquan, yepeijun, lizheng, zhengchenda, chenruihao, yangyilun, donglele
```

## Required Workflow

### 1. Agent Rules Before Code

在 `agent.md` 未确定前，不允许修改业务代码。

阶段 0 允许修改：

- `agent.md`
- `task_plan.md`
- `findings.md`
- `progress.md`
- `docs/project.md`
- `memories.md`

### 2. File-Based Planning Is Mandatory

非简单任务必须维护：

- `task_plan.md`
- `findings.md`
- `progress.md`
- `docs/project.md`
- `memories.md`

每个阶段开始前，主 agent 必须读取这些文件，确认当前目标和下一步。每个阶段完成后，必须更新阶段状态、验证记录、关键文件和剩余风险。

### 3. Sub Agent Workflow

每个实现阶段至少使用：

- coding agent：只实现当前阶段，不处理未来阶段，不做无关重构。
- testing/review agent：只测试、审查、复现问题和报告 bug，不直接修改代码。

如果 testing/review agent 发现 bug：

1. 主 agent 将 bug report 记录到 `progress.md`。
2. 主 agent 将 bug report 转发给当前阶段 coding agent。
3. coding agent 只修复报告中的问题。
4. testing/review agent 复测。
5. 同一问题最多 3 轮，仍失败则暂停并向用户报告。

### 4. TDD And Verification

新增功能或 bugfix 必须优先写测试或最小可复现验证，再写实现。无法自动化测试的 GPU/视频/环境行为，必须写清楚 smoke test 命令、输入样例和人工判定标准。

完成任何阶段前，必须有新鲜验证证据：

- 单元测试。
- CLI smoke test。
- FFmpeg 命令检查。
- vLLM health check。
- 输出 JSON schema/字段检查。

不能只根据代码阅读声称完成。

## Local Batch PoC Requirements

### 1. Input

本次 PoC 优先支持本地视频文件夹：

- 通过 CLI 参数或 config 选择输入目录。
- 递归或非递归行为必须可配置。
- 支持常见视频格式，例如 `.mp4`、`.mov`、`.mkv`、`.avi`、`.flv`、`.ts`、`.m4v`。
- 不支持或损坏的视频要记录失败原因，不能阻塞整个文件夹。

### 2. Video Processing

- 必须优先使用 FFmpeg + NVDEC GPU 解码。
- 默认 1 FPS 抽帧。
- 默认 clip 长度 10 秒，允许配置 10-20 秒。
- 禁止逐帧 LLM 推理，必须 clip 级推理。
- Clip 输入帧数要小，默认 8-10 帧，避免 RTX 3080 20GB OOM。
- 输出目录保存 manifest、抽帧中间结果、clip 结果和汇总 JSON。

### 3. Prompt Configuration

- prompt 必须从 config 读取，不能硬编码在业务逻辑中。
- 支持 `prompt.system` 和 `prompt.user`。
- Prompt 必须要求模型输出严格 JSON。
- Prompt 必须要求输出画面时间字段；如果画面时间不可读，要保留 clip 的视频相对时间。

### 4. Timeline Output

输出结果必须包含监控画面的时间轴。至少包含：

- `video_id` 或视频文件路径。
- `video_start_time`：如果文件或画面可识别则填写，否则为 `null`。
- `clip_start_seconds`。
- `clip_end_seconds`。
- `clip_start_timecode`，格式如 `HH:MM:SS`。
- `clip_end_timecode`，格式如 `HH:MM:SS`。
- `frame_times`：clip 内参与推理帧的相对秒数或 timecode。
- `screen_time` 或 `画面时间`：模型从监控画面 OCR 到的时间，无法读取则为空。
- 事件级 `start_time` / `end_time` 或对应 clip 范围。

不能只输出 `datetime.now()` 这种服务处理时间。

### 5. Model Inference

- 优先兼容 OpenAI-compatible `/v1/chat/completions`。
- 默认模型名：`memai-zhengxin-v3-20260413`。
- 默认配置使用 `api_base_url: http://localhost:8679` 和 `chat_completions_path: /v1/chat/completions`，由代码拼接为完整请求 URL。
- RTX 3080 20GB 上 batch 保守起步，先 batch size 1，再逐步尝试 2-4。
- vLLM dtype 和显存参数要在测试环境验证；如 BF16 不稳定，优先 FP16。

## Security And Data Rules

- 不要在新文档、测试夹具或输出示例中复制真实 RTSP 密码、token、Webhook 密钥、Cookie。
- 参考项目 `service/config.yaml` 包含真实内网 RTSP URL 和密码，阅读可以，传播要脱敏。
- 本地视频、抽帧图片、模型输出可能包含门店画面，默认视为敏感数据。
- 不要把视频帧、日志、输出样例批量复制到仓库外部。
- 不要删除用户已有视频或模型文件。

## Implementation Rules

- 所有新增代码放在本项目目录内。
- 不修改参考项目实时 RTSP 主链路。
- 可参考 `shared/vlm_client.py` 的接口设计，但新实现应位于本项目。
- 不引入不必要的分布式系统。
- 不引入大型依赖解决小问题。
- 保持配置、运行命令、文档一致。
- 所有输出文件命名要稳定，支持断点续跑。
- JSON 输出必须可被机器解析；模型 raw response 可以保留，但不能作为唯一结构化结果。

## Validation Matrix

阶段 0 文档/agent 规则：

- 检查文件存在：
  - `agent.md`
  - `task_plan.md`
  - `findings.md`
  - `progress.md`
  - `docs/project.md`
  - `memories.md`
- 检查 `zhengxin-vlm-0413` 下没有本次误放的工作流文件。

本地批处理代码变更后：

- Python 语法检查：
  - `python3 -m py_compile <changed python files>`
- 单元测试：
  - 如新增 tests，运行对应 `python3 -m unittest ...` 或 `pytest ...`
- FFmpeg/NVDEC 检查：
  - `ffmpeg -hwaccels`
  - `ffmpeg -decoders | grep cuvid`
- vLLM health check：
  - `curl http://localhost:8679/v1/models`
- 最小视频 smoke test：
  - 使用一个短视频目录运行本地批处理入口。
  - 检查输出包含 clip 级时间轴和汇总 JSON。

测试环境验证：

- 通过 `ssh xiaozheng@192.168.5.100` 执行前，先确认路径、依赖和 GPU 状态。
- 远端命令要尽量只读或写入明确输出目录。
- 不要覆盖远端已有模型和配置。

## Definition Of Done

本次 PoC 完成必须满足：

1. 支持本地文件夹所有视频分析。
2. 不依赖海康云眸云存储。
3. 模型提示词可通过 config 调整。
4. 输出包含视频、clip、事件的监控时间轴。
5. 4B VLM 使用现有模型路径或测试环境已有模型。
6. 断点续跑和失败记录有基本支持。
7. 文档更新，包含运行命令、配置项和输出结构。
8. 必要验证命令已运行并记录。
9. 每个阶段的子 agent 审查结论记录在 `progress.md`。