verify-patterns

Agent 模式验证

目的

检查 AI Agent 代码中常见的反模式，这些问题可能导致无限循环、重试失控、工具不匹配以及上下文溢出。所有分析均在本地进行。

使用时机

当用户要求以下操作时，触发此技能：

• “验证 Agent 模式”
• “检查 Agent 循环”
• “验证工具”
• “检查重试限制”
• “验证 Agent 安全性”

注意： 如需进行包含安全性、质量和特定语言检查的完整验证，请告知用户说 “验证 Agent”。

流程

步骤 1：检测 Agent 框架

检查 Python/TypeScript 文件中的导入语句，确定 Agent 框架：

导入模式	框架
from langgraph 或 import langgraph	LangGraph
from crewai 或 import crewai	CrewAI
from autogen 或 import autogen	AutoGen
from langchain 或 import langchain	LangChain
仅使用直接导入的 openai/anthropic SDK	自定义

同时检查框架配置文件：langgraph.json、crew.yaml。

步骤 2：定位 Agent 文件

查找要分析的文件：

优先检查的文件：

• graph.py、graph.ts - Agent 工作流定义
• tools.py、tools.ts、tools/*.py、tools/*.ts - 工具实现
• state.py、state.ts - 状态架构
• prompts.py、prompts/*.md、system.md - 提示词模板
• agent.py、agent.ts - Agent 核心逻辑

要检查的目录：

• src/agent/、agent/、src/、项目根目录
• lib/、app/、packages/

从分析中排除：

• skills/ 目录 — 这些是技能定义，不是 Agent 系统提示词

步骤 3：运行模式检查

检查级别

• [PATTERN] — 机械检查。严格按说明执行。
• [HEURISTIC] — 需要判断。清晰标注检查结果。

为每条检查结果标注 [P]（模式）或 [H]（启发式）。

---

3.1 [PATTERN] 循环安全性

机械执行检查。如果某个循环“看起来可能会终止”，也不得判定为通过。

要查找的模式	通过条件	严重程度
Python 中的 while True:	同一代码块作用域内存在 break 语句	缺失时为 ⚠️ 警告
Go 中的 for { }	代码块内存在 break 或 return	缺失时为 ⚠️ 警告
TS/JS 中的 while (true)	代码块内存在 break 或 return	缺失时为 ⚠️ 警告
函数递归调用自身	存在非递归返回路径（基本情况），或存在深度/计数器参数	缺失时为 ⚠️ 警告

[HEURISTIC] 回退检查：未识别的循环模式

应用模式表后，还需扫描以下情况：

• 终止完全取决于外部/运行时状态且没有超时机制的循环
• 无限执行 yield、且没有记录退出条件的生成器函数
• 没有超时参数的事件/轮询循环
• 跨多个函数的递归调用链没有深度跟踪

标记为 ⚠️ 警告：“可能存在不符合已知模式的无界循环 — 请手动验证终止条件”

---

3.2 [PATTERN] 重试次数上限检查

机械式应用。如果缺少必需参数，则标记为 ❌ Issue。

Python — 基于装饰器：

库/模式	必需参数	失败条件
@retry (tenacity)	stop=stop_after_attempt(n) 或 stop=stop_after_delay(n)	缺少 stop=
@backoff.on_exception	max_tries=n	缺少 max_tries=

Python — HTTP 客户端重试：

库/模式	必需参数	失败条件
urllib3.Retry(...)	total=n，其中 n > 0	缺少 total= 或 total=0
HTTPAdapter(max_retries=Retry(...))	Retry 对象必须具有 total=n	缺少 total=
httpx.HTTPTransport(retries=n)	retries=n，其中 n > 0	缺少 retries= 或 retries=0

Python — AWS SDK (boto3)：

库/模式	必需参数	失败条件
Config(retries={...})	max_attempts > 1	缺少 max_attempts 或 ≤ 1

注意：未显式配置重试时，boto3 使用 SDK 默认值（尝试 3 次）——不标记缺失项。

JavaScript/TypeScript：

库/模式	必需参数	失败条件
retry(...) (async-retry)	选项中的 retries: n	缺少 retries:
pRetry(...) (p-retry)	选项中的 retries: n	缺少 retries:

自定义重试循环（所有语言）：

要查找的模式	通过条件	失败条件
循环 + try/except + continue	整数计数器带上限检查	没有计数器 → ❌ Issue

[HEURISTIC] 回退：无法识别的重试模式

应用模式表后，扫描以下内容：

• 名称中包含 "retry"、但不在上述表格中的函数/装饰器
• 包名中包含 "retry" 的导入模块（例如 stamina、aiohttp_retry）
• 包含 sleep + 异常处理 + 重新调用，且没有可见计数器的循环
• max_retries、retry_count、attempts 等配置键

标记为 ⚠️ Warning："可能存在与已知库不匹配的重试模式 — 请手动验证重试上限"

---

3.3 [PATTERN] 工具注册表一致性

步骤 1：收集已定义的工具

扫描工具定义文件。任何模式匹配到的名称都视为已注册。

Python — 装饰器模式：

模式	名称提取方式
@tool（LangChain）用于 def	装饰器下方的函数名
@function_tool（OpenAI Agents SDK）用于 def	装饰器下方的函数名
@tool(name="...")	使用 name= 参数值

Python — 字典/列表模式：

模式	名称提取方式
{"type": "function", "function": {"name": "..."}}（OpenAI）	"function" 中 "name" 的值
{"name": "...", "input_schema": {...}}（Anthropic）	顶层的 "name"
{"name": "...", "description": "...", "parameters": {...}}	顶层的 "name"
ToolNode([func1, func2, ...])（LangGraph）	列表中的每个函数名
tools = [func1, func2] / TOOLS = [...]	列表中的每个标识符

TypeScript/JavaScript：

模式	名称提取方式
{ type: "function", function: { name: "..." } }（OpenAI）	function: 中的 name:
tool({ description: "...", parameters: z.object({...}) })	const 变量名
new DynamicTool({ name: "...", ... })（LangChain.js）	name: 的值
zodFunction({ name: "...", ... })	name: 的值

步骤 2：从提示词中收集工具引用

扫描 .md、.txt、prompts.py，查找以反引号括起、表示能力的标识符。

步骤 3：交叉引用

发现项	严重程度
引用未出现在定义列表中	❌ 问题（幻觉工具）
已定义工具未出现在任何提示词中	⚠️ 警告（未记录的工具）

[HEURISTIC] 从未绑定到大模型的工具

查找工具的定义位置和大模型的调用位置。如果存在工具，但从未将其连接到大模型调用，则标记为 ❌ 问题："已定义工具，但从未连接到大模型调用"

[HEURISTIC] 回退：未识别的工具定义

扫描类似工具的结构：

• 同时包含 "description" 和 "parameters" 键的字典
• 带有结构化文档字符串（名称、参数、返回值）的函数
• 名为 tools、tool_list、available_tools、functions 的变量
• 包含 run()、execute() 或 __call__() 方法的类

将其计入数量，并注明："通过启发式检测到工具 — 请确认这是预期的 Agent 工具。"

---

3.4 [PATTERN] 上下文大小感知

公式：token_estimate = len(file_content_chars) / 4

内容	⚠️ 警告阈值	❌ 问题阈值
系统提示词文件	> 4,000 tokens	> 8,000 tokens
单个工具描述	> 500 tokens	> 1,000 tokens
所有工具描述合计	> 2,000 tokens	> 4,000 tokens

排除： skills/ 目录（按需加载，不会嵌入）

[HEURISTIC] 回退：临界值和非标准情况

• 估算值在阈值的 20% 范围内 → 标记并建议使用分词器
• 动态提示词（f-string、.format()）→ 如果模板本身较大，则标记
• 多个拼接的提示词 → 估算合并后的大小
• 包含 include 的提示词 → 注明实际大小可能更大

---

3.5 [HEURISTIC] 显式工具列表

检查系统提示词中是否包含：

• 类似“可用工具”“你可以使用”的标题
• 工具能力描述

如果工具已定义，但未在系统提示词中说明，则进行标记。

---

3.6 [PATTERN] LangGraph 图循环分析

（仅在检测到 LangGraph 时）

检测步骤：

a. 查找图文件（graph.py、graph.ts，或包含 StateGraph/MessageGraph 的文件）

b. 构建边映射：

• workflow.add_edge(source, dest) — 无条件边
• workflow.add_conditional_edges(source, fn, mapping) — 从映射中提取目标节点

c. 识别循环：可从自身到达的节点

d. 对于每个循环，检查是否可通过条件边到达 END（或 "__end__"）

条件	严重性
存在循环，且可到达 END	✅ 通过
存在循环，但没有到达 END 的路径	❌ 问题
图中没有 END 节点	❌ 问题
节点没有出边，且不是 END	⚠️ 警告（死胡同）

示例 — 无限循环（❌ 问题）：

workflow.add_edge("agent", "tools")
workflow.add_edge("tools", "agent")  # no path to END

示例 — 带有出口的循环（✅ 通过）：

workflow.add_conditional_edges("agent", should_continue, {
    "continue": "tools",
    "end": END
})
workflow.add_edge("tools", "agent")

[HEURISTIC] 回退方案：非 LangGraph 图

扫描类似图的控制流：

• 带有转换表的状态机
• 带有隐式循环的自定义路由
• LangGraph.js（驼峰命名方法）
• CrewAI/AutoGen Agent 交接
• 没有终止路径的邻接表

标记为 ⚠️ 警告：“可能存在循环控制流 — 请确认终止条件存在”

---

第 4 步：生成报告

# Agent Pattern Verification Report

**Project:** [name or path]
**Date:** [current date]
**Framework detected:** [LangGraph | CrewAI | AutoGen | LangChain | Custom | None]
**Files analyzed:** [count]

## Summary

✅ X checks passed | ⚠️ Y warnings | ❌ Z issues

## Loop Safety

- [x] All loops have termination conditions
- [ ] ⚠️ Potential unbounded loop at `[file:line]`

## Retry Limits

- [x] All retry mechanisms have explicit limits
- [ ] ❌ Missing retry limit at `[file:line]`

## Tool Consistency

- [x] Tool registry found: X tools defined
- [ ] ❌ Y hallucinated tool references
- [ ] ⚠️ Z undocumented tools

## Context Size

- [x] System prompt within limits (~X tokens)
- [ ] ⚠️ System prompt exceeds recommended size

## Findings

> `[P]` = pattern-matched · `[H]` = heuristic

### ✅ Passing
- `[P]` [Check]: [confirmation]

### ⚠️ Warnings
- `[P|H]` [Check]: [description]
  - **Location:** [file:line]
  - **Suggestion:** [how to fix]

### ❌ Issues
- `[P|H]` [Check]: [description]
  - **Location:** [file:line]
  - **Rule:** [which rule violated]
  - **Fix:** [specific remediation]

## Recommendations

1. [Priority recommendation]
2. [Additional improvements]

---

如需进行包括安全性、质量和特定语言检查在内的完整验证，请说“verify agent”。