背景

事情是这样的：公司搬到新办公点后，发现附近有桌球馆可以预约。某个周五晚上，被两位同事拉去打了几场，感觉还挺有意思，从此就开始沉迷桌球。虽然运动量谈不上多大，但好歹也是有运动，总归是好事 :D

可问题在于作为一个运动白痴，之前几乎没怎么碰过桌球，光靠每周打一次，想涨球技属实不够。既然实力不行，那就上点科技试试 😉

再加上今年各类大模型和 Agent 进展飞快，靠 vibe coding 快速做几个小工具出来，只要不纠结代码质量和架构设计，开发效率直接起飞，代码直接交给 Agent 库库库地写（只要不观测，代码就不会坍缩成屎山）。尤其国产模型的能力也赶上来了，再配上 opencode 那种 “$10 换 $60 token” 的实惠套餐，只要有想法，花点时间，花点小钱还是能实现的。

需求分析

灵感：一个 “开挂” 的视频

小红书上刷到这么一段视频：球还没出杆，桌面上已经亮起一条线，告诉你要打哪颗、往哪儿瞄，白球和目标球的预期走向。

具体的实现也不算复杂：

吊灯位置挂投影仪 + 摄像头
摄像头俯拍桌面，实时分析球路
投影仪将分析结果投射回桌面

线画在真桌上，球动人走都跟着刷新，就是那种 “动态追踪” 的效果。

但是呢，这个方案看着效果挺好但是有几个问题：

场地限制：需要在球馆吊顶施工走线供电，设备绑死固定的某个球桌（移动式的还需要支持校准）
设备成本：设备成本高，摄像头 + 投影 + 主机一套下来，就算是丐中丐的版本也得大几百

总结一下就是门槛太高了，光前期准备就费老大劲了，更适合球馆老板来作为基建接入，而非桌球玩家来使用。

不过仔细思考了下，其实关键就是摄像头 + 投影，我们手上的手机就可以做这个事情：

手机有现成的摄像头
手机的芯片足够好，可以做识别 & 运算
手机虽然无法投影，但是有屏幕可以显示，未来也有接入投影的可能

因为手机人人都有，所以门槛也很低，只要做成 APP 装到手机里，到了球场拍个照就可以用，还是比较方便的～

小插曲：一场争论

我和 AI 聊了几十轮，对大致架构有了初步认识后，又和太太聊了这个项目。聊到具体怎么用时，我俩争了很久：

我坚持 “低门槛”：有手机就行，不接任何外设，随手就能用；为了打球搞一整套硬件配置，太麻烦，最后大概率吃灰。
太太坚持 “要实时、要能一直看”：得塞进智能眼镜之类的硬件里，辅助线直接叠在眼前实时看；低配点也得能通过夹具挂在脸前，像运动相机那样实时取景。

争论一番，谁也说服不了谁：我觉得她太纠结于细枝末节的使用场景，忽略了工程实现的本质；而她觉得我没抓住最现实的使用场景，要是路走歪了，只会做出来一个没人想用的东西。

吵到最后决定不纠结了，产品的本质还是拍照识别，然后标出这一杆怎么打、往哪条线走。差别只在结果往哪儿显示，手机屏幕 or 眼前屏幕，形态问题不影响核心实现，先往下做（反正干活的都是我 🫠）

需求总结

对着球桌拍照，屏幕上直接告诉你这一杆怎么打，其他的都不做，keep it simple

输入：拍照 / 相册选图（相册是为了开发调试方便，且后续也可以支持实时视频流）
输出：球与袋口的识别框、瞄准线、瞄准点，底部区域给杆法提示（高 / 中 / 低杆、力度、加塞）
过程：全部本地算完（大模型虽好，但是烧 token，延迟也高，不利于后续做实时视频流）

产品调研

为了避免重复造轮子，我也去应用商店 & 各类 App 开发平台翻了一圈，确实也放到一个类似的项目 HereLiesAz/CueDetat，代码库的描述很有意思，翻了一下 commit 记录，发现也是 vibe coding 出来的，试用了下不是很符合我的需求，还是自己搞一个吧 😏

