qwai-tech_obsidian-plugin-intelligence-assistant/docs/reference/api.md

API 文档

本文档描述了新架构的核心 API 接口和使用方法。

📚 目录

• 核心 API
• 领域实体
• 应用服务
• 基础设施
• UI 组件
• LLM 提供商

🔧 核心 API

Result

统一的错误处理模式，避免异常传播。

import { Result } from '../src/core';

// 创建成功结果
const success = Result.success('operation completed');

// 创建失败结果
const failure = Result.failure('operation failed', 'ERROR_CODE');

// 检查结果
if (result.isSuccess) {
  console.log(result.value); // 成功值
} else {
  console.error(result.error, result.code); // 错误信息
}

方法

• Result.success<T>(value: T): Result<T> - 创建成功结果
• Result.failure(error: string, code?: string): Result<never> - 创建失败结果
• Result.fromPromise<T>(promise: Promise<T>): Promise<Result<T>> - 包装 Promise
• Result.combine<T>(results: Result<T>[]): Result<T[]> - 组合多个结果
• result.map<U>(fn: (value: T) => U): Result<U> - 映射成功值
• result.flatMap<U>(fn: (value: T) => Result<U>): Result<U> - 平面映射
• result.getOrElse(defaultValue: T): T - 获取值或默认值

IService

服务生命周期接口。

interface IService {
  readonly name: string;
  readonly version: string;
  readonly isInitialized: boolean;
  
  initialize(context: any): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
  cleanup(): Promise<void>;
  getStatus(): Promise<{
    status: 'healthy' | 'degraded' | 'error';
    details?: any;
  }>;
}

IRepository

通用仓储接口。

interface IRepository<T> {
  save(entity: T): Promise<Result<T>>;
  findById(id: string): Promise<Result<T | undefined>>;
  findAll(options?: QueryOptions): Promise<Result<T[]>>;
  update(id: string, updates: Partial<T>): Promise<Result<T>>;
  delete(id: string): Promise<Result<boolean>>;
  count(filter?: any): Promise<Result<number>>;
}

🏗️ 领域实体

Message

消息实体模型。

import { Message, MessageFactory } from '../src/domain/chat/entities';

// 创建用户消息
const userMessage = MessageFactory.createUser({
  conversationId: 'conv-123',
  content: 'Hello, world!',
  author: 'User'
});

// 创建 AI 消息
const aiMessage = MessageFactory.createAI({
  conversationId: 'conv-123',
  content: 'Hello! How can I help you?',
  author: 'Assistant',
  model: 'gpt-4',
  usage: {
    promptTokens: 10,
    completionTokens: 15,
    totalTokens: 25
  }
});

// 添加反应
aiMessage.addReaction('👍', 'user-id');
aiMessage.addReaction('❤️', 'user-id-2');

// 添加书签
aiMessage.addBookmark('Important response');

// 转换为存储格式
const storageData = aiMessage.toStorage();

属性

• id: string - 消息唯一标识
• conversationId: string - 所属对话 ID
• content: string - 消息内容
• role: 'user' | 'assistant' | 'system' - 消息角色
• author: string - 作者名称
• timestamp: number - 创建时间戳
• status: MessageStatus - 消息状态
• attachments: MessageAttachment[] - 附件列表
• reactions: Map<string, string[]> - 反应映射
• bookmarks: string[] - 书签列表
• metadata: Record<string, any> - 元数据

方法

• updateContent(content: string): void - 更新内容
• addAttachment(attachment: MessageAttachment): void - 添加附件
• removeAttachment(id: string): void - 移除附件
• addReaction(emoji: string, userId: string): void - 添加反应
• removeReaction(emoji: string, userId: string): void - 移除反应
• addBookmark(reason?: string): void - 添加书签
• removeBookmark(): void - 移除书签
• toStorage(): any - 转换为存储格式
• validate(): ValidationResult - 验证数据

Conversation

对话实体模型。

import { Conversation, ConversationFactory } from '../src/domain/chat/entities';

// 创建对话
const conversation = ConversationFactory.create({
  title: 'My Chat',
  agentId: 'agent-123',
  systemPrompt: 'You are a helpful assistant.'
});

// 更新设置
conversation.updateSettings({
  model: 'gpt-4',
  temperature: 0.7,
  maxTokens: 2000
});

// 更新统计
conversation.updateStats({
  messageCount: 10,
  lastActivity: Date.now()
});

// 转换为存储格式
const storageData = conversation.toStorage();

