AI开发与编程

Claude Code 的「Claude usage limit reached」不是错误，而是 Pro/Max 订阅使用量限制的设计方式。限制分为「滚动的5小时窗口」与「每周窗口」两层，Max 还另有仅针对 Opus 的每周额度。本文梳理什么在吃掉额度（模型选择影响最大）、撞到上限那一刻的5种对策、如何用 /usage 查看剩余量，以及订阅限制与 API 限制的根本区别。

Claude Code / API 的「Prompt is too long」不是 bug，而是你的输入（会话历史＋文件＋工具定义等）超出了模型的上下文窗口。它既不是 usage limit 额度，也不是 max_tokens 输出截断。本文梳理什么在填满窗口、最快的5步对策（/compact、/clear、subagent、削减固定负载、1M 模型）、200K 与 1M 窗口的区别，以及如何与容易混淆的错误区分开。

Claude Code 的 MCP 服务器连接错误可分为三大类：本地子进程启动失败、远程认证、配置文件错误，而 /mcp 的状态会告诉你属于哪一类。本文梳理状态读法、按原因分类的对策、Windows 上的 npx 陷阱（用 cmd /c 包裹），以及从状态到 stderr 再到独立启动的排查工作流。

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

把庞大的 AI 从头重新训练太贵，但你又想为自己稍作调整；LoRA（Low-Rank Adaptation）通过冻结原始模型、只训练一个极小的附加部件（适配器），把可训练参数削减约 90%，实现了这个愿望。LoRA 让微调大幅更便宜、更快，并在 Stable Diffusion 等图像生成中作为添加角色或画风的小文件极受欢迎。本文用补丁的比喻来讲解。LoRA 是参数高效微调（PEFT）的代表：把庞大的原始权重冻结，在每一层插入一个小的附加矩阵，只训练它（W = W0 + BA，其中 W0 被冻结，BA 是新增的那一小部分）。它建立在这样一个发现之上：调整 AI 并不需要大的改动，低秩就足够。优势：可训练参数减少约 90%（在 GPT-3 规模下据报道少 10,000x）、更省 GPU 内存（约少 3x）、训练更快更便宜、合并适配器后不增加推理延迟、更不易过拟合。它最大的优势是适配器可更换：保留一个通用底座，按用途即时更换小巧的（几 MB）LoRA 文件（客户支持、公司语气、某个特定角色）。很多人第一次接触 LoRA 是在图像生成中，Stable Diffusion 上学会了角色、画风或主体的 LoRA 被广泛共享（添加画风、学会角色、轻巧易分享）。QLoRA 结合量化，在 4-bit 底座之上训练 LoRA，比标准 LoRA 省约 4x 内存，能在消费级 GPU（有时是 CPU）上微调庞大模型，且精度损失极小。相比全量微调（训练所有权重），LoRA 在训练的权重、成本、产出和适用场景上都不同；对大多数工作，LoRA 就足够。底座保持原样，风味小幅调出。文中数值引自公开资料，仅供参考。

一个庞大的 70B 模型不再需要数据中心的 GPU 机架，而能在家里一台游戏 PC 上运行，这要归功于量化——它降低模型权重的数值精度，从而大幅缩小体积和内存。模型蒸馏是把知识转移到另一个更小的模型，而量化则是让同一个模型变轻。本文用照片压缩的比喻来讲解。量化把以 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% 权重，往往精度高 1-2% 且更快）、GGUF（llama.cpp/Ollama 格式，Q2_K-Q8_0，CPU+GPU 混合，用于本地）和 QLoRA（4-bit 基础加 LoRA，在消费级 GPU 上微调）。它与蒸馏（转移到另一个小模型）和微调（增添任务知识）不同，三者通常组合使用（量化蒸馏后的模型；在量化基础上微调）。开始时，用 Ollama 一条命令跑一个 GGUF 模型，按 VRAM 选 Q4/Q8，代码或精确计算避开 INT4。多数主流模型已以量化形式发布，下载即用。保留聪明，只去掉重量。文中数字引用自公开资料，仅供方向参考。

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

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

