1. 从零手写 Mini-CursorReAct 循环驱动的 AI 编程 Agent 是什么Mini-Cursor 是一个用 Node.js 手写的 AI 编程 Agent它能自己读文件、写代码、跑命令在十几轮 ReAct 循环里把一个 React TodoList 项目从空目录搭到能跑起来。适合谁适合已经会用 LangChain 定义工具、但还没把「工具调用 文件读写 代码生成」串成完整闭环的开发者。这一课要解决的核心问题很具体前四课我们有了工具定义、Agent Loop、CLI 执行、完整工具箱但它们还是散落的零件没有一个能独立运行的主程序把它们驱动起来。我试过把工具和主循环写在一个文件里结果改一个工具就要动整个 Agent调试时日志混在一起根本看不清哪一步是模型推理、哪一步是工具执行。所以这一课的关键动作是分层all-tools.mjs只负责工具定义与导出mini-cursor.mjs只负责 ReAct 主循环、消息管理和安全护栏。两者通过import连接职责清晰。ReAct 循环的本质是「推理—行动—观察」三步反复模型先想下一步该干什么Reason然后调用一个工具Act拿到工具返回结果Observe把结果塞回消息历史再进入下一轮推理。Mini-Cursor 把这个循环跑在一个for循环里最多 30 轮每轮都检查模型有没有返回tool_calls——没有就说明任务完成直接返回最终回复。这一课最终交付三样东西一份可复制的 Agent 主程序配置片段、一份工具注册示例、一次端到端代码生成验证动作。跑通之后你手里就有一个能独立干活的 AI 编程 Agent而不是一堆需要手动拼接的函数。下面从环境准备开始一步步把它搭起来。2. TaoToken 前置统一 Key 与 Base URL 接入配置在写 Agent 主程序之前先把模型通道配好。Mini-Cursor 需要一个兼容 OpenAI 接口协议的 Base URL 和 API KeyTaoToken 提供统一通道把模型调用收敛到一个入口省得每个模型单独配一套环境变量。这一步的目标是让ChatOpenAI能通过 TaoToken 的 Base URL 正常发起请求。先拿到 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就得重建。然后确认你要用的模型 IDTaoToken 的模型列表在 https://taotoken.net/doc 可以查到编程任务建议选推理能力强的模型。接下来配置环境变量。在项目根目录建一个.env文件写入# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL你的模型ID这里有个容易踩的坑Base URL 结尾不要带/v1也不要带斜杠。TaoToken 的 API 入口是https://taotoken.net/apiSDK 会自己拼接路径。如果你写成https://taotoken.net/api/v1请求会打到错误路径上返回 404 而不是 401排查时容易误判成 Key 问题。然后在mini-cursor.mjs里初始化模型。用langchain/openai的ChatOpenAI把configuration.baseURL指向 TaoTokenimport dotenv/config; import { ChatOpenAI } from langchain/openai; const model new ChatOpenAI({ modelName: process.env.TAOTOKEN_MODEL, apiKey: process.env.TAOTOKEN_API_KEY, temperature: 0, configuration: { baseURL: process.env.TAOTOKEN_BASE_URL, }, });temperature: 0是编程 Agent 的标配代码生成要的是确定性不是创意。modelName从环境变量读换模型不用改代码。如果你用的是 Claude Code 或 Cline 这类工具配置逻辑一样Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你选的模型。三件套对齐通道就通了。依赖安装用 npm 或 pnpm 都行pnpm add langchain/openai langchain/core dotenv chalk装完之后可以先写一个最小验证脚本确认通道能通再往下写 Agent 主循环。这一步别跳过通道不通后面所有调试都是白费。3. 可复制配置Agent 主程序与工具注册片段这一节给出可以直接复制的mini-cursor.mjs核心片段包含工具注册、System Prompt 和 ReAct 主循环。先看工具注册部分从all-tools.mjs导入四个工具并绑定到模型import { HumanMessage, SystemMessage, ToolMessage } from langchain/core/messages; import { executeCommandTool, readFileTool, writeFileTool, listDirectoryTool, } from ./all-tools.mjs; import chalk from chalk; const tools [ readFileTool, writeFileTool, listDirectoryTool, executeCommandTool, ]; const modelWithTools model.bindTools(tools);bindTools是关键一步它把工具 schema 注入到模型的请求里模型才知道有哪些工具可调、每个工具要什么参数。没有这一步模型只会返回纯文本永远不会触发tool_calls。接着是 System Prompt这里要预埋防呆规则。Mini-Cursor 最容易出的错是路径叠加模型在workingDirectory已经切到子目录的情况下还在命令里再cd一次导致找不到目录。所以在 System Prompt 里明确写清楚const systemPrompt 你是一个项目管理助手使用工具完成任务。 当前工作目录: ${process.cwd()} 工具: 1. read_file: 读取文件 2. write_file: 写入文件 3. execute_command: 执行命令支持 workingDirectory 参数 4. list_directory: 列出目录 重要规则 - execute_command: - workingDirectory 参数会自动切换到指定目录 - 使用 workingDirectory 时绝对不要在 command 中使用 cd - 错误示例: { command: cd react-todo-app pnpm install, workingDirectory: react-todo-app } - 正确示例: { command: pnpm install, workingDirectory: react-todo-app } 回复要简洁只说做了什么;这段规则看着啰嗦但实测下来能省掉大量事后修 bug 的时间。在提示词里提前埋好防呆规则比等模型犯错再回头改代码高效得多。然后是 ReAct 主循环这是整个 Agent 的心脏async function runAgentWithTools(query, maxIterations 30) { const messages [ new SystemMessage(systemPrompt), new HumanMessage(query), ]; for (let i 0; i maxIterations; i) { console.log(chalk.bgGreen(正在等待第 ${i} 次 AI 思考...)); const response await modelWithTools.invoke(messages); messages.push(response); if (!response.tool_calls || response.tool_calls.length 0) { console.log(\nAI 最终回复:\n${response.content}\n); return response.content; } for (const toolCall of response.tool_calls) { const foundTool tools.find((t) t.name toolCall.name); if (foundTool) { const toolResult await foundTool.invoke(toolCall.args); messages.push( new ToolMessage({ content: toolResult, tool_call_id: toolCall.id, }) ); } } } return messages[messages.length - 1].content; }用for而不是while是因为maxIterations提供了硬性兜底。while循环如果模型一直返回tool_calls可能无限跑下去烧 tokenfor循环最多 30 轮就停安全得多。ToolMessage必须带上tool_call_id这是 OpenAI 协议的要求缺了会报错。最后是执行入口和超时兜底try { await runAgentWithTools(case1); } catch (err) { console.error(\n错误: ${err.message}); } setTimeout(() { console.log(超时兜底强制退出进程); process.exit(0); }, 1000000);三层安全护栏maxIterations防无限循环try-catch捕获异常setTimeout超时强制退出。工程级 Agent 这三层缺一不可。4. 验证请求一次端到端代码生成动作配置写完现在跑一次真实的端到端验证。任务 Prompt 用一个完整的编程规格书让 Agent 生成一个 React TodoList 项目const case1 创建一个功能丰富的 React TodoList 应用 1. 创建项目: echo -e n\nn | pnpm create vite react-todo-app --template react-ts 2. 修改 src/App.tsx实现完整的 TodoList: - 添加、删除、标记完成 - 分类筛选全部/进行中/已完成 - 统计信息显示 - localStorage 数据持久化 3. 添加复杂样式: - 渐变背景蓝到紫 - 卡片阴影圆角 - 悬停效果 4. 添加动画: - 添加/删除时的过渡动画 - 使用 css transitions 5. 列出目录确定 注意使用 pnpm功能要完整样式要美观要有动画效果 之后 react-todo-app 项目中 1. 使用 pnpm install 安装依赖 2. 使用 pnpm run dev 启动服务器 ;运行node src/mini-cursor.mjs观察 Agent 的 ReAct 循环。它会经历大约 10 到 15 轮第一到二轮模型推理出需要先创建 Vite 项目骨架调用execute_command执行pnpm create vite观察到项目创建成功。第三轮调用list_directory查看react-todo-app/src下有哪些文件观察到App.tsx、main.tsx、index.css。第四轮调用read_file读取App.tsx现有内容确认是默认模板代码。第五到六轮调用write_file写入完整的 TodoList 组件代码两百多行。第七轮再调write_file写入样式文件加上渐变背景、卡片阴影和过渡动画。第八轮调用execute_command执行pnpm install注意这里workingDirectory设为react-todo-app命令里不带cd。第九轮执行pnpm run dev启动开发服务器观察到 Vite 启动在http://localhost:5173/。第十轮再调list_directory做最终确认。工具调用统计大致是execute_command四到五次write_file两到三次read_file一到两次list_directory两到三次。跑完之后hello-langchain/react-todo-app/目录真实存在浏览器打开http://localhost:5173/能看到一个带渐变背景、卡片阴影、悬停效果和过渡动画的 TodoList支持添加、删除、标记完成、分类筛选、统计显示和 localStorage 持久化。整个过程没有任何人工编写代码Agent 自己规划步骤、调用工具、逐步完成。这就是 ReAct 循环的威力模型负责推理工具负责执行循环负责推进。5. 本篇常见错排查401、local proxy failed、reading choices 报错跑 Mini-Cursor 时最容易撞上几类报错逐个说清楚怎么定位。第一类是 401 未授权。报错长这样401 Incorrect API key provided或AuthenticationError: 401。原因通常是.env里的TAOTOKEN_API_KEY没读到或者 Key 复制时带了空格。排查步骤先在mini-cursor.mjs开头加一行console.log(process.env.TAOTOKEN_API_KEY?.slice(0, 8))确认 Key 前八位打印出来。如果打印undefined说明dotenv/config没生效检查import dotenv/config是不是在文件最顶部。如果 Key 打印正常但还是 401去 https://taotoken.net/api-keys 确认 Key 没过期、没被删。第二类是local proxy failed或连接超时。报错类似Connection error或fetch failed。这通常是 Base URL 写错了。检查TAOTOKEN_BASE_URL是不是https://taotoken.net/api结尾不要带/v1不要带斜杠。如果写成https://taotoken.net/api/v1请求路径会变成/api/v1/chat/completions而正确路径是/api/chat/completions结果就是 404 或连接失败。改回正确 Base URL 即可。第三类是reading choices报错。完整报错类似TypeError: Cannot read properties of undefined (reading choices)。这个错说明模型返回的响应结构不对SDK 拿不到choices字段。常见原因是模型 ID 写错了TaoToken 返回了一个错误对象而不是正常的 completion 响应。去 https://taotoken.net/doc 核对模型 ID 拼写确认TAOTOKEN_MODEL填的是有效模型。另一个可能是 Base URL 指向了一个不兼容 OpenAI 协议的端点确认用的是https://taotoken.net/api。第四类是 OAuth 相关报错如果你用 Claude Code 或 Cline 接入可能遇到OAuth token expired或invalid_grant。这类工具走的是 OAuth 流程但 TaoToken 用的是 API Key 模式需要在工具设置里把认证方式从 OAuth 切换成 API KeyBase URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你选的模型。三件套对齐后 OAuth 报错就消失了。第五类是工具调用死循环。Agent 反复调用同一个工具跑满 30 轮还没结束。这通常是 System Prompt 里的规则不够明确模型不知道任务已经完成。检查 System Prompt 有没有写清楚「任务完成后返回纯文本不要继续调用工具」。如果还不行把maxIterations调小到 15先跑通再放宽。排查时记住一个原则先确认通道通不通用最小脚本发一次请求再确认工具注册对不对打印tools数组最后看 ReAct 循环逻辑。分层排查比盯着报错猜快得多。6. 语义一致 CTA把 Mini-Cursor 接到 TaoToken 跑通闭环Mini-Cursor 跑通之后你手里有一个能独立干活的 AI 编程 Agent。它的模型通道走 TaoToken 统一 Key 和 Base URL换模型只改环境变量不用动 Agent 代码。接下来可以做的几件事如果你在排查接入问题比如 401、Base URL 写错、模型 ID 不对直接看接入文档 https://taotoken.net/doc 里面有完整的 Base URL、Key、Model ID 三件套说明。需要新建或管理 Key去 https://taotoken.net/api-keys 。想先验证模型对话是否正常不写代码用模型对话页面发一条消息试试通道https://taotoken.net/model-chat 。确认通道通了再回来跑 Agent能省掉一半调试时间。如果你打算长期做编码 Agent、把 Mini-Cursor 扩展成日常工具或者接 Claude Code、Cline 这类工具做长期开发Coding Plan 更划算https://taotoken.net/coding-plan 。它按编码场景优化了配额适合高频调用。Mini-Cursor 的完整闭环是TaoToken 提供模型通道all-tools.mjs提供工具能力mini-cursor.mjs提供 ReAct 主循环三者串起来就是一个能自己读文件、写代码、跑命令的 AI 编程 Agent。把 Base URL 改到 TaoTokenKey 和 Model ID 对齐node src/mini-cursor.mjs一跑闭环就通了。