Architecture

「绝大多数 Agent 项目死在 PoC 和生产之间的那段没有地图的荒野。」 这句话是我反复读 Relay 项目文档时自己写下来的。Relay 是一个开源的求职 AI Agent 系统——不是那种「3 行 LangChain 代码 + GPT-4」的演示，而是一个有完整架构文档、172 个工程任务、混合技术栈、并且对每个设计决策都给出了明确反例的项目。 它还没有完全跑起来。Agent 层的代码还在写。但这恰恰是我觉得值得写这篇文章的原因：这是一个在设计层面思考非常深的系统，而那些深度思考本身——无论这个项目最终走向何方——都是对所有在做 Agent 工程的人有价值的参考。 这篇文章不是产品介绍，是一次架构拆解。 一、问题背景：为什么求职场景特别适合做 Agent 系统 在聊架构之前，我想先回答一个更基础的问题：为什么求职是一个适合 Agent 而不只是 AI 工具的场景？ 求职的本质是一条多阶段、多工具、高认知负担的工作流： 简历准备 → 职位搜索 → 简历定制 → 表单填写 → 投递追踪 ↑ ↓ └──────── 面试准备 ← 面试邀请 ←────────────────┘ 每个节点都需要大量「低价值的机械劳动」——搜索、复制、粘贴、调格式、填表单。同时，每个节点的「高价值判断」——这份职位适合我吗？这段经历该怎么呈现？这道面试题我应该怎么练？——都是高度个人化、依赖上下文的问题。 这正是 Agent 系统应该介入的地方：把机械劳动自动化，把高价值判断辅助化，把不可逆操作透明化。 Relay 的北极星是：「质量优先而非数量优先——精准的一发，胜过无脑的一百发。」 这个定位本身就决定了它的架构不能是「一键批量投递」，而必须是「每一份投递都经过用户确认」。 二、整体架构：五层设计 Relay 的架构分五层，从底向上依次是： ┌──────────────────────────────────────────────────────────┐ │ 第 5 层：UI 层 │ │ Next.js 16 Web 控制台 + Manifest V3 浏览器扩展 │ ├──────────────────────────────────────────────────────────┤ │ 第 4 层：API + 编排层 │ │ Hono/Bun TypeScript API + Redis Event Bus │ ├──────────────────────────────────────────────────────────┤ │ 第 3 层：Agent 执行层 │ │ Python FastAPI + LangGraph（5 个 domain agent） │ ├──────────────────────────────────────────────────────────┤ │ 第 2 层：共享服务 │ │ Auth、Notification、Audit、LLM Router │ ├──────────────────────────────────────────────────────────┤ │ 第 1 层：数据 + 外部集成 │ │ PostgreSQL + pgvector、Redis、MinIO、OpenRouter │ └──────────────────────────────────────────────────────────┘ 最核心的设计决策是混合后端：API 层用 TypeScript（Hono + Bun），Agent 层用 Python（FastAPI + LangGraph），两层通过 HTTP + Redis + 共享 PostgreSQL 连接。 ...

「Agent loop 是 10 行代码，Agent engineering 是 10 万行代码。」 这句话我第一次读到时愣了一下，然后越想越觉得它锋利。它把整个领域里最大的一个错觉戳破了：很多人以为做 Agent 就是把 prompt 写好、把 LLM API 调通——而真正把一个 demo 推到生产、能在无人值守下安全跑一整夜的工程量，99% 都不在那个 loop 里。 这篇文章想做一件事：把 Agent Engineering 当成一门学科来拆，而不是当成一个教程。我不会教你怎么用 LangGraph，我想给你一张地图——这门学科由哪八根支柱构成、每一根填补了前一根留下的什么缺口、它的最小实现长什么样、又会在什么时候失效。读完之后，你看任何一个 Agent 框架、任何一篇大厂工程博客，都能立刻定位它在这张地图的哪个位置。 地图的素材，一半来自我自己造 Agent 系统时反复踩的坑，另一半来自 2025 到 2026 这一年里 Anthropic、OpenAI、Cognition、Manus、Temporal 这些一线团队公开出来的实践。我会尽量把每个关键论点的出处标清楚——因为这个领域里，错传的"事实"比真相传得更快，这一点我们马上就会撞上第一个。 一、那个被反复引用的数字：98.4% 先从一个流传极广的数字开始，因为它是这篇文章的标题，也是整个领域最好的一句开场白。 2026 年有一篇逆向拆解 Claude Code 的论文 《Dive into Claude Code》（VILA-Lab，arXiv: 2604.14228），分析对象是 Claude Code v2.1.88——大约 1900 个 TypeScript 文件、51 万行代码。它的摘要里有一段我愿意原样抄下来的话： 「系统的核心是一个简单的 while 循环，它调用模型、运行工具、然后重复。然而绝大部分代码，都活在这个循环周围的系统里：一个有七种模式和一个基于 ML 的分类器的权限系统、一条用于上下文管理的五层压缩流水线、四种可扩展机制（MCP、插件、技能、钩子）、一个带 worktree 隔离的子 agent 委派机制，以及面向追加的会话存储。」 注意这里有个重要纠偏：那个广为流传的精确数字「1.6% 是 AI 决策逻辑、98.4% 是基础设施」其实不在论文摘要里，它是二次概述时的渲染。而且网上很多人把它归给 minusx 的博客、或者"UCL 团队逆向泄露源码"——这些归属都是错的。minusx 那篇《Decoding Claude Code》写得很好，但里面根本没出现过任何百分比；论文也不是基于泄露源码，而是分析公开的 TypeScript。 ...