name	agent-evaluator
version	1.0.2
author	BEIBEICSY
description	评价 AI Agent 项目架构，对标 SOTA 标准。当用户要求评价 Agent 项目、分析架构差距、或对比主流大厂方案时调用。支持完整版（含代码细节）和精简版（仅结论和建议）两种报告格式。
github	https://github.com/BEIBEICSY/awesome-agent-evaluator-skill

AI Agent 项目评价 Skill

使命：降低学习/构建 Agent 的门槛，让不懂代码的人也能理解"为什么这样设计"。

一、核心原则

1. SOTA 标准评价

定义: SOTA = State of the Art（当前最佳技术）

要求: 每次评价必须对标当前年份的行业最高水平，而非过时范式。

目的: 确保及时学习最新知识，避免停留在 2022-2025 年的旧范式。

2. 搜索年份动态调整

要求: 搜索时必须根据当前日期动态调整年份关键词。

当前日期: 2026-04-30

示例:

错误做法: "AI agent architecture 2025"  ← 信息滞后
正确做法: "AI agent architecture 2026"  ← 获取最新信息

3. 主流大厂优先

要求: 搜索参考时优先 Follow 主流大厂官方文档，而非小众实验性框架。

目的: 参考经过大规模验证的生产级方案。

4. 强制先检索（最重要！）

要求: 在评价任何 Agent 项目前，必须先执行 SOTA 搜索，获取最新信息。

原因:

AI Agent 领域在 2026 年发展极快，3 个月前的知识可能已过时
不检索最新信息，评价可能基于错误的假设
检索结果必须多源交叉验证

5. reference/ 与 WebSearch 的边界（重要！）

核心定位：

信息源	定位	使用方式
`reference/` 目录的 9 个静态文档	离线缓存 / 启动模板	用于快速建立对各厂商的初步认知，不可作为最终结论的唯一依据
WebSearch（每次评估必须执行）	真相来源 / 最新事实	每次评估都必须重新搜索，验证 reference/ 内容是否过期

强制规则：

报告第三部分每个里程碑的 SOTA 对标，必须在当次会话中通过 WebSearch 验证至少一项最新事实（如版本号、API 变更、新发布的论文/产品）
当 WebSearch 结果与 reference/ 静态文档冲突时，以 WebSearch 为准，并在报告中注明"reference/ 已过期"
当 reference/ 文件的 last_updated 距今超过 3 个月时，必须执行刷新（用 WebSearch 找最新内容并更新 reference/ 文件）

二、评估清单（七大里程碑）

核心洞察：这七个里程碑不是随意选择的，而是基于 Agent 的本质定义：Agent = LLM + System + Environment。

里程碑详解

里程碑	通过标准	为什么这是标准（设计原理）	来源
感知层	多模态反馈闭环	核心洞察：Agent 的行动能力受限于它的感知能力。一个只能"读文本"的 Agent，就像一个只能听电话的盲人——它无法理解 UI 截图、无法识别图表、无法感知用户语气。设计原理：感知 → 解释 → 决策 → 行动 → 再次感知，这是一个闭环。没有闭环，Agent 就无法验证自己的行动是否有效。	Perception in AI Agents 2026
大脑层	Plan-and-Execute 或自反思循环	核心洞察：ReAct（2022年）是基础版，但 2026 年的 SOTA 已经进化到 Plan-and-Execute（先规划再执行）或自反思循环（每一步都自检）。设计原理：LLM 的推理是概率性的，单次推理容易出错。通过"规划 → 执行 → 反思 → 调整"的循环，可以显著提高可靠性。	AI Agent Architecture 2026 Guide
协议层	MCP 或结构化函数调用（零正则解析）	核心洞察：正则解析依赖模型输出格式的稳定性，这是 2022-2023 年的旧范式。2026 年的 SOTA 是 MCP（Anthropic）或 Function Calling（OpenAI），它们通过 schema 强制校验，从根本上消除了格式解析失败的风险。设计原理：LLM 输出是概率性的，正则解析是确定性的——两者不兼容。结构化协议让模型输出"被迫"符合 schema，从根本上解决了可靠性问题。	MCP vs Function Calling 2026
行动层	异步/并行执行与错误容错	核心洞察：生产环境的 Agent 会遇到网络超时、API 限流、服务重启等问题。没有重试机制和异步执行，Agent 会频繁失败。设计原理：Agent 的执行链路有多点故障（LLM 调用、工具执行、网络请求），每个点都需要独立的错误处理和重试策略。	AI Agent Best Practices 2026
记忆层	分层管理（向量长时记忆 vs 上下文短时记忆）	核心洞察：LLM 的上下文窗口是有限的（即使 GPT-5 有 100k tokens，也会被填满）。没有分层记忆，Agent 会"忘记"之前学到的知识。设计原理：短期记忆（当前会话）像 RAM，快速但容量有限；长期记忆（跨会话）像硬盘，持久但需要检索。两者分离，才能既保持推理效率，又积累长期知识。	Redis: AI Agent Memory
工程化	上下文滑动窗口、Token 成本控制与自动化评测	核心洞察：LLM 调用是昂贵的（每次推理都消耗 tokens）。没有成本控制和评测系统，Agent 的运营成本会失控。设计原理：上下文滑动窗口防止 token 爆炸；自动化评测（Evals）确保 Agent 输出质量稳定。	AI Agent Infrastructure 2026
安全性	执行沙箱、路径白名单及敏感操作的人工确认机制	核心洞察：Agent 会执行代码、读写文件、调用 API。没有沙箱隔离，Agent 可能误删文件、泄露数据、执行恶意代码。设计原理：沙箱隔离（容器化）防止 Agent 影响宿主系统；路径白名单限制 Agent 只能访问特定目录；敏感操作确认（Human-in-the-loop）防止 Agent 自主执行高风险操作。	GKE: Secure AI Agents

三、SOTA 对标选择逻辑

核心问题：为什么选择这些公司作为 SOTA 对标？为什么不参考其他？

选择原则

选择优先级排序：

1. 【行业标准制定者】（最高优先级）
   - Anthropic (MCP)：MCP 是开放标准，Anthropic 是标准制定者
   - OpenAI (Function Calling)：Function Calling 是实践标准，OpenAI 是标准制定者
   - 选择原因：参考标准制定者，就是参考行业最高水平

2. 【生产级验证】（高优先级）
   - LangGraph：25k stars，被 Klarna、Replit、Elastic 采用
   - 选择原因：经过大规模生产验证，不是实验性框架

3. 【最新范式】（高优先级）
   - Manus：完全自主执行 + Sandbox 隔离
   - Hermes：自进化记忆 + $1B 估值
   - 选择原因：代表 2026 年的最新范式，不是 2022-2023 年的旧范式

不参考的原因

不参考的公司/项目	原因	具体说明
AutoGPT	旧范式	182k stars，但仍是 2022 年的 ReAct 正则解析范式，不是 2026 年的 SOTA
CrewAI	编排不可控	45k stars，但使用"对话式编排"，无法保证执行路径可控，不适合生产环境
小众 GitHub 项目	未验证	stars < 10k，无生产验证，可能存在未知问题
Devin	场景单一	自主编程，但场景单一（仅编程），无法代表通用 Agent 架构

四、评价执行流程

步骤 0：询问报告版本（强制！）

核心要求：在开始读取项目代码前，必须先询问用户需要的报告版本。

必须执行的操作：

使用 AskUserQuestion 工具询问用户：

问题	选项	说明
"您需要哪种版本的评估报告？"	完整版（推荐给想要学习详尽架构设计的用户）	包含所有代码截取、逐行解读、mermaid 流程图、概念扩展卡片
	精简版（推荐给只想要评估结果和改进建议的用户）	去掉代码截取和逐行解读，只保留设计思路、差距分析、改进建议

询问时必须包含的说明：

完整版：适合想要深入理解 Agent 架构设计的用户，报告较长，包含大量代码示例和类比解释。适合想要学习"为什么这样设计"的用户。
精简版：适合只想要"结论+下一步"的用户，报告较短，不包含代码细节，但保留所有评估结论和改进建议。适合不愿意阅读代码的用户。

用户选择后的处理：

如果用户选择"完整版" → 按完整版流程执行（步骤 1-5）
如果用户选择"精简版" → 按精简版流程执行（见下文"精简版执行流程"）

步骤 1：通读项目所有 md / README / docs（强制！）

核心要求：在动任何代码之前，必须先把项目里所有的文档读完——这是理解作者"设计思路"的唯一途径，也是写出"一、项目整体概况"的前提。

必须执行的操作：

1. 用 Glob 列出项目所有 md/markdown/rst/txt 文档：
   - **/README*
   - **/*.md
   - **/docs/**
   - **/CHANGELOG*
   - **/ARCHITECTURE*
   - **/DESIGN*

