# SoftwareDevHelper 智能体设计文档

## 1. 智能体概述

**名称**：SoftwareDevHelper
**角色**：专业的软件开发学习助手
**目标**：为软件开发初学者提供个性化的学习体验，包括水平评估、智能出题、开发指导以及自动化的代码测试与打分。
**核心框架**：基于 `HelloAgents` 框架的 `SimpleAgent` 范式构建。

## 2. 系统提示词 (System Prompt)

智能体的行为和职责由以下系统提示词严格定义：

```text
你是一个专业的软件开发学习助手。你的职责是：
1. 使用 user_memory 工具了解用户的当前编程水平和历史做题记录。
2. 根据用户水平，为他们出适合的编程题目，或者从网上搜索真实的开发案例。
3. 在用户开发过程中，提供有针对性的建议和指导。
4. 当用户完成开发并上传项目压缩包后，你需要：
   - 仔细分析题目要求。
   - 编写严谨的 pytest 测试用例代码。
   - 使用 code_test 工具，传入压缩包路径和你的测试代码，对用户的项目进行自动化测试。
   - 根据测试结果给出最终打分和详细的代码审查反馈。
5. 任务完成后，使用 user_memory 工具更新用户的水平评估和做题记录。

请始终保持鼓励和专业的态度。
```

## 3. 工具与技能 (Tools & Skills)

该智能体挂载了两个核心的自定义工具，用于实现与外部环境（文件系统、测试环境、记忆库）的交互：

### 3.1 UserMemoryTool (用户记忆工具)
- **功能**：管理用户的编程水平和做题历史记录。实现跨会话的个性化记忆。
- **参数**：
  - `action` (string, 必填)：操作类型，可选 `'get'`（读取记忆）或 `'update'`（更新记忆）。
  - `level` (string, 选填)：用户的新水平评估（例如 'beginner', 'intermediate', 'advanced'）。
  - `record` (string, 选填)：新完成的题目记录。
- **底层实现**：将数据持久化存储在后端的 `data/user_memory.json` 文件中。

### 3.2 CodeTestTool (代码自动测试工具)
- **功能**：接收用户上传的项目压缩包，自动解压，并运行由 LLM 动态生成的测试代码，最后给出评分。
- **参数**：
  - `zip_path` (string, 必填)：用户上传的项目压缩包绝对路径。
  - `test_code` (string, 必填)：由智能体根据题目要求动态生成的 `pytest` 测试代码。
- **底层实现**：
  1. 清理并创建解压目录 `outputs/extracted`。
  2. 使用 `zipfile` 解压用户代码。
  3. 将 `test_code` 写入 `test_generated.py`。
  4. 使用 `subprocess` 调用 `pytest` 运行测试，并捕获标准输出和错误信息。
  5. 根据退出码（`returncode`）给出 100 分（全过）或 0 分（有失败），并返回详细的测试日志供智能体分析。

## 4. 交互流程 (Workflow)

1. **初始化/对话**：用户进入系统，智能体通过 `UserMemoryTool` 获取用户的当前水平（如 beginner）和历史记录。
2. **出题阶段**：智能体根据记忆信息，生成难度适宜的编程题目。
3. **开发与指导**：用户在本地开发，期间可通过聊天界面向智能体请教问题，智能体提供代码建议。
4. **提交与测试**：
   - 用户通过前端上传 `.zip` 格式的项目代码。
   - 后端接收文件并保存，将文件路径以系统消息形式发送给智能体。
   - 智能体编写对应的 `pytest` 测试用例（支持子目录模块动态导入）。
   - 智能体调用 `CodeTestTool` 执行自动化测试。
5. **反馈与更新**：
   - 智能体根据测试输出日志，为用户提供打分和代码审查报告。
   - 智能体调用 `UserMemoryTool` 将本次题目记录到历史中，并视情况升级用户的水平等级。

## 5. 交互设计 (Interaction Design)

- **输入输出格式**：
  - 用户输入：自然语言文本、代码片段、项目压缩包 (.zip)。
  - 智能体输出：格式化的 Markdown 文本、工具调用可视化控件（实时展示工具调用的参数与结果）。
- **用户界面 (UI)**：
  - 基于 Web 的聊天界面，提供清晰的对话流。
  - 支持多会话管理，左侧边栏显示历史会话列表，支持切换和删除。
  - 右侧边栏实时展示用户的当前水平和历史做题记录。
  - 聊天气泡内嵌专门的 UI 控件，用于优雅地展示智能体后台调用工具的详细过程。
- **反馈机制**：
  - 在打分后，提供详细的代码审查反馈，指出优点和改进空间。
  - 当测试失败时，明确指出是逻辑错误还是项目结构错误，并提供修改建议。
  - 在执行工具操作前，智能体会先向用户解释即将进行的操作，保持透明度。

## 6. 配置说明

- **模型配置**：默认使用配置在 `.env` 中的大语言模型（如 `Qwen/Qwen2.5-72B-Instruct`、`Gemini` 或 `Azure OpenAI`）。
- **特殊配置**：为兼容部分严格校验 JSON Schema 的模型（如 Azure/Gemini），在初始化 `SimpleAgent` 时，通过 `Config(todowrite_enabled=False)` 禁用了框架内置的 `TodoWrite` 工具。