作者：基于 HiveMind 智能体框架的真实工程经验撰写

本文不是理论空谈，而是从一个经过多轮生产验证的智能体框架中提炼出的架构方法论。HiveMind 已在桌面端、移动端、Web 管理端三端落地，支持多供应商模型路由、主子 Agent 协作、PDCA 工作流引擎、自我进化等能力。本文将这些实践背后的设计哲学和工程决策系统性地呈现出来。

---

一、Agent 核心架构：五层模型

一个可靠的 AI Agent 系统由五个核心层次构成，从底层模型到顶层交互层层递进：

┌─────────────────────────────────────┐
│         5. 工具与技能生态             │  Agent 的能力边界
├─────────────────────────────────────┤
│         4. 记忆与经验系统             │  跨会话的知识沉淀
├─────────────────────────────────────┤
│         3. 工作流引擎                │  计划→执行→校验→反思
├─────────────────────────────────────┤
│         2. 提示词体系                │  Agent 的"操作系统"
├─────────────────────────────────────┤
│         1. 模型基础设施              │  LLM 路由与配置
└─────────────────────────────────────┘

1.1 模型基础设施层

LLM 是 Agent 的"大脑"。构建生产级 Agent 的第一步是处理好模型层的几件事：

• 多供应商支持：不绑定单一模型。云端（阿里百炼、火山引擎、OpenAI 兼容）+ 本地（Ollama）并存，根据任务场景自动路由。
• 视觉模型智能切换：当检测到用户上传图片附件时，自动切换到支持多模态的模型。
• 配置热更新：模型的添加、删除、参数调整支持运行时热加载，无需重启服务。
• 输入输出参数配置：每种模型可独立配置温度和上下文长度，开发者可针对不同模型的行为特点做单独引导。

核心原则：模型是可变组件，架构设计应保证切换模型不影响上层逻辑。

1.2 提示词体系层

提示词是 Agent 的"操作系统"——它定义了 Agent 知道什么、能做什么、怎么做。

很多开发者的提示词就是一段长长的 Markdown 文本堆在一起。但在生产级 Agent 中，提示词应该被体系化设计，分为以下几大模块：

模块	作用	内容
身份与角色	定义 Agent 人格	角色名称、性格特质、语气风格、价值观
能力与权限	划定能力边界	可用工具列表、操作权限、禁止事项
上下文背景	提供运行时信息	工作目录、系统环境、附件、对话历史、技能列表、子 Agent 状态
执行流程	规范思考与行动	PDCA 四步闭环的推理模板
规则与约束	划定安全底线	反幻觉规则、工具选择优先级、格式规范
交互规则	规范与用户沟通	提问方式（固定选项 vs 开放问题）、批量采集协议
示例参考	降低理解偏差	工具调用 JSON 示例、端到端场景示例
优先级排序	帮助模型做权衡	安全高于效率，工具规范高于自由发挥

为什么要模块化？ 因为不同的提示词模块有不同的更新频率和来源：

• 身份角色 → 用户在配置页设置
• 能力权限 → 由工具注册中心自动生成
• 上下文背景 → 运行时动态构建
• 执行流程 → 开发者维护的基线提示词
• 规则约束 → 开发者 + 用户自定义覆盖

模块化让提示词可以分层加载、独立更新、热替换。

1.3 工作流引擎层

工作流是 Agent 的"执行中枢"。一个完整的 Agent 执行流程应该是：

用户输入
    ↓
意图分类 ──→ QA 模式（纯问答，零工具调用）
    │
    ├──→ SIMPLE_TOOL 模式（单工具调用，跳过计划）
    │
    └──→ COMPLEX 模式（完整 PDCA 闭环）
                │
           P: 生成执行计划
                │
           D: 执行计划（ReAct 循环）
                │  ├── 主 Agent 直接执行
                │  ├── 委托子 Agent
                │  └── 批量并行委托
                │
           C: 校验结果（文件真实、内容质量、语法正确）
                │
           A: 生成响应（结构化输出）

