# 从零到一：像造一辆车那样，造一个 AI 编程助手 > 写给**编程零基础的文科生**：当你已经能看懂各种 AI Agent 项目的技术构造之后，如何真正从零、按照专业的软件开发流程，亲手造出一个类似 Claude Code 的产品。 > > 我们以 **[[Claude Code]]** / **[[Claude Desktop]]** 为镜子，一边解剖它，一边反推：如果这件事落到你头上，你该怎么想、怎么做、找谁做、按什么顺序做。 > > 全书所有**加了双方括号的词**（如 [[主循环]]、[[版本控制]]）都是"知识树节点"——在配套网站里它们会变成可点击的链接，帮你把散落的概念连成一张网，做到**融会贯通、举一反三**。 --- ## 0. 使用说明：这本书是一棵"知识树" 这本书不是从头读到尾的小说，而是一棵可以**任意跳转**的树。 - **主干**（第 1–8 章）：一条完整的主线——从"想法"到"上线"，一个软件是怎么被造出来的。 - **延伸**（第 9 章 客户端模块）：如果目标是做成图形化客户端，还需要哪些额外的技术模块——UI、动画、桌面打包。 - **叶子**（第 10 章 术语总表）：每一个专业名词，都用"人话 + 生活比喻"解释一遍。 - **根系**（第 11 章 知识树地图）：把所有概念之间的关系画成一张图，让你看清"谁依赖谁、谁是谁的前提"。 > 📌 **阅读建议**：第一遍先顺着主干读，遇到看不懂的 [[术语]] 先不要停，记住它是个链接，读完整章再回到术语表补课。第二遍再顺着知识树，把概念之间的连线走一遍。 三个贯穿全书的**主角视角**，请始终带着它们读： 1. **传统软件公司**怎么做这件事？（一群人，分工明确，流程厚重） 2. **单人独立开发者**怎么做这件事？（一个人，分饰多角，处处取舍） 3. **AI Agent 时代**怎么做这件事？（一个人 + 一群 AI 助手，比如用 [[Claude Desktop]] 当副驾） --- ## 1. 先看懂"终点"：我们要造的到底是什么 在动手造车之前，先把一辆车拆开看看。我们要造的东西，长得像 [[Claude Code]]：**一个住在终端里、能读你的代码、能自己动手改文件、能跑命令、会跟你商量的编程助手。** ### 1.1 用一句话说清它的本质 > **它 = 一个大语言模型（[[大语言模型|LLM]]）+ 一圈让模型能"动手"的软件。** 模型本身只会做一件事：**读一段文字，写一段文字**。它不会打开文件、不会运行命令、不会记住昨天的对话。所有这些"超能力"，都是外面那圈软件给它的。这圈软件，就是我们要造的主体。 ### 1.2 把它拆成五层（这就是"产品解剖图"） 借用 Claude Code 的经典结构，任何这类 agent 都可以拆成**五层**（这是本书反复引用的地图，记作 [[五层架构]]）： | 层 | 生活比喻 | 职责 | 对应术语 | |---|---|---|---| | ① 界面层 | 汽车的方向盘和仪表盘 | 接收你打的字、把结果画在屏幕上 | [[用户界面|UI]]、[[终端界面|TUI]] | | ② 大脑层 | 司机的大脑 | 调用 [[大语言模型|LLM]]，把你的话变成"下一步做什么" | [[模型供应商|Provider]]、[[流式响应|Streaming]] | | ③ 循环层 | 发动机 | 一圈圈地转：问模型→执行→再问模型 | [[主循环]]、[[Agent Loop]] | | ④ 手脚层 | 车轮和刹车 | 真正去读写文件、跑命令、搜网页 | [[工具系统|Tools]]、[[权限系统|Permission]] | | ⑤ 记忆层 | 后备箱和行车记录仪 | 记住对话、压缩历史、跨会话记住你 | [[上下文]]、[[上下文压缩|Compaction]]、[[记忆系统|Memory]] | > 🎯 **反推的第一课**：造这样一个产品，本质上就是**把这五层，一层一层地实现出来，再拼起来**。后面第 7 章的"一步一步"，走的正是这条路。 ### 1.3 Claude Code 和 Claude Desktop 的区别（别搞混） - **[[Claude Code]]**：跑在**终端**里的编程助手，主打"改代码"。 - **[[Claude Desktop]]**：一个**桌面聊天应用**，主打"和 Claude 对话 + 通过 [[MCP]] 连接你的本地工具"。 本书造的产品，形态更接近 Claude Code；但在讲"AI Agent 时代怎么开发"时，我们会用 **Claude Desktop 当你的开发副驾**——它就是你身边那个不知疲倦的初级工程师。 --- ## 2. 从"想法"到"软件"：一款软件诞生的全景地图 一个软件从无到有，会经过几个大阶段。这套流程有个正式名字叫 [[软件开发生命周期|SDLC]]（Software Development Life Cycle）。用"开一家餐厅"来比喻： | 阶段 | 餐厅比喻 | 软件里叫什么 | 产出物 | |---|---|---|---| | 1. 想清楚要做什么 | 决定开一家川菜馆、给谁吃 | [[需求分析]] | [[产品需求文档|PRD]] | | 2. 画图纸 | 画厨房动线、餐位布局 | [[架构设计]] | [[技术设计文档|设计文档]] | | 3. 装修施工 | 砌墙、通水电、买设备 | [[编码|开发]] | 源代码 | | 4. 试营业尝味道 | 请人来试吃、挑毛病 | [[测试]] | 测试报告、[[缺陷|Bug]]列表 | | 5. 开业 | 挂招牌、迎客 | [[部署]]/[[发布]] | 可下载/可访问的产品 | | 6. 天天经营 | 根据客人反馈改菜单 | [[运维]]/[[迭代]] | 新版本 | > 💡 **关键认知**：这六步**很少一次走完**。现代开发是**转圈**的——做一点、测一点、发一点、再改一点。这种"小步快跑、不断转圈"的做法，就是下一章要讲的 [[敏捷开发|敏捷]]。 --- ## 3. 软件工程是什么，为什么需要"流程" ### 3.1 "编程" ≠ "软件工程" - **编程**：写出能跑的代码。像"会做一道菜"。 - **[[软件工程]]**：让**一群人**在**很长时间**里，持续做出**别人也能看懂、能维护、不容易坏**的软件。像"开一家能连锁十年的餐厅"。 一个人写个小脚本，不需要什么工程。但要造一个像 Claude Code 这样成千上万人用、要活很多年的产品，就必须讲工程。工程解决的核心矛盾是： > **人会忘、人会走、需求会变、代码会越来越乱。** 工程就是一整套对抗这些"熵增"的纪律。 ### 3.2 两种主流"流程范式" **① [[瀑布模型|瀑布开发]]**：像盖楼——先全部设计好，再施工，一步步往下流，不回头。 - 优点：适合需求非常明确、不太会变的场景。 - 缺点：等你盖完发现设计错了，推倒重来代价巨大。 **② [[敏捷开发|敏捷]]**：像搭乐高——先搭个能玩的小车，给用户玩，听反馈，再加零件。 - 核心动作：把大目标切成两周左右的小周期（[[迭代|Sprint]]），每个周期都产出一个"能用的一点点"。 - 配套仪式：每日站会、[[需求池|Backlog]]、[[看板]]、回顾会。 - 今天绝大多数互联网产品，包括 AI 产品，都用敏捷。 > 🧭 **给你的建议**：单人开发，用**"极简敏捷"**——不需要开会，但要保留敏捷的灵魂：**永远先做出一个能跑的最小版本（[[最小可行产品|MVP]]），再逐步加**。 --- ## 4. 造这个产品，需要哪些"角色" 在传统公司里，下面这些是**不同的人**；单人开发时，是**你一个人分饰多角**；AI 时代，其中很多角色可以由 **AI 助手辅助甚至部分替你扮演**。 先认识他们。每个角色我给出：**使命、要求、产出物、最容易和谁吵架**。 ### 4.1 产品经理（[[产品经理|PM]]） - **使命**：搞清楚"做什么、为谁做、为什么值得做"。 - **要求**：懂用户、会取舍、能把模糊的想法写成清楚的 [[产品需求文档|PRD]]。 - **产出物**：PRD、功能优先级列表、[[用户故事]]。 - **最容易和谁吵架**：和工程师吵"这个功能到底难不难、值不值得做"；和设计师吵"要好看还是要快"。 ### 4.2 [[用户体验设计师|UX/UI 设计师]] - **使命**：让产品**好用又好看**。 - **要求**：懂人的操作习惯、会画 [[原型图]]、定义交互与视觉规范。 - **产出物**：线框图、高保真设计稿、[[设计系统]]。 - 对 Claude Code 这类终端产品，"设计"体现在：命令怎么起名、报错怎么说人话、流式打字的节奏、颜色和排版。 ### 4.3 [[前端工程师]] - **使命**：把设计稿变成用户能点、能看的**界面**。 - **要求**：掌握界面技术（网页里是 [[HTML]]/[[CSS]]/[[JavaScript]] 与 [[React]] 等框架；终端里是 [[TUI]] 技术）。 - **产出物**：界面层代码（对应五层里的 ① 界面层）。 ### 4.4 [[后端工程师]] - **使命**：造用户看不见、但支撑一切的**引擎**。 - **要求**：掌握服务器、[[数据库]]、[[API]] 设计、并发、安全。 - **产出物**：大脑层、循环层、手脚层、记忆层的大部分代码（对应五层里的 ②③④⑤）。 - 这是本类产品**最核心、最重的**角色。 ### 4.5 [[AI/机器学习工程师|AI 工程师]] - **使命**：把 [[大语言模型|LLM]] 用好——写 [[提示词工程|Prompt]]、设计 [[上下文]] 组装、调 [[流式响应|Streaming]]、控成本（[[Prompt 缓存]]）。 - **要求**：懂模型脾气、会评估效果、能省 [[Token]]。 - 在 AI 产品里，这个角色和后端高度重叠，是"新时代"最关键的新增角色。 ### 4.6 [[测试工程师|QA]] - **使命**：在用户之前，先找出所有毛病。 - **要求**：会设计测试用例、写 [[自动化测试]]、盯 [[边界情况]]。 - **产出物**：测试用例、Bug 报告、质量红线。 ### 4.7 [[运维工程师|DevOps]] - **使命**：让产品能顺利**发布、更新、不宕机**。 - **要求**：会 [[持续集成|CI]]/[[持续部署|CD]]、[[打包分发]]、[[监控可观测性|监控]]。 - **产出物**：发布流水线、安装包、监控面板。 ### 4.8 [[技术负责人|架构师/Tech Lead]] - **使命**：定技术大方向、守住代码质量底线、拍板技术争议。 - **要求**：经验丰富、能看长远、会做 [[代码审查|Code Review]]。 > 🗺️ **一张"角色—五层"对应表**： > > | 角色 | 主要负责的层 | > |---|---| > | PM / 设计 | 决定 ① 界面层长什么样、整体做什么 | > | 前端 | ① 界面层 | > | 后端 / AI 工程师 | ②③④⑤ 大脑/循环/手脚/记忆层 | > | QA | 全部五层的质量 | > | DevOps | 让五层拼成的整体能发布运行 | > | 架构师 | 五层怎么切、怎么拼 | --- ## 5. 角色之间如何协作，又如何"处理矛盾" 造软件最难的往往不是技术，而是**人和人、目标和目标之间的冲突**。列几个最典型的矛盾，以及专业团队怎么化解： ### 5.1 三个经典矛盾 **矛盾一：PM 想要更多功能 ⨯ 工程师说做不完。** - 化解：用[[优先级排序]]（如 MoSCoW：必须做/应该做/可以做/这次不做）。把"既要又要"变成"先要什么"。产品的本质是**取舍**，不是堆料。 **矛盾二：做得快 ⨯ 做得好（[[技术债]]）。** - 为了赶工写的烂代码，就像刷信用卡——[[技术债]]。短期爽，长期要还利息（越来越难改）。 - 化解：明确"这里我们**故意欠债**，下个迭代还"，并记进 backlog。而不是假装没欠。 **矛盾三：我觉得该这样 ⨯ 你觉得该那样（技术方案之争）。** - 化解：写 [[技术方案文档|设计文档]]，把两种方案的利弊摆到桌面上，由 [[技术负责人|架构师]] 或团队用**依据**（性能数据、维护成本、风险）而不是**嗓门**来拍板。这正是本项目分析里反复出现的"选择困境"思维。 ### 5.2 让协作不崩的三样"基础设施" 无论几个人，这三样都必须有（单人也要）： 1. **[[版本控制|Git]]**：所有代码的"时光机 + 协作台"。谁改了什么、什么时候改的、出错了怎么回退，全靠它。→ 详见术语表。 2. **[[代码审查|Code Review]]**：代码合并进主线前，让另一双眼睛（或 AI）先看一遍。单人开发时，可以让 [[Claude Desktop]] 当那双眼睛。 3. **[[文档]]**：给未来的你和别人留说明书。README、设计文档、代码注释。 --- ## 6. 三种开发范式对比：同一个产品，三条造法 现在把三个视角正面摆在一起。假设目标都是造出前面那个五层结构的编程 agent。 ### 6.1 传统软件公司怎么做 ``` 立项 → PM 写 PRD → 设计出稿 → 架构评审 → 拆任务给前端/后端/AI 工程师 → 各自开发（用 Git 分支协作）→ 提交 Code Review → QA 测试 → DevOps 走 CI/CD 发布 → 监控运营 → 收集反馈 → 下一个迭代 ``` - **特点**：分工细、流程重、质量有多重保险、沟通成本高、速度相对慢。 - **优点**：能造大、造稳、能长期维护。 - **代价**：一个小改动可能要走一长串流程。 ### 6.2 单人独立开发者怎么做 - 你一个人是**全栈**（前端+后端+AI+测试+运维）+ 半个 PM + 半个设计。 - **核心策略：极致取舍 + 借力**。 - 不自己造轮子：能用现成的[[开源]]库、现成的模型 [[API]]，绝不自己写。 - 只做 [[最小可行产品|MVP]]：先让"问模型→改一个文件"这条最短链路跑通，再加功能。 - 把"未来的自己"当成协作对象：写清楚 README 和注释，因为三个月后你也会忘。 - **优点**：极快、无沟通成本、完全自由。 - **代价**：容易在"我不擅长的层"（比如安全、测试）留下大坑；一个人精力有限。 ### 6.3 AI Agent 时代怎么做（以 Claude Desktop 为副驾） 这是本书最想让你理解的**新范式**：你不再孤军奋战，而是**指挥一队 AI**。 把第 4 章的角色重新分配： | 角色 | 新时代由谁来干 | |---|---| | PM | 你（人）定方向；AI 帮你把想法写成 PRD、挑优先级 | | 设计 | 你定审美；AI 出多套方案、生成界面草稿 | | 前端/后端/AI 工程 | **AI 写大部分代码**，你审阅、把关、连接 | | QA | AI 生成测试用例、跑测试、找 Bug | | Code Review | AI 先审一遍，你终审 | | DevOps | AI 帮你写发布脚本、配 CI/CD | - **人的新使命**：从"写每一行代码"升级为"**定义问题、做关键决策、把关质量、负最终责任**"。你是**导演**，AI 是**演员**。 - **协作方式**：像和一个聪明但需要明确指令的初级工程师合作—— 1. 给它**清晰的上下文**（这正是本项目分析里 [[上下文工程]] 的价值）； 2. 让它**小步产出**、你**逐步验收**； 3. 用它不擅长的地方（长期架构判断、审美、责任）由你补上。 - **优点**：一个人能达到接近小团队的产能。 - **风险**：AI 会自信地犯错（[[幻觉|Hallucination]]）；你若看不懂它写的代码，就无法把关。**所以你越懂技术原理，越能驾驭 AI**——这也是你读完前面所有 agent 分析的意义。 > 🚀 **一句话总结三范式**：传统公司靠**流程和人海**，单人靠**取舍和借力**，AI 时代靠**你的判断力 × AI 的生产力**。 --- ## 7. 一步一步：从零构建 "MiniClaude" 的完整链路 下面是本书的**实操主线**：假设你要做一个简化版编程 agent，就叫它 **MiniClaude**。每个阶段我都给出：**做什么 → 涉及的术语 → 传统公司/单人/AI 时代分别怎么做**。 ### 阶段 0：搭好"工作台"（环境与工具） 在写任何代码前，先准备工具。类比：厨师做菜前要先有厨房。 - **[[终端|命令行]]（Terminal）**：一个用打字来指挥电脑的黑框框。程序员的主战场。 - **[[编辑器/IDE]]**：写代码的地方（如 VS Code、Cursor）。 - **[[版本控制|Git]] + [[代码托管|GitHub]]**：代码的时光机和云端仓库。 - **[[编程语言]] 与 [[运行时]]**：选一门语言（本类项目常用 [[TypeScript]]/[[Python]]/[[Rust]]）。语言需要"运行时"才能跑，比如 [[Node.js]]、Python 解释器。 - **[[包管理器]]**：帮你自动下载别人写好的代码库（如 npm、pip）。 > 🤖 **AI 时代做法**：直接问 [[Claude Desktop]]："我在 Mac 上，想学做一个 Python 的命令行工具，帮我列出要装什么、给出每条安装命令并解释。" 它会成为你的**环境配置向导**。 ### 阶段 1：想清楚做什么（需求 → PRD） - 写一份**一页纸 [[产品需求文档|PRD]]**： - **谁用**（目标用户）、**解决什么痛点**、**最核心的三个功能**、**明确不做什么**。 - MiniClaude 的 MVP 需求可以是：*"在终端输入一句话，它能读取当前目录的一个文件、按我的要求改写它、改之前先问我同不同意。"* - **传统公司**：PM 访谈用户、写详细 PRD、评审。 - **单人**：给自己写三句话需求，够了。 - **AI 时代**：把你的模糊想法丢给 AI，让它反问你问题、帮你补全 PRD。 ### 阶段 2：画图纸（架构设计） - 决定 MiniClaude 的**五层**怎么落地： - ① 界面：先用最简单的命令行读一行输入。 - ② 大脑：调用某个 [[模型供应商|Provider]] 的 [[API]]。 - ③ 循环：一个 `while` [[主循环]]。 - ④ 手脚：先实现两个 [[工具系统|工具]]——"读文件"和"写文件"。 - ⑤ 记忆：先把对话存在内存里就行。 - 画一张**数据流图**：你的话 → 组装成给模型的 [[上下文]] → 模型返回"要调用写文件工具" → 执行前弹窗问你 → 执行 → 结果喂回模型 → 模型说"改好了"。 - **术语**：[[API]]、[[上下文]]、[[工具调用|Tool Use]]、[[权限系统|Permission]]。 ### 阶段 3：搭骨架（技术选型 + 脚手架） - **[[技术选型]]**：根据"团队会什么、生态好不好、要解决什么痛点"选语言和库（本项目分析第三、四章正是讲这个）。单人建议选你**最熟**或**AI 最擅长辅助**的语言。 - **[[脚手架]]**：用工具一键生成项目的初始文件结构，不用从空白开始。 ### 阶段 4：让心脏跳起来（[[主循环]] MVP） 这是整个产品的"发动机"，也是最关键的一步。伪代码（人人都能看懂的版本）： ``` while 对话没结束: 把"历史对话 + 你的新指令"打包成上下文 发给大模型，问它：下一步做什么？ 如果模型说"我要调用某个工具": （必要时）先弹窗问用户同不同意 执行工具，拿到结果 把结果加回对话历史 继续循环 ← 让模型看到结果后决定下一步 否则（模型只是回话）: 把回答显示给用户 结束这一轮 ``` > 这段循环，就是所有 agent 的共同心跳。你在六个开源项目里看到的所有花样，都是围绕这段循环加的"配套设施"。 - **传统公司**：多人分别写模型调用、工具执行、界面渲染，再联调。 - **单人**：先把上面这段用最少的代码跑通，哪怕丑。 - **AI 时代**：让 AI 生成第一版循环，你逐行读懂、亲手调通——**这一步一定要自己弄懂，否则后面无法把关**。 ### 阶段 5：装上手脚（[[工具系统|工具系统]]） - 定义工具的统一"接口"：每个工具有**名字、说明、参数、执行函数**。 - 关键工程点（呼应项目分析）： - 工具的说明每轮都要发给模型，很费 [[Token]] → 工具不要太多。 - 给工具打**安全标记**（只读？会改文件？会跑命令？）→ 决定要不要审批。 ### 阶段 6：装上刹车（[[权限系统|权限与安全]]） - 危险操作（删文件、跑命令）执行前必须经过闸门：**要么问用户，要么规则拦截，要么丢进[[沙箱]]隔离**。 - 这是**新手最容易忽视、却最重要**的一层——一个能自己跑命令的 agent，没有刹车就是灾难。 ### 阶段 7：装上记忆（[[上下文]]与[[记忆系统|记忆]]） - 对话会越来越长，超过模型能读的上限（[[上下文窗口]]）→ 需要 [[上下文压缩|压缩]]（把旧对话总结成摘要）。 - 想让它"跨天记得你" → 把重要信息写进一个 [[记忆文件]]（如项目里的 `AGENTS.md`/`CLAUDE.md`）。 ### 阶段 8：试吃挑毛病（[[测试]]） - **[[单元测试]]**：测最小的零件（如"写文件工具"单独能不能正常工作）。 - **[[集成测试]]**：测几个零件拼起来（如"整条主循环"）。 - **[[边界情况]]测试**：网断了怎么办？模型胡说怎么办？用户按了取消怎么办？—— 成熟产品的一大半代码都在处理这些。 ### 阶段 9：开业（[[打包分发]]与[[发布]]） - 把代码变成别人能一键安装运行的东西（[[安装包]]、发布到 [[包管理器]]、或做成网站）。 - 建立 [[持续集成|CI]]：每次改代码自动跑测试，防止改坏。 ### 阶段 10：天天经营（[[迭代]]与[[运维]]） - 收集用户反馈 → 排进 backlog → 下一个迭代做 → 循环回到阶段 1。 - 加[[监控可观测性|监控]]：知道有多少人用、哪里报错、花了多少钱。 --- ## 8. 贯穿始终的"工程心法" 这些不是某一步，而是从头到尾都要有的**习惯**： - **[[版本控制|小步提交]]**：每完成一小块就用 Git 存档，写清楚这次改了啥。 - **[[代码审查|审查]]**：合并前多一双眼睛（人或 AI）。 - **[[自动化测试]]**：让机器帮你反复检查，而不是每次手动点。 - **[[持续集成|CI/CD]]**：把"测试→发布"自动化成流水线。 - **[[文档]]先行**：先写清楚要做什么，往往比直接写代码更省时间。 - **[[可观测性]]**：让系统"会说话"——出问题时能快速知道哪里坏了。 - **管理[[技术债]]**：允许欠债，但要记账、要还。 > 🧠 **给零基础读者的终极心法**：**先能跑，再能看，最后能久。** 别一开始就追求完美架构——先让最短的链路跑起来（能跑），再让代码清晰（能看），最后才考虑长期可维护（能久）。这正是 Claude Code 等成熟项目一路走过来的轨迹。 --- ## 9. 如果最终目标是客户端——还需要哪些模块 > 前面八章讲的是一个"住在终端里的 AI 编程助手"——靠命令行就能跑起来。但很多人的真正目标是做成一个**图形化的客户端产品**：有界面、有动画、有快捷键、甚至可以打包成桌面 App 安装在别人电脑上。这一章回答：如果你要走这条路，在前八章的基础上，**还需要多做哪些事情**。 ### 9.1 界面层：从命令行到可视化界面 你的 agent 已经有了主循环、工具系统、权限管理——这些都是"大脑"。现在你要给它装一张"脸"。 **选择 UI 框架**，主要两条路： | 场景 | 推荐技术 | 代表项目 | |---|---|---| | 纯终端（字符界面）| Ratatui（Rust）/ Ink（TypeScript）| Claude Code、grok-build、CodeWhale | | 网页/桌面混合 | React + TypeScript + Vite | opencode、hermes、nanobot WebUI | | 桌面原生 App | Electron（Web 技术打包）或 Tauri（Rust 后端 + Web 前端）| goose（Electron）、grok-build 未来方向 | > 💡 **给零基础读者的建议**：先从 React + TypeScript 网页界面入手——它的学习资料最多、调试工具最好，做熟了再考虑打包成桌面 App。 ### 9.2 流式展示：边生成边显示 命令行版本可以直接把模型的输出打印出来。图形界面要做到"打字机效果"（逐字显示），需要处理**流式渲染**： - **技术原理**：模型 API 返回的是 [[流式响应|SSE（Server-Sent Events）]] 或 WebSocket 流——不是一次性返回全文，而是一个字一个字地推过来。 - **前端要做的事**：监听流、把每个新字符追加到界面上、同时让滚动条自动跟到底部。 - **困难点**：如果同时有多个工具在并行执行，界面要能显示"多个任务同时进行中"的状态，而不是等最后一个跑完再一起显示。 实际项目里，这个部分的代码量通常比你想象的大——opencode 的前端仅流式展示相关代码就有数百行。 ### 9.3 代码高亮与 Diff 视图 AI 编程助手最核心的展示场景是**代码**，普通文本框完全不够用。你需要： - **[[语法高亮]]**：不同语言的关键词、字符串、注释用不同颜色显示。推荐用 **Prism.js** 或 **Shiki**（Shiki 支持 VS Code 主题，效果最好）。 - **[[Diff 视图]]**：AI 修改了文件，你要能一眼看到"删了什么、加了什么"（红色 vs 绿色的对比）。推荐用 **Monaco Editor**（VS Code 同款编辑器组件）的 diff 模式，或者轻量方案 **diff2html**。 - **代码块交互**：用户能一键复制代码块、能点击"Apply"把 AI 生成的代码写入真实文件——这些都需要单独实现。 ### 9.4 动画与过渡效果 好的客户端产品，每一个状态切换都应该是流畅的，而不是闪现。需要考虑： - **加载动画**：模型在思考时，界面要有转圈 / 打点 / 波纹等动画告诉用户"正在处理"。 - **消息进入动画**：新消息出现时用淡入或滑入，而不是突然出现。 - **工具执行状态**：读文件、运行命令时，显示进度条或实时滚动的日志。 - **推荐库**：CSS 动画（轻量）、**Framer Motion**（React 动画库，交互式动画首选）、**GSAP**（复杂时间轴动画）。 > 注意：动画是体验加分项，但**性能是前提**——流式输出时每一帧都在重渲染，动画过重会导致界面卡顿。先保证流畅，再加动画。 ### 9.5 状态管理：界面和大脑的"同步问题" 你的 agent 后端有一套状态（当前会话、正在执行的工具、用户权限……），前端界面需要**实时反映**这些状态。这就是"状态管理"。 - **简单场景**：用 React 的 `useState` / `useContext` 就够了。 - **中等场景**：用 **Zustand**（轻量）或 **Jotai**（原子化状态），适合会话列表 + 当前消息 + 工具状态这种层级。 - **复杂场景**（多窗口、多会话并发、实时同步）：考虑 **Redux Toolkit** 或 opencode 的思路——把后端当服务器，前端只是一个"薄客户端"，所有状态以后端为准，前端只管显示和发指令。 ### 9.6 多面板布局与快捷键 专业的编程工具都有多面板布局：左边是文件树、中间是对话、右边是代码预览。这需要： - **布局方案**：CSS Grid / Flexbox 基础布局；可拖拽调整大小用 **react-resizable-panels** 库。 - **面板联动**：点击对话里的文件路径，右边代码面板自动跳转到对应位置。 - **[[键盘快捷键]]**：`Ctrl+K` 呼出命令面板、`Esc` 中断任务、`Ctrl+Enter` 发送消息——这些都要单独注册和处理（用 **hotkeys-js** 或原生 `keydown` 事件）。 - **命令面板（Command Palette）**：类似 VS Code 的 `Ctrl+Shift+P`，用户输入关键词就能找到任何功能。grok-build 的 `Ctrl+P` 命令面板就是这种设计。 ### 9.7 主题系统：亮色 / 暗色模式 用户期待能切换深色/浅色主题，专业工具还支持自定义配色。 - **CSS 变量方案**：定义一套颜色变量（`--color-bg`、`--color-text`……），切换主题时只改变量值，不改组件代码。这是最通用的方案。 - **Tailwind CSS**：它内置了 `dark:` 前缀支持，配合 `class="dark"` 开关非常方便。 - **注意事项**：代码高亮库（如 Shiki）要单独配置对应主题；终端模拟器颜色要额外处理。 ### 9.8 终端模拟器：在界面里显示真实的命令行输出 你的 agent 会运行 Shell 命令，用户希望在界面里看到彩色的终端输出（ANSI 转义码渲染），而不是一堆乱码。 - **推荐库**：**xterm.js**——VS Code 内置终端就是用它，支持 256 色、光标移动、实时流式输出。 - **集成要点**：后端把命令的 stdout/stderr 通过 WebSocket 流推给前端，xterm.js 逐行渲染；同时处理好 ANSI 颜色转义码（`\033[32m`之类）。 ### 9.9 桌面打包：从网页到可安装的 App 如果你想让用户"下载安装"而不是"打开浏览器访问"，需要把网页打包成桌面 App： | 方案 | 特点 | 代表 | |---|---|---| | **Electron** | 用 Node.js + Chromium，包体较大（50–200MB）；生态最成熟 | goose 桌面端、VS Code | | **Tauri** | 用系统自带 WebView + Rust 后端，包体很小（几 MB）；Rust 学习曲线 | 新一代桌面 App 首选 | | **PWA** | 浏览器内"安装"，无需打包；能力受限，不能调用本地命令 | 轻量场景 | 对于 AI 编程助手这类需要**调用本地文件、运行命令**的工具，Electron 或 Tauri 是必选项——PWA 权限不够。打包之后还需要处理**自动更新**（Electron 用 `electron-updater`，Tauri 内置更新器）。 ### 9.10 小结：客户端的额外工作量 把 AI agent 做成图形化客户端，工作量通常是"纯终端版"的 **2–4 倍**。主要额外工作： ``` ① UI 框架搭建（React + 路由 + 状态管理） 约 1–2 周 ② 流式展示 + 代码高亮 + Diff 视图 约 1–2 周 ③ 动画与加载状态 约 3–5 天 ④ 多面板布局 + 快捷键 + 命令面板 约 1 周 ⑤ 主题系统 约 2–3 天 ⑥ 终端模拟器集成 约 3–5 天 ⑦ 桌面打包 + 自动更新（如需要） 约 1–2 周 ``` > 📌 **建议**：不要试图一开始就做客户端。先让纯终端版（第 7 章的 MiniClaude）跑起来、验证产品方向，再加界面。**界面可以后加，核心循环必须先稳。** 参考 goose 的历程——它的 Electron 桌面端是在 Rust 引擎稳定之后才做的，核心 API 稳定是界面开发的前提。 --- ## 10. 术语总表（零基础人话版） > 每条：**术语｜一句话人话｜生活比喻**。这些是知识树的"叶子节点"。 - **[[大语言模型|LLM]]**｜能读文字、写文字的超大 AI 模型｜一个读过全世界的书、但记不住昨天聊了啥的天才。 - **[[Token]]**｜模型处理文字的最小计价单位｜出租车的"公里数"，用得越多越贵。 - **[[API]]**｜程序之间对话的标准接口｜餐厅的点菜窗口，你按菜单点，后厨照做。 - **[[提示词工程|Prompt]]**｜你写给模型的指令｜给天才助手交代任务的说明书。 - **[[上下文]]**｜这一次发给模型的全部信息｜考试时你能带进考场的所有小抄。 - **[[上下文窗口]]**｜模型一次最多能读多少字｜小抄纸的大小，超了塞不下。 - **[[上下文压缩|Compaction]]**｜把旧对话总结成摘要以省空间｜把厚笔记浓缩成几行要点。 - **[[流式响应|Streaming]]**｜模型一个字一个字地吐结果｜打字机边打边出，不用等全文。 - **[[主循环]]**｜"问模型→执行→再问"的反复循环｜发动机一圈圈转。 - **[[工具系统|Tools]]**｜让模型能真正动手的功能（读写文件等）｜给大脑接上手和脚。 - **[[工具调用|Tool Use]]**｜模型说"我要用某个工具"｜大脑发出"抬手"的指令。 - **[[权限系统|Permission]]**｜危险操作前的审批闸门｜手术前要签同意书。 - **[[沙箱]]**｜把危险操作关进隔离的小房间跑｜实验室里的防爆箱。 - **[[记忆系统|Memory]]**｜跨对话记住信息｜行车记录仪 + 备忘录。 - **[[模型供应商|Provider]]**｜提供大模型服务的公司｜不同品牌的发动机厂。 - **[[Prompt 缓存]]**｜重复内容缓存起来少付费｜月票，常走的路更便宜。 - **[[版本控制|Git]]**｜记录代码每次改动、可回退、可协作｜游戏的存档 + 多人协作台。 - **[[代码托管|GitHub]]**｜放代码的云端仓库｜代码的网盘 + 社区。 - **[[分支|Branch]]**｜在不影响主线的情况下试验新改动｜平行宇宙，试完再合并。 - **[[代码审查|Code Review]]**｜合并前让别人检查代码｜作业交前同桌帮看一遍。 - **[[Bug|缺陷]]**｜程序里的错误｜菜里的头发。 - **[[测试]]**｜系统性地检查有没有毛病｜出厂前的质检。 - **[[单元测试]]**｜测单个最小零件｜单独测一颗螺丝。 - **[[集成测试]]**｜测多个零件拼起来｜测整台发动机。 - **[[边界情况]]**｜极端/异常的情形｜"如果客人不给钱怎么办"。 - **[[持续集成|CI]]**｜每次改代码自动跑测试｜流水线上的自动质检机。 - **[[持续部署|CD]]**｜自动把新版本发布出去｜自动把成品送上货架。 - **[[部署]]/[[发布]]**｜让产品能被真实用户使用｜餐厅开业迎客。 - **[[打包分发]]**｜把代码变成能安装的成品｜把菜装进外卖盒。 - **[[运维]]**｜保证上线后稳定运行｜餐厅日常运营维护。 - **[[监控可观测性|监控]]**｜实时了解系统运行状况｜仪表盘和摄像头。 - **[[技术债]]**｜为赶工欠下的"代码烂账"｜刷信用卡，早晚要还。 - **[[重构]]**｜不改功能、只让代码更整洁｜不换菜品、重新整理厨房。 - **[[敏捷开发|敏捷]]**｜小步快跑、不断迭代的做法｜边搭乐高边玩边加。 - **[[最小可行产品|MVP]]**｜能验证核心价值的最简版本｜只卖一道招牌菜的试营业。 - **[[前端]]**｜用户看得见的界面部分｜餐厅的门面和餐桌。 - **[[后端]]**｜用户看不见的引擎部分｜后厨。 - **[[全栈]]**｜前后端都会做｜又当厨师又当服务员。 - **[[框架|Framework]]**｜别人搭好的半成品结构｜盖楼用的预制件。 - **[[开源]]**｜代码公开、可免费使用/修改｜公开的菜谱，人人可用可改。 - **[[幻觉|Hallucination]]**｜AI 一本正经地编造错误信息｜自信地记错事的天才。 - **[[上下文工程]]**｜精心设计"发给模型什么信息"的手艺｜给助手准备恰到好处的资料包。 - **[[MCP]]**｜让 AI 应用连接外部工具的通用协议｜各种电器通用的插座标准。 --- ## 11. 知识树地图：概念之间怎么连 下面这张"关系网"是全书的**根系**——理解了连线，就能举一反三。（配套网站会把它渲染成可交互的图。） ``` ┌─────────────────────────────┐ │ 大语言模型 (LLM) │ │ 只会读字/写字，其余靠外围软件 │ └───────────────┬─────────────┘ │ 通过 ┌─────▼─────┐ │ API │──需要──▶ 模型供应商 / Token / Prompt缓存 └─────┬─────┘ │ 被谁调用 ┌──────────────┬─────────────────▼──────────────┬─────────────────┐ │ │ 主循环 (心脏) │ │ 上下文(记忆)◀──组装──┤ │ 驱动 ├──产出──▶ 流式响应 │ │ ┌─────▼─────┐ │ 上下文压缩 提示词工程 │ 工具系统 │──危险时──▶ 权限系统 ──▶ 沙箱 │ └───────────┘ └──────────────────────── 五层架构 ────────────────────────┘ │ 被谁造出来 ┌────────────────────────────────▼────────────────────────────────┐ │ 软件工程 / SDLC │ │ 需求(PRD) → 架构设计 → 编码 → 测试 → 部署 → 运维/迭代 │ │ ▲ ▲ ▲ ▲ ▲ │ │ 产品经理 架构师 前后端/AI QA DevOps │ │ │ │ 贯穿：版本控制 · 代码审查 · 自动化测试 · CI/CD · 文档 · 技术债 │ └──────────────────┬────────────────────────────────────────────┘ │ 用什么方式做 ┌──────────────────┼──────────────────┐ ▼ ▼ ▼ 传统软件公司 单人独立开发 AI Agent 时代 (流程+人海) (取舍+借力) (你的判断力 × AI 生产力) │ 副驾是 ▼ Claude Desktop ``` **几条最重要的"连线"含义**： - **LLM ──靠──▶ 五层架构**：模型只是"大脑"，是外围五层给了它超能力。 - **主循环 ──是──▶ 五层里的核心**：所有 agent 的共同心跳。 - **工具系统 ──必须配──▶ 权限系统**：给了手脚，就必须给刹车。 - **五层架构 ──被──▶ 软件工程 ──造出来**：技术产物是工程流程的结果。 - **软件工程 ──可用三种方式──▶ 传统/单人/AI**：同一套工程，三种资源配置。 --- ## 12. 结语：你现在站在哪，往哪走 读到这里，你已经拥有了一张**完整的地图**： 1. 你知道产品**长什么样**（五层架构）； 2. 你知道它**怎么被造出来**（SDLC + 软件工程心法）； 3. 你知道**谁来造、怎么协作、如何化解矛盾**（角色与协作）； 4. 你知道**三种时代三种造法**，尤其是如何用 AI 当副驾放大一个人的能力。 > **终极目标回到原点**：当你理解了各种 agent 的技术构造，又掌握了标准开发流程，你就具备了"从零指挥（人或 AI）造出一个类似产品"的能力。技术原理让你**看得懂、把得住关**；工程流程让你**做得成、做得久**。二者缺一不可。 **下一步建议**： - 回到本仓库的《[[Claude Code]] 工作原理深入版》和六个开源项目分析，带着"如果是我来造，这一层我会怎么实现"的问题重读一遍。 - 用 [[Claude Desktop]] 当副驾，真的动手把第 7 章的 MiniClaude MVP（问模型→改一个文件→先问我）跑起来——哪怕只有一百行代码。**造过一次，胜过读十遍。** --- *本教程为配套《claude code 源码分析》系列而作，面向编程零基础读者。所有 [[双括号词]] 均为知识树节点，将在配套网站中变成可点击的动态链接。*