技术选型

框架选型

在没有 vibe coding 的年代，技术框架的选型需要慎之又慎，我们一般会选择自己熟悉的语言 + 相关的框架，因为之前用 Fyne 做过 App，因此一开始的时候我是有用 Fyne 的倾向的，但是既然是 vibe coding，是不是会有更合适的框架呢？

和 AI 聊了之后，发现有 Flutter 与 React Native 这两个框架，这两个都会比 Fyne 更合适，在性能、硬件调用、后台进程存续、现成轮子等方面都有更好的表现。最后考虑到性能 & 编译期检查等能力，还是选择 Google 出品的 Flutter，虽然这个是基于 Dart 语言，反正是 vibe coding，不看代码就不需要学 👻

视觉模型

在视觉识别模型方面，本项目选的是 YOLO 模型（You Only Look Once），这是一类目标检测的算法，也就是说：给模型一张图，它会告诉你里面有什么、分别在哪，你可以通过数据标注 + 训练来提高识别的准确度。

在其出现之前，老式算法（如：R-CNN）要把图片切成小块一块块看，效率很低；YOLO 的革命性在于只看一次整张图，就同时完成 找+认 两个操作。

具体到我们的项目中， YOLO 模型要做/不做的事情是：

✅ 找球：认出每颗球在哪、属于哪一类（黑、白、全、花）
✅ 找袋口：认出台面上看得见的袋口，供瞄准使用
❌ 数字识别：数字面可能不会出现在镜头中，实现成本过高

YOLO 的本质也是卷积神经网络（CNN），核心操作是卷积：拿一个小窗口（卷积核，通常是 3×3）在图上从左到右、从上到下地滑动，每滑一个位置就输出一个数，滑完整张图就得到一张新的 “特征图”，窗口里的权重在整张图上共享。

卷积层层堆叠后，网络就从局部看到整体：浅层学边缘和色块，中层学纹理与形状（条纹、圆形轮廓），深层学 “这是一颗球” 这种整体概念；每过几层做一次下采样，分辨率减半、感受野翻倍。

经典的 YOLO 处理结构上分成三段，外加一段后处理：

Backbone：卷积 + 下采样，逐层提取特征
Neck：融合深浅多尺度特征（浅层分辨率高管小目标，深层语义强管大目标）
Head：在每个位置输出「4 个坐标 + 各类别分数」，全图汇总成一个 [1, 4+类别数, 8400] 的张量
后处理：置信度筛选 → NMS 去重 → 换算回原图像素坐标

YOLO 的关键机制是密集预测，而不是 “给一个答案”：在 80×80 / 40×40 / 20×20 三个尺度的每个位置上都预测一次（8400 = 6400 + 1600 + 400 个候选框），一次前向全部出完；三个尺度分别覆盖小、中、大目标。

训练方式和所有神经网络一样：前向预测 → 与人工标注的框比对算损失 → 反向传播，循环几万次。所以标注质量决定识别上限：* *模型没有任何先验知识，它从标注里学到的就是它认知的全部**。

YOLO 模型本身自 2015 年提出以来，也在快速迭代（目前最新是 v26），从 v8 开始各代的模型侧重点各不相同（难分优劣）：

版本	大概的定位
v1	开山之作，将检测转化为回归问题，单次前向即可得到结果，速度极快但精度有限
v4	集大成者：CSPNet、PANet、Mish 激活、CIoU Loss，在 COCO 上首次达到 SOTA
v8	成熟稳定、资料最多、生态最全
v12	引入了注意力机制，框的定位精度更好，但收敛慢（冷启动明显慢），对量化也更敏感
v16	自蒸馏训练策略 + 动态正负样本分配，收敛速度加快，冷启动问题较 v12 有所缓解
v20	量化感知训练（QAT）全面优化，INT8 精度损失 < 1%，更适合边缘 NPU 部署
v26	最新一代，重心明显往端侧友好挪：端到端免后处理（连 NMS 都省了）、结构更简单、CPU 推理更快、小模型精度更高

