去年启动了一个 AI Agent 项目，当时有不少同学一起参与学习和开发。经过这一年的技术演进，Agent 相关的技术栈也发生了不小的变化。因此，这次决定对项目进行彻底重构，使其能够跟上当前的技术要求。下面就来聊聊这个全新的项目——它是什么、如何设计、以及为什么值得关注。

项目背景与定位

什么是 Agent？

很多同学可能对 Agent 这个概念还有些模糊，不确定它与 AI、LLM 之间的关系。其实，这三者可以这样理解：

• AI（人工智能）是一个涵盖所有相关技术的总称，覆盖了当前整个行业的全部内容。
• LLM（大语言模型）即我们目前常用的 GPT、Claude、Deepseek、Qwen、Kimi 等模型，是核心的智能引擎。
• Agent（智能体）是在大模型基础上构建的应用，例如 Claude Code、Cursor、Manus、OpenClaw Hermes 等。

打个比方，LLM 就像大脑，聪明但无法动手；Agent 则为大脑配上了手脚口鼻眼，不仅能思考，还能真正执行任务。

我们要做一个什么样的项目？

去年第一版项目是一个 AI 面试官，应用范围较窄，主要用于优化简历、模拟面试、解答面试题。这次重构，计划打造一个通用的、能够对标当前主流 AI Agent 的项目，类似于 OpenClaw 小龙虾那样的架构。

不过，当前版本先采用控制台形式运行，类似于 Claude Code。暂时不接入飞书、钉钉等 IM 工具，但其功能与配置与 OpenClaw 完全一致：你可以与 AI 聊天、让它读写文档、配置 Skills、设置定时任务、通过 MCP server 发送消息……它是一款优秀的个人 AI 助理，而且更加轻量、成本更低。

语言与框架选型

这次依然选择 TypeScript 和 Node.js，这两项技术社区资源丰富，对前端开发者非常友好。框架上继续使用 LangChain 和 LangGraph，它们能够快速搭建和配置一个 Agent。

前端开发者为何要学习 Agent？

这有两方面原因：其一，学习 Agent 开发，能让你更深入地使用类似 Claude Code、Cursor 这类工具，因为它们的设计原理有很多相通之处。其二，它为转型成为 AI 工程师提供了可能。这个项目几乎覆盖了 Agent 开发的所有必备技能，能帮助你从零到一打造出优秀的产品。

AI Agent 架构设计

去年第一版基于一个开源项目二次开发，本质上还是 AI Chat 的形式。这次重构，完全从零搭建，涵盖了当前 AI Agent 的所有核心技术模块：tools、skills、memory、context、permission、subagent、session、command、hook、MCP-server……如今 Agent 的技术体系已经相对稳定，Claude Code、Cursor、OpenClaw 都遵循类似的模式。

LLM 大模型

LLM 大模型是一切的基础，所有的决策、每一步的推理与执行都需要经过它。一个优秀的 Agent 应该兼容所有常见的大模型 API，至少需要支持国内和本地的模型接口。

查询引擎（Query Engine）

有了 LLM 接口后，每步请求还需要单独封装一个引擎，需要考虑很多细节：

• Stream 流式输出，模拟打字效果。
• Abort 取消接口，出错时能及时停止。
• Error 错误处理，例如网络错误、接口错误。
• Retry 自动重试，遇到错误尝试两三次。
• Limit 限制，比如调用的频率限制，以及上下文的 Token 数量限制。

例如，用户发送一个请求，AI 流式输出回复，中途可以按 ESC 取消请求。整个流程就是这样。

ReAct Agent

ReAct = Reasoning（推理） + Action（执行）。边推理边执行，是当前 Agent 的基础流程。其工作机制大致如下：

• 用户发送信息，请求发送给 LLM。
• 检查 LLM 的回复，是否需要调用工具（Tool）？
• 如果不需要，说明已经是最终答案，直接回复用户。
• 如果需要，调用工具取得结果，再发送给 LLM。
• 回到第二步继续判断。

因此，只要有 LLM 和工具，再加上这个流程，一个最基本的 Agent 就成型了。

工具（Tools）

前面提到，ReAct Agent 的基础版本就是 LLM + Tools。LLM 是大脑，Tools 是手脚。一个通用的 Agent 至少要内置以下工具：

• read_file 读取文件
• write_file 新建或重写文件
• exec 执行 Shell 脚本
• web_search 搜索引擎
• web_fetch 下载网络资源
• run_python 运行 Python 脚本

这些是最基础的，没有它们 Agent 无法正常运行。而且，Tools 会贯穿全局，后续的功能、MCP server 扩展，核心都是这套机制。

技能（Skills）

一个 Skill 就是一本技能手册，Skills 是 Agent 的知识库和技能包。AI 会根据主题选择相关的技能，按照指导进行回答，这样回复质量更高、更符合要求。更巧妙的是，Skill 的文本就能定义工作流，LLM 能够很好地理解。2025 年之前大家还在靠画流程图，那确实很麻烦。这次重构的项目原生支持 Skills，你可以安装第三方 Skill，也可以创建自己的 Skill。

