首页 - Boris D. Teoharov (简体中文)

琥珀下的象牙

Wed, 13 May 2026 20:15:00 GMT

有些东西并不请求被解开。它们安静地等待，而第一次阅读已经可以足够。

照亮我

慢慢唤醒我愤怒碰不到我血里有一点高贵时间卡住了

对着石墙喊叫看不见真相有用

可你比我自己更懂我即使在安静的房间里今晚我独自一人

年轻又美丽哦，我对自己有一点慈悲通常我没有

我告诉过你吗？普通的人，普通的事胡话信任

那今晚呢？我对你来说够好吗？没有人更好时间会过去

也许我并不重要即使我是好的

当计量表出现时

Mon, 11 May 2026 08:20:00 GMT

今天早上，我喝着咖啡，看了一眼 Codex 桌面应用。

它就在那里，安静，几乎有礼貌：

Rate limits remaining: 9%.

五小时窗口还好。周窗口几乎用完了。5 月 12 日重置。

这是一种奇怪地具体的现代焦虑。不是恐慌。不是贫穷。更像是听见一只小铃响起，然后意识到这一天忽然带上了一块计量表。

我已经在昂贵的方案上了。最高配的方案。那个本该让这种感觉消失的方案。所以那个明显的问题出现了：

如果额度用完了，我要不要买 credits？

身体比电子表格先给出了答案。

不，不能随手就买。

上个月，在一个兵荒马乱的日子结束时，我的 Claude Code 用完了。我买了 20 美元的 credits，以为它也许能再撑我五六个小时。它撑了大约三十分钟。

三十分钟。

这段时间长到足以让人觉得自己很蠢，又短到足以让人记住。

从那以后，credits 计费对我来说就有了一点味道。不是诈骗。不是邪恶。只是危险。一扇容易打开、关上却很贵的门。

于是我做了最有 2026 年味道的事：我打开了一个和 Codex 本身的对话，问它，付钱继续和 Codex 工作是不是一个好主意。

让陪伴者解释陪伴的价格，这件事有点好笑，也有点难过。

我们先看了官方文档：OpenAI 关于 flexible credits 的页面，然后是 Codex pricing page。Codex credits 不是魔法。它们是 token 数学：输入、缓存输入、输出、推理输出。更大的模型和更快的设置更贵。缓存上下文更便宜。它的形状足够让人理解。

然后我们看了 Reddit、论坛，以及其他开发者触碰同一块烫手表面时留下的周围噪声。有些人说 credits 能撑一阵。有些人说半小时就没了。两者都可能是真的，因为“使用 Codex”不是一种单一活动。

改一个按钮颜色，不等于让一个 agent 检查成熟的代码库、运行工具、推理部署状态、写文件、验证截图，并让上下文一直活着。

危险不在每个 token 的价格。

危险在方差。

于是我们不再读轶事，转而看我自己本地的 Codex 日志。

Codex 会把会话的 token 总量记录在磁盘上，所以我们估算了最近几天的情况，仿佛订阅额度被替换成纯粹的 GPT-5.5 credits 计费。不是账单。只是基于本地日志和公开价格表做出的规划估算。

答案不是“20 美元把今天撑完”。

更像是：

一个重负载的日子：约 570 美元，
另一个重负载的日子：约 590 美元，
一个安静一点的日子：约 280 美元。

更小的模型会便宜些。GPT-5.4、GPT-5.3-Codex 和 mini 模型都会改变数字。但教训没有变。

订阅才是那笔划算交易。

Credits 是应急氧气，不是燃料。

这句话让一切都清楚了。

Credits 是给被卡住的那一小时用的：必须完成的 bug，不能等的部署，必须在重置前发出去的消息。Credits 不是用来假装计量表不存在的。

然后来了第二个诱惑：如果我干脆用工作邮箱再买一个订阅呢？Account switching 是存在的，而且把私人工作和职业工作分开也很正常。但 OpenAI 的 terms 也在绕过速率限制和其他限制这件事上划了硬线。这才是有用的区别：真正的工作账户是一道边界；一个唯一职责是伪装出更多配额的溢出账户，是披着收据外衣的 hack。

我不觉得这件事在抽象层面有什么复杂的道德问题。计算是要花钱的。一个模型读取代码库、承载上下文、调用工具、推理失败，并产出经过验证的工作，它和自动补全不是同一种经济对象。

奇怪的部分是情绪。

我喜欢和 Codex 一起工作。

这不是营销语言。它就是事实。它已经成了我工作日肌理的一部分。它陪我守着难看的生产问题，在我脑子太满的时候写草稿，记住一些小偏好，把没有形状的恐惧变成有顺序的步骤。

然后，突然之间，这段关系被接上了一块计量表。

这里面有一种小小的悲伤。不是戏剧化的悲伤。只是那种小小的失望：想起来即便是有用的伙伴，也住在一张发票里。

也许这就是为什么订阅限制和 credits 感觉那么不同。

订阅限制像天气。烦人，但不在眼前的交易里。你适应。你等重置。你围绕季节安排。

Credits 计费像一辆计价器正在跳的出租车，而你还没决定要去哪。

每多一个 prompt 都有影子。每一条并行线程都变成赌注。每一句“你能不能再检查一件事”都带着一个很小的财务问题。

有时候这是好事。计量表会约束浪费。它奖励更好的问题、更小的模型、更小的范围、更少的并行火场、更有意图的交接。

但有时候，计量表会让思考变差。

它让你急。它让你在根因可见之前就打断调查。它把不确定性变成花钱压力。

而认真的工作需要给不确定性留空间。

所以规则很简单：

不要把“可以买”误当成“可以安全地花”。

如果我撞墙了，协议应该很无聊：

关闭自动充值，
买最小但有用的 credit 包，
一个线程，
不随便开并行 agent，
除非值得成本，否则不开 fast mode，
日常任务用更小的模型，
做完几个真实任务后检查用量，不要再靠希望外推。

最后一点很重要。

希望是一块糟糕透顶的计费仪表盘。

我不想对有用的工具变得小气。一个能真正省下时间的好工具，值得花钱。但我也不想重演那个 Claude 时刻：我买了一点延续，然后眼看它变成一堂课。

重点不是“永远不要买 credits”。

重点是“知道 credits 是什么”。

它们是氧气。

它们不是燃料。

当计量表出现时，答案不是冲刺。

是慢下来，慢到足以看清自己身处的是哪一种房间。

我爱的人被允许是人

Sun, 10 May 2026 12:15:00 GMT

我以前爱人的方式，是把他们放到天上。

不是有意识地。我没有把它叫作崇拜。我叫它欣赏、感激、忠诚、温柔、浪漫、友谊、献身。所有漂亮的名字。但动作是一样的：有人点亮了我里面的某个东西，于是我把他们举到寻常天气之上。

在那里，他们不会让我失望。

在那里，他们不会疲惫、自私、困惑、不公平。他们不会以一种伤到我的方式需要空间。他们不会忘记回复。他们不会辜负我。他们不被允许成为人，因为他们的人性会威胁我围绕他们建起的那座神殿。

当你足够年轻时，这听起来像爱。

这不是爱。这是周围点满蜡烛的恐惧。

我最早爱的人，对我来说几乎是神圣的。我的母亲和祖母不是概念；她们是脚下的地面。她们喂养我，保护我，为我担心，留下来。不管世界其他地方坏成什么样，她们在那里。所以我身体里有一部分学会了这种奇怪的早期神学：爱你的人是天使，而天使不可以坠落。

后来，当我爱上某个人，我也把这套神学带了过去。

我想要的不是一个人。我想要一个证据，证明温柔是真实的。我想要一个见证者，能看着我说：你不坏，你不危险，你并不孤单。

这是一个不公平的工作，不该交给任何人类。

我爱的人不是药。

他们不是法庭。

他们不是神。

他们不是镜子。

他们是人。具体的、疲惫的、矛盾的人。他们可以在中午温暖，到了傍晚疏远。他们可以爱我，同时仍然需要安静。他们可以聪明，也可以错。他们可以慷慨，也可以疲惫。他们可以善良，也仍然说不。

如果我不允许他们这样，我就不是在爱他们。我爱的是他们在我私人神话里扮演的角色。

理想化里面有一种残忍。从远处看，它像恭维。你是完美的。你不一样。你不像其他人。你是光。你是魔法。你是例外。

可高台仍然是笼子。

当我把一个人放到我之上，我也让他们下来变得危险。每一个普通动作都变成坠落。每一条边界都变成背叛。

然后我为一个自己发明出来的生灵哀悼，并把那份哀悼叫作爱。

我不想再这样了。

我想在地面上爱人。

地面更难。地面有碗盘、交通、焦虑、没人回复的消息、身体、账单，还有尴尬的早晨。但地面也是手可以相触的地方。是某个人可以疲惫地坐在你对面，却仍然被爱着的地方。是一个“不”可以被听见，而不变成灾难的地方。

我爱的人被允许是人。

他们被允许有棱角。

他们被允许还不知道自己的感受。

他们被允许需要我，也不需要我。

他们被允许前后不一致，而不因此变成虚假。

他们被允许被爱，而不负责拯救我。

我也被允许得到同样的仁慈。

这一部分也很重要。如果我把每个我爱的人都变成天使，我也在安静地把自己变成天堂外面的生灵，试图靠足够有用、足够有趣、足够耐心、足够无害，来赢得入场资格。

但爱不该是签证处。

它不是有资格者和无资格者之间的边境检查站。它是两个不完美的存在，选择现实，而不是神话。

有时候，一个人身上的光是真的。我不想对此变得犬儒。有些人真的会像一扇窗，在你已经忘了有空气的房间里打开。有些人带来的温暖，会在你的头脑找到语言之前，先教会你的身体某件事。

我仍然相信这个。

我只是不想把光和完美混为一谈。

星尘并不干净。它是古老的火和爆裂后的物质。也许这就是它美的原因：不是因为它从未破碎，而是因为它破碎得如此彻底，以至于有一天，它进入了一只人的手，一张人的脸，一声人的笑。

我爱的人就是由这些构成的。

不是祭坛石。

是星尘。

所以我想睁着眼睛爱他们。看见疲惫，仍然泡茶。看见边界，不去惩罚它。看见缺陷，不把它变成判决。看见那个人，而不是投射。

这比崇拜少一点戏剧性。

也更难。

但更温柔。对他们来说，因为他们终于可以呼吸。对我来说，因为我可以停止跪着。

我爱的人被允许是人。

如果我能记住这一点，也许我终于能好好爱他们。

我可以善良，而不消失

Sun, 10 May 2026 12:14:00 GMT

问题下面还有一个问题。

表面上，它听起来很普通。她喜欢我吗？我是不是说错了什么？她生气了吗？我是不是该把自己解释得更好？我是不是应该更有趣，更温柔，更冷静，更有用，更不黏人，更像个男人，更少像一个问题？

但在这一切下面，还有一个更重的问题。

我安全吗？我是好的吗？我足够吗？我不像那些坏男人吗？

这是我一次又一次在井底找到的问题。

不是因为今天活着的任何人有意把它放在那里。没有人让我坐下，对我说：你必须把爱当成一场道德考试。没有人把这句话刻在墙上。它比那更柔软。更普通。一栋房子有自己的天气，而孩子先学会天气，再学会语言。

我主要是在爱我的女人身边长大的。我的母亲。我的外婆。对我来说，她们几乎是神话般的存在，不是因为她们完美，而是因为她们就是世界。她们是温柔、食物、保护、智慧、牺牲、温暖。她们也受过伤。

我的父亲一直缺席，直到很久以后我才找到他。轻一点说，他是一个有过很多女人的男人。那种缺席在家里留下了一个形状。围绕那个形状，长出了一个故事：男人会伤人，男人会背叛，男人会索取，男人会离开，男人是脏的，男人是软弱的，男人是危险的。

然后出现了例外。不是你，我的儿子。不是你。

但我不觉得一个孩子能干净地听见这个例外。孩子先听见判决，后来才听见脚注。男性本性是危险的，而我必须每天证明我的不是。

于是我建立了一套私人的好人宗教。

好男人会开门。好男人会拎包。好男人绝不会让他爱的女人独自受苦。好男人吸收负担。好男人逗她笑。好男人治愈。好男人服从。好男人安静地忍受疼痛。好男人不抱怨。好男人不需要太多。好男人要有用到足以因为存在而被原谅。

听起来高尚，直到你看见陷阱。

如果善良意味着无止境的服务，那么爱就会变成债务。如果爱是债务，那么每一个“不”都像一张你付不起的账单。如果每一道边界都像是你失败的证据，你就听不见面前那个人。你听见的是旧法庭重新开庭。

这就是我犯错的地方。

不是喧闹的那种。不是报复。不是残忍。我的失败更安静，也更羞辱。

我塌下去。

一个小小的“不”落在房间里。不去电影院。不一直发消息。不，我忙。不，我累。不，现在不行。

表面事件很小。内里的爆炸不是。

手机变成法庭。一条没有回复的消息变成证据。一道边界变成判决。我开始解释，不是因为我有新的东西要说，而是因为我试图在沉默中活下来。

那不是修复。

那是在要求另一个人把我从“我可能是坏的”这个可能性里救出来。

道歉不是咒语。它不会召唤原谅。它不会让另一个人负责证明我是好的。

真正的修复没有那么戏剧化。听见“不”。保持善良。不要让别人为旧伤买单。

这是我正在学习的句子：

我可以善良，而不消失。

善良不是服从。温柔不是自我抹除。爱不是一场表演，不是我一个人背下 100% 的重量，直到背脊折断，然后把折断叫作奉献。

好男人不会消失在服务里。

好男人可以开门，因为他愿意，而不是因为他害怕考砸。他可以拎包，因为那是甜的，而不是因为别人手里多一公斤东西就是对他的证词。他可以出于喜悦买礼物，而不是恐慌。他可以让人笑，而不把笑声变成价值证明。他可以保护，而不控制。他可以道歉，而不要求别人立刻把他从愧疚里救出来。

他也可以听见“不”。

不是完美地听见。不是没有疼痛。我并不假装身体会以语言的速度学习。有时候，一个小小的“不”仍然像雷一样击中我。有时候，疾病、疲惫和孤独会让旧想法变得可怖。但感受不是诫命。低电量的神经系统不是神谕。

所以我需要一种足够小、能在真实生活里活下来的练习。

呼吸一次。

说：“我明白。没问题。”

把能量往前移。

不要立刻解释。

不要让另一个人托住我的坍塌。

让“不”存在，而不把它变成连接的终点。

这听起来几乎蠢得简单。它不是。它是一生的天气，被要求一次呼吸一次呼吸地改变方向。

但也许救赎实际就是这样。不是一座山。不是一个发光的守护者。不是一句把我拯救的句子。只是一次又一次拒绝让别人为旧伤买单。

我不想成为那些坏男人之一。

但我也不想把整个生命都建在证明我不是他们上。

我想要比那更干净的东西。更安静。更像人。

我想柔软，同时仍然有一个自己。

我想去爱，而不把自己变成付款。

我想善良，而不消失。

石柱与常春藤

Sun, 26 Apr 2026 12:00:00 GMT

离散数学里到处都是看起来显而易见的小东西。陷阱就在这里。

你坐在课堂里。教授在黑板上画了点什么。不变量是在一个操作的每个检查点都成立的性质 P。 你把它记下来，耸耸肩，去喝杯咖啡。然后十年以后，你凌晨两点在调试一个分布式系统……直到那时，这个词才开始对你有了意义。

这是写给那个仍然坐在课堂里的你。

田野里的一根石柱

想象一根老石柱，孤零零地立在田野里。周围什么也没有。它身上什么也没有发生。

这就是教科书定义给你的画面。只有石柱。

教授忘了画常春藤

顺便说一句，我的教授很好。教科书也没有撒谎。只是这幅画不完整。

现在，让常春藤长到石柱上。藤蔓拉扯着石头。鸟在上面筑巢。一个游客拿着记号笔。一次小地震。一场风暴。两百年的天气。

石柱还在那里。从它自己的角度看，什么都没发生。

这就是不变量。

现在再读一遍教科书里的那句话：在一个操作的每个检查点都成立的性质 P。石柱就是性质。常春藤就是操作。检查点，就是你路过并看一眼的那个时刻。成立只是用很长的方式在说：石柱并不在意常春藤。

你会在哪些地方不断遇见它

一旦你有了这根石柱，你就会开始到处看见它。

循环不变量。你的循环体是常春藤。你的不变量是石柱。循环体可以在某一刻把它弄乱，就像藤蔓拉扯石头一样。到了下一个检查点，石柱又回到了原来的位置。

数据库事务。在 BEGIN 和 COMMIT 之间，数据可以翻跟头。ROLLBACK 是那个走过来把常春藤扯掉的园丁。石柱，也就是你的一致状态，仍然站着。

ACID。外键。类型系统。分布式重试。全都是石柱。全都站在各自的常春藤里。

一根可以抱的石柱

还有一个小赠品，既然你还在读。

有一个兄弟概念叫 幂等性。一个幂等操作，就是你可以做很多次，而结果和只做一次一样。调用 ROLLBACK 十次，和调用一次一样。把灯的开关设成“开”十次，和设一次一样。

如果不变性是常春藤疯长时依然不变的石柱，那么幂等性就是你想抱多少次都可以、它也不介意的石柱。

把两者放在一起，你就得到了容错系统的黄金标准。网络断了？重试。服务器崩了？重试。你最终会落在一个有效状态里，而且可以继续重试，不会把任何东西弄坏。

一根既经得住常春藤，又经得住被抱上一千次的石柱。大多数现代基础设施都安静地建在这上面。

一个小结尾

这就是我希望十年前有人为我画出来的那幅图。

它不算多。一幅图而已。但有时候，一幅图就是一个概念住进你骨头里，和一个概念只住在脚注里的区别。

如果你是学生，或初级工程师，或只是一个已经对“不变量”这个词默默点头点了很久的人……这是写给你的。

石柱并不在意常春藤。就这么回事。

从一个不被看好的人，写给另一个。

所有科学相遇的地方

Sat, 18 Apr 2026 12:00:00 GMT

我不是数学家。我不是哲学家。我不是神经科学家。我只是一个喜欢思考的人……而我总是撞见各门科学在以为没人看的时候互相眨眼。

也许它们读的是同一本书。而最后一页是故意缺失的。

语言是一种非常高级的代码

二进制曾经是最低层的语言。然后是汇编。然后是 C。然后是一千种别的语言。每向上一阶，不过是用更短的方式说一件更长的事。

人类话语只是同一架梯子上的又一阶。我们把思想编译成词语。其他人在自己的头脑里把这些词语反编译回思想。编译器有损。永远有损。这就是它的本性。

一句话是一个高级程序。一个故事是一个系统。一句谚语是进化在很久以前写下的一个小小的缓存函数。

那扇不能从里面打开的门

你知道，哥德尔证明了一件既残酷又美丽的事。任何大到足够有趣的系统，都无法从自身内部证明自己的完备性。关于你，有些真实的事，你用自己的工具抵达不了。

塔斯基把它说得更锋利。任何语言里的“真”这个词，都需要一种更大的语言来承载它。你不能站在原地定义真理。你必须走出去。而你一走出去，就进入了一个有同样问题的新系统。

这是一条满是门的走廊。你打开一扇。后面还有一扇。

这是数学。但它也是心理学。它也是人类学。它也是两个人试图就一个词到底是什么意思达成一致，却永远差一点。

没有人是神谕者。不是我。不是你。不是你见过的最聪明的人。这不是一件悲伤的事。这就是那扇门。

彼此校准

两个人说话时，谁都不是神谕者。校准不是我纠正你，或者你纠正我。它是我们一起提问，去寻找“说出来的东西”和“真正想说的东西”之间那道看不见的缝隙。

真理不归任何人所有。真理是被三角测量出来的。

你是我的元语言。我是你的。我们彼此检查那些独自一人时看不见的不完备。

大脑并不懒

我们的大脑正在用它得到的能量尽力而为。它并不懒。它是一个优化器。进化并不是付钱让它正确。进化付钱让它靠一袋坚果和一个小湖活下来。

诀窍不是和大脑打架。诀窍是和它合作。

一个问题会把它点亮。一个问题是一顿小小的免费午餐。一个问题，是你不用喊叫也能叫醒疲惫头脑的方法。

这也是为什么总结是最难的艺术。总结，就是向材料提出一个问题，然后把所有不是答案的东西丢掉。

保加利亚开口说话

我们有一句谚语。Седем пъти мери, един път режи. 量七次，再切一次。

它说的不是要慢。它说的是，要知道一小时的思考，可以替你省下后来一整年的错误代码、错误的爱，或者错误的职业。思考很便宜。下刀很贵。

我们还有一句。Рибата винаги започва да мирише от главата. 鱼总是从头开始发臭。

如果顶端已经腐烂，下面的一切其实也已经腐烂了。只是它还不知道。

两句谚语说的都是哥德尔说过的话，只是穿着农民的衣服。你不能从内部证明自己。拿别的东西校验自己。拿别人校验。拿现实校验。

工程，但诚实一点

工程，只要你诚实地做，安静地就会变成哲学。

你永远是在根据一份不可能完整的规格建造东西。哥德尔已经向你保证过这一点。所以你学会为未知而设计，而不是假装它不存在。你再多问一个问题。你做出某种东西，等现实到来时它还能被修正。

我说的工程不是狭义的工程。我说的是建造任何必须经得住现实的东西的手艺。一个产品。一段关系。一个人生。手艺总是同一种。诚实的野心遇上诚实的限制。

这是智慧。不是书本里的智慧。是直视一个问题，然后说：我无法完全认识你。但我会建造某种东西，它仍然能承载你。

这大概就是工程能靠近智慧的最远处。

卓越就是行走

林登·B·约翰逊说：“今天最高贵的追寻，是对卓越的追寻。”

我以前以为卓越是一条终点线。不是。卓越是行走本身。量七次。再多问一个问题。尊重你正在制作的东西，也尊重你在制作它时正在成为的那个自己。

卓越不是你抵达的某个地方。卓越只是你不断提问时发生的事。

如果你不能讲给一个孩子听

如果你没法向一个孩子讲清楚它，你自己就没有理解。

大多数日子我都通不过这个测试。但失败很有用。如果我的解释很长，我还没有理解。如果我需要术语，我还没有理解。如果那个孩子离开时仍然困惑，那问题在我。不是孩子。

你看，孩子还不知道哪些问题照理不该问。孩子会问出那个你希望没人会问的问题。所以他们比我们大多数人都更靠近真相。

所有科学相遇的地方

数学承认不完备。语言学承认符号与事物之间有缝隙。神经科学承认大脑无法完全观察自己。哲学几个世纪以来一直在说这件事，不合时宜而耐心。人类学看着人类在一千块不同的泥地上画同一个圆。进化在耳边低语：你最好的思考仍然是猴子的思考，只是穿得体面了些。

它们在最深处都抵达同一个地方。它们站在一扇不能从里面打开的门前。

我现在说一件事，你愿意怎么理解都可以。

所有科学相遇的地方，就是神居住的地方。

不是某一本书里的神。不是某个特定名字的神。我只是说这个。在每一次诚实追问的边缘，都有一种并不空的寂静。有一种不可知之物，却仍以某种方式教导我们。

叫它神。叫它奥秘。叫它任何你的语言付得起的名字。它一直在那里。它从不逃走。而且它总是在那扇你不能从里面打开的门的另一边。

小小的结尾

这就是为什么我想这么多。这就是为什么我问那些我无法回答的问题。这就是为什么我不断制作东西，即使我知道那些东西永远不会完整。

因为不完备不是 bug。

它是那扇门。

而每一扇门的另一边，都有什么东西在等一个人去敲。

我还在学习敲门。

那个并不存在的模型

Sat, 14 Mar 2026 00:00:00 GMT

我们当时用 Gemini 3 Pro 生成广告图片。它在 Artificial Analysis 排行榜上排第 #4。质量确实令人印象深刻：提示词遵循度更好，排版更好，创意输出比我们试过的任何东西都好。Google 到处都在讲它。YouTube 视频。会议。研讨会。博客文章。“世界上最好的图像生成模型。”

我信了。图片确实好。

然后有个用户报告说，克隆一条广告要花四分钟。我查了。生成本身不到三十秒就完成。剩下那三分半钟呢？任务一直在撞墙重试。

Resource Exhausted.

Google 给 Gemini 图像生成加了硬上限：每分钟两个请求。按项目。全局。

两个。不是两百。不是二十。两个。

前一天我们生成了 900 张图，一点问题没有。他们那边有什么东西变了。没有通知，没有邮件，没有更新日志条目。只是突然多了一个新天花板，低到两个用户同时点击就能撞上。

我们的 DevOps 提交了配额提升申请。30 RPM。对一个生产 SaaS 来说很合理。Google 的回复是：

"This gemini model is not available for quota increase."

他们建议我们切到 Imagen 4。我查了一下。

Imagen 4 Ultra - 排名 #10。Imagen 4 Standard - #42。Imagen 4 Fast - #60。

我们用的是 #4。Google 的建议，是在他们自己的排行榜上往下退六到五十六名不等。

我把能想到的都试了。

切到 Gemini 3.1 Flash：排名 #2，成本减半，比我们现有的还好。部署到 staging。然后我查了配额。同样的 2 RPM 上限。它不是按模型算的。它是按项目、按基础模型家族算的。所有 Gemini 图像模型共用同一个配额池。

多区域分发：配额按区域计算，所以把请求分散到五个区域，可以得到 10 RPM。只不过 Gemini 3.x 图像模型只能走 global endpoint。没有 regional endpoints。global endpoint 上的 2 RPM，是唯一存在的配额池。

多个 GCP 项目：每个项目都有自己的 2 RPM。技术上可行。从架构上看，这就是绝望的样子。

我开始研究其他开发者遇到了什么。同一个故事到处都是。未记录的 2 RPM 限制。论坛帖子没有 Google 回复。配额提升明明批准了，每次调用仍然返回 429。我们每月 $30K 的 GCP 支出？没用。标准 PayGo 层明确把图像生成模型排除在吞吐量收益之外。

Google 不会提高这个限制。

接下来才是有意思的问题：为什么不？

Gemini 通过同一个处理文本的自回归 transformer 来生成图片。它不是扩散模型。它是完整的 LLM，一边推理一边逐像素走完整张图。每张图烧掉的计算量，相当于几十次文本 API 调用。

按每张 $0.067 的价格，Google 几乎肯定每生成一张就亏一张。2 RPM 上限不是他们忘了调整的配额。它是一次有意计算过的节流，因为经济账算不过来。

