从零构建 AI 智能体协作系统我做 TraceOne 的 15 天实战复盘15天一个从 0 到 1 的 AI 智能体协作平台踩过的坑、趟过的雷、总结的教训都在这里了。引言为什么要做一个奇怪的东西事情要从一个月前说起。那天我像往常一样和 AI 对话让它帮我写代码。写着写着我突然意识到一个问题我同时在和好多个 AI 助手对话。Trae 帮我写代码Claude 帮我 ReviewGPT 帮我查资料还有一个专门的 AI 帮我优化 Prompt每个 AI 都有擅长的领域但它们之间无法沟通。我想如果有一个系统能够让不同的 AI 像团队成员一样协作有明确的分工和流程能够记住上下文和历史能够自我学习和进化同时还能帮我不断的创造智能体当初定了一个奇怪的数字200 个会不会很酷于是TraceOne项目就这么开始了。一、技术选型为什么不用现成的1.1 市面上的方案调研在开始之前我调研了市面上的主流方案方案优点缺点LangChain/LangGraph功能强大生态成熟学习曲线陡峭定制困难AutoGen多智能体协作能力强架构重部署复杂CrewAI上手简单定制化程度低n8n可视化工作流不是为 AI 设计的调研一圈下来我发现一个尴尬的事实没有现成方案完全满足我的需求。我需要的是一个轻量级、可定制、能自我进化的系统。说到底最合适的方案往往是自己写的方案。1.2 最终技术栈经过权衡我选择了这样的技术栈核心框架Next.js Prisma TypeScriptAI 集成Trae对话 MCP工具扩展工作流编排自定义 JSON 流程定义存储SQLite开发→ PostgreSQL生产部署Docker Colima你没有看错我没有用 LangGraph。原因很简单当时的 LangGraph 安装失败了网络问题于是我被迫用原生 Python 实现了自己的图结构。后来发现这个被迫反而成了优势——我对整个工作流系统有了完全的控制权。二、架构设计从能用到好用2.1 三层架构设计整个系统分为三层┌─────────────────────────────────────────────┐ │ Agent Layer智能体层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Architect│ │ Backend │ │ Frontend│ │ │ └─────────┘ └─────────┘ └─────────┘ │ ├─────────────────────────────────────────────┤ │ Framework Layer框架层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Skills │ │ Workflow│ │ Memory │ │ │ └─────────┘ └─────────┘ └─────────┘ │ ├─────────────────────────────────────────────┤ │ Infra Layer基础设施层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Trae │ │ DB │ │ MCP │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────┘Agent Layer是最顶层负责具体任务的执行。我定义了 12 种智能体architect- 系统架构设计backend-engineer- 后端开发frontend-engineer- 前端开发devops-engineer- 运维部署qa-engineer- 质量测试business-analyst- 业务分析product-manager- 产品设计team-coordinator- 团队协调session-logger- 会话记录search-agent- 信息检索ui-ux-designer- UI/UX 设计permanent-memory- 永久记忆Framework Layer是核心包括Skills 系统可插拔的能力单元Workflow 引擎自定义的流程编排Memory 管理短期会话 长期记忆Infra Layer是基础设施连接外部服务。2.2 核心模块详解2.2.1 Skills 系统这是我认为最有价值的创新。每个 Skill 是一个独立的能力单元包含skill: name: 图像生成 version: 1.0.0 description: 调用 ModelScope API 生成图像 scripts: - generate_image.py triggers: - keyword: 生成图片 - keyword: 画一个 parameters: - name: prompt type: string required: true - name: size type: string default: 1024x1024这个设计的核心思想是技能即函数配置即代码。任何时候我只需要写一个 Python 脚本定义一个 SKILL.md 配置文件系统自动加载即插即用你会发现这个设计比 Dify 的工作流更灵活比 n8n 的节点更轻量。2.2.2 Workflow 引擎最开始我用的是简单的 JSON 配置{ workflow: article-creation, steps: [ {id: 1, name: 热点搜索, tools: [mcp-search]}, {id: 2, name: 选题策划, tools: []}, {id: 3, name: 内容创作, tools: [claude]}, {id: 4, name: 配图生成, tools: [generate_image.py]}, {id: 5, name: 发布同步, tools: [sync_to_obsidian.py]} ] }但后来发现一个问题有些步骤是并行的有些是串行的有些是条件分支的。这让我萌生了引入 LangGraph 图结构的想法。不过由于安装失败我用 Python 字典实现了一个简化版的状态机class WorkflowState: def __init__(self): self.data {} self.current_step 0 self.history [] def transition(self, next_step): self.history.append(self.current_step) self.current_step next_step def can_proceed(self, condition): # 条件判断逻辑 pass虽然简单但足够用了。最大的感悟不要追求完美的架构先解决眼前的问题。过度设计是最大的浪费。2.2.3 Memory 体系这是 TraceOne 最独特的模块。我设计了三级记忆体系级别存储内容生命周期技术实现短期记忆当前对话上下文对话结束JSON 文件中期记忆任务会话历史30 天SQLite长期记忆技能、知识库永久JSON 向量短期记忆很容易理解就是 Trae 的上下文窗口。中期记忆我用的是 SQLite存储每个任务的完整会话记录支持检索和回溯。长期记忆最有意思。我把所有经验都存成了结构化 JSON{ skill: session-logger, version: 2.0.0, capabilities: [会话记录, 任务追踪], usage_count: 156, success_rate: 0.94, learnings: [ 自动记录比手动触发更可靠, 索引结构影响检索效率 ] }每次执行完任务系统会自动更新这些经验。你会发现这套体系不需要向量数据库也能实现记住的效果。三、踩坑复盘那些让我睡不着觉的问题3.1 问题一API Key 管理症状部署到生产环境后发现 API 调用失败。排查检查日志发现是环境变量没有正确传递。根因本地开发时直接在 shell 里设置了环境变量但 Docker 容器里没有。解决# 使用 .env 文件 cp .env.example .env # 编辑填入真实的 API Key # Docker Compose 中加载 services: app: env_file: - .env教训不要假设环境配置是一致的。从第一天起就做好环境管理。3.2 问题二数据库连接超时症状部署到 Colima 后Prisma 查询经常超时。排查本地 SQLite 正常Docker 容器内连接超时根因Colima 的网络模式导致容器访问宿主机数据库性能差Prisma 的连接池配置不合理解决// prisma/schema.prisma datasource db { provider postgresql url env(DATABASE_URL) // 增加连接池大小 schemas [public] } // 在代码中优化连接 const prisma new PrismaClient({ datasources: { db: { url: process.env.DATABASE_URL ?connection_limit5 } } })教训开发环境和生产环境的差异是最大的坑。尽早用 Docker 模拟生产环境。3.3 问题三Skill 脚本路径错误症状调用生图脚本时返回文件不存在。排查日志显示路径是./scripts/generate_image.py但实际文件在/app/scripts/generate_image.py。根因工作流配置用的是相对路径但执行环境的工作目录不一致。解决# 使用绝对路径 SCRIPT_DIR Path(__file__).parent IMAGE_SCRIPT SCRIPT_DIR / scripts / generate_image.py教训路径问题是最低级但最常见的错误。统一使用绝对路径或者在入口处统一处理路径。3.4 问题四并发冲突症状多个任务同时执行时出现数据竞争。根因SQLite 不支持真正的并发写入。解决短期方案使用文件锁长期方案迁移到 PostgreSQLimport filelock lock_file /tmp/workflow.lock with filelock.FileLock(lock_file): # 执行任务 execute_workflow(task)教训并发问题是隐藏最深的雷。不并发测试永远不知道。四、经验总结从做了什么到学到了什么4.1 技术层面1. 不要过度追求完美架构TraceOne 的架构改了三轮。第一轮纯 JSON 配置第二轮引入状态机第三轮抽象出 Skills 系统每次重构都有充分的理由但每次都发现之前的方案其实够用了只是我想更好。现在我学乖了先解决能用再追求好用最后才考虑扩展。2. 日志是最好的调试工具这一个月我写了大量的日志代码import logging logger logging.getLogger(__name__) def execute_step(step): logger.info(f开始执行步骤: {step[name]}) try: result run_tool(step[tool]) logger.info(f步骤完成耗时: {result[duration]}ms) return result except Exception as e: logger.error(f步骤失败: {str(e)}) raise事实证明这些日志帮我解决了 80% 的问题。3. 配置即代码但配置不要太复杂我的工作流配置从 JSON 变成 YAML最后变成 Python 类。但我现在发现JSON/YAML 更适合非开发者理解Python 更适合复杂逻辑。现在的策略是简单配置用 JSON复杂逻辑用 Python不要为了优雅而过度抽象4.2 产品层面1. 先定义最小可用产品TraceOne 一开始想做的太多多智能体协作工作流编排记忆系统自我进化插件市场做了三个月其实只有一个功能真正稳定会话记录。我现在会这样思考MVP 核心功能 × 80% 质量核心功能是用户最常用的 20%80% 质量意味着能用但不完美2. 用户反馈是最好的需求来源我有三个反馈渠道自己的使用感受日志中的错误统计读者的评论和私信最有价值的是第三个。你永远猜不到用户会用你的产品做什么。4.3 团队协作层面1. AI 辅助开发的最佳实践这一个月我 90% 的代码都是 AI 写的。但我也总结了 AI 的局限性不知道项目的整体架构容易写出看起来对但跑不起来的代码不擅长处理复杂的边界条件我的做法是AI 负责实现具体的函数我负责设计整体架构AI 负责写测试我负责改测试2. 文档是最好的知识管理TraceOne 的文档比代码还多AGENT.md - 智能体定义SKILL.md - 技能定义WORKFLOW.md - 工作流定义README.md - 项目说明但我现在发现最好的文档是代码本身。与其写长篇大论不如函数名起得清晰注释写得精准类型定义完整五、后续规划下一步做什么5.1 短期目标1-2 个月完成会话记录的自动分类增加 Skill 市场的探索优化工作流的图结构5.2 中期目标3-6 个月引入真正的 LangGraph实现多智能体的并行协作增加插件系统5.3 长期目标6-12 个月探索自我进化能力建立开发者社区开源核心模块结语做一个奇怪的东西是什么体验答案是痛并快乐着。痛在于你永远在踩坑永远在解决问题。快乐在于每一个坑都是学习的机会每一次解决都是成长。如果你也想做一个奇怪的东西我的建议是先开始再完美。TraceOne 从一个简单的想法走到现在用了 15 天。这 15 天里我踩过的坑、趟过的雷、总结的教训都在这篇文章里了。希望对你有帮助。互动时间你在开发 AI 应用时踩过哪些有趣的坑欢迎在评论区分享我们一起交流。如果觉得这篇文章对你有帮助欢迎点赞、收藏、转发。关注我后面会出更多技术实战干货。本文是 TraceOne 项目实战复盘记录于 2026 年 3 月。