在Nicholas Carlini的笔记本电脑上，一段Bash脚本在后台循环运行。它运行的逻辑很简单：逐个打开内核源码文件，把代码喂给Claude Opus 4.6，让AI假装自己在打CTF夺旗赛，找出里面能被攻破、利用的漏洞。跑完一个文件，自动切到下一个，一直循环。Carlini并没有盯着它跑，这类脚本他已经跑了好几个月。但他得到的所有回应，不过是一片噪音。

但紧接着，一条结果突然弹了出来……瞬间让他停下了手里的打字动作。

该模型在Linux的网络文件共享代码中发现了一个漏洞。这段代码同样广泛运行于很多公司的文件服务器、医院的存储设备、学校的共享驱动器，以及AWS、谷歌云、Azure等平台的大量文件共享后端中。利用这个漏洞，一个刚入职第一天的实习生，只要连上办公室的访客Wi-Fi，就可以运行一段简短的脚本，从而完全控制文件服务器。所谓“控制”指的是：读取HR团队的薪资表、删除payroll归档、复制CEO的邮件备份、安装一个能扛过三次重启的持久后门。无需管理员密码，无需窃取任何凭据，也无需串联第二个漏洞。从2003年3月到2026年4月期间出货的每一台基于Linux的文件服务器，都存在这个漏洞。

Carlini查阅了内核提交记录，这个漏洞早在2003年3月就被引入内核代码中。也就是说，它甚至比Git出现得还早（Git于2005年4月才正式推出）。过去二十年间上市的所有Linux架构存储设备，无一例外都带有这个漏洞。他盯着屏幕静坐良久。后来，在人工智能安全大会上，他面向听众坦言：“我这辈子从没找到过这种级别的漏洞，这件事非常、非常、非常难做到。”

我从2004年起就一直在交付部署Linux系统，覆盖电信、数字医疗、深度科技影像等领域。我曾无数次在深夜的生产环境的文件系统上紧急执行xfs_repair修复命令，次数多到数不清，也经历过NFS服务突然卡死失联，直接导致整个团队一整天的工作全部停滞。

Carlini写的这段脚本谈不上多高明，但胜在成本极低。

只需单人运维、一周的算力消耗，背后是简单直白的成本逻辑……

三周后，Linus Torvalds正式标注发布Linux 7.0版本。他在发布邮件里轻描淡写地写道：“我认为，未来很长一段时间里，各类AI工具会持续帮我们挖出各种边界漏洞，这恐怕会成为短期内的新常态。”

2026年4月12日周日，Linux 7.0正式发布。

本文就来讲述，伴随这次版本更新一同到来的重大变化，以及背后的推手。

而这一版本，也正式宣告：行业新常态已然降临。

Greg Kroah-Hartman 负责维护Linux稳定版内核，是Carlini的核心副手。同时他还掌管内核安全问题专属收件邮箱，这也意味着多年以来，他每天打开邮箱，看到的基本都是垃圾内容。他将这类东西称作AI劣质垃圾产出：全是AI自动生成的报告，没有真实漏洞，文件不对、代码行不对，通篇错漏百出。他甚至专门建了一个文件夹，用来收纳这类无效的报告。

二月底的一天早上，这个文件夹再也没有新增垃圾内容。取而代之的，是一条条实打实的漏洞上报：精准标注代码行号、可稳定复现的利用脚本、经得起推敲的根因分析。今年三月，他在接受《The Register》采访时表示：“就在几个月前，我们每天收到的全是所谓的AI垃圾产出。但一个月前风向突变，整个行业彻底变了。现在送来的，全是货真价实的有效漏洞报告。”他还坦言：“我们毫无头绪，没人能解释背后的原因。”要么是一众前沿大模型在同一个月内，C语言代码解析能力集体大幅跃升；要么是大批安全研究员不约而同在同一周集中用大模型扫描老旧历史代码；又或者，两种情况同时发生。

Greg恪守内核维护者的本职工作，负责编写各类文档。在Linux 7.0第七个候选版本发布前夕，他提交了一条合并请求，更新了security-bugs.rst文档。该文件用于规范安全研究员提交漏洞的标准流程。这次更新专门针对大语言模型优化说明内容：明确划分各子系统对应的维护负责人、规范合格漏洞报告的撰写格式，同时列明自动化扫描流程必须包含的关键字段。现在，Linux内核的安全漏洞接收通道正式改为双适配模式：人工研究员与AI智能代理，将通过同一套流程统一提交漏洞。

另有一支团队长期监控内核代码提交记录，而非通用漏洞披露编号（CVE）。 Google的Roman Gushchin推出了一款名为Sashiko的检测工具，采用Rust语言开发，名称源自日本传统刺绣工艺。（这其中藏着一个小巧的伏笔，后文便会揭晓。）Sashiko会逐行读取发布在Linux内核邮件列表（LKML）上的所有补丁。研究人员抽取一千条真实开发环境下的补丁作为基准测试集，该工具成功检出了后续被确认漏洞中的53%。而这部分被测出的问题，全部都被人工审核人员遗漏。被问及该检测指标时，Gushchin表示：“有人可能觉得53%的检出率并不算亮眼。但要清楚一点：这些安全问题，当初没有任何一位人工审核人员发现。”

就在当前的Linux内核邮件列表归档中，藏着这么一个补丁：如果放任上线，下周二半夜，值班的SRE必然会被紧急叫醒处理故障。而这款Sashiko工具，早在上个月就已经将该问题标记告警。你永远不会知道，究竟是哪一段代码、哪一个补丁化解了这场潜在事故。这，就是行业新常态下，从业者最真实的切身感受。

Linux 7.0正式发布当天，Miguel Ojeda提交了他为该版本适配的最后一则Linux内核Rust支持合并请求，即 7.0。

“实验已经完成，Rust从此常驻内核。”

四年前，这句话可能招来一片指责。2022年末，Rust首次随Linux 6.1版本合入内核，当时只是一项可选启用的实验性特性。即便遭到多位内核维护者反对，该功能仍被合并。他们认为Rust只是一时风潮、形式化工程，甚至弊大于利。历经六个版本迭代后，Rust正式摘掉实验标签，成为内核中与C语言平起平坐的一等开发语言。各个子系统仍可自主决定是否接纳Rust代码，内核主体绝大部分依旧由C语言编写，但这场持续多年的技术争论，已然尘埃落定。Nova驱动（NVIDIA面向图灵架构的开源驱动，用于替代nouveau，适配目前工作站主流的GeForce RTX 20系列与GTX 1600 系列显卡）已在Linux 7.0中内置Rust实现。过去两年由Danilo Krummrich持续开发的Rust版DRM直接渲染管理框架，也正式并入内核主线。

但那些耗费四年时间推动Rust落地内核的人，并未身处这场成果揭晓的现场。

Wedson Almeida Filho曾主导微软的Linux内核Rust适配工作。过去四年里，他不断和保守的C语言模块维护者拉锯，对方坚决抵制Rust代码接入自家子系统。最终，他发布离职说明，直言缘由是“非技术层面的无端拉扯”，选择抽身离开。而与他一同牵头该项目的Alex Gaynor，也在Rust正式转正的同一周宣布卸任。这份胜利的荣光，与他们毫无干系。

另一边，Christoph Hellwig执掌内核DMA（直接内存访问）子系统长达二十年。该模块属于底层核心基础组件，绝大多数工程师日常无需接触，甚至不清楚归属维护者。一年前，他曾在公开邮件中直言，Rust与C语言混合开发是“难以根除的顽疾”。当内核维护团队达成共识，允许Rust驱动通过轻量化抽象层调用C语言DMA接口时，Hellwig选择直接卸任，该模块后续由Marek Szyprowski接手维护。

二十年来，他一直维护着核心底层代码，支撑内核所有驱动与硬件的交互通信。这不仅是职业生涯的一段履历，而是他毕生的事业。最后的争论，仅仅围绕一件小事：新语言能否通过一层封装接口，调用他编写的底层函数。他输掉了这场博弈，随后选择转身离场。

Safe Rust从代码结构层面直接杜绝了一整类经典漏洞：缓冲区溢出、释放后复用、空指针解引用。Carlini脚本挖出的这处长达23年的NFSv4溢出漏洞，从语言机制设计上，绝无可能出现在Safe Rust代码中。如今内核正式纳入全新开发语言，从根源上杜绝了本文开篇这类高危漏洞的产生。可为之奔走争取的人已然离场，激烈反对的人也选择离去，但Linux 7.0依旧如期发布，尘埃落定。

图片来源：作者，跨子系统的Linux 7.0版本组合

全新的配套规范随版本一同正式落地。今后，所有借助AI辅助编写的补丁，必须添加Assisted-by: 尾注，标明所用大模型与工具。AI代理不得签署 Signed-off-by 合规签名，因为开发者原产地声明具备法律效力，仅可由自然人出具。漏洞责任最终仍由提交代码的开发者全权承担。这项规则的诞生，并非社区冷静研讨、从容制定的结果。起因是NVIDIA的工程师Sasha Levin向内核6.15提交了一则补丁：全篇代码连同更新日志，几乎完全由大模型生成，且全程未提前告知任何人。这段代码能够正常编译，顺利通过初步审核，却暗藏性能退化问题。该缺陷一路流入稳定版内核，直接毁掉了不少人的一周工作。此事引发强烈舆论反弹。向来不愿为流程规范开会扯皮的Linus，直接终结了这场争论：他表示，一刀切禁止AI编码只是毫无意义的姿态作秀。AI只是一种开发工具，责任必须绑定到人，相关规范即刻落地生效。

红帽，这家商业化Linux发行厂商的从业资历，远比本文中多数开发者的编程生涯还要久远，他们提出了一个至今尚无答案的严峻问题。基于GPL开源代码训练的大模型，会从根源上导致代码提交的版权溯源难以保障。AI生成代码的版权究竟归属何方？这个难题并未随着Linux 7.0的发布得到解决，且会长期持续存在。

数据中心内的RAID磁盘阵列控制器，会在夜间执行磁盘巡检（SCRUB）周期，对阵列内所有磁盘开展常规完整性校验。过程中，文件系统的记账元数据里，恰好有一个比特位发生翻转。在内核最不容出错的位置，一个0被意外改成了1。如果你的环境使用XFS文件系统（RHEL、Rocky Linux、AlmaLinux、Oracle Linux 的默认文件系统），以往只会通过两种方式察觉故障：要么业务服务异常报错，要么次日一早卸载磁盘，从xfs_repair修复日志中发现问题。无论哪种，都会迎来糟糕透顶的周一。

2026年1月15日，Darrick J. Wong提交了第六版XFS自愈补丁集，该功能现已随Linux 7.0正式上线。在此版本之前，如果一家中型公司的文件服务器在周末丢失了单字节的文件系统元数据，值班工程师就会接到告警，并赶往机房停机维护，执行xfs_repair修复后再重新上线，全程赶在周一上班前完成。情况好的话，也要停机四小时；一旦修复耗时超出维护窗口，周一例会的开场，便只能以故障致歉收场。Linux7.0彻底终结了这种周末紧急抢修的旧模式。全新后台守护进程xfs_healer可自动识别此类损坏，在业务不间断提供文件服务的同时完成在线修复，并留存系统日志。终端用户毫无感知，告警设备保持静默，周一的工作也能照常开启。

再放眼整个云计算领域，影响将成倍放大。亚马逊云、谷歌云、微软Azure上的RHEL系列镜像，均默认采用XFS文件系统。全球绝大多数企业级Linux服务器集群，自此不再频发这类突发故障告警，运行愈发平稳安静。

在法兰克福某家银行，一台SPARC M7服务器正在处理一笔交易结算。其上运行的软件开发于1998年，且与甲骨文签订的合约明确要求，整套环境禁止迁移改造。就在4月12日，这台老旧服务器依旧迎来了内核补丁更新。SPARC（Sun Microsystems，20 世纪 90 年代初的版本），迎来了fork/clone漏洞修复、全新clone3系统调用支持与接口优化整理。早已淡出主流的DEC Alpha架构，如今大多留存于科研实验室，运行着我高中时代编写的仿真程序，本次也修复了内存整理过程中引发的用户态内存损坏问题。Motorola 68000架构同样获得了补丁维护。使用这些老旧平台的人，不会为此撰写技术博客大肆宣扬。他们只会默默升级内核，在心底悄然感受到：自己小众老旧的业务环境，依然有被关注到。

4月7日，内核开发主线分支正式敲定，将在Linux 7.1中移除对Intel i486的支持。i486处理器于1989年问世。32位x86架构如今仍被广泛使用，而舍弃i486兼容适配后，现有所有x86设备的运行效率都将得到提升。SPARC架构得以保留，是因为仍有专人持续维护、愿意为之负责；而486架构惨遭淘汰，原因也恰恰相同：早已无人关注、无人维护。

图片来源：作者，Linux 7.0可衡量的性能改进