2. 用 Read 通读每一份文档，重点提取：
   - 作者明示的设计目标 / 设计思路 / 取舍说明
   - 整体架构图 / 模块划分 / 数据流
   - 已知限制 / TODO / Roadmap
   - 引用的论文 / 框架 / SOTA 对标

3. 输出文档清单与摘录（写进报告"一、项目整体概况"）：
   | 文档路径 | 类型 | 关键设计声明摘录 |
   |:---|:---|:---|
   | README.md | 入口 | "本项目是一个 ReAct + 正则解析的本地 Agent..." |

为什么这一步是强制的：

不读 md 文档 → 只能从代码逆推设计意图，容易误判作者初衷
读了 md 文档 → 能把"作者怎么想的"和"代码怎么实现的"做交叉验证，识别设计思路与代码实现之间的偏差
如果项目没有任何 md 文档：必须在报告中明确指出"项目缺少设计文档"——这本身就是一个工程债

步骤 2：识别项目类型

首先识别用户要评价的项目类型：

- Agent 项目: 包含 agent、智能体、agent_framework 等关键词
- Coding Agent: 包含 coding、编程、代码生成等关键词
- Multi-Agent: 包含 multi-agent、协作、团队等关键词
- 通用 Agent: 包含 general、通用、manus 等关键词
- 自主执行 Agent: 包含 autonomous、自主、sandbox 等关键词

步骤 3：执行 SOTA 搜索（强制先检索！）

强制要求：在评价任何 Agent 项目前，必须先执行以下搜索：

搜索关键词模板：

# 1. 学术前沿（最新技术突破）
arXiv AI agent 2026
AI agent paper 2026
AI agent architecture 2026

# 2. 官方文档（生产级方案）
Anthropic MCP official documentation 2026
OpenAI Function Calling official guide 2026
LangGraph StateGraph architecture 2026

# 3. 开源实现（实际实现）
GitHub AI agent trending 2026
AI agent implementation 2026

# 4. 监管动态（合规安全）
AI agent acquisition 2026
AI agent regulation 2026
AI agent sandbox security 2026

验证要求：至少 3 个来源交叉验证，确保信息一致。

步骤 4：读取项目代码

必须读取的核心文件：

1. 主入口文件（main.py / app.py / index.js）
2. 工具定义文件（tools.py / tools.js）
3. 配置文件（config.py / config.json）
4. Prompt 文件（prompts/ 目录）
5. 记忆系统文件（memory.py / memory.json）

步骤 5：生成评价报告（严格 4 大块结构）

报告必须严格按以下 4 大块输出——这是用户预期的报告框架，不允许新增/删除/合并模块：

一、项目整体概况
   - 1.1 项目定位（一句话说清楚 Agent 是做什么的）
   - 1.2 设计思路（作者怎么想的，从 md 文档摘录原文 + 代码交叉验证）
   - 1.3 整体架构图（mermaid 流程图，展示模块关系与数据流）
   - 1.4 关键模块清单（文件 → 职责对照表）
   - 1.5 技术栈（语言、框架、依赖、模型、协议）
   - 1.6 文档清单与关键设计声明摘录（来自步骤 1）

二、七大模块阶段评估（清单进度）
   - 2.1 七大里程碑标准化表格：
     | 里程碑 | 通过标准 | 当前状态 | 当前阶段判定 | 为什么这样判定（一句话证据） |
   - 2.2 阶段判定要使用范式演进阶梯（第八节）做横向定位
   - 2.3 必须给出"代码证据"——从被评价 Agent 中找一行/一段代码作为判定依据

三、七大模块深度评价（核心，严格 3 段式 + 1 概念卡片）
   - 按七大里程碑顺序，每个里程碑独立一节，必须严格按以下子结构：
     3.x.1 被评价 Agent 怎么做的（必须截取真实代码）
     3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处
     3.x.3 建议怎么改（立即/短期/中期）
     3.x.4 概念扩展卡片（辅助学习）
   - 工程债检测下沉为每个里程碑 3.x.1 的子条目（不再单独成块）

四、整体评分
   - 4.1 七维度评分表（一一对应七大里程碑）
   - 4.2 总分（百分制）
   - 4.3 架构等级判定（架构师 / 协议专家 / 脚本工程师 / 新手）
   - 4.4 一句话总结：当前阶段 + 最关键的下一步

强制规则：

报告只能有这四部分，不允许新增"工程债检测""可执行建议""SOTA 对标深度解析"等独立模块——这些都已下沉到"三、七大模块深度评价"的子节
"三、七大模块深度评价"每个里程碑必须截取真实代码（用 CODE REFERENCE 格式 startLine:endLine:filepath）
"四、整体评分"的评分维度必须严格对应"二、七大模块阶段评估"的七大里程碑，权重见第九节

精简版执行流程（用户选择"精简版"时执行）

核心差异：精简版不截取代码、不逐行解读，只保留设计思路和改进建议。目标是让不愿意阅读代码的用户也能理解评估结论和下一步改进建议。

执行步骤：

步骤 1-3：与完整版相同

步骤 1：通读项目所有 md 文档（强制）
步骤 2：识别项目类型
步骤 3：执行 SOTA 搜索（强制）

步骤 4：读取项目代码（精简版调整）

只读取关键文件，不需要截取代码片段
重点提取：设计思路、架构模式、关键决策，而非具体实现细节
不需要记录代码行号，只需要理解"被评价 Agent 是怎么设计的"

步骤 5：生成精简版报告（严格 4 大块结构）

精简版报告结构：

一、项目整体概述（去掉代码摘取部分）
   - 1.1 项目定位（一句话说清楚 Agent 是做什么的）
   - 1.2 设计思路（从 md 文档摘录原文，不需要代码交叉验证）
   - 1.3 整体架构图（mermaid 流程图，展示模块关系）
   - 1.4 关键模块清单（文件 → 职责对照表）
   - 1.5 技术栈（语言、框架、依赖、模型、协议）
   - 1.6 文档清单与关键设计声明摘录（来自步骤 0）

二、七大模块阶段评估（与完整版保持）
   - 2.1 七大里程碑标准化表格：
     | 里程碑 | 通过标准 | 当前状态 | 当前阶段判定 | 为什么这样判定（一句话证据） |
   - 2.2 阶段判定要使用范式演进阶梯（第八节）做横向定位
   - 2.3 必须给出"判定依据"（一句话说明，不需要代码证据）

三、七大模块深度评价（精简版调整）
   - 每个里程碑独立一节，结构调整为：
     3.x.1 被评价 Agent 的设计思路（不展示代码，只讲清楚"怎么设计的"）
     3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处（与完整版相同）
     3.x.3 建议怎么改（与完整版相同）
   - **去掉**：3.x.4 概念扩展卡片（精简版不需要）
   - **保留**：差距等级（红/黄/绿）、类比解释、建议的时间划分（立即/短期/中期）

四、整体评分（与完整版保持）
   - 4.1 七维度评分表（一一对应七大里程碑）
   - 4.2 总分（百分制）
   - 4.3 架构等级判定（架构师 / 协议专家 / 脚本工程师 / 新手）
   - 4.4 一句话总结：当前阶段 + 最关键的下一步

精简版强制规则：

报告只能有 4 大块（与完整版相同）
"三、七大模块深度评价"每个里程碑不需要截取代码，只需要用一句话描述"被评价 Agent 的设计思路"
"三、七大模块深度评价"每个里程碑不需要概念扩展卡片
"二、七大模块阶段评估"的"判定依据"只需要一句话说明，不需要代码证据
必须保留：差距等级（红/黄/绿）、类比解释、建议的时间划分（立即/短期/中期）
核心目标：让用户读得懂，不需要强制页数限制

五、架构深度分析模板（严格 3 段式 + 1 概念卡片）

核心要求：三、"七大模块深度评价"中，每个里程碑必须严格按以下模板输出，顺序不可调换、子节不可省略。

模板：单个里程碑分析

## 3.x 【里程碑名称】

### 3.x.1 被评价 Agent 怎么做的（必须截取真实代码）

**代码截取**（强制，至少一段 CODE REFERENCE）：

```startLine:endLine:filepath
// 真实代码片段，含起止行号
```

**逐行解读**（讲清楚这段代码在做什么）：
- 行 X: ...
- 行 Y: ...

**行为流程图**（mermaid）：

```mermaid
graph LR
    A[输入] --> B[当前里程碑的处理]
    B --> C[输出]
```

**类比解释**（来自第六节类比库或新增）：
[用生活中的类比让不懂代码的人也能看懂]

**工程债痕迹**（如有，从第十节检测清单中判定）：
| 痕迹 | 位置 | 风险等级 |
|:---|:---|:---:|
| [如：正则解析] | [文件:行号] | 🔴 高 |

---

### 3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处

**SOTA 选择**：[公司/项目名称]（每次必须用 WebSearch 验证最新动态，不可仅依赖 reference/）

**为什么选这家做对标**：
| 选择原因 | 具体说明 |
|:---|:---|
| [行业标准/生产级验证/最新范式] | [具体证据 + 来源链接] |

