赵培州

先别急着上 RAG：四根轴算清适用边界

Mon, 17 Aug 2026 00:00:00 GMT

大模型的上下文窗口冲到百万 token 之后，“RAG 已死”的论调隔三差五出来一次；另一边，简历里”智能客服 + RAG”仍是标配，好像不做检索增强就跟不上时代。两边都把问题想简单了。RAG 不是默认件，也不是遗产，它是一个有明确适用边界的工程选项——这篇文章把这条边界画出来。

同一个问题，两种问法，两种命运#

先把模式抽象出来。设用户想问的问题是 a，文档库里对应的答案是 A，问法有两种：

a1（行话版）——用户嘴里的词和文档里的词高度重合
a2（口语版）——用户用自己的生活语言描述同一个意图，文档原词一个没出现

a1 靠关键词检索就能命中；a2 是关键词检索的天敌。举个具体例子，某公司报销制度里写的是”探亲路费凭票报销，硬座全报、卧铺报七成”：

问法 a1：“探亲假火车票的报销标准是什么？”——“探亲""火车票""报销”全是文档原词，关键词检索秒中。制度全文不到一千字，命中后直接整篇读进上下文，什么都不用再建。
问法 a2：“我老家在外地，过年回去的高铁票能报多少？“——文档里没有”过年""回去""高铁”，关键词检索零命中。但语义上这就是探亲路费，向量检索能接住。

同一个意图，两种问法，命运完全不同。这就是检索选型的第一性原理——分界线不在数据量，不在公司规模，在用户嘴里的词和文档里的词的重合度。

四根轴，一条口诀#

轴	问什么	判断
规模	语料塞不塞得进窗口	百 K 以内可以全塞；超窗口没得选，检索是唯一路径
频次	查询量多大	全塞的成本是乘法——每次查询都付全量 token，乘上次数就是真金白银
词汇重合度	用户说不说行话	说行话关键词够；不说行话才需要语义检索
语料规范度	文件名和内容规不规范	法条、判例、规章制度这类规范语料，命中即读全文，语义检索无增益

口诀：塞得下加低频，全塞；塞得下加高频，检索省钱省延迟；塞不下，没得选；要精度，检索是降噪器。

把后两根轴交叉，能得到一个反直觉的结论——语义检索的真实主战场是非规范语料乘口语化提问（工单、聊天记录、会议纪要），而不是规范文档。给一万条法条建向量库，不如一个文件名匹配加全文阅读。

顺带拆掉两个常见误解：

误解一，“做个路由判断，简单问题走关键词、复杂问题走向量”。不需要，也做不好——用户下一句话会怎么措辞，事前不可知。工业界的答案是并联：两路检索同时发出，用 RRF（倒数排名融合）把两份榜单合成一份。不赌用户的嘴，让两路投票。这也不是两套系统，关键词索引可以内存直跑，向量库是同一批文档的另一个视图，同源同更新。

误解二，“检索策略要动态选”。其实产品形态在立项时就把策略定死了——用户要原文（工程师查报错），做成搜索产品，返回列表加高亮，不用接大模型；用户要人话（新人问制度），做成问答产品，检索是内部管道，用户只看到答案加引用角标。运行时零判断。

“我都 1M 上下文了，全部塞进去不行吗？”#

小语料、低频场景——行，而且这就是最优解，主流 AI 编码工具就是这么干的（不用向量库，代理自己搜索加读文件）。但账要算完四笔：

成本是乘法。十万 token 语料，全塞与检索只差九万五，单次看着免费；乘上一千次查询就是每天一个亿 token 级的重复读入。且超长输入通常分档加价，缓存会在文档一改时全部失效。
延迟买不掉。十万 token 的读入阶段首字延迟是秒级，五千是亚秒级。这是吞吐问题，加钱只能缓解不能消除。
精度随长度衰减。大海捞针测试（一根针藏进百万 token 找出来）强模型近乎满分，但真实任务是多针加干扰项加交叉引用——塞十万 token 其中九成与本题无关，注意力被稀释，实测答案质量反而低于只塞五千精准内容。
规模上限。十万篇文档是数亿 token，百万窗口塞不进百分之一，“全塞”根本不在选项里。

还有个反转认知的事实。很多人说”我用关键词把相关内容全找出来，一起塞进上下文”——这句话里的”找出来”本身就是检索。关键词匹配、按相关度排序返回前若干条，这就是检索器的召回端，只是没叫 RAG 的名字。所以真实的格局不是”RAG 对抗全塞”，而是分层共存。

检索没死，但换了角色#

强模型时代，检索的三个新定位：

供料阀门。再强的模型也读不见窗口里不存在的内容。检索的角色从”补模型知识短板”变成”省钱的供料阀门”——用百分之一的 token，买到九成的效果。
降噪器。这是长上下文给不了的能力——把无关内容挡在窗口外面。前排噪音挤占 token 预算，正确文档排太后还会被截断、被”中间遗忘”，所以精排才有价值：给上下文窗口里那几个宝贵座位挑对的乘客。
幻觉的缰绳。反直觉但重要——模型越强，幻觉越自信。召回不足时，强模型更敢用内部知识补漏。供料质量与模型能力是乘法关系，不是替代关系。

同时有一份贬值清单。查询改写、多轮语义扩充这类”帮模型理解差句”的优化正在贬值——现代大模型在输入时自己就会理解、联想、改写，它本身就是查询理解器，在它前面再包一层人工查询工程是浪费时间。升值的是召回准确性、精排、去重。

口诀：优化”喂什么”的永远有效，优化”帮模型理解差句”的正在贬值。

真要上，默认配方能到九十分#

基本向量库加 embedding 切块加一个精排模型，就是 90% 可用的系统，接入大模型答题能到七八十分。剩下那二十分，没有规模和评测集就不要追。

顺带把精排说透，因为它是被误解最深的一环。召回阶段用的是双塔结构——查询和文档各自独立编码成一个向量再比对距离，两者从未”见过面”，快，可以离线预计算，毫秒级扫全库。精排是另一种模型——把查询和文档拼接成一个序列一起读，词级交互，逐对打分，准但慢，只能伺候前二十到五十个候选。一个是海选简历，一个是面试当面聊。另外注意，把向量从 768 维换成 2048 维不是精排——那是换更强的召回模型，两件事正交。

那二十分怎么追？靠评测闭环，不是靠感觉。核心是先有一小份金标准评测集——二十条起步，每条是”问题加应命中的文档加标准答案”。来源三选：让大模型从文档反向生成问题（半天出几百条，但问法一股文档腔，只能冷启动用）；从真实查询日志里抽题人工标注（二十条约一小时，质量最高）；上线后收集用户点”答案不对”的反馈滚动入库（每周一两个小时，评测集随产品长大）。有了它，每次改配置都有分数可看，错误可归因——该召回的没召回改切块和混合检索，召回了排太后上精排，召回全对答案胡编改接地指令和引用标注，答案跑题改提示词或换模型。

归因口诀：用户骂”答非所问、胡编”，先查检索；用户骂”讲得绕、听不懂”，再换模型。检索决定有没有答案，模型决定答案讲得好不好。

写在最后#

回到开头的两派。“RAG 已死”派只看到了窗口变宽，没看到注意力会稀释、延迟要付钱；“无脑上 RAG”派只看到了简历潮流，没问过用户说不说行话。两者共享同一个错误——把工程选项当信仰。

下次有人问”要不要上 RAG”，先反问四个问题：语料多大、查得多不多、用户说不说行话、文档规不规范。四个答案出来，要不要上、上到哪一层、优化停在哪一分，自己就出来了。

ASR 模型选型实战：从一段全是噪音的录音说起

Fri, 14 Aug 2026 00:00:00 GMT

事情的起点#

一批 8kHz 的无线通话录音要做转写。这个选型前后做了两轮：第一轮把市面上叫得上号的开源模型扫了一遍（七个本地模型 + 四家云端 API），第二轮圈定四款做批量集中验证。

第一天就撞上了第一个坑，而且是我自己挖的。

第一坑：PCM 根本不是一种格式#

拿到的是一批无扩展名的裸音频文件，按”8kHz × 8bit = 64kbps”的直觉，我用无符号 8bit 线性 PCM 去解：

Terminal window

1
ffmpeg -f u8 -ar 8000 -ac 1 -i input.pcm output.wav

解出来一听——噪音巨大，人声若有若无。我的第一反应是”源文件音质就这么差”。

直到有人拿配套的专用转换工具转了一版，同样源文件，听感明显干净。一个 14MB 的小工具能做到 ffmpeg 做不到的事？我不信。

strings 扫了一遍那个工具的核心 DLL，导出函数列表里躺着一行答案：

1
G729ToALaw
2
PcmtoWaveNew

G729 转 A-law——这批录音是电信系统的 A-law 对数编码，根本不是线性 PCM。

对数编码和线性编码的区别可以抽象成一个通用模式：同一个字节值 b，在线性语义下表示”幅度就是 b”，在对数语义下表示”幅度是 exp(b) 的映射”。两套语义对小信号的处理完全不同——对数编码正是为了在 8bit 里塞下电话级动态范围设计的。你拿线性去解对数，等于拿对数表当加法表用，信噪比全乱，出来的”噪音”其实是被错误还原的语音。

换正确的解码方式：

Terminal window

1
ffmpeg -f alaw -ar 8000 -ac 1 -i input.pcm -c:a pcm_s16le output.wav

听感和专用工具完全一致。顺带搞清了大小差异：它输出 8bit 我输出 16bit，同一段音频正好差一倍，内容零差别。

教训：遇到陌生的裸数据，先逆向它的配套工具，别凭参数直觉猜格式。 A-law（中国/欧洲电信）还是 μ-law（美日），这一步猜错，后面所有评测全部作废——我第一轮全量推理就是这么报废的。

第二坑：升采样不会提升质量#

纠错过程中我还犯过另一个方向的错误：把 8kHz 升到 16kHz 再喂模型，理由是”主流模型都要 16kHz”。

错。奈奎斯特定理决定了 8kHz 录音里最高只有 4kHz 的频率信息，升采样不会凭空造出新信息，插值算法反而会把 8bit 的量化误差扩散到更多采样点上，信噪比更低。正确姿势是保持原生采样率，让模型内部的重采样逻辑自己处理——各家模型都带这一层。

当然有例外：个别开源模型（比如 FireRedASR2）要求外部喂 16kHz，那就单独转一份给它，但这是”喂给特定模型的适配层”，不是”提升音质”。

没有标注数据，怎么做评测？#

这批录音没有人工转写的标准答案，算不了字错率（CER）。实际用的是两条腿走路：

交叉对比：多个模型转同一段音频，互为参照。所有模型都识别出的内容，大概率是对的；只有一个模型独有的内容，人工抽听裁决。

维度量化：把”识别质量”拆成可数的指标——

行业术语命中数（维护一张领域术语表，统计每家的命中次数）
地名/呼号识别（词表 + 正则）
文本输出量（平均/中位字数，过短=漏内容，过长=可能有幻觉）
成功率（失败、空输出单独计数）
速度（平均耗时、RTF=处理时间/音频时长）

测速还有个铁律：必须标注并发数和 batch size。 云端 API 开 5 个并发和串行，吞吐天差地别；本地模型 batch=1 和 batch=8 也不是一回事。我第一版报告只写了”平均 X 秒”，被自己人一句”你到底并发了几个”问穿——没有并发标注的速度数据，等于没测。

第一轮：基准排名会骗人#

第一轮扫描覆盖了七个本地开源模型：FireRedASR2-LLM、FireRedASR2-AED、Qwen3-ASR-1.7B、FunASR-Nano、SenseVoice-L、Paraformer-Large、Whisper-Large-v3，外加豆包/讯飞/腾讯云/阿里云四家云端。先看各论文在标准 16kHz 测试集上的普通话 CER：

模型	基准CER%
FireRedASR2-LLM	2.89
FireRedASR2-AED	3.05
豆包ASR	3.69
Qwen3-ASR-1.7B	3.76
FunASR-Nano	4.16
SenseVoice-L	4.47
Paraformer-Large	4.56
Whisper-Large-v3	9.86

拿同一段真实的 8kHz 低质量通话音频喂进去，排名反转了：基准第四的 Qwen3-ASR 实测最优——专业词汇最准、转写最完整通顺；基准第一的 FireRedASR2 鲁棒性反而略逊，出现了把”夜航资质”听成”银行资质”这类领域词错误。

这一轮最大的教训就一句话：基准测试集是 16kHz 干净音频，你的业务音频是另一回事，选型必须拿真实数据实测。

初筛还抓到几种有意思的失效模式，值得记录：

重复循环：Qwen3-ASR 和 Whisper Turbo 在噪声段陷入复读，同一个词组输出几百次（Whisper 还顺手切成了繁体中文）
整体乱码：Paraformer 在这批音频上输出完全不可读
同门几乎一致：FireRedASR2 标准版和 Lite 版输出几乎逐字相同，买大不买小没有意义

另外做了个底座核查，结论对选型很有参考价值：榜单上的高分”新”模型，大量是开源底座的衍生品。核查方法很简单——抓 HuggingFace 模型仓库的 raw README（详情页是 SPA，curl HTML 拿不到内容）。核查结果：MOSS-Transcribe 是 Qwen3-1.7B 底座 + Qwen3-Omni 音频编码器；Higgs Audio v3 是 Whisper-Large-v3 编码器 + Qwen3 解码器；某排行榜第 10 名的模型点开详情一看，“基于千问 1.7B 微调”。所以追赶榜单之前，先看看它爹是谁。

第二轮：四款集中验证#

第二轮圈定四款：Qwen3-ASR 与 FireRedASR2 本地部署、讯飞与豆包云端 API，用批量的真实数据（100 个常规文件 + 两批各 10 个长音频）集中验证。维度量化结果：

维度	Qwen3-ASR	FireRedASR2	讯飞	豆包 Seed
部署	本地 GPU	本地 GPU	云端 API	云端 API
成功率	99%	81%~70%	99%	86%（限流所致）
行业术语	多	少	最多	多
处理速度（RTF，越小越快）	0.20	0.12	0.70	0.40
词级时间戳	需额外对齐模型	原生支持	—	—
数字输出	汉字（需后处理）	汉字	汉字+阿拉伯混合	自带阿拉伯数字

几个值得展开的点：

FireRedASR2 被稳定性淘汰。 它推理最快、原生带词级时间戳和置信度评分，设计上很优雅。但常规批 19% 的文件输出空文本，换一批长音频又随机挂掉三个——置信度掉到 0.07，其他三家都识别得完整。测试结束后我把它从服务器上删了，理由就一个：ASR 是个流水线零件，零件可以慢，不能随机坏。

豆包的限流很严。 并发 3 就开始批量 429，1140 个文件的单线程补跑花了好几个小时。它的 API 是两步式（提交任务+轮询结果），认证信息全放 HTTP Header，网上能搜到的旧版端点基本都 404 或 403，照着官方文档的 v3 路径走才通。

讯飞的语种参数是 cn 不是 zh。 这个坑值得单独写一行：报”转写语种未授权”先检查语种代码，中国区普通话的代码是 cn。另外它的签名放在请求头而不是 URL 参数，音频要发原始二进制——base64 会触发文件大小校验不一致。

LLM 系 ASR 的数字问题#

Qwen3-ASR 识别准确率很高，但所有数字都输出汉字：“三四三四”而不是”3434”。这对通话类场景是硬伤——呼号、编号、高度值都需要阿拉伯数字。

第一反应是加提示词：“所有数字用阿拉伯数字表示”。实测两种提示词的输出逐字节相同。原因在于 LLM 系 ASR 是音频驱动的转写器，说话人怎么读它就怎么写，文字提示控制不了输出格式。云端 API 没这个问题是因为服务端内置了 ITN（逆文本规范化）。

解法是本地后处理，配方三件套：

cn2an 的 smart 模式处理量词式读法（“三百”→300，“十二点”→12点）
逐位映射表处理逐字读法（幺=1、两=2、拐=7、洞=0——行业读法里 0 读”洞”）
贪心分段处理混合读法：“六百三零幺六”整体解析会失败，拆成 cn2an 能吃的最长前缀（六百三→630）加逐位尾巴（零幺六→016），拼出 630016

还有两个防御性细节：末尾的”点”是钟点语义（“十二点”→“12点”），要防着被当小数点吞掉；“一起”、“统一”这类含数字字的常用词不能误伤。

显存与内存：实测数字#

部署前总得回答”多大的卡能跑”。用 120 秒的长音频把流程压满实测（bf16 精度）：

场景	显存峰值	内存峰值
纯转写	4.68 GB	4.76 GB
转写+词级时间戳	6.40 GB	4.99 GB

结论：满血（转写+时间戳）8G 显存起步，内存 8G 稳妥；纯转写 6G 显存够用；4G 显存或 4G 内存的机器跑不动——权重本身 bf16 就 3.4GB，加上 CUDA 上下文和激活值必然爆。

顺带修了一个自己的惯性错误：一开始用 fp32 跑（显存直接翻倍），其实 bf16 加一行输入特征类型转换就完全正常，输出质量一致、速度更快。

最后的选型答案#

两轮跑完，答案收敛得很干净：

数据不能出域 / 无网络环境：Qwen3-ASR 本地部署，配上数字后处理和时间戳对齐模型，功能闭环
要省事、要准确率：讯飞云端，术语识别最多、稳定 99%
要阿拉伯数字原生输出：豆包，但要接受单线程限流
没有 GPU、纯 CPU 跑：SenseVoice-Small 或 Paraformer（第一轮结论，轻量场景够用）
不想部署也不想挑模型：直接走大厂托管 API
FireRedASR2：速度快，但随机空输出这个性质决定了它不适合做生产流水线零件

这次评测最大的收获反而不是选型结论，而是三条方法论：遇到陌生数据格式先逆向配套工具；基准排名会骗人，选型必须拿真实业务音频实测（基准第一的模型在我们的数据上被反超，最后还因稳定性出局）；以及没有标注数据时，多维交叉对比照样能收敛出可信结论。至于那个让我第一轮全量报废的 A-law——下次再见到 8kHz 的”PCM”，我会先 strings 一眼再动手。

