Git 仓库不该装下整个开发环境#

公开 README 里很明确地区分了几类东西：

• src/ 里的项目源码应该进入 Git。
• docker/、docs/、scripts/ 这类工程支撑材料应该进入 Git。
• 第三方 SDK、构建镜像、模型权重和输出成果不该直接提交。
• 大文件和本地运行数据要通过忽略规则或手动分发隔离。

这几类东西混在一起，后面最容易出问题。

很多嵌入式项目一开始为了方便，会把“能跑起来所需的一切”都堆在项目目录里。短期看省事，长期看会让仓库越来越不可维护：拉取变慢、历史变脏、二进制文件反复冲突、外部读者分不清哪些是源码、哪些只是某台机器上的中间状态。

端侧视觉项目尤其容易踩这个坑。模型文件、SDK、构建成果和测试数据都可能很大，而且生命周期不同。源码每天变，模型偶尔变，SDK 可能由供应商维护，输出成果则应该随时可删。

把这些东西放在同一个 Git 历史里，是把四种生命周期强行绑在一起。

Docker 是协作工具，不是万能盒子#

这个仓库把 Docker 作为重点开发路径之一：开发者在宿主机写代码，通过容器获得工具链和一致的构建环境。

这里用 Docker 的重点，是把大家的开发方式固定下来：

• 宿主机负责编辑源码和管理 Git。
• 容器负责提供构建环境。
• SDK 和模型作为外部材料挂载或放置。
• 输出成果进入独立目录。
• 文档说明第一次环境搭建和日常开发循环。

这比在 README 里写一句“请安装好依赖”靠谱得多。

嵌入式项目的依赖不只是几个 pip 包，还包括交叉编译器、板级 SDK、构建脚本和刷写工具。Docker 不能消除这些复杂性，但能把复杂性固定在一个相对可描述的位置。

这也是为什么 README 里的目录说明比功能列表更关键。功能列表说明项目要做什么，目录结构则说明代码、环境和产物各放在哪里。

模型和输出要从一开始就隔离#

视觉项目很容易把模型权重当成普通资源文件处理。不过在真实项目里，模型权重有几个麻烦点：

• 体积大。
• 更新频率和源码不同。
• 可能来自不同训练流程。
• 可能需要转换成不同部署格式。
• 有时还带有授权或分发限制。

输出成果也类似。编译结果、日志、测试图像、临时报告都不该自然进入 Git。它们对本地调试有用，但不适合作为仓库历史的一部分。

这个仓库的忽略规则把镜像、SDK、模型权重、输出和构建成果分开处理。它不解决所有问题，但至少建立了一个基本原则：仓库记录的是工程结构和可维护源码，不是开发机器的缓存。

这个原则对博客写作也适用。我可以写“模型文件应该怎样作为外部资产管理”，但没必要公开真实权重、测试数据或本地输出。

README 需要服务新人上手，而不是展示复杂度#

端侧项目的 README 容易越写越像炫技清单：支持多少模块、用了多少算法、接了多少外设。

但对协作者来说，更有用的是这些信息：

• 第一次克隆后哪些目录应该自己准备。
• 哪些文件不会进入 Git。
• 日常开发应该在哪个环境里编译。
• 代码和容器之间怎样同步。
• 测试和构建命令在哪里运行。
• 出问题时先检查哪几个范围。

it-gets-you-better-than-her 的 README 虽然还带有早期项目文档的痕迹，但它已经把“首次环境搭建”“实际构建流程”“日常开发流程”“容器管理”“常见问题”写进去了。这些内容对后来接手的人更有用，至少能少问几轮“我该在哪儿编译”。

一个项目越接近硬件，文档越应该降低环境不一致带来的沟通成本。

模块多了以后，先把几条线分开#

目标检测、跟踪、深度估计、点云、定位和避障可以串成一条很长的视觉链路。如果没有工程分层，任何一个现象都可能被误判。

比如避障表现不对，原因可能是检测框不稳定，也可能是深度估计慢，也可能是坐标变换错，也可能是外设接口延迟，还可能是构建出来的并不是你刚改的版本。

所以端侧视觉项目要先区分几条线：

• 算法线：检测、跟踪、深度、定位、避障。
• 构建线：源码、CMake 或 Makefile、交叉编译、成果。
• 资产线：模型、SDK、样例数据。
• 设备线：相机、屏幕、串口或其他外设。
• 协作线：分支、PR、文档和问题追踪。

这篇文章和之前那篇 A1 分层调试回看的区别在这里：之前写的是运行时排障分层，这篇写的是仓库和协作分层。前者解决“现象不对先查哪一层”，后者解决“项目怎样不把所有东西混成一团”。

开源展示要控制信息密度#

公开端侧视觉仓库还有一个问题：README 里很容易混进内部协作习惯、本地环境说明、历史脚本和临时指南。它们对当时团队有帮助，但对外部读者可能噪声很大。

更理想的公开版本应该把信息分成三层：

• 首页 README 只解释目标、架构、目录范围和快速上手。
• docs/ 放完整开发指南、Docker 指南和协作规范。
• scripts/ 保留可验证的构建、检查或辅助命令。

这样首页不会变成杂物间，读者也能按需要深入。

如果未来继续整理这个仓库，我会优先做两件事：第一，把本地协作痕迹移到合适的文档页；第二，补一个最小 smoke test，让外部读者不用真实硬件也能验证配置解析、模块装配或构建脚本的基本路径。

算法之外先把仓库理顺#

端侧视觉项目离不开模型和算法，不过项目早期更常见的麻烦，是仓库先乱起来。

一个靠谱的仓库应该先回答这些问题：

• 什么进入 Git？
• 什么只作为外部资产？
• 什么是构建输出？
• Docker 管到哪里为止？
• 新人如何从零到第一次构建？
• 文档如何避免把临时经验和长期规范混在一起？

it-gets-you-better-than-her 给我的提醒是：硬件和视觉项目公开出来时，算法能力要写，工程组织方式也要写。很多调试时间不是花在模型本身，而是花在确认环境、资产、构建产物到底是不是同一套。