全文精简复习版（速查表）

面向小白的Agent开发核心知识总览，建议收藏随时查阅

📋 全文知识点速查表

模块	核心功能	关键概念/操作	小白记忆口诀
Agent概念	智能体/数字员工的基本原理	技能+记忆+模型三要素	会干活、有记忆、会思考
主Agent	Claude Code本身，总负责人	路由决策、派活给下属	公司CEO，啥都管
Sub Agent	子代理，专项数字员工	独立上下文、并行运行	部门专家，专干一件事
单元测试技能	自动检验每个函数对不对	unit-test技能、Vitest框架	每个零件单独质检
测试专家	专门做单元测试的数字员工	tester Sub Agent	质检部门主管
注释检查技能	检查代码注释够不够、准不准	comments-check、3:7比例	检查说明书写全了没
安全审计技能	检查代码有没有安全漏洞	security-audit、五大维度	安全检查员
质量工程师	综合质量检查的数字员工	quality Sub Agent、双技能+内置	质量总监，全面检查
Hook钩子	拦截工具调用，加前置条件	pre_tool_use、settings.json	安检门，没票不让进
质量门禁	提交代码必须过测试和质检	通行证机制、一次性使用	双证齐全才能存档

---

一、Agent基本概念与单元测试技能开发

1.1 知识点汇总表

知识点	作用说明	类比理解
Agent智能体	由技能、记忆、模型三者组成的数字员工	一个完整的虚拟员工
技能Skills	决定Agent能干什么事	员工掌握的工作技能
记忆Memory	Agent的上下文对话和长期记忆	员工的工作记忆和经验
模型Model	Agent的大脑，负责思考决策	员工的智商和思维能力
主Agent	Claude Code本身，总调度者	公司CEO，总负责人
Sub Agent子代理	专注某一领域的专项数字员工	各部门专家，专干一件事
单元测试	单独验证每个函数功能是否正确	每个零件单独质检
测试用例	给函数指定输入和预期输出	考试题目，规定标准答案
测试报告	汇总测试通过/失败情况	考试成绩单
Vitest框架	React项目常用的单元测试工具	专用考试答题卡
/reload skills	重新加载技能，不用重启软件	刷新技能列表

1.2 什么是Agent？三要素搞懂智能体

所谓Agent（智能体/代理），本质上就是一个数字员工。它由三部分组成：

组成部分	作用	现实类比
技能Skills	决定这个Agent能做什么事，技能越多能力越强	员工掌握的专业技能，比如财务技能、编程技能
记忆Memory	Agent知道自己是谁、要干什么、之前发生了什么	员工的工作记忆和经验积累
模型Model	Agent的大脑，负责思考、决策、推理	员工的智商和思维能力

这三者缺一不可，组合在一起就形成了一个可以独立干活的数字员工。

1.3 主Agent vs Sub Agent：公司组织架构

Claude Code本身就是一个主Agent，相当于公司的CEO，什么都能管。但一个人精力有限，所以可以配置很多Sub Agent（子代理），每个子代理专注做一件事。

• 主Agent（CEO）：跟你直接对话，接收你的需求，判断该派给谁去做

• Sub Agent（部门专家）：专注某一领域，比如测试专家、安全专家、运维专家

• 路由决策：主Agent收到需求后，自动判断该叫哪个专家来干活

• 并行工作：主Agent可以同时派好几个专家一起干活，效率更高

小白理解：你是老板，Claude是总经理。你说"帮我做代码测试"，总经理不用自己干，他会叫测试部门的员工来干。你只需要跟总经理说话，具体谁来干、怎么干，总经理会安排。

1.4 单元测试：给代码做"零件质检"

单元测试是什么？用汽车工厂来比喻：

• 一辆汽车有几千个零件，每个零件都要单独检查合格了才能装车

• 软件项目有很多函数，每个函数就是一个"零件"

• 单元测试就是单独检验每个函数是否工作正常

