"Same person. Different era. The difference is the tooling."
人未变，时代已改。拉开差距的，全在工具。

——Garry Tan, Y Combinator 总裁 & CEO, 2026 年

卷首语用五个人的故事画出了一幅图景：Karpathy 半年没写代码，Amodei 预言 90% 代码将由 AI 完成，Garry Tan 的产出翻了 810 倍，Boris Cherny 不再写代码只审查代码，antirez 放下了亲手雕琢每一行的执念。这些信号指向同一个结论——软件工程正在经历自 1968 年这门学科诞生以来最深刻的一次范式转换。

本章建立理解这场变革所需的概念坐标。它是怎么一步步走到今天的？新旧范式之间真正的断裂在哪里？全书贯穿的那根主线——"用结构化知识驾驭非结构化 AI 能力"——是怎么来的？

1.1 软件工程简史: 一个假设的五十年

1968 年 NATO 软件工程会议上，"软件危机"被正式命名——项目失败、成本超支、交付延期——催生了"软件工程"这门学科。解决方案是用工程化流程约束创造力：阶段分解、评审关口、文档驱动。

此后半个多世纪，方法论不断演化。一个核心假设从未被挑战。

瀑布模型（Winston Royce, 1970）将开发划分为需求分析、设计、实现、测试、维护的严格线性阶段。Royce 本人的论文远比后来的教条版本微妙——他实际上提倡迭代（"do it twice"）——但瀑布作为一种管理模式被广泛采纳。它的核心前提是：需求可以在编码之前被完整地理解。

敏捷运动（Agile Manifesto, 2001）拆掉了瀑布的刚性阶段门。"个体和互动高于流程和工具，可工作的软件高于详尽的文档。"敏捷承认了需求会变，但保留了最底层的假设——写代码的人依然是写代码的人。所有的 Scrum 站会、Sprint 计划、用户故事，都建立在一个未经审视的前提之上：软件是由人类工程师一行一行写出来的。

DevOps 打破的是开发与运维之间的墙。CI/CD、基础设施即代码、容器化——这些运动将运维带入了工程视野。但它们同样没有触及那个核心信条。DevOps 优化的是"写完之后怎么办"，而不是"谁来写"。

最后这个假设——代码由人亲自编写——在 2023 年第一次动摇了。不是因为新的管理方法或流程改进，而是因为大语言模型。它能理解自然语言指令，自主探索代码库，执行完整的功能开发。它不是更聪明的自动补全。它在转移编程行为的主体。

1.2 AI Coding Agent 的四层演进

如果将 AI Agent 的能力演进放到时间轴上，可以看到四个清晰的阶段。每个阶段都在重新定义"编程"这个行为的含义——不只是效率的提升，而是人类和机器在编程活动中各自的角色发生了质变。

L2 对话：ChatGPT 改变了交互范式。程序员学会了"提问"——替代了查文档、搜 Stack Overflow。但代码仍然是程序员亲手写的。AI 是搜索引擎的替代品，不是代码的作者。

L3 任务：Claude Code 于 2025 年 2 月发布，同时 Cursor、Codex CLI、OpenCode 等工具将体验升级为"AI 帮你实现一个功能"。Agent 开始具备自主理解代码库、定位修改位置、执行多文件变更的能力。人类从"写代码的人"向"分配任务的人"滑动。

L4 自主流程：进入 2026 年，Agent 不再只是执行任务，而是开始管理流程——从理解需求到设计方案、实现代码、编写测试、创建 PR，一次会话走完整条链路。这正是卷首语中 Boris Cherny 描述的工作状态：他不再写代码，只审查代码。

从 L1 到 L4，变的不是 AI 能力的量，而是编程行为中主体的位置。L1 中人类是唯一主体。L4 中 AI 变成主动参与者，人类变成监督者和质量守门人。

1.3 Vibe Coding: 解放还是陷阱？

AI 让编程门槛降到了历史最低点。任何人——不管会不会写代码——都可以用一句话让 AI 生成一个能跑的应用。Andrej Karpathy 给这种现象取了一个生动的名字：Vibe Coding（氛围编程）。

这是解放，毫无疑问。但它也是一个精心包装的陷阱。

Vibe Coding 的典型模式：对 AI 说"给我做一个 todo app"→ AI 十几秒生成一整套代码 → "加一个暗黑模式"→ "加一个拖拽排序"。你甚至不需要知道 useState 是什么。你只要"vibe"就可以了。

陷阱在于：它拉高下限的同时，模糊了上限的存在。 当你不需要理解自己的代码如何工作，当你的应用在"看起来能运行"和"真正能在生产环境运行"之间存在巨大的鸿沟——Vibe Coding 的产物往往是一团不可测试、不可重构、不可理解的代码浆糊。

这就是 Karpathy 为什么特意区分了两个概念：Vibe Coding 与 Agentic Engineering（智能体工程）。前者的关键词是"放手"——把需求丢给 AI，接受它吐出的一切。后者的关键词是"掌控"——把 AI 视为极其强大但带有随机性和盲区的工具，通过结构化方法引导、约束、验证它的产出。

作为卷首语中详细展开过的论证，这里不再重复，但需要强调它的推论：AI 不会救你，它会放大你。 你给它清晰的架构，它还你整洁的代码；你给它模糊的意图，它还你一团浆糊。一个人用 AI 后的产出上限，是由他在没有 AI 时的工程素养决定的。Redis 创造者 antirez 用一周时间完成 DS4 项目——但他审查了 AI 生成的每一行代码。

这就是为什么，在 AI 让编码门槛降到历史最低点的时刻，工程化的价值反而达到了历史最高点。

1.4 核心主张: 从 Prompt-Driven 到 Skill-Driven

这就引出了全书最核心的概念转折。

过去两年间，一个洞见在不同的人和实践中反复出现、逐步收敛。它不是某个人独自发明的，而是社区在实践中达成的共识：Prompt 是临时的，Skill 是持久的。

当你对 AI 说"帮我做代码审查"，你能得到什么？一个审查结果。它的质量取决于你当时的表达、AI 当时的理解、对话上下文的完整度。改天再做一次，结果可能完全不同。Prompt 消失在对话历史里——不可复用、不可迭代、不可积累。

而一个 Skill——比如 /review-it——是一个结构化指令文件，定义了什么算好的审查、审查哪些维度、遇到每种问题怎么处理。它可以在不同项目、不同时间、对不同的代码重复使用。每次使用都是一次验证机会，如果出现偏差，你可以改进 Skill 本身，让下一次更好。Skill 留在你的工具链里——可复用、可迭代、可积累。

"对话一次"和"建立一个系统"之间的区别，就是一位 AI 时代的合格工程师和一位"vibe coder"之间的区别。

也正是在这个意义上，四个层次构成了一个递进：Prompt Engineering 让 AI 理解意图（一次性对话）→ Skill Engineering 让能力可复用（持久化方法论）→ Agent Orchestration 让多个 Agent 协同（编排调度）→ Harness Engineering 让整个系统安全可控（运行环境与权限）。每一层建立在前一层基础上。Skill Engineering 处于"从临时到持久"的转折点上——它不是让 AI 变得更聪明，而是让使用 AI 的人变得更体系化。

这引出了全书的核心理念：

在 AI 时代，软件工程的核心竞争力不再是"你能写多快的代码"，而是"你能不能构建一套让 AI 高质量产出的方法和系统。"

这套系统应具备五个特征：可复用、可验证、可迭代、可组合、不依赖特定模型。

围绕这些原则，一个全新的方法论生态已经生长出来。以下方法论将在本书第一部分逐一展开：

1.5 本章小结

我们正站在软件工程史上一个罕见的转折点上。上一次这种量级的改变，要追溯到 1968 年——当这门学科本身被命名时。

这次转折有三个核心特征：

第一，编程行为的主体正在转移。五十年来的第一次，不是人类在敲键盘。人类从"作者"变成了"指挥者"，再变成"审查者"。

第二，速度和质量之间出现了新的张力。AI 让写代码极快，但验证代码的速度远远跟不上。Vibe Coding 是解放，也是陷阱。工程化不是减速带，而是让你高速行驶时不翻车的底盘。

第三，方法论的价值超过了工具本身。工具每天都在变。但"用结构化知识驾驭非结构化 AI 能力"的原则不会变。Skills 系统、Spec-Driven Development、闭环工作流——这些不是某个具体工具的说明书，而是在任何 AI 工具上都能成立的工程原则。

从下一章开始，我们将逐一展开这些方法论。但在进入细节之前，请记住本章最核心的那个判断：

AI 不会救你，它会放大你。在 AI 时代，你的工程素养不是变得不重要了，而是第一次变得如此重要。

"I don't think I've typed like a line of code probably since December, basically, which is an extremely large change."
从去年十二月起，我基本上一行代码都没写过，这是一个巨大的变化。

——Andrej Karpathy，No Priors 播客，2026 年 3 月

半年没写一行代码

2026 年春天的一个午后，Andrej Karpathy 坐在播客录制间里，用他标志性的、几乎不带任何修辞起伏的语调，说出了一句让整个软件行业安静下来的话。

他已经半年没有亲手写过一行代码了。

不是两周，不是一个月。是从去年十二月开始，一天都没有。

在任何一个其他时代，这句话如果出自一位顶尖程序员之口，只意味着一件事：他离开了这个行业。但 Andrej Karpathy——OpenAI 联合创始人、前特斯拉 AI 总监、计算机视觉领域最具影响力的研究者之一——并没有离开。恰恰相反，他正处在职业生涯中产出最高的时期。他以自然语言驱动 AI Agent，完成从创业项目到开源探索的全部开发工作——一人之力推动着过去需要一个完整团队才能完成的迭代节奏。英语成了他新的编程语言，而 AI 成了他的编译器。他只是不再亲手写代码了。

这是一个关于杠杆的故事。

2026 年 5 月 19 日——Karpathy 宣布了一个消息：他加入了 Anthropic。 "我认为未来几年在 LLM 的前沿将会特别具有塑造性，"他写道，"我非常兴奋能加入这个团队，重新回到研发工作中。我仍然对教育充满热情，并计划在适当的时候继续我的相关工作。"这个消息之所以意味深长，不在于一个人换了东家——而在于这位"半年没写一行代码"的工程师选择加入的公司，正是 Claude Code 的缔造者，而他返回的还是软件开发的前线。从 OpenAI 到特斯拉到独立探索，再到 Anthropic，他的轨迹恰好画出了 AI 软件工程从实验室到产品、从工具到基础设施的完整弧线。

在那期播客以及随后的多次深度访谈中，Karpathy 展开了一幅比他那句名言本身更为深邃的思想图景。他将软件工程的历史划分为三个时代——软件 1.0、软件 2.0、软件 3.0——并以此解释了他所看到的这场变革的本质。

软件 1.0 是人类编写明确的代码规则。你告诉机器每一步怎么做，机器照做。这是过去半个多世纪的编程范式。软件 2.0 是人类通过创建数据集来训练神经网络，让模型从数据中学到规则。这是过去十年的深度学习范式。而软件 3.0，Karpathy 说，编程变成了**提示（Prompting）**本身——上下文窗口成了控制这个新型计算设备（LLM）的杠杆。他说，LLM 已经不再是传统意义上的"程序"，而是一种全新的计算机：你输入一段文本，它输出一段文本，但这中间执行的是人类无法逐行追踪的、基于大规模统计模拟和强化学习的涌现计算。他称之为 "召唤幽灵"——我们构建的不是具有动物般内在动力的智能体，而是基于统计模式的模拟产物。它们能在瞬间重构十万行代码或发现零日漏洞，却会在常识问题上给出荒谬的建议。它们的智能是"参差不齐的"（Jagged Intelligence）：在可验证的领域（编程、数学）突飞猛进，因为强化学习能给明确的验证奖励；而在不可验证的领域，它们依然脆弱。

正是基于这种认识，Karpathy 提出了一个他亲自命名的概念区分："氛围编程"（Vibe Coding）与"智能体工程"（Agentic Engineering）。 Vibe Coding 的意义在于「拉高下限」——它让任何人，无论是否具备专业背景，都能让 AI 生成一个能跑的应用。这是一种民主化，也是一种诱惑。但 Agentic Engineering 的核心是「守住上限」——它是一门新的工程学科，要解决的问题是如何协调那些强大但带有随机性、容易出错的 AI 智能体，在不引入漏洞、不牺牲质量的前提下大幅提升开发速度。

Karpathy 的措辞很克制，但判断很锋利：掌握 Agentic Engineering 的工程师带来的效率提升，将远远超越过去所谓的"10 倍工程师"。

这意味着人类的角色将发生根本性的重塑。开发者不再需要死记硬背 PyTorch 的张量维度或 NumPy 的 API 细节——这些都可以放权给拥有"完美记忆力"的 AI 智能体。但放手细节的同时，人类必须提升另一个维度的能力：品味、判断力、架构直觉、系统审美。人类与智能体共同制定详细的规格说明，然后智能体来填充底层实现。Karpathy 用了一个工业时代的比喻来总结：人类不再是打字员，而是工头。

但他说出的最重要的一句话，也许是这句旁人转述给他的格言："你可以外包你的思考，但不能外包你的理解力。"机器可以生成代码、总结文档、分析数据，但人类始终是那个决定"为什么要建这个系统"和"如何指导智能体"的人。利用 AI 工具来增强自身的理解力，而不是用 AI 来替代自身的思考——这才是 Agentic Engineering 的终极壁垒。

从软件危机到智能体崛起

过去两年间，软件工程领域发生的变化，比过去二十年加起来还要剧烈。这不是修辞。这是一场从「工具辅助人类」到「人类指导工具」的根本性反转——程度的加深叠加方向的逆转。

时间线拉长一些，才能看清这件事的历史分量。

1968 年，北大西洋公约组织在德国加米施召开了后来被载入史册的 NATO 软件工程会议。在那次会议上，"软件危机"（Software Crisis）作为一个正式术语被提出——软件项目的失败率居高不下，成本超支成为常态，交付日期一再推迟。那次会议催生了"软件工程"这个学科本身。当时的解决方案是用工程化的流程约束创造力：瀑布模型、需求规格、阶段评审、文档驱动。

半个多世纪以来，这个基本框架没有变过。敏捷运动拆掉了瀑布的刚性阶段门，但保留了"人写代码、流程管质量"的核心假设。DevOps 打破了开发与运维的墙，但写代码的人依然是写代码的人。

直到 AI 编码 Agent 的出现。

2022 年，GitHub Copilot 让程序员第一次体验到了"AI 帮你写下一行"的感觉——它是一个聪明的自动补全工具。2025 年，Claude Code、Codex、Cursor、OpenCode 等一系列工具将这种体验升级为"AI 帮你写一个函数"。到了 进入 2026 年，这些工具已经进化为能够自主理解整个代码库、管理完整开发流程、甚至学习私有 API 和内部框架的工程 Agent。

变化的斜率不是线性的。它在加速。

先行者们看到了同一件事

Andrej Karpathy 不是唯一一个感受到这场震荡的人。如果你仔细聆听，你会发现来自不同背景、不同时代、不同编程哲学的声音正在汇成同一个和弦。

2025 年，Anthropic 的 CEO Dario Amodei 在一次公开访谈中给出了一个让很多人不以为然的预测：AI 将在三到六个月内编写 90% 的代码，十二个月内编写几乎全部代码。批评者说这是营销。投资者说这是讲故事。但到了 2026 年，这个预测正在被一个又一个的数据点验证。Claude Code 的用户不仅仅是"使用 AI 辅助编码"——他们在与一个能够自主探索代码库、提出架构方案、执行完整功能开发的 Agent 协作。人类工程师的角色正在从"写代码的人"转变为"定义目标、审查产出、做架构决策的人"。

Y Combinator 总裁兼 CEO Garry Tan 用一个对比数字让整个硅谷沉默了。他公开了自己作为同一个工程师、同样高强度工作状态下，2013 年和 2026 年的 GitHub 贡献数据：2026 年的逻辑代码行产出是 2013 年的 八百一十倍。这不是百分比增长，这是数量级的跃迁。他在全职运营 Y Combinator 的同时，用自己开发的 gstack 方法论，在六十天内交付了三个生产级服务和四十多个功能。他自己这样说："Same person. Different era. The difference is the tooling."同样的人，不同的时代。差别只在于工具。

Garry Tan 的数字让人震撼。2026 年 5 月的硅谷 AI Ascent 大会上，Claude Code 的缔造者 Boris Cherny 给出的画面则让人恍惚。Cherny——Anthropic 的工程负责人（Engineering Lead）、Claude Code 的创造者——走上台，平静地描述了他现在的日常工作：他不再写代码。他审查代码。 他曾经同时运行大约一千个 AI Agent，并在一天之内合并了一百五十个拉取请求。今天的开发者，Cherny 说，本质上是一支临时工模型大军的"工程经理"。

但 Cherny 也没有回避最棘手的问题：AI Agent 编写补丁的速度，已经远远超过了人类组织验证它们的能力。 这就是"验证差距"（Verification Gap）。模型经常在工作真正完成之前表现得"非常自信"——你既不能完全不信任 Agent，那样你会失去速度；也不能完全信任 Agent，那样你会失去质量。他给出的答案简洁得近乎冷酷：委派任务前的判断力，给予信任前要求证据的能力，合并代码后的责任感。 敲击键盘的速度和记忆 API 的数量不再重要。判断力、验证力、责任感才是新的硬通货。这三项能力构成了 AI 时代工程师的新技能栈。

但也许最令人动容的转变来自 Redis 的创造者 Salvatore Sanfilippo——社区里人们叫他 antirez。在程序员群体中，antirez 代表了一种几乎已经消失的浪漫：他相信每一行代码都应该经过人手的雕琢。他曾经写道："I love writing software, line by line. My career was a continuous effort to create software well written, minimal, where the human touch was the fundamental feature."他热爱一行一行地写代码。他的整个职业生涯都在追求一种极简的、充满人性触感的软件美学。

然而，就是这个人，在 2025 年坦承："Facts are facts, and AI is going to change programming forever."事实就是事实，AI 将永远改变编程。

antirez 没有选择抵制。他选择理解。他提出了一个至关重要的概念区分——"Automatic Programming"（自动编程）与 "Vibe Coding"（氛围编码）是两回事。Vibe Coding 是把需求丢给 AI，接受它吐出的一切，不做审查，不做设计。而真正的 Automatic Programming 需要人类的直觉、设计判断、持续引导和对软件系统的深刻理解。AI 是放大器，不是替代品。他用 AI 在一周内完成了 DS4 项目的开发，让它成为了当时最流行的本地 AI 体验工具。但他审查了 AI 生成的每一行代码，做出了每一个关键架构决策。

AI 放大了一切——包括你的工程缺陷

这些声音——Karpathy 的平静陈述、Amodei 的大胆预测、Garry Tan 的冰冷数据、Cherny 的工程坦率、antirez 的审慎拥抱——来自完全不同的方向，却指向同一个结论：**软件工程的范式正在发生五十年之变。**一个人的产出可以等于过去一个团队。自然语言正在成为最强大的编程接口。写代码这项技能，正在从"必须自己动手"变成"必须自己动脑"。

但如果你仔细听，在这些声音下面，有一个更深层的矛盾正在浮出水面。

AI 让"写代码"变得前所未有的容易，却让"写好软件"变得前所未有的困难。

任何人都可以用一句话让 AI 生成一个能跑的应用。这就是 Vibe Coding 的诱惑：你不需要理解数据结构，不需要考虑边界条件，不需要设计错误处理——你只需要说"给我做一个"。AI 会给你一个。它甚至看起来还不错。但当这个应用需要维护、需要扩展、需要与团队协作、需要经受生产环境的流量冲击时，Vibe Coding 的产物往往暴露了它的本质：一团不可测试、不可重构、不可理解的代码浆糊。

AI 可以让你以一百倍的速度写出代码。它也可以让你以一百倍的速度积累技术债务。AI 可以让你一小时交付一个原型。它也可以让你一周后完全无法理解自己的代码做了什么。AI 不会救你——它会放大你。你给它清晰的架构，它还你整洁的代码；你给它模糊的意图，它还你一团浆糊。它暴露你的工程能力，也同等精确地暴露你的工程缺陷。

这就是为什么，在 AI 让编码门槛降到历史最低点的时刻，工程化的价值反而达到了历史最高点。

