内容
# 🧠 Cerebro — 你的大脑在 Azure 云端
<p align="center">
<img src="docs/images/cerebro-logo.png" alt="Cerebro Logo" width="200">
</p>
> 一个完全基于 Azure 的个人知识库。从任何与 MCP 兼容的 AI 客户端或 Microsoft Teams 捕获思绪,使用 Azure OpenAI 嵌入,存储在 PostgreSQL 中,并使用 pgvector,让任何 AI 助手搜索你的记忆。包括任务管理、文件附件和 AI 驱动的每日/每周摘要,通过电子邮件发送。
[](https://learn.microsoft.com/azure/azure-functions/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
---
## ✨ 功能介绍
- 🔍 **语义搜索** — 通过含义而非关键词查找思绪(pgvector 余弦相似度)
- 📝 **从任何地方捕获** — MCP 客户端(VS Code、Claude、ChatGPT)和 Microsoft Teams
- ✅ **任务管理** — 通过语义匹配完成、重新打开和软删除任务
- 📎 **文件附件** — 图片由 GPT-4o 视觉分析,DOCX 解析,存储在 Blob Storage 中
- 📊 **每日和每周摘要** — AI 生成的摘要通过 Teams 主动消息 + 电子邮件发送
- 🔐 **GitHub OAuth 2.1** — 浏览器登录,用于 MCP 客户端,无需管理 API 密钥
- 🤖 **Teams 机器人** — Bot Framework 集成,带有 JWT 验证
---
## 🏗️ 架构
```text
┌──────────────┐ ┌──────────────────┐ ┌────────────────────┐
│ MCP 客户端 │─── OAuth 2.1 ──▶│ Azure 函数 │──────▶│ PostgreSQL │
│ (任意 AI) │ GitHub 登录 │ cerebro-mcp │ │ pgvector (1536d) │
└──────────────┘ └──────────────────┘ └────────────────────┘
│ ▲
▼ │
┌──────────────┐ │
│ Azure OpenAI │ │
│ 嵌入 + 聊天 │ │
└──────────────┘ │
│
┌──────────────┐ ┌──────────────────┐ │
│ Microsoft │──────▶│ Azure 函数 │──────────────────────────┘
│ Teams │ 机器人 │ cerebro-teams │──▶ Blob Storage (文件)
└──────────────┘ 框架 └──────────────────┘
┌──▶ Teams(主动消息)
┌──────────────┐ ┌──────────────────┐ │
│ 计时器 + │──────▶│ Azure 函数 │─────────┤
│ HTTP 触发器 │ │ cerebro-digest │ │
└──────────────┘ └──────────────────┘ └──▶ 电子邮件(ACS)
```
**四组函数** 在 Azure Functions v4(TypeScript,Node.js 20)上:
| 函数 | 触发器 | 目的 |
|----------|---------|---------|
| `cerebro-mcp` | HTTP(GET/POST) | MCP 服务器 — 通过 Streamable HTTP 提供 7 种工具 |
| `cerebro-teams` | HTTP(POST) | Teams 机器人 Webhook — Bot Framework |
| `cerebro-digest` | 计时器 + HTTP | 每日/每周 AI 摘要 |
| `cerebro-oauth` | HTTP(6 个路由) | GitHub OAuth 2.1 端点 |
---
## 🔧 MCP 工具
MCP 服务器向任何连接的 AI 客户端公开 **7 种工具**:
| 工具 | 描述 |
|------|-------------|
| `search_thoughts` | 通过查询相似性进行语义搜索 |
| `list_thoughts` | 按类型、主题、人员、时间范围、状态、文件浏览/筛选 |
| `thought_stats` | 聚合统计 — 总数、类型、热门主题、人员 |
| `capture_thought` | 保存新的思绪,自动嵌入 + 元数据提取 |
| `complete_task` | 通过与开放任务的语义匹配将任务标记为完成 |
| `reopen_task` | 通过与已完成任务的语义匹配重新打开任务 |
| `delete_task` | 通过语义匹配软删除思绪 |
---
## 📡 连接 AI 客户端
当你连接时,浏览器会打开 GitHub 登录页面 — **无需 API 密钥**。
| 客户端 | 如何连接 |
|--------|----------------|
| **VS Code / Copilot** | 添加到 `mcp.json`:`{"type": "http", "url": "https://your-func.azurewebsites.net/cerebro-mcp"}` |
| **Claude Desktop** | 设置 → MCP → 添加服务器 → HTTP → 粘贴 URL |
| **Claude Code** | `claude mcp add cerebro --transport http https://your-func.azurewebsites.net/cerebro-mcp` |
| **其他 MCP 客户端** | 直接使用 HTTP URL;OAuth 发现是自动的 |
OAuth 使用 **RFC 9728 + RFC 8414** 发现,**RFC 7591** 动态客户端注册和 PKCE 支持。`host.json` 路由前缀设置为空字符串,因此 `.well-known` 路由在根目录下解析。VS Code、opencode、Claude Code 和任何其他符合 RFC 7591 的 MCP 客户端都将自动注册并连接,无需手动配置。
---
## 🤖 Teams 机器人
向 Cerebro 机器人发送任何消息 — 它会自动捕获为一个思绪。
| 输入 | 发生情况 |
|-------|--------------|
| 任意消息 | 捕获为思绪(嵌入,元数据提取) |
| `done: <描述>` | 将最匹配的开放任务标记为完成 |
| `reopen: <描述>` | 重新打开最匹配的已完成任务 |
| `delete: <描述>` | 软删除最匹配的思绪 |
| 文件附件 | 存储在 Blob Storage 中 + 由 AI 分析 |
**文件处理:** 图片由 GPT-4o 视觉分析。DOCX 文件由 mammoth 解析。分析包含在思绪内容中,以便搜索。
**循环保护:** 机器人拒绝以其自己的回复前缀(`**Captured**`、`✅ **Marked done**` 等)开头的消息,以防止 Power Automate / webhook 重新触发循环。
**自动注册:** 机器人在第一次消息时为摘要传递注册对话。
---
## 📊 摘要
AI 生成的您最近的思绪、已完成的任务和即将到来的提醒的摘要。
| 摘要 | 时间表 | 内容窗口 |
|--------|----------|----------------|
| **每日** | 6:00 AM 中部时间(计时器) | 过去 24 小时 + 接下来 48 小时的提醒 |
| **每周** | 星期日 12:00 PM 中部时间(计时器) | 过去 7 天 + 接下来 7 天的提醒 |
两者都有手动 HTTP 触发器,用于按需生成。
**传递:** Teams 主动消息 + 通过 Azure Communication Services 的电子邮件。`summary` 字段(Teams Markdown)上限约为 24KB — 如果内容超过此限制,Teams 中会省略思绪列表,但会在 HTML 电子邮件中保留。
---
## 🔐 身份验证
| 表面 | 方法 |
|---------|--------|
| **MCP 端点** | GitHub OAuth 2.1 — 浏览器登录,PKCE,DCR(RFC 7591),令牌刷新 |
| **Teams 机器人** | Bot Framework JWT 验证通过 Entra ID |
| **摘要 HTTP 触发器** | Azure Functions 主机密钥(函数级身份验证) |
---
## 🚀 快速开始
> 完整指南: **[docs/setup.md](docs/setup.md)**
```bash
# 1. 预配基础设施
cd infra/terraform
cp terraform.tfvars.example terraform.tfvars # 用您的值编辑
terraform init && terraform apply
# 2. 运行数据库迁移(4 个文件,按顺序)
psql "$DATABASE_URL" -f infra/database/01-enable-pgvector.sql
psql "$DATABASE_URL" -f infra/database/02-create-thoughts-table.sql
psql "$DATABASE_URL" -f infra/database/03-create-search-function.sql
psql "$DATABASE_URL" -f infra/database/04-create-digest-channels.sql
# 3. 注册 GitHub OAuth 应用(用于 MCP 身份验证)
# 4. 构建和部署
cd functions
npm install && npm run build
func azure functionapp publish cerebro-func --node
# 5. 连接 MCP 客户端
# VS Code → mcp.json: {"type": "http", "url": "https://your-func.azurewebsites.net/cerebro-mcp"}
```
---
## ☁️ Azure 服务
| 服务 | 默认名称 | 目的 |
|---------|-------------|---------|
| 资源组 | `cerebro-rg` | 所有资源的容器 |
| Azure Functions | `cerebro-func` | 无服务器计算(消耗计划) |
| Azure 数据库 for PostgreSQL | `cerebro-db` | 使用 pgvector 的向量存储 |
| Azure OpenAI | `cerebro-openai` | 嵌入 + 聊天 + 视觉 |
| Azure Blob Storage | `cerebrostorage` | 文件附件存储 |
| Azure Communication Services | `cerebro-acs` | 摘要的电子邮件传递 |
| Azure Bot Service | `cerebro-bot` | Teams 机器人注册 |
| Azure API 管理 | `cerebro-apim` | 可选:速率限制,监控 |
| Application Insights | *(自动预配)* | 监控 + 日志记录 |
| Entra ID | 应用注册 | Bot Framework 身份验证 |
---
## 📁 项目结构
```text
cerebro-ms/
├── functions/ # Azure Functions v4(TypeScript,Node 20)
│ ├── app.ts # 入口点 — 导入所有函数模块
│ ├── cerebro-mcp/index.ts # MCP 服务器(7 种工具,Streamable HTTP)
│ ├── cerebro-teams/index.ts # Teams 机器人 Webhook(Bot Framework)
│ ├── cerebro-digest/index.ts # 计时器 + HTTP 摘要触发器
│ ├── cerebro-oauth/index.ts # GitHub OAuth 2.1(6 个路由)
│ ├── lib/
│ │ ├── azure-ai.ts # Azure OpenAI — 嵌入,元数据,视觉
│ │ ├── database.ts # PostgreSQL 连接池 + 查询
│ │ ├── blob-storage.ts # Blob 上传 + SAS URL 生成
│ │ ├── email.ts # ACS 电子邮件传递
│ │ ├── github-oauth.ts # GitHub OAuth 帮助程序
│ │ ├── auth.ts # Bot Framework JWT 验证
│ │ └── types.ts # 共享 TypeScript 接口
│ ├── host.json # 函数应用配置(空路由前缀)
│ ├── package.json
│ └── tsconfig.json
├── infra/
│ ├── terraform/ # 所有 Azure 资源的 IaC
│ └── database/ # SQL 迁移(01–04,按顺序运行)
├── teams/ # Teams 应用清单 + 图标
├── docs/ # 设置和部署指南
├── archive/ # 原始项目文件(存档)
├── .env.example # 环境变量参考
└── README.md
```
---
## 🛠️ 开发
```bash
cd functions
npm install # 安装依赖
npm run build # 编译 TypeScript → dist/
npm run watch # 在监视模式下编译
npm run start # 本地开发服务器(需要 Azure Functions Core Tools v4)
```
没有配置测试套件或 linter。
### ⚙️ 环境变量
参见 [`.env.example`](.env.example) 获取完整列表。关键组:
| 组 | 变量 |
|-------|-----------|
| Azure OpenAI | `AZURE_OPENAI_ENDPOINT`,`AZURE_OPENAI_API_KEY`,`*_EMBEDDING_DEPLOYMENT`,`*_CHAT_DEPLOYMENT`,`*_VISION_DEPLOYMENT` |
| 数据库 | `DATABASE_URL` |
| Blob Storage | `AZURE_STORAGE_CONNECTION_STRING` |
| Teams 机器人 | `TEAMS_BOT_APP_ID`,`TEAMS_BOT_APP_SECRET`,`TEAMS_BOT_TENANT_ID` |
| GitHub OAuth | `GITHUB_OAUTH_CLIENT_ID`,`GITHUB_OAUTH_CLIENT_SECRET`,`GITHUB_ALLOWED_USERS` |
| 电子邮件(ACS) | `ACS_CONNECTION_STRING`,`ACS_EMAIL_SENDER` |
| Graph API | `GRAPH_TENANT_ID`,`GRAPH_CLIENT_ID`,`GRAPH_CLIENT_SECRET` |
> **注意:** Azure OpenAI 使用 **部署名称**,而非模型名称。
### 🧩 密钥约定
- **嵌入 + 元数据提取并行运行**(`Promise.all`)— 绝不串行
- **向量维度为 1536**(text-embedding-3-small)。更改模型需要更新 SQL 迁移 + HNSW 索引
- **星期几 + 中部时间** 注入 AI 提示中,用于相对日期解析(“下一个星期一”等)
- **计时器触发器** 使用 `WEBSITE_TIME_ZONE=Central Standard Time`
- **循环保护** 防止机器人重新处理其自己的回复
- **摘要截断** 在 ~24KB(Teams 消息限制);完整内容在电子邮件 HTML 中
- **SQL 迁移是幂等的**(`IF NOT EXISTS` / `CREATE OR REPLACE`)
- **令牌验证缓存** 5 分钟/令牌/函数实例 — GitHub API 不会在每个 MCP 请求上调用
- **动态客户端注册**(RFC 7591)在 `/oauth/register` 上支持 — VS Code、opencode 和其他兼容客户端自动注册
---
## 📚 文档
| 指南 | 描述 |
|-------|-------------|
| [设置指南](docs/setup.md) | 完整的部署指南 |
| [MCP OAuth 设置](docs/02-mcp-oauth-setup.md) | MCP 服务器和 GitHub OAuth 配置 |
| [Teams 清单](teams/README.md) | Teams 应用打包和侧载 |
| [数据库迁移](infra/database/README.md) | SQL 迁移详细信息 |
---
## 💡 灵感
该项目是原始 [Cerebro](https://github.com/asudbring/cerebro) 的 Azure 原生适配版,灵感来自 [Open Brain (OB1)](https://github.com/NateBJones/OB1) 项目,由 Nate B. Jones 创建。
---
## 📄 许可证
MIT
连接信息
猜你喜欢
everything-claude-code
完整的 Claude Code 配置集合 - agents、skills、hooks、commands、rules、MCPs。来自 Anthropic...
MarkItDown
将文件和办公文档转换为Markdown的Python工具。
awesome-claude-skills
一份精心整理的 Claude Skills、资源和工具列表,用于定制 Claude AI 工作流程
agentic-awesome-skills
适用于 Claude Code、Cursor、Codex CLI、Autohand Code、Gemini CLI、Antigravity 等的...
antigravity-awesome-skills
Claude Code/Antigravity/Cursor 的 130 多个 Agentic Skills 终极合集。 经过实战检验、高性能的 AI...
context-mode
MCP 是用于工具访问的协议。我们是上下文的虚拟化层。