MonkeyCode AI对话引擎深度解析：从自然语言到可执行代码的智能桥梁
引言
"编程的本质是沟通——人与机器之间的沟通。MonkeyCode 的使命是让这种沟通变得像人与人交谈一样自然。"
在 AI 编程助手领域，代码补全只是冰山一角。真正的革命在于对话式编程——开发者用自然语言描述需求，AI 理解意图并生成精确的代码实现。这不仅是效率的提升，更是编程范式的根本性转变。
MonkeyCode 作为完全开源（Apache License 2.0）的 AI 编程助手，其核心差异化能力正是强大的 AI 对话引擎。本文将深入剖析 MonkeyCode 对话引擎的架构设计、多轮对话管理、上下文理解、以及如何实现从模糊需求到精确代码的智能转换。
🎯 核心信息
- GitHub 仓库: https://github.com/monkeycode-ai/monkeycode
- 开源协议: Apache License 2.0
- 对话引擎版本: v3.2 (持续迭代中)
- 支持模型: OpenAI / Anthropic / Ollama 本地模型 / 自定义 API
- 欢迎贡献对话能力改进！
一、对话引擎架构总览
1.1 分层架构设计
┌─────────────────────────────────────────────────────────────┐
│ MonkeyCode AI 对话引擎架构 │
│ │
│ ══════════════════════════════════════════════════════ │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ 用户交互层 (User Interface Layer) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ VS Code │ │ JetBrains│ │ Web IDE │ ... │ │
│ │ │ 扩展 │ │ 插件 │ │ 集成 │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ └───────┼──────────┼──────────┼────────────────────┘ │
│ │ │ │ │
│ ┌───────▼──────────▼──────────▼────────────────────┐ │
│ │ 会话管理层 (Session Manager) │ │
│ │ │ │
│ │ • 多轮对话状态维护 │ │
│ │ • 上下文窗口管理 (Context Window Management) │ │
│ │ • 会话历史压缩与摘要 │ │
│ │ • 意图识别与路由 │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────┐ │
│ │ NLU 层 (Natural Language Understanding) │ │
│ │ │ │
│ │ • 意图分类器 (Intent Classifier) │ │
│ │ • 实体提取器 (Entity Extractor) │ │
│ │ • 代码上下文分析器 (Code Context Analyzer) │ │
│ │ • 歧义消解模块 (Ambiguity Resolver) │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────┐ │
│ │ 推理与生成层 (Inference & Generation) │ │
│ │ │ │
│ │ • Prompt 模板引擎 │ │
│ │ • Few-shot 示例检索 │ │
│ │ • RAG (检索增强生成) │ │
│ │ • 代码生成后处理 (Post-processing) │ │
│ │ • 安全过滤 (Safety Filter) │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼───────────────────────────┐ │
│ │ LLM 抽象层 (LLM Abstraction Layer) │ │
│ │ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │GPT-4o│ │Claude│ │Ollama│ │Custom│ │ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│ │
╚═══════════════════════════════════════════════════════════╝
1.2 核心组件职责
| 组件 | 职责 | 关键技术 |
|---|---|---|
| 会话管理器 | 维护多轮对话状态、管理上下文窗口 | State Machine, Sliding Window, Summarization |
| NLU 引擎 | 理解用户意图、提取关键实体 | Fine-tuned Classifier, Rule-based + ML Hybrid |
| Prompt 引擎 | 构建最优提示词模板 | Template Engine, Chain-of-Thought, Few-shot |
| RAG 系统 | 检索相关代码库/文档作为上下文 | Vector DB, Embedding, Hybrid Search |
| LLM 适配器 | 统一接口对接多种大模型 | Adapter Pattern, Streaming, Fallback |
| 安全层 | 过滤有害输出、保护敏感信息 | Content Filter, PII Detection, Output Sanitizer |
二、NLU 自然语言理解引擎
2.1 意图分类体系
// ===== packages/core/src/nlu/intent-classifier.ts =====
/**
* MonkeyCode 意图分类系统
*
* 将用户的自然语言输入分类为预定义的意图类别，
* 以便后续选择最合适的处理策略。
*/
import { z } from 'zod';
// === 意图类型定义 ===
export enum IntentType {
// === 代码生成类 ===
CODE_GENERATION = 'code_generation', // "写一个快速排序"
FUNCTION_IMPLEMENTATION = 'function_impl', // "实现一个用户登录函数"
CLASS_CREATION = 'class_creation', // "创建一个 User 类"
API_INTEGRATION = 'api_integration', // "调用 GitHub API 获取用户信息"
// === 代码解释类 ===
CODE_EXPLANATION = 'code_explanation', // "这段代码在做什么？"
CONCEPT_EXPLANATION = 'concept_explanation', // "什么是闭包？"
// === 代码修改类 ===
BUG_FIX = 'bug_fix', // "修复这个空指针异常"
REFACTORING = 'refactoring', // "重构为函数式风格"
OPTIMIZATION = 'optimization', // "优化这段查询的性能"
// === 代码审查类 ===
CODE_REVIEW = 'code_review', // "审查这个 PR 的改动"
SECURITY_AUDIT = 'security_audit', // "检查是否有 SQL 注入风险"
BEST_PRACTICE = 'best_practice', // "这里有没有更好的写法？"
// === 测试类 ===
TEST_GENERATION = 'test_generation', // "为这个函数写单元测试"
TEST_DEBUG = 'test_debug', // "为什么这个测试失败了？"
// === 项目操作类 ===
PROJECT_SETUP = 'project_setup', // "初始化一个新的 React 项目"
DEPLOYMENT = 'deployment', // "帮我配置 Docker 部署"
CONFIGURATION = 'configuration', // "配置 ESLint 规则"
// === 信息查询类 ===
DOCUMENTATION = 'documentation', // "查找 Array.prototype.map 的文档"
ERROR_RESOLUTION = 'error_resolution', // "TypeError: Cannot read property 'x'"
VERSION_COMPATIBILITY = 'version_compat', // "React 18 和 17 有什么区别？"
// === 对话控制类 ===
CLARIFICATION = 'clarification', // "你是指 X 还是 Y？"
FOLLOW_UP = 'follow_up', // "在此基础上，再加..."
CANCEL = 'cancel', // "算了，不用了"
FEEDBACK = 'feedback', // "这个建议很好/不好"
}
// === 意图置信度 Schema ===
const IntentResultSchema = z.object({
intent: z.nativeEnum(IntentType),
confidence: z.number().min(0).max(1), // 置信度 0-1
// 备选意图（当主意图置信度较低时）
alternatives: z.array(z.object({
intent: z.nativeEnum(IntentType),
confidence: z.number().min(0).max(1),
})).optional(),
// 意图相关的元数据
metadata: z.object({
language: z.string().optional(), // 推测的目标语言
framework: z.string().optional(), // 推测的框架
complexity: z.enum(['simple', 'medium', 'complex']).optional(),
estimatedTokens: z.number().optional(), // 预估需要的 token 数
}).optional(),
});
export type IntentResult = z.infer<typeof IntentResultSchema>;
// === 意图分类器实现 ===
export class IntentClassifier {
private rules: Map<IntentType, IntentRule[]>;
private mlModel?: MLClassifier;
constructor(config: ClassifierConfig) {
this.rules = this.buildRules();
if (config.mlModelPath) {
this.mlModel = new MLClassifier(config.mlModelPath);
}
}
/**
* 分类用户输入的意图
*/
async classify(input: string, context?: ConversationContext): Promise<IntentResult> {
// 1. 基于规则的快速匹配
const ruleResults = this.matchRules(input);
// 2. 基于模型的精细分类
let mlResult: MLClassificationResult | undefined;
if (this.mlModel) {
mlResult = await this.mlModel.classify(input);
}
// 3. 融合规则和模型结果
const fused = this.fuseResults(ruleResults, mlResult, context);
// 4. 后处理：应用业务逻辑调整
return this.postProcess(fused, input, context);
}
/**
* 构建基于规则的匹配模式
*/
private buildRules(): Map<IntentType, IntentRule[]> {
const rules = new Map<IntentType, IntentRule[]>();
// 代码生成模式
rules.set(IntentType.CODE_GENERATION, [
{ pattern: /^(写|创建|生成|实现|给我写)\s*(一个?|一段?)?(.+)$/i, weight: 0.9 },
{ pattern: /^(can you|could you|please|help me)\s*(write|create|generate|implement)/i, weight: 0.85 },
{ pattern: /(写个|搞个|弄个)(函数|方法|类|组件|接口)/i, weight: 0.88 },
]);
// Bug 修复模式
rules.set(IntentType.BUG_FIX, [
{ pattern: /^(修复|解决|fix|resolve)\s*(这个?|那个?|以下)?(.+)?(错误|问题|bug|issue)/i, weight: 0.92 },
{ pattern: /(报错|出错|失败|不工作|doesn't work|error|fail)/i, weight: 0.8 },
{ pattern: /(NullPointerException|TypeError|ReferenceError|undefined is not)/i, weight: 0.95 },
]);
// 代码解释模式
rules.set(IntentType.CODE_EXPLANATION, [
{ pattern: /^(解释|说明|explain|what does|what's|why|怎么)/i, weight: 0.85 },
{ pattern: /(什么意思|做什么用的|干啥的|这段代码)/i, weight: 0.87 },
{ pattern: /^(tell me about|describe|walk me through)/i, weight: 0.82 },
]);
// 重构模式
rules.set(IntentType.REFACTORING, [
{ pattern: /^(重构|refactor|改写|优化.*结构|简化)/i, weight: 0.9 },
{ pattern: /(更简洁|更优雅|更好|cleaner|better|simpler)/i, weight: 0.75 },
{ pattern: /(改成|转换为|convert to|transform into)/i, weight: 0.8 },
]);
// 测试生成模式
rules.set(IntentType.TEST_GENERATION, [
{ pattern: /^(写|生成|创建|add|write).*测试(test|spec|unit)/i, weight: 0.93 },
{ pattern: /(测试|test|spec|jest|mocha|pytest)/i, weight: 0.78 },
{ pattern: /(覆盖|coverage|断言|assert|expect)/i, weight: 0.8 },
]);
// 安全审计模式
rules.set(IntentType.SECURITY_AUDIT, [
{ pattern: /(安全|漏洞|注入|攻击|vulnerability|injection|attack|xss|csrf|sql)/i, weight: 0.91 },
{ pattern: /(检查|check|audit|scan|review).*安全(security)/i, weight: 0.89 },
]);
return rules;
}
/**
* 融合规则和模型结果
*/
private fuseResults(
ruleResults: RuleMatch[],
mlResult: MLClassificationResult | undefined,
context?: ConversationContext,
): IntentResult {
// 实现加权融合算法...
// 结合规则匹配的高精度和模型泛化能力
}
}
2.2 实体提取与代码上下文分析
// ===== packages/core/src/nlu/entity-extractor.ts =====
/**
* 实体提取器 — 从自然语言中提取结构化信息
*/
export enum EntityType {
PROGRAMMING_LANGUAGE = 'language', // "Python", "TypeScript"
FRAMEWORK = 'framework', // "React", "Vue", "Django"
LIBRARY = 'library', // "lodash", "axios", "express"
DATA_TYPE = 'data_type', // "string", "int", "User[]"
FUNCTION_NAME = 'function_name', // "fetchUser", "calculateTotal"
VARIABLE_NAME = 'variable_name', // "userList", "config"
FILE_PATH = 'file_path', // "/src/utils/helper.ts"
API_ENDPOINT = 'api_endpoint', // "GET /api/users/:id"
ERROR_TYPE = 'error_type', // "404 Not Found", "ECONNREFUSED"
DESIGN_PATTERN = 'design_pattern', // "单例模式", "观察者模式", "Factory"
ALGORITHM = 'algorithm', // "二分查找", "DFS", "quick sort"
DATABASE = 'database', // "PostgreSQL", "MongoDB", "Redis"
PLATFORM = 'platform', // "AWS", "Docker", "Kubernetes",
VERSION = 'version', // "v3.2", "React 18", "Node 20"
CONSTRAINT = 'constraint', // "O(n)", "线程安全", "幂等"
}
export interface ExtractedEntity {
type: EntityType;
value: string; // 提取的原始值
normalized?: string; // 标准化后的值
confidence: number; // 提取置信度
span: { start: number; end: number }; // 在原文中的位置
aliases?: string[]; // 可能的同义词
}
/**
* 代码上下文分析器
*
* 分析当前光标位置的代码环境，
* 为意图理解提供额外的结构化信息。
*/
export class CodeContextAnalyzer {
/**
* 分析当前代码上下文
*/
async analyze(context: CodeAnalysisRequest): Promise<CodeContext> {
const results: CodeContext = {
language: await this.detectLanguage(context),
currentScope: await this.analyzeScope(context),
imports: await this.extractImports(context.fileContent),
nearbySymbols: await this.getNearbySymbols(context.position, context.ast),
typeInformation: await this.inferTypes(context),
projectStructure: await this.analyzeProjectStructure(context.projectRoot),
gitContext: await this.analyzeGitContext(context.projectRoot),
};
return results;
}
/**
* 当前作用域分析
*
* 了解当前代码所在的函数/类/模块作用域，
* 这对生成正确的代码至关重要。
*/
private async analyzeScope(context: CodeAnalysisRequest): Promise<ScopeInfo> {
return {
type: this.determineScopeType(context), // function | class | module | global
name: this.getScopeName(context),
variables: this.getLocalVariables(context),
parameters: this.getParameters(context),
returnType: this.getInferredReturnType(context),
accessibleMembers: this.getAccessibleMembers(context),
parentScopes: this.getParentChain(context),
};
}
}
三、多轮对话管理与上下文窗口
3.1 会话状态机
// ===== packages/core/src/session/state-machine.ts =====
/**
* MonkeyCode 对话状态机
*
* 管理一次完整对话的生命周期和状态转换
*/
import { z } from 'zod';
export enum DialogState {
IDLE = 'idle', // 空闲，等待输入
PROCESSING = 'processing', // 正在处理用户输入
GENERATING = 'generating', // 正在生成代码/回复
AWAITING_CLARIFICATION = 'clarify', // 需要澄清歧义
AWAITING_CONFIRMATION = 'confirm', // 等待用户确认操作
EXECUTING = 'executing', // 正在执行操作（如文件写入）
REVIEWING = 'reviewing', // 代码审查阶段
COMPLETED = 'completed', // 当前任务完成
ERROR = 'error', // 出错状态
}
export enum DialogAction {
USER_INPUT = 'user_input',
SUBMIT_REQUEST = 'submit_request',
START_GENERATION = 'start_generation',
COMPLETE_GENERATION = 'complete_generation',
REQUEST_CLARIFICATION = 'request_clarification',
RECEIVE_CLARIFICATION = 'receive_clarification',
REQUEST_CONFIRMATION = 'request_confirmation',
CONFIRM_ACTION = 'confirm_action',
REJECT_ACTION = 'reject_action',
START_EXECUTION = 'start_execution',
COMPLETE_EXECUTION = 'complete_execution',
REQUEST_REVIEW = 'request_review',
PROVIDE_FEEDBACK = 'provide_feedback',
FOLLOW_UP = 'follow_up',
CANCEL = 'cancel',
ERROR_OCCURRED = 'error',
RESET = 'reset',
}
// 状态转换规则
const TRANSITIONS: Record<DialogState, Partial<Record<DialogAction, DialogState>>> = {
[DialogState.IDLE]: {
[DialogAction.USER_INPUT]: DialogState.PROCESSING,
},
[DialogState.PROCESSING]: {
[DialogAction.SUBMIT_REQUEST]: DialogState.GENERATING,
[DialogAction.REQUEST_CLARIFICATION]: DialogState.AWAITING_CLARIFICATION,
[DialogAction.ERROR_OCCURRED]: DialogState.ERROR,
},
[DialogState.GENERATING]: {
[DialogAction.COMPLETE_GENERATION]: DialogState.AWAITING_CONFIRMATION,
[DialogAction.REQUEST_REVIEW]: DialogState.REVIEWING,
[DialogAction.ERROR_OCCURRED]: DialogState.ERROR,
},
[DialogState.AWAITING_CLARIFICATION]: {
[DialogAction.RECEIVE_CLARIFICATION]: DialogState.PROCESSING,
[DialogAction.CANCEL]: DialogState.IDLE,
},
[DialogState.AWAITING_CONFIRMATION]: {
[DialogAction.CONFIRM_ACTION]: DialogState.EXECUTING,
[DialogAction.REJECT_ACTION]: DialogState.IDLE,
[DialogAction.REQUEST_REVIEW]: DialogState.REVIEWING,
},
[DialogState.EXECUTING]: {
[DialogAction.COMPLETE_EXECUTION]: DialogState.COMPLETED,
[DialogAction.ERROR_OCCURRED]: DialogState.ERROR,
},
[DialogState.REVIEWING]: {
[DialogAction.CONFIRM_ACTION]: DialogState.EXECUTING,
[DialogAction.REJECT_ACTION]: DialogState.IDLE,
[DialogAction.FOLLOW_UP]: DialogState.PROCESSING,
},
[DialogState.COMPLETED]: {
[DialogAction.FOLLOW_UP]: DialogState.PROCESSING,
[DialogAction.USER_INPUT]: DialogState.IDLE,
},
[DialogState.ERROR]: {
[DialogAction.USER_INPUT]: DialogState.PROCESSING,
[DialogAction.RESET]: DialogState.IDLE,
},
};
export class DialogStateMachine {
private currentState: DialogState = DialogState.IDLE;
private history: Array<{ from: DialogState; action: DialogAction; to: DialogState; timestamp: Date }> = [];
private listeners: Array<(state: DialogState, action: DialogAction) => void> = [];
get state(): DialogState {
return this.currentState;
}
/**
* 执行状态转换
*/
transition(action: DialogAction): boolean {
const allowedTransitions = TRANSITIONS[this.currentState];
const nextState = allowedTransitions?.[action];
if (!nextState) {
console.warn(`Invalid transition: ${this.currentState} --[${action}]--> ?`);
return false;
}
const prevState = this.currentState;
this.currentState = nextState;
this.history.push({ from: prevState, action, to: nextState, timestamp: new Date() });
// 通知监听者
this.listeners.forEach(listener => listener(nextState, action));
return true;
}
/**
* 订阅状态变化
*/
onStateChange(listener: (state: DialogState, action: DialogAction) => void): () => void {
this.listeners.push(listener);
return () => {
this.listeners = this.listeners.filter(l => l !== listener);
};
}
/**
* 获取完整的对话轨迹
*/
getTrace(): readonly typeof this.history {
return this.history;
}
}
3.2 上下文窗口智能管理
// ===== packages/core/src/session/context-manager.ts =====
/**
* 上下文窗口管理器
*
* 解决 LLM 上下文长度限制的关键组件：
* - 智能裁剪策略
* - 对话摘要压缩
* - 关键信息保留
* - 动态优先级排序
*/
import { z } from 'zod';
export interface ContextWindowConfig {
maxTokens: number; // 最大 token 数 (如 128000 for GPT-4o)
reservedTokens: number; // 预留给输出的 token 数
systemPromptTokens: number; // System prompt 占用的 token 数
compression: {
enabled: boolean;
threshold: number; // 触发压缩的阈值 (如 80%)
strategy: 'summarize' | 'truncate' | 'hybrid';
summaryModel: string; // 用于摘要的轻量模型
};
retention: {
keepFirstMessage: boolean; // 保留第一条消息（通常包含关键需求）
keepLastError: boolean; // 保留最近的错误信息
keepCodeBlocks: boolean; // 优先保留代码块
maxHistoryTurns: number; // 最大保留轮次
};
}
export interface MessagePriority {
messageIndex: number;
priority: number; // 0-100, 越高越重要
reason: string; // 优先级原因
tokens: number;
}
export class ContextManager {
private config: ContextWindowConfig;
private messages: ChatMessage[] = [];
private summaries: SummaryChunk[] = [];
constructor(config: ContextWindowConfig) {
this.config = config;
}
/**
* 添加消息到上下文
*/
addMessage(message: ChatMessage): void {
this.messages.push(message);
// 检查是否需要压缩
const totalTokens = this.calculateTotalTokens();
const threshold = this.config.maxTokens * (this.config.compression.threshold / 100);
if (totalTokens > threshold) {
this.compress();
}
}
/**
* 获取用于 LLM 调用的最终上下文
*/
buildLLMContext(systemPrompt: string): ChatMessage[] {
const availableTokens = this.config.maxTokens
- this.countTokens(systemPrompt)
- this.config.reservedTokens;
const result: ChatMessage[] = [
{ role: 'system', content: systemPrompt },
...this.summaries.map(s => ({
role: 'system' as const,
content: `[之前对话摘要]\n${s.content}`,
})),
];
// 按优先级选择消息
const prioritized = this.prioritizeMessages(availableTokens);
result.push(...prioritized);
return result;
}
/**
* 消息优先级排序
*
* 核心算法：根据多条规则计算每条消息的重要性
*/
private prioritizeMessages(budgetTokens: number): ChatMessage[] {
const priorities: MessagePriority[] = this.messages.map((msg, index) => {
let priority = 50; // 基础分
// 规则1: 第一条用户消息（包含原始需求）+30
if (index === 0 && msg.role === 'user') {
priority += 30;
return { messageIndex: index, priority, reason: '原始需求', tokens: this.countTokens(msg.content) };
}
// 规则2: 包含代码块的消息 +25
if (/```[\s\S]*?```/.test(msg.content)) {
priority += 25;
}
// 规则3: 最近的消息 +20 (线性衰减)
const recencyBonus = Math.floor((index / this.messages.length) * 20);
priority += recencyBonus;
// 规则4: 错误/修复相关 +15
if (/(error|错误|修复|fix|bug|exception)/i.test(msg.content)) {
priority += 15;
}
// 规则5: 用户确认/反馈 +10
if (msg.role === 'user' && /(好的|可以|ok|yes|确认|apply|用这个)/i.test(msg.content)) {
priority += 10;
}
// 规则6: AI 生成的长代码块 +15
const codeBlockCount = (msg.content.match(/```/g) || []).length / 2;
if (msg.role === 'assistant' && codeBlockCount > 0) {
priority += Math.min(codeBlockCount * 5, 15);
}
// 规则7: 包含具体技术细节 +10
if (/(function|class|interface|type|def |const |let |var )/i.test(msg.content)) {
priority += 10;
}
return {
messageIndex: index,
priority,
reason: this.getPriorityReason(priority),
tokens: this.countTokens(msg.content),
};
});
// 按优先级降序排列，然后在预算内选择
priorities.sort((a, b) => b.priority - a.priority);
const selected: ChatMessage[] = [];
let usedTokens = 0;
for (const p of priorities) {
if (usedTokens + p.tokens <= budgetTokens) {
selected.push(this.messages[p.messageIndex]);
usedTokens += p.tokens;
}
}
// 恢复原始顺序
selected.sort((a, b) =>
this.messages.indexOf(a) - this.messages.indexOf(b)
);
return selected;
}
/**
* 对话压缩（混合策略）
*/
private compress(): void {
switch (this.config.compression.strategy) {
case 'summarize':
this.summarizeCompression();
break;
case 'truncate':
this.truncateCompression();
break;
case 'hybrid':
this.hybridCompression();
break;
}
}
/**
* 混合压缩策略：
* 1. 早期对话 → 摘要压缩
* 2. 中期对话 → 选择性保留
* 3. 近期对话 → 完整保留
*/
private async hybridCompression(): Promise<void> {
const totalMessages = this.messages.length;
const recentThreshold = Math.floor(totalMessages * 0.4); // 最近 40% 完整保留
// 早期消息进行摘要
const earlyMessages = this.messages.slice(0, totalMessages - recentThreshold);
if (earlyMessages.length > 0) {
const summary = await this.generateSummary(earlyMessages);
this.summaries.push({
turnRange: [0, earlyMessages.length - 1],
content: summary,
compressedAt: new Date(),
});
// 移除已摘要的消息
this.messages = this.messages.slice(totalMessages - recentThreshold);
}
}
}
四、Prompt 工程与Few-Shot学习
4.1 Prompt 模板引擎
// ===== packages/core/src/prompt/template-engine.ts =====
/**
* MonkeyCode Prompt 模板引擎
*
* 支持动态构建、变量插值、条件渲染、链式提示
*/
import { z } from 'zod';
// === 模板变量类型 ===
export interface PromptVariables {
// 用户输入
userQuery: string;
userLanguage?: string; // 用户使用的语言
// 代码上下文
targetLanguage: string; // 目标编程语言
codeContext?: string; // 光标附近的代码
filePath?: string; // 当前文件路径
projectName?: string; // 项目名称
// 对话历史
conversationHistory?: string; // 格式化的对话历史
// 项目信息
dependencies?: string[]; // 项目依赖列表
projectStructure?: string; // 项目目录结构
// 约束条件
constraints?: string[]; // 特殊约束
styleGuide?: string; // 编码风格指南
// Few-shot 示例
examples?: Example[];
}
export interface Example {
input: string;
output: string;
description?: string;
tags?: string[];
}
// === 模板定义 ===
export interface PromptTemplate {
id: string;
name: string;
description: string;
version: string;
template: string; // 模板字符串（支持 Mustache-like 语法）
variables: string[]; // 需要的变量列表
optionalVariables: string[]; // 可选变量列表
// 元数据
intents: string[]; // 适用意图
languages: string[]; // 适用语言
complexity: 'simple' | 'medium' | 'complex';
// 版本控制
createdAt: Date;
updatedAt: Date;
author: string;
// 性能指标
avgScore?: number; // 平均质量评分
usageCount?: number; // 使用次数
}
// === 模板引擎实现 ===
export class PromptTemplateEngine {
private templates = new Map<string, PromptTemplate>();
private cache = new Map<string, string>(); // 渲染缓存
/**
* 注册模板
*/
registerTemplate(template: PromptTemplate): void {
this.templates.set(template.id, template);
}
/**
* 渲染模板
*/
async render(
templateId: string,
variables: PromptVariables,
options?: RenderOptions,
): Promise<string> {
// 检查缓存
const cacheKey = this.buildCacheKey(templateId, variables);
if (options?.useCache !== false && this.cache.has(cacheKey)) {
return this.cache.get(cacheKey)!;
}
const template = this.templates.get(templateId);
if (!template) {
throw new Error(`Template not found: ${templateId}`);
}
// 变量验证
this.validateVariables(template, variables);
// 渲染
let rendered = template.template;
// 1. 变量替换
rendered = this.replaceVariables(rendered, variables);
// 2. 条件渲染 {{#if variable}}...{{/if}}
rendered = this.renderConditionals(rendered, variables);
// 3. 列表渲染 {{#each items}}...{{/each}}
rendered = this.renderLists(rendered, variables);
// 4. 后处理
rendered = this.postProcess(rendered, options);
// 缓存
this.cache.set(cacheKey, rendered);
return rendered;
}
/**
* 根据意图自动选择最佳模板
*/
selectBestTemplate(
intent: IntentType,
language: string,
complexity: 'simple' | 'medium' | 'complex',
): PromptTemplate | null {
const candidates = Array.from(this.templates.values()).filter(t =>
t.intents.includes(intent) &&
t.languages.includes(language) &&
t.complexity === complexity
);
if (candidates.length === 0) return null;
// 按 performance score 排序
candidates.sort((a, b) => (b.avgScore || 0) - (a.avgScore || 0));
return candidates[0];
}
}
4.2 内置高质量 Prompt 模板示例
<!-- ===== templates/code-generation/system.md ===== -->
You are MonkeyCode, an expert AI programming assistant.
## Core Principles
1. **Correctness First**: Generated code must be correct and functional.
2. **Best Practices**: Follow language-specific idioms and conventions.
3. **Security**: Never generate insecure code patterns (SQL injection, XSS, etc.).
4. **Performance**: Consider time/space complexity when relevant.
5. **Readability**: Write clean, well-documented code.
## Current Context
- Language: {{targetLanguage}}
- File: {{filePath}}
- Project: {{projectName}}
## User's Request
{{userQuery}}
## Nearby Code (for reference)
```{{targetLanguage}}
{{codeContext}}
Constraints
{{#each constraints}}
- {{this}}
Style Guide
{{styleGuide}}
Instructions
- Analyze the user's request carefully.
- Consider the surrounding code context.
- Generate code that integrates seamlessly.
- Add brief comments explaining non-obvious logic.
- If multiple approaches exist, prefer the most idiomatic one.
- Include necessary imports/dependencies.
Output ONLY the code solution. No explanations unless explicitly asked.
```markdown
<!-- ===== templates/debugging/system.md ===== -->
You are MonkeyCode Debug Expert.
## Debugging Methodology
### Step 1: Reproduce & Understand
- Analyze the error message and stack trace
- Identify the exact line and condition causing the issue
### Step 2: Root Cause Analysis
- Trace the data flow leading to the error
- Check for common anti-patterns:
- Null/undefined access
- Race conditions
- Type mismatches
- Off-by-one errors
- Async/await misuse
### Step 3: Solution Design
- Propose the minimal fix that resolves the root cause
- Explain WHY the fix works
- Suggest preventive measures
## Error Information
{{errorMessage}}
## Relevant Code
```{{targetLanguage}}
{{relevantCode}}
Recent Changes (if applicable)
{{recentChanges}}
Provide:
- Root cause explanation
- Fixed code with changes highlighted
- Prevention tips
---
## 五、RAG 检索增强生成系统
### 5.1 RAG 架构
```typescript
// ===== packages/core/src/rag/rag-system.ts =====
/**
* MonkeyCode RAG (Retrieval-Augmented Generation) 系统
*
* 通过检索项目代码库、文档、历史对话等外部知识源，
* 增强 LLM 的回答质量和准确性。
*/
import { z } from 'zod';
export interface RAGConfig {
// 向量数据库
vectorDB: {
provider: 'chromadb' | 'pinecone' | 'qdrant' | 'local';
embeddingModel: string; // 如 'text-embedding-3-small'
dimension: number; // 向量维度
indexName: string;
};
// 数据源
sources: {
codebase: {
enabled: boolean;
includePatterns: string[]; // 如 ['**/*.ts', '**/*.py']
excludePatterns: string[]; // 如 ['**/node_modules/**', '**/*.test.*']
chunkSize: number; // 代码分块大小 (字符数)
chunkOverlap: number; // 分块重叠大小
};
documentation: {
enabled: boolean;
paths: string[]; // 文档路径
formats: string[]; // 支持 md, rst, txt
};
gitHistory: {
enabled: boolean;
maxCommits: number; // 检索最近 N 次 commit
includeDiff: boolean;
};
issues: {
enabled: boolean;
providers: ('github' | 'gitlab' | 'jira')[];
maxIssues: number;
};
webSearch: {
enabled: boolean;
apiKey?: string;
maxResults: number;
};
};
// 检索策略
retrieval: {
topK: number; // 返回的最相关结果数
minScore: number; // 最小相似度阈值
hybridWeights: {
vector: number; // 向量搜索权重
keyword: number; // 关键词搜索权重
recency: number; // 时间新鲜度权重
};
reranking: {
enabled: boolean;
model: string; // 重排序模型
topN: number; // 重排序后保留数量
};
};
}
export interface RAGResult {
query: string;
chunks: RetrievedChunk[];
totalProcessed: number;
retrievalTimeMs: number;
// 用于 prompt 注入的格式化上下文
formattedContext: string;
}
export interface RetrievedChunk {
id: string;
content: string;
source: ChunkSource;
score: number;
metadata: Record<string, any>;
}
export class RAGSystem {
private config: RAGConfig;
private vectorStore: VectorStore;
private embedder: EmbeddingModel;
private indexer: CodeIndexer;
constructor(config: RAGConfig) {
this.config = config;
this.vectorStore = VectorStoreFactory.create(config.vectorDB);
this.embedder = new EmbeddingModel(config.vectorDB.embeddingModel);
this.indexer = new CodeIndexer(config.sources.codebase);
}
/**
* 检索相关上下文
*/
async retrieve(query: string, options?: RetrieveOptions): Promise<RAGResult> {
const startTime = Date.now();
// 1. 查询扩展（同义词、相关术语）
const expandedQueries = await this.expandQuery(query);
// 2. 多路检索
const [vectorResults, keywordResults] = await Promise.all([
this.vectorSearch(expandedQueries),
this.keywordSearch(query),
]);
// 3. 结果融合 (Reciprocal Rank Fusion)
const fused = this.reciprocalRankFusion(
vectorResults,
keywordResults,
this.config.retrieval.hybridWeights,
);
// 4. 过滤低分结果
const filtered = fused.filter(r => r.score >= this.config.retrieval.minScore);
// 5. 重排序 (可选)
let finalChunks = filtered.slice(0, this.config.retrieval.topK);
if (this.config.retrieval.reranking.enabled) {
finalChunks = await this.rerank(finalChunks, query);
}
// 6. 格式化为 prompt 上下文
const formattedContext = this.formatForPrompt(finalChunks);
return {
query,
chunks: finalChunks,
totalProcessed: filtered.length,
retrievalTimeMs: Date.now() - startTime,
formattedContext,
};
}
/**
* 索引项目代码库
*/
async indexProject(projectPath: string): Promise<IndexStats> {
console.log(`📂 Starting to index project: ${projectPath}`);
// 1. 扫描文件
const files = await this.indexer.scanFiles(projectPath);
console.log(`📊 Found ${files.length} files to index`);
// 2. 分块处理
const chunks: CodeChunk[] = [];
for (const file of files) {
const fileChunks = await this.indexer.chunkFile(file);
chunks.push(...fileChunks);
}
console.log(`✂️ Created ${chunks.length} chunks`);
// 3. 生成向量嵌入
const embeddings = await this.embedder.embedBatch(
chunks.map(c => c.content),
);
console.log(`🔢 Generated ${embeddings.length} embeddings`);
// 4. 存入向量数据库
await this.vectorStore.upsert(
chunks.map((chunk, i) => ({
id: chunk.id,
vector: embeddings[i],
metadata: chunk.metadata,
content: chunk.content,
})),
);
console.log('💾 Indexing complete!');
return {
filesIndexed: files.length,
chunksCreated: chunks.length,
totalTimeMs: Date.now() - startTime,
};
}
}
5.2 代码分块策略
// ===== packages/core/src/rag/chunker.ts =====
/**
* 代码感知的分块策略
*
* 与普通文本分块不同，代码分块需要：
* - 保持语法完整性（不在函数中间切断）
* - 保留语义边界（以函数/类为单位）
* - 维护依赖关系（包含必要的 import）
*/
export enum ChunkStrategy {
FUNCTION = 'function', // 以函数为单位
CLASS = 'class', // 以类为单位
SEMANTIC_BLOCK = 'semantic_block', // 语义块（连续的相关代码）
FIXED_SIZE = 'fixed_size', // 固定大小（回退方案）
HYBRID = 'hybrid', // 混合策略
}
export interface CodeChunk {
id: string;
content: string;
filePath: string;
language: string;
startLine: number;
endLine: number;
// 结构信息
symbols: SymbolInfo[]; // 包含的符号（函数名、类名等）
imports: string[]; // 相关 import 语句
exports: string[]; // export 的符号
// 元数据
chunkStrategy: ChunkStrategy;
complexity: number; // 圈复杂度估计
dependencies: string[]; // 依赖的其他 chunk ID
}
export class CodeChunker {
private strategy: ChunkStrategy;
private maxSize: number;
private overlap: number;
constructor(config: ChunkerConfig) {
this.strategy = config.strategy || ChunkStrategy.HYBRID;
this.maxSize = config.maxSize || 1500;
this.overlap = config.overlap || 200;
}
/**
* 将文件内容分割为语义完整的代码块
*/
async chunkFile(file: FileInfo): Promise<CodeChunk[]> {
// 使用 Tree-sitter 解析 AST
const ast = await this.parseAST(file.content, file.language);
switch (this.strategy) {
case ChunkStrategy.FUNCTION:
return this.chunkByFunction(file, ast);
case ChunkStrategy.CLASS:
return this.chunkByClass(file, ast);
case ChunkStrategy.SEMANTIC_BLOCK:
return this.chunkBySemanticBlock(file, ast);
case ChunkStrategy.HYBRID:
return this.chunkHybrid(file, ast);
default:
return this.chunkFixedSize(file);
}
}
/**
* 混合分块策略（推荐）
*
* 优先按函数/类分块，对于超大的代码块再进行二级切分
*/
private async chunkHybrid(file: FileInfo, ast: ASTNode): Promise<CodeChunk[]> {
const chunks: CodeChunk[] = [];
// 1. 提取顶层函数和类
const topLevelNodes = this.extractTopLevelSymbols(ast);
// 2. 文件头部的 imports 作为特殊块
const importBlock = this.extractImportBlock(file.content);
if (importBlock) {
chunks.push(this.createChunk(file, importBlock, 'imports'));
}
// 3. 每个函数/类作为一个块
for (const node of topLevelNodes) {
const nodeText = this.extractNodeText(file.content, node);
if (nodeText.length > this.maxSize) {
// 超大块：进一步分割
const subChunks = this.splitLargeChunk(file, node, nodeText);
chunks.push(...subChunks);
} else {
chunks.push(this.createChunk(file, nodeText, this.strategy, [node]));
}
}
// 4. 记录块间依赖关系
this.linkDependencies(chunks);
return chunks;
}
}
六、多模型适配与Fallback机制
6.1 统一LLM接口
// ===== packages/core/src/llm/adapter-interface.ts =====
/**
* LLM 统一适配接口
*
* 支持多种 LLM 提供商的无缝切换
*/
import { z } from 'zod';
import { EventEmitter } from 'events';
// === 统一的请求/响应格式 ===
export interface LLMRequest {
messages: ChatMessage[];
// 模型配置
model?: string; // 覆盖默认模型
temperature?: number; // 0-2
maxTokens?: number;
topP?: number;
// 流式控制
stream?: boolean;
streamOptions?: StreamOptions;
// 高级选项
stopSequences?: string[];
presencePenalty?: number;
frequencyPenalty?: number;
// 元数据
metadata?: {
requestId?: string;
userId?: string;
sessionId?: string;
intent?: string;
};
}
export interface LLMResponse {
id: string;
content: string;
finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
usage: TokenUsage;
model: string;
provider: string;
latencyMs: number;
// 流式响应时累积的内容
chunks?: DeltaChunk[];
}
export interface TokenUsage {
promptTokens: number;
completionTokens: number;
totalTokens: number;
// 缓存命中（支持 prompt caching 的模型）
cachedPromptTokens?: number;
// 成本估算
estimatedCostUsd?: number;
}
// === 适配器抽象基类 ===
export abstract class LLMAdapter extends EventEmitter {
abstract readonly providerName: string;
abstract readonly supportedModels: string[];
abstract readonly defaultModel: string;
abstract readonly maxContextTokens: number;
/**
* 发送聊天补全请求
*/
abstract complete(request: LLMRequest): Promise<LLMResponse>;
/**
* 流式聊天补全
*/
abstract stream(
request: LLMRequest,
onDelta: (delta: DeltaChunk) => void,
onDone: (response: LLMResponse) => void,
onError: (error: Error) => void,
): AbortController;
/**
* 健康检查
*/
abstract healthCheck(): Promise<boolean>;
/**
* 获取模型信息
*/
abstract getModelInfo(model: string): ModelInfo;
// === 通用工具方法 ===
/**
* 计算消息的 token 数
*/
countTokens(messages: ChatMessage[]): number {
// 使用 tiktoken 或近似估算
let total = 0;
for (const msg of messages) {
// 每条消息有约 4 个 token 的开销
total += 4;
total += this.estimateTokenCount(msg.content);
}
return total;
}
private estimateTokenCount(text: string): number {
// 粗略估算：英文约 4 字符/token，中文约 1.5 字符/token
const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).length;
const otherChars = text.length - chineseChars;
return Math.ceil(chineseChars / 1.5 + otherChars / 4);
}
}
// === 具体适配器实现 ===
/**
* OpenAI 适配器
*/
export class OpenAIAdapter extends LLMAdapter {
readonly providerName = 'openai';
readonly supportedModels = ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'o1', 'o3-mini'];
readonly defaultModel = 'gpt-4o';
readonly maxContextTokens = 128000;
private client: OpenAI;
constructor(apiKey: string, config?: OpenAIConfig) {
super();
this.client = new OpenAI({ apiKey, ...config });
}
async complete(request: LLMRequest): Promise<LLMResponse> {
const start = Date.now();
try {
const response = await this.client.chat.completions.create({
model: request.model || this.defaultModel,
messages: request.messages.map(m => ({ role: m.role, content: m.content })),
temperature: request.temperature ?? 0.7,
max_tokens: request.maxTokens,
stream: false,
});
const choice = response.choices[0];
return {
id: response.id,
content: choice.message.content || '',
finishReason: choice.finish_reason as LLMResponse['finishReason'],
usage: {
promptTokens: response.usage.prompt_tokens,
completionTokens: response.usage.completion_tokens,
totalTokens: response.usage.total_tokens,
},
model: response.model,
provider: this.providerName,
latencyMs: Date.now() - start,
};
} catch (error) {
this.emit('error', { provider: this.providerName, error });
throw error;
}
}
}
/**
* Ollama 本地模型适配器
*/
export class OllamaAdapter extends LLMAdapter {
readonly providerName = 'ollama';
readonly supportedModels: string[] = []; // 动态获取
readonly defaultModel = 'codellama:13b';
readonly maxContextTokens = 16384; // 取决于本地模型
private baseUrl: string;
constructor(baseUrl: string = 'http://localhost:11434') {
super();
this.baseUrl = baseUrl;
}
async complete(request: LLMRequest): Promise<LLMResponse> {
const start = Date.now();
const response = await fetch(`${this.baseUrl}/api/chat`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model: request.model || this.defaultModel,
messages: request.messages,
stream: false,
options: {
temperature: request.temperature ?? 0.7,
num_predict: request.maxTokens,
},
}),
});
const data = await response.json();
return {
id: `ollama-${Date.now()}`,
content: data.message?.content || '',
finishReason: 'stop',
usage: {
promptTokens: data.prompt_eval_count || 0,
completionTokens: data.eval_count || 0,
totalTokens: (data.prompt_eval_count || 0) + (data.eval_count || 0),
},
model: request.model || this.defaultModel,
provider: this.providerName,
latencyMs: Date.now() - start,
};
}
async healthCheck(): Promise<boolean> {
try {
const res = await fetch(`${this.baseUrl}/api/tags`);
const data = await res.json();
this.supportedModels = data.models?.map((m: any) => m.name) || [];
return true;
} catch {
return false;
}
}
}
6.2 智能Fallback与负载均衡
// ===== packages/core/src/llm/fallback-manager.ts =====
/**
* Fallback & Load Balancing Manager
*
* 当主模型不可用时自动切换到备用模型，
* 同时支持多实例负载均衡
*/
export interface FallbackConfig {
primary: LLMAdapter;
fallbacks: Array<{
adapter: LLMAdapter;
priority: number; // 优先级 (越小越高)
conditions: FallbackCondition[]; // 触发条件
}>;
// 全局策略
strategy: 'sequential' | 'parallel' | 'smart';
// 超时设置
timeoutMs: number;
// 重试配置
retry: {
maxAttempts: number;
baseDelayMs: number;
maxDelayMs: number;
backoffMultiplier: number;
};
// 熔断器配置
circuitBreaker: {
enabled: boolean;
failureThreshold: number; // 连续失败多少次触发熔断
recoveryTimeoutMs: number; // 熔断恢复时间
};
}
export type FallbackCondition =
| { type: 'timeout'; ms: number }
| { type: 'rate_limit'; retryAfterMs?: number }
| { type: 'error'; codes: string[] }
| { type: 'model_unavailable' }
| { type: 'cost_threshold'; maxCostPerRequest: number };
export class FallbackManager {
private config: FallbackConfig;
private circuitStates = new Map<string, CircuitState>;
private metrics = new MetricsCollector();
constructor(config: FallbackConfig) {
this.config = config;
}
/**
* 带自动 fallback 的请求
*/
async completeWithFallback(request: LLMRequest): Promise<LLMResponse> {
const adapters = this.getOrderedAdapters();
let lastError: Error | undefined;
for (const adapter of adapters) {
// 检查熔断状态
if (this.isCircuitOpen(adapter.providerName)) {
continue;
}
try {
// 带超时的请求
const result = await this.withTimeout(
adapter.complete(request),
this.config.timeoutMs,
);
// 成功：记录指标，重置熔断计数
this.metrics.recordSuccess(adapter.providerName, result.latencyMs);
this.resetCircuit(adapter.providerName);
return result;
} catch (error) {
lastError = error as Error;
this.metrics.recordFailure(adapter.providerName, error);
// 检查是否需要熔断
this.checkCircuitBreaker(adapter.providerName);
// 决定是否继续 fallback
if (!this.shouldFallback(error, adapter)) {
throw error;
}
}
}
// 所有 adapter 都失败
throw new AllAdaptersFailedError(
'All LLM adapters failed',
lastError,
this.getMetricsSnapshot(),
);
}
/**
* 智能 fallback：并行请求多个模型，返回最快的结果
*/
async smartComplete(request: LLMRequest): Promise<LLMResponse> {
if (this.config.strategy !== 'smart' && this.config.strategy !== 'parallel') {
return this.completeWithFallback(request);
}
// 并行请求所有可用 adapter
const promises = this.getAvailableAdapters().map(adapter =>
this.withTimeout(adapter.complete(request), this.config.timeoutMs)
.then(result => ({ adapter, result }))
.catch(error => ({ adapter, error: error as Error })),
);
// 等待第一个成功的结果
return new Promise((resolve, reject) => {
let completed = 0;
const total = promises.length;
for (const promise of promises) {
promise.then(({ adapter, result, error }) => {
completed++;
if (error) {
this.metrics.recordFailure(adapter.providerName, error);
} else {
this.metrics.recordSuccess(adapter.providerName, result!.latencyMs);
resolve(result!); // 第一个成功的结果胜出
}
// 所有都完成了且没有成功
if (completed === total && !resolved) {
reject(new AllAdaptersFailedError(...));
}
});
}
});
}
/**
* 获取各 adapter 的健康状态报告
*/
getHealthReport(): HealthReportEntry[] {
return this.getAvailableAdapters().map(adapter => ({
provider: adapter.providerName,
circuitOpen: this.isCircuitOpen(adapter.providerName),
successRate: this.metrics.getSuccessRate(adapter.providerName),
avgLatencyMs: this.metrics.getAvgLatency(adapter.providerName),
lastError: this.metrics.getLastError(adapter.providerName),
recommended: this.recommendAdapter(),
}));
}
}
七、对话质量保障体系
7.1 输出质量评估
# ===== packages/core/src/quality/evaluator.py =====
"""
MonkeyCode 对话输出质量评估器
从多个维度评估 AI 回复的质量
"""
from dataclasses import dataclass, field
from enum import Enum
from typing import Optional
import re
class QualityDimension(Enum):
CORRECTNESS = "correctness" # 正确性：代码能否正确运行
RELEVANCE = "relevance" # 相关性：是否回应了用户的问题
COMPLETENESS = "completeness" # 完整性：是否覆盖了所有需求
EFFICIENCY = "efficiency" # 效率：时间和空间复杂度
READABILITY = "readability" # 可读性：代码清晰程度
SECURITY = "security" # 安全性：是否存在安全隐患
STYLE_CONFORMANCE = "style" # 风格一致性：是否符合项目规范
EXPLAINABILITY = "explainability" # 可解释性：注释和文档是否充分
@dataclass
class QualityScore:
dimension: QualityDimension
score: float # 0-100
details: str # 评分原因
suggestions: list[str] = field(default_factory=list)
@dataclass
class EvaluationResult:
overall_score: float # 加权总分
dimensions: list[QualityScore]
passed: bool # 是否通过质量门槛
should_regenerate: bool # 是否建议重新生成
class DialogueQualityEvaluator:
def __init__(self, config: EvaluatorConfig):
self.config = config
self.threshold = config.threshold or 70.0
# 各维度权重
self.weights = {
QualityDimension.CORRECTNESS: 0.25,
QualityDimension.RELEVANCE: 0.15,
QualityDimension.COMPLETENESS: 0.15,
QualityDimension.EFFICIENCY: 0.10,
QualityDimension.READABILITY: 0.10,
QualityDimension.SECURITY: 0.15,
QualityDimension.STYLE_CONFORMANCE: 0.05,
QualityDimension.EXPLAINABILITY: 0.05,
}
def evaluate(
self,
user_query: str,
ai_response: str,
context: Optional[CodeContext] = None,
) -> EvaluationResult:
"""全面评估回复质量"""
scores = []
# 1. 正确性检查
scores.append(self.check_correctness(ai_response, context))
# 2. 相关性检查
scores.append(self.check_relevance(user_query, ai_response))
# 3. 完整性检查
scores.append(self.check_completeness(user_query, ai_response))
# 4. 效率评估
scores.append(self.check_efficiency(ai_response))
# 5. 安全扫描
scores.append(self.check_security(ai_response))
# 6. 可读性评估
scores.append(self.check_readability(ai_response))
# 7. 风格一致性
scores.append(self.check_style_conformance(ai_response, context))
# 计算加权总分
overall = sum(
s.score * self.weights[s.dimension]
for s in scores
)
return EvaluationResult(
overall_score=overall,
dimensions=scores,
passed=overall >= self.threshold,
should_regenerate=overall < self.threshold * 0.8,
)
def check_correctness(self, code: str, context: Optional[CodeContext]) -> QualityScore:
"""检查代码正确性"""
issues = []
score = 100
# 语法检查
if context and context.language:
syntax_ok = self._check_syntax(code, context.language)
if not syntax_ok:
score -= 30
issues.append("存在语法错误")
# 常见错误模式检测
error_patterns = [
(r"==\s*None", "使用 'is None' 而非 '== None'"),
(r"except\s*:", "裸 except 应指定异常类型"),
(r"\$\([^)]*\)", "避免命令注入风险的 shell 调用"),
(r"eval\s*\(", "eval 存在安全风险"),
(r"innerHTML\s*=", "innerHTML 可导致 XSS"),
]
for pattern, warning in error_patterns:
if re.search(pattern, code):
score -= 10
issues.append(warning)
return QualityScore(
dimension=QualityDimension.CORRECTNESS,
score=max(0, score),
details=f"发现 {len(issues)} 个潜在问题" if issues else "未发现明显问题",
suggestions=issues,
)
def check_security(self, code: str) -> QualityScore:
"""安全扫描"""
score = 100
vulnerabilities = []
# SQL 注入检测
if re.search(r'(f["\'].*SELECT|f["\'].*INSERT|f["\'].*UPDATE)', code, re.I):
vulnerabilities.append("可能的 SQL 注入风险 (f-string 拼接 SQL)")
score -= 25
# XSS 检测
if re.search(r'dangerouslySetInnerHTML|innerHTML\s*=.*\+', code):
vulnerabilities.append("可能的 XSS 风险")
score -= 25
# 硬编码密钥
if re.search(r'(password|secret|api_key|token)\s*=\s*["\'][^"\']{3,}', code, re.I):
vulnerabilities.append("硬编码敏感信息")
score -= 20
# 不安全的反序列化
if re.search(r'pickle\.loads|yaml\.load\s*\(', code):
vulnerabilities.append("不安全的反序列化")
score -= 20
return QualityScore(
dimension=QualityDimension.SECURITY,
score=max(0, score),
details=f"发现 {len(vulnerabilities)} 个安全问题" if vulnerabilities else "未发现安全问题",
suggestions=vulnerabilities,
)
7.2 对话效果指标
| 指标 | 说明 | 目标值 | 当前值 |
|---|---|---|---|
| 首解准确率 | 第一次回复即满足需求的比率 | >85% | 87.3% |
| 平均对话轮次 | 完成一个任务的平均交互次数 | <5 | 3.8 |
| 用户满意度 | 用户主动反馈的正向比例 | >90% | 92.1% |
| 代码采纳率 | 用户接受生成的代码的比例 | >80% | 84.7% |
| 安全违规率 | 生成含安全问题的代码比例 | <0.5% | 0.12% |
| 平均响应延迟 | 从输入到首次输出的时间 | <2s | 1.6s |
| 上下文利用率 | 上下文窗口的有效使用率 | >70% | 76.8% |
八、实际案例演示
案例1：从自然语言到完整功能
用户输入：
"帮我写一个用户认证的中间件，需要支持 JWT 验证和角色权限检查"
MonkeyCode 对话引擎处理流程：
┌─────────────────────────────────────────────────────┐
│ 📥 用户输入 │
│ "帮我写一个用户认证的中间件..." │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 🔍 NLU 意图分类 │
│ 意图: CODE_GENERATION (置信度: 0.94) │
│ 实体: [中间件, JWT验证, 角色权限] │
│ 语言: TypeScript (推测) │
│ 复杂度: medium │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 📂 代码上下文分析 │
│ • 检测到项目使用 Express + TypeScript │
│ • 发现已有 User 模型和 Role 枚举 │
│ • 已安装 jsonwebtoken 依赖 │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 🔎 RAG 检索 │
│ • 检索到项目中已有的 auth.utils.ts │
│ • 检索到项目的 middleware 模式约定 │
│ • 检索到 Role 类型的定义 │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 🤖 Prompt 构建 + LLM 生成 │
│ • 选择 code-generation 模板 │
│ • 注入上下文、RAG 结果、代码规范 │
│ • GPT-4o 生成代码 │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ ✅ 质量评估 + 输出 │
│ • 正确性: 95/100 ✅ │
│ • 安全性: 98/100 ✅ │
│ • 风格一致性: 92/100 ✅ │
│ • 总分: 94.5/100 → 通过 ✅ │
└─────────────────────────────────────────────────────┘
生成的代码：
// ===== src/middleware/auth.middleware.ts =====
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import { UserRole } from '../models/user.model';
import { UnauthorizedError, ForbiddenError } from '../utils/errors';
// 扩展 Express Request 类型以包含用户信息
declare global {
namespace Express {
interface Request {
user?: {
id: string;
email: string;
role: UserRole;
};
}
}
}
const JWT_SECRET = process.env.JWT_SECRET!;
const JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN || '24h';
export interface JwtPayload {
userId: string;
email: string;
role: UserRole;
iat: number;
exp: number;
}
/**
* JWT 认证中间件
*
* 验证请求中的 JWT token，并将解码的用户信息附加到 req.user
*
* @example
* ```ts
* app.get('/protected', authenticate, handler);
* ```
*/
export function authenticate(
req: Request,
_res: Response,
next: NextFunction,
): void {
const authHeader = req.headers.authorization;
if (!authHeader?.startsWith('Bearer ')) {
return next(new UnauthorizedError('缺少认证令牌'));
}
const token = authHeader.substring(7);
try {
const payload = jwt.verify(token, JWT_SECRET) as JwtPayload;
req.user = {
id: payload.userId,
email: payload.email,
role: payload.role,
};
next();
} catch (error) {
if (error instanceof jwt.TokenExpiredError) {
return next(new UnauthorizedError('认证令牌已过期'));
}
if (error instanceof jwt.JsonWebTokenError) {
return next(new UnauthorizedError('无效的认证令牌'));
}
next(new UnauthorizedError('认证失败'));
}
}
/**
* 角色权限检查中间件工厂
*
* @param allowedRoles - 允许访问的角色列表
* @returns Express 中间件函数
*
* @example
* ```ts
* // 仅管理员可访问
* app.delete('/users/:id', authorize([UserRole.ADMIN]), deleteUser);
*
* // 管理员和版主都可访问
* app.put('/posts/:id', authorize([UserRole.ADMIN, UserRole.MODERATOR]), updatePost);
* ```
*/
export function authorize(allowedRoles: UserRole[]) {
return (
req: Request,
_res: Response,
next: NextFunction,
): void => {
if (!req.user) {
return next(new UnauthorizedError('请先登录'));
}
if (!allowedRoles.includes(req.user.role)) {
return next(
new ForbiddenError(
`需要 ${allowedRoles.join('/')} 权限，当前角色: ${req.user.role}`,
),
);
}
next();
};
}
/**
* 组合中间件：认证 + 授权一步到位
*
* @param roles - 允许的角色列表
* @returns 组合后的中间件数组
*/
export function requireAuth(roles: UserRole[]) {
return [authenticate, authorize(roles)];
}
案例2：多轮迭代调试
用户: 这个中间件在 token 过期时应该自动刷新
↓
MonkeyCode: [添加 refresh token 逻辑 + 自动刷新机制]
↓
用户: 很好，但还需要处理并发请求时的竞态条件
↓
MonkeyCode: [引入 token 刷新锁 + 请求排队机制]
↓
用户: 能加一下单元测试吗？
↓
MonkeyCode: [生成完整的 Jest 测试套件，覆盖正常/过期/刷新/竞态场景]
↓
用户: 完美！✅
九、性能基准数据
9.1 对话引擎性能指标
| 指标 | P50 | P95 | P99 | 目标 |
|---|---|---|---|---|
| 意图分类延迟 | 12ms | 28ms | 45ms | <50ms |
| 实体提取延迟 | 18ms | 42ms | 68ms | <80ms |
| RAG 检索延迟 | 45ms | 120ms | 280ms | <300ms |
| Prompt 构建延迟 | 8ms | 15ms | 25ms | <30ms |
| LLM 首字节延迟 | 380ms | 1200ms | 3500ms | <2000ms |
| 完整生成延迟 | 1.2s | 3.8s | 12s | <5s |
| 端到端响应延迟 | 1.8s | 4.5s | 13s | <6s |
9.2 不同场景下的表现
| 场景 | 平均轮次 | 准确率 | 用户满意度 |
|---|---|---|---|
| 简单代码生成 | 1.2 | 94.2% | 96.1% |
| Bug 修复 | 2.1 | 89.7% | 91.3% |
| 代码重构 | 2.8 | 86.4% | 88.9% |
| 功能实现 | 3.2 | 84.1% | 87.6% |
| 架构设计 | 4.5 | 78.3% | 82.1% |
| 调试排错 | 2.5 | 91.2% | 93.4% |
结语
"最好的编程助手不是替你写代码，而是真正理解你的意图。"
MonkeyCode 的 AI 对话引擎不仅是一个"聪明的代码生成器"，更是一个深度的编程理解伙伴。通过多层 NLU、智能上下文管理、RAG 增强和多模型协作，它能够：
- ✅ 听懂你的自然语言描述
- ✅ 理解你的代码上下文和项目背景
- ✅ 思考最佳的实现方案
- ✅ 生成高质量、安全的代码
- ✅ 迭代直到你完全满意
这就是 MonkeyCode 对话引擎的核心价值——让编程回归本质：解决问题，而不是与工具搏斗。
💬 参与方式
- 🐛 发现对话问题？→ 提交 Issue 并标记
dialogue-engine- ✨ 想改进对话能力？→ 查看 CONTRIBUTING.md 中的 NLP 贡献指南
- 💬 讨论对话体验？→ Discord #dialogue 频道
- 📊 查看最新评测？→ eval.monkeycode.ai
MonkeyCode — 让每一次对话都更有价值。 🐵💬✨
浙公网安备 33010602011771号