关联#

检阅报告（内网）：四模型横向对比页，含音频播放与分段可点时间轴

从 OpenClash 到 dae：一个刷机老手的两天折腾记

Sun, 09 Aug 2026 00:00:00 GMT

2026 年 8 月，星期天。女朋友不在家，一个人，有大把时间。于是我想起一件盘算了很久的事：把路由器的代理方案，从 OpenClash 换到 dae。

事情是怎么开始的#

这件事的起因，一半是技术判断，一半是”手痒”。

先说判断。我从 2017 年开始折腾路由器，那会儿还念高中，在闲鱼淘了台斐讯 K2。一开始用的甚至不是 OpenWrt——是 hanwckf 的 Padavan，华硕固件底子改的，又稳又省心。后来刷了潘多拉（PandoraBox），才算真正弄懂 OpenWrt 那套东西：内核、feeds、opkg，还有 Breed——刷不死鸟引导器，只要 Breed 还在，刷机刷得再烂都死不了。

快十年，手里的机器从 K2 换到 K2 Pro，再到现在的 360T7。软路由只在 N1 盒子上短暂玩过，主力一直是硬路由。插件则换了一茬又一茬：SSR、Passwall、OpenClash。

这套组合用着一直还行，但有两个问题慢慢积攒起来。一是架构越来越重——OpenClash 当代理，AdGuard Home 当广告过滤，两层各管一摊，总觉得哪里别扭。二是性能一直没打满——千兆宽带，日常上网只能跑到 700M。

所以当我在网上看到 dae 这个方案时，第一反应不是”要不要换”，而是”这值得认真评估一下”。它宣称的东西——eBPF、内核层分流、真直连——恰好命中了我那两个痛点。

为什么要翻墙#

先把这事儿说透。为什么要翻墙？

不是为了什么不可告人的东西。是信息、学术、工具、内容——一个搞技术的，GitHub 打不开、Google 搜不了、一堆开发文档在墙外，这日子没法过。我高中那会儿想看的教程、想下的软件、想进的学习网站，一堆在墙外。这不只是我的需求，是一代人的需求。

从 2003 年金盾工程立项起，这堵墙和绕墙的人就一直在玩猫鼠游戏：

早期是免费代理、Tor——反复被墙；
后来是 PPTP/L2TP/OpenVPN——2012 到 2015 年被 DPI（深度包检测）识别封杀；
2012 年，Shadowsocks 出现。它把流量加密成随机字节流，看起来就是普通流量，优雅地躲过特征检测，一夜爆红；
2015 年大清洗，ss 的握手特征被识别，于是 SSR（ShadowsocksR）加上了混淆协议，猫鼠游戏升级；
2015 年 V2Ray/VMess 带着时间校验、动态端口杀进来；
2018 年 Trojan 更进一步——直接伪装成一个正常的 HTTPS 网站，你连过去它给你看网页，你带上钥匙它就是隧道，正面刚”443 非 TLS 就封”的策略；
2018 年 Clash 带着 YAML 规则和订阅管理来了，机场生态爆发，使用门槛骤降；
2022 年 REALITY 借真实网站的 TLS 指纹，几乎无法检测；
再到 2023 年的 sing-box、dae……

但所有这些，到了路由器这一层，都只是”内核”。你看到的插件——SSR Plus、Passwall、OpenClash——都是壳。壳决定体验，内核决定能力。换插件不叫升级，换内核才是。

换壳记：从 SSR 到 OpenClash#

我第一次用 SSR 的时候，还在高中。那时候的插件就是 luci-app-ssr-plus 那一类，简单、够用。后来为什么一路换？

两个原因。

第一个：节点支持的协议不一样。SSR 毕竟年代久远，它的安全性和抗检测能力都偏低了。机场的节点协议在升级，老插件接不住新协议，你不换插件，节点都没法用。

第二个，也是更本质的：不同插件的规则可定义范围不一样。核心功能——翻墙上网——大家都能做，区别在于你能对流量做多精细的控制。SSR Plus 的规则就那么几板斧，Passwall 灵活一些、能挂多个核心（v2ray/xray），而 OpenClash 的自定义程度最高：YAML 规则、规则集、节点策略组、订阅管理，几乎什么都能配。

所以我的路线图是：SSR → Passwall → OpenClash。一路往上，本质是在换”壳”，换更自由的控制面板。

700M 的税：OpenClash 的代价#

OpenClash 好用，但那个”别扭”感，我后来想明白了。

我原来的架构是分层：OpenClash 当代理层，AdGuard Home 当广告过滤层。但两层太复杂，后来我把广告过滤直接塞进了 OpenClash 的代理规则里——图一个少一层。

代价很快就显现。千兆宽带，日常上网只能跑到 700M。而且 MT7981 这颗 CPU 开始发热：待机 60 度，WiFi 模块 55 度；满速跑代理，CPU 能冲到 70 度，负载飙到 2 甚至接近 3。

问题出在哪？

OpenClash 是 Clash/Mihomo 内核的用户态方案。TUN 模式下，流量路径是这样的：

1
设备 → 网卡驱动 → 内核协议栈 → TUN 虚拟网卡 → Clash 进程（用户态）
2
     → 分流判定 + 代理/直连处理 → 内核协议栈 → 网线出去

注意最后那步：即使是”直连”的国内流量，也要从内核态切到用户态（Clash 进程），处理完再切回内核态发出去。每个包两次上下文切换。我把广告过滤塞进规则后，国内流量也得过 Clash 这一层——那 300M 的差距，就是用户态处理的税。

这不是 Clash 的错，是用户态方案的宿命：你的分流逻辑跑在用户态，流量就得进用户态。

遇见 dae：eBPF 和”真直连”#

dae 是 daeuniverse 的作品。它的作者 mzz2017 之前做了 v2rayA——v2ray-core 的 Web 界面，用 iptables 分流。做久了，他看到了一个天花板：任何用户态代理，连”直连”流量都要经过用户态处理一遍。这是架构性的浪费，不是调优能救的。

他的解法是换个赛道：用 eBPF 把分流程序写进 Linux 内核的 tc（traffic control）挂载点，在流量进入 TCP/IP 协议栈之前就完成分流。eBPF 程序跑在内核态，没有上下文切换。

直连流量是这样走的：

1
设备 → 网卡驱动 → tc 挂载点（eBPF 分流判定）
2
  ├─ 直连 → 内核 L3 路由直接转发 → 网线出去    ← 零用户态开销
3
  └─ 代理 → 重定向到 dae 的 tproxy 端口 → dae 用户态加密 → 网线出去

关键在”Real Direct”（真直连）：直连流量在内核层就拐弯了，Linux 变成一台纯交换机/路由器。mzz2017 自己在文档里写：“以 benchmark 来看，dae 的直连性能和其他代理程序相比就像个怪物。“隔着屏幕都能看见那点得意。

除了分流，还有两个设计细节值得玩味：

进程匹配：Clash 要扫 /proc 文件系统才能知道一个连接属于哪个进程，可能要几十毫秒；dae 用 eBPF 在 cgroupv2 挂载点监听系统调用，直接读进程控制块，快一个量级。
域名匹配：dae 劫持 DNS 请求，建立”域名 → IP”的映射表。所以它的 DNS 处理必须自己来——这也是为什么配置里 dnsmasq 的流量要 must_direct（强制直连），否则 DNS 不过 dae，域名分流就失效。

但架构没有白来的好处。eBPF 的性能来自内核，代价也是内核：要内核 5.17+，要 BTF 调试信息，要 veth 虚拟网卡，要一堆 CONFIG 选项。桌面 Linux 默认开着，嵌入式固件（OpenWRT/Armbian）默认关掉。

换句话说：dae 把性能做进了内核，把税留给了固件。而我的 360T7 恰好装着 Yuzhii 的 fixed-parts U-Boot——这是整个迁移里唯一真正需要认真对待的约束。

迁移：两天，15 个坑，一次关键判断#

先说清楚我的方法论：这件事我没打算”试试看”，而是先列约束，再逐条验证。迁移的第一条约束就很硬——Yuzhii 的 U-Boot 只认 FIT 格式。

约束之一：分区表是硬门槛#

Yuzhii 的 U-Boot 从闪存固定偏移读原始 FIT 镜像（魔数 d00dfeed），不解析 UBI 卷：

格式	特征	能不能启动
FIT (.itb)	魔数在偏移 0	✅
sysupgrade (.bin)	魔数在偏移 0x800	❌
UBI factory (.bin)	魔数 UBI#	❌

官方 ImmortalWrt 固件全按 UBI 分区布局组织，分区表和 Yuzhii 的 U-Boot 对不上——跟手机刷机一个道理，分区表不兼容，镜像再新也刷不进去。

这条约束我在动手前就确认过，所以固件选择从一开始就没走偏。但强刷不兼容固件这件事，我确实验证过一次——不是为了试错，是为了确证”哪些固件真的不能用”。结果卡红灯，SSH 全断。对很多人这是噩梦，对我来说只是流程里的一步：进 U-Boot TFTP 模式，推 initramfs-recovery.itb 进去，十分钟救回来。

这里要纠正一个说法：这不叫变砖。

什么叫真正的砖？我从安卓 2.3.2 刷到 4.0.4、再刷到 4.4.4 那一代人，见过真正的砖：连引导器都进不去，没有任何恢复模式。手机没有 fastboot 就是黑砖，只能靠高通 9008 厂商模式串口救；路由器连 Breed/U-Boot 都进不去，就得拆壳上 TTL 串口线，看 bootlog，手搓救砖。

卡开机？U-Boot 还在、TFTP 还能进？那只是小场面，跟换轮胎差不多。

约束之二：kmod-veth 必须编译期解决#

dae 启动时要创建 veth 虚拟网卡对，内核缺 CONFIG_VETH 直接报 fatal。这条约束有个隐蔽的点：kaslana（我此前维护的自编译固件）用的 SNAPSHOT 内核，vermagic 和官方仓库的 kmod 包对不上，apk add kmod-veth 直接”No such package”。

根本原因：内核和 kmod 包不是一起编译的，ABI 签名不一致。所以这条只能靠”编译时把 kmod-veth 编进固件”解决，事后装不了——这也是我后来去跑自编译的动机之一：既然要动内核，干脆验证一遍构建链路。

约束之三：BTF 与 eBPF 工具链#

自编译那两天，GitHub Actions 跑了 11 次、12 小时，坑确实多，但复盘下来最值得写的有两个，都指向构建系统本身的隐蔽性：

一个是通配符陷阱。我用 for f in target/linux/generic/config-* 循环改内核配置，结果 config-* 把 config-filter 也匹配进去了，排序后版本号解析成 “filter”，BTF 选项全写进了错误的文件。编译了两遍都”成功”，但 BTF 没生成，daed 照样崩。这类 bug 不写进文章没人信，但它就是真实存在的。

另一个是静默剔除。@HAS_BPF_TOOLCHAIN 是 Kconfig 条件，不满足时 make defconfig 会静默移除 daed 包，一个警告都没有。得开 CONFIG_DEVEL=y + CONFIG_BPF_TOOLCHAIN_HOST=y 才看得到。

关键判断：为什么自编译本身是个伪需求#

两天泥潭的尽头，不是”终于编译成功了”，而是一个更值钱的发现——自编译这个前提，本身站不住。

我在 6.12 内核上跑 daed，崩在：

1
program of this type cannot use helper bpf_get_current_task#35

根因是内核 6.12 的 sockops 程序不支持 bpf_get_current_task helper。我当时的第一反应是”那我编译一个带正确配置的内核”。这是惯性思维。

停下来问了一句：官方 SNAPSHOT 用什么内核？ 答案是 master = 6.18。再验证一句：6.18 支持这个 helper 吗？支持。那结论就清楚了——官方固件已经满足 dae 的全部运行条件，缺的只是 BTF 数据和几个 kmod 包。而 vmlinux-btf 走 CO-RE 机制跨版本兼容，6.12 的 BTF 数据在 6.18 上也能用。

于是最终的迁移路径短得反常识：刷官方 SNAPSHOT → 加 cooluc 第三方源 → apk add vmlinux-btf daed luci-app-daed → 5 分钟装完。

重新审视最初的判断：我为什么想自编译？因为想要完全可控的内核配置。但当官方固件已经满足全部硬性约束时，这个前提就塌了。结论不是”我白编了两天”，而是”我用了最硬核的方式，验证了一条其实更短的路径”。这种验证本身是有价值的——它排除了”官方固件不行，必须自编译”这个假设。

现在是真舒服#

迁移完成，一切正常。逐项对照最初的痛点：

国内直连：恢复千兆满速。eBPF 的内核分流，国内流量不进用户态，那 300M 的税没了。
代理流量：说实话，国外网速没有提升，还是 150M 左右。原因很实在：代理速度的瓶颈在加密和线路，不在分流机制——不管 eBPF 还是 TUN，代理流量最终都要进用户态做加密，CPU 算力到头了就是那么多。这点得说清楚，不吹。
广告过滤：拆出来单独跑了 AdBlock Fast（adblock 的轻量版），不再塞进代理规则。分层又回来了，但这次没有性能税，因为广告过滤在代理之外。
温度：待机 60 度，满速代理 70 度，比 OpenClash 时代舒服。

开发者视角：mzz2017 的取舍#

写到最后，想说点站在开发者角度的话。

mzz2017 先是做了 v2rayA，然后抛弃了它。不是不好，是看到了天花板。他审视市面上的方案：

Clash：用户态做一切，直连流量也交税；
Fake IP：有 DNS 缓存污染的老问题；
iptables/nftables：挂在 netfilter 上，位置太靠后，分流已经晚了；
域名嗅探：只能嗅 TLS/HTTP。

他的想法很直接：为什么不能在最早的路径上就把流量分了？eBPF 给了他答案。代价是内核要求高，用户侧适配成本大——也就是我这两天验证的全部内容。

dae 适合谁？适合软路由玩家、愿意折腾内核配置的人、在乎直连性能和资源占用的人。它不适合纯小白——底层约束太多，一个 kmod-veth 就能劝退一片。

但换个角度想：dae 把性能做进内核，是把”性能税”从运行时转移到了部署时。 运行的时候快得飞起，部署的时候要过五关斩六将。这个交易划不划算，看你是哪种用户。

附录：给想迁移的人#

固件：官方 SNAPSHOT（内核 6.18）即可，或 Wei.G 上 T7 非 UBI 编译的固件
kmod-veth：必须编译期包含，事后装不上（vermagic 不匹配）
BTF：确认 CONFIG_DEBUG_INFO_BTF=y，否则 daed 无法运行；缺的话装 vmlinux-btf
分区变体：Yuzhii U-Boot 只认非 UBI，永远选非 UBI 固件
恢复：卡开机就 U-Boot TFTP 推 initramfs-recovery.itb，十分钟的事
包管理：25.12 用 apk，不是 opkg
配置：全在 /etc/daed/wing.db，SQLite 可以直接操作
订阅转换：Clash YAML 需转 URI，用 luci-app-daede 或 Python 脚本
接口：必须设 br-lan，不是 wan
广告过滤：daed 不带，用 AdBlock Fast 之类单独跑

各行各业都在做仪表盘,但它们根本不是一种东西

Thu, 06 Aug 2026 00:00:00 GMT

最近因为做一个研发效能看板,我顺着这条线研究了一圈别的行业的仪表盘——电商的、医院的、数据中心的、智慧城市的、公安的。

越看越觉得一件事:大家都在做”仪表盘”,但做出来的根本不是一种东西。

表面看都是图表、卡片、排行榜,技术栈也差不多。但只要往里走一步就会发现,它们的核心使命完全不同,踩的坑完全不同,甚至连”什么算成功”都不一样。

很多人做看板翻车,不是技术不行,是一开始就把一种仪表盘当成了另一种来做。

这篇文章,我把见过的几类仪表盘摊开,讲清楚它们各自的侧重点、难在哪、要注意什么。

先找到一个底层视角#

要看懂不同行业的仪表盘,最快的方法不是看行业,而是看一个更底层的东西——这张看板做出来,是为了让人干什么?

我把它叫”核心动作”。核心动作不一样,整张看板的骨头就不一样。我见过的大概有五种。

一、监控告警型：出事了,得立刻让人知道#

代表是数据中心机房监控、服务器监控、价格异动监控。

看板上长什么样：一堆实时数字、几条折线、某个值红了就弹报警。

侧重点就三个字：快、准、不漏。

做这种看板要注意:

数据得是秒级新鲜的,昨天的数据放上来没人看。
告警要有阈值,但不能太敏感。天天报警,几天后人就麻了,真出事反而看不到——这叫”告警疲劳”,是这类系统最常见的死法。
不能漏报。机房温度爆了你没报出来,是要出事、要赔钱的。这条比”画得好看”重要一万倍。
图表反而不用花,关键是数据链路够不够快、够不够稳。

这类看板,价值全在”出事那一秒能抓住”,平时没人看它,反而是它最成功的时候。

二、度量考核型：事后算账,分蛋糕#

代表是研发绩效、销售排行、各种 KPI 仪表盘。

看板上长什么样：完成率、排名、达标/未达标。

侧重点：口径权威、处处对得上账。

注意:

每一个数字背后都有一套”怎么算”的规则,行话叫”口径”。这套规则是开会吵出来的,不是技术定的。你说技术定不了,对不起,业务方也定不清楚,得一群人坐一起磨。
口径一定会变。 业务在跑,人在用,用着用着发现原来的定义不公平、不全、不对,就得改。
同一个数字出现在看板的好几个位置,必须保证处处一致。顶部大数和下面分组列表对不上,老板第一个找你。
这类看板,难的根本不是画图,是让每一个数字”可信”。

这块是我亲历的。我那张研发看板,图表三天画完了,口径改了半年。改到后面我都怀疑人生,但确实每一版改完,数字才真的”对得上账”。

三、调度协调型：当下怎么动,资源怎么分#

代表是医院床位、仓储、运力调度。

看板上长什么样：每个科室还剩几张床、哪些车在跑、谁闲着。

侧重点：资源状态实时准确,能支持当下决策。

注意:

