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

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

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

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

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

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。