当开发速度不再稀缺，工程化就是最后的壁垒

如果你的木工房里突然出现了一把能以一百倍速度切割木材的激光刀，你最需要的是更精确的测量工具、更严格的工艺流程、更可靠的安全护栏——而不是更快的刀。软件工程同理。当执行的速度被 AI 提升到前所未有的高度时，决定质量的是执行之前的规划、执行之中的约束、执行之后的验证。执行本身不再稀缺。

这正是过去两年间涌现的一系列新方法论试图解决的问题。

Matt Pocock——TypeScript 社区最受尊敬的工程教育家之一——提出了 Skills 系统的概念。他的核心洞见：Prompt 是临时的，Skill 是持久的。你不需要每次都对 AI 解释"如何做代码审查"，你只需要给它一个 Skill。/diagnose 系统化调试、/grill-me 启动前对齐、/tdd 红-绿-重构——每一个 Skill 都是针对 AI 编程中特定失败模式的工程化解药，小而聚焦，模型无关，鼓励改造。

如果说 Skills 解决的是"单次交互的质量"，那么 Spec-Driven Development 解决的就是"跨次交互的一致性"。OpenSpec 和 Spec-Kit 代表的 SDD 方法论将规格文档变成了人类与 AI 之间的一份"合约"——在写代码之前先写规格，你不需要审查 AI 的每一行思维过程，你只需要审查它在规格层面是否履约。

Ralph Loop 将这个逻辑推到了极致：让 AI Agent 在循环中持续改进自己的代码，直到满足验收标准为止。Frank Bria 设计的双条件出口门机制要求 AI 既要说「我做完了」，还要显式发出退出信号。因为 AI 的自我评估不可信，需要多重验证。

Garry Tan 的 gstack 则展示了一种完全不同的想象力：将 Claude Code 变成一个拥有二十三个专家角色的虚拟工程团队。CEO 审查战略、工程经理审查架构、QA 审查质量、安全官审查漏洞——整个 Sprint 从 Think 到 Reflect 被构建为一条七阶段审查流水线。一个人就是一支军队。

superpowers 框架——全球已获超过十五万颗星标——将这些 Skills 组织成了一整套方法论库。而 jnMetaCode 的中文增强版 superpowers-zh，则为中国开发者补充了国内代码托管平台适配、中文排版规范、Conventional Commits 本地化等原创能力。

这些方法论背后的共同逻辑是什么？

用结构化知识驾驭非结构化 AI 能力。

Prompt 消失在对话历史里，Skill 留在你的工具链里。Vibe Coding 的产物不可复现，Spec-Driven 的产出有据可查。一次性的 AI 对话无法保证质量，闭环工作流让每一次产出都经过验证。

为智能体构建运行环境

2025 年末，一个被称为"Harness Engineering"的新概念开始在 AI Agent 开发者社区中流传。它的核心关注点不是写 AI 模型，不是做产品功能，而是构建编码 Agent 的底层运行基础设施——工具系统、权限模型、hooks 机制、配置管理层级。社区逐渐认识到：如果说 Prompt Engineering 是"教会 AI 说什么"，Skill Engineering 是"教会 AI 做什么"，那么 Harness Engineering 就是"为 AI Agent 构建安全可靠的运行环境"。

这是一个信号。它意味着 AI Agent 的开发正在从一个"试试看"的实验阶段，进入一个需要专业工程实践的成熟阶段。正如游戏引擎架构之于游戏开发、编译器设计之于语言工具开发，Harness Engineering 正在成为 AI Agent 产品开发中的专门工程领域。它代表了从"能用的 Agent"到"可靠的 Agent 产品"之间那条必须跨越的工程鸿沟。

关于这本书

我是一名在软件工程领域工作了近30年的程序员。过去两年里，我和许多同行一样，眼睁睁看着自己熟悉的那个世界——手写代码、逐行调试、Code Review——被 AI 一步步重构。我参与了多个 AI 驱动的开源项目，也亲手构建了一套名为 Goal Workflow 的 AI 研发工作流技能集。这本书中的每一个方法论，我都亲自实践过；每一个结论，都来自真实的项目迭代而非纸上推演。

这本书的写作动机，正是源于上述所有这些变化的交汇点。

全书分为三个部分。

第一部分——原理篇（第 1–11 章）——是全书的主体。我们从软件工程范式的五十年之变出发，逐一考察当前最具代表性的方法论：Matt Pocock 的 Skills 系统、OpenSpec 与 Spec-Kit 的规格驱动开发、Ralph Loop 的自主循环引擎、Garry Tan 的 gstack 虚拟团队方法、superpowers 技能框架、autoresearch 的全自动化开发流程，以及 Goal Workflow 的目标驱动研发闭环。然后将这些方法论放在一起对比、碰撞、融合。在此基础上，我们深入 Harness Engineering——为 AI Agent 构建安全可控运行环境的专门工程领域，以及用 Kanban 编排 AI Agent 项目的实践。这一部分帮助你构建属于自己的 AI 研发体系。

第二部分——技能篇（第 12–17 章）——聚焦 AI 软件工程的实用技能与工具链。我们考察 Anthropic 官方插件如何为 Agent 注入领域知识与工程工作流，Understand-Anything 如何构建代码知识图谱，UML 在理解 AI 生成代码中的新用途，AI 时代的重构方法论，Go 语言的 AI 开发工具链，以及 autoreview 与 Crabbox 带来的自动化代码审查与远程验证。这一部分是从方法论到日常工程实践的桥梁。

第三部分——实战篇（第 18–23 章）——以一个真实的 Go 语言项目 goscapy 为载体，完整演示前两部分的方法论和技能在真实项目中的落地执行。从项目背景理解到 PRD 规划，从 /goal 迭代实现到 /review-it 自动化审查，从 /ship-it 交付合入到 Bonus Skills 的增强工具链——每一步都是实战，每一步都有真实代码和真实决策。goscapy 是一个纯 Go 实现的网络协议库，多协议支持、跨平台兼容，在生产环境中运行。这不是一个玩具项目。

但需要说清楚的是：这不是一本「如何使用 AI 工具」的操作手册。工具每天都在变。今天的 Claude Code 明天就不长这样，后天又会出现全新的工具形态。这是一本关于「如何在 AI 时代思考软件工程」的方法论著作。

声明式编程的古老智慧

回到 Karpathy。

在那期播客里，除了那句被广泛引用的"半年没写一行代码"之外，他还说了另一句话，没那么出名，但同样重要。他说，使用 AI 编程的体验让他想起了一个古老的计算机科学概念：声明式编程。你不需要告诉计算机"怎么做"，你只需要告诉它"要什么"。

SQL 是声明式的——你说"给我这些列、从这个表、满足这些条件"，数据库引擎自己决定执行计划。在 AI 时代，整个软件开发正在变成声明式的：你说"给我一个支持多协议、高并发、跨平台的网络包处理库"，AI Agent 自己决定架构、选择模式、实现细节。

但声明式编程有一个前提：声明本身必须是精确的。模糊的 SQL 查询返回模糊的结果。模糊的需求描述产生模糊的软件。

这就是为什么，在 AI 可以帮你写出一切的时代，知道"要什么"比知道"怎么做"更重要。而"知道要什么"——定义清晰的验收标准、设计合理的架构约束、建立可验证的质量门——正是软件工程这门学科用半个世纪沉淀下来的核心能力。

这些能力从来没有过时。它们只是在等待一个让它们变得至关重要的时刻。

那个时刻就是现在。

欢迎来到 AI 时代的软件工程。

本文带你走一遍 LLM 的工作原理。现代 LLM 大多是由 transformer 块反复堆叠而成的，因此理解了 transformer 机制，你就掌握了大部分。

我将覆盖现代基于 transformer 的 LLM 内部的核心机制，避开那些复杂的数学。别误会，你应该学数学，但本文可以作为一个入门。

大多数现代 LLM 共享同一套 transformer 家族的骨架。差异来自于各自的训练数据、规模和配置选择，以及在此之上的后训练。读完本文后，你应该能够阅读许多现代 LLM 论文或模型卡，并知道每个部分在讲架构中的哪个组件。

路线如下：

1. Token——一串文本如何变成一组整数序列
2. Embedding——这些整数如何获得含义
3. 位置编码——模型如何知道 token 的顺序
4. Attention——token 之间如何交换信息

5. 多头注意力——模型如何同时追踪多种关系
6. 前馈网络——模型存储结构的主要所在
7. 残差流与层归一化——是什么让深层堆叠可训练
8. 预测下一个 token——模型实际输出什么，以及生成循环如何运作
9. 架构 vs 训练权重——现代 LLM 之间广泛共享什么，以及什么不同

文中穿插了一些简短解释（tiny explainer），无论你的背景如何都能跟上。

Tokenization（分词）

模型不直接阅读文本。它们读取整数 ID。这一步将你的提示转换为一组整数序列。

这个转换步骤叫做 tokenization（分词）。一个 tokenizer（分词器）接收一个字符串并产生一组整数序列，其中每个整数指向固定词汇表中的一个条目。现代 LLM 的词汇表通常包含数万到数十万个条目。

简短解释：token ID
token ID 是模型用于某个词汇表条目的整数。模型处理的是数字，而不是书写的单词本身。

Token 通常不是完整的单词。它们通常是子词片段。单词 "tokenization" 可能被拆分为 ["token", "ization"]。"running" 可能被拆分为 ["run", "ning"]。原因在于效率。全词词汇表太大，且无法泛化到新词。字符级词汇表又太小，迫使模型从零开始学习最简单的模式。子词分词则处于中间地带。最常见的片段成为单独的 token，罕见或新颖的词则由更小的片段组合而成。

简短解释：词汇表（vocabulary）
词汇表是分词器的固定片段列表。每个片段有一个 ID，模型只能直接接收来自该列表的 ID。

这种权衡在意想不到的地方表现出来。经典例子：问 LLM "strawberry" 中有几个 R。LLM 过去常常回答错误。这不是模型不会计数。而是模型不直接操作字母，它只操作那些恰好拼写出一个单词的 token ID——而这个单词人类会逐字母拆分。

不同的模型家族使用不同的分词器。GPT 模型使用 BPE（Byte Pair Encoding）变体。SentencePiece 在 LLaMA 风格的模型中很常见。选择影响计算量（更少的 token 意味着更少的工作）和多语言覆盖等，但基本形式相同：文本进，整数出。

现在提示已经是一组整数序列，下一步是赋予这些整数含义。

Embedding（嵌入）

一个像 1024 这样的 token ID 只是一个行索引。它本身没有任何意义。赋予它意义的是一个巨大的表，叫做嵌入矩阵（embedding matrix）。

每个模型都有一个。它对词汇表中的每个条目都有一行，每行是一个长长的数字向量。每行的长度就是模型的隐藏维度大小（hidden size）。在许多 7B 级别的模型中，这意味着每个 token 对应 4,096 个数字。更大的模型通常使用更宽的向量。

简短解释：向量（vector）
向量就是一个数字列表。在 transformer 中，每个 token 变成一个向量，这样模型就可以用它做数学运算。

当分词器把整数交给模型时，模型查找那一行并用向量替换它。那个向量就是 token 的嵌入（embedding）。它是模型对该 token "含义" 的表示，是在训练过程中学到的。

简短解释：嵌入矩阵（embedding matrix）
嵌入矩阵是一个查找表。token ID 进，学到的向量出。

这些嵌入的一个有趣特性是，语义上相似的 token 最终会得到相似的向量。"king" 的向量在空间中接近 "queen" 的向量，"Paris" 的向量接近 "France" 的向量。这一切都不是硬编码的。它是在足够多的文本上训练后涌现出来的，模型学会这些位置是因为它们能让模型更好地预测文本。

你可以对嵌入做算术运算，有时候确实有效。著名的例子是 king − man + woman ≈ queen。嵌入空间的几何结构携带着真实的语义结构，尽管没有人告诉模型要以这种方式构建它。

有一点需要明确：在这个阶段，每个 token 都被它的嵌入替换了，但嵌入本身不包含 token 在序列中的位置信息。"dog" 的向量无论在提示的第一个还是第五个位置，都是同一个向量。这是个问题。

这就是位置编码要填补的空白。

Positional Encoding（位置编码）

纯粹的 self-attention 没有内置的词序表示。没有某种位置信号，它无法直接知道 "dog" 在 "bites" 之前而不是之后。

词序会改变含义。所以模型需要另一个组件。它需要一种方式将每个 token 的位置注入到数学运算中。

简短解释：位置编码（positional encoding）
位置编码是模型获取顺序信息的方式。它告诉模型每个 token 在序列中的位置。

最初的 transformer 论文（Vaswani et al. 2017）的解决方案是给每个位置赋予自己的数字模式，并在任何其他处理之前直接加到每个 token 的嵌入上。位置 1 有一种模式，位置 5 有不同的模式，位置 100 有另一种模式。这些模式来自不同频率的正弦和余弦波。这样一来，位置 1 的 "dog" 的嵌入就不同于位置 5 的 "dog" 的嵌入，仅仅因为加在它上面的位置模式不同。

这能够工作，而且选择正弦编码的部分原因是它们可以外推到超出训练时见过的序列长度。但加法式的位置方案仍然有两个随着模型规模扩大而变得重要的问题。

首先，嵌入必须在同一组数字中同时承载含义和位置。能塞进去的东西是有限的。

其次，尤其是学到的绝对位置嵌入（learned absolute position embeddings）不能干净地泛化。如果你训练的提示最长 2,048 个 token，模型在训练时从未见过位置 5,000，那个位置的嵌入就不是以同样的方式学到的。

现代模型大多使用一种不同的方案，叫做 Rotary Position Embeddings（RoPE），由 Su et al. 于 2021 年提出，现在被 LLaMA、Mistral、Gemma、Qwen 和大多数其他开源权重家族所使用。直觉是：RoPE 不是将位置信息加到每个 token 的向量上，而是将 Query 和 Key 向量旋转一个取决于 token 位置的角度。位置 1 的 token 转一个小的角度，位置 100 的 token 转一个更大的角度。当两个 token 在后面的 attention 中被比较时，重要的是它们 Query 和 Key 旋转的差值，这编码了它们相距多远。

简短解释：RoPE
RoPE 代表 Rotary Position Embeddings。它不是加一个位置向量，而是旋转 Query 和 Key 向量，使相对距离在 attention 中显现出来。

实际的优点是真实的。RoPE 自然地编码相对位置（这更接近 attention 实际需要的东西）。它能更好地泛化到更长的上下文。而且它不给模型增加新的参数。

即使有了好的位置编码，现代 LLM 仍然有一个已记录在案的"迷失在中间（lost in the middle）"问题（Liu et al. 2023）。它们使用长提示开头和结尾的信息比使用中间的信息更可靠。这就是为什么像"把重要上下文放在前面"或"在末尾重复关键信息"这样的提示工程技巧确实有用。模型并不是同等地使用你提示的每个部分。

有了 token 含义和位置都编码完成，下一个问题是：token 实际上如何交换信息？

Attention

这就是赋予这个架构名字的机制。Attention。

在每个 transformer 层内部，attention 做一件事。它让每个 token 查看它被允许看到的其他 token，并决定哪些对接下来发生的事重要。

它通过同时给每个 token 赋予三个角色来实现。每个 token 被转换成三个新的向量，称为 Query、Key 和 Value（Q、K、V）。

简短解释：Q、K、V
Query 表示"我在找什么"，Key 表示"我匹配什么"，Value 是匹配成功时被传递的信息。

• Query 问："我从其他 token 那里在寻找什么？"
• Key 说："这就是我提供给正在看我的 token 的东西。"
• Value 携带："这就是匹配发生时被传递的东西。"

同一个 token 同时扮演全部三个角色。Q、K、V 的变换是学到的矩阵，所以模型在训练过程中会弄清楚每个 token 应该寻找什么以及它应该提供什么。

匹配通过相似度分数来发生。每个 token 的 Query 与它被允许看到的每个 token 的 Key 进行比较，使用缩放点积（scaled dot product）。直观地说，这衡量了两个向量的对齐程度。缩放使得数字在 softmax 之前保持稳定。

简短解释：点积（dot product）
点积是一种简单的方法，用于给两个向量的对齐程度打分。对齐程度越高意味着匹配越强。

然后，匹配分数通过 softmax 转换为权重。Softmax 接收任意一组数字，将它们转化为总和为 1 的类概率分布。匹配分数更高的 token 获得更高的权重，然后用这些权重取 value 向量的加权平均。

简短解释：softmax
Softmax 将原始分数转化为加起来等于 1 的权重。大分数得大权重，小分数得小权重。

举个例子。考虑句子 "The cat that I saw yesterday was sleeping." 当模型处理 "was" 时，它需要弄清什么在睡觉。"was" 的 Query 向量与它被允许看到的 token 的 Key 向量进行比较。与 "cat" 的点积很高，因为模型已经学会像 "was" 这样的动词需要一个主语，而像 "cat" 这样的主语会产生与之对齐良好的 Key 向量。与 "yesterday" 的点积很低。Softmax 将这些分数转化为权重，"cat" 得到高权重，"yesterday" 得到低权重。然后模型对相应的 value 向量取加权和，所以 "cat" 的 value 主导了结果。"was" 的新表示现在主要由 "cat" 的 value 塑造。这就是几个位置之前的 token 如何成为被指代对象。

有一个 GPT 风格语言模型特有的约束，即它们从左到右生成文本。位置 5 的 token 只能关注位置 1 到 5。它不能关注位置 6、7、8 的 token，因为它们还没被生成。这叫做因果掩码（causal masking）。实现很简单：未来 token 的匹配分数低到经过 softmax 后权重几乎为零。

简短解释：因果掩码（causal masking）
因果掩码隐藏未来的 token。它阻止 decoder-only 语言模型在预测下一个 token 时向前偷看。

可解释性研究中最有趣的发现之一是关于一种专门的注意力头，叫做 induction head（归纳头），由 Anthropic 在 2022 年发现。这些头学会了在提示中发现 "A B … A" 这种模式，并预测接下来的会是 B。当模型第二次看到 "A" 时，归纳头回溯到上一次 "A" 出现的地方，看到它后面是什么，然后复制那个。它们是已知的最清晰的上下文学习（in-context learning）机制之一——LLM 从你的提示中捕捉到一个模式并继续它的能力。

简短解释：归纳头（induction head）
归纳头是一种注意力头，它注意到提示中重复的模式并帮助延续它们。

Attention 有一个巨大的成本。在全注意力（full attention）中，每个 token 与它被允许看到的所有 token 比较，所以提示长度加倍，工作量大约翻四倍。这就是为什么长提示运行成本高，以及为什么最近很多研究都在关注让 attention 更高效（FlashAttention、稀疏注意力、线性注意力）。

但一个注意力头只给模型提供一种关于关系的学到的视角。

Multi-Head Attention（多头注意力）

一次 attention 传递给模型提供了一种决定哪些 token 对其他 token 重要的方式。这还不够。语言中有许多同时发生的关系。主谓一致。代词及其指代的名词。句子之间的长距离引用。词序和局部短语。

多头注意力通过并行地运行多次 attention 来解决这个问题，每个并行的传递在它自己较小的空间中操作。每个并行传递被称为一个头（head）。

简短解释：注意力头（attention head）
一个注意力头是一次独立的 attention 传递，拥有自己学到的投影。

这部分经常被描述错误——包括在大量教程中。每个头并不是获取原始 token 向量的字面切片。每个头有自己学到的投影矩阵，将完整的 token 向量映射到它自己较小的 Q、K、V 向量。所以如果一个模型每个 token 有 4,096 个数字和 32 个头，每个头通常在 128 维空间中工作，但那 128 个数字是完整 4,096 的学到的投影，而不是固定的切片。是同一 token 的不同"视角"，而不是它的不同分块。

每个头独立运行它的 attention 传递。然后所有头的输出被拼接（concatenate）起来，经过一个最终的线性层，将它们混合回一个完整大小的向量。模型也学习那个最终的混合。

有意思的是，不同的头往往最终部分地专门化。模型从未被告知每个头应该做什么。专门化是在训练中自然涌现的。研究人员发现了追踪语法的头（将动词连接到宾语、冠词连接到名词）、弄清代词指代哪个名词的头、追踪位置模式的头、归纳头，以及更多。一个 transformer 层可能有 32 个头。一个现代前沿模型有几十层。所以一个典型的 LLM 总共有数千个注意力头，每个都贡献自己学到的视角。