资源是有限的,有人占了别人就不能占。两个人同时抢一张床,系统不能把一张床分给两个人。
状态要绝对一致。看板上显示有空床,护士跑过去发现没有,这种事多发生几次,这套看板就没人信了。
往往还带预测：明天大概会有多少床空出来,后天呢?
这类看板,背后是一个状态机。图表只是状态机的一张脸。

它的核心是”现在”,不是”过去”(那是考核型),也不是”未来”(那是预测)。每一秒的数字都得是真的。

四、分析洞察型：找规律,做决策#

代表是电商品类分析、市场趋势、用户分群。

看板上长什么样：多维交叉表、能钻取、能对比。

侧重点：能自由探索,查询够快,数据够干净。

注意:

用户会疯狂钻取。从这个品类点到那个地区,再点到那个时间段,一层层往下问。查询性能扛不住,体验直接崩。
维度一多,口径更多。钻着钻着发现两个数对不上,是常态。
这类看板,本质不是给人”看”的,是给人”玩”的。它是个自助分析工具,用户想问什么就能问什么。

做这种看板,最大的错觉是以为把图画出来就完了。不是,你交付的是”用户能问到多深”,画图只是最外面那层。

五、流程驱动型：推着业务一步步往前走#

代表是电商订单全流程(咨询→下单→付款→发货→物流→签收)、工单系统。

看板上长什么样：每个订单现在卡在哪一步、有多少积压、哪个环节是瓶颈。

侧重点：全生命周期状态机,一步都不能丢。

注意:

状态流转是核心。从”待付款”到”已签收”,中间每一步都不能跳、不能丢、不能回不去。
异常补偿特别难。付了款没发货怎么办?发了货要退款怎么办?每一个异常分支都得有交代。
幂等性：同一个动作来两次,不能造出两个订单。涉钱的事,这点是天条。
这类看板,看的是流程的脉搏。图表展示的是分布和瓶颈,帮人看出”哪一步堵了”。

它跟调度型容易混。区别是：调度型管的是”资源此刻在哪”,流程型管的是”一件事走到了哪一步”。

六、指挥展示型：它根本不是给人用的#

这一类我犹豫了很久要不要单列,因为它的逻辑跟前面五种完全不一样。

代表是智慧城市大脑、应急指挥中心、领导驾驶舱。

看板上长什么样：整面墙的大屏、3D 数字孪生(一个能转的虚拟城市)、满屏滚动的数字和轨迹,科幻感拉满。

它的核心动作是什么?说实话,很多时候它的核心动作是”被看”——被领导看、被视察组看、被新闻镜头看。

这话有点刻薄,但反映了一个真实情况：这类大屏,展示价值常常大于实用价值。设计的时候,“好不好看、像不像科幻片”的优先级,可能比”数据准不准”还高。我也见过一些城市的车流量、人口热力图,数据是有美化成分的——这是行业里公开的秘密,toG 项目自带政治属性。

但你要说它纯花瓶,也不公平。它真正的技术难度在这两点:

数据打通：一个城市大脑要接交警、消防、卫健委、环保、城管几十个委办局的系统。每个系统一个厂家,一套标准,谁也不愿意把数据共享出来。把这群数据捏到一块儿,才是这个项目最吃人的地方。技术不难,难在协调。
渲染：一个能流畅转动的 3D 城市,加载整个城市的建筑模型,这背后是真功夫(不是图表库能搞定的,得用游戏引擎那套)。

造价常常是千万级。但这钱大部分花在硬件(摄像头、大屏、指挥中心装修)和集成上,软件本身占比很小。

如果你接到这类活,记住一条:别被那个转来转去的 3D 城市唬住,真正的功夫在数据治理和系统打通,不在那个壳。

七、强权限和保密型：公安这类#

公安系统(案件管理、治安态势、结案率大屏)骨子里是度量考核 + 流程驱动,前五种就覆盖了。我单拎出来,是因为它有几个独有属性,你做的时候不注意会出大事。

保密是红线。数据脱敏、传输加密、不落明文,这些不是”可选优化”,是及格线。涉案信息泄露,不是 bug,是事故。
权限分级极严。一个民警能看到的数据范围,和他警种、级别、是否主办人强绑定。你不能让一个基层民警一打开系统看到全国数据。权限模型设计错一步,就是泄密。
跨系统协查：一个案子可能要查户籍、车辆、住宿、通讯,这些系统分散在不同部门。查询链路的复杂度远超普通看板。
结案率、破案率这种口径,也会朝令夕改——政策导向一变,考核口径跟着变。这点和我做的研发绩效看板一模一样,谁也别笑谁。

做这类看板,数据安全和权限模型,优先级在所有东西之上,包括图表好不好看。

还有一根轴,解释了很多误会#

讲完这几种,还有一个维度特别重要,它能解释一件事——为什么有的看板数据量很大但不难,有的数据量很小却要命。

这根轴是：数据是硬的,还是软的。

硬数据：传感器读数、金额、数量。机房温度就是温度,订单金额就是金额,全世界只有一个值。

软数据：人填的、口径模糊的。任务完成度、满意度、工作质量。

硬数据看板(机房、电商交易),难点在规模和实时——几万个传感器每秒一个点,怎么存、怎么算、怎么秒级刷出来,这是技术硬骨头。

软数据看板(研发绩效、考核),难点在口径治理——数据可能就那么点,但”怎么算”这件事,能吵半年、改半年。

很多人会觉得”我的看板简单,因为数据量小”。但你做的如果是软数据看板,数据量再小,口径这条线上的难度,可能比一个硬数据看板还高。

我那张研发看板就是典型：数据量小到单文件数据库就够装,但口径改了半年。反过来看一个机房监控,数据量是我这的几万倍,但每个数字是死的、是客观的,反而不用扯皮。

复杂度不是一根轴,是好几根。数据量只是其中一根。

仪表盘还藏在哪些行业#

上面七种只是”主力”。仪表盘其实无处不在,每个行业都有自己的变种,我快速点几个:

金融交易：股票看盘、交易风控。把”监控告警”和”分析洞察”推到极致——毫秒级实时,错了直接赔钱,是实时和准确的天花板。
工业制造和能源：工厂车间 MES、电网调度。和机房监控一类,但更狠:看了数据,系统还要自动去调设备(加大电流、关阀门)。这不只是看,是闭环控制,出错了会炸设备、会停电。
交通：红绿灯调控、地铁客流、航班调度。调度协调 + 城市级规模,一个城市几万个路口。
物流：双十一物流大屏、快递轨迹。流程驱动的代表,一个包裹从揽收到签收的全生命周期。
互联网运营：DAU、留存、实时在线人数。分析洞察的高频版,全靠埋点喂出来的。

你看,每一种都能对回到前面那几个核心动作上,只是每个行业把它推到了不同的极致。

回到开头#

所以你明白我为什么说”它们根本不是一种东西”了。

下次做仪表盘之前,先问自己几件事:

这张看板的核心动作是什么? 是出事要报警,还是事后要考核,还是当下要调度,还是给人探索,还是推流程走,还是只是给人看?核心动作不同,整个架构的骨头就不同。
我的数据是硬的还是软的? 硬的,把力气花在规模和实时上;软的,把力气花在口径和一致性上。别使错劲。
我最怕的失败是什么? 是漏报?对不上数?状态错乱?查询超时?丢步?泄密?怕的不一样,防守的重点就不一样。
这是不是个 toG / 强展示场景? 如果是,把力气分一份给”数据打通”和”看起来像回事”;如果涉及保密,权限和安全是地基,不是装饰。

这几件事想清楚再动手,能省掉后来很多”为什么这么简单的东西,改了半年还没完”的痛苦。

各行各业的仪表盘,长得像,是因为图表那层皮长得像。皮下面,它们是好几种完全不同的生物。

一份342页PDF转Word的活，逼我把6.3GB大模型塞进了8GB笔记本

Thu, 06 Aug 2026 00:00:00 GMT

事情的起点很朴素：有人递给我一份 342 页的招标 PDF,要转成 Word。

第一步绕不开 OCR。但这份文件里全是表格、多栏、图文混排,还有跨页的章节——传统逐页切图的 OCR 一上,版面碎成渣,语境全丢。云 OCR 呢,342 页要钱,而且招标内容含商务条款,不适合往云上传。

我盯上了百度刚开源的 Unlimited-OCR。它不是飞桨 PaddleOCR 那条传统检测+识别的线,而是一个 3B MoE 的视觉语言大模型(VLM),6.3GB,官方标语很狂:“One-shot Long-horizon Parsing”——一次性长文档解析,无限上下文,整篇文档一起理解。

听起来正合适。但问题是：我这台笔记本是 RTX 5060 Laptop,只有 8GB 显存。6.3GB 的模型塞进 8GB 的卡,听起来就像把一头大象塞进冰箱。

后来的两天,就是在反复验证”到底塞不塞得进去”。这篇文章记的就是这个过程。

选型：为什么是 VLM 路线#

OCR 方案我大致分三类:

传统 OCR(PaddleOCR、Tesseract)：检测+识别管线,快、轻,但跨页语境丢光——表格被分页切断、标题和正文分家、图文混排还原差。
云端 OCR：效果好,但贵 + 招标内容不宜外传。
VLM 大模型 OCR(Unlimited-OCR、DeepSeek-OCR、MinerU)：整页当图像喂给大模型,它自己理解版面、保持上下文,对复杂版式还原最强。

Unlimited-OCR 的卖点正好打在痛点上：无限上下文、VLM 理解版面、开源可本地。零成本、完全可控,代价是得和 8GB 显存死磕。

先说清楚一件事：本次是部署 + 推理工程优化,不是微调。没改一行模型权重,纯粹是把官方模型在消费级硬件上跑稳、跑快、跑通批量。这两件事千万别混。

第一关：环境,一堆无声的坑#

下载源——别盲目走代理#

2.5GB 的 torch wheel,我一开始用阿里云镜像,下了 20 分钟才三分之一。后来换交大镜像(mirror.sjtu.edu.cn),1 分钟搞定,42MB/s。

更坑的是官方 CDN(download.pytorch.org)走 Clash 代理必报 SSL EOF——TLS 指纹问题。清华 TUNA 当时只有不到 5KB/s。

教训：大文件下载先 curl 测 6 秒速,再选源。国内直连镜像常比走代理快得多。

源	速度	备注
官方 CDN 走 Clash	SSL EOF	TLS 指纹问题
mirrors.aliyun.com	1.5 MB/s	慢
mirror.sjtu.edu.cn	42 MB/s	torch wheel 首选
hf-mirror.com	61 MB/s	HuggingFace 模型首选

Blackwell 显卡必须用 cu128#

RTX 5060 是 50 系,compute capability 是 sm_120(Blackwell)。我装了 torch cu126,torch.cuda.is_available() 返回 True,以为成了。结果一跑推理,报 “not compatible”。

这是最阴的一类坑——它不直接报错,而是装的时候正常、用的时候无声失败。cu126 构建只支持到 sm_90,50 系是 sm_120,对不上。cu129 又没有 Windows 构建,只有 cu128 有。

教训：装 torch 前先 torch.cuda.get_device_capability() 确认 GPU 算力,选对应 CUDA 版本。50 系必上 cu128。

Windows 上的段错误#

模型用了 trust_remote_code,我照惯例加了 low_cpu_mem_usage=True 想省内存。结果 from_pretrained 时直接 Segmentation fault(段错误)崩溃。

诡异的是纯 import 没事,一到加载就崩。排查走了弯路。最后发现:去掉这个参数就正常了。

trust_remote_code 模型在 Windows 上慎用 low_cpu_mem_usage,有段错误风险。这是个没法预报、只能靠踩的坑。

第二关:“无限上下文”的真相#

这是最核心的一个坑,也是我觉得最值得写的一坑。

Unlimited-OCR 不是号称”无限上下文、一次性长文档解析”吗?那我第一反应是：342 页一股脑塞给它,model.infer_multi() 一次搞定,多爽。

结果全废。342 页长文档,token 截断、OOM,什么都跑不出来。

翻官方架构才发现:它自己也是 PyMuPDF 拆页 → 逐页单独 infer() → 流式聚合。

这里有个反讽,必须说清楚:

官方标语”无限上下文 One-shot 长文档解析”是模型能力层面的——单页内能理解任意长内容、不截断。但工程上跑 342 页 PDF,仍然必须逐页拆分喂,否则显存和 token 都顶不住。

“模型能力” ≠ “工程实现”。 标语说的是模型单次推理内不截断,不代表你能把整本 PDF 一次塞进推理函数。分不清这个,架构就会判错。

正确做法:infer_multi() 是给”几张图一起识别”用的,不是给”几百页文档一起理解”用的。大 PDF 必须逐页推理,靠前端聚合结果。这是架构红线。

第三关：8GB 显存,怎么塞 6.3GB 模型#

这是整件事最反直觉的部分。

起初我太保守,设 max_memory={0:"4.8GiB"},把三分之一层 offload 到 CPU。结果 PCIe 来回搬数据,GPU 利用率一直上不去,我当时还以为是”batch=1 的天花板”——这是个刻板印象,很多人会这么归因。

后来放宽到 {0:"6.8GiB"},打印 model.hf_device_map 的 Counter一看,所有层都在 cuda 上了({'0': 1}),GPU 利用率直接拉到 99%。

超额的部分怎么办?靠 Windows 共享 GPU 内存自动兜底。这是 8GB 卡能跑起来的关键。

诊断方法：加载后打印 model.hf_device_map 的 Counter,看层在 cuda vs cpu 的分布。GPU 利用率低,第一件事不是怀疑 batch,是确认层分布。

反直觉高潮：Windows 原生居然赢了 WSL2#

我想更快,试了 WSL2 + SGLang(一个推理框架)。结果这条路彻底走不通,而且原因很反直觉:

WSL2 GPU 直通只有 6.84GB 可用(CUDA context 占了点)
模型加载完(6.49GB)只剩 0.28GB,SGLang 的 KV cache 池无处安放
关键:WSL2 用不了 Windows 的共享 GPU 内存兜底——这是它和 Windows 原生 WDDM 架构的根本差异

也就是说,在 Windows 原生下,8GB 是”8GB + 共享内存兜底”;在 WSL2 下,8GB 是硬墙。

结论：8GB 卡只能 Windows 原生 Transformers;SGLang 至少要 12GB 显存才有意义。

很多人下意识觉得”Linux/WSL2 跑 AI 更专业”,在小显存这个场景里,这个直觉是错的。

最终架构#

抛弃了 Gradio(版本冲突太烦),换 FastAPI + SSE + 自定义前端,更可控:

1
C:\Users\Legion\Unlimited-OCR\
2
├── run_web.bat          Web 服务启动(双击)
3
├── app.py               FastAPI 后端(推理 + SSE 流式)
4
├── index.html           深色双栏前端(复刻官方 UI)
5
├── run_ocr.bat          单图命令行(拖拽即用)
6
├── test_infer.py        命令行推理入口
7
├── models/Unlimited-OCR/  权重 + 5 个 trust_remote_code .py
8
└── .venv/               torch 2.10+cu128 + transformers 4.57.1

几个关键优化:

stdout 劫持实现 token 级流式：复刻官方 ThreadTargetedStdout,劫持推理线程的 stdout,逐 token 推到前端 SSE,边识别边出字。
save_results=False：去掉每页用 matplotlib 画带框图的开销(前端用不到),GPU 不用空等。
双层文本清理：模型原始输出是 <|det|>title [46,81,521,134]<|/det|>实际文本 这种带检测框坐标的——流式时用 clean_stream 缓冲隐藏未闭合标记,整页完成后用官方 remove_det 规整。

实测结果：33MB / 342 页招标文件,逐页流式解析成功,中文识别精准,GPU 利用率 ~99%。

一些可以复用的认知#

踩完这堆坑,我总结了下面这些,下次本地部署大模型应该能少走弯路:

8GB 显存是大模型本地部署的生死线,6.3GB 刚好挤进去,再大就难。
Windows 共享 GPU 内存是 8GB 卡的救命稻草,WSL2 没有这个机制——所以小显存反而 Windows 原生更合适。
GPU 利用率低,先排查 offload,别急着甩锅给 batch=1。先看 hf_device_map 层分布是不是全在 GPU。
大 PDF 必须逐页处理,即便模型号称”无限上下文”——那是模型能力,不是工程实现。
trust_remote_code 模型在 Windows 慎用 low_cpu_mem_usage,有段错误风险。
Blackwell(50 系)必须 cu128+,cu126 会无声失败。
“模型能力” ≠ “工程实现”,这是这次最大的认知更新。标语、benchmark、demo 展示的都是模型能力上限,工程落地要打很多折扣。

一份检查清单#

下次小显存本地部署大模型,按这个走:

torch.cuda.get_device_capability() 确认算力,选对应 CUDA 版本 torch
大文件下载先 curl 测速选镜像(hf-mirror / SJTU / 阿里云)
transformers / gradio / sglang 的 huggingface-hub 版本对齐
trust_remote_code 模型：避免 low_cpu_mem_usage=True
小显存:device_map="auto" + max_memory 宽松,依赖 Windows 共享内存
加载后打印 hf_device_map 确认层分布全在 GPU
大 PDF：PyMuPDF 拆页 → 逐页推理,不要 infer_multi
流式：stdout 劫持方案
文本后处理：清理 det 等版面标记
Windows bat 脚本用 GBK 编码(cmd.exe 用 GBK 解析 .bat)
WSL2：venv 建在 ext4 ~/,别放 /mnt/c(drvfs 慢且易出权限问题)

最后#

342 页 PDF 最终是转出来了,中文识别很准,表格和版面还原也比我预期好。整个过程最值钱的不是 OCR 结果本身,是踩出来的一套”消费级硬件跑大模型”的工程直觉——什么能省、什么不能省、哪些直觉是错的。

Unlimited-OCR 仓库：https://github.com/baidu/Unlimited-OCR

如果你也在小显存卡上折腾大模型,希望这篇能帮你少踩两个坑。

Agent = Model + Harness：为什么你的 AI 编码工具总是不稳定

Wed, 05 Aug 2026 00:00:00 GMT

