245 lines
6.2 KiB
Markdown
245 lines
6.2 KiB
Markdown
# @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) |