本文永久链接 – https://tonybai.com/2025/08/01/proposal-purego

大家好，我是Tony Bai。

对于许多 Go 开发者来说，purego 构建标签一直是一个模糊的存在。它到底意味着“没有 Cgo”、“没有 unsafe”，还是“没有汇编”？这个问题的答案在社区中众说纷纭，甚至连标准库中的使用也不尽统一。最近，一项历时六年、编号为#23172 的提案终于尘埃落定，Go 团队正式接受 (accepted) 了关于 purego 含义的共识。本文将带大家一起回顾这场漫长而精彩的社区辩论，深入探讨其背后的技术权衡，并阐明这个小小的标签对于 Go 的跨实现（如 TinyGo）和可移植性生态的深远意义。

背景：一个模糊的约定

purego 标签的诞生，源于 Go 生态系统日益增长的多样性。除了官方的 gc 编译器，还涌现出了 GopherJS、TinyGo、gccgo 等多种 Go 实现。在这些非标准环境中，对 unsafe 包的指针操作、Cgo 的支持以及 Go 汇编的兼容性各不相同。

最初，protobuf 等库为了兼容Google App Engine 等不允许 unsafe 的环境，开始使用 safe 标签。这个概念逐渐演变为 purego，但其确切含义从未被正式定义。这导致了混乱：

• 有人认为 purego 意味着完全的内存安全，即禁止 unsafe 包。
• 有人认为它意味着纯粹的 Go 代码，即禁止 cgo 和汇编。
• 还有人认为它应该是一个包罗万象的标签，同时禁止 unsafe、cgo 和汇编。

这种模糊性给库作者和不同 Go 实现的维护者带来了困扰。

辩论的焦点：一个标签，多重含义的冲突

提案的讨论过程充满了精彩的技术思辨，核心矛盾在于试图用一个标签来承载多个正交（orthogonal）的概念：

1. noasm vs. nounsafe vs. nocgo：来自 TinyGo 团队的开发者明确指出，TinyGo 支持 unsafe 和 cgo，但不支持 Go 汇编。如果 purego 同时禁止这三者，那么 TinyGo 将被迫禁用它本可以支持的功能。!cgo 标签已经很好地解决了 Cgo 的问题，因此将 cgo 捆绑进来显得多余。

2. unsafe 的多重“不安全”：Go 安全负责人 Filippo Valsorda (@FiloSottile) 进一步指出，unsafe 包本身也包含了不同层次的“不安全”：

   • 类型转换（如 unsafe.String）：通常是可移植的。
   • linkname：与运行时实现紧密耦合。
   • 指针运算：依赖内存布局，是真正的不可移植性的主要来源。

   用一个 nounsafe 标签一概而论，过于粗暴，可能会“误伤”许多可移植的 unsafe 用法。

3. 生态现状：seankhliao 通过 GitHub 搜索发现，社区中 //go:build !purego 与 import “unsafe” 的组合（表示非 purego 版本才使用 unsafe）远多于 //go:build purego 与 import “unsafe” 的组合。这表明，社区的主流用法倾向于将 purego 视为不使用 unsafe 和汇编的版本。

达成共识：“完美是优秀的敌人”

在长达数年的讨论后，Filippo Valsorda 的一段评论为这场辩论指明了方向，他主张“不要让完美成为优秀的敌人”：

• 核心用例：当前最主要的需求来自 TinyGo 和标准库加密包的通用后备代码测试，这两者本质上都需要一个“禁用汇编”的开关。
• 现有约定：purego 已经是社区和标准库中广泛用于禁用汇编的事实标准。虽然名字不够理想（noasm 会更清晰），但改变一个已广泛使用的约定的成本太高。
• 重新界定：我们应该停止扩大 purego 的定义，回归其最核心、最被需要的用途。

最终，在 aclements 等核心成员的推动下，社区达成了清晰的共识。

最终决议：purego 意为“无汇编”

Go 团队最终接受 (accepted) 了该提案，并明确了其最终方向：将在 go help buildconstraint 中正式文档化 purego 构建标签的约定：

