从零打造一个 AI Agent CLI--掘金小册课程推荐/优惠

作者介绍

谭 sir，全栈工程师，长期专注前端工程化、Node.js 后端、AI Agent 应用方向。可在 GitHub / 掘金 / 知乎 关注后续动态。

开源积累：GitHub 2.7K+ followers、累计 60+ 公开仓库、单项目最高 5.6K stars；多个项目在前端学习者中长期获得关注：

• visual-drag-demo（5.6K stars）—— 一个低代码可视化拖拽教学项目
• nand2tetris（2.9K stars）—— 从 NAND 门到俄罗斯方块，从零搭建一台现代计算机
• introduction-to-front-end-engineering（2K stars）—— 一本前端工程化入门小书
• Front-end-articles（1.6K stars）—— 多年技术文章合集
• mini-vue / mini-cli / mini-single-spa / tiny-rendering-engine / monitor-demo —— 一系列「从零实现一个 X」教学项目，覆盖框架、脚手架、微前端、浏览器渲染引擎、前端监控 SDK 等方向

写作沉淀：掘金优秀创作者，60+ 篇技术长文、阅读量 78 万+、点赞 1.7 万+；知乎 1 万+ 关注者、80+ 篇文章累计获 1.4 万+ 赞同 / 3.4 万+ 收藏。代表作覆盖前端性能优化、Nestjs 工程实践、AI Agent 应用实践等方向。

写这本小册的初心：作者过往的开源主线就是"从零实现一个完整工程"——尽量把工程取舍讲清楚，让读者能对照源码读下来。这本小册延续这条主线，把焦点对准 AI 编程助手：配套的 X-Code CLI 是一个完整可运行、持续迭代的开源项目，章节内容按 git tag 切片冻结对应代码状态，避免叙述与代码漂移（具体版本见下文「配套源码与版本对应」）。

小册介绍

跟随这本小册，你将从零构建一个运行在终端的 AI 编程助手——它能理解自然语言指令、自主调用工具读写文件、执行命令、检索代码，在命令行中完成日常开发任务。

成品基于开源项目 X-Code CLI：用户输入一句"帮我把 src/utils.ts 里的 formatDate 重构成支持时区参数的版本"，它会先读源码、分析依赖、生成修改、请求确认、最后落盘——整个过程透明可见，写操作前都会先问过用户。

AI 知识背景：AI Coding Agent 简史

AI 辅助编程不是新鲜事——2021 年 6 月 GitHub Copilot 上线，第一次把"AI 在 IDE 里补全代码"带到主流开发者面前。但它只是补全 / 改写，不能"代你完成任务"。

2023-2024 年开始走向 agentic——也就是 AI 能自主拆解任务、调用工具、读写文件、跑命令：

• Cursor（2023）/ Windsurf——AI 原生 IDE，把 agent 能力深度集成进编辑器
• Devin（2024，Cognition Labs）——第一个号称"软件工程师 AI"的远程 agent，跑在云端浏览器 + 终端里
• Claude Code（2025-02，Anthropic）——CLI 形态，专门给"终端 + Claude"用户的 agent
• GitHub Copilot Agent Mode（2025-02）——Copilot 自己也长出了 agent 能力
• OpenAI Codex CLI / Google Gemini CLI / opencode——2024-2025 涌现的一批开源 / 半开源 CLI agent

这本小册讲的就是"CLI 形态的 coding agent"这条路线。和 IDE 集成的 Copilot / Cursor 不同，CLI agent 不依赖编辑器、不需要 GUI，能跑在任何有终端的环境里（包括 SSH 进生产服务器）。这类工具背后的核心机制——agent loop、工具调用、流式渲染、上下文管理、权限模型——就是本小册要拆解的内容。

小册不只是讲"怎么用 AI SDK 写一个 demo"，而是把一个生产级终端 AI 助手该处理的工程问题逐个讲透：

• LLM Tool Use 协议在 Anthropic / OpenAI / Google 等多家上的差异与统一
• Agent Loop 的多轮工具调用、压缩、超长输出截断、错误恢复
• 终端 UI 的 cell-level diff 渲染——为什么 Ink 默认渲染会抖、怎么解决
• 权限模型、loop guard、prompt caching、思考模式、多模态附件
• 子 agent 委派、Plan Mode 状态机、todoWrite 实时清单
• 知识系统（AGENTS.md 链 + 后台 memory extractor）、JSONL 会话持久化与恢复

