Nanocoder：在本地终端运行的代码生成工具

nanocoder 是一个在本地终端环境中运行的AI编程工具，它的核心设计理念是“本地优先”，充分保护用户的隐私和数据安全。 这个工具让开发者可以在自己的电脑上，通过命令行界面与AI进行交互，完成代码编写、审查和重构等任务。nanocoder 的特点是支持多种AI模型服务商。用户既可以连接完全在本地运行的Ollama，实现离线代码生成，也可以配置OpenRouter或兼容OpenAI的API接口，来使用那些功能更强大的云端AI模型。 它内置了一套实用的工具系统，允许AI直接读写文件、执行终端命令，还能通过模型上下文协议（MCP）连接到更多外部服务，例如文件系统、GitHub仓库和网络搜索等，进一步拓展了应用能力。

功能列表

• 支持多种AI服务商：可以连接本地运行的Ollama、云端的OpenRouter以及任何与OpenAI API兼容的服务（如LM Studio、vLLM等）。
• 高级工具系统：内置了文件操作、执行bash命令等工具。AI在获得用户许可后，可以执行读写文件或运行代码等操作。
• 模型上下文协议（MCP）：支持连接到MCP服务器，从而扩展AI的工具能力，例如可以接入文件系统、GitHub、Brave搜索和记忆库等。
• 自定义指令系统：用户可以在项目的.nanocoder/commands目录下，使用Markdown文件创建带有参数的可复用指令，方便执行重复性高的任务，例如生成测试、代码审查等。
• 智能用户体验：提供命令自动补全、对话历史追溯、会话状态保持等功能，并且会根据任务状态实时显示AI的思考过程、Token用量和执行时间。
• 项目级独立配置：通过在项目根目录放置agents.config.json文件，可以为每个项目设置不同的AI模型或API密钥，方便管理。
• 开发者友好：整个项目使用TypeScript构建，代码结构清晰，易于扩展。同时提供了详细的调试工具和日志等级控制。

使用帮助

nanocoder 是一个运行在终端（命令行界面）的工具，下面将详细介绍如何安装和使用它。

安装流程

1. 环境准备

安装 nanocoder 之前，需要确保你的电脑上已经安装了 Node.js (版本需要18以上) 和 npm 包管理工具。npm通常会随Node.js一起安装。

2. 全局安装

推荐使用全局安装的方式，这样你就可以在电脑的任何目录下直接运行 nanocoder。打开你的终端，输入以下命令：

npm install -g @motesoftware/nanocoder

安装完成后，你可以在任何项目文件夹中直接通过输入 nanocoder 命令来启动它。

配置AI模型

nanocoder 的强大之处在于它可以连接不同的AI模型。你需要根据自己的需求，选择并配置一种AI服务。配置信息保存在一个名为agents.config.json的文件里，你需要把这个文件放在你项目代码的根目录中。

方案一：使用Ollama（本地模型）

这是最保护隐私的方式，因为模型完全在你自己的电脑上运行。

1. 首先，你需要安装并运行Ollama。
2. 然后，从Ollama模型库中下载一个你需要的模型。例如，下载一个轻量的qwen2:0.5b模型：

   ollama pull qwen2:0.5b
   

3. 完成以上步骤后，直接运行nanocoder，它会自动检测到你本地的Ollama服务并连接。

方案二：使用OpenRouter（云端模型）

OpenRouter集合了市面上多种优秀的AI模型，例如GPT-4o、Claude 3等。

1. 在你的项目根目录下，创建一个agents.config.json文件。
2. 将下面的内容复制到文件中，并把your-api-key-here替换成你自己的OpenRouter API密钥，同时在models字段中填入你想使用的模型名称。

   {
   "nanocoder": {
   "openRouter": {
   "apiKey": "your-api-key-here",
   "models": ["openai/gpt-4o", "anthropic/claude-3-opus"]
   }
   }
   }
   

方案三：使用兼容OpenAI的API（本地或远程）

如果你使用的AI服务（例如LM Studio、vLLM或你自己搭建的服务）提供了兼容OpenAI的API接口，也可以进行配置。