单元测试三步走：

1. 创建测试用例：给每个函数出"考试题"——规定输入什么，预期输出什么

2. 执行测试：运行所有考试题，看函数能不能答对

3. 生成测试报告：汇总几个通过、几个失败、哪里出错了

举个例子：一个加法函数，输入5和6，必须输出11，否则就是有问题。

1.5 单元测试技能开发实操

小白开发技能完全不用自己写代码，一句话交给AI就行：

"帮我创建一个单元测试的技能，用来对代码创建单元测试、执行测试、给出测试报告。我不懂，先给我解释一下。"

AI会先给你解释概念，然后给出技术方案选择（比如方案A Vitest、方案B其他）。你选一个方案，AI就自动帮你生成完整的技能文件。

技能文件包含：

• 技能名称和用途描述

• 使用的技术框架

• 测试文件命名规则

• 完整执行流程步骤

• 编写测试的原则

• 示例代码（少样本学习）

创建完技能后，可以用 /reload skills 命令重新加载，不用重启软件。然后直接输入 /unit-test 就能用了。

实战效果：一个完整的记账App项目，AI可以自动生成124个测试用例，并且全部通过。代码质量好不好，跑一遍单元测试就知道。

---

二、测试专家数字员工（Sub Agent开发实战）

2.1 知识点汇总表

知识点	作用说明	存放位置
Sub Agent子代理	专项数字员工，独立运行	.cloud/agents/ 文件夹
技能 vs Sub Agent	技能是快捷指令，Sub Agent是独立专家	概念区别，见对比表
独立上下文	Sub Agent有自己的对话记忆，不跟主Agent串	避免记忆混乱
自动路由	主Agent自动判断该调用哪个Sub Agent	总经理派活
手动调用	也可以用 /agent 命令手动指定	直接点名找人
共享技能	所有Sub Agent共用技能库，告诉它能用哪些就行	公司工具库大家都能用
tester测试专家	专门负责单元测试的数字员工	调用unit-test技能
并行运行	多个Sub Agent可以同时干活	多部门同时开工

2.2 技能 vs Sub Agent：一次搞清楚区别

很多小白分不清技能和Sub Agent的关系，这张表彻底搞懂：

对比维度	技能Skill	Sub Agent子代理
调用方式	斜杠手动调用 /xxx	主Agent自动判断调用
本质	快捷指令模板，一段提示词	独立专家角色，有完整身份
上下文	在当前对话中执行	独立运行，有自己的上下文
能否并行	一次只能跑一个	可以多个同时跑
类比	快捷键、一键宏	专门的员工、部门专家
存放位置	.cloud/skills/	.cloud/agents/

关系理解：技能是"工具"，Sub Agent是"会用工具的人"。公司有一个工具箱（所有技能），每个员工（Sub Agent）可以被授权使用某些工具。员工干活的时候自己去工具箱里拿工具用。

2.3 独立上下文：为什么不会串记忆？

Sub Agent最大的特点就是有自己独立的上下文。什么意思呢？

• 你跟主Agent聊了很多内容，比如项目背景、之前的讨论

• 主Agent派Sub Agent去干活时，只告诉它"去做单元测试"

• Sub Agent看不到你和主Agent之前的全部聊天记录

• 它只专注干自己那一件事，干完把结果回报给主Agent

这样做的好处：

• 记忆不串扰：每个专家只知道自己该知道的，不会被无关信息干扰

• 节省上下文：不用把全部历史都塞给每个专家，更高效

• 职责清晰：各司其职，测试专家就只管测试，不管别的

2.4 创建测试专家Sub Agent实操

还是一句话搞定，小白完全不用写代码：

"帮我创建一个Sub Agent，名字叫tester，专门用于单元测试，可以使用 /unit-test 技能。用户有单元测试需求时都可以调用这个Sub Agent。"

AI会自动帮你：

1. 创建 .cloud/agents/ 文件夹

2. 生成 tester.md 描述文件