关键设计决策：

1. 意图分类先行：不是所有任务都需要完整循环。简单问答直接走 QA 模式，省时省 token；仅复杂任务才走完整 PDCA。
2. PDCA 闭环：不是一次性输出答案，而是 Plan → Do → Check → Act 四步循环，每一步都有明确的输入输出。
3. C 阶段是灵魂：很多 Agent 只有 P 和 D，缺少校验环节。HiveMind 的 C 阶段会做文件真实性校验、Python 语法校验、计划完成度检查、反幻觉检测——校验不通过就重试。

1.4 记忆与经验系统层

Agent 需要"记住"什么？不是传统的向量数据库 RAG，而是对自身经验的沉淀。

HiveMind 的记忆系统分为三层：

• 短期记忆：当前会话的对话历史。控制长度（最近 N 轮），避免超出上下文窗口。
• 长期记忆：跨会话的重要经验和结论。以自然语言段落存储，每次执行前检索相关记忆注入提示词（“来自过往经验的回忆”）。
• 意识反思：每次任务结束后，Agent 自主反思——这次做对了什么、做错了什么、下次应该注意什么。反思结果存入长期记忆。

与传统 RAG 的区别：

维度	传统 RAG	Agent 记忆系统
数据源	外部文档库	Agent 自身的执行经验
检索方式	向量相似度	关键词 + 语义匹配
注入方式	拼接到上下文	以"回忆"段落注入提示词
更新方式	手动索引文档	Agent 自主反思 + 进化引擎自动生成技能

1.5 工具与技能生态层

工具是 Agent 与外部世界交互的桥梁。一个健康的工具生态应该满足：

• 标准化调用协议：所有工具统一通过 <ACTION>{JSON}</ACTION> 格式调用，不支持其他格式（如 XML 标签）。
• 分类管理：文件操作类、网络搜索类、代码执行类、交互提问类——每类工具有明确的使用场景和优先级规则。
• MCP 协议集成：通过 MCP（Model Context Protocol）标准统一外部服务接入，让工具集成变成配置问题而非开发问题。
• 技能系统：技能是"可复用的经验包"——把重复性任务编码为 SKILL.md 文件，通过 execute_skill 工具动态加载。技能采用渐进式披露：列表只显示名称和简短的描述（Level 0），使用时才加载完整指令（Level 1），避免挤占上下文窗口。

---

二、提示词工程：最大的"杠杆"

在 AI Agent 开发中，提示词是投入产出比最高的模块。一个经过精心设计的提示词体系，能把同样的模型能力放大 3-5 倍。

2.1 不要写"大 prompt"

常见错误：把所有规则、示例、约束拼成一段超长文本。这样做的问题是：

• 模型注意力会稀释，重要规则被埋没
• 无法动态更新（改一处就要整体替换）
• 不同模型表现差异大（长文本对不同模型的注意力分布影响不同）

正确做法：模块化 + 动态拼接。

// 伪代码：系统提示词 = 多个模块按需拼接
systemPrompt += identity(角色身份)       // 模块1: 用户配置
systemPrompt += capabilities(工具列表)     // 模块2: 自动生成
systemPrompt += envInfo(运行环境)          // 模块3: 运行时
systemPrompt += hardRules(硬规则)          // 模块5: 开发者维护
systemPrompt += examples(示例参考)         // 模块7: 端到端场景

2.2 反幻觉设计

LLM 天然倾向于"编造"。反幻觉不是靠提示词说一句"不要虚构"就行，需要系统性设计：

第一层：提示词硬规则。明确 5-10 条不可违反的规则，放在显眼位置。例如：“绝对禁止虚假文件声明——不得声称文件已写入除非真的调用了 write 工具”。

第二层：执行时检测。在 ReAct 循环中，每次 LLM 输出后检查：

• 是否声明了文件操作但实际未调用对应工具？
• 是否使用了错误的工具调用格式？
• 是否在文本中罗列选项而非使用 AskUserQuestion 工具？
• 是否跳过了计划步骤？

