PNArchives/Memoh
1
0
Fork 0
mirror of https://github.com/memohai/Memoh.git synced 2026-04-25 07:00:48 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs: update readme

Browse Source
This commit is contained in:
Acbox
2026-01-12 16:29:55 +08:00
parent 93cb54fbe7
commit 88f0f14700
6 changed files with 32 additions and 736 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+30 -2
View File
@@ -9,11 +9,16 @@ Memohome是一个专属于你的AI私人管家，你可以把它跑在你的NAS
- [x] 长记忆：Memohome拥有长记忆能力，可以为你的家庭成员提供个性化的服务。他会存储最近一段时间（默认最近15个小时）的上下文，超出时间后则会根据你的需求按需加载记忆
- [x] 定时任务：Memohome可以帮你创建智能的定时任务，比如：每天早上七点生成一个早餐菜谱，通过Telegram发送给我
- [ ] 聊天软件支持：Memohome可以支持多种聊天软件，比如：Telegram，微信，QQ等常用社交软件，通过直接发送消息与Memohome进行交互，同时Memohome也可以通过事件触发，选择工具主动给你发送消息
- [x] 聊天软件支持：Memohome可以支持多种聊天软件，比如：Telegram，微信，QQ等常用社交软件，通过直接发送消息与Memohome进行交互，同时Memohome也可以通过事件触发，选择工具主动给你发送消息
- [ ] 文件系统管理：Memohome可以帮你管理你的文件系统，比如：文件搜索，图片分类，文件分享等。他可以创建文件，也可以通过聊天软件发送文件给你；你也可以通过发送文件给他帮你处理。
- [ ] MCP支持：Memohome可以支持多种MCP接口，与多种外部工具进行交互。
- More...
## Message Platforms
- [x] Telegram ([Telegram配置](#telegram-bot))
- [ ] Wechat
- [ ] Lark
## Quick Start
环境：
@@ -94,4 +99,27 @@ pnpm cli config set --chat-model <uuid> --summary-model <uuid> --embedding-model
```bash
pnpm cli config set --max-context-time <minutes>
```
- `--max-context-time`: 最大上下文加载时间，单位为分钟
- `--max-context-time`: 最大上下文加载时间，单位为分钟
## Telegram Bot
你需要获取你的Telegram Bot Token， 然后启动Telegram Service：
```bash
pnpm telegram:start
```
Telegram Service将在 `http://localhost:7101` 启动，这个是endpoint，你需要在Memohome中配置你的Telegram Bot Token：
使用Memohome Cli:
```bash
pnpm cli platform create
```
根据提示配置platform
- name: telegram
- endpoint: http://localhost:7101
- config: { "botToken": "<your-telegram-bot-token>" }
然后你就可以通过Telegram Bot与Memohome进行交互了。
REFACTORING_SUMMARY.md
-418
View File
@@ -1,418 +0,0 @@
# 重构总结文档
## 概述
本次重构将 MemoHome CLI 项目分离成了清晰的两个层次，并实现了 Telegram Bot 的多用户登录鉴权系统。
## 重构目标
1. ✅ **分离关注点**: CLI UI 层和核心业务逻辑完全分离
2. ✅ **可复用性**: Core 层可被任何平台使用（CLI、Telegram、Web 等）
3. ✅ **多存储后端**: 支持不同的存储方式（文件、Redis 等）
4. ✅ **多用户支持**: Telegram bot 支持多个 TG 账号绑定多个 MemoHome 账号
## 架构变化
### 之前 (单体架构)
```
packages/cli/
├── src/
│ ├── client.ts # 混合了 API 调用和配置管理
│ ├── config.ts # 硬编码文件存储
│ ├── utils.ts
│ ├── types.ts
│ └── commands/ # CLI 命令直接调用 API
│ ├── auth.ts
│ ├── user.ts
│ └── ...
```
**问题**:
- CLI 和业务逻辑耦合
- 配置硬编码为文件存储
- 无法在其他平台复用
- 单用户设计
### 之后 (分层架构)
```
packages/cli/
├── src/
│ ├── core/ # 核心业务逻辑（可复用）
│ │ ├── context.ts # 上下文管理
│ │ ├── storage.ts # 存储接口定义
│ │ ├── storage/
│ │ │ ├── file.ts # 文件存储实现
│ │ │ └── index.ts
│ │ ├── client.ts # API 客户端（支持多种存储）
│ │ ├── auth.ts # 认证逻辑
│ │ ├── user.ts # 用户管理
│ │ ├── agent.ts # AI 对话
│ │ └── ...
│ ├── cli/ # CLI UI 层
│ │ ├── index.ts # CLI 入口
│ │ └── commands/ # 命令定义（使用 core）
│ │ ├── auth.ts
│ │ ├── user.ts
│ │ └── ...
│ ├── types/ # 类型定义
│ └── utils/ # 工具函数
packages/platform-telegram/ # Telegram 平台
├── src/
│ ├── storage.ts # Redis 存储实现
│ ├── auth.ts # Telegram 认证处理
│ ├── index.ts # Bot 实现（使用 cli/core）
│ └── bot.ts # 独立启动入口
```
## 核心改进
### 1. 存储抽象层
**接口定义** (`cli/src/core/storage.ts`):
```typescript
export interface TokenStorage {
getApiUrl(): Promise<string> | string
setApiUrl(url: string): Promise<void> | void
getToken(userId?: string): Promise<string | null> | string | null
setToken(token: string, userId?: string): Promise<void> | void
clearToken(userId?: string): Promise<void> | void
}
```
**实现**:
1. **FileTokenStorage** (CLI 用)
- 存储位置: `~/.memohome/config.json`
- 单用户
- 同步操作
2. **TelegramRedisStorage** (Telegram Bot 用)
- 存储位置: Redis
- 多用户: `memohome:tg:token:{telegram_user_id}`
- 异步操作
- 30 天过期
### 2. 上下文管理
**MemoHomeContext** (`cli/src/core/context.ts`):
```typescript
export interface MemoHomeContext {
storage: TokenStorage // 存储后端
currentUserId?: string // 当前用户 ID（用于多用户场景）
}
```
**使用方式**:
```typescript
// CLI 场景（单用户，文件存储）
import { setContext, FileTokenStorage } from '@memohome/cli/core'
setContext({
storage: new FileTokenStorage()
})
// Telegram 场景（多用户，Redis 存储）
import { createContext } from '@memohome/cli/core'
import { TelegramRedisStorage } from '@memohome/platform-telegram'
const storage = new TelegramRedisStorage()
const context = createContext({
storage,
userId: telegramUserId // 不同的 TG 用户
})
```
### 3. 同步/异步 API 支持
为了同时支持同步存储（文件）和异步存储（Redis），提供了两套 API：
```typescript
// 同步版本（CLI 用）
export function login(params: LoginParams, context?: MemoHomeContext)
export function isLoggedIn(context?: MemoHomeContext): boolean
export function getToken(context?: MemoHomeContext): string | null
// 异步版本（Telegram Bot 用）
export async function loginAsync(params: LoginParams, context?: MemoHomeContext)
export async function isLoggedInAsync(context?: MemoHomeContext): Promise<boolean>
export async function getTokenAsync(context?: MemoHomeContext): Promise<string | null>
```
### 4. Telegram Bot 多用户架构
**存储结构**:
```
Redis:
memohome:tg:token:123456 -> "token_abc..." (Telegram User 123456)
memohome:tg:user:123456 -> { username, role }
memohome:tg:token:789012 -> "token_def..." (Telegram User 789012)
memohome:tg:user:789012 -> { username, role }
```
**工作流程**:
1. 用户 A (TG ID: 123456) 发送: `/login userA passwordA`
2. Bot 验证 -> 获取 token -> 存储到 Redis: `token:123456`
3. 用户 B (TG ID: 789012) 发送: `/login userB passwordB`
4. Bot 验证 -> 获取 token -> 存储到 Redis: `token:789012`
5. 两个用户独立聊天，使用各自的 token
**鉴权中间件**:
```typescript
bot.command('chat', requireAuth(storage), async (ctx) => {
// 自动检查用户是否已登录
// 获取该用户的 token
// 执行命令
})
```
## 使用示例
### CLI 使用（不变）
```bash
# CLI 仍然使用文件存储
memohome auth login -u admin -p password
memohome agent chat "Hello"
```
### 作为库使用
```typescript
import { login, chat } from '@memohome/cli'
// 默认使用文件存储
await login({ username: 'admin', password: 'password' })
const response = await chat({ message: 'Hello' })
```
### Telegram Bot 使用
```bash
# 配置环境变量
export BOT_TOKEN="your_bot_token"
export REDIS_URL="redis://localhost:6379"
export API_BASE_URL="http://localhost:7002"
# 启动 bot
cd packages/platform-telegram
pnpm start
```
**用户操作**:
```
User A: /login adminA passwordA
Bot: ✅ Login successful! Username: adminA
User B: /login userB passwordB
Bot: ✅ Login successful! Username: userB
User A: 今天天气怎么样？
Bot: 🤖 今天天气...
User B: 讲个笑话
Bot: 🤖 好的，听好了...
```
### 在其他项目中使用 Core
```typescript
import {
createContext,
loginAsync,
chatStreamAsync
} from '@memohome/cli/core'
import { TelegramRedisStorage } from '@memohome/platform-telegram'
// 创建自定义存储
const storage = new TelegramRedisStorage({
redisUrl: 'redis://localhost:6379'
})
// 为用户创建上下文
const userContext = createContext({
storage,
userId: 'user_12345'
})
// 登录
await loginAsync({
username: 'user',
password: 'pass'
}, userContext)
// 聊天
await chatStreamAsync({
message: 'Hello'
}, async (event) => {
if (event.type === 'text-delta') {
console.log(event.text)
}
}, userContext)
```
## 关键文件清单
### CLI 包
| 文件 | 作用 |
|------|------|
| `src/core/storage.ts` | 存储接口定义 |
| `src/core/storage/file.ts` | 文件存储实现（CLI 用） |
| `src/core/context.ts` | 上下文管理 |
| `src/core/client.ts` | API 客户端（支持上下文） |
| `src/core/auth.ts` | 认证逻辑（同步/异步版本） |
| `src/core/agent.ts` | AI 对话（同步/异步版本） |
| `src/core/index.ts` | 统一导出 |
| `src/cli/commands/*` | CLI 命令（使用 core） |
### Telegram 平台包
| 文件 | 作用 |
|------|------|
| `src/storage.ts` | Redis 存储实现 |
| `src/auth.ts` | Telegram 认证处理器 |
| `src/index.ts` | Bot 主逻辑 |
| `src/bot.ts` | 独立启动入口 |
| `README.md` | 使用文档 |
| `SETUP.md` | 设置指南 |
## 迁移指南
如果你有旧代码需要迁移：
### 旧代码
```typescript
import { createClient, getToken } from './client'
import { loadConfig } from './config'
const client = createClient()
const token = getToken()
```
### 新代码
```typescript
// 方式 1: 使用默认上下文（CLI 场景）
import { createClient, getToken } from '@memohome/cli/core'
const client = createClient()
const token = getToken()
// 方式 2: 使用自定义上下文（多用户场景）
import { createContext, createClientAsync, getTokenAsync } from '@memohome/cli/core'
import { TelegramRedisStorage } from '@memohome/platform-telegram'
const storage = new TelegramRedisStorage()
const context = createContext({ storage, userId: 'user123' })
const client = await createClientAsync(context)
const token = await getTokenAsync(context)
```
## 测试
### CLI 测试
```bash
cd packages/cli
pnpm start auth login -u admin -p password
pnpm start agent chat "Hello"
```
### Telegram Bot 测试
1. 启动 Redis: `redis-server`
2. 启动 API: `cd packages/api && pnpm start`
3. 启动 Bot: `cd packages/platform-telegram && pnpm start`
4. 在 Telegram 中测试:
- `/start`
- `/login admin password`
- `/chat 你好`
## 优势总结
### 1. 关注点分离
- ✅ Core 层: 纯业务逻辑，无 UI 依赖
- ✅ CLI 层: 只负责用户交互
- ✅ Platform 层: 平台特定实现
### 2. 可扩展性
- ✅ 轻松添加新的存储后端
- ✅ 轻松添加新的平台（Web、Desktop、Discord 等）
- ✅ 轻松添加新功能到 core
### 3. 可测试性
- ✅ Core 层可独立测试，无需模拟 UI
- ✅ Storage 可以 mock
- ✅ Context 可以独立创建
### 4. 多用户支持
- ✅ Telegram bot 支持多个用户同时使用
- ✅ 每个用户独立的 session
- ✅ Token 自动管理和过期
### 5. 类型安全
- ✅ 完整的 TypeScript 类型定义
- ✅ 导出所有类型供外部使用
## 未来扩展
基于这个架构，可以轻松添加：
1. **Discord Bot**
```typescript
// packages/platform-discord
import { createContext, loginAsync } from '@memohome/cli/core'
import { DiscordRedisStorage } from './storage'
const storage = new DiscordRedisStorage()
// 类似 Telegram 实现
```
2. **Web 应用**
```typescript
// packages/web
import { createContext, loginAsync, chatStreamAsync } from '@memohome/cli/core'
import { BrowserStorage } from './storage'
const storage = new BrowserStorage() // localStorage
// 在 React/Vue 中使用
```
3. **移动应用**
```typescript
// packages/mobile
import { createContext } from '@memohome/cli/core'
import { SecureStorage } from './storage'
const storage = new SecureStorage() // React Native AsyncStorage
```
## 总结
本次重构实现了：
1. ✅ **完全分离** CLI 和 Core 层
2. ✅ **抽象存储** 支持多种后端
3. ✅ **多用户支持** Telegram bot 可服务多个用户
4. ✅ **同步/异步** API 适配不同场景
5. ✅ **可扩展** 易于添加新平台和功能
6. ✅ **文档完善** README、SETUP、示例齐全
现在你可以：
- 继续使用 CLI（体验不变）
- 启动 Telegram bot 服务多个用户
- 在其他项目中复用 Core 功能
- 轻松添加新的平台支持
TELEGRAM_BOT_COMPLETE.md
-313
View File
@@ -1,313 +0,0 @@
# ✅ Telegram Bot 完成总结
## 🎉 完成的功能
### 1. Core 层重构 ✅
**位置**: `packages/cli/src/core/`
- ✅ **存储抽象层** (`storage.ts`): 定义 `TokenStorage` 接口
- ✅ **文件存储** (`storage/file.ts`): CLI 使用的文件存储
- ✅ **上下文管理** (`context.ts`): 支持多用户场景
- ✅ **客户端** (`client.ts`): 同步/异步 API 支持
- ✅ **认证** (`auth.ts`): 同步/异步登录、登出
- ✅ **AI 对话** (`agent.ts`): 同步/异步流式对话
### 2. Telegram Bot 实现 ✅
**位置**: `packages/platform-telegram/`
- ✅ **Redis 存储** (`src/storage.ts`): 多用户 token 管理
- ✅ **认证处理** (`src/auth.ts`): 登录、登出、鉴权中间件
- ✅ **Bot 实现** (`src/index.ts`): 完整的 Telegram bot
- ✅ **独立启动** (`src/bot.ts`): 可独立运行
### 3. 多用户支持 ✅
```
Telegram User A (ID: 123456) → Token A → MemoHome User A
Telegram User B (ID: 789012) → Token B → MemoHome User B
```
- ✅ 每个 TG 用户独立登录
- ✅ 独立的 session 管理
- ✅ Token 自动过期（30天）
- ✅ 用户信息缓存
## 📁 项目结构
```
packages/
├── cli/ # CLI 和 Core 层
│ └── src/
│ ├── core/ # 核心功能（可复用）
│ │ ├── storage.ts # 存储接口
│ │ ├── storage/
│ │ │ ├── file.ts # 文件存储
│ │ │ └── index.ts
│ │ ├── context.ts # 上下文管理
│ │ ├── client.ts # API 客户端
│ │ ├── auth.ts # 认证逻辑
│ │ ├── agent.ts # AI 对话
│ │ └── index.ts # 统一导出
│ └── cli/ # CLI UI 层
│ └── commands/
│
└── platform-telegram/ # Telegram Bot
├── src/
│ ├── storage.ts # Redis 存储
│ ├── auth.ts # TG 认证处理
│ ├── index.ts # Bot 主逻辑
│ └── bot.ts # 启动入口
├── .env.example # 环境变量示例
├── README.md # 完整文档
├── SETUP.md # 设置指南
└── QUICKSTART.md # 快速开始
```
## 🚀 快速开始
### 1. 配置环境
```bash
cd packages/platform-telegram
cp .env.example .env
```
编辑 `.env`:
```env
BOT_TOKEN=你的_bot_token
REDIS_URL=redis://localhost:6379
API_BASE_URL=http://localhost:7002
```
### 2. 启动服务
```bash
# Terminal 1: Redis
redis-server
# Terminal 2: MemoHome API
cd packages/api
pnpm start
# Terminal 3: Telegram Bot
cd packages/platform-telegram
pnpm start
```
### 3. 测试 Bot
在 Telegram 中：
```
/start
/login admin password
/chat 你好
```
## 🎯 核心特性
### 存储抽象
```typescript
// 接口定义
interface TokenStorage {
getToken(userId?: string): Promise<string | null> | string | null
setToken(token: string, userId?: string): Promise<void> | void
clearToken(userId?: string): Promise<void> | void
// ...
}
// CLI 使用文件存储
const fileStorage = new FileTokenStorage()
// Telegram 使用 Redis 存储
const redisStorage = new TelegramRedisStorage()
```
### 多用户上下文
```typescript
// 为不同用户创建独立上下文
const userAContext = createContext({
storage: redisStorage,
userId: 'telegram_123456' // User A
})
const userBContext = createContext({
storage: redisStorage,
userId: 'telegram_789012' // User B
})
// 使用各自的上下文
await loginAsync({ username: 'userA', password: 'passA' }, userAContext)
await loginAsync({ username: 'userB', password: 'passB' }, userBContext)
```
### 鉴权中间件
```typescript
// 自动检查用户是否登录
bot.command('chat', requireAuth(storage), async (ctx) => {
// 只有登录用户才能执行
})
```
### 流式对话
```typescript
await chatStreamAsync({
message: '讲个故事',
language: 'Chinese'
}, async (event) => {
if (event.type === 'text-delta') {
// 实时更新 Telegram 消息
}
}, userContext)
```
## 📊 Redis 存储结构
```
memohome:tg:token:123456 → "token_abc..." (30天过期)
memohome:tg:user:123456 → {
"username": "userA",
"role": "admin",
"userId": "user-id-xxx"
}
memohome:tg:token:789012 → "token_def..."
memohome:tg:user:789012 → {
"username": "userB",
"role": "user",
"userId": "user-id-yyy"
}
```
## 🔧 Bot 命令
| 命令 | 描述 | 需要登录 |
|------|------|---------|
| `/start` | 欢迎消息 | ❌ |
| `/help` | 帮助信息 | ❌ |
| `/login <username> <password>` | 登录 | ❌ |
| `/logout` | 登出 | ✅ |
| `/whoami` | 查看当前用户 | ✅ |
| `/chat <message>` | AI 对话 | ✅ |
| 直接发送消息 | AI 对话 | ✅ |
## 🎨 使用示例
### CLI 使用（不受影响）
```bash
memohome auth login -u admin -p password
memohome agent chat "Hello"
```
### Telegram Bot 使用
```
User A: /login adminA passwordA
Bot: ✅ Login successful! Username: adminA
User A: 今天天气怎么样？
Bot: 🤖 今天天气...
User B: /login userB passwordB
Bot: ✅ Login successful! Username: userB
User B: 讲个笑话
Bot: 🤖 好的，听好了...
```
### 编程使用
```typescript
import { createContext, loginAsync, chatStreamAsync } from '@memohome/cli'
import { TelegramRedisStorage } from '@memohome/platform-telegram'
const storage = new TelegramRedisStorage()
const context = createContext({
storage,
userId: 'telegram_123456'
})
// 登录
await loginAsync({
username: 'user',
password: 'pass'
}, context)
// 对话
await chatStreamAsync({
message: 'Hello'
}, async (event) => {
console.log(event)
}, context)
```
## 📚 文档
- 📖 [README.md](packages/platform-telegram/README.md) - 完整功能文档
- 🚀 [QUICKSTART.md](packages/platform-telegram/QUICKSTART.md) - 5分钟快速开始
- 🛠 [SETUP.md](packages/platform-telegram/SETUP.md) - 详细设置指南
- 🏗 [REFACTORING_SUMMARY.md](REFACTORING_SUMMARY.md) - 重构总结
- 📐 [ARCHITECTURE.md](packages/cli/ARCHITECTURE.md) - CLI 架构说明
## ✨ 亮点
1. **完全分离**: CLI UI 和业务逻辑完全解耦
2. **可复用**: Core 层可被任何平台使用
3. **多存储**: 支持文件、Redis 等多种存储
4. **多用户**: Telegram bot 支持多用户独立 session
5. **类型安全**: 完整的 TypeScript 类型
6. **文档完善**: README、SETUP、示例齐全
7. **易扩展**: 轻松添加新平台（Discord、Web 等）
## 🔮 未来扩展
基于这个架构，可以轻松添加：
- 🎮 Discord Bot
- 🌐 Web 应用
- 📱 移动应用
- 💬 微信 Bot
- 🤖 其他平台...
只需实现对应的 `TokenStorage` 和平台逻辑即可！
## ✅ 测试清单
- [x] CLI 登录/登出功能正常
- [x] CLI 对话功能正常
- [x] Telegram bot 启动成功
- [x] Telegram 多用户登录
- [x] Telegram 独立 session
- [x] Telegram 流式对话
- [x] Redis 存储正常
- [x] Token 过期管理
- [x] 鉴权中间件工作
- [x] 错误处理完善
- [x] 类型检查通过
- [x] 文档完整
## 🎊 总结
重构完成！现在你拥有：
1. ✅ **清晰的架构**: Core 层可复用，CLI 和 Platform 独立
2. ✅ **多用户支持**: Telegram bot 支持多个用户同时使用
3. ✅ **灵活的存储**: 文件存储（CLI）和 Redis 存储（Telegram）
4. ✅ **完善的文档**: 从快速开始到详细设置一应俱全
5. ✅ **易于扩展**: 添加新平台只需实现存储接口
现在可以：
- 继续使用 CLI（体验不变）
- 启动 Telegram bot 服务多个用户
- 在其他项目中复用 Core 功能
- 轻松添加新的平台支持
祝使用愉快！🚀
package.json
+1
View File
@@ -16,6 +16,7 @@
"db:migrate": "pnpm --filter @memohome/db migrate",
"db:generate": "pnpm --filter @memohome/db generate",
"db:studio": "pnpm --filter @memohome/db studio",
"telegram:start": "pnpm --filter @memohome/platform-telegram start",
"cli": "pnpm --filter @memohome/client start",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
packages/api/memory.db
BIN
View File
Binary file not shown.
packages/platform-telegram/src/bot.ts
+1 -3
View File
@@ -25,9 +25,7 @@ async function main() {
const platform = new TelegramPlatform()
try {
platform.serve({
botToken,
})
platform.serve()
console.log('✅ Bot is running...')
console.log('Press Ctrl+C to stop')