**SOTA 具体怎么做**（贴 SOTA 代码示例或伪代码）：

```language
// SOTA 实现示例
```

**SOTA 设计思路**（为什么这样设计——讲清楚原理）：
| 设计决策 | 设计原理 |
|:---|:---|
| [决策1] | [背后的工程/学术原理] |
| [决策2] | [...] |

**好处 vs 坏处**（权衡分析，必须两边都写）：
| 维度 | 好处 | 坏处 |
|:---|:---|:---|
| [可靠性] | [...] | [...] |
| [性能] | [...] | [...] |
| [复杂度] | [...] | [...] |

**与被评价 Agent 的差距等级**：🔴 较大差距 / 🟡 中等差距 / 🟢 接近 SOTA

**差距证据**（一句话说清楚为什么是这个等级）：
[基于 3.x.1 的代码 vs SOTA 设计原理的对照]

---

### 3.x.3 建议怎么改

**立即行动（本周）**：
- 具体步骤 + 代码示例（贴可直接照抄的最小改动）

```language
// 立即可用的代码片段
```

**短期目标（2 周内）**：
- 具体步骤 + 涉及的依赖/工具

**中期目标（1 个月内）**：
- 具体步骤 + 验收标准

---

### 3.x.4 概念扩展卡片（辅助学习）

> **目的**：把该里程碑涉及的关键概念串成一条演进线索，帮助你建立 Agent 知识体系。

**核心概念**：[如：ReAct / Reflection / Plan-and-Execute]

**概念演进时间轴**：
| 年份 | 范式 | 核心思想 | 代表项目 |
|:---:|:---|:---|:---|
| 2022 | ReAct | Thought→Action→Observation | AutoGPT |
| 2024 | Reflection | 增加自检环节 | Reflexion |
| 2026 | Plan-and-Execute | 先规划再执行+反思 | Claude Managed Agents |

**类比解释**（来自第六节类比库，必须引用）：
[把复杂概念用生活类比讲清楚]

**深入阅读**（来自当次 WebSearch 验证过的链接）：
- [资源 1]
- [资源 2]

必填项检查清单

写完每个里程碑后，自查以下 8 项是否都填了：

3.x.1 截取了真实代码（CODE REFERENCE 格式）
3.x.1 画了 mermaid 行为流程图
3.x.1 写了类比解释
3.x.2 SOTA 选择经过当次 WebSearch 验证
3.x.2 同时写了好处和坏处（不只写一边）
3.x.2 给出了差距等级（红/黄/绿）
3.x.3 至少有一段可直接照抄的代码示例
3.x.4 概念卡片包含了演进时间轴 + 类比 + 深入阅读链接

六、类比解释技术概念（降低门槛）

核心原则：用生活中的类比解释技术概念，让不懂代码的人也能理解。

强制使用规则："三、七大模块深度评价"每个里程碑的 3.x.1（类比解释）和 3.x.4（概念扩展卡片）必须从下表中引用至少一条对应类比；如本表没有合适条目，必须新增一条到本表，再在报告中引用——确保概念辅助学习自动进入报告。

类比库（按里程碑分组，方便深度评价 3.x.4 直接调用）

协议层

技术概念	类比解释
正则解析	让 AI 写一封信，然后你用眼睛找关键词。AI 可能写错格式，你可能找错关键词，结果经常误解。
MCP / Function Calling	给 AI 一个表格，让它填空。表格有固定格式，AI 只能填空不能改格式，结果不会误解。
JSON Schema 校验	像表格的"输入限制"：性别栏只能填男/女，年龄栏只能填数字。AI 想乱填都填不进去。

大脑层

技术概念	类比解释
ReAct 单循环	像新手做饭：看到食材就动手，没有计划，经常做错。
Reflection	像有经验的厨师：每一步都尝味道，发现不对就调整。
Plan-and-Execute	像专业厨师：先写菜单、准备食材、按步骤执行、每步验证。
StateGraph	像地铁线路图：每个站点是一个步骤，每条线路是一个分支，你可以清楚看到所有可能的路径。
while 循环	像走迷宫没有地图：你只能一步步走，不知道下一步去哪，走错了只能从头开始。

记忆层

技术概念	类比解释
短期记忆	像 RAM（内存）：快速但容量有限，关机就消失。
长期记忆	像硬盘：持久但需要检索，可以跨会话保存知识。
工作记忆	像 CPU 缓存：当前任务需要的上下文，用滑动窗口控制大小。
记忆晋升	像"写日记"：把重要的事情从短期记忆（今天的想法）写到长期记忆（日记本）。

行动层

技术概念	类比解释
重试机制	像打电话没接通就等几秒再打，最多打 3 次，而不是一次没接通就放弃。
异步执行	像发邮件：你发完就去做别的事，不用等对方回复。
并行执行	像请 3 个人同时做 3 件事，而不是一个人做完再做下一件。
错误隔离	像电路的保险丝：一个房间短路不影响其他房间。

工程化

技术概念	类比解释
滑动窗口	像聊天只保留最近 10 条消息，而不是保存所有历史。
Token 成本	像手机流量：每次调用都消耗"流量"，需要控制用量。
自动化评测（Evals）	像考试自动评分：每次输出都自动检查是否达标。
Checkpointing	像游戏存档：每过一关就存档，失败了可以从存档点继续，不用从头开始。

安全性

技术概念	类比解释
沙箱隔离	像把 AI 放在玻璃房里：它可以做事，但无法触碰外面的世界，即使它犯错也不会影响你的系统。
路径白名单	像只给 AI 一把"特定房间的钥匙"，而不是"整栋楼的钥匙"。
Guardrails	像护栏：AI 在高速公路上行驶，护栏防止它冲出道路，即使它想犯错也被限制在安全范围内。
Human-in-the-loop	像自动驾驶的"确认按钮"：AI 可以做大部分事，但关键决策需要你按下确认按钮才能执行。

感知层

技术概念	类比解释
多模态感知	像司机开车：需要同时看路况、听导航、感知车身震动，不能只用一个感官。
反馈闭环	像你按了按钮，需要看到灯亮了才能确认操作成功——没有看到反馈就不能算"做完了"。
盲人打电话	只能听声音，无法看到对方的表情、手势、环境——这就是"只能读文本"的 Agent。

概念扩展卡片填写规范（写进 3.x.4 时使用）

每个里程碑的 3.x.4 概念扩展卡片必须包含以下 3 个固定字段：

**类比解释**（引用上表对应里程碑分组）：
> [从类比库中复制对应条目]

**概念演进时间轴**（用表格展示该概念近 3-5 年的演进）：
| 年份 | 范式 | 核心思想 | 代表项目 |
|:---:|:---|:---|:---|
| ... | ... | ... | ... |

**深入阅读**（来自当次 WebSearch 验证过的链接）：
- [资源 1]
- [资源 2]

七、参考框架索引

reference/ 使用约定

注意：reference/ 目录是离线缓存，每次评估必须用 WebSearch 验证最新动态（详见第一节第 5 条）。