AMD最新一代服务器芯片EPYC 9005，也是当下各大云厂商正在大批量上架部署的主力机型，在Linux 7.0优化后的KVM虚拟化架构下，加密虚拟机的运行效率大幅提升。加密虚拟机是银行、医疗机构愿意额外付费采购的核心能力，可杜绝云厂商私自读取内部敏感数据。基于新一代EPYC 9005“Turin”平台的实测数据显示：在高内存负载场景下，SEV-SNP机密虚拟化的性能损耗已压缩至个位数至百分之十几的低位。AMD正在推进的RMPOPT优化已纳入后续内核迭代计划，旨在进一步抹平剩余性能开销。对云厂商而言，这组性能差距，直接决定机密计算服务能否盈利，而非只停留在PPT宣传层面。对入驻的银行客户来说，这意味着可以安心选购付费隐私云服务，不必无奈退守自建机房，走回运维老路。

ML-DSA（基于模块格的数字签名算法，美国国家标准与技术研究院认证的后量子密码标准）正式并入内核，提供44、65、87三档安全等级。Linux设备每次加载驱动时，都会校验加密签名，确保驱动来自合法授权方。目前通用的签名算法，一旦遭遇规模化量子计算机即可被破解。这类设备当下虽未问世，但情报敌对势力早已开始全网采集留存各类加密签名，提前布局、长线蛰伏。等2035年量子计算机落地，攻击者便可伪造合法内核更新，定向推送至目标终端，将设备改造成长期监听节点。2026年落地的ML-DSA，趁漏洞窗口期尚短，提前彻底堵死这条攻击路径。同一版本中，面对未来量子设备会在数分钟内被暴力破解的SHA-1模块签名机制，也已正式移除。

谷歌向Linux 7.0的HID修复合并请求提交补丁，在输入子系统中新增三组按键键码，同时牵头制定了配套的USB-IF HID 行业规范 HUTRR119。

• KEY_ACTION_ON_SELECTION（0x254）：针对选中内容触发AI操作，包括解读、总结、检索。

• KEY_CONTEXTUAL_INSERT（0x255）：唤起悬浮窗口，在当前输入框内生成或调取文字内容。

• KEY_CONTEXTUAL_QUERY（0x256）：基于选中内容，推送关联智能建议。

不同于微软2024年推出的Copilot按键（按键改造旧式功能键、强行绑定自家专属助手），这三组全新键码属于标准原生HID定义，不绑定任何AI服务商。

笔记本厂商可自由将其映射至Claude、Gemini、本地 llama.cpp模型，或是自定义Shell脚本。未来的ThinkPad、戴尔 XPS、Framework等机型，都将标配这类通用AI功能按键。

图片来源：作者，人工智能在整个Linux 7.0发布生命周期中的参与

仅此一个版本迭代，四大变革悄然落地，全都沉淀在同一份代码提交记录中。

• AI现已参与内核邮件列表的补丁审核，问题检出率达53%；

• AI挖出了隐匿长达23年的内核底层漏洞；

• 依照全新规范与标签机制，AI 正式被列为署名贡献者；

• 系统输入子系统新增三颗实体键盘按键，专门用于唤起各类AI助手。

就在这短短一周之内，既有为AI而生的全新底层架构，也有借AI加固升级的安全体系，新旧变革，同步发生。

如果仅凭一人、一段Bash脚本，就能在一个周末内挖出5个内核漏洞，那么谷歌内部团队究竟掌握了多少？你的硬件厂商自研团队又发现了多少？又有多少漏洞，早已被国家级势力发现、封存，秘而不宣？

Linus将这种现状称作新常态。OpenSSL、GCC、Python、Postgres、Chromium，还有代码仓库里那些开发者离职后十年无人维护的微服务，皆是如此。各处代码中，随处可见一类隐患：112字节的缓冲区，却要写入1056字节的数据，这类细节以前无人留意。它们静静潜伏，等待某段尚未被编写出来的脚本，将漏洞引爆。

如果你在用NFS服务，想必已经修复了CVE-2026–31402漏洞。如果使用基于RHEL的衍生系统并搭载XFS文件系统，建议先在测试环境试运行自愈守护进程。如果你在KVM虚拟化中部署AMD EPYC 9005处理器并开启SEV‑SNP 机密计算，在向业务方承诺节约成本之前，务必针对自身业务负载完成基准性能测试。但凡你环境中还跑着2010年前开发、至今仍在线上运行的老旧系统，这周就该咨询安全负责人：一旦有人用 Claude Code 扫描这批代码，该如何应对。“我们有代码审核流程” 早已不再是有效说辞。要知道，当年那处内核漏洞，靠人工代码审查足足遗漏了二十三年。

当一段Bash脚本就能让你的代码库爆出高危CVE漏洞，那事后的复盘报告又该如何落笔？

作者丨Can Artuc      编译丨dbaplus社群

来源丨网址：https://canartuc.medium.com/linux-7-0-one-bash-script-one-weekend-23-years-of-kernel-bugs-8aab1c9671e1

dbaplus社群欢迎广大技术人员投稿，投稿邮箱：editor@dbaplus.cn

这一年“RAG 已死”的说法甚嚣尘上，比如《长上下文窗口、Agent 崛起，RAG 已死？》、《The RAG Obituary: Killed by Agents》。而像 Claude Code、Codex 这类新一代 Agent CLI 也纷纷放弃了 embedding，官方直接承认：不建索引、不用向量库，靠 LLM 驱动 Grep 就够用。RAG 真的不适合现在的 Agent 了吗？围绕这个问题，我们展开了深入调研，同时对Claude Code 等前沿解决方案的源码进行了拆解，最终形成本文力求回答 RAG 在 Agent 时代是否还有一席之地这一核心关切点。

Claude Code 的创建者 Boris Cherny 在多个公开场合提到过这个让很多人意外的事实：Claude Code 不用 RAG，不用 embedding，不建索引。 核心搜索靠 LLM 驱动 Grep （Grep 是 Unix 下的文本搜索工具，给一个正则表达式，它就在文件里逐行找匹配）。

在 X/Twitter 上，他说得很直接：

在 Pragmatic Engineer 的采访中更进一步：

Anthropic 官方的 Context Engineering 博客也确认了这一架构：Claude Code 使用 Grep 和 Glob 将代码动态加载到 context 中。这个选择不是拍脑袋做的，Boris 在 Pragmatic Engineer 的采访 中提到，他在 Meta 时观察到 Instagram 工程师在 IDE 的 click-to-definition 功能崩溃后，所有人都回退到手动 Grep 搜代码。不过他也在 Latent Space 播客 中坦承，放弃 RAG 的决策部分基于直觉。尽管 Anthropic 说了不用 RAG，用 agentic search + Grep，但 Grep 具体怎么调用、LLM 怎么决定搜什么、工具调用循环长什么样，这些实现细节都没有公开。

2026 年 3 月，Claude Code CLI 的一份源码快照因泄露被公开。我去看了一下，发现确实如 Boris 所说，源码中没有任何 embedding、vector、similarity search 相关的实现。但更有意思的是这套零索引内容搜索机制的具体实现方式。

这篇文章就是基于这份源码以及一些行业实践，从实现层面拆解 Claude Code 的代码搜索机制以及其背后的设计哲学。本文先拆解 Claude Code 如何驱动多轮 Grep 循环（第二章），再看暴力搜索为什么在本地项目上够快（第三章），最后和 Cursor 等行业方案对比，讨论 Grep 方案的真实成本与收益（第四章）。为了让整套机制不停留在抽象层面，我们用一个贯穿全文的例子来看。Claude Code 除了终端 CLI 模式外，还有网页版和桌面版，而这些模式下它通过一个叫 bridge 的远程控制系统运行，由服务端 session 执行实际工作。假设你在读这份源码时产生了一个好奇：当 LLM 调用 GrepTool 做搜索时，bridge 是怎么追踪和记录这次工具调用的？ 你让 Claude Code 帮你从源码中找答案，接下来会发生什么？

Claude Code 的代码搜索可以用一句话概括：LLM 自己决定搜什么、用什么工具搜、搜到后要不要继续搜，直到信息充分为止。 没有预设的搜索流程，没有固定的工具调用顺序，一切由 LLM 在运行时决定。这一章先讲搜索循环怎么运转、循环里有哪些工具可用，然后深入最核心的 GrepTool 看它怎么控制返回的信息量。最后用开篇提出的那个实战问题，完整走一遍多轮搜索的过程。

整套搜索机制的核心是一个循环：将用户输入和可用工具列表传给 LLM，LLM 返回文本或工具调用请求。如果是工具调用，执行工具后把结果追加到对话历史，然后带着更新后的完整历史再次调用 LLM。LLM 基于不断增长的上下文决定下一步做什么，直到它认为信息充分、直接生成文本回答而不再调用工具，循环自然结束。循环也有强制退出机制：达到最大轮次上限、超出预算限制、用户中断、或工具调用被权限拒绝。

这个循环对所有工具是平等的。LLM 可以在任何时候调用任何工具，甚至在一次响应中同时调多个。没有硬编码的“必须先搜再读”。与代码搜索相关的核心工具有四个：

此外还有 LSP（Language Server Protocol）工具，用 “go to definition”、“find references” 等语义精确的操作补充 Grep 的不足。但核心搜索架构建立在这四个工具之上。

其中 AgentTool 比较特殊：它不是直接搜索文件，而是启动一个独立的子 agent，让子 agent 在自己的 context window 里完成一整套搜索任务，最后只把结论返回给主对话。子 agent 有多种类型，与搜索最相关的是 Explore 类型：它只配备搜索和读取工具（Grep、Glob、Read），不能编辑文件、不能执行命令、不能嵌套启动新的 Agent，是一个纯只读的搜索专家。

子 agent 的核心价值是 context 隔离。它从零开始构建自己的对话历史，不继承主对话的消息，这意味着它搜索过程中产生的大量 grep 结果、代码片段都留在自己的 context 里，主对话只收到一段总结性的文本结论。对于需要大范围搜索的任务，如果在主对话里直接搜索，几轮 grep/read 下来 context 可能就被中间结果塞满了。因此交给子 agent 处理后，主对话的 context 只增加一条结论消息。

在一般实践中，LLM 最常用的模式是“先定位，再深入”：先用 Grep/Glob 找到相关文件，再用 Read 读具体内容。但 Grep 搜到文件后，是不是每次都要接一个 Read 才能用？不一定。关键在于 GrepTool 有三种输出模式，返回的信息量完全不同：

• files_with_matches 模式（默认）：只返回匹配的文件路径列表，不返回任何代码内容。比如搜 "class.*Transport" 会返回 cli/transports/WebSocketTransport.ts、cli/transports/SSETransport.ts 这样的路径。LLM 拿到的只有文件名，所以这种模式下通常需要接 Read 才能看到具体代码。这也是为什么默认模式设计成只返回文件名，即故意控制信息量，避免一次 Grep 就把大量代码涌入 context window，让 LLM 自己判断哪些文件值得深入读取。另外还有一个保护机制：head_limit 默认 250，即使搜到 10,000 条匹配也只返回前 250 条，防止搜索结果淹没 context。

• content 模式：返回匹配行及其上下文代码。比如 Grep({pattern: "TOOL_VERBS", output_mode: "content", "-C": 5}) 会直接返回匹配行前后各 5 行的代码片段。对于很多场景，例如确认一个常量的值、看一个函数签名、检查某个 import 是否存在，这些片段就够了，不需要再 Read 整个文件。

• count 模式：只返回每个文件的匹配数量，用于快速评估搜索词在项目中的分布密度，不返回具体内容。

所以实际的工具组合方式是灵活的：Grep（默认模式）→ Read 是最常见的路径，但 Grep（content 模式）可以独立使用，LLM 也可以直接调 Read（如果已经知道文件路径），或者一次同时发起多个 Grep 并行搜索。这种灵活性是有意为之。其思想是用软引导代替硬约束：system prompt 建议 LLM 先 Grep 定位再 Read 深入，GrepTool 的默认输出模式也自然引导这个流程，但不在代码里堵死其他路径，让 LLM 根据具体情况做判断。

回到开篇的例子。当然这个问题是我刻意挑的，因为答案分散在多个文件中，需要多轮搜索才能拼出全貌，目的是展示多轮搜索的完整过程。我把这个问题抛给了 Claude Code，以下是真实的搜索过程。

第 1 轮：广撒网。 LLM 把问题中的 GrepTool 和 追踪 翻译成 grep 关键词，用默认的 files_with_matches 模式扫一遍：

Grep({pattern: "GrepTool|tool.*track|tool.*activity", glob: "*.ts"})→ 返回 4 个文件：structuredIO.ts, sessionRunner.ts, bridgeUI.ts, bridgeStatusUtil.ts

4 个文件，其中 3 个在 bridge/ 目录下，1 个在 cli/ 下。问题问的是 bridge 系统，LLM 关注 bridge/ 下的文件。sessionRunner.ts（session + runner = 会话执行器）最可能包含工具执行追踪逻辑。

