AI开发与编程：用AI构建应用的实战指南

在公司电脑上或通过 VPN 使用 Claude Code 时，出现 “Can't reach the API server”、“Connection refused”、“SSL certificate verification failed” 或 “fetch failed” 而连不上——这些都是网络错误，意味着请求根本没到达 Anthropic 服务器（api.anthropic.com），与认证（401/403）、服务器过载（529/500）和速率限制（429）不同。v2.1.227 之前，同样的错误显示为 “Unable to connect to API (ECONNREFUSED)”。本文说明现行每条消息的含义、首次设置时以 “Unable to connect to Anthropic services” 退出的情况、代理改动响应时出现的 “Streaming response ended before any complete data was received” 警告，以及代理设置（HTTPS_PROXY、NODE_EXTRA_CA_CERTS、绝不使用 NODE_TLS_REJECT_UNAUTHORIZED=0）、防火墙放行域名与排查工作流——全部基于官方的错误参考。

Claude Code 的“API Error: 529 Overloaded”和“500 Internal server error”都是服务器端事件，并非你的请求或设置有误，也不消耗配额。Claude Code 在显示提示前已以指数退避自动重试最多 10 次。本文说明等待重试、用 /model 切换、查看状态页、/feedback 反馈等应对，以及它们与 429、usage limit 的区别和面向开发者的设计要点。

Claude Code 的“You've hit your session limit · resets 3:45pm”不是错误，而是订阅使用量限制的设计方式。官方错误参考列出了4种：session（滚动的5小时窗口）、weekly（每周窗口），以及 Opus 和 Sonnet（只针对某一系列模型的额度）；由于会话额度和每周额度由全部模型共用，换模型也恢复不了。本文梳理每种提示的含义、从旧提示“Claude usage limit reached”以来的文字变化、什么在吃掉额度，以及撞到上限时该怎么办：Opus/Sonnet 额度用 /model 换到其他系列、等待重置（v2.1.234 起自动继续）、用 /usage-credits 开启使用量额度，或切换到按量付费的 API。还介绍了如何用 /usage 查看剩余额度，以及哪些相似提示并不是你的额度用完。

Claude Code 的 Prompt is too long 表示准备发送的完整输入无法装入上下文窗口。本文区分长对话历史、初始输入过大和压缩本身失败，介绍 /context、/compact、/clear、对话回退及子智能体的独立窗口。另说明 MCP 详细定义的按需加载、200K 与 1M 的模型和连接及计划条件、容量与计费的区别、相似错误，以及直接调用 API 时的 token 计数与请求缩减。

Claude Code 的 MCP 服务器连接失败时，应结合状态、连接方式和 Issue 详情判断。failed 可能表示 stdio 启动失败、HTTP 通信失败或固定认证请求头被拒绝。本文解释 Connection closed、环境变量与未定义引用、项目配置与批准、Windows 上的 npx 启动、调试日志，以及重新连接后的操作验证；同时说明为什么零工具不一定是错误，单独启动成功也不能保证 MCP 连接成功。

在 Claude Code 长时间作业时，屏幕上突然涌出“court”加上原始的 invoke / parameter 标签，工具调用却没有执行——这是 Claude（Opus 4.8/4.7 系列）在生成工具调用控制 token 时把它生成坏掉的模型侧缺陷，并非你的环境或命令的失误。harness 以 fail-closed 方式拒绝坏掉的调用，因此不会误执行命令；真正棘手的是坏块残留历史后模型会模仿它、产生“连锁”。本文基于官方文档与实际 Issue，梳理其机制、两大成因、三个常见误解，以及用户与开发者各自的对策（核心铁律：失误两次就撤到新会话 /clear）。

