手撕 Agent 教程 - 打造一个轻量级个人智能助手

Alioo Agent - 轻量级个人智能助手

一个简化版的个人智能助手，专注于两个核心功能：PDF 阅读 和新闻摘要。

✨ v0.2.0 新特性:

🎯 更清晰的代码结构和模块划分
📝 完善的类型注解和文档字符串
🔧 改进的 CLI 用户体验
🌐 Web 服务支持 CORS 和错误处理
✅ 增强的错误处理和日志记录
📚 详细的贡献指南

✨ 特性

📄 PDF 阅读 - 读取 PDF 文件并总结内容，支持限制页数
📰 新闻摘要 - 获取知乎、Reddit 热门新闻和 RSS 订阅
🚀 轻量简洁 - 大幅简化架构，易于理解和扩展
🔧 灵活配置 - 支持 DashScope、Ollama、OpenAI 等多种模型
💬 多种交互 - 命令行聊天、Web 界面、API 调用
📝 类型安全 - 完整的类型注解，更好的 IDE 支持
🛡️ 健壮性 - 统一的异常处理和友好的错误提示

📦 安装

开发安装

资源见文章结尾处资源链接

bash 复制代码

cd alioo-agent

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate 

# 安装依赖
pip install -e "."

依赖说明

主要依赖：

agentscope - Agent 框架
pydantic - 数据验证和配置管理
click - CLI 框架
PyMuPDF - PDF 解析
feedparser - RSS 解析
beautifulsoup4 - HTML 解析
requests - HTTP 请求
fastapi + uvicorn - Web 服务（可选）

开发依赖：

pytest - 测试框架
black - 代码格式化
ruff - 代码检查

🚀 快速开始

1. 初始化配置

bash 复制代码

# 使用 DashScope（通义千问）
alioo init --provider dashscope --model qwen-turbo

# 或使用本地 Ollama
alioo init --provider ollama --model llama3.1:8b

alioo init --provider ollama --model qwen2.5:7b


# 或使用 OpenAI
alioo init --provider openai --model gpt-3.5-turbo

设置 API Key（如果使用云服务）：

bash 复制代码

export DASHSCOPE_API_KEY="your-api-key"

2. 开始对话

方式一：命令行聊天

bash 复制代码

# 交互式对话
alioo chat

# 直接提问
alioo chat "帮我读一下这个 PDF：~/document.pdf"
alioo chat "看看今天有什么热点新闻"

方式二：脚本调用

python 复制代码

# -*- coding: utf-8 -*-

from alioo_agent.agents.agent import create_agent
from agentscope.message import Msg
import asyncio

def debug_pdf_reading():
    """调试 PDF 阅读功能"""
    # PDF 文件路径
    pdf_path =  "/Users/mac/Downloads/xx_9年.pdf"
    # pdf_path = "/Users/mac/Downloads/2025_123.pdf"

    print("=" * 60)
    print("开始调试 PDF 阅读功能")
    print("=" * 60)

    # 测试: 使用智能体进行完整流程
    print("\n[测试] 使用智能体处理 PDF...")
    agent = create_agent()

    query = f"解读一下这篇文章：{pdf_path}"
    msg = Msg(name="user", content=query, role="user")

    print(f"用户问题：{query}")
    print("等待 AI 响应...")

    # 异步执行
    response = asyncio.run(agent.reply(msg))

    print(f"\nAI 回答:\n{response.get_text_content()}")
    print("=" * 60)
    print("调试完成!")

if __name__ == "__main__":
    # 在这里设置断点！
    debug_pdf_reading()

🛠️ 使用示例

PDF 阅读

bash 复制代码

alioo chat "帮我读一下这篇论文：/path/to/paper.pdf，总结主要内容"
alioo chat "读取 ~/report.pdf 的前 5 页"

新闻摘要

bash 复制代码

# 获取知乎热榜
alioo chat "看看知乎热榜"

# 获取 Reddit 热门
alioo chat "看看 Reddit 有什么热门话题"

# 自定义 RSS 源
alioo chat "获取这个 RSS 的新闻：https://example.com/feed.xml"

📁 项目结构

复制代码

alioo-agent/
├── src/alioo_agent/
│   ├── __init__.py          # 包初始化
│   ├── config.py            # 配置管理
│   ├── model_factory.py     # 模型工厂
│   ├── agents/
│   │   └── agent.py         # 智能体核心
│   ├── tools/
│   │   ├── __init__.py      # 工具导出
│   │   ├── pdf_reader.py    # PDF 阅读工具
│   │   └── news_reader.py   # 新闻阅读工具
│   └── cli/
│       ├── __init__.py
│       ├── main.py          # CLI 主程序
│       ├── interactive.py   # 交互式聊天
│       └── web_server.py    # Web 服务器
├── tests/                   # 测试目录
├── pyproject.toml           # 项目配置
└── README.md               # 本文档

⚙️ 配置文件

配置文件位于 ~/.alioo/config.json：

json 复制代码

{
  "model": {
    "provider": "dashscope",
    "model_name": "qwen-turbo",
    "api_key": "",
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  },
  "agent": {
    "max_iters": 50,
    "language": "zh"
  },
  "working_dir": "~/.alioo"
}

🔧 扩展开发

添加新工具

在 src/alioo_agent/tools/ 下创建新模块：

python 复制代码

# weather_tool.py
def get_weather(city: str) -> str:
    """获取城市天气"""
    # 实现天气查询逻辑
    return f"{city}今天晴朗，25°C"

注册到智能体：

python 复制代码

# agents/agent.py
from .tools.weather_tool import get_weather

def _create_toolkit(self):
    toolkit = Toolkit()
    toolkit.register_tool_function(get_weather)  # 新增
    return toolkit

修改系统提示词

编辑 agents/agent.py 中的 _build_system_prompt() 方法。

🆚 与 CoPaw 的对比

特性	CoPaw	Alioo Agent
代码复杂度	高（完整企业级）	低（教学级）
技能数量	20+	2 个核心技能
渠道支持	6+ (钉钉、飞书等)	命令行 + Web
记忆管理	向量数据库 + 压缩	无（简化版）
定时任务	APScheduler	无
MCP 集成	支持	无
本地模型	llama.cpp, MLX	Ollama
适用场景	生产环境	学习/原型/轻量使用
代码行数	~5000+	~1500
上手难度	中等	简单

📝 设计理念

极简主义 - 只保留最核心的功能
易于理解 - 代码直白，注释清晰
快速上手 - 3 个命令即可开始使用
方便扩展 - 清晰的模块划分