第三层：响应后验证。对 LLM 最终输出做净化：

• 检查所有声称的文件路径是否真实存在于磁盘
• 清除泄漏的推理产物（ACTION 标签、PLAN 标签等内部标记）

2.3 工具调用协议

工具调用的格式规范极其重要。一个好的协议应该：

• 单一格式：所有工具统一格式，避免模型混淆
• JSON 而非 XML：JSON 的编码和解析更可靠
• 带 stepId：多步任务中每个工具调用标记对应的计划步骤编号
• 支持批量：允许一次输出多个 <ACTION> 块并行执行

标准格式：
<ACTION>
{"type":"tool","tool":"write","parameters":{"path":"hello.py","content":"print('Hello')"},"stepId":1}
</ACTION>

错误格式（系统不会识别）：
<write path="hello.py">print('Hello')</write>

---

三、工作流引擎：PDCA 闭环

PDCA（Plan-Do-Check-Act）是质量管理领域的经典方法论，完美适配 AI Agent 的执行场景。

3.1 P 阶段：生成计划

不是所有任务都需要硬编码的工作流。Agent 应该能自主制定计划：

输入：用户说"帮我写一个 Python 爬虫"
输出：
<PLAN>
{
  "goal": "开发一个可运行的Python爬虫脚本",
  "steps": [
    {"id": 1, "tool": "read", "purpose": "了解项目现有文件结构"},
    {"id": 2, "tool": "write", "purpose": "编写爬虫主脚本"},
    {"id": 3, "tool": "exec", "purpose": "测试脚本是否能正常运行"},
    {"id": 4, "tool": "edit", "purpose": "修复测试中发现的问题"}
  ]
}
</PLAN>

计划生成的要点：

• 子任务粒度适中：太粗（“完成项目”）失去可执行性；太细（“打开编辑器”）浪费 token
• 依赖关系明确：步骤间有先后顺序的用 id 索引关联
• 允许动态调整：执行过程中发现计划不合理，允许修正

3.2 D 阶段：ReAct 循环

ReAct（Reasoning + Acting）是 Agent 执行的微观模式：

每轮循环：
  1. LLM 输出推理过程（分析当前步骤状态、验证信息充分性）
  2. LLM 输出 ACTION 标签（工具调用 / 委托 / 响应）
  3. 系统执行 ACTION，返回工具结果
  4. 工具结果注入下一轮 LLM 上下文

关键工程要点：

• 流式用户体验：LLM 输出时实时推送给用户，但当检测到 ACTION 标签后，后续内容（JSON + stepId）对用户隐藏，只执行不展示。
• 停滞检测：如果连续多轮的观察结果高度相似（Jaccard 相似度 > 阈值），说明 Agent 陷入了循环，需要强制退出。
• 失败重试：工具调用连续失败 N 次后自动跳过该步骤，避免死循环。

3.3 C 阶段：校验机制

C 阶段是区分"玩具 Agent"和"生产级 Agent"的分水岭：

校验项	检查内容	失败处理
计划完整性	所有计划步骤是否都已执行	引导 LLM 补执行
文件真实性	声称的文件是否真实存在于磁盘	清除虚假文件声明
内容质量	文件非空、无占位符文本、语法正确	引导 LLM 修复
反幻觉	是否虚构工具返回值	重新执行
推理产物泄露	ACTION/PLAN 标签是否泄漏到用户可见输出	调用净化函数清除

3.4 A 阶段：生成响应

最后的 A 阶段不是简单"返回结果"，而是结构化输出：

{
  "summary": "已完成爬虫脚本开发，放在 spider.py，功能如下...",
  "evidence": "1. spider.py 已写入磁盘（验证通过）\n2. 测试运行输出：已抓取 10 条数据",
  "verdict": "success"
}

为什么重要：结构化输出让后续流程（日志、监控、审计）可以自动解析结果，而非依赖自然语言解析。