3. 写清楚身份、职责、可用技能、工作方式、输出规范

Sub Agent描述文件内容：

• 你是谁（单元测试专家）

• 你能做什么（创建测试、执行测试、出报告）

• 你的工作方式（调用unit-test技能）

• 你的技术栈（Vitest、React、TypeScript）

• 重要规则（测试覆盖率、命名规范等）

• 输出格式要求

全部都是自然语言描述，不用写代码！

2.5 效果验证：自动派活

创建完重启一下，然后你只需要说：

"帮我执行一下单元测试"

主Agent收到需求后，会自动判断："这是测试的活，应该叫测试专家来干"，然后自动把任务派给 tester 这个Sub Agent。你会看到：

• 提示"测试任务委派给 tester sub agent 执行"

• 然后就是测试专家在干活，输出测试过程

• 测试完成后，结果回到主Agent这里

整个过程你完全感觉不到中间有个"派活"的步骤，就像直接跟主Agent说一样自然。但背后其实是专业的测试专家在干活。

---

三、质量工程师数字员工（双技能整合）

3.1 知识点汇总表

知识点	作用说明	检查维度
注释检查技能	检查代码注释的数量和质量	覆盖率、准确度、小白可读性
安全审计技能	检查代码中的安全隐患	敏感信息、注入、配置、桌面安全等
质量工程师	综合质量检查的数字员工	双技能+内置质量检查
注释覆盖率	注释行数占总代码行数的比例	建议3:7（3成注释）
敏感信息泄露	代码里写死了密码、密钥等	硬编码密码、API密钥
SQL注入	恶意用户通过输入篡改数据库	不安全的SQL拼接
XSS跨站脚本	注入恶意脚本攻击用户	不安全的HTML渲染
错误处理	异常情况有没有try-catch	异步、数据库、文件操作
类型检查	TypeScript类型是否规范	滥用any、不必要的断言
质量评分	综合打分，直观展示代码质量	安全分、注释分、质量分

3.2 注释检查技能：代码说明书够不够？

注释就是代码的"说明书"。小白看不懂代码，但能看懂中文注释。注释检查技能帮你检查三件事：

检查维度	检查什么	为什么重要
注释覆盖率	注释够不够多，比例是否达标	代码多、注释少，以后看不懂
内容准确度	注释说的和代码做的对不对得上	注释写错了比没注释还坑人
小白可读性	是不是用大白话写的，技术小白能看懂	方便自己以后维护代码

推荐比例：十行代码中，三行注释、七行代码（3:7比例）。当然这个可以自己调，不用太苛刻。

3.3 安全审计技能：代码有没有安全漏洞？

安全审计检查五大维度，都是常见的安全坑：

1. 敏感信息泄露：代码里有没有写死密码、API密钥、数据库地址

2. SQL注入风险：数据库查询有没有用字符串拼接，容易被黑客攻击

3. 配置文件安全

4. 桌面应用安全（Electron专属）：桌面程序的安全配置

5. 其他常见隐患：

   1. XSS跨站脚本攻击

   2. 不安全的随机数

   3. 危险的eval动态执行

   4. 用户输入没有校验

   5. 敏感数据明文存储

小白须知：AI写的代码功能没问题，但安全方面经常偷懒。比如密码直接写死在代码里、用户输入不校验。这些问题平时看不出来，但上线后会被黑客利用。所以安全审计非常有必要！

3.4 质量工程师：一个顶俩的数字员工

有了注释检查和安全审计两个技能后，我们把它们打包成一个质量工程师Sub Agent。

这个质量工程师除了会用两个技能，还自带内置的质量检查：

• 错误处理检查：异步函数、数据库操作、文件读写有没有加try-catch异常捕获

• 类型检查：有没有滥用any类型、不必要的类型断言

• 重复代码检查：有没有大段复制粘贴的重复代码

• 输入校验：用户输入的数据有没有做合法性检查

创建方式还是一句话：

