AI Agent项目开发中踩过的5个坑

近期我们正在开发一款名为智语的 AI Agent（智能体）项目，定位为个人助手类智能体，功能上与 OpenClaw 小龙虾类似。它集成了 tools、skills、memory、context、permission、subagent、session、command、hook、MCP-server 等 Agent 核心能力。用户可以与它对话交互、读写文档、配置技能（Skills）、设置定时任务，甚至通过 MCP server 发送消息——几乎覆盖了个人助手的全部功能需求。

本文将分享我们在智语开发过程中遇到的实际问题与关键技术注意事项，希望能为正在探索 Agent 开发的同行们提供有价值的启发。

不要急于完善 Chat 功能

刚接触 AI Agent 开发的开发者，尤其是想快速搭建 demo 或项目时，很容易将主要精力投入到 Chat 聊天功能的打磨上。接入 LLM 接口、成功发送第一个请求后，便开始琢磨如何让聊天界面更炫酷。实际上在 Agent 开发中，Chat 功能远不如想象中关键——甚至可以说，Chat 并非 Agent 项目的核心组成部分，它更多是前端 UI 的职责。此前我们曾分享过文章《别再把 AI Agent 当作聊天机器人了》，详细阐述了 Agent 与 Chat 的本质差异，建议初学者首先厘清这一概念。

正确的方法是依据 Agent 架构设计进行模块拆分，将 Chat 作为独立模块，与 Agent 实现解耦。例如在智语项目中，功能模块划分清晰——Agent 包含各类智能体能力模块，但绝不包含 Chat 模块。

避免将 Skills 配置嵌入代码库

在最初设计 Skills 功能时，我们没有充分考虑用户实际安装与使用的场景，错误地将 Skills 配置直接嵌入代码库。甚至在构建时还会把 Skills 文件夹复制到 dist 目录——随后才意识到这完全不可行。试想，用户安装一个新 Skill，怎么会去触碰你的代码库呢？

因此我们借鉴了 OpenClaw 小龙虾的做法：创建独立的工作空间目录 ~/.zhitalk，将所有配置存放于此。现在 Skills 存储在工作空间中，分为两个目录：

• 来自第三方的 Skill 安装后存放在 .agents/skills 目录
• 用户自行创建的 Skill 存放在 skills 目录

同理，MCP Server 和 Hooks 的配置现在也都统一放在工作空间目录的配置文件 ~/.zhitalk/zhitalk.json 中。

记忆存储：从 Markdown 到分层结构化方案

最初参考 OpenClaw 小龙虾时，发现它使用 memory.md 存储用户记忆，于是我们也想用单个 Markdown 文件记录所有记忆。但很快发现了这种方式的弊端：所有记忆混杂在一起，随着使用时间增长，管理变得愈发困难。

记忆应该分层，不同层级管理不同的内容：

• 短期记忆（short-term memory）：仅在当前 session 有效
• 长期记忆（long-term memory）：跨 session 持久化
• 个人信息（profile）：全局生效

针对长期记忆，我们最终选用 SQLite 这类结构化数据库存储，方便进行增删改查操作。

Context 压缩策略：避免粗暴截取

每次调用 AI 接口时，如果上下文（Context）过大，会引发诸多问题——这一点之前在博客中多次提及。一个成熟的 AI Agent 必须具备 Context 压缩能力，否则随着对话记录增多，上下文会无限膨胀。许多初学者的压缩方法简单粗暴：仅截取前 xx 条消息。尽管高效，但会丢失大量历史信息，直接影响短期记忆效果。

智语项目设计了 4 层 Context 压缩机制，再配合记忆功能，几乎不会有内容丢失：

1. 压缩 tool 输出并持久化 tool output
2. 压缩 tool message
3. 超过 80% 时压缩整个 Context
4. 超过 300 条 message 再截取

你可以调用 /compact 命令手动触发压缩，也可以等 Context 使用量超过 80% 时由系统自动压缩。

权限设计：减少用户打扰

Agent 的权限与安全是开发中不可回避的问题，尤其在 tool 调用时，不能让 LLM 随意操作。一些初学者设计的权限方案就是不断向用户确认——但凡有一丝不确定，就弹窗询问。这种方法看似负责，实则严重影响用户体验，频繁打断操作。

智语项目里有一套比较详细的权限设计思路，总结下来是三种类型，核心原则是尽量少打扰用户：

• 危险操作直接拒绝，不打扰用户
• 安全操作直接执行，也不打扰用户
• 其他无法判断风险的操作，才交由用户确认

总结

AI Agent 开发并非一蹴而就，许多陷阱只有在实际编码中才会暴露。从 Chat 功能的合理定位、Skills 配置的正确方式、记忆存储的方案选择、Context 压缩的策略设计，到权限管理的用户体验优化，每个环节都需要仔细权衡。希望本文分享的这些实际踩坑经验，能助你少走弯路。