Dual Cycle Reasoner

MCP 双循环推理器

一个为自主 Agent 实现双循环元认知推理框架的模型上下文协议（MCP）服务。该工具通过智能循环检测和经验获取，赋予 Agent 更强的自我意识和可靠性。

描述

MCP Dual-Cycle Reasoner 是一款复杂的工具，旨在增强 AI Agent 的自主性和可靠性。通过实现双循环元认知框架，它使 Agent 能够监控自身的认知过程，检测是否陷入重复循环，并从过往经验中学习，以做出更好的决策。

该框架由两个主要组件构成：

• Sentinel：监控 Agent 的操作并检测异常，例如操作重复、状态不变和进展停滞。
• Adjudicator：管理过往经验案例库，使 Agent 能够存储和检索曾经遇到的问题的解决方案。

该服务使用 TypeScript 构建，并利用高性能库进行统计分析、自然语言处理和语义相似度计算，从而实现基于熵的高级异常检测、基于 NLI 的文本分析和智能案例管理等功能。

主要功能

• 📊 高级统计分析：基于熵的异常检测和时间序列分析。
• 🧠 增强的基于案例推理：结合基于 NLI 的文本分析进行语义相似度匹配。
• 🎯 多策略检测：统计、基于模式和混合循环检测。
• 📈 时间序列分析：趋势检测和周期性模式识别。
• 🔧 可配置检测：领域专用阈值和进度指标。
• 🎨 智能案例管理：质量评分、去重和基于使用情况的优化。
• 🚀 高性能库：使用 simple-statistics、natural、compromise 和 HuggingFace Transformers 构建。

技术栈

• 语言：TypeScript
• 框架：Node.js
• 服务：使用 SSE 传输的 FastMCP
• NLP 和机器学习：
  • @huggingface/transformers：用于基于 NLI 的语义分析
  • natural：用于情感分析和分词
  • compromise：用于自然语言处理
• 统计：
  • simple-statistics：用于统计计算
  • ml-matrix：用于矩阵运算
• 开发工具：
  • jest：用于测试
  • eslint：用于代码检查
  • prettier：用于代码格式化
  • zod：用于模式验证

安装

要在本地运行项目，请按以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/cyqlelabs/mcp-dual-cycle-reasoner.git
   cd mcp-dual-cycle-reasoner
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

使用方法

运行服务

你可以通过两种模式运行服务：

1. HTTP 流（默认）：

   npm start
   

   服务将在端口 8080 上启动。

2. Stdio：

   npm start -- --stdio
   

与 Claude Desktop 配合使用

将以下内容添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "dual-cycle-reasoner": {
      "command": "npx",
      "args": ["@cyqlelabs/mcp-dual-cycle-reasoner"]
    }
  }
}

对于 stdio 传输，请将 --stdio 标志添加到 args 数组中。

可用工具

核心监控工具

start_monitoring

初始化对 Agent 认知过程的元认知监控。

输入架构：

{
  goal: string; // Current goal being pursued
  initial_beliefs?: string[]; // Initial beliefs about the task
}

process_trace_update

主要监控函数——处理 Agent 的认知轨迹更新。

输入架构：

{
  last_action: string; // Latest action name
  current_context?: string; // Current environment context
  goal: string; // Current goal being pursued
  window_size?: number; // Monitoring window size (default: 10)
}

返回载荷：

返回一个 JSON 对象，指示是否需要干预，以及检测到的循环的详细信息。

{
  "intervention_required": true,
  "loop_detected": {
    "detected": true,
    "type": "action_repetition",
    "confidence": 0.85,
    "details": "Loop detected via parameter_repetition: 57% anomaly score...",
    "actions_involved": ["click_submit_button"]
  }
}

stop_monitoring

停止元认知监控并获取会话摘要。

输入架构：{}

循环检测工具

detect_loop

使用各种策略检测 Agent 是否陷入循环。

输入架构：

{
  current_context?: string; // Current environment context
  goal: string; // Current goal being pursued
  detection_method?: "statistical" | "pattern" | "hybrid"; // Detection method (default: "hybrid")
}

返回载荷：

以 JSON 字符串形式返回一个 LoopDetectionResult 对象。

{
  "detected": true,
  "type": "action_repetition",
  "confidence": 0.85,
  "details": {
    "dominant_method": "parameter_repetition",
    "anomaly_score": 0.57,
    "actions_involved_count": 1,
    "recent_actions_count": 10,
    "metrics": {
      "semantic_repetition": 0.6,
      "parameter_repetition": 0.8
    }
  },
  "actions_involved": ["click_submit_button"]
}

configure_detection

配置循环检测参数和特定领域的进展指标。

输入架构：

{
  progress_indicators?: string[]; // default: []
  min_actions_for_detection?: number; // default: 5
  alternating_threshold?: number; // default: 0.5
  repetition_threshold?: number; // default: 0.4
  progress_threshold_adjustment?: number; // default: 0.2
  semantic_intents?: string[]; // default: []
}

增强体验管理

store_experience

