前端转 AI 这趟路走到第 13 天终于要搞点正经东西了。前 12 天零零散散学了 TypeScript、Node.js、大模型 API 调用、Prompt 工程、函数调用这些基础如果一直停留在跟着教程敲 demo的状态说实话心里是发虚的——学了不用等于白学。所以 Day 13 我给自己定的任务很明确抛开教程、抛开网页 UI纯粹用命令行做一个能用的 AI 助手 v1把前 12 天学的东西全部串起来。这篇文章就是完整的项目复盘从设计思路到踩坑记录都有打算走前端转 AI这条路的朋友可以直接照着做。先说清楚这个项目解决什么问题。日常写代码最烦的就是在终端和浏览器之间来回切遇到一个报错要复制去问 AI改完配置想让它解释一下又得切窗口。命令行 AI 助手就是把大模型塞进终端里你在哪写代码就在哪问问题输出还能直接作为命令执行效率完全是另一个量级。适合谁看前端转 AI 的自学者、想熟悉 Node.js CLI 开发的工程师以及单纯想给终端加个外挂的开发者。1. 综合项目选型与设计思路1.1 前 12 天学的技术点怎么串起来做综合项目最忌讳的是把以前写过的东西原样拼一遍。我前 12 天学的内容大致分四块TS 类型系统、Node.js 运行时能力、大模型 HTTP 接口交互、Prompt 与工具调用设计。这次做 CLI 助手每块都得真正发挥作用而不是为了用而用。TS 类型系统用在了两个地方。一是配置文件的 Schema 定义我用 Zod 做运行时校验环境变量、用户配置、命令行参数全部过一遍校验类型错误在启动阶段就暴露而不是等到请求大模型时才报错。二是会话消息的类型设计把 system、user、assistant、tool 四种消息角色建模成联合类型后续做上下文拼装、tools 消息处理都基于这套类型编译器帮我兜底。Node.js 能力这块重点用了原生 fetch 和流式读取。Node 18 之后fetch是全局的不需要装axios调用大模型 API 完全够用。流式响应则用ReadableStream的异步迭代器逐段读取配合readline做逐行解析把 SSE 格式的数据流转化成可读的文本块。终端交互部分用readline/promises提供的question方法逐行读输入同时监听keypress事件实现快捷键。这些都是前端思维的直接迁移——事件驱动、状态管理、异步流程控制在 CLI 里照样适用只是把 DOM 换成了 stdin/stdout。大模型 API 交互不再停留在发一个请求拿到完整回复的层面。这次我专门封装了流式请求、超时中断、错误重试、上下文拼接还实现了 tools 调用协议模型返回工具调用请求时CLI 负责执行工具、回传结果、让模型基于工具输出继续生成。Prompt 与工具调用的设计结合得更紧密。系统 Prompt 不再是一段固定文本而是由角色设定、可用工具清单、输出规范三段动态拼接工具清单会随用户配置变化。工具调用也不是模板代码——我真正写了 shell 命令执行和文件读取两个工具让模型能伸手操作电脑。1.2 为什么是命令行而不是网页应用作为前端转 AI 的人第一个综合项目不做网页反而做 CLI很多人不理解。我的理由有三层。第一层是成本考量。网页应用意味着要处理 UI 框架、路由、状态管理、构建配置、跨域请求、部署方案这一整套东西这些我之前已经熟练了再练一遍边际收益很低。转换期的目标是补齐前端之外的能力CLI 正好把技能树往 Node.js 生态和工程化方向扩展。第二层是交互本质。AI 助手的核心价值是低摩擦调用终端天然是开发者高频驻留的场景。在 IDE 的终端里唤起助手看报错、改命令、查 API 参数比打开浏览器、新建对话、粘贴代码再等回复快得多。命令行产品没有图形界面反而逼着我思考信息如何用最紧凑的排版呈现——这也是一种产品能力。第三层是工程复杂度合适。CLI 项目麻雀虽小五脏俱全参数解析、配置管理、密钥安全、日志输出、会话持久化、子命令设计、跨平台兼容、交互体验优化该有的工程问题一个不少。作为综合项目复杂度和 12 天的学习量刚好匹配做大了收不住比如做成 GUI 应用做小了没挑战比如只跑一次脚本。这一步踩实了后面再上 Agent、上 Web 服务都顺理成章。1.3 v1 版本的功能边界怎么划综合项目最容易翻车的地方是功能膨胀。我列功能清单时反复问自己哪些功能能证明我掌握了前 12 天的核心知识哪些只是锦上添花最终 v1 圈定的核心功能是五条对话问答支持流式输出与中断、多轮上下文自动维护历史消息、工具调用shell 执行和文件读取、会话持久化退出后恢复上下文、子命令控制清空、切换模型、查看上下文。这五条对应的是大模型 API、流式处理、上下文管理、工具调用、CLI 交互这五大核心技能点。明确砍掉的功能也列一下联网搜索功能先不做涉及外部服务聚合、多 Agent 协作不做复杂度超标、插件系统不做工程化太重)、用户认证体系不做单机工具不需要。砍功能的意义在于让项目能在两三天内完成能完整跑通而不是半成品。v1 是骨架完整、器官齐全不是功能堆叠、到处是洞。2. 工程化搭建与核心模块设计2.1 项目结构和依赖选型项目用 pnpm 初始化TypeScript 直接跑在tsx上不经过编译步骤开发体验接近前端项目里用 Vite 那种即时反馈。先看完整的目录结构ai-cli/ ├── package.json ├── tsconfig.json ├── .env.example ├── .gitignore └── src/ ├── index.ts # 入口命令分发 ├── types.ts # 全局类型定义 ├── config.ts # 配置加载与校验 ├── ai/ │ ├── client.ts # 大模型 API 封装 │ ├── prompt.ts # 系统 Prompt 组装 │ └── stream.ts # SSE 流式解析 ├── tools/ │ ├── registry.ts # 工具注册表 │ ├── shell.ts # 执行 shell 命令 │ └── file.ts # 读取文件内容 ├── session/ │ └── store.ts # 会话持久化 └── ui/ ├── render.ts # 终端输出格式化 └── spinner.ts # 加载动画依赖控制在个位数zod做配置校验dotenv读环境变量commander做子命令解析picocolors给输出上色其他全部用 Node.js 原生能力。这里有个很重要的选型原则CLI 工具依赖越少越好。依赖多意味着安装慢、体积大、供应链风险高。能用原生 API 解决的绝不引包比如参数解析其实可以用node:util的parseArgs但commander的子命令帮助信息太方便了值得引入。而像 axios 这种纯 HTTP 库就没必要原生 fetch 已经足够。安装命令pnpm add zod dotenv commander picocolors pnpm add -D typescript tsx types/node2.2 配置管理与 API 密钥安全配置加载的顺序是默认值 环境变量 配置文件 命令行参数后面的覆盖前面的。实际实现时用zod定义一个完整的配置 Schemaimport { z } from zod; const ConfigSchema z.object({ apiKey: z.string().min(1, API Key 不能为空), baseURL: z.string().url(模型接口地址必须是合法 URL), model: z.string().min(1, 模型名称不能为空), systemPrompt: z.string().default(你是一个乐于助人的命令行助手。), temperature: z.number().min(0).max(2).default(0.7), maxTokens: z.number().positive().default(2048), sessionDir: z.string().default(.ai-cli/sessions), }); export type AppConfig z.infertypeof ConfigSchema;这里用z.infer把运行时校验的 Schema 直接推导成 TS 类型一套定义两个用途省掉了手写重复类型。apiKey从.env文件加载项目根目录放.env.example提交到 Git真实的.env写进.gitignore。这是前 12 天学到的最重要的安全习惯密钥类敏感信息绝不入库、绝不打日志、绝不通过命令行参数传入因为ps能直接看到。2.3 会话管理把上下文变成可持久化的数据多轮对话的上下文管理本质是把消息数组传进 API 再接收新消息但绝不能每次请求都带无限增长的历史。v1 的做法是用一个会话文件保存当前对话的所有消息每次发起新请求时拼接上下文窗口最内的 20 条消息大概是最近 8000 token超出部分直接丢弃。会话持久化的核心是一个很简单的SessionStoreexport class SessionStore { constructor(private dir: string) {} private pathOf(id: string): string { return join(this.dir, ${id}.json); } async save(id: string, messages: ChatMessage[]): Promisevoid { await mkdir(this.dir, { recursive: true }); await writeFile(this.pathOf(id), JSON.stringify(messages, null, 2), utf-8); } async load(id: string): PromiseChatMessage[] { try { const raw await readFile(this.pathOf(id), utf-8); return JSON.parse(raw) as ChatMessage[]; } catch { return []; } } }会话文件是纯 JSON好处是既能被程序读取也能让用户直接打开编辑——调 Prompt 或者删掉某条可疑消息都方便。这个设计思路跟前端本地存储一模一样只是把 localStorage 换成了文件系统。3. 核心功能实现与代码实战3.1 CLI 入口与子命令分发入口文件的核心逻辑是解析参数后分发到不同处理函数。commander帮我把ai ask 报错原因、ai check、ai clear这类命令快速搭好#!/usr/bin/env node import { Command } from commander; import { loadConfig } from ./config.js; import { ask } from ./commands/ask.js; import { check } from ./commands/check.js; import { clearSession } from ./commands/clear.js; const program new Command(); program .name(ai) .description(命令行 AI 助手 v1) .version(1.0.0); program .command(ask [question...]) .description(向 AI 提问支持流式输出) .option(-m, --model name, 临时切换模型) .option(-s, --session id, 指定会话 ID默认为 default) .action(async (question: string[], opts) { const config await loadConfig(); await ask({ config, question: question.join( ), sessionId: opts.session ?? default, modelOverride: opts.model, }); }); program .command(check) .description(检查当前配置是否可用) .action(async () { const config await loadConfig(); console.log(模型: ${config.model}); console.log(接口: ${config.baseURL}); console.log(会话目录: ${resolve(config.sessionDir)}); }); program .command(clear) .description(清空指定会话的上下文) .option(-s, --session id, 指定会话 ID) .action(async (opts) { await clearSession(opts.session ?? default); }); program.parse();注意到ask命令接收[question...]不定长参数这样ai ask 这段代码为什么会报错能自动把所有词拼成完整问题。前端思维在这里体现得很明显——把输入框从网页搬到命令行交互形态变了但输入处理的思路是共通的。3.2 流式输出与交互体验处理流式输出是 CLI 助手体验的关键。如果等大模型生成完 500 个字再一次性打印用户会怀疑程序卡死了。正确做法是边生成边打印还要处理几个交互细节输出前面加转圈的加载动画spinner首字到达时切掉 spinner输出过程中按CtrlC能中断生成中断后已经生成的内容要留在终端供用户阅读。核心的流式处理函数如下export async function streamChat( config: AppConfig, messages: ChatMessage[], onToken: (text: string) void, signal?: AbortSignal ): PromiseChatMessage { const resp await fetch(${config.baseURL}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${config.apiKey}, }, body: JSON.stringify({ model: config.model, messages, stream: true, temperature: config.temperature, max_tokens: config.maxTokens, }), signal, }); if (!resp.ok) { const errBody await resp.text(); throw new Error(API 请求失败 (${resp.status}): ${errBody.slice(0, 300)}); } if (!resp.body) { throw new Error(响应中没有数据流); } const reader resp.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; let fullContent ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop() ?? ; for (const line of lines) { const trimmed line.trim(); if (!trimmed.startsWith(data:)) continue; const payload trimmed.slice(5).trim(); if (payload [DONE]) continue; try { const json JSON.parse(payload); const token json.choices?.[0]?.delta?.content; if (token) { fullContent token; onToken(token); } } catch { // SSE 数据可能被拆到多行里解析失败就跳过等下一轮 continue; } } } return { role: assistant, content: fullContent }; }SSE 流式解析有个典型的坑网络包不会严格按照data:行来切割一个 JSON payload 可能被拆成两半也可能两个 data 挤在同一块。所以必须维护一个buffer变量先把拿到的字节解码成字符串再按换行符切分。这里我设置了decoder.decode(value, { stream: true })把多字节字符比如中文可能被拆包的情况也一并处理掉——这个细节我从前端处理分片上传里迁移过来的思路。3.3 工具调用让 AI 能执行 Shell 命令工具调用function calling是 v1 的技术含量担当。实现思路先把工具的描述用 JSON Schema 格式发给模型模型在生成过程中判断这时候需要调用某个工具返回一个特殊的 assistant 消息——里面带着工具名和参数。CLI 收到后执行真实函数把结果以tool角色的消息回传给模型模型再基于结果继续生成最终回答。工具定义和注册import { z } from zod; const ShellArgs z.object({ command: z.string().describe(要执行的 shell 命令), cwd: z.string().optional().describe(工作目录默认当前目录), }); const FileArgs z.object({ path: z.string().describe(文件绝对路径), }); const shellTool { name: run_shell, description: 执行任意 shell 命令并返回标准输出。适合查看目录、运行脚本、安装依赖等操作。, parameters: { type: object, properties: { command: { type: string, description: 要执行的 shell 命令 }, cwd: { type: string, description: 工作目录可选 }, }, required: [command], }, async execute(args: unknown) { const { command, cwd } ShellArgs.parse(args); const result await runCommand(command, cwd); return result; }, }; const fileTool { name: read_file, description: 读取指定文本文件的内容适合查看代码和配置文件。, parameters: { type: object, properties: { path: { type: string, description: 文件绝对路径 }, }, required: [path], }, async execute(args: unknown) { const { path } FileArgs.parse(args); return await readTextFile(path); }, }; export const toolRegistry new Map([ [shellTool.name, shellTool], [fileTool.name, fileTool], ]);执行 shell 命令用child_process的execFile而不是exec——execFile不会经过 shell 解释传参更安全。命令执行设 30 秒超时超时就杀掉进程并返回错误信息。工具调用循环的完整流程async function runWithTools(config, messages) { let currentMessages [...messages]; while (true) { const resp await fetch(${config.baseURL}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${config.apiKey}, }, body: JSON.stringify({ model: config.model, messages: currentMessages, tools: [...toolRegistry.values()].map(t ({ type: function, function: { name: t.name, description: t.description, parameters: t.parameters, }, })), tool_choice: auto, }), }); const data await resp.json(); const msg data.choices[0].message; currentMessages.push(msg); if (!msg.tool_calls?.length) { return msg.content; } for (const call of msg.tool_calls) { const tool toolRegistry.get(call.function.name); if (!tool) { currentMessages.push({ role: tool, tool_call_id: call.id, content: 未知工具: ${call.function.name}, }); continue; } try { const output await tool.execute(JSON.parse(call.function.arguments)); currentMessages.push({ role: tool, tool_call_id: call.id, content: typeof output string ? output : JSON.stringify(output), }); } catch (err) { currentMessages.push({ role: tool, tool_call_id: call.id, content: 工具执行失败: ${(err as Error).message}, }); } } } }为什么这个设计有价值因为它是 Agent 的雏形。模型不再只是聊天而是能根据用户的指令自主决定要不要执行命令、执行什么命令、读取什么文件。v1 只接了两个工具但架构上已经能无限扩展。以后想加搜索、加数据库查询、加调用其他 API只需要往 registry 里注册一个新工具主流程完全不用动。3.4 会话上下文与消息拼装上下文不仅是把 messages 数组原样传给 API那么简单。v1 里我做了三件事第一系统 Prompt 动态组装。默认 Prompt 里会注入当前目录、用户平台等信息让模型回答更贴合场景export function buildSystemPrompt(userPrompt: string): string { return [ userPrompt, , ## 运行环境, - 当前工作目录: ${process.cwd()}, - 平台: ${process.platform} (${process.arch}), - Node 版本: ${process.version}, , ## 回答要求, - 回答简洁直接优先给出可执行的命令或代码, - 如果使用工具基于工具结果回答不要臆测, - 涉及文件操作时推荐返回绝对路径, - 不确定的信息明确说不确定不要编造, ].join(\n); }第二上下文裁剪。每次请求前把 messages 截断到最近 20 条同时确保第一条 system 消息始终在。这个数字可以根据模型上下文窗口调整但对 v1 来说 20 条够用。第三自动生成会话标题。每次完成一轮对话后取用户的第一条消息的前 20 个字作为文件名标识。前端背景带来的一个小习惯——任何数据都要有可读性会话文件也不例外。4. 踩坑实录与问题排查4.1 流式输出的中文乱码与断行问题v1 的第一个严重 Bug 出在中文输出上。首次实测时发现回复里的中文经常出现这样的替换字符。排查过程是这样的先单独测 API 请求数据用curl直接看原始流没问题。再看 Node 侧的解析发现问题出在TextDecoder的使用上——我第一次写的代码是decoder.decode(value)没有传{ stream: true }。原因很底层UTF-8 编码下一个中文字符占 3 个字节网络传输时这 3 个字节可能被拆成两次read()的返回值。如果不告诉 decoder 这是流式数据它会认为每个 chunk 都是独立完整的编码序列遇到被拦腰截断的字符就直接报错替换。加上{ stream: true }后decoder 会把残缺的字节放在内部缓冲区里等下一个 chunk 到了再拼起来解码。避坑心得所有涉及流式文本处理的场景TextDecoder一定要用stream: true模式。这个问题在浏览器里很少遇到因为浏览器内置的流处理已经帮你包好了但 Node 端一切都要自己处理。4.2 Shell 工具执行的安全隐患与超时处理给模型开放 shell 执行权限是双刃剑。v1 里我做了三层防护。第一层是超时保护命令超过 30 秒直接kill防止模型生成一个死循环命令把用户终端卡住。第二层是输出截断工具返回内容超过 3000 字符就截断并追加提示避免大文件输出把上下文窗口撑爆。第三层是沙箱提示在系统 Prompt 里明确告知模型命令将在用户电脑上真实执行让它对危险操作提高警惕。实操中还有一个隐性问题execFile虽然有参数列表的安全优势但没法天然支持ls -la | grep xxx这种管道写法。v1 的折中方案是用execFile执行 shell 程序本身import { execFile } from node:child_process; import { promisify } from node:util; const execFileAsync promisify(execFile); export async function runCommand(command: string, cwd?: string) { const { stdout, stderr } await execFileAsync(/bin/sh, [-c, command], { cwd: cwd ?? process.cwd(), timeout: 30_000, maxBuffer: 1024 * 1024, env: { ...process.env, PATH: process.env.PATH ?? }, }); if (stderr) { return ${stdout}\n[stderr]\n${stderr}; } return stdout; }用/bin/sh -c相当于绕了一个圈还是经过了解释器安全和管道不能兼得v1 先保证功能可用后续再考虑白名单机制。4.3 中断交互与状态残留问题按CtrlC中断大模型生成这个功能实现起来比想象中复杂。最初的做法是直接监听SIGINT信号调用AbortController.abort()取消 fetch。但实测发现中断后终端进入了一种半死状态——按回车没反应输入不回显。原因是readline的接口在 fetch 中断后没有正确恢复。Node 的readline/promises接口在等待question()时如果底层的 stdin 被某种方式打断它会一直挂起。解决办法是在中断后手动关闭并重建 readline 实例同时把光标移到下一行、恢复 stdin 的 flow 模式function handleInterrupt() { // 取消当前请求 controller.abort(); // 恢复终端状态 rl.close(); process.stdin.resume(); // 重新创建交互接口 rl createInterface({ input: process.stdin, output: process.stdout }); }这类问题在浏览器里永远不会出现页面级事件循环帮你处理好了但 CLI 里每个 I/O 状态都要自己管理这也是这次项目最大的收获之一。4.4 跨平台兼容性速查表项目在 macOS 上开发放到 Windows 和 Linux 上各踩了几个坑。整理成表格供参考问题现象解决方案路径分隔符硬编码/导致 Windows 下路径错误统一用node:path的join()、resolve()Shell 路径直接写/bin/sh在 Windows 不存在用process.env.ComSpec或process.platform判断窗口尺寸process.stdout.columns在部分终端返回 undefined兜底默认值 80ANSI 颜色Windows 老终端不显示颜色picocolors自动检测必要时设FORCE_COLOR0文件编码Windows 下读 GBK 编码文件乱码默认按 UTF-8 读取读取失败时提示用户转编码跨平台问题不一定要在 v1 全部解决但至少要在 README 里写清楚当前支持到什么程度。我最后的选择是优先保证 macOS/Linux 的完整体验Windows 下保证核心功能可用。5. 测试与发布5.1 手工验证清单CLI 工具没有图形界面测试基本靠脚本和手工。我把核心链路列成一个验证清单每次改动后跑一遍# 1. 配置检查 ai check # 2. 基本问答流式输出 ai ask 用一句话解释什么是递归 # 3. 多轮上下文 ai ask 给我一段斐波那契的 TS 实现 ai ask 解释下刚才那段代码的时间复杂度 # 4. 工具调用 ai ask 当前目录下有哪些文件 ai ask 帮我读取 package.json 并总结依赖情况 # 5. 会话持久化 ai ask 记住我的名字叫小明 # 退出后重新进入 ai ask 我叫什么名字 # 6. 中断体验 ai ask 写一篇 5000 字的小说 # 生成过程中按 CtrlC # 7. 清空会话 ai clear这 7 条基本覆盖了所有核心功能。实测中第 4 条最容易暴露问题——工具调用链路涉及模型判断→参数解析→执行→回传→二次生成五个环节任何一个环节出错都会导致回答质量下降。5.2 打包与全局安装为了让ai命令在终端里全局可用package.json 里设置bin字段然后打包发布{ name: yourname/ai-cli, version: 1.0.0, bin: { ai: ./dist/index.js }, files: [dist], scripts: { dev: tsx src/index.ts, build: tsc, prepublishOnly: npm run build } }本地测试时用npm link或pnpm link --global把命令链接到全局这样直接输入ai就能唤起。注意入口文件第一行必须要有#!/usr/bin/env node的 shebang否则安装后执行会报错。发布到 npm 之前建议先npm pack --dry-run看看包里包含哪些文件files字段要明确只发dist目录避免把源码和测试文件都打进去。v1 阶段其实不急着发布到公共仓库本地 link 完全够用等 100 天计划走到后期再考虑发布会更成熟。6. 复盘与后续迭代方向Day 13 这个项目做完一个很明显的感受是前端转 AI 并不是要丢掉前端而是把前端的工程化思维带去新的领域。CLI 项目的模块拆分、类型设计、状态管理、错误处理、用户体验打磨每一层都受益于我过去写 React/Vue 时积累的习惯。v1 的架构上留好了几个扩展位后续 100 天计划里我会优先做这些方向增加更多工具基于 registry 的模式加入 Web 搜索、执行 SQL、调用内部 API让它从一个问答助手进化成真正的 Agent。支持多会话切换现在只有 default 会话 ID后续支持列出会话、命名会话、按会话继续对话。交互增强增加 markdown 渲染终端里的代码高亮、表格对齐、类似fzf的模糊搜索快捷键。接入本地知识库把常用项目的 README、文档片段向量化工具调用时先检索再回答。最后分享一个我这次项目里学到的非常实用的技巧调试 CLI 工具时在代码里加一个DEBUGai-cli*的环境变量判断只有打开调试开关时才打印内部日志API 请求体、上下文消息数、工具调用详情。正常使用时终端保持干净遇到问题打开 DEBUG 又能看到全部细节。这个习惯让排障效率至少提高一倍。