本篇回答四个问题它到底是个什么东西它有几种露面方式它靠什么技术跑起来它的几千个文件是怎么摆放的1.1 它到底是个什么东西一个住在终端里、会自己动手改代码的 AI先说一个最常见的误解很多人以为 AI 编程助手就是一个更聪明的聊天机器人你问它代码怎么写它把代码贴给你你自己复制过去。不是。它更像一个坐在你电脑前的实习生只不过这个实习生能听懂你说的话“帮我把这个 bug 修了”自己会去看文件、搜代码、跑命令不用你把代码喂给它看完之后直接动手改改完还能自己跑测试验证遇到拿不准的事比如要删文件会回头问你一句。所以它和聊天机器人有一个本质区别聊天机器人只会输出文字它能输出动作。打个比方。普通聊天机器人像一个顾问你问他答动嘴不动手。而它像一个有钥匙的钟点工你说把厨房收拾一下他会自己打开柜门、找到脏碗、洗掉、放回原处——你只需要在他要动你保险柜的时候喊停。那动手这件事在程序里是怎么实现的答案很朴素它能做的每一个动作都被写成了一个工具你可以理解成一个函数读文件是一个工具、改文件是一个工具、跑终端命令是一个工具。AI 每次想做事就说一句我要调用’读文件’工具参数是这个路径程序收到后真的去读再把结果喂回给 AI。你说帮我看看这个报错 ↓ AI我要调用「跑命令」工具执行 npm test ↓ 程序真的跑了 npm test把报错文字拿回来 ↓ AI我要调用「读文件」工具读 src/auth.ts ↓ 程序真的读了文件把内容拿回来 ↓ AI我要调用「改文件」工具把第 42 行的 改成 ↓ 程序真的改了 ↓ AI修好了原因是……你看到的回答这个AI 说要做什么 → 程序真的去做 → 把结果还回去的转圈就是整个产品最核心的机制第 3 篇会专门拆开讲。还有一个关键点AI 本身是远程的。真正在思考的那个大模型运行在别人家公司的服务器上通过网络调用。你电脑上运行的这个程序本质上是一个大管家负责把你的话、你的文件、你的环境信息打包发给远端的大脑再把大脑的指令翻译成本地动作。这个大管家做得好不好决定了产品好不好用——大脑各家都差不多管家才是分水岭。1.2 它的四种露面方式终端对话、被程序调用、被编辑器调用、被手机远程指挥同一个大管家内核穿了四件不同的外套应付四种场合。第一种终端里的对话窗口最主要的形态你在命令行敲一个命令进入一个全屏的对话界面上面是聊天记录下面是输入框能显示彩色的代码改动、待办清单、转圈的加载动画。这是给人直接用的形态也是功能最全的形态。本书大部分篇幅讲的都是它。第二种被别的程序调用它不只是给人用的也可以被别的程序当成零件装进去。比如你写了一个自动化脚本想让 AI 在脚本里帮你分析日志你可以用代码的方式调用它传入一句话它返回结果全程不出现任何界面。打个比方第一种形态像去饭店堂食你和服务员面对面第二种像外卖中央厨房别的 App 下单厨房做好递出去顾客根本看不到厨房。第三种被编辑器调用像 Zed、Cursor 这类代码编辑器可以通过一套标准的对话规矩一套双方都遵守的消息格式来指挥它。编辑器负责显示界面、处理你的点击它负责思考和干活。好处是编辑器厂商不用自己造一个 AI 助手只要按规矩发消息就行而它也不用为每个编辑器单独做适配。这就像电器和插座的关系不管是台灯还是电脑只要插头符合标准插上就能用电。它是电编辑器是电器那套对话规矩就是插座标准。第四种被手机远程指挥你出门在外用手机发一句话帮我把 CI 挂了的那个测试修一下家里电脑上的它收到后真的开始干活过程和结果实时传回手机遇到要删文件这种事手机上会弹个确认框你点同意它才敢动手。技术上这是在本地跑了一个小小的收发室程序手机连着它它再指挥本地的管家内核。四种形态看起来差别很大但内核是同一套都是收到一句话 → 转圈思考和干活 → 把结果回传。区别只在于这句话从哪来、结果送到哪去、确认弹窗弹给谁。把同一套内核塞进不同外壳是这个项目架构上最重要的一个决定——后面讲到第 3 篇和第 7 篇时你会反复体会到它的好处。1.3 它靠什么跑起来为什么选了这几门技术一个程序用什么语言、什么框架写本来是私事但这个项目的选型很有特点而且每个选择都直接影响了它为什么长这样所以值得花一章讲。运行时Bun一个又快又新的 JavaScript 运行环境写这个程序用的是 JavaScript/TypeScript 这门语言。JavaScript traditionally 是跑在浏览器里的后来有人把它搬到服务器上跑Node.jsBun 就是这类让 JavaScript 跑出浏览器的环境里最新、最快的一个。为什么选它三个现实原因AI 生态几乎都在 JavaScript 这边。大模型的官方开发工具包、终端界面库、各种插件JavaScript 版本最全最成熟。启动快。这种工具是敲一次命令、用一次、退出的程序每次启动都要重新加载自己。启动慢 0.5 秒用户每天就会多等几十秒。Bun 启动特别快。自带打包能力。它能直接把几千个源码文件打成可发布的产物还支持打包时就把用不到的代码删掉这个能力对第 11 篇要讲的功能开关机制至关重要。界面React做网页的那套技术 一个自研的终端界面库这是最有意思的选择。终端本来只能显示文字做界面 traditionally 是往屏幕上打印字符这种很原始的方式界面一复杂就很难维护。这个项目的做法是用做网页的思路做终端界面。React 是做网页界面最流行的框架它的核心思想是你只管用代码描述界面应该长什么样数据一变框架自动帮你把界面更新成新样子不用你手动去改屏幕上的字。但 React 默认只会渲染到网页上不认识终端。所以项目自己造了一个翻译层把 React 描述的界面翻译成终端能懂的字符和控制指令光标移到哪、用什么颜色、清掉哪一行。这个翻译层是整个项目里技术难度最高的部分之一第 6 篇会专门讲。打个比方普通终端程序像手绘黑板报改一个字都要自己擦自己画用 React 的方式像做幻灯片你只管写内容和排版规则换内容时幻灯片自动重排。语言TypeScript带类型的 JavaScriptJavaScript 写小程序很爽写几万行的大项目就容易乱你不知道一个变量里装的是字符串还是对象传错了要等运行起来才报错。TypeScript 给 JavaScript 加了类型相当于给每个数据贴标签“这个是字符串”“这个是包含 name 和 age 两个字段的对象”写错了在写代码的时候就提醒你。这种几十万个文件的大项目没有类型约束根本不敢改。一句话总结这一节Bun 负责跑得快、启动快TypeScript 负责大项目不出错React 负责复杂界面好维护自研翻译层负责把网页界面搬进终端。1.4 代码仓库导览几千个文件是怎么分门别类的最后带你在门口看一眼这栋大楼的平面图后面每一篇都会说这在大楼的哪个房间。整个项目分两大块主程序和独立小包。主程序的src/目录可以理解为主楼最重要的几个房间src/ ├── entrypoints/ ← 大门程序从这里启动 ├── main.tsx ← 总服务台所有命令行参数在这里登记 ├── query.ts ← 核心车间一问一答的转圈就在这 ├── QueryEngine.ts ← 车间调度安排一场长对话怎么跑 ├── Tool.ts ← 工具说明书一个工具长什么样的规定 ├── tools.ts ← 工具库房登记处一共发了哪些工具 ├── screens/ ← 门面终端里你看到的那些画面 ├── components/ ← 门面零件消息气泡、输入框、加载动画 ├── commands/ ← 服务区四十多个 / 开头的斜杠命令 ├── services/ ← 外联部对接大模型、对接外部工具等 │ ├── api/ ← 对接各家 AI 模型 │ ├── mcp/ ← 对接外部能力GitHub、数据库之类 │ └── acp/ ← 对接编辑器 ├── bridge/ ← 收发室手机远程控制走这里 ├── memdir/ ← 档案室AI 的长期记忆 ├── daemon/ ← 值夜班的门房关掉终端还在后台干活 ├── buddy/、modes/ ← 小角色陪伴助手、各种工作模式 └── utils/ ← 杂物间几百个各干各的小工具函数独立小包的packages/目录可以理解为院子里的独立车间。这些是可以单独拿出去用的零件各自有独立的身份证各自的 package.jsonpackages/ ├── ant/ink/ ← 那个自研的终端界面库第 6 篇的主角 ├── ant/model-provider/ ← 对接各家 AI 模型的适配层第 7 篇讲 ├── builtin-tools/ ← 六十多个内置工具的实现第 4 篇讲 ├── acp-link/ ← 编辑器对接的代理程序 └── 还有音频采集、电脑控制等十几个小包为什么要把有些东西拆成独立小包两个好处一是边界清楚比如终端界面库完全不知道AI“对话这些概念它只管把界面画到终端上”可以单独测试、单独复用二是按需加载用不到的小包比如电脑控制平时根本不会被搬进内存。还有一个贯穿全书的词你先记住功能开关feature flag。项目里有很多实验性功能它们的代码虽然写在仓库里但发布时可以被一键摘掉普通用户拿到的程序里根本没有这些代码。就像杂志排版时编辑可以决定某篇文章这期发不发——不发的话印刷厂直接不印而不是印了再涂黑。第 11 篇会讲它怎么做到的。本篇小结它不是聊天机器人是一个能动手的管家AI 出脑子程序出手工具就是手。同一套内核有四种外套终端对话、被程序调用、被编辑器调用、被手机远程指挥。技术选型各有任务Bun 快、TypeScript 稳、React 让界面好维护、自研库把网页界面搬进终端。代码分主楼src/和独立车间packages/记住几个关键房间的名字后面会反复回来。下一篇我们走到大门口看看你敲下启动命令的那一瞬间程序内部到底发生了什么。