文件头部约定：每个 reference/*.md 文件的开头必须包含 last_updated 字段：

---
project: Anthropic Claude
last_updated: 2026-04-30
verified_sources:
  - https://www.anthropic.com/research/model-context-protocol
  - https://docs.anthropic.com/...
---

刷新规则：

当 last_updated 距今 超过 3 个月 → 必须刷新（用 WebSearch 重写）
当 WebSearch 结果与文件内容冲突 → 必须刷新
刷新后更新 last_updated 字段

核心参考（详细架构见 reference/ 目录）

类别	项目	核心价值	Reference
工业级	Anthropic Claude	生产级架构、安全护栏、MCP标准	reference/anthropic.md
工业级	OpenAI Agents	模型原生集成、Guardrails、Sandbox	reference/openai.md
开源	OpenClaw	250k stars、Local-first、MCP扩展	reference/openclaw.md
开源	Hermes	自进化记忆、$1B估值	reference/hermes.md
前沿	Manus	完全自主、PlanAct、LangGraph	reference/manus.md
编排	LangGraph	StateGraph、Durable Execution	reference/langgraph.md
国内	阿里 Qoder	专家团模式、三大引擎	reference/qoder.md
国内	腾讯 CodeBuddy	P2P协作、共享任务列表	reference/codebuddy.md
国内	字节 Trae	人机协同、多模态	reference/trae.md

评估标准详解

详见 reference/evaluation-standards.md - 七大里程碑的详细设计原理。

八、范式演进阶梯

使用规则：本阶梯用于"二、七大模块阶段评估"中给被评价 Agent 横向定位。每次使用前必须用 WebSearch 验证最顶端范式是否仍是当前 SOTA。

范式演进路径（2026 年分叉结构，从下到上越新）：

                    ┌─────────────────────┐
                    │ 当前 SOTA            │
                    │ （每次评估前用       │
                    │  WebSearch 验证）    │
                    └──────────┬──────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
┌───────▼─────────┐  ┌─────────▼─────────┐  ┌────────▼────────┐
│ Composable AI   │  │ Autonomous Loop   │  │ Router-Based    │
│ (实验性,        │  │ (LangGraph        │  │ (Orchestrator   │
│  2027+ 预测)    │  │  StateGraph)      │  │  pattern)       │
└─────────────────┘  └───────────────────┘  └─────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Agent Teams         │
                    │ (Anthropic 子代理)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Multi-Agent         │
                    │ (CrewAI / AutoGen)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Plan-and-Execute    │
                    │ + Reflection        │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Reflection          │
                    │ (Reflexion, 2024)   │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ ReAct 基础版        │
                    │ (2022 年)           │
                    └─────────────────────┘

关键洞察：
1. 范式演进是分叉的，而非线性的——一个项目可能同时处于多个范式阶段。
2. 顶端"当前 SOTA"是动态变量——每次评估前必须用 WebSearch 验证。
3. 早期版本曾把 "HyperAgents (Meta, 2026.03)" 列在顶端，但来源不可考、与"主流大厂优先 + 多源交叉验证"原则冲突，已删除。

九、最终评分标准

七维度评分（严格 1:1 对齐七大里程碑）

核心原则：评分维度必须与第二节的七大里程碑一一对应，确保"评估什么 → 评分什么"形成闭环，不允许出现"评估了某项但评分里没有"或"评分里有但评估时没看"的错配。

#	评分维度	对应里程碑	权重	评分要点（满分 100）
1	协议层	协议层	20%	MCP/Function Calling + Schema 校验 + 零正则解析
2	大脑层	大脑层	18%	Plan-and-Execute / Reflection / 自检循环
3	记忆层	记忆层	15%	短长期分层 + 记忆晋升 + 上下文压缩
4	安全性	安全性	15%	沙箱隔离 + 路径白名单 + Human-in-the-loop
5	行动层	行动层	12%	重试 + 异步/并行 + 错误隔离
6	工程化	工程化	12%	滑动窗口 + Token 控制 + 自动化评测
7	感知层	感知层	8%	多模态输入 + 反馈闭环验证
	合计		100%

单维度评分细则（每个维度 0-100 分）

分数段	含义	判定参考
90-100	接近或达到 SOTA	实现了该里程碑的所有 SOTA 特征，可生产部署
70-89	主流方案	用了主流框架，但缺 1-2 个 SOTA 特征
50-69	基础实现	有基本功能，但是 2024-2025 年的旧范式
30-49	简陋实现	只满足"能跑"，存在关键工程债
0-29	缺失或反范式	完全没实现，或用了 2022 年的反模式（如正则解析）

总分计算公式

总分 = Σ (维度分 × 维度权重)
     = 协议层×0.20 + 大脑层×0.18 + 记忆层×0.15 + 安全性×0.15
     + 行动层×0.12 + 工程化×0.12 + 感知层×0.08

架构等级判定

总分	架构等级	说明
80-100	架构师	接近 SOTA，可生产部署
60-79	协议专家	核心协议已迁移，需完善编排和安全
40-59	脚本工程师	有基础实现，存在关键工程债
0-39	新手	需要系统性学习 Agent 架构

评分输出模板（写进报告"四、整体评分"）

## 四、整体评分

### 4.1 七维度评分

| 维度 | 权重 | 得分 | 加权分 | 关键证据 |
|:---|:---:|:---:|:---:|:---|
| 协议层 | 20% | 30 | 6.0 | 用 re.search 解析 Thought/Action（agent_framework.py:70-71） |
| 大脑层 | 18% | 40 | 7.2 | ReAct 单循环，无 Plan/Reflection |
| 记忆层 | 15% | 25 | 3.75 | 仅 self.messages 单层 list |
| 安全性 | 15% | 20 | 3.0 | 无沙箱、无路径白名单 |
| 行动层 | 12% | 35 | 4.2 | 同步阻塞、无重试 |
| 工程化 | 12% | 30 | 3.6 | 仅 max_steps，无 token 控制 |
| 感知层 | 8% | 30 | 2.4 | 仅文本输入，无反馈闭环 |
| **合计** | | | **30.15** | |

### 4.2 总分：30 / 100

### 4.3 架构等级：新手

### 4.4 一句话总结
当前是 2022 年 ReAct 范式的最小可行版本，最关键的下一步是**把正则解析改为 Function Calling**（一周内可完成，立即提升协议层 30 分）。

十、工程债检测

氛围感编程（Vibe Coding）定义

定义：依赖模型运气而非系统设计，易因幻觉/格式偏差失败。

检测清单

痕迹	检测方法	风险等级
正则解析 Thought/Action	搜索 `re.search` + `Thought`	🔴 高
启发式判断状态	搜索 `if` + `ready` + `heuristic`	🟡 中
无工具调用 schema	检查 tools 文件是否有 JSON Schema	🔴 高
无执行沙箱	检查是否有 docker/容器相关代码	🔴 高
无重试机制	检查是否有 `retry` + `timeout`	🟡 中

十一、输出标准

重要说明：本 Skill 支持两种报告版本——完整版（含代码细节）和精简版（仅结论和建议）。在开始评估前，必须先询问用户需要的版本（见第四节步骤 0.5）。

完整版评价报告必须严格包含 4 大块（不多不少）

** 一、项目整体概况**——含项目定位、设计思路（来自 md 文档原文摘录+代码验证）、整体架构 mermaid 图、关键模块清单、技术栈、文档清单
** 二、七大模块阶段评估**——七大里程碑清单表 + 当前阶段 + 为什么这样判定 + 代码证据
** 三、七大模块深度评价**——每个里程碑严格 3 段式 + 1 概念扩展卡片（详见第五节模板）；工程债下沉为子条目，不单独成块
** 四、整体评分**——七维度评分（与七大里程碑 1:1）+ 总分 + 架构等级判定 + 一句话总结

精简版评价报告必须严格包含 4 大块（与完整版结构相同，但内容精简）

** 一、项目整体概述**——含项目定位、设计思路（来自 md 文档原文摘录，不需要代码验证）、整体架构 mermaid 图、关键模块清单、技术栈、文档清单
** 二、七大模块阶段评估**——七大里程碑清单表 + 当前阶段 + 为什么这样判定（一句话说明，不需要代码证据）
** 三、七大模块深度评价**——每个里程碑 3 段式（去掉 3.x.4 概念扩展卡片）；3.x.1 只讲设计思路，不展示代码；保留差距等级、类比解释、建议时间划分
** 四、整体评分**——七维度评分（与七大里程碑 1:1）+ 总分 + 架构等级判定 + 一句话总结

完整版强制规则（违反任何一条都视为报告不合格）

规则	具体要求
结构唯一性	报告只能有 4 大块；"工程债""可执行建议""SOTA 对标"等不允许独立成块
代码截取强制	"三、七大模块深度评价"每个里程碑的"被评价 Agent 怎么做的"必须用 CODE REFERENCE 引用真实代码（含起止行号）
类比强制	每个里程碑必须包含一个类比解释（来自第六节类比库或新增）
文档摘录强制	"一、项目整体概况"的"设计思路"必须从 md 文档中摘录原文，不能凭空总结
SOTA 验证强制	"三、七大模块深度评价"的 SOTA 对标必须经过当次 WebSearch 验证（不能完全依赖 reference/ 静态文件）
评分对齐	"四、整体评分"评分维度必须严格对应"二、七大模块阶段评估"七大里程碑，权重见第九节

精简版强制规则（违反任何一条都视为报告不合格）

规则	具体要求
结构唯一性	报告只能有 4 大块（与完整版相同）
代码截取禁止	"三、七大模块深度评价"每个里程碑的"被评价 Agent 的设计思路"不需要截取代码，只需要一句话描述
类比强制	每个里程碑必须包含一个类比解释（来自第六节类比库或新增）——这是让不懂代码的用户理解的关键
差距等级强制	每个里程碑必须给出差距等级（红/黄/绿）——这是用户最关心的评估结论
建议时间划分强制	每个里程碑的建议必须分为"立即/短期/中期"——这是用户最关心的下一步
文档摘录强制	"一、项目整体概述"的"设计思路"必须从 md 文档中摘录原文，不能凭空总结
SOTA 验证强制	"三、七大模块深度评价"的 SOTA 对标必须经过当次 WebSearch 验证（不能完全依赖 reference/ 静态文件）
评分对齐	"四、整体评分"评分维度必须严格对应"二、七大模块阶段评估"七大里程碑，权重见第九节
核心目标	让用户读得懂，不需要强制页数限制

语言要求（完整版和精简版通用）

使用用户语言（中文/英文）
技术概念必须用类比解释
完整版：代码引用必须使用 CODE REFERENCE 格式（含文件路径和行号）
精简版：不需要代码引用，但必须用类比解释技术概念
SOTA 对标必须包含选择逻辑和设计原理

name	agent-evaluator
version	1.0.2
author	BEIBEICSY
description	评价 AI Agent 项目架构，对标 SOTA 标准。当用户要求评价 Agent 项目、分析架构差距、或对比主流大厂方案时调用。支持完整版（含代码细节）和精简版（仅结论和建议）两种报告格式。
github	https://github.com/BEIBEICSY/awesome-agent-evaluator-skill

AI Agent 项目评价 Skill

使命：降低学习/构建 Agent 的门槛，让不懂代码的人也能理解"为什么这样设计"。

一、核心原则

1. SOTA 标准评价

定义: SOTA = State of the Art（当前最佳技术）

要求: 每次评价必须对标当前年份的行业最高水平，而非过时范式。

目的: 确保及时学习最新知识，避免停留在 2022-2025 年的旧范式。

2. 搜索年份动态调整

要求: 搜索时必须根据当前日期动态调整年份关键词。

当前日期: 2026-04-30

示例:

错误做法: "AI agent architecture 2025"  ← 信息滞后
正确做法: "AI agent architecture 2026"  ← 获取最新信息

3. 主流大厂优先

要求: 搜索参考时优先 Follow 主流大厂官方文档，而非小众实验性框架。

目的: 参考经过大规模验证的生产级方案。

4. 强制先检索（最重要！）

要求: 在评价任何 Agent 项目前，必须先执行 SOTA 搜索，获取最新信息。

原因:

AI Agent 领域在 2026 年发展极快，3 个月前的知识可能已过时
不检索最新信息，评价可能基于错误的假设
检索结果必须多源交叉验证

5. reference/ 与 WebSearch 的边界（重要！）

核心定位：

信息源	定位	使用方式
`reference/` 目录的 9 个静态文档	离线缓存 / 启动模板	用于快速建立对各厂商的初步认知，不可作为最终结论的唯一依据
WebSearch（每次评估必须执行）	真相来源 / 最新事实	每次评估都必须重新搜索，验证 reference/ 内容是否过期

强制规则：

报告第三部分每个里程碑的 SOTA 对标，必须在当次会话中通过 WebSearch 验证至少一项最新事实（如版本号、API 变更、新发布的论文/产品）
当 WebSearch 结果与 reference/ 静态文档冲突时，以 WebSearch 为准，并在报告中注明"reference/ 已过期"
当 reference/ 文件的 last_updated 距今超过 3 个月时，必须执行刷新（用 WebSearch 找最新内容并更新 reference/ 文件）

二、评估清单（七大里程碑）

核心洞察：这七个里程碑不是随意选择的，而是基于 Agent 的本质定义：Agent = LLM + System + Environment。

里程碑详解

里程碑	通过标准	为什么这是标准（设计原理）	来源
感知层	多模态反馈闭环	核心洞察：Agent 的行动能力受限于它的感知能力。一个只能"读文本"的 Agent，就像一个只能听电话的盲人——它无法理解 UI 截图、无法识别图表、无法感知用户语气。设计原理：感知 → 解释 → 决策 → 行动 → 再次感知，这是一个闭环。没有闭环，Agent 就无法验证自己的行动是否有效。	Perception in AI Agents 2026
大脑层	Plan-and-Execute 或自反思循环	核心洞察：ReAct（2022年）是基础版，但 2026 年的 SOTA 已经进化到 Plan-and-Execute（先规划再执行）或自反思循环（每一步都自检）。设计原理：LLM 的推理是概率性的，单次推理容易出错。通过"规划 → 执行 → 反思 → 调整"的循环，可以显著提高可靠性。	AI Agent Architecture 2026 Guide
协议层	MCP 或结构化函数调用（零正则解析）	核心洞察：正则解析依赖模型输出格式的稳定性，这是 2022-2023 年的旧范式。2026 年的 SOTA 是 MCP（Anthropic）或 Function Calling（OpenAI），它们通过 schema 强制校验，从根本上消除了格式解析失败的风险。设计原理：LLM 输出是概率性的，正则解析是确定性的——两者不兼容。结构化协议让模型输出"被迫"符合 schema，从根本上解决了可靠性问题。	MCP vs Function Calling 2026
行动层	异步/并行执行与错误容错	核心洞察：生产环境的 Agent 会遇到网络超时、API 限流、服务重启等问题。没有重试机制和异步执行，Agent 会频繁失败。设计原理：Agent 的执行链路有多点故障（LLM 调用、工具执行、网络请求），每个点都需要独立的错误处理和重试策略。	AI Agent Best Practices 2026
记忆层	分层管理（向量长时记忆 vs 上下文短时记忆）	核心洞察：LLM 的上下文窗口是有限的（即使 GPT-5 有 100k tokens，也会被填满）。没有分层记忆，Agent 会"忘记"之前学到的知识。设计原理：短期记忆（当前会话）像 RAM，快速但容量有限；长期记忆（跨会话）像硬盘，持久但需要检索。两者分离，才能既保持推理效率，又积累长期知识。	Redis: AI Agent Memory
工程化	上下文滑动窗口、Token 成本控制与自动化评测	核心洞察：LLM 调用是昂贵的（每次推理都消耗 tokens）。没有成本控制和评测系统，Agent 的运营成本会失控。设计原理：上下文滑动窗口防止 token 爆炸；自动化评测（Evals）确保 Agent 输出质量稳定。	AI Agent Infrastructure 2026
安全性	执行沙箱、路径白名单及敏感操作的人工确认机制	核心洞察：Agent 会执行代码、读写文件、调用 API。没有沙箱隔离，Agent 可能误删文件、泄露数据、执行恶意代码。设计原理：沙箱隔离（容器化）防止 Agent 影响宿主系统；路径白名单限制 Agent 只能访问特定目录；敏感操作确认（Human-in-the-loop）防止 Agent 自主执行高风险操作。	GKE: Secure AI Agents

三、SOTA 对标选择逻辑

核心问题：为什么选择这些公司作为 SOTA 对标？为什么不参考其他？

选择原则

选择优先级排序：

1. 【行业标准制定者】（最高优先级）
   - Anthropic (MCP)：MCP 是开放标准，Anthropic 是标准制定者
   - OpenAI (Function Calling)：Function Calling 是实践标准，OpenAI 是标准制定者
   - 选择原因：参考标准制定者，就是参考行业最高水平

2. 【生产级验证】（高优先级）
   - LangGraph：25k stars，被 Klarna、Replit、Elastic 采用
   - 选择原因：经过大规模生产验证，不是实验性框架

3. 【最新范式】（高优先级）
   - Manus：完全自主执行 + Sandbox 隔离
   - Hermes：自进化记忆 + $1B 估值
   - 选择原因：代表 2026 年的最新范式，不是 2022-2023 年的旧范式

不参考的原因

不参考的公司/项目	原因	具体说明
AutoGPT	旧范式	182k stars，但仍是 2022 年的 ReAct 正则解析范式，不是 2026 年的 SOTA
CrewAI	编排不可控	45k stars，但使用"对话式编排"，无法保证执行路径可控，不适合生产环境
小众 GitHub 项目	未验证	stars < 10k，无生产验证，可能存在未知问题
Devin	场景单一	自主编程，但场景单一（仅编程），无法代表通用 Agent 架构

四、评价执行流程

步骤 0：询问报告版本（强制！）

核心要求：在开始读取项目代码前，必须先询问用户需要的报告版本。

必须执行的操作：

使用 AskUserQuestion 工具询问用户：

问题	选项	说明
"您需要哪种版本的评估报告？"	完整版（推荐给想要学习详尽架构设计的用户）	包含所有代码截取、逐行解读、mermaid 流程图、概念扩展卡片
	精简版（推荐给只想要评估结果和改进建议的用户）	去掉代码截取和逐行解读，只保留设计思路、差距分析、改进建议

询问时必须包含的说明：

完整版：适合想要深入理解 Agent 架构设计的用户，报告较长，包含大量代码示例和类比解释。适合想要学习"为什么这样设计"的用户。
精简版：适合只想要"结论+下一步"的用户，报告较短，不包含代码细节，但保留所有评估结论和改进建议。适合不愿意阅读代码的用户。

用户选择后的处理：

如果用户选择"完整版" → 按完整版流程执行（步骤 1-5）
如果用户选择"精简版" → 按精简版流程执行（见下文"精简版执行流程"）

步骤 1：通读项目所有 md / README / docs（强制！）

核心要求：在动任何代码之前，必须先把项目里所有的文档读完——这是理解作者"设计思路"的唯一途径，也是写出"一、项目整体概况"的前提。

必须执行的操作：

1. 用 Glob 列出项目所有 md/markdown/rst/txt 文档：
   - **/README*
   - **/*.md
   - **/docs/**
   - **/CHANGELOG*
   - **/ARCHITECTURE*
   - **/DESIGN*

