---
title: "从零设计一个准生产级 LLM Agent：可靠性、上下文与恢复机制"
source_url: "https://mp.weixin.qq.com/s/UTEdhrkV3G3Ycfrg0Jng_A"
publisher: "工程师与艺术家"
author: "Thinking（工程师与艺术家）"
published: "2026-06-02"
ingested: "2026-06-17"
sha256: "8acacf03ec2ddc37dbfec1cad4322909bf0e0a2dc79c5af497cee0163360cb88"
type: raw
tags:
  - agent-framework
  - thinkingagent
  - pipeline-architecture
  - harness-engineering
  - reliability
  - context-management
  - checkpoint
  - llm-gateway
  - quality-evaluation
  - model-routing
  - safeguard
  - flywheel
---

# 从零设计一个准生产级 LLM Agent：可靠性、上下文与恢复机制

> ThinkingAgent 是一个轻量级，准生产就绪的 LLM Agent 框架，支持多 LLM Provider、复杂任务编排、自动故障恢复和长任务断点续跑。本文完整记录了我从 0 到 1 构建 ThinkingAgent 的全过程。所有方案均为独立设计与实现，不依赖于任何已有代码或架构。

## 0. 演示：从任务输入到结果交付的完整样例

### 0.1 任务描述

让 ThinkingAgent 制定一个 6 月份去尼泊尔旅行的行程规划，提示词要求：
- 9-11 天行程，每天安排交通/住宿/景点/餐饮
- 广州出发往返
- 具体时间安排（如 13:00-15:00 火车）
- 每个景点不少于 100 字描述 + 配图
- 汇总交通/餐饮/住宿/签证/其他五类费用
- 无时间冲突
- Markdown 格式，不超过 5000 字
- 成功后保存为本地文件

### 0.2 对比评测

| Agent | 评分 | 优势 | 劣势 |
|-------|------|------|------|
| ThinkingAgent | 4.5⭐ | 排版最好，当地特色/宗教风俗/安全建议最全 | 酒店餐馆介绍不如携程 |
| 豆包 | 4⭐ | 输出所有要求信息 | 排版差，大部分无配图 |
| 携程 | 3.8⭐ | 餐馆酒店信息最丰富 | 缺少当地特色，默认自驾 |
| Qwen | 2⭐ | — | 只有简单文字描述 |

## 1. 战略规划：先定义边界，再选择进化路径

### 1.1 需求与目标
- 能自主分析/规划/执行/验收的通用个人助手
- 处理需要推理 + 工具调用的任务
- 处理长周期、多步骤、复杂任务

### 1.2 设计原则
- "基础能力"与"可靠性"设计同时进行
- **LLM Agent 是典型的 Pipeline 系统，每个环节都可能失败。每个失败点都要有恢复策略，每个恢复策略都要有代价意识**
- 不是所有失败都需要最激进的恢复策略——代价意识让系统在可靠性和效率之间找到平衡

### 1.3 四层能力分层
从下到上：基础能力层 → 可靠性层 → 安全性层 → 飞轮层。每一层面向不同领域问题，可独立深入和演进。第一个版本设置一个月 deadline。

## 2. 系统架构设计：用 Pipeline 收束动态决策

### 2.1 五层垂直分离架构

LLM Agent 与传统数据流系统最重要的区别是 **LLM-in-the-loop**——需要为 LLM 这个不确定算子设计 Harness 框架，从架构层面支撑 LLM 的动态决策和行为。

采用 **DDD 领域建模 + 数据流系统建模** 双轨设计方法：
1. 基于数据流动提出关键业务事实
2. 编排业务事实的时间顺序
3. 推导 Command 和约束 Policy
4. 抽聚合、提取根对象、确定聚合边界

### 2.2 Pipeline 是唯一的"上帝视角"

**三个关键动机**：
- 串联和协调各聚合根的动作顺序
- 制造干净的依赖关系（星形拓扑，非网状依赖）
- 未来多 session 并发时，Pipeline 成为执行流的数据隔离单元

