# AiPYTask

**Repository Path**: mdunion/ai-pytask

## Basic Information

- **Project Name**: AiPYTask
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-10
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIPyApp 项目架构说明文档

## 1. 项目概述

AIPyApp 是一个基于"Python-Use"新范式的AI智能体应用，提出"AI驱动的Python和Python驱动的AI"理念。该项目旨在将大型语言模型(LLM)与Python解释器深度集成，构建一个完整的"任务→计划→代码→执行→反馈"循环，实现"没有智能体，代码就是智能体"的新型AI执行范式。

**核心哲学**：传统的AI智能体(Agent 1.0)依赖外部"假肢"(Function Calling、Tools、MCP-Servers、Workflows)，而AIPyApp让LLM直接使用Python代码与环境交互，实现真正的"AI Think Do"。

**主要特性**：
- 多模式运行：任务模式、Python模式、IPython模式、GUI模式、Agent HTTP服务器模式
- 自动代码生成与执行
- 智能上下文管理
- 插件系统扩展
- 多模态支持(图像、语音)
- 容器化部署

## 2. 技术栈

### 2.1 核心框架
- **Python版本**: >=3.11
- **包管理**: uv (现代Python包管理器)
- **构建工具**: hatchling + hatch-vcs
- **配置管理**: dynaconf
- **数据验证**: pydantic
- **日志系统**: loguru
- **国际化**: 自定义i18n系统

### 2.2 主要依赖库
| 类别         | 库                                | 用途                   |
| ------------ | --------------------------------- | ---------------------- |
| **AI/LLM**   | anthropic, openai, promptabs      | LLM客户端支持          |
| **UI/CLI**   | prompt-toolkit, rich, term-image  | 命令行界面和富文本显示 |
| **数据处理** | pandas, seaborn, openpyxl         | 数据分析和Excel处理    |
| **Web/网络** | fastapi, requests, beautifulsoup4 | HTTP服务器和网页抓取   |
| **工具协议** | mcp[cli]                          | 模型上下文协议支持     |
| **模板引擎** | jinja2                            | 提示词模板渲染         |
| **序列化**   | pyyaml, tomli-w                   | YAML和TOML支持         |

### 2.3 开发工具
- **测试框架**: pytest + pytest插件生态
- **代码检查**: ruff (替代flake8+black+isort)
- **持续集成**: GitHub Actions + GitLab CI
- **容器化**: Docker + 多阶段构建

## 3. 整体架构

### 3.1 架构图（概念层级）

```
┌─────────────────────────────────────────────────────────┐
│                    用户界面层                            │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │ CLI任务 │  │Python模式│  │IPython模式│  │ GUI模式 │   │
│  │  模式   │  │         │  │         │  │         │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                    应用协调层                            │
│  ┌──────────────────────────────────────────────────┐   │
│  │                 TaskManager                      │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │   │
│  │  │ClientMgr │ │PluginMgr │ │RoleMgr   │         │   │
│  │  └──────────┘ └──────────┘ └──────────┘         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │   │
│  │  │DisplayMgr│ │MCPToolMgr│ │Diagnose  │         │   │
│  │  └──────────┘ └──────────┘ └──────────┘         │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                    核心执行层                            │
│  ┌──────────────────────────────────────────────────┐   │
│  │                     Task                         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │   │
│  │  │ContextMgr│ │ToolCall  │ │EventBus  │         │   │
│  │  │          │ │Processor │ │          │         │   │
│  │  └──────────┘ └──────────┘ └──────────┘         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │   │
│  │  │Step      │ │CodeBlocks│ │Runtime   │         │   │
│  │  │          │ │          │ │          │         │   │
│  │  └──────────┘ └──────────┘ └──────────┘         │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                    基础设施层                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  LLM接口 │ │代码执行器│ │插件系统  │ │配置管理  │   │
│  │          │ │          │ │          │ │          │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
└─────────────────────────────────────────────────────────┘
```

### 3.2 架构特点

1. **模块化分层架构**：清晰的分层设计，各层职责明确
2. **领域驱动设计**：核心领域模型(Task、Step、CodeBlock等)贯穿整个系统
3. **事件驱动通信**：基于事件总线的松耦合组件通信
4. **插件化扩展**：支持通过插件系统扩展功能
5. **多运行时支持**：支持CLI、GUI、HTTP服务器等多种运行模式

