xhj的博客

最近，小J在尝试用 AI Agent 为一个中等规模的代码库完整添加国际化（i18n）支持。 理论上，这是一类非常适合 AI 处理的任务：规则明确，需要识别所有硬编码字符串并替换为t(‘KEY’)的形式，同时在语言文件中补充对应键值；任务重复性高，几乎不需要创造性。 一开始进展顺利。Agent 像一台推土机一样，一个文件接一个文件地处理代码。但几个小时后，情况开始失控。对话历史、数百行代码搜索结果、工具调用日志、Linter 报错、人工补充指令……所有信息都被不断塞进同一个上下文窗口。Agent 的响应速度从秒级下降到分钟级，随后开始“胡言乱语”。它会突然忘记之前已经处理过的文件，在一个无关的函数里问我“这个变量是什么意思”，甚至开始修改一些完全不相关的业务逻辑。 最终，当一个简单的 JSON 配置文件也被改得面目全非时，小宁只能选择终止任务。原本寄予厚望的 AI 助手，变成了一个堆满草稿、废弃代码和错误日志的“垃圾场”。 单一 Agent 模式中，上下文不断堆积，噪声与历史信息会持续侵蚀主流程 这次失败揭示了一个关键问题：当任务复杂度超过一定阈值时，单一 Agent 模式极易...

一、最新研究进展Google DeepMind 联合 MIT，做了一件业界期待已久的事：用 180 组控制实验，定量回答”多 Agent 到底比单 Agent 强多少”。 论文叫《Towards a Science of Scaling Agent Systems》（arXiv: 2512.08296），跨 3 个模型家族（OpenAI、Google、Anthropic）、5 种架构、4 个基准任务。不是理论推导，不是案例论证，这是真金白银烧 token 跑出来的实验数据。 结论一句话： “More Agents Is NOT All You Need.” 更多的 Agent 不等于更好的结果。在大多数场景下，多 Agent 系统的表现不仅没有显著优于单 Agent，反而因为协调开销而更差。 二、论文里的六个关键数字这篇论文最大的价值不是观点，是数据。以下是六个关键定量发现，每一个都直接对应我们日常使用中的某种”体感”： 1：工具协调惩罚系数 = -0.330在论文的 20 参数回归模型中，工具 - 协调交互项是最大的负因子。 翻译成人话：你给多 Agent 系统...

今年以来这个Harness Engineering这个词的热度很高，最近公司一直在推AI辅助编程，所以就花了几天时间学习了下这个东西。harness这个词不是一个软件框架（比如orm的mybatis），它是一种开发的新范式，可以理解是一种指导思想、一种开发规范，本质是用来提升大模型的使用效果。 https://openai.com/index/harness-engineering/ 这篇文章提出了Humans steer. Agents execute的观点。 开发人员主要关注以下： systems（通过prompt进行系统功能、任务描述） scaffolding（脚手架设计，像架构分层及层级单向调度） leverage（好多地方翻译为杠杆，我认为的是影响力，对agent自动执行流程施加影响，按prompt交互运行）。 Harness Engineering这种工程范式体现在以下几个方面： 1、提高程序的可读性(Increasing application legibility)：采取了各种辅助手段（application UI, logs, and app met...

第 25 篇：架构模式总结 — 可迁移到你自己项目的设计模式在过去 24 篇文章中，我们逐一拆解了 Claude Code 的每个子系统——从启动链路到对话循环，从工具系统到权限防线，从 Prompt Cache 到 MCP 协议。每篇都聚焦于”这个模块是怎么设计的“。 但工程师阅读源码的终极目的不是理解别人的代码，而是把好的设计用到自己的项目里。 本篇将切换视角：不再关注 Claude Code 特有的业务逻辑，而是提取那些跨项目可复用的架构模式。这 7 个模式覆盖了从编译期优化到运行时状态管理、从工具注册到安全防线的全栈设计决策。 模式 1：编译期 DCE — 同一份代码构建多版本问题你的产品需要从同一份代码库构建出多个版本——内部版/外部版、免费版/付费版、或者面向不同客户的定制版。传统做法是维护多个分支或在运行时用 if/else 判断，前者导致合并噩梦，后者让所有版本都包含所有代码。 Claude Code 的解法利用 Bun bundler 的 feature() 函数实现编译期 Dead Code Elimination（DCE）。关键技巧是将...

第 24 篇：Skill/Plugin 开发实战 — 基于源码理解扩展点为什么需要理解扩展点？Claude Code 的核心是一个 AI Agent 运行时。但不同团队、不同项目的需求千差万别 —— 有人需要自动化代码审查流程，有人需要集成内部工具链，有人需要约束 Agent 只做特定任务。 Claude Code 提供了四个层级的扩展机制，从轻量到重量依次为： 1Hook 脚本 → Skill 文件 → Agent 定义 → Plugin 包 Hook：在特定事件（工具调用前后、会话开始结束）触发 Shell 命令 Skill：一个 Markdown 文件，定义一段 prompt + 行为约束，模型可以自主调用 Agent：一个 Markdown 文件，定义一个独立的 AI 角色（有自己的 prompt、工具集、模型） Plugin：一个完整的目录包，可以同时提供 Skill、Agent、Hook、MCP 服务器 本篇将逐一解析这四个扩展点的编写方式，并指出它们在源码中是如何被发现、解析和执行的。 一、自定义 Skill 编写1.1 目录结构与发现机制Skil...

