企业官网建设流程全解析

前端转 AI 一百天计划进行到第 13 天，我决定不再学新知识了，而是做点正经事——把前 12 天学的东西，全部塞进一个能跑的终端工具里。这个工具就是一个命令行 AI 助手：在终端敲一句ai "帮我写一个快速排序"，它调用大模型把答案逐字打出来；输入ai chat，可以和它连续聊好几轮；还能用参数指定模型和角色。没有网页 UI，没有数据库，没有复杂部署，只有最朴素的黑底白字终端，和一个完整的 AI 应用开发链路。

前 12 天我学了 Node.js 异步、HTTP 与 API 调用、Prompt 工程、SSE 流式协议、环境变量管理……这些东西单独拿出来每一个都不算难，但它们就像一堆散落的零件。今天这个综合项目，就是把这些零件拧成一个能用的产品。这篇文章我打算把整个项目的设计思路、核心代码、搭建过程和踩坑记录都摊开讲，希望能给正在走"前端转 AI"这条路的同行一个可直接参考的样板。

1. 项目定位：为什么第一个综合项目选"命令行 AI 助手"

1.1 完成一个"能交付"的项目，比再学十个 API 更重要

很多前端转 AI 的同行会有一个迷思：觉得自己 Python 没学透、算法没背熟、深度学习框架还没摸过，就不敢动手做 AI 项目。我前 12 天也差不多是这个状态，越学越虚，总觉得自己还差点火候。但 Day 13 我想明白一件事：AI 应用开发的门槛，远没有想象中那么高。你不需要自己训练模型，你只需要学会"如何正确地调用一个已经训练好的模型，并把它的能力整合进自己的产品里"。这是一道填空题，而不是证明题。

所以要迈出第一步，关键是选一个"够得着"的项目。命令行 AI 助手的完成度可控之处在于：它只有一块核心业务逻辑（模型调用），没有数据库、没有前端界面、没有复杂的部署流程。一天之内做一个 v1 版本是完全可行的，不会有做到一半烂尾的风险。而且这个工具的实用价值是实打实的——我自己日常写代码就经常切到终端查资料，遇到想不起的 API 用法，直接问一句总比开浏览器翻文档快。做完之后它还能变成一个简历上能演示的实战案例，面试官问"你凭什么觉得自己能转 AI"，我不用空谈热情，直接现场跑一遍工具给他看，比说十句都管用。

1.2 前端选手为什么用 Node.js 而不是 Python

这里先回答一个一定会被问的问题：AI 生态不是 Python 的天下吗，你一个前端转 AI 的，为什么用 Node.js 写？我的理由其实特别朴素：第一个综合项目，目的是把 AI 开发的核心链路打通，而不是再学一门新语言。我前端背景最熟的就是 JavaScript，用 Node.js 可以把学习摩擦降到最低。既然目标是把这 12 天学的 AI 知识串起来，那就别再让自己卡在语法上。

技术上的底气在于：Node.js 18 开始内置了 fetch，我连 axios 都不用装；流式读取有 Web Streams API；readline 模块可以直接做交互。真正必须依赖第三方库的只有两件事：读 .env 环境变量（用 dotenv）和输出终端颜色（用 chalk，不加也行）。我也认真对比过 Python 方案：写起来确实更短，但用它的代价是同时要处理 Python 环境、pip 依赖和异步模型的差异，这对前端开发者来说是一堆额外负担。结论很明确：第一个项目用 Node.js 拿下，Python 可以等真正需要的时候再补。工具只是手段，核心是那一整套 API 调用、流式解析、上下文管理的通用能力，换语言只是换一层皮。

2. 整体架构：从需求到代码模块的拆解

2.1 v1 规划了四个核心能力

动手写代码之前，我先把 v1 的能力边界画了出来。做综合项目最忌讳需求膨胀，所以我给自己定了四条硬规矩，每个功能都必须能回答"用户什么时候会用到它"。

