# @ai-assistant/core

AI Terminal Assistant 的核心引擎包 - 提供 AI 代理、工具和集成功能。

## 📦 安装

```bash
pnpm add @ai-assistant/core
```

## 🌟 功能特性

- **AI 代理引擎** - 使用 Claude API 进行流式文本生成
- **工具系统** - 带有 Zod 验证的可扩展工具注册表
- **编辑器模式** - 多种编辑策略（整体、差异、搜索替换）
- **语言服务协议** - 代码智能和分析
- **检查点系统** - Shadow Git 安全实验
- **钩子系统** - 执行前后的自定义处理
- **模型上下文协议** - 外部工具的 MCP 客户端
- **仓库映射** - 基于 Tree-sitter 的代码分析

## 🏗️ 架构

```
src/
├── core/
│   ├── agent.ts           # 主要的 Agent 类，支持流式处理
│   ├── config.ts          # 配置管理
│   └── types.ts           # 核心类型定义
├── tools/
│   ├── registry.ts        # 工具注册系统
│   ├── bash.ts            # Bash 命令执行
│   ├── file.ts            # 文件操作
│   ├── search.ts          # 代码搜索工具
│   └── index.ts           # 工具导出
├── editors/
│   ├── base.ts            # 基础编辑器接口
│   ├── whole.ts           # 整体文件替换
│   ├── diff.ts            # 基于差异的编辑
│   └── search-replace.ts  # 搜索和替换
├── lsp/
│   ├── client.ts          # LSP 客户端实现
│   └── server.ts          # LSP 服务器管理
├── checkpoint/
│   ├── manager.ts         # 检查点管理
│   └── git.ts             # Shadow Git 操作
├── hooks/
│   ├── manager.ts         # 钩子执行系统
│   └── types.ts           # 钩子类型定义
├── mcp/
│   ├── client.ts          # MCP 客户端实现
│   └── protocol.ts        # 协议定义
└── repomap/
    ├── generator.ts       # 仓库映射生成
    └── parser.ts          # Tree-sitter 解析
```

## 🚀 快速开始

### 基本用法

```typescript
import { Agent, toolRegistry } from '@ai-assistant/core';

// 创建代理实例
const agent = new Agent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-sonnet-4-20250514',
  maxTokens: 4096
});

// 与代理对话
const response = await agent.chat('帮我编写一个 TypeScript 函数', {
  onChunk: (chunk) => console.log(chunk),
  onComplete: (response) => console.log('完成:', response)
});
```

### 工具注册

```typescript
import { toolRegistry } from '@ai-assistant/core/tools';
import { z } from 'zod';

// 注册自定义工具
toolRegistry.register({
  name: 'my_tool',
  description: '执行有用的操作',
  parameters: z.object({
    input: z.string().describe('输入参数')
  }),
  execute: async (params) => {
    // 工具实现
    return { success: true, result: params.input.toUpperCase() };
  }
});
```

### 编辑器模式

```typescript
import { createEditor } from '@ai-assistant/core/editors';

// 整体文件替换
const wholeEditor = createEditor('whole');
await wholeEditor.edit('file.ts', '新内容');

// 基于差异的编辑
const diffEditor = createEditor('diff');
await diffEditor.edit('file.ts', '--- old\n+++ new\n...');

// 搜索和替换
const searchEditor = createEditor('search-replace');
await searchEditor.edit('file.ts', {
  search: 'oldFunction',
  replace: 'newFunction'
});
```

### 检查点系统

```typescript
import { CheckpointManager } from '@ai-assistant/core/checkpoint';

const manager = new CheckpointManager('/project/path');

// 创建检查点
await manager.create('重构前');

// 进行更改...

// 需要时恢复
await manager.restore('重构前');

// 列出检查点
const checkpoints = await manager.list();
```

### 语言服务协议

```typescript
import { LSPClient } from '@ai-assistant/core/lsp';

const lsp = new LSPClient({
  serverCommand: 'typescript-language-server',
  serverArgs: ['--stdio']
});

await lsp.initialize('/project/path');

// 获取诊断信息
const diagnostics = await lsp.getDiagnostics('file.ts');

// 获取代码补全
const completions = await lsp.getCompletions('file.ts', { line: 10, character: 5 });

// 跳转到定义
const definition = await lsp.getDefinition('file.ts', { line: 10, character: 5 });
```

## 🔧 配置

```typescript
interface AgentConfig {
  apiKey: string;                      // Anthropic API 密钥
  model?: string;                       // 模型名称（默认：claude-sonnet-4-20250514）
  maxTokens?: number;                   // 最大响应令牌数（默认：4096）
  temperature?: number;                 // 采样温度（默认：0.7）
  systemPrompt?: string;                // 系统提示词
  tools?: Tool[];                       // 可用工具
  hooks?: HookConfig;                   // 钩子配置
  checkpointDir?: string;               // 检查点目录
}
```

## 📚 API 参考

### Agent

```typescript
class Agent {
  constructor(config: AgentConfig);

  chat(message: string, options?: ChatOptions): Promise<Response>;
  streamChat(message: string, options?: StreamOptions): AsyncIterator<Chunk>;
  reset(): void;
  getHistory(): Message[];
}
```

### 工具注册表

```typescript
class ToolRegistry {
  register(tool: ToolDefinition): void;
  unregister(name: string): void;
  get(name: string): Tool | undefined;
  list(): Tool[];
  execute(name: string, params: any): Promise<ToolResult>;
}
```

### 编辑器接口

```typescript
interface Editor {
  edit(path: string, content: string | EditParams): Promise<void>;
  validate(content: string): boolean;
  preview(path: string, content: string): string;
}
```

## 🧪 测试

```bash
# 运行测试
pnpm test

# 运行覆盖率测试
pnpm test:coverage

# 监视模式
pnpm test:watch
```

## 🤝 贡献

欢迎贡献！请按照以下步骤：

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交 Pull Request

## 📄 许可证

MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。

## 🔗 链接

- [主仓库](https://github.com/username/ai-terminal-assistant)
- [API 文档](https://docs.example.com/core)
- [问题跟踪](https://github.com/username/ai-terminal-assistant/issues)