项目复盘与技术总结
13 个 AI Agent 项目，覆盖了从底层架构、前端交互、分布式协同到实时处理的完整链路。这篇文章是对这些项目的系统性复盘：每个项目解决了什么问题、做了哪些关键决策、踩了哪些坑、前端经验在 Agent 开发中到底有什么用。
一、项目全景地图
先画一张全景图，对整个 portfolio 有清晰的认知。
┌─────────────────────────────────────────────────────────────────────┐
│ 项目 portfolio 全景地图 │
│ │
│ ┌─── 核心 Agent 项目 ──────────────────────────────────────────┐ │
│ │ │ │
│ │ jojo-code Coding Agent（Python + LangGraph） │ │
│ │ agent-sse-flow SSE 流式可视化组件（React） │ │
│ │ smart-city-agent 多 Agent 协同（强化学习） │ │
│ │ behavior-sense 实时流处理引擎（Flink + 规则引擎） │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── 前端 Agent 生态 ──────────────────────────────────────────┐ │
│ │ │ │
│ │ Agent Skills 可复用 Prompt 模板库 │ │
│ │ Generative UI Agent 生成式界面实践 │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── 工具链与基础设施 ────────────────────────────────────────┐ │
│ │ │ │
│ │ xmind2md-mcp MCP Server 工具开发 │ │
│ │ Agent 测试框架 单元测试 + 集成测试 │ │
│ │ Prompt 工程体系 结构化 Prompt 设计 │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── 前端工程化积累 ──────────────────────────────────────────┐ │
│ │ │ │
│ │ 前端监控体系 Sentry + 自定义埋点 │ │
│ │ 微前端架构 qiankun 实践 │ │
│ │ 自动化测试 Playwright + 单元测试 │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
项目分层逻辑
整个 portfolio 可以分成四层：
- 核心 Agent 项目：技术深度所在，覆盖 Agent 架构、流式交互、多 Agent 协同、实时处理
- 前端 Agent 生态：体现前端转型的独特价值，Agent UI 和 Prompt 模板化
- 工具链与基础设施：展示工程化思维，MCP 工具开发、测试框架、Prompt 体系
- 前端工程化积累：基本功的体现，监控、微前端、自动化测试
每个项目解决的问题不同，但它们之间有递进关系——上一个项目发现的问题，往往是下一个项目的起点。
二、核心项目拆解
每个项目用统一的框架来复盘：背景（为什么做）、目标（解决什么问题）、行动（做了什么决策）、结果（产出和收获）。
2.1 jojo-code：从零实现 Coding Agent
这是技术含量最高的项目，也是整个 Agent 体系的起点。
背景
2025 年初，AI 编码工具爆发，Claude Code、Cursor、Windsurf 各显神通。但作为开发者，对这些工具的底层原理理解很浅——它们到底是怎么调用 LLM 的？怎么管理上下文窗口？怎么执行代码修改？市面上没有一个足够清晰的开源实现可以学习。
目标
从零实现一个轻量级的 Coding Agent，目标不是和商业产品竞争，而是彻底搞清楚 Coding Agent 的核心架构。要求：Python + LangGraph 状态机驱动，支持多轮对话、工具调用（文件读写、代码执行）、上下文管理、错误重试。
关键决策
- 架构选型：选了 LangGraph 而不是简单的 chain，因为 Coding Agent 本质是一个状态机——它需要在"思考-执行-观察-再思考"之间循环，LangGraph 的 graph 天然适合这种场景
- 上下文管理：这是最棘手的问题。LLM 的 context window 有限，但 Coding Agent 需要处理大量代码。实现了分层记忆策略——短期记忆存当前会话的工具调用结果，长期记忆存项目级的代码结构摘要，通过 LLM 自动压缩历史对话
- 工具系统：设计了可插拔的 Tool Registry，每个工具自带 JSON Schema 描述和使用示例，LLM 通过 function calling 调用。支持文件读写、Shell 执行、代码搜索等
- TUI 界面：用 Textual 做了一个终端 UI，WebSocket 实时通信，让用户能看到 Agent 的思考过程
收获
这个项目让我对 Agent 架构有了从理论到实践的完整理解——后来做其他 Agent 项目时，很多设计决策都是基于 jojo-code 积累的经验。
2.2 agent-sse-flow：Agent 流式可视化
这个项目最能体现"前端 + Agent"的交叉价值。
背景
在开发 Agent 应用时发现一个痛点：Agent 在后台"思考"的时候，用户只能看到一个 loading 动画，不知道它在干什么。用的是哪个工具？花了多少 token？思考了多久？全是黑盒。这种不透明的体验会让用户焦虑，尤其是 Agent 需要执行多步任务的时候。
目标
需要一个轻量级 React 组件，能把 Agent 的 SSE（Server-Sent Events）事件流实时渲染成可视化的思考过程。要求零依赖、TypeScript 类型安全、支持自定义渲染器、性能要能处理大量事件。
关键决策
- 事件协议设计：定义了标准化的 SSE 事件格式——
thinking（思考文本）、tool_call（工具调用）、tool_result（执行结果）、token_usage（Token 消耗），让前端可以精确渲染每一步 - 流式渲染引擎：基于 React hooks 实现了事件解析器，支持增量渲染——新事件进来时只更新变化的部分，而不是整个列表重新渲染
- 虚拟滚动优化：当 Agent 执行几十步任务时，事件列表会很长。引入虚拟滚动，只渲染可视区域内的事件
- 自定义渲染器模式：通过 render prop 模式，让用户可以自定义每种事件类型的渲染方式，适配不同的 UI 风格
收获
这个项目成为"前端 + Agent"方向的验证——前端经验在 Agent 开发中不是短板，而是独特优势。Agent 的可观测性、用户体验、流式渲染，这些都需要前端能力。
2.3 smart-city-agent：多 Agent 协同
这个项目展示的是系统设计能力和算法思维。
背景
城市交通信号控制是一个经典的多智能体协同问题。每个路口的信号灯是一个 Agent，它们需要根据实时车流量调整配时，同时还要和相邻路口的 Agent 协调，避免"这边放行了、那边堵死了"的情况。
目标
实现一个多 Agent 强化学习系统：每个路口 Agent 独立决策，但通过信息共享实现全局最优。技术栈包括强化学习环境模拟、多 Agent 通信协议、奖励函数设计。
关键决策
- 环境建模：用 Python 搭建了交通仿真环境，模拟车辆生成、路口等待、绿灯通行等场景
- Agent 架构：每个 Agent 用 DQN（Deep Q-Network）做决策，状态空间包括当前队列长度、相邻路口状态、历史车流量
- 协同机制：设计了信息共享层——相邻 Agent 之间定期交换状态摘要，每个 Agent 在决策时不仅看自己的状态，还参考邻居的状态
- 奖励函数：这是最关键的部分。不能只优化单个路口的通行效率，要优化全局路网的平均等待时间。设计了包含局部奖励和全局奖励的复合奖励函数
收获
仿真结果表明，多 Agent 协同方案比单 Agent 独立决策的全局等待时间降低了约 30%。这个项目让我对分布式系统中的 Agent 协同有了深入理解。
2.4 behavior-sense：实时流处理引擎
这个项目展示的是数据工程能力和实时系统设计。
背景
在金融风控场景中，需要对实时交易流做行为分析和欺诈检测。规则需要支持热加载——业务人员修改规则后立即生效，不需要重启服务。同时需要完整的审计日志，每次检测结果都能追溯到具体的规则匹配过程。
目标
构建一个实时行为分析引擎：接收 Kafka 交易流数据，经过规则引擎实时检测，输出风险评分和告警。核心挑战是规则热加载和低延迟处理。
关键决策
- 流处理框架：基于 Flink 实现流式计算管道，利用 Flink 的状态管理做窗口聚合
- 规则引擎：设计了一个轻量级规则引擎，规则用 JSON 配置描述，支持条件组合、阈值判断、时间窗口等模式
- 热加载机制：规则存储在 Redis 中，通过 Redis Pub/Sub 通知 Flink 作业更新规则缓存，实现秒级生效
- 审计工作流：每次检测结果都记录完整的触发规则链路，方便事后追溯
收获
系统上线后处理延迟控制在 100ms 以内，规则热加载后 5 秒内生效。这个项目让我理解了流式系统和 Agent 事件处理的共通之处——都是"事件驱动 + 状态管理 + 实时响应"的模式。
三、前端经验在 Agent 开发中的价值
这是整个 portfolio 最核心的叙事线：前端经验不是短板，而是独特优势。
3.1 技能迁移对照表
┌─────────────────────┬───────────────────────────────────────┐
│ 前端技能 │ Agent 开发中的应用 │
├─────────────────────┼───────────────────────────────────────┤
│ 状态管理 │ Agent 对话状态、工具调用状态管理 │
│ (Redux/Zustand) │ (LangGraph State, Checkpoint) │
├─────────────────────┼───────────────────────────────────────┤
│ 流式渲染 │ SSE 事件流可视化、Agent 思考过程展示 │
│ (Server Components) │ (agent-sse-flow 组件) │
├─────────────────────┼───────────────────────────────────────┤
│ 组件化思维 │ Tool Registry、Skill 模块化设计 │
│ (React Components) │ (Agent Skills 体系) │
├─────────────────────┼───────────────────────────────────────┤
│ 性能优化 │ LLM 调用优化、Token 消耗控制 │
│ (懒加载/虚拟滚动) │ (Context Window 管理) │
├─────────────────────┼───────────────────────────────────────┤
│ 用户体验设计 │ Agent UI/UX 设计、Generative UI │
│ (交互设计) │ (对话界面、工具调用展示) │
├─────────────────────┼───────────────────────────────────────┤
│ 测试方法论 │ Agent 行为测试、Prompt 回归测试 │
│ (单元/集成/E2E) │ (Agent 测试框架) │
└─────────────────────┴───────────────────────────────────────┘
3.2 技术深度 vs 广度的平衡
做项目 portfolio 容易陷入两个极端：讲得太广，每个都浅尝辄止；讲得太深，视野不够。
策略是"T 型结构"：
- 横向：快速过一遍 portfolio，每个项目 1-2 句话定位
- 纵向：挑 1-2 个项目深入讲架构决策和技术细节
具体来说，jojo-code 和 agent-sse-flow 是深入讲解的重点，其他项目作为补充展示不同维度的能力。
四、技术演进路径
这些项目不是随机做的，而是一个递进的学习路径。
技术演进路径：
jojo-code（Coding Agent）
│ ├── 发现问题：Agent 思考过程不可见
│ └── 延伸项目：agent-sse-flow（流式可视化）
│
agent-sse-flow（前端 Agent 组件）
│ ├── 发现问题：单 Agent 能力有限
│ └── 延伸项目：smart-city-agent（多 Agent 协同）
│
smart-city-agent（多 Agent 协同）
│ ├── 发现问题：仿真环境和真实生产有差距
│ └── 延伸项目：behavior-sense（实时流处理）
│
behavior-sense（实时流处理）
│ ├── 发现问题：Agent 工具链需要标准化
│ └── 延伸项目：xmind2md-mcp（MCP 工具开发）
│
工具链项目（MCP、测试、Prompt）
│ └── 发现问题：Agent UI 需要更好的交互模式
│ └── 延伸项目：Generative UI、Agent Skills
每个项目都是上一个问题的延伸。它们合在一起，覆盖了 Agent 开发的完整链路——从底层架构、到前端交互、到分布式协同、到实时处理。
五、踩坑经验
5.1 不要试图证明什么都会
一个常见的错误是试图展示所有技术都懂。正确的做法是讲清楚主线和支线：
- 主线：前端 -> Agent 全栈（持续积累）
- 支线：Python 后端、DevOps（为 Agent 开发补充的能力）
5.2 前端标签是优势不是劣势
有些人觉得"前端"在 AI 岗位中是减分项，试图把自己包装成"后端工程师"。但前端经验在 Agent 开发中有独特价值——Agent UI、SSE 流式渲染、用户体验设计，这些恰恰是纯后端 Agent 开发者做不好的。
5.3 讲"为什么这样做"而不是"做了什么"
技术分享中最容易掉进的陷阱是流水账式地描述项目功能。读者不想听"我用了 React + TypeScript + Tailwind"，他们想听的是：
- 为什么选 React 而不是 Vue？
- 为什么用 SSE 而不是 WebSocket？
- 为什么用 LangGraph 而不是 LangChain？
- 这些选择有什么 trade-off？
5.4 工程化能力是基本功
个人项目最容易被质疑的是"有没有工程化"。确保能回答：
- 有测试吗？怎么测试 Agent 的行为？
- 有 CI/CD 吗？怎么部署的？
- 有文档吗？其他人能看懂代码吗？
- 代码质量怎么保证的？
最好的技术复盘不是背答案，而是真正做过这些项目。当你亲手写过 Agent 的状态机、调过 LLM 的 API、踩过 context window 溢出的坑、做过 SSE 流式渲染的优化——你只需要把做过的事情讲出来。真实的技术经历，本身就是最好的内容。