### 2.3 ComponentAssembler：依赖注入的统一入口

- 测试替换：注入 mock 组件不需改业务代码
- 配置集中：所有配置在一个收口管理
- 依赖可见：依赖关系一目了然
- 生命周期管理：控制创建顺序（如 LLMGateway 必须在 ReasoningManager 之前）

### 2.4 PipelineDriver：用户与 Agent 的消息桥梁

- 支持预定义的产品能力（权限放过、信息澄清、二次确认、用户引导）
- 技术防腐层：用户消息与 Agent Command 互转

### 2.5 EventBus 事件总线：15+ 领域事件

覆盖从任务分析到最终交付的完整生命周期：TaskAnalysisStarted、PlanGenerateSucceed、StageExecutionStarted、ToolCallStarted、TaskExecutionSucceed 等。通过订阅所有事件可重建任务执行的完整时间线。

## 3. 基础能力层

### 3.1 推理框架：Plan-and-Execute + ReAct + Self-Reflection

**以 Plan-and-Execute 为骨架，以 ReAct 为血肉，以 Reflection 为进化驱动力**的混合式智能体。

### 3.2 三段式循环（核心控制流）

**Task 级循环**：任务分析 → 重写用户问题 → 制定/评审计划 → 调用 Stage 循环 → 评审交付结果 → 知识/偏好提取

**Stage 级循环**：模型路由 → 调用推理循环 → 评审步骤结果 → 恢复流程 → Checkpoint 保存

**推理级循环**：非阻塞轮询用户指令 → 构建上下文窗口 → 调用 LLM → 工具调用分支

### 3.3 任务分析：让 Agent 真正理解任务

把一个模糊的自然语言请求转化为结构化的、机器可处理的任务描述。产出四方面信息：

**(1) 任务语义层面**：task_type（影响模型路由）、intent（真实意图）、task_goal（贯穿全程）、entities（规范化处理，如"上周五"→"2026-05-15"）

**(2) 执行约束层面**：action_constraints（行为约束）、output_constraints（输出约束）、risks（潜在风险）

**(3) 工具匹配层面**：对每个可用工具计算语义相关性评分

**(4) 模型路由提示**：required_capability_tags、estimated_context_tokens、latency_sensitive、cost_sensitive

### 3.4 知识注入

在任务分析结束后进行（而非基于原始描述），避免语义模糊导致噪音。知识 Entry 包含 entry_id、元数据、索引信息、内容块。检索分三阶段。

### 3.5 用户偏好注入

原始偏好以键值对存储，周期性任务负责总结。Analyzer 决定应用哪些偏好并转化到执行约束/工具匹配/模型路由等字段。

### 3.6 提示词工程

**基于模板的提示词管理**：Jinja2 模板引擎，提示词与代码分离，支持复用、动态注入、版本控制、A/B Testing。

**四个关键实践**：

1. **从模型行为规律反推 Prompt 布局**：头部放稳定的全局控制信息（系统角色/任务目标/执行约束），中部放可压缩的过程信息，尾部放当前决策所需的高优先级信息。**头部负责"定方向"，尾部负责"控动作"，中部负责"保连续性"**

2. **工具选择的优先级提示**（first match wins）：简单数学→calculator，多步数据处理→run_python，Excel→excel，Shell→shell，SQL→SQL 工具，网络事实→search

3. **为副作用设计提示词**：Self-Reflection 的输入应定义为从副作用中抽取的特征，而非副作用内容本身。如字数检查输出 checklist summary 而非全文

4. **为 LLM 推理输出加装消息信封**：Agent 控制流用标准化 JSON 格式（`{"final_answer":"..."}`），质检时提取原始消息

### 3.7 检查点机制：长任务的生命线

**保存时机**：每个阶段**通过质量评估后**保存（而非每次工具调用/每次推理/阶段完成）。核心洞察：检查点保存的是"已验证的进度"，不是"已完成的工作"。