理解本小册讲什么有两个有用的视角：

• 三层工程视角——当前 AI 工程可以分成 提示词工程 / 上下文工程 / 驾驭工程（Harness Engineering） 三层，离模型由近到远。本小册讲的多数工程问题落在最外层的驾驭工程，但每一章都会触及前两层。详见 Coding Agent 的三个工程层级
• 失败模式视角——把 40 章翻成"防什么失败"的反向视角：模型幻觉 / 工具误用 / 死循环 / 上下文溢出 /供应商故障 / 用户中断 / 终端环境异常，每一类失败都对应若干章节的工程动机。详见 生产级 Coding Agent 的 7 类失败

两种视角互补——三层讲"工程师在哪里工作"、失败模式讲"在防什么事故"。两个维度交叉能完整解释 40 章每一章为什么存在。

全书结构：主体 40 章按主题分为 7 个部分 + 3 篇附录，共计 43 节：

• 第一部分 · 开篇（Ch.01–03）：Hello Agent（50 行跑通最小 agent）、Coding Agent 的三个工程层级、生产级 Coding Agent 的 7 类失败
• 第二部分 · 架构基石（Ch.04–06）：项目定位与工程基础、CLI 启动流程、本地把项目跑起来
• 第三部分 · Agent Loop 引擎（Ch.07–11）：Tool Use 协议、Agent Loop 实现、多供应商适配、流式 chunk 处理、错误恢复
• 第四部分 · 工具系统（Ch.12–22）：工具系统总览，文件 / Shell / 代码库探索 / 网络 / 控制类工具，工具结果处理，子 agent 与 task，todoWrite，Plan Mode 状态机，三者对比
• 第五部分 · 终端 UI（Ch.23–28）：Ink + Yoga 抖动溯源、cell-level diff 渲染、跨终端工程实战、流式输出、Markdown ANSI、模态对话框
• 第六部分 · 生产化加固（Ch.29–36）：权限模型、token 经济学、上下文压缩、loop guard、prompt caching、thinking 模式、多模态附件、知识与会话系统
• 第七部分 · 扩展生态（Ch.37–40，写作中）：MCP 协议接入、Skill 系统、插件系统、插件 marketplace 与分发
• 附录（三篇）：构建工具链内部、完整代码流程串讲、术语表

配套源码与版本对应

• 第一至第六部分（Ch.01–Ch.36）+ 三篇附录基于 x-code-cli v0.2.10
• 第七部分（Ch.37–Ch.40，扩展生态）将随 MCP / Skill / 插件 / marketplace 功能发布后基于新 tag 写就，届时本节会回填对应 tag 链接

想边读边对照源码，推荐用 git clone --branch v0.2.10 https://github.com/woai3c/x-code-cli.git 拿到与正文严格对应的代码状态。每一章正文里的代码片段上方都标注了源文件路径（精确到 packages/core/src/...），克隆后直接打开对照即可。

你会学到什么？

读完这本小册，你会掌握构建一个生产级终端 AI 编程助手所需的核心工程能力。具体覆盖以下方向：

Agent 引擎层面

• 多模型支持：内置 8 家主流厂商（Claude、GPT、Gemini、Grok、DeepSeek、Qwen、GLM、Kimi），并兼容任意 OpenAI 兼容端点
• Agent Loop 实现：多轮工具调用、流式 chunk 处理、tool-call ↔ tool-result 配对修复
• 三层上下文压缩：light compaction → proactive → reactive 兜底
• Loop guard：检测重复 tool call、软 / 硬两阈值阻断 doom-loop
• Prompt caching：Anthropic 原生 + OpenAI 兼容端点的 prefix caching
• Thinking 模式：把各厂商参数差异统一为 /thinking on|off 单一开关

工具系统层面

• 13 个静态工具 + task 动态注入：文件读写、Shell 执行、代码检索（glob / grep / listDir）、Web（webSearch / webFetch）、用户交互（askUser）、清单（todoWrite）、计划模式（enterPlanMode / exitPlanMode）
• 子 Agent 委派：4 个内置 agent（explore / general-purpose / plan / code-reviewer）+ 用户自定义 agent
• Plan Mode 状态机：只读探索 + 写 plan 文件 → 用户审批后切回执行
• 三级权限模型：always-allow / ask / deny
• 工具结果截断：双预算（行数 + 字节）、按工具配 head-tail / head-only 策略

