# 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