有一个实际的成本问题驱动了近期的架构变化。每个头需要将所有已生成 token 的 Key 和 Value 向量保存在内存中，这样当生成新 token 时模型不必从头重新计算所有内容。这叫做 KV 缓存（KV cache），它是在长上下文长度下运行 LLM 的主要内存成本。

简短解释：KV 缓存（KV cache）
KV 缓存在生成过程中存储旧的 Key 和 Value 向量。它省去了模型每增加一个 token 就重新计算整个提示的工作。

现代 decoder-only LLM 大多使用一种变体，叫做 Grouped-Query Attention（GQA）。不是每个头都有自己的 key 和 value，而是头分组共享相同的 key 和 value 头。LLaMA-2 70B 有 64 个 query 头但只有 8 个 key/value 头。Mistral 7B 有 32 个 query 头和 8 个 key/value 头。结果几乎是全多头注意力相同的精度，但内存压力和推理成本大大降低。

简短解释：GQA
Grouped-Query Attention 允许多个 query 头共享更少的 key/value 头。这在保持多个 query 视角的同时削减了 KV 缓存内存。

Feed-Forward Network（前馈网络）

在 attention 完成 token 之间的信息混合之后，每一层还有第二步，但谈论它的人少得多。前馈网络。

如果说 attention 是 token 之间互相交谈，那么前馈网络是每个 token 独立地做更多处理。它对每个 token 的向量独立运行，没有跨 token 的混合。

前馈网络按顺序做三件事：

1. 将 token 的向量扩展到更大的尺寸（原始 transformer 使用 4x，而现代 SwiGLU 模型通常使用不同的扩展尺寸）。
2. 应用一个非线性函数。
3. 将向量压缩回原始尺寸。

中间那个非线性步骤做了某件值得理解的具体事情。非线性是一个弯曲其输入的函数。最简单的，ReLU，对任何负数输出零，对正数原样传递。

简短解释：非线性（non-linearity）
非线性是一个函数，它阻止网络坍塌成一个大的线性变换。

没有它，FFN 只是两个线性层叠在一起，而堆叠纯线性数学会坍塌。两个线性层连续排列在数学上等价于一个线性层，一百层线性层连续排列仍然等价于一层。非线性阻止了这种坍塌，它是 FFN 能够做到比单次矩阵乘法更丰富的事情的原因。

原始 transformer 使用 ReLU。GPT 和 BERT 转向 GELU。现代模型如 LLaMA、Mistral 和 PaLM 使用 SwiGLU。扩展-然后-压缩的结构保持不变。被迭代改进的是非线性本身。

密集 transformer 模型的大部分参数都在 FFN 中，而不是 attention 中。大部分权重位于前馈层中。

而这些参数不是泛化的。它们承载了模型存储的大部分事实和语义结构。研究人员发现 FFN 内部的某些神经元与特定的概念或事实强烈关联。一个神经元可能在埃菲尔铁塔相关的文本上强烈激活。另一个在编程语言上。另一个在过去式动词上。当模型"知道"巴黎是法国的首都时，这个事实由特定层中的 FFN 权重和激活来表示。

这种存储记忆的特性有一个有趣的推论。研究人员已经弄清楚了如何在训练好的模型中直接编辑某些事实而无需重新训练。像 ROME（Rank-One Model Editing）这样的方法可以通过对特定 FFN 权重矩阵进行目标低秩编辑，将"埃菲尔铁塔在巴黎"改为"埃菲尔铁塔在罗马"。然后模型会倾向于生成与编辑后的关联一致的文本。

一些现代前沿模型已经开始用称为 Mixture of Experts（MoE）的东西替换密集 FFN。不是每层有一个前馈网络，模型有许多并行的 FFN（称为 experts），以及一个微小的路由网络来选择哪些 expert 处理每个 token。Mixtral 8x7B 每层有 8 个 expert；对于任何给定的 token 只有 2 个被激活。总参数量大幅增加，但每个 token 的计算量增长慢得多，因为只有少数几个 expert 在运行。这就是如何在不成比例地扩展推理成本的情况下扩展参数规模。

简短解释：MoE
Mixture of Experts 意味着模型有几个前馈网络，并将每个 token 只路由通过其中少数几个。

Mixtral 8x7B 总共有 467 亿参数，但每个 token 只用大约 129 亿。对于非常大型的模型，这已经成为一个常见选项，因为它让你在不断增加参数规模的同时不让推理成本成比例增长。

Residual Stream and Layer Normalization（残差流与层归一化）

残差流使得模型是"加法式"的而不是"替换式"的。在 attention 运行之后，或前馈网络运行之后，结果通常不替换 token 的向量。它被加到上面。逐个位置地加。新向量等于旧向量加上子块的输出。

简短解释：残差连接（residual connection）
残差连接将块的输出加回它起始时的向量。它为信息和梯度提供了通过网络的捷径。

跨越三十、五十或一百层，每层的贡献累积起来，而不是简单地覆写前一个向量。这个运行中的和被称为残差流（residual stream），它有一个奇特的性质。原始输入嵌入仍然有一条到达后面层的直接加法路径，与沿途每个子块的贡献混合在一起。

残差连接不是为 transformer 发明的。它们来自 ResNet（He et al. 2015），最初用于图像识别。动机是深层网络无法训练。训练信号在穿越许多层回来时变得太弱（或有时太强）。模型实际上无法从自己的错误中学习。添加一条捷径路径让信号直接从输出流回输入。突然间你可以训练有数百层的网络了。Transformer 继承了同样的技巧。

在现代可解释性研究中，残差流已经成为核心对象。每个组件——每个注意力头、每个前馈网络、甚至最后的反嵌入步骤——都从残差流读取并写回其中。

第二部分，层归一化（layer normalization），存在的原因要实际得多。没有它，残差流将无法保持稳定。流经数十次加法的数字倾向于要么爆炸式增长，要么坍缩到零。无论哪种情况，训练都会失败。层归一化在每个子块之间将每个 token 的向量重新缩放到一个受控的范围。

简短解释：层归一化（layer normalization）
层归一化重新缩放 token 向量，使其数字在模型训练期间保持在一个稳定的范围内。

原始 2017 年的 transformer 在每个子块之后应用归一化（post-norm）。这对于浅层模型有效，但随着深度增加变得更难可靠训练。现代 transformer（GPT-2 以后，LLaMA、Mistral）通常在每个子块之前应用归一化（pre-norm）。这是使得非常深的 transformer 更容易训练的变更之一。

归一化函数本身也变了。许多现代开源模型（LLaMA、Mistral、Gemma、Phi）使用一种更简单的变体，叫做 RMSNorm。原始层归一化同时做两件事：将每个向量向零平移，然后重新缩放数字的大小。RMSNorm 去掉了平移步骤，只保留缩放。经验上，缩放承载了大部分好处，同时计算成本更低。

简短解释：RMSNorm
RMSNorm 是一种更便宜的归一化方法，在不先减去均值的情况下重新缩放向量大小。

这就是那些不光彩的基础设施。没有残差连接，非常深的模型会变得极难训练。没有层归一化，运行中的和可能爆炸或坍缩。有了两者，你就能得到数百层深的模型。

Next-Token Prediction（下一个 token 预测）

在所有 attention 和前馈处理层完成之后，模型对序列中的每个 token 都有一个向量。在生成过程中，要预测下一个词，它只取最后一个 token 的最终向量。

那个最后的向量被转换为每个可能的下一个 token 对应一个数字。如果词汇表有 100,000 个 token，那就是 100,000 个数字。这些数字叫做 logits。它们还不是概率。它们可以是任何大小，正数或负数。

简短解释：logits
Logits 是每个可能的下一个 token 的原始分数。只有在 softmax 之后它们才变成概率。

Softmax 将这些 logits 转化为模型在可能的下一个 token 上的概率分布。和之前一样的操作，在模型中的不同位置。

模型通常不每次只选最高概率的 token。解码设置控制输出的确定性或多样性程度。Temperature 改变分布的尖锐程度。Top-k 和 top-p 将选择限制在最合理的一组下一个 token。这就是为什么同一个模型在一种设置下可以感觉精确，在另一种设置下可以更有创意。

简短解释：temperature
Temperature 控制采样期间的随机性。低 temperature 使模型更保守；高 temperature 使输出更多样化。

一旦选出一个 token，它就被添加到输入中。模型在更长的序列上运行下一步，通常重用 KV 缓存，这样就不必从头重新计算整个前缀。新 token 的新 attention。新前馈。新最终向量。新预测。循环继续，直到模型输出一个序列结束 token 或达到长度限制。一整段话就是这个循环，一次一个 token。

这个单一目标——预测下一个 token——是基础 LLM 的核心训练信号。基础模型不是被训练来做事实准确性、对话能力、推理或编程的。它被训练来预测海量文本中的下一个 token。之后的后训练才能将模型调整为指令遵循、偏好、安全性和对话行为。

有一个值得了解的重大效率创新。它叫做投机解码（speculative decoding）。一个小型快速模型提前提出几个 token。大模型并行地验证它们。如果提出的 token 在大模型的概率下被接受，就接受它们。如果没有，就回退到大模型。做得正确的话，输出分布与单独运行大模型一致，但循环可以快得多。

简短解释：投机解码（speculative decoding）
投机解码使用一个小型草稿模型向前猜测，然后让较大的模型一次验证几个猜测的 token。

下一个 token 预测循环是架构中最简单的部分，但它是让整个系统运作起来的东西。

Architecture vs Trained Weights（架构 vs 训练权重）

我们已经走过了核心机制：token、嵌入、位置编码、attention、多头注意力、前馈网络、残差流与归一化，以及输出侧的下一个 token 循环。这就是基本架构的一遍遍历。

那么 GPT、Claude、Gemini 和 LLaMA 之间实际有什么区别？公开细节各不相同，而闭源模型不会公布所有的架构选择。但在本文所覆盖的层面，它们大致处于同一 transformer 家族的设计空间之中。

大多数现代基于 transformer 的 LLM 使用相同的大致结构：分词、嵌入、位置编码、堆叠的 transformer 层（每层有多头注意力和前馈网络）、残差流、层归一化，以及下一个 token 预测。

模型之间的不同在于：

1. 训练权重本身——从不同的训练数据、在不同的规模上学习而来。
2. 配置：层数、词汇表大小、头数、参数量、MoE 还是密集。
3. 后训练：指令微调、基于人类反馈的学习、在基础模型之上应用的安全控制。

简短解释：权重（weights）
权重是模型内部学到的数字。训练会改变这些数字，直到模型能很好地预测文本。

2023-2025 年的"现代 transformer"技术栈在许多严肃的前沿和开源权重模型上收敛到了一组共同的选择，尽管不同的团队是独立达到这些选择的。Pre-norm 布局。RMSNorm。RoPE。SwiGLU。Grouped-Query Attention。在一些最大型的模型中使用 Mixture of Experts。这些都不是一次性发明的。它们是在原始 2017 年设计之上大约五年的精炼中累积起来的。

未来走向

Transformer 家族架构的收敛在机器学习历史上是不寻常的。在这个领域的大部分历史中，每个问题都有自己的专门网络。图像识别用一种。语言用另一种。音频用第三种。视觉和语言团队几乎不共享方法。

现在 transformer 风格的模型出现在语言、视觉、音频和多模态系统中。Transformer 吸收了该领域的很大一部分。

这可能会改变。Mamba 和其他状态空间模型是可信的替代方案，特别是对于非常长的序列。混合架构正在被探索。Mixture-of-Experts 已经以五年前会被认为是异域的方式改变了前沿上"架构"的含义。

但本文中的核心机制——token、嵌入、位置编码、attention、前馈网络、残差流与归一化，以及下一个 token 预测——是持久的部分。即使架构发生变化，这些也是任何序列模型必须以某种形式解决的问题。

如果你读到了这里，你现在可以阅读许多现代 transformer 论文或模型卡，并知道每个部分在讲哪个组件。这就是目标。

原文来源：0xkato, "How LLMs Actually Work", June 1, 2026, https://www.0xkato.xyz/how-llms-actually-work/

这些实验性特性有不同的形式：有时是标准库中全新的包，有时是编译器或运行时的改动，偶尔也可能是对 Go 行为的破坏性变更。

大多数情况下，实验性特性的目的是在某个功能正式进入 通用可用（general availability） 阶段、成为 Go 的永久组成部分之前，从用户那里获取真实世界的反馈。如果该特性导致性能退化，或收到社区的负面反馈，它可以在最终定稿前被修改——甚至被完全放弃。

一些示例

让我们看几个近期的例子，来说明 Go 实验特性可能涉及的内容类型。

• Go 1.24 发布时附带了新的 testing/synctest 包的实验性支持（该包提供了测试并发代码的支持）。在收到反馈后，该包的 API 略有调整，并在 Go 1.25 中正式进入通用可用阶段。

• Go 1.25 发布时附带了新的垃圾回收器设计的实验性支持，具有更好的性能。在吸收反馈之后，新的垃圾回收器在 Go 1.26 中成为默认选项。

• Go 1.21 发布时附带了循环变量语义行为变更的实验性支持。这一变更消除了 Go 代码中一个以前常见的 bug，但在技术上是对语言的破坏性变更。将该变更作为实验发布，让人们在 Go 1.22 中该行为成为默认之前有机会测试自己的代码。

实验特性的生命周期

实验特性并没有单一固定的生命周期，但有一些常见的模式。

大多数实验特性最初以**默认关闭（off-by-default）**的方式发布。你需要显式选择加入（opt-in）来试用该功能，通常是通过设置 GOEXPERIMENT 环境变量（稍后会详细讨论）。

如果一切顺利，经过一到两个版本之后，实验特性被最终确定，进入通用可用阶段，并变为默认开启（on-by-default）。

如果一个实验特性影响了某些行为，那么它在进入通用可用阶段后，有时——但并非总是——会有一个过渡性的宽限期，在此期间可以临时禁用该特性并使用旧行为。例如，在 Go 1.26 中，新的垃圾回收器设计（上面简要提到过）进入了通用可用阶段并默认开启，但如果需要，仍然可以禁用它并使用旧的垃圾回收器。

以上就是最常见的模式，但有时候事情会更漫长或走向不同的方向。例如：

• Go 1.22 发布时附带了编译器内联逻辑的实验性实现，两年多过去了，它仍然默认关闭，处于评估之中。
• 同一次发布还附带了一个内存 arena 实验。在收到用户的负面反馈和顾虑之后，它仍然默认关闭，处于无限期搁置状态，最终可能会被完全移除。

或者，当 Go 团队对某个变更足够有信心时，他们可能会跳过反馈阶段，直接进入通用可用阶段……但仍然可能有一个过渡性的宽限期，在此期间可以禁用它。

一个很好的例子是 Go 1.24 将其 map 实现改为使用 Swiss tables。Go 团队对实现及其性能优势足够有信心，因此直接进入通用可用阶段并默认开启，但——至少目前——如果你愿意，仍然可以选择退出并使用旧的 map 实现。

所以在实践中，实验特性实际上有三种大致状态：

• 默认关闭，评估中
• 默认关闭，搁置/休眠中
• 默认开启，但有临时退出选项

永久实验特性

Go 还有一些实验性功能，它们并非通常意义上的"实验"。

这些功能默认关闭，但它们不在评估中，不在寻求反馈，也没有预期它们最终会进入通用可用阶段并变为默认开启。

尽管它们通过 GOEXPERIMENT 环境设置以与其他实验相同的方式控制，但实际上它们更像是你可能在特定场景下想要使用的可选 Go 功能。

在下文中，我将这些称为"永久实验特性（permanent experiments）"。

例如，有一个 field tracking 诊断功能，用于追踪哪些结构体字段被访问。它已经存在十年了，并且没有意图让它进入通用可用阶段。还有一个 static lock ranking 功能，这是一个用于查找 Go 运行时中潜在死锁的诊断工具。

当前有哪些可用的实验特性？

要了解当前有哪些可用的实验特性及其状态，出奇地困难。

遗憾的是，Go 官方文档或 Go Wiki 中没有一个页面来追踪实验特性的状态，为了写这篇文章，我不得不从各处拼凑信息。如果你想做同样的事：

• 可以运行 $ go doc goexperiment.Flags 获取所有可用实验的列表。
• 可以通过阅读 src/internal/buildcfg/exp.go 的源码——特别关注 ParseGOEXPERIMENT() 函数中的 baseline 变量声明——来找出哪些实验是默认开启的。
• 可以将实验名称与 Go 发布说明交叉对照，并搜索 GitHub issues 来尝试弄清当前的状态。

据我所知，截至 Go 1.26，以下是当前可用的永久实验特性：

以下是当前默认关闭的实验特性及其状态：

以下是当前默认开启的实验特性：

如何启用和禁用实验特性？

实验特性通过 GOEXPERIMENT 环境设置来控制。

如果你想尝试某些默认关闭的实验特性，应将实验名称作为逗号分隔的小写值包含在 GOEXPERIMENT 中。例如，如果你想在构建应用程序时启用 JSONv2 和 GoroutineLeakProfile 实验，可以这样做：

1

$ GOEXPERIMENT=jsonv2,goroutineleakprofile go build ./...

如果你想关闭某个默认开启的实验特性，可以在小写实验名称前加上 no 前缀。例如，如果你想在构建应用程序时关闭 GreenTeaGC 和 RandomizedHeapBase64 实验，可以这样做：

1

$ GOEXPERIMENT=nogreenteagc,norandomizedheapbase64 go build ./...

混合启用和禁用的实验也完全没有问题：

1

$ GOEXPERIMENT=jsonv2,nogreenteagc go build ./...

注意，如果你使用不同的 GOEXPERIMENT 值构建同一个包，Go 会将它们视为不同的构建，并在构建缓存中存储独立的条目。

我在上面的示例中使用了 go build，但你在使用 go run 或 go test 时也可以使用完全相同的模式。如果你想亲自尝试，试着创建以下使用实验性 encoding/json/v2 包的程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package main

import (
    "encoding/json/v2"
    "fmt"
)

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
    City string `json:"city"`
}

func main() {
    p := Person{Name: "Ada", Age: 36, City: "Vienna"}

    data, _ := json.Marshal(p, json.StringifyNumbers(true))
    fmt.Println(string(data))
}

如果你正常运行此程序，它将无法编译，你会看到类似以下的错误消息：

1
2
3

$ go run main.go
package command-line-arguments
        imports encoding/json/v2: build constraints exclude all Go files in /usr/local/go/src/encoding/json/v2

但如果你启用了 JSONv2 实验，程序将按预期运行：

1
2

$ GOEXPERIMENT=jsonv2 go run main.go
{"name":"Ada","age":"36","city":"Vienna"}

你应该关注哪些实验特性？

如果你像我一样是个普通的 Gopher，主要用 Go 编写程序而非开发 Go 本身，那么大多数可用的实验特性可能与你关系不大。

最有意思、最相关的几个可能是：

• GreenTeaGC —— 如果你在使用 Go 1.26，你已经在默认使用它了。但如果你注意到任何性能或行为问题，你应该知道自己仍然可以禁用它（并且还应该提交一个 issue）。
• Dwarf5 —— 同样，如果你在使用 Go 1.25 或更高版本，你已经在默认使用它了。但如果你遇到任何问题，知道自己仍然可以禁用它是有用的。
• JSONv2 —— 我不建议在它进入通用可用阶段之前切换，但如果你编写大量处理 JSON 的代码，值得尝试新的 encoding/json/v2 包，熟悉即将到来的内容，并在发现问题时给出反馈。
• GoroutineLeakProfile —— 这个特性可以立即派上用场，如果你怀疑有 goroutine 泄漏并需要调试，值得启用。
• RuntimeSecret —— 如果你编写加密代码或需要处理敏感数据，值得尝试并给出反馈。
• RuntimeFreegc —— 如果你的应用程序严重依赖垃圾回收器，可能值得在启用此特性的情况下对你的代码进行基准测试，看看是否提高了性能，并在发现问题时给出反馈。

最后，需要强调的是，实验特性不受 Go 兼容性承诺的覆盖。它们的 API、行为和性能特征都可能发生变化，因此通常最好避免过早采用，不要在实验特性最终确定之前依赖它们。

但实验特性通常是对 Go 中一些最重大变更的预览。如果你知道某个实验最终进入通用可用阶段并默认开启后可能会影响你或你的代码，那么尝试它、酌情运行基准测试、并在发现问题时给出反馈是个好主意。