**检查点内容**：任务信息、执行计划、已完成阶段结果、当前上下文窗口、模型路由状态（含熔断器状态）、用户偏好快照。

### 3.8 工具系统

**两遍打分过滤**：Analyzer（任务整体视角）+ Planner（执行细节视角），两次评分都需超过阈值。

**Anti-Skills 立场**：不把 Skills 作为独立一等抽象，而是拆解到知识、偏好、工具和推理轨迹控制四个更基础的层面。工具要简约（像 Shell），SOP/资料纳入"知识"，人设/风格纳入"用户偏好"。

## 4. 可靠性体系建设

**核心哲学**：失败是常态，不是异常。可靠性设计的重心不是如何避免失败，而是失败后如何以最小代价恢复。

### 4.1 Pillar-Layer 异常处理

| Level | 关注点 | 发现机制 | 恢复手段 |
|-------|--------|---------|---------|
| Task | 最终交付结果是否可靠 | Evaluator 评估 + 下层异常 | Retry 原计划 / 重新制定计划 |
| Stage | 流程约束/目标匹配/结果可靠 | Evaluator 评估 + 下层异常 | 重试 / 重新规划 / 全计划重来 |
| Reasoning | 一次推理是否成功 | 下层异常 | 模型切换 |
| LLM Gateway | API 交互异常 | 本地检查 + 错误码 | Backoff 重试 / 模型降级 / 厂商切换 |
| Tool Registry | 工具调用异常 | 调用前检查 + 重复调用纠偏 | Backoff / 纠偏 Prompt / 工具降级 |
| Context | 推理轨迹可靠性 | 上下文检查 | 上下文修复/压缩 |

### 4.2 带行为的标准化异常

在错误码基础信息之上增加 caller action 和 action data，直接驱动调用端的恢复行为。错误码展示逻辑与恢复逻辑分离。

### 4.3 基于代价设计恢复策略

从最低代价开始尝试恢复，恢复策略自动升级。如 SQL 写错→重试当前步骤；计划描述不清→微调本步骤；数据清洗有问题→从上游重新规划。

### 4.4 上下文管理

**双缓冲设计**：_ctx_window（当前活跃上下文，可增删）+ _history（完整追加历史，只增不删）。阶段回滚时从 _ctx_window 删除，但 _history 保持完整。

**五步自动修复法**：
1. 删除孤立 tool_result
2. 确保第一条是 user 消息
3. 修复 tool_use/tool_result 配对
4. 删除末尾孤立 tool_use
5. 合并相邻同角色消息

**Token 预算管理：角色分配制**：
- 预留区（reserved_tokens）：给 LLM 响应输出
- 可用区按角色比例分配：system / user / assistant / tool
- 超限时优先压缩 tool 消息，其次较早的 assistant 消息

**上下文压缩：混合策略 + 渐进式处理**：
- 5 种压缩策略（消除重复工具调用 / 简化失败消息 / 缺省过长参数 / 缺省过长字段 / GROUP 替换为摘要）
- 消息分 BLOCK（原子语义单元）和 GROUP（同 Stage 的 BLOCK 集合）
- 从侵入最少的策略开始，满足预算就早停
- **不引入直接裁剪**（实践中发现可能引发推理轨迹断裂）

**Prompt Caching**：两个 cache_control 标记（Task Plan 所在 tool role + 最新一条消息）

### 4.5 LLM 网关

**设计目标**：调用方不需要关心 LLM 调用的任何可靠性问题。

**标准化协议**：UnifiedLLMRequest / UnifiedLLMResponse，统一所有提供商的请求参数。

**恢复策略**：
- 带 Jitter 的 Backoff 重试（Timeout/429/5xx）
- 模型降级（Quota Exceeded / 回包解析问题）
- 厂商切换（4xx Auth / Content Policy / Invalid Request）
- 报文内容修复（JSON fence 修复 / 缺失 key-value 本地修复）