2. 用 Read 通读每一份文档，重点提取：
   - 作者明示的设计目标 / 设计思路 / 取舍说明
   - 整体架构图 / 模块划分 / 数据流
   - 已知限制 / TODO / Roadmap
   - 引用的论文 / 框架 / SOTA 对标

3. 输出文档清单与摘录（写进报告"一、项目整体概况"）：
   | 文档路径 | 类型 | 关键设计声明摘录 |
   |:---|:---|:---|
   | README.md | 入口 | "本项目是一个 ReAct + 正则解析的本地 Agent..." |

为什么这一步是强制的：

不读 md 文档 → 只能从代码逆推设计意图，容易误判作者初衷
读了 md 文档 → 能把"作者怎么想的"和"代码怎么实现的"做交叉验证，识别设计思路与代码实现之间的偏差
如果项目没有任何 md 文档：必须在报告中明确指出"项目缺少设计文档"——这本身就是一个工程债

步骤 2：识别项目类型

首先识别用户要评价的项目类型：

- Agent 项目: 包含 agent、智能体、agent_framework 等关键词
- Coding Agent: 包含 coding、编程、代码生成等关键词
- Multi-Agent: 包含 multi-agent、协作、团队等关键词
- 通用 Agent: 包含 general、通用、manus 等关键词
- 自主执行 Agent: 包含 autonomous、自主、sandbox 等关键词