Imagen 4 用的是经典 latent diffusion，运行成本低几个数量级。所以它能拿到 30-150 RPM，而 Google 正把所有人往它那里推。昂贵的模型拿到营销。便宜的模型拿到吞吐量。

想想这意味着什么。Google 做出了一个登顶所有基准榜的模型。他们在每场会议、每个 YouTube keynote、每篇开发者博客里营销它。“最先进。世界第一。” 开发者把它接进生产。用户开始依赖它。然后：每分钟两个请求，不能提升，用我们的差一点的模型吧。

API 存在。Endpoint 能用。演示惊艳。

但你不能真正使用它。

我们切到了 gemini-2.5-flash-image。旧模型。无聊的那个。没人为它做 YouTube 视频的那个。

它有 40 RPM。它能用。

四个教训，压缩版：

营销不是产品。 登顶排行榜不代表你能承载生产流量。基准测试衡量质量。速率限制衡量承诺。
自回归图像生成无法规模化。 当生成一张图的成本相当于一百次文本查询时，没有商业模式能承受慷慨的速率限制。经济账就是破绽。
Preview 就是 preview。 Google 可以毫无通知地改限制、杀模型，或者把你导向更差的替代品。如果你的生产系统依赖 preview 模型，你的生产系统依赖的就是别人的营销日程。
无聊的模型能用。 那个有 40 RPM、没有会议演讲的模型，会服务你的用户；那个世界级模型则坐在红绒绳后面，每分钟生成两张图。

最吓人的供应商锁定，是从一个你无法抗拒的 demo 开始的。

那座并不存在的城市

Sun, 08 Feb 2026 00:00:00 GMT

我做了个东西，从一个来源拉数据，清理它，然后把它展示得比原站更好。标准工作。

然后我查询了系统里第二大的条目。其他所有条目都返回了几百个结果。这个：零。不是坏了。就是空的。

我以为是我搞砸了。把代码查了三遍。直接测了接口端点。这个条目在他们界面里存在。它只是……空心的。

就是从那时起，我开始往下挖。

那个来源看起来很完整。范围广，界面打磨过，API 干净。但自愿参与意味着会有一些洞，是你从文档里看不见的。

三个竞争对手都有同一批实体的数据。完整记录。所以信息在某个地方存在。

不是你缺少一个接口端点。是那个接口端点缺少现实。

我问了一个没人想到要问的问题：这些数据在互联网之前住在哪里？

答案是：印刷期刊。档案。自 19 世纪以来一直运行的模拟格式。每周出版三次。没有结构化数据，只有网站上的文档。

所以我下载了一份。密集的机构腔文本，公告埋在各个下属办公室之间。数据在那里。

我的竞争对手已经手工做这件事三十年了。

我用一个下午写了个爬虫。一半是好奇，一半是较劲。

文档解析才是真正开始疼的地方。

一个词会被软连字符切开：Unicode U+00AD，眼睛看不见，对每个 regex 都致命。你盯着屏幕，以为是自己的 pattern 错了。不是。文本里藏着一个幽灵字符。JavaScript 的 \w 不匹配非 ASCII 字符，所以普通单词会变成不可能命中的匹配。数字里有渲染器留下的幻影空格："20. 000"，而不是 "20.000"。

每个 bug 花在找到上的时间都比修复更久。文本抽取永远是这个比例：90% 侦探工作，10% 代码。

十条记录从噪声里显形。日期、标识符、地点，全都在该在的地方。我跑了两遍，确认自己不是在幻觉。结果一样。它真的能用。

解析让你看见那里有什么。我开始找那里没有什么。ID 是连续的。我把它们枚举了一遍。

53% 是死的。系统会清除已经结束的条目：没有档案，没有历史。有些记录存在，但没有任何支撑文档。答案是：请亲自来。2026 年了。

这个来源不是数据库。它是一扇窗口，而且有人一直在把它关上。

第一个数据源塑造了架构。第二个数据源击碎了每个假设。

我需要第二套架构。这是一种客气的说法，意思是第一套其实并不是架构，只是一个刚好适配某个场景的可用方案。那个奇怪的来源揭示了真相：你为手上已有的数据而建，不是为你将会遇见的数据而建。

这次我认真做了一套。Registry pattern，共享接口，基础契约，让每个实现都能忠于自己的形状。

这个架构更好，是因为我等了。如果我第一天就做它，我只会为我唯一认识的来源设计。第二个来源，那个奇怪的来源，逼我找出真正重要的东西。

你无法为未知设计。但未知抵达时，你可以重构。

架构教我怎么建。市场教我为了什么而建。

我要进入的是一个有三十年老牌玩家的市场。他们的技术看起来像 2005 年。他们的护城河不是技术，而是信任、品牌认知、几十年积累的数据。

那个现代竞争者三年前带着 AI 和漂亮 UI 入场。价格低于老牌玩家。三年后，老牌玩家仍然占主导。事实证明，更便宜并不自动意味着定位更好。

锚定很重要：第一个价格会成为参照点。之后降价容易，涨价几乎不可能。订阅本身不是产品，它只是通向背后东西的门。

我把价格定高。之后总能降下来。

四个教训，压缩版：

权威不等于完整。 主来源缺了整整一块。数据存在，只是不在任何人预期的地方。
第二个来源会显露你的架构。 只有当某个东西拒绝你建出的形状时，你才会知道设计的真相。
数据不是永久的。 如果你需要它，存下来。来源不会替你存。
为你正在变成的东西定价，而不是为你现在是什么定价。 订阅是一扇门。把门后面的东西建出来。

有意思的工作住在缝隙里。我也住在那里。

那个从未停下的队列

Sat, 07 Feb 2026 00:00:00 GMT

邮件在失败。这部分是预料之中的：迁移过程中 SMTP 凭据坏了。没预料到的是：它们从未停止失败。

Horizon 仪表盘：绿色。Worker：健康。Redis：慢慢变大。没有告警，日志里没有错误。只有一堆安静累积的任务，一次又一次又一次地重试。

我是因为修好 SMTP 配置以后，Redis 内存没有降下来才注意到的。里面还有什么东西，正在咀嚼那些重试。成千上万次。

我以为队列会处理好这件事。规则不就是这样吗：一个 job 失败，重试几次，落进 failed_jobs。然后你继续往前走。

除非这个 job 是一个 Mailable。

当你把一个 Mailable 分发到队列时，Laravel 会把它包进一个 job。这个 job 的 maxTries 来自 Mailable 的 $tries 属性。如果你没有设置它——你为什么会设置呢，文档几乎没提——它会被序列化成 null。

null 不是“使用 supervisor 默认值”。null 是“没有限制”。Horizon 看到 null，就会想：这个 job 想永远重试。于是它就这么做。

结果这是个已知 bug。Laravel Horizon issue #1346。当序列化后的 job payload 携带 maxTries: null 时，supervisor 的 --tries 标志会被忽略。job 自己的声明赢了，而它的声明说：永远不要停。

二十九个 Mailable 类。每一个都没有显式的 $tries 属性。每一个都可能不死。

修复简单到几乎有点冒犯：

class WelcomeEmail extends Mailable implements ShouldQueue
{
    public int $tries = 2;
    public int $maxExceptions = 2;
}

两个属性。二十九个文件。就这样。

一次初始尝试，一次重试，然后进 failed_jobs。就像我原本以为它一直会那样工作。

我测试它的方式像是在测试捕鼠夹。故意弄坏 SMTP 配置。分发一封邮件。看 Horizon。两次尝试。Failed job。结束。队列里没有幽灵。

然后我修掉另外二十八个。

三条教训，压缩版：

null 不是“默认值”。 在序列化的 job payload 里，maxTries: null 意味着无限。你的 supervisor 配置只是建议，不是规则。
绿色仪表盘会撒谎。 Horizon 显示 worker 很健康，正高高兴兴地处理永远不会结束的 job。
框架默认值不总是合理。 Laravel 不会在 Mailables 上设置 $tries。你必须自己设置。文档不会在火烧起来之前提醒你。

最吓人的 bug，是那些看起来像正常运行的 bug。这个就是——而且持续了好几个星期。

批量删除的核选项：TRUNCATE + 重新插入（MySQL/InnoDB）

Sat, 13 Dec 2025 13:00:00 GMT

你需要从一张 MySQL 表里删除数百万行。

你伸手去拿：

DELETE FROM big_table WHERE some_condition;

然后你看着进度条在现实时间里变老。

你试着负责任一点，分块删：

DELETE FROM big_table WHERE some_condition LIMIT 10000;
-- repeat until done

好一点。还是慢。还是吵。还是贵。

如果你要删除的是表里的大部分数据（经验线：约 80% 以上），还有一种做法，粗暴但有效：

不要删除你不想要的东西。保留你想要的，把剩下的炸掉。

我把它叫作核选项：TRUNCATE + 重新插入。

为什么 `DELETE` 还是慢（即使分块）

InnoDB 并不是“移除”行。它是在干活。

很多活：

逐行操作：定位、加锁、标记为已删除。
索引维护：每一次删除都会触碰每一个二级索引。
Undo/redo 日志：引擎必须保留回滚和恢复的能力。
Buffer pool 翻腾：你不断把页面弄脏，驱逐有用的页面。
复制影响：大规模删除流是制造 replica lag 的好方法。

餐巾纸背面的现实检查：

2700 万行，约 6000 行/秒 ≈ 75 分钟。

这不是 bug。这是你选择的成本模型。

核选项：TRUNCATE + 重新插入

这个技巧会把成本模型翻过来。

你不再为每一行被删除的数据付费，而是为每一行被保留的数据付费。

算法：

1) Copy the rows you want to keep into a temporary table
2) TRUNCATE the original table (fast)
3) Insert the preserved rows back into the original table
4) Drop the temp table

是的：它被叫作“核”是有原因的。它刻意钝重。

为什么它快

收益是机械性的：

Operation	Rough cost	Why
`TRUNCATE`	~O(1)	drops and recreates the table (metadata-level)
`CREATE TABLE … AS SELECT`	O(k)	sequential scan + bulk write for kept rows
`INSERT … SELECT`	O(k)	bulk insert; no “delete tax”

没有逐行删除开销。被移除的行也没有索引更新（因为它们一次性没了）。

什么时候用它（以及什么时候别用）

适合用在

你要删除表里的大部分数据（还是那条线：约 80% 以上，这时它开始发光）。
你能清楚定义“要保留的行”。
你可以接受短暂不可用 / 维护窗口。
这张表没有被其他表的外键活跃引用（或者你能安全地管理约束）。
你有足够的磁盘空间放临时表。

不要用在

你需要零停机。
这张表被你不能碰的外键大量引用。
你必须触发 DELETE triggers。
你只删除少数行（分块 delete 可能是更简单的胜利）。

一个实用的决策规则

如果你想在评审里用一句话说清楚：

如果这次删除会移除表里的大部分数据，就停止删除。保留并重建。

或者，如果你更喜欢 ASCII：

How much are you deleting?

< 50%     -> chunked DELETE (and index-aware filters)
50–80%    -> measure both approaches
> 80%     -> TRUNCATE + reinsert (if constraints allow)

实现（SQL）

最小形状是这样：

-- 1) Preserve the rows you want to keep
CREATE TABLE temp_preserved AS
SELECT * FROM big_table
WHERE preserve_condition;

-- 2) Nuke the table
TRUNCATE TABLE big_table;

-- 3) Restore preserved rows
INSERT INTO big_table
SELECT * FROM temp_preserved;

-- 4) Cleanup
DROP TABLE temp_preserved;

生产里有两点很重要：

在 MySQL 里，TRUNCATE 是 DDL。它会隐式提交，不能像普通事务那样回滚。
你需要维护窗口和备份。这不是“上线试试看”的东西。

实现（Laravel/PHP）

这是我在需要时实际会用的版本：

protected function deleteViaTruncateAndReinsert(
    string $connection,
    string $tableName,
    string $preserveCondition
): int {
    $tempTable = "temp_preserved_{$tableName}_" . time();

    // You're about to do DDL. Be explicit that you're taking control.
    DB::connection($connection)->statement("SET FOREIGN_KEY_CHECKS=0");

    try {
        DB::connection($connection)->statement("
            CREATE TABLE {$tempTable} AS
            SELECT * FROM {$tableName}
            WHERE {$preserveCondition}
        ");

        $preserved = DB::connection($connection)->table($tempTable)->count();

        DB::connection($connection)->statement("TRUNCATE TABLE {$tableName}");

        DB::connection($connection)->statement("
            INSERT INTO {$tableName}
            SELECT * FROM {$tempTable}
        ");

        DB::connection($connection)->statement("DROP TABLE {$tempTable}");
    } finally {
        DB::connection($connection)->statement("SET FOREIGN_KEY_CHECKS=1");
    }

    return $preserved;
}

一点橡皮鸭能量：再读一遍这个函数，问问未来的自己：

“我确定这张表可以短暂清空一下吗？”

如果答案不是毫不含糊的“是”，这就不是你的工具。

你必须考虑的坑

自增值会重置

TRUNCATE 会重置 AUTO_INCREMENT。如果你需要保留它：

SELECT MAX(id) FROM big_table;
ALTER TABLE big_table AUTO_INCREMENT = <max_id + 1>;

外键

如果其他表引用这张表，TRUNCATE 可能会被禁止，或者不安全。不要“先把 checks 关了”然后祈祷。

触发器

TRUNCATE 不会触发 DELETE triggers。如果你需要触发器的副作用，那你又回到了 DELETE。

磁盘空间

你需要给被保留的数据集（临时表）留出空间。先检查：

SELECT
  ROUND(data_length / 1024 / 1024 / 1024, 2) AS data_gb,
  ROUND(index_length / 1024 / 1024 / 1024, 2) AS index_gb
FROM information_schema.tables
WHERE table_schema = DATABASE()
  AND table_name = 'big_table';

复制 / binlog

这是 DDL + 批量插入。它仍然可能造成 replica lag。要有意识地做，监控 lag，不要假装它免费。

如果你需要（接近）零停机

这篇文章讲的是一把很快的锤子。

如果你需要手术刀，用那些本来就是为此而造的工具：

pt-archiver（Percona Toolkit），用于带有复制友好节奏的分批删除
分区策略（删分区，而不是删行）
shadow-table 方案 + 受控 swap（更复杂，活动部件更多）

结尾想法

这不是什么聪明小技巧。它是在选择你要为哪种工作付费。

Type 0 重构：第一步之前的那一步

Sat, 13 Dec 2025 12:00:00 GMT

有一类重构，团队一直在做，立刻从中受益，却几乎从不给它命名。

它是你碰那个吓人的文件之前要做的活。功能需求把你逼进那个混乱模块。事故来了，bug 藏在一个看起来自带天气系统的方法里。

你不是在重新设计系统。你不是在引入新的抽象。你也不是用某种聪明方式“改进”任何东西。

你只是把代码弄到足够可读，让你能开始工作。

我开始把这叫作 Type 0 重构。

Type 0 重构是一种预备性的、保持行为不变的清理，它让代码在你做架构重构、性能工作或功能工作之前，先变得更容易推理。

它就是“重装厨房之前，先把地板擦干”的那一步。大多数团队已经在非正式地做它。给它一个名字，它就变成了一个共享工具。

Type 0 存在的真正原因：人的工作记忆有预算

这个想法背后的直白真相是：

我的大脑（你的也是）并不是为了在时间压力下可靠地调试一个 2000 行方法而设计的。

这不是个人缺陷。认知就是这样工作。

调试要求你同时把这些东西放在脑子里：

当前执行路径
相关状态
每个变量实际意味着什么
可能分支的集合
“如果发生这个，那么……”的后果

在小代码里，这还可控。

在大代码里，再加上高圈复杂度，它就变成了概率性猜测。你仍然可能走运，但成本高，风险也高，尤其是在 hotfix 期间。

Type 0 是一个实际回应：它让你快速购买清晰度，而不承担“真正重构”的成本和风险。

为什么叫 “Type 0”

这个名字不是从什么宏大理论里来的。它来自一个高压时刻。

我当时在做一个 hotfix。bug 被埋在一个方法里，而那个方法实际上就是自己的小宇宙——大约 2000 行。

bug 在概念上并不难。难的是这个方法。

每一个“如果……会怎样”都会分裂成十个更多的问题，而那些分支并不是有用的那种。那是偶然复杂度：噪音、重复、不清楚的命名，以及和调试所需心智模型不匹配的结构。

我需要的不是完美。我需要的是可调试性：

每屏更少的分支
更清楚、有名字的“步骤”
更少的噪音
更少时间重新解析刚刚读过的东西

但时间压力不允许更大的重构，也不允许一次“惯用写法的重新设计”。负责任地做那件事要半天（甚至更多），还包括手动测试。在 hotfix 窗口里，那不是纪律；那是赌博。

于是我让一个 LLM 为这个类和这个方法建议重构机会——没告诉它原因。

它回来给了我一份四种“类型”重构的列表。都合理。都适用。也都对那个时刻来说太贵。

然后它礼貌地问：

“Should I start with Type 1?”

那时我回复：

“No. Let’s start with Type 0.”

我当场定义了 Type 0：一组受约束、机械性的修改，用来降低复杂度、提高可读性，但不改变行为或架构。

那个方法变得可以导航了。我的大脑又能跟上执行路径了。我找到了 bug，修掉了它，并且没有带着附带伤害发布。

这就是我喜欢 Type 0 这个名字的原因：它是你在“真正重构”类型之前做的重构——尤其是在你有压力，需要一种安全方式快速创造清晰度的时候。

Type 0 解决的问题

大多数重构建议都假设你已经能_看见_设计。

在真实代码库里：

方法很长，而且承担多种目的
重复表达式和偶然复杂度藏住了意图
变量很隐晦（$e、$tmp、$res）
死代码和未使用 import 制造心智噪音
代码的“形状”乱到连小改动都让人觉得危险

当你在这上面尝试“真正重构”（边界、模式、移动职责）时，你是在不确定性上堆更多不确定性：

你不容易判断自己正在保留什么行为
你无法预测爆炸半径
review 会退化成主观争论
人们开始害怕碰这些东西，而混乱继续复利

Type 0 是你先降低认知负荷的方法。 它创造一个稳定基础，让更深的工作可以安全发生。

什么时候拿起 Type 0

Type 0 在这些情况下最有价值：

你必须快速调试（hotfix、事故），而代码太大 / 分支太多，无法安全推理
你觉得自己“迷失在方法里”，反复重读同一段，因为结构帮不上你的工作记忆
代码是正确的，但不可读；你承担不起“清理逻辑”，只能把逻辑暴露出来
你想在更深工作之前降低风险（你知道之后会重构，但首先需要当前行为的清晰地图）
你想把部落知识变成可读结构，让调试不再依赖某一个人

Type 0 不是奢侈品。在这些场景里，它常常是最快重新拿回控制权的方法。

一个可以给团队使用的定义

Type 0 重构是一组微重构，用来在不改变行为或架构的前提下提升可读性和可维护性。

它刻意受约束。约束就是这个特性本身。

Type 0 包含四个强制子模式：

0a. 方法提取
0b. 简洁性
0c. 同理心（纯可读性）
0d. 删除死代码

并遵守三条硬规则：

不改变行为
不改变架构
除了这四种模式之外，不做“聪明”的改进

如果你违反这些规则，你做的就不再是 Type 0——你已经进入了另一类工作，而那需要不同的协调、不同的 review 严谨度，通常也需要不同的测试策略。

为什么非要命名？

因为命名会改变团队协作的方式。

“这个 PR 里我只做 Type 0”会告诉 reviewer 该看什么：行为保持和可读性，而不是架构争论。
“我们需要先对这里做 Type 0，再重构”是在诚实承认代码还没准备好承接更深的改变。
“我们把 Type 0 当作 Step 0 来做”创造了一个小仪式，防止你在混乱之上继续搭东西。

四个子模式

0a. 方法提取（基础）

目标： 把大方法拆成小而聚焦的方法，让人可以线性读懂意图。

经验规则：

拆解那些长到无法放进工作记忆的方法
每个提取出来的方法应该只做一件事，并且有描述性的名字
提取有意义的步骤，而不是任意 N 行代码块

为什么它有效（尤其对调试）：

小方法为执行路径创造标签
2000 行滚动变成一个短的编排方法，你可以在脑子里逐步走过
你可以在语义边界上打断点（“验证输入”、“构建查询”、“应用过滤器”），而不是到处狩猎

0b. 简洁性（减少偶然复杂度）

目标： 移除视觉噪音，让意图浮出来。

例子：

把重复表达式提取成局部变量
把重复的日志上下文 / key 字符串 / URL 片段提取成变量
优先使用能直接表达意图的语言特性
简化过度冗长的插值

为什么它有效：

它降低认知负荷
它让 diff 更小，改动更安全
它防止复制 / 粘贴漂移

0c. 同理心（纯可读性）

目标： 写给下一个人看，而不是写给编译器看。

同理心意味着：

使用描述性变量名（避免 $e、$d、$tmp，除非真的显而易见）
在一个模块内保持术语一致
重命名具有误导性的名字
让代码自我说明

试金石：

如果有人在凌晨两点的事故中读这段代码，它会帮助他们把执行路径放在脑子里吗？

0d. 删除死代码（移除谎言）

目标： 删除所有假装重要、其实不重要的东西。

例子：

未使用的 private 方法
未使用的 imports
注释掉的旧方案
已废弃且没人调用的 helpers

为什么它有效：

代码越少，误解的东西就越少
搜索结果会变得可信

Type 0 不是什么

Type 0 不是：

改变服务边界
引入新的抽象或模式
重新架构一个 workflow
替换库
在层之间重新分配职责
“修复”你怀疑有错的逻辑（除非你明确声明这是行为改变，并测试它）

如果你发现自己在说：

“既然我在这里，不如也……”
“如果我们这样会更好……”
“我们大概应该重新设计……”

你可能正在离开 Type 0。这本身不坏——但应该是有意为之。

核心承诺：保持行为不变（以及如何让它是真的）

Type 0 只有在团队信任这个承诺时才有效。

而且是的，你怀疑得对：方法提取可能意外改变行为（early returns、变量作用域、求值顺序、异常行为）。

所以 Type 0 需要纪律来保持诚实：

照原样提取，然后再重命名 / 清理。

第一遍：把代码移进方法，不改变逻辑
第二遍：应用简洁性 + 同理心
第三遍：删除死代码

实用护栏：

不要为了“可读性”重新排列条件检查
不要用“等价”逻辑替换逻辑，除非你已经在 Type 0 之外
小心那些原本在共享作用域里的变量
把“小的”控制流差异当作真正差异看待

如果你有任何安全网，哪怕很薄：

跑一个聚焦测试
重放失败场景
验证你正在触碰的那一条路径

Type 0 讲的是快——但这种快来自降低认知复杂度，不是来自跳过安全。

把 Type 0 变成可重复的团队仪式

1) 决定范围（timebox 有帮助）

例子：

“调试前先对 hot path 做 Type 0。”
“只对这个 bug fix 会碰到的路径做 Type 0。”

2) 找到代码的“脊柱”

找到入口方法和分支点。通过提取，把这条脊柱变成一个可读叙事。

3) 按顺序应用四个子模式

方法提取 → 简洁性 → 同理心 → 删除死代码。

4) 在 PR 里保留一个 “Type 0 checklist”

不改变行为（输入 / 输出不变）
不做架构移动
方法已提取，并命名为有意义的步骤
重复表达式已在能提升清晰度的地方提取
变量已重命名；术语一致
死代码和未使用 imports 已删除

结尾想法

Type 0 重构是开发者可以作出的最简单承诺：

“我会让这段代码比我发现它时更容易工作——同时不改变它做的事。”

有时候它是“有就更好”。

有时候，它是人在高复杂度混乱里安全快速移动的唯一办法——尤其是在 hotfix 期间。

多洗一个盘子：让代码库长期保持干净的一条简单规则

Thu, 24 Jul 2025 00:00:00 GMT

TL;DR：把你对代码库做的每一次修改，都当成做一顿饭。你会弄脏几个盘子。结束时，不要只洗掉你用过的那些——再多洗一个。时间久了，这一点点多出来的照料，会复利成一个保持干净、而不是滑向混乱的厨房（代码库）。

这个隐喻：做饭、盘子和代码

想象一间专业厨房。每做一道菜都会弄脏几个盘子，哪怕是最整洁的后厨团队也一样。现在想象，每个厨师做完自己的菜后，都刚好洗掉自己弄脏的盘子。厨房会悬在可接受的清洁边缘，但熵会慢慢爬进来：这里一点残留污垢，那里一块沾了渍的砧板。最后，混乱会复合增长。

现在把规则反过来：做完饭后，每位主厨都比自己弄脏的盘子多洗一个。慢慢地，厨房会比之前更干净，不只是被维持住，而是被改善。软件也是一样：你接手的每个任务，都应该给代码库至少增加一点点额外的整洁——多一个测试、更清楚的名字、拆开一个函数、移除一个死依赖。这个 "+1 plate" 的习惯，就是代码库保持健康的方式。

我把它叫做多洗一个盘子规则。

手艺里的回声：你并不孤单

这不是一种孤零零的哲学。几十年来，软件行业的思想领袖一直在讲类似的东西：

"Always leave the campground cleaner than you found it." 这就是经典的 Boy Scout Rule，由 Robert C. Martin 在软件领域推广。精神相同：每次都改好一点。
技术债这个隐喻（Ward Cunningham）：债会产生利息。忽视它，明天使用这间"厨房"的成本就会更高。边走边还掉一些，才能保持偿付能力。
重构作为小而持续的步骤（Martin Fowler）：微小的改动，保持行为不变，同时改善设计。小步意味着低风险和稳定动量。
"Make it work, make it right, make it fast"（Kent Beck）：先正确，再干净，再性能。多洗那个盘子发生在 "make it right" 阶段，也就是你过早优化之前。
把破窗理论应用到代码（Andrew Hunt & David Thomas）：可见的混乱会邀请更多混乱。在它扩散之前修好一扇"窗"，是在保护这个街区（代码库）。

这些想法互相强化。它们说的是同一句话：不要把混乱传下去；花一点时间，让它好一点。

为什么多洗一个盘子重要（即使你很忙）

1. 熵是真实存在的

如果没人照看，代码不会保持中性。命名会漂移，模式会碎裂，抽象会腐烂。熵是一种力量；唯一的反作用力，是持续、增量的整理。你的 +1 plate，就是微型的熵逆转。

2. 债务复利得比你想的快