## 4. 核心模块说明

### 4.1 aipyapp/ (主包)
- **`__main__.py`**：应用入口点，命令行参数解析和多模式路由
- **`runtime.py`**：应用运行时管理
- **`interface.py`**：公共接口定义(Event、EventBus等)
- **`i18n.py`**：国际化支持
- **`plugin.py`**：插件系统基类

### 4.2 aipy/ (核心AI引擎)
- **`task.py`**：任务模型(Task/TaskData)，核心领域实体
- **`taskmgr.py`**：任务管理器，协调所有子管理器
- **`config.py`**：配置管理(基于dynaconf)
- **`context.py`**：上下文管理(滑动窗口、重要性过滤等策略)
- **`events.py`**：强类型事件系统
- **`toolcalls.py`**：工具调用系统(支持AIPY、OPENAI、MCP等)
- **`runtime.py`**：Python运行时环境(CliPythonRuntime)
- **`step.py`**：任务步骤管理(Round模型)
- **`blocks.py`**：代码块管理(CodeBlock模型)
- **`client.py`**：LLM客户端包装
- **`response.py`**：LLM响应处理
- **`prompts.py`**：提示词管理
- **`features.py`**：功能特性管理

### 4.3 llm/ (LLM集成)
- **`manager.py`**：客户端管理器(ClientManager)，支持多LLM提供商
- **`base.py`**：基础消息类和接口
- **`config.py`**：LLM客户端配置
- **`client_*.py`**：各厂商客户端实现(Claude、Gemini、Ollama等)

### 4.4 exec/ (代码执行)
- **`executor.py`**：代码块执行器(BlockExecutor)
- **`python/`**：Python运行时环境
- **`types.py`**：执行结果类型定义

### 4.5 cli/ (命令行界面)
- **`cli_task.py`**：任务模式主界面
- **`cli_python.py`**：Python模式界面
- **`cli_ipython.py`**：IPython模式界面
- **`cli_agent.py`**：Agent HTTP服务器
- **`command/`**：命令系统(内建命令、自定义命令、自动补全)

### 4.6 gui/ (图形界面)
- **`main.py`**：GUI主窗口(基于wxPython)
- **`config.py`**：GUI配置
- **`providers.py`**：LLM提供商界面
- **`statusbar.py`**：状态栏管理

### 4.7 display/ (显示管理)
- **`manager.py`**：显示管理器(DisplayManager)
- **`base.py`**：显示协议抽象
- **`base_rich.py`**：基于Rich的显示插件
- **`themes.py`**：主题管理

### 4.8 plugins/ (插件系统)
- **`live_display.py`**：实时显示插件
- **`p_web_tools.py`**：Web工具插件
- **`p_style_*.py`**：各种显示样式插件

### 4.9 config/ (配置模块)
- **`base.py`**：配置基类
- **`llm.py`**：LLM配置管理

### 4.10 res/ (资源文件)
- **`prompts/`**：Jinja2提示词模板
- **`roles/`**：角色定义(aipy.toml)
- **`commands/`**：内建命令定义
- **`css/`, `js/`**：Web资源文件
- **`models.yaml`**：模型配置文件

## 5. 领域模型

### 5.1 核心领域实体

```python
# 任务实体
class TaskData(BaseModel):
    id: str                    # 任务ID
    version: int               # 任务版本
    depth: int                 # 任务深度(用于子任务)
    features: PromptFeatures   # 功能特性
    steps: List[StepData]      # 步骤列表
    blocks: CodeBlocks         # 代码块集合
    context: ContextData       # 上下文数据
    message_storage: MessageStorage  # 消息存储
    events: List[BaseEvent]    # 事件列表
    session: Dict[str, Any]    # 会话数据
    tools: List[Dict[str, Any]] # 工具列表

# 步骤实体
class Round(BaseModel):
    llm_response: Response            # LLM响应
    toolcall_results: List[ToolCallResult]  # 工具调用结果
    system_feedback: ChatMessage      # 系统反馈
    context_deleted: bool             # 上下文清理标记

# 代码块实体
class CodeBlock(BaseModel):
    name: str            # 代码块名称
    lang: str            # 编程语言
    code: str            # 代码内容
    path: Optional[str]  # 文件路径
    version: int         # 版本号
    deps: Dict[str, set] # 依赖关系
    co: CodeType         # 编译后的代码对象
```