第 2 轮：看上下文。Grep 切换到 content 模式，看 GrepTool 在 sessionRunner.ts 中的上下文：

Grep({pattern: "GrepTool|tool.*activity", path: "bridge/sessionRunner.ts", output_mode: "content", "-C": 5})

返回的代码片段中能看到一张映射表的尾部，显示 GrepTool: 'Searching'、BashTool: 'Running'，但上文被截断了。LLM 判断需要 Read 整段代码才能看全。

第 3 轮：调用Read。 使用 Read 打开 sessionRunner.ts 的完整上下文，一次看到了三个关键结构：

第一个是工具名→动词映射表（TOOL_VERBS，共 18 个条目，这里列出与搜索相关的部分）。每个搜索工具（Grep、Glob）在这里都被映射成 Searching。注意有两套命名，比如内部名 Grep 和外部 SDK 名 GrepTool。这表明工具名是硬编码在映射表里的，不是动态注册的。

Grep: 'Searching',   GrepTool: 'Searching',
Glob: 'Searching',   GlobTool: 'Searching',
Read: 'Reading',      FileReadTool: 'Reading',
Edit: 'Editing',      FileEditTool: 'Editing',
Bash: 'Running',      BashTool: 'Running',
// 还有 Write, MultiEdit, WebFetch, WebSearch, Task, NotebookEditTool, LSP 等

第二个是摘要生成函数，它把动词和搜索目标拼接在一起：动词来自上面的映射表，目标则从工具调用的输入中提取（优先取 file_path，其次 pattern、command、url 等）。所以一次 GrepTool({pattern: "reconnect|backoff"}) 调用的摘要就是 Searching reconnect|backoff。

第三个是活动解析器：它从 session 的 stdout 中逐行解析 JSON，当发现工具调用事件时，调用上面的摘要函数生成摘要，打包成一条活动事件。

到这里已经知道了怎么追踪和怎么记录，但活动事件生成之后去了哪里？

第 4 轮：追踪使用方。 Grep 搜 SessionActivity 被谁引用，一次追出整条链：

Grep({pattern: "SessionActivity|currentActivity", path: "bridge/", output_mode: "content", "-C": 2})

三个文件同时浮出水面：

• bridge/types.ts ：活动事件的类型定义，只有 3 个字段（类型、摘要、时间戳）。每个 session 维护一个环形缓冲区和一个当前活动指针。

• bridge/bridgeMain.ts ：一个定时器周期性轮询每个 session 的当前活动，并维护最近 5 次工具调用的轨迹，例如 Searching → Reading → Searching → Editing 这样的历史。

• bridge/bridgeUI.ts ：收到工具启动事件后，缓存摘要文字并渲染到 bridge 的状态面板。

这样就拼出了完整的追踪链：session 进程输出工具调用的 JSON → 活动解析器提取并生成摘要 → bridge 主进程定时轮询获取最新活动 → UI 模块渲染到状态面板。

上一章展示了 Claude Code 如何用多轮 Grep 搜索代码。但这引出一个显而易见的问题：每轮 Grep 都是在项目文件中暴力扫描。一个大一点的项目可能有几万个文件，暴力扫描不会慢吗？

Grep 在今天是一个大家族。诞生于 1973 年的 GNU grep 是最经典的版本，逐文件递归、不认识 .gitignore、默认单线程。而 Claude Code 的 GrepTool 底层调的并不是它，而是 ripgrep，在2016 年由 Andrew Gallant 用 Rust 重写的现代实现，默认遵守 .gitignore、自动跳过二进制文件、多线程并行、用 SIMD 加速匹配，为在大型代码库里快速搜索这个场景从头设计。

源码佐证：tools/GrepTool/GrepTool.ts:21 里 import { ripGrep } from '../../utils/ripgrep.js' ，所以真正干活的是 ripgrep，不是系统自带的 grep。

这一章解释为什么 ripgrep 的暴力扫描在开发者本地项目上足够快：五层过滤怎么把搜索范围从几万文件缩小到几十个，SIMD 和 Boyer-Moore 怎么加速文件内匹配，以及代码搜索和向量检索在数据规模上的本质差异。3.4 节还有一组用 Claude Code 自己的源码做的 ripgrep vs GNU grep 实测数据，可以直接看到差距。

ripgrep 不是对每个文件都做正则匹配。它在真正搜索内容之前，有多层过滤逐步缩小范围：

层级1: 目录级剪枝（.gitignore）  — 跳过整棵目录子树，连目录内容都不读取
层级2: 路径范围限制（path 参数）  — 限定目录遍历的起点
层级3: 文件类型过滤（glob 参数）  — 遍历目录但跳过不匹配文件
层级4: 二进制文件检测            — 读文件头几个字节，发现是二进制就跳过
层级5: 内容搜索（正则匹配）      — 最后才对通过所有过滤的文件做匹配

各层过滤是乘法叠加的。回到我们贯穿全文的例子，第 4 轮搜索 Grep({pattern: "SessionActivity|currentActivity", path: "bridge/", glob: "*.ts"})。在泄露的 Claude Code 源码（4,471 个文件）上，实际的过滤链是：

原始文件数:                 4,471
层级1 .gitignore 剪枝:     → 4,471  （源码快照无 node_modules，此层无效果）
层级2 path 限制 bridge/:   → 32     （只遍历 bridge/ 目录）
层级3 glob *.ts 过滤:      → 32     （bridge/ 下全是 .ts，此层无额外过滤）
层级4 二进制检测:           → 32     （全是文本文件）
层级5 正则匹配:            → 3 个文件命中（bridgeStatusUtil.ts、sessionRunner.ts、bridgeUI.ts）

这个例子中 path 限制是最大的过滤器，一步从 4,471 砍到 32。但如果是一个包含 node_modules/ 的完整 Node.js 项目，.gitignore 剪枝的效果更大。因为一个典型项目中 node_modules/ 可能包含数万个文件，一条规则就砍掉大量的文件数量。

通过过滤后需要实际搜索的文件，ripgrep 在内容匹配层面也有多项优化：

• SIMD 向量化匹配。 ripgrep 底层使用 Rust 的 regex crate，它利用 CPU 的 SIMD 指令并行比较字节。普通逐字节比较一次处理 1 个字节，AVX2 一次处理 32 个字节。搜索时先用 SIMD 快速扫描搜索词首字符的出现位置，只在命中时才做完整匹配。对于多模式搜索，ripgrep 使用 Teddy 算法实现 SIMD 级别的多模式并行匹配。

• Boyer-Moore 跳跃。 对于固定字符串搜索，从 pattern 末尾开始比对，遇到不匹配时根据 bad character table 直接跳过多个字符。长 pattern 时只需扫描约 n/m 个字符（n = 文件大小，m = pattern 长度）。

• 操作系统 Page Cache。 读过的文件内容会被操作系统缓存在内存中。对于经常使用的代码项目，文件几乎永远在缓存中。首次搜索可能触发磁盘 I/O，第二次搜索直接从内存返回。

• mmap 零拷贝。 对于大文件，ripgrep 使用 mmap（内存映射）代替普通的 read() 系统调用。普通 read() 需要将数据从内核空间复制到用户空间，mmap 让进程直接访问内核的 Page Cache，省掉一次数据复制。对小文件反而因为系统调用开销不划算，所以 ripgrep 会根据文件大小动态选择。

• 多线程并行。 ripgrep 用线程池并行处理多个文件：一个线程遍历目录树产出文件路径，多个 worker 线程并行搜索不同文件，结果通过 lock-free queue 汇总。

用 Claude Code 自己的源码（4,500 文件、95 万行代码）做一组实测，对比 ripgrep 和 GNU grep 在同一台机器上搜索同一个关键词的耗时（取 3 次运行的稳定值）：

两者搜索的文件范围几乎一样（ripgrep 4,494 个文件 vs GNU grep 4,522 个），差距主要来自 ripgrep 的多线程并行和 SIMD 向量化加速，而非文件过滤。0.1 秒的搜索延迟对交互式使用来说基本无感。

一个很重要的原因，Claude Code 面对的数据规模（开发者本地项目）恰好落在暴力搜索可行的范围内。

一个 250MB 的代码库在 Page Cache 命中（开发者的日常项目几乎总是命中）的情况下，连磁盘 I/O 都省了，整份数据就躺在内存里。按现代开发机约 30GB/s 的内存带宽算，把这 250MB 从 page cache 搬一遍的数据搬运下界约为 250MB / 30GB/s ≈ 8 毫秒。真实情况下还要加上 ripgrep 做 SIMD 模式匹配本身的 CPU 开销，实测总耗时通常在几十到一百多毫秒，因此没有构建索引的必要性。

Claude Code 选择零索引，但行业中并非所有人都这么想。这一章把 Claude Code 和 Cursor、Codex 放在一起比较：Cursor 的双索引架构长什么样，Codex 为什么做出了和 Claude Code 几乎相同的选择但实现路径不同，规模如何决定架构选择，以及 Claude Code 自身的演进方向。然后回应 Grep 方案最常见的批评 ，即token 成本问题，从源码看 Claude Code 用了哪些机制来控制成本。

Cursor 使用经典的 RAG 架构，并在此基础上叠加了 trigram 索引。这里只介绍 Cursor 区别于 Claude Code 的索引部分，因为Cursor 同样有 Grep 搜索工具可用（见 4.2 节）。

• 语义索引： 本地用 tree-sitter 把代码按语法边界切成块，通过 Merkle Tree 做增量同步（只传变化的部分），代码块加密上传到 Cursor 服务端，服务端用 embedding 模型生成向量后立即丢弃原始代码，向量和元数据存入 Turbopuffer（一个向量搜索引擎）。搜索流程为：用户提问 → embedding → 向量最近邻搜索 → top-K → reranking → 组装到 context。

• 精确搜索索引： Cursor 在 2025-2026 年开发了 Instant Grep，使用 trigram（三字符组合）倒排索引加速 grep 搜索。预处理时把文件内容切成 3 字符的滑动窗口（如 "OAuth" → "OAu", "Aut", "uth"），为每个 trigram 维护一个包含该 trigram 的文件列表。搜索时取所有 trigram 对应文件列表的交集得到候选文件，只对候选文件跑正则匹配。

总的来说，Cursor 走的是预处理路线：代码仓库在后台被分块、embedding，向量写入 Turbopuffer，同时再喂给 Merkle 树维护增量同步，离线建好的索引是整条链路的前提。

Claude Code 走的是按需路线：没有索引、没有预处理，LLM 在对话里实时决定用什么关键词 grep、读哪些文件，所有语义理解都由模型自己在循环中完成。这两种架构对应两套取舍：索引换来的是命中率和跨仓库扩展性，零索引换来的是零启动、零维护和与开发者工作流的零摩擦。

Cursor 的索引规模本身就说明了问题。Turbopuffer 的官方客户案例披露了 Cursor 的向量基础设施数据：100 亿+ 向量、1,000 万+ 命名空间（每个命名空间对应一个用户的一个代码库）、写入吞吐量约 10GB/s。CTO Sualeh Asif 称 Turbopuffer 是“扩展过程中少数不需要操心的基础设施之一”。这个规模意味着 Cursor 面对的不只是小型个人项目。当代码库足够大时，暴力 Grep 的延迟会变得不可接受。对于 Agent 场景来说，搜索延迟直接决定了在有限时间内能做多少轮搜索，也就决定了 Agent 对代码的理解深度。

所以，零索引和双索引不是技术优劣之分，而是场景选择。Claude Code 面向开发者本地项目（MB ~ 几百 MB），ripgrep 暴力扫描只需几十毫秒，加上 LLM 的推理能力，零索引意味着零启动延迟、零维护成本、零配置。Cursor 面向更广泛的场景包括大型代码库，暴力扫描的延迟不可接受，索引是必需的。

但有一点值得玩味的是 Cursor 在 2025 年 3 月泄露的 Agent system prompt 里，grep_search 被明确标注为主要探索工具（MAIN exploration tool），LLM 被要求先用一组宽泛关键词进行 Grep，codebase_search（语义搜索）只在“概念性查询”时作为补充。一家把语义搜索当核心卖点、为此自建整套向量基础设施的公司，内部却把 Grep 放在第一个被调用的位置，这说明在代码搜索这个任务上，“精确匹配找到已知符号”远比“语义理解找到相似概念”来得高频和确定。向量检索解决的是 Grep 覆盖不到的长尾，而不是反过来。行业趋势也在印证这一点，有分析指出 Cursor 正在弱化纯向量搜索、转向混合搜索；Claude Code 则把这条路线推到了极端，即完全不用语义检索，靠 LLM 把语义需求翻译成精确关键词，再交给 Grep。

值得注意的是，Claude Code 自己也在演进。v2.0.74 版本引入了 LSP（Language Server Protocol）支持，用 “go to definition” 这类语义精确的操作替代部分 Grep + 多文件 read，实测降低了约 40% 的 token 消耗。社区也在做补充：有人开发了 Beacon 插件，用 Claude Code 自带的 PreToolUse hooks 拦截 Grep 调用，替换为混合搜索（向量 + BM25 + rank fusion）。