把庞大的 AI 从头重新训练太贵，但你又想为自己稍作调整；LoRA（Low-Rank Adaptation）通过冻结原始模型、只训练一个极小的附加部件（适配器），把可训练参数减少到原始模型的 1% 以下，实现了这个愿望。LoRA 让微调大幅更便宜、更快，并在 Stable Diffusion 等图像生成中作为添加角色或画风的小文件极受欢迎。本文用补丁的比喻来讲解。LoRA 是参数高效微调（PEFT）的代表：把庞大的原始权重冻结，在每一层插入一个小的附加矩阵，只训练它（W = W0 + BA，其中 W0 被冻结，BA 是新增的那一小部分）。它的基础是这样一个假设：调整 AI 并不需要大的改动，低秩就足够，原论文的实验证实了这一点（也有报告指出在数学和编程上不如全量训练）。优势：可训练参数不到原来的 1%（原论文的 GPT-3 175B 上约为万分之一）、更省 GPU 内存（同一实验中训练时 1.2TB → 350GB）、训练更快更便宜、合并适配器后不增加推理延迟、不易遗忘原有能力。它最大的优势是适配器可更换：保留一个通用底座，按用途即时更换小巧的 LoRA 文件（客户支持、公司语气、某个特定角色）。很多人第一次接触 LoRA 是在图像生成中，Stable Diffusion 上学会了角色、画风或主体的 LoRA 被广泛共享（添加画风、学会角色、轻巧易分享）。QLoRA 结合量化，在 4-bit 底座之上训练 LoRA：以 16 位训练全部参数需要超过 780GB 的 65B 模型，用一块 48GB 的 GPU 即可微调，33B 可在 24GB 的消费级 GPU 上微调；论文的对比中成绩与 16 位方式相当（33B、65B 能否与全量训练比肩，论文自己写明尚未验证）。相比全量微调（训练所有权重），LoRA 在训练的权重、成本、产出和适用场景上都不同；对大多数工作，LoRA 就足够。底座保持原样，风味小幅调出。文中数值来自原论文等的实验条件，仅供参考。

一个庞大的 70B 模型不再需要数据中心的 GPU 机架，而能在家里一台 PC 上运行（消费级 GPU 装不下的部分交给 CPU 和内存），这要归功于量化——它降低模型权重的数值精度，从而大幅缩小体积和内存。模型蒸馏是把知识转移到另一个更小的模型，而量化则是让同一个模型变轻。本文用照片压缩的比喻来讲解。量化把以 FP16/FP32 小数存储的权重替换成 INT8（8 位）或 INT4（4 位）整数，减少每个权重的字节数（FP32=4、INT8=1、INT4=0.5）；就像把 RAW 照片压成 JPEG，你牺牲一点点精度换来大幅减重，令人惊讶的是放弃的东西竟然这么少。在内存上，4-bit 约为 FP16 的四分之一：70B 模型从 ~140GB 降到 ~35GB，8B 模型在 4-bit 下约 ~4.5-5GB，能塞进中端 8GB VRAM 的 GPU 用于本地运行（LLM 的民主化）。在精度上，INT8 几乎无损，据报道 INT4 在一般问答/常识类任务上退化不到 4%，但在数学、代码生成和高难度推理上损失更明显（表现为困惑度小幅上升），所以要按任务选位宽。主要方法：GPTQ（精确 4-bit 的先驱）、AWQ（保护最重要的约 ~1% 权重，与 GPTQ 孰优孰劣因评估而异）、GGUF（llama.cpp/Ollama 格式，Q2_K-Q8_0，CPU+GPU 混合，用于本地）和 QLoRA（4-bit 基础加 LoRA，在消费级 GPU 上微调）。它与蒸馏（转移到另一个小模型）和微调（增添任务知识）不同，三者通常组合使用（量化蒸馏后的模型；在量化基础上微调）。开始时，用 Ollama 一条命令跑一个 GGUF 模型，按 VRAM 选 Q4/Q8，代码或精确计算避开 INT4。多数主流模型已以量化形式发布，下载即用。保留聪明，只去掉重量。文中数字引用自公开资料，仅供方向参考。