这四件事覆盖了一个命令行 AI 助手的最小可用闭环。没做的功能包括：联网搜索、多模态输入、本地记忆持久化、多轮会话并行——这些我全部砍掉了，统一留给 v2/v3。砍需求本身也是一种设计。比如"记忆持久化"是个看起来很酷但是很容易把复杂度无限拉高的功能：一旦要存历史，就要考虑存储格式、会话 id、清空策略……v1 阶段先让历史消息只存活在内存里，退出即清空，这完全够用。真正的产品设计不是不停做加法，而是在合适的阶段做减法。

2.2 模块划分与数据流

代码组织比我想象的更重要。很多人写命令行工具喜欢把所有逻辑堆在一个文件里，我这次刻意拆成了四个模块，每个模块只负责一件事。这样做的直接好处是调试简单：出问题了能立刻判断是参数解析的锅、网络请求的锅还是渲染的锅。

ai-cli/ ├── bin/ │ └── ai.js // 入口：参数解析和命令分发 ├── lib/ │ ├── cli.js // 手动实现的参数解析器 │ ├── config.js // 读取 .env 环境变量 │ ├── llm.js // 大模型 API 调用（含流式解析） │ ├── chat.js // 交互式多轮对话循环 │ └── handler.js // 单次问答与交互模式的统一入口 ├── .env // 密钥配置（不提交到仓库） └── package.json

数据流其实特别直白：终端输入 → 解析出选项和内容 → 拼装成 messages 数组 → 交给 llm.js 发起请求 → 通过 SSE 拿到增量片段 → 逐字打印到终端。如果是 chat 模式，再多维护一个历史消息列表，每轮结束后把 assistant 的回复追加进去，下一轮请求时把整个历史一起带上。这个链路不复杂，但它是所有 AI 应用的地基——网页聊天、IDE 插件、自动化脚本，底层都是同一套东西。

2.3 这样拆的好处在哪里

如果只是想要一个能跑的东西，根本不需要拆模块。但我是把这次项目当成一个"未来要长大的产品"来写的——后面加 Function Calling（让模型能调用外部工具）、加多模型路由、加上下文压缩，都是往模块里加代码，而不是推倒重来。一个清晰的模块边界，能让每一次迭代都只动该动的地方。比如 v2 我要加多模型路由，只需要改 cli.js 的参数解析和 handler.js 的分发逻辑，llm.js 里的网络请求和流式解析一动都不用动。这个思路一开始就定好，能少走很多弯路。

3. 核心实现：参数解析、流式输出与上下文管理的完整代码

3.1 参数解析：自己动手，不引 commander

一开始我也想引入 commander 这个成熟的命令行框架，毕竟它处理子命令、参数、帮助文档都很顺手。但想了想：整个工具只有两三个参数和两个子命令，引一个框架反而把学习重心带偏了。手动解析虽然土，但能让我彻底理解"命令行参数"的本质——它不过就是 process.argv 里的一段字符串数组，你定义规则，它就能被解析成结构化配置。

// bin/ai.js #!/usr/bin/env node import { parseArgs } from '../lib/cli.js'; import { runOnce, runChat } from '../lib/handler.js'; import { config } from '../lib/config.js'; const argv = process.argv.slice(2); const options = parseArgs(argv); if (options.help) { console.log(` 用法: ai "问题" 单次提问 ai chat 进入多轮对话模式 ai -m <模型> "问题" 指定模型提问 ai -s "系统角色" "问题" 指定系统提示词 `); process.exit(0); } if (options.version) { console.log('ai-cli v1.0.0'); process.exit(0); } if (!config.apiKey) { console.error('缺少 LLM_API_KEY，请在 .env 中配置'); process.exit(1); } if (options.interactive) { await runChat(options); } else { await runOnce(options); }