前面对比了 Cursor（双索引）和 Claude Code（零索引）的不同选择。但还有一个重要的参照物：OpenAI 的 Codex CLI。

Codex 的代码搜索架构和 Claude Code 惊人地相似：同样不建索引、不用 embedding、不用向量数据库。 社区提交的 向量索引功能请求 被 OpenAI 团队关闭，明确表示“not currently on our roadmap”。

但两者的实现路径有一个关键分歧：代码搜索的工具设计不同。Claude Code 为搜索操作封装了专用工具。GrepTool 有三种输出模式和 head_limit 等参数，GlobTool 做文件名匹配，FileReadTool 按行范围读取。每个工具有明确的参数 schema，LLM 通过结构化的工具调用来使用它们。Codex 没有专门的搜索工具。它的核心工具是 shell（执行任意 shell 命令）和 apply_patch（专用 diff 格式编辑文件），此外还有 update_plan、view_image、web_search、spawn_agent（多 agent 协作）等。所有代码搜索操作通过 shell 工具完成。LLM 可以直接组合 rg、find、cat、git 等 Unix 命令来搜索。

Codex 的多个 system prompt 文件中都写了同一条指令："When searching for text or files, prefer using rg or rg --files respectively because rg is much faster than alternatives like grep."搜索模式同样是多轮迭代：Grep → 读文件片段 → 调整关键词 → 再搜。

两种路径的核心分歧在搜索工具的封装程度上。Claude Code 把 Grep 封装成带结构化参数的专用工具，LLM 不需要解析原始 shell 输出，减少出错概率，也让系统更容易控制信息量；Codex 让模型直接写 shell 命令调用 rg，给予最大灵活性（可以自由组合管道、正则、路径过滤），但需要模型自己处理非结构化的文本输出。

真正值得注意的是两者的共识：两个互为竞争对手的 AI 编程产品，独立做出了几乎相同的架构决策，用 LLM 驱动 ripgrep，放弃向量检索。 这不太可能是巧合。这说明在当前 LLM 能力水平和开发者本地项目的规模范围内，零索引 + Grep 已经是一个被反复验证的有效方案。

为什么选 Grep 而不用向量检索？两个核心原因：无需预建索引，每次直接用 Grep 搜磁盘上的实时文件，零启动延迟、零维护成本、不存在索引过期问题。此外，代码搜索的核心需求是精确匹配，Grep 比语义相似度可靠。但这带来了一个显而易见的成本问题：多轮调用 Grep 和 Read，不会很烧 token 吗？毕竟搜索循环的每一轮都要把完整的对话历史发给 Claude API，context 越来越长。

向量数据库厂商 Milvus（Zilliz）的工程师曾发表文章 “Why I'm Against Claude Code's Grep-Only Retrieval? It Just Burns Too Many Tokens” 直接质疑这一点。文章展示了一个实测案例：用 Claude Code 调试一个 VSCode 扩展的 bug，Grep 在仓库中反复搜索、倾倒大量无关文本，最终花了 14 次工具调用、32.2k tokens、59.3 秒才找到答案，但实际上正确的 10 行代码埋在 500 行噪声里。文章将问题归纳为三点：token 膨胀（每次 Grep 把大量无关代码塞进 context，成本随仓库规模恶化）、时间税（AI向代码库问二十个问题，开发者干等）、零语义（Grep 只做字面匹配，不理解代码含义和关联）。作为替代方案，他们开源了基于向量检索的 MCP 插件 Claude Context，声称在相同任务上 token 消耗降低约 40%、工具调用次数减少约 36%。

那么 Claude Code 自己是怎么应对 context 膨胀的？从源码看至少有三层机制（需要指出的是，这三层都是通用的工程手段，embedding 方案同样可以使用，并非 grep 独有的优势）：

• 第一层：prompt cache 降低重复计费。 API 会识别出本次请求的输入前缀和上次完全相同，因为只是在末尾追加了最新一轮的工具结果。这样一来可以直接复用已有的计算缓存，只为新增的增量部分付全价，前面累积的大头按约 1/10 的缓存价计费。源码中可以看到 Claude Code 为此做了精细的工程优化：system prompt 在发送前被拆成多个独立的文本块，每个块可以单独标记缓存策略。这种分块设计确保不变的部分能精确命中缓存，不会因为动态内容变化而失效。Vadim 在 2025 年 12 月的分析发现，agentic 循环中 92% 的 prompt 前缀在相邻轮次间完全相同，实测成本降低约 81%。

• 第二层：auto-compaction 压缩历史。 多轮 grep/read 会让对话历史持续增长。当累积的 token 数接近 context window 上限时，Claude Code 自动触发对话压缩：用 LLM 对旧的对话历史生成摘要，然后用摘要替换原始消息，直接缩短对话历史。这意味着 context 不是无限增长的，早期搜索轮次的 grep 结果和 read 内容最终会被压缩成一段摘要，为后续搜索腾出空间。

• 第三层：子 agent 隔离搜索结果。 第二章提到的 Explore 子 agent 本身就是一种 context 管理手段。大量 grep/read 的原始结果在子 agent 的独立 context 中处理和消化，只有精炼后的结论返回主对话，避免主 context 被搜索中间结果撑满。

这三层机制让暴力多轮搜索在实践中可控，但并没有消除 Grep 方案相对于 embedding 方案在单次检索精准度上的差距。Grep 方案的核心 tradeoff 是：用更多的搜索轮次和更大的 context 开销，换取零索引、零维护、零启动延迟的工程简洁性。这个 tradeoff 在开发者本地项目的规模上是合算的，但在更大规模上是否仍然成立，取决于搜索轮次和 context 成本的增长曲线。

Milvus 的批评针对的是通用场景下的 token 开销。但在代码搜索这个具体场景下，Grep 的表现可能比直觉预期的要好得多。一项系统性研究（GrepRAG: An Empirical Study and Optimization of Grep-Like Retrieval for Code Completion，ISSTA '26）在 CrossCodeEval 和 RepoEval_Updated 两个代码基准数据集上做了严格对比：让 LLM 自主生成 ripgrep 命令检索代码上下文，然后用检索到的内容做代码补全。结果发现， 即使是最朴素的单轮 Grep 检索，代码补全效果也超过了基于 embedding 的 RAG 基线：在 RepoEval_Updated 的 Python Line 补全任务上，Naive GrepRAG 的 Exact Match 达到 38.61%，而 Vanilla RAG（BM25 + embedding）只有 24.99%。论文分析了 grep 在代码场景下成功的原因：代码搜索的关键词 95% 是标识符：类名（36%）、方法名（41%）、变量名（18%）。标识符本身就是代码的语义，精确匹配恰好是最直接的检索方式。这和自然语言搜索不同，自然语言中“词汇不匹配”是常态，但代码中 getUserById 就是 getUserById，不会被改述成 fetchPersonByIdentifier。

不过这一切有个前提：任务是代码搜索。一旦切换到自然语言问答这种场景，结论会变得复杂得多。Zach Nussbaum 在 On the Lost Nuance of Grep vs. Semantic Search 里做过一组实测：在 Natural Questions 数据集（一个自然语言的问答数据集），他直接用 ripgrep（rg -i -c，把查询去掉停用词后作为关键词集合去搜）做检索。初始的效果很差，因为自然语言问答的 query 和答案文档之间常常存在严重的词汇不匹配，query 里说的是概念，文档里用的是同义词或改写。有意思的是，只要加一步 LLM query expansion，用一个便宜的小模型（gpt-5-mini）先把查询改写成一组更相关的关键词，再把这些关键词喂给 Grep，召回率就大约能提升5-10倍。换句话说，来自 LLM 在查询端的语义理解能起到类似 embedding 的语义搜索效果。但即便做了这一步，Grep 仍然追不上 embedding 在语义匹配上的能力：当用户只记得某个概念的侧面特征、却想不起合适的关键词时，向量检索依然是更合适的工具。

代码里的函数名、类名是程序员亲手埋的精确锚点，Grep 几乎总能命中；自然语言里的一个概念可以有十几种表达，就需要 LLM 或 embedding 帮忙把概念翻译成可能的关键词。Claude Code 选择放弃 embedding，不是因为向量检索本身不行，而是因为代码搜索恰好是 Grep 最适合的地方。

需要指出的是，无论是 GrepRAG 论文还是上述在 NQ 数据集上的测试，采用的都是单轮检索，没有“看结果不满意 → 换关键词再搜”的迭代过程。而 Claude Code 的搜索循环是多轮迭代的（如第二章实战中的四轮搜索）。多轮迭代理论上能进一步提升效果（可以根据中间结果调整搜索方向），但也意味着更多的 context 开销，而这正是 Milvus 批评的痛点。多轮 grep 相比单轮到底能带来多大提升、又付出多大 context 代价，目前还没有直接的实验数据。

回到开头那个问题：RAG 真的死了吗？要回答这个问题，得先问一件更基础的事：我们说的 RAG 到底是什么？如果按 Retrieval-Augmented Generation 本来的定义，它指的是一个很宽的范式：先检索相关内容，再把检索结果塞进 context，最后让模型基于这些内容生成回答。按这个定义，Claude Code 做的事完全符合 RAG。它只是把检索这一层从 embedding + 向量库换成了 LLM 驱动的 grep 和 glob，整个“检索 → context → 生成”的骨架没动。

但过去一年被反复唱衰的那个“RAG”，指的其实是另一件更窄的事：预先把代码分块、embedding，写进向量库，用户提问时再跑一次最近邻检索，把 top-K 结果喂给模型。这是 RAG 最常见的一种落地形式，但它只是范式的一种实现。所以更准确的说法是：不是 RAG 死了，而是“预先建索引、静态一次性检索”这种做 RAG 的方式在某些场景下正在被替换掉。

本文在上面已经解释了为什么在代码搜索这个具体场景上可以这么换，总结有三个原因：

1）代码本身就是 Grep 友好的。 代码里的函数名、类名、常量，本质是程序员埋进去的高精度锚点，精确匹配恰好是最直接的检索方式。GrepRAG 的论文在 CrossCodeEval 等基准上验证了这一点：单轮 grep 驱动的检索就能超过 embedding RAG 基线。这也解释了为什么连 Cursor 这种把语义索引当核心卖点的公司，内部 system prompt 仍然把 grep_search 标为“主要探索工具”。

2）开发者本地项目的规模撑得住暴力扫描。 4,500 个文件的项目 ripgrep 跑完只要 0.1 秒，这个数量级根本用不着离线索引。“暴力搜索慢”的前提是数据大到暴力算法跑不动，而大多数本地代码库离这个前提还差好几个数量级。

3）Agent 带来的是检索模式的转变。传统 RAG 是被动的：系统在问题出现之前就预先决定“你可能需要看什么”，一次性检索一批相关块塞进 context，模型只能在这批给定的内容上做推理。而 Agent 时代的检索是主动的：模型每一轮主动决定当前需要什么、用什么工具拿、拿到之后要不要继续找。第二章那四轮实战搜索就是主动搜索的具体形态，每一步搜什么都由上一步的发现决定，这条路径是任何预检索都猜不出来的。这种场景下，Grep 的潜力能够充分发挥，例如在4.5章节的实验中，使用LLM对query进行改写后，仅单轮搜索准确率就提升了5-10倍。

这才是“RAG 已死”那批标题背后真正在发生的事：死的不是检索增强生成这个范式，而是代码搜索一定要靠 embedding 预索引这个默认假设。Claude Code 和 Codex 殊途同归地选择了零索引，说明在代码搜索这个领域上，用 LLM 驱动 Grep 已经是一个足够好、甚至更省心的替代方案。至于范围之外呢？在自然语言问答这类软语义主导的场景里，embedding 依然是重要的部分，在更大规模的代码仓库上，索引也无法被抛弃。总之，技术的选择由数据的特性和规模决定，不应该是信仰问题。

1、Claude Code 官方公开信息

2、学术研究