步骤 3：执行 SOTA 搜索（强制先检索！）

强制要求：在评价任何 Agent 项目前，必须先执行以下搜索：

搜索关键词模板：

# 1. 学术前沿（最新技术突破）
arXiv AI agent 2026
AI agent paper 2026
AI agent architecture 2026

# 2. 官方文档（生产级方案）
Anthropic MCP official documentation 2026
OpenAI Function Calling official guide 2026
LangGraph StateGraph architecture 2026

# 3. 开源实现（实际实现）
GitHub AI agent trending 2026
AI agent implementation 2026

# 4. 监管动态（合规安全）
AI agent acquisition 2026
AI agent regulation 2026
AI agent sandbox security 2026

验证要求：至少 3 个来源交叉验证，确保信息一致。

步骤 4：读取项目代码

必须读取的核心文件：

1. 主入口文件（main.py / app.py / index.js）
2. 工具定义文件（tools.py / tools.js）
3. 配置文件（config.py / config.json）
4. Prompt 文件（prompts/ 目录）
5. 记忆系统文件（memory.py / memory.json）

步骤 5：生成评价报告（严格 4 大块结构）

报告必须严格按以下 4 大块输出——这是用户预期的报告框架，不允许新增/删除/合并模块：

一、项目整体概况
   - 1.1 项目定位（一句话说清楚 Agent 是做什么的）
   - 1.2 设计思路（作者怎么想的，从 md 文档摘录原文 + 代码交叉验证）
   - 1.3 整体架构图（mermaid 流程图，展示模块关系与数据流）
   - 1.4 关键模块清单（文件 → 职责对照表）
   - 1.5 技术栈（语言、框架、依赖、模型、协议）
   - 1.6 文档清单与关键设计声明摘录（来自步骤 1）

二、七大模块阶段评估（清单进度）
   - 2.1 七大里程碑标准化表格：
     | 里程碑 | 通过标准 | 当前状态 | 当前阶段判定 | 为什么这样判定（一句话证据） |
   - 2.2 阶段判定要使用范式演进阶梯（第八节）做横向定位
   - 2.3 必须给出"代码证据"——从被评价 Agent 中找一行/一段代码作为判定依据

三、七大模块深度评价（核心，严格 3 段式 + 1 概念卡片）
   - 按七大里程碑顺序，每个里程碑独立一节，必须严格按以下子结构：
     3.x.1 被评价 Agent 怎么做的（必须截取真实代码）
     3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处
     3.x.3 建议怎么改（立即/短期/中期）
     3.x.4 概念扩展卡片（辅助学习）
   - 工程债检测下沉为每个里程碑 3.x.1 的子条目（不再单独成块）

四、整体评分
   - 4.1 七维度评分表（一一对应七大里程碑）
   - 4.2 总分（百分制）
   - 4.3 架构等级判定（架构师 / 协议专家 / 脚本工程师 / 新手）
   - 4.4 一句话总结：当前阶段 + 最关键的下一步

强制规则：

报告只能有这四部分，不允许新增"工程债检测""可执行建议""SOTA 对标深度解析"等独立模块——这些都已下沉到"三、七大模块深度评价"的子节
"三、七大模块深度评价"每个里程碑必须截取真实代码（用 CODE REFERENCE 格式 startLine:endLine:filepath）
"四、整体评分"的评分维度必须严格对应"二、七大模块阶段评估"的七大里程碑，权重见第九节

精简版执行流程（用户选择"精简版"时执行）

核心差异：精简版不截取代码、不逐行解读，只保留设计思路和改进建议。目标是让不愿意阅读代码的用户也能理解评估结论和下一步改进建议。

执行步骤：

步骤 1-3：与完整版相同

步骤 1：通读项目所有 md 文档（强制）
步骤 2：识别项目类型
步骤 3：执行 SOTA 搜索（强制）

步骤 4：读取项目代码（精简版调整）

只读取关键文件，不需要截取代码片段
重点提取：设计思路、架构模式、关键决策，而非具体实现细节
不需要记录代码行号，只需要理解"被评价 Agent 是怎么设计的"

步骤 5：生成精简版报告（严格 4 大块结构）

精简版报告结构：

一、项目整体概述（去掉代码摘取部分）
   - 1.1 项目定位（一句话说清楚 Agent 是做什么的）
   - 1.2 设计思路（从 md 文档摘录原文，不需要代码交叉验证）
   - 1.3 整体架构图（mermaid 流程图，展示模块关系）
   - 1.4 关键模块清单（文件 → 职责对照表）
   - 1.5 技术栈（语言、框架、依赖、模型、协议）
   - 1.6 文档清单与关键设计声明摘录（来自步骤 0）

二、七大模块阶段评估（与完整版保持）
   - 2.1 七大里程碑标准化表格：
     | 里程碑 | 通过标准 | 当前状态 | 当前阶段判定 | 为什么这样判定（一句话证据） |
   - 2.2 阶段判定要使用范式演进阶梯（第八节）做横向定位
   - 2.3 必须给出"判定依据"（一句话说明，不需要代码证据）

三、七大模块深度评价（精简版调整）
   - 每个里程碑独立一节，结构调整为：
     3.x.1 被评价 Agent 的设计思路（不展示代码，只讲清楚"怎么设计的"）
     3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处（与完整版相同）
     3.x.3 建议怎么改（与完整版相同）
   - **去掉**：3.x.4 概念扩展卡片（精简版不需要）
   - **保留**：差距等级（红/黄/绿）、类比解释、建议的时间划分（立即/短期/中期）

四、整体评分（与完整版保持）
   - 4.1 七维度评分表（一一对应七大里程碑）
   - 4.2 总分（百分制）
   - 4.3 架构等级判定（架构师 / 协议专家 / 脚本工程师 / 新手）
   - 4.4 一句话总结：当前阶段 + 最关键的下一步

精简版强制规则：

报告只能有 4 大块（与完整版相同）
"三、七大模块深度评价"每个里程碑不需要截取代码，只需要用一句话描述"被评价 Agent 的设计思路"
"三、七大模块深度评价"每个里程碑不需要概念扩展卡片
"二、七大模块阶段评估"的"判定依据"只需要一句话说明，不需要代码证据
必须保留：差距等级（红/黄/绿）、类比解释、建议的时间划分（立即/短期/中期）
核心目标：让用户读得懂，不需要强制页数限制

五、架构深度分析模板（严格 3 段式 + 1 概念卡片）

核心要求：三、"七大模块深度评价"中，每个里程碑必须严格按以下模板输出，顺序不可调换、子节不可省略。

模板：单个里程碑分析

## 3.x 【里程碑名称】

### 3.x.1 被评价 Agent 怎么做的（必须截取真实代码）

**代码截取**（强制，至少一段 CODE REFERENCE）：

```startLine:endLine:filepath
// 真实代码片段，含起止行号
```

**逐行解读**（讲清楚这段代码在做什么）：
- 行 X: ...
- 行 Y: ...

**行为流程图**（mermaid）：

```mermaid
graph LR
    A[输入] --> B[当前里程碑的处理]
    B --> C[输出]
```

**类比解释**（来自第六节类比库或新增）：
[用生活中的类比让不懂代码的人也能看懂]

**工程债痕迹**（如有，从第十节检测清单中判定）：
| 痕迹 | 位置 | 风险等级 |
|:---|:---|:---:|
| [如：正则解析] | [文件:行号] | 🔴 高 |

---

### 3.x.2 SOTA 怎么做的 + 设计思路 + 好处/坏处

**SOTA 选择**：[公司/项目名称]（每次必须用 WebSearch 验证最新动态，不可仅依赖 reference/）

**为什么选这家做对标**：
| 选择原因 | 具体说明 |
|:---|:---|
| [行业标准/生产级验证/最新范式] | [具体证据 + 来源链接] |

