Universal Agent + Skills 教程:从零构建你的 10 人工程团队
Universal Agent + Skills 教程:从零构建你的 10 人工程团队
想象一下:
你对 AI Agent 说:"帮我写份技术文档",它立刻加载 technical-writer.skill,变身技术作家。
说完文档,你又说:"分析一下竞品的广告策略",它换上 marketing-analyst.skill,开始爬数据。
更酷的是,如果你需要一个特定领域的专家——比如"SQL 性能优化"——而市面上没有?让 Agent 自己写一个 skill 给自己用。
这不是科幻。实现起来,极其简单。
这篇文章会教你构建一个 Universal Agent:
- ✅ 加载任意技能 - 拖进去一个
.skill文件,Agent 立刻获得新能力 - ✅ 自己写技能 - Agent 可以为自己创建新的专业技能包
- ✅ 持久化工作 - 文件跨对话保留,上午写的代码下午继续改
- ✅ 零基础设施 - 不需要 Docker、K8s,一个 Next.js 项目就够
把它想象成组建一支 10 人的创始团队:每个技能就是一个专家,Agent 是项目经理,你是 CEO。
架构概览
核心组件:
bash-tool- 内存文件系统,支持 bash、readFile、writeFile- Skills 在
sandbox/user/{id}/skills/(只读,来自 S3) - Workspace 在
sandbox/user/{id}/workspace/(可读写,持久化) - AI SDK 处理流式响应、工具调用、token 统计
核心实现
1. Skill 结构
每个 skill 是一个 .skill 文件(zip 格式),结构简单:
SKILL.md 示例:
上传流程:用户上传 zip → 存储到 S3 → 数据库记录 → Agent 按需加载。
2. 路由处理器
文件:app/api/chat/universal/route.ts
关键点:
- 启动时加载 skills 和 workspace
- Skills 隔离在
skills/前缀下(只读) - Workspace 在根目录(可读写,持久化)
onFinish将所有变更写回磁盘
3. Workspace 持久化
文件:lib/skill/workspace.ts
工作流程:
- 加载:从磁盘读取所有文件到内存
- Agent 工作:在沙箱中创建/修改文件
- 保存:提取非 skill 文件,写回磁盘
- 下次请求:文件重新出现在沙箱中
4. System Prompt
文件:app/prompt/index.ts
关键设计:
- 技能用 XML 格式(Claude 原生格式)
- 清晰区分 workspace 和 skills
- 强调持久化行为
- 简单、可执行的指令
实战场景
场景 1:技术文档生成
场景 2:跨会话工作
场景 3:Agent 创建自己的技能
关键设计决策
1. 为什么选 bash-tool?
考虑过的方案:
- 直接文件系统访问 → 安全风险
- Code interpreter(Python)→ 太局限
- 完整 VM(@vercel/sandbox)→ 文件操作太重
bash-tool 的优势:
- 内存隔离沙箱
- 熟悉的 bash 命令(ls、cat、grep、find)
- 不执行脚本(安全)
- 完美适配文件操作 + 探索
2. 为什么分离 Skills 和 Workspace?
3. 为什么用完整同步而非增量?
理由:
- 实现更简单(无需变更跟踪)
- 自然处理删除(文件缺失 → 已删除)
- 性能:workspace 通常 < 100 个文件,同步很快
- 可靠性:避免同步漂移问题
4. 为什么技能用 Claude XML?
Claude 模型在训练时就使用 XML 结构处理工具和 artifacts。这种格式:
- Claude 训练原生支持
- 易于解析
- 可扩展(添加元数据不会破坏现有结构)
- Claude 技能发现时更熟悉
部署考虑
Docker 配置
挑战: bash-tool 使用原生模块(@mongodb-js/zstd、node-liblzma)做压缩。
解决方案: 不复制原生模块——它们是可选的。
next.config.ts:
存储管理
性能基准
基准测试(M1 Mac,50 个 skills,200 个 workspace 文件):
优化建议:
- 跨请求缓存 skill 文件(同一用户、同样的 skills)
- 大文件导出使用流式传输
- workspace > 1MB 时用 zstd 压缩
下一步
扩展系统:
- 版本控制:为 workspace 集成 Git
- 技能市场:用户间共享技能
- 协作工作空间:多个 agent,一个 workspace
- 技能组合:Agent 同时加载多个技能
- 技能继承:基础技能 + 专业化变体
核心理念: 每个用户都能成为拥有完整工程团队的创始人。每个技能就是一个专家。Agent 负责协调。Workspace 持久化。可能性无限。
代码参考
- 主路由:
src/app/(universal)/api/chat/universal/route.ts - Workspace 持久化:
src/lib/skill/workspace.ts - Skill 加载:
src/lib/skill/loadToMemory.ts - 导出工具:
src/app/(universal)/tools/exportFolder.ts - System prompt:
src/app/(universal)/prompt/index.ts - README:
src/app/(universal)/README.md
基于 Next.js 15、Vercel AI SDK、bash-tool 和 Claude 4.5 Sonnet 构建。