mirror of
https://github.com/memohai/Memoh.git
synced 2026-04-27 07:16:19 +09:00
Acbox
222 lines
5.8 KiB
Markdown
222 lines
5.8 KiB
Markdown
# MemoHome CLI 架构说明
|
|
|
|
## 项目重构概述
|
|
|
|
本项目已重构为两个清晰分离的层次：
|
|
|
|
1. **Core 层** (`src/core/`): 纯粹的功能函数，不依赖任何 CLI UI 库
|
|
2. **CLI 层** (`src/cli/`): 命令行交互界面，负责用户输入输出
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
src/
|
|
├── core/ # 核心功能层（可被其他项目使用）
|
|
│ ├── index.ts # 统一导出所有核心功能
|
|
│ ├── auth.ts # 认证相关功能
|
|
│ ├── user.ts # 用户管理功能
|
|
│ ├── model.ts # 模型配置功能
|
|
│ ├── agent.ts # AI 对话功能
|
|
│ ├── memory.ts # 记忆管理功能
|
|
│ ├── schedule.ts # 定时任务功能
|
|
│ ├── settings.ts # 设置管理功能
|
|
│ ├── debug.ts # 调试工具
|
|
│ ├── config.ts # 配置管理
|
|
│ └── client.ts # API 客户端
|
|
├── cli/ # CLI 交互层
|
|
│ ├── index.ts # CLI 入口
|
|
│ └── commands/ # 命令定义
|
|
│ ├── auth.ts
|
|
│ ├── user.ts
|
|
│ ├── model.ts
|
|
│ ├── agent.ts
|
|
│ ├── memory.ts
|
|
│ ├── schedule.ts
|
|
│ ├── config.ts
|
|
│ └── debug.ts
|
|
├── types/ # 类型定义
|
|
│ └── index.ts
|
|
├── utils/ # 工具函数
|
|
│ └── index.ts
|
|
└── index.ts # 主导出文件
|
|
```
|
|
|
|
## Core 层特点
|
|
|
|
Core 层提供纯粹的功能函数，特点：
|
|
|
|
- ✅ **无 UI 依赖**: 不使用 chalk, ora, inquirer 等 CLI UI 库
|
|
- ✅ **类型安全**: 提供完整的 TypeScript 类型定义
|
|
- ✅ **错误处理**: 通过 throw Error 返回错误，调用者可自行处理
|
|
- ✅ **可复用**: 可被 CLI 或其他项目（如 Web 应用）导入使用
|
|
- ✅ **单一职责**: 每个模块只负责特定功能域
|
|
|
|
### Core 层 API 示例
|
|
|
|
```typescript
|
|
// Auth
|
|
import { login, logout, getCurrentUser } from '@memohome/cli/core'
|
|
|
|
await login({ username: 'admin', password: 'password' })
|
|
const user = await getCurrentUser()
|
|
logout()
|
|
|
|
// Agent
|
|
import { chat, chatStream } from '@memohome/cli/core'
|
|
|
|
// 非流式对话
|
|
const response = await chat({
|
|
message: 'Hello',
|
|
language: 'Chinese'
|
|
})
|
|
|
|
// 流式对话
|
|
await chatStream({ message: 'Hello' }, async (event) => {
|
|
if (event.type === 'text-delta') {
|
|
console.log(event.text)
|
|
}
|
|
})
|
|
|
|
// Model
|
|
import { listModels, createModel } from '@memohome/cli/core'
|
|
|
|
const models = await listModels()
|
|
const newModel = await createModel({
|
|
name: 'GPT-4',
|
|
modelId: 'gpt-4',
|
|
baseUrl: 'https://api.openai.com/v1',
|
|
apiKey: 'sk-xxx',
|
|
clientType: 'openai',
|
|
type: 'chat'
|
|
})
|
|
|
|
// Memory
|
|
import { searchMemory, addMemory, getMessages } from '@memohome/cli/core'
|
|
|
|
const memories = await searchMemory({ query: 'test', limit: 10 })
|
|
await addMemory({ content: 'Important note' })
|
|
const messages = await getMessages({ page: 1, limit: 20 })
|
|
```
|
|
|
|
## CLI 层特点
|
|
|
|
CLI 层负责用户交互，特点：
|
|
|
|
- ✅ **命令定义**: 使用 commander.js 定义命令
|
|
- ✅ **美化输出**: 使用 chalk 颜色、ora 加载动画
|
|
- ✅ **交互输入**: 使用 inquirer 提示用户输入
|
|
- ✅ **错误显示**: 友好的错误信息展示
|
|
- ✅ **调用 Core**: 所有业务逻辑调用 Core 层函数
|
|
|
|
## 使用方式
|
|
|
|
### 1. 作为 CLI 使用
|
|
|
|
```bash
|
|
# 安装
|
|
pnpm install
|
|
|
|
# 运行命令
|
|
memohome auth login
|
|
memohome agent chat "Hello"
|
|
memohome model list
|
|
```
|
|
|
|
### 2. 作为库使用
|
|
|
|
在其他项目中导入：
|
|
|
|
```typescript
|
|
// 导入所有功能
|
|
import * as memohome from '@memohome/cli'
|
|
|
|
// 或导入特定模块
|
|
import { login, chat, listModels } from '@memohome/cli'
|
|
import * as auth from '@memohome/cli/core'
|
|
import type { User, Model } from '@memohome/cli/types'
|
|
|
|
// 使用
|
|
await memohome.login({ username: 'admin', password: 'password' })
|
|
const response = await memohome.chat({ message: 'Hello' })
|
|
const models = await memohome.listModels()
|
|
```
|
|
|
|
## 包导出
|
|
|
|
`package.json` 中的导出配置：
|
|
|
|
```json
|
|
{
|
|
"exports": {
|
|
".": "./src/index.ts", // 主入口，导出所有 core 功能
|
|
"./core": "./src/core/index.ts", // Core 层
|
|
"./types": "./src/types/index.ts", // 类型定义
|
|
"./utils": "./src/utils/index.ts" // 工具函数
|
|
},
|
|
"bin": {
|
|
"memohome": "./src/cli/index.ts" // CLI 入口
|
|
}
|
|
}
|
|
```
|
|
|
|
## 设计原则
|
|
|
|
1. **关注点分离**: CLI UI 和业务逻辑完全分离
|
|
2. **可测试性**: Core 层可以独立测试，无需模拟 CLI 环境
|
|
3. **可复用性**: Core 层可在不同环境使用（CLI、Web、Desktop 等）
|
|
4. **类型安全**: 完整的 TypeScript 类型定义
|
|
5. **错误处理**: 统一的错误处理机制
|
|
|
|
## 迁移指南
|
|
|
|
如果你之前使用旧版本的代码，迁移方式：
|
|
|
|
### 旧代码（CLI 层调用）
|
|
```typescript
|
|
// 这些只能在 CLI 中使用，有 UI 输出
|
|
```
|
|
|
|
### 新代码（Core 层调用）
|
|
```typescript
|
|
// 可以在任何地方使用，无 UI 依赖
|
|
import { login, chat } from '@memohome/cli'
|
|
|
|
try {
|
|
await login({ username: 'admin', password: 'password' })
|
|
const response = await chat({ message: 'Hello' })
|
|
console.log(response)
|
|
} catch (error) {
|
|
console.error('Error:', error.message)
|
|
}
|
|
```
|
|
|
|
## 开发指南
|
|
|
|
### 添加新功能
|
|
|
|
1. 在 `src/core/` 中添加新的核心功能模块
|
|
2. 在 `src/core/index.ts` 中导出
|
|
3. 在 `src/cli/commands/` 中添加对应的 CLI 命令
|
|
4. 在 `src/cli/index.ts` 中注册命令
|
|
|
|
### 测试
|
|
|
|
Core 层可以直接测试：
|
|
|
|
```typescript
|
|
import { login, chat } from '../src/core'
|
|
|
|
test('login should work', async () => {
|
|
const result = await login({ username: 'test', password: 'test' })
|
|
expect(result.success).toBe(true)
|
|
})
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
- Core 层函数通过 `throw Error` 返回错误，调用者需要处理
|
|
- CLI 层负责美化错误信息和用户反馈
|
|
- 配置文件位于 `~/.memohome/config.json`
|
|
- API 客户端使用 Eden Treaty
|
|
|