// lib/cli.js export function parseArgs(argv) { const options = { model: process.env.LLM_MODEL || 'gpt-4o-mini', system: '你是一个乐于助人的命令行 AI 助手。回答要简洁、准确、直接。', stream: true, interactive: false, help: false, version: false, prompt: '' }; const rest = []; for (let i = 0; i < argv.length; i++) { const arg = argv[i]; if (arg === '--help' || arg === '-h') { options.help = true; } else if (arg === '--version' || arg === '-v') { options.version = true; } else if (arg === '--model' || arg === '-m') { options.model = argv[++i]; if (!options.model) throw new Error('--model 后面需要跟模型名'); } else if (arg === '--system' || arg === '-s') { options.system = argv[++i]; if (!options.system) throw new Error('--system 后面需要跟角色描述'); } else if (arg === '--no-stream') { options.stream = false; } else if (arg === 'chat') { options.interactive = true; } else { rest.push(arg); } } options.prompt = rest.join(' ').trim(); return options; }

这里有两个细节值得展开。第一，options.prompt = rest.join(' ')这行，是把所有非参数的内容拼起来作为提示词。这样用户偶尔不加引号直接ai 你好 世界也能工作，天然做了一层容错；第二，--system和--model是成对出现的，取值取的是下一个参数，所以必须做越界保护——如果用户只敲了ai -m后面什么都没跟，程序不能直接抛出一个让人摸不着头脑的 TypeError，而是报一句清晰的错误。

3.2 大模型调用与流式输出：SSE 解析是核心中的核心

接下来是重头戏——真正向大模型发起请求。我用的方式是直接 fetch 到/chat/completions接口，这是当前所有 OpenAI 兼容服务的事实标准。请求头带 Content-Type 和 Authorization，body 里传模型名和消息数组。请求本身不复杂，复杂的是流式响应。

当stream: true时，响应 body 不再是完整 JSON，而是一个 SSE（Server-Sent Events）流。每个数据块以data:开头，中间是 JSON 片段，结束标记是[DONE]。解析思路：按换行符切行，每行去掉data:前缀；遇到[DONE]就结束；其余行尝试 JSON.parse，取choices[0].delta.content，把这个片段直接写进终端。这其实就是 ChatGPT 网页版打字机效果的底层原理。

// lib/llm.js import { config } from './config.js'; export async function chatCompletion(messages, { model, stream = true }) { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 60_000); try { const response = await fetch(`${config.baseUrl}/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${config.apiKey}` }, body: JSON.stringify({ model, messages, stream }), signal: controller.signal }); if (!response.ok) { const text = await response.text(); throw new Error(`API 请求失败（${response.status}）：${text}`); } if (!stream) { const data = await response.json(); return data.choices[0].message.content; } return await streamResponse(response); } finally { clearTimeout(timer); } } async function streamResponse(response) { const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; let result = ''; 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 data = trimmed.slice(5).trim(); if (data === '[DONE]') continue; try { const json = JSON.parse(data); const delta = json.choices?.[0]?.delta?.content; if (delta) { result += delta; process.stdout.write(delta); } } catch { // 半行数据直接忽略，等下一块补全 } } } process.stdout.write('\n'); return result; }

这段代码里有两个非常关键的细节，值得反复强调。第一个是decoder.decode(value, { stream: true })里的stream: true参数——这是解决中文乱码的关键。流式返回的数据块可能把一个汉字拆成两半，比如"你"字的 UTF-8 编码被切到了两个 chunk 里，TextDecoder 在流式模式下会缓存不完整的字节，等下一块数据到了再一起解码。如果这里不用 stream 模式，大概率会遇到"最后一个字是乱码"的诡异问题。

第二个是const lines = buffer.split('\n'); buffer = lines.pop();这两行。网络包不保证按行切分，可能一个包里有好几行，也可能一行被拆到两个包里。我的处理是先把已有的 buffer 按换行符切分，把最后一个可能不完整的片段存回 buffer，只处理前面完整的行。这个模式是 SSE 解析的标准姿势，第一次写的时候容易漏掉，漏掉就会出现内容偶尔卡住、偶尔少一截的情况。