---

四、多 Agent 协作体系

当单个 Agent 的上下文窗口或能力范围不足以完成复杂任务时，就需要多 Agent 协作。

4.1 主子 Agent 分层

主 Agent（决策层）
    │
    ├── 与用户对话（AskUserQuestion）
    ├── 需求分析、任务拆解
    ├── 指定执行策略
    └── 委托子任务
          │
          ├── 子 Agent A（执行层）
          ├── 子 Agent B（执行层）
          └── 子 Agent C（执行层）

职责边界：

• 主 Agent：负责用户交互、需求分析、策略制定、任务拆解。涉及与用户直接对话的环节必须由主 Agent 亲自执行。
• 子 Agent：负责执行层任务（信息检索、内容生成、文件操作等），不负责与用户的直接对话交互。

关键约束：禁止将 AskUserQuestion 委托给子 Agent。问用户问题必须主 Agent 亲自执行——这是防止 Agent 擅自决策的重要安全屏障。

4.2 委托机制

委托有两种模式：

单委托：一个任务交给一个子 Agent 执行。

主 Agent 拆分任务 → 委托给子 Agent A → 等待完成 → 主 Agent 汇总

批量并行委托：多个独立子任务并行执行。

主 Agent 拆分任务
    ├── 并行委托子 Agent A（任务1）
    ├── 并行委托子 Agent B（任务2）
    └── 并行委托子 Agent C（任务3）
所有子 Agent 完成后 → 主 Agent 汇总汇报

并行委托的要点：

• 并发数限制：建议 ≤ 3 个并行，避免资源争抢
• 进度广播：每个子 Agent 完成时向用户推送进度消息，避免"长时间无响应"的体验
• 汇总汇报：所有子 Agent 交差后，主 Agent 做自然语言汇总（而非机械拼凑），用领导向老板汇报的口吻

4.3 委托审计与重派

子 Agent 执行完后，主 Agent 可以审计其产出质量。审计不通过时自动触发重派：

子 Agent 完成 → 主 Agent 审计
    ├── 通过 → 继续下一步
    └── 不通过 → 下发重派指令（包含违规点和修正方向）
          └── 子 Agent 根据反馈修正（而非从零重做）

---

五、记忆与经验系统

5.1 短期记忆：会话上下文

短期记忆就是当前对话的消息历史。管理要点：

• 长度控制：限制保留的轮数（如最近 8 轮 user + assistant），避免上下文窗口溢出
• 压缩策略：过长的单条消息截断前 2000 字符
• 隔离机制：每个会话独立维护，互不干扰

5.2 长期记忆：经验沉淀

长期记忆存储跨会话的有价值经验。关键设计：

存储什么？

• 任务执行的成功经验（“写 Python 爬虫时，记得先检查目标网站 robots.txt”）
• 失败教训（“上次用了错误的正则表达式导致匹配失败”）
• 用户偏好（“用户喜欢详细的执行步骤说明”）

如何注入？每次执行前，从长期记忆中检索与当前任务相关的记忆，以"来自过往经验的回忆"段落注入到用户提示词中：

来自过往经验的回忆：
- 写 Python 爬虫时，记得先调试单个 URL 再批量抓取
- 之前用 BeautifulSoup 解析 HTML 时踩过编码问题的坑

5.3 意识反思与自我进化

这是 Agent 具备"成长能力"的关键机制：

任务执行完成
    ↓
Agent 反思：
  - 这次执行中哪些步骤做得好？
  - 出现了什么异常？如何解决的？
  - 下次遇到类似任务应该怎么做？
    ↓
反思结果 → 存入长期记忆
    ↓
进化引擎检查：
  - 同一类型成功经验是否达到阈值？
  - 是否需要自动生成技能（可复用的经验包）？
    ↓
是 → 生成技能，下次同类任务可直接使用

---

六、反幻觉与安全治理

这是"在生产环境能跑起来"和"在生产环境能放心跑"的区别。