会话（Session）

之前的项目是传统的 AI Chat 界面，左侧是对话列表，右侧是聊天区域。重构后不再采用这种形式，而是使用斜杠命令（Slash Command）进行管理，与 Claude Code 一致。例如 /new 开启新会话，/sessions 查看最近 20 条历史对话，/rewind xxx 回到某个历史节点。

上下文（Context）

默认情况下，每次向 AI 发送请求时，Agent 会把当前所有聊天记录都发送过去。这很容易导致上下文变得臃肿，引发 AI 幻觉、Token 用量大、成本高。因此，一个优秀的 Agent 必须配备上下文压缩机制，而且不能简单粗暴地裁剪或让 AI 总结，需要结合具体情况分析。

重构后的项目设计了 4 层压缩机制：

• 压缩工具输入：内容过多时，存储到硬盘上，只给 AI 文件地址，需要时再读取。
• 压缩聊天记录中的工具消息：这些消息冗余信息多，要简化。
• 压缩整个会话：让 AI 总结核心内容，但带有要求和模板，不是随意发挥。
• 裁剪聊天记录：保底行为。

例如，当上下文内容超过 80% 时，会自动开启压缩，并提示你使用 /new 开启新会话。

PS. 上图是为了测试，把 token limit 设成了 4000。测试完会还原为默认的 256,000。

记忆（Memory）

一名合格的个人 AI 助理，必须具备记忆能力。比如，你告诉它“我叫双越，我是一名程序员”，它需要记住你的姓名和职业，还要记得你最近做的事和个人习惯。

重构后的项目设计了 3 层记忆，这也是其他开源 Agent 的常见做法：

• 短期记忆：当前会话的记忆，即上下文内容。
• 长期记忆：跨会话的记忆，会记录一段时间，但会随时间推移而衰减。
• Profile：记录用户画像。

权限（Permission）

记得 OpenClaw 火爆的时候，很多人担心安全问题，不敢安装在自己的电脑上。Agent 确实存在安全隐患，任何软件都无法保证 100% 绝对安全。但我们可以尽量保证绝大多数场景的安全，拦截危险操作和危险目录。

具体做法是，为所有工具设置权限级别：read、write、exec、network、db。安全级别低的（如 read、network）可直接执行；安全级别高的需要其他防护措施。

然后判断当前操作的文件或目录是否为系统敏感文件或目录。如果是，直接拒绝。如果不是，再检查是否在当前目录内。不在当前目录，就征求用户同意。

执行的 Shell 脚本也需要判断是否为危险命令，比如 rm -rf /，如果是则直接拒绝。Agent 安全防护流程分为四个阶段：

阶段 1（Bash 预检）→ 阶段 2（Deny 规则）→ 阶段 3（Allow 规则）→ 阶段 4（Ask）

例如，如果试图让其读取系统敏感文件，它会提示无法读取。

钩子（Hook）

Permission 的规则是固定的，内置在项目中，无法直接修改。Hook 就是让用户自定义权限规则的方式，你可以在各种时机定义自定义规则。例如，在调用工具前，可以定义哪些文件不能被操作（如 .env）。或者在会话开始前，为聊天内容添加一些信息。

OpenClaw 社区里最火的 Skill 叫 self-improving-agent，它正是利用 Hook 来集成内容的。这说明 Hook 已经是 Agent 的必备模块。

子智能体（SubAgent）

聊天内容一旦过多、过乱，上下文就容易超过 Token 限制，也容易产生幻觉。解决方法之一就是用 SubAgent 执行独立任务。SubAgent 的上下文与主 Agent 完全隔离，不会影响主 Agent 的上下文大小。因此，SubAgent 也是 Agent 项目的必备能力。

例如，你可以启动一个 SubAgent，让它去完成一项任务，无论它怎么做，最后告知结果即可。

其他功能

除了核心模块，还有一些辅助功能。比如，Agent 需要能够配置 MCP server 来扩展第三方能力。但 MCP server 也有局限，它会导致 Agent 请求 AI 接口时携带大量 Tools，影响效率和成本。目前很多人也在对比 MCP server 和 Skills+CLI，后者正在社区中被推广。

斜杠命令（Slash command）也是常见功能，例如前面提到的 /new、/rewind、/sessions、/compact。

顺便提一句，RAG（检索增强生成）和向量数据库在当前 Agent 设计中的重要性有所降低。主要原因是成本较高，在个人使用场景下，有其他方式可以替代。

另外，因为是本地运行的 Agent，它天生就能读取本地文件（文档、表格、图片等），只要 LLM 支持就不成问题。后续也会考虑支持语音输入等高级功能，提升用户体验。

总结

浅层学习看输入，深入学习看输出。无论阅读多少文章和视频，都只是皮毛，看完就忘。只有从零开始逐步将这些内容实现出来，才是真正理解 AI Agent，才有机会进入这个领域。这条路，值得走下去。