很多人以为 AI 编码工具好不好用，取决于底层模型强不强。但用久了会发现一个现象：同一个模型，有人用起来很稳，有人用几天就崩。差别不在模型，而在模型之外的那一层——Harness。

拆开看：Model 和 Harness#

把任何一个 AI 编码工具拆开，其实是两个正交的部分：

Model（模型）：负责理解、推理、生成代码。这是你最容易感知到的部分。
Harness（工程规范）：让模型能稳定、按流程干活的整套工程约束系统。包括——
- 项目规范的存放位置（该听谁的、不该听谁的）
- 任务状态管理（做到哪一步了、下一步是什么）
- 上下文投喂策略（该喂什么、不喂什么、喂多少）
- 经验沉淀机制（踩过的坑下次怎么避免）
- 工具调用规程（什么时候该跑命令、什么时候该问人）
- 行为边界设定（哪些事绝不能让它自作主张）

三个关键认知#

1. 解耦思维 把”模型能 coding”和”模型能在项目中持续稳定 coding”彻底分开。前者是能力，后者是系统。

2. Harness 才是稳定性的来源 单一模型的提升，替代不了工程规范的缺失。模型再强，没有好的 Harness，照样在真实项目里翻车——因为它不知道你的项目规范、不知道上下文怎么组织、不知道边界在哪。

3. 表现归因 当 AI 编码工具表现不好时，先查 Harness 的完备性，而不是归咎于模型。这是最容易犯的错误：一不顺就换更强的模型，结果问题依旧。

我的实践#

我日常用 Claude Code 做主力交付，一开始也遇到过”越用越崩”的阶段。后来我把稳定性问题归因到 Harness 层，给自己搭了一套”永不遗忘系统”：

对话记忆：跨会话记住上下文，不用每次从零讲
代码知识图谱：全项目调用链、影响半径存进图数据库，改代码先定位影响
wiki 知识库：修过的 bug、做过的架构决策，以稳定引用的方式沉淀，下次不重踩

这就是我的 Harness 层。效果很直接：一个人能同时维护多个系统不掉线，新会话 5 秒内能检索到历史经验。这套系统让我真正理解了 Agent 好用的根源——不是快，是让知识跨会话积累。

结论#

评价一个 AI 编码工具（或你自己的 Agent 工作流），先看它的 Harness，再谈模型。从 vibe coding（无约束的乱写）到 spec coding（有工程规范的落地），本质就是给模型补上 Harness 这一层。模型会持续升级，但真正让你稳定产出的是那套看不见的工程系统。

Agent 工作流生态的三层解剖：方法论、运行时与实践

Wed, 05 Aug 2026 00:00:00 GMT

调研 Agent 工作流生态时，我犯过一个典型错误：把不同层次的项目拉到同一平面比 feature。

结果得到一张”功能对照表”，看似全面，实则什么也说明不了——因为它把三类完全正交的东西混在一起了。后来重做调研，按三层架构解剖，一切都清晰了。

三层架构#

1
┌─────────────────────────────────────────────┐
2
│  实践层（pattern）                           │
3
│  把方法论层的技能组合起来，解决真实的大问题     │
4
│  ↓ 依赖                                      │
5
│  方法论层（skill 集）                         │
6
│  教 Agent 干活时遵循什么纪律                  │
7
│  ↓ 运行于                                    │
8
│  运行时层（framework）                        │
9
│  Agent 怎么部署、持久化、多渠道               │
10
└─────────────────────────────────────────────┘

方法论层回答”Agent 干活时遵循什么纪律”。代表作是各种”技能集”——一套教 Agent 怎么写测试、怎么写计划、怎么追问的技能集合。
运行时层回答”Agent 怎么长期存活”。代表作是 Agent 运行时框架——checkpoint 持久化、沙箱、多渠道接入。
实践层回答”具体怎么把技能拼起来解决一个大问题”。代表作是”让弱模型一夜写完上万行代码”这类实践案例。

方法论层和运行时层不是竞争关系，是宿主关系——一套技能集既可以跑在这个运行时上，也可以跑在那个运行时上。

方法论层的两种风格：强约束 vs 轻启发#

同属方法论层，两套主流技能集分化成两种风格：

维度	强约束派	轻启发派
约束机制	铁律、硬门、红线表（大写、不可协商）	决策树 + 推荐答案
典型句式	”没有根因调查，就不许修"	"逐分支走下去，给出你的推荐答案”
追问机制	一次一问，终点是产出规范文档	一次一问 + 每题附推荐答案
目标用户	初级工程师、弱模型	有经验的工程师、强模型

两者的理论血统同源（TDD、领域驱动设计、深模块、缝等经典软件理论），但风格分化。

关键洞察：强约束和轻启发不是对错，是适配——

弱模型干活用强约束，强模型干活用轻启发。

弱模型没有”品味”，需要铁律和红线把它钉死；强模型有判断力，规则反而束缚它。如果你有多模型路由能力，正好可以按任务复杂度分发：简单任务给轻启发技能，关键任务给强约束技能。

运行时层的真正创新#

以一个”filesystem-first 的持久化 Agent 框架”为例，它的目录结构本身没什么，真正值得借鉴的是两个设计决策：

文档随包分发：Agent 能在本地读到自己框架的文档，不依赖模型参数里记住的东西。
durable = checkpointed workflow：每一步存证，崩溃从断点续跑，等审批时不消耗算力。

它的安全哲学也值得记：安全边界不是绝对隔离，而是靠窄工具设计 + 权限控制 + 审批 + 幂等设计一起完成。AI 生成的不可信代码进沙箱，开发者的工具在运行时里调沙箱，一行配置即可加工具级审批。

实践层最有价值的结论#

实践层案例里信息密度最高的一个洞察是：

代码仓库里最有价值的不是实现代码，是那套验证机制。工程师从质检员，变成质检闸门的设计师。

具体到工程：TDD 红绿循环是基础设施，但真正稀缺的是对抗性验证——比如让一个独立的子 Agent 监控测试有没有被”偷改”、用对比脚本证明新旧实现行为等价。这些机制防止的不是写错代码，是防止”弱模型绕过验证”。

结论#

看 Agent 生态，先分层再比较：

比较技能集 → 方法论层内比较（强约束 vs 轻启发）
比较框架 → 运行时层内比较（持久化、沙箱、渠道）
学习方法 → 去实践层找最高密度的案例

把不同层混比，是调研里最贵的错误。 分层之后，每层都有清晰的评判维度，照方抓药就行。

AI 应用的成本优化：从选型到缓存的全链路

Wed, 05 Aug 2026 00:00:00 GMT

做 AI 应用，尤其是 Agent 系统，“你的项目怎么节约成本”是面试必问、上线必踩的题。成本不是”换便宜模型”一个开关，而是贯穿从模型选型到任务编排的全链路方法论。

成本从哪来#

先拆清楚 AI 应用的成本结构：

Token 消耗：每次调用的输入 + 输出 token
调用次数：一个用户请求触发多少次模型调用（Agent 系统常是 N 次）
重复推理：重试、中断、幂等没做好导致的白跑
上下文膨胀：对话历史越攒越长，每次都重传一遍

六个优化方向#

1. 模型选择与路由#

不是所有任务都需要最强模型。 按任务复杂度动态路由：

简单分类 / 提取 → 轻量模型（便宜、快）
复杂推理 / 代码生成 → 强模型（贵但准）
结构化输出 → 带 JSON mode 的模型，省 token

实际工程里用 new-api、LiteLLM 这类网关做路由，按任务类型分发到不同模型。一次 Agent 流程里，规划用强模型、执行用便宜的，能砍掉一大块成本。

2. 提示压缩与上下文治理#

每次调用传的上下文越短越省钱。具体手段：

历史对话摘要而不是全量重传
只带相关文档（RAG 检索 top-k，不是把整个知识库塞进去）
系统提示用 prompt caching（Anthropic / OpenAI 都支持，缓存命中后输入 token 大幅打折）

3. 缓存与复用#

相同或相似的请求，结果缓存复用，避免重复推理：

确定性请求（如”总结这篇文章”）：结果落库，下次直接返回
半确定性请求：语义缓存（embedding 相似度匹配）
prompt caching：把固定上下文（系统提示、知识库）缓存到模型侧，命中后输入成本降 90%

4. 推理效率#

批处理：多个请求合并一次推理
流式输出：早返回早结束，减少超时重试
早停 / 结构化输出：让模型只输出必要内容，别啰嗦

5. 重复推理避免#

Agent 系统最容易浪费的地方：任务失败重试，从头再跑一遍。

解法：

任务状态检查点：每步做完落库，失败从断点续跑，不从头
幂等设计：同一个任务执行多次结果一致，重试不产生副作用
结果缓存按任务 ID：重试时先查缓存

6. 成本监控与归因#

不能笼统知道”这个月花了 500 块”，要能拆到具体功能 / 链式调用 / 用户。建立精细化追踪：

每次调用记录：哪个功能触发、走了哪个模型、消耗多少 token
按功能 / 用户 / 链路聚合，找出成本大头
大头先优化（二八定律——20% 的调用常消耗 80% 的成本）

一个常被忽略的点：上下文增长#

长对话 Agent 最隐蔽的成本是上下文雪球。第 10 轮对话时，前 9 轮历史每轮都要重新传一遍，token 消耗线性增长。

解法：

记忆分层：近期对话保原文，远期对话压缩成摘要
记忆系统：把事实沉淀到外部存储（向量库 / 知识图谱），用时检索，不靠对话历史承载
会话窗口管理：超过阈值自动截断 / 摘要

成本和质量的平衡#

成本优化的红线是不显著损害性能。判断方法：

核心链路（影响用户体验的关键步骤）→ 用强模型，不省
辅助链路（路由判断、简单提取、格式转换）→ 用便宜模型
可缓存链路 → 缓存优先，模型兜底

一刀切换便宜模型是最差的做法——核心链路质量下降直接毁产品。

结论#

AI 成本优化是个系统工程：选型（路由）+ 输入（提示压缩 / 缓存）+ 执行（幂等 / 续跑）+ 输出（结构化 / 监控）。每一步都有优化空间，组合起来能把成本压一个数量级。

面试时被问”做了哪些成本优化”，回答全链路 + 量化结果（降了百分之多少）才是工程师视角；只答”换便宜模型”是用户视角。

从 20 多个 bug 里归纳出的 6 类调试模式

Wed, 05 Aug 2026 00:00:00 GMT

写代码踩的 bug 成千上万，但归起类来，大部分 bug 都是同一类模式的重复。记录过 20 多个 bug 后，我发现它们收敛成 6 类模式。识别模式，比记住每个 bug 的细节高效得多。

模式一：编码 / 字符集问题#

典型症状：中文文件名乱码、特殊字符导致接口 500、自定义名称不被库识别。

常见根因：

默认编码不对（比如归档工具用旧编码处理中文名）
自定义名称和库内置字典对不上（tiktoken 不认模型名）
文件名含特殊字符，URL 编码 / 解码不对称

通用修复思路：任何处理文件名、编码、名称的地方，都要验证字符串全链路传递正确——编码 → 传输 → 解码，任一段错就乱。

模式二：数据计算精度#

典型症状：统计值反复出错、数据重复写入、单日工时异常巨大。

常见根因：

复杂计算逻辑在重构中丢失了某一段
缺少防重复写入机制（幂等）
总账没按基准摊分（单日 120h 这种不合理值没人挡）

通用修复思路：数据计算加防御层——输入验证 → 中间校验 → 输出合理性检查。不要只在末端验证。

模式三：配置 / 环境问题#

典型症状：服务连不上、构建撑爆磁盘、参数边界报错。

常见根因：

服务绑定 127.0.0.1 而不是 0.0.0.0，外部连不上
构建前不检查磁盘空间，直接打满
参数校验边界两端不一致

通用修复思路：环境问题先查四件事——端口绑定、磁盘空间、权限、启动顺序。四个都不对再深挖。

模式四：前端 / API 契约#

典型症状：API 重定向导致功能瘫痪、页面渲染异常、字段对不上。

常见根因：

API 尾部斜杠 / 大小写不宽容，重定向把请求带飞
单体 HTML 里函数重复定义互相覆盖
前端改了字段名，后端没同步

通用修复思路：API 对输入宽容（尾部斜杠、大小写）；前端改完跑全功能回归，不只测改的那一页。

模式五：数据管道#

典型症状：数据在链路里”变了样”，源头没问题、结果不对。

核心认知：数据从源头到页面经过多个阶段，每个阶段都可能引入偏差——拉取不全、解析断字段、清洗边界错、计算重复、渲染不匹配。

通用修复思路：管道逐阶段加检查点（详见数据管道的六阶段验证），让问题当场暴露在哪一段，而不是最后才知道。

模式六：对象存在 ≠ 功能可用#

典型症状：配置”看起来都在”，服务”看着活着”，但用户路径就是不通。

常见根因：

路由对象存在但实际不可达
进程存活但功能已挂
映射条目在但读不了数据

通用修复思路：任何状态判断都验证最终用户路径（真实读取、真实连接），而不是只看对象 / 进程 / 配置存在。

调试通用流程#

识别出模式后，调试本身也有固定流程：

1
复现 → 确认不是环境/配置问题 → 二分定位到最少代码行 → 加日志看中间状态
2
→ 查历史（有没有同类 bug 记录过）→ 最小改动修复 → 写测试防回归 → 记录沉淀

其中两条最容易被跳过：二分定位（一次改一堆再试是浪费）和查历史（大概率有人踩过，先搜再动手）。

结论#

bug 是模式，不是事件。

遇到 bug 先归类——是编码、计算、环境、契约、管道、还是状态判断？归到类，修复思路就出来了。再对照通用调试流程走一遍，基本都能落。

把 bug 沉淀成模式库，比记住”这个 bug 怎么修”值钱得多——因为模式能迁移到下一个项目。

口径变更的三层陷阱：改代码 ≠ 改数据 ≠ 改缓存

Wed, 05 Aug 2026 00:00:00 GMT

业务系统里，“统计口径”（某个数字到底怎么算）是朝令夕改的高频对象。而口径变更最容易踩的坑不是”改代码”，是只改了代码。

一个统计口径的变更，至少涉及三层：代码逻辑、历史数据、展示缓存。漏掉任何一层，你看到的都是”改了但没变”。

陷阱一：改代码 ≠ 改数据#

场景：某个统计从”排除 X”翻转为”纳入 X”。

你把代码改了：查询逻辑、聚合逻辑、前端显示全改了，单测也过了。但线上的数字没变。

为什么？因为过去的历史数据在”排除 X”阶段就已经被清理掉了。X 现在根本不在数据库里，代码再对，也无米下锅。

口径从”排除 X”翻转为”纳入 X”时，多问一句：X 现在在数据库里吗？ 如果之前是”同步即删”的设计，光改代码不够，必须触发一次全量重同步，让新逻辑把 X 重新拉回来。

陷阱二：改生成端 ≠ 清展示端缓存#

场景：数字是 AI 生成的结论。你改了生成规则（比如禁用一个指标），提示词对了、喂的数据对了、服务重启了、单测过了。用户看到的结论还是旧的。

为什么？因为展示端是读结论缓存表的，旧记录还在表里，页面读缓存直接显示，根本不会触发重新生成。你改了”生产端”，但”展示端”的历史结论没清。

正确的闭环有四段，缺一不可：

改生成端：提示词 + 喂给模型的数据
清展示端缓存：删掉结论缓存里的旧记录
触发一次重算：让新规则落进缓存
验证新输出：拉一条结论，grep 旧关键词确认 0 命中

光改生成端 + 重启 ≠ 用户看到新结论。 这条是”改了但没效”的典型：代码层完全正确，但展示链路里的旧状态还在。

陷阱三：改 AI 结论，剥字段比改提示词可靠#

接上面的场景：你想让 AI 结论里不再出现某个指标（比如加班时长）。光在提示词里加一句”禁止使用 X”够吗？不够。 模型还是会从喂给它的数据字段里自己推出来——字段里有 hours_over_8h、total_overtime_h，它自然会用。

模型的结论口径 = 喂的数据 + 提示词约束，共同决定。 提示词禁令是”口头劝阻”，剥字段是”物理约束”。改 AI 口径先想：这些字段还要不要喂？能不喂就不喂。

陷阱四：用户口述自相矛盾 → 结构化锁定#

口径变更里最隐蔽的坑：用户自己说的话前后矛盾。

比如需求文档里写”指标 A 改为指标 B”，用户口述却是”指标 A 改为指标 C”。两个词长得很像，语义完全不同。你按其中一句猜着改了，必然返工。

解法不是猜，是给结构化选项让用户一次拍死：

用 4 个选项把口径问清楚（保持 A / 统一为 B / 统一为 C / 其他），附一个推荐项。代价是 1 个问题，收益是不返工。

口述越模糊、术语越相近，越要用选择题，而不是靠上下文猜。

一个共性#

这四个陷阱背后是同一个认知：“改了源头” ≠ “改了运行时” ≠ “改了展示链路的旧状态”。代码正确只是第一层，历史数据要重新同步，展示缓存要显式失效，AI 结论要物理约束喂的数据。

口径变更不是一次代码修改，是代码、数据、缓存、验证四个动作的一次组合拳。

下一次改任何”数字怎么算”的需求，先列这张清单再动手：改代码 → 重同步数据 → 失效缓存 → 触发重算 → 验证新输出。一步都不能省。

代码知识图谱怎么选：纯代码结构 vs 全模态知识图谱

Wed, 05 Aug 2026 00:00:00 GMT

想让 AI 助手”读懂”你的代码库，常见方案是建代码知识图谱。但”读代码库”其实有两种完全不同的需求，对应两类不同的工具：

代码结构图谱：回答”这个函数被谁调用了？”
全模态知识图谱：回答”这个系统的设计动机是什么？”

把这两类混为一谈，是选型时最常犯的错。

两类工具的本质差异#

纯代码结构图谱：源码 → 语法分析（AST）→ 存进数据库 → 一个查询工具。只含代码结构：函数、类、调用关系、导入关系。

1
源码 → AST → 数据库 → "authMiddleware 被谁调用了？"

全模态知识图谱：代码 + 文档 + PDF + 图片全部索引 → 代码走语法分析，文档/图片走 LLM 提取概念 → 存进图结构 → 交互式可视化 + 多种查询。