如果你想追踪有哪些可用的实验特性及其状态，Go 发布说明最近在记录实验特性及其使用方式方面做得越来越好了。结合这篇博客文章和每次 Go 新版本发布时浏览发布说明，你应该能对整体情况有一个不错的了解。

原文来源：Alex Edwards, "Go Experiments Explained", June 1, 2026, https://www.alexedwards.net/blog/go-experiments-explained

在 Go 1.17 之前，Go 编译器总是生成可由任何 64 位 x86 处理器执行的 x86 二进制文件。
Go 1.18 为 AMD64 引入了 4 个架构级别 。每个级别在编译器可以包含在生成的二进制文件中的 x86 指令集上有所不同：

• GOAMD64=v1（默认值）：基准模式。仅生成所有 64 位 x86 处理器都能执行的指令。
• GOAMD64=v2：所有 v1 指令，加上 CMPXCHG16B、LAHF、SAHF、POPCNT、SSE3、SSE4.1、SSE4.2、SSSE3。
• GOAMD64=v3：所有 v2 指令，加上 AVX、AVX2、BMI1、BMI2、F16C、FMA、LZCNT、MOVBE、OSXSAVE。
• GOAMD64=v4：所有 v3 指令，加上 AVX512F、AVX512BW、AVX512CD、AVX512DQ、AVX512VL。

例如，设置 GOAMD64=v3 将允许 Go 编译器在生成的二进制文件中使用 AVX2 指令（这在某些情况下可能会提高性能）；但是这些二进制文件将无法在不支持 AVX2 的旧 x86 处理器上运行。
Go 工具链也可能生成更新的指令，但会通过动态检查来确保它们只在支持的处理器上执行。例如，如果设置了 GOAMD64=v1，并且 CPUID 报告 POPCNT 指令可用，那么 math/bits.OnesCount 仍然会使用该指令。否则，它会回退到通用实现。
Go 工具链目前不生成任何 AVX512 指令。
不支持 SSE3 的平台不支持种族检测器。

64 位 Intel 和 AMD 处理器已经演进了几十年。当你为 64 位 Intel 或 AMD 处理器编译 Go 程序时，编译器默认面向的是一个将近 20 年前的指令集。生成的二进制文件几乎能在任何 x64 芯片上运行，但同时也放弃了自 2003 年以来添加的所有指令。

我们通常用微架构级别（microarchitecture levels）来描述这一分层。每个级别捆绑了一组可以假定存在的指令集扩展：

在我看来，这个阶梯已经略显过时了。它大约在 2020 年定型，而硬件已经向前发展了。我们还需要加入最新的 AVX-512 子扩展（VBMI、VBMI2、VNNI、BF16、FP16、VPOPCNTDQ 等），这些在最新的服务器和消费级芯片上已经支持，但 v4 并未要求。虽然 v1 到 v4 是一种有用的通用语言，但今天一个现实的"用尽该 CPU 提供的一切"目标至少需要一个 v5，而且可以说整个方案应该被更细粒度的特性检测所取代。

无论如何，Go 工具链通过 GOAMD64 环境变量暴露了这个 v1 到 v4 的阶梯。设置 GOAMD64=v3 告诉编译器可以使用直到 AVX2（含）的所有指令。默认值是 v1，即最低公共分母。

这就引出了一个显而易见的问题：如果我拿一个真实的、对性能敏感的库，在每个级别上重新编译，实际能获得多大收益？我选择了 Roaring Bitmaps，它是一种用于数据库和搜索引擎的压缩位集数据结构。

Roaring Bitmap 存储一组 32 位整数。它将 32 位空间按高 16 位划分为每块 65,536 个值的 chunk，每个 chunk 存储在一个仅保存低 16 位的容器（container）中。容器有三种形式，库始终保留最小的那种：

• 数组容器（array container）：一个已排序的 16 位值列表，当 chunk 稀疏时使用（最多几千个元素）；
• 位图容器（bitmap container）：一个扁平的 8 KB 位向量（65,536 位，每个可能值对应一位），当 chunk 密集时使用；
• run 容器（run container）：一个 [start, length] 区间列表，当集合中的位聚集成连续区间时使用。简单说就是把连续的一大段 1 压缩成"从哪开始、有多长"——比如"第 3 到第 100 位全是 1"只记成 [3, 98]，而不是逐位存 98 个 1。

我拉取了该库的最新版本，然后用它自带的基准测试套件运行了四次，每次一个级别，每个级别采集八个样本。我在一台 Intel Xeon Gold 6548N（Emerald Rapids，支持全部四个级别，包括 AVX-512）上完成测试，使用 Go 1.26.2 和 Roaring v2.18.2。

种群计数（population count，或称 popcount，也叫汉明重量）简单来说就是一个机器字中被置为 1 的位数。Roaring 大量依赖它：位图容器的基数——它持有多少个值——是其 1024 个 64 位字的种群计数之和。现代 x86 芯片有专门的 popcnt 指令可以在单次操作中完成这一计算，但该指令只在 v2 级别（SSE4.2，2008 年）才可用。没有它，编译器只能退回到多指令的位操作序列。

最清晰的单一结果是种群计数：计算位图容器中置位比特的数量。v1 基线无法使用 popcnt 指令，因此 Go 生成的是软件回退实现。一旦我们移到 v2，popcnt 变得可用，耗时几乎减半：

这是 43% 的减少，而且是免费的：无需改动源码，只需一个编译器标志。不过请注意，v3 和 v4 没有进一步改善。单条 popcnt 指令已经是最优的了；就 Go 编译器而言，AVX2 和 AVX-512 在此没有可添加的东西。

种群计数是容易获得的胜利。库中其他部分呢？

另一个明显的胜利是从密集位图构建容器。FromDense array 基准测试接收一个原始的 8 KB 位向量，并为其构造最紧凑的容器：它对每个字做 popcount 以获知基数，然后扫描出所有置位比特的位置。这种逐字的 popcount-扫描 循环正是编译器在 256 位寄存器可用后可以自动向量化的模式，因此收益在 v2 之后继续增长：

v2 通过使用标量 popcnt/tzcnt 指令已减少了 21%，而 v3（AVX2）几乎将其翻倍，达到 38% 的减少。与种群计数一样，v4 没有任何增益。

集合操作也呈现出相同的模式。IntersectionCardinality 基准测试计算两个位图共有多少个值：对于位图容器，它将字逐对做 AND 操作，然后对结果做种群计数，而不用物化出交集。在这里 v2 基本没有作用（标量 popcnt 已经在内部循环中了），但 v3 让编译器将 AND-计数 循环扩展到 256 位寄存器，将耗时减少了 22%：

要点总结：

1. 在现代硬件上，每个人都应该使用 v2 或更高版本。生成的二进制文件可以在任何数据中心和任何非古董笔记本电脑上运行。
2. v3 级别值得研究。
3. v4 级别在我的一些基准测试中本应有所帮助，但实际上没有。我怀疑是 Go 编译器在这方面还不够好。

（显然：请运行你自己的基准测试。）

原文来源：Daniel Lemire, "How much do amd64 microarchitecture levels help in Go?," in Daniel Lemire's blog, June 6, 2026, https://lemire.me/blog/2026/06/06/how-much-do-amd64-microarchitecture-levels-help-in-go/

精选评论

Xarn（2026年6月8日）：

关于 v4 没有任何作用，来自他们的文档：

Go 工具链目前不生成任何 AVX512 指令。

Marco（2026年6月9日）：

我自己的使用 AVX512 指令的经验是，使用它们的逻辑（和数据结构）与常规使用的结构差异如此之大，编译器不太可能翻译并非专门为它们构建的代码。问题是编程语言何时会创建易于使用的语法来方便地使用这些扩展。

0. 缘起

我想要一个 Go 语言的 RDMA 库。

从去年我们做高性能网络的黑盒监控起，就开始尝试用 RDMA 做探测。但我们的技术栈是 Go，找了几个库，实现得不好也不稳定；换成 C 语言技术栈对团队同学来说成本太高；自己实现当时觉得挺有挑战，于是这件事就搁下了，最后还是退回到用普通 UDP 协议探测。

RDMA for Go 库市面上的选择不多：要么是某个公司内部、绑定很深的封装，要么是年久失修的 binding。而我要的东西很明确——地道的 Go API，封装 libibverbs + librdmacm（也就是 rdma-core 的用户态库），支持 RC/UD 两种传输、Send/Recv 和 RDMA Read/Write，再配一套对标 perftest 的 ib_send_bw/lat、ib_write_bw/lat、ib_read_bw/lat 的 Go 版工具。

今年不同了，AI Coding 技术飞速发展，我也有信心去做移植这件事。尤其本周 Loop Engineering 这种工作方式大家讨论得很热烈，我也在自己的 goal workflow 里加了个 loop-it 技能，实现了一个轻量级的 Loop Engineering，正好拿来试试手。

还有，大家普遍担心 Loop Engineering 实践起来 token 花费太高，我也想实际看看到底花费几何。

移植RDMA到Go生态圈是个典型的「工作量不小、但每一步都不算难」的活儿。cgo 封装 verbs 是体力活：几十个 C 结构体、状态机、字节序、资源生命周期，错一个字段编译就挂。正是这种结构清晰、可分解、可验证的任务，最适合拿来做一次 Loop Engineering 实验。

所谓 Loop Engineering，核心就一句话：不要让 Agent 一口气写完一个大项目，而是把工作拆成带依赖的小单元，让它在一个可恢复、可观测的循环里逐个吃掉，每一步都有验证关卡。

这是我的锅，实现的loop-it有问题。后来在执行过程中我发现了这个问题，修复了 loop-it。

4. 补救：真正的审查发现了什么

最后我还是做了补救，让 CC「现在跑一次真正的审查」。这次 CC 调起了能用的 /code-review（high effort：多个独立角度并行找问题，再逐条对抗式验证），对已合并的全部代码做了一轮真正的 correctness 审查。

结果很扎心——8 个确认/可信的问题，其中两个是致命的编译错误：

1. cq_linux.go：c.imm_data undefined
struct ibv_wc 里 imm_data 在一个匿名 union 里，cgo 根本无法用 .imm_data 访问；而且它是 __be32（网络字节序）。

2. device_linux.go：ibv_query_port 类型不匹配
   现代 rdma-core 把 ibv_query_port 做成 static inline，转发到一个收 _compat_ibv_port_attr* 的真实符号，cgo 直接调会类型不符。

还有 6 个运行时/逻辑问题，例如：

3. rdma_cm 路径的 Endpoint.Peer 永远没赋值 → 所有走 -R 的 Write/Read 都会立刻报 errNoPeer。
4. write.go 的 busy-wait 没有内存屏障 → for buf[last] != expect {} 读的是 NIC 通过 RDMA 写入、Go 运行时看不见的内存，编译器可能把这次 load 提到循环外，造成死循环或读到陈旧值。
5. imm_data 发送侧字节序 → 没 htonl，对端会读到字节翻转的立即数。
6. rdma_cm 错误路径资源泄漏、errno 读取时机不对、setup 忽略了 -c/-d/-i/-x 参数……

最刺眼的事实是：这两个编译错误意味着，整个 cgo 核心从来没在 Linux 上编译过。我全程在 macOS 上开发，走的是 stub 路径，go build 一路绿灯，但那只证明了「桩实现能编译」，完全没碰到真正的 verbs 代码。

5. 修复阶段：一步步把真相逼出来

接下来的过程，本质上是让真实环境替我做验证。这部分非常有意思，因为它展示了 Agent 的盲区如何被一台真机一点点照亮。

我还是做了一点点额外的工作，以下是我手工触发的。

第一步，质量清理（/simplify）。4 个角度并行审查：reuse / simplification / efficiency / altitude。修了几处真问题：

• stats.go 的延迟统计，原来每打印一行 summary 要 sort 3 次（Min/Max/Percentile 各自 sort 一遍），直方图路径甚至 5 次。改成 Stats() 一次排序算出 min/avg/max/p99。
• 带宽测试的「保持 TxDepth 个请求在途」的循环，在 send/write/read 里三份几乎一样的拷贝 → 抽成一个 runBWPipeline(cfg, cq, post)，用闭包传 opcode。
• 4 个工具 main 里重复的 -R/UD 拒绝逻辑 → 收敛成一个 Config.RequireOneSidedTCP()。
• 删掉过时的 var _ = C.IBV_QPT_RC cgo 占位 anchor。

第二步，工程化。加了 Makefile（vet/build/test/tools/cross/stub/integration/lint/fmt，硬件相关的 integration 用 GORDMA_HW=1 闸住），加了 make fmt 和 make lint。

make lint 一跑，golangci-lint 报了 20 个问题：16 个 errcheck（没检查的 defer Close() 返回值等）、2 个 unused、以及 2 个 staticcheck SA5002，正是 write.go 那个 busy-wait race。静态分析工具独立地撞上了 /code-review 早就指出的内存模型 bug。

这里有个小插曲值得一记：修这个 race 时我第一反应是用 atomic.LoadUint8——结果 Go 根本没有 8 位原子操作，编译直接挂。最后改成：定位包含该字节的 4 字节对齐 word，用 atomic.LoadUint32 + CompareAndSwapUint32 只改其中一个字节（代价是要求 Size >= 4）。Agent 也会想当然，差别只在于有没有一个会立刻打脸的编译器。

第三步，真机连环打脸。用户把代码弄到一台真正的 H20 GPU 服务器上（装了 RDMA 网卡），开始跑 make：

• 第一次：fatal error: rdma/rdma_cma.h: No such file or directory，缺 librdmacm-dev。换成我的开发 docker，上面已经装好了相应依赖库。
• 第二次：c.imm_data undefined + ibv_query_port 类型不匹配，就是 /code-review 预言的那两个编译错误，这下在真机上真实地复现了。CC 按 libibverbs 的正确用法修：给 imm_data 写 C 辅助函数 wc_imm_data()（ntohl 转主机序）；给 ibv_query_port 包一层 C wrapper gordma_query_port() 让 inline 在 C 里展开；发送侧 imm_data 补 htonl。
• 第三次：device_linux.go:67: possible misuse of unsafe.Pointer，go vet 嫌弃把指针存进 uintptr 再做算术。改用 unsafe.Add，让指针运算全程保持 unsafe.Pointer 形式。

因为这些都没进 Loop，所以不适合放在循环里，而是在循环之外执行的。起始后续/simplify 也可以加在循环中。

6. 完整的提交时间线

如果把 16 个功能 PR 之后的修复也算上，整条提交线是这样的（节选）：

1
2
3
4
5
6
7
8

