从零搭建一个可落地的 AI 智能体平台：我的 aigent-dev 项目复盘

一个人、一个月、33 个迭代任务，把「LLM + 工具 + 循环」写成了一个带控制面 / 边缘节点 / 审批 / 观测的完整智能体系统。

为什么要做这件事

市面上大多数"Agent 教程"停留在一个 while 循环 + 几个 function call，跑个天气查询就结束了。但当我真的想让一个智能体帮我做事——定时提醒、跨设备执行、接入日历和推送、失败可回放——会立刻发现：单机脚本做不到，它需要的是一套系统。

于是我决定自己写一遍，从最小可运行的 Agent 核心出发，一步步长出一个可部署、可观测、可扩展的平台。项目叫 aigent-dev。

架构：三层开始，长成六层

最初的结构非常朴素，只有三层：

层	职责
Agent	调度循环，不关心具体 LLM 和工具
Provider	封装 Claude / Ollama 等 LLM 的 API 差异
Tool	定义能力并执行

用户输入 → LLM 思考 → 要用工具？ ─是→ 调用工具 → 结果喂回 LLM
                        │
                        否 → 返回最终回答

写到第 5 个任务我就意识到：一个真正要跑在设备上的智能体，光有 Agent 循环不够。它需要被调度、被监控、被重启、被审计。于是结构慢慢演化成：

src/aigent/
├── agent.py               # 核心调度循环
├── providers/             # Claude / Ollama 适配
├── tools/                 # 可插拔工具（计算、天气、知识库…）
├── control_plane/         # 控制面：任务分发、WebUI、移动端 OpenAPI
├── edge_agent/            # 边缘节点：设备侧运行时、注册、心跳
├── notifications/         # 邮件 / 企微 / 钉钉 / App Push
├── calendar/              # Google Calendar 集成
├── domain/                # 领域模型（任务、工件、审批）
├── application/           # 用例编排
└── infrastructure/        # 存储、消息、Redis 事件总线

这是一个典型的 控制面 + 边缘节点 架构：中心节点负责任务编排和策略，边缘节点真正执行，两者之间通过 WebSocket 长连接 + Redis 事件总线通信。

33 个任务，我踩过哪些坑

项目用任务驱动的方式推进——每个能力先写成 tasks/backlog/NNN-xxx.md 的任务卡，完成后归档到 tasks/done/。到今天已经完成 33 个任务。下面挑几个真正让我长见识的。

Task 005：任务路由 + 执行流式输出

最初以为"发任务"就是 HTTP POST 一下。真写下去才知道要处理：执行日志实时回传、中途取消、跨进程状态同步。最后用 SSE + 事件流 解决，所有阶段事件都打到同一条时间轴上，前端订阅一次就能播放整个执行过程。

Task 018：任务可靠性状态机

一个任务从 pending → dispatched → running → succeeded/failed 看起来很简单，但叠加上"边缘节点掉线"、"重试策略"、"人工干预"后就变成了一张图。我把状态机单独抽成模块，所有状态迁移必须经过一个函数，这样所有失败场景都能被单测覆盖。这是我第一次真正体会到"状态机不是过度设计，是必需品"。

Task 022：高风险任务审批流

智能体可以自动执行，但有些动作必须人类点头（删文件、发消息、调用付费 API）。我给任务加了"风险等级"字段，高风险任务会暂停并推送到审批队列，审批人通过 WebUI 或移动端确认后才继续。这让我意识到：Agent 的安全边界不是模型侧的 system prompt，而是架构侧的流程闸门。

Task 027：Redis 事件总线 + 跨实例分发

单机跑着舒服，但一旦部署多实例立刻裂开——任务被两个节点同时抢走，或者没人接。用 Redis Pub/Sub + 消费组重构了事件分发，任何实例都能接任务，执行结果也会广播回所有订阅方。这一步让系统从"演示代码"变成了真能扛并发的服务。

Task 032：策略驱动的风控与路由

把"什么任务走什么设备"、"什么任务需要审批"从硬编码改成了 YAML 策略文件。意味着后续加新规则不用改代码，运营同学直接改策略就能上线。这是我第一次在自己的项目里做"配置即代码"的分离，感受到了架构红利。

工程实践：我如何让一个人的项目不崩

任务卡驱动：每个功能都是一个 NNN-xxx.md 任务文件，包含目标、范围、验证方式、风险。AI 智能体（Codex / Claude）可以直接读任务卡执行。
自动化调度脚本：写了 scripts/automation/run-loop.ps1，支持 codex / claude / dual（双智能体交叉审查）三种模式，能持续轮询 backlog 自动执行。这本身就是个小型多 Agent 系统。
pytest 作为唯一真源：每次提交前 pytest 必须绿。测试现在有一百多条，覆盖状态机、事件总线、审批流、产物存储。
Review-as-a-role：在 CLAUDE.md 里明确规定了 AI 在仓库里的三种角色：Coordinator / Builder / Reviewer。这让我和 AI 协作时边界非常清晰——它是执行者，不是决策者。

我从这个项目里真正学到了什么

Agent 的难点不在模型，在调度。模型能力这两年提升得够快，真正卡住落地的是：任务怎么发、状态怎么同步、失败怎么兜底、人怎么介入。
控制面 / 数据面分离是必然的。一旦你想跨设备、跨进程、跨时区地让智能体做事，这套架构就不可避免地长出来。
配置化是放大器。策略文件、任务模板、通知渠道，一旦抽象成可配置，系统承载的业务密度会指数级上升。
和 AI 协作开发本身就是一门工程。写清任务卡、定死角色边界、用测试当合约，这些不是教条，是让 AI 产出可用的唯一方式。

下一步

接入向量检索，让 Agent 能"记住"历史任务
产物文件做多版本 diff
把边缘节点打包成可独立分发的 MSI / PKG
写一个可视化的策略编辑器

项目技术栈：Python 3.11、FastAPI、Redis、WebSocket/SSE、pytest、Ollama / Claude API 仓库规模：33 个任务 / 100+ 测试 / 控制面 + 边缘节点双端架构 开发方式：单人 + AI 协作（Claude Code + Codex 双智能体循环）

如果你也在做 Agent 相关的事，欢迎交流——我相信下一代软件的形态，就藏在这些"看起来还很粗糙"的智能体系统里。