然后每代模型也有进度之分，比如 v8s / v8m，一般会有 n/s/m/l/x 五档（nano, small, medium, large, x-large），一般来说移动端用 n/s/m 比较好，不然可能会遇到性能的问题。

总得来说，如果实际项目中要使用到 YOLO，可以多选几个模型来训练下（在 M4 mbp 上感觉速度还行，几百张的数据量基本在 1 小时左右就可以训完），测试下来其实多个模型的区别并没有很明显，比如 v12s 大部分情况下比 v8m 更好（但是也有 v8s 反杀 v12s 的情况出现）；说到底真正决定效果的是数据与标注质量，而不是模型代际。

技术实现

实际落地实现过程还是踩了不少坑的，这里挑几个大的讲讲 🧐

是否投影回俯视图

真正动手后第一个问题是坐标系：球该标在哪张平面上？

最初想把斜拍的照片 “投影” 回正俯视图，在正视图上算瞄准线，再画回原照片（因为几何计算在正视图上最干净），但是实测下来发现走不通：掰平至少要在画面里凑齐 4 个定位点（比如 4 个袋口），才能算出照片和桌面的对应关系。自动找 4 个袋口（袋口本身认不太稳，mAP50 0.763）或让用户手点 4 个角袋，都要求画面里能看到 4 个角袋，而实际拍摄基本都是 1~3 个。

于是整条掰平链路（对齐计算、坐标换算、校准界面）被删掉，改成直接在斜着的原图上标：原图缩放到模型要的尺寸喂进去，拿回球和袋口的框，按同样比例换回原图坐标、去掉重复框，再画线。识别、画线、算球路，全程只用原图像素坐标。唯一例外是物理模拟需要球的真实大小，所以整体乘一个系数换算到 “桌面尺度” 跑一遍再换回来，即只是整体缩放，不是真掰平，透视变形一点没少。

代价是每个量都不能再用统一值：球的大小直接用识别框的短边推算（远近球本就大小不同，取短边还能抗运动模糊）；换算系数实测 0.82，之前用 0.95 让球偏大四分之一，瞄准点被推偏、角度被算大 10° 以上，能打的直球被判 “打不进”；袋口瞄准点不是框中心，要从框中心朝所有球的加权中心挪一点、并设上限；判断遮挡时每颗球用自己的大小，靠得太近（不足 1.5 个球半径）的重复框直接忽略。

模型输出很脏，靠四道过滤才 “标得住”，几乎全是真机 bug 换来的：

置信值门槛降到 0.15，实拍里不少真球只有 0.10~0.25 分，卡 0.25 会在 24 张图里丢掉 56 个框
按类别去重，重叠度高的同类框只留一个；
母球和黑八全场各只有一颗，只留最高分的那个；
再补一道跨类别去重，防止同一颗球被判成两类、两个框都活下来。

举个例子：有颗酒红球被同时检成 “全色” 和 “黑八”，重复框的位置恰好落在母球到击球点的线路上，遮挡判断把它当成了另一颗球，一个能打的近直球被判 “路径被遮挡”。修完去重，又给遮挡判断补了一层豁免。

模型总会错，所以识别结果也是可以被手动纠正的：长按照片就地纠错（改类别、删误检、补漏检）；手动改选目标球和袋口并锁定球组；人工补的框取既有球框短边的中位数。

两个没闭合的账：遮挡判断是在图像空间做的近似——有张实拍红球挂袋、紫花球挡在母球到击球点的走廊上，间距 54px 需要 78px，参数修完仍判 “打不进”，而能解决它的桌面精算恰恰是被砍掉的校准模式；斜拍也不如正俯视，画面之外的袋口和球等于不存在，要拍全局得站得远还得有广角，而项目服务的就是 “站在桌边举起手机”，所以局部视野是默认前提：看得到的认真算，看不到的如实说。

训练数据来源

识别质量的上限其实取决于训练数据，而数据这一关走了三段弯路。