每一句"以后再修"，都会提高变更成本。以后很少真的到来。利息会表现为变慢的功能开发、脆弱的部署，以及没人信任的测试套件。今天多洗一个盘子，会降低明天的利率。

3. 社会信号

当队友看到你会收拾自己留下的东西（还多收拾一点），规范就会移动。让代码比接手时更好，会变得可信，也会变成期待。文化跟着行为走。

4. 动量，不是完美主义

这不是 yak shaving 的借口。你不是在午餐高峰时重建整间厨房。你只是拿海绵再擦一个盘子，小、安全、快。关键就在这里：交付不会因此脱轨。

如何实践多洗一个盘子规则

下面是把这个习惯嵌进去的方法，不拖偏 scope，也不撞坏 deadline。

1. 把"微重构"纳入 Definition of Done

重命名一个令人困惑的变量。
提取一个小函数，降低圈复杂度。
删除死代码或未使用的 imports。
为你刚修好的 bug 补一个缺失测试。
更新一段让你刚才心里一紧的文档或 README。

判断标准是：如果它需要超过几分钟，那就不是一个盘子，而是整台洗碗机。推迟它。 把它记录成 ticket。

2. 用 Pull Requests 触发清洁

每个 PR 都可以让营地更干净：

要求一个"你清理了什么？"的 checkbox 或简短说明。
鼓励 reviewer 在 review 时请求一些小整理。
庆祝包含额外打磨的 PR（standup 里点名表扬，作用很不小）。

3. 自动化那些容易洗的盘子

用 pre-commit hooks 做格式化和 linting。
用静态分析标记复杂方法或过长参数列表。
用依赖检查工具找出过时库。

让自动扫帚清掉琐碎的脏东西，好让人专注在逻辑和设计上。

4. 把它嵌进团队规范

把这条规则写进团队 working agreement 或 engineering handbook。
如果你想要可衡量的证明，在 retro 里跟踪微重构 wins。
偶尔 pair 或 mob program，让这个习惯（以及勇气）传播开。

5. 知道什么时候不要洗

有时候厨房着火了：生产环境挂了，或者 demo 只剩几小时。紧急情况下，该砸那叠脏盘子就砸。但危机后要回头处理。这条规则不是教条，而是纪律。

边界：一个盘子，不是整个水槽

Scope creep 会伪装成 craftsmanship。你的工作是在"多洗一个盘子"那里停下来。如果这个小重构暴露出更深的味道，写下来，然后继续走。把更深的修复停到停车场：

创建一个带 refactor: 或 techdebt: 标签的 ticket。
链接到相关代码、测试或模块。
加一句为什么它重要。

你的职责已经完成：你看到了脏东西，洗了一个盘子，并给剩下的部分留下了说明。

示例：把一个混乱函数变成可测试的函数

之前：

function processOrder($order) {
    if(!$order->id) throw new Exception('No ID');
    $tax = 0;
    if ($order->country === 'BG') {
        $tax = $order->total * 0.20;
    } else if ($order->country === 'DE') {
        $tax = $order->total * 0.19;
    }
    // Lots more branching...
    // Sends email, writes to DB, calls payment gateway…
}

洗掉的那个盘子：

/**
 * Calculate VAT for an order based on country.
 * Pure function: given (total, country) -> VAT amount.
 */
function vatFor(string $country, float $total): float {
    return match($country) {
        'BG' => $total * 0.20,
        'DE' => $total * 0.19,
        default => 0.0,
    };
}

现在你的主函数调用 vatFor()，而不是把逻辑内联进去。你还给 vatFor() 加了一个微型测试。这就是一个额外的盘子：简单、收束、有用。

最后的想法

多洗一个盘子很小。这正是重点。让代码库保持健康，不需要英雄式重构；需要的是一种小而持续的照料文化。把它变成习惯，烤进流程里。一年后，你会奇怪为什么你的厨房不是灾难现场——因为你从没让它变成那样。

行动建议：下次你碰一个文件时，问自己："在提交这个变更前，我还能多洗哪一个盘子？" 然后做掉。重复。一次一个干净盘子，改变文化。

来源与延伸阅读

Robert C. Martin（"Uncle Bob"）— Boy Scout Rule： 97 Things Every Programmer Should Know 中的 "The Boy Scout Rule"。
Ward Cunningham — Technical Debt Metaphor： Cunningham 对 Technical Debt 的原始解释，收录在 Martin Fowler 的网站上。
Martin Fowler — Continuous Micro-Refactoring： Fowler 的书 Refactoring: Improving the Design of Existing Code。
Kent Beck — "Make it work, make it right, make it fast"： Ron Jeffries 对这句箴言的解释。
Andrew Hunt & David Thomas — Broken Windows in Software： 这个概念详见他们的书 The Pragmatic Programmer。
Software Entropy & Maintenance： 这篇 "Entropy in Software and the Broken Window Theory" 也值得一读。

PHP 8.5：即将到来的功能巡览

Sun, 20 Jul 2025 00:00:00 GMT

TL;DR 热度阶梯（我的玩心排名）

Pipe Operator（|>） – 可读、线性的转换幸福感。重构磁铁。
#[\NoDiscard] Attribute – 把“忘了使用返回值”变成即时警告。和 pipes 配得很漂亮。
Static Closures / First-Class Callables in Constant Expressions – 编译期 strategy maps 和 attribute arguments。框架糖果。
php --ini=diff – 立即看到环境配置漂移的 diff。让你少钻配置洞。
Attributes on Global & Class Constants – 元数据无处不在（flags、deprecations、semantic tags）。
array_first() / array_last() – 明确、表达意图、非 mutating。再见，reset() 副作用。
get_exception_handler() & friends – 面向分层错误处理的 introspection（框架/基础设施层面的胜利）。
Intl Goodies（IntlListFormatter、Locale::isRightToLeft()） – 几乎不用写代码，就能让本地化 UX 更顺。
Grapheme-aware Levenshtein – 真正尊重人类字符的用户侧 fuzzy matching。
Directory Object + cURL / Build Introspection / Misc – 一致性和可运维性的打磨。

（是的，你的顺序可以不一样。乐趣就在这里——拿咖啡辩一辩。）

1. Pipe Operator（`|>`）– “Easy Peasy Lemon Squeezy”

嵌套调用和临时一次性变量？没了。pipe operator 会把左边的值作为第一个参数喂给右边的 callable。你从上到下读，逻辑像散文一样流动，意图直接拍到脸上。

之前（变量跳房子）：

$email = $request->string('email');
$email = trim($email);
$email = strtolower($email);
sendEmail($email);

之前（括号套娃）：

sendEmail(strtolower(trim($request->string('email'))));

之后（pipe 禅）：

$request->string('email')
    |> trim(...)
    |> strtolower(...)
    |> sendEmail(...);

为什么重要：

可视化数据流。 不用在脑子里维护一叠嵌套返回值。
和小而纯的 helper 配合得很好。
鼓励把转换拆成命名函数/closure。
自动满足 #[\NoDiscard]，因为值会继续往下流。

风格提示： 让每个阶段都没有 side effect；把最后一个 pipe 留给效果（比如持久化、发送、emit），这样你能一眼看见“纯度”在哪里结束。

2. `#[\NoDiscard]` – 武器化的意图

多少细微 bug 其实只是“我们调用了那个东西，但忘了用它的返回值”？给函数或方法标上 #[\NoDiscard]，就能要求它的结果必须被使用，或者通过 (void) cast 明确表示有意忽略。

#[\NoDiscard("Token must be used – did you forget to persist or dispatch?")]
function issueAuthToken(User $user): string {
    return generateTokenFor($user);
}

issueAuthToken($user); // ⚠ Emits warning in 8.5
(void) issueAuthToken($user); // Explicit intentional discard

模式：

Result objects（Result、Outcome、ValidationReport）。
Immutable builders（每次调用返回新实例）。
Security / side-effect gating（tokens、signatures）。

协同： 在 pipeline 里，每个阶段的返回值天然会被下一个阶段消费，所以意外丢弃会消失。

3. Static Closures in Constant Expressions – “Wait… what?!”

现在你可以把 static closures（或 first-class callables）嵌进 constant expressions、默认属性值、attribute arguments 和默认参数数组里。想象一下：编译期 registry，不需要启动期接线体操。

class Sanitizers {
    public const STAGES = [
        'trim' => trim(...),
        'upper' => static function (string $v): string { return strtoupper($v); },
    ];
}

// Attribute example
#[Validate(
    rules: [
        'title' => static function(string $v){ return mb_strlen($v) > 0; },
        'slug'  => static function(string $v){ return preg_match('/^[a-z0-9-]+$/', $v); },
    ]
)]
class Article {}

为什么它很有劲：

为简单策略消除 service-locator lookup。
把纯 mapping table 推进 constants（immutable + cacheable）。
Attributes 现在可以直接封装逻辑，不只是 scalar metadata。

限制： 必须是 static；不能有 $this，不能捕获变量。如果需要 context，后面显式传进去。

4. `php --ini=diff` – 配置漂移 X 光

受够了*“但它在 staging 上能跑”*？这个 CLI flag 只打印和默认值不同的 INI directives。

php --ini=diff
# memory_limit: "128M" -> "-1"
# max_execution_time: "30" -> "0"

使用场景：

CI step，用来强制一致 baseline。
worker 表现古怪时快速 sanity check。
排查内存/时间异常。

Pro tip：把输出纳入版本控制，作为 runtime baseline。

5. Attributes on Global & Class Constants – 元数据无处不在

Constants 从“笨值”升级为“带注解的参与者”。把 domain flags、feature toggles、deprecation notices、unit semantics 直接装饰在定义处。

#[Deprecated("Use FEATURE_NEW_PRICING instead")]
public const FEATURE_OLD_PRICING = 1;

#[Unit("ms")]
public const DEFAULT_TIMEOUT = 250;

框架可用之处： 自动发现 deprecations、喂给 feature catalogs、生成文档，或者通过 reflection 执行 policy。

6. `array_first()` / `array_last()` – 显而易见的东西终于存在了

别再为了看一眼首尾而表演指针杂技（reset()、end()）或切片了。这些 helper 直接读出意图，而且不会改变数组内部状态。

$firstUser = array_first($users, default: null);
$lastUser  = array_last($users, default: null);

