使用说明
🟣 基于MCP的代理生产力系统
认知执行助理,具有持久记忆、多模式处理和通过MCP协议进行子代理编排。
📋 概述
米拉 是一个基于人工智能的编排器,它将谷歌工作区服务(日历、任务、Gmail)和财务管理集中到Telegram上的对话界面中。该系统实现了一种受人类记忆模型启发的认知架构,其特征是感觉处理、短期记忆和巩固为长期记忆。
关键能力
- 🧠 认知架构:感官、短期和长期记忆之间的明确区分。
- 🎙️ 多模态:通过Google Gemini 2.0处理文本、音频、图像和文档。
- 🔒 护栏:检测NSFW内容和越狱尝试。
- 🔧 MCP协议:专门负责特定任务的次级代理人。
- 📊 RAG系统:使用Supabase矢量存储进行检索增强生成。
- ⚡ 智能缓冲器:用于会话上下文保存的消息聚合。
🏗️ 系统架构
高级概述
graph TB
subgraph "Input Layer"
TG[Telegram Bot]
USER[User]
end
subgraph "Sensory Processing"
SWITCH{Content Type}
AUDIO[Audio Transcription]
IMAGE[Image Analysis]
DOC[Document Analysis]
TEXT[Text Input]
GR[Guardrails<br/>NSFW + Jailbreak]
end
subgraph "Sensory Memory"
BUFFER[(Message Buffer<br/>PostgreSQL)]
WAIT[Wait 3s]
AGG[Message Aggregator]
end
subgraph "Cognitive Layer"
AGENT[Complex Agent<br/>GPT-4.1-mini]
STM[(Short-term Memory<br/>PostgreSQL)]
LTM[(Long-term Memory<br/>Vector Store)]
end
subgraph "Tool Registry"
THINK[Think Tool]
CALC[Calculator]
MCP[MCP Sub-agents]
SEARCH[Web Search]
end
subgraph "Output Layer"
SEND[Telegram Send]
CLEAN[Buffer Cleanup]
end
USER -->|Message| TG
TG --> SWITCH
SWITCH -->|Text| TEXT
SWITCH -->|Audio| AUDIO
SWITCH -->|Image| IMAGE
SWITCH -->|Document| DOC
TEXT --> GR
AUDIO --> GR
IMAGE --> GR
DOC --> GR
GR -->|Safe| BUFFER
GR -->|Unsafe| SEND
BUFFER --> WAIT
WAIT --> AGG
AGG --> AGENT
AGENT <--> STM
AGENT <--> LTM
AGENT <--> THINK
AGENT <--> CALC
AGENT <--> MCP
AGENT <--> SEARCH
AGENT --> SEND
SEND --> CLEAN
CLEAN --> BUFFER
🧩 技术组件
1.感觉层(输入处理)
责任多模式输入的识别和规范化。
graph LR
INPUT[Input] --> SWITCH{Type?}
SWITCH -->|text| TEXT[Direct to Guardrails]
SWITCH -->|voice| VOICE[Get Audio File]
SWITCH -->|photo| PHOTO[Get Image File]
SWITCH -->|document| DOC[Get Document File]
VOICE --> TRANS[Transcribe<br/>Gemini 2.0]
PHOTO --> ANALYZE[Analyze Image<br/>Gemini 2.0]
DOC --> EXTRACT[Extract Text<br/>Gemini 2.0]
TRANS --> GR[Guardrails]
ANALYZE --> GR
EXTRACT --> GR
TEXT --> GR
GR -->|Pass| BUFFER[(Buffer)]
GR -->|Fail| REJECT[Send Rejection]
堆栈:
- 谷歌双子座2.0 Flash:音频转录、图像分析和文档提取。
- Llama 3.1 70B:护栏(NSFW检测、越狱预防)。
- 阈值:两道护栏均为0.7。
韵律学:
- 平均延迟:800毫秒-1.5秒
- 精度(护栏):~94%
2.感官记忆(消息缓冲区)
责任:聚合连续消息以构建上下文。
算法:
-- 1. Insert into buffer
INSERT INTO message_buffer (chat_id, content, batch_id)
VALUES ($chat_id, $content, NULL);
-- 2. Wait 3 seconds (allows for multiple incoming messages)
-- 3. Atomic marking with batch_id
UPDATE message_buffer
SET batch_id = $execution_id
WHERE chat_id = $chat_id
AND batch_id IS NULL
RETURNING content;
-- 4. Aggregation
SELECT STRING_AGG(content, '\n' ORDER BY id) as full_context
FROM message_buffer
WHERE batch_id = $execution_id;
-- 5. Post-processing Cleanup
DELETE FROM message_buffer WHERE batch_id = $execution_id;
优势:
- ✅ 原子性:使用
batch_id防止比赛条件。 - ✅ 上下文窗口:~3s内的多条消息会一起处理。
- ✅ 自动清理:缓冲区在每个循环后被清除。
3.认知层(代理+记忆)
代理架构
graph TB
subgraph "Agent Core"
INPUT[User Input] --> THINK[Think Tool<br/>Intent Analysis]
THINK --> DECISION{Decision Type}
end
subgraph "Memory Systems"
STM[(Short-term<br/>PostgreSQL<br/>10 msgs)]
LTM[(Long-term<br/>Supabase Vector<br/>OpenAI Embeddings)]
end
subgraph "Tool Registry"
CALC[Calculator]
WEB[Web Search<br/>Native GPT-4.1]
MCP[MCP Sub-agents]
end
DECISION -->|Retrieval| LTM
DECISION -->|Action| MCP
DECISION -->|Compute| CALC
DECISION -->|Research| WEB
STM -.->|Context| DECISION
LTM -.->|Memories| DECISION
MCP --> OUTPUT[Response]
CALC --> OUTPUT
WEB --> OUTPUT
LTM --> OUTPUT
型号: GPT-4.1分钟(GPT-5.1)
- 上下文窗口:10条信息(短期记忆)。
- 温度:默认值(0.7)。
- 内建:网络搜索(中等上下文)。
提示工程
应用策略:
- 思维链(CoT):强制要求
think用于显式推理的工具。 - 小样本学习:系统提示中嵌入的交互示例。
- TOON(面向令牌的对象表示法):分层提示结构。
- 工具调用:基于意图分析的决策。
系统提示结构:
🟣 SYSTEM_IDENTITY
🟣 CONTEXT_VARIABLES (date, time, user)
🟣 GLOBAL_CONSTRAINTS (formatting, data integrity)
🟣 DECISION_PROTOCOL (priority order)
🟣 TOOL_REGISTRY (tech specs)
🟣 ORCHESTRATION_PROTOCOL (workflow)
🟣 FEW_SHOT_EXAMPLES
4.存储系统
短期记忆(工作记忆)
graph LR
A[New Interaction] --> B[(PostgreSQL<br/>n8n_chat_histories)]
B --> C{Window Size}
C -->|Keep| D[Last 10 messages]
C -->|Archive| E[Long-term Consolidation]
D --> F[Agent Context]
架构:
CREATE TABLE n8n_chat_histories (
id SERIAL PRIMARY KEY,
session_id VARCHAR(255),
message JSONB,
created_at TIMESTAMP DEFAULT NOW()
);
保留政策:
- 活动窗口:最后10条消息。
- 清理:删除超过30天的邮件(每月定时)。
长期记忆(情景记忆)
graph TB
subgraph "Daily Consolidation (3AM)"
CRON[Schedule Trigger] --> AGG[Aggregate 24h Messages]
AGG --> EXTRACT[Information Extractor<br/>Llama 3.3 70B]
end
subgraph "Extraction Schema"
EXTRACT --> SCHEMA{Extracted Fields}
SCHEMA --> T[main_topic]
SCHEMA --> E[entities]
SCHEMA --> A[action_taken]
SCHEMA --> I[relevant_info]
end
subgraph "Vector Storage"
SCHEMA --> EMBED[OpenAI Embeddings<br/>text-embedding-3-small<br/>1536 dims]
EMBED --> VDB[(Supabase pgvector<br/>agent_memory)]
end
subgraph "Retrieval"
QUERY[User Query] --> QEMBED[Embed Query]
QEMBED --> SEARCH[Cosine Similarity]
VDB --> SEARCH
SEARCH --> CONTEXT[Top-K Results]
end
合并查询:
-- 24h Aggregation
SELECT STRING_AGG(message->>'content', E'\n' ORDER BY id) as batch
FROM n8n_chat_histories
WHERE created_at > NOW() - INTERVAL '1 day';
矢量存储架构:
CREATE TABLE agent_memory (
id BIGSERIAL PRIMARY KEY,
content TEXT,
metadata JSONB,
embedding VECTOR(1536)
);
CREATE INDEX ON agent_memory
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
检索策略:
- 嵌入模型:
text-embedding-3-small(OpenAI)。 - 距离度量:余弦相似性。
- 顶部K:5个结果。
- 元数据筛选:
chat_id,date_range.
5.MCP子代理(任务委托)
MCP协议:用于主代理和专用子代理之间通信的模型上下文协议。
graph TB
AGENT[Complex Agent] -->|MCP Request| SERVER[MCP Server]
SERVER --> CAL[calendar_agent]
SERVER --> MAIL[gmail_agent]
SERVER --> FIN[financial_agent]
SERVER --> REPORT[financial_report]
SERVER --> TASK[tasks_agent]
CAL -->|CRUD| GCAL[Google Calendar API]
MAIL -->|Send/Reply| GMAIL[Gmail API]
FIN -->|Read/Write| SHEETS[Google Sheets API]
REPORT -->|Generate Chart| VIZ[Data Visualization]
TASK -->|CRUD| GTASKS[Google Tasks API]
GCAL --> RESPONSE[MCP Response]
GMAIL --> RESPONSE
SHEETS --> RESPONSE
VIZ --> RESPONSE
GTASKS --> RESPONSE
RESPONSE --> AGENT
子代理规格:
| 代理 | 功能 | API | 范围 |
|---|---|---|---|
calendar_agent |
CRUD事件、列表、搜索 | Google日历 | - |
gmail_agent |
发送、回复、标签、搜索 | Gmail | - |
financial_agent |
记录费用,读取余额 | 谷歌表格 | personal or business |
financial_report |
生成图表、摘要 | 谷歌表格+Chart.js | personal or business |
tasks_agent |
CRUD任务,标记完成 | Google任务 | - |
MCP呼叫示例:
{
"tool": "sub_agents",
"params": {
"agent": "calendar_agent",
"prompt": "Schedule meeting with Ana on Jan 15th, 2026 at 2 PM",
"scope": null
}
}
响应处理:
- 成功:子代理返回结构化确认。
- 失败:自动重试(最多2次尝试)。
- 媒体输出:
financial_report返回图像(绕过文本生成)。
错误处理
该系统实现了一个强大的错误处理机制,以确保连续执行和显式恢复。具体来说,它使用 错误触发器 在n8n中检测故障并解锁当前流状态。
已实现的错误流
1.流量解锁机制
一 错误触发器 如果与关联的执行中出现问题,则激活 message_buffer。该流清空当前批以防止死锁并重新处理消息:
流量:
- 触发:检测错误事件。
- 取消记录器:删除
batch_id从message_buffer使用以下SQL:
UPDATE message_buffer
SET batch_id = NULL
WHERE batch_id = '{{ $execution.id }}';
此过程可确保没有消息保持锁定状态,从而允许对受影响的流进行新的执行。
2.短期内存清理
定期安排的工作(预定触发器)删除过时的记录(超过30天的交互):
流量:
- 触发:每月凌晨3点运行。
- 清洁工:执行以下命令:
DELETE FROM n8n_chat_histories
WHERE created_at < NOW() - INTERVAL '30 days';
这通过仅保留相关窗口来确保最佳性能 STM 操作。
📊 绩效和指标
延迟分解
gantt
title Execution Timeline (without tools)
dateFormat SSS
section Input
Sensory Processing :000, 800ms
Guardrails Check :800, 400ms
section Buffer
Wait Period :1200, 3000ms
Message Aggregation :4200, 200ms
section Cognitive
Agent Processing :4400, 2000ms
section Output
Telegram Send :6400, 300ms
| 场景 | 延迟 | 令牌 | 成本(估计) |
|---|---|---|---|
| 简单文本(无工具) | ~3s | 1k-3k | 0.001-0.003美元 |
| 文本+工具调用 | ~7s-10s | 4k-15k | 0.004-0.015美元 |
内存统计
- 短期窗口:10条消息(滚动)。
- 长期储存:约30个记忆/月。
🔧 技术栈
核心基础设施
- 编排:n8n(自托管)
- 数据库:PostgreSQL 15+pgvector
- 向量存储:Supabase(管理)
- 托管:人质
AI模型
| 组件 | 模型 | 提供者 | 目的 |
|---|---|---|---|
| 主代理 | GPT-4.1-mini | OpenAI | 认知编排 |
| 转录 | Gemini 2.0 Flash | 谷歌 | 音频→ 文本 |
| 图像分析 | Gemini 2.0 Flash | 谷歌 | 视觉→ 文本 |
| 文档分析 | Gemini 2.0 Flash | 谷歌 | PDF/Doc→ 文本 |
| 护栏 | Llama 3.1 70B | OpenRouter | 安全检查 |
| 内存提取 | Llama 3.3 70B | OpenRouter | 信息提取 |
| 嵌入 | 文本嵌入-3-小 | OpenAI | 矢量生成 |
集成
-
电报机器人API:用户界面
-
谷歌云平台:
-
日历API
-
Gmail API
-
任务API
-
表API
-
MCP协议:自定义子代理服务器
🚀 用例
1.议程管理
👤 User: "Lunch with Ana tomorrow at 1 PM"
🟣 Mira: [Calls calendar_agent]
"Done! Scheduled Lunch with Ana
for tomorrow (Jan 15) at 1 PM. ✅"
2.财务控制
👤 User: "Spent $50 on lunch"
🟣 Mira: "Was this Personal or Business expense?"
👤 User: "Business"
🟣 Mira: [Calls financial_agent]
"Logged! 💰 $50.00 (Business - Food)"
3.视觉报告
👤 User: "How much did I spend this month?"
🟣 Mira: "Do you want the Personal or Business report?"
👤 User: "Personal"
🟣 Mira: [Calls financial_report]
[Sends PNG chart via Telegram]
4.上下文检索
👤 User: "What did I agree with Carlos in the last meeting?"
🟣 Mira: [Searches long-term memory]
"In the meeting on Jan 10th, you agreed with Carlos to:
• Deliver the proposal by Jan 20th
• Review the cost spreadsheet
• Next meeting: Jan 25th at 3 PM"
📄 完整的技术文档
此README介绍了项目的高级架构。获取完整的技术文档,包括:
- 🔧 带有模拟凭据的设置指南
- 📊 详细成本分析
- 🎥 用例视频演示
- 📝 山宁泰工作流程JSON
- 🧪 性能测试
联系我 通过codeajr@gmail.com.
🤝 贡献
这是一个为个人/商业用途开发的专有项目。完整的源代码尚未公开,但欢迎通过Issues提出技术建议和讨论。
📝 许可证
专有许可 -保留所有权利。
该项目是保密的,包含专有集成。本文档仅用于技术组合目的。
👤 作者
安德烈·科达
- 领英: https://linkedin.com/in/andrecodea
- github: https://github.com/andrecodea
- 电子邮件:codeajr@gmail.com
Built with ❤️ using n8n, OpenAI, and lots of ☕
