从Claude Code到nanocode：轻量级AI编程助手核心架构与工程实践

1. 项目概述从Claude Code到nanocode的轻量化之路如果你是一名开发者尤其是对AI编程助手AI Agent的内部工作原理充满好奇那么你很可能听说过Anthropic的Claude Code。它是一个功能强大的命令行AI代理能够理解你的指令调用各种工具如读写文件、执行命令、搜索网络来帮你完成编程任务。然而它的官方实现是一个超过50万行代码、依赖近200个包的庞然大物对于想要学习其核心设计思想的人来说无异于面对一座难以翻阅的高山。这就是nanocode诞生的背景——一个仅用约9000行代码就复现了Claude Code约85%-90%核心能力的轻量级开源实现。我最初接触这个项目是出于对AI Agent架构的好奇。市面上的教程大多停留在API调用层面而像Claude Code这样能进行复杂多步推理和工具调用的系统其内部“思考循环”和“决策引擎”是如何工作的一直是个黑盒。nanocode的出现就像有人为这座高山绘制了一份精确的等高线图。它通过逆向工程Claude Code的npm包源码剥离了所有用于生产环境的“重型外壳”——比如React/Ink构建的复杂终端UI、遥测系统、云端桥接、插件市场等只保留了最直接影响Agent推理质量和执行效率的20个关键工程决策。简单来说nanocode是一个纯粹为教育、研究和深度定制而生的项目。它让你能在自己的机器上用一个干净、可读的TypeScript代码库运行一个功能完整的AI编程助手并清晰地看到消息是如何被压缩、工具是如何被并行调用、子任务是如何被规划和执行的。对于想构建自己AI Agent的开发者或是想深入理解现有Agent内部机制的研究者这无疑是一个绝佳的学习范本和起点。接下来我将带你深入拆解nanocode的设计精髓、实操部署的每一个细节并分享我在研究和测试过程中积累的一手经验与避坑指南。2. 核心架构与设计哲学解析2.1 逆向工程与“瘦身”逻辑nanocode的起点是对anthropic-ai/claude-codev2.1.88这个npm包进行反编译和源码提取。这个过程本身就是一个有趣的工程案例。原包虽然编译成了JavaScript但通过工具可以还原出大致的TypeScript结构和核心逻辑。nanocode的作者并非简单复制而是进行了一次彻底的“架构考古”和“精炼手术”。核心设计哲学是区分“能力”与“包装”。原版Claude Code的50万行代码中绝大部分属于“包装”层为了打造一个商业化、用户友好、可维护的产品而引入的复杂度。这包括复杂的UI框架基于React和Ink的终端用户界面提供了丰富的交互元素但也带来了巨大的依赖和打包体积。生产运维设施数据遥测Telemetry、错误报告、性能监控如集成Datadog。扩展与集成完整的插件市场系统、与Claude Desktop和云服务的桥接层、OAuth认证流程。边缘功能90多个斜杠命令中很多是针对特定场景的便利功能而非核心代理循环所必需。nanocode则像一位外科医生精准地切除了所有这些“包装”组织只保留了维持Agent生命活动的“器官系统”代理循环引擎驱动整个“思考-行动-观察”循环的核心异步生成器。工具执行系统包括15个最核心的工具Bash, Read, Edit, Write等及其并行执行器。上下文工程三层压缩策略、提示词缓存、令牌预算管理这是处理长对话和大量工具输出的关键。会话与状态管理基于JSONL的会话持久化与恢复机制。技能与子代理系统允许定义可复用技能和派生子任务的能力。这个选择的结果是惊人的代码量降至原版的1.8%依赖从192个锐减到6个打包体积从12MB缩小到约200KB。但根据测试在核心的代码理解、编辑、问题解决任务上其能力保留了85%-90%。这强有力地证明了AI Agent的核心效能取决于少数几个精心设计的关键模式而非堆砌功能。2.2 核心循环与数据流剖析理解nanocode必须理解其核心工作流我将其概括为“一个循环两条主线三层压缩”。一个循环即主代理循环AgentLoop。它是一个async generator不断地接收输入从用户或上一个工具结果获取信息。调用模型将当前会话上下文经过压缩和处理发送给LLM如Claude 3 Opus。解析决策模型返回的响应中可能包含纯文本思考extended thinking、工具调用请求tool_use或最终答案final。执行工具如果模型请求调用工具则通过StreamingExecutor并行或串行执行对应的工具如运行Bash命令、读取文件。观察结果将工具执行的结果作为新的“观察”消息追加到会话历史中。回到步骤2循环继续直到模型返回最终答案或用户中断。这个循环是所有AI Agent的通用范式但nanocode的实现异常清晰你可以在src/core/agent.ts中看到不到300行的主循环逻辑没有一丝赘肉。两条主线对话主线即用户与模型之间的消息历史messages。这条线负责维护对话的连贯性和上下文。文件主线一个独立的FileHistoryLRU缓存。它跟踪最近被读取或编辑过的文件。这是实现“后压缩恢复”功能的关键——当旧消息因上下文长度限制被压缩或丢弃时系统可以优先将这些活跃文件的内容重新注入上下文确保Agent不会“忘记”它正在操作的文件。三层压缩这是应对有限上下文窗口Context Window的工程艺术。假设Claude 3 Opus的上下文窗口是20万令牌而一次复杂的编程会话很容易超过这个限制。第一层自动压缩当会话历史令牌数接近阈值contextWindow - maxOutputTokens - 13000时系统会自动触发。它会将最早的一部分消息通常是用户和助理的对话回合总结成一段简短的摘要替换掉原始的长篇消息从而腾出空间。这个摘要本身也是一个LLM调用使用更小、更快的模型提示词模板在src/prompt/compact.ts中定义。第二层微压缩主要针对单个但体积巨大的工具输出比如grep搜索了整个代码库的结果。系统会将其截断只保留开头和结尾部分并加上一个“此处被截断”的标记。第三层后压缩恢复这是最精妙的一层。在压缩发生后系统会检查FileHistory缓存找出最近最活跃的5个文件将它们的最新内容以Read工具结果的形式重新插入到当前上下文的末尾。这样即使关于这些文件的原始对话被压缩了Agent手头依然有最新的文件内容可供参考实现了“工作记忆”的效果。实操心得这三层压缩机制是保证长会话有效性的基石。在你自己设计Agent时直接复制这个模式是一个极好的起点。关键在于“阈值”的设定nanocode预留了13000令牌的缓冲空间这是为了避免在模型生成回答的中途触发压缩导致混乱。你可以根据你使用的模型和任务类型调整这个缓冲值。3. 从零开始部署与深度配置指南3.1 环境准备与安装nanocode对运行环境的要求非常宽松这得益于其极简的依赖。Node.js确保你的系统安装了Node.js 18或更高版本。你可以使用nvmNode Version Manager来管理多个Node版本这对于前端或Node.js开发者来说是标配。# 检查当前版本 node --version # 如果版本低于18使用nvm安装并切换 nvm install 18 nvm use 18安装nanocode通过npm全局安装命令行工具。npm install -g nanocode-cli安装完成后直接在终端输入nanocode应该就能启动交互式REPL读取-求值-打印循环界面。如果提示命令未找到可能是你的npm全局路径没有添加到系统PATH环境变量中。一个常见的排查方法是# 查看npm的全局安装路径 npm config get prefix # 通常会是 /usr/local 或 /Users/你的用户名/.nvm/versions/node/v18.x.x # 确保该路径下的bin目录在你的PATH中 echo $PATH3.2 模型API配置详解nanocode本身不提供AI模型它需要连接一个后端LLM API。它原生支持Anthropic的API并且通过兼容OpenAI的接口可以连接无数个第三方平台。方案一使用Anthropic官方API推荐用于测试Claude 3系列访问 Anthropic控制台 注册并创建一个API密钥。在终端中设置环境变量export ANTHROPIC_API_KEYsk-ant-你的密钥为了持久化通常将这行命令添加到你的shell配置文件如~/.bashrc,~/.zshrc中然后执行source ~/.zshrc。方案二使用OpenRouter等聚合平台性价比与灵活性之选OpenRouter聚合了数十个主流模型包括Claude、GPT、Gemini等统一了API接口且价格透明有时更有优势。访问 OpenRouter官网 注册并获取API密钥。设置环境变量并指定基础URL指向OpenRouterexport OPENROUTER_API_KEYsk-or-你的密钥 export ANTHROPIC_BASE_URLhttps://openrouter.ai/api重要提示当你设置了ANTHROPIC_BASE_URLnanocode会默认你使用OpenAI兼容的接口。此时你还需要通过--model参数明确指定模型名称因为OpenRouter上的模型标识符与Anthropic不同。例如要使用Claude 3.5 Sonnet你需要知道其在OpenRouter上的完整名称。启动与模型选择# 使用Anthropic API默认模型是claude-3-5-sonnet-20241022 nanocode # 使用OpenRouter并指定模型 nanocode --model anthropic/claude-3-5-sonnet-20241022 # 启用“深度思考”模式让模型展示更多推理链消耗更多令牌 nanocode --thinking # 单次任务模式直接提出要求执行后退出 nanocode -p 帮我检查当前目录下所有TypeScript文件的语法错误第一次运行可能会比较慢因为它需要下载和缓存系统的提示词模板。启动后你会看到一个简洁的提示符表示已经进入交互模式。3.3 项目级配置与技能系统实战nanocode会从你运行它的目录开始向上层目录搜索配置文件形成层级化的配置。这让你可以为不同的项目设置不同的行为。1. 项目指令文件NANOCODE.md/CLAUDE.md这是最重要的配置文件。它的内容会被加载到每个会话的系统提示词System Prompt开头用来指导Agent在这个特定项目中应该如何行事。例如在一个React项目中你可以创建这样的NANOCODE.md# 本项目规范 - 这是一个使用TypeScript和Next.js 14构建的前端项目。 - 代码风格遵循ESLint配置和Prettier规则。 - 组件使用函数式组件和React Hooks。 - 所有API调用必须放在app/api/目录下并使用Route Handlers。 - 在修改任何样式文件前请先检查现有的Tailwind CSS类是否可用。 - 优先使用现有的工具函数库/lib/utils。当你在该项目目录下运行nanocode时这些指令会成为Agent的“背景知识”使其产出更符合项目规范。2. 权限配置文件.nanocode/settings.json这个文件控制Agent能做什么不能做什么是安全性的关键。{ permissions: { default: ask, // 全局默认权限allow允许, deny拒绝, ask询问 rules: [ { pattern: **/*.js, permission: allow }, { pattern: **/secrets/**, permission: deny }, { pattern: rm -rf *, permission: ask } ] }, mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /] } } }default: “ask”意味着对于任何没有明确规则匹配的操作Agent都会先询问你“是否允许执行此Bash命令”。rules数组允许你针对特定文件路径或命令模式设置白名单或黑名单。mcpServers部分配置了MCPModel Context Protocol服务器这可以让Agent访问更强大的工具比如这里的文件系统服务器它提供了比内置Read/Write工具更丰富的文件操作能力。3. 自定义技能.nanocode/skills/技能Skill是将复杂或重复性操作封装成可复用的提示词块。例如你可以创建一个代码审查技能--- name: code-review description: 对指定的代码文件进行全面的代码审查 user-invocable: true context: inline --- 请扮演资深代码审查员对以下代码进行审查 文件路径$ARGUMENTS 请从以下角度提供反馈 1. **功能正确性**逻辑是否有误边界条件是否处理 2. **代码风格**是否符合项目ESLint/Prettier配置命名是否清晰 3. **性能与安全**有无潜在的性能瓶颈或安全漏洞如SQL注入、XSS 4. **可维护性**代码结构是否清晰是否有过多的嵌套或重复逻辑 5. **改进建议**提供具体的、可操作的修改建议。 请直接开始审查。将这个文件保存为.nanocode/skills/code-review.md。之后在nanocode会话中你可以直接使用技能 /skills Available skills: code-review 使用技能code-review审查src/utils/auth.ts$ARGUMENTS会被替换成你提供的参数。context: inline意味着技能提示词会被直接插入到对话中。fork模式则会开启一个新的子会话来执行技能避免污染主会话上下文。4. 内置工具与斜杠命令实战详解4.1 核心工具链深度使用nanocode的15个内置工具是其“手”和“眼”。理解每个工具的特性和边界能让你更高效地与它协作。Bash工具安全与效率的平衡这是最强大也最危险的工具。nanocode实现了一套精细的安全检查机制来实现“只读命令自动批准”。# 当你输入以下命令时Agent会直接执行而不会询问你 列出当前目录下所有以.ts结尾的文件 # Agent可能会调用 ls -la *.ts因为这个命令被识别为“安全”的。其安全检查逻辑包括源码在src/tools/bash.ts中命令是否以cd,ls,cat,grep,find,pwd等无害命令开头命令中是否包含重定向输出到文件、|管道等可能改变系统状态的符号如果有则会触发询问命令是否包含rm,mv,dd,format等危险关键词一定会触发询问是否尝试访问敏感路径如/etc/passwd,~/.ssh避坑指南虽然有了安全检查但永远不要在包含重要数据且未备份的环境中随意使用--dangerously-skip-permissions参数。一个被误导的Agent可能会执行rm -rf ./*。我的习惯是在敏感项目中将settings.json的默认权限设为ask并对项目根目录设置permission: deny规则仅对src/等子目录开放allow。Edit与Write工具代码编辑的两种范式Edit工具用于修改现有文件。它要求你提供精确的字符串查找和替换内容。其强大之处在于内置了“唯一性验证”——它会确保你提供的“查找”字符串在目标文件中只出现一次否则会报错防止误改。这对于修改大型文件中的特定函数非常有用。 将auth.ts中第25行的‘const token localStorage.getItem(“key”)‘ 改为 ‘const token sessionStorage.getItem(“authToken”)‘Write工具用于创建新文件。它会自动创建不存在的目录并以原子方式写入先写入临时文件再重命名避免写入过程中程序崩溃导致文件损坏。Glob与Grep工具高效导航代码库当项目很大时让Agent“看到”所有文件是不现实的。你需要引导它使用这些搜索工具。 查找所有包含“UserInterface”这个类型定义的文件 # Agent可能会调用 grep -r type UserInterface src/ 或使用内置Grep工具。 在components目录下查找所有的React组件文件.tsx # Agent可能会调用 glob(src/components/**/*.tsx)。实操技巧如果你的系统安装了ripgreprg命令nanocode的Grep工具会优先使用它因为rg比原生grep快得多。建议开发者安装ripgrep来提升Agent的代码搜索体验。Agent工具开启“分身”与“并行”这是实现复杂任务分解的关键。你可以让主Agent派生出子Agent去处理专项任务。同步模式主Agent暂停等待子Agent完成任务并返回结果。异步模式主Agent继续自己的工作子Agent在后台运行。探索模式给子Agent一个开放性的探索任务比如“研究一下这个代码库的结构并汇报”。 我需要重构用户认证模块。请先派一个子Agent去分析当前auth.ts和user.ts的耦合度。 # 主Agent可能会调用 Agent(“分析auth.ts与user.ts的耦合度找出所有相互引用的地方。”, mode“sync”)4.2 斜杠命令会话管理的高级操作斜杠命令是控制会话状态和获取信息的快捷方式。/compact手动触发上下文压缩。当对话历史很长你感觉Agent似乎“忘记”了之前的内容时可以使用它。执行时会有一个旋转的进度提示Spinner。/cost实时查看本次会话消耗的令牌数和估算费用。这对于控制使用成本非常重要尤其是在使用Opus等昂贵模型时。/plan切换到“计划模式”。在此模式下所有会修改系统的工具如Bash非只读、Edit、Write都会被禁用。Agent只能进行读取、搜索和思考。这非常适合在真正执行破坏性操作前让Agent先制定一个详细的计划供你审阅。/init一个强大的项目初始化命令。它会分析当前目录的代码结构文件类型、框架等并自动生成一个初步的NANOCODE.md文件包含针对该项目的通用指导原则。这是一个很好的起点你可以在此基础上进行修改。/resume session-id恢复之前的会话。所有会话都以JSONL格式保存在~/.nanocode/sessions/目录下文件名就是会话ID。当你处理一个长期任务需要中断时这个功能至关重要。5. 开发、调试与扩展进阶5.1 从源码运行与调试如果你想深入研究或贡献代码需要从GitHub克隆源码。git clone https://github.com/Lyt060814/nanocode.git cd nanocode npm install npm run build # 编译TypeScript到dist目录 # 直接运行本地编译后的版本 node dist/cli.js # 或者使用开发模式代码变动会自动重编译 npm run dev调试技巧由于nanocode是命令行工具你可以利用Node.js的调试功能。在VSCode中可以创建一个launch.json配置{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug nanocode, skipFiles: [node_internals/**], program: ${workspaceFolder}/dist/cli.js, console: integratedTerminal } ] }然后在你感兴趣的地方比如src/core/agent.ts的循环处打上断点即可单步跟踪Agent的整个决策和执行流程。5.2 常见问题与排查实录即使设计精巧在实际使用中仍会遇到各种问题。以下是我遇到的一些典型情况及其解决方法问题1Agent陷入循环或输出无关内容现象Agent不停地调用Read工具读取同一个文件或者开始输出与任务无关的哲学思考。原因通常是系统提示词包括NANOCODE.md不够清晰或者上下文窗口已满导致早期的重要指令被压缩或丢弃。排查与解决使用/context命令检查当前上下文使用率。如果接近100%使用/compact手动压缩。检查你的NANOCODE.md指令是否明确、无歧义。避免使用“可能”、“或许”等模糊词汇。用肯定的、具体的语句如“必须使用async/await处理异步操作”。如果问题持续尝试用/clear清空当前会话历史重新开始并在一开始就给出最精确的指令。问题2工具调用权限被意外拒绝现象即使是ls这样的简单命令Agent也总是询问或直接拒绝。原因settings.json中的权限规则rules可能存在冲突或过于严格的路径模式。排查与解决运行/config命令查看当前生效的配置。nanocode会合并从当前目录到根目录的所有settings.json可能存在上层目录的严格规则覆盖了你的本地规则。检查你的settings.json中rules数组的顺序。规则是按顺序匹配的第一个匹配的规则生效。确保你的允许规则allow放在拒绝规则deny之前。路径模式**/*会匹配所有文件慎用。问题3连接OpenRouter等第三方API失败或模型不可用现象启动时提示API错误或模型未找到。原因环境变量设置错误或第三方平台的模型标识符与nanocode预期不符。排查与解决确认环境变量已正确设置echo $OPENROUTER_API_KEY。OpenRouter的模型名称是带命名空间的。使用nanocode --model list命令如果支持或直接去OpenRouter的模型列表查看正确的名称。例如使用Claude 3.5 Sonnet应该是anthropic/claude-3-5-sonnet-20241022。有些第三方API端点可能有频率限制或需要额外的请求头。目前nanocode的API客户端配置相对固定如果遇到复杂情况可能需要修改src/core/api-client.ts文件来添加自定义请求头。问题4会话无法恢复或恢复后状态错乱现象使用/resume id后Agent似乎不记得之前做过的事情。原因会话文件JSONL可能损坏或者恢复时的工作目录与保存时不同。排查与解决会话文件保存在~/.nanocode/sessions/下是纯文本的JSONL格式你可以用文本编辑器打开检查。确保每一行都是一个完整的JSON对象。关键点会话中记录的文件路径是相对路径。如果你在/home/user/projectA下保存了会话然后切换到/home/user/projectB下去恢复那么会话中关于./src/index.ts的引用就会指向错误的位置。务必在相同的项目根目录下恢复会话。5.3 扩展你的nanocode添加自定义工具nanocode的架构非常清晰添加一个新工具是学习其插件机制的最佳方式。假设我们想添加一个Fetch工具用于获取URL内容。定义工具接口在src/tools/types.ts中工具调用遵循Anthropic的消息格式。我们需要定义输入参数。创建工具文件在src/tools/目录下创建fetch.ts。// src/tools/fetch.ts import { Tool } from ./types; import axios from axios; // 需要先安装: npm install axios export interface FetchInput { url: string; method?: GET | POST; // 简单支持两种方法 headers?: Recordstring, string; body?: any; } export const fetchTool: ToolFetchInput { name: Fetch, description: Fetch content from a URL, inputSchema: { type: object, properties: { url: { type: string, description: The URL to fetch }, method: { type: string, enum: [GET, POST], default: GET }, headers: { type: object, additionalProperties: { type: string } }, body: { type: object } }, required: [url] }, execute: async (input: FetchInput) { try { const response await axios({ url: input.url, method: input.method || GET, headers: input.headers, data: input.body }); return { content: [ { type: text, text: Status: ${response.status}\nHeaders: ${JSON.stringify(response.headers, null, 2)}\nBody:\n${response.data} } ] }; } catch (error: any) { return { content: [{ type: text, text: Fetch failed: ${error.message} }], isError: true }; } } };注册工具在src/tools/registry.ts中导入并添加你的新工具到tools数组中。import { fetchTool } from ./fetch; // ... 其他导入 export const tools [ // ... 其他工具 fetchTool, ];更新类型定义可选但推荐在src/core/types.ts中更新工具名称的联合类型确保类型安全。重新编译并测试运行npm run build然后启动nanocode。现在当你要求Agent“获取某个API的数据”时它就有可能调用你新创建的Fetch工具了。这个过程揭示了nanocode工具系统的本质一个符合特定接口name,description,inputSchema,execute的JavaScript对象数组。这种简洁性使得功能扩展变得非常直接。6. 性能调优与最佳实践经过一段时间的深度使用我总结出一些能让nanocode发挥最佳效能的经验。1. 模型选择策略复杂推理与规划使用能力最强的模型如Claude 3.5 Sonnet或Opus。它们对复杂指令的理解更深制定的计划更可靠。日常编辑与简单任务切换到更小、更快的模型如Claude 3 Haiku或通过OpenRouter调用的GPT-4o-mini。这能大幅节省成本和等待时间。在nanocode中你可以随时使用/model命令切换。压缩步骤nanocode在压缩历史消息时会调用一个更小、更快的模型在代码中可配置。确保这个“压缩模型”的设置是成本效益最优的。2. 提示词工程优化nanocode的系统提示词模板在src/prompt/system.ts中。虽然不建议新手直接修改但理解其结构有助于你编写更好的NANOCODE.md。角色设定要具体不要只说“你是一个助手”。要说“你是一个经验丰富的TypeScript后端工程师擅长使用NestJS框架和Prisma ORM”。约束条件要前置把最重要的规则放在NANOCODE.md的最前面。LLM对提示词开头的部分注意力更高。使用示例如果某种操作模式很复杂在NANOCODE.md中提供一个清晰的示例。例如“当需要创建新的API端点时请按照以下格式1. 在controller中定义路由。2. 在service中实现逻辑...”。利用技能将常用的复杂指令集封装成技能。这比每次在对话中详细描述要高效得多也减少了上下文消耗。3. 会话管理纪律定期清理长时间会话必然导致上下文累积。对于已经完成的大型任务主动使用/clear开始一个新会话而不是一直延续一个臃肿的旧会话。善用/plan模式在执行任何可能影响大量文件的修改如重构前先进入计划模式。让Agent输出一个详细的步骤列表你审核通过后再切换回正常模式执行。项目隔离为不同的项目创建不同的.nanocode配置目录。避免用一个通用的配置去处理所有类型的项目。4. 安全边界设定最小权限原则在settings.json中始终以default: “ask”开始。只对你完全信任的目录如src/设置allow规则。审计日志nanocode目前没有详细的审计日志。一个简单的补救方法是结合系统的script命令或终端复用器如tmux的日志功能记录下所有会话中执行的命令便于事后复查。代码审查对于Agent生成的、尤其是涉及核心逻辑或安全功能的代码必须进行人工审查。不要盲目信任其输出。nanocode像一把锋利的手术刀它剥离了商业AI Agent的华丽外衣将最核心的“大脑”与“神经反射弧”赤裸地展示给你。通过它你不仅能获得一个强大且可定制的编程伙伴更能深刻理解现代AI Agent是如何思考、规划和执行任务的。这种理解或许比你用它完成的任何一个具体项目都更有价值。