1. 同样，在项目根目录创建agents.config.json文件。
2. 填入以下内容，将baseUrl替换成你的服务地址，如果需要API密钥也一并填入。

   {
   "nanocoder": {
   "openAICompatible": {
   "baseUrl": "http://localhost:1234",
   "apiKey": "optional-api-key",
   "models": ["model-1", "model-2"]
   }
   }
   }
   

基本操作指令

启动 nanocoder 后，你会进入一个交互式聊天界面。你可以直接输入自然语言描述你的需求，也可以使用斜杠/开头的内置指令来控制程序。

• /help: 显示所有可用的指令列表。
• /provider: 切换AI服务商，例如从Ollama切换到OpenRouter。
• /model: 在当前服务商提供的模型列表中进行切换。
• /clear: 清空当前的聊天记录，开始一个新的会话。
• /debug: 切换日志显示级别，用于查看程序运行的详细信息。
• /exit: 退出nanocoder程序。

使用自定义指令

自定义指令是nanocoder的一个特色功能，它能帮你把常用的复杂任务模板化。

1. 在你的项目根目录下创建一个名为.nanocoder的文件夹，然后在其中再创建一个commands文件夹。
2. 在.nanocoder/commands/目录下，创建一个Markdown文件，例如test.md。
3. 在该文件中，你可以定义指令的描述、别名和参数。 例如，创建一个用于生成单元测试的指令：

   ---
   description: "为指定的组件生成全面的单元测试"
   aliases: ["testing", "spec"]
   parameters:
     - name: "component"
       description: "需要测试的组件或函数名称"
   required: true
   ---
   请为 {{component}} 生成全面的单元测试。测试需要覆盖以下几点：
   - 正常情况下的行为
   - 边界条件和异常处理
   - 对外部依赖进行模拟
   - 清晰的测试描述
   

4. 保存文件后，你就可以在nanocoder中使用这个新指令了。比如，为UserService生成测试，你可以输入：
   /test component="UserService"

程序会自动将{{component}}替换为UserService，然后把整个提示发送给AI模型，让它执行任务。

应用场景

1. 快速生成代码片段
   当开发者需要编写一个新功能或模块时，可以直接在终端中向nanocoder描述需求，例如“创建一个解析CSV文件的TypeScript函数”，AI会直接生成对应的代码。
2. 代码审查和重构
   可以将一段写好的代码交给nanocoder进行审查，并提出改进建议。也可以使用自定义的重构指令，例如/refactor:dry，让AI按照“不要重复自己”的原则优化代码。
3. 编写单元测试
   为已有的函数或组件快速生成单元测试用例，是软件开发中比较繁琐的一环。通过自定义的/test指令，开发者只需提供组件名，即可让AI自动编写测试代码，提高开发效率。
4. 学习新的编程语言或框架
   当接触不熟悉的技术时，可以通过提问的方式，让nanocoder提供代码示例，或者解释某些代码的用途和工作原理，把它当作一个随叫随到的编程老师。

QA

1. nanocoder支持哪些操作系统？
   nanocoder是基于Node.js开发的，因此可以在所有主流操作系统上运行，包括Windows、macOS和Linux，只要系统上安装了Node.js环境即可。
2. 使用本地的Ollama模型有什么要求？
   使用Ollama需要在你的电脑上先安装并运行Ollama程序。对电脑硬件有一定要求，主要取决于你运行的AI模型的大小。越大的模型（例如超过70亿参数）需要越多的内存和一块性能较好的显卡（GPU）来保证生成速度。
3. 我的API密钥和代码数据安全吗？
   nanocoder的设计理念是“本地优先”。当你使用Ollama时，所有数据和计算都在你的本地电脑上完成，不经过任何外部服务器。当你使用OpenRouter等云端服务时，你的代码和提示会通过API发送给相应的服务商，这种情况下你需要遵守该服务商的数据隐私政策。配置文件agents.config.json保存在你的本地项目目录中，不会被上传。
4. nanocoder和其他AI编程工具有什么不同？
   nanocoder的主要区别在于它是一个纯粹在命令行终端中运行的工具，这让它非常适合那些习惯于键盘操作和终端工作流的开发者。其次，它强调本地优先和用户控制，让用户可以自由选择使用本地模型还是云端模型，并且通过项目级配置文件进行精细化管理。