"帮我开发一个Sub Agent，名字叫质量工程师quality，可以使用安全审计和注释检查两个技能，主要完成上述两个维度的审查，以及你认为合理的其他质量方面的检查。"

3.5 质量报告与自动修复

运行质量审查后，会输出一份质量报告，包含：

• 综合评分：比如61分（满分100）

• 安全分项：几个问题，有没有高危

• 注释分项：覆盖率多少，达标了吗

• 代码质量分项：有几个问题

• 问题清单：每个问题在哪、是什么、严重程度

发现问题后，直接跟AI说"帮我修复注释问题"或者"帮我修复这些质量问题"，AI就会自动帮你补全注释、修复代码。修完可以再跑一遍质量检查，直到分数满意。

小白心法：你不用懂怎么修，你只需要说"修一下"。AI知道怎么改，改完你再检查一遍分数就行。

---

四、Hook钩子拦截与Git提交质量门禁

4.1 知识点汇总表

知识点	作用说明	类比理解
Hook钩子	拦截工具调用，在执行前后插入自定义逻辑	安检门，过门前先检查
pre_tool_use	工具调用前触发的钩子	进门之前先安检
质量门禁	提交代码前必须通过测试和质检	双证齐全才能存档
通行证机制	通过检查后生成标记文件作为凭证	考试合格发合格证
一次性通行证	提交成功后立即删除，防止重复使用	门票用一次就作废
git-commit-agent	专门负责提交代码的编排Agent	安检主管，统一安排流程
并行检查	单元测试和质量检查同时跑	两个安检口同时检查
settings.json	hook配置存放的文件	安检规则手册
Agent型Hook	用模型判断是否放行，比脚本更灵活兼容	人工安检比机器安检更智能

4.2 什么是Hook钩子？安检门的原理

Hook（钩子）就是一种拦截机制。可以在工具执行前、执行后、执行失败时，插入你自定义的逻辑。

最常用的是 pre_tool_use（工具调用前）钩子：

• 当AI要执行某个命令时，先被钩子拦下来

• 钩子执行你的检查逻辑

• 检查通过 → 放行，正常执行命令

• 检查不通过 → 拒绝，命令不执行

就像地铁站的安检门：你想进站，先过安检，包里没问题才能进，有违禁品就给你拦下来。

4.3 质量门禁需求：不能随便提交代码

我们的目标：代码不能随便存档，必须通过单元测试和质量检查才能提交。

为什么要这样？

• Git存档点应该是"稳定版本"，以后要回退的

• 如果存了一个有Bug的版本，以后回退回去也是坏的

• 加个门禁，确保每个存档点都是经过检验的好版本

整体架构设计：

组件	职责
测试专家	跑单元测试，通过了发"测试通行证"
质量工程师	跑质量检查，通过了发"质检通行证"
Hook安检门	拦截git commit，检查两个通行证是否齐全
提交主管Agent	安排流程：先并行跑两个检查 → 拿到通行证 → 触发提交 → 销毁通行证

4.4 通行证机制：一次性合格证

怎么证明通过了检查？用通行证文件：

• 测试专家跑完单元测试，如果全部通过，就在项目里写一个文件，内容是"pass"

• 质量工程师跑完质检，如果达标了，也写一个文件，内容是"pass"

• 这两个文件就是"通行证"

• Hook拦截git commit时，去读这两个文件，如果都是pass就放行

• 提交成功后，立即删除这两个通行证文件

为什么要删除？：通行证是一次性的。这次提交用了就作废，下次提交必须重新跑测试、重新质检，重新发新的通行证。防止拿旧的合格证蒙混过关。

4.5 git-commit-agent：提交主管的工作流

为了方便使用，我们创建一个专门负责提交代码的 git-commit-agent，它是一个编排者，工作流程是：

1. 清理旧通行证：先把上次的合格证删掉，防止作弊

2. 并行启动检查：同时叫测试专家和质量工程师开工

