# 🤖 tinyCodingAgent

一个用 Rust 从零实现的轻量级 AI 编程助手，帮助你理解 Coding Agent 的核心原理。

[![Rust](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/)

## 📖 项目简介

**tinyCodingAgent** 是一个建议的 Coding Agent 实现，它展示了如何构建一个能够：

- 🔧 **调用工具** - 读写文件、执行命令、搜索代码
- 🧠 **自主推理** - 基于 ReAct 模式循环思考和行动
- 🔌 **扩展能力** - 通过 MCP 协议集成外部服务
- 📋 **规划任务** - 将复杂任务分解为可管理的步骤
- 📚 **学习技能** - 通过 Markdown 文件扩展新能力

本项目代码简洁、注释详尽，非常适合学习 AI Agent 的实现原理。

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **Chat Completion 协议** | 标准化的 LLM 通信接口，兼容 OpenAI/Claude/本地模型 |
| **工具调用 (Tool Calling)** | 让 LLM 能够执行实际操作 |
| **ReAct 循环** | 推理-行动-观察的智能循环 |
| **上下文管理** | 智能修剪 + LLM 摘要，防止 Token 溢出 |
| **MCP 协议支持** | 动态发现和调用外部工具服务 |
| **安全审查机制** | 敏感操作需用户确认，支持 Diff 预览 |
| **计划模式** | 可视化任务进度跟踪 |
| **Skills 系统** | 无代码扩展 Agent 能力 |

## 🏗️ 架构概览
![Overview](./docs/pic/Overview.jpg)

## 📁 项目结构

```
tinyCodingAgent/
├── Cargo.toml              # 项目配置和依赖
├── config.toml             # 运行时配置（MCP、Skills）
├── .env                    # 环境变量（API密钥等）
└── src/
    ├── main.rs             # 入口点，主循环
    ├── config.rs           # 配置加载
    ├── agent/
    │   ├── mod.rs          # Agent 核心逻辑
    │   ├── context_manager.rs  # 上下文管理
    │   ├── plan_manager.rs # 计划管理
    │   ├── security.rs     # 安全审查
    │   └── skills.rs       # Skills 系统
    ├── llm/
    │   ├── mod.rs          # 消息类型定义
    │   ├── client.rs       # LLM 客户端
    │   └── tokenizer.rs    # Token 计数
    ├── mcp/
    │   ├── mod.rs          # MCP 模块
    │   ├── client.rs       # MCP 客户端
    │   └── protocol.rs     # JSON-RPC 协议
    └── tools/
        ├── mod.rs          # 工具接口定义
        ├── read_fs.rs      # 读取文件
        ├── edit_fs.rs      # 编辑文件
        ├── list_fs.rs      # 列出目录
        ├── bash.rs         # 执行命令
        ├── code_search.rs  # 代码搜索
        ├── update_plan.rs  # 更新计划
        └── mcp_tool_adapter.rs  # MCP 工具适配器
```

## 🚀 快速开始

### 1. 环境准备

```bash
# 确保已安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装 ripgrep（代码搜索依赖）
# Windows
winget install BurntSushi.ripgrep.MSVC
# macOS
brew install ripgrep
# Linux
sudo apt install ripgrep
```

### 2. 配置环境变量

创建 `.env` 文件：

```env
# LLM 配置
API_KEY=your-api-key-here
API_BASE=https://api.openai.com/v1
MODEL_NAME=gpt-4o

# 上下文配置
CONTEXT_WINDOW=128000
PRUNE_MARGIN=40000
```

### 3. 配置 MCP 和 skills 根目录（可选）

编辑 `config.toml`：

```toml
[skills]
paths = ["./.skills"]

[mcp_servers.dbhub]
command = "npx"
args = ["-y", "@bytebase/dbhub", "--transport", "stdio", "--dsn", "mysql://user:pass@localhost:3306/mydb"]
```

### 4. 编译运行

```bash
cargo build --release
cargo run
```

## 💬 使用方法

### 基本对话

```
You> 帮我看一下 src/main.rs 的代码结构
Agent> (Thinking...)
 [Tool Call] read_file args: {"path":"src/main.rs"}
 [Tool Result] Length: 2345 chars
Agent> 这个文件是程序的入口点，主要包含以下部分...
```

### 内置命令

| 命令 | 说明 |
|------|------|
| `/clear` | 清空对话历史 |
| `/plan` | 查看当前任务计划 |
| `/skills` | 列出可用技能 |
| `exit` | 退出程序 |

### 安全审查

当 Agent 要执行敏感操作时，会请求确认：

```
[SECURITY ALERT] Agent wants to execute: edit_file
Target: src/main.rs
--------------------------------------------------
- (Remove)
println!("old");

+ (Add)
println!("new");
--------------------------------------------------
Allow execution? [y/N]: 
```

## 📚 教程系列

本项目文档：

todo

## 🔧 内置工具

| 工具 | 说明 |
|------|------|
| `read_file` | 读取文件内容，支持行号范围 |
| `edit_file` | 通过搜索替换编辑文件 |
| `list_files` | 列出目录结构（树形视图） |
| `bash`/`shell` | 执行系统命令 |
| `code_search` | 使用 ripgrep 搜索代码 |
| `update_plan` | 创建/更新任务计划 |

## 🔌 MCP 生态

支持的 MCP Server 示例：

- `@bytebase/dbhub` - 数据库查询


## 📂 Skills 扩展

创建自定义技能只需添加一个文件夹：

```
.skills/
└── my-skill/
    ├── SKILL.md       # 技能说明（必需）
    ├── scripts/       # 脚本（可选）
    └── references/    # 参考文档（可选）
```

`SKILL.md` 格式：

```markdown
---
name: my-skill
description: 当用户说"xxx"时使用此技能
---

# 技能说明

详细的使用指南...
```

**⭐ 如果这个项目对你有帮助，欢迎 Star！**