• purego 主要用于禁用汇编代码，从而启用纯 Go 的实现作为后备。
• purego 与 cgo 是正交的。是否使用 Cgo 应由 cgo 标签控制。
• purego 不常规地影响 unsafe 包的使用。可移植的 unsafe 用法是被允许的。

对 Go 开发者的影响

这个决议对于 Go 生态系统意义重大：

1. 为库作者提供了清晰的指导：当你的库同时包含汇编优化版本和纯 Go 实现版本时，purego 是官方推荐的、用于在两者之间切换的标签。
2. 为 Go 的替代实现铺平了道路：像 TinyGo 这样的编译器现在可以自信地默认设置 purego 标签，从而无缝地使用标准库和第三方库中提供的纯 Go 后备代码，而不用担心会意外地禁用它们所支持的 unsafe 或 cgo 功能。
3. 提升了测试的便利性：开发者可以在拥有汇编优化的平台（如 amd64）上，通过 -tags purego 来方便地测试和调试纯 Go 的实现版本。

结论

purego 标签的标准化之路，是 Go 社区在实践中不断探索、辩论并最终达成务实共识的又一个经典案例。它表明，一个健康的语言生态不仅需要顶层设计，更需要在真实世界的需求碰撞中，不断澄清和完善其约定。通过为 purego 赋予一个清晰、专注的定义，Go 语言再次为其跨平台、跨实现的承诺，奠定了一块坚实的基石。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

本文永久链接 – https://tonybai.com/2025/07/30/six-principles-production-ai-agents

大家好，我是Tony Bai。

随着 AI Agent 技术的兴起，许多开发者都投入到构建智能体的浪潮中，但很快就会发现，让 Agent 稳定、可靠地工作远非想象中容易。它们时而产生幻觉，时而偏离轨道，时而做出一些令人费解的“愚蠢”行为。最近，来自 app.build 的 Arseni Kravchenko 分享了他们在构建生产级 AI Agent 过程中总结出的六大核心工程原则。这些原则摒弃了虚无缥缈的“提示词黑魔法”，回归到坚实的软件工程基础。对于正在或计划使用 Go 构建 AI Agent 的开发者来说，这是一份宝贵的实践指南。

原则一：投资你的系统提示 (System Prompt)

许多人对“提示词工程”持怀疑态度，认为它充满了“我奶奶快不行了，请帮帮我”之类的奇技淫巧。然而，作者指出，现代 LLM 真正需要的是直接、详细、清晰且无矛盾的上下文，而非情感操控。

对于开发者而言，你要做的就是不要耍小聪明，要把系统提示当作给 Agent 的API 文档来写。

当你为 Agent 提供一个通过 os/exec 调用的工具时，不要只告诉它工具的名字。在系统提示中清晰地说明：

• 工具的完整命令是什么。
• 每个参数的含义、类型和格式。
• 预期的输出格式以及如何解析它。
• 前置条件和错误情况。

一个详尽的系统提示是 Agent 可靠行为的基石。

原则二：拆分上下文 (Split the Context)

“上下文工程”是比“提示词工程”更重要的概念。巨大的、单一的上下文不仅成本高、延迟大，还会导致模型出现“注意力衰减”，忽略掉关键信息。

作者建议大家：默认只提供最少必要知识，并通过工具让 Agent 在需要时主动获取更多上下文。

与其在初始提示中塞入整个项目的源代码，不如：

• 提供文件列表：在提示中只给出项目的文件树结构。
• 提供 read_file 工具：让 Agent 在需要时，通过调用这个工具来读取特定文件的内容。
• 上下文压缩：在 Agent 的反馈循环中，主动使用工具（甚至另一个 LLM）来压缩和总结日志、工具输出等动态信息，避免上下文无限膨胀。

如上图所示，将一个庞大的任务分解为多个具有专注上下文的、可编排的子任务，是构建高效 Agent 的关键。

原则三：精心设计你的工具 (Design Tools Carefully)

工具是 AI Agent 的核心。设计给 Agent 用的工具，比设计给人用的 API 更具挑战性，因为 LLM 不会“读心术”，它们会毫不留情地滥用你留下的任何漏洞。