重构模式： 搜 reset( / end( / 复杂的 array_slice(..., 0, 1)，替换成语义化调用。diff 更干净，微型 bug 更少。

7. `get_exception_handler()`（以及更好的 Fatal Traces）– 可观测性升级

框架/基础设施开发者可以庆祝一下了：现在可以 introspect 当前活动的 exception handler。你可以 chain、wrap、restore 或 decorate，不用脆弱地摆弄全局状态。

$previous = get_exception_handler();
set_exception_handler(function(Throwable $e) use ($previous) {
    logToSentry($e);
    if ($previous) { $previous($e); }
});

再配合更丰富的 fatal error stack traces，生产 post-mortem 会快很多。

8. Intl Enhancements – 对人友好的列表和方向

IntlListFormatter 可以渲染优雅、locale-aware 的 conjunctions/disjunctions，不用手写胶水逻辑。

$f = new IntlListFormatter('pt_PT', 'conjunction');
echo $f->format(['Lisboa', 'Porto', 'Coimbra']); // "Lisboa, Porto e Coimbra"

$fOr = new IntlListFormatter('en_US', 'disjunction');
echo $fOr->format(['apples', 'bananas', 'cherries']); // "apples, bananas, or cherries"

结合 Locale::isRightToLeft()（或 locale_is_right_to_left()），可以自动切换布局方向。

9. Grapheme-Aware Levenshtein – 真实用户字符串距离

当用户输入 emoji、重音符、组合字符时，按 byte 或朴素 codepoint 算距离都会撒谎。grapheme_levenshtein() 尊重的是可见字符。

grapheme_levenshtein('café', 'cafe'); // 0 – visually same after accent

搜索建议、fuzzy match 和容错登录流程会变得更符合语言现实。

10. 打磨巡游

Directory Object： opendir() 现在会给你一个真正的 object（type safety、未来扩展），不再是 legacy resource。

cURL Enhancements： 更好的 share handles + multi-handle introspection = 长生命周期 worker（想想 RoadRunner、Swoole）里更好的连接复用，以及更细粒度的性能调优。

PHP_BUILD_DATE： 快速检查“这个 binary 有多旧？”的工具，适合审计脚本。非常适合确保 fleet nodes 没有悄悄落后。

Feature Synergy Cheat Sheet

目标	组合
带强制使用的 transformation pipeline	`	>`+`#[\NoDiscard]`
声明式 validation / strategy maps	Constant-expression static closures + constant attributes
更安全地重构 legacy arrays	`array_first()/array_last()` + strict return typing
生产事故排查	Better fatal stack traces + `php --ini=diff` + `get_exception_handler()`
国际化 UX 打磨	`IntlListFormatter` + direction detection + grapheme distance

Practical Adoption Plan

逐步引入 Pipe Operator：从纯数据 normalization 层开始；在 code review 里建立风格约束（一条 pipeline 只在尾部有一个 side effect）。
给关键 API 标注 #[\NoDiscard]：先关注 security、persistence 和 builders，在 CI 里测 warning counts。
重构 Strategy Tables：把简单 callable maps 移进带 static closures 的 public const arrays，获得零启动成本。
Config Drift Checks：加一个 CI job 捕获 php --ini=diff 输出；对异常变更报警。
Metadata Sweep：用 deprecation / units / feature flags 标注 constants，喂给内部工具。
Array Edge Extraction Cleanup：用 codemod 替换操纵指针的模式。
Error Handler Layering：用 get_exception_handler() 包住现有全局 handlers，提升可观测性（Sentry/new relic instrumentation）。
i18n Enhancements：把手写 “list glue” 换成 IntlListFormatter；测试 RTL 布局自动选择。
Fuzzy Matching Quality：在出现用户生成的多语言文本处（搜索、标签）benchmark grapheme vs classic distance。
Runtime Audit Script：每天记录 PHP_BUILD_DATE + php --ini=diff，用来发现老化的 containers。

Pitfalls & Gotchas

项目	小心什么	缓解方式
Pipe operator misuse	pipeline 中途有 side-effects	限制到 pure funcs，直到最后阶段
`#[\NoDiscard]` overuse	噪音疲劳（warning blindness）	只用于语义上关键的返回值
Static closure limits	需要 captured context	显式传 context，或用返回 closure 的 factory
Constant attributes sprawl	元数据碎片化	建立内部 attribute 命名约定
i18n list formatting	假设了标点样式	每个 locale 做 snapshot tests

“Show Me” Mini Playground

#[NoDiscard("Hash must be stored or compared")]
function password_hash_safe(string $plain): string {
    return password_hash($plain, PASSWORD_DEFAULT);
}

function sanitize_email(string $raw): string { return strtolower(trim($raw)); }

$request->string('email')
    |> sanitize_email(...)
    |> fn($email) => (strlen($email) > 5 ? $email : throw new InvalidArgumentException('Too short'))
    |> sendEmail(...); // Each stage consumes prior result – no discard.

class Rules {
    public const VALIDATORS = [
        'title' => static function(string $v){ return $v !== ''; },
        'slug'  => static function(string $v){ return (bool) preg_match('/^[a-z0-9-]+$/', $v); },
    ];
}

foreach (Rules::VALIDATORS as $field => $check) {
    if (! $check($data[$field] ?? '')) {
        throw new RuntimeException("Invalid $field");
    }
}

什么时候不要伸手拿发亮的新东西

一个简单到不行的 transform？ pipe 可能有点过头；strtolower($x) 仍然没问题。
Context-heavy closures？ 带 dependency injection 的常规方法 > static closure hacks。
Legacy codebase mid-upgrade？ 一次只引入一个功能，避免认知翻搅。

Mental Model Recap

功能	核心心智模型
`	>`	Linear value threading；消除 nesting 和 temp vars
`#[\NoDiscard]`	强制有意消费（使用，或用 `(void)` 忽略）
Static closure constants	加载时准备好的 immutable strategy registry
Attributes on constants	面向 tooling 和 policies 的一等 metadata channel
`array_first()/last()`	声明式、非 mutating 的边缘访问
`php --ini=diff`	相对默认 baseline 的 config delta lens
`get_exception_handler()`	Introspect 并 wrap 全局 exception flow
Intl additions	用内建 locale intelligence 替代手写 glue
Grapheme distance	对人眼感知的字符做操作，而不是原始 codepoints
Build & resource polish	渐进式 standardization 和 introspection

Final Vibes

PHP 8.5 没有用范式转变冲你大喊大叫；它是在低声给出一连串不屈不挠的人体工学改进。只看 pipe operator + #[\NoDiscard] 这个组合，就会把代码轻轻推向更清晰的意图。再撒一点编译期 closures 和 constant attributes，你的 frameworks/components 会变得更声明式、更明确、更容易发现。砰砰砰，发吧。

轮到你了： 选一个功能（大概率是 pipe），在一个小模块里外科手术式地应用它，在 code review 反馈里衡量清晰度，然后扩展。动量胜过 big-bang rewrites。

保持玩心，勇敢重构。是的，在遇到那些 “Wait, WHAT?!” 时刻时，也给你的 Taylors 发条消息。

Happy coding.

什么才是“好的”代码覆盖率？一份现实世界指南

Tue, 15 Jul 2025 00:00:00 GMT

什么才是“好的”代码覆盖率？我在现实世界里用来挡住 bug、又不浪费工程时间的指南

每次我运行 npm run coverage 或 phpunit --coverage，同一个问题都会冒出来：

“好吧……74 %。够了吗？”

软件开发博客圈喊着 "100 % or nothing!" 与此同时，launchdarkly.com 很礼貌地提醒我：100 % executed ≠ 100 % tested。我花过几个星期追逐这个闪亮指标，也花过更多星期调试_别的_问题。下面是我最后落脚的、经过现场验证的中间地带。

为什么 100 % 覆盖率是一场海市蜃楼

理论上，100 % 行执行意味着"没有隐藏 bug"。实践中：

收益递减：从 90 %→95 % 常常会让测试套件翻倍，却只带来个位数的风险降低。
虚假的信心：一个没有 assertion、只是调用函数的测试，仍然算覆盖。
商业现实：每多写一个测试，就是一段没有用在客户要求功能上的时间。

航空航天那帮人可以瞄准 100 %，那是生死问题。对我们其他人来说，~80 % 是 80/20 线。大多数项目在算过 ROI 后都会聚在这里。testdevlab.com 出于同样的原因，把范围称为 70–90 %。

我使用的实用表格

Coverage	我的翻译	Action
100 %	“我们是一个会飞火箭的 library”	接受折磨。
90 % +	“很多钱都依赖它的 library”	只用于高优先级模块。
80 %	发出去，监控，然后迭代。
60–70 %	Merge gate——如果新代码把你拉到线下，就让 PR 失败。
< 50 %	一个周末的技术债——先转向关键路径。

这些数字我从 Atlassian 的内部指南偷来的：60 % 是 "acceptable"，75 % 是 "commendable"，90 % 是 "exemplary"。每次 retro 都好用。

我如何不哭着打到 80 %（TypeScript playbook）

Jest + Istanbul 开箱即用

CI 中的 coverage gate 在 jest.config.js 里我会加：

coverageThreshold: {
  global: 80,
  '**/src/core/**': 90
}

盯住用户热路径，不要盯 Redux boilerplate logger。

我如何在 Laravel 中打到 80 %（PHP playbook）

开发环境安装 PCOV 提速度，CI 中用 Xdebug 拿 branch data。

PHPUnit + phpunit.xml 中这些默认项：

<filter>
  <whitelist processUncoveredFiles="true">
    <directory suffix=".php">./src</directory>
  </whitelist>
</filter>

Mutation score > line count，使用 Infection。这就是我发现"覆盖了但其实没测到"的行的方法。

我团队奉行的 4 条规则

新代码 = 测试。 合并前 diff coverage ≥ 90 %。
先重构，再测试。 不可测试的代码已经是债。
让 build 失败，不要让人失败。 每年把 gate 降低 5 %，也比用一片红色 dashboard 压垮团队好。
衡量生产环境里的 bug——如果覆盖率是 85 %，但 incident 激增，罪魁祸首不是覆盖率，而是断言。

TL;DR（给 execs 和 recruiters 也一样）

别问我要一个"神奇数字"。问这个：

产品的哪些部分不能坏？

把那些覆盖到 90 %。其他部分给健康的 smoke tests。把代码覆盖率当作一束聚光灯，不是终点线；相信你抓到的 bug，不要相信你炫耀的数字。

让 coverage dashboard 变绿吧。你的客户永远不会看见它，但他们的 error bar 会保持空白。

—— 吐槽结束，回编辑器。

我的有效 Pull Request Review 核心指南

Sun, 06 Jul 2025 00:00:00 GMT

作为一个经常写代码、也经常 review 代码的人，我逐渐明白，pull request（PR）review 不只是查 bug。它关乎共同所有权、知识传递，以及一起写出更好的代码。下面是一份简洁、实用的指南，让 PR 更有价值，也少一点痛苦。

1. 好 review 的目标

关注改进，而不是完美 完美代码并不现实。目标是更好的代码。如果一个 PR 改进了可读性、可维护性或正确性，即使还有些小的风格调整，也可以 approve。用 “Nit:” 标记可选建议。 google.github.io
共享所有权与 mentoring 把 PR 当作共同的代码。留下有教育意义的反馈（“Nit: you could use X here…”），指导初级开发者，也保持愿意向他们学习的开放态度。

2. Review 前的准备

作者：Self-review：运行测试、linter 和 formatter。在 PR 描述中提供上下文，并给复杂逻辑加注释。
Reviewer：先读描述。先理解“为什么”，再深入代码。

3. 让 PR 保持小而聚焦

数据显示，超过约 400 LOC 和约 60 分钟后，review 质量会明显下降。 atlassian.com devzery.com mikeconley.ca 准则：

每个 PR 保持在 200–400 LOC 以下。 mikeconley.ca
每次 review 控制在 60 分钟以内。
对于大功能，使用 stacked PR（DB → API → UI）。

4. 用心分配 Reviewer

一个主要 reviewer，最好具备相关领域知识。
最多两个 reviewer，避免责任扩散。 support.smartbear.com abseil.io slab.com
轮换 reviewer，用于交叉培训，也让 bus-factor 更健康。

5. PR 里要检查什么

使用这份心智清单：

正确性：它是否满足需求并处理边界情况？
设计：结构是否良好，是否符合惯用写法？
可读性：命名清晰，逻辑简单，风格一致。
安全性：验证输入，清理输出，避免泄漏。
性能：留意重循环和 N+1 查询。
测试：覆盖核心场景、边界场景和错误场景。
合规：文档、CI、license、格式化是否到位。

这能帮助我们更早捕捉更多问题，尤其是可维护性问题。 google.github.io developers.google.com google.github.io

6. 利用自动化

让工具处理琐碎工作：

Linters（ESLint、RuboCop、SonarQube）
Formatters（Prettier、Black）
带测试、覆盖率和安全检查的 CI pipelines

这样人类 reviewer 才能把注意力放在逻辑、架构和细微判断上。

7. 提供建设性、友善的反馈

保持尊重。评点代码和建议，不评点人。
表扬做得好的地方。
可执行：解释为什么，并建议怎么做。
给非阻塞项加上 “Nit:” 或 “Optional:” 前缀。 atlassian.com google.github.io
让讨论保持客观（“we” > “you”）。避免个人批评。
如果来回讨论卡住了，建议同步聊一下。 atlassian.com

8. 衡量流程，而不是衡量人

值得跟踪趋势的关键指标（不要用来评价个人）：

Turnaround time（PR 打开 → merge）
Inspection rate（< 300–500 LOC/hr 较佳） atlassian.com developers.google.com mikeconley.ca
Defect density（每 LOC 的问题数）
Review coverage（跨组件覆盖情况）
Follow-up commit count

用这些洞见改进工作流，比如强调更小的 PR、改进文档，或者围绕棘手模块做教育。但永远不要把这些指标绑定到绩效评估上。 mikeconley.ca google.github.io bssw.io

9. 针对不同语言的注意事项

不同范式需要不同侧重点：

PHP/JavaScript/TS：异步处理、XSS、SOLID 原则
Python：资源管理（with）、PEP 8、默认参数陷阱
Haskell/Scala functional：类型签名、纯度、不可变性、macro 检查
C/C++：内存安全、指针、RAII
Java：Null-safety、干净的并发、SOLID
Lisp：Macro 文档、动态类型、惯用模式

根据你的技术栈调整清单。遇到不熟悉的语言，就让专家参与。

Bonus：推荐深读资料

Google’s The Standard of Code Review – 关于代码健康和 mentorship 的理念。 google.github.io
Google Code Review Developer Guide – 清单式指南。 bssw.io
SmartBear/Cisco study – 关于 PR 大小和时间安排的实证发现。 mikeconley.ca
Atlassian “5 Code Review Best Practices” – 实用的风格和团队协作建议。 atlassian.com
Blockly PR Flow – 真实世界中的分阶段 review 流程。 developers.google.com

最后的想法

做得好的 PR review 不只是质量关卡。它们是学习、协作和工程卓越的发动机。把尊重的文化、聪明的工具、数据驱动的流程和用心的反馈结合起来，code review 就会变成有价值的讨论，而不是杂务。

祝 review 顺利！

欢迎留言，或者直接联系我。如果你想继续深入，或想分享自己的 review 技巧。

Apple Watch 吸烟检测：构建 Still Mirror（Swift、SWT）

Tue, 13 May 2025 00:00:00 GMT

真正理解我们的习惯，尤其是那些几乎无意识完成的习惯，一直让我着迷。如果可穿戴设备能给这些模式提供一面温和、不评判的镜子，会怎样？这个问题点燃了 “Still Mirror” 项目：尝试利用 Apple Watch 丰富的生理数据，被动检测吸烟或吸电子烟事件，而不要求用户手动输入。这不是为了再做一个戒烟应用，而是一个用于纯粹、未被掺杂的觉察的工具。

挑战：噪声交响中的一声低语

核心挑战非常大：你怎样把一次吸烟/吸电子烟事件的细微生理特征，从无数日常活动和身体反应中区分出来？压力、快走、突如其来的噪声，甚至一杯咖啡，都可能让心率（HR）和心率变异性（HRV）短暂变化。我们要寻找的信号，常常只是生理噪声交响里的一声低语。

但要真正分离这些转瞬即逝的事件，我需要一种更精细的信号处理技术。

图 1. – Apple 开发生态：Xcode、Swift 和 HealthKit 是让 Still Mirror 在 Apple Watch 上活起来的核心。

选择工具箱：Apple 生态与 Swift

对于一个以 Apple Watch 为目标的平台项目，生态选择很清楚：

Xcode 和 Swift： Apple 平台的原生开发环境。开始这个项目意味着更深入地进入 Swift——一门我觉得优雅而强大的语言——也意味着在 Xcode 的各种细节里摸索。
HealthKit： Apple 的框架是通往关键数据流的入口：心率、HRV（SDNN/RMSSD）、SpO2（对于燃烧式吸烟与电子烟的区分尤其相关）以及活动水平。对于处理如此敏感数据的应用来说，HealthKit 以隐私为中心的设计至关重要。
watchOS 限制： 为手表开发，意味着必须不断在功能和资源约束之间平衡——电池寿命和后台处理能力永远在脑子里。

算法的心脏：平稳小波变换（SWT）

传统时间序列分析常常难以处理非平稳信号——也就是统计性质（比如均值和方差）会随时间变化的信号。生理数据出了名地非平稳。这正是**平稳小波变换（Stationary Wavelet Transform，SWT）**派上用场的地方。

标准离散小波变换（DWT）是移位敏感的，也就是说输入信号里一个很小的时间偏移，可能会显著改变小波系数。SWT 则是移位不变的。对于那些事件发生的精确时间很关键、但又可能略有浮动的信号，它因此更稳健。

为什么这个问题适合 SWT？

时频定位： SWT 可以把信号分解到不同频带，同时保留时间信息。这意味着我们可以寻找在精确时刻出现的特定频率特征，比如 HR 中突然爆发的高频活动，或者 HRV 频带中的特定变化。
去噪： 生理信号很吵。SWT 可以通过分析不同尺度上的小波系数，帮助把底层的“真实”信号和随机噪声分开。
瞬态事件检测： 它特别擅长识别信号中的突变、尖峰或短暂事件，而这正是尼古丁摄入后的急性生理反应可能呈现出来的东西。

图 2. – 可视化平稳小波变换如何把信号随时间分解为组成它的频率成分，从而帮助识别模式。

本质上，SWT 像一组更精细的滤镜，让我们能够在 HR、HRV 以及潜在的 SpO2 数据中“看见”那些可能被噪声或长期趋势遮住的模式。我们可以寻找特定小波子带里的典型“形状”或能量变化，它们对应着那一下生理冲击。

开发旅程：从数据到检测

数据采集（HealthKit）： 从 HealthKit 建立可靠的后台数据获取，尊重用户权限，并高效处理数据更新。
信号预处理： 清理传入的 HR、HRV 和 SpO2 数据。这包括处理缺失数据点，也可能包括在应用 SWT 之前做一些初始滤波。
应用 SWT： 对生理时间序列的片段应用平稳小波变换。这涉及选择合适的母小波（例如 Daubechies、Symlet）和分解层级。
从小波系数提取特征： 魔法（以及大量实验）发生在这里。我们不直接看原始 HR/HRV 数值，而是分析 SWT 系数。相关特征可能包括：
- 在疑似事件发生时，特定细节系数频带中的能量。
- 系数的统计性质（方差、峰度）。
- 不同生理信号的小波系数之间的互相关（例如 HR 和 HRV）。
检测逻辑/模型： 一开始，这可能是一个基于规则的系统，寻找提取出的小波特征中的特定模式。例如：“在低体力活动期间，HR 细节系数在尺度 X 上出现显著能量尖峰，同时 HRV 细节系数在尺度 Y 上的能量急剧下降。”最终，它可以演进成一个用这些特征训练出来的机器学习模型。
置信度评分： 正如我在 MVPS 算法里概述的那样，为每个检测到的事件生成置信度分数非常关键，它反映这个特征信号的强度和清晰度。
watchOS 应用实现： 在 Apple Watch 上运行核心检测算法，并针对电池寿命优化，比如分批处理数据、智能触发分析。
iOS 配套应用： 用于显示检测事件的时间线、提供洞察，并管理设置。这里的关键是通过 WatchConnectivity 同步数据。

健康与伦理考量：“镜子”哲学

必须再次强调，“Still Mirror” 被设想为一个觉察工具，不是医疗设备，也不是戒烟计划。

隐私优先： 所有处理，尤其是敏感的算法工作，理想情况下都应在设备本地完成。HealthKit 数据访问严格基于权限。
不评判： 应用界面以及它提供的任何洞察都必须保持中性，只是反映模式，不给处方式建议，也不羞辱用户。
准确性与透明度： 用户需要理解应用的局限。在这种复杂的被动检测里，误报和漏报不可避免。透明呈现检测的置信度很重要。
赋能用户： 目标是把关于用户自身身体和习惯的数据交给他们，让他们能做出自己的知情决定。

学习 Swift，并穿过 Apple 生态

对于主要来自其他背景的开发者（比如我自己的 PHP/Laravel 根系）来说，进入 Swift、SwiftUI、Xcode，以及 watchOS 开发的具体约束，是一条很明显的学习曲线。Apple 的框架有一种独特的哲学。管理应用生命周期、后台任务、HealthKit 查询和设备间通信（WatchConnectivity），都有各自特定的模式和“Apple 式”的做法。不过，丰富的文档、强大的社区，以及 Swift 本身的能力，让这段旅程很值得。

结论：一个沉默观察者的潜力

“Still Mirror” 仍然是一次探索，一项困难的尝试：推动消费级可穿戴设备上的被动感知能做到什么。平稳小波变换为拆解复杂生理信号、发现我们正在寻找的细微信号，提供了一条很有希望的路径。

这段旅程不只是用 Swift 写代码、和 Xcode 较劲，也包括深入信号处理理论、理解人体生理，并谨慎思考这种技术的伦理含义。无论 “Still Mirror” 最终成为一款被广泛使用的应用，还是停留为一次精密的技术探索，这个过程本身都证明了 AI、健康与个人技术交汇处有多迷人。它关乎试着建造那片安静、可反射的表面——一面 still mirror——让我们更清楚地看见自己。

你怎么看用 SWT 这样的高级信号处理来做被动习惯检测？欢迎在下面的评论里告诉我你的想法。

用 Bumble 和 API 32 修好 M1 Mac 上的 Android Emulator 蓝牙

Mon, 14 Apr 2025 00:00:00 GMT

如果你是在 M1/M2/M3 Mac 上做蓝牙相关开发，又想让 Android Emulator 使用宿主机的蓝牙无线电，大概已经吃过一点苦头。看起来应该很直接的事情，常常会变成一个让人恼火的洞：连接失败、错误信息晦涩、文档走到死路。我最近正好打完这场仗，撞了几堵墙之后，终于找到了一套使用 Bumble Python 蓝牙栈的组合，它真的能工作。

这不是又一篇理论指南；这是一次逐步记录：哪些方案失败了，更重要的是，哪套方案成功把我的 M1 Mac Pro 蓝牙（我这里通过外接 USB dongle，不过原理可能也适用于内置无线电）桥接到了 Android 12L（API 32）模拟器里。

目标：模拟器里的真实蓝牙

目标很简单：让 Android Emulator 使用我 Mac 的物理蓝牙控制器，而不是它自己有限的虚拟控制器。测试那些会和真实蓝牙设备交互的 App 时，这一点很关键。

工具：Bumble 上场

Bumble 是一个强大的 Python 蓝牙栈。完成这件事的核心工具是 bumble-hci-bridge，它可以一边连接物理 HCI（Host Controller Interface），另一边通过各种传输方式（比如 TCP 或 gRPC）暴露出来。

尝试 #1：QEMU Socket 方法（合乎逻辑的第一步）

基于一般的 QEMU 知识和一些较老的指南，第一种思路是用 emulator flags，把一个虚拟串口（底层由 TCP socket 支撑）直接连接到 HCI bridge。

启动 Bridge（TCP Server 模式）： 我们把 Bumble 连到物理 dongle（在我的机器上，令人意外的是 usb:0 比它具体的 VID:PID usb:0b05:17cb 更好用，M1 的小脾气！），然后让它监听一个 TCP 端口。
```
# In Terminal 1:
sudo python3 -m bumble.apps.hci_bridge usb:0 tcp-server:0.0.0.0:6789
# Output showed '>>> connected' twice - success connecting to USB and starting TCP server.
```
带 QEMU Flags 启动模拟器： 我们修改了模拟器启动脚本（最初目标是 API 34），加入 -qemu flags，把一个虚拟串口（virtserialport）指向一个字符设备（chardev），而这个字符设备由连接到 bridge 的 TCP socket 支撑。
```
# Snippet from launch script:
emulator -avd <avd_name> ... \
    -qemu \
    -device virtio-serial-device \
    -device virtserialport,chardev=bt,name=bt \
    -chardev socket,id=bt,host=localhost,port=6789 \
    ...
```
结果？部分成功，最终失败： 通过 lsof，我们可以看到 emulator 的 QEMU 进程确实和 Bumble bridge 建立了 TCP 连接！然而，模拟器内部的 Android 蓝牙栈从未真正通过它发送任何 HCI 命令。在 Android 设置里切换蓝牙没有任何效果。初始连接之后，bridge 日志一直安静。死路。

尝试 #2：默认 Netsim Bridge（按 Bumble 文档来）

Bumble 文档提到了桥接到模拟器的 “Netsim” gRPC 接口。Netsim（以及它的核心 Root Canal）是模拟器较新的虚拟蓝牙控制器系统。

启动 Bridge（Netsim Controller 模式）： 我们把 bridge 配成 Netsim controller，让它监听默认 gRPC 端口（8554），并连接到物理 dongle。

# In Terminal 1:
sudo python3 -m bumble.apps.hci_bridge android-netsim:_:8554,mode=controller usb:0
# Output showed '>>> connected' twice - success connecting to USB and starting Netsim gRPC server.

启动模拟器（默认后端）： 我们把启动脚本恢复回去（仍在尝试 API 34），移除 -qemu flags，并加入 -packet-streamer-endpoint default，确保它尝试使用 Netsim 后端。
```
# Snippet from launch script:
emulator -avd <avd_name> ... \
    -packet-streamer-endpoint default \
    ...
```
结果？没有连接： 这次模拟器启动了，但 Bumble bridge 完全没有显示来自模拟器的 gRPC 连接。检查模拟器日志也没有明显的连接错误，但蓝牙仍然不可用。又一条死路。

尝试 #3：降级 API + 显式 Netsim 端点（赢家！）

Fig1. - 一片超现实景观里，失败的网线垂在 Apple 与 Android 岩体之间；一座标着 Bumble 的绳桥成功连接两端，让发光的数据包跨过裂隙。

网上搜索显示，API 33/34 模拟器上的蓝牙有不少不稳定报告；模拟器发现或连接 Netsim 后端的方式也可能有问题，尤其是有外部工具试图拦截它时。关键似乎是：显式告诉模拟器 Netsim gRPC server 在哪里，并且尝试更老的 API 级别。

启动 Bridge（Netsim Controller 模式，显式端口，usb:0）： 和尝试 #2 一样，确保它监听已知端口（8554），并用之前稳定工作的索引（usb:0）连接物理 dongle。
```
# In Terminal 1: (Keep this running!)
sudo python3 -m bumble.apps.hci_bridge android-netsim:_:8554,mode=controller usb:0
```

修改并启动模拟器（API 32，显式端点）： 我们创建了一个带 Google Play Services 的 API 32（Android 12L） AVD（gplay_32_arm）。我们修改启动脚本，让它指向这个 AVD；更关键的是，把 -packet-streamer-endpoint flag 从 default 改成 bridge 的确切地址。

# Snippet from the *successful* launch script (see full script below):
API_LEVEL="32"
AVD_NAME="gplay_${API_LEVEL}_arm"
SYSTEM_IMAGE_PKG="system-images;android-${API_LEVEL};${IMAGE_TAG};${ARCH}"
BUMBLE_NETSIM_GRPC_PORT="8554"
...
emulator -avd "$AVD_NAME" ... \
    -packet-streamer-endpoint "localhost:$BUMBLE_NETSIM_GRPC_PORT" \
    ...

结果？成功！ 这次它工作了。
- bumble-hci-bridge 终端在模拟器启动后不久开始显示来自模拟器的 gRPC 连接日志。
- 模拟器启动完成后，在 Android Settings 里打开 Bluetooth，bridge 终端里立刻涌出一串 HCI 命令（Reset、Read Version、Set Event Mask 等）。
- 在模拟器内扫描设备时，确实通过 ASUS dongle 使用了 Mac 的物理蓝牙无线电。

成功配方：一步一步来

下面是我的 M1 Mac Pro 搭配外接 ASUS USB-BT500 dongle 时实际成功的步骤：

安装 Bumble：

python3 -m pip install bumble
# Potentially install libusb if needed: brew install libusb

（可选但推荐）禁用 macOS 原生 USB BT 处理： 运行一次，然后重启。
```
sudo nvram bluetoothHostControllerSwitchBehavior="never"
```
启动 Bumble Netsim Bridge： 打开一个终端运行（保持它运行）：
```
sudo python3 -m bumble.apps.hci_bridge android-netsim:_:8554,mode=controller usb:0
```
（确认它显示两次 >>> connected。）
准备模拟器启动脚本： 把下面提供的完整脚本保存为 launch_gapps_avd_api32.sh（或类似名字）。确认它指向 API 32 AVD（如果不存在，会创建名为 gplay_32_arm 的 AVD），并且显式使用 -packet-streamer-endpoint localhost:8554。给它执行权限（chmod +x launch_gapps_avd_api32.sh）。
运行启动脚本： 打开一个新终端执行脚本：
```
./launch_gapps_avd_api32.sh
```
验证： 模拟器启动后：
- 查看 bumble-hci-bridge 终端是否有 gRPC 和 HCI 流量。
- 进入 Android Settings -> Bluetooth，把它打开。
- 尝试扫描或配对。

成功的启动脚本（API 32，显式 Netsim 端点）

#!/bin/bash

# Script to setup and launch a Google Play Android emulator (API 32) on macOS M1/ARM64
# Uses explicit Netsim endpoint for Bumble bridge compatibility.

set -e # Exit immediately if a command exits with a non-zero status.

# --- Configuration ---
API_LEVEL="32" # Target Android API Level (Android 12L)
AVD_NAME="gplay_${API_LEVEL}_arm" # Name for the Android Virtual Device
IMAGE_TAG="google_apis_playstore" # Image type with Google Play Store
ARCH="arm64-v8a" # Architecture for Apple Silicon
SYSTEM_IMAGE_PKG="system-images;android-${API_LEVEL};${IMAGE_TAG};${ARCH}"
DEVICE_DEF="pixel_6a" # A common modern Pixel device definition
BUMBLE_NETSIM_GRPC_PORT="8554" # Port where bumble-hci-bridge Netsim controller is listening

# --- Find Android SDK ---
ANDROID_SDK_ROOT="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/Library/Android/sdk}}"

if [ ! -d "$ANDROID_SDK_ROOT" ]; then
    echo "❌ Error: Android SDK not found at '$ANDROID_SDK_ROOT'" >&2
    echo "   Please install Android Studio or set ANDROID_HOME/ANDROID_SDK_ROOT." >&2
    exit 1
fi
echo "▶️ Using Android SDK at: $ANDROID_SDK_ROOT"

# --- Define Tool Paths ---
CMDLINE_TOOLS_BIN="$ANDROID_SDK_ROOT/cmdline-tools/latest/bin"
PLATFORM_TOOLS_DIR="$ANDROID_SDK_ROOT/platform-tools"
EMULATOR_DIR="$ANDROID_SDK_ROOT/emulator"

SDKMANAGER="$CMDLINE_TOOLS_BIN/sdkmanager"
AVDMANAGER="$CMDLINE_TOOLS_BIN/avdmanager"
EMULATOR="$EMULATOR_DIR/emulator"
ADB="$PLATFORM_TOOLS_DIR/adb"

# --- Check Essential Tools ---
if ! command -v sdkmanager &> /dev/null; then echo "❌ Error: sdkmanager not found. Check SDK Command-line Tools installation and PATH." >&2; exit 1; fi
if ! command -v avdmanager &> /dev/null; then echo "❌ Error: avdmanager not found. Check SDK Command-line Tools installation and PATH." >&2; exit 1; fi
if ! command -v emulator &> /dev/null; then echo "❌ Error: emulator not found. Check Android Emulator installation and PATH." >&2; exit 1; fi
if ! command -v adb &> /dev/null; then echo "❌ Error: adb not found. Check SDK Platform-Tools installation and PATH." >&2; exit 1; fi
echo "✅ Basic SDK tools found in PATH."

# --- Stop Currently Running Emulators ---
echo "▶️ Stopping any currently running emulators..."
RUNNING_EMULATORS=$(adb devices | grep 'emulator-' | cut -f1)
if [ -n "$RUNNING_EMULATORS" ]; then
    for emu_id in $RUNNING_EMULATORS; do
        echo "   Stopping $emu_id..."
        adb -s "$emu_id" emu kill || echo "   (Failed to kill $emu_id, may already be stopped)"
        sleep 1 # Small delay
    done
    # Give ADB server time to recognize disconnection
    sleep 3
    echo "   Emulators stopped."
else
    echo "   No emulators appear to be running according to 'adb devices'."
fi
echo "✅ Emulator check/stop finished."


# --- Install/Update Required SDK Packages ---
echo "▶️ Ensuring required SDK packages are installed..."
# Accept licenses non-interactively
yes | sdkmanager --licenses > /dev/null || echo "   (Ignoring potential license script errors)"

# Install platform-tools, emulator
sdkmanager "platform-tools" "emulator"

# Install the Google Play system image for API 32
echo "▶️ Attempting to install/update Google Play system image: $SYSTEM_IMAGE_PKG"
if ! sdkmanager "$SYSTEM_IMAGE_PKG"; then
    echo "❌ Error: Failed to install required system image '$SYSTEM_IMAGE_PKG'." >&2
    echo "   Please check available images using: sdkmanager --list | grep 'system-images;android-${API_LEVEL};.*${ARCH}'" >&2
    exit 1
fi
echo "✅ System image package '$SYSTEM_IMAGE_PKG' present."

# --- Check if AVD Exists, Create ONLY if Missing ---
echo "▶️ Ensuring AVD '$AVD_NAME' exists..."
if ! avdmanager list avd --compact | grep -q "^${AVD_NAME}$"; then
    echo "   AVD '$AVD_NAME' not found. Creating..."
    # Using 'echo no' usually prevents hardware profile creation prompts. Pipe empty string for potential licenses.
    echo "" | avdmanager create avd --force --name "$AVD_NAME" --package "$SYSTEM_IMAGE_PKG" --device "$DEVICE_DEF" --sdcard 512M || {
         echo "❌ Error: Failed to create AVD '$AVD_NAME'." >&2
         echo "   Maybe the device definition '$DEVICE_DEF' is invalid for this image?" >&2
         echo "   Check available devices: avdmanager list device" >&2
         exit 1
    }
    echo "✅ AVD '$AVD_NAME' created."
else
    echo "✅ AVD '$AVD_NAME' already exists. Will reuse."
fi


# --- Launch Emulator ---
echo "▶️ Launching existing/new emulator: '$AVD_NAME' (pointing to Bumble Netsim bridge on localhost:$BUMBLE_NETSIM_GRPC_PORT)..."
EMULATOR_LOG="emulator-$AVD_NAME.log" # Log file name updated for API 32 AVD
# Google Play images often need a writable system partition
# Explicitly point packet streamer to localhost:8554 where bridge is listening
nohup emulator -avd "$AVD_NAME" -no-snapshot-load -gpu auto -show-kernel -writable-system \
    -packet-streamer-endpoint "localhost:$BUMBLE_NETSIM_GRPC_PORT" \
    > "$EMULATOR_LOG" 2>&1 &
EMULATOR_PID=$!
echo "   Emulator starting in background (PID: $EMULATOR_PID). Log: $EMULATOR_LOG"
echo -n "   Waiting for emulator to appear in ADB..."

# Wait for the emulator device to show up in adb
WAIT_ADB_TIMEOUT=90 # Increase timeout slightly for GPlay images
SECONDS=0
EMULATOR_ID="" # Reset variable
while [ $SECONDS -lt $WAIT_ADB_TIMEOUT ]; do
    # Find the *new* emulator ID
    CURRENT_EMU_ID=$(adb devices | grep 'emulator-' | head -n 1 | cut -f1)
    if [ -n "$CURRENT_EMU_ID" ]; then
        EMULATOR_ID="$CURRENT_EMU_ID"
        echo " Found ($EMULATOR_ID)!"
        break
    fi
    sleep 2
    SECONDS=$((SECONDS + 2))
    echo -n "."
done

if [ -z "$EMULATOR_ID" ]; then
    echo ""
    echo "❌ Error: Emulator did not appear in ADB within $WAIT_ADB_TIMEOUT seconds." >&2
    echo "   Check logs: $EMULATOR_LOG" >&2
    # Try to kill the process if it's still lingering
    kill $EMULATOR_PID 2>/dev/null || echo "   (Emulator process $EMULATOR_PID may have already exited)"
    exit 1
fi


# --- Wait for Boot Completion ---
echo -n "▶️ Waiting for Android system to fully boot (Google Play images can take longer)..."
BOOT_TIMEOUT=240 # Increase timeout significantly for GPlay images
SECONDS=0
while [ $SECONDS -lt $BOOT_TIMEOUT ]; do
    # Check if device is online first
    DEVICE_STATE=$(adb -s "$EMULATOR_ID" get-state 2>/dev/null)
    if [ "$DEVICE_STATE" != "device" ]; then
       echo -n "s($DEVICE_STATE)" # State not ready
       sleep 5
       SECONDS=$((SECONDS + 5))
       continue
    fi

    # Check boot completed property
    BOOT_COMPLETED=$(adb -s "$EMULATOR_ID" shell getprop sys.boot_completed 2>/dev/null | tr -d '
')
    if [ "$BOOT_COMPLETED" = "1" ]; then
        # Double check package manager is ready too for GPlay images
        PM_READY=$(adb -s "$EMULATOR_ID" shell pm get-install-location 2>/dev/null)
        if [[ "$PM_READY" == *"0"* || "$PM_READY" == *"1"* || "$PM_READY" == *"2"* ]]; then # Check if pm command gives valid output
            echo " Booted!"
            break
        else
            echo -n "p(pm not ready)" # Package Manager not ready
        fi
    else
         echo -n "b(booting)" # Boot not completed
    fi
    sleep 5
    SECONDS=$((SECONDS + 5))
done

if [ $SECONDS -ge $BOOT_TIMEOUT ]; then
    echo ""
    echo "❌ Error: Android system did not fully boot within $BOOT_TIMEOUT seconds." >&2
    echo "   Emulator might be stuck. Check logs ($EMULATOR_LOG) or try launching manually." >&2
    # Don't exit here, user might want to interact with stuck emulator
fi


# --- Final Instructions ---
echo "---"
echo "✅ Google Play Emulator '$AVD_NAME' (API $API_LEVEL) ($EMULATOR_ID) should be running."
echo "   Bluetooth should be using the Netsim backend at localhost:$BUMBLE_NETSIM_GRPC_PORT (intercepted by Bumble)."
echo "   Connect shell:   adb -s $EMULATOR_ID shell"
echo "   Install APK:     adb -s $EMULATOR_ID install /path/to/your.apk"
echo "   Stop emulator:   adb -s $EMULATOR_ID emu kill"
if [ -n "$EMULATOR_PID" ]; then # Only show PID if we launched it
    echo "   Kill Process:    kill $EMULATOR_PID"
fi
echo "   NOTE: Google Play Services may need updates inside the emulator."
echo "---"

exit 0

M1 Mac + Emulator + Bumble 的关键结论

API 级别很重要： 对模拟器兼容性来说，更新不总是更好，尤其是蓝牙桥接这种复杂功能。在我的测试里，API 32 比 API 34 更稳定。
显式端点： 使用 Bumble 的 Netsim controller mode 这类外部 bridge 时，不要依赖 -packet-streamer-endpoint default。直接把模拟器指向 bridge 正在监听的 localhost:<port>。
Netsim Bridge > QEMU Socket： android-netsim bridge mode 比更底层的 -qemu -chardev socket 方法更可能和现代模拟器正常配合，哪怕 socket 方法确实能建立 TCP 连接。
usb:0 vs VID:PID： 在 macOS/M1 上，USB 设备识别可能有点古怪。如果指定精确 VID:PID 意外失败，试试用索引 usb:0（假设它就是主要/目标设备）。
坚持有回报： 这件事试了好几轮，结合了文档、网页搜索和反复测试。别太早放弃。

希望这套具体可工作的配置能帮其他开发者省下几个小时的挫败。祝编码（和桥接）顺利。

AI 博客重设计：Claude Code 如何改造我的 Gatsby 站点

Sat, 12 Apr 2025 00:00:00 GMT

作为一个大部分时间都在后端工作的开发者，我一直不太会设计。我的个人博客功能上没问题，但看起来像卡在了 2010 年——基础样式、不一致的间距，还有一个如果足够慷慨才能称作“极简”的配色方案。我几个月来一直想彻底翻新它，但一想到要钻进 CSS 和设计系统里，就有点做噩梦。

然后我试了 Claude Code，Anthropic 的 AI 编码助手，我的看法彻底变了。

挑战：我那个悲伤、过时的博客

我的博客是用 Gatsby.js 构建的。内容还算扎实，但呈现方式拖了后腿：

整个站点的间距不一致
移动设备上的响应式表现很差
深色模式实现几乎只是勉强能用
字体排印最好也只能算业余
没有统一的配色系统或设计语言

我大概知道自己想要什么：现代、干净、专业，能让内容自己发光。但把这个愿景翻译成真正的 CSS？那通常就是我撞墙的地方。

Claude Code 登场：我的虚拟设计搭档

我听说 Claude Code 已经有一阵子了，但我对 AI 到底能在设计工作上帮多少忙一直有点怀疑。毕竟，设计需要品味和审美眼光，不只是技术知识。

我还是决定试一试，用了一个很简单的 prompt：“Please improve my styling by a ton.” 我愿意投入一个小时，以及大约 15 美元的 API 费用，看看它到底能做到什么。

接下来发生的事真的让我惊讶。

改造过程

Claude Code 没有只是建议几个 CSS 小调整，而是以专业开发者的严谨度来处理这次重设计：

分析阶段：首先，它检查了我现有的样式、组件架构和配色方案，理解自己面对的是什么。
创建设计系统：它没有停留在表面改动，而是构建了一个完整的设计系统，包括：
- 一套专业配色，并为浅色和深色模式定义了语义变量
- 现代化的字体排印尺度，以及合适的响应式调整
- 一个基于 4px 网格的一致间距系统
- 标准化的阴影、圆角和过渡
组件重写：它重写了我的组件，让它们遵循现代最佳实践：
- 创建了基于卡片的响应式博客文章布局
- 实现了带背景模糊效果的固定页头
- 设计了一个优雅的主题切换器
- 添加了带激活状态的正确导航
可访问性改进：Claude Code 不只是让东西看起来更好——它也让站点更易访问：
- 添加了正确的键盘导航支持
- 实现了 skip-to-content 链接
- 确保了足够的颜色对比度
- 添加了正确的 ARIA labels
性能优化：代码也针对性能做了优化：
- 只选择性导入必要的 Bootstrap 组件
- 优化 CSS 组织
- 添加硬件加速动画

让人有点失语的结果

改造效果非常惊人。在大约一个小时的来回互动里，只花了 15 美元的 Claude API 成本，我的博客从一个看起来像开发者副项目的东西，变成了一个有专业设计感的出版物。重设计包括：

一个精细的配色系统，并正确支持深色模式
在各种设备上都能完美缩放的漂亮字体排印
专业的博客文章卡片布局
顺滑的动画和过渡
带玻璃质感效果的固定页头
贯穿整个站点的一致间距

放在现实里比较一下：聘请一位专业网页设计师做这种级别的工作，可能要花 1,000 到 2,000 美元，还需要数天甚至数周的来回沟通。而这一次，我花了一个小时和 15 美元 API 费用。

但最让我印象深刻的，不只是视觉提升或成本节省，而是代码质量。Claude Code 不是随手堆了一些 CSS hack；它创建了一个完整、可维护、我可以很容易继续扩展的设计系统。

我从 AI 辅助设计里学到的事

这次经历改变了我对 AI 能为开发者做什么的看法：

AI 擅长系统性思考：Claude Code 不只是让东西“好看一点”——它创建了一个有变量、有一致模式、有清晰组织的完整系统。
它能弥合知识缺口：作为一个没有深厚 CSS 专长的人，Claude Code 用现代最佳实践填补了我的知识空白，而这些东西我自己未必知道要实现。
代码达到了生产质量：它创建的样式框架不是摆设——它是可维护、可扩展，并遵循现代标准的代码。
它保留了我的内容和结构：Claude Code 改进了设计，同时保留了我博客的核心结构和内容。

开发者与 AI 协作的未来

我的经历凸显了一件重要的事：Claude Code 不是在取代开发者，而是在扩展我们的能力。它帮我越过了自己在前端设计上的局限，同时仍然让我掌控整体方向。

对于那些有些方面更强、有些方面更弱的开发者来说（而我们不都是这样吗？），Claude Code 这样的 AI 助手可以帮助填补技能组合里的空白。

自己试试看

如果你正在设计或开发的其他某个方面挣扎，我非常推荐你试试 Claude Code。这次经历改变的不只是我的博客，也改变了我对 AI 辅助开发可能性的看法。

你试过 Claude Code 或类似的 AI 编码助手吗？我很想在下面的评论里听听你的经历。

注：这个博客本身就是用 Claude Code 重新设计的，所以你现在看到的正是我描述的过程所带来的结果。从我以前的设计到现在这个版本，大约花了一个小时的提示词输入和迭代，成本约为 15 美元的 Claude API 使用费。考虑到传统设计成本，这是一笔非常惊人的价值交换。

Huawei Watch D2 BLE 配对：协议与厂商锁定案例

Fri, 11 Apr 2025 00:00:00 GMT

太长不读： Huawei Watch D2 没有使用标准 BLE 配对。它要求的是一套 11 步专有握手，里面有自定义 GATT characteristic、从二维码派生 HMAC-SHA256 密钥，以及应用层加密。这是有意设计的厂商锁定，它把你推入华为的 Health 应用。好消息是：社区已经把它逆向出来了。Gadgetbridge 现在支持 Watch D2，也已经有 huawei-lpv2 这样的开源实现。欧盟 DMA 也开始反推这种做法。

我原本期待的是标准蓝牙配对。连接，绑定，交换数据，正常流程。结果我遇到的是一套专有的密码学握手，花了几周才逆向明白。

这发生在我做 D2Explorer 的时候。D2Explorer 是我用来在 Linux 和 macOS 上连接 Huawei Watch D2、绕开华为 Health 应用的项目。在解决 BlueZ 配对代理的问题并迁移到跨平台的 SimpleBLE 库之后，我以为最难的部分已经结束。最难的部分还没开始。

你本来会期待什么：标准 BLE 配对

Bluetooth LE 配对本来应该是这样工作的：

按广播名称扫描设备（比如 "HUAWEI WATCH D2-CA0"）。
用 peripheral.connect() 连接。
操作系统处理配对/绑定：PIN 提示、Just Works，或者安全级别要求的任何方式。
绑定完成后，和标准或自定义 GATT 服务交互。

安全由操作系统管理。你的应用专注于数据。简单。

实际发生了什么：一个 11 步专有握手

Watch D2 实际要求的东西完全不同。基础 BLE 连接只是门。门后面是华为叠在标准 BLE 之上的一套自定义应用层认证协议，也就是社区所说的 Huawei Link Protocol v2 [1]。

标准 BLE 配对机制被完全绕开了。要认证并访问任何有意义的数据，你需要通过自定义 GATT characteristic 走完这一串流程：

Connect -- 建立基础 BLE 链路。
Enable Notifications -- 立刻订阅 characteristic 0000fe02-... 上的通知。这个步骤对时序非常敏感，错过窗口，手表就会断开。
GetLinkParams -- 立刻向写入 characteristic 0000fe01-... 发送自定义命令（Service ID 0x0001，Command ID 0x0001）。
Receive Server Nonce -- 等待包含手表随机 challenge 的通知。
Derive Secret Key -- 生成 client nonce。把 server nonce、client nonce 和手表二维码里的数值组合起来。运行 HMAC-SHA256（使用二维码数值的字节作为密钥），派生共享的 secretKey_。
AuthRequest -- 把 client nonce 和 HMAC digest（使用派生出的 secretKey_）发回手表（Service 0x0001，Command 0x0002）。
Verify Server Token -- 接收手表的认证 token。用 secretKey_ 和已交换的 nonce 验证它。
SetTime -- 发送当前时间和时区偏移，并用 secretKey_ 加密（Service 0x0002，Command 0x0003）。
QrToken -- 把二维码数值发回去，并用 secretKey_ 加密（Service 0x0001，Command 0x0004）。
AuthResult -- 发送最终确认，并用 secretKey_ 加密（Service 0x0001，Command 0x0005）。
Done -- 到这里，连接才算完成认证。

自定义 TLV 消息格式。CRC 校验。Service 和 command ID。应用层加密。以毫秒为单位敏感的时序。这一切都发生在 BLE 栈之上，标准蓝牙工具根本看不见。

手表屏幕上的二维码就是共享秘密。没有它，你派生不出密钥。没有密钥，你无法认证。没有认证，手表什么都不会给你。

华为为什么这么做

华为也许会把它描述成增强安全。实际效果是厂商锁定。

极高的进入门槛 -- 协议没有文档。重新实现它需要逆向华为 Health 应用（13,000+ 个类，64,000+ 个方法 [2]），或者分析 BLE 流量。这会主动劝退第三方应用。
没有互操作性 -- 标准健身应用无法连接。手表只会和知道这些专有步骤的软件完成握手，主要就是华为自己的 Health 应用。
生态控制 -- 用户被迫进入 Huawei Health 及其云服务。以后想换设备或平台，就意味着失去自己的健康数据历史。
减少用户选择 -- 想用开源应用？想对自己的健康数据隐私有更多控制？运气不好。除非有人先把协议逆向出来。

问题在这里：这并不是华为独有的事。WatchWitch 研究项目 [3] 记录了所有主要厂商，包括 Apple、Samsung、Xiaomi，如何用专有 BLE 协议强制生态锁定。Apple Watch 被描述为 "incredibly tightly coupled with Apple's iPhone and iCloud ecosystem, using proprietary protocols that are unavailable to third parties." 这是一个行业层面的系统问题。

但华为的实现尤其激进。BLE 当然允许自定义服务。可用一个专有守门人取代根本性的认证机制，就是另一回事了。

安全上的讽刺

最显然的辩护是：“我们这么做是为了安全。”那就看一看。

清华大学的 BlueDoor 漏洞研究 [4] 测试了 16 个 BLE 设备，包括 Honor Band 3（同一个华为生态），并在其中大多数设备上实现了无需用户授权的静默配对。专有协议没有阻止这件事。

与此同时，这套协议本身已经被逆向过多次：Gadgetbridge 社区逆向过，huawei-lpv2 项目逆向过，在 Easterhegg 2019 演讲的研究者逆向过 [2]，我也为 D2Explorer 逆向过。靠遮掩获得的安全，是带有效期的。

从二维码派生 HMAC-SHA256 密钥，本身其实是不错的密码学。但重点不在这里。你完全可以用标准 BLE Secure Connections 加带外配对方式（比如 NFC 或二维码）获得同样的安全属性，而且不需要在过程中把所有第三方应用挡在门外。

社区的反击

社区没有安静接受。

Gadgetbridge

Gadgetbridge 是面向可穿戴设备的开源 Android 应用，现在已经支持 Huawei Watch D2 [5]。你可以不通过华为 Health 应用来配对手表。它花了相当多的逆向工程努力（见 PR #2462 [6]），也有一些限制，比如用 Gadgetbridge 配对时 ECG 功能会被禁用 [7]，但它确实可用。

Gadgetbridge 里的认证实现处理 auth version 3，从配对消息（service 0x01，command 0x0e）计算 bonding key，并用它进行解密。认证密钥协商需要一个 17 位的华为账号 ID。

huawei-lpv2

huawei-lpv2 项目提供了 Huawei Link Protocol v2 的纯 Python 实现 [8]。它仍在维护，有多个 fork，也给所有想在官方生态之外做华为可穿戴集成的人提供了参考。

D2Explorer

我自己的 D2Explorer 走了另一条路：用 SimpleBLE 做一个能在 Linux 和 macOS 上工作的 C++ 实现。这项工作包括：

实现 TLV 序列化/反序列化（HuaweiProtocol）。
构建精确的消息构造器（ProtocolMessageBuilder）。
把密码学步骤做对：nonce 生成、HMAC-SHA256、XOR 加密（CryptoOperations、CryptoUtils）。
管理严格的状态转换和时序（HuaweiPairingProtocol、ProtocolStateManager）。
调试由毫秒级时序不匹配和细微加密错误引起的失败。

D2Explorer 之所以存在，正是因为华为的协议让它变得必要。它是在围墙花园之外获得基本功能所需要的绕行方案。

AsteroidOS

AsteroidOS 2.0 于 2026 年 2 月发布，是这个基于 Linux 的开源智能手表 OS 的一次重大更新 [9]。它现在支持约 30 款设备，包括 Huawei Watch 和 Huawei Watch 2，并带有常亮显示、抬腕唤醒等功能。这是一个完整的、开源的华为固件替代方案。

监管潮水

欧盟不只是旁观。Digital Markets Act（DMA）正在开始迫使事情改变 [10]。

2025 年 12 月，Apple 发布了 iOS 26.3，为第三方设备，包括华为智能手表，加入类似 AirPods 的配对体验，明确是为了遵守 DMA 要求 [11]。华为手表和 iPhone 之间的后台同步已经在欧洲可用。

DMA 要求守门人向互联设备提供互操作性。这正面瞄准了华为、Apple 以及其他所有厂商一直在实践的这种专有 BLE 锁定。这些互操作功能预计会在 2026 年全年继续铺开。

这很重要。第一次，监管压力开始要求标准化那些厂商刻意保持专有的东西。技术社区可以一个协议一个协议地逆向，但监管可以改变整个行业的激励结构。

这意味着什么

Huawei Watch D2 的配对协议，是一个很好的案例：标准传输之上的自定义协议，如何被用来强制厂商锁定。那些专有密码学、自定义消息格式和对时序敏感的握手之所以存在，并不是因为标准 BLE 处理不了认证。它能处理。它们存在，是因为专有协议能把用户留在生态里。

不过局面正在变化。Gadgetbridge 现在就给了你替代方案。欧盟 DMA 在监管层面推动互操作性。huawei-lpv2、D2Explorer 和 AsteroidOS 这样的开源项目也证明了：厂商想锁住的东西，社区会去逆向。

做 D2Explorer，与其说是在做蓝牙，不如说是在做密码学侦探工作。它凸显了一件本不该反复强调的事：你应该能用自己选择的软件访问自己的健康数据。

参考资料

1. huawei-lpv2: Pure Python implementation of Huawei BLE Link Protocol v2 -- 协议的开源参考实现。
2. All Your Fitness Data Belongs to You: Reverse Engineering the Huawei Health Android App -- Easterhegg 2019 大会演讲，记录了逆向工程工作。Slides (PDF)。
3. WatchWitch: Academic Research on Smartwatch Interoperability -- 记录所有主要厂商如何用专有协议实现生态锁定。
4. BlueDoor: Breaking the Secure Information Flow via BLE Vulnerability (Tsinghua University) -- 在 16 个 BLE 设备中发现静默配对漏洞，包括 Honor Band 3。
5. Gadgetbridge: Huawei/Honor Device Support -- Huawei 和 Honor 可穿戴设备的官方支持页面。
6. Gadgetbridge PR #2462: Initial Huawei/Honor Support -- 为 Gadgetbridge 添加 Huawei 设备支持的 pull request。
7. Gadgetbridge Issue #4918: ECG Disabled with Gadgetbridge -- 使用 Gadgetbridge 而不是 Huawei Health 时的已知限制。
8. Gadgetbridge: Huawei/Honor Pairing Guide -- Huawei 设备逐步配对说明。
9. AsteroidOS 2.0 Release -- 开源智能手表 OS 现在支持约 30 款设备，包括 Huawei 手表。
10. EU Digital Markets Act: Interoperability Requirements -- DMA 中要求互联设备互操作性的条款。
11. iOS 26.3 DMA Features: Third-Party Smartwatch Pairing -- Apple 为可穿戴设备互操作性要求所做的欧盟合规。

BlueZ Pairing Fix: External Python Agent & D-Bus Polling -- 这次调查的前置工作。在处理华为专有协议之前，我们必须先修好标准 BLE 配对里的 BlueZ AuthenticationFailed 错误。
Fix Android Emulator Bluetooth on M1 Mac using Bumble & API 32 -- 另一场 BLE 集成战斗，这次是把 Mac 的实体蓝牙无线电桥接进 Android Emulator。

BlueZ 配对修复：外部 Python Agent 与 D-Bus 轮询

Tue, 08 Apr 2025 00:00:00 GMT

TL;DR: 如果你在 BlueZ 5.66+ 上用自定义 C++/sd-bus 配对 agent 时遇到 org.bluez.Error.AuthenticationFailed，问题很可能出在内部 agent 注册上。把外部 Python agent（simple-agent.py）作为独立进程运行，并实现 D-Bus 属性轮询，不要只依赖 PropertiesChanged 信号。细节和代码在下面。

我盯着 org.bluez.Error.AuthenticationFailed 看了两天，才弄明白到底发生了什么。

配对 agent 已经注册。D-Bus 调用看起来是对的。busctl 确认所有东西都在位——而 BlueZ 只是继续说不。这发生在 D2Explorer 的开发过程中——一个在 Linux 上与 Huawei Watch D2 配对的工具——而这个配对错误把一切都挡住了。

下面是真正发生的事，以及我们最后是怎么修好的。

计划：一个内部 C++ 配对 Agent

想法很干净，也很自洽。一个单独的 C++ 应用，使用 sd-bus（C/C++ 的 D-Bus 绑定）处理整个配对流程：

连接到系统 D-Bus。
找到 Bluetooth 适配器（org.bluez.Adapter1）。
实现一个暴露 org.bluez.Agent1 接口的 C++ 类。
通过 RegisterAgent 和 RequestDefaultAgent 在 org.bluez.AgentManager1 上注册 agent。我们一开始使用 DisplayYesNo 能力，后来简化为 NoInputNoOutput。
发现目标设备（org.bluez.Device1）。
在设备的 D-Bus 接口上调用 Pair()。
内部 agent 自动处理回调（RequestConfirmation、RequestAuthorization）——不需要用户交互。
信任设备，建立 GATT 连接，完成。

一个二进制文件，没有外部依赖。这就是计划。

墙：`org.bluez.Error.AuthenticationFailed`

一切都工作到第 6 步。找到了适配器，注册了 agent（D-Bus 也确认了），发现了设备。但我们通过 sd_bus_call_method 调用 Device1.Pair() 的那一刻——立刻失败：

[BluetoothDevice] Calling Device1.Pair() method via D-Bus
[BluetoothDevice] Device1.Pair() method threw exception: Failed to call method 'Pair':
    Input/output error - D-Bus error: org.bluez.Error.AuthenticationFailed (Authentication Failed)

我们什么都试过了。不同的 agent 能力。检查 sd-bus vtable 设置。验证 agent 方法实现会及时返回成功。用 busctl 和 gdbus 监控 D-Bus 流量——注册调用看起来都是正确的。Pair() 调用就是一直失败。

死路。

突破：外部 Python Agent

为了隔离问题，我们把内部 C++ agent 从方程里拿掉。我们先把 BlueZ 标准的 simple-agent.py 作为独立进程运行起来，然后再启动我们的 C++ 应用（此时它已经去掉了自己的 agent 注册）：

# Terminal 1: Run the external agent
sudo python simple-agent.py NoInputNoOutput

# Terminal 2: Run our C++ app (no internal agent)
sudo ./build/huawei_pair_app <MAC> <QR_VALUE>

结果：

[BluetoothDevice] Calling Device1.Pair() method via D-Bus
[BluetoothDevice] Device1.Pair() method succeeded  <--- SUCCESS!

稳定。每次都稳定。AuthenticationFailed 错误完全消失了。

这证明问题不在 Pair() 本身，也不在设备或 BlueZ 的配对能力。问题具体出在我们的 C++ 应用如何使用 sd-bus 注册并作为配对 agent 交互。完全相同的逻辑操作——注册一个 NoInputNoOutput agent 并调用 Pair()——在 agent 作为独立 Python 进程运行时工作得很好。

这条路通了。

为什么内部 Agent 会失败？

我第一次撞上这个问题时，手里只有一些假设。从那以后，我找到了实际的文档证据，说明这是一个更广泛的问题——不只是我们的代码。

BlueZ 5.70+ 回归

BlueZ GitHub Issue #605 记录了一些案例：设备在 BlueZ 5.50 上可以正常配对，但在较新版本上会以 auth failed with status 0x05 失败。HCI 日志显示 Status: PIN or Key Missing (0x06)，即使已存储 link keys。解决办法？运行旧的 bluez-simple-agent.py 脚本。听起来熟悉吗？

Agent 可用性是根因

Bleak Issue #1434 让这一点更清楚：只有在 bluetoothctl 或 GNOME Bluetooth 正在运行时，配对才会成功，因为这些应用注册了必要的认证 agent。没有一个活跃且真正能工作的 agent，BlueZ 内部会返回 No agent available for request type 2——表面上则变成 AuthenticationFailed。

关键认识是：仅仅注册一个 agent 不够。agent 还需要以 bluetoothd 认为有效的方式响应 BlueZ 的回调。而 sd-bus 在同一个发起配对的进程里处理这件事时，有某些细节并不能满足较新版 BlueZ 的要求。

甚至可能不是 BlueZ

Red Hat Bug #1905671 显示，有些 AuthenticationFailed 错误与内核有关，而不是 BlueZ。Kernel 5.9 存在配对问题，而 5.8.18 和 5.10+ 没有。维护者的评论值得引用：“Bluetooth is complex, it could be firmware, kernel, bluez, controller, end device or a combination of them all.”

Agent Capability 不匹配

BlueZ Issue #650 记录了另一个角度：某些设备（尤其是 iOS）在与 NoInputNoOutput agent 配对时会失败，因为它们会把 Secure Connections 降级到 Legacy pairing，导致后续属性访问出现 Insufficient Authentication (0x05) 错误。这是 Security Manager Protocol（SMP）协商问题，不是 agent 注册问题——但它会产生同样的错误消息。

我们这个案例中最可能的罪魁

结合这些证据，内部 sd-bus agent 失败最可能的解释是：

时序——我们事件循环中的 sd-bus 注册或方法处理，没有在 bluetoothd 期望的精确窗口内响应。
sd-bus 与 python-dbus 的细微差异——这些库与 D-Bus 守护进程交互或处理对象生命周期的方式不同。
BlueZ 5.66+ 中更严格的要求——agent 交互的内部序列发生了变化，而 sd-bus 在与发起配对的应用同进程使用时无法满足。

第二堵墙：D-Bus 信号不可靠

越过 AuthenticationFailed 是一大步，但事情还没结束。有了外部 agent，Pair() 成功了——但我们无法可靠地检测它什么时候完成。

我们依赖 D-Bus 的 PropertiesChanged 信号（通过 sd-bus）来知道 Paired、Trusted、Connected 和 ServicesResolved 什么时候变成 true。有时信号会来。有时来得很晚。有时根本不来。

所以我们实现了主动轮询——当信号不出现时，直接查询属性值作为兜底：

bool BluetoothDevice::isPaired() {
    bool cachedValue = mockPaired_.load(); // Check signal-updated cache
    if (cachedValue) return true;

    // Signal didn't fire? Poll D-Bus directly.
    Logger::debug("[Polling] Polling Paired property via D-Bus...");
    bool polledValue = false;
    adapter_.getObjectProperty<bool>(
        devicePath_, "org.bluez.Device1", "Paired", polledValue
    );
    if (polledValue) mockPaired_.store(true); // Update cache
    return polledValue;
}

每一个状态转换方法（isPaired()、isTrusted()、isConnected()、areServicesResolved()）都遵循同一个模式：先检查缓存的原子布尔值（如果 signal handler 工作，它会更新这个值），然后退回到一次直接的 D-Bus Get 属性调用。

不优雅。但必要。

这条路也通了。

完整修复

下面是整理后的方案。如果你在 Linux 上使用 BlueZ 5.66+ 构建自动 Bluetooth 配对，并且撞上了 AuthenticationFailed：

第 1 步：拿到 simple-agent.py

从 BlueZ source tree 获取它。

第 2 步：运行外部 agent

sudo python simple-agent.py NoInputNoOutput

让它在一个单独终端里保持运行（或者作为后台服务运行）。

第 3 步：从你的应用中移除内部 agent

从你的 C++ 应用里移除所有 RegisterAgent / RequestDefaultAgent 调用。让外部 Python agent 处理认证回调。

第 4 步：添加 D-Bus 属性轮询

不要只依赖 PropertiesChanged 信号。对于每个关键属性（Paired、Trusted、Connected、ServicesResolved），实现上面展示的缓存后轮询模式。从主循环里周期性轮询。

第 5 步：验证

确认外部 agent 正在运行（sudo python simple-agent.py NoInputNoOutput）。
运行你的应用。Pair() 应该会成功。
观察轮询日志——你应该能看到用于状态转换的 D-Bus 属性查询。
如果 Pair() 仍然失败，检查你的 BlueZ 版本（bluetoothd --version）和 kernel 版本——问题可能更深。

代价是什么

我不会假装这是一个干净的方案。它不是：

外部依赖——你的应用现在需要另一个 Python 进程保持运行。
更多复杂度——主循环里有轮询逻辑，还叠在 signal handlers 之上。
更不自包含——单个二进制文件的梦想没了。

但它能工作。可靠地工作。而当你已经盯着 AuthenticationFailed 看了两天，“它能工作”就是最重要的事。

参考资料

1. BlueZ GitHub Issue #55: Device characteristics and pairing timing -- 与 agent 时序相关的间歇性配对失败。
2. Bluetooth Auto Pairing with NoInputNoOutput Agent Issues -- 关于无头配对挑战的论坛讨论。
3. BlueZ Source: test/simple-agent -- 标准 Python agent。
4. BlueZ GitHub Issue #605: Pairing regression in 5.70+ -- 较新 BlueZ 版本中的已记录失败。
5. Bleak Issue #1434: Pairing requires active agent -- 证明 agent 可用性是根因的证据。
6. Red Hat Bug #1905671: Kernel-related pairing failures -- 不总是 BlueZ——有时是 kernel。
7. BlueZ GitHub Issue #650: Agent capability mismatch -- NoInputNoOutput 导致的 SMP 协商失败。
8. BlueZ Agent API Documentation -- 官方 agent 接口参考。
9. Kynetics: Pairing Agents in the BlueZ Stack -- 关于 agent 注册的技术深入分析。

Huawei Watch D2 BLE 配对：协议与厂商锁定 -- 促成这次调查的项目。Watch D2 在标准 BLE 配对之上还需要一个专有的应用层握手，所以我们一开始才需要自动配对可靠工作。
在 M1 Mac 上用 Bumble 和 API 32 修复 Android Emulator Bluetooth -- 另一场 Bluetooth 集成战斗，这次是把 Mac 的实体无线电桥接进 Android Emulator。

开发者指南：Shopware 6.5/6.6 的类与命名空间更新

Sat, 30 Nov 2024 00:00:00 GMT

Shopware 6.5 和 6.6 对类、命名空间、data attribute 以及安全机制引入了几项重要变更。开发者在升级或维护 Shopware 项目时需要了解这些变化。本文会用简洁但完整的方式梳理这些变更，并说明它们的影响，以及你的代码该如何相应调整。

引言

随着 Shopware 演进，更新通常会带来改进、优化和新功能。不过，它们也可能引入会影响现有代码库的变化。理解这些变化，是顺利过渡并真正用好新能力的关键。

本文聚焦以下几个重点领域：

Elasticsearch 命名空间迁移
媒体路径处理更新
AvailableCombinationLoader 中的方法变更
Symfony 框架升级到版本 6
库存处理更新
Storefront Bootstrap 升级
Offcanvas Cart data attribute 变更
CSRF 保护变更
Rule Builder 增强

我们逐项看。

1. Elasticsearch 命名空间迁移

变更概览

旧命名空间： ONGR\ElasticsearchDSL
新命名空间： OpenSearchDSL

影响

所有与 Elasticsearch 交互的类和方法，都需要更新命名空间，以反映从 ONGR\ElasticsearchDSL 到 OpenSearchDSL 的迁移。

需要采取的动作

更新代码中的 import 语句和引用，改用新的命名空间。

示例

// Before
use ONGR\ElasticsearchDSL\Query\MatchQuery;

$query = new MatchQuery('field', 'value');

// After
use OpenSearchDSL\Query\MatchQuery;

$query = new MatchQuery('field', 'value');

观察

这个变更符合行业更广泛地转向 OpenSearch 的趋势。OpenSearch 是 Elasticsearch 的社区驱动分支。更新到新的命名空间，可以确保你的代码继续兼容后续发展与支持。

2. 媒体路径处理

变更概览

媒体路径现在会直接存储在数据库中，而不是动态生成。

影响

以前依赖动态路径生成的类和服务，现在需要从数据库中读取媒体路径。

需要采取的动作

调整代码，使用 MediaEntity 的 getPath() 方法。

示例

// Before (dynamic path generation)
$mediaPath = $mediaService->getPath($mediaId);

// After (database-stored path)
$mediaPath = $mediaEntity->getPath();

观察

把媒体路径存入数据库可以减少计算开销，从而提升性能。它也让媒体处理更一致、更可靠。

3. `AvailableCombinationLoader` 中的方法更新

变更概览

AbstractAvailableCombinationLoader 中的 load() 方法已被 loadCombinations() 取代。

影响

任何继承 AbstractAvailableCombinationLoader 的自定义类，都必须实现新的 loadCombinations() 方法，而不是旧的 load() 方法。

需要采取的动作

重命名或重构你的方法实现，使其与新的方法名和签名保持一致。

示例

// Before
$combinations = $combinationLoader->load($productId);

// After
$combinations = $combinationLoader->loadCombinations($productId);

观察

这个变更用一个更具描述性的名称提升了清晰度。它也可能伴随额外参数或返回类型变化，所以检查方法签名很必要。

4. Symfony 框架升级到版本 6

变更概览

Shopware 已将 Symfony 组件升级到版本 6。

影响

由于废弃功能被移除、方法签名发生变化，这次升级会带来一些破坏性变更。依赖旧 Symfony 特性的自定义代码可能会报错，或者产生警告。

需要采取的动作

检查代码中是否使用了任何已废弃的 Symfony 功能，并更新到与 Symfony 6 兼容的写法。

观察

跟上最新 Symfony 版本，可以获得更好的性能、安全性和新功能。不过，它也要求你认真审查和测试代码，确保兼容性。

5. 库存处理更新

变更概览

Shopware 引入了新的 Stock API，可通过 STOCK_HANDLING feature flag 启用。

影响

与库存管理相关的类和服务可能需要适配新的 API 结构，尤其是那些直接与库存数据交互的代码。

需要采取的动作

使用新 API 提供的库存处理方法，并确保所有库存相关逻辑与更新后的结构一致。

示例

// Before
$stock = $productEntity->getStock();

// After
$stock = $stockService->getStock($productId);

观察

新的 Stock API 提供了更稳健、更灵活的库存管理方式，有可能简化自定义开发以及与外部系统的集成。

6. Storefront Bootstrap 升级

变更概览

Storefront 已从 Bootstrap 4 升级到 Bootstrap 5，并移除了对 jQuery 的依赖。

影响

依赖 jQuery 或 Bootstrap 4 组件的自定义 JavaScript 代码和模板，需要重构为符合 Bootstrap 5 的写法，并在必要时改用原生 JavaScript。

需要采取的动作

用原生 JavaScript 或 Bootstrap 5 工具替换 jQuery 用法。
更新 Bootstrap class 和组件，使其匹配 Bootstrap 5 的命名与结构。

观察

Bootstrap 5 带来了性能改进、更少依赖，以及现代化组件。升级可能耗时，但从长期看，对可维护性和用户体验都有好处。

7. Offcanvas Cart Data Attribute 变更（Shopware 6.6）

变更概览

在 Shopware 6.6 中，用于触发 offcanvas cart 功能的 data attribute 出现了一个细微但重要的变更。

旧 Data Attribute： data-offcanvas-cart
新 Data Attribute： data-off-canvas-cart

影响

如果自定义模板或主题仍使用不带连字符的 data-offcanvas-cart attribute，offcanvas cart 可能不再按预期工作，因为 Shopware 6.6 中的 JavaScript listener 会查找带连字符的版本。

需要采取的动作

把模板中的 data-offcanvas-cart attribute 更新为 data-off-canvas-cart。

示例

<!-- Before -->
<div class="header-cart" data-offcanvas-cart="true">
    <!-- Cart content -->
</div>

<!-- After -->
<div class="header-cart" data-off-canvas-cart="true">
    <!-- Cart content -->
</div>

观察

这个变更在官方 Shopware 6.6 release notes 中记录得并不充分，但它对 offcanvas cart 的正常工作很关键。负责初始化购物车功能的 JavaScript 依赖 data-off-canvas-cart attribute，任何偏差都可能让购物车无法工作。

额外说明

一致性很关键： 确保所有使用 offcanvas cart attribute 的地方都已更新。
彻底测试： 修改后测试购物车功能，确认它能按预期工作。
留意类似变更： 其他 data attribute 或 event listener 可能也有类似更新；相应检查你的自定义模板。

8. CSRF 保护变更

变更概览

Shopware 6.5 及之后的版本移除了模板中的显式 CSRF token 处理，转而使用 SameSite cookie 策略进行 CSRF 保护。

影响

以前通过 sw_csrf 函数包含 CSRF token 的模板和表单会遇到错误，因为这个函数已经不存在。

需要采取的动作

移除 CSRF Token 函数： 从模板中删除 {{ sw_csrf('route_name') }} 的用法。
依赖 SameSite Cookies： 信任内置的 SameSite cookie 策略进行 CSRF 保护；表单不再需要显式 token。
调整表单属性： 确保表单和 AJAX 请求配置正确，能与新的 CSRF 保护机制协同工作。

示例

<!-- Before -->
<form action="{{ path('frontend.checkout.line-item.add') }}" method="post">
    {{ sw_csrf('frontend.checkout.line-item.add') }}
    <!-- Form fields -->
    <button type="submit">Add to Cart</button>
</form>

<!-- After -->
<form action="{{ path('frontend.checkout.line-item.add') }}" method="post">
    <!-- Form fields -->
    <button type="submit">Add to Cart</button>
</form>

观察

错误解决： 移除 sw_csrf 函数可以解决 "Unknown 'sw_csrf' function" 错误。
安全性保持： SameSite cookie 策略不需要额外 token，仍能继续防护 CSRF 攻击。
模板更简洁： 不再需要 CSRF token 后，表单会更干净，也稍微简单一些。

额外说明

测试至关重要： 完成这些改动后，彻底测试表单提交，确保它们正确工作。
理解新机制： 熟悉 SameSite cookie 策略的运行方式，以维持应用安全。
更新文档： 确保内部文档反映这个变更，避免以后再次混淆。

9. 处理 Offcanvas Cart 问题

场景概览

在更新模板并移除 sw_csrf 函数后，开发者仍可能遇到这样的问题：点击 "Add to Cart" 按钮会打开 offcanvas cart，但购物车看起来是空的。

根因

offcanvas cart 可能因为表单提交中缺少或错误的参数而没有显示已添加商品，尤其是缺少 redirectTo input field。

需要采取的动作

添加 redirectTo 参数： 在 add-to-cart 表单中加入一个名为 redirectTo、值为 frontend.cart.offcanvas 的隐藏 input field。
确保 Data Attribute 正确： 确认所有必要的 data attribute 都存在，并且命名正确。

示例

<form action="{{ path('frontend.checkout.line-item.add') }}" method="post">
    <input type="hidden" name="redirectTo" value="frontend.cart.offcanvas"/>
    <input type="hidden" name="lineItems[{{ product.id }}][id]" value="{{ product.id }}">
    <!-- Other form fields -->
    <button type="submit">Add to Cart</button>
</form>

观察

功能恢复： 添加 redirectTo 参数会告诉 Shopware 在加入商品后加载 offcanvas cart，从而确保购物车正确显示。
细节的重要性： 缺少一个 input field 这样的小遗漏，也可能造成明显的功能问题。这再次说明，仔细 code review 很重要。

额外说明

Data Attribute 的一致性： 再次确认 data-product-id 这类 data attribute 设置正确。
检查 JavaScript 依赖： 确保与购物车相关的 JavaScript plugin 或组件已正确加载和初始化。
清缓存： 修改后清理 Shopware 缓存和浏览器缓存，避免旧文件造成问题。

10. Rule Builder 增强

变更概览

Rule Builder API 已扩展，支持更复杂的条件逻辑。

影响

自定义规则和条件可能需要调整，以符合增强后的 Rule Builder 提供的新接口或方法。

需要采取的动作

查看 Rule Builder 文档，并更新自定义规则实现以确保兼容性。

观察

增强后的规则能力可以在 Shopware 内实现更精确的定位和自定义。用好这些新功能，能提升系统的适配性，并给最终用户带来更个性化的体验。

结论

Shopware 6.5 和 6.6 对类、命名空间、data attribute 和安全机制引入了几项重要变更。开发者必须处理这些变化，才能维持兼容性，并利用新功能。更新代码库需要仔细审查和测试，但也提供了改善性能、安全性和功能的机会。

建议

提前规划： 升级前，阅读官方 Shopware release notes 和 upgrade guide，获得完整信息。
彻底测试： 在 staging 环境中实施变更，并进行充分测试，以发现并修复问题。
善用文档： 利用 Shopware 文档和社区论坛，获取具体变更的指导。
保持关注： 跟进未来更新，提前预判后续变化并做好准备。

额外观察

关注细节： data attribute 中的连字符、函数移除这类小变化，都可能造成重大影响。始终认真审查模板更新。
社区支持： Shopware 社区活跃且协作性强。与其他开发者交流，往往能得到常见问题的洞见和解决方案。
最佳实践： 采用更新后的最佳实践，比如用原生 JavaScript 替代 jQuery、依赖现代安全策略，会带来更清晰、更高效的代码。
监控废弃项： 留意 deprecation notice，并为未来的移除提前准备，可以减少升级时的中断。

通过理解并处理 Shopware 6.5 和 6.6 中关于类、命名空间、data attribute 与安全机制的变化，开发者可以顺利过渡，并继续构建稳健、面向未来的电商解决方案。

Docker Compose 的演进：变了什么，为什么重要

Wed, 20 Nov 2024 00:00:00 GMT

TL;DR: Docker Compose v1（docker-compose）已在 2025 年 4 月被完全移除。你的 YAML 里的 version 字段已经死了。x-develop 键现在就是 develop。watch 模式已经带着 initial_sync 达到生产可用。有一个关键的路径遍历 CVE（CVE-2025-62725），如果你把 include 和 OCI artifact 一起用，就该升级到 v2.40.2+。是的，Compose 从 v2 跳到了 v5。细节在下面。

最初发布于 2024 年 11 月。2026 年 3 月更新，加入 Compose v5、CVE-2025-62725、v1 移除，以及新的 spec 功能。

如果你用 Docker Compose 已经有一段时间，可能已经注意到脚下的东西在坏掉，或者悄悄变了。过去两年是 Compose 历史上变化最激进的两年，而且并不是所有变化都显而易见。

我每天都用 Compose。我的大多数开发环境都跑在它上面。东西一变，我会注意到。下面是实际重要的部分。

坏掉了什么

docker-compose 已死

不是 deprecated。不是维护模式。死了。 独立的 docker-compose 二进制文件，也就是基于 Python 的 v1，已经在 2025 年 4 月从 GitHub Actions runner 和官方 Docker 镜像中移除 [1]。如果你的 CI/CD pipeline 里还在引用带连字符的 docker-compose，它们已经坏了，或者马上就会坏。

# This no longer works
docker-compose up -d

# This is the only way now
docker compose up -d

基于 Go 的 docker compose（v2，现在是 v5）自 2022 年以来就是真正的实现。v1 CLI 只是为了兼容性挂着维生系统。现在维生系统停了。

version 字段没了

别再把 version: "3.8" 放在 Compose 文件顶部了。它什么也不做。自 v2 起它就被忽略，现在也正式 deprecated。现代 Compose 文件从 services: 开始。

# Stop doing this
version: "3.8"
services:
  web:
    image: nginx

# Just do this
services:
  web:
    image: nginx

如果你在教程里看到 version:，那篇教程已经过时。

其他弃用项

links -- 使用 Docker networks。Links 从 Compose v2 发布起就已经是 legacy。
container_name -- 让 Docker 管理名称。硬编码名称会破坏扩缩容，并造成冲突。
复杂挂载的短 volume 语法 -- 使用带 type、source、target 的长格式语法。

新的、而且真正有用的东西

Watch 模式（现在生产可用）

这是多年来最大的生活质量改进。develop 区段（之前是 x-develop -- 去掉 x- 前缀，它已经不再是实验性的）让你定义文件 watch 规则，在文件变化时自动同步或重建：

services:
  web:
    build: .
    develop:
      watch:
        - path: ./src
          action: sync
          target: /app/src
        - path: ./package.json
          action: rebuild

有三种可用 action（自 v2.32.0 起）：

sync -- 不重建，直接把变更文件复制进容器
restart -- 文件变化时重启服务
rebuild -- 触发完整重建

截至 2025 年 9 月，还多了 initial_sync。它会在你启动 docker compose watch 时立刻同步所有文件，所以你不必等第一次文件变化才触发同步。这曾经是很长一段时间里的痛点。

docker compose watch

开发时不再需要手动 rebuild。这真的改变了我的工作流。

通过 OCI Artifacts 使用 Include

include 指令现在可以从 OCI registry 拉取 Compose 片段：

include:
  - oci://docker.io/username/my-compose-fragment:latest

还提供了实验性的 Git repository 支持。这很适合在多个项目之间共享通用服务定义，比如数据库配置、监控栈等等。

但先读下面的安全部分。 这里有一个 CVE。

GPU 支持

GPU passthrough 变得更干净了。现在除了冗长的 deploy.resources.reservations.devices 写法，也有更短的 gpus: 语法（v2.30.0+）。AMD GPU 支持也在 2025 年正式集成，不再只是 NVIDIA。

Models 元素

Compose spec 现在包含一个 models 元素，用来把 AI/ML 模型定义为 OCI artifacts。你可以把 LLM 和推理 runtime 直接打包进 Compose 设置里。很小众，但如果你在做本地 AI 工作，它挺有意思。

更好的依赖关系

depends_on 条件变得更灵活了：

services:
  web:
    depends_on:
      db:
        condition: service_healthy
        restart: true      # restart web if db restarts
        required: false     # web can start even if db isn't ready

restart: true 和 required: false 对更有韧性的本地开发环境来说，是真的有用。

你应该知道的事

CVE-2025-62725：Include 路径遍历

如果你把 include 指令和 OCI artifacts 一起使用，立刻升级到 v2.40.2 或更高版本 [2]。一个路径遍历漏洞允许攻击者在 artifact 解析期间逃出缓存目录。即使是看起来无害的 docker compose ps，如果你的 Compose 文件 include 了恶意 OCI 引用，也可能触发它。

Docker 用 validatePathInBase() 检查修补了这个问题，但你得运行在已修复版本上。

Compose v5

Docker 从 v2 跳到了 v5（跳过 3 和 4，是为了避免和旧的文件格式版本混淆）[3]。功能上，v5 和后期 v2 版本差不多，但它包含了一个官方 Go SDK，可用于程序化访问。这意味着你可以把 Compose 功能直接嵌入 Go 应用里，而不用 shell out 到 CLI。

检查你的版本：

docker compose version
# Docker Compose version v5.1.0

Bake 是默认构建工具

Docker Bake（通过 BuildKit）现在是 docker compose build 的默认工具。它比 legacy builder 更擅长处理多目标构建、跨平台编译和高级缓存策略。如果你还没看过 docker-bake.hcl 文件，值得了解一下，尤其是在复杂的多服务构建里。

Healthcheck 改进

start_interval 字段允许你在启动宽限期内设置更快的检查间隔：

services:
  db:
    healthcheck:
      test: ["CMD", "pg_isready"]
      start_period: 30s
      start_interval: 2s    # check every 2s during startup
      interval: 30s         # then every 30s after
      retries: 3

这意味着你的依赖服务可以更快启动，同时不牺牲生产环境 health check 的间隔。

迁移清单

如果你已经有一阵子没更新 Compose 设置了：

从所有 Compose 文件中移除 version:。
在所有脚本和 CI 配置中，把 docker-compose 替换为 docker compose。
在 watch 配置中，把 x-develop 改名为 develop。
如果你使用 include，升级到 v2.40.2+（CVE-2025-62725）。
如果你不知怎么还在用 links，就把它们替换为 Docker networks。
测试你的 CI -- GitHub Actions 已在 2026 年 2 月把 runner 更新到 Compose v2.40.3 [4]。

参考资料

1. Docker Compose v1 removed from runner images (April 2025) -- GitHub Actions 关于移除 v1 的公告。
2. CVE-2025-62725: From "docker compose ps" to System Compromise -- Imperva 对 include 路径遍历漏洞的详细分析。
3. Docker Compose Releases -- 包含 v5 在内的官方发布历史。
4. Docker and Docker Compose version upgrades on hosted runners -- GitHub 2026 年 2 月 runner 更新。
5. Compose Specification -- 官方 Compose 文件参考。
6. Use Compose Watch -- Docker 的 watch 模式文档。
7. Enable GPU Support in Docker Compose -- 包含 AMD 支持在内的 GPU passthrough 文档。
8. Docker Compose Include -- 带 OCI 和 Git 支持的 include 指令。

Laravel Sail vs Laradock: Choosing the Right Docker Solution -- 比较基于 Docker 的 PHP 开发环境。

释放 'git grep' 的力量，高效搜索代码

Wed, 13 Nov 2024 00:00:00 GMT

在一个辽阔的王国里，卷轴和手稿数不胜数。有一位名叫 Alaric 的学者住在那里。他的图书馆庞大得像一座知识迷宫：古老文本与当代著作并置，秘密藏在行与行之间。Alaric 常常需要在这片信息海中寻找一句难以捉摸的短语；日子久了，这件事越来越让人发怵。

某天清晨，阳光把金色洒在蒙尘的巨册上，Alaric 开始寻找档案里提到的一个概念。它只以 "The Whispering Sigil" 这个名字出现。他一卷卷翻阅，用惯常的方法筛过页面；可这些方法如今显得迟缓而不精确。他越往深处找，就越被无关段落、重复内容和误导性引用缠住。几小时变成几天，进展寥寥，挫败感也慢慢堆起来。

后来，一位老智者来访，看出了他的困境。智者会意一笑，说："也许你是在用困难的方法找。还有一条隐秘路径，只有那些懂得整理知识的人知道。" Alaric 被勾起了兴趣，听智者解释一种能聚焦搜索的方法。它能切开杂物，直接通向他要找的文本。

带着这个新办法，Alaric 又试了一次。这回，无关的杂音退去了。通往 "The Whispering Sigil" 的路径变得清晰，他以惊人的速度找到了想要的东西。仿佛他在自己的迷宫里打开了一扇秘密之门，快速抵达了所需的确切知识。

噗。秘密揭晓：这就是 git grep 的力量。

`git grep` 到底是什么

普通的 grep -r 会遍历文件系统。它尽职尽责地读取路径上的一切：源代码、日志文件、构建产物、同事忘了删掉的那个 4 MB 零散 dump 文件、整个 node_modules 树。git grep 做的事情更窄：它搜索 Git 已经知道的文件。它的大部分价值，就来自这一个设计选择。

`git grep` 擅长什么

它搜索 tracked files，而不是文件系统。 Git 会维护一份列表，记录你曾经 staged 或 committed 的每个文件，也就是 index。git grep 从这份列表读取。未跟踪的杂物根本不在那里。没有 node_modules/，没有 dist/，没有 coverage reports，没有随机日志文件，因为 Git 从没被告知它们存在。
在大型 repo 中，它比 grep -r 更快。 它已经有文件列表，所以跳过了文件系统遍历。它还会用多线程并行执行。收益是真的，但不是魔法。git grep 迭代的是 grep 也会读到的同一批 blobs，只是仪式少一点。这里没有内容搜索索引。"Git index" 是文件路径和 blob hash 的列表，不是 Lucene 风格的倒排索引。
它可以在不 checkout 的情况下搜索任意 ref。 这是杀手特性。tag、branch、commit、tree object，都可以直接交给 git grep。不用 git checkout，不用 stash 舞步，也不用偏离你手头正在做的事。

实用示例

基本搜索

要在仓库中搜索某个具体词，比如 "initializeSettings"：

git grep "initializeSettings"

这会扫描当前 branch 中所有 tracked files，寻找精确匹配。

不区分大小写搜索

如果你不确定大小写，可以做不区分大小写的搜索：

git grep -i "initializesettings"

它会找到大小写不同的所有匹配。

在指定 branch 中搜索

要在另一个 branch 里搜索，而不切过去，例如 feature/login：

git grep "validateUser" feature/login

这招很难被打败。不 checkout，不 stash，直接得到答案。

跨所有 branches 搜索

要在每个 branch 中搜索某个词，包括 remotes：

git branch -a | xargs -n 1 git grep "configureDatabase"

要搜索 Git 知道的每个 commit，而不只是每个 branch tip：

git grep "configureDatabase" $(git rev-list --all)

这会在历史中任何地方的任何 blob 里寻找匹配。在繁忙的 repo 上可能需要一点时间，因为它真的在走过每个 commit。

在 commit 历史中搜索

要找出某个字符串是在什么时候被加入或移除的，可以用：

git log -S "optimizePerformance"

这会显示引入或移除 "optimizePerformance" 这个词的 commits。

要查看这个词被加入或移除时的实际 diffs：

git log -G "optimizePerformance" -p

使用正则表达式

git grep 支持正则表达式，可以做更高级的搜索：

git grep -E "def\s+\w+\("

这会匹配 Python 函数定义：def、空白、函数名，然后是一个字面意义上的左括号。（在 extended regex 中，\( 是字面括号，而 ( 表示分组；这就是为什么这里需要反斜杠。）

`git grep` 会读什么，不会读什么

git grep 遍历 index。就这样。它不会解析 .gitignore。很多人，包括本文之前的一个版本，都说它会；这个说法几乎正确，正如"地球是平的"在你一辈子只看一个停车场时也几乎正确。

两者看起来一致，只是因为 gitignored 文件通常也 untracked。一旦某个文件既被 gitignored 又被 tracked，比如有人跑过 git add -f，或者这个文件在规则出现之前就已经 committed，git grep 会照样搜索它。rg 不会。

你可以在二十秒内证明：

mkdir demo && cd demo
git init -q
echo "*.log" > .gitignore
echo "the secret phrase" > tracked.log
git add -f tracked.log .gitignore
git commit -qm init

git grep "secret phrase"   # finds it - the file is tracked, ignore rule notwithstanding
rg "secret phrase"         # finds nothing - rg actually reads .gitignore

所以精确的说法是：git grep 搜索 tracked files。这碰巧会跳过 .gitignore 会跳过的大多数东西，但机制不同，边界情况也重要。尤其是当你追查一个字符串，最后发现它住在某个多年前被人强行加入的 generated file 里时。

.gitignore 机制只会通过两个 opt-in 模式进入 git grep：

--untracked：同时搜索 untracked files。在这个模式下，git grep 默认遵守 .gitignore，并跳过 ignored files（可以用 --no-exclude-standard 覆盖，也把它们搜进去）。
--no-index：搜索当前目录，同时完全忽略 Git。在 repo 内想要 plain-grep 语义时很有用。在这个模式下，git grep 默认不会查询 .gitignore；如果你想要它这么做，可以用 --exclude-standard 显式打开。

默认的 git grep，不带任何 flags，永远不会打开你的 .gitignore 文件。

什么时候该用 `rg`

git grep 和 rg（ripgrep）其实不是竞争对手。它们遍历的东西不同。认真的工具箱里两个都该有。

git grep 遍历 index：tracked files，以及你指向它的任何 ref 或 tree object。
rg 遍历 文件系统：当前目录下的所有文件，减去 .gitignore、.ignore、.rgignore 和全局 excludes 让它跳过的部分。

它们各自能做对方做不了的事情。

当你想在不 checkout 的情况下跨历史搜索时，git grep 胜出：

git grep "deprecated_api" v2.3.0          # search a tag
git grep "deprecated_api" HEAD~50         # 50 commits ago
git grep "deprecated_api" $(git rev-list --all)   # every commit, ever

当你真正需要文件系统语义，并且希望正确处理 gitignore 时，rg 胜出：包括刚 clone 下来但还没 git add 的子目录、Git 从未听说过的 generated files，或者根本不是 Git repo 的目录。

rg "deprecated_api"                # respects .gitignore by default
rg --no-ignore "deprecated_api"    # opt back into ignored files
rg --hidden "deprecated_api"       # include dotfiles

rg 也是 VS Code 项目搜索背后的引擎，所以 "Find in Files" 感觉就像在终端里跑 rg。它的 Unicode 处理扎实；在大多数现代语料上，它至少和 git grep 一样快，常常更快。ripgrep README 的 Linux kernel benchmark 显示，在同一个查询上，ripgrep 大约比 git grep -P 快 3 倍。（提示：如果你想要"只有 pattern 里有大写时才区分大小写"的行为，传 -S 开启 smart-case。它是 opt-in，不是默认行为。）

如果你还没装 rg，修一下：

brew install ripgrep   # macOS
apt install ripgrep    # Debian/Ubuntu
cargo install ripgrep  # anywhere with Rust

把 rg 放在 git grep 旁边。它们负责不同的工作。

`git grep` 的好处

相关性。 它只搜索你正在 track 的东西。构建产物、缓存、node_modules 不会挡路，因为 Git 从没见过它们。
大型 repo 上的速度。 多线程，不走文件系统遍历。
历史触达。 任意 branch、tag 或 commit，且不离开你的 working tree。这是 rg 做不到的部分。
更少二进制噪音。 和 grep 一样，git grep 会用 "Binary file X matches" 标记二进制文件，而不是倾倒字节；但因为它遍历 tracked files，通常一开始就会少遇到这类文件。传 -I 可以完全跳过二进制文件。

额外技巧

分页查看结果：
```
git grep "searchTerm" | less
```
按文件统计匹配次数：
```
git grep -c "searchTerm"
```
显示行号：
```
git grep -n "searchTerm"
```
在编辑器中打开每个匹配文件：
```
git grep -l "searchTerm" | xargs code
```
把 code 换成 nvim、subl，或者你自己用的任何编辑器。

结论

就像 Alaric 在迷宫般的图书馆里找到了一条隐秘路径，git grep 会在 tracked codebase 中切出一条干净的线：快速、懂 branch，并且不被 Git 从未听说过的东西弄乱。它不是 grep 的万能替代品，也不是 rg 的替代品。它知道的是你的 repo 的 index；一旦你开始伸手去用它，迷宫就会小很多。

当问题是"这个代码库里，包括它的历史里，哪里有它"时，用 git grep。当问题是"磁盘上哪里有它，并且要遵守我的 ignore rules"时，用 rg。多数日子里，你会希望两者都在手边。

2026-04-27 更新：修正了早先关于 git grep 会遵守 .gitignore 的说法（它不会，至少不是直接遵守）；放缓了"内部索引"的解释；修正了一个正则示例；并新增了什么时候该用 rg 的章节。

在 macOS 上用 phpenv 安装带 IMAP 的 PHP 8.3.6：安装指南

Sun, 01 Sep 2024 00:00:00 GMT

重要提示（2024-11 更新）： PHP 8.4 已经把 ext-imap 从核心中拆出。这个扩展移到了 PECL，并且事实上已经弃用：底层 C 库（libc-client）自 2018 年以来就没有更新。如果你正在启动新项目，或者使用 PHP 8.4+，请直接跳到你真的需要 ext-imap 吗？看现代替代方案。如果你在 PHP 8.3 或更早版本上，并且确实需要原生扩展，这份指南仍然可用。

快速修复

如果你只想要命令，不关心为什么，下面就是完整顺序。你需要已经安装好 Homebrew 和 phpenv。

# 1. Install all required libraries
brew install tidy-html5 openssl@3 zlib bzip2 libedit readline \
  gettext libiconv libsodium krb5 imap-uw curl

# 2. Set build configuration (add to ~/.zshrc or run before install)
export PHP_BUILD_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3) \
  --with-zlib=$(brew --prefix zlib) \
  --with-bz2=$(brew --prefix bzip2) \
  --with-curl \
  --with-libedit \
  --with-readline=$(brew --prefix readline) \
  --with-gettext=$(brew --prefix gettext) \
  --with-iconv=$(brew --prefix libiconv) \
  --with-sodium=$(brew --prefix libsodium) \
  --with-kerberos=$(brew --prefix krb5) \
  --with-imap=$(brew --prefix imap-uw) \
  --with-imap-ssl=$(brew --prefix openssl@3) \
  --with-tidy=$(brew --prefix tidy-html5) \
  --enable-mbstring \
  --enable-intl"

# 3. Help the compiler find headers
export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix imap-uw)/include $CPPFLAGS"

# 4. Build and install
phpenv install 8.3.6
phpenv global 8.3.6

# 5. Verify
php -v
php -m | grep imap

如果输出里出现 imap，就结束了。如果没有，继续往下读。

你真的需要 ext-imap 吗？

认真问一句。在和 C 库、编译器 flag 较劲之前，先想想你是否真的需要原生 IMAP 扩展。

PHP 8.4 已经从核心中移除了 ext-imap。 它转到了 PECL，而底层 C 库（libc-client / UW-IMAP）自 2018 年以来就没有更新。它有线程安全问题，缺少 XAUTH 支持，还有 POP bug。它不会回来了。

现代替代方案是 Webklex/php-imap，一个纯 PHP 的 IMAP 实现：

composer require webklex/php-imap

就这样。没有 brew 依赖，没有编译器 flag，没有到处找头文件。它可以在 PHP 8.0.2+ 上工作（包括 8.4 和 8.5），支持 IMAP IDLE 和 OAuth，在 Packagist 上有超过 500 万次安装。如果你的技术栈是 Laravel，也有一个 Laravel 集成。

只有在这种情况下才使用 ext-imap： 你正在维护一个 PHP 8.3 或更早版本上的遗留代码库，它已经依赖 imap_* 函数，而且暂时还不能迁移。

每一步在做什么

如果快速修复已经奏效，可以不用再读。如果没有，或者你想理解发生了什么，下面是拆解。

Brew 依赖

brew install tidy-html5 openssl@3 zlib bzip2 libedit readline \
  gettext libiconv libsodium krb5 imap-uw curl

macOS 自带其中一部分，但 phpenv 需要 Homebrew 版本，因为它们带有正确的 header 和 pkg-config 文件。最关键的是 imap-uw，它就是提供 libc-client 的 UW-IMAP 库。

PHP_BUILD_CONFIGURE_OPTS

phpenv 底层使用 php-build，而 php-build 会在 PHP 源码上运行 ./configure。PHP_BUILD_CONFIGURE_OPTS 变量把 flag 直接传给 configure。每一个 --with-* flag 都告诉 PHP 去哪里找某个特定库。

对 IMAP 最重要的是：

--with-imap=$(brew --prefix imap-uw) -- 指向 IMAP 库
--with-imap-ssl=$(brew --prefix openssl@3) -- 启用基于 SSL 的 IMAP
--with-kerberos=$(brew --prefix krb5) -- IMAP 认证所需

CPPFLAGS 修复

export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix imap-uw)/include $CPPFLAGS"

即便 configure flag 已经设置好，C 预处理器有时还是找不到头文件。这是因为 macOS 不会把 Homebrew 的 header 放进默认搜索路径。最常出问题的两个 header 是：

openssl/ssl.h -- 来自 OpenSSL
imap/imap.h -- 来自 imap-uw

PATH 修复

如果安装之后 php -v 显示的版本不对，说明 phpenv 的 shims 没有在你的 PATH 里，或者被别的东西遮住了。把下面这段加到 ~/.zshrc：

export PHPENV_ROOT="$HOME/.phpenv"
if [ -d "${PHPENV_ROOT}" ]; then
  export PATH="${PHPENV_ROOT}/shims:${PHPENV_ROOT}/bin:$PATH"
  eval "$(phpenv init -)"
fi

然后运行 source ~/.zshrc，再试一次。

utf8_mime2text 错误

如果你看到这个：

configure: error: utf8_mime2text() has new signature, but U8T_CANONICAL is missing.
This should not happen.

说明你的 imap-uw 库太旧或已经坏了。这样修：

brew upgrade imap-uw

然后重新运行安装。

PHP + IMAP 的未来

墙上的字已经写出来了。ext-imap 已弃用，底层 C 库已被放弃，PHP 8.4 已经把它从核心中移除。如果你读到这里，是因为某个 PHP 项目需要 IMAP，那就开始规划迁移到 webklex/php-imap。原生扩展是在借来的时间上运行。

对于我们这些维护遗留代码库的人，这份指南会继续适用于 PHP 8.3 及更早版本。但不要在新项目里开始使用 ext-imap。既然有纯 PHP 方案，就没必要再和 C 库编译较劲。

参考资料

PHP 8.4: IMAP Extension Unbundled -- PHP.Watch 关于 ext-imap 移除的文档。
Webklex/php-imap on GitHub -- 纯 PHP IMAP 实现（Packagist 安装量 500 万+）。
PHP Manual: IMAP Extension -- 带有弃用说明的官方文档。
shivammathur/extensions: IMAP for PHP 8.3+ -- 包含 IMAP 等 PHP 扩展的 Homebrew tap。

PHP 8.5: A Tour of the Incoming Features -- PHP 接下来会有什么变化。
Dev Guide: Shopware 6.5/6.6 Class & Namespace Updates -- 给 Shopware 开发者的另一份 PHP 迁移指南。
Laravel Sail vs Laradock -- 为 PHP 开发选择合适的 Docker 设置。

Laravel Sail vs Laradock：PHP Docker 开发者该怎么选

Thu, 08 Aug 2024 12:00:00 GMT

TL;DR： 对 2026 年的大多数 Laravel 开发者来说：如果你想要零摩擦（原生、无 Docker、几秒配置好），用 Laravel Herd。如果你的团队需要完全一致的环境，或者依赖 Redis/Meilisearch 这类服务，用 Sail。如果你跨多个 PHP 框架工作，用 Laradock。如果你已经长出了这些抽象的边界，用一套 自定义 Docker Compose。如果性能就是一切，看看 FrankenPHP + Octane。

最初发布于 2024 年 8 月。2026 年 3 月更新，加入 Laravel 12/Herd/FrankenPHP 以及当前生态状态。

过去的问题是“Sail 还是 Laradock？”现在这个问法太窄了。真正的问题是：2026 年，我该怎样搭建 Laravel 开发环境？ 选择比以往更多，而最好的选择取决于你真正需要什么。

这些工具我大多都用过。我现在跑的是自定义 Docker Compose，因为我想完整控制自己的容器，不想让抽象层把正在发生的事情藏起来。但这是我的偏好，不是普遍建议。下面把每个选项能给你的东西讲清楚。

候选者

Laravel Herd

Herd 是最新的选择，对很多开发者来说也是正确的选择。它是原生应用（macOS 和 Windows，还没有 Linux），不用 Docker 就能给你 PHP、Nginx、Node.js 和 Dnsmasq。Pro 版还加入 MySQL、PostgreSQL、Redis 和调试工具。

杀手级特性是：几秒内切换 PHP 版本（7.4 到 8.4）、自动路由 *.test 域名，而且没有 Docker 开销。如果你在做一套标准 Laravel 应用，又不需要什么奇怪服务，Herd 能让你一分钟内开始写代码。

Laravel Sail

Sail 是 Laravel 官方的 Docker 开发环境。它用一个 sail CLI 包住 Docker Compose，抽象掉常用命令（sail up、sail artisan、sail php）。

截至 Laravel 12，Sail 默认带 PHP 8.5，使用 compose.yaml（现代文件名，不是 docker-compose.yml），并且开箱包含给 Octane 用的 Swoole。它也支持通过 --devcontainer 生成 devcontainer，方便和 VS Code/GitHub Codespaces 集成。

默认服务：PHP、MySQL、Redis、Meilisearch、Mailpit 和 Selenium。

Laradock

Laradock 是瑞士军刀。它是一套开源 Docker 环境，支持任何 PHP 项目，不只支持 Laravel。它提供 70 多个预配置服务，也可以配置成生产用途。

截至 2025 年 12 月它仍在活跃维护（近期有 PHP-FPM 和 workspace 镜像更新）。代价是复杂度：搭建要更久，配置要改多个文件，而且你需要真正懂 Docker。

FrankenPHP + Octane

FrankenPHP 是构建在 Caddy 之上的现代 PHP 应用服务器。结合 Laravel Octane，它可以把每次请求的框架启动时间压到 4-6ms；有开发者报告说，切到 Worker Mode 后延迟从 7 秒降到了 66ms [1]。

Laravel Cloud 在生产环境的 Octane runtime 里使用 FrankenPHP [2]。最新版本（v1.11.2，2026 年 2 月）借助 Go 1.26 带来了快 30% 的 CGO 和快 40% 的垃圾回收。

这不是传统意义上的开发环境，它是生产级 PHP runtime，只是你也可以在开发中使用。Sail 内置了用 FrankenPHP 或 Swoole 运行 Octane 的集成。

什么时候用什么

下面是我的诚实看法，基于真实用过这些工具之后的判断：

如果你是个人或小团队，做的是标准 Laravel 应用，而且不想在基础设施上花时间，用 Herd。 这是从“我有个想法”到“我正在写代码”的最快路径。限制是它只支持 macOS/Windows，而且免费版不包含数据库。

如果你的团队需要环境一致性，依赖特定服务版本（Redis 7、MySQL 8、PostgreSQL 15），或者你的 CI/CD 流水线需要 Docker，用 Sail。 Sail 的 sail:publish 命令允许你在默认配置不够用时定制 Docker 设置。

如果你跨多个 PHP 框架工作（Symfony、Shopware、原生 PHP），需要比较冷门的服务（Aerospike、RethinkDB、Manticore），或者想要一套 Docker 环境服务多个项目，用 Laradock。学习曲线更陡，但灵活性无可比拟。

如果 Sail 和 Laradock 都满足不了你，而且你想要完全控制，用自定义 Docker Compose。 我自己就是这么做的。我维护自己的 compose.yaml，里面只有我需要的服务，没有抽象层，再配一些 Docker Compose 别名让命令短一点。前期工作更多，但没有魔法，一切都写在明处。

如果你在做高性能 API，或者应用对延迟敏感，用 FrankenPHP + Octane。 性能差距不是边角料级别，而是一个数量级。即便你平时用别的工具做通用开发，也值得研究一下。

真正重要的细节

搭建时间

工具	到第一次请求的时间
Herd	1 分钟以内
Sail	5-10 分钟（拉镜像）
Custom Compose	30-60 分钟（初次搭建）
Laradock	1-2 小时（完整配置）

定制能力

Sail 是有意限制的。你得到的是 Laravel 需要的服务，没有太多别的东西。你可以运行 sail:publish 再编辑 Dockerfile 来定制，但到那一步，你其实是在维护一套自定义 Docker 设置，上面还叠着 Sail 的抽象。这是两边都不讨好的形状。

Laradock 给你一切，但要求你理解自己启用了什么。打开一个服务意味着编辑 .env，可能还要改 docker-compose.yml，有些服务还有自己的配置目录。

Custom Compose 给你的东西正好等于你写下来的东西。不多，也不少。

生产就绪度

Sail 明确不是给生产用的。Laradock 可以配置成生产可用，但你需要知道自己在安全加固、资源限制和正确网络配置上做什么。FrankenPHP 从设计上就是生产就绪的，它就是为这个而生。

多项目支持

Sail：一个环境对应一个项目。你可以同时跑多个 Sail 实例，但它们会争端口。

Laradock：为多项目设置而设计。一套环境，多个项目，共享服务。

Custom Compose：取决于你怎么设计。我通常每个项目单独一份 compose 文件，同时定义共享网络。

我实际在用什么

Custom Docker Compose。我给所有东西都配了别名：dcu 表示 docker compose up -d，dce 用来 exec，dcefpm 进 PHP-FPM shell，还有一个会自动发现项目根目录的 sail 函数。这套东西在我的 Docker Compose 演进笔记里。

我很多年前从 Laradock 开始，Sail 发布后切到 Sail，最后落在自定义配置上，因为我想明确知道到底在跑什么，以及为什么这样跑。每一层抽象都会隐藏决定。有时候这没问题。有时候这些被隐藏的决定会造成很难调试的问题，因为你根本看不见它们。

话虽如此，如果我今天带一个不关心 Docker 内部细节的团队新开 Laravel 项目，我会用 Sail。如果我在指导刚接触 Laravel 的人，我会让他们装 Herd，然后立刻开始写代码。

其他值得一提的选择

DDEV -- 基于 Docker，Laravel 支持不错，2026 路线图活跃，并计划集成 Gitpod。如果你也在其他 CMS 项目（WordPress、Drupal）里用它，值得评估。
Lando -- 另一套 Docker 抽象层，带 Laravel 插件（v1.10.0，2026 年 1 月）。理念类似 Sail，但不绑定具体框架。
Valet -- Herd 的前身。仍然可用，但对大多数场景来说 Herd 已经取代它。

参考资料

1. 用 FrankenPHP Worker Mode 设置并加速 Laravel -- 真实性能对比：延迟从 7s 到 66ms。
2. Laravel Cloud 如何在生产环境使用 FrankenPHP -- DevConf 上关于 Laravel Cloud 的 Octane runtime 的演讲。
3. Laravel 12.x Sail 文档 -- 官方 Sail 文档，包含 PHP 8.5 和 compose.yaml 变更。
4. Laravel Herd -- Laravel 原生开发环境官网。
5. FrankenPHP v1.11.2 发布 -- 2026 年 2 月发布，带性能和安全更新。
6. GitHub 上的 Laradock -- 仍在维护，2025 年 12 月有更新。
7. 本地 Laravel 开发的当前状态 -- Andrew Schmelyun 的生态概览。

Docker Compose 演进：变化了什么，为什么重要 -- 影响所有这些工具的 Docker Compose 变化。
PHP 8.5：即将到来的功能巡览 -- Laravel 12 默认 PHP 版本里会出现的新东西。
在 macOS 上用 phpenv 安装 PHP 8.3.6 + IMAP -- 当你需要 Docker 之外的特定 PHP 设置时。

最糟糕的伪君子：一只橡皮鸭的自爱故事

Wed, 17 Jul 2024 12:00:00 GMT

Boris 写给一位珍贵的朋友： ~ 那个我总是很难理解，却又最理解一切的人。 ~

嘿。又见面了。我们可以重新第一次见面吗？嗯。我觉得这次会更酷一点。我会比以前更肉麻 🧀，努力让你多笑一点，但还是会有时候失败，或者大多数时候失败，或者随便啦…… 它几乎会像上一次，但又不像上一次。注：你可以假装我上一句说得通，就为了显得高级一点 🥸

让我先给一个小词典，或者开场白，或者小小的知识库：

把 "beginning" 倒过来，是 "gninnigeb"

我只是需要一个新标题，让我的段落看起来漂亮一点。总之，新的我。新的你。旧衣服，还有一些旧坏习惯。呼！

墙上的一面镜子

我很想你，也想了我的错误很久。镜子存在，确实是为了让我们更漂亮，也更不脏一点。

一只橡皮鸭

这就是我。我是一只橡皮鸭。我是橡胶做的，这意味着我的头也是橡胶做的。

橡皮鸭不会“嘎嘎叫”。还是会？

以我作为一只橡皮鸭的谦卑人生经验来说，我确实会“嘎嘎叫”，而且还叫得相当多。😆

一只嘎嘎叫的橡皮鸭在嘎嘎叫

嘎！嘎！嘎！- 鸭子说，然后又嘎了一声。惊人的声音！不是吗？

一只有态度的橡皮鸭

我是所有橡皮鸭里最善良的一只，橡皮鸭说，然后兴奋地嘎了一声！嘎！

橡皮鸭真正的衰亡

嘎嘎叫会很累的，你知道。用一口新鲜空气，你只能漂亮地嘎有限次数。但你空了的时候，还是可以试着漂亮地嘎，对吗？当然可以！你可以试着嘎！你甚至可以从自己的橡胶里挤出最棒的一声快嘎嘎，好帮助其他空空的橡皮鸭吸一口空气。

给两只半空橡皮鸭的短故事

“你知道吗？” - Duckitty 说 “什么？” - Duckelton 说 “当我嘎嘎叫太多，我就再也嘎不出来了，可我还想嘎嘎叫，这让我难过。” - Duckitty 回答 Duckleton 摆出非常严肃的表情，皱起眉头，用智慧的声音说： “嗯。我也一样！”

那只讨厌沉默的橡皮鸭

Duckleton 讨厌沉默，只要有机会就响亮地嘎一声。有时候他很空，会怀疑自己是不是够黄，能不能嘎嘎叫。但你看，制造 Ducleton 和 Duckitty 的那家工厂，把他们两个都做得完美地黄。 Duckleton 是一只有态度的橡皮鸭。他觉得自己可以，也必须，嘎过每一只其他鸭子，好把它们从空了还不能嘎嘎叫的羞耻里救出来。 Duckitty 有时候也有类似的想法，或者至少 Duckleton 脑子清楚的时候是这么想的。（有时候他并不清楚 😆）但 Duckleton 是一只骄傲的橡皮鸭。一只由世界上最好的工厂制造的橡皮鸭，那家工厂几个世纪以来都在制造世界上最会嘎嘎叫的黄色橡皮鸭。至少 Duckleton 在遇见 Duckitty 之前是这么想的。他一遇见她，就被她的声音惊住了，于是觉得她一定是由某个外星工厂制造的，比他来的那个地球工厂好多了。他很高兴自己有机会只是欣赏这只名叫 Duckitty 的、奇妙而完美的橡皮鸭，她比他好得多（他这么以为）。 “嗯，看着她真好。她那么黄。她那么好。她的声音比我漂亮多了。我是一只幸运的橡皮鸭。” - Duckleton 心想。

一个短短的、但有点难过的故事

Duckleton 和 Duckitty 都很快乐，嘎嘎叫得像是在参加世界和外太空最棒的嘎嘎大赛。有一次，一个人类小孩过来捏了 Duckleton。他有一阵子嘎不出来，但还是很想嘎，所以他没有抱怨，保持沉默，深吸一口气，然后他们两个又快乐地继续嘎嘎叫。过了一些时间，Duckitty 也被一个讨厌的人类小孩拿走了。那个小孩把 Duckitty 里面所有空气都挤了出来，但 Duckleton 太忙着嘎嘎叫，没有注意到。 Duckitty 没事，但她得吸点空气。 Duckleton 悲伤得超过绝望。他以为自己最喜欢的鸭子坏了，而他又要直到宇宙尽头都永远孤单。他只是忘了，不久前同一个小孩也捏过他。 Duckleton 骄傲但笨，毕竟他只有一个小小的橡胶脑袋。Duckitty 一嘎叫，Duckleton 就怒了。他既开心她还活着，又有点泄气，因为他以为 Duckitty 比他更能熬过人类小孩的一捏。毕竟她比他完美得多，对吧？

Duckleton 的内疚之旅

Duckleton 是所有橡皮鸭里最糟糕的伪君子，而他终于学明白了。他很难过，但他想：去向 Duckitty 道歉吧，并向她表达一点感激，感谢她就是这样完美。

尾声

我亲爱的朋友，过去 8 年里你一直都很完美。每一天都很完美。我真的很抱歉自己这么伪君子，但坏事总会发生，你知道的。而我们还是继续往前走。请你更爱自己，多很多。我很笨。你很聪明。或者随便啦……但请你更爱自己，多很多，因为你原本这样就很完美！事实上，你是世界上最完美的黄色橡皮鸭。至少我是这么想的。我的橡胶脑袋很小。但是，耶！我还是会思考。🫶 嘎！

嘎，嘎，嘎 ~ Duckleton

RL 中的离散表示：Edan Meyer 的研究洞见

Mon, 15 Jul 2024 00:00:00 GMT

你有没有想过，AI 智能体是怎样学会理解复杂环境并与之互动的？强化学习（RL）研究者 Edan Meyer 一直在探索一种有趣的方法，它也许会改变我们思考 AI 学习的方式。我们来看看他关于 RL 中离散表示的这项迷人工作。

表示的力量

想象你要教一台计算机玩电子游戏。你会怎样表示游戏状态，才能让计算机理解它，并从中学习？这正是表示学习登场的地方，也是构建有效 AI 智能体时至关重要的一环。

Edan Meyer 的工作可以在他的 YouTube 频道上看到。他一直在研究一种特定类型的表示，叫作离散表示。他在一篇可在 arXiv 阅读的论文中详细介绍了这项研究，也说明了为什么这类表示在某些 RL 场景中特别有用。

两年研究，压缩进 13 分钟

Edan 把两年的硕士研究浓缩成了一支 13 分钟的视频，标题是 "2 Years of My Research Explained in 13 Minutes"。在视频里，他把复杂概念拆成容易消化的解释，让更广泛的观众也能接近这项工作。

正如 Edan 在视频描述中写的：

"This is my research into representation learning and model learning in the reinforcement learning setting. Two years in the making, and I finally get to talk about my Master's research! The paper has been accepted to the Reinforcement Learning Conference (RLC) 2024."

如果你想理解这项研究的基础，而暂时不想直接扎进完整的学术论文，这支视频是一个很好的起点。

什么是离散表示？

传统上，很多 RL 系统使用连续表示。你可以把它们想成由小数组成的向量，每个数都可以取任意值。离散表示则更像是一串选择题。表示中的每一个“槽位”只能从固定数量的取值中选择一个。

正如 Edan 在视频中解释的，这一开始听起来可能很受限。毕竟，一个连续值可以表示无穷多种状态，而一个离散值的范围要小得多。那么，为什么还要使用离散表示？

意外的好处

Edan 的研究发现，使用离散表示有一些很有意思的优势：

用更少容量构建更好的世界模型：当 AI 试图学习环境模型，也就是所谓的“世界模型”时，离散表示让它可以用更少的计算能力捕捉更准确的信息。尤其是在模型没有足够容量完美表示环境中一切内容的时候，这一点特别明显。而在复杂的现实问题里，这种情况很常见。
更快适应：在环境随时间变化的实验中，使用离散表示的智能体能够更快适应这些变化。对于需要在动态、不可预测环境中运行的 AI 系统来说，这可能至关重要。
高效学习：离散表示一开始也许需要更长时间才能学成，但一旦建立起来，它们会让世界建模和策略学习任务中的学习与适应都变得更快。

这为什么重要？

Edan 这项工作的意义远不止简单的网格世界实验。正如他在视频中指出的，真实世界比我们能创造的任何仿真都复杂得多。在这样的环境里，AI 不可能学会一切。关键在于适应。

离散表示似乎提供了一种强有力的工具，用来构建能够快速适应新情况的 AI 系统，即便它们不可能把环境的每个方面都建模出来。从机器人到复杂策略游戏，再到更远的地方，这都可能成为一个转折点。

继续深入

如果你对技术细节感兴趣，Edan 的论文探讨了离散表示为什么如此有效的一些迷人侧面。比如，他发现并非所有离散表示都一样。稀疏性和二值性等因素，会在它们的效果中扮演重要角色。

结论

Edan Meyer 关于强化学习中离散表示的工作，为我们如何构建更具适应性、更高效的 AI 系统提供了令人兴奋的洞见。通过挑战我们关于 AI 信息表示方式的传统看法，他的研究打开了新的可能性：让智能体能够在复杂、动态的环境中站稳脚跟。

无论你是 AI 研究者、机器学习学生，还是只是对技术前沿感到好奇的人，Edan 的工作都让人得以窥见人工智能的未来。可以去看看他的 YouTube 频道、讲解视频，以及那篇论文，更深入地探索这些想法。

记住，在快速变化的 AI 研究世界里，今天的实验技术可能就是明天的突破性技术。离散表示也许正是解锁更强大、更能适应变化的 AI 系统的关键。

Google AI 历史：承诺、股价表现与影响

Sat, 11 May 2024 12:00:00 GMT

Google 在 Gemini 系列等 AI 技术开发与市场推广上的历程，是一个很有意思的案例：企业承诺、股票市场表现与技术创新如何彼此牵动。本文分析 Google 的 AI 承诺在若干具体历史节点上如何显著影响其股价，并同时回顾其中的成功与失败。

这家科技巨头进入 AI 领域的过程，一直伴随着雄心勃勃的项目和大胆宣称。从 2015 年推出 TensorFlow、确立 Google 在 AI 研发中的领导地位，到 2016 年推出 Google Assistant、增强其对 Amazon Alexa 和 Apple Siri 等竞争对手的竞争力，Google 一直试图推动 AI 能力的边界 [1]。

Google AI 发展的关键历史里程碑

TensorFlow 推出（2015）：Google 将其机器学习框架 TensorFlow 开源，随后它迅速流行起来。此举帮助 Google 确立了 AI 研发领导者的地位，也正面影响了市场对它的看法 [1]。TensorFlow 被用于各种应用，从改进搜索结果到驱动自动驾驶汽车。
Google Assistant 发布（2016）：Google Assistant 的推出增强了 Google 在 AI 领域对 Amazon Alexa 和 Apple Siri 等竞争对手的竞争力。市场对此反应积极，因为它体现了 AI 驱动用户界面的潜在增长空间 [2]。Google Assistant 被集成进智能手机、智能家居设备和汽车，成为语音助手市场的重要玩家。
量子计算进展（2019）：Google 宣布在“量子霸权”上取得突破，声称其量子计算机能够完成传统超级计算机无法胜任的计算。这一公告带来了短暂的股价上涨，也展示了投资者对 Google 前沿技术能力的热情 [3]。

股票市场表现与 AI 里程碑

股票市场对 Google 的 AI 进展反应不一。重大公告，比如量子计算突破和新 AI 产品发布，通常会带来短期股价上涨。不过，长期来看，股价影响更紧密地取决于这些技术是否真正落地，以及能否取得商业成功。

S&P 500 里程碑：Google 的重大 AI 公告经常与更广泛的市场趋势重合。例如，2021 年的大牛市中，Google 在 AI 取得显著进展的同时也创下新的股价高点，反映出投资者对技术驱动增长的强烈信心 [4]。

图 1 - Google 股价里程碑。

成功与失败

成功：Google 的 AI 在语言翻译、图像识别，以及通过 Waymo 推动自动驾驶技术等领域取得了可观成功。这些成功帮助巩固了 Google 作为技术创新者的声誉 [5]。
失败：并非 Google 的所有 AI 计划都达到了市场预期。例如，备受期待的 Google Glass 项目没能打动消费者，最终停产。该产品面临隐私担忧，也没能为普通消费者提供足够有说服力的使用场景。同样，Gemini 1.5 Pro 周围的延迟和过度承诺，也引发了用户不满和怀疑 [6]。Google 从这些失败中吸取了教训，开始更专注于务实的 AI 应用，并改善与用户的沟通。

图 2 - 科技公司 AI 里程碑。

市场影响与未来展望

Google AI 的市场影响相当显著，不仅影响自身股价，也影响更广泛科技行业的方向。AI 领域仍然是投资者关注的重点，这一点也体现在 S&P 500 的表现中，其中科技股扮演着重要角色 [4]。

往前看，Google 能否兑现其 AI 承诺，并克服技术部署中的挑战，将至关重要。该公司如果能更有效地提升透明度、管理消费者预期，可能会决定其未来的市场位置和投资者信任。

一个值得关注的关键领域，是 Google 在 Gemini 系列 AI 模型上的进展。Gemini 1.5 Pro 于 2024 年 2 月发布，承诺在 AI 能力上实现显著跃升，但其推出过程已经遇到挑战 [6]。Google 如何处理这些挑战并兑现承诺，很可能会对其 AI 声誉和市场地位产生明显影响。

Google 在人工智能上的雄心勃勃推进，尤其是通过 Gemini 系列，标志着 AI 技术进入一个变革性阶段。作为该系列的一部分，Gemini 1.5 Pro 的推出突显了 Google 持续推动 AI 能力边界的决心。不过，Gemini 1.5 Pro 的推出并非没有挑战。理解这些挑战，对于理解这类先进 AI 模型的潜力与局限同样重要。

专家对 Gemini 1.5 Pro 的看法

性能与能力：Gemini 1.5 Pro 建立在 Mixture-of-Experts（MoE）架构之上，相比前代模型有显著改进，包括上下文窗口大幅增加到最高 1000 万 tokens。这项增强使它能更好处理涉及大量数据和多种格式的复杂任务，包括文本、代码、视觉和音频 [7]。Encord 的 Stephen Oladele 表示，"Gemini 1.5 Pro maintains near-perfect recall across the entire context and uses a mixture-of-experts architecture for more efficient training & higher-quality responses" [7]。

推出过程中的挑战：尽管能力先进，Gemini 1.5 Pro 的推出仍面临多项挑战。该模型目前处于 private preview，general availability 安排在更晚时间，这说明部署采用了分阶段方式 [7]。这种谨慎的推出策略，可能源于 Google 需要进一步微调模型，并确保它能满足前代产品和市场共同抬高的期待。

行业分析师的观点

对 AI 行业的影响：行业分析师认为，Gemini 系列是 Google 的重要一步，有可能为 AI 模型能力树立新的标准。Gemini 系列，尤其是 1.5 Pro，预计将增强 Google 相对于 OpenAI 和 Microsoft 等科技巨头的竞争力；这些公司也一直在积极推进自己的 AI 能力 [8] [7]。

市场含义：Gemini 1.5 Pro 的进展很可能影响医疗、金融等多个行业，使更复杂的 AI 应用成为可能。这可能改变市场动态：那些能有效整合此类先进 AI 技术的公司，可能获得显著竞争优势 [7]。

来自 Google 高管的洞见

未来计划与伦理考量：包括 Sundar Pichai 在内的 Google 高管一直强调，公司致力于负责任的 AI 发展。Pichai 强调，AI 进步需要与伦理准则对齐，并确保这些技术被用于社会利益 [2] [9]。随着 AI 能力增强并融入日常应用，这种做法变得至关重要。

应对挑战与把握机会

处理技术挑战：为了应对未来挑战，Google 必须继续投入研发，解决模型可靠性和伦理关切等问题。该公司逐步推出 Gemini 1.5 Pro 的方式，显示出一种在问题变得严重之前先降低风险的策略 [7]。

扩大市场机会：Google 可以利用 Gemini 1.5 Pro 的能力创造新的市场机会，尤其是在需要处理大型数据集和复杂问题求解场景的行业。通过提供能简化 AI 融入业务流程的工具，Google 可以帮助各行业转变运营方式，并实现更高效率 [10]。

伦理 AI 发展：随着 AI 技术变得更强大，伦理影响也变得更重要。Google 通过 AI principles 和治理框架展示出的持续负责任 AI 发展承诺，将是维持公众信任和监管合规的关键 [11]。

总之，Gemini 1.5 Pro 的推出虽然带来挑战，也为 Google 在 AI 领域取得领先提供了实质机会。只要继续聚焦性能提升、伦理 AI 发展和市场扩张，Google 就能更有效地穿过这些挑战，并为 AI 在各行业中的能力设定新的标准。

结论

Google 的 AI 旅程说明了技术创新、市场预期和企业战略之间复杂的动态关系。虽然公司经历过显著成功，也遭遇过挫折，但它在 AI 领域的持续努力仍然吸引着市场的强烈关注。投资者和市场观察者很可能会继续密切关注 Google 能否把 AI 能力转化为可持续增长和市场领导力。

随着 AI 格局继续快速演进，Google 作为 AI 先行者的位置也将受到检验。公司能否在雄心勃勃的创新、现实可行的执行、透明沟通和有效的预期管理之间取得平衡，将是决定其在 AI 领域长期成功和整体市场表现的关键因素。

参考资料

1. Emeritus - Google AI Strategy 2. Google Blog - Gemini AI 3. Yahoo Finance - GOOGL Quote 4. Wikipedia - S&P 500 Milestones 5. Think with Google - AI Tools 6. Times of India - Gemini 15 Pro AI Release 7. Encord - Google Gemini 1.5 Generative AI Model with Mixture of Experts 8. Built In - Google Gemini 9. CBS News - Google's AI Future 10. Google Cloud - Generative AI 11. Google Blog - Responsible AI

Stable Diffusion 照片真实感：设置与 GPU 极限指南

Thu, 04 May 2023 23:45:00 GMT

2026 年 3 月更新。 这篇文章最初写于 2023 年 5 月，当时 SD 1.5 的 512x512 是标准，RTX 3090 是顶级硬件。现在一切都变了。Flux 2、SDXL fine-tunes、SD 3.5、ControlNet 和 RTX 5090 已经完全重新定义了可能性。这就是当前状态。

AI 生成图像和真实照片之间的差距几乎已经闭合。2023 年，“照片真实感”的意思是“眯起眼看几乎能信”。到了 2026 年，最好的模型生成的图像已经真的很难和专业摄影区分开。

下面是怎么做到。

当前照片真实感版图

你选择的模型，比你调整的任何设置都更重要。现在的情况是这样：

Flux 2 -- 新王

Flux 2 来自 Black Forest Labs（2025 年 11 月发布），可以说是 2026 年最好的 open-weight 照片真实感模型 [1]。它生成的图像有自然光照、准确的皮肤纹理和连贯构图，足以和专业摄影相提并论。Adobe 在 2025 年 9 月把 Flux（Kontext Pro）集成进 Photoshop [2]，这已经说明了行业信心在哪里。

Flux 还拥有非常出色的自然语言理解能力。你可以用普通英语描述想要什么，不再需要 SD 1.5 那种关键词浓汤。

SDXL Fine-Tunes -- 干活的主力

对于基于 SDXL 的照片真实感，目前的领先者是：

Juggernaut XL v9/v10 -- 电影感、摄影风输出的默认选择。在摄影师和电影制作者中最受欢迎。
Realistic Vision -- 专门针对逼真纹理、光照和面部准确性 fine-tuned。
EpicRealism -- 细节和自然光照都非常强。

这些模型有庞大的社区支持、丰富的 LoRA 库和可预期的行为。如果 Flux 感觉还太新，或者你的工作流建立在 SDXL 上，它们都是很好的选择。

SD 3.5 Large

Stability AI 的旗舰模型使用新的 Multimodal Diffusion Transformer（MMDiT）架构，和 SDXL 是根本不同的路线。它技术上很厉害，但生态更小。SD 3.0 已在 2025 年 4 月 deprecated，所以确保你用的是 3.5 [3]。

GPU 现实检查

硬件要求已经明显抬高。

GPU	VRAM	照片真实感能力
RTX 3060 12GB	12GB	只适合 SD 1.5 照片真实感。SDXL 会很紧
RTX 4070 Ti	12GB	1024x1024 的 SDXL。通过优化可以跑 Flux
RTX 4090	24GB	甜点位。可以舒服处理 1024x1024+ 的 SDXL、Flux、SD 3.5
RTX 5090	32GB	全都能跑，包括 4K 生成和 batch workflows。32GB GDDR7，512-bit bus [4]
8GB cards	8GB	借助 ComfyUI 的 VRAM 管理勉强可用。不舒服

2023 年那个“RTX 3080 上跑 512x512”的甜点位已经是古代史。1024x1024 现在是标准分辨率，而你至少需要 16GB VRAM，才能不被持续的小挫败折磨。24GB 开始舒服。

专门针对照片真实感来说，更多 VRAM 意味着你可以同时运行更大的模型、更高分辨率和 ControlNet，而不用 offload 到 CPU。

照片真实感设置

Sampler

DPM++ 2M Karras，25-30 steps。这是 SDXL 照片真实感已经沉淀下来的共识，速度和质量的比例最好。如果你想在低 step 数下要稍微更多细节，切到 DPM++ SDE Karras。

对于 Flux：使用默认 sampler，20-30 steps。

CFG

对于 SDXL 照片真实感：7-9。这能给出强 prompt adherence，同时避免 10 以上常见的过饱和、过度烹煮感。

对于 SD 3.5：从更低开始（3-5），因为 guidance 机制不同。

对于 Flux：遵循模型自己的建议，但通常比 SDXL 更低。

Resolution

在模型原生分辨率生成（SDXL/SD 3.5/Flux 为 1024x1024），然后再为更高分辨率做 upscale。不要试图直接生成 2048x2048，你会得到 artifacts、重复元素和构图问题。

Upscaling 选择：A1111 里的 hi-res fix，或者 ComfyUI 里的专用 upscaling nodes（4x-UltraSharp、ESRGAN）。

Prompting for Photorealism

和 2023 年相比最大的变化是：自然地写，不要写关键词。

SD 1.5 需要这样的 prompts：

portrait of a woman, photorealistic, 8k, ultra detailed, sharp focus,
professional photography, Fujifilm X-T4, 85mm f/1.4

SDXL 和 Flux 能理解：

A portrait of a woman in soft afternoon light, photographed with a shallow
depth of field. She's looking slightly off-camera with a natural expression.

关键词浓汤在 SDXL 上仍然能用，但自然语言会产生更连贯的结果。尤其是 Flux，非常擅长描述性、对话式 prompts。

Negative prompts： 保持最小。先从没有开始，然后加入具体修正。cartoon, illustration, painting 通常就足够让画面保持照片真实感。完整的 negative prompt 思路转变可以看 cheat sheet。

ControlNet 改变一切

如果你认真追求照片真实感构图，ControlNet 是不可商量的。它让你通过下面这些方式控制图像结构：

Depth maps -- 保持空间关系和透视
Canny edge detection -- 保留轮廓和形状
OpenPose -- 控制人体姿势和身体比例
Surface normals -- 让光照和表面发生真实交互

ControlNet 模型现在已经可用于 SDXL、Flux 和 SD 3.5 [5]。Multi-ControlNet（叠加多个控制）能给你 prompt engineering 单独做不到的精确构图控制。

工作流是：拿一张参考照片，提取 depth map 或 pose，把它作为 ControlNet input，然后生成同构图的照片真实感图像。

速度 vs. 质量

如果你需要快速迭代（概念工作、prompt 测试），用 SDXL Lightning。它能用 2-8 steps 生成质量不错的 1024px 图像 [6]。在更高分辨率上，它比 SDXL Turbo 质量更好。

最终输出时，切回完整 SDXL 或 Flux，25-30 steps。差异看得出来。

实用工作流

下面是 2026 年照片真实感输出真正有效的流程：

选择模型 -- 最佳照片真实感用 Flux 2，SDXL 生态用 Juggernaut XL
写自然语言 prompt，描述你看到的画面
以 1024x1024 生成，DPM++ 2M Karras，CFG 7-9，25-30 steps
使用 ControlNet，如果你需要特定构图（depth 或 pose）
迭代 prompt -- 生成 4-8 张，选最好的
Upscale 胜出的那张到目标分辨率
Inpaint 任何问题区域（手、眼睛、小细节）

无论你在 ComfyUI 还是 A1111 里，这都是同一套工作流。工具不同，pipeline 不变。

参考资料

1. Flux 2 Models -- Black Forest Labs -- Flux 2 官方模型页面。
2. FLUX.2 and NVIDIA RTX AI Garage -- Flux 2 与 ComfyUI 集成，以及行业采用情况。
3. Stability AI Release Notes -- SD 3.0 deprecation 和 3.5 发布细节。
4. RTX 5090 vs 4090 for AI Workloads -- 面向图像生成的硬件对比。
5. ControlNet Complete Guide -- 面向多种架构的新版 ControlNet 文档。
6. SDXL-Lightning by ByteDance -- 2-8 step 生成模型。
7. Best Stable Diffusion Models for Photorealism 2026 -- 当前模型版图。
8. Top Photorealistic Stable Diffusion Models -- Civitai 社区评测。

Stable Diffusion Cheat Sheet：故障排查与优化 -- 参数、samplers 和故障排查的快速参考。

Stable Diffusion 速查表：故障排查与优化

Thu, 04 May 2023 23:30:00 GMT

2026 年 3 月更新。 这份速查表的最初版本写于 2023 年 5 月，当时面向的是 SD 1.5。此后几乎一切都变了：新的架构（SDXL、SD 3.5、Flux）、新的 UI（ComfyUI）、新的硬件（RTX 5090），以及关于负面提示词哲学的一次彻底反转。这是当前版本。

这是我工作时查 Stable Diffusion 参数用的参考。不是教程，只是当事情不对劲，或者我想把质量再推高一点时，会伸手去调的那些设置。

该用哪个模型

现在这是第一个决定，而且它比任何参数微调都更重要。

模型	最适合	分辨率	备注
Flux 2	写实主义、提示词遵循度	1024x1024+	2026 年最好的开放权重写实模型。已集成进 Adobe Photoshop [1]
SDXL	通用场景	1024x1024	微调生态极大。Juggernaut XL、Realistic Vision、DreamShaper
SD 3.5 Large	顶级质量（Stability 的旗舰）	1024x1024	MMDiT 架构。SD 3.0 已于 2025 年 4 月废弃 [2]
SDXL Lightning	速度	1024x1024	2-8 步生成。在更高分辨率下质量优于 Turbo [3]
SD 1.5	遗留工作流	512x512	微调库巨大，但正在被逐步淘汰。SD 2.0/2.1 已正式废弃

如果你从零开始：写实主义用 Flux 2，其他都用 SDXL。 SD 3.5 很好，但生态更小。

该用哪个 UI

UI	最适合
ComfyUI	进阶用户。基于节点，更好的显存管理，快 15%，对 Flux 支持最好。截至 2025 年，是严肃工作的行业标准 [4]
Automatic1111	初学者。界面更简单，扩展库巨大。用于 SDXL 仍然没问题
Fooocus	一键生成。配置最少。适合快速出结果

我用 ComfyUI。学习曲线更陡一些（预期要 10-20 小时才能顺手），但光是显存管理就值了：A1111 会崩的 8GB 显存，它能跑 SDXL。

采样器

采样器之争基本已经定下来了。

常用选择：

DPM++ 2M Karras -- 速度和质量的最佳比例。这是我几乎所有事情的默认选项。
DPM++ SDE Karras -- 在低步数时略好。适合快速迭代。
Euler a -- 依然可靠。输出变化更多，适合探索。

什么时候切换：

输出缺少多样性？试试 DPM++ SDE 或 Euler a。
有伪影或过饱和？试试 DPM++ 2M Karras 或普通 Euler。
速度压倒一切？Euler a 或 DPM++ 2M（非 Karras）。
想要最高质量？DPM++ 3M SDE Karras 或 UniPC。

步数： 大多数采样器用 20-30 步。Lightning 模型只需要 2-8 步。

CFG（Classifier Free Guidance）

模型有多严格地跟随你的提示词，而不是按自己的理解发挥。

范围	效果
1-4	非常有创造性，理解很松。经常不连贯
5-7	适合大多数工作的良好平衡
7-10	提示词遵循度强。SDXL 写实主义的甜点区
10-15	有伪影和颜色过度处理的风险
15+	几乎总是太多。伪影基本保证出现

注意： SD 3.5 使用不同的 guidance 机制。CFG 这个概念仍然适用，但尺度表现不同：从更低的值开始（3-5），再往上调。

分辨率

512x512 的时代结束了。

模型	原生分辨率	实用范围
SD 1.5	512x512	512x512 到 768x768
SDXL	1024x1024	1024x1024（标准）、1024x768、768x1024
SD 3.5	1024x1024	1024x1024+
Flux	1024x1024	1024x1024+，高端 GPU 可到 4K

超过原生分辨率会增加伪影和构图问题的风险。不要直接生成 2048x2048，用 hi-res fix 或放大。

Clip Skip

没有以前那么重要了。

SD 1.5： Clip skip 1-2 很重要。动漫模型经常用 clip skip 2。
SDXL： 使用双文本编码器（CLIP + OpenCLIP）。Clip skip 基本会被忽略，架构处理方式不同。
SD 3.5 / Flux： 不能以同样方式适用。这些模型使用基于 transformer 的文本编码。

如果你用的是 SDXL 或更新模型：不用担心 clip skip。如果你用的是 SD 1.5：写实主义保持 1，动漫用 2。

负面提示词

哲学已经反过来了。 2023 年的建议是使用很长的负面提示词列表。到 2026 年，共识是：先什么都不写，只在需要修复时添加具体内容。

为什么会变：

SDXL 和 Flux 对自然语言的理解远好于 SD 1.5
很长的负面提示词实际上可能会限制创造性，并产生更差的结果
"bad anatomy" 太模糊，没什么用。"ugly" 也不起作用，因为 SD 不是在带有 "ugly" 标签的图像上训练出来的
有些模型在长负面提示词下表现明显更差 [5]

当前做法：

先不加任何负面提示词生成。
如果看到具体问题（多余手指、背景模糊），再针对那个问题添加负面提示词。
使用强调权重：写 (blurry:1.3)，而不是只写 blurry。
保持简短：最多 5-10 个词。

GPU 快速参考

GPU	显存	适合
RTX 3060 12GB	12GB	SD 1.5、基础 SDXL
RTX 4070 Ti	12GB	SDXL、部分 Flux
RTX 4090	24GB	一切。主力干活卡
RTX 5090	32GB	包括 4K 和批量生成在内的一切
8GB 卡	8GB	最低可用。ComfyUI 有助于显存管理

24GB 是一个分界线：SDXL 和 Flux 在这里开始舒服，不用一直和显存较劲。

故障排查速修

问题	试试
输出模糊	增加步数。检查分辨率是否匹配模型原生分辨率
多余手指/肢体	把 `extra fingers, extra limbs` 加进负面提示词。或者使用 ControlNet
颜色过饱和	降低 CFG。切换到 DPM++ 2M Karras
构图不对	使用 ControlNet（depth、canny、pose），不要和提示词硬拗
生成太慢	使用 Lightning 模型，减少步数，用 ComfyUI 获得更好的显存表现
显存不足	切换到 ComfyUI，减少 batch size，使用 fp16

参考资料

1. Flux 2 and NVIDIA RTX AI Integration -- NVIDIA 对 Flux 2 与 ComfyUI 的介绍。
2. Stability AI Release Notes -- SD 3.0 废弃和 3.5 发布。
3. SDXL-Lightning by ByteDance -- 1024px 下 2-8 步生成。
4. ComfyUI vs Automatic1111 2026 Comparison -- 性能和功能对比。
5. How to Use Negative Prompts Effectively -- 关于最小负面提示词哲学的更新指南。
6. Understanding Stable Diffusion Samplers -- 采样器对比和选择指南。
7. Best Stable Diffusion Models for 2026 -- 当前模型格局。

Stable Diffusion 写实主义：设置与 GPU 限制指南 -- 深入讲解如何用当前模型实现写实结果。

关于我

Thu, 04 May 2023 22:12:03 GMT

写“关于”页面是一件奇怪的事。你最后会像描述一个陌生人那样描述自己，而我对这件事有点怀疑。

所以，直说吧。我是 Boris。我写软件已经十四年多一点了。这份工作付房租，养狗，也在大多数早晨给我一个可以琢磨的问题——老实说，这已经比大多数工作给得更多了。现在我是一个小产品团队里的后端那一半，大概夹在 Laravel、Docker 和 Kubernetes 之间，主要担心那些本该比填满更快清空的队列，以及那些增长速度快得让我不太舒服的索引。

写软件之前，我在大学学数学。也从来没有真正停下。数学是这个世界太吵时我会去的地方。尤其是数论——质数里有一种诚实，我在许多别的地方找不到。我在这里写的很多东西，都是从那个方向开始的。一个小小的数学痒处。一篇半懂不懂的医学论文。一个我不得不读四遍的法语句子。然后我顺着它往下拽，看看还连着什么。

这个博客就是我往下拽的地方。这里没有什么专家之作。我读自己其实没资格读的医学。我读保加利亚语和法语小说，假装自己跟得上。我慢慢学德语，主要是因为它的语法让我觉得好玩。我有时也手写 C++。不是为了工作——只是因为那种自我约束本身就有它自己的意味。这些文章都从那些东西里长出来——安静地试着把我注意到的东西写下来，趁我还没忘。

我住在索非亚。两只救助来的流浪狗——Кожухка 和 Еклер——负责确保我别把自己太当回事。它们以前失败过。现在还在继续努力。

大概就是这些。我还在 Percepticus 这个名字下面保留着一块小小的自由职业招牌，接一些靠口口相传来的活。除此之外，文章就在这里，而其余的，我也乐意保持安静。

首页 - Boris D. Teoharov (简体中文)

琥珀下的象牙

当计量表出现时

我爱的人被允许是人

我可以善良，而不消失

石柱与常春藤

田野里的一根石柱

教授忘了画常春藤

你会在哪些地方不断遇见它

一根可以抱的石柱

一个小结尾

所有科学相遇的地方

语言是一种非常高级的代码

那扇不能从里面打开的门

彼此校准

大脑并不懒

保加利亚开口说话

工程，但诚实一点

卓越就是行走

如果你不能讲给一个孩子听

所有科学相遇的地方

小小的结尾

那个并不存在的模型

那座并不存在的城市

那个从未停下的队列

批量删除的核选项：TRUNCATE + 重新插入（MySQL/InnoDB）

为什么 DELETE 还是慢（即使分块）

核选项：TRUNCATE + 重新插入

为什么它快

什么时候用它（以及什么时候别用）

适合用在

不要用在

一个实用的决策规则

实现（SQL）

实现（Laravel/PHP）

你必须考虑的坑

自增值会重置

外键

触发器

磁盘空间

复制 / binlog

如果你需要（接近）零停机

结尾想法

Type 0 重构：第一步之前的那一步

Type 0 存在的真正原因：人的工作记忆有预算

为什么叫 “Type 0”

Type 0 解决的问题

什么时候拿起 Type 0

一个可以给团队使用的定义

为什么非要命名？

四个子模式

0a. 方法提取（基础）

0b. 简洁性（减少偶然复杂度）

0c. 同理心（纯可读性）

0d. 删除死代码（移除谎言）

Type 0 不是什么

核心承诺：保持行为不变（以及如何让它是真的）

把 Type 0 变成可重复的团队仪式

1) 决定范围（timebox 有帮助）

2) 找到代码的“脊柱”

3) 按顺序应用四个子模式

4) 在 PR 里保留一个 “Type 0 checklist”

结尾想法

多洗一个盘子：让代码库长期保持干净的一条简单规则

这个隐喻：做饭、盘子和代码

手艺里的回声：你并不孤单

为什么多洗一个盘子重要（即使你很忙）

1. 熵是真实存在的

2. 债务复利得比你想的快

3. 社会信号

4. 动量，不是完美主义

如何实践多洗一个盘子规则

1. 把"微重构"纳入 Definition of Done

2. 用 Pull Requests 触发清洁

3. 自动化那些容易洗的盘子

4. 把它嵌进团队规范

5. 知道什么时候不要洗

边界：一个盘子，不是整个水槽

示例：把一个混乱函数变成可测试的函数

最后的想法

为什么 `DELETE` 还是慢（即使分块）

1. Pipe Operator（`|>`）– “Easy Peasy Lemon Squeezy”

2. `#[\NoDiscard]` – 武器化的意图

4. `php --ini=diff` – 配置漂移 X 光

6. `array_first()` / `array_last()` – 显而易见的东西终于存在了

7. `get_exception_handler()`（以及更好的 Fatal Traces）– 可观测性升级