edd44e2 docs: add badges to README
4fa8b9c fix: use unsafe.Add to walk device list (go vet unsafe.Pointer)   ← 真机第3次
f0b0453 fix: cgo compile errors (imm_data, ibv_query_port) + imm byte order ← 真机第2次
d253e36 Chore/simplify cleanups (#31)                                     ← 质量清理+工程化
f2519af docs: README usage, godoc, and CI workflow (#15)                  ← loop-it 最后一个 issue
...
d15513b 项目骨架：go.mod、cgo 构建配置、非 Linux stub (#1)                  ← loop-it 第一个 issue
56514ff Initial commit

#1 到 #15 是 loop-it 自动跑出来的，干净利落。d253e36 之后的几个 fix，则是人把 Agent 拽回现实的痕迹。

7. 成本：那 239 块钱

说说标题里的钱。

我一直盯着Claude Code中钱的消耗，最后算下来一共花了 239 元。239 这个数字是按整轮交互（一份 PRD、15 个 issue 的实现、一轮 high-effort code-review、一轮 4 角度 simplify，外加多轮真机修复往返）的量级估的。我不想在这篇复盘里编一张逐项发票出来——那本身就违背了全文的主旨。

但即便按这个量级看，几个判断是成立的：

• 这是「一个有经验的工程师几天的活儿」：cgo 封装整套 verbs、写 6 个 perftest 工具、跨平台 stub、CI、文档。按工时折算，几百块的 API 成本对应的是数千块的人力成本。
• 真正贵的不是「写」，是「来回」。第一遍实现其实很快、很便宜，大约100块。烧钱的是后面那些本可以避免的往返——如果一开始就在有网卡的 Linux 上开发，那两个编译错误根本不会漏到合并之后，也不会有「真机连环打脸」的三轮修复。
• 跳过审查省下的钱，会在后面加倍还回来。loop-it 静默降级掉的 /review-it，最终是用一轮独立的 /code-review + 多轮真机调试补回来的。省一步，赔三步。。

附：项目信息

• 仓库：github.com/smallnest/gordma
• 规模：52 个 Go 文件 / ~3981 行
• 能力：Device/Context/PD/MR/CQ/QP/AH 全套 verbs；RC + UD；TCP 握手 + rdma_cm 两种建连；6 个 perftest 风格工具
• 构建：Linux+cgo 真实实现，非 Linux/CGO_ENABLED=0 stub 实现
• 状态：cgo 编译错误已在真机修复；硬件数据通路的端到端验证已在 RoCE v2 真机上验证

开篇：一个让人又爱又怕的技术

如果你做过高性能网络，一定听过 RDMA 这个词。它是 AI 训练集群里 GPU 之间狂飙数据的底层、是分布式存储压榨延迟的杀手锏、是金融交易系统微秒必争的武器。

两种传输 & 两种操作

• RC(可靠连接，类比 TCP):有序可靠，支持双边和单边操作

• UD(不可靠数据报，类比 UDP):无连接，一对多

• 双边操作(Send/Recv):接收方要先挂好接收请求，双方 CPU 都参与

• 单边操作(RDMA Write/Read):发起方直接读写对端内存，对端 CPU 完全不参与——这是 RDMA 最"魔法"的地方

二 · 先用 perftest 摸清家底

在写代码之前，先得知道你的网卡能跑多快。业界标准是 perftest(linux-rdma 出品的 C 版基准工具)。gordma 贴心地用 Go 复刻了一套对标工具，放在 cmd/ 下:

命名规律很简单:操作(send/write/read) + 指标(bw 带宽 / lat 延迟)。每个工具不带地址就是服务端，带对端地址就是客户端。

跑一把带宽测试:

1
2
3
4
5
6
7

go build -o bin/ ./cmd/...

# 服务端(不带地址)
./bin/go_send_bw -s 65536 -n 1000000 -d mlx5_1 -x 3

# 客户端(带服务端 IP)
./bin/go_send_bw -s 65536 -n 1000000 -d mlx5_1 -x 3 33.0.226.25:18515

输出:

1
2

#bytes    #iterations   BW average[MB/s]   MsgRate[Mpps]
65536     1000000       48996.54           0.747628

48996 MB/s ≈ 392 Gb/s(注意单位:go_send_bw 输出的是 MB/s=10⁶ 字节/秒，×8÷1000 才是 Gb/s)，这就是这张 400G 网卡的实力基准。记住这个数，后面要拿它当标尺。

⚠️ 单位是个大坑:三个常用工具输出单位各不相同,直接比原始数会差出 8 倍——C 版 ib_send_bw 是 MiB/s(2²⁰ 字节)、Go 版 go_send_bw 是 MB/s(10⁶ 字节)、gordma 的 --raw 是 MiB/s(已对齐 C 版)。本文所有数字都统一换算到 Gb/s(10⁹ bit) 再比较。

💡 小贴士:命令里的 IP 是服务端 -d 指定的那张 RoCE 网卡绑定的 IP，不是CPU网络/SSH 那个 IP。这是新手最容易连不上的坑。两端的 -d(设备)和 -x(GID 索引，RoCE v2 常用 3， 可以使用show_gids查看)要对齐同一张物理网络。

三 · 底层 API:完全掌控,但要写够样板

gordma 的底层包 gordma 一比一映射了 RDMA 的对象模型。想要完全掌控每个工作请求、每个 QP 参数，用它。代价是:你得自己走完那七步。

来看一个完整可跑的 RC 回显(用 rdma_cm 建连，省掉手写状态机):

服务端:收一条,回显

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

func server(addr string) error {
    ln, _ := gordma.Listen(addr)          // rdma_cm 监听
    defer ln.Close()
    cm, _ := ln.Accept()                  // QP 已在 RTS 状态
    defer cm.Close()
    qp, cq, pd := cm.QP(), cm.CQ(), cm.PD()

    // 注册接收缓冲区——网卡只能 DMA 已注册内存
    mr, _ := pd.RegMRBuffer(4096, gordma.AccessLocalWrite)
    defer mr.Close()

    // 收之前必须先挂 recv,否则对端发来会 RNR
    sge := gordma.SGEFromMR(mr, 0, 4096)
    qp.PostRecv(gordma.RecvWR{WRID: 1, SGList: []gordma.SGE{sge}})

    // 轮询完成队列
    wc := make([]gordma.WorkCompletion, 1)
    pollOne(cq, wc)
    msg := mr.Bytes()[:wc[0].ByteLen]
    fmt.Printf("got %q\n", msg)

    // 原样发回
    copy(mr.Bytes(), msg)
    qp.PostSend(gordma.SendWR{
        WRID: 2, Opcode: gordma.OpSend,
        SGList:   []gordma.SGE{gordma.SGEFromMR(mr, 0, len(msg))},
        Signaled: true,
    })
    pollOne(cq, wc)                       // 等发送完成
    return nil
}

// 忙轮询 CQ 直到取到一个完成
func pollOne(cq *gordma.CQ, wc []gordma.WorkCompletion) {
    for {
        if n, err := cq.Poll(wc); err != nil || n > 0 {
            return
        }
    }
}

每一行都对应一个 RDMA 概念:注册内存 → 先挂 recv → 轮询 CQ → post send。底层 API 的好处是没有任何隐藏行为,你能做单边 Write/Read、能精调 QP 容量、能复刻 perftest——坏处是,样板真的多。

四 · 高级 API:像写 net 一样写 RDMA

如果你只是想写业务,不想碰 MR、WR、CQ 这些——用 rdmanet 子包。它把上面那一大坨全收进了 Dial / Listen / SendMsg / RecvMsg。

来看同样的事,高级怎么写。一个 RPC 服务:

服务端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

func serve(addr string, opts []rdmanet.Option) error {
    ln, err := rdmanet.Listen(addr, opts...)
    if err != nil { return err }
    defer ln.Close()
    for {
        conn, err := ln.Accept()
        if err != nil { return err }
        go handle(conn)               // 每个连接一个 goroutine
    }
}

func handle(conn *rdmanet.Conn) {
    defer conn.Close()
    for {
        req, err := conn.RecvMsg()    // 收一条完整请求
        if err == io.EOF { return }   // 客户端关闭,正常结束
        if err != nil { return }
        conn.SendMsg(process(req))    // 处理并回复
    }
}

客户端

1
2
3
4
5

conn, _ := rdmanet.Dial("33.0.226.25:18515",
    rdmanet.WithDevice("mlx5_1"), rdmanet.WithGIDIndex(3))
defer conn.Close()
conn.SendMsg([]byte("hello"))
reply, _ := conn.RecvMsg()           // 阻塞等响应

没有 MR、没有 WR、没有 CQ 轮询、没有状态机。 是不是和标准库 net 一模一样?

rdmanet 还提供了一整套实用能力:

• 消息语义 SendMsg/RecvMsg:保留边界,大消息自动分片重组
• 字节流适配器 Read/Write:Conn 直接满足 io.ReadWriteCloser,能配 io.Copy 传文件
• 批量 I/O SendBatch/RecvBatch:摊薄每次调用开销
• UD 数据报 PacketConn:无连接、一对多
• 地址注册表 Registry:带外发现对端

仓库里还附带了 17 个按功能拆分的示例(examples/ 目录),从最小回显到全双工聊天、文件传输、一对多广播,一个功能一个目录,照着抄就行。

五 · RawConn:既要 net 风格,又要榨干网卡

高级 Conn 好用,但有个问题:它为了"保留消息边界 + 流控 + 易用"付出了固定成本——封帧、信用流控、bounce 缓冲拷贝、后台 poller goroutine 的跨线程交接。这些叠加起来,让它在 64KB 大包上只能跑到约 28 Gb/s,远没喂满 400G 网卡。

于是 gordma 给了第三个选择:RawConn。

它的理念很直接:把所有花哨的东西全剥掉,直接暴露"注册内存 + 投递 WR + 自己轮询 CQ",在同一个 goroutine 里 post + busy-poll,无封帧、无流控、无交接。这正是 perftest 打满线速的那套循环。

最省事的用法是内置的 PipelineBatch,保持 N 个请求 in-flight(同时在网卡里跑),每完成一个补一个:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

rc, _ := rdmanet.DialRaw(addr,
    rdmanet.WithDevice("mlx5_1"),
    rdmanet.WithGIDIndex(3),
    rdmanet.WithQueueDepth(128))
defer rc.Close()

mr, _ := rc.RegisterMemory(size * txDepth)
defer mr.Close()

rc.PipelineBatch(iters, txDepth, func(wrID uint64) gordma.SendWR {
    slot := int(wrID) % txDepth
    return gordma.SendWR{
        WRID:     wrID,
        Opcode:   gordma.OpSend,
        SGList:   []gordma.SGE{gordma.SGEFromMR(mr, slot*size, size)},
        Signaled: true,
    }
})

RawConn 还支持:

• 单边 Write/Read:走 TCP 握手交换了对端 rkey/地址,可以直接做"对端 CPU 不参与"的远程读写
• 批量提交 PostSendBatch:用 WR 链表一次 ibv_post_send 提交多个请求,把 cgo 跨界开销从"每个 WR 一次"降到"每批一次"，小包消息率因此能提升约一个数量级
• 逃生舱 QP()/CQ()/PD():需要时随时下沉到底层自己驱动

代价当然有:RawConn 不替你保留消息边界、不做流控(得自己控制 in-flight 数,否则 RNR)、不托管缓冲区。一句话：先用 Conn，确实要榨干网卡时再上 RawConn。

🔬 顺带破一个误解:很多人(包括我一开始)以为"Go 经 cgo 调 RDMA 一定比 C 慢一截"。我用 GORDMA_PROBE=1 把发送循环拆成"提交 WR(post)"和"忙等完成(poll)"两段实测,结论反直觉:一次 ibv_post_send 含 cgo 跨界约 300ns,只占总时间 ~15%,而且 go_send_bw 和 RawConn 两者完全相同。也就是说——cgo 提交开销真实存在但很小,不是性能差距的主因。后面第六节会看到,go_send_bw 状态好时能直接追平 C 版 ib_send_bw,根本没有"Go 追不上 C"的固有差距。

六 · 真刀真枪:带宽压测对比

理论讲完,上数据。同一对 400G RoCE v2 节点,64KB 大包,100 万条消息,实测:

结论很清楚:

• 从 Conn 到 RawConn,同一个库、同一张卡,吞吐 暴涨约 8 倍，证明那 28 Gb/s 的天花板就是高级那套便利机制的固定成本。
• RawConn 用纯 Go(加薄薄一层 cgo)把吞吐推到了 230+ Gb/s 的量级,已经和同一个库的底层 go_send_bw 在同一个数量级。

一个反直觉的发现:差距不在 cgo,而且不是固定的

我原本想搞清"RawConn(232) 为什么比 go_send_bw(392) 慢约 1.7 倍",于是做了一组同机、同口径、交替跑的实验(锁核 taskset + 性能调频,尽量压住抖动),用 GORDMA_PROBE=1 拆出 post/poll。结果挖出三件事:

① cgo 提交不是瓶颈。 两个工具的 post(提交 WR)都是 ~300 ns/WR、占比 ~15%,完全相同。所谓"每个 WR 一次 cgo 跨界拖慢了 Go",在这个负载上站不住——提交很便宜,而且两边一样便宜。

② Go 能追平 C。 锁核后 go_send_bw 实测峰值 0.748 Mpps,和 C 版 ib_send_bw 完全一致。早先看到的"go_send_bw 只有 ~314 Gb/s"是机器状态差时的数,不是 cgo 的锅。

③ 差距是"可变"的,不是固定缺陷。 交替跑 3 轮,go_send_bw 在 0.414 / 0.748 / 0.414 Mpps 之间离散双峰跳变,而 RawConn 稳定在 0.42。也就是说:go_send_bw 状态差的那几轮,和 RawConn 几乎持平;两者差距在 **1.05×1.76× 之间晃**,取决于那一轮 go_send_bw 能不能抢到干净的网卡/CPU 窗口。

差距的真正位置在 poll(忙等完成到达):go_send_bw 的 poll 在 0.75~1.33 µs/WR 间大幅波动(状态好就打满线速),RawConn 则被稳定压在 ~1.40 µs。考虑到这是一台共享 GPU 机、400G 链路被其他租户竞争,最合理的解释是环境竞争,而非 RawConn 有独立的代码缺陷——两个工具走的是同一套 QP 建立和 CQ 轮询路径,逐行核对没有能让 RawConn 单独变慢的差异。

🧭 给读者的实用结论:① 不要迷信"Go+cgo 必慢于 C",在大包带宽场景两者能打平;② cgo 的固定开销真实但小,真正要省它得靠批量提交 + 忙轮询(见下文小包测试);③ 想认真比性能,务必锁核、独占机器、多次取中位数,共享机上的单次数字会骗你。

小包更能看出批量提交的威力

64KB 大包很容易撞带宽上限,看不出 CPU 侧的优化。换成 1KB 小包(消息率受限场景):

1

./bin/go_rdmanet_bw --raw -s 1024 -n 5000000 -d mlx5_1 -x 3 -b 128 33.0.226.25:18515

1

raw-batch Send(txDepth=128): 5000000 x 1024 bytes in 0.85s: 47.92 Gb/s, 5.850 Mpps

5.85 Mpps——批量提交(PostSendBatch)在小包上把消息率拉高了一个数量级。这正是榨干高频小消息场景的关键。

尾声:三个档位,按需取用

gordma 最打动我的,是它没有逼你在"易用"和"性能"之间二选一,而是给了一条平滑的升级路径:

而且全部代码在任何平台都能编译(macOS/Windows 走 stub 桩实现,RDMA 调用优雅返回 ErrNotSupported),只有真正运行时才需要 Linux + RDMA 硬件。这意味着你可以在 MacBook 上写代码、跑单元测试,真要压测时再丢到带卡的机器上，开发体验和门槛都友好得多。

如果你正在被 RDMA 编程劝退,或者想给你的 Go 服务接上高性能网络,不妨试试 gordma:

🔗 github.com/smallnest/gordma

从 go run ./examples/echo-msg 跑通第一个 RDMA 程序开始,你会发现——原来 RDMA 也可以这么"傻瓜"。

本文所有性能数据均为同一对 400G RoCE v2 节点上的实测结果,会随硬件与配置不同而变化。完整教程、API 文档、17 个示例和 8 个压测工具均在仓库中。

这不是一个ping能解决的问题。

今天，我们将百度物理网络黑盒监控方向的工具集 nettools 开源了（https://github.com/baidu/nettools），第一批放出的是 bitflip 和 bitflip6，用于检测网络丢包和比特翻转，在百度内部跑了很长时间了。

后续还有更多工具和SDK正在整理中，包括骨干网fullmesh监控、网关设备监控、连接客户内部机房设备的监控、定位工具等等，还有对巨量监控数据的处理。百度物理网络黑盒监控团队积累了一大批经验、产品和工具，后续逐步整理开源出来，欢迎关注。

为什么不是一个ping？

在大规模物理网络中，ping几乎没有用。

下面是一个集群简化的示意图。实际上层级比这更多，同一层级的网络设备数量远远大于图中画的，一个交换机有几十个端口而不是图中的几根连线，一个ToR交换机可能连接几十台服务器……两台服务器之间可走的链路有很多种可能。

bitflip用4种salt填充模式来覆盖各种跳变场景：

每个包按序列号选择一种模式，服务端用相同模式验证，精确到哪个字节、哪个bit翻转了。

这个场景非常讨厌。可能一年就遇到一次，遇到了就特别麻烦，影响还大，错误数据被当成正常数据保存了。客户发现还算容易，因为除了能绕过checksum的那部分，大部分坏包会被服务器的checksum校验drop掉，通过采集监控服务器的checksum指标，理论上容易发现（实际还有一些坏包干扰）。

但定位起来就头疼了。客户报过来说好几个机房有改包现象，到底是哪个机房哪一层设备的哪个板卡？

这时候用bitflip工具，如果能复现，就可以通过找改包五元组的共同路径，定位到故障的设备和端口。这要靠单向监控，双向的话就像前面说的，有可能误导。

工程细节：raw socket + BPF

在百度的规模下，每秒要发送数千甚至上万个探测包。普通的UDP socket不够用：

• 需要自由构造IP头（设置TOS/DSCP等网络参数）
• 需要用极少的socket覆盖上百个端口对
• 需要精确控制发包速率

bitflip客户端用raw socket直接构造IP+UDP包，通过BPF过滤收包，只接收目标端口范围内、特定TOS值的回包。读侧按端口范围切分为最多8个goroutine，每个绑定独立的BPF过滤器。

1
2
3
4
5
6
7
8
9
10
11
12
13

func portRangeBPF(minPort, maxPort, tos int) []bpf.Instruction {
    return []bpf.Instruction{
        bpf.LoadIndirect{Off: 9, Size: 1},
        bpf.JumpIf{Cond: bpf.JumpEqual, Val: uint32(17), SkipFalse: 4},
        bpf.LoadIndirect{Off: 1, Size: 1},
        bpf.JumpIf{Cond: bpf.JumpEqual, Val: uint32(tos), SkipFalse: 4},
        bpf.LoadAbsolute{Off: 22, Size: 2},
        bpf.JumpIf{Cond: bpf.JumpGreaterOrEqual, Val: uint32(minPort), SkipFalse: 2},
        bpf.JumpIf{Cond: bpf.JumpLessOrEqual, Val: uint32(maxPort), SkipFalse: 1},
        bpf.RetConstant{Val: 0xffff},
        bpf.RetConstant{Val: 0x0},
    }
}

双向对比判断故障方向

bitflip同时支持客户端和服务端两侧统计。对比两侧丢包：

• 仅服务端有丢包：故障在正向路径（Client → Server）
• 仅客户端有丢包，服务端正常：故障在回程路径（Server → Client）
• 两端都有丢包：需要进一步分析

结合traceroute获取的链路拓扑，分析丢包五元组的公共端口/设备，就能定位到具体哪台设备、哪个板卡、哪个端口。

快速体验

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 克隆并编译
git clone https://github.com/baidu-sys/nettools.git
cd nettools && make build

# 在远端启动服务端（自动检测IP，自动注册客户端）
./bitflip

# 在本地启动客户端
sudo ./bitflip -r client -s <server_ip>

# 以每秒10000包的速率探测60秒
sudo ./bitflip -r client -s <server_ip> --rate 10000 --duration 60s

# 开启详细模式，丢包时输出具体五元组
sudo ./bitflip -r client -s <server_ip> --verbose

IPv6环境使用 bitflip6，用法一致。

使用手册查看：bitflip使用指南

后续规划

nettools 目前开源的是 bitflip/bitflip6。后续还有更多工具和SDK在整理中：

• 更多探测场景的工具
• 通用的网络探测SDK
• 定位分析相关的工具

写在最后

在百度这种体量的物理网络中做监控和定位，不是写几个socket程序就能搞定的。为什么用UDP不用ICMP和TCP？为什么有时候又采用TCP syn探测？为什么需要单向探测？为什么协议头要带上一个窗口的发送信息？为什么salt要用4种模式？每个选择背后都有对应的故障场景和教训。

这些东西以前都在内部，现在开源出来了。

项目地址：https://github.com/baidu/nettools

欢迎Star、试用、提Issue和PR。

今天介绍的lidar工具，区别于传统的pingmesh探测方案，是我来百度后创造的第一个特殊的底层网络方案，我将其称之为lidar(激光扫描)方案，是一个很形象的比喻，我会话专门一节详细介绍它的优缺点，在这之前，我们介绍传统的赫赫有名的机房大规模的网络监控方案 pingmesh。

https://nettools.rpcx.io

pingmesh 探测以及为什么我们不用它？

PingMesh（"Pingmesh: A Large-Scale System for Data Center Network Latency Measurement and Analysis"）是微软在SIGCOMM 2015上发表的论文。作者团队来自微软研究院和Azure网络部门。

一句话概括：在所有服务器之间互相ping，测量每一对服务器之间的延迟和丢包，然后做异常检测和根因定位。

听起来很笨。几千台服务器，两两之间全部ping一遍，消息复杂度 O(n²)，谁敢这么干？

微软敢，而且早在2015年之前就已经在全量数据中心里跑了。当前他们也做了一些优化，实际并不是所有的服务器之间fullmesh探测，只是保证同一层级之间的设备之间fullmesh，比如同一层级的IB之间的设备都互有探测。

论文作者大部分是微软研究院的。其中最值得关注的是几位：

• Chuanxiong Guo（郭传雄）：微软研究院资深研究员，PingMesh是他主导的项目之一。后来曾任字节跳动人工智能实验室（AI Lab）总监，2022年因对数据中心网络设计的贡献当选IEEE Fellow，在数据中心网络领域有较高知名度。2023离开字节创业。
• Lihua Yuan：微软Azure网络团队核心成员，今年四月去了OpenAI。他和团队把PingMesh从论文推进到了Azure全量部署。
• 其他几位作者现在散落各大厂——Google、Meta等等。PingMesh的影响力从作者们的去向就能看出来，论文里的思想被带着在各个云厂商落地。

你可以从微软网站上下载这篇经典论文，它提供了一个很好的设计和分析网络故障的方案，它的探测分析图也深深影响我设计lidar的分析方法。

这个pingmesh设计也没众多的云厂商使用并演化，比如腾讯等，几乎成了机房内网络监控的标配。

百度也在2016年开发了类似的监控系统 netradar, 使用常态的TCP Client/Server进行探测， 支撑了百度网络的黑盒监控多年，不过在我来百度的时候相关的开发人员基本都走了，系统也面临的众多的问题：

• 常态机房间和机房内都超过了阈值，大盘是常态飘红
• 准确率不足，要么是误报、要么是漏报
• 时效性太慢，基本2，3分钟才可能有告警
• TCP的重试机制会导致偶发丢包发现不了
• 误告严重，经常服务器的上下线就导致了误报。尤其6.18、双十一这些节日涉及到大量的服务器的上下线

还有一个重要的问题，一旦Agent有个bug修复或者想扩展一个功能，全网所有的服务器要升级一遍的话，至少需要一个季度才能完成，甚至半年，因为需要小范围的灰度才能逐步的扩展，还得涉及到变更窗口的审批，另外RD和运维也很痛苦，因为这些变更都

lidar 探测

2020/2021年，百度迫切需要一个高时效高准确率的黑盒探测方案，去面对日益增长的云客户的对故障发现和处理的业务需求。

我恰巧刚刚来到百度，我还是第一次接触到众多的网络概念：机房、交换机、路由器、CLOS架构、骨干网、ADC、DC、IB、IC、TOR、ECMP等，对我来说一切都很新奇。面对当前探测的需求，我初始的想法是在前人的基础上(netradar)优化，先来快速解决当前棘手的问题。也做了一些尝试、比如netradar探测频率的提升、聚合程序整体引流和替换等等，在两三个月之后，虽然比最初的情况好些了，但是还是没有从根因上解决问题。

同时，我们团队也在研发骨干网的监控，在百度称之为B1的网络。当时我设计一个我称之为『sonar』的探测方案，采用UDP + Rawsocket的方式构造不同的五元组进行探测，为了解决rawsocket性能低下的问题(它会拦截和复制服务器全部的UDP包)，我也是各大论坛寻师问友，后来在slack有人告诉我可以使用bpf，基本上单个服务器rawsocket可以达到6万pps不丢包的性能，当然如果不使用rawsocket而是采用普通的UDP服务器，可以稳定实现80万pps的探测频率，但是又没办法实现狗构造成千上万的PPS。 这都是我们在前期的一些经验的总结，也很有意思，这些都是工程化的过程中才可能获得的宝贵经验，最终我们同学在这个方案的基础上实现了B1骨干网的监控，而且效果非常不错。

这给我了很大的信心。也就是我们也能根据百度自己的网络特点，设计出符合我们自己的网络监控方案。下一步就是解决DCN的网络监控了，我准备替换netradar。彼时netradar还没有移交到我这边的团队。设计的最重要的一点，就是可以快速的验证和部署，时不我待，当时的情况和压力已经不允许我们花半年的时间才去部署一套还不确定的探测方案。

和pingmesh不同，lidar采用一台探测机就可以探测机房内所有的服务器。作为冗余和交叉验证，我们采用机房内一台探测机，机房外一台探测机。如果资源充足，探测机的数量再多一些就更好。

这台探测机从topo数据库中拉取服务器信息，然后选取高质量的服务器作为目标服务器，通过发送TCP SYN包就】进行探测。测试效果不错，后来我们基于这个方案实现了机房内的网络探测1.0。

我们以这个简易的网络架构为例。我们在服务器1部署lidar探测程序，它去探测其他服务器的447端口。实际上我们还会从其他机房不是一个探测程序，探测这个机房的这些服务器。

这样，我们在很短的时间就完成了开发工作并部署，并又花了一个季度的时间进行打磨和调优，当然这些优化我们可以快速的进行更新部署，一次变更就完成了。

原理：三种响应，一个答案

lidar 发一个 SYN 出去，目标的内核 TCP 协议栈会自动响应——这是 TCP 协议栈的底层行为，不需要安装任何软件。也是大家都已经熟悉的三次握手阶段的第一步。

收到什么，就知道什么状态：

就这么简单。不需要 agent，不需要 server 端部署，不需要任何配置。给个 IP 和端口，立刻告诉你结果。

当前最好的方式是探测一个监听的端口，比如 ssh 端口 22等。
实际测试探测一个不存在的端口，有些服务器并不会为每一个SYN请求都返回一个RST，导致误报。
即使是探测一个监听的端口，服务器上可能设置了防止SYN Flooding攻击的策略，也不允许你高频的探测，实际在 20 ~ 100 PPS之间是合理的。

输出长这样：

1

21:37:14, [192.168.1.14 -> 74.48.173.243], sent: 10, received: 10 (SYN-ACK: 10, RST: 0), timeout: 0

每秒一个统计窗口，sent/received/SYN-ACK/RST/timeout 一目了然。丢包了打 [WARN]，正常打 [INFO]。

你会不会担心服务器建立很多的半连接的TCP,会不会影响性能。实际是不会的，首先服务器有防止SYN Flooding的策略，如果收到太多的SYN会丢弃的，其次为了避免被策略丢弃，我们针对每台服务器的探测频率并不是很高，基本上在20pps ~ 100pps之间。

虽然单个服务器才100pps,但是因为一个TOR下我们会选取至少三台服务器，所以只对这些服服务器连接的ToR，它的探测频率是哦300pps, 如果更往上一层Leaf设备，它的探测频率又是几十倍，更往上Spine设备和DC，那探测频率是几万pps到几十万pps了。所以这种方式层级越高，探测的精度越高。

同时，还有一个很有意思的现象：在建立TCP握手的时候，目标服务器不是回传一个TCP+SYN的响应吗，探测服务器收到这个响应，发现它本机并没有监听这个端口(我们使用rawsocket进行旁路处理的)，然后TCP/IP协议栈就会自动发一个RST给目标服务器，目标服务器就会把这个半连接关闭掉。所以实际上，这个半连接很快就被关闭了。这都是自动的。

macOS 和 Linux 的收包差异，踩了坑

lidar 的开发过程中，最头疼的不是发包，是收包。

发 SYN 用 raw socket（SOCK_RAW + IPPROTO_RAW + IP_HDRINCL），macOS 和 Linux 行为一致，一套代码搞定。

收包就不一样了。

Linux 上，raw socket（SOCK_RAW + IPPROTO_TCP）直接就能收到 TCP 响应包。内核处理 TCP 的同时，会把副本投递给 raw socket。简单直接。

macOS 上，同样的代码，一个包都收不到。

原因是 macOS 的内核 TCP 协议栈会"拦截"TCP 报文。raw socket 注册了 IPPROTO_TCP，但内核觉得"这是我的 TCP 连接"，不给 raw socket 副本。BPF 设备（Berkeley Packet Filter）是唯一的出路——在链路层抓包，绕过 TCP 协议栈。

1
2
3
4
5
6

// macOS: 打开 /dev/bpf* 设备，在链路层抓包
// 1. 打开 /dev/bpf* 设备
// 2. ioctl BIOCSETIF 绑定到出接口
// 3. 设置 immediate mode + promiscuous mode
// 4. 读取 BPF 数据包（BPF 头 + 链路层头 + IP + TCP）
// 5. 剥离链路层头，解析 IP/TCP

拿到的是原始链路层帧，带 14 字节的以太网头。得手动剥离，再解析 IP 和 TCP。

Linux 上拿到的直接就是 IP 包，没有链路层头。同一套解析逻辑，入口不同。

这是两个操作系统内核的设计差异，没有谁对谁错。但写代码的人得知道。

我们内部都是Linux服务器，所以没有这个问题，但是开源的版本我希望更通用些，方便使用苹果本的同学也能测试和使用，所以代码做了兼容。

在高吞吐服务器上，BPF 过滤器救了命

Linux 上用 raw socket 收包有个隐患：SOCK_RAW + IPPROTO_TCP 会收到所有 TCP 报文。

在万兆网卡、几十万 pps 的服务器上，内核会把海量无关的 TCP 包拷贝到用户态，导致性能低下，吞吐率不高设置丢包。

解法是内核层过滤。SO_ATTACH_FILTER 挂载一个 classic BPF（cBPF）程序，在内核里就把不相关的包丢掉，只投递匹配探测端口的报文：

1
2
3
4
5
6
7

A = packet[14] & 0x0f * 4          // 从 IP IHL 算 TCP 头偏移
A = packet[A+0..1]                  // 取 TCP srcPort（目标端口）
if A != serverPort → reject          // 不是我们要的端口？丢掉
A = packet[A+2..3]                  // 取 TCP dstPort（探测源端口）
if A < localPort → reject
if A >= localPort + count → reject
accept

12 条 cBPF 指令，硬编码在代码里。内核只把匹配的极少数报文投递上来，用户态几乎零开销。

1
2
3
4
5

func buildBPFProbeFilter(serverPort int, srcPort uint16, portCount uint16) []sendrecv.BPFInstruction {
    // 手工构造 BPF 指令序列
    // 在内核层完成 srcPort 和 dstPort 的过滤
    // ...
}

源端口轮转，覆盖 ECMP 多路径

和 bitflip 一样，lidar 也面临多路径覆盖的问题。

两个固定 IP 之间，TCP 五元组如果固定（源端口不变），哈希结果始终相同，永远只走一条链路。怎么覆盖所有可能路径？

lidar 的做法是源端口轮转。每次发完一轮（所有目标各发一个 SYN），源端口 +1。配置了 100 个源端口，就跑 100 轮，每条可能的 ECMP 路径都有概率被覆盖到。

1
2
3
4
5

// 每轮所有目标各发一个 SYN 后，源端口 +1
s.currentPort++
if s.currentPort >= s.srcPort+s.portCount {
    s.currentPort = s.srcPort  // 回绕
}

这不是完美的"全覆盖"——你没法精确知道哪个端口走哪条路——但 100 个源端口在统计意义上足够覆盖典型的多路径拓扑。

用起来

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 探测单个目标的 80 端口
sudo ./lidar -t 10.0.0.2 -p 80

# 多目标探测
sudo ./lidar -t 10.0.0.2,10.0.0.3,10.0.0.4 -p 22

# 高速率探测 30 秒
sudo ./lidar -t 10.0.0.2 -p 80 --rate 100 -d 30s

# 发送固定 1000 个包
sudo ./lidar -t 10.0.0.2 -p 80 -n 1000

# 攻击队友好帮手：Verbose 模式看丢包端口
sudo ./lidar -t 10.0.0.2 -p 80 -v

也支持配置文件：

1
2
3
4
5
6
7

{
  "target_addrs": "10.0.0.1,10.0.0.2",
  "server_port": 80,
  "rate": 10,
  "span": "1s",
  "delay": "3s"
}

1

sudo ./lidar -c lidar.json

三个工具，三件不同的事

bitflip 做 UDP 丢包和改包检测，baize 做常态的丢包和改包检查，lidar 做 TCP SYN 端口可达性探测。三个工具解决的问题不同，但底层技术栈是相通的：raw socket 构造报文、BPF 过滤收包、时间桶统计、速率控制。

注意， lidar没办法进行改包检测，你知道为什么吗？所以下一个要开源的工具是mping。

冷知识
最早是从radar这个名字开始，为我们的工具起名 sonar、lidar。
后来我们的平台就用中国古代神话人物和神兽命令：比如离娄、白泽和飞鸿。

这只是 nettools 的冰山一角。后续还有网关设备监控、evr的监控工具、定位工具，以及巨量监控数据的处理方案。

项目地址：https://github.com/baidu/nettools

欢迎 Star、试用、提 Issue 和 PR。

5000 包/秒高频探测 + 无需时钟同步的单向丢包检测 + 全路径覆盖。内部跑了多年，现在开源了。

先讲一个实际case。

线上服务突然超时，用户投诉电话打爆了。打开监控大盘，一切正常——没有任何告警。折腾两小时，最后发现是某条链路间歇性轻微丢包，丢包率 0.3‰，传统监控压根抓不到。

百度内部，baize 跑了多年：

• 集群间高频探测：机房内跨集群链路fullmesh监控
• 机房间fullmesh探测：机房间,LCC机房链路fullmesh监控()
• 混合云高频探测：A区和C区之间的混合云链路监控，5000 pps，秒级发现异常
• 专线 SLA 监控：运营商专线质量持续监测，为 SLA 考核提供数据支撑
• 网络改造保障：设备割接、链路升级期间持续监控，改造前后对比一目了然
• 故障回切验证：从灾备切回主链路后，确认回切路径无丢包、无 bitflip后再切流

06 开源与社区

baize 是百度 nettools 工具集的第二个开源工具，MIT 协议。

• GitHub: https://github.com/baidu/nettools
• 使用指南：https://nettools.rpcx.io/baize.html
• 语言：Go 1.26+
• 平台：Linux / macOS，AMD64 / ARM64

内部版还支持从数据库拉配置、推数据到 Kafka 聚合，开源版做了简化，但留了可插拔的 Sender 接口——你可以自己实现，把数据发到 ClickHouse、Prometheus 或者任意后端。

网络监控这件事，不是能不能做的问题，是做得够不够细的问题。

每一条链路、每一个端口、每一个比特，都值得被监控。 这是我们在百度内部坚持的标准，今天开源出来，希望对你有用。

被间歇性轻微丢包折磨过的话，去 GitHub 点个 Star，试试 baize。

Go 网络编程，大家第一反应就是 gopacket。但如果你用过 Scapy，你会发现 gopacket 的 API 繁琐得让人抓狂。goscapy 把 Scapy 的优雅搬到了 Go 里——流式构建、自动校验和、协议自动推断、一行代码搞定数据包，还能嗅探、发送、收响应。

最早接触到python生态圈的scapy是两年前，在和交换机的同学搞交换机探针的时候，他写了几行python代码就实现了一个发包探测程序，我立马就被scapy吸引了，居然写网络测试程序可以这么简单？

03 数据包解析：自动协议推断

构造包只是故事的一半，解析包是另一半。

goscapy 的 Dissect 能从原始字节自动推断出完整的协议栈：

1
2
3
4
5
6
7

raw := []byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xaa, 0xbb, ...}
pkt, _ := packet.DissectByProto(raw, "Ethernet")
fmt.Println(pkt.String()) // "Ethernet / IP / ICMP"

// 访问具体层
ipLayer := pkt.GetLayer("IP")
srcIP, _ := ipLayer.Get("src") // net.IP{192, 168, 1, 1}

解析引擎靠注册表驱动。每一层解析完后，查 keyField 找到下一层——Ethernet 看看 type 字段（0x0800 → IP），IP 看看 proto 字段（6 → TCP），TCP 看看 dport（80 → HTTP）。VXLAN 这种隧道协议还能递归解析内层包，最多支持 8 层嵌套。

启发式规则也注册了一大堆：UDP 53 端口 → DNS，TCP 80 → HTTP，UDP 4789 → VXLAN，IP proto 47 → GRE……抓到的包基本都能自动识别到应用层。

04 嗅探和收发包：Scapy 的 sr/srp 到 Go

写过 Scapy 的人一定对 sr() 和 sr1() 不陌生——发一个包，自动等响应，还能做协议级匹配。goscapy 把这套逻辑完整搬过来了。

发包

1
2
3
4
5
6
7
8
9

// 构造结构化的 Packet 对象（不是 Build 出 []byte）
pkt := goscapy.NewEthernet().
    DstMAC("ff:ff:ff:ff:ff:ff").
    Over(goscapy.NewIP().SrcIP("192.168.1.1").DstIP("8.8.8.8")).
    Over(goscapy.NewICMP().Type(8).Code(0)).
    Packet()

sendrecv.Send(pkt, "eth0")   // L3 发送（IP 层，OS 补 Ethernet）
sendrecv.Sendp(pkt, "eth0")  // L2 发送（完整以太网帧）

发包收响应

1
2
3
4
5
6

// 类似 Scapy 的 sr1()：发 ICMP Echo，等第一个响应
sent, reply, err := sendrecv.Sr1(pkt, "eth0", 3*time.Second, nil)
if reply != nil {
    ipLayer := reply.GetLayer("IP")
    srcIP, _ := ipLayer.Get("src") // 8.8.8.8 的回复
}

DefaultMatch 自动匹配响应包——ICMP Echo Request 配 Echo Reply（ID 匹配），TCP SYN 配 SYN-ACK（端口翻转 + ack = seq+1），UDP 配端口翻转，DNS 匹 transaction ID，ARP 配 IP 交换。不用写一行匹配逻辑。

gopacket 更适合：需要解析冷门协议、对 pcap 文件读写有强需求、已经重度依赖 libpcap 生态的项目。

goscapy 更适合：网络工具开发、安全扫描、协议测试、网络监控探测——任何需要快速构造和收发数据包的场景。纯 Go 部署简单，API 用起来舒服。

10 性能：零拷贝序列化

goscapy 在序列化上做了不少优化：

• SerializeInto：直接写入目标 buffer，无额外堆分配
• BuildInto：用户提供 buffer，整个包一次序列化完成
• RecvInto：收包直接读入用户 buffer，减少一次拷贝
• 校验和零拷贝：checksumIPv4Pseudo 直接折叠多个内存区域，不拼接
• WireSize：预计算序列化大小，一次分配精确大小的 buffer

1
2
3

// 零拷贝发送
buf := make([]byte, 1500) // MTU 大小的 buffer
result, err := pkt.BuildInto(buf) // 直接写入，无额外分配

还有 Linux 特有的高性能接收模式——AF_PACKET mmap、零拷贝 (PACKET_QDISC_BYPASS)、io_uring 原始套接字——适合高频探测场景。这些在 examples 目录里有完整示例（23-packet-mmap、21-zerocopy、22-uring-raw-socket）。

11 丰富的示例库

goscapy 自带了 50+ 个示例，覆盖从基础到高级的几乎所有场景：

• 基础：ping、traceroute、TCP SYN 扫描、ARP 扫描
• 协议：DNS 客户端、DHCP 客户端、NTP 客户端
• 隧道：VXLAN 封装、GRE 隧道、ERSPAN
• 高级：PCAP 读写、TCP 流重组、BPF 过滤
• 性能：零拷贝收包、io_uring、packet mmap、批量发送
• 无线：802.11 WiFi 帧、蓝牙 HCI/L2CAP、Zigbee、LoRaWAN
• 安全：p0f 指纹、端口扫描、ARP 扫描

每个示例都是可编译运行的小程序，直接 go run 就能跑。

项目地址：github.com/smallnest/goscapy

纯 Go，MIT 协议，零 C 依赖。go get github.com/smallnest/goscapy 就能用。

如果你在做网络工具、安全扫描、协议测试、监控探测——试试 goscapy，可能会让你重新爱上 Go 网络编程。

大多数 agent 团队不构建运行时。他们采用一个。LangChain、LangGraph、OpenAI Agents SDK、Anthropic SDK、CrewAI、AutoGen——循环、工具、记忆、编排，都是作为一个单一决策从货架上挑选的。运行时是一个你 import 的框架。如果里面的什么东西不合适，你就 fork 它、跟它斗争、或者绕过它。

我认为这种形态是错的，这就是为什么每个长期运行的 agent 团队最终都会从头重写它的运行时。运行时不是一个东西。它是十到十二个不同的东西被捆绑在一起，因为周围的生态系统没有给你组合它们的方式。Pi agent 的包化走在了正确的路上，但它们仍然处在"再添加一个服务并与所有其他服务集成"的范式中。iii 引擎将所有 worker 一视同仁，完全移除了集成逻辑。provider 路由器、凭证保管库、策略引擎、审批网关、模型目录、会话存储、预算追踪器、调用后 hook 扇出、持久化的 turn 循环——这些都是独立的关注点。它们全都可以与你的队列、HTTP/API 服务器、流式传输、甚至浏览器 worker 互操作。一个把它们当作整体发布的框架，是在卖给你一个你本不必做的权衡。

iii 底层的赌注是：它们不应该是一个整体。应该有一组 worker 运行在共享引擎上，每一个都可替换，每一个可独立版本化，每一个通过一个单一原语连接起来：一个触发器（iii.trigger()），其他每个 worker 也都使用它。运行时变成一组可安装的 worker 堆栈，"构建你自己的"不再意味着"fork 一个框架"，而是意味着"替换几个 worker"。

本文带你看看这实际上是什么样的。今天驱动一个 iii agent turn 的完整技术栈，为什么每一层都是自己的 worker，以及你如何替换其中任何一层。

Agent 运行时必须完成的 15 项工作

如果你把一个生产级 agent 运行时剥离回它的职责，你会得到大致像这样的一个列表：

1. 接受来自客户端的 turn 请求并持久化它

2. 为被调用的模型 provider 解析凭证

3. 查询所选模型实际能做什么（视觉、工具、流式传输、上下文窗口）

4. 驱动每个 turn 的状态机：预配、流式传输 assistant、运行工具、引导、清理

5. 加载并提供 skill 描述体，说明每个函数的请求格式、错误码和使用说明

6. 组装系统提示词：模式段落、身份前言、工作目录、默认 skill 附录

7. 当模型产生 token 时将 token 流式推送回客户端

8. 在运行前检查每个工具调用（这只是一个函数）是否符合策略

9. 暂停需要人工决策的工具调用，并将决策结果路由回正确的 turn

10. 按工作空间或 agent 跟踪 LLM 支出

11. 在工具调用前后运行 hook（日志记录、脱敏、自定义副作用）

12. 将会话持久化为分支树，以便 fork 和恢复正常工作

13. 当上下文窗口填满时压缩会话历史

14. 发出 UI 订阅的事件流

15. 我看到每家 agent 公司构建中都缺失的一块：在每一步携带一条 OpenTelemetry 追踪，这样你才能调试它

每个严肃的 agent 运行时处理其中大多数。昂贵的处理全部。廉价的走捷径，然后在进入生产环境后重新构建那些捷径部分。框架将它们捆绑成一个单体，并发布每样东西的一个版本。最后这一点是让你付出代价的部分，因为一年后，你会发现你想要的策略引擎不是框架自带的那个策略引擎，而替换它意味着替换整个运行时。

iii 运行时将这十三项工作中的每一项都作为独立的 worker 部署在 workers.iii.dev 注册中心上。每个使用相同的 WebSocket 协议。每个在相同的引擎总线上注册函数和触发器。每一个都可以 iii worker add、可替换、可用 SDK 以任何语言编写。

按 worker 拆解技术栈

以下是来自 iii-hq/workers 单体仓库的实际生产级技术栈，每个 worker 的职责用一句话概括。整个代码包发布在 github.com/iii-hq/workers/harness：

十一个 worker。一个引擎。每个都有发布的版本。每个都可以作为独立进程运行（开发时 pnpm dev:<worker>，作为发布二进制时 iii worker add <specific-worker>），或者作为将它们一起启动的组合入口点的一部分。

这之所以重要：表中的每个框都是一个别人可以递给你一个不同 worker、而你可以保留其余部分的地方。不喜欢静态模型目录？换一个注册了 models::list 并从实时 API 读取的 worker。不喜欢基于文件的凭证？换一个注册了 auth::get_token 并从密钥管理器读取的 worker。想要一个针对不同分支 workflow 的不同 turn FSM？替换 turn-orchestrator——每个依赖方通过相同的总线调用 run::start 并读取 turn_state，所以技术栈的其余部分不会改变。

循环的实际运行方式

一个 turn 的形态如下，按 worker 的触发顺序逐一遍历。

浏览器、CLI 或聊天客户端通过 harness::trigger POST 一个 turn，携带 {session_id, message_id, payload}。harness meta-worker 将 payload 转发给 run::start。这一跳的存在是为了让 OpenTelemetry span 包装器可以将 session ID 和 message ID 作为 baggage 植入，传播到技术栈中每个 worker 的每个嵌套 iii.trigger 调用。另一端的追踪树是一个连接的图。

run::start 落在 turn-orchestrator 上。它持久化运行请求，在 iii state 的 session/<sid>/turn_state 处植入初始的 TurnStateRecord，然后立即返回。实际工作在持久化的每状态机内部完成，由发布到 turn-step FIFO 的消息唤醒。

两个终止状态是 stopped（通过 finishSession() 正常退出）和 failed（未预期的处理程序抛出被路由到此处，ack 队列使其停止重试，并发出 message_complete{stop_reason:'error'} 加上 agent_end，以便 UI 显示原因）。Teardown 是一个内联的 finishSession() 调用，从任何 turn 结束路径调用，而不是单独的入队步骤。

provisioning 做三件事。如果运行需要隔离执行，它启动一个 iii-sandbox 微虚拟机。它为 system_default_skills（默认为 ["iii://iii-directory/index"]）中的每个命名空间调用 directory::skills::download，使 iii-directory 预先缓存运行启动时所需的 skill 描述体。然后它分三层组装系统提示词：从 run_request.mode 中选取的模式段落（plan、ask 或 agent），iii 身份前言教给模型 agent_trigger 约定和 directory::skills::get 按需发现模式，以及 agent 启动时附带的默认 skill 索引。调用方可以通过在 run::start 上传递 system_prompt 来覆盖整个提示词；否则由编排器构建它。函数 schema 来自实时引擎目录。

assistant_streaming 在匹配此次运行的 provider 字段的 provider worker 上调用 provider::<name>::stream。provider worker 通过 auth::get_token（auth-credentials）拉取凭证，将模型的 SSE 响应流式推送到 iii channel 中，编排器消费该 channel，在 agent::events 上发出 message_update 事件供 UI 扇出。Channel 创建和读取循环位于 provider-stream.ts 中基于拉取的 MessagePump 之后，因此流式状态专注于状态转换。

当 assistant 返回工具调用时，FSM 进入 function_execute。每个工具调用都经过 dispatchWithHook——编排器中唯一的卡控点。consultBefore 直接调用 policy::check_permissions，带有 5 秒超时。策略 worker（在默认技术栈中，就是 harness meta-worker）读取 iii-permissions.yaml，将调用的 function_id 与规则集进行匹配，返回三种结果之一：

• allow：继续分发；编排器触发目标函数并写入结果
• deny：以 DenialEnvelope 短路分发，结果成为一条拒绝记录
• needs_approval：单个调用被停放到 turn 的 awaiting_approval 列表中。批次的其余部分继续分发。仅当有一个或多个待审批条目时，turn 才会转换到 function_awaiting_approval

审批唤醒是响应式且共享的。编排器在 scope approvals 上注册了正好一个 turn::on_approval 状态触发器。当控制台调用 approval::resolve 时，approval-gate worker 将 approvals/<sid>/<cid> = {decision, reason} 写入 iii state。该写入触发 turn::on_approval，推进受影响的会话。function_awaiting_approval 只读取刚刚到达的决策，在每个决策到达时分发它（allow 成为预批准的分发，deny 或 aborted 成为合成的拒绝），并在 awaiting_approval[] 为空时推进。无需为每个调用注册恢复函数。无需启动时重新扫描来恢复待处理的审批。一个触发器覆盖所有会话。

默认拒绝是构造性的：如果策略 worker 不可达，或者 5 秒超时触发，consultBefore 以 gate_unavailable 信封拒绝调用。如果 iii::durable::publish 本身出错，hook fanout 返回 publish_failed: true，编排器将其视为拒绝。

这种形态带来了几项延迟优化。当没有持久化订阅者为该主题注册时，函数调用后 hook 通过订阅者存在缓存短路 publish_collect，每个执行的函数调用移除大约 500 毫秒。tearing_down 被内联到 finishSession() 中，每个 turn 移除一次持久化队列跃点。context-compaction 订阅了编排器在 turn 边界发出的专用 agent::turn_end 流，因此压缩器的唤醒是每个 turn 一次而非每个事件一次。session-create 扇出状态触发器仅通过 scope 进行门控并在进程内匹配，因此之前每次写入的 harness::session::is_create_event RPC 已经消失。

批次完成后，steering_check 决定是继续、停止还是达到 max_turns。如果继续，循环回 assistant_streaming。如果停止或达到上限，finishSession() 内联运行：发出 agent_end，释放 sandbox，转换到 stopped。

在整个运行过程中，每个参与的 worker 发出的 OTel span 都带有 iii.session.id、iii.message.id 和 iii.function.id 标签。这些标签正是引擎的 engine::traces::group_by 读取的内容，用于在追踪 UI 中填充"按会话分组"/"按消息分组"/"按函数分组"。埋点是自动的：src/runtime/worker.ts 将每个 registerFunction 包装在 Proxy 中，因此不必有任何 worker 代码记住要添加 span。

构建你自己的

有趣的部分在于，以上所有 worker 都不是特殊的。每一个都是一个打开 WebSocket 连接到引擎、注册一些函数和触发器并运行的进程。这个契约与每个应用 worker 使用的契约完全相同。运行时构建在与你的业务逻辑相同的原语之上。

这意味着"构建你自己的运行时"分解成与"编写任何 worker"相同的操作。你选择你想替换的层，你写一个在总线上注册相同函数的 worker，你 iii worker add 它，技术栈的其余部分就开始使用你的 worker。

有两个层没有出现在上述 worker 表中，但对运行时的行为很重要。Skills 是每个 worker 告知其函数功能的机制。每个 worker 可以在 iii://<worker>/<function> 处发布一个 skill，agent 在首次调用该函数之前通过 directory::skills::get 获取它。系统提示词在每个 turn 由模式段落、iii 身份前言以及运行配置的默认 skill 描述体组装而成。两者都是总线驱动的：skill 由 iii-directory worker 提供服务，系统提示词由 turn-orchestrator 组装。两者都可替换。

五个具体示例。

用实时 API 替换模型目录。 写一个 worker，注册 models::list、models::get、models::supports。让它每 N 分钟从你 provider 的目录端点获取数据并缓存。发布它。iii worker add your-org/dynamic-models-catalog。停止静态的 models-catalog worker。turn-orchestrator 感知不到任何差异。它调用 iii.trigger('models::list')，引擎路由到最近注册了该函数 ID 的任意 worker。

添加新的 provider。 provider-kimi 和 provider-lmstudio 已经证明了这种形态。每个都是一个 worker，注册 provider::<name>::stream 和 provider::<name>::complete，将来自上游 API 的 SSE 流导入 iii channel，并通过 budget::record 将其模型用量写入 llm-budget。添加第五个 provider 就是写一个文件夹，包含一个 iii.worker.yaml 和一个 register.ts。发布到注册中心，或保留在本地。turn-orchestrator 通过每次运行的 provider 字段选择 provider；新 provider 在 worker 连接的瞬间即可使用。

从私有制品库提供 skill。 写一个 worker，注册 directory::skills::get 和 directory::skills::list，后端是内部文档系统或私有 S3 存储桶。断开或重命名默认的 iii-directory worker。编排器的 bootstrap 为每个命名空间调用 directory::skills::download；你的 worker 来响应。agent 的"在调用新函数前获取每个函数的 skill"模式保持不变，因为 wire 格式相同。

完全覆盖系统提示词。 run::start 接受一个可选的 system_prompt 字段。传入它，编排器将逐字使用你的字符串，跳过模式段落 + 身份前言 + skill 附录的组装。当你有一个已有的提示词资产，想让运行时原封不动地遵守时，这很有用。Skill 下载仍在 bootstrap 中运行，因此 agent 即使使用自定义提示词也保留 directory::skills::get 按需发现能力。

替换审批网关的 UI 界面。 默认的 approval-gate worker 注册 approval::resolve。wire 模式是一次函数调用：

1
2
3
4
5
6

iii.trigger('approval::resolve', {
  session_id: '...',
  function_call_id: '...',
  decision: 'allow' | 'deny' | 'aborted',
  reason: 'optional human text',
})

处理程序将 approvals/<sid>/<cid> = {decision, reason} 持久化到 iii state。编排器唯一的 turn::on_approval 状态触发器捕获该写入并唤醒正确的会话。如果你想从 Slack 而非控制台驱动审批，写一个 Slack worker，监听 /approve <id> 和 /deny <id> 斜杠命令，然后用正确的 payload 调用 approval::resolve。编排器感知不到任何差异。整个 approval-gate worker 保持原封不动。你添加了一个新 worker；你没有替换已有的那个。

如果你想要不同的策略引擎（OPA、Cedar、你自己的 DSL），写一个 worker，注册 policy::check_permissions，返回 { decision, rule_id?, matched_constraint? }。断开默认的策略 worker（它包含在 harness meta-worker 中，所以你需要禁用那个处理程序或者运行一个精简版的 meta-worker）。turn-orchestrator 的 consultBefore 感知不到任何差异。相同的 5 秒超时、相同的 fail-closed 语义、相同的 wire 格式。

这些示例的重点不在于具体的替换项。而在于操作的形态。iii 技术栈中的每个运行时层都可以通过总线上的一两个函数 ID 访问。替换一个层就是写一个注册了这些 ID 的 worker。系统的其余部分保持不变。

运行时是一个滑块，而不是分岔路口

经典的运行时争论以薄 vs 厚的框架来表述。Anthropic 的薄循环 vs LangGraph 的显式 DAG。这种框架假设你选择一边并接受它。

当运行时由同一总线上的 worker 组合而成时，薄 vs 厚只是你安装了多少个 worker 的计数。薄运行时是 turn-orchestrator 加上 provider-anthropic 加上 auth-credentials 加上最小化的 harness meta-worker。仅此而已。没有审批、没有预算、没有策略引擎、没有 hook fanout。运行任何东西。信任模型。适用于自主研究 agent、实验性循环、任何内部用途。

厚运行时是所有 worker 加上 context-compaction 加上自定义策略 worker 加上自定义 approval-gate 加上 Slack 集成的审批界面加上按工作空间执行支出上限的预算 worker。适用于运行面向客户 workflow 的 agent，其中每个工具调用都需要可审计，每次模型支出都需要汇总到财务仪表板。

薄与厚之间的架构距离不是重写。它是一个配置更改。相同的原语、相同的 wire 协议、相同的追踪格式、相同的可观测性方案。通过在 config.yaml 中添加和移除 worker 来移动滑块。其他一切保持不变。

这也适用于单个 worker 内部。turn-orchestrator 刚刚发布了一个重构，将其 FSM 从十一个状态压缩为七个，删除了每个调用的 turn::approval_resume::<sid>/<cid> 机制，代之以在 scope approvals 上的一个响应式 turn::on_approval 状态触发器，并将 tearing_down 内联到 finishSession() 调用中。技术栈中的其他每个 worker（approval-gate、session、llm-budget、providers、models-catalog、auth-credentials、hook-fanout、context-compaction）保持不变。approval::resolve wire 格式没有变化。契约保持住了。这就是组合性带给你的特性：一个 worker 的重大内部重写是自包含的变更，因为每个邻居都通过总线级的函数 ID 与它通信。

这是框架模型无法给你的部分。框架替你选择了滑块上的一个位置并锁定你。worker 模型将滑块留在你手中。

这在实际中意味着什么

如果你一直在某个框架之上运行 agent，并且感受到大多数团队在规模化时遇到的相同的边界问题，那么答案很可能不是"用我们自己的框架重写运行时"。策略引擎无法按你需要的方式扩展。审批 UI 被捆绑在框架的聊天界面里。凭证存储无法与你的密钥管理器对话。预算追踪器位于追踪无法看到的 sidecar 数据库中。答案是切换到一个运行时从一开始就被解耦的基座。

最快感受到这个论点的方法是 clone github.com/iii-hq/workers，pnpm install，pnpm build，然后运行组合入口点。你将获得指向 iii 引擎的完整十四 worker 运行时。你可以通过从启动列表中移除 worker 条目来禁用任何 worker。你可以通过写一个注册了相同函数 ID 的替代品来替换任何 worker。你可以通过向其 hook 主题添加订阅者来扩展任何 worker。hook-fanout::publish_collect 是每个 iii hook 构建于其上的通用机制。

文档在 iii.dev/docs。引擎在 github.com/iii-hq/iii。Worker 注册中心在 workers.iii.dev。运行时代码包在 github.com/iii-hq/workers/harness。

赌注

运行时不是你安装的东西。运行时是你的系统为了让一个 agent 持久化、安全、可观测地运行而必须做的一组工作。框架时代之所以将这些工作捆绑在一起，是因为底层没有任何东西给你组合它们的方式。

iii 的赌注是：一个原语——一个 worker 通过 WebSocket 连接到引擎并注册函数和触发器——小到足以分别吸收这每一项工作，并且由此产生的技术栈比任何框架都更有用，因为每一层都可以独立替换。

你不是"采用" iii 运行时。你安装你想要的 worker，编写你需要的 worker，最终获得一个完全匹配你系统形态的运行时。每一层相同的协议。每一次调用相同的追踪。从注册中心拿来的组件和你自行发布的组件，使用同样的 iii worker add。

这就是当基座形态正确时，"构建你自己的 agent 运行时"该有的样子。选择 worker。编写缺失的。组合。运行时就是这种组合。

加入我们，一起构建现代世界所需的完美 agent 运行时：discord.gg/iiidev

iii 是开源的。从 iii.dev/docs 开始。运行时 worker 在 github.com/iii-hq/workers，引擎在 github.com/iii-hq/iii。

— Mike Piccolo, 创始人兼 CEO

src/ 下面 200 多个文件平铺在一个目录里，没有分层，没有模块边界。一个叫 UserService 的类 1800 行，发邮件、对接支付、状态管理全塞在里面，还挂着三个 TODO 标着"后面要重构"。业务逻辑全堆在 Service 层，Model 类只剩 getter 和 setter，贫血得像张纸。数据库查询藏在 for 循环里，每循环一次发一条 SQL。你问老员工这模块谁负责，得到一句："这个……已经没人记得了。"

Martin Fowler 把这类问题叫做"代码坏味道"（Code Smell）。Brian Foote 和 Joseph Yoder 在 1997 年的论文里给了一个更直白的名字：Big Ball of Mud（大泥球）。

祖传的手搓代码是这样。到了 vibe coding 时代，AI 生成的代码也没好到哪去，能力差一些的模型甚至更糟糕。

闻到臭味容易，定位臭源难。更难的是知道该先处理哪个、怎么处理。

今天介绍一个叫 /smell 的开源 Skill，专门干这件事。

它不是为你的新项目设计架构，而是对你已有的项目的分析架构，找到不合理的反模式的设计。

它是干什么的

/smell 是一个可以嵌入 Claude Code、Codex、Cursor 等 AI 编程 Agent 的 Skill。在项目里输入 /smell 或"帮我找找代码里的坏味道"，它会扫描代码库，从架构层面到代码层面做一轮完整检测，最后输出一份 Markdown 报告。

报告精确到文件和行号：哪个模块是 God Object，哪里有循环依赖，哪段代码是 N+1 查询，哪个类违反了单一职责。每个问题都附带代码证据和重构建议。

知识库整合了软件架构领域几十年的积累：

• Martin Fowler 的《重构》和《分析模式》
• Robert C. Martin 的 SOLID 原则
• Eric Evans 的领域驱动设计（DDD）
• Foote & Yoder 的 Big Ball of Mud 论文
• Clean Architecture、Onion Architecture、Hexagonal Architecture 等主流架构风格
• 一套算法复杂度反模式检测规则

相当于把一个资深架构师十几年攒下的"闻臭味"经验，塞进了一个命令里。

八个检测维度

1. 架构级反模式

最严重的层级。Big Ball of Mud（根本没有架构）、Distributed Monolith（声称是微服务，改一个功能得同时部署五个）、Anemic Domain Model（贫血模型，逻辑全在 Service 层，Domain 对象只剩 getter/setter）、Violated Layer Boundaries（层级穿透，领域层直接 import 基础设施层）。

2. 耦合问题

循环依赖（A import B，B 又 import A）、Content Coupling（直接改另一个模块的内部状态）、Common Coupling（到处用的全局变量和单例）、Stamp Coupling（传一整个大对象进去只用两个字段）。

3. 内聚性问题

God Object（一个类 800 行、30 个公开方法，管了十件不相关的事）、Shotgun Surgery（改一个需求要动 7 个文件）、Feature Envy（一个方法调别人家方法比调自己的还多）、Data Clumps（同样的参数组合反复出现在不同函数签名里）。

4. 设计原则违反

SOLID 原则的各种违反场景、DRY 重复代码、KISS 过度工程化、YAGNI 为假设的未来需求提前写了一堆抽象。

5. 代码级坏味道

Long Method（超过 50 行的函数）、Long Parameter List（参数超过 4 个）、Primitive Obsession（用 string 表示 Email、int 表示金额）、Magic Numbers（if (status == 3) 到处都是）、Dead Code（注释掉的代码块和未使用的 import）。

6. 测试健康度

零测试覆盖的模块、测试耦合了实现细节（测私有方法、mock 内部调用）、依赖真实 I/O 的慢测试。

7. 命名质量

满屏的 Manager、Handler、Util、Helper、Service——等于没起名。还有 snake_case 和 camelCase 混用、同一概念在不同地方用不同名字。

8. 算法复杂度热点

这部分我觉得最有价值。很多工具只管"代码丑不丑"，/smell 还管"代码跑不跑得动"：

• N+1 查询：循环里发数据库请求，100 条数据 = 101 次 SQL
• 嵌套循环 O(n²)：双层 for，数据量一大就原地爆炸
• 循环内线性扫描：includes() 写在循环里，本该用 Set 做 O(1) 查找
• 循环内排序：每次迭代都 sort() 一遍，K × O(n log n)
• 渲染路径重计算：React/Vue 组件里 .filter().map().sort() 没做 memoization
• 选错了数据结构：该用 Map 的地方用了 Array 做 O(n) 查找

怎么用

在 Claude Code 中打开项目，输入：

1

/smell

它会先问分析范围：

1
2
3
4
5

你想分析哪个范围？
  A. 整个项目（全面但耗时）
  B. 指定模块/目录
  C. 仅分析最近改动的文件（git diff）
  D. 仅分析架构级问题（跳过代码级坏味道）

选完之后它会启动多个并行探索任务：扫描项目结构、分析依赖关系、检测模块内聚性、识别反模式签名、评估测试覆盖，同时跑。

分析完成后在 tasks/ 目录下生成报告，比如 tasks/smell-report-2026-05-28-1430.md，终端同时打印摘要：

看到摘要你就知道该从哪下手了。可以直接让 AI 按分析结果做架构优化：

重构完成后 AI 会给出修改报告：

报告长什么样

Executive Summary：检测到的架构风格、整体健康评估、最关键的 3-5 个问题，三段话说完。

架构风格识别：分层架构？模块化单体？微服务？六边形？Clean Architecture？还是 Big Ball of Mud。用一张表对比"期望 vs 现实"。

严重度分级清单：🔴 Critical（必须修）、🟡 Warning（应该修）、🔵 Suggestion（建议修）。

逐条问题分析：类别、严重度、反模式名称、文件行号、违反的原则、代码证据、重构建议。每一条都回答三个问题：这是什么坏味道？为什么它是坏味道？怎么改？

依赖图分析：模块间依赖关系、循环依赖路径、耦合热点。

模块健康度记分卡：每个模块的代码行数、God Object 风险、耦合度、内聚性、测试覆盖率。

Smell 分布统计：八个维度各发现多少问题，按严重度排列。

重构路线图：当前 Sprint 立即行动、1-3 个月短期改善、3-12 个月长期演进。分阶段治理，不用一口气全改完。

一个实际场景

接手一个迭代了两年的 Go 项目，不确定架构质量，跑一遍：

1

/smell 分析这个 Go 项目的架构质量

它发现：

1. internal/model/ 下的结构体全是贫血模型，只有字段没有方法，逻辑全在 internal/service/。典型的 Anemic Domain Model，应该把行为移回领域对象。
2. internal/service/order.go:233 有 N+1 查询，遍历订单时逐条查商品。改成 WHERE id IN (...) 批量加载就完了。
3. pkg/auth 和 pkg/user 互相导入，循环依赖。抽取一个公共接口可以打破循环。
4. internal/handler/ 下 6 个文件都有大段重复的参数校验逻辑，违反 DRY。提一个公共校验中间件。
5. 23 处魔法数字，if order.Status == 3 随处可见。定义个 const StatusCompleted = 3 或者用枚举。

报告附带了分阶段的重构路线图。你按优先级一步步来就行，不用面对整个代码库发呆。

快捷模式

只想看致命伤，不等全面分析：

1

/smell 快速检查一下架构

跳过代码级和命名级检测，只跑架构反模式、循环依赖、God Object、N+1 查询这些 Critical 级别。几分钟出结果。

也可以只关注一个维度：

1

/smell 只分析算法复杂度热点

就只找嵌套循环、N+1 查询、选错数据结构这些性能问题。

为什么需要它

有人会说："这些坏味道我自己也能看出来啊。"

如果你有十年架构经验、Fowler 和 Uncle Bob 的书都读过、反模式论文烂熟于心，当然可以。但大多数团队不是这样。

团队里的初中级开发看不出 Anemic Domain Model 有什么问题，他们觉得"Service 写逻辑、Model 放数据"天经地义。即使你自己有经验，一个 10 万行的项目你也看不过来。看了三天同一套代码，嗅觉已经疲劳了。Code Review 通常只关注功能正确性和代码风格，没人在 PR Review 的时候画依赖图、算圈复杂度。

/smell 填补的就是这个空缺。它给你证据，你自己做决策。每个问题都标了严重度，你根据优先级和资源决定修哪些。

安装

这个 Skill 内置在 goal-workflow 的 skills 集合中。已配置 goal-workflow 的直接用 /smell。

安装命令：

1

npx skills add smallnest/goal-workflow --skill smell

用 Claude Code 的话，也可以直接把 SKILL.md 放到 .claude/skills/smell/ 目录下，立刻生效。

写在最后

代码坏味道是一天天堆出来的。每次赶 deadline 时的妥协，每次"只加一个 if"的侥幸，每次 copy-paste 省下的五分钟，都在给代码库增重。

治理的难点从来不是"要不要做"，而是"从哪开始"。/smell 给你一张问题地图，标清楚了臭在哪、有多严重、该按什么顺序清理。路还是得你自己走。

代码是给人读的，顺便让机器执行。如果你自己都不想读自己的代码，让 AI 先帮你闻闻吧。

一个阶段有一个阶段的玩法。

现在我看到了另一种路子：大家直接用 Claude Code、Codex、OpenCode、Pi 这些 coding agent "套壳"来实现智能体。

先说两个很多人搞混的点。

别觉得这些工具只能写代码。Claude Code、Codex 的架构走的是通用智能体模式，早就不止 coding 了。

也别把"套壳"当贬义词。Manus 刚火那阵，就有同事撇嘴说"这不就是 Claude 的套壳"。但你看，Claude、Codex、Antigravity 一个个都在推 SDK，巴不得你基于它们二次开发。牛顿怎么说的，站在巨人肩膀上不丢人。

百度厂内突然蹿红了一个叫 dodo 的应用比龙虾都火。就是靠"套壳"快速出产品原型，再慢慢长成大家离不开的工具。百度公众号和前几天的百度大会上也推了。

OpenClaw 是在 Pi coding agent 上搭起来的智能体产品，上半年火得不成样子。

这些东西免费（CC），有的还开源（Codex CLI、OpenCode、Pi），甚至设计了 harness engineering 这套东西。等于送你一个结实的产品基座，剩下的精力全押在产品和创意上。

一行命令就能跑：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 流式输出（文本→stdout，元数据→stderr）
agent-wrapper run --provider claude-code "解释这段代码"

# JSON 聚合输出（CI/脚本友好）
agent-wrapper run --provider codex "fix the bug" --json

# 带审批+预算
agent-wrapper run --provider claude-code "重构本项目" --approve-all --budget-tokens 50000

# NDJSON 管道输出
agent-wrapper run --provider claude-code "hello" --json --stream | jq .

# 恢复会话
agent-wrapper run --provider claude-code --session-id abc123 "继续"

但更核心的用法是当 Go 库用。go get 一下，import 进去，调 orch.Run。零额外进程，零协议开销。Claude Code、Codex、Pi、OpenCode，五个 provider，一套接口。

套壳的真正价值

套壳不丢人。

丢人的是换一次工具重写一遍胶水代码。丢人的是用着 AI Agent 还得手工管子进程生命周期。丢人的是一晚上 API 烧了几十美刀第二天看账单才后悔。

agent-wrapper 就是个壳。但解决的不是"怎么调一次 Agent"，是"怎么让 Agent 安全地、长期地、按预算地、跨 provider 为你工作"。把"玩一下"变成"能上线"。

项目地址：https://github.com/smallnest/agent-wrapper

最后说几句

大多数人用 Agent 还停留在"命令行输一个 prompt"。这没什么不对，但不够。

十年前我们从手写 SQL 走到满世界 ORM，从手动部署走到 k8s 编排。每一轮变化里，有人站在第一层骂套壳，有人站在第二层埋头套壳，还有人站在第三层——让所有想套壳的人套得更快。

Agent 时代，把壳套好，就是最好的手艺。

线上服务 P99 延迟从 50ms 飙到 800ms，Grafana 告警刷了满屏。CPU profile 翻来覆去看了三遍，热点函数是 sync.Mutex.Lock —— 锁竞争。但问题出在哪？锁粒度大、false sharing、还是并发模型本身选错了？脑子里闪过一堆可能性，每一条都够排查半小时。

如果有一个 Go语言的并发专家和性能专家在身边多好。

还有，对于有经验的老Go程序员，已经习惯了历史的Go语法和代码，对于新的特性反而没有新手更了解，如何保持与时俱进而不被新人所唾弃？

现在，这个愿望变成了现实：三个skill = 顶级有活力的Go语言专家。

三个 Skill，把 Go 的三座大山装进 AI

做 Go 开发这些年，我发现 Go 程序员面对的最棘手的问题，几乎都可以归为三类：

第一类：并发。 死锁、数据竞争、goroutine 泄漏、channel 关闭时机不对、WaitGroup 计数配不平、锁重入导致自死锁……你写过 Go，就一定被其中至少一个坑过。

第二类：性能。 内存分配太多导致 GC 压力大、逃逸分析看不懂、编译器有没有帮你做 BEC 边界检查消除、sync.Pool 到底用对了没、struct 字段排列浪费了多少内存、CPU 缓存 false sharing 在拖累你的并发吞吐……

第三类：代码现代化。 Go 版本在狂飙，每个版本都带来新 API 和惯用法。interface{} 早该换成 any 了。for i := 0; i < n; i++ 能写成 for i := range n。手写的 if a < b { v = a } 不如直接用 min(a, b)。sort.Slice 该退休了，换成 slices.SortFunc。但你不可能记住 Go 1.18 到 1.26 每一个版本的每一个变更——结果就是老代码里到处是"上一代"的写法。

这三类问题有一个共同点：答案分散在无数本书、无数篇博客、无数个 GitHub Issue 里，排查的时候你得像侦探一样在各种资料之间跳来跳去。

我当时刚出版完《Go并发编程实战》，书里把 Go 标准库 sync 包的每一个原语、官方扩展并发库（信号量、SingleFlight、ErrGroup、限流）、13+ 种并发模式、第三方并发库（CyclicBarrier、断路器、WorkerPool）、甚至基于 etcd 的分布式同步原语全部拆开讲了一遍。300 多页，够系统，但——有几个程序员会随身带着一本书写代码？

所以我把这本书"灌"进了一个 AI Skill：chao-go-sync。

然后又想，并发问题解决了，性能呢？于是我又把 Dave Cheney 的 High Performance Go Workshop、dgryski 的 go-perfbook、Effective Go、Go 101 Optimizations 这些 Go 性能领域的"圣经"级资料整合成了第二个 Skill：chao-go-perf。

再然后，项目里的老代码看着越来越扎眼。Go 从 1.0 一路进化到 1.26，每一个版本都引入了更简洁、更高性能的 API 和语法糖——但你不可能手动把所有老项目翻一遍。于是我把 Go 团队 modernize 分析(已集成到go fix命令中)、社区最佳实践、以及 28 个版本感知的转换规则集成起来，做了第三个 Skill：modern-go。它就像一个智能版的 go fix，但不是只修语法——修复惯用法。

三个 Skill 合在一起：一个管并发，一个管性能，一个管现代化。Go 编程的铁三角，齐了。

它们到底能干什么？

说的很玄，来点实际的。这三个 Skill 嵌入 AI Coding Agent 之后，你的 AI 智能体会变成这样：

/chao-go-sync：Go 并发编程专家

你把一段并发代码或者整个项目告诉 AI，它会自动：

诊断 Bug。 代码里有潜在的数据竞争？它不会只告诉你"可能有 race condition"，而是会指出来——这段代码里 WaitGroup.Add 放在 goroutine 内部了，这是典型的竞态模式；那把锁在两个函数里的获取顺序不一致，死锁只是时间问题；你 Copy 了一个 Mutex struct，go vet 能检测到但你没跑。

推荐方案。 "这里保护共享变量，读写比例大概 95:5，应该用 RWMutex 而不是 Mutex"，然后它会给出改写代码。甚至能告诉你 Go 1.21 新出的 OnceValue[T] 比你的手写双重检查锁更干净，Go 1.25 新加的 WaitGroup.Go(f) 能让你的编排代码少写 3 行。

覆盖的广度。 从 sync 包的全部标准原语（Mutex、RWMutex、WaitGroup、Cond、Once、Pool、sync.Map、atomic、channel、context），到官方扩展库（Semaphore、SingleFlight、ErrGroup、限流），到 13+ 种并发模式（半异步半同步、Reactor、断路器、Per-CPU 等），到基于 etcd 的分布式同步原语（Leader 选举、分布式锁、分布式队列、STM），再到哲学家就餐、理发师问题这些经典并发场景——一本书的知识，全在你的 Copilot 里。

即使是沉浸Go语言开发十多年的老兵，而且还出了 Go 并发实战专栏和相关图书的程序员，我写的代码也不能保证没有并发的问题。比如我用它分析我最近开源的 goscapy 网络库项目, 我在Claude Code中输入： /chao-go-sync 分析这个项目有没有并发问题，把发现的文体summary给我即可,它给我了一个详细的分析报告：

结果一目了然，非常详细而且值得学习，接下来你可以根据自己的需求，让它自动修复或者你自己手搓代码。

/chao-go-perf：Go 性能分析专家

性能问题更难排查，因为"瓶颈在哪"本身就是一个需要专业知识才能回答的问题。这个 Skill 解决的就是这个：

数据驱动。 不再凭直觉猜瓶颈——它教你正确写 benchmark（sink 变量防优化消除、b.ResetTimer 去预热噪音）、用 benchstat 做统计验证（p < 0.05 才叫显著），然后用 pprof 精准定位 CPU 热点和内存分配热点。

编译器视角。 很多人写了十年 Go，没看过一次逃逸分析输出（go build -gcflags="-m"），不知道编译器有没有帮你做 BCE（边界检查消除），不清楚哪些函数被内联了、为什么没被内联。这个 Skill 就补这一块——它懂编译器，你能让它帮你分析。

硬件友好。 CPU 缓存、cache line 对齐、false sharing 消除、struct 字段排序减少 padding、分支预测友好代码——这些"高阶操作"在 Skill 里都是速查项。

版本感知。 Go 1.12 到 1.27 每个版本的关键性能变更都记录了。从 Go 1.17 的寄存器传参（5-10% 性能提升），到 Go 1.20/1.21 的 PGO（Profile-Guided Optimization），到 Go 1.24 sync.Map 重写为 hash-trie map——你的 Copilot 知道哪个版本能给你什么免费的性能提升。

我在Claude Code中输入： /chao-go-perf 本项目有性能问题吗？, 它给我了一个详细的性能分析报告：

它会给你它发现的每一个性能问题以及详细分析，还包括改进的建议，你可以决定要不要让AI自动优化，比如你可以选择高优先级的问题进行修复。

/modern-go：Go 代码现代化专家


这是三个 Skill 里最"务实"的一个。它不跟你讲原理，直接动手。

和go fix类似又有点不一样，它会根据你的go.mod选择的Go版本，将Go现代语法优化到这个版本，并提供详细的分析报告。

把项目交给它，它会自动：

扫描 go.mod，确定目标版本。 你的项目声明的 Go 版本是多少，它就应用多少版本能用的转换。Go 1.21 的项目不会收到 Go 1.22+ 的规则——绝对不会引入兼容性问题。

按版本从旧到新，逐条应用 28 种转换。 time.Now().Sub(start) → time.Since(start)（Go 1.0）；interface{} → any（Go 1.18）；for i := 0; i < n; i++ → for i := range n（Go 1.22）；b.N 循环 → b.Loop()（Go 1.24）；sync.WaitGroup.Add + go func → wg.Go(f)（Go 1.25）；errors.As + 临时变量 → errors.AsType 直接表达式（Go 1.26）……覆盖了 Go 1.0 到 1.26 每一个有意义的惯用法升级。

改完自动跑 goimports。 新增的 import（如 slices、maps、cmp）自动补齐，移除的 import 自动清理。代码不会因为改完而编译不过。

输出清晰总结。 哪个文件改了什么转换、总共改了多少处、哪些转换被跳过（因为版本不够）。一目了然。

举个真实例子。这是我前段时间写的一个命令行“斗地主”扑克牌游戏，我在Claude Code中输入/modern-go 本项目, 它给了253285.png)

它不但找出了陈旧的Go写法，还帮我更新到go.mod中定义的Go版本新语法。

安装只需一行命令

三个 Skill 都是 MIT 开源协议，完全免费。如果你用的是 Claude Code 或者支持 Skills 规范的 AI Coding Agent：

1
2
3
4
5
6
7
8

# Go 并发编程专家
npx skills add smallnest/chao-go-sync

# Go 性能分析专家
npx skills add smallnest/chao-go-perf

# Go 代码现代化专家
npx skills add smallnest/goal-workflow --skill modern-go

装完之后，不需要手动触发——当你的代码或对话涉及 Go 并发、性能或现代化相关话题时，对应的 Skill 会自动激活。你也可以手动调用：

1
2
3

/chao-go-sync   # 提一个并发问题
/chao-go-perf   # 分析一段代码的性能
/modern-go      # 现代化你的 Go 代码

三个skill的GitHub 地址：

• chao-go-sync: https://github.com/smallnest/chao-go-sync
• chao-go-perf: https://github.com/smallnest/chao-go-perf
• modern-go: https://github.com/smallnest/modern-go

title: "从需求到上线，让 AI 管理你的整个研发流程"
author: "smallnest"
publish_date: "2026-05-17"
summary: "介绍 goal-workflow：AI 驱动的端到端研发工作流，覆盖 PRD 生成、需求拆解、代码审查、自动提交等全流程自动化"

你是否曾经有过这样的经历：

• 写了一篇 PRD，结果开发实现的时候完全跑偏

• 实现完代码后，发现还有一堆体力活要做：代码审查、写 commit、创建 PR、等待 CI 检查...

• 团队成员对同一个需求理解不一致，导致返工

• 多次开会同步需求进度，但最终代码还是和预期不一样

• Issue 拆得太细或太粗，开发时常卡住不知道下一步该做什么

• 每次提交都要重新敲一遍规范的 commit message，累死了

如果你也遇到过这些问题，不妨来了解一下 goal-workflow。这是一套 AI 驱动的研发工作流系统，覆盖从需求分析到代码交付的完整生命周期。

什么是 goal-workflow？

goal-workflow 是一套专为 Claude Code 和其他 AI 代码编辑器设计的工作流工具集。它通过一系列 Skill（技能）模块，将产品规划、代码实现、代码审查、代码提交、文档优化等环节串联起来。

简单来说，它解决的是 "从想法到发布，中间所有的繁琐工作" 。

四步闭环：从需求到交付

goal-workflow 将软件开发拆分为四个标准化步骤，每一步由一个专属 Skill 驱动：

Step 1：/prd — 需求规划

传统的方式是先写文档，再开会评审需求，再拆解任务。在 goal-workflow 中，你只需要描述一个想要做的功能，比如："给任务管理系统加一个优先级功能"，然后系统会自动提出 3-5 个关键澄清问题（带 A/B/C/D 选项）：

1
2
3
4
5

1. 这个优先级功能主要解决什么问题？
   A. 帮助团队聚焦重要任务
   B. 自动排序任务列表
   C. 支持紧急任务通知
   D. 区分长期和短期任务

你只需要回答"1A, 2C, 3B"这样的格式，系统就能生成结构化的 PRD 和对应的 Issue 列表。每个 Issue 都是独立可实施的，还会标注依赖关系：

1
2
3
4
5

📋 Generated 4 Issues from PRD:
#1: Add priority field to database (backend, high)
#2: Display priority indicator (frontend, high) — depends on #1
#3: Add priority selector (frontend, medium) — depends on #1
#4: Filter tasks by priority (frontend, medium) — depends on #1, #2

支持 GitHub Issues、本地 Markdown 文件和百度 iCafe 多种创建模式。

Step 2：/goal — 功能实现

选择一个 Issue 卡片，Agent 会理解验收标准并端到端实现：

1
2

/goal #42          # 指定 GitHub Issue 编号
/goal tasks/issue-001.md  # 指定本地 Issue 文件

Agent 会自动读取 Issue 描述、分析代码库结构、编写实现代码、运行测试，逐条确认验收标准是否满足。一个 Issue，一次会话，完成一个功能。

Step 3：/review-it — 代码审查

提交前自动审查代码，发现潜在问题并迭代修复。/review-it 的审查原则很有意思——它不盲从：

• 验证后执行：每个发现都通过读取真实代码验证，而非盲目应用
• 拒绝噪音：拒绝不切实际的边界情况、投机性风险、过度重构
• 迭代修复：修复后重新审查，直到无可操作发现
• 最小变更：优先小修复，不做不必要的大重构

它会自动检测你的工作区状态（未提交变更、分支差异等），选择合适的审查模式。

Step 4：/ship-it — 提交交付

代码审查通过后，/ship-it 一键完成收尾流程：

1

git commit → git push → gh pr create → gh pr merge → gh issue close

具体来说：

• 提交代码，commit message 自动关联 Issue 编号
• 推送分支并创建 PR（PR body 包含 Closes #N）
• Squash merge 合入，自动删除远程分支
• Issue 自动关闭（或手动关闭），添加实现总结

遇到 CI 失败、合并冲突等常见问题也有对应的处理策略。

整个过程，四步闭环，除了写代码之外，几乎所有其他工作都是自动化的。

技术特色

1. 端到端闭环：PRD → Issue → 实现 → 审查 → 提交 → 优化
2. 多工具兼容：支持 Claude Code、Codex、OpenCode、DeepSeek TUI
3. 双语支持：中英文触发词，适合中文开发者
4. 可信审查：验证后执行，而非盲目应用
5. 灵活部署：GitHub Issues、本地 Markdown、百度 iCafe 多平台支持

快速开始

1
2
3
4
5
6
7
8

# 全局安装
npx skills add smallnest/goal-workflow -g

# 在项目中使用
/prd 创建需求文档
/goal 开始实现
/review-it 代码审查
/ship-it 提交发布

总结

goal-workflow 的核心理念是：让 AI 做它最擅长的事情，人专注于创造性工作。

它不是要取代开发者，而是成为你的研发助理，处理那些重复、规则、耗时的工作，让你可以专注于真正有价值的事情。

如果你是个人开发者，可以用它加速 MVP 的开发；如果你是团队成员，可以用它标准化工作流程；如果你是开源项目维护者，可以用它自动化 Issue 处理。

项目地址：GitHub - smallnest/goal-workflow

安装：npx skills add smallnest/goal-workflow

欢迎尝试，如果觉得有用，请给个 Star 支持一下。