From 0281ae8afa75170eceab4c4f45392f4666cac4cb Mon Sep 17 00:00:00 2001
From: lroyia <lirh@chinaweal.com.cn>
Date: Mon, 2 Feb 2026 17:27:34 +0800
Subject: [PATCH] Update README with project description and add AGENTS
 documentation

---
 AGENTS.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  48 +++++++++++++-
 2 files changed, 239 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a435c1a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,192 @@
+# PoseFind 项目上下文指南
+
+## 项目概述
+
+PoseFind 是一个基于 MediaPipe 的人像姿态识别项目，专注于实现人体姿态估计和可视化。项目使用 Python 开发，主要面向计算机视觉和人机交互应用场景。
+
+### 主要功能
+- 摄像头实时姿态检测
+- 图片单张/多人姿态识别
+- 33个全身姿态关键点检测
+- 姿态骨架可视化绘制
+
+### 技术栈
+- **语言**: Python 3.7+
+- **核心框架**: MediaPipe (Google 开源的姿态估计库)
+- **图像处理**: OpenCV (opencv-python)
+- **图像操作**: Pillow
+- **许可证**: Apache License 2.0
+
+### 架构设计
+项目采用面向对象设计，核心类为 `PoseDetector`，包含以下关键组件：
+- 双检测器模式：静态检测器（用于多人检测）和流式检测器（用于实时视频）
+- 姿态检测与绘制功能分离
+- 支持单人和多人姿态信息提取
+
+## 项目结构
+
+```
+posefind/
+├── pose_detector.py      # 主程序文件，包含 PoseDetector 类和主函数
+├── requirements.txt      # Python 依赖列表
+├── README.md            # 项目简介和快速开始指南
+├── USAGE.md             # 详细使用说明文档
+├── LICENSE              # Apache 2.0 许可证
+├── test.webp            # 测试图片
+├── yolov8s.onnx         # YOLOv8 模型文件（当前未使用）
+├── .gitignore           # Git 忽略规则（标准 Python 项目配置）
+└── AGENTS.md            # 本文件，AI 助手上下文指南
+```
+
+## 构建和运行
+
+### 环境准备
+```bash
+# 安装依赖
+pip install -r requirements.txt
+
+# 如遇网络问题，可使用国内镜像源
+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+### 运行命令
+
+#### 摄像头实时检测
+```bash
+python pose_detector.py
+```
+- 自动打开默认摄像头（索引 0）
+- 实时显示姿态检测结果
+- 按 `q` 键退出
+
+#### 图片检测
+```bash
+python pose_detector.py <图片路径>
+```
+- 示例：`python pose_detector.py test.webp`
+- 显示带有姿态骨架的图片
+- 打印姿态关键点坐标信息
+- 按任意键关闭窗口
+
+### 测试说明
+- 项目使用 `test.webp` 作为示例测试图片
+- 暂无自动化测试脚本，需手动测试功能
+
+## 开发约定
+
+### 代码风格
+- **注释语言**: 中文（项目主要面向中文用户）
+- **文档字符串**: 使用 Google 风格的 docstring
+- **类和函数命名**: 遵循 PEP 8 规范，使用驼峰命名法（类名）和下划线命名法（函数/变量）
+- **代码组织**: 将核心逻辑封装在类中，功能模块化
+
+### 关键类和方法
+
+#### PoseDetector 类
+**位置**: `pose_detector.py`
+
+核心方法：
+- `__init__()`: 初始化两个 MediaPipe Pose 检测器（静态和流式）
+- `detect_pose(image)`: 单人姿态检测（流式模式，用于视频）
+- `detect_poses(image)`: 多人姿态检测（静态模式，用于图片）
+- `draw_pose(image, results, color)`: 绘制单个姿态骨架
+- `draw_poses(image, pose_results)`: 绘制多个姿态骨架（不同颜色）
+- `get_pose_info(results)`: 获取单人姿态信息
+- `get_poses_info(pose_results)`: 获取多人姿态信息
+
+**配置参数**:
+- `model_complexity=1`: 中等复杂度模型
+- `min_detection_confidence=0.5`: 最小检测置信度
+- `min_tracking_confidence=0.5`: 最小追踪置信度
+
+#### 主函数
+- `run_webcam()`: 摄像头检测模式的主循环
+- `run_image(image_path)`: 图片检测模式
+- `main()`: 程序入口，根据命令行参数选择运行模式
+
+### 依赖版本
+```
+opencv-python==4.8.1.78
+mediapipe==0.10.8
+Pillow==10.1.0
+```
+
+### 多人检测说明
+- MediaPipe Pose 主要优化单人检测
+- 静态模式下可以尝试检测多个人物
+- 每个人物使用不同颜色区分（绿、红、蓝、黄、紫、青）
+- 对于复杂多人场景，检测结果可能不完整
+
+### 常见问题处理
+1. **摄像头无法打开**: 检查摄像头占用，尝试修改索引（0, 1, 2...）
+2. **检测效果不佳**: 确保光线充足、人物完整可见、避免复杂背景
+3. **依赖安装失败**: 使用国内镜像源安装
+4. **多人检测不准确**: MediaPipe 局限性，可考虑集成 YOLO 等目标检测器
+
+### 扩展方向建议
+- 添加姿态识别功能（站立、坐着、举手等）
+- 支持视频文件输入
+- 姿态数据保存和加载
+- 集成目标检测器实现更精确的多人检测
+- 姿态异常检测
+- 姿态轨迹跟踪
+
+## Git 工作流
+
+### 分支信息
+- **当前分支**: main
+- **远程仓库**: http://47.107.61.133:3000/lirh/posefind.git
+
+### 提交规范
+- 提交信息应简洁明确，说明"为什么"而非"是什么"
+- 示例：`Add pose detector implementation with YOLOv8 and supporting files`
+
+### 忽略规则
+项目使用标准 Python `.gitignore`，忽略以下内容：
+- Python 编译文件 (`__pycache__/`, `*.pyc`)
+- 虚拟环境 (`.venv/`, `venv/`)
+- IDE 配置 (`.idea/`, `.vscode/`)
+- 构建产物 (`dist/`, `build/`)
+- 测试覆盖率文件 (`.coverage`, `htmlcov/`)
+
+## 注意事项
+
+1. **MediaPipe 局限性**: MediaPipe Pose 模型主要针对单人优化，多人检测能力有限
+2. **模型文件**: 项目中包含 `yolov8s.onnx` 文件，但当前代码未使用，可能是未来的扩展方向
+3. **中文环境**: 项目文档和注释使用中文，维护时保持一致性
+4. **跨平台**: 代码支持 Windows/Linux/macOS，但摄像头索引可能因系统而异
+5. **资源管理**: 使用 `try-finally` 确保摄像头和窗口正确释放
+
+## 开发工具
+
+### 可用工具
+- Python (需在虚拟环境中运行)
+- Git (版本 2.45.1.windows.1)
+- FFmpeg (已安装，可用于视频处理)
+- curl (已安装)
+
+### 不可用工具
+- `rg` (ripgrep) - 使用 `search_file_content` 工具替代
+- `gh` (GitHub CLI)
+- `wget` - 使用 `curl` 替代
+
+### Python 执行
+注意：当前环境中 `python` 命令不可用，需要在虚拟环境中运行。项目使用 `.venv` 虚拟环境（已忽略）。
+
+## 维护指南
+
+### 修改代码时
+1. 保持中文注释和文档字符串的一致性
+2. 遵循现有的类和方法命名规范
+3. 确保资源正确释放（摄像头、窗口）
+4. 添加功能时更新相关文档（USAGE.md）
+
+### 添加新依赖时
+1. 在 `requirements.txt` 中添加具体版本号
+2. 测试在不同平台上的兼容性
+3. 更新 USAGE.md 中的环境要求部分
+
+### 修复 Bug 时
+1. 先在 USAGE.md 的"常见问题"部分记录
+2. 如涉及核心逻辑，更新相关方法文档
+3. 考虑添加错误处理和用户友好的提示信息
\ No newline at end of file
diff --git a/README.md b/README.md
index a6584c3..41b9039 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,48 @@
-# posefind
+# PoseFind
 
+基于 MediaPipe 的人像姿态识别项目，支持摄像头实时检测和图片姿态检测。
+
+## 功能特性
+
+- 🎥 **摄像头实时检测** - 实时检测视频中的人像姿态
+- 📸 **图片检测** - 支持单张图片中的人像姿态识别
+- 👥 **多人检测** - 静态图片模式支持多个人物检测（不同颜色区分）
+- 🦴 **33个关键点** - 全身姿态关键点识别
+- 🎨 **骨架可视化** - 在图像上绘制姿态骨架
+
+## 快速开始
+
+### 环境要求
+
+- Python 3.7+
+- Windows/Linux/macOS
+
+### 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 使用方法
+
+#### 摄像头实时检测
+
+```bash
+python pose_detector.py
+```
+
+按 `q` 键退出程序。
+
+#### 图片检测
+
+```bash
+python pose_detector.py path/to/your/image.jpg
+```
+
+## 详细文档
+
+更多使用说明请查看 [USAGE.md](USAGE.md)。
+
+## 许可证
+
+本项目遵循 LICENSE 文件中的许可证规定。
\ No newline at end of file