docs: 更新项目文档
This commit is contained in:
@@ -0,0 +1,245 @@
|
||||
# @ai-assistant/core
|
||||
|
||||
Core engine package for AI Terminal Assistant - provides the AI agent, tools, and integrations.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
pnpm add @ai-assistant/core
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **AI Agent Engine** - Streaming text generation with Claude API
|
||||
- **Tool System** - Extensible tool registry with Zod validation
|
||||
- **Editor Modes** - Multiple editing strategies (whole, diff, search-replace)
|
||||
- **Language Server Protocol** - Code intelligence and analysis
|
||||
- **Checkpoint System** - Shadow Git for safe experimentation
|
||||
- **Hook System** - Pre/post execution customization
|
||||
- **Model Context Protocol** - MCP client for external tools
|
||||
- **Repository Mapping** - Tree-sitter based code analysis
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/
|
||||
│ ├── agent.ts # Main Agent class with streaming
|
||||
│ ├── config.ts # Configuration management
|
||||
│ └── types.ts # Core type definitions
|
||||
├── tools/
|
||||
│ ├── registry.ts # Tool registration system
|
||||
│ ├── bash.ts # Bash command execution
|
||||
│ ├── file.ts # File operations
|
||||
│ ├── search.ts # Code search utilities
|
||||
│ └── index.ts # Tool exports
|
||||
├── editors/
|
||||
│ ├── base.ts # Base editor interface
|
||||
│ ├── whole.ts # Whole file replacement
|
||||
│ ├── diff.ts # Diff-based editing
|
||||
│ └── search-replace.ts # Search and replace
|
||||
├── lsp/
|
||||
│ ├── client.ts # LSP client implementation
|
||||
│ └── server.ts # LSP server management
|
||||
├── checkpoint/
|
||||
│ ├── manager.ts # Checkpoint management
|
||||
│ └── git.ts # Shadow Git operations
|
||||
├── hooks/
|
||||
│ ├── manager.ts # Hook execution system
|
||||
│ └── types.ts # Hook type definitions
|
||||
├── mcp/
|
||||
│ ├── client.ts # MCP client implementation
|
||||
│ └── protocol.ts # Protocol definitions
|
||||
└── repomap/
|
||||
├── generator.ts # Repository map generation
|
||||
└── parser.ts # Tree-sitter parsing
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
import { Agent, toolRegistry } from '@ai-assistant/core';
|
||||
|
||||
// Create an agent instance
|
||||
const agent = new Agent({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY,
|
||||
model: 'claude-sonnet-4-20250514',
|
||||
maxTokens: 4096
|
||||
});
|
||||
|
||||
// Chat with the agent
|
||||
const response = await agent.chat('Help me write a TypeScript function', {
|
||||
onChunk: (chunk) => console.log(chunk),
|
||||
onComplete: (response) => console.log('Done:', response)
|
||||
});
|
||||
```
|
||||
|
||||
### Tool Registration
|
||||
|
||||
```typescript
|
||||
import { toolRegistry } from '@ai-assistant/core/tools';
|
||||
import { z } from 'zod';
|
||||
|
||||
// Register a custom tool
|
||||
toolRegistry.register({
|
||||
name: 'my_tool',
|
||||
description: 'Does something useful',
|
||||
parameters: z.object({
|
||||
input: z.string().describe('Input parameter')
|
||||
}),
|
||||
execute: async (params) => {
|
||||
// Tool implementation
|
||||
return { success: true, result: params.input.toUpperCase() };
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Editor Modes
|
||||
|
||||
```typescript
|
||||
import { createEditor } from '@ai-assistant/core/editors';
|
||||
|
||||
// Whole file replacement
|
||||
const wholeEditor = createEditor('whole');
|
||||
await wholeEditor.edit('file.ts', 'new content');
|
||||
|
||||
// Diff-based editing
|
||||
const diffEditor = createEditor('diff');
|
||||
await diffEditor.edit('file.ts', '--- old\n+++ new\n...');
|
||||
|
||||
// Search and replace
|
||||
const searchEditor = createEditor('search-replace');
|
||||
await searchEditor.edit('file.ts', {
|
||||
search: 'oldFunction',
|
||||
replace: 'newFunction'
|
||||
});
|
||||
```
|
||||
|
||||
### Checkpoint System
|
||||
|
||||
```typescript
|
||||
import { CheckpointManager } from '@ai-assistant/core/checkpoint';
|
||||
|
||||
const manager = new CheckpointManager('/project/path');
|
||||
|
||||
// Create a checkpoint
|
||||
await manager.create('before-refactoring');
|
||||
|
||||
// Make changes...
|
||||
|
||||
// Restore if needed
|
||||
await manager.restore('before-refactoring');
|
||||
|
||||
// List checkpoints
|
||||
const checkpoints = await manager.list();
|
||||
```
|
||||
|
||||
### Language Server Protocol
|
||||
|
||||
```typescript
|
||||
import { LSPClient } from '@ai-assistant/core/lsp';
|
||||
|
||||
const lsp = new LSPClient({
|
||||
serverCommand: 'typescript-language-server',
|
||||
serverArgs: ['--stdio']
|
||||
});
|
||||
|
||||
await lsp.initialize('/project/path');
|
||||
|
||||
// Get diagnostics
|
||||
const diagnostics = await lsp.getDiagnostics('file.ts');
|
||||
|
||||
// Get completions
|
||||
const completions = await lsp.getCompletions('file.ts', { line: 10, character: 5 });
|
||||
|
||||
// Go to definition
|
||||
const definition = await lsp.getDefinition('file.ts', { line: 10, character: 5 });
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
```typescript
|
||||
interface AgentConfig {
|
||||
apiKey: string; // Anthropic API key
|
||||
model?: string; // Model name (default: claude-sonnet-4-20250514)
|
||||
maxTokens?: number; // Max response tokens (default: 4096)
|
||||
temperature?: number; // Sampling temperature (default: 0.7)
|
||||
systemPrompt?: string; // System prompt
|
||||
tools?: Tool[]; // Available tools
|
||||
hooks?: HookConfig; // Hook configuration
|
||||
checkpointDir?: string; // Checkpoint directory
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 API Reference
|
||||
|
||||
### 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[];
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Registry
|
||||
|
||||
```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>;
|
||||
}
|
||||
```
|
||||
|
||||
### Editor Interface
|
||||
|
||||
```typescript
|
||||
interface Editor {
|
||||
edit(path: string, content: string | EditParams): Promise<void>;
|
||||
validate(content: string): boolean;
|
||||
preview(path: string, content: string): string;
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Watch mode
|
||||
pnpm test:watch
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please follow these steps:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests for new functionality
|
||||
5. Ensure all tests pass
|
||||
6. Submit a pull request
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [API Documentation](https://docs.example.com/core)
|
||||
- [Issue Tracker](https://github.com/username/ai-terminal-assistant/issues)
|
||||
Reference in New Issue
Block a user