ai-terminal-assistant/packages/core/README.zh-CN.md

@ai-assistant/core

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

📦 安装

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 解析

🚀 快速开始

基本用法

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)
});

工具注册

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() };
  }
});

编辑器模式

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'
});

检查点系统

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

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

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

// 进行更改...

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

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

语言服务协议

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 });

🔧 配置

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

class Agent {
  constructor(config: AgentConfig);

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

工具注册表

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

编辑器接口

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

🧪 测试

# 运行测试
pnpm test

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

# 监视模式
pnpm test:watch

🤝 贡献

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

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

📄 许可证

MIT 许可证 - 查看 LICENSE 了解详情。

🔗 链接

• 主仓库
• API 文档
• 问题跟踪