终端 UI 层面

• Ink + Yoga 抖动问题溯源、cell-level diff 渲染替代方案
• 跨平台兼容：Windows / macOS / Linux（含 cmd.exe / 老 PowerShell 的 ASCII 渲染回退）
• @-mention 文件补全菜单、context-window 占用率底部显示
• 结构化 edit diff + 语法高亮、主题选择器、流式 Markdown ANSI 渲染

知识 + 会话层面

• AGENTS.md 项目说明 + 后台 memory extractor 提炼记忆
• JSONL 单文件 transcript + /resume 历史会话恢复
• 多模态附件：文本、PDF、Office、图片，纯文本模型自动借用其他厂商视觉模型

读完之后，你不仅能用现成的 AI 编程助手，还能自己构建一个、修改一个、把它定制成适配自身代码库 / 团队工作流的工具。

适宜人群

本小册面向以下三类开发者：

1. 想理解 AI Coding Agent 内部机制的工程师——已经在用 Claude Code、Cursor、Codex 等工具，但好奇"模型是怎么调用工具的"、"上下文怎么压缩"、"权限系统怎么设计"
2. 想构建自己的 CLI 工具的开发者——有具体场景需要落地一个针对自身代码库 / 团队工作流的 AI 助手，但不知道从哪里开始
3. 对 TUI / 终端渲染感兴趣的前端工程师——好奇 Ink、Yoga、ANSI 渲染、CJK 抖动这类话题的工程实现

阅读小册不需要 AI 相关的深度背景，但以下技能是默认掌握的：

• TypeScript 基础语法——类型注解、泛型、接口；高阶类型不要求
• Node.js 与 npm / pnpm——能运行一个项目、知道 package.json 各字段含义
• 基本的命令行操作——使用 git、bash 或 PowerShell
• 大致了解 React 组件模型——TUI 部分用到 Ink（React for CLI），熟悉 JSX / Hook 即可，没用到 React 的高级特性

至于 LLM 的 tool-use 协议、流式响应处理等概念，第二部分会从零讲起，无需提前准备。

为了把核心讲透，以下话题不在小册范围内：

• 大模型原理——不讲注意力、Transformer、训练流程
• 模型微调与部署——直接调用现成的 API，不做模型工程
• 通用 React / Node.js 教程——只讲与 CLI / Ink 相关的部分
• Web 前端工程化——构建工具部分仅覆盖 esbuild 在 CLI 场景下的用法

• 开篇示例：Hello Agent —— 50 行跑通一个 agent

• 开篇：生产级 Coding Agent 的 7 类失败

• 项目定位与工程基础

• 开篇：Coding Agent 的三个工程层级

• 实现 Agent Loop

• Tool Use 协议

• CLI 启动流程

• 本地把项目跑起来

• 多供应商支持

• 错误恢复

• 流式 chunk 处理

• 工具结果处理

• 文件工具：readFile / writeFile / edit

• 工具系统总览

• 控制类工具：askUser / enterPlanMode / exitPlanMode

• Shell 工具：把任意命令跑起来

• 代码库探索：glob / grep / listDir

• 网络工具：webSearch / webFetch

• 子 Agent 与 task 工具：把工作"外包"出去

• todoWrite：模型自管理的任务清单

• Ink + Yoga：CJK 抖动溯源

• 流式输出

• Plan Mode：先计划再开工

• Plan Mode、todoWrite、task：三种"让模型自己规划"的形态对比

• 权限对话框、askUser 模态、SelectOptions

• ChatInput cell-level diff 渲染

• 让 cell buffer 在真实终端上跑稳——三个原则

• Token 经济学：四层防御一览

• Markdown → ANSI 自研渲染器

• 三级权限模型与 shell 命令分级

• 上下文压缩：轻量 / 主动 / 反应式三层

• Loop guard：doom-loop 检测

• Thinking 模式统一开关

• Prompt caching：跨供应商的缓存策略

• 知识与会话：长期事实与单文件 transcript

• 插件 marketplace 与分发

• 文件附件 & 视觉降级（vision-fallback）

• MCP 协议接入

• Skill 系统

• 插件系统（打包 MCP + Skill + commands + agents）

• 附录一：构建工具链内部

• 附录二：完整代码流程串讲

• 附录三：术语表