第一段想省事，直接用了线上开源数据集：983 张球桌照片重标成我们要的类别，在它自带的验证集上连最小模型都能跑到 mAP50 0.95。但一上真机就崩——那些图几乎全是正俯拍，没有一张是正常打球的斜视角度，模型只学会了 “从正上方看球桌长什么样”。教训很直接：别人验证集上的高分不等于真实场景能用，数据的价值不在数量，而在像不像真实使用时拍到的画面。

第二段自己造数据：在 App 里加了开发者模式，拍一张标一张。真用起来效率太低——手机屏幕就那么大，逐球点框又慢又容易点错，拍十张图的工夫标注要花十倍时间，根本维持不下去。

第三段拆开：手机只负责采集，拍完一键把「原图 + 当前识别结果」打包导出；电脑上用桌面标注器逐球画框、改类别、补漏检——数字键 1~5 切类、左键加框、右键删框、滚轮调大小、z 撤销、a/d 翻图即存。标注仍是五类（白球 / 全色 / 花色 / 黑八 / 袋口）。手机上干脆把人工标注整条链路删掉（约 -800 行），定位收窄成 “只采集”。

之后标注就变成一轮一轮做、每轮针对上一轮暴露的短板再补一批，前后三轮：

第一轮补真实拍摄域，先逐球标注一部分、再给整批补袋口框，87 张
第二轮新采一批盲标，不看 AI 结果从零画框，摸清它到底差在哪，111 张 / 1109 框
第三轮从旧批次里隔离出跨场次样本，做一把 “没见过的场次” 的尺子，25 张 / 329 框。

累计人工标注 220 多张图、1600 多个框；每轮标完重训一版模型，再用同一把人工尺子复评，v8 / v12 / v26 三代模型也做横向对比：

阶段	评价口径	结果
只用开源数据（983 张俯拍）	开源自带验证集	mAP50 0.95，漂亮但没用
首批实拍微调（24 张）	自验证	0.93，跟自己对齐、水分大
第一轮后（87 张）	人工框算召回	框召回 0.643、类别正确 0.607
第二轮后（111 张 / 1109 人工框）	人工真值	AI 召回 69.1%、类别正确 61.0%
照短板重训	同场次人工验证	0.857 → 0.942
第三轮后（跨场次样本）	跨场次验证	0.725 → 0.811

两个数字最值得看：AI 召回 69.1%、类别正确 61.0%，这就是 “准确率七八十” 的来源；袋口 0.685 → 0.950、条纹球召回 0.488 → 0.826，正是当时点名的短板。三轮的定位也刚好递进：第一轮把拍摄场景对上，第二轮把问题看清，第三轮把泛化验实。在跑完三轮训练后识别的准确率还可以，因此可以先做几何计算相关的功能，后续有需要的话，多搞点数据进行训练应该可以进一波提升准确度 😉

落地效果

在多轮迭代 & 优化后，大概是这么一个效果，基本可以实现设想的功能，但是准确率还不是很棒，然后最开始说是不要接入云端大模型，但还是一时手痒 vibe 了一波 hhh，感觉效果也没有特别的好（和 YOLO 对比的话）

不过目前还存在比较多的 bug，比如部分场景置信度不高、部分挡路的情况无法判别，白球逃逸路线异常，库边判定等等的问题还是表现不太好，总之后续再多采些数据，交给 AI Master 去优化优化 :P

总结一下

带到球场分享了一下，收到一条评论说：“没用，先把球打直比什么都重要。”，话糙理不糙，打铁还得自身硬。

出球都打不直，上再多科技也白搭；角度算得再准，杆子一歪，白球根本不听你的。CueCast 能告诉你要往哪打，但它没法让你打准。

所以这个项目的定位还是：负责 “看” 和 “算”，把几何关系算明白，把击球方式推荐出来。但击球本身，CueCast 是替不了的。

“科技” 再好，也只是辅助，该练的基本功一个都省不掉。把该算的算清楚，把该练的留给球台，设计 CueCast 大概就是这么个想法吧。