什么值得买App下载 App ›
连续签到专享现金活动

手撕Claude Code:Agent生产级架构的工程化解构

为了深入理解生产级 Agentic CLI 的运作机制,通过纯 TypeScript 从零复刻了一个功能等价的 Claude Code 引擎。该项目坚持零框架原则,仅引入了必要的 fast-glob 依赖,最终产出 46 个文件共一万行代码。通过对该系统的重构,揭示了 Claude Code 在架构设计、缓存策略、工具链风控及多 Agent 协作等方面的工程化实现细节。
01核心架构与依赖设计
  • 分层架构
    系统被严格划分为 core(引擎层)、tools(工具系统)、ui(终端渲染)、plugins(扩展系统)、skills(技能库)、commands(命令分发)六层,各层保持单向依赖,底层绝不向上越权。
  • 网络通信
    基于 Node.js 22 原生能力,使用纯原生的 fetch 和 ReadableStream 构建网络通信层,未引入额外的网络库。
  • 多模型兼容
    在 SSE 客户端初始化时注入 format: 'openai' 参数,在事件解析层将不同模型(如 GPT、Claude、Ollama 等)的异构事件流统一翻译为内部事件类型,实现 Agent Loop 引擎层与底层模型的解耦。
02Prompt 缓存与成本控制
针对生产环境中 API 调用的成本问题,采用了基于 Anthropic Prompt Caching 机制的深度优化策略。系统将 System Prompt 拆分为静态段和动态段,利用 cache_control 实现差异化的缓存命中。
分段类型包含内容缓存策略
静态段身份声明、工具使用规范、编码风格、安全执行规则进程启动时写入并打上缓存标记,后续请求低价命中
动态段当前工作目录、Git 状态、CLAUDE.md 内容、MCP 动态指令每轮重新计算,不带缓存标记

Prompt 分段缓存策略

03Agent Loop 与执行管线
Agent Loop 的本质是一个设定了上限的 while 循环,最大迭代次数被锁定在 25 次以防止死循环。系统包含严密的六阶段工具执行管线,并具备自动摘要机制以应对上下文窗口限制。
  1. 终端渲染展示(renderToolCall)
  2. 基于类型的权限拦截(permissionCheck)
  3. 插件系统前置拦截(preHook)
  4. 破坏性操作的文件快照(checkpoint)
  5. 实际执行(executeTool)
  6. 后置拦截(postHook)
当上下文逼近模型窗口限制的 85% 时,系统会触发自动 compact 机制,发起独立 API 调用生成摘要并替换臃肿的历史消息,确保长任务流的持续运行。
04工具系统与风控机制
系统内置了 21 个工具,并通过 Deferred Tools(延迟加载)和 MCP 协议扩展能力。同时,建立了严密的权限中枢以确保执行安全。

工具执行策略

性能优化

通过技术手段降低 Token 消耗与延迟

  • Bash 工具设置 120 秒超时限制,输出超 500 行则截断(保留头 200 行和尾 100 行)
  • Edit 工具强制要求提供唯一的 old_string,避免模糊匹配导致的误操作
  • Deferred Tools 机制:低频工具(如读取 Notebook)按需加载,减少约 40% 的固定 Token 开销
安全风控

多层级权限拦截与分类器机制

  • 三种权限模式:default、auto、plan
  • 工具分类:safe、dangerous、write、bypass
  • 两阶段分类器:第一阶段模式匹配拦截 90% 请求,第二阶段由 Haiku 模型作为“风控官”判断模糊操作,必要时优雅降级至 ask_user
05多 Agent 协作与记忆系统
为突破单 Agent 串行执行的瓶颈,系统实现了多 Agent 协作机制。主 Agent 通过 TeamCreate 招募子 Agent,利用 SendMessage 下发任务。子 Agent 在隔离的 Git worktree 分支上执行,最多迭代 15 轮。跨会话记忆(Auto Memory)则采用“土法炼钢”的方式,使用带 YAML 头信息的 Markdown 文件存储偏好,完全复用现有的 Read、Write、Edit 工具链,实现了零新增代码路径的持久化存储。
该复刻项目验证了 Claude Code 的工程质量远高于行业平均水平。其核心难点已不再是大模型 API 的调用,而是涵盖了错误恢复、工具反馈精度、用户交互穿插等深不可测的 Harness Engineering(驾驭工程)。这构成了工业级 AI 工具与玩具应用之间的核心护城河。

评论

评论区空态插画

当前文章无评论,是时候发表评论了