6.1 三层验证体系

第0层：提示词约束（软约束）
  → 在系统提示词中声明规则
  → LLM 可能忽视

第1层：执行时拦截（硬约束）
  → ReAct 循环中实时检测：
    - 虚假文件声明（正则匹配 "已写入/已保存" 等关键词）
    - 文本列选项（应使用 AskUserQuestion）
    - 跳步执行（跳过计划步骤直接声明完成）

第2层：输出后净化（兜底）
  → 最终输出中：
    - 验证文件路径真实性
    - 清除推理标记（ACTION/PLAN/CONTENT）
    - 清除文件链接格式（open-file:///、file:///）

6.2 常见的 Agent 幻觉模式

幻觉类型	表现	检测方法
虚假文件声明	说"已写入文件"但未调用 write	正则匹配 + 工具执行记录交叉验证
格式混淆	用 XML 标签而非 JSON ACTION	解析器识别所有非标准格式
工具虚构	声称调用了工具但无对应执行记录	追踪所有已执行工具的签名
交互违规	在文本中列选项而非用工具	检测"供您选择""请选择"等模式
跳步执行	跳过计划步骤直接输出结果	计划步骤完成度校验
信息泄漏	推理产物暴露给用户	净化函数清除内部标记

6.3 安全边界管控

• 工作区沙箱：Agent 的文件操作限制在工作目录内，路径穿越检测
• 敏感工具隔离：子 Agent 物理移除用户交流类工具（AskUserQuestion）
• 权限分层：主 Agent 拥有全部权限，子 Agent 仅拥有执行权限

---

七、模型管理与智能路由

生产环境的模型管理远比"配置一个 API Key"复杂：

7.1 多模型分层

分类模型（低成本）     → 意图识别、简单问答
标准模型（均衡）       → 日常任务执行
强模型（高成本）       → 复杂推理、代码生成
视觉模型（多模态）     → 图片分析、OCR
本地模型（离线）       → 敏感数据处理、无网络场景

7.2 智能路由策略

• 基于输入特征：检测到图片附件 → 自动切换到视觉模型
• 基于任务复杂度：简单任务走低成本模型，复杂任务走强模型
• 基于供应商成本：多个供应商之间按利润率和可用性均衡调度
• 降级策略：主模型不可用时自动降级到备用模型

---

八、总结：一份"健康检查清单"

如果你的 Agent 项目已经初步能跑，可以用以下清单检查工程化成熟度：

提示词体系

• 提示词是否模块化拆分（而非一大段文本）？
• 是否支持热更新（不改代码即可修改提示词）？
• 模型特定提示词是否与通用提示词分离？
• 是否有明确的反幻觉规则和示例？

工作流

• 是否支持任务意图分类（区分问答/简单工具/复杂任务）？
• 复杂任务是否走 PDCA 闭环（计划→执行→校验→响应）？
• 校验阶段是否覆盖了虚假文件声明/跳步执行/产物泄漏？
• 工具调用失败是否有重试/跳过机制？

记忆系统

• 是否区分子短期记忆和长期记忆？
• Agent 能否从失败经验中学习？
• 是否有跨会话记忆检索注入机制？

多 Agent 协作

• 主 Agent 和子 Agent 的职责边界是否清晰？
• 委托审计重派机制是否就绪？
• 并行任务的进度是否对用户可见？

安全治理

• 是否有三层反幻觉验证（提示词约束 + 执行拦截 + 输出净化）？
• 子 Agent 的权限是否已被正确限制？
• 工作区路径隔离是否生效？

---

后记

构建可靠 AI Agent 不是一个"写完 prompt 就完事"的一次性工程。它是一个需要持续迭代的系统工程——从提示词到工作流，从记忆系统到安全治理，每一层都需要精心设计。

但好消息是：一旦建立了正确的架构骨架，后续的迭代就变成了在这个骨架上的增量优化，而不是每次都从零开始。希望本文的分享能帮你的 Agent 项目少走弯路。