属性

• id: string - 对话唯一标识
• title: string - 对话标题
• agentId: string - 关联的代理 ID
• systemPrompt: string - 系统提示词
• createdAt: number - 创建时间
• updatedAt: number - 更新时间
• settings: ConversationSettings - 对话设置
• stats: ConversationStats - 统计信息
• metadata: Record<string, any> - 元数据

方法

• updateTitle(title: string): void - 更新标题
• updateSettings(settings: Partial<ConversationSettings>): void - 更新设置
• updateStats(stats: Partial<ConversationStats>): void - 更新统计
• incrementMessageCount(): void - 增加消息计数
• toStorage(): any - 转换为存储格式
• validate(): ValidationResult - 验证数据

🎯 应用服务

ChatService

聊天业务逻辑服务。

import { ChatService } from '../src/application/services/chat.service';

// 创建服务实例
const chatService = new ChatService(messageRepo, conversationRepo, llmProvider);

// 初始化
await chatService.initialize(app);

// 发送消息
const result = await chatService.sendMessage('conv-123', userMessage);
if (result.isSuccess) {
  console.log('AI Response:', result.value.content);
} else {
  console.error('Send failed:', result.error);
}

// 获取对话历史
const history = await chatService.getConversationHistory('conv-123', {
  limit: 50,
  offset: 0
});

// 搜索消息
const searchResults = await chatService.searchMessages('conv-123', 'hello world');

// 删除消息
const deleted = await chatService.deleteMessage('conv-123', 'msg-456');

方法

• initialize(app: App): Promise<void> - 初始化服务
• sendMessage(conversationId: string, message: Message): Promise<Result<Message>> - 发送消息
• getConversationHistory(conversationId: string, options?: PaginationOptions): Promise<Result<Message[]>> - 获取历史
• searchMessages(conversationId: string, query: string): Promise<Result<Message[]>> - 搜索消息
• updateMessage(messageId: string, updates: Partial<Message>): Promise<Result<Message>> - 更新消息
• deleteMessage(conversationId: string, messageId: string): Promise<Result<boolean>> - 删除消息
• getMessageStats(conversationId: string): Promise<Result<ConversationStats>> - 获取统计

🏛️ 基础设施

LLM 提供商

统一的 LLM 提供商接口。

import { providerRegistry, OpenAIConfig } from '../src/infrastructure/llm';

// 创建 OpenAI 提供商
const openaiConfig: OpenAIConfig = {
  name: 'OpenAI',
  version: '0.0.1',
  apiKey: 'your-api-key',
  defaultModel: 'gpt-4o-mini'
};

const provider = providerRegistry.createProvider('OpenAI', openaiConfig);
await provider.initialize(openaiConfig);

// 聊天完成
const response = await provider.chatCompletion([
  { role: 'user', content: 'Hello!' }
], {
  model: 'gpt-4o-mini',
  temperature: 0.7,
  maxTokens: 1000
});

// 流式聊天
await provider.chatCompletionStream([
  { role: 'user', content: 'Hello!' }
], {
  model: 'gpt-4o-mini'
}, (chunk) => {
  console.log('Chunk:', chunk.delta?.content);
});

// 获取提供商信息
const capabilities = provider.capabilities;
const models = provider.models;
const status = await provider.getStatus();

仓储实现

Obsidian 存储仓储。

import { MessageRepository, ConversationRepository } from '../src/infrastructure/persistence/obsidian';

// 创建仓储
const messageRepo = new MessageRepository();
const conversationRepo = new ConversationRepository();

// 初始化
await messageRepo.initialize();
await conversationRepo.initialize();

// 使用仓储
const message = MessageFactory.createUser({...});
const saved = await messageRepo.save(message);
if (saved.isSuccess) {
  console.log('Message saved:', saved.value.id);
}

// 查询消息
const messages = await messageRepo.findByConversation('conv-123', {
  limit: 10,
  orderBy: 'timestamp',
  order: 'desc'
});

🎨 UI 组件

ChatState

聊天状态管理。

import { useChatStore } from '../src/presentation/state/chat.state';

function ChatComponent() {
  const chatStore = useChatStore();
  
  // 获取状态
  const currentConversation = chatStore.getCurrentConversation();
  const messages = chatStore.getMessages('conv-123');
  const isLoading = chatStore.isLoading();
  
  // 执行操作
  const handleSend = async (content: string) => {
    const result = await chatStore.sendMessage(content);
    if (result.isFailure) {
      console.error('Send failed:', result.error);
    }
  };
  
  return (
    <div>
      {messages.map(msg => (
        <MessageComponent key={msg.id} message={msg} />
      ))}
      <InputComponent onSend={handleSend} disabled={isLoading} />
    </div>
  );
}