### 5.2 领域服务

1. **TaskManager**：任务生命周期管理
2. **ContextManager**：智能上下文管理(支持多种策略)
3. **ToolCallProcessor**：工具调用处理
4. **ClientManager**：LLM客户端管理
5. **PluginManager**：插件管理

## 6. 通信机制

### 6.1 事件驱动架构
- **EventBus**：基于类型化事件的事件总线
- **BaseEvent**：所有事件的基类，使用Pydantic强类型定义
- **TypedEvent**：向后兼容的包装器

```python
# 事件定义示例
class BaseEvent(BaseModel):
    name: str = Field(..., title="Event Name")
    timestamp: float = Field(default_factory=lambda: time.time())
    
# 事件使用
class TaskStarted(BaseEvent):
    task_id: str
    instruction: str
```

### 6.2 管理器间通信
1. **直接依赖注入**：TaskManager初始化时注入所有子管理器
2. **回调机制**：插件系统通过回调函数扩展功能
3. **配置共享**：通过统一的Settings对象共享配置

### 6.3 进程间通信
- **HTTP API**：Agent模式提供RESTful API(n8n集成)
- **共享目录**：父子任务通过文件系统共享数据
- **环境变量**：任务间通过环境变量传递上下文

## 7. 部署架构

### 7.1 容器化部署
```dockerfile
# 多阶段构建
FROM ghcr.io/astral-sh/uv:alpine  # 使用uv作为包管理器
RUN apk add --no-cache ttyd        # 添加Web终端支持
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1
# ... 依赖安装和应用部署
EXPOSE 80
ENTRYPOINT ["/app/entrypoint.sh"]
```

### 7.2 部署模式
1. **本地CLI模式**：直接运行`aipy`命令
2. **Docker容器模式**：提供Web终端访问
3. **Agent服务器模式**：作为HTTP服务运行
4. **GUI桌面模式**：图形界面应用

### 7.3 持续集成/部署
- **GitHub Actions**：自动化测试和Docker镜像构建
- **GitLab CI**：企业级CI/CD支持
- **多架构支持**：支持Alpine和Debian基础镜像

## 8. 开发与构建

### 8.1 开发工作流
```bash
# 安装开发依赖
uv sync --dev

# 运行测试
pytest
pytest -m unit          # 仅单元测试
pytest -m integration   # 集成测试

# 代码检查
ruff check aipyapp tests
ruff format aipyapp tests

# 构建项目
python -m build
```

### 8.2 项目结构约定
- **模块化组织**：按功能划分模块目录
- **类型注解**：全面使用Python类型注解
- **PEP 8合规**：遵循Python编码规范
- **配置外部化**：所有配置支持外部文件覆盖
- **国际化**：支持多语言界面

### 8.3 扩展点
1. **插件开发**：通过`TaskPlugin`基类扩展功能
2. **角色定制**：通过TOML文件定义AI角色
3. **命令扩展**：支持自定义命令
4. **显示样式**：可自定义显示插件

## 9. 总结

AIPyApp采用先进的**模块化领域驱动设计**，结合**事件驱动架构**和**插件化扩展**，构建了一个高度灵活和可扩展的AI智能体平台。其核心创新在于将Python执行环境直接暴露给LLM，实现了"代码即智能体"的新范式。

**架构优势**：
- ✅ 清晰的层次分离，便于维护和扩展
- ✅ 强类型领域模型，提高代码可靠性
- ✅ 灵活的事件系统，支持松耦合组件通信
- ✅ 全面的插件机制，易于功能扩展
- ✅ 多模式运行，适应不同使用场景

**技术亮点**：
- 基于uv的现代Python开发工作流
- 使用pydantic进行数据验证和序列化
- 采用ruff统一代码检查和格式化
- 容器化部署支持Web终端访问
- 完整的国际化支持

该项目代表了AI智能体架构的新方向，通过简化工具链、强化代码执行能力，为AI与真实世界的交互提供了更直接、更强大的桥梁。