第 23 篇：Memory 系统 — AI 记忆的多层架构为什么 AI Agent 需要记忆？LLM 天生是”金鱼记忆” —— 每次对话都是从零开始。用户上次告诉 Claude “我喜欢用 bun 而不是 npm”，下次对话它就忘了。用户在项目里纠正了 Claude 三次”不要 mock 数据库”，第四次它可能又 mock 了。 这不仅仅是用户体验问题 —— 它直接影响 AI Agent 的工作效率。没有记忆的 Agent 永远是新手：每次都要重新了解用户偏好、重新踩同样的坑、重新探索同样的代码库。 Claude Code 的解决方案是一个五层记忆架构： 层级 名称 生命周期 存储位置 核心职责 1 CLAUDE.md 指令文件 永久 项目目录 / 用户目录 静态指令与规则 2 Auto Memory（memdir） 跨会话 ~/.claude/projects/<slug>/memory/ 自动提取的持久化知识 3 Session Memory 单次会话 ~/.claude/projects/<slug>/<sessi...

第 22 篇：设计系统 — 终端 UI 的组件化实践为什么终端应用需要设计系统？当你用 console.log 输出几行文字时，不需要设计系统。但当你的终端应用有流式输出、多工具并行进度条、权限确认对话框、Tab 切换面板、模糊搜索选择器、dark/light 主题切换时，情况就完全不同了。 Claude Code 面对的正是这样的复杂度。它的 UI 不是静态的信息打印，而是一个高度动态的交互界面。在第 21 篇中我们看到了 forked Ink 框架如何在终端中运行 React；本篇则关注在这个框架之上，团队如何构建了一套可复用的组件化设计系统。 这套设计系统回答三个核心问题： 颜色从哪来？ — 6 套主题 × 80+ 语义化颜色 token 的主题系统 组件怎么组合？ — 15 个设计系统组件 + 1 个颜色工具函数的职责划分 工具 UI 怎么统一？ — Tool 接口中 10 个 render/查询方法构成的 UI 协议 一、主题系统：80+ 语义化颜色 token1.1 Theme 类型：颜色的语义化契约终端应用的颜色管理比 Web 更复杂。We...

第 21 篇：Ink 框架深度定制 — 在终端中运行 React 本篇深入 Claude Code 的 forked Ink 框架（ink/ 目录，约 90 个文件），揭示如何在终端中构建一个完整的 React 渲染引擎：从自定义 Reconciler、Yoga 布局、双缓冲渲染管线，到虚拟滚动、鼠标事件、文本选择等深度定制。 为什么要 Fork Ink？Ink 是一个开源框架，让你在终端中使用 React 组件编写 UI。官方 Ink 适合简单的 CLI 工具 —— 但 Claude Code 不是简单的 CLI。它需要： 全屏模式：Alt Screen 下的完整 UI，不是”追加式”输出 虚拟滚动：对话历史可能有上千行，不能全部渲染 鼠标交互：点击、拖拽选择文本、滚轮滚动 60fps 渲染：流式输出时每 16ms 刷新一帧，不能闪烁 IME 支持：CJK 输入法需要物理光标精确定位 官方 Ink 不支持这些。Claude Code 团队 fork 了 Ink 并进行了大量深度定制，最终形成了一个功能完备的终端 React 渲染引擎。 一、架构全景：从 React 到终...

第 20 篇：API 调用与错误恢复 — 面向不可靠网络的鲁棒设计 本篇是《深入 Claude Code 源码》系列第 20 篇。我们将深入 API 调用层的错误恢复机制，看看一个生产级 AI CLI 如何在不可靠的网络环境下保持稳定运行。 为什么需要如此复杂的错误恢复？当你在本地调用一个 REST API 时，最简单的做法是失败就报错。但 Claude Code 面对的是一个远比这复杂的现实： 网络不可靠 — 用户可能在咖啡馆 WiFi、企业代理、VPN 隧道后面使用 API 容量波动 — 529 过载和 429 限流是 LLM API 的常态，不是异常 认证令牌过期 — OAuth token、AWS credential、GCP credential 都有 TTL 流式连接脆弱 — SSE 流可能在中途断开、超时、或被代理截断 多 Provider 差异 — 同一份代码要兼容 Anthropic 直连、AWS Bedrock、GCP Vertex、Azure Foundry 四种后端 如果每种错误都让用户手动重试，用户体验将是灾难性的 —— 想象你在一个需要 10 分...

第 19 篇：Feature Flag 与编译期优化 — 同一份代码构建两个产品 本篇揭示 Claude Code 如何用一套代码库同时维护内部版和外部版两个产品。你将看到 Bun 的 feature() 编译期常量折叠、process.env.USER_TYPE 构建时 --define 常量、MACRO.* 构建时值注入、以及 GrowthBook A/B 测试平台如何在不同的时间维度上协同工作。 为什么需要多层 Feature Flag？假设你是一家 AI 公司的工程师，你的产品既有面向公众的开源版本，也有内部员工使用的增强版本。内部版有更多实验性功能（语音模式、多 Agent 协调器、后台任务引擎），但你不想维护两个独立的代码仓库。 Claude Code 面临的正是这个问题。它的解决方案是三层 Feature Flag 体系，每层解决不同的问题： 层级 机制 决策时机 目的 编译期 feature() from bun:bundle 构建时 从产物中物理删除内部代码分支 编译期 process.env.USER_TYPE (--define)...