状态选择器

• getCurrentConversation(): Conversation | undefined - 当前对话
• getMessages(conversationId: string): Message[] - 对话消息
• isLoading(): boolean - 加载状态
• getError(): string | undefined - 错误信息
• getUnreadCount(conversationId: string): number - 未读数

状态操作

• sendMessage(content: string): Promise<Result<Message>> - 发送消息
• loadConversation(id: string): Promise<void> - 加载对话
• createConversation(options: CreateConversationOptions): Promise<Result<Conversation>> - 创建对话
• updateMessage(id: string, updates: Partial<Message>): Promise<void> - 更新消息
• deleteMessage(id: string): Promise<void> - 删除消息

🔌 LLM 提供商 API

注册自定义提供商

import { ILLMProvider, ILLMProviderFactory } from '../src/infrastructure/llm';

// 实现提供商
class MyProvider implements ILLMProvider {
  public readonly name = 'MyProvider';
  public readonly version = '0.0.1';
  
  async initialize(config: LLMProviderConfig): Promise<void> {
    // 初始化逻辑
  }
  
  async chatCompletion(messages: LLMMessage[], options: LLMRequestOptions): Promise<LLMResponse> {
    // 实现聊天完成
    return {
      id: 'resp-123',
      object: 'chat.completion',
      created: Date.now(),
      model: options.model,
      content: { text: 'Response content' }
    };
  }
  
  // 实现其他必需方法...
}

// 实现工厂
class MyProviderFactory implements ILLMProviderFactory {
  public readonly name = 'MyProvider';
  
  create(config: LLMProviderConfig): ILLMProvider {
    return new MyProvider();
  }
  
  validateConfig(config: LLMProviderConfig): { valid: boolean; errors: string[] } {
    // 验证配置
    return { valid: true, errors: [] };
  }
  
  getDefaultConfig(): LLMProviderConfig {
    return {
      name: 'MyProvider',
      version: '0.0.1',
      defaultModel: 'my-model'
    };
  }
}

// 注册提供商
providerRegistry.register(new MyProviderFactory());

使用提供商管理器

import { llmProviderManager } from '../src/infrastructure/llm';

// 获取默认提供商
const defaultProvider = llmProviderManager.getDefaultProvider();

// 获取特定提供商
const openaiProvider = llmProviderManager.getProvider('OpenAI');

// 切换默认提供商
await llmProviderManager.switchDefaultProvider('Ollama');

// 获取所有提供商状态
const status = await llmProviderManager.getAllStatus();

// 批量测试提供商
const testResults = await llmProviderManager.testAllProviders();

📝 类型定义

核心类型

// Result 类型
interface Result<T> {
  readonly isSuccess: boolean;
  readonly isFailure: boolean;
  readonly value?: T;
  readonly error?: string;
  readonly code?: string;
}

// 服务状态
type ServiceStatus = 'initializing' | 'ready' | 'error' | 'stopped';

// 生命周期
interface ServiceLifecycle {
  initialize(context: any): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
  cleanup(): Promise<void>;
}

LLM 类型

// 消息格式
interface LLMMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  attachments?: MessageAttachment[];
}

// 请求选项
interface LLMRequestOptions {
  model: string;
  temperature?: number;
  maxTokens?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  stop?: string[];
}

// 响应格式
interface LLMResponse {
  id: string;
  object: string;
  created: number;
  model: string;
  content: LLMResponseContent;
  usage?: TokenUsage;
  finishReason?: string;
  processingTime?: number;
}

🧪 测试 API

测试工具

import { createMockProvider, createTestRepositories } from '../src/test-support';

// 创建模拟提供商
const mockProvider = createMockProvider({
  responses: ['Hello!', 'How can I help?']
});

// 创建测试仓储
const { messageRepo, conversationRepo } = createTestRepositories();

// 测试服务
const chatService = new ChatService(messageRepo, conversationRepo, mockProvider);

// 测试消息发送
const result = await chatService.sendMessage('conv-123', message);
expect(result.isSuccess).toBe(true);

🔗 相关链接

• 架构设计
• 开发指南
• 测试指南

---

API 文档会随着项目发展持续更新。