# MiniCode

**Repository Path**: naka507/MiniCode

## Basic Information

- **Project Name**: MiniCode
- **Description**: 基于事件驱动支持多个提供商 的AI 编程助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-24
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCode

<div align="center">

**一个基于事件驱动架构的多提供商 AI 编程助手**

[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)

[English](./README_EN.md) | 中文文档

</div>

---

## 项目简介

MiniCode 是一个先进的 AI 编程助手，采用**事件驱动架构**和**可插拔能力系统**设计。它支持多个主流 AI 提供商（Anthropic Claude、Google Gemini），通过统一的接口提供强大的代码辅助功能。

## 核心特性

### 🎯 多提供商支持
- **Anthropic Claude**: 支持 Claude 4.5 Sonnet、Claude 4 Opus 等模型
- **Google Gemini**: 支持 Gemini 2.5 Flash、Gemini 2.5 Pro 等模型
- **灵活切换**: 通过配置文件轻松切换不同的 AI 提供商

### 🏗️ 先进的架构设计
- **事件驱动架构**: 完全解耦 UI 层和 Provider 层，通过 EventBus 进行通信
- **可插拔能力系统**: 模块化的能力管理（Caching、Warmup、Thinking、Streaming）
- **适配器模式**: 统一不同 AI 提供商的 API 差异
- **工具注册表**: 集中管理和执行各类工具

### 🛠️ 丰富的工具集

#### 文件操作工具
- **Read**: 读取文件内容，支持行号和分页
- **Write**: 创建或覆盖文件
- **Edit**: 精确编辑文件内容
- **Glob**: 模式匹配查找文件
- **Grep**: 内容搜索和正则匹配

#### 系统工具
- **Bash**: 执行 Shell 命令（带安全验证）
- **TodoWrite**: 任务管理和追踪

#### 高级工具
- **Task**: 启动专门的子代理处理复杂任务
  - **General**: 通用代理，可使用所有工具
  - **Explore**: 代码库探索专家（Glob、Grep、Read、Bash）
  - **Plan**: 规划和分析专家（Glob、Grep、Read、Bash）

#### 工具分类
工具按用途分为四大类别：
- **readonly**: 只读操作（Read、Glob、Grep）
- **writeops**: 写入操作（Write、Edit）
- **bash**: 命令执行（Bash）
- **task**: 任务管理（TodoWrite、Task）

### 🔒 工具执行审核

为了安全性，MiniCode 实现了智能的工具执行审核机制：

**审核策略**：
- **只读工具**（Read、Glob、Grep）：无需审核
- **写入工具**（Write、Edit）：首次执行需要审核
- **命令工具**（Bash）：首次执行需要审核
- **任务工具**（TodoWrite、Task）：无需审核

**审核选项**：
- **y（是）**: 批准本次执行
- **n（否）**: 拒绝本次执行
- **a（总是）**: 批准并自动批准该类别的所有后续操作

**配置**：
```bash
# .env 文件中可以完全禁用审核
REQUIRE_TOOL_APPROVAL=false
```

**智能缓存**：
- 用户选择"总是批准"后，该类别的工具不再需要审核
- 会话期间持久化，提高工作效率

### 🧠 智能任务调度
- **任务分类器**: 自动识别任务类型（SEARCH、READ、CODE、REVIEW、DEBUG、TEST、GENERAL）
- **复杂度评估**: 评估任务复杂度（SIMPLE、MODERATE、COMPLEX）
- **模型调度器**: 根据任务特征智能选择合适的模型
- **成本优化**: 简单任务使用轻量模型，复杂任务使用强大模型

## 项目亮点 ⭐

### 1. 零侵入事件驱动架构
- UI 层和 Provider 层**完全解耦**，通过 EventBus 异步通信
- 无需在业务代码中注入 UI 依赖，保持代码纯净
- 支持多个 UI 层同时监听，便于调试和扩展