庞大而高性能的 AI 聪明但又重又贵；模型蒸馏（知识蒸馏）通过把大教师模型的知识转移到小学生模型来解决这一问题，以小得多的体积和更快的速度保留接近教师的性能。本文用教师与学生的比喻讲解。关键在于软标签：普通训练只教“答案是猫”（硬标签），蒸馏则传递教师“90% 猫、8% 狗、2% 狐狸”这样的整个概率分布，其“犹豫程度”蕴含丰富信息；温度参数会软化概率以显现微妙关系（真实例子：OpenAI 于 2024 年在 API 中加入用大模型输出训练小模型的功能）。好处：又快又便宜、大幅更紧凑且保留接近教师的性能（TinyBERT 约 1/7.5 体积、96.8% 以上）、可在边缘端运行、擅长用途专精。两种方式：白盒（完全访问权重和内部表示，转移更深，用于自家或 OSS 模型）与黑盒（只能看到输出/API 响应，把别家 API 当教师可能违反条款）。它与量化（压缩同一模型的权重精度）、微调（对现有模型针对任务追加训练）不同——蒸馏是把知识转移到另一个小模型，三者可组合。法律与 ToS 现实是 2026 年的重大议题：技术正当，但 OpenAI、Anthropic、xAI 等都设有反蒸馏条款，禁止用输出打造竞争模型，因此用受限 API 蒸馏竞品可能违反条款。OpenAI 诉 DeepSeek 的纠纷（OpenAI 主张疑似 DeepSeek 相关账号绕过限制获取输出用于蒸馏，而 DeepSeek 条款据称允许蒸馏其输出）表明评估取决于适用谁的 API 条款，且 Claude Fable 5/Mythos 5 会把被判定为蒸馏的请求转给能力较低的 Opus 模型。要诀：用自家或已授权 OSS 模型当教师、用商用 API 前确认反蒸馏条款，并判断用途是否属于“开发竞争模型”。聪明靠大模型、运营靠小模型——但选谁当教师会改变技术与法律结果。数据引用自公开资料，仅供参考。

在《如何搭建多智能体系统》中我们说过，增加智能体前先为每次交接装上度量；支撑这种度量的技术正是 AI 可观测性。它让你看清 LLM 与智能体在生产环境中究竟在做什么，从而能回溯到原因。与普通应用监控的决定性区别在于：AI 可以返回 200 OK、50ms 却仍自信地产生幻觉，所以多数 AI 故障是质量故障而非基础设施故障。可观测性基于三大支柱：trace、metrics 与 logs。可观测性展示“发生了什么”，评估（evals）则衡量答案好不好，两者需成套使用。本文梳理关键指标与 LangSmith、Langfuse、Arize Phoenix、MLflow、AgentOps、OpenTelemetry 等主要工具，并讲解如何起步以及为何对智能体至关重要。

继“什么是多智能体”之后的实践篇。核心原则是先用单一智能体构建，碰到瓶颈后再以最小规模增加（Google Research 的研究发现，在严格按顺序推理的任务上，多智能体配置全部比单一差 39%～70%；Anthropic 报告多智能体系统消耗的 token 约为聊天的 15 倍）。基本形态是主管模式：Claude Agent SDK 中是子智能体，OpenAI Agents SDK 中是 Agents as tools。除了分解、定义工作者、设计主管、交接、测量这 5 步，还按两个 SDK 的官方文档给出最小代码（主管 1 个+调研员、核查员），说明如何限定每个角色的工具、maxTurns、max_turns、费用三重上限、何时改用交接、好的拆分与坏的拆分，以及 Anthropic 实际遇到的失败（简单问题派出 50 个子智能体、重复调查）与对策。

AI 智能体已日益普及，下一个挑战是如何让智能体彼此协作。如果说 MCP 把智能体连接到工具，那么 A2A（Agent2Agent）就是把智能体连接到另一个智能体 —— 一套开放标准，让基于不同厂商和框架构建的 AI 通过共同约定相互发现、通信与协作。Google 于 2025 年 4 月发布，同年 6 月将其捐赠给 Linux Foundation，到 2026 年达到 v1.0。这篇初学者指南涵盖：A2A 是什么（用“企业间业务合作的礼仪”作比喻）、为什么需要它（各有专长的智能体接力工作 —— 规划智能体到酒店预订智能体再到支付智能体）、它与 MCP 有何不同（MCP 是纵向，智能体 ↔ 工具；A2A 是横向，智能体 ↔ 智能体；把两者叠加是标准的双层结构）、它如何运作（通过 Agent Card —— 位于 /.well-known/agent-card.json 的 JSON“名片”—— 来发现能力，然后用 Task 携带请求经过 working、input-required、completed 等状态，并以 Artifact 返回结果，全部基于 HTTP、Server-Sent Events 和 JSON-RPC 2.0，且智能体保持内部细节隐藏），以及现状与落地实现（截至 2026 年 4 月，150+ 家组织支持，22,000+ GitHub stars，提供五种语言的 SDK —— Python、JavaScript、Java、Go、.NET —— Microsoft、Salesforce、SAP、ServiceNow 均有参与）。口诀：连接工具 = MCP，连接同伴 = A2A。