作者建议：把你的 Agent 当成一个聪明但容易分心的初级开发者，为它设计 API：

• 保持粒度一致：工具（函数）应该有相似的抽象层次。不要混用一个 read_byte 和一个 deploy_to_kubernetes。
• 限制数量和参数：一个典型的工程 Agent 通常只有不到 10 个核心工具，每个工具只有 1-3 个严格类型的参数。
• 追求幂等性：尽可能让工具是幂等的，这可以极大地简化 Agent 的状态管理和错误恢复逻辑。
• 清晰、无歧义、无冗余：确保没有两个工具的功能是重叠的，这会让 LLM 感到困惑。

原则四：设计一个反馈循环 (Design a Feedback Loop)

一个没有验证和反馈的 Agent 是不可靠的。优秀的 Agent 系统总是将 LLM 的创造力与传统软件的严格性结合起来，形成一个“演员-评论家”（Actor-Critic）模型：让 LLM Actor 自由创造，让严格的 Critic 程序来验证。

对于开发者来说，这是一个天然的优势领域！

• Actor (LLM)：负责生成代码、配置文件或执行计划。
• Critic：负责执行一系列自动化验证：
  • 代码能否编译通过？
  • 代码能否通过测试？
  • 代码是否符合静态检查规范？
  • 领域特定不变量：例如，如果 Agent 修改了订单系统，是否依然满足“订单总价等于所有商品价格之和”这个业务规则？

这个反馈循环不仅能过滤掉错误的输出，更是 Agent 学习和改进的基础。

原则五：用 LLM 驱动错误分析

当 Agent 失败时，手动排查海量的日志是不现实的。我们可以构建一个“meta Agent”来解决这个问题，即让另一个 LLM 来分析失败 Agent 的日志，找出问题的根源。

流程：

1. 建立一个基线版本的 Agent。
2. 部署多个实例并收集它们的执行轨迹和日志。
3. 将失败的日志喂给一个具有更大上下文窗口（如 Gemini 1.5 Pro）的 LLM进行分析。
4. 根据 LLM 的分析洞察，改进基线 Agent 的系统提示、工具或上下文管理。

这个元循环能高效地发现我们自己可能忽略的系统性问题。

原则六：令人沮丧的行为是系统问题的信号

当 Agent 做出一些“愚蠢”的行为，比如忽略你的明确指令，或者用一种奇怪的方式绕过问题时，我们的第一反应通常是“这个模型真笨”。

但作者建议：先调试你自己的系统，再怪罪模型。

作者分享了一个亲身经历：他明确要求 Agent 使用一个集成工具来获取数据，但 Agent 却固执地使用模拟的随机数据。在愤怒地检查日志后，他发现自己忘了给 Agent 配置正确的 API 密钥。Agent 尝试调用工具，连续失败，最后只能选择一个它能走的通的、但却是错误的路径。

因此，当你的 Agent 行为异常时，请检查一下：

• 工具是否缺失？ 它是否需要一个 write_file 的能力而你没有提供？
• 提示是否模糊？ 你是否清晰地解释了工具的用法和边界？
• 上下文是否充分？ 它是否因为缺少必要信息（比如一个 API 密钥或文件权限）而无法执行任务？

小结

构建有效的 AI Agent，关键不在于寻找一个能解决所有问题的“银弹”提示或高级框架。它回归到了系统设计和严谨的软件工程。

作为开发者，我们应该聚焦于：

• 清晰的指令（通过系统提示）
• 精简的上下文管理（通过工具和压缩）
• 健壮的工具接口（简单、幂等、无歧义）
• 自动化的验证循环（编译、测试、静态检查）

当你被 Agent 的行为所困扰时，记住，问题很可能出在缺失的工具、模糊的提示或不足的上下文，而不是模型本身的局限性。将错误分析视为开发过程中的一等公民，我们的目标不是构建一个从不犯错的完美 Agent，而是构建一个可靠的、可恢复的、能够优雅地失败并被我们迭代改进的Agent。

资料链接：https://www.app.build/blog/six-principles-production-ai-agents

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。