### 2. 智能成本优化
```javascript
// 示例：简单查询自动使用 Gemini Flash（快速低成本）
"查看 README.md 文件"  → Gemini 2.5 Flash

// 复杂任务自动升级到强大模型
"重构整个缓存系统并优化性能"  → Gemini 2.5 Pro
```
- 自动分析任务复杂度，动态选择最合适的模型
- 简单任务成本可降低 **80%+**
- 支持自定义调度策略

### 3. 高性能缓存系统
- **Prompt 缓存**: 系统提示词自动缓存，减少重复计算
- **Warmup 预热**: 首次请求即享受缓存加速
- **成本节省**: 缓存命中可节省 90% 输入 Token 成本

### 4. 可插拔能力系统
每个 Provider 可以独立配置四大核心能力：
- **Caching** - 智能缓存管理
- **Warmup** - 预热优化
- **Thinking** - 深度思考模式（Gemini 专属）
- **Streaming** - 流式输出

### 5. Task 工具：子代理系统
Task 工具允许主 AI 启动专门的子代理来处理复杂任务，实现任务的**分而治之**：

**工作原理**：
```
用户请求 → 主 AI → 调用 Task 工具 → 启动子代理 → 执行任务 → 返回报告 → 主 AI 整合结果
```

**使用场景**：
- 复杂的代码库探索
- 多步骤的文件搜索
- 需要多次迭代的分析任务

**示例**：
```javascript
// AI 自动使用 Task 工具
用户："找出项目中所有的 API 端点定义"

AI 思考：这需要多次搜索，使用 Explore 代理更高效

AI 调用：Task({
  subagent_type: "Explore",
  prompt: "搜索所有 API 路由定义，包括 Express、Koa 等框架的路由..."
})

Explore 代理执行：
  → 使用 Glob 搜索路由文件
  → 使用 Grep 查找路由定义
  → 使用 Read 确认内容
  → 返回完整的 API 列表

AI 整合：根据 Explore 的报告，为用户展示所有 API 端点
```

**优势**：
- **专注性**: 子代理只关注特定任务
- **工具隔离**: 不同代理有不同的工具访问权限
- **并行执行**: 支持同时启动多个子代理
- **成本控制**: 子代理可使用更便宜的模型

### 6. 统一工具接口
```javascript
// 同一套工具代码，无缝支持多个 AI 提供商
const tools = [Read, Write, Edit, Glob, Grep, Bash, TodoWrite, Task];
// 自动适配 Anthropic、Gemini、OpenAI 等不同 API 格式
```

### 7. 完整的可观测性
- 实时任务分类和调度决策展示
- 工具执行过程可视化
- 工具审核交互提示
- Token 使用统计和成本追踪
- 通过 `/stats` 命令查看详细统计信息

## 项目架构 🏗️

### 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                          MiniCode                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐        EventBus         ┌──────────────┐      │
│  │              │◄────────────────────────┤              │      │
│  │  UI Layer    │   Events (async)        │   Provider   │      │
│  │  (UIManager) │                         │    Layer     │      │
│  │              ├────────────────────────►│              │      │
│  └──────┬───────┘                         └──────┬───────┘      │
│         │                                        │              │
│         │ Display                         ┌──────▼───────┐      │
│         │                                 │   Adapter    │      │
│         │                                 │ (API Format) │      │
│         │                                 └──────┬───────┘      │
│         │                                        │              │
│  ┌──────▼────────┐                       ┌──────▼───────┐       │
│  │ Approval      │                       │  Capability  │       │
│  │ System        │                       │   System     │       │
│  │               │                       │ ┌──────────┐ │       │
│  └───────────────┘                       │ │ Caching  │ │       │
│                                          │ │ Warmup   │ │       │
│  ┌──────────────┐                       │ │ Thinking │ │       │
│  │ Task         │                       │ │Streaming │ │       │
│  │ Classifier   │                       │ └──────────┘ │       │
│  │ + Model      │                       └──────────────┘       │
│  │ Scheduler    │                                              │
│  └──────────────┘                       ┌──────────────┐       │
│                                         │   Agent      │       │
│  ┌──────────────┐                       │ (Sub-agent)  │       │
│  │ Tool         │                       └─────��┬───────┘       │
│  │ Registry     │                              │               │
│  │              │                       ┌──────▼───────┐        │
│  │ - Read       │◄──────────────────────┤  API Client  │        │
│  │ - Write      │   Tool Execution      │ (HTTP Layer) │        │
│  │ - Edit       │                       └──────────────┘        │
│  │ - Glob       │                                               │
│  │ - Grep       │                                               │
│  │ - Bash       │                                               │
│  │ - TodoWrite  │                                               │
│  │ - Task       │                                               │
│  └──────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 核心模块说明