存储案例，以供将来进行基于案例的推理，并添加增强元数据和质量评分。

输入架构：

{
  problem_description: string;
  solution: string;
  outcome: boolean;
  context?: string;
  difficulty_level?: "low" | "medium" | "high";
}

retrieve_similar_cases

使用高级语义匹配和筛选来检索相似案例。

输入架构：

{
  problem_description: string;
  max_results?: number; // default: 5
  context_filter?: string;
  difficulty_filter?: "low" | "medium" | "high";
  outcome_filter?: boolean;
  min_similarity?: number; // default: 0.6
}

返回载荷：

以 JSON 字符串形式返回一个 Case 对象数组。

[
  {
    "id": "case-123",
    "problem_description": "Form submission button not responding to clicks",
    "solution": "Ensure all required fields are filled correctly.",
    "outcome": true,
    "context": "registration_form",
    "difficulty_level": "medium",
    "similarity_metrics": {
      "combined_similarity": 0.92
    }
  }
]

系统工具

get_monitoring_status

获取当前监控状态和统计信息。

输入架构：{}

返回载荷：

返回一个 JSON 字符串，其中包含当前监控状态，包括 is_monitoring、current_goal、trace_length 和 intervention_count。

{
  "is_monitoring": true,
  "current_goal": "Complete user registration process on website",
  "trace_length": 15,
  "intervention_count": 2,
  "recent_actions": [
    { "type": "click_submit_button", "timestamp": 1678886400000 },
    { "type": "click_submit_button", "timestamp": 1678886401000 }
  ]
}

reset_engine

重置双循环引擎状态。

输入架构：{}

使用场景示例

以下完整示例展示了如何使用双循环推理器监控自主 Agent，并随着时间推移积累经验：

1. 初始设置与配置

// Configure detection parameters for your domain
await configure_detection({
  progress_indicators: ['page_loaded', 'form_submitted', 'data_extracted'],
  min_actions_for_detection: 3,
  alternating_threshold: 0.6,
  repetition_threshold: 0.3,
  semantic_intents: [
    'navigating to page',
    'clicking element',
    'filling form field',
    'submitting form',
    'validating input',
    'handling popup',
    'extracting data',
    'waiting for response',
  ],
});

// Start monitoring the agent's goal
await start_monitoring({
  goal: 'Complete user registration process on website',
});

2. 监控 Agent 操作

// Monitor each action the agent takes
await process_trace_update({
  last_action: 'click_signup_button',
  current_context: 'homepage',
  goal: 'Complete user registration process on website',
});

// ... agent continues actions ...

// Agent gets stuck clicking submit repeatedly
await process_trace_update({
  last_action: 'click_submit_button',
  current_context: 'registration_form',
  goal: 'Complete user registration process on website',
});
// Returns: {
//   "intervention_required": true,
//   "loop_detected": {
//     "detected": true,
//     "type": "action_repetition",
//     "confidence": 0.85,
//     "details": {
//       "dominant_method": "parameter_repetition",
//       "anomaly_score": 0.57,
//       "actions_involved_count": 1,
//       "recent_actions_count": 10,
//       "metrics": {
//         "semantic_repetition": 0.6,
//         "parameter_repetition": 0.8
//       }
//     },
//     "actions_involved": ["click_submit_button"]
//   }
// }

3. 存储和检索经验

// Store a successful experience
await store_experience({
  problem_description: 'Email validation error blocking form submission',
  solution: 'Check email format and retry with valid email address',
  outcome: true,
  context: 'registration_form',
  difficulty_level: 'medium',
});

// When a loop is detected, retrieve similar cases for recovery
const similarCases = await retrieve_similar_cases({
  problem_description: 'Form submission button not responding to clicks',
  max_results: 3,
  context_filter: 'registration_form',
  outcome_filter: true,
});

了解循环检测

当 process_trace_update 工具检测到潜在循环时，会返回一个详细的 loop_detected 对象。了解此对象的组成部分有助于诊断和调试 Agent 行为。

以下是 details 对象中关键指标的简要说明：

• dominant_method：触发循环检测的主要方法（例如，semantic_repetition、state_invariance）。
• anomaly_score：综合评分（0-1），表示 Agent 最近的操作属于循环的置信度。它是多种检测方法的加权平均值。
• actions_involved_count：被识别为属于检测到的循环的近期操作数量。
• recent_actions_count：分析的近期操作总数。
• metrics：包含不同检测方法原始评分的对象，例如：
  • semantic_repetition：近期操作在语义上彼此相似的百分比。
  • parameter_repetition：语义相似操作的参数之间的相似度百分比。
  • exact_repetition：近期操作中逐字符完全重复的百分比。
  • cyclical_pattern：表示重复操作序列是否存在的评分（0-1）。
  • oscillation_pattern：表示振荡（来回切换）操作是否存在的评分（0-1）。
  • alternating_pattern：表示交替操作模式是否存在的评分（0-1）。

参与贡献

欢迎贡献！请阅读贡献指南，并确保所有测试均通过后再提交拉取请求。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。