3. 等待检查完成：两个专家各自干活，互不干扰

4. 生成通行证：检查通过就发合格证

5. 执行git提交：提交命令被Hook拦截，检查通行证

6. Hook检查放行：两个pass都有，允许提交

7. 销毁通行证：提交成功，删掉两个合格证

这样你只需要说"帮我提交代码"，git-commit-agent就会自动把整套流程跑完。

4.6 Hook配置与实现方式

Hook配置写在 .cloud/settings.json 文件里。实现方式有两种：

方式一：脚本型Hook

写一个shell脚本或PowerShell脚本，Hook触发时执行脚本，脚本检查文件返回结果。优点是快、确定；缺点是Windows环境兼容性差，路径、编码、中文都容易出问题。

方式二：Agent型Hook（推荐）

不用写脚本，直接给AI一段提示词，让模型来判断通不通过。Hook触发时，AI读取通行证文件，用模型判断内容是不是pass。

优点：

• 跨平台兼容性好，Windows/Linux/Mac都能用

• 更灵活，可以处理复杂判断逻辑

• 不用写脚本代码，自然语言描述就行

课程实战经验：最开始用shell脚本，Windows下各种报错，改了PowerShell还是有问题，最后改成Agent型Hook才稳定运行。小白直接用Agent型就行，省心。

4.7 拦截规则匹配细节

一个容易踩的坑：Hook的匹配规则。

最开始写的规则是"匹配 git commit 开头的命令"，但实际AI执行的是组合命令 git add . && git commit ...，不是以git commit开头，所以匹配不到，Hook不触发。

正确写法：用通配符 *git commit*，只要命令中包含git commit就触发拦截。

4.8 调试心得：AI也需要反复迭代

配置Hook的过程不是一次成功的，中间经历了：

• 脚本环境不兼容 → 换脚本语言

• 路径有中文编码问题 → 改编码

• 匹配规则不对 → 改用通配符

• 脚本写在JSON里转义混乱 → 拆成独立文件

• 最终改用Agent型Hook才稳定

重要认知：AI也不是一次就能写对的。就像人第一次检查可能漏了问题，第二次检查又发现新问题。这是大模型的概率性特点，很正常。发现问题就让AI修，修完再验证，反复迭代直到稳定。

4.9 最终效果：全自动质量门禁

全部配置好之后的效果：

1. 你说"帮我提交代码"

2. 自动并行跑单元测试 + 质量检查

3. 如果有问题，自动修复，修复完重新检查

4. 两个检查都通过了，才允许git提交

5. 提交成功后自动删除通行证

你完全不用管中间过程，只需要等结果。确保每一个Git存档点都是经过检验的、质量达标的好版本。

---

🎯 总结：Agent开发完整路线图

阶段	核心动作	产出物	达到的效果
第1步	理解Agent概念	三要素：技能+记忆+模型	知道数字员工是什么
第2步	开发专项技能	unit-test、comments-check、security-audit	工具箱里有了专业工具
第3步	装配数字员工	tester、quality两个Sub Agent	有了测试专家和质量专家
第4步	配置Hook门禁	settings.json + 通行证机制	提交代码必须过安检
第5步	编排流程Agent	git-commit-agent	一键跑完整套质量流程

数字员工	拥有的技能	职责
测试专家 tester	unit-test 单元测试技能	负责代码功能正确性检验
质量工程师 quality	comments-check + security-audit + 内置质量检查	负责注释、安全、代码规范全面质检
提交主管 git-commit-agent	编排前两位专家 + git-save技能	负责安排完整的质量门禁提交流程

小白终极心法：整个Agent开发过程，你不需要写一行代码。你只需要做三件事：

• 1. 用自然语言描述你的需求；
• 2. 跟AI讨论方案，确认设计符合你的想法；
• 3. 测试效果，发现问题就让AI修。你是产品经理，AI是开发工程师。你负责想清楚要什么，AI负责帮你实现。