3.3 多轮对话：上下文管理其实是个"记忆游戏"

单轮问答做通之后，ai chat模式的核心就是历史消息管理。大模型接口本身没有记忆，所谓多轮对话，本质上就是每次请求把所有历史消息重新发一遍。正确的做法是维护一个 messages 数组，把 system、user、assistant 三种消息按顺序排列，请求时整个数组一起提交。

// lib/chat.js import readline from 'readline'; import { chatCompletion } from './llm.js'; const MAX_MESSAGES = 20; export async function runChat(options) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: '你 > ' }); const messages = [{ role: 'system', content: options.system }]; console.log('进入多轮对话模式，输入 exit 或 :q 退出。\n'); rl.prompt(); rl.on('line', async (line) => { const input = line.trim(); if (!input) return; if (['exit', 'quit', ':q'].includes(input)) { rl.close(); return; } messages.push({ role: 'user', content: input }); process.stdout.write('AI > '); try { const reply = await chatCompletion(messages, { model: options.model, stream: options.stream }); messages.push({ role: 'assistant', content: reply }); trimHistory(messages); } catch (err) { console.error(`\n请求失败：${err.message}`); messages.pop(); } rl.prompt(); }); rl.on('close', () => { console.log('\n再见，本次会话记录已清除。'); process.exit(0); }); } function trimHistory(messages) { while (messages.length > MAX_MESSAGES) { messages.splice(1, 2); } }

为什么要把历史上限设为 20 条？因为上下文窗口和成本都是现实约束。一条历史按 100 到 200 token 估算，20 条历史加上 system prompt 和当前问题，也就 2000 到 4000 token，绝大多数模型都能轻松容纳。这里我用的策略是粗暴的滑动窗口——超出上限就从头删掉最早的一组 user/assistant。更优雅的方案是让模型对旧历史做摘要压缩，但那是 v2 的事了。

这里还有一个容易踩坑的点：请求失败时一定要把刚 push 进去的那条 user 消息弹出来（代码里的messages.pop()），否则下一次重试会把失败的这条重复计入，上下文越来越脏，钱也越花越多。这个小细节是我实际调试了三次才想明白的，否则你会在日志里看到同一句话被模型反复强调"你说过好几次了"。

4. 搭建实录：从空目录到全局ai命令

4.1 环境准备：三步走完

具体环境准备真的不复杂。第一步，确认 Node.js 版本，因为这个项目用到了内置 fetch 和 Web Streams API，Node 必须大于等于 18。用node -v看一眼版本，我这边是 v20，跑起来没有任何问题。如果你是更老的 Node 版本，建议先升级到 LTS。第二步，初始化项目：npm init -y生成 package.json，然后把type: "module"加上，这样就能直接用 import 语法，不用再折腾 CommonJS。

{ "name": "ai-cli", "version": "1.0.0", "type": "module", "bin": { "ai": "./bin/ai.js" } }

第三步，创建 .env 文件。我在里面放了三项配置，每一项的含义我在代码里都做了注释。注意 .env 必须写进 .gitignore，这个文件里是密钥，提交到公开仓库等于把账号拱手送人。我在项目里还加了启动时的校验：如果没读到 LLM_API_KEY 就直接报错退出，而不是带着空 key 去发请求拿一个 401 回来，白白浪费几秒钟调试时间。

LLM_API_KEY=你的密钥 LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-4o-mini

4.2 开发顺序与核心联调

这个项目我严格按"先单后多、先直后流、先命令后交互"的顺序开发。第一步做的是参数解析和ai "一句话问题"主流程，先用非流式把接口整个跑通。看到终端打出完整回答的那一刻，整个链路就已经成立了一半。第二步把 stream 改成 true，实现逐字打印。这一步的逻辑变化不大，但体验提升非常明显——回答不是等十几秒后才突然蹦出来，而是像打字机一样实时生成。实测下来，同样一个问题，心理上的等待时间至少缩短一半。