**SOTA 具体怎么做**（贴 SOTA 代码示例或伪代码）：

```language
// SOTA 实现示例
```

**SOTA 设计思路**（为什么这样设计——讲清楚原理）：
| 设计决策 | 设计原理 |
|:---|:---|
| [决策1] | [背后的工程/学术原理] |
| [决策2] | [...] |

**好处 vs 坏处**（权衡分析，必须两边都写）：
| 维度 | 好处 | 坏处 |
|:---|:---|:---|
| [可靠性] | [...] | [...] |
| [性能] | [...] | [...] |
| [复杂度] | [...] | [...] |

**与被评价 Agent 的差距等级**：🔴 较大差距 / 🟡 中等差距 / 🟢 接近 SOTA

**差距证据**（一句话说清楚为什么是这个等级）：
[基于 3.x.1 的代码 vs SOTA 设计原理的对照]

---

### 3.x.3 建议怎么改

**立即行动（本周）**：
- 具体步骤 + 代码示例（贴可直接照抄的最小改动）

```language
// 立即可用的代码片段
```

**短期目标（2 周内）**：
- 具体步骤 + 涉及的依赖/工具

**中期目标（1 个月内）**：
- 具体步骤 + 验收标准

---

### 3.x.4 概念扩展卡片（辅助学习）

> **目的**：把该里程碑涉及的关键概念串成一条演进线索，帮助你建立 Agent 知识体系。

**核心概念**：[如：ReAct / Reflection / Plan-and-Execute]

**概念演进时间轴**：
| 年份 | 范式 | 核心思想 | 代表项目 |
|:---:|:---|:---|:---|
| 2022 | ReAct | Thought→Action→Observation | AutoGPT |
| 2024 | Reflection | 增加自检环节 | Reflexion |
| 2026 | Plan-and-Execute | 先规划再执行+反思 | Claude Managed Agents |

**类比解释**（来自第六节类比库，必须引用）：
[把复杂概念用生活类比讲清楚]

**深入阅读**（来自当次 WebSearch 验证过的链接）：
- [资源 1]
- [资源 2]

必填项检查清单

写完每个里程碑后，自查以下 8 项是否都填了：

3.x.1 截取了真实代码（CODE REFERENCE 格式）
3.x.1 画了 mermaid 行为流程图
3.x.1 写了类比解释
3.x.2 SOTA 选择经过当次 WebSearch 验证
3.x.2 同时写了好处和坏处（不只写一边）
3.x.2 给出了差距等级（红/黄/绿）
3.x.3 至少有一段可直接照抄的代码示例
3.x.4 概念卡片包含了演进时间轴 + 类比 + 深入阅读链接

六、类比解释技术概念（降低门槛）

核心原则：用生活中的类比解释技术概念，让不懂代码的人也能理解。

强制使用规则："三、七大模块深度评价"每个里程碑的 3.x.1（类比解释）和 3.x.4（概念扩展卡片）必须从下表中引用至少一条对应类比；如本表没有合适条目，必须新增一条到本表，再在报告中引用——确保概念辅助学习自动进入报告。

类比库（按里程碑分组，方便深度评价 3.x.4 直接调用）

协议层

技术概念	类比解释
正则解析	让 AI 写一封信，然后你用眼睛找关键词。AI 可能写错格式，你可能找错关键词，结果经常误解。
MCP / Function Calling	给 AI 一个表格，让它填空。表格有固定格式，AI 只能填空不能改格式，结果不会误解。
JSON Schema 校验	像表格的"输入限制"：性别栏只能填男/女，年龄栏只能填数字。AI 想乱填都填不进去。

大脑层

技术概念	类比解释
ReAct 单循环	像新手做饭：看到食材就动手，没有计划，经常做错。
Reflection	像有经验的厨师：每一步都尝味道，发现不对就调整。
Plan-and-Execute	像专业厨师：先写菜单、准备食材、按步骤执行、每步验证。
StateGraph	像地铁线路图：每个站点是一个步骤，每条线路是一个分支，你可以清楚看到所有可能的路径。
while 循环	像走迷宫没有地图：你只能一步步走，不知道下一步去哪，走错了只能从头开始。

记忆层

技术概念	类比解释
短期记忆	像 RAM（内存）：快速但容量有限，关机就消失。
长期记忆	像硬盘：持久但需要检索，可以跨会话保存知识。
工作记忆	像 CPU 缓存：当前任务需要的上下文，用滑动窗口控制大小。
记忆晋升	像"写日记"：把重要的事情从短期记忆（今天的想法）写到长期记忆（日记本）。

行动层

技术概念	类比解释
重试机制	像打电话没接通就等几秒再打，最多打 3 次，而不是一次没接通就放弃。
异步执行	像发邮件：你发完就去做别的事，不用等对方回复。
并行执行	像请 3 个人同时做 3 件事，而不是一个人做完再做下一件。
错误隔离	像电路的保险丝：一个房间短路不影响其他房间。

工程化

技术概念	类比解释
滑动窗口	像聊天只保留最近 10 条消息，而不是保存所有历史。
Token 成本	像手机流量：每次调用都消耗"流量"，需要控制用量。
自动化评测（Evals）	像考试自动评分：每次输出都自动检查是否达标。
Checkpointing	像游戏存档：每过一关就存档，失败了可以从存档点继续，不用从头开始。

安全性

技术概念	类比解释
沙箱隔离	像把 AI 放在玻璃房里：它可以做事，但无法触碰外面的世界，即使它犯错也不会影响你的系统。
路径白名单	像只给 AI 一把"特定房间的钥匙"，而不是"整栋楼的钥匙"。
Guardrails	像护栏：AI 在高速公路上行驶，护栏防止它冲出道路，即使它想犯错也被限制在安全范围内。
Human-in-the-loop	像自动驾驶的"确认按钮"：AI 可以做大部分事，但关键决策需要你按下确认按钮才能执行。

感知层

技术概念	类比解释
多模态感知	像司机开车：需要同时看路况、听导航、感知车身震动，不能只用一个感官。
反馈闭环	像你按了按钮，需要看到灯亮了才能确认操作成功——没有看到反馈就不能算"做完了"。
盲人打电话	只能听声音，无法看到对方的表情、手势、环境——这就是"只能读文本"的 Agent。

概念扩展卡片填写规范（写进 3.x.4 时使用）

每个里程碑的 3.x.4 概念扩展卡片必须包含以下 3 个固定字段：

**类比解释**（引用上表对应里程碑分组）：
> [从类比库中复制对应条目]

**概念演进时间轴**（用表格展示该概念近 3-5 年的演进）：
| 年份 | 范式 | 核心思想 | 代表项目 |
|:---:|:---|:---|:---|
| ... | ... | ... | ... |

**深入阅读**（来自当次 WebSearch 验证过的链接）：
- [资源 1]
- [资源 2]

七、参考框架索引

reference/ 使用约定

注意：reference/ 目录是离线缓存，每次评估必须用 WebSearch 验证最新动态（详见第一节第 5 条）。

