# Maian SDK v1.0.0 快速入门

## 简介
Maian SDK 是 Maian AI 的官方开发工具包，允许开发者集成 Maian 的推理能力到自己的应用中。

## 安装

```bash
npm install @maian/core
# 或
yarn add @maian/core
```

## 基本使用

### 初始化
```javascript
import MaianAgent from '@maian/core';

const agent = new MaianAgent({
  agentId: 'my-app',
  dataDir: './data',
  ollamaUrl: 'http://127.0.0.1:11434',
  logs: true
});

await agent.init();
```

### 发送消息
```javascript
const response = await agent.chat('你好，请介绍一下自己');
console.log(response.reply);
```

### 使用技能
```javascript
// 列出可用技能
const skills = await agent.listSkills();
console.log(skills);

// 调用技能
const result = await agent.invokeSkill('weather', { city: '北京' });
console.log(result);
```

## API 参考

### MaianAgent 类

#### constructor(options)
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| agentId | string | ✅ | Agent 唯一标识 |
| dataDir | string | ❌ | 数据目录（默认 `./data`） |
| ollamaUrl | string | ❌ | Ollama 地址（默认 `http://127.0.0.1:11434`） |
| ffcosmosUrl | string | ❌ | FFCosmos 云端地址 |
| ffcosmosKey | string | ❌ | FFCosmos API Key |
| logs | boolean | ❌ | 是否输出日志（默认 false） |

#### methods
| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `init()` | - | Promise<void> | 初始化 Agent |
| `chat(message)` | string | Promise<{reply: string}> | 发送对话消息 |
| `listSkills()` | - | Promise<Skill[]> | 列出所有技能 |
| `invokeSkill(id, params)` | string, object | Promise<any> | 调用指定技能 |
| `getMemory(query)` | string | Promise<Memory[]> | 检索记忆 |
| `storeMemory(content, tags)` | string, string[] | Promise<void> | 存储记忆 |

## 技能开发

### 创建技能
```javascript
// my-skill/script.js
export default {
  name: 'my-skill',
  description: '我的自定义技能',
  async run(params) {
    // 技能逻辑
    return { result: 'done' };
  }
};
```

### 注册技能
```javascript
await agent.registerSkill('./my-skill');
```

## 高级配置

### 自定义推理引擎
```javascript
agent.setInferenceEngine({
  type: 'ollama', // 或 'cloud'
  model: 'qwen2.5:3b',
  timeout: 15000
});
```

### 记忆管理
```javascript
// 存储重要信息
await agent.storeMemory('用户喜欢使用简洁回复', ['preference', 'user:123']);

// 检索相关记忆
const memories = await agent.getMemory('用户偏好');
```

## 示例项目
- [Maian-X 桌面端](https://github.com/maian-ai/maian-x)
- [Maian Hub](https://maianai.com/api/hub/)
- [SDK 示例代码](https://github.com/maian-ai/sdk-examples)