### 4.6 ToolRegistry

- **准入检查**：调用前统一完成（存在性/必填参数/类型约束）
- **工具降级**：search 失败→降级使用本地数据库搜索
- **连续同质化调用限制**：超过 10 次注入引导消息（"软干预"而非"硬终止"）
- **LLM-Driven 修复**：错误信息注入上下文由 LLM 决定下一步

### 4.7 质量评估：三层体系

| 层次 | 时机 | 代价 | 价值 |
|------|------|------|------|
| 计划评估 | 执行前 | 最低（~500-1000 token） | 发现方向性错误 |
| 阶段评估 | 每阶段后 | 中等 | 早发现早修复 |
| 任务评估 | 全部完成后 | 最高但必要 | 最终质量把关 |

**评估策略**：
- 计划评估：全局匹配分析 + 双向因果关系论证（从因看果 + 由果观因），提升成功率 ~15pp
- 阶段评估：显式要求（key results 是否包含）+ 隐式要求（是否推动 task_goal 前进）
- 任务评估：6 维度（目标达成/意图对齐/输出约束/风险规避/信息完整/副作用产物）

### 4.8 智能模型路由

**CapabilityMatchStrategy**：多信号加权评分（任务类型匹配 / 能力标签命中 / 认知复杂度覆盖 / 场景相似度 / 工具调用支持 / API 稳定性）

**认知复杂度 L1-L4**：L1 单步模板化 → L4 深度推理/长链思维

**熔断器**：三态状态机（CLOSED→OPEN→HALF_OPEN），优先恢复高优先级提供商

## 5. 安全性体系建设

使用代理模式为每个 Tool 套一层 Safeguard：

**通用检查**：工具白名单、调用频率限制、会话独立工作子目录

**个性化处理**：
- Run Python Tool：三层沙箱（静态导入检查 AST + 受限内置函数 + 子进程隔离 + 资源限制）
- SQL Query Tool：参数化查询 + 只读限制 + 行数限制 + 数据脱敏 + 库表限制

**高危操作**：不在白名单中的工具调用需用户二次确认

## 6. 构建飞轮：在任务之后沉淀知识和偏好

**两种记忆**：
- 知识库（Knowledge）：事实性信息（DB Schema / 数据质量问题 / 业务规则 / 问题定位套路）
- 偏好库（Preference）：行为偏好（输出格式 / 语言 / 详细程度 / 工具使用）

**异步学习**：任务完成后异步提取，不阻塞当前任务。用学习延迟换取执行延迟降低。

**知识提取三条件**：可复用性 + 稳定性 + 准确性。LLM 判断哪些值得提取，用户审查标记。

**偏好衰减**：JSONL 追加写入，超 64KB 自动删除最旧 20 条（"最近优先"策略）。

## 7. Benchmark：5 任务 × 40 次 = 200 次独立运行

| 指标 | 结果 |
|------|------|
| 推理轨迹正确率 | 99% |
| 工具选择正确率 | 98% |
| JSON 解析成功率 | 100% |
| 样本任务完成率 | 94% |
| 工具参数填充正确率 | 98.75% |
| 轨迹效率（最少必要步数/实际步数） | Avg 0.75 |

**任务设计原则**：必须同时包含推理和工具调用 / 至少 2 种不同工具 / 多步骤多轮次 / 明确限制约束 / 可应用偏好 / 可应用知识库

**局限性**：测试任务有限 / 无 baseline 对照组 / LLM as a Judge 可能误判 / 无消融实验

## 8. 工程实践总结

- LLM Agent 的可靠性设计和基础能力搭建要**同时进行**，避免后期架构剧烈冲击
- LLM Agent 工程最核心的是**如何产生高质量的推理轨迹**——如何有目的地控制那台高维度贝叶斯概率机器
- 提前做好系统可观测性和辅助分析工具
- 实践过程是真金白银花钱的——平均跑一个测试任务 4 块多人民币，考虑到无数次失败和反复调试，累积可观