文件头部约定：每个 reference/*.md 文件的开头必须包含 last_updated 字段：

---
project: Anthropic Claude
last_updated: 2026-04-30
verified_sources:
  - https://www.anthropic.com/research/model-context-protocol
  - https://docs.anthropic.com/...
---

刷新规则：

当 last_updated 距今 超过 3 个月 → 必须刷新（用 WebSearch 重写）
当 WebSearch 结果与文件内容冲突 → 必须刷新
刷新后更新 last_updated 字段

核心参考（详细架构见 reference/ 目录）

类别	项目	核心价值	Reference
工业级	Anthropic Claude	生产级架构、安全护栏、MCP标准	reference/anthropic.md
工业级	OpenAI Agents	模型原生集成、Guardrails、Sandbox	reference/openai.md
开源	OpenClaw	250k stars、Local-first、MCP扩展	reference/openclaw.md
开源	Hermes	自进化记忆、$1B估值	reference/hermes.md
前沿	Manus	完全自主、PlanAct、LangGraph	reference/manus.md
编排	LangGraph	StateGraph、Durable Execution	reference/langgraph.md
国内	阿里 Qoder	专家团模式、三大引擎	reference/qoder.md
国内	腾讯 CodeBuddy	P2P协作、共享任务列表	reference/codebuddy.md
国内	字节 Trae	人机协同、多模态	reference/trae.md

评估标准详解

详见 reference/evaluation-standards.md - 七大里程碑的详细设计原理。

八、范式演进阶梯

使用规则：本阶梯用于"二、七大模块阶段评估"中给被评价 Agent 横向定位。每次使用前必须用 WebSearch 验证最顶端范式是否仍是当前 SOTA。

范式演进路径（2026 年分叉结构，从下到上越新）：

                    ┌─────────────────────┐
                    │ 当前 SOTA            │
                    │ （每次评估前用       │
                    │  WebSearch 验证）    │
                    └──────────┬──────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
┌───────▼─────────┐  ┌─────────▼─────────┐  ┌────────▼────────┐
│ Composable AI   │  │ Autonomous Loop   │  │ Router-Based    │
│ (实验性,        │  │ (LangGraph        │  │ (Orchestrator   │
│  2027+ 预测)    │  │  StateGraph)      │  │  pattern)       │
└─────────────────┘  └───────────────────┘  └─────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Agent Teams         │
                    │ (Anthropic 子代理)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Multi-Agent         │
                    │ (CrewAI / AutoGen)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Plan-and-Execute    │
                    │ + Reflection        │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ Reflection          │
                    │ (Reflexion, 2024)   │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │ ReAct 基础版        │
                    │ (2022 年)           │
                    └─────────────────────┘

关键洞察：
1. 范式演进是分叉的，而非线性的——一个项目可能同时处于多个范式阶段。
2. 顶端"当前 SOTA"是动态变量——每次评估前必须用 WebSearch 验证。
3. 早期版本曾把 "HyperAgents (Meta, 2026.03)" 列在顶端，但来源不可考、与"主流大厂优先 + 多源交叉验证"原则冲突，已删除。

九、最终评分标准

七维度评分（严格 1:1 对齐七大里程碑）

核心原则：评分维度必须与第二节的七大里程碑一一对应，确保"评估什么 → 评分什么"形成闭环，不允许出现"评估了某项但评分里没有"或"评分里有但评估时没看"的错配。

#	评分维度	对应里程碑	权重	评分要点（满分 100）
1	协议层	协议层	20%	MCP/Function Calling + Schema 校验 + 零正则解析
2	大脑层	大脑层	18%	Plan-and-Execute / Reflection / 自检循环
3	记忆层	记忆层	15%	短长期分层 + 记忆晋升 + 上下文压缩
4	安全性	安全性	15%	沙箱隔离 + 路径白名单 + Human-in-the-loop
5	行动层	行动层	12%	重试 + 异步/并行 + 错误隔离
6	工程化	工程化	12%	滑动窗口 + Token 控制 + 自动化评测
7	感知层	感知层	8%	多模态输入 + 反馈闭环验证
	合计		100%

单维度评分细则（每个维度 0-100 分）

分数段	含义	判定参考
90-100	接近或达到 SOTA	实现了该里程碑的所有 SOTA 特征，可生产部署
70-89	主流方案	用了主流框架，但缺 1-2 个 SOTA 特征
50-69	基础实现	有基本功能，但是 2024-2025 年的旧范式
30-49	简陋实现	只满足"能跑"，存在关键工程债
0-29	缺失或反范式	完全没实现，或用了 2022 年的反模式（如正则解析）

总分计算公式

总分 = Σ (维度分 × 维度权重)
     = 协议层×0.20 + 大脑层×0.18 + 记忆层×0.15 + 安全性×0.15
     + 行动层×0.12 + 工程化×0.12 + 感知层×0.08

架构等级判定

总分	架构等级	说明
80-100	架构师	接近 SOTA，可生产部署
60-79	协议专家	核心协议已迁移，需完善编排和安全
40-59	脚本工程师	有基础实现，存在关键工程债
0-39	新手	需要系统性学习 Agent 架构

评分输出模板（写进报告"四、整体评分"）

## 四、整体评分

### 4.1 七维度评分

| 维度 | 权重 | 得分 | 加权分 | 关键证据 |
|:---|:---:|:---:|:---:|:---|
| 协议层 | 20% | 30 | 6.0 | 用 re.search 解析 Thought/Action（agent_framework.py:70-71） |
| 大脑层 | 18% | 40 | 7.2 | ReAct 单循环，无 Plan/Reflection |
| 记忆层 | 15% | 25 | 3.75 | 仅 self.messages 单层 list |
| 安全性 | 15% | 20 | 3.0 | 无沙箱、无路径白名单 |
| 行动层 | 12% | 35 | 4.2 | 同步阻塞、无重试 |
| 工程化 | 12% | 30 | 3.6 | 仅 max_steps，无 token 控制 |
| 感知层 | 8% | 30 | 2.4 | 仅文本输入，无反馈闭环 |
| **合计** | | | **30.15** | |

### 4.2 总分：30 / 100

### 4.3 架构等级：新手

### 4.4 一句话总结
当前是 2022 年 ReAct 范式的最小可行版本，最关键的下一步是**把正则解析改为 Function Calling**（一周内可完成，立即提升协议层 30 分）。

十、工程债检测

氛围感编程（Vibe Coding）定义

定义：依赖模型运气而非系统设计，易因幻觉/格式偏差失败。

检测清单

痕迹	检测方法	风险等级
正则解析 Thought/Action	搜索 `re.search` + `Thought`	🔴 高
启发式判断状态	搜索 `if` + `ready` + `heuristic`	🟡 中
无工具调用 schema	检查 tools 文件是否有 JSON Schema	🔴 高
无执行沙箱	检查是否有 docker/容器相关代码	🔴 高
无重试机制	检查是否有 `retry` + `timeout`	🟡 中

十一、输出标准

重要说明：本 Skill 支持两种报告版本——完整版（含代码细节）和精简版（仅结论和建议）。在开始评估前，必须先询问用户需要的版本（见第四节步骤 0.5）。

完整版评价报告必须严格包含 4 大块（不多不少）

** 一、项目整体概况**——含项目定位、设计思路（来自 md 文档原文摘录+代码验证）、整体架构 mermaid 图、关键模块清单、技术栈、文档清单
** 二、七大模块阶段评估**——七大里程碑清单表 + 当前阶段 + 为什么这样判定 + 代码证据
** 三、七大模块深度评价**——每个里程碑严格 3 段式 + 1 概念扩展卡片（详见第五节模板）；工程债下沉为子条目，不单独成块
** 四、整体评分**——七维度评分（与七大里程碑 1:1）+ 总分 + 架构等级判定 + 一句话总结

精简版评价报告必须严格包含 4 大块（与完整版结构相同，但内容精简）

** 一、项目整体概述**——含项目定位、设计思路（来自 md 文档原文摘录，不需要代码验证）、整体架构 mermaid 图、关键模块清单、技术栈、文档清单
** 二、七大模块阶段评估**——七大里程碑清单表 + 当前阶段 + 为什么这样判定（一句话说明，不需要代码证据）
** 三、七大模块深度评价**——每个里程碑 3 段式（去掉 3.x.4 概念扩展卡片）；3.x.1 只讲设计思路，不展示代码；保留差距等级、类比解释、建议时间划分
** 四、整体评分**——七维度评分（与七大里程碑 1:1）+ 总分 + 架构等级判定 + 一句话总结

完整版强制规则（违反任何一条都视为报告不合格）

规则	具体要求
结构唯一性	报告只能有 4 大块；"工程债""可执行建议""SOTA 对标"等不允许独立成块
代码截取强制	"三、七大模块深度评价"每个里程碑的"被评价 Agent 怎么做的"必须用 CODE REFERENCE 引用真实代码（含起止行号）
类比强制	每个里程碑必须包含一个类比解释（来自第六节类比库或新增）
文档摘录强制	"一、项目整体概况"的"设计思路"必须从 md 文档中摘录原文，不能凭空总结
SOTA 验证强制	"三、七大模块深度评价"的 SOTA 对标必须经过当次 WebSearch 验证（不能完全依赖 reference/ 静态文件）
评分对齐	"四、整体评分"评分维度必须严格对应"二、七大模块阶段评估"七大里程碑，权重见第九节

精简版强制规则（违反任何一条都视为报告不合格）

规则	具体要求
结构唯一性	报告只能有 4 大块（与完整版相同）
代码截取禁止	"三、七大模块深度评价"每个里程碑的"被评价 Agent 的设计思路"不需要截取代码，只需要一句话描述
类比强制	每个里程碑必须包含一个类比解释（来自第六节类比库或新增）——这是让不懂代码的用户理解的关键
差距等级强制	每个里程碑必须给出差距等级（红/黄/绿）——这是用户最关心的评估结论
建议时间划分强制	每个里程碑的建议必须分为"立即/短期/中期"——这是用户最关心的下一步
文档摘录强制	"一、项目整体概述"的"设计思路"必须从 md 文档中摘录原文，不能凭空总结
SOTA 验证强制	"三、七大模块深度评价"的 SOTA 对标必须经过当次 WebSearch 验证（不能完全依赖 reference/ 静态文件）
评分对齐	"四、整体评分"评分维度必须严格对应"二、七大模块阶段评估"七大里程碑，权重见第九节
核心目标	让用户读得懂，不需要强制页数限制

语言要求（完整版和精简版通用）

使用用户语言（中文/英文）
技术概念必须用类比解释
完整版：代码引用必须使用 CODE REFERENCE 格式（含文件路径和行号）
精简版：不需要代码引用，但必须用类比解释技术概念
SOTA 对标必须包含选择逻辑和设计原理