基于 ROSLander 移动机械臂平台的葡萄智能视觉采摘项目，面向教室模拟葡萄架场景。
本仓库同时管理项目代码、YOLO 数据与模型说明、ROS2/机械臂资料、阶段分析，以及组员使用 Codex 开发时必须遵守的事实和安全约束。
项目已经具备 YOLO 葡萄检测、RGB-D 数据读取和普通物体抓取基线，但尚未形成稳定的农业采摘闭环。
仓库已新增独立的固定工位基本夹取执行器，但目前只完成离线实现和只读接口取证；
默认模式不发送动作，现场姿态和夹爪参数仍为 UNKNOWN。这不代表基本夹取已经通过
实车验证，也没有解除检测-only节点的动作硬禁用。
当前代码仍需要逐步解决：
- 小车与葡萄的距离、横向位置和机械臂可达性；
- RGB 与深度图的空间对齐；
- 葡萄中心点、有效深度和多目标选择；
- 无目标时的主动搜索；
- 夹爪开闭语义、反馈和异常归位；
- 夹紧后的低速向下脱离；
- 抓取复检、超时、恢复和重试。
详细分析见葡萄采摘问题分析与实施建议。报告中的建议不代表已经实现，状态以项目事实基线为准。
- 从仓库根目录启动 Codex；
- 让它先完整读取 AGENTS.md；
- 阅读Codex 与项目治理入口；
- 复制提示词模板开始只读校准；
- 每次只交给 Codex 一个可验证任务，并明确文件白名单；
- 未通过开发与实车放行关卡前，不启用执行器。
标准文件名是 AGENTS.md，不是 AGENT.md。后续 Codex 读到它后，会获得项目背景、必读顺序、事实状态、接口禁区和交付要求。
给 Codex 的推荐第一句话：
请先完整阅读根目录 AGENTS.md，并按其中必读顺序校准项目。
本轮先只读分析，不修改文件，不运行任何会驱动底盘、机械臂或夹爪的命令。
请先列出相关真实文件、外部接口来源和 UNKNOWN 项。
| 文件 | 作用 |
|---|---|
| AGENTS.md | Codex 在本仓库必须遵守的最高优先级规则 |
| 项目事实基线 | 防止把推断、旧资料或计划写成当前事实 |
| ROS2 接口合同 | 防止生成无来源的 topic、service、message、import 和函数 |
| Codex 协作流程 | 规定组员怎样拆任务、提问、实现、审查和交接 |
| 开发与实车放行关卡 | 规定代码从离线测试进入真实小车的条件 |
| 提示词模板 | 提供可直接复制的只读、设计、实现和审查提示词 |
这些文件不能让 AI“绝对不出错”，但能让未知信息保持未知，并阻止未经证据和验证的代码直接获得硬件权限。
| 目录 | 内容 | 管理要求 |
|---|---|---|
docs/ |
项目文档、治理合同、分析报告和精选资料 | 通过 docs/README.md 导航；建议与事实分开 |
official_examples/ |
ROSLander 官方示例源码备份 | 默认只读，不直接在其中开发 |
robot/ |
当前自研机器人端代码、launch 和部署脚本 | 涉及硬件，必须经过接口合同和分级验证 |
yolo/ |
数据集配置、训练记录和脚本 | 模型与数据版本必须可追溯 |
configs/ |
后续统一配置入口 | 参数必须包含单位、范围和来源 |
tests/ |
自动测试、固定小样本和验证说明 | 离线测试不等于实车放行 |
tools/ |
不直接属于运行节点的辅助工具 | 不放一次性危险控制脚本 |
frontend/ |
前端规划与说明 | 当前不是采摘控制核心路径 |
建立实机事实与接口快照
-> 把纯算法、状态机、ROS2 适配和硬件安全层分开
-> 补目标选择、稳健深度和异常处理测试
-> 检测-only
-> 跟踪-only
-> 夹爪单测
-> 低速向下脱离
-> 底盘预对准
-> 主动搜索、复检和恢复
-> 完整采摘集成
不要一次性让 Codex 重写完整采摘系统。高或 Ultra 推理档位适合做深层分析、架构设计和审查，但外部接口必须有来源，文件范围必须小，硬件权限默认关闭。
enable_arm默认保持false；后续动作权限应进一步拆分。- 未确认真实接口、坐标方向和安全范围前，不发布底盘或机械臂动作。
official_examples/和docs/source-materials/默认只读。- ROS1 农业案例只移植设计思想，不直接覆盖 ROS2 代码。
- 大量图片、完整 rosbag、训练输出和大型压缩包不提交普通 Git。
- 公共仓库不得提交密码、SSH 私钥和未经确认可公开的资料。
- 所有实车测试保留 commit、配置、模型哈希、日志和回滚方法。
不适合直接上传 GitHub 的压缩包、完整资料集、rosbag 和训练数据可以由组内私发。仓库中至少保留：
文件名
用途
来源
版本或日期
大小
SHA-256
获取方式
重点阅读文件
是否允许公开
当前大型 agripicking.zip 建议私发，组员按问题分析报告中的整理任务提取核心流程、参数和疑点，不直接把整个压缩包提交到普通 Git。