前言

写给前端工程师的 CLI 课

我做了十年前端，能写出像样的 React 组件，能调通 Webpack，能在 PR 评论里和后端同事辩论接口设计。但很长一段时间里，凡是和命令行打交道的环节都是我的盲区。npm publish 报错我只会复制错误信息去搜，gh 命令我只会跟着教程敲，更别提自己从零写一个能被同事天天用的 CLI 工具。

直到 2024 年下半年，Claude Code 出现了。我第一次在终端里看到 AI 像一个真正的程序员那样工作——读文件、改代码、跑测试、提 commit。它不带任何 GUI，只有一个 REPL，但完成的任务比我之前用过的任何 IDE 插件都更深。

我开始反思：为什么 AI 编程工具不约而同地选了 CLI？为什么 Cursor、Windsurf 这些 IDE 形态的产品反而被 Claude Code、Codex CLI、Gemini CLI 追平甚至反超？

想明白这个问题之后，我决定写一本书，把 CLI 工具开发这件事，专门讲给前端工程师听。

为什么这本书面向前端工程师

我猜你符合下面几条中的一两条：

写前端三年以上，TypeScript 写得很顺，但没有正经写过 CLI 工具
用过 Vue CLI、Create React App、Vite，知道它们好用，但不知道这些工具内部是怎么组织起来的
想做点跟 AI 相关的东西，但不知道入口在哪
看过 Claude Code 之类的工具，觉得它的工作方式很妙，想自己复刻一个

如果你是 Node.js 后端工程师，这本书对你也成立，只是某些前端的类比可以跳过。如果你完全没写过 JavaScript/TypeScript，这本书会比较吃力，建议先补齐这块。

我不假设你懂任何 CLI 框架，不假设你熟悉 OAuth，不假设你接过大模型 API。这些都会在书里从头讲。

这本书干什么、不干什么

这本书做的事：从零写一个叫 repox 的 AI 仓库助手。一个真实的、能用的、可以发到 npm 上的命令行工具。书里的每一章对应 repox 的一个真实功能：

命令设计、参数解析、子命令组合
交互式提示、进度条、彩色输出
配置文件的多层覆盖
GitHub OAuth 登录与 token 管理
接入大模型，把 LLM 当作 CLI 的一个工具
AI Agent 模式：让 CLI 自主完成多步任务
插件系统、错误处理、测试、发布

每一章后面都有可运行的代码，所有代码片段都对应到 repox 仓库里的真实文件。读完整本书你会同时拥有两个东西：repox 这个工具，以及把它做出来的全部技能栈。

这本书不做的事：

不讲 Bash 脚本编程。这是另一本书的话题
不讲 Rust/Go 的 CLI 开发。技术栈固定在 Node.js + TypeScript
不当 AI 入门书。涉及 LLM 的章节会简要介绍调用方式，但不会从注意力机制讲起。需要这部分背景的读者，请先看 Transformer 工程实战
不是 Claude Code 源码解读。书里会引用它作为对照，但不做逐行拆解。需要那个，请看自己动手写 AI Agent

阅读路线

全书 14 章 + 3 个附录，分五个部分：

第一部分（第 1-4 章）基础篇——把命令、交互、输出这三件基础事情搞定。这部分是后面所有内容的地基，建议顺序读。

第二部分（第 5-7 章）核心篇——配置、鉴权、网络请求，CLI 工具的三块硬骨头。

第三部分（第 8-9 章）AI 篇——从把 LLM 当 API 调用，到让 CLI 自主完成多步任务。AI Agent 那一章是全书的转折点，前面所有内容都是为它做铺垫。

第四部分（第 10-11 章）工程篇——错误处理、调试、测试、发布。把玩具变成生产工具靠的就是这部分。

第五部分（第 12-14 章）进阶篇——插件系统、Ink 组件化 UI、CLI 作为 AI 基础设施（MCP）。第 14 章会回到本书开头的那个问题：CLI 凭什么在 AI 时代再次成为主角。

附录是 CLI 开发的实用速查表、从 Claude Code 源码里总结的设计模式、CLI 设计 Checklist。可以在动手做项目的时候反复翻。

关于源码

repox 是一个真实的开源项目，仓库在配套的 GitHub 地址。每一章引用的代码都标了文件路径和行号，建议把仓库 clone 下来，对照着读。书里的版本基于某个稳定分支，源码后续会继续演进——这是好事，意味着你能看到一个 CLI 工具在生产中是如何成长的。

CLI 工具的内核没那么容易过时。Commander.js 的命令注册方式十年前就定型了，inquirer 的交互模型在 Node 社区是事实标准。AI 接入层会随着模型演进而变化，但调用一个 API 的工程姿势——超时、重试、流式、错误分类——这些是稳定的。

一个小提醒

写一个 CLI 工具不难。写一个用户愿意每天打开的 CLI 工具，难。这中间的差距就是这本书想填的——大量看似琐碎、但能决定工具体验的细节：错误信息怎么写才让人不骂街、Ctrl-C 怎么处理才不留下脏数据、首次运行的 onboarding 怎么做才不劝退用户、加载状态怎么显示才让人觉得程序还活着。

这些东西在文档里很少被认真讲。它们的好坏，决定了你写的工具是被收藏到 README 里然后忘掉，还是被同事偷偷加到自己的 .zshrc 里。

开始吧。