在掌握"什么是多智能体系统？"的概念之后，这是动手实践的续篇。以 2026 年事实上的标准——主管模式为题材，带初学者走完 5 步构建流程。核心原则：先用单一智能体构建，撞到瓶颈后再以最小配置增加（约 80% 的用途用一个就够；对简单的直线式流程使用多智能体会让成本膨胀 3-10x，据 Google 研究在顺序型任务上精度还会下降 -39-70%）。应转向多智能体的 3 个信号：专业性分离、并行性、判断分离。主管接收整体任务、分解、委派给专业工作者并汇总结果——Claude Code 子智能体、LangGraph Supervisor 与 OpenAI Agents SDK 的交接都收敛到了这一形态，因为它框架支持最广、失败模式已知、易于审计。5 步：①事先清晰分解；②定义工作者，一个角色＋工具＋输出格式（最多 3-5 个）；③设计主管，明确列出可调用名称（硬上限）并在此花最多时间；④确定交接与上下文共享，只传必要信息（标准是 A2A）；⑤增加前测量每次交接，给迭代/token/成本设上限，准备好 evals 与护栏。伪代码展示工作者定义、硬上限主管与带迭代上限的运行循环。共通教训：比起框架，提示词、工具设计与评估框架更能决定成败。小步构建、测量、只在划算时增加。图表引用自公开资料与研究，视条件而定。

「把一个 AI 智能体无法独自完成的复杂任务拆分给多个智能体来分担」，正是多智能体系统的核心思路。本文面向初学者梳理其运作机制、主要模式与主流框架，更重要的是不带夸张地给出真正的决策准则：什么时候该用多个智能体、什么时候一个就够。多智能体系统让多个角色各异的 AI 协同解决一个大型任务；相对于独自包揽全部的单智能体（约 80% 的场景已够用，且便宜、易调试），它按专长分工以实现并行处理与交叉校验，代价是更高的协调成本与 token 消耗。四种主流编排模式为：orchestrator-worker（总指挥拆解、并行分派 worker 再整合，最普及且有审计轨迹）、顺序交接（连同上下文交给下一个）、群组对话（在同一线程辩论、由选择器决定谁发言，擅长交叉验证）、图状态机（智能体为节点、转移为边、显式管理状态，擅长分支与检查点）。框架在 2026 年收敛为 LangGraph（生产采用规模最大）、CrewAI（学习曲线最低、原型开发）、AutoGen/AG2（辩论与验证、研究）与 OpenAI Swarm（轻量交接）。但它并非万能：复杂跨领域任务在推理基准上最高 +23%，而单线顺序任务上 Google 研究发现相比单智能体 −39-70%，把同样算力给单智能体往往打平甚至胜出，且据报告每 10 个部署有 7 个只增成本无回报、token 消耗约 15 倍（瞄准得当时平均 ROI 2.5-3.5 倍、头部四分位 4-6 倍）。推荐路径：先构建单智能体，找出具体瓶颈（角色混淆、可并行化），再以 2-3 个智能体的总指挥型最小团队起步并设好成本上限与日志，然后度量准确率提升是否值得这笔增量。A2A（通信协议）与 MCP（工具连接）是支撑多智能体的底层技术。80% 用单智能体，只有难啃的部分才上多智能体。文中数值引自调查与研究，依赖具体条件，仅作方向性参考。

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。

你搭好了 RAG，但检索质量却平平——这正是重排序能派上用场的时候。重排序把嵌入（向量）检索粗略收集到的候选，按它们与查询的相关度重新打分并重新排序，只保留最前面的那些；仅这一步就能大幅改变 RAG 系统的回答质量。本初学者指南讲解重排序是什么（以"初筛加终面"作比），为什么需要它（嵌入检索把查询和文档分开向量化，因此只能粗略判断相关度，而糟糕的排序会直接拉低回答质量——研究报告称加入重排序约带来 40% 的 RAG 准确率提升，把它叠加到混合检索上已是 2026 年的标准做法），两阶段检索如何运作（先用快速嵌入检索"广撒网"求召回，再用重排序器"智能筛"求精度，然后把最前面的交给 LLM），为什么重排序器更准确（bi-encoder 把查询和文档各自向量化，快但近似；cross-encoder 把两者一起喂入并输出 0–1 的相关度分数，准确但开销大——所以用快速的 bi-encoder 收集，用准确的 cross-encoder 筛选），以及模型与实现（API 型如 Cohere Rerank、Voyage、Jina；开源型如 BGE reranker、mixedbread、FlashRank；以及基于 LLM 的打分如 RankLLM——只需检索 50–100 个再筛到前 5 个）。原则就是：广撒网、智能筛，并用 AI 评测来调整数量。