如果你想自己做一个 Claude Code，需要哪些模块

2026/7/19 12:50:17 · 来源

#claude-code#agent-architecture#ai-agent#knowledge#cli-tool

本文深入解析了类似 Claude Code 的终端 AI 智能体架构，指出其并非简单的模型加工具调用，而是由交互、主循环、工具协议、上下文装配、权限审批等八大运行时模块构成的完备系统。

想要自研一个类似 [[Claude Code]] 的终端 AI 编码助手，不能仅停留在“模型 + Function Calling + TUI”的简易设定。一个生产级别的 AI 终端工具必须构建起一套完整的运行时（Runtime）架构，包含从状态管理、上下文装配到权限审批的 8 大核心模块。

核心架构：跳出“Chat + Tool”的误区

很多开发者在研究 [[Claude Code]] 源码后，第一反应是自己也做一个。但这其中存在一个认知误区：

不要把它理解成简单的“模型 + function calling + terminal UI”。

从源码来看，一个实用的 Claude Code 至少需要一整套完整的运行时模块。以下是系统的最小完整架构图：

Rendering diagram…

Claude Code 文档截图

核心系统八大模块解析

1. 入口与交互层

你至少需要一个明确的运行宿主：

命令行 (CLI)
终端 UI (TUI)
IDE 插件
Web UI

Claude Code 选择了终端 + React Ink的方案。这虽然不是唯一选择，但你必须先构建起一个稳定的交互外壳。

2. 会话主循环

这一层对应 Claude Code 源码中的 QueryEngine.ts。没有它，系统就只有零散的 API 调用，无法形成真正的任务闭环。

主循环至少要负责：

消息历史管理：维护上下文链。
模型调用与工具调用：解析并分发模型指令。
结果回流：确保工具执行结果能反馈给模型。
中断与预算控制：防止无限循环和 Token 超支。
会话状态延续：保持多轮对话的连贯性。

3. 统一工具协议

这一层对应 Tool.ts。如果没有统一的工具协议，系统很快会出现：

每个工具的输入输出格式不一致，难以维护。
权限管理难以统一。
UI 渲染和交互逻辑难以标准化。
外部扩展（如接入自定义工具）难以对接。

因此，统一的工具协议几乎是整个系统的底层地基。

4. 上下文装配系统

这是最容易被忽略，但决定了工具上限的关键部分。除了调用模型，你还必须决定模型在每轮对话开始前能“看见”什么：

Git 状态：当前的修改和分支信息。
项目规则：如特定的编码规范和约束文件。
记忆文件 (Memory)：项目的核心业务逻辑和长效背景。
当前日期与运行模式：提供必要的时间与场景感知。

Claude Code 之所以表现得非常“懂项目”，很大程度上就得益于这一层精准的上下文装配。

5. 权限与审批系统

一旦工具涉及修改本地文件、执行终端命令等真实动作，权限系统就必须上线。否则，它将因安全隐患而无法进入真实的工程环境。

Rendering diagram…

6. 文件与 Shell 基础设施

如果你想做的是一个“工程助手”，这两类工具是不可或缺的基石：

文件读写与精准编辑：支持对代码文件的精细化读写和修改。
Shell / 命令执行环境：能够安全、可靠地执行终端命令。

缺乏这两者，AI 将无法完成任何实质性的开发闭环。

7. 状态与任务系统

只要系统开始支持以下复杂场景，你就一定需要一个统一的状态中心：

多轮长对话
耗时较长的后台命令
异步后台任务
多 Agent 协同协作
远程会话连接

这也是许多玩具级 Demo 在往工业级真实产品过渡时最容易崩溃的地方。

8. 扩展系统

当基础能力稳定后，为了实现平台化演进，你需要引入扩展系统以支持：

插件机制
Model Context Protocol (MCP)
Language Server Protocol (LSP)
自定义 Skills / Agent

分阶段研发路线图

如果你计划亲自动手实现一个类似工具，不要试图一步复刻完整的 Claude Code。更现实的研发路线是：