**1. EventBus（事件总线）**
```javascript
// 发布事件
EventBus.toolStart('Read', { file: 'test.js' });
EventBus.streamDelta('Hello', 'text');
EventBus.generateComplete('Gemini', message, usage);

// 订阅事件
EventBus.on('tool:start', (data) => { /* 处理 */ });
```
- 单例模式，全局唯一实例
- 支持 20+ 种事件类型
- 提供 Promise 风格的 `waitFor()` 方法
- 支持工具审核的异步请求/响应机制

**2. Provider Layer（提供商层）**
```
BaseProvider (抽象基类)
    ├── AnthropicProvider
    │   ├── AnthropicClient (HTTP)
    │   ├── AnthropicAdapter (格式转换)
    │   ├── Capabilities: Caching, Warmup, Streaming
    │   └── Tools: 自定义 cache_control
    │
    └── GeminiProvider
        ├── GeminiClient (HTTP)
        ├── GeminiAdapter (格式转换)
        ├── Capabilities: Caching, Thinking, Streaming
        └── Tools: maxToolsPerRequest 限制
```

**3. Agent（子代理管理器）**
```javascript
// 管理 Task 工具的子代理执行
agent.initialize(provider, toolRegistry);

// 根据代理类型过滤工具
agent.getToolsForAgentType('Explore'); // ['Glob', 'Grep', 'Read', 'Bash']

// 执行子代理任务
await agent.execute(description, prompt, agentType, model);
```

**4. Tool Registry（工具注册表）**
```javascript
// 自动注册所有工具
toolRegistry.initialize();

// 按类别获取
toolRegistry.getToolsByCategory('readonly'); // [Read, Glob, Grep]
toolRegistry.getToolsByCategory('writeops'); // [Write, Edit]

// 执行工具（带审核）
const result = await toolRegistry.execute('Read', { file_path: '/path/to/file' });
```

**5. Approval System（审核系统）**
```javascript
// 检查是否需要审核
if (toolRegistry._requiresApproval(tool)) {
  // 请求用户审核
  const result = await EventBus.requestApproval(name, category, input);

  // 处理用户响应
  if (result.approved) {
    if (result.autoApproveCategory) {
      // 缓存自动批准的类别
      autoApprovedCategories.add(category);
    }
  }
}
```

**6. Task Classifier + Model Scheduler（智能调度）**
```javascript
// 任务分类
const task = classifier.classify("优化缓存系统");
// → { type: 'CODE', complexity: 'COMPLEX', confidence: 0.85 }

// 模型调度
const schedule = scheduler.analyze(task);
// → { model: 'gemini-2.5-pro', tools: null, reason: '复杂代码任务' }
```

## 快速开始

### 1. 环境要求

- Node.js >= 18.0.0
- npm 或 yarn

### 2. 安装方式

**方式一：通过 npm 全局安装（推荐）**

```bash
npm install -g minicode
```

安装后可以直接使用 `minicode` 命令：

```bash
minicode
```