• GrepRAG: An Empirical Study and Optimization of Grep-Like Retrieval for Code Completion (ISSTA '26): 在 CrossCodeEval 和 RepoEval_Updated 上系统对比 grep 检索 vs embedding/graph RAG，证明 LLM 驱动的单轮 grep 在代码补全任务上优于传统 RAG 基线 https://arxiv.org/abs/2601.23254

3、社区分析与讨论

4、Claude Code 源码分析： 基于 2026 年 3 月 31 日因泄露公开的 Claude Code CLI 源码快照

• Cursor 相关： Engineer's Codex: How Cursor Indexes Codebases Fast、Cursor Agent system prompt（2025 年 3 月泄露版本）、Turbopuffer Customer Story: Cursor。https://read.engineerscodex.com/p/how-cursor-indexes-codebases-fast  https://turbopuffer.com/customers/cursor

5、OpenAI Codex 相关

你信吗? 2TB内存数据库发生OOM?

你以为把 work_mem 从 4MB 调到 64MB，是在“优化排序和哈希”？

很多时候，你不是在提速。

你是在把一颗延时爆炸的内存雷埋进生产库。更扎心的是：

就算你把 work_mem 设成 2MB，也不代表 PostgreSQL 一条查询最多只会吃 2MB。

PostgreSQL官方文档写得很清楚：work_mem 规定的是单个查询操作在写临时文件前可使用的基础内存上限，典型对象包括 sort 和 hash table；复杂查询里可能同时存在多个 sort/hash，多个会话还能并发执行， 总内存消耗可能是 work_mem 的很多倍。更要命的是，哈希类操作的上限还会再乘以 hash_mem_multiplier，默认就是 2.0。并行查询时，每个 worker 还会各自独立吃这份资源。官方甚至直接提醒：一个 4-worker 的并行查询，资源占用可能接近无并行时的 5 倍。

翻译成人话就是：

work_mem 从来不是“每条 SQL 的内存上限”，更不是“这台机器的安全阈值”。

它只是执行计划里某个内存操作节点的预算起点。

所以，很多团队一上来就问：“我们 256GB 内存，work_mem 设 64MB 保守吗？”

这问题从第一性原理上就问错了。

你不先问并发数、执行计划里有多少内存节点、是否启用并行、哈希是否放大、是否有错误估算，单独讨论 work_mem 数字，基本等于闭眼开车。

这是最容易被误解的地方。

很多人知道一个常识：work_mem 不是“每查询”，而是“每操作”。这没错。

但只知道这一层，还不够。

最近一篇 PostgreSQL 实战文章里记录了一个非常典型的事故：生产集群曾被 OOM killer 干掉，机器吃掉了 2TB RAM；而 work_mem 当时只有 2MB。作者复盘时，在复现环境里通过 pg_log_backend_memory_contexts 抓到了后端内存上下文：单个 backend 的日志里，ExecutorState 约 235MB，HashTableContext 约 340MB，总计约 557MB，其中 ExecutorState 还出现了 524,059 chunks。

这件事说明什么？

说明真正的危险，不只是“有很多 sort/hash 节点”，而是：这些内存未必会在过程中及时归还。

PostgreSQL 的内存管理核心机制是 memory context。它设计的优势就是：不按对象逐个 free，而是按上下文整块释放。

官方/社区对这一机制的解释非常一致：memory context 的主要优势，是能“一次性释放整个上下文里的内容”，这样更快，也更可靠。

问题也正出在这里。

如果某些分配挂在一个生命周期很长的上下文上，比如 ExecutorState，那它们就可能一路攒着，直到整个执行结束才释放。如果查询本身很大、执行很久、又因为函数封装或糟糕的 SQL 结构把本来可以切开的步骤揉成了“一锅大杂烩”，内存就会像滚雪球一样涨。

所以你看到的现象是：

• 配置上 work_mem 并不夸张

• 单看某个节点预算也不离谱

• 但执行期间，多个节点、多个 worker、多个分配上下文叠加

• 再加上长生命周期上下文延迟释放

• 最后，操作系统出来“物理教你做人”

这不是 PostgreSQL “不遵守 work_mem”。而是你把 work_mem 当成了硬上限，而它从来都不是。

官方表述其实已经给出答案：work_mem 是“在写临时磁盘文件之前”的内存预算。

注意这句话的关键词：

before writing to temporary disk files

也就是说，它更像是一个节点级的内存-磁盘切换阈值。

它能影响 sort / hash 是更愿意在内存里做，还是更早 spill 到磁盘。

但它并不能替代下面这些问题：

• 执行计划是不是错了？

• 行数估算是不是低得离谱？

• 一个查询里是不是同时堆了太多 hash/sort/memoize？

• 并行是不是把放大器打开了？

• SQL 是否把多个阶段硬捏成了一个长生命周期执行体？

• 函数、CTE、子查询、JOIN 方式是否让释放时机变晚？

所以， 把 work_mem 调大，常常不是解决问题，而是在隐藏问题。

在小并发、强控制、偏分析型 workload 里，调大 work_mem 当然可能有收益；PostgreSQL 官方也明确说了，在 hash 经常 spill，而提高 work_mem 又带来内存压力时，可以考虑用更高的 hash_mem_multiplier，甚至在某些环境中提升到 2.0–8.0 以上。

但这里有一个不可跳过的前提：

• 前提一：并发是可控的

• 前提二：查询形态是可控的

• 前提三：执行计划足够稳定

如果这三个前提不成立，调大 work_mem 往往不是优化，而是把单点慢 SQL 升级成整库级故障。

这才是 DBA 和开发最应该正视的现实。

原文里的事故，本质上不是“参数设错了”，而是查询写法和执行生命周期设计出了问题。复盘中提到：一个 SELECT 调用了 plpgsql 函数，函数内部还做了 COPY 相关操作，再把结果拿去 JOIN。语法上合法，但从执行器角度看，这可能把原本应该切分、释放、落盘的东西，拼成了一个超长生命周期的大操作。

这背后有两个基本规律：

如果统计信息失真，Planner 低估行数，就更容易选出本该 spill 却没及时 spill、或者本不该 hash 却选了 hash 的计划。PostgreSQL 官方也明确建议，复杂查询可能同时进行多个 sort/hash；而是否会落盘、落到什么时候，本来就强依赖计划和执行路径。

很多开发喜欢把逻辑包进函数、子查询、CTE、视图，然后再层层 JOIN，觉得“代码优雅了”。

但数据库不是应用层对象系统。

数据库优化器看的是数据流、算子、生命周期、代价模型，不是“抽象是否漂亮”。

对 PostgreSQL 来说， 好维护的代码结构，不一定等于好执行的 SQL 结构。

这是很多团队直到出事故都没真正接受的事实。

在这类问题上，很多人本能会问：“那有没有一个参数，限制单连接最多吃多少内存？”

很遗憾，没有。

至少没有一个像很多人想象中的、简单直接、可靠的“per-backend hard cap”配置。原文对此说得很直白： 你不能对 PostgreSQL 每个 backend 设一个硬性内存封顶。

你能做的，是一整套“风险治理”组合拳，而不是迷信一个参数：

• 控制并发

• 修正统计信息

• 改写 SQL

• 限制并行

• 设置超时

• 观察实际内存上下文

• 把大查询和高峰流量隔离

这才是工程化思路。不是“把 work_mem 调小一点，求神保佑”。

PostgreSQL 已经给了你非常好用的工具：pg_log_backend_memory_contexts(pid)。

官方文档说明，它会把指定 backend 的 memory contexts 以 LOG 级别打进日志；而且要注意，这个函数可能带来明显开销，因为它会生成大量日志。

这类工具为什么重要？

因为过去很多团队排查内存问题，方法都非常原始：

• 看操作系统 RSS

• 看 pg_stat_activity

• 看慢 SQL

• 猜是 sort 爆了还是 hash 爆了

但真正的关键问题是：

• 内存到底堆在哪个上下文里？

• 是谁分配的？

• 为什么没释放？

没有 memory context 视角，你看到的只是“高血压”；有了它，你才能找到“是哪根血管堵了”。

另外，如果你想看当前会话自己的内存上下文，PostgreSQL 还提供了 pg_backend_memory_contexts 视图；默认只有 superuser 或具备 pg_read_all_stats 权限的角色可读。

1）不要全局盲调大 work_mem

全局大 work_mem，本质是在给所有会话、所有复杂查询、所有并行 worker批量发放内存信用卡。官方文档已经明确说明，总体消耗可能是很多倍。

2）优先做分层配置，而不是“一刀切”

把高并发 OLTP、低并发分析、批处理、报表查询分开。能按 role、database、session、事务级设置的，就不要全局放开。

3）先压风险，再谈提速

高峰业务链路上，先配 statement_timeout，因为它能在语句执行时间过长时直接中止；官方还明确提示，不建议在 postgresql.conf 里对所有 session 粗暴统一设置。

4）把统计信息治理当成容量治理的一部分

不是只盯 CPU、IO、shared buffers。行数估算偏差，本质上就是容量预算偏差。

5）对并行保持敬畏

并行会加速，也会放大。官方直接说了：资源限制是按 worker 单独生效的，4 worker 的并行查询可能吃出接近 5 倍资源。

1）别把数据库函数、CTE、子查询当成“代码封装美学”工具乱嵌套

你看到的是“复用”；优化器看到的可能是“更长的执行生命周期”和“更差的释放时机”。

2）能分阶段物化的，就别硬拼成一个超级 SQL

有些中间结果，就该落临时表、物化结果集或拆分步骤。数据库最怕的是“逻辑优雅、执行灾难”。

3）你以为的“小查询”，在执行器眼里可能是一条大工程流水线

一个 SELECT 里套函数、函数里再跑复杂逻辑，不代表数据库会把它当“小事”。

4）SQL 性能问题，最终都不是字符串问题，而是资源调度问题

内存、磁盘、CPU、锁、并行度、统计信息、数据分布，缺一不可。

也不是说 work_mem 永远不能调大。这篇文章最容易被误读成“work_mem 一调就死”，这也不对。

从第一性原理出发，下面这些前提成立时，提升 work_mem 往往是合理的：

• 并发数低且稳定

• 查询主要是分析型，排序/聚合/哈希代价高

• 有足够内存余量

• 并行度可控

• 执行计划稳定

• 已确认瓶颈真的是 spill 到临时文件，而不是估算失真或 SQL 结构错误

如果这些前提成立，调大 work_mem 是优化。

如果这些前提不成立，调大 work_mem 是赌博。

一字之差，结果天差地别。

原文里最值得反复咀嚼的一句判断是：

不是硬件不够大，而是查询写法错了。

哪怕你有 2TB RAM，照样可能被一条“看起来没什么”的 SQL 拖垮。

所以真正成熟的 PostgreSQL 团队，不会把 work_mem 当成万能旋钮。

他们会把它看成：

• 一个执行器节点预算参数

• 一个磁盘/内存切换阈值

• 一个会被并发、并行、哈希放大、生命周期拖长的风险源

说白了：

work_mem 不是性能开关。

它是资源杠杆。

杠杆用对了，省力；用错了，砸库。

你们线上出过和 work_mem、临时文件、Hash Join、并行查询有关的事故吗？

你更认同“参数先行”，还是“SQL 与统计信息优先治理”？

作者丨digoal

来源丨公众号：digoal德哥（ID：gh_eb6d10476af2）

dbaplus社群欢迎广大技术人员投稿，投稿邮箱：editor@dbaplus.cn

Skill 是 Agent 能力的最小封装单元，它把领域知识、工作流程和工具集成打包成一个即插即用的模块，让通用 Agent 秒变领域专家。

现在所有人都在写 Skill、分享 Skill，但面临的问题是：

• 你写的那个 Skill，真的够好吗？

• 网络上获取的 Skill 选哪一个更好？

能跑和好用之间隔着十万八千里。

一个 Skill，description 写得太宽泛了，很可能 Agent 根本不会触发它；工作流缺少分支逻辑，可能碰到稍复杂的输入就翻车；明明需要附带脚本却硬塞在 Markdown 里，每次执行都重写一遍相同的代码。更麻烦的是，这些问题写的时候不一定能看出来，只有真正使用的时候才会暴露（也有可能不会暴露）。

基于此设定了一套 8 个维度的量化评估框架并实现了一个评估 Skill，从元数据质量、执行引导、领域知识密度到工作流完整性等，逐项打分、加权汇总，最终给出 Skill 的 S/A/B/C/D 等级评定。它能帮你审视自己的 Skill：哪里还有短板、该怎么改；也能横向对比多个 Skill：谁设计得更好、好在哪里。

审视自己的作品，它是改进路线图；对比他人的作品，它是选型决策工具。

我们要评估一个 Skill 的好坏，不能只靠感觉，必须要有一套可量化的标准。

下面的 8 个维度分布在一个 Skill 从被发现到被执行完成的完整生命周期，分成三个评估阶段：

第一阶段：能不能被找到

一个 Skill 装好之后，Agent 在每次对话中只会读到它的 name 和 description。如果这几十个字写得不好，Skill 就根本不会被触发，后面写得再好也没用了。

D1. 元数据质量 评估的就是这个第一印象。description 是否精准地描述了功能？是否包含了用户可能使用的关键词？最好的 description 甚至会写明不该在什么场景触发，防止误触发。

这是唯一一个决定 Skill 生死的维度。其他维度影响的是"好不好用"，D1 决定的是"有没有机会被用到"。

第二阶段：用起来顺不顺

Agent 决定触发后，会加载 SKILL.md 的完整内容。这时候考验的是：Agent 能不能顺畅地把任务执行完？

这一阶段有四个维度：

• D2. 执行引导清晰度：Agent 加载了 Skill，但面对用户的具体输入，它知道该走哪条路吗？什么情况需要追问用户？什么情况该直接执行？什么操作不该做？好的 Skill 像一本清晰的操作手册，而不是一堆信息的堆砌；

• D4. 工作流完整性：如果说 D2 是每一步怎么走，D4 就是整条路是否走得通。流程是否端到端？步骤之间的衔接是否顺畅？碰到异常（API 超时、文件下载失败）有没有处理方案？

• D5. 输入输出清晰度：用户给什么、最终得到什么？这听起来是基本功，但很多 Skill 只写了中间步骤，用户第一次看完全不知道整个流程的起点和终点是什么；

• D6. 资源利用：该用脚本的地方是不是用了脚本？该放参考文档的地方是不是放了？还是把所有东西都塞在一个巨大的 SKILL.md 里？好的资源结构遵循渐进式披露（SKILL.md 保持精简，详细内容按需加载）；

第三阶段：值不值得存在

最后，跳出执行细节，从更高的视角审视这个 Skill 本身。

• D3. 领域知识密度：这是 Skill 存在的根本理由。如果 Skill 里的内容，通用 Agent 不靠它也能做到，那它就没必要存在。好的 Skill 内嵌了难以获取的专业知识：私有 API 的调用方式、内部系统的数据模型、行业特定的最佳实践。

• D7. 写作质量：SKILL.md 本质上是写给另一个 AI 看的技术文档。结构是否清晰？有没有冗余？Agent 能否快速扫读并抓到关键信息？

• D8. 范围与聚焦：一个 Skill 应该做好一件事，而不是试图包揽一切。过宽的 Skill 什么都做不好，过窄的 Skill 不值得封装。

并非所有维度同等重要。我们按对 Skill 实际效果的影响程度分配权重：

每个维度具体的评分方式这里不赘述，有兴趣的同学可以从附录下载 Skill 查看。

加权求和后，总分映射为五个等级：

接下来，我们用这套框架实际评估一个 Skill，看看分数背后的含义。

光看评分标准还是比较抽象，这里先拿一个真实的 Skill 跑一遍评估。

演示中使用的是百度内部 AI 工作助手 dodo。使用其他支持 Skill 的 AI 工具如 Claude Code、小龙虾等也都是可以的。

下面参与评估的这个 Skill 是我在内部另一篇实例中真实开发并已投入使用的：

评估得出的具体问题与建议摘录如下：

D1. 元数据质量 (3/10)：description 过于简略，缺少触发条件

• 影响：Agent 无法自动识别何时应触发此 Skill

• 建议：扩展 description，包含触发关键词和功能概述

D7. 写作质量 (7/10)：存在重复内容

• 影响：文档冗余，影响可读性

• 建议：删除重复的 SQL 示例（第 333-347 行），保留一处即可；合并重复的说明段落

ip-bill 是一个功能完整、执行清晰的 Skill，适合自动化处理公网 IP 出账流程。主要优势在于：

• 工作流设计严谨，包含连通性检查和错误处理

• 领域知识丰富，API、数据库、BOS 等各环节都有详细说明

• 资源组织合理，脚本、参考文档、示例文件齐全

主要改进空间在于元数据描述和文档精简。增强 description 中的触发条件描述，有助于 Agent 自动识别使用场景。

这里从 dodo 的可用 Skill 列表中随便选取了两个功能相近的 Skill 进行评估对比：

• Skill A：workos-weekly

• Skill B：subordinate-weekly-report

详细评估结果摘录如下：

1）workos-weekly 更强的方面：

• 领域知识密度更高（OKR 关系、活跃空间、洞察分析等）

• 资源利用更丰富（references、examples、CHANGELOG）

• 工作流更复杂（9 步端到端流程）

2）subordinate-weekly-report 更强的方面：

• 元数据质量更高（场景路由表更清晰）

• 输入输出清晰度更高（每个 action 都有完整的输入输出示例）

• 场景覆盖更全面（6 种 action 覆盖多种查询场景）

3）subordinate-weekly-report 更弱的方面：

• 领域知识密度较低（专业概念较少）

• 资源利用不足（参考资料较少）

两个 Skill 做得好的地方：

• 都有明确的触发条件和反向排除条件

• 都有清晰的执行引导和错误处理

• 都聚焦于单一场景，边界清晰

• 写作质量都很高，结构清晰易读

• workos-weekly 的 HARD-GATE 设计值得借鉴，能明确强制规则

• subordinate-weekly-report 的场景路由表设计优秀，能快速匹配用户意图

• 两个 Skill 都有详细的命令示例和输出示例，降低了 Agent 的理解成本

前面的评估案例中，分数评定由一个模型完成。这就像一场考试只有一个阅卷老师，他可能偏严，也可能偏松，我们却无从判断。

实测中很明显的看到，不同模型对同一个 Skill 的评分存在些许差异。例如用 GLM-5.1 评估某 Skill，得到 7.8 / A，换成 Claude Opus 4.6 评估则为 6.5 / B。分数差了一个等级，但两个模型指出的核心问题却是趋同的。

这说明单模型评分的绝对值不够可靠，但不同模型之间的共识是有价值的。

基于这个观察，我又给本 skill-evaluator 增加了多模型交叉验证机制：让多个模型独立评估、互相质疑、最终再由主模型完成仲裁，把一家之言升级为专家评审团。

第一阶段：独立评估。

多个模型各自按 8 维度标准独立打分。

第二阶段：交叉互审。

所有独立评估完成后，每个模型会看到其他模型的评分。它们需要找出与自己分差 ≥ 2 分的维度，明确指出对方哪里评得不合理，并且必须引用 Skill 中的具体内容作为证据。例如：你 D3 给了 8 分，但这个 Skill 的领域知识只覆盖了 API 调用方式，缺少数据模型和决策逻辑的描述（见第 45-60 行），7 分以上要求要有丰富的专家知识，我认为 6 分更合理。

并且，在审查完对方之后，每个模型还要做自我修正：看了对方的论据后，我是否要调整自己的分数？这一步迫使模型认真对待对方的质疑，而不是固执己见。

第三阶段：仲裁综合。

由主模型（仲裁者）汇总所有独立评估和交叉互审的结果，对每个维度做出最终裁决。

针对于每个评估维度，这里设计了一个三级共识机制，用于主模型执行仲裁：

在最终的评估报告中，每个维度都会标注共识度，让使用者能直接看出哪些分数是比较确定的，哪些是有争议的。

例如：

如果一个维度被标记为"仲裁"，说明这个维度的质量确实处于模糊地带，值得 Skill 作者重点关注。

不是所有环境都支持多模型调用，为此在这里我设计了一个兜底方案：单模型多视角评估。

在这个方案中，单一模型扮演三个不同的评审角色，依据评审风格分为：

三个视角评完后同样进行交叉审查和仲裁。

虽然本质上还是一个模型，但通过角色分化强制引入多样性：严格派可能在 D4 给 5 分，务实派同一维度给 8 分，这种分歧是有意义的。

不同的 AI 工具能力不同。有的工具（如 Claude Code）支持通过 subagent 同时调用自家多个模型，dodo 也支持这种模式调用 Claude 的 Opus 4.6、Sonnet 4.6、Haiku 4.5 模型。但如果想融合更多其他第三方模型或自定义评估模型列表目前还没有原生支持。所以这里在 Skill 中集成了千帆平台的模型能力，对于上述 Claude 系列之外的模型则通过千帆的能力支持。

如果交叉验证只能在特定工具上跑，这个功能的适用范围就很窄。为了保证在各种 AI 工具及不同的触发场景中本 Skill 执行的兼容性，这里设计了四种执行策略：

从使用者的视角，只需要提供参与评审的模型：指定主模型（仲裁模型）和交叉评审模型。

策略路由逻辑根据模型列表自动分类：

• 全是工具原生模型走 A

• 全是第三方走 B，两者都有走 A + B

• 如果运行中出了问题自动降级到策略 C

策略 B 依赖一个 Python 脚本来调用千帆 API。这个脚本只使用了 Python 标准库，不需要操心依赖之类的问题。脚本支持了多模型并行调用和自动重试。

这里测试了几种模型组合的评审效果：

当前 Skill 中已默认配置了模型，主模型为：当前 Agent 自身设置的模型；交叉互评模型为：ernie-5.0、sonnet、glm-5.1、minimax-m2.5。

上文中对我写的 ip-bill 这个 Skill 进行了单模型的评估，最终评估结果虽然有理有据，但是我们仍然无法确定其权威性，一家之言终归是片面的：这个模型的结果是偏严了还是偏松了？它指出的问题是最关键的还是恰好它注意到的？那些没被扣分的维度，是真的没问题，还是被这个模型忽略了？

用多模型交叉验证对 ip-bill 再评一次。这次由 ernie-5.0、sonnet 4.6、glm-5.1、minimax-m2.5 四个来自不同厂商的模型独立评估，互相质疑，最终由主模型 Claude Code Opus 4.6 仲裁出一份经过质证的结论。评估结果篇幅较长，这里我直接导出了一份报告文件：

拿到评估结果和改进建议后，可以继续让 AI 助手代劳。本文为了演示方便，拆分成了评估 + 优化，懒得看结果的话可以让 AI 助手直接一步处理分析 + 优化（这里演示的是单模型评估后优化，多模型的操作也是类似的）。

更多的用法实践可以自行扩展，例如多 Skill 的对比优化，互相学习其优点改进缺点等等，主要还是要依赖模型的分析能力。

回到开头的两个问题：自己写的 Skill 够不够好？网上下载的选哪个？

现在你有了一套 8 维度的评估框架来回答它们，给 Skill 打分、找短板、做对比，把感觉还行变成可量化的判断。并且可以选择通过多模型交叉评估来避免单模型一言堂的造成的评估局限，但是多模型也会增大 Token 的消耗和 Skill 的运行时间，具体使用哪种方式来评估可以由使用者自由选择。

随着更多人写 Skill、分享 Skill，我们可能需要更完善的评估手段：自动化的静态检查工具、基于实际执行数据的动态评分、社区驱动的 Skill 评级体系。这些都值得探索。

这套评估框架只是一把尺子，也有一定的局限性，它度量的是 Skill 的文档工程质量，而非运行时的全部真相。

知道它能量什么、不能量什么，才能用好它。

• 本案例中的 Skill 地址：https://github.com/sunxingboo/skill-evaluator

2026 XCOPS智能运维管理人年会将于5月22日在广州举办，本次大会聚焦AI时代的真实落地实践，紧扣大模型迭代、Agent深度应用等技术热点，邀请行业领军人物、资深技术专家与学术大师，从技术架构、实战案例到科研成果，与大家一起探索AI应用于智能运维与数据库的最佳方式，找到可落地、可复用的破局方案。其中，NineData合伙人&首席产品经理蔡冬者老师将分享《当Vibe Coding遇上数据库：如何在AI爆发式生产力下守住安全与性能红线》，一起来先睹为快：

做后端开发，调 BUG 有一个让人头疼的固定流程：打开日志平台，输入 traceId 或关键词，搜日志；从几十上百条日志里，找到关键的那几条；把日志里的类名、方法名复制出来，去 IDE 里找对应代码；结合代码逻辑，判断哪里出了问题；如果一次找不准，回去再搜日志，再翻代码……

这个过程相对固定，但非常耗时间。每次 BUG 定位，光在日志平台和 IDE 之间来回切换，就能消耗掉大半的时间。

最开始在去年 Q3 想到这个问题的时候，脑子里浮现的第一个方案是：用 Cursor + MCP，把日志平台接进来，再挂一个代码知识库，让 AI 帮我查日志。但这个方案有缺陷 —— 日志查询是「动态的」，它依赖环境、应用、时间范围，没办法静态预置。此外，这样处理没有办法做到比较丝滑地读代码、改代码。

后来开始用 Claude Code，接触到了 Skill 的概念：可以在项目里定义一套自定义命令，描述 AI 应该怎么执行这个命令的每个步骤，于是整个思路变得清晰了。

日志平台有 MCP，Claude Code 有 Skill，两者结合，就能让 AI 自动完成「查日志 → 找关键信息 → 扫描代码 → 定位问题」这整个闭环。然后在 PM 的帮助下，才有了 /log-diagnosis 这个 Skill。

日志平台推出了基于 MCP（Model Context Protocol）协议的日志查询服务，让 Claude 可以直接调用日志平台的能力，无需人工在日志平台上手动查询。

MCP 本质上是一种标准化的「工具调用协议」，Claude Code 通过 SSE（Server-Sent Events）长连接与 MCP Server 通信，实时获取日志数据。

secretKey（日志平台后管申请）
    ↓ acquireTokenTool
accessToken（1小时有效，最多同时存在5个）
    ↓ 携带 accessToken
logsQuery / logSqlQuery / countLogTool ...

secretKey 申请地址：进入日志管理后台 → 日志权限 → 我的应用 → 生成密钥。

log-diagnosis 是一个运行在 Claude Code 里的自定义诊断命令。Claude Code 支持通过 .claude/skills/ 目录定义自定义技能（Skill），以 Markdown 文件描述行为规范，Claude 在收到对应命令时会自动加载并执行。你只需要把 traceId 或告警信息告诉它，剩下的全部交给 AI。完整执行链路如下：

用户输入 /log-diagnosis {环境} {代码分支} {诉求}
    ↓
Claude 加载 .claude/skills/log-diagnosis/SKILL.md
    ↓
读取 .diagnosis/config.json 获取当前环境配置
    ↓
检查 accessToken 是否过期，过期则自动刷新
    ↓
从 traceId 计算日志时间范围（取第9-16位16进制时间戳）
    ↓
调用日志平台 MCP 分页拉取全量日志（最多20页，不遗漏）
    ↓
切换到指定代码分支，结合日志关键词检索代码
    ↓
综合分析：上游日志 + 当前服务日志 + 代码逻辑 → 根因
    ↓
生成诊断报告（飞书文档 or 本地 Markdown）
    ↓
恢复原始代码分支

• Token 自动管理：accessToken 过期自动刷新，无需手动维护；

• 分页全量拉取：自动分页拉完所有日志，禁止只查第一页就下结论（最多 20 页）；

• 跨服务分析：自动识别上下游服务，拉取关联服务日志交叉验证；

• 代码联动：日志里出现的类名/方法名，直接在代码里精确定位。

# 格式
{field} {操作符} "{值}" {连接符} {field} {操作符} "{值}"
# 操作符
=  : 精确匹配
≈  : 模糊匹配（like）
# 连接符
AND / OR / NOT
# 示例
trace_id = "a1b2c3d4e5f6789012345678abcdef01"
trace_id = "xxx" AND log_level = "ERROR"
endpoint ≈ "/api/your-endpoint" AND log_level = "ERROR"
message ≈ "timeout"

注意：时间范围只通过 start/end 参数控制，不要写在 queryString 中。

1）Claude Code

在 Claude Code 命令行中执行，按需安装对应环境：

# 测试环境
claude mcp add --transport sse dw-log-mcp-t1 https://{your-t1-aigw-domain}/api/v1/mcp/log-mcp/sse
# 预发环境
claude mcp add --transport sse dw-log-mcp-pre https://{your-pre-aigw-domain}/api/v1/mcp/log-mcp/sse
# 生产环境
claude mcp add --transport sse dw-log-mcp-prd https://{your-prd-aigw-domain}/api/v1/mcp/log-mcp/sse

安装后重启 Claude Code，执行 /mcp 确认连接状态正常。

2）Cursor

①打开 Cursor Setting；

②点击 Tools & MCP，添加 MCP Server；

③添加 URL，MCP Server 名称任意。

建议按需安装 MCP Server，避免额外消耗 token，示例配置：

{
  "mcpServers": {
    "dw-log-mcp-t1": {
      "url": "https://{your-t1-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-pre": {
      "url": "https://{your-pre-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-prd": {
      "url": "https://{your-prd-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-oversea-prd": {
      "url": "https://{your-oversea-aigw-domain}/api/v1/mcp/log-mcp/sse"
    }
  }
}

④返回设置，就可以看到已经连接上。

将 log-diagnosis 目录放到项目的对应目录下：

1）Claude Code

your-project/
└── .claude/
    └── skills/
        └── log-diagnosis/
            ├── SKILL.md        # 技能行为规范（核心）
            ├── README.md       # 使用说明
            └── reference.md   # 附录：时间脚本、queryString 示例等

2）Cursor

your-project/
└── .cursor/
    └── skills/
        └── log-diagnosis/
            ├── SKILL.md        # 技能行为规范（核心）
            ├── README.md       # 使用说明
            └── reference.md   # 附录：时间脚本、queryString 示例等

3）配置 .diagnosis/config.json

首次运行会自动引导创建（直接调用 /log-diagnosis，Skill 会一步步指示你给出 secret key），也可手动在项目根目录创建 .diagnosis/config.json：

your-project/
└── .cursor/
    └── skills/
        └── log-diagnosis/
            ├── SKILL.md        # 技能行为规范（核心）
            ├── README.md       # 使用说明
            └── reference.md   # 附录：时间脚本、queryString 示例等

字段说明：

• secretKey：唯一需要人工填写的字段，在日志平台后管申请；

• accessToken：首次使用时由 AI 自动调用 acquireTokenTool 获取，过期自动刷新；

• accessTokenExpireAt：从 acquireTokenTool 返回值自动填充；

• fields：调用 logFields 工具自动获取。

命令格式：

/log-diagnosis {环境} {代码分支（可选）} {诉求描述}

参数说明：

• {环境}：T1 / PRE / PRD（按实际环境标识填写）；

• {代码分支}：可选，留空则使用当前分支；

• {诉求描述}：包含 traceId 或告警信息的问题描述，用自然语言书写即可。

示例：

# 用 traceId 定位接口异常
/log-diagnosis T1 feature/your-branch trace_id: "your-trace" 为什么最终没有返回数据
# 用告警信息分析错误原因
/log-diagnosis PRD master 告警详情：【接口：YourService/yourMethod】【业务码：10002000】【业务码消息：系统异常，请稍后重试】帮我分析问题可能性

一行命令，AI 全程接管，几分钟内给出根因分析。

某搜索接口在测试环境反馈没有返回数据。拿到 traceId，直接执行：

/log-diagnosis T1 feature/your-branch trace_id: "your-trace" 为什么最终没有返回数据

← 就这一句话，接下来全部交给 AI。

Skill 触发后，AI 自动完成：

• 从 traceId 推算出日志时间范围（2026-02-27 全天）；

• 检查 accessToken 已过期，自动刷新；

• 调用日志平台 MCP，分 2 页拉取完整日志，共 73 条。

请求入参（从日志自动提取）：

{
  "assembleByOrg": true,
  "channelType": "MANUAL",
  "orderNo": "your-order-no",
  "status": 1,
  "ticketNo": "your-ticket-no"
}

AI 自动识别出关键节点：resultList is empty，SQL 查询返回了空结果。问题在 DB 层，而不在业务逻辑层。

从日志中提取到 toSearchDTO 组装结果：

{
  "channelType": "MANUAL",
  "customerTag": 1,
  "deliveryMode": "某配送方式",
  "orderStatus": "8010",
  "orderType": "0",
  "productCategoryIds": [29],
  "status": 1,
  "ticketSource": 67,
  "ticketTypeId": 5802
}

ORM 框架在日志中打印了实际执行的 SQL，AI 直接读取并分析：

SELECT a.id, a.pid, a.name, a.mode, a.status, a.org_id, a.org_ids,
       a.ticket_group_id, a.tenant_id, a.is_del, a.channel_types
FROM your_type_table a
LEFT JOIN your_relation_table b
    ON b.tenant_id = 1 AND a.id = b.type_id AND b.type = 3 AND b.is_del = 0
WHERE a.tenant_id = 1 AND a.mode = 2 AND a.is_del = 0
  AND a.status = 1
  AND (a.channel_types IS NULL OR a.channel_types = '' OR FIND_IN_SET('MANUAL', a.channel_types) > 0)
  AND (b.root_id is null or b.root_id in (29))
  AND (a.order_types IS NULL OR a.order_types = '' OR FIND_IN_SET('0', a.order_types) > 0)
  AND (a.order_statuses IS NULL OR a.order_statuses = '' OR FIND_IN_SET('8010', a.order_statuses) > 0)
  AND (a.delivery_modes IS NULL OR a.delivery_modes = '' OR FIND_IN_SET('某配送方式', a.delivery_modes) > 0)
  AND (a.ticket_sources IS NULL OR a.ticket_sources = '' OR FIND_IN_SET(67, a.ticket_sources) > 0)
  AND (a.customer_tag IS NULL OR a.customer_tag = 1)   ← BUG 在此

AI 发现：其他字段都处理了 IS NULL 和 = ''（空字符串代表 “不限制”）两种情况，唯独 customer_tag 只判断了 IS NULL，遗漏了空字符串 '' 的情况。

SQL 语义对比：

-- 其他字段（正确）：IS NULL 和 '' 都处理了
AND (a.order_types IS NULL OR a.order_types = '' OR FIND_IN_SET('0', a.order_types) > 0)
AND (a.delivery_modes IS NULL OR a.delivery_modes = '' OR FIND_IN_SET('某配送方式', a.delivery_modes) > 0)
AND (a.ticket_sources IS NULL OR a.ticket_sources = '' OR FIND_IN_SET(67, a.ticket_sources) > 0)
-- customer_tag（遗漏了 = '' 的判断）← BUG
AND (a.customer_tag IS NULL OR a.customer_tag = 1)

DB 中现有的数据，customer_tag 字段都存的是空字符串（未配置），按业务语义本应匹配所有请求，却因为这个遗漏被全部过滤掉了。

AI 在代码中直接找到对应的 MyBatis Mapper XML：

<!-- 问题代码 -->
<iftest="customerTag != null">
    and (a.customer_tag IS NULL OR a.customer_tag = #{customerTag})
</if>
<!-- 修复后 -->
<iftest="customerTag != null">
    and (a.customer_tag IS NULL OR a.customer_tag = '' OR a.customer_tag = #{customerTag})
</if>

这个 BUG 的隐蔽性在于：SQL 语法正确，逻辑上也「看起来」没问题——只有对比了其他字段的写法，才能发现 customer_tag 独自遗漏了空字符串的处理。这类细节差异，人工排查很容易忽略，AI 反而很擅长。

• 有 traceId 时优先用 traceId 拉日志，可精准获取单次请求的完整链路，比关键词搜索精确得多；

• 关注关键日志节点：toSearchDTO finished / search begins / resultList is empty / search finished 等，快速判断数据在哪一层丢失；

• SQL 打印日志（ORM 框架输出）是黄金线索，直接反映最终执行的查询条件，AI 能从中发现肉眼难以察觉的差异；

• 分页必须拉完：日志平台一次只返回部分数据，AI 会严格执行分页直到取完，确保不遗漏关键日志。

核心思路：用「协议 + 规范」让 AI 接管固定流程：

这篇文章的本质，是一次对重复性工程劳动的自动化尝试。调 BUG 的过程——查日志、提取关键信息、找代码、分析原因——逻辑固定，步骤繁琐，但并不需要太多创造性思维。这类工作恰好是 AI 最擅长接管的。

实现这个闭环，靠的是两个关键组合：

1）MCP：让 AI 能够调用外部系统（日志平台），突破了「AI 只能处理静态上下文」的限制，实现了对动态数据的实时获取。

2）Skill：给 AI 一份行为规范，告诉它每一步该怎么做、先做什么后做什么、遇到什么情况怎么处理，把「一次性对话」变成「可复用的工程化能力」。

两者缺一不可。只有 MCP，AI 能查日志但不知道怎么系统地分析；只有 Skill，AI 有流程但没有数据来源。组合起来，才形成了真正可落地的闭环。

值得借鉴的地方：

1）识别「固定流程」是自动化的起点

不是所有工作都适合 AI 接管，但凡是「步骤固定、信息来源明确、输出格式可预期」的工作，都值得尝试用 Skill + MCP 的方式来自动化。排查 BUG 是一个典型，类似的还有：代码审查、性能分析报告生成、告警巡检等。

2）Skill 的本质是「给 AI 写操作手册」

Skill 文件不是在「训练模型」，而是在给 AI 一份清晰的 SOP。写得越细、约束越明确（比如「禁止只查第一页就下结论」「必须分页拉完所有数据」），AI 的执行质量越稳定。这和写给人看的文档本质上是一回事。

3）AI 擅长发现「横向对比」类的 BUG

本文的案例揭示了一个有意思的规律：AI 在处理「同类字段逻辑不一致」这类问题时，表现往往比人工更好。原因在于 AI 没有「先入为主」的经验偏见，不会因为「这段代码看起来没问题」就跳过，它会对所有字段做同等的审查。

最后说一句：AI 时代，工程师的核心竞争力不只是「能写代码」，更是「能把自己的经验和流程转化成可复用的 AI 能力」。/log-diagnosis 是一次小小的尝试，但背后的思路，值得在更多场景里延伸。

大多数Kubernetes工程师每天都在使用CRD，但真正理解其原理与设计的人寥寥无几。

打开你的终端，运行以下命令：

kubectl 获取 crds

现在暂停一下。

向下滚动。

观察显示了多少行内容。

数百行？

没错，这里有一个扎心的事实：

你用Kubernetes很多年了，却根本不了解它是如何实现自身拓展的。

这些：

• Argo CD的Application

• KEDA的ScaledObject

• Crossplane资源

• cert-manager的Certificate

它们本质上都是同一个东西：自定义资源定义（CRD）

大多数人以为Kubernetes只是：

• Pod

• 部署

• 服务

然而，这只是表面现象。

底层的真相是：

Kubernetes不是一个平台，而是一种语言。

那CRD是什么？

CRD让你给这门语言添加新词汇。

好好想想：

你不是在“扩展”Kubernetes，你是在教它新的名词。例如：

• DatabaseCluster

• MLModel

• TenantConfig

一旦定义完成，它们就变成：

• 一级API对象

• 可通过kubectl查询

• 存储在etcd中

• 采用RBAC进行安全保护

• 像原生资源一样被监控

你的构想，就此成为Kubernetes本身的一部分。

为什么这一点能颠覆一切？

大多数教程都忽略了这一点：

CRD不只是一项功能，它是整个云原生生态的基石。

你欣赏的每一款成熟的Kubernetes工具，都构建在它之上。

不是插件，不是黑科技。

仅仅是......一些新的名词而已。

我们来创建一个真实的例子：

DatabaseCluster，用于管理PostgreSQL或云数据库的抽象概念。

只需要关注以下3个核心点：

• group

• name

• version

apiVersion:  apiextensions.k8s.io/v1 
kind:  CustomResourceDefinition 
metadata: 
  name:  databaseclusters.infra.example.com   # 必须为：<复数>.<组> 
spec: 
  group:  infra.example.com         # 您的 API 组（例如 apps、batch、networking.k8s.io）
  scope:  Namespaced                # 或者：集群
  名称:
    复数:  databaseclusters       # kubectl get databaseclusters
    单数:  databasecluster      # kubectl get databasecluster my-db 
    kind:  DatabaseCluster          # 用于 YAML 清单
    shortNames: 
      -  dbc                        # kubectl get dbc 
  versions: 
    -  name:  v1alpha1 
      serving:  true                 # 此版本处于活动状态并接受请求
      storage:  true                # 此版本用于 etcd 中的持久化
      schema: 
        openAPIV3Schema: 
          type:  object 
          properties: 
            spec: 
              type:  object 
              properties: {}       # 我们将在下一步中填写
            status: 
              type:  object 
              properties: {}

分析一下其中的关键决策：

这一行代码：

名称: databaseclusters.infra.example.com

这不仅仅是一个名字。

这是一个API端点。

Kubernetes刚刚创建了：

/apis/infra.example.com/v1alpha1/databaseclusters

无需重启，无需安装插件，无需重建服务器。

你刚刚扩展了Kubernetes API。

范围：命名空间级（Namespaced） VS 集群级 （Cluster）

• 命名空间：资源位于命名空间内，绝大多数CRD属于此类。

• 集群：全局资源，用于集群级概念，例如 cert-manager 的 ClusterIssuer或基于角色的访问控制 (RBAC)中的ClusterRole。

服务（served）VS存储 （storage）

• served: true：该版本对外提供API服务。

• storage: true：该版本数据持久化存储到etcd，有且仅有一个版本可设为storage: true。

这种分离是实现安全多版本CRD的关键：可以同时提供v1 和 v1alpha1版本的API服务，但只存一份v1到etcd中。

注意：不做版本控制直接改schema会破坏现有资源。

很多人在这里搞混。

必须明确：CRD只定义意图，不执行任何动作。

它不会：

• 创建Pod

• 供应数据库

• 扩缩工作负载

一句话总结：

• CRD = 词汇

• Operator = 动作

如果没有控制器，执行以下命令：

kubectl get dbc

只会查到一堆静静躺在那儿的对象。

就这么一直等着，什么也不会发生。

让我们使其达到生产级别。

定义：

• 必填字段

• 校验规则

• 枚举

• 默认值

# database-cluster-crd.yaml 
apiVersion:  apiextensions.k8s.io/v1 
kind:  CustomResourceDefinition 
metadata: 
  name:  databaseclusters.infra.example.com 
  annotations: 
    controller-gen.kubebuilder.io/version:  v0.14.0 
spec: 
  group:  infra.example.com 
  scope:  Namespaced 
  names: 
    plural:  databaseclusters 
    singular:  databasecluster 
    kind:  DatabaseCluster 
    shortNames: 
      -  dbc 
  versions: 
    -  name:  v1alpha1 
      serve:  true 
      storage:  true 
      # 启用状态子资源（对运维人员至关重要）
      subresources: 
        status: {} 
      # kubectl get dbc 输出中显示的自定义列
      additionalPrinterColumns: 
        -  name:  Replicas 
          type:  integer 
          jsonPath:  .spec.replicas 
        -  name:  Region 
          type:  string 
          jsonPath:  .spec.region 
        -  name:  Phase 
          type:  string 
          jsonPath:  .status.phase 
        -  name:  Age 
          type:  date 
          jsonPath:  .metadata.creationTimestamp 
      schema: 
        openAPIV3Schema: 
          type:  object 
          properties: 
            spec: 
              type:  object 
              required: [ "engine" , "replicas" , "region" ] 
              properties: 
                engine: 
                  type:  string 
                  enum: [ "postgres" , "mysql" , "mariadb" ] 
                  description:  "要使用的数据库引擎" 
                replicas: 
                  type:  integer 
                  minimum:  1 
                  maximum:  9 
                  description:  "数据库副本数" 
                region: 
                  type:  string 
                  description:  "AWS 区域或数据中心位置" 
                storageGB: 
                  type:  integer 
                  minimum:  10 
                  default:  20 
                  description:  "存储大小（GB）" 
                version: 
                  type:  string 
                  description:  "数据库引擎版本（例如，PostgreSQL 的 '16.2'）" 
            status: 
              type:  object 
              properties: 
                phase: 
                  type: 字符串
                  描述： “当前生命周期阶段：待处理、配置中、就绪、失败”
                端点：
                  类型： 字符串
                  描述： “集群就绪后的连接端点”
                条件：
                  类型： 数组
                  项：
                    类型： 对象
                    属性：
                      类型：
                        字符串 状态
                      ：
                        类型： 字符串
                      lastTransitionTime：
                        类型： 字符串
                        格式： 日期时间
                      原因：
                        类型： 字符串
                      消息：
                        类型： 字符串

• 没有schema：Kubernetes几乎可以接受任何格式。

• 有schema：Kubernetes变成第一道防线。

无效的配置根本触及不了Operator。

将其应用到集群：

kubectl apply -f database-cluster-crd.yaml 


# 验证是否已注册
kubectl get crd databaseclusters.infra.example.com 


# 创建于
# databaseclusters.infra.example.com 2026-03-31T16:00:00Z

应用此配置之后，Kubernetes会立即注册新API端点，无需重启。

现在CRD已经存在，你可以创建它的实例，就像创建任何其他Kubernetes对象一样：

# my-postgres.yaml
apiVersion: infra.example.com/v1alpha1
kind: DatabaseCluster
metadata:
  name: production-postgres
  namespace: databases
spec:
  engine: postgres
  replicas: 3
  region: ap-south-1
  version: "16.2"

应用与操作：

kubectl apply -f my -postgres.yaml 


# 像操作任何原生资源一样操作它
kubectl get dbc -n databases 


# NAME REPLICAS REGION PHASE AGE 
# production-postgres 3 ap-south-1 <none> 10s


 kubectl describe dbc production-postgres -n databases 
kubectl delete dbc production-postgres -n databases

你不再只是简单使用Kubernetes，而是在塑造它的API体系。

此时Phase列为 <none>，因为没有控制器更新状态。

注意：仅有CRD而没有控制器，是没有任何作用的。

此图展示了CRD在Kubernetes架构中的完整生命周期：

• 应用DatabaseCluster YAML

• API server 按 OpenAPI schema 校验

• 存入etcd

• 一个controller监视它

• controller让实际状态匹配你的期望状态

Kubernetes 并非在执行 YAML，它是在调和你的意图。

一旦你理解了这一点……

其它一切：operators、controllers、自动化等等，都变得显而易见了。

这一点能区分新手与平台工程师。

添加：

subresources:
  status: {}

现在，神奇的事情发生了。

• 如果没有它：任何人都能覆盖系统状态

• 有了它：只有Operator能修改实际状态

想想看：

• spec：用户定义期望状态

• status：Operator上报真实状态

并且Kubernetes在API层强制执行这种分离。

这不是惯例，而是架构层面的强制性规定。

在你的Python operator中，将像这样更新status ：

只有操作员才能写入 /status — 用户无法覆盖此设置
。patch.status[ 'phase' ] = 'Ready'
 patch.status[ 'endpoint' ] = f"postgres. {name} .svc.cluster.local:5432"

status包含两种类型的信息：

1）简单字段（实际是什么？）

这些字段回答：“当前状态是什么？”

2）条件数组（健康状况如何？）

这些条件回答：“一切正常吗？当前情况如何？”

一个condition就像指示每个方面的交通信号灯。

先来了解如何使用官方kubernetes Python client与自定义资源进行交互。这一方法适用于脚本编写、CI流水线以及数据迁移任务。

# pip install kubernetes
 from kubernetes import client, config 


 # 加载 kubeconfig（如果运行在 pod 中，则加载集群内配置）
 config.load_kube_config() 


 # 使用动态客户端访问自定义资源
dyn_client = client.ApiClient() 
custom_api = client.CustomObjectsApi(dyn_client) 


GROUP = "infra.example.com"
 VERSION = "v1alpha1"
 PLURAL = "databaseclusters"
 NAMESPACE = "databases" 


 # 列出所有 DatabaseCluster 资源
clusters = custom_api.list_namespaced_custom_object( 
    group=GROUP, 
    version=VERSION, 
    namespace=NAMESPACE, 
    plural=PLURAL 
) 


for cluster in clusters[ "items" ]: 
    name = cluster[ "metadata" ][ "name" ] 
    phase = cluster.get( "status" , {}).get( "phase" , "Unknown" ) 
    replicas = cluster[ "spec" ][ "replicas" ] 
    print(f "{name}: phase={phase}, replicas={replicas}" ) 
# 以编程方式创建一个新的数据库集群
new_cluster = { 
    "apiVersion" : f "{GROUP}/{VERSION}" , 
    "kind" : "DatabaseCluster" , 
    "metadata" : { "name" : "staging-mysql" , "namespace" : NAMESPACE}, 
    "spec" : { 
        "engine" : "mysql" , 
        "replicas" : 1, 
        "region" : "ap-south-1" , 
        "storageGB" : 20, 
        "version" : "8.0"
     } 
} 


custom_api.create_namespaced_custom_object( 
    group=GROUP, 
    version=VERSION, 
    namespace=NAMESPACE, 
    plural=PLURAL, 
    body=new_cluster 
) 
print( "已创建 staging-mysql 数据库集群" ) 


#修补状态
（通常仅由操作员执行）
 status_patch = { "status" : { "phase" : "Provisioning" }} 
custom_api.patch_namespaced_custom_object_status( 
    group=GROUP, 
    version=VERSION,
    namespace=NAMESPACE, 
    plural=PLURAL, 
    name= "staging-mysql" , 
    body=status_patch 
)

这是原始的API交互层。

添加：

additionalPrinterColumns:

现在运行：

kubectl get dbc

输出示例：

名称 副本数 区域 阶段 时间
production-postgres 3 ap-south-1 就绪 2天
staging-mysql 1 ap-south-1 配置中 5个月

你刚刚把kubectl变成了一个仪表盘。

无需UI和额外工具，考的仅仅只是巧妙的API设计。

在构建自己的CRD之前，请避免以下情况：

• 没有 schema → 会接收无效或错误的输入数据

• 没有 status 子资源 → 用户可覆盖系统状态

• 破坏性修schema 变更 → 破坏现有资源

• 忘记写 Operator → 不会执行任何实际操作

大多数CRD问题不是Kubernetes本身的问题，而是API设计问题。

让我们把视角拉远一些。

这篇文章讲的不仅仅是YAML，而是了解Kubernetes的演进方式。

你学到了：

• 工具的实际构建方式

• API的扩展方式

• 平台的设计方式

更重要的是：

你不再只是Kubernetes用户，而是开始像平台工程师一样思考。

目前，你的CRD仍然存在一个缺陷。

任何人都可以这样操作：

副本数：0

而Kubernetes会照单全收。

在API服务器内部运行的验证规则：

不需要webhooks，不需要额外的服务。

仅仅只是靠API层面的强制约束。

假设你要创建一个系统，让用户可以通过声明式的方式定义数据库备份。他们不用写脚本，而是编写YAML文件即可。

用户想要输入的内容如下：

apiVersion:  backup.example.com/v1  
kind:  DatabaseBackup  
metadata: 
 name:  my-postgres-daily  
spec:  
 database:  "postgres-prod"  
 schedule:  "0 2 * * *"  # 每天凌晨 2 点
 执行 retention:  7  # 保留 7 个备份

请思考：

• 我希望备份按指定的计划执行

• 我希望保留指定数量的备份

还可以补充什么？

• 当前实际存在多少个备份？

• 上一次备份是什么时候？

• 上一次备份是成功还是失败？

• 还有哪些信息值得跟踪？

• 备份存储位置（S3、GCS、本地存储）？

• 备份类型（全量、增量）？

• 成功或者失败通知？

• 其它内容？