第一阶段：先做单会话主循环（实现基础的 LLM-Tool 交互）。
第二阶段：补齐文件读写与 Shell 执行工具（具备基本的代码修改与运行能力）。
第三阶段：引入上下文装配与严格的权限审批机制（确保安全可控且懂项目）。
第四阶段：完善任务与状态系统（支持长任务、后台挂起及多轮复杂会话）。
第五阶段：考虑 MCP、LSP、远程部署和多 Agent 协同（走向平台化）。

Key takeaways

避免简易化误区：自研 AI 编码助手不能只靠简单的“模型 + Function Calling”，必须具备一套完整的运行时（Runtime）系统。
底层协议先行：统一的工具协议 (Tool.ts) 和会话主循环 (QueryEngine.ts) 是系统的骨架，需要优先完成设计。
上下文与安全是核心差异：工具之所以好用，在于其精妙的上下文装配（Git/Memory）与严密的权限审批设计。
循序渐进构建：从最基础的单会话和文件/Shell 工具开始，逐步补齐状态与权限，最后再向平台化（MCP/插件）演进。

学习地图

第一阶段：单机闭环（从零到一构建智能体底座）

命令行交互与宿主环境 (TUI)
- 学习如何使用 React Ink 或 Commander.js 编写 CLI 界面，让用户与 Agent 有一个稳定的交互外壳。
会话主循环 (QueryEngine)
- 实现核心调度逻辑，完成「接收输入 -> 调用模型 -> 解析工具 -> 回流结果」的闭环，这是智能体的大脑中枢。

第二阶段：生产力工具与情境感知

统一工具协议 (Tool Protocol)
- 设计标准化工具接口（如 Tool.ts），统一定义输入 Schema 和执行入口，方便未来扩展。
上下文动态装配系统
- 学习在每次向 LLM 发送请求前，动态注入当前 Git 状态、项目 Rule、系统日期等，让 Agent 具备“懂项目”的感知力。

第三阶段：安全与多任务工程化

权限控制与人工审批机制
- 实现敏感操作（如执行 Shell 命令、修改核心文件）拦截，加入用户确认交互，确保 Agent 在可控范围内运行。
状态中心与任务调度
- 引入多轮会话管理、后台任务及多 Agent 协同机制，提升系统应对复杂长流程任务的能力。

动手实践——分步指南

环境准备与初始化 初始化一个 Node.js 项目并安装必要的依赖：

mkdir my-cli-agent && cd my-cli-agent
npm init -y
npm install @anthropic-ai/sdk dotenv prompts

设计统一工具协议 创建一个 tools.js，定义一个简单的读文件工具：

const fs = require('fs');
const readFilesTool = {
  name: 'read_file',
  description: '读取指定路径的文件内容',
  input_schema: {
    type: 'object',
    properties: { path: { type: 'string' } },
    required: ['path']
  },
  execute: async ({ path }) => fs.readFileSync(path, 'utf-8')
};
module.exports = { readFilesTool };

编写会话主循环 (Query Engine) 在 index.js 中引入 Anthropic SDK，编写核心的 runAgent 循环，使其能够识别模型返回的 tool_use，执行 readFilesTool.execute，并将结果回传给模型再次生成回答。
引入用户审批环节 在执行工具前，增加一段阻断代码：如果是写文件或执行命令，使用 prompts 询问用户：是否允许执行该工具？(y/N)。只有用户确认后才调用 execute 函数，否则直接返回「用户拒绝执行」给模型。

三大推荐资源

1
Anthropic Claude Code Guide
Anthropic 官方关于 Claude Code 命令行工具的详细说明与架构指南。
https://docs.anthropic.com/en/docs/agents-and-tools/claude-code
2
React Ink GitHub Repository
Claude Code 用于构建其精美命令行交互界面的 React CLI 渲染框架。
https://github.com/vadimdemedes/ink
3
LangGraph Official Documentation
学习如何利用图结构管理复杂 Agent 状态、循环和多智能体协同的首选开源框架。
https://github.com/langchain-ai/langgraph

链接由 AI 推荐——使用前建议快速核实。