1
代码 + 文档 + PDF + 图片 → AST(代码) + LLM(文档) → 图谱 → 可视化 + 查询

对比表#

维度	纯代码结构	全模态知识图谱
索引内容	只有代码	代码 + 文档 + 图片 + PDF
代码提取	语法分析 AST	语法分析 AST（相同）
文档 / 图片	❌ 不支持	✅ LLM 提取概念和关系
索引成本	零（纯本地解析）	文档部分走 LLM（有 token 费）
输出	文本查询结果	HTML 交互图 + JSON + 多种格式
”为什么”	❌ 只有结构	✅ 从注释/docstring 提取设计动机
社区发现	❌	✅ 自动聚类相似模式
置信度	无	✅ 区分事实（抽取）与推测（推断）

四个典型场景怎么选#

场景一：日常代码导航——“上传接口在哪个文件？调用链是什么？” 两个都能做，但纯代码结构更轻更快。

场景二：跨项目 Bug 模式——“ZIP 编码问题在 A 和 B 两个项目都出现过，它们有共同点吗？” 纯代码结构看不到跨项目概念；全模态图谱的社区发现会把两个 bug 自动聚类到一起。

场景三：新人接手项目——“系统整体架构什么样？关键设计决策是什么？” 纯代码结构能给结构，但没有”为什么”；全模态图谱能提取设计动机、输出架构报告。

场景四：文档与代码联动——“这份文档说的修复，对应代码里哪个函数？” 纯代码结构不索引文档；全模态图谱把文档和代码放进同一个图谱，直接关联。

选型建议#

如果你的资产只有代码 → 纯代码结构图谱（零成本、极简、快）。

如果代码 + 文档（wiki / bug 记录 / 设计文档）都要 → 全模态知识图谱。代码部分走语法分析（零 token），文档部分走 LLM（有缓存，只处理一次），成本可控。

如果两个都要，先装轻的。 纯代码结构解决 80% 的日常导航需求；等文档资产多起来，再补全模态的做跨项目分析。

一个务实的组合#

很多人最终会走到”分层”的路线：

代码导航用轻量的结构图谱（毫秒级响应、零成本）
知识沉淀用文档型知识库（人机共用、版本可控）
跨项目洞察用全模态图谱（按需建，处理文档资产）

三个各司其职，而不是一个工具试图解决所有问题。

结论#

选型先分清问题：

“函数被谁调用”是结构问题，用代码结构图谱；“系统为什么这么设计”是知识问题，用全模态图谱。

先回答你要解决哪个问题，再选工具。两个都答不出”哪个适合你”，那就先上轻的那个。

定时任务凌晨配置白天跑？先查时区

Wed, 05 Aug 2026 00:00:00 GMT

线上服务每天上午 10 点准时出现几百条超时/500，持续十几分钟，然后”自己好了”。这种幽灵故障，90% 的根因不是业务代码——是定时任务的时区错位。

典型症状#

服务每天固定时刻出现几百条超时/500，持续十几分钟，然后自愈
配置/文档里写的是凌晨低峰执行维护，实际运行时间却是白天工作时间
维护任务耗时随数据量增长逐日恶化（今天 2 分钟，下周 20 分钟）

排查路径（按序，命中率高）#

1. 按分钟聚合 ERROR/WARN，找爆发窗口 不是看单条错误，而是看分布。grep '"level":"ERROR"' log | 按 time 分桶统计，错误会聚成一个明显的尖峰。

2. 与维护任务起止时间对齐 找 VACUUM / GC / backup / checkpoint 这类任务的 Start/Complete 日志，比对是否与错误窗口严丝合缝。能对上 = 找到元凶。

3. 看维护任务耗时趋势 VACUUM 之类每天都会记录 duration，统计 7 天趋势——持续恶化 = 数据增长型问题。

4. 源码确认 Timezone（关键一步） grep Timezone 调度注册代码。凡是 Timezone: "UTC" + 服务器在 UTC+8，直接把 UTC 时间 +8 才是真实执行时刻。

举例：cron 写 0 2 * * *（凌晨 2 点），如果调度用 UTC，那它在 UTC+8 就是上午 10 点 执行——工作时间黄金时段。

两条铁律#

铁律一：配置”低峰时间”前，先确认调度时区。凌晨配置白天执行，先查时区，别查业务逻辑。

铁律二：排查”固定时刻故障”时，不要一开始就查业务代码，先看有没有每日维护任务在这个时刻跑（VACUUM / 备份 / 清理 / 缓存重建都是候选）。

放大因素：数据只进不出#

这类故障常被一个隐藏问题放大：存储策略默认关闭清理。

请求日志只进不出，DB 7 天涨到 8GB，所有全表操作（VACUUM / 备份 / 查询）逐日变慢，维护窗口越拖越长，最终撞进工作时间。

教训：“默认不清理”对日志型表是定时炸弹。启用保留策略（如请求日志保留 7 天），让库停在固定水位。

守护进程的”假死”特性#

守护进程维护类操作（VACUUM / 全量备份）对在线服务的杀伤方式很特别：锁库期间所有请求超时 → 对外表现为 500 或超时，且进程本身没崩。

监控看起来一切正常（CPU 不高、内存正常、进程存活），但用户疯狂 500。这是”假死”不是”崩溃”，不会触发重启告警，特别容易漏判。

结论#

记住这套症状指纹：每日固定时刻 500 + 维护任务在同一时刻 + 进程没崩。下次遇到，第一反应不是去读业务代码，而是 grep Timezone 看调度时区——这一步能省你一整天瞎排查。

数据管道的六阶段验证：别等最后才发现错误

Wed, 05 Aug 2026 00:00:00 GMT

数据系统上线后最难受的事：流程全跑完了，页面数字不对，但你不知道错在哪一步。

一个典型数据管道长这样：源系统 → 拉取 → 解析 → 清洗 → 计算 → 评分 → 渲染。数据在六个阶段之间流动，每个阶段都可能悄悄引入偏差。如果在最后一个阶段才发现问题，你得逆着整条链路往回查，定位成本成倍上升。

六道关口，各自的问题#

1
拉取 → 解析 → 清洗 → 计算 → 评分 → 渲染
2
 ↑       ↑      ↑      ↑      ↑      ↑
3
检查点  检查点  检查点  检查点  检查点  检查点

阶段	常见问题
拉取	分页不全、权限不足、接口超时、中途断流
解析	字段缺失、类型错误、编码乱码
清洗	过滤条件不对、边界情况遗漏
计算	公式错误、日期基准不同、重复计算
评分	权重不合理、缺少归一化、口径口径漂移
渲染	数据格式不匹配、前端解析失败

每一关都是独立的出错源。最坑的是相邻两关的偏差会互相掩盖——上游多算了一倍，下游以为那是正确值，一路带到最末端。

核心教训：每阶段都要有验证点#

不要在最后一个阶段才发现数据问题。做法是在管道每一段出口都放一个”检查点”，用断言守住：

拉取完 → 断言”条数 >= 0 且与源系统一致”（分页有没有拉全）
解析完 → 断言”关键字段全部非空、类型正确”（有没有解析断字段）
清洗完 → 断言”过滤后的集合等于预期集合”（过滤条件有没有改错边界）
计算完 → 断言”总账与明细账对得上”（有没有重复计算）
渲染前 → 断言”数据格式能被前端直接消费”（前端不用自己推导）

每段出口的断言，把”最后才知道错”变成”当场就知道错在哪一段”。

边界场景是最常漏的#

很多管道 bug 不是主流程错，是边界场景没覆盖：

空数据（今天一条都没有，不是异常，但要能显示”0”）
极值（单条记录异常巨大，不能把均值拉爆）
重复数据（同一批被拉了两次，幂等要挡住）
口径切换（统计规则变了，历史数据要不要重新算？）

给每个边界场景写一条独立断言，而不是只在”happy path”上验证。

和”缓存失效”是一对#

管道验证守的是”算得对不对”，缓存同步失效守的是”看的是不是新结果”。一个管上游、一个管下游，两者都漏才是”改了完全没反应”。

结论#

数据系统的可靠性不靠”仔细写代码”，靠在管道的每一段出口都放检查点。六个阶段，六道关卡，任何一道先发现问题，你就知道往哪一段回查，而不是把整个管道从头到尾再审一遍。

别等最后一个阶段才发现数据问题——每一段都加验证点。

Docker 部署的红线经验：什么时候用、什么时候别用

Wed, 05 Aug 2026 00:00:00 GMT

Docker 很香，但不是所有部署都该用 Docker。用错时机、碰错红线，付出的代价远超省下的环境隔离时间。

什么时候用 Docker#

上游有官方镜像且维护活跃：装一个官方长期维护的服务，直接用现成镜像
依赖复杂：Python / Node 多版本共存，环境互相污染，容器隔离干净
需要隔离环境：不同项目要不同版本的库

什么时候别用 Docker#

简单服务（单个 Python / Node 进程）：直接 systemd 托管更轻、更好排查
轻量工具：能走标准输入输出的，不需要容器
大镜像构建（>5GB）：构建峰值可能吃掉十几个 G，系统盘扛不住

四条红线（每一条都踩出过事故）#

红线一：容器运行时的 daemon 绝不能随意重启#

systemctl restart docker 会杀掉所有容器，等于一次全站停机。如果你在服务器上还连着对话、跑着业务，这一下全断。

要重启容器，用 docker restart <容器名>。daemon 重启是核弹，单容器重启是手术刀。

红线二：构建前必须看磁盘空间#

一次构建峰值吃掉 25GB，系统盘总共几十 G——直接打满，所有服务卡死。

规则：

构建大东西之前先 df -h
大项目、大数据集放数据盘
系统盘容量是红线，任何超过几个 G 的操作都危险

红线三：容器内访问宿主机，别用 127.0.0.1#

Docker 网桥下，容器里的 127.0.0.1 是容器自己，不是宿主机。容器内要访问宿主机服务：

用 host.docker.internal（Docker 提供的主机别名）
宿主机的服务要监听 0.0.0.0 而不是 127.0.0.1，否则容器连不上

红线四：常驻服务必须 systemd 托管#

不要手动 nohup 起一个长期服务——服务器重启后它就没了。

1
常驻服务 → systemd unit + systemctl enable（开机自启）

容器网络一句话总结#

1
容器内 127.0.0.1 = 容器自己
2
宿主机服务 = host.docker.internal（需监听 0.0.0.0）

长期运行的隐性风险#

容器长期不重启会隐藏 latent bug：内存缓慢泄漏、文件句柄累积、缓存过期逻辑从没触发过。定期滚动重启 + 状态巡检，让这些问题在可控时暴露，而不是在某个高峰期崩。

结论#

Docker 部署的四条红线：

daemon 不随便重启，单容器重启走 docker restart
构建前先 df -h，大东西放数据盘
容器访问宿主机用 host.docker.internal，别用 127.0.0.1
常驻服务 systemd 托管，别裸跑

Docker 解决环境隔离，但环境隔离解决不了磁盘、网络、进程管理的问题。用对时机，别让工具绑架架构。

从 Vibe Coding 到 Spec Coding：AI 编码该有的样子

Wed, 05 Aug 2026 00:00:00 GMT

上一篇聊了 Agent = Model + Harness，说真正让 AI 编码稳定的是 Harness 层。这篇接下去：Harness 落地到日常编码，就是 spec coding——规范编码。 它和 vibe coding 是两种完全不同的工作方式。

两种编码风格#

Vibe coding（凭感觉编码）：打开 AI，把需求一股脑丢过去，让它”帮我写个 XXX”。AI 生成什么你就用什么，不顺再让它改。爽在即时反馈，像在飙车。

Spec coding（规范编码）：写代码之前，先把项目规范、任务进度、上下文、经验教训沉淀到项目结构里，再让 AI 基于这些事实干活。

vibe coding 不是”错”，它在 demo、原型、一次性脚本里效率极高。但一旦项目长期化、需要多人协作或持续迭代，vibe coding 必崩——因为 AI 记不住上次怎么做的，每次都重新猜。

为什么 vibe coding 会崩#

根因是会话失忆：

今天和 AI 说”这个项目用 camelCase 命名”，明天新开会话它又给你 snake_case
上周定下的”错误码用数字枚举”，这周它给你写字符串
你踩过的坑，下次它会让你再踩一遍

vibe coding 把所有”应该怎么做”放在临时对话里。对话一结束，这些事实就蒸发了。你被迫每次重新传递上下文——传少了 AI 乱来，传多了 token 爆炸。

Spec coding 的核心：把事实从对话搬到结构#

spec coding 不是”把每件事都流程化”（那是官僚主义）。它的重点是：

沉淀长期有复用价值的项目事实，不在于把每件事都流程化。

什么是”项目事实”：

规范：命名约定、代码风格、技术栈选型、禁止行为清单
架构决策：为什么选 A 不选 B、哪些边界不能破
任务进度：做到哪了、下一步是什么、哪些坑已踩
经验教训：bug 根因、修复方案、踩过的陷阱

这些事实原来散在对话里，spec coding 把它们搬到项目结构里——README、ARCHITECTURE、规范文件、CLAUDE.md、任务清单、bug 日志。AI 每次干活前先读这些，自动对齐，不用你每次重讲。

三个具体做法#

1. 规范文件：项目根目录放一份规范（比如 CLAUDE.md），写清”这个项目该怎么做、不该怎么做”。AI 每次进来先读。

2. 架构先行：动手前先让 AI 输出功能解析 + 架构图 + 边界清单，确认无误再写代码。比直接让它”写”慢 5 分钟，但少走 2 小时弯路。

3. 经验闭环：修完 bug、做完决策，立刻沉淀到 wiki/文档里，以稳定引用（不是裸行号）记录。下次同类问题 AI 先查历史，不重踩。

它和 Harness 是一回事#

spec coding 是 Harness 在编码流程里的具体形态。Harness 是”让模型稳定干活的工程约束系统”，spec coding 是”工程师怎么用这个系统”。

我之前那套”永不遗忘系统”（对话记忆 + 代码图谱 + wiki 知识库）就是 spec coding 的工程实现——让我能跨会话、跨项目保留项目事实，AI 进来 5 秒就能对齐上下文。

结论#

vibe coding 适合一次性，spec coding 适合长期主义。判断标准很简单：

这个项目/任务一周后还要不要继续？ 要 → spec coding；不要 → vibe coding 随便爽。

从 vibe 到 spec 的转变，本质是给 AI 编码补上”项目事实”这一层。模型会升级，工具会更迭，但”把事实沉淀好”这件事会一直值钱。

后端工程师学前端：一条踩坑驱动的学习路径

Wed, 05 Aug 2026 00:00:00 GMT

后端工程师学前端，最常见的坑是按教程从 HTML/CSS 一路学，学完还是不会做项目。我的路线反过来：直接做项目，每个技术点靠踩坑学会。

主线：Next.js + React + Tailwind#

Next.js：React 的全栈框架，自带路由、SSR、构建工具，是现在做前端的主线
React：函数组件 + Hooks 优先，别在类组件上浪费时间
Tailwind CSS：原子化 CSS，不用写一堆 class 文件
组件库：shadcn/ui 风格——直接把组件源码拷进自己项目改，而不是引入整个依赖

每个技术点背后的坑#

1. 字体加载：next/font/google 会坑你

Next.js 的 Turbopack 构建模式下，next/font/google 会构建失败（Unknown font）。

