docs: 添加中文文档

2025-12-12 15:31:38 +08:00
parent 4ca8c413a6
commit 563224fa73
6 changed files with 1947 additions and 0 deletions
@@ -0,0 +1,245 @@
+# @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)