🤖 tinyCodingAgent

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

📖 项目简介

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

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

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

✨ 核心特性

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

🏗️ 架构概览

📁 项目结构

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. 环境准备

# 确保已安装 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 文件：

# 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：

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

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

4. 编译运行

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 格式：

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

# 技能说明

详细的使用指南...

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