1
解法：改用 @fontsource-variable/* 自托管

自托管的好处：字体加载稳定、不依赖 Google CDN、国内可访问。

2. Node 版本：Next.js 16 需要 Node 20+

Node 18 不支持新版 Next.js。版本不匹配会在构建时爆，而不是运行时。 装新项目前先确认 Node 版本。

3. Tailwind 原生模块：缺失就构建失败

@tailwindcss/oxide 这类原生模块缺失会导致构建失败。解法通常是重新安装 node_modules。

4. 部署：静态导出最轻量

纯静态页面用 next export 导出 + nginx 直接指向目录，是最轻量的部署方式。需要动态能力再用服务器渲染。

5. 子路径部署：需要 basePath + nginx

部署到 /my-app/ 子路径下，Next.js 要配 basePath，nginx 要配对应的反代规则。不然静态资源和 API 全迷路（详见nginx 子路径部署）。

学习素材：逆向真实站点#

比看教程更快的方法：找一个做得好的站点，F12 逆向它的实现。

看它的技术栈（Next.js + Tailwind + 图标库 + 构建工具）
看它的设计风格（暗色主题、渐变背景、卡片式布局）
数一数它的 JS chunk 数，理解模块化架构
参考它的排版和配色

把真实站点拆开看一遍，比看十篇”什么是 Tailwind”的文章有用。

每次做前端都要对照的检查清单#

后端工程师做前端，做完容易”能用就行”。但一个”能用的页面”和”一个像样的页面”差距巨大。我每次做前端必对照 10 项：

图标 / 通知 / 动效 / 暗色模式 / 字体 / 排版 / 三态（默认/悬停/禁用）/ 搜索 / 组件复用 / 响应式

少一项，页面就”缺点意思”。这 10 项就是前端不该是 LLM 的默认审美那篇里”反默认审美”的具体落地清单。

结论#

后端学前端的正确姿势：

直接做项目，技术点靠踩坑学会
逆向真实站点，比看教程快
用组件库源码，不重复造轮子
每次做完对照检查清单，别停在”能用”

前端不是一门”学完再会用”的课，是一门”做着做着就会”的功夫。

后端功底（数据、接口、性能思维）反而是做前端时的差异化优势——你会比纯前端更在意加载、缓存和接口设计。

前端不该是 LLM 的默认审美

Wed, 05 Aug 2026 00:00:00 GMT

让 LLM 直接”写个 landing page”，你大概率会得到这种东西：

蓝紫渐变的安全配色
千篇一律的卡片 grid 布局
每个区块上方一个”眉毛标签”（eyebrow label）
全静态，没有任何过渡和动效
看起来很”现代”，但毫无记忆点

这就是 LLM 的默认审美——安全、平庸、一眼 AI 味。问题不在模型能力，在于直接让模型生成 = 放弃了设计决策。

为什么会这样#

LLM 训练数据里充斥着这种”安全模板”：成千上万的中等质量 landing page，配色保守、布局套路、动效为零。模型学到的”前端正确答案”就是这个平均水平。

你让它”做得好看点”，它会加大渐变、加阴影、加 emoji——离”好看”越来越远，离”AI 味”越来越近。

Design Token：把设计决策前置#

跳出默认审美的第一步，是先做设计决策，再写代码。

具体做法是先定义 Design Token——把颜色、字体、圆角、阴影、间距这些视觉原子，抽成命名的变量：

1
color.bg.primary     = #0a0a0f
2
color.text.primary   = #f5f5f7
3
color.accent         = #ff4d8d   // 强调色，品牌锚点
4
font.display         = "Inter Display"
5
font.body            = "Inter"
6
radius.card          = 16px
7
shadow.elevated      = 0 8px 32px rgba(0,0,0,0.3)

把 #ff4d8d 抽象成 color.accent，意义在于：设计决策（用这个粉色）和代码实现（在哪里用）解耦了。改主题只改 token 文件，全局生效。

模型拿到 token 文件后生成，配色就不再是”安全蓝紫”，而是你定的风格。你把决策权从模型手里拿回来了。

Design System：让风格可复现#

Token 之上是 Design System——一套组件的样式契约（按钮的三态、卡片的层级、间距的节奏）。

有了 Design System：

换主题 = 换 token 映射表（白标 / 暗色 / 多品牌一键切换）
风格统一 = 所有页面共享同一套样式逻辑
AI 生成 = 给定 token + system，生成的界面风格一致，不是每次随机

组件库（shadcn/ui、Radix）本质就是 Design System 的工程实现——它们用 token 定义基础样式的单一事实源，避免样式碎片化。

几条反默认审美的实践#

1. 先设计后编码 不是”让 AI 写个页面”，而是”先定设计意图（关键词：情绪 / 风格 / 参考站），再让 AI 基于这个意图生成”。设计意图前置，模型才有方向。

2. 用参考站锚定 别用形容词描述设计（“高级感""极简风”模型听不懂），用具体参考站：“像 linear.app""像 stripe.com”。模型对具体站点的视觉特征有记忆，比抽象词靠谱。

3. 强调动效 默认生成是静态的。明确要求”hover 有微动效""滚动有进入动画""主题切换平滑过渡”，模型才会加。动效是页面”活”的关键。

4. 自托管字体 next/font/google 在某些构建工具下会报错（Unknown font）。改用 @fontsource-variable/* 自托管——字体加载稳定、不依赖 Google CDN、国内可访问。

5. 部署前必须真机验证 截图第一次就要 cache-bust（--user-data-dir 独立 profile 绕缓存），否则你看到的是旧版本，改了等于没改。

我的流程#

后端工程师做前端，最大的坑不是”不会写”，是”被 LLM 的默认审美带跑”。我现在的工作流：

1
定设计意图 + 参考站 → 定义 Design Token → 让 AI 基于 token 生成 → 真机验证 → 微调

每一步都把”设计决策”从我手里显式地交给模型，而不是让模型自己拍板。这样出来的前端，才不是 LLM 的默认审美，而是我的审美被工程化实现。

结论#

LLM 的默认前端 = 安全 + 平庸 + 一眼 AI。要跳出这个陷阱：

设计决策前置，模型只负责实现，不负责拍板。

Design Token 和 Design System 是把决策权拿回来的工程工具。前端能力弱的工程师，靠这套流程也能做出有风格、有记忆点的界面——而不是又一个”AI 生成的 landing page”。

如何组织一个机器可读的知识库：Obsidian + Markdown 的实践

Wed, 05 Aug 2026 00:00:00 GMT

个人知识库很容易长成”剪藏垃圾场”：看到好文章就收藏，几个月后想找某个经验，翻半天找不到。

我踩过这个坑之后，把知识库重构成一套机器可读的规范——不只是给人看的，也是喂得动 AI 的。

这库是干什么的：先划边界#

要	不要
项目决策、Bug 根因、可复用经验	无筛选的剪藏垃圾场
人机都能检索的结构化 Markdown	只给插件看的英文双轨分类
入口清晰：首页 → 目录 → 页面	只靠侧边栏滚目录

底层方法：借 ACE 意图（知识 / 行动 / 时间）+ MOC 导航 + 受控页面类型。不采用全库硬切 PARA、无约束卡片狂拆。

新建一页前，先走决策树#

最防止”垃圾场”的是新建门槛。每次要记东西，先过一遍决策树：

这是不是一次可复用的经验？是 → 经验
是不是故障闭环？是 → bug
挂在现有项目页的变更日志够不够？够 → 不新建
外部文章 → 只建来源索引，概念能不拆就不拆

第 3 条最关键：能挂在现有页面就绝不新建。页面数量爆炸是知识库烂掉的开始。

写正文的规范#

1. frontmatter 填全：type / title / created / updated，业务页补状态和所属领域。

2. 链接只用裸链接：[[页面名]] 而不是 [[目录/页面]]。裸链接按名字解析，文件移动不断链。

3. 结论先看：高价值的经验页，开头先给一句话结论，别让人翻到底才知道这页讲什么。

4. 用醒目块区分关键信息：症状 / 根因 / 修复 / 教训 / 风险，用不同的强调块区分，一眼扫到重点。

MOC：只做索引，不写长文#

MOC（Map of Content）是知识库的导航层，只放链接，不写正文。

1
MOC-Agent与Harness
2
MOC-部署与网关
3
MOC-前端设计
4
...
5

6
新增一页 → 在对应 MOC 下加一行
7
  - [[页面名]] — 一句话

首页 → MOC → 页面，三级入口。新知识库成员（人或 AI）进来，5 秒知道有什么、在哪。

为什么”机器可读”很重要#

这套规范最大的受益者其实是 AI 助手。给 AI 配一个知识库 MCP 接口后：

它按 type 字段知道一页是经验还是 bug
它按裸链接能顺着 [[关联]] 跳转相关页
它按 MOC 能找到”这个领域有哪些内容”
它读经验页时先看到结论，不用全文读完

规范即接口。你给知识库定的结构，就是 AI 检索它的接口定义。

两条禁忌#

不为单篇剪藏自动生成十几个概念页——那是垃圾场膨胀的自动版
不写路径链接（[[dir/page]]）——文件一移动全断

看到”不自动生成概念页”，你可能会问：那什么时候才该建概念页？

这里的关键不是”建不建”，而是”门槛设在哪”。LLM Wiki 和 Obsidian 自动生成概念页的逻辑，本质是把门槛降到了”出现一次就建”——每个专有名词一页，为的是给关系图谱提供节点。这在”领域百科”型知识库（系统收集一个领域的术语）里是对的，术语就是知识骨架；但你的库如果是”项目记忆库”（记经验、记决策、记 bug），概念就是配角，无脑拆页只会让图谱被空壳节点淹没。

图谱的节点不一定是概念页——项目页、经验页、bug 页互相 [[关联]]，本身就是图谱。MOC 是手动策展的导航层，图谱是自动的关联层，两者互补。你要的是”节点和边够多”，不是”每个名词都有一页”。

那什么时候把一个名词”升格”成独立概念页？三条门槛，满足其一才建：

判断维度	问自己	门槛
复用度	这个概念会被几个页面引用？	≥2 个才建；只在单篇剪藏出现 → 留在原文
权威性	这个词的语义需要统一定义吗？	多处说法会不一致才建页”定锚”
丢失风险	不建这页，它会丢吗？	散落各处检索不到才建；不会 → 不建

三条都答”否” → 不建，让它留在记录页里。

自动生成和克制升格，差的只是这道门槛设在哪。门可以低，不能为零。

结论#

知识库组织规范的本质是三件事：

建前有门槛（决策树），写时有模板（受控类型），检索有入口（MOC）。

个人知识库不需要复杂工具，一套克制的规范 + Markdown + Git 版本控制就够了。克制，是知识库最稀缺的品质。

LangChain / LangGraph 学习笔记：什么时候该用，什么时候别用

Wed, 05 Aug 2026 00:00:00 GMT

LangChain / LangGraph 几乎是 AI 应用开发绕不开的名字。我学它的时候记了三句话，后来发现这三句话就是选型时最该想清楚的事。

先搞懂它是什么#

LangChain：链式调用大模型 + 工具的组合框架。把”调模型、接工具、做中间处理”串成一条链。
LangGraph：有状态的 Agent 工作流。用图结构表达”先做什么、条件分支、循环、多步骤状态”，适合复杂流程。

一句话：LangChain 是”链”，LangGraph 是”图”。 简单流程用链，复杂状态机用图。

三句学习笔记#

第一句：通用框架 vs 专用系统，先分清。

LangChain/LangGraph 是通用的 Agent 框架——什么业务都能套。而有些 Agent 系统是专用的（为特定场景设计好了一整套能力和边界）。

通用框架的好处是灵活、可定制；坏处是所有东西都要自己搭——工具调用、记忆、状态管理、错误处理，每个都要配置和调试。专用系统则相反：上手快、开箱即用，但扩展受限。

选型的关键不是”哪个更流行”，是”你的项目需要多强的定制”。

第二句：学它 ≠ 用它。

学习 LangChain 是为了理解 AI 应用的通用范式——工具调用、链式编排、状态管理、上下文处理。这套心智模型是通用的，换个框架、甚至自己写，都用得上。

但学到 ≠ 生产项目必须用它。如果你的项目用一个专用 Agent 系统已经能满足需求，不要为了”用上了热门框架”而强行迁移。技术选型的成本收益要算清：迁移一个正在运行的系统，要付出什么，得到什么？

第三句：没有它，现在的需求也能完成吗？

每次想引入一个框架，先问这句。如果现有工具链已经覆盖需求，新框架引入的是新的依赖、新的学习成本、新的 bug 面——而不是新能力。

什么项目适合 LangGraph#

复杂、有状态、需要精细控制流程的项目：

多步骤流程，步骤间有依赖和分支
需要持久化中间状态（做到一半保存，下次继续）
需要人对关键步骤审批 / 干预
需要精细控制每步用哪个模型、什么上下文

什么项目别用#

简单的一次性调用（调模型 → 得结果 → 结束）
已有专用系统覆盖的场景
团队没人熟悉、需要从零学起的项目

结论#

每个 AI 工程师都该学 LangChain，但不是每个项目都该用 LangChain。

学它，是为了建立 AI 应用的通用心智模型；选不选它，要回到需求本身。框架是工具，不是信仰。 一个在跑的专用系统，不会因为”更流行的框架出现了”就自动变差。

LLM API 统一管理实践：多模型路由的配置与踩坑

Wed, 05 Aug 2026 00:00:00 GMT

做 AI 应用，几乎都会走到这一步：代码里要用好几种模型——代码生成用强模型、日常对话用便宜模型、前端任务用快模型、嵌入用专门的向量模型，还来自不同厂商。

最省事的做法是搭一个统一网关，所有模型在一个面板里管理，代码只认网关的标准接口。

统一网关解决了什么#

一个 API 入口：代码里不用记每个厂商的地址和密钥
统一接口格式：OpenAI 兼容的接口，换模型不改代码
集中管理渠道：每个模型挂在哪个渠道、哪个厂商、额度还剩多少，一个面板看清
按用途分发：把”用哪个模型”从代码里抽出来，变成面板上的配置

一张模型用途表#

典型的多模型分工：

用途	模型	说明
代码生成	强模型	贵但准，关键任务用
日常对话	便宜模型	量大，用便宜快的
前端 / 轻任务	快模型	低延迟优先
嵌入	向量模型	专门做 embedding
视觉	多模态模型	处理图片

踩坑一：同一个模型挂了多个渠道#

这是最隐蔽的坑。一个模型（比如”强代码模型”）同时在两个渠道上挂载：

渠道 A：付费渠道，额度充足
渠道 B：免费渠道，额度已经耗尽

网关做路由时，可能在 A 和 B 之间随机/轮询。请求被路由到额度耗尽的渠道 B → 直接 403 拒绝。表现就是：同一个请求，有时能用，有时报错，完全随缘。

修复：同一个模型只挂一个渠道。如果多渠道确实需要，把额度耗尽的渠道上移除该模型，让路由只有一条可达路径。

经验法则：模型 × 渠道是多对多的关系，但一个模型的可用渠道必须随时可验证。别让”可能路由到坏渠道”的概率留在线上。

踩坑二：嵌入模型换了维度就数据不兼容#

嵌入（embedding）模型有一个隐藏属性：输出维度。不同的嵌入模型维度不同（比如 1024 维 vs 3072 维）。

如果你把应用里用的嵌入模型从 A 换成 B，而新旧模型维度不同：

旧的向量库数据（A 生成的 1024 维向量）和新请求（B 生成的 3072 维向量）无法互相比较
相似度检索结果全乱

修复：切换嵌入模型必须清空旧向量库重新生成，或者做好版本隔离。维度不一致的数据，比没有数据更危险。

踩坑三：网关的安全#

统一网关是把所有模型密钥集中在一个入口，它也变成高价值攻击目标：

关闭自助注册：开源网关默认开放注册，曾有外部 IP 自助注册后白嫖额度。第一时间关掉注册开关
入口收敛：网关面板和管理端口不要直接暴露公网

四条经验#

一个模型只挂一个可用渠道，随时在面板确认渠道状态
切嵌入模型 = 清旧向量库，维度不同数据不兼容
统一网关的安全要当回事，关注册、收敛入口
网关的数据库和配置要备份，它是所有模型访问的单一故障点

结论#

多模型统一网关的价值：把”用哪个模型”变成一次配置，而不是一次改代码。

但统一也意味着集中——单点故障、安全暴露、路由错误都会放大。用它的收益，也要接受它的纪律：

路由要可验证，模型不跨坏渠道，嵌入版本要隔离，入口要收敛。

做到这四条，多模型路由就从”配置麻烦”变成”一次配置，长期稳定”。

AI 记忆系统的三次进化：从外挂检索到代理化生命周期

Wed, 05 Aug 2026 00:00:00 GMT

大模型的记忆方案五花八门：向量库、RAG、知识图谱、Wiki、会话记录…… 但把它们放到一条演进路径上，位置一目了然。

记忆系统沿”外部检索 → 内化记忆 → 复合生命周期”演进。

三个代际，三种核心问题。

第一代：RAG 时代——记忆的外挂化#

核心问题：模型无记忆，怎么外挂一个？

记忆完全放在外部索引里，每次提问时从向量库或关键词索引捞出片段，注入提示窗口。本质是”无状态、有索引”。

局限也很明显：

成本高：索引 500 页文档动辄几十到上百美元
延迟大：每次提问都要检索注入
对问法敏感：换一种问法就捞不到
被动：只在你问的时候才干活，没有理解

第一代的进步是”让模型能查到记忆”，但记忆和模型是两张皮。

第二代：结构化时代——LLM 主动维护#

核心问题：如何跨会话维持知识？

第一代的问题在于”现场检索”——提问时才开始理解。第二代把工作前置：让模型提前把记忆组织成结构，而不是临场捞。

代表方案分几类：

LLM 维护的 Wiki：模型增量维护一个 Markdown 知识库，无数据库、版本可控（Git）、人机共用
自动会话记录：每次对话自动记录，新会话开始时注入相关历史
代码知识图谱：跨项目语义关联，支持调用链和影响半径查询

这一代的价值是”记忆有了归属和结构”，但仍有局限：维护边界模糊、整理不自动化、搜索依赖文件系统而非语义。

第三代：代理化时代——记忆的生命周期#

核心问题：如何让记忆自我进化？

第三代让模型自己成为记忆的管理者：自主决定记什么、忘什么、何时回忆、如何进化（总结、合并、抽象）。记忆不再是”存了就忘不掉的档案”，而是一组可被压缩、重组、遗忘的活实体。

核心特征：

记忆有优先级和衰减曲线（更像人脑的长期记忆增强）
后台线程持续运作，主动扫描、修正、提炼
模型自驱动，不等人类提出正确的问题

这一代还在探索期，可控性与可靠性都未验证——让模型自主决定”忘什么”，边界在哪还没人答清楚。

三代之间不是替代，是叠加#

三阶段不是严格取代，存在重叠和过渡。现在最务实的组合是：

会话记忆（自动记录）负责”我说过什么”
结构化 Wiki（长期决策）负责”我为什么这么做”
知识图谱（语义关联）负责”代码之间什么关系”

三个各司其职，互相补位。等到代理化记忆成熟，它接管的是”整理和遗忘”这件现在最耗人的事。

为什么值得关注#

记忆系统解决的不是”检索快不快”，是知识能不能跨会话、跨项目积累。

一个好的记忆系统应该做到：修过一次的 bug 不再重踩，做过一次的架构决策下次不用重新推导。这比任何单点工具的升级都值钱。

模型的进化看能力，系统的进化看记忆。

方向清楚了，下一个问题是执行——代理化记忆的”遗忘策略”怎么设计，这会是未来几年最有意思的工程问题之一。

需求多维化拆分的防扩散设计原则

Wed, 05 Aug 2026 00:00:00 GMT

需求来了：“把’延期’从一类拆成三类（研发延期 / 测试延期 / 父任务延期）“。听起来就是加几个 if。但实际做下去，bug 一个接一个，过几天才陆续暴露。

这类 bug 的根因不在”代码写错”，而在改动的影响面没有被识别和控制。属于设计思路错误，不是编码错误。

为什么”1→N 拆分”是 bug 高发区#

典型模式：

旧需求定义了一个单维度概念（“延期” = 看子任务 deadline）
新需求把它拆成多维度（“延期” = 研发延期 / 测试延期 / 父任务延期三类）
拆分时没有重整架构，而是在每个消费点各自加分类判断
消费点散落在计算层、AI 层、导出层、前端 N 个页面
漏改 / 改错一处 → bug，且因边界场景才触发，往往上线几天后才被发现

同一个概念，N 个地方各写一遍分类逻辑，必然漂移。

五条防扩散设计原则#

#	原则	踩坑表现	正确做法
1	单一数据源	”X 怎么算”在 N 个函数各写一遍，必然漂移	抽一个函数，所有页面/导出/AI 都调它，禁止重复实现同一计算
2	展示层与计算层分离	把分类标签混进了核心计算，逻辑纠缠	核心值先算出来；分类标签在最后渲染时再贴，计算层不感知分类
3	大改动先列影响面清单	改完等用户报 bug，才知道哪个页面漏了	维度拆分前先 `grep` 所有读该概念的地方，列成清单逐个验证
4	口径变更要带边界用例	没有测试，靠人工点页面	为每个分类写边界用例，测试驱动
5	同语义双实现要自动对齐	两个函数各算一遍没断言 → 必然漂移	加测试断言”同一对象在不同页面的统计值相等”，用测试守住一致性

启动三问（下次遇到”1→N 分类”需求时必问）#

改之前先回答这三句，任何一句答不上来就先补设计、别急着写代码：

1. 计算层的单一数据源在哪？ 这个概念的核心计算，是不是只有一个函数在算？如果 N 个地方各算一遍，先收口。

2. 分类能不能只活在展示层？ 新增的维度能不能做成最后渲染时贴的标签，而不是侵入计算的 if？

3. 所有消费点是否都有测试覆盖？ grep 出来的每个消费点，有没有对应的用例守着？漏改了能不能被测试抓住？

一个讽刺的真实现场#

某系统”人数”这个统计被 3 处消费：顶部总览、部门卡、横向对比。某天领导要求”人数排除组长”——三处逐个改完。当天领导又改口”人数要含组长”（组长数据仍排除在工时/任务外，但人数含组长）——三处又得逐个改回。

如果当初抽了 group_member_count() 单一函数，这次翻转只改一个函数、所有页面自动同步。 朝令夕改在业务系统是常态，“一处改全同步”的价值正是在这种时候兑现。

什么时候必须建聚合函数层#

不是所有项目都要做。涉及上万条级数据库记录 + 偏仪表盘 / 多页面对账的网页才需要——同一个统计口径被多个页面 / 接口 / 导出 / AI 同时消费时，立项阶段就要建统一聚合函数层，别等 bug 出来再补。

分层规范：

1
数据源 DB → 统一聚合函数（一个概念一个函数）
2
         → 后端算好派生字段（禁止把原始复合结构抛给消费端各自解读）
3
         → API 契约（字段字典，前端只读渲染，不做 len() 推导）

加 跨页一致性断言测试 兜底：“同一对象在 A 页的统计 = B 页 = C 页”，后端改错立刻被抓，不用等用户报。

结论#

需求多维化本身没错，错的是用”加 if”的方式去做架构级的改动。下次遇到”把 X 拆成几类”的需求，先停一下，回答启动三问——任何一个答不上来，先补设计。

改动的影响面必须被显式识别，不能靠”改完看看”兜底。

nginx 子路径部署的隐形炸弹：绝对路径怎么把页面变白屏

Wed, 05 Aug 2026 00:00:00 GMT

一台服务器上跑多个应用，通常用 nginx 子路径区分：/app-a/、/app-b/、/app-c/。部署第三个应用时，页面全白——控制台里一堆静态资源 404，但浏览器不报错。

这种”页面白屏”是最难排查的一类，因为它是静默失败。

根因：绝对路径逃出子路径#

SPA 应用（React、Next.js、Vue）内部常用绝对路径引用资源：

静态资源：/_next/static/chunks/xxx.js
后端 API：/api/config
页面路由：/settings

应用部署在 /app-c/ 子路径下时，浏览器把这些绝对路径解析为：

1
http://host:port/_next/static/xxx.js     ← 没有前缀
2
http://host:port/api/config               ← 没有前缀

nginx 找不到对应的 location，请求落入 catch-all location /。如果 catch-all 恰好反代到另一个 SPA 应用，它会返回一个 200 的 HTML 壳（因为 SPA 对任意路径都返回首页）。浏览器拿到 HTML 但内容不是 JS 文件 → 白屏，且不报错。

为什么 200 比 404 更坑#

404 至少告诉你”路径不对”。这里的问题是：

请求 /api/config → 落 catch-all → 返回别的应用的 HTML → 200
前端以为成功，实际拿到的是垃圾 → 业务静默失败

200 但内容是错的，比 404 隐蔽十倍。 排查时不要只看状态码，要看返回的 Content-Type 和实际内容。

子路径部署必配的三类路径#

路径类型	例子	要不要配
页面路由	`/app-c/settings`	✅ proxy_pass 到前端端口
静态资源	`/_next/static/`	✅ 单独 location（SPA 框架的资源路径固定）
后端 API	`/app-c/api/`	✅ proxy_pass 到后端端口（不要 redirect，会丢请求体）

框架静态资源路径速查：

Next.js：/_next/static/ 必须单独配 location
Vite：/assets/ 通常相对路径，但要检查
Create React App：/static/ 同理

部署前 5 分钟检查，避免 1 小时返工#

Terminal window展开收起

1
# 1. 看 HTML 里引用了哪些路径
2
curl -s http://localhost:PORT/ | grep -oE '(src|href|action)="[^"]+"' | sort -u
3

4
# 2. 识别绝对路径（以 / 开头的）
5
#    /_next/... → 静态资源
6
#    /api/...   → API 调用
7
#    /xxx       → 页面路由
8

9
# 3. 每个绝对路径都要有 nginx location
10
#    静态资源 → proxy_pass 到前端端口
11
#    API 路径 → proxy_pass 到后端端口（保留请求体）
12
#    页面路径 → 带前缀反代
13

14
# 4. 一次性测试所有路径
15
curl -I http://domain:port/_next/static/chunks/xxx.js   # 静态资源
16
curl -X POST http://domain:port/api/config -d '{}'      # API（测请求体）

展开收起

一次惨痛的失败教训#

有一次部署因为没做上面的检查，一路边部署边修：页面白 → 配静态资源 → 链接 404 → 配页面路由 → API 失败 → 配 API → CORS 报错 → 加 CORS 头 → 前端硬编码 localhost → 改相对路径……

用户反复测试了 7 次，总共花了 1 小时 10 分钟，最终项目被放弃删除。本该 10 分钟搞定的事。

根因就是：没在部署前一次性检查所有绝对路径，而是让用户当测试员，一轮一轮发现问题。

正确流程：

1
读部署检查清单 → 部署前检查所有路径 → 本地测试所有路径 → 一次性配好 → 用户最终验证（1 次）

结论#

子路径部署的铁律：

部署前把 HTML 里所有绝对路径列出来，为每个配 nginx location
catch-all location / 是隐患，能改成导航页就改
用户只做最终验证，不做问题测试员
页面白屏先查是不是 200 但内容错误，别只盯 404

子路径部署的坑不在 nginx，在应用内部的绝对路径。先查路径，再查配置。

图片进管道，先分清楚：要"取字"还是"理解"

Wed, 05 Aug 2026 00:00:00 GMT

业务系统里经常有”处理一张图”的需求，最常见的选择错误是：把”提取文字”和”理解内容”混为一谈。

一个典型场景：用户上传了一张流程图图片，你的 AI 助手需要分析它。你让它”读一下这张图”——结果它返回的是图片里的内嵌引用，而不是图里的文字。因为它走错了工具。

两个能力，边界要划清#

处理图片有两类完全不同的能力：

OCR（光学字符识别）：把图里的文字提取出来。只取字，不理解意思。
Vision（多模态理解）：理解图片内容。能看图说话、描述画面、回答关于图的问题。

一个”提取文字”的问题，用理解模型去做，又贵又容易跑偏；一个”理解图意”的问题，用纯 OCR 去做，得到一堆字却回答不了问题。

边界划分表（铁律）#

需求	用什么
纯提取文字（发票、截图、扫描件）	OCR
理解图片内容再回答（“这图在讲什么”）	多模态 Vision
流程图 / 截图里的文字	OCR（开启”图片内文字”模式）
需要理解图意再回答	多模态 Vision

关键判断：你最终需要的是”一串文字”，还是”对图的理解”？要字 → OCR；要懂 → Vision。

一个真实的坑#

用户提交流程图图片，走 OCR 分析。结果 OCR 返回的是嵌入式图片引用而非流程图文字——数据到手却是错的。

原因：OCR 默认模式处理”图片里有图片”的场景，把内嵌图当成了引用，没把文字抽出来。切换模型版本并开启”图片内文字”选项后，才正确输出流程图文字。

这个坑的教训：工具选对只是第一步，同一类工具的配置细节也可能让它答非所问。验证时不要只看”返回了什么”，要确认返回的是你要的那一层内容。

文字模型永远别”猜图”#

还有一个更隐蔽的坑：没有视觉能力的纯文字模型，绝不能被要求”看一下这张图”。

文字模型处理图片，本质是在猜。对话上下文里有点线索它就能”脑补”出一段看似合理的描述——但那是编的。如果系统里必须有一个文字模型和图片打交道，正确的做法是：先用多模态模型把图片转成文字描述，再交给文字模型继续处理。取字走 OCR，理解走 Vision，文字模型只接文字。

结论#

图片处理的第一步不是写代码，是回答一个问题：这图要的是字，还是懂？

要字 → OCR（便宜、快、准）
要懂 → 多模态 Vision（能回答、能描述）
纯文字模型 → 永远不要让它直接碰图，先转文字再交接

把边界划清楚，处理图片的需求能少踩一半的坑。

个人服务器的日常运维清单：磁盘、内存、服务、安全

Wed, 05 Aug 2026 00:00:00 GMT

一台个人服务器，上面跑着几个业务服务和 Docker 容器。系统盘只有几十 G，某天构建一个东西把盘打满，所有服务一起卡死。运维的核心不是”出事才修”，是定期检查 + 预判红线。

日常检查四件套#

Terminal window

1
# 1. 磁盘空间（系统盘是红线，数据盘才是大仓库）
2
df -h /
3

4
# 2. 内存（历史上有过突发尖峰挂死）
5
free -h
6

7
# 3. 常驻服务健康
8
systemctl list-units --state=running | grep -E "nginx|sshd|docker"
9

10
# 4. Docker 容器
11
docker ps

三条用挂一次换来的教训#

教训一：系统盘有红线，大东西放数据盘。 系统盘空间有限（几十 G），任何大于几 G 的操作（构建镜像、装大数据集、日志堆积）都可能打满。大项目必须放到数据盘（几百 G）。构建大东西之前先 df -h，别赌。

教训二：重启验证。 改文件、改路径、迁移数据后，立刻 systemctl restart 验证一次。运行正常 ≠ 重启后正常——有些 bug 只在冷启动时暴露，长期运行的进程会把它藏起来。

教训三：uptime 会隐藏 bug。 一个服务跑了 200 天没出过事，不代表它”健康”，只代表”还没触发那个 bug”。定期滚动重启、定期做状态巡检，让隐藏问题提前暴露。

常驻服务清单（可审计）#

每个常驻服务都应该有：systemd 管理 + 开机自启 + 归属说明。

服务	类型	说明
网关入口	systemd	所有流量的入口
API 管理	Docker	LLM API 统一管理
容器运行时	systemd	容器基础设施（有独立纪律）
代理网关	systemd	网络代理

核心纪律：基础设施容器绝不能随意重启——重启容器运行时会杀掉所有容器，等于一次全站停机。要重启某个容器，用 docker restart <容器名>。

安全规则#

SSH 端口暴露公网：公网端口每天被大量扫描，靠强密码 + 云安全组兜底
关闭不必要的注册 / 开放：开源服务默认开着注册就有人来白嫖资源，第一时间关
本机不放多余的防火墙：云安全组管入口，本机别叠一堆规则增加复杂度
对外不裸露真实地址：前端 / 给外部看的链接不带服务器真实 IP

清理动作#

Terminal window

1
# Docker 无用资源
2
docker system prune -f
3

4
# 系统日志（保留 3 天）
5
journalctl --vacuum-time=3d
6

7
# 包管理器缓存
8
# （pip 等按实际清理）

日志和缓存是磁盘的隐形杀手，定期清理比扩容便宜得多。

结论#

个人服务器运维就三句话：

红线提前设，检查定期做，重启勤验证。

系统盘容量、内存尖峰、日志堆积都是”慢性病”，等它爆发那天就是全站卡死。每天花 30 秒跑一遍四件套，比出事修一晚上划算。

AI 技能生态治理：做减法比做加法难

Wed, 05 Aug 2026 00:00:00 GMT

用过 AI Agent 的人都会经历一个阶段：疯狂安装 skill 和插件。社区推荐帖里全是”必装""神器”，装上就觉得自己强了。

然后发现：skill 越来越多，但 AI 干活并没有变好，反而——选型变慢了、每次调用更费了、有些 skill 互相打架、有的装了根本没碰过。

技能生态的管理，做减法比做加法难。

五条治理原则#

1. 按需取用，禁止堆砌。 不因为”热门”就装。先问：这个技能解决什么具体问题？没有它我现在能不能完成？

2. 同类只留一个。 功能重叠的技能会互相调用、关系混乱，每次选型都是浪费。同类对比后只留最好用的一个，不共存。

3. 安装前安全扫描。 技能和 MCP server 权限很大（能碰文件、网络、Shell）。来源不明的，先扫一遍它的定义文件再决定装不装。

4. 先用现有工具，再补新技能。 遇到新需求，第一反应不是”装个新技能”，而是”现有能力里有没有能覆盖的”。搜索有搜索的、深度研究有深度研究的、办公有办公的——先翻自己兜里。

5. 定期审计。 每季度清点一次已装技能的使用频率，低使用率且可替代的，下架归档。

一次真实清理：5 个重叠技能#

有一次，我发现自己装了 5 个功能高度重叠的技能（并行 agent 分发、子代理驱动开发、写计划、追问、再一个追问），互相调用关系混乱，导致每次让 AI 干活时选型都纠结，token 白白浪费。

处理方式：

把 5 个重叠技能归档到备份目录
只保留功能最完整的一个同类技能
其他工作流能力用更轻量的方式替代

结果是：技能选择变清晰了，调用路径变明确了，AI 不再”不知道用哪个”。

一次反面教材：重型工具草率引入#

另一次，未经充分评估就装了一个”全量安装”的压缩/模型类工具。依赖链巨大（CUDA + 模型文件），国内下载极慢，最后整个安装卡死。

代价是一整套卸载：清依赖、清配置、清注册的钩子。教训很直接：

重型工具先看依赖体积和离线可用性
生产环境 / 主会话不要试验重型工具
评估不了就先不装，别”试试再说”

选型决策树#

1
需要新能力？
2
  ├─ 现有技能能覆盖？            → 直接用，不装
3
  ├─ 同类产品已存在？            → 对比后替换，不共存
4
  ├─ 来源可信？                → 先扫描再安装
5
  ├─ 依赖可接受？              → 小步试，能离线最好
6
  └─ 确认有效后沉淀取舍原因       → 下次不用重新纠结

结论#

技能生态治理的本质是对抗”囤积本能”。每一个技能都是你 Agent 的一项”可选项”，选项越多，决策成本越高。

装得快是本能，删得狠是能力。

定期给 Agent 的技能库做减法，和给代码仓库做重构一样，都是长期健康的一部分。

SMB 网络盘上的 Git 锁文件：一个网络文件系统引发的坑

Wed, 05 Aug 2026 00:00:00 GMT

把 Git 仓库放在网络盘上（比如用 Obsidian 管理一个远程服务器上的笔记库，本地通过 SMB 挂载），平时没事，某次网络抖动之后，Git 突然全部操作报错：

1
fatal: Unable to create '.git/index.lock': File exists.
2
fatal: cannot lock ref 'HEAD': Unable to create '.git/refs/heads/main.lock': File exists.

添加、提交、推送全挂了。这是 Git 的锁文件机制在网络文件系统上被”坑”了。

根因：网络文件系统不保证原子删除#

Git 的锁机制依赖文件系统的一个原子操作：创建锁文件用 O_CREAT | O_EXCL——“如果文件不存在就创建，存在就报错”，这个操作是原子的，用来防止两个进程同时写。

但在 SMB 网络文件系统上，这个保证不牢靠。网络抖动时：

Git 进程创建了锁文件（index.lock）
删除锁文件的操作因为 SMB 网络延迟 / 抖动失败
锁文件残留在 .git 目录里
下次任何 Git 操作看到锁文件存在 → 认为”有进程正在写” → 拒绝执行

网络断一下，锁就永远留下来了。

哪些锁文件会阻塞什么#

锁文件	阻塞的操作
`.git/index.lock`	任何改暂存区的操作（`add`、`commit`）
`.git/HEAD.lock`	改 HEAD（`commit`、`merge`、`rebase`）
`.git/refs/heads/*.lock`	更新分支引用（`commit`、`push`、`pull`）

立即修复：删掉残留锁文件#

在仓库根目录执行：

Terminal window

1
find .git -name "*.lock" -delete

Windows 命令提示符：

1
del /q .git\index.lock .git\HEAD.lock 2>nul
2
del /q .git\refs\heads\*.lock 2>nul

注意：删锁文件前确认没有 Git 进程在真正运行——如果有个卡死的 Git 进程握着锁，删了也会被重新创建。

预防：降低碰撞概率#

1. 降低自动提交频率。 如果用了”自动备份”类插件（定时自动 commit），把间隔调大到 10-30 分钟。自动提交越频繁，并发碰撞的概率越高。

2. 避免设置包装脚本。 某些工具支持配置自定义 Git 路径 / 包装脚本，但配置可能被迁移到工具内部存储里，之后即使从配置文件删掉也不生效——必须在工具设置界面里手动清空。

3. 考虑本地 + 远程双副本。 如果对可靠性要求高，把仓库放本地，通过同步工具推送到远程，而不是直接在网络盘上跑 Git。

一句话经验#

网络文件系统（SMB / NFS / 网盘）对 Git 的原子锁操作支持不稳定。仓库尽量放本地盘，放网络盘就要接受”网络抖动 = 锁残留”的风险，并准备好清理手段。

这不是 Git 的 bug，是”网络文件系统不保证本地盘语义”这个通用事实。凡是依赖原子操作的工具（数据库、Git、构建缓存），放在网络盘上都要多一份警惕。

一个人 + AI 的团队，开发测试体系怎么建

Wed, 05 Aug 2026 00:00:00 GMT

一个人 + AI 做业务系统，最大的风险不是写不出代码，是没人帮你发现”改坏了”。

传统团队里，改了代码有人 review、有人测、有人验收。一人团队里这些职责全没了，只能靠制度代替人——把”怎么证明改对了”写进流程，强制执行。

一、数据管道：先设计再编码#

任何新数据源接入，数据要经过 6 个阶段流动：

1
拉取 → 解析 → 清洗 → 计算 → 评分 → 渲染

铁律：不能在最后一个阶段（渲染）才发现第一个阶段（拉取）的问题。每一段出口放一个检查点（详见数据管道六阶段验证）。

二、API 契约先行#

前后端最容易扯皮的是”字段名对不上”。解法是契约先行：

设计阶段先写出请求/响应的 JSON 形状，前后端各自确认，再开始编码。

禁止”后端写完让前端适配”或”前端写完让后端照着返回”。契约文件就是你们的产品需求文档。

三、三层测试架构#

没有 QA，就把”测试职责”拆成三层，每层负责一类问题：

1
Layer 3：用户视角（浏览器自动化，走真实网关）
2
  ├─ 每页截图存档
3
  ├─ 验证渲染出来的值正确（不是"元素存在"）
4
  └─ 跨页面导航完整走通
5

6
Layer 2：全链路追踪（浏览器抓网络请求）
7
  ├─ 用户点击 → 前端 → HTTP → 网关 → 后端 → 数据库
8
  └─ 验证每一步的 URL、响应码、内容类型
9

10
Layer 1：后端单元 + 接口集成（自动化测试）
11
  ├─ 接口形状验证（响应里关键字段都在）
12
  ├─ 字段名一致性验证
13
  └─ 边界条件

三层缺一不可：Layer 1 证明”接口返回对”，Layer 2 证明”网关转发对”，Layer 3 证明”用户看得到对”。只测一层就宣布”修好了”，是”声称修复但用户看不到”的最常见来源。

四、修复验证清单（每次改 bug 必须过）#

修完任何一个 bug，逐项打勾：

Layer 1：接口返回正确数据？
Layer 2：网关代理正常？
Layer 3：用户能看到正确内容？
所有页面都验证（不只改的那一页）
所有角色/分组都验证（不只默认的那个）
每个按钮点击有效果
截图存档作为证据

重点看两条：

“所有 X”类验证：很多 bug 只修了”默认的那个”——默认页面修了，其他页面还坏；默认分组测了，其他分组没测。一次改动必须验证所有实例。
截图存档：没有证据的”应该好了”，等于没修。

五、bug 修复的层次思维#

业务系统的数据通常是分层的（全局 / 分组 / 个人）。修 bug 时：

1
发现 bug → 确认影响范围 → 检查所有层级 → 修复 → 验证所有层级

禁止：修完一个层级就声称”修好了”。全局改对了，分组和个人可能还是旧的。

六、部署链路检查#

从代码到线上，中间每一步都可能出错：

1
产出 → 语法检查 → 检查外部依赖 → 检查路径 → 对接数据 → 部署 → 走网关验证

具体的坑：脚本语法错误、引用了境外 CDN、用了绝对路径、字段名前后端不一致。每一项都有对应的自动化检查。

结论#

一人 + AI 团队的本质，是把团队的分工写成制度，用工具执行：

数据管道检查点 = 数据正确性的”代码审查”
API 契约 = 前后端的”需求文档”
三层测试 = 你的”测试同事”
修复验证清单 = 你的”验收人”

一个人做事，最怕的是”自己觉得没问题”。制度就是那个说”你不许觉得没问题”的人。

没有团队，就给自己造一个虚拟团队——分工、流程、验收标准一个不少。这正是 Agent 时代一个人能顶一个团队的关键。

SSH 频繁断连的系统化排查：先列排除清单，别重复试错

Wed, 05 Aug 2026 00:00:00 GMT

一个让人抓狂的场景：SSH 连上几分钟就断，天天断。网上搜一圈，答案五花八门——调 keepalive、换客户端、看带宽、查丢包……挨个试了一遍，全都没用。

问题不在这些解法，在于没有用系统化排除法，而是凭感觉乱试。

正确的打开方式：列排除清单#

先别动手改配置，把候选变量全列出来，然后逐项排除，每次只动一个变量。

第一轮：先排除”软件配置”层（改动成本低）#

候选	排除方法	结果
服务器资源	看内存 / CPU / 磁盘	❌ 正常
SSH 配置	服务端加存活探测（如 ClientAliveInterval）	❌ 仍断
客户端软件	换一个客户端（A 换成 B）	❌ 仍断
带宽限制	检查有没有流量整形 / 限速规则	❌ 移除后带宽恢复但连接仍断
丢包	ping 长期监控	❌ 0% 丢包、延迟正常

这一轮排除了五个常见嫌疑，说明问题不在服务器和软件配置。

第二轮：锁定”网络路径”层（剩下的候选）#

排除掉软件层之后，剩下的候选都指向网络路径的某个环节：

⚠️ 双网络环境（有线 + WiFi 同时开）导致路由切换
⚠️ 本地路由器 NAT 表空闲回收
⚠️ ISP 中间设备 TCP 空闲连接回收
⚠️ 网卡硬件 / 驱动问题

其中”双网络同时开”嫌疑最大——两个网卡并存时，系统可能在切换默认路由，SSH 长连接经不起切换。

验证方法同样是一变量一改：拔掉有线只用 WiFi 跑 25 分钟，连接稳定了；但这只是单次观察，还需要长周期确认。

三个排查纪律#

1. 每次只动一个变量。 同时改 keepalive + 换客户端 + 调带宽，断连了就不知道是谁的功劳。

2. 记录每次尝试的效果。 一张表格（日期 / 尝试 / 效果），几轮下来哪些排除过一目了然，避免重复试错。

3. 先排除便宜假设，再动贵的。 改配置、换客户端便宜，换网络环境、换硬件贵。先排便宜的。

一个更深的教训#

排查到最后，很多”SSH 断连”其实是网络空闲回收——运营商 / 路由器对长时间空闲的 TCP 连接做回收。这类问题的共性特征是：

不是”断”，是”一段时间不用就死”
高峰期活跃时反而不掉
客户端和服务端配置都”看起来没问题”

如果你遇到的是这个模式，方向就不是调 SSH 配置，而是看网络路径上谁在回收空闲连接。

结论#

SSH 断连这类”配置看着都对但就是不行”的问题，最大的敌人是病急乱投医。

先列排除清单，每次只动一个变量，记录效果，先便宜后贵。

系统化的排除，比灵机一动的十个”偏方”都有效。

天地图 API + Leaflet：一个通勤选房的轻量级实践

Wed, 05 Aug 2026 00:00:00 GMT

需求很实际：北京的一批保障房候选小区，怎么挑一个对两个人的工作地通勤都友好的？

方案：天地图 API 算通勤 + Leaflet 做地图可视化。全程预计算成静态 JSON，页面秒开、不暴露 API key。

架构：预计算，不实时调用#

1
候选小区列表 → 地理编码(地址→经纬度) → 到双方工作地的路径规划(公交/驾车)
2
            → 通勤时间打分 → 排序 → 静态 JSON(预计算) → Leaflet 渲染

关键设计：所有地图 API 调用在生成静态数据时一次性跑完，页面只读预计算的 JSON 渲染，不做实时 API 调用。

好处：

省调用量：几十个小区每个算 2 条路线，一次跑完
页面秒开：没有等待 API 的延迟
不暴露 key：key 只在生成脚本里，不进页面

天地图 API 三个接口#

天地图 = 国家地理信息公共服务平台（lbs.tianditu.gov.cn）。

1. 地理编码（地址 → 经纬度）

1
ds = json.dumps({"keyName": "北京市海淀区xxx"}, ensure_ascii=False)
2
url = "http://api.tianditu.gov.cn/geocoder?ds=" + urllib.parse.quote(ds) + "&tk=" + TK
3
# 返回 {"location": {"lon": 116.3, "lat": 39.9, ...}}

2. 公交路径规划（参数坑最多）

1
ps = json.dumps({
2
    "startposition": f"{slon},{slat}",
3
    "endposition": f"{elon},{elat}",
4
    "linetype": "1"   # 1=较快捷 / 2=少换乘 / 4=少步行 / 8=不坐地铁
5
}, ensure_ascii=False)
6
url = "http://api.tianditu.gov.cn/transit?type=busline&postStr=" + urllib.parse.quote(ps) + "&tk=" + TK
7
# 注意：字段是全小写 startposition/endposition/linetype，不是 start/end
8
# 总时长 = results[].lines[].segments[].segmentLine[0].segmentTime 累加

3. 驾车路径规划（字段名和公交不同，别混）

1
ps = json.dumps({"orig": f"{slon},{slat}", "dest": f"{elon},{elat}", "style": "0"}, ensure_ascii=False)
2
url = "http://api.tianditu.gov.cn/drive?type=drive&postStr=" + urllib.parse.quote(ps) + "&tk=" + TK
3
# 驾车用 orig/dest/style，公交用 startposition/endposition/linetype

三个实测的坑#

坑一：公交接口字段名全小写。 startposition/endposition/linetype，写成 start/end 直接报参数错误。每个接口的字段各不相同，别复用错。

坑二：服务端 key 浏览器直调会被 WAF 拒。 天地图检测到浏览器请求（UA 是浏览器 / 带 Referer）就拒绝；跨源还会被浏览器的跨域安全策略拦（ERR_BLOCKED_BY_ORB）。解法：key 只放后端 / 代理，服务端调完把结果给前端。

坑三：底图瓦片也要同源反代。 瓦片请求同样面临跨域问题，用 nginx 反代瓦片，伪装成非浏览器请求：

1
location ~ ^/tdt/vec/(\d+)/(\d+)/(\d+)\.png$ {
2
    set $tk "你的KEY";
3
    proxy_pass http://tile.your-domain.com/vec_w/wmts?SERVICE=WMTS&...&tk=$tk;
4
    proxy_set_header User-Agent "curl/7.68.0";
5
    proxy_set_header Referer "";
6
    proxy_set_header Origin "";
7
}
8
# 前端直接用 L.tileLayer('/tdt/vec/{z}/{x}/{y}.png')

批量调用要限速 + 重试#

几十个小区逐个算公交路线，批量调用必须限速 + 超时重试（本项目逐小区跑，超时重试 3 次 + 间隔）。别一把梭全发出去，会被限流。

可视化#

Leaflet 画地图，圆形标记按通勤排名分级着色，点击显示通勤分钟 / 月租。纯前端，无框架，一个 HTML 文件搞定。

结论#

这个项目最值得借鉴的不是地图本身，是”预计算”这个设计：

能提前算完的，就别让用户等；能在服务端算的，就别让浏览器碰。

用一次性的预计算脚本把 API 调用全部跑完、结果落成静态 JSON，页面只做渲染——省调用、省延迟、保安全。很多”地图类”需求都适用这个套路。

Windows 网络盘的"双幽灵"事故：换盘符不是容灾

Wed, 05 Aug 2026 00:00:00 GMT

Windows 上把远程目录映射成网络盘（SMB），某天盘突然”断开”了。常见的第一反应：换个盘符重新映射，或者加一个”备用盘符”做容灾。

这一步就是事故的开始。

现场：两个盘符，一个幽灵#

映射盘 N: 断开后，你加了 O: 做后备。结果 Explorer 里同时显示两个”断开的网络驱动器”，都访问不了。

逐层取证，发现一个矛盾：

net use 列表：空（系统认为没有映射）
注册表持久映射：不存在
但 Explorer 显示盘存在，底层设备表也显示盘符指向那个共享

系统”认为”盘不存在，但 Explorer 和底层设备都”显示”它存在。 这是 Windows SMB 重定向层的一个”幽灵”状态——介于存在和不存在之间的第三种状态。

更关键的是：换盘符根本解决不了。新加的 O: 也报”盘名已占用”，两个盘符共享同一条故障链路。

为什么之前的修复都没用#

尝试	修的层	实际故障层
清理残留隧道进程	隧道层	重定向层
调整 keepalive	隧道层	重定向层
换盘符做后备	盘符层	重定向层

前几轮在隧道 / 进程层打转，因为故障根本不在那一层。最危险的是”换盘符做后备”——它假设”换盘符 = 换故障域”，但两个盘符映射同一个共享，共享的是同一条 SMB 会话、同一个重定向状态。换盘符只是把同一个幽灵复制成第二个。

根因：盘符名不是独立故障域#

盘符名不是独立故障域。 N: 和 O: 映射同一个共享，共享 Windows SMB 重定向器的同一会话。把”换盘符”当成”容灾”，只会把同一个幽灵复制到第二个盘符。

一个映射盘的健康状态由多层决定：盘符（别名）、SMB 会话、网络重定向设备、系统记住的连接。盘符只是最外层的别名，它不代表任何一层故障隔离。

修复：单盘符 + 双层护栏#

修复方案的核心是承认盘符不提供容灾，然后用架构护栏让”再加一个盘符”这件事从物理上不可能：

单盘符状态机：只管理一个盘符，不创建任何备用。盘不可读但底层隧道健康时，判定为”重定向层问题”，不重启健康的底层进程。
启动期护栏：配置文件里如果出现第二个盘符，服务拒绝启动，并给出说明：“备用盘符不是独立故障域，会复现双幽灵。要在证明故障域独立后才能扩展。”
运行时护栏：每次挂载成功前，扫描所有盘符，发现多于一个盘符绑定同一个共享，立即报错，而不是继续在第二个幽灵上叠挂载。

护栏的意义：让错误假设在”发生前”就失败，而不是运行几天后才以幽灵的形式暴露。

四条可复用的经验#

1. 容灾设计必须先画故障域表。 “后备”只有在故障域独立时才成立。设计任何后备方案前，先回答：后备目标和主目标在哪些层是独立的？ 同服务器、同凭据、同会话——答不上来，就不是后备，是别名。

2. 权威状态源不止一个。 判断一个盘是否存在，不能只看 net use（系统会话层）。还要看设备表（底层设备层）和 Explorer（UI 层）。net use 看不到，不代表盘真的不存在。

3. “对象存在” ≠ “功能可用”。 映射条目存在 / 进程存活 / 配置存在，都不等于实际可达、可读、健康。任何状态判断都要验证最终的用户路径（真实读取、真实连接），而不是只看对象存在。

4. 错误码有歧义。 同一个错误码（比如”设备名已占用”）可能代表”真的被幽灵占用”，也可能代表”其实已经正常映射了”。不能凭一次错误码就下结论——先真实读取，不可读才重建，重建仍失败再判异常。

结论#

这个事故的根因不在代码细节，在设计阶段的一个错误假设：想当然地认为”换个名字就是新的路径”。

迁移不是搬代码，是保持旧系统所有可观察行为；容灾不是加别名，是先证明故障域独立。

当系统出现”越修越乱”的迹象时，停下来问一句：我是不是在同一个幽灵上复制副本？

写操作必须同步失效缓存：为什么"改了却没生效"

Wed, 05 Aug 2026 00:00:00 GMT

系统里有个”部门人数”统计，为了性能加了 60 秒内存缓存。某天做”离职”操作，人明明走了，用户刷新一看人数没变；过一会儿再看，人又”消失”了。同一天里同一个数字两次不一致。

这不是性能问题，是架构问题：给接口加缓存之后，缓存就变成了一条必须维护的消费端。

问题长什么样#

典型场景：

一个读接口被频繁访问，于是加了缓存（key 按查询参数，TTL 60 秒）
一系列写操作会改变这个接口的底层数据：新增、删除、批量导入、重新计算
写操作成功了，但没清缓存 → 读接口继续吐旧数据
直到 TTL 过期或 key 变化，用户才看到新数据

用户视角就是一句”改了为什么还没好”。等 TTL 过期？60 秒都等不起，更别说用户会手动刷新触发各种不可预期的顺序。

两个同类 bug#

案例一：离职/入职没清缓存。 “部门人数”缓存 key 只含时间段参数，但”有没有人离职”跟时间段无关——单靠换 key 根本挡不住。离职接口成功返回，缓存还是旧的，人还在里面。直到用户切到别的时间段再切回来，缓存过期重查，人才消失。同一个操作，两次看到两个不同的结果。

案例二：改 AI 生成结论的提示词没清缓存。 把大模型结论的生成规则改了（比如禁用一个指标），服务重启了，但结论缓存表里的旧记录还在，页面读缓存直接显示，用户看到的还是改之前的结论。代码层完全正确——提示词对、数据对、单测过、服务重启了——但用户视角就是”反复改都没好”。

两个案例同一个根因：写操作（改数据 / 改口径）与缓存失效脱钩了。

五条设计原则#

#	原则	做法
1	写操作 = 缓存失效点	设计功能点时先问：这个数据被谁缓存？哪些写操作会改变它？列成”写操作 × 消费端缓存”清单，一个不漏
2	写操作统一走失效函数	项目里有缓存，就建一个 `invalidate_xxx_cache()`，所有写操作成功后可调用，不要散落一堆 `cache.clear()`
3	缓存 key 覆盖不了所有维度	key 只能按查询参数区分，但影响数据的维度（新增 / 删除 / 重算）往往跟查询参数无关——必须显式失效
4	TTL 只是兜底，不是方案	永远不要说”等过期”。用户的预期是”改了马上看到”
5	影响面清单把缓存算进去	大改动列影响面时，缓存消费端要进清单，详见需求拆分防扩散

上线前的触发三问#

任何写操作上线前，先回答：

1. 这个写操作改了哪些数据？（新增？删除？修改属性？重算结论？）

2. 哪些接口 / 页面缓存了这些数据？（内存缓存？持久化缓存表？TTL 多久？）

3. 写操作成功后缓存失效了吗？（有失效函数吗？没有就补上。）

结论#

“改了没生效”这一类 bug 的共同点，是改了源头 ≠ 改了运行时 ≠ 改了展示链路的旧状态。代码正确只是第一步，展示端的历史缓存不清，用户看到的永远是新代码之前的旧世界。

写操作与缓存失效必须同步，TTL 永远只是兜底。