第三步才是加ai chat交互模式。交互模式本质上是对单次问答的复用，历史数组加 readline 循环，半小时就写完了。最后我在 system prompt 里换了几种角色实测：让它扮演"资深前端面试官"出题、扮演"代码审查员"审一段 JavaScript、扮演"翻译官"翻译文档，效果都符合预期，而且前面几轮对话的上下文能正确影响后续回答。整个 v1 从空目录到全局命令生效，一个下午的时间，完全可控。

5. 踩坑记录：高频问题与两个 Bug 复盘

5.1 高频问题速查表

开发过程中我遇到了不少坑，整理成一张速查表，如果你也在搭类似工具，可以直接对着查。

表格里列的问题大部分都集中在两类：一类是网络层，一类是编解码层。网络层的解法就是重试、超时、退避；编解码层的解法就是理解字节和字符的关系，别让半截数据流直接进了解析器。

5.2 两个印象深刻的 Bug 复盘

第一个 Bug 是流式输出"假死"。现象是：回答内容会突然停住，过一会又继续，终端看起来像卡死了。查了半天发现是 SSE 解析时积攒了大量半行数据没触发输出。原因是我把 buffer 的重新切分逻辑写在了for循环外面，导致每次只处理了第一行，剩下的行全部留在缓存里，下一轮循环又覆盖了它们。修复的方式就是前面代码里写的那样，每次循环都要重新切分 buffer，而不是只在循环外切一次。

第二个 Bug 是中文提示词被 shell 吃掉。有次我敲ai 请问二分查找怎么写，结果模型返回的答案牛头不对马嘴，仔细一问才发现它收到的是残缺的字符串。排查下来发现：没加引号时，shell 会把空格当成参数分隔符，程序收到的 argv 被拆成了['请问二分查找怎么写']前面那部分直接丢了。这算不上代码 bug，但却是命令行工具真正上线后最常见的用户困惑。后来我在帮助信息里加了一行提示："建议始终用双引号包住提示词"，这个问题才基本消失。

5.3 体验优化心得

v1 做完之后，我顺手做了几个小的体验优化，成本很低但收益实在。第一个是超时控制。大模型接口有时候真的会很慢，我在 fetch 外层套了 AbortController，设了 60 秒超时。没有这个设置，网络层异常可能让终端挂几分钟没反应。第二个是退出路径。ai chat里用 readline 监听 line 事件，用户输入 exit、quit 或者 :q 都能优雅退出，并且退出时打印一句提示，告诉他本次会话记录已清除。这个细节看起来不起眼，但命令行工具如果连退出都做不好，用户会很烦躁。

第三个是对请求失败的用户体验处理。一旦流式中途报错，我会打印错误信息并结束本轮，但程序本身不崩溃，用户还能继续提问。这是 CLI 工具和网页应用的差异：网页里报错可以刷页面，终端里报错要是把进程带崩，之前的会话就全丢了。做工具类产品，稳定性和可恢复性永远比新功能优先。

最后说说我个人做完这个项目最深的体会。前 12 天学的那些零散知识——fetch 的用法、异步流的处理、SSE 协议、Prompt 设计——单独拿出来每一个都不难，但它们之间是如何协同工作的，不亲手把它们拼成一个能跑的产品，是永远理解不了第二层的。这个命令行 AI 助手本质上已经是一个极简的 AI Agent 雏形：有输入、有模型调用、有上下文管理，唯一缺的是"工具"——让模型可以主动执行代码、查文件、调接口的能力。

所以我的 Day 14 计划很明确：在这个 v1 基础上接上 Function Calling，让 AI 助手不只是回答问题，还能替我把事情做掉。按照我目前的模块拆分，这个扩展只需要动 handler.js 和 llm.js，其他代码完全不用改。你也想从零搭一个的话，可以先按这个四步走：定边界、画架构、跑通主链路、补异常处理。做完之后你会发现，前端转 AI 最难的那道坎，其实已经在不知不觉中迈过去了。