**方式二：从源码运行**

```bash
# 克隆仓库
git clone https://gitee.com/naka507/MiniCode.git
cd MiniCode

# 安装依赖
npm install

# 运行
node src/main.js
```

### 3. 配置 API Key

创建 `.env` 文件（参考 `.env.example`）:

**使用 Anthropic Claude:**
```bash
PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-xxx
```

**使用 Google Gemini:**
```bash
PROVIDER=gemini
GEMINI_API_KEY=your_gemini_api_key
```

### 4. 运行程序

**如果是全局安装：**
```bash
minicode
```

**如果是从源码运行：**
```bash
node src/main.js
```

## 配置选项

### 基础配置

| 变量名 | 说明 | 默认值 | 示例 |
|--------|------|--------|------|
| `PROVIDER` | AI 提供商 | gemini | anthropic / gemini |
| `MODEL` | 模型名称 | 自动选择 | claude-sonnet-4.5 / gemini-2.5-flash |
| `MAX_TOKENS` | 最大输出 Token 数 | 4096 | 8192 |

### API 配置

| 变量名 | 说明 | 必需 |
|--------|------|------|
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 使用 Anthropic 时 |
| `ANTHROPIC_BASE_URL` | Anthropic API 地址 | 否（默认官方） |
| `GEMINI_API_KEY` | Gemini API 密钥 | 使用 Gemini 时 |
| `GEMINI_BASE_URL` | Gemini API 地址 | 否（默认官方） |

### 功能开关

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ENABLE_CACHE` | 启用 Prompt 缓存 | true |
| `ENABLE_WARMUP` | 启用预热优化 | true |
| `ENABLE_THINKING` | 启用思考模式 | true |
| `ENABLE_STREAMING` | 启用流式输出 | true |
| `ENABLE_MODEL_SCHEDULING` | 启用智能模型调度 | true |
| `REQUIRE_TOOL_APPROVAL` | 启用工具执行审核 | true |

### 模型调度配置

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `FAST_MODEL` | 快速模型（简单任务） | gemini-2.5-flash |
| `POWERFUL_MODEL` | 强大模型（复杂任务） | gemini-2.5-pro |
| `THINKING_BUDGET` | 思考预算（Gemini 专用） | -1（无限制） |

### 调试配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VERBOSE` | 详细日志输出 | false |
| `DEBUG` | 调试模式 | false |

## 命令行交互

启动程序后，支持以下命令：

| 命令 | 功能 | 说明 |
|------|------|------|
| `/help` | 显示帮助信息 | 查看所有可用命令 |
| `/stats` | 显示统计信息 | 查看 Token 使用、工具执行统计 |
| `/clear` | 清屏 | 清除终端显示内容 |
| `/exit` 或 `/quit` | 退出程序 | 保存会话并退出 |

### 使用示例

```bash
# 启动程序
$ node src/main.js

# 查看文件内容
> 读取 src/main.js 文件的前 50 行

# 编写代码
> 创建一个工具函数用于格式化日期

# 复杂任务（AI 会自动使用 Task 工具）
> 找出项目中所有使用了缓存的地方，并分析缓存策略

# 查看统计
> /stats

# 退出程序
> /exit
```

### 工具审核交互示例

```bash
# 当 AI 尝试执行写入操作时
Tool Execution Requires Approval
Tool: Write (writeops)
Input:
  file_path: /path/to/file.js
  content: ...

Approve execution? (y/n/a)
  y = yes (this time)
  n = no (cancel)
  a = always (auto-approve writeops)
> a

✓ Auto-approval enabled for category: writeops
# 后续 Write/Edit 操作将自动批准
```

## 许可证

本项目采用 ISC 许可证。

---

<div align="center">

**Made with ❤️ by MiniCode Team**

[GitHub](https://gitee.com/naka507/MiniCode) | [文档](./README.md) | [English](./README_EN.md)

</div>