基于 HelloAgents 构建 SoftwareDevHelper从出题、测试到打分的软件开发学习助手【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读SoftwareDevHelper 是 HelloAgents 社区共创项目中一个面向软件开发初学者的智能学习助手它把「记忆用户水平 → 按水平出题 → 开发指导 → 上传项目自动测试打分 → 更新学习轨迹」串成一条完整的个性化学习闭环。本文基于 Co-creation-projects/angelen-SoftwareDevHelper 仓库剖析其基于 HelloAgentsSimpleAgent范式与两个自定义工具的实现原理并给出可直接运行的部署步骤与每个核心模块的源码级解读。读完你将掌握如何用 HelloAgents 的自定义工具Tool实现持久化记忆与外部命令执行如何用 FastAPI 支撑多会话 Web 交互以及如何实现「LLM 动态生成 pytest 测试用例并对用户代码自动打分」的全链路方案。一、项目概览它解决了什么问题初学者的编程学习往往缺乏针对性与即时反馈题目难度要么过难要么过易写完代码没有人帮忙审阅和打分。SoftwareDevHelper 的答案是让智能体扮演「懂你的私教」记忆用户水平跨会话记住用户是 beginner / intermediate / advanced以及历史做题记录按水平出题根据记忆动态生成难度适配的编程题或从网上搜索真实开发案例开发过程指导开发中随时提问智能体提供代码审查与优化建议自动化测试打分用户上传.zip项目压缩包智能体自动编写 pytest 测试用例、执行测试并给出评分闭环更新测试完成后把题目记录写回记忆视情况升级用户水平等级。项目采用前后端分离架构前端为 HTML5 CSS3 Vanilla JavaScript后端为 Python FastAPI Uvicorn智能体核心基于 HelloAgents 框架的SimpleAgent。这一划分可以在仓库的 README 与目录结构src/、frontend/中得到印证。二、技术栈与依赖清单层次技术选型说明智能体框架HelloAgentsSimpleAgent、ToolRegistry、Tool 等负责对话推理与工具调度后端框架FastAPI Uvicorn提供 REST API 与静态资源服务前端HTML5 / CSS3 / Vanilla JavaScript聊天界面、会话侧边栏、用户档案栏大模型预留多模型接口如 Qwen 等通过.env配置LLM_API_KEY/LLM_BASE_URL/LLM_MODEL_ID工具链Pythonzipfile、subprocess、pytest解压、执行测试、采集测试输出依赖清单位于 requirements.txt核心为hello-agents[all]0.2.7、fastapi0.109.0、uvicorn0.27.0、python-multipart0.0.9、python-dotenv1.0.0、pytest8.0.0。其中python-multipart是 FastAPI 处理文件上传UploadFile/Form的必需依赖python-dotenv负责加载.env配置。三、智能体核心System Prompt 与 SimpleAgent 装配智能体的全部行为由 src/agents/helper_agent.py 中的get_helper_agent()装配这是理解整个项目的钥匙。它完成了三件事创建ToolRegistry并注册两个自定义工具UserMemoryTool()与CodeTestTool()从环境变量读取LLM_MODEL_ID默认Qwen/Qwen2.5-72B-Instruct构造HelloAgentsLLM用系统提示词 工具注册表 配置项构造SimpleAgent(nameSoftwareDevHelper, ...)。系统提示词严格定义了智能体的工作流与 Agent_Design.md 中记录的一致你是一个专业的软件开发学习助手。你的职责是 1. 使用 user_memory 工具了解用户的当前编程水平和历史做题记录。 2. 根据用户水平为他们出适合的编程题目或者从网上搜索真实的开发案例。 3. 在用户开发过程中提供有针对性的建议和指导。 4. 当用户完成开发并上传项目压缩包后你需要 - 仔细分析题目要求。 - 编写严谨的 pytest 测试用例代码。注意用户的代码通常在解压目录的某个子文件夹中 如 test-projects/main.py你的测试代码需要能够递归查找 .py 文件并动态导入模块 而不是简单地假设代码在当前目录下。可以参考使用 sys.path.insert(0, str(project_root)) 来辅助导入。 - 使用 code_test 工具传入压缩包路径和你的测试代码对用户的项目进行自动化测试。 - 根据测试结果给出最终打分和详细的代码审查反馈。 5. 任务完成后使用 user_memory 工具更新用户的水平评估和做题记录。 请始终保持鼓励和专业的态度。一个值得注意的细节是装配时的特殊配置from hello_agents.core.config import Config # 禁用 TodoWrite 工具避免在 Azure/Gemini 下出现 schema 验证错误 config Config(todowrite_enabledFalse)从源码注释可以推断部分严格校验 JSON Schema 的模型如 Azure / Gemini无法兼容框架内置TodoWrite工具的 schema因此通过Config(todowrite_enabledFalse)显式关闭该内置工具。这一做法展示了 HelloAgentsConfig的细粒度开关能力也提示了在多模型环境下部署时需要关注内置工具的 schema 兼容性。四、两个自定义工具记忆与测试的底层实现HelloAgents 中自定义工具需要继承Tool基类实现run(parameters)与get_parameters()两个方法前者是执行逻辑后者向 LLM 声明可用的参数 schema。本项目的两个工具分别负责「记忆」与「测试」是系统闭环的两大支柱。4.1 UserMemoryTool跨会话的用户水平记忆该工具helper_agent.py把用户水平与做题记录持久化到data/user_memory.json参数 schemaactionstring必填get读取记忆update更新记忆levelstring选填新的水平评估如beginner、intermediate、advancedrecordstring选填新完成的题目记录。实现细节__init__中调用_ensure_memory_file()保证 JSON 文件存在缺失时初始化为{level: beginner, history: []}action get时直接序列化返回整个记忆对象action update时按需写入level并向history追加record。返回值统一使用ToolResponse.success(text...)/ToolResponse.error(text...)成功或失败信息以文本形式回传给 LLM 分析。记忆的「跨会话共享」还体现在后端main.py中GET/POST /api/user_memory与DELETE /api/user_memory直接操作同一份user_memory.json前端右侧边栏因此能实时展示和修改用户档案水平下拉框、做题记录列表、清空按钮。4.2 CodeTestTool解压 → 写测试 → 跑 pytest → 打分该工具helper_agent.py实现了「全链路自动化测试」的核心逻辑run依次执行参数校验要求zip_path用户上传压缩包绝对路径与test_codeLLM 动态生成的 pytest 测试代码都存在否则返回错误解压清理旧的outputs/extracted目录后用zipfile.ZipFile(...).extractall(...)解压用户代码写入测试文件把test_code写入解压目录下的test_generated.py执行测试通过subprocess.run([pytest, test_file_path, -v], cwdself.extract_dir, capture_outputTrue, textTrue, timeout30)运行测试-v输出详细日志timeout30防止测试挂死对subprocess.TimeoutExpired单独返回「测试执行超时」评分当前版本采用简单评分逻辑score 100 if result.returncode 0 else 0README 中亦说明可按 pytest 输出优化并把score、test_outputstdoutstderr、status打包为 JSON 返回供智能体做代码审查与反馈。这里有两个值得展开的实战要点子目录模块动态导入由于用户代码通常嵌套在解压目录的子文件夹如test-projects/main.py系统提示词明确要求 LLM 生成的测试代码「递归查找.py文件并动态导入模块」并提示使用sys.path.insert(0, str(project_root))辅助导入。这正是 README 中提到的「避免了暴力全量导入导致触发 Pythonantigravity彩蛋的问题」——即不能简单粗暴地对解压目录下所有.py文件做全量 import而应有选择地按项目结构动态加载被测模块。沙箱隔离意识测试在独立子进程subprocess中执行并限制超时既避免污染服务进程也降低用户代码对后端的影响。五、多会话管理后端持久化 上下文恢复SimpleAgent默认在内存中保存对话历史为支持多会话src/main.py 采用了「内存缓存 Agent 实例 磁盘持久化会话」的组合方案agent_sessions {}字典以session_id为键缓存 Agent 实例get_or_create_agent(session_id)负责惰性创建创建时若磁盘上已有会话文件data/sessions/{session_id}.json则把messages历史逐条恢复为hello_agents.core.message.Message注入agent._history。源码注释特别强调恢复时只恢复纯文本忽略 tool_calls避免不完整的工具调用记录在后续请求中导致大模型调用报错——这是多会话场景下上下文恢复的稳健性细节save_session_history()每次请求后把消息含tool_calls、时间戳追加写入 JSON并维护会话title与updated_at。对应的 REST API方法路径作用GET/api/sessions列出全部会话按updated_at倒序GET/api/sessions/{session_id}获取某个会话的消息历史DELETE/api/sessions/{session_id}删除会话同时清理内存缓存POST/api/chat发送文本消息自动创建会话、保存历史、返回工具调用信息POST/api/upload_project上传.zip项目触发智能体自动测试打分流程GET/POST/DELETE/api/user_memory*读取 / 更新 / 重置用户记忆其中/api/chat的实现值得细看它在调用agent.run(message)前后分别记录len(agent.get_history())随后遍历运行期间新增的消息把 assistant 消息中的tool_calls工具名、参数 JSON与对应 tool 角色的执行结果配对随响应一起返回给前端。这正是「工具调用可视化」的数据来源。六、前端交互会话侧边栏、用户档案与工具调用可视化前端是纯静态三栏布局index.html左栏新建会话按钮 会话列表每条会话可点击切换、悬停出现删除按钮删除时先弹窗确认再调用 DELETE 接口带 300ms 淡出动画中栏聊天区 输入区文本框与「上传项目 (.zip)」按钮右栏用户档案含水平下拉框beginner / intermediate / advanced、做题记录列表与「清空」按钮。app.js 中的addMessage(text, isUser, toolCalls)实现了工具调用可视化若消息携带tool_calls会先渲染一组「工具调用块」每个块展示️ 调用工具: name、格式化后的「输入参数」与「执行结果」尝试JSON.parse 2 空格缩进美化失败则原样展示。这样用户在聊天界面就能实时看到智能体后台「读取记忆 → 调用 code_test → 更新记忆」的完整过程增加透明度和可信度。前端还实现了完整的会话状态管理currentSessionId为null表示新会话首次发消息后端返回session_id后自动接管切换会话时重新拉取历史消息并逐条渲染含工具调用块聊天后主动刷新会话列表与用户记忆保证「智能体更新记忆 → 侧边栏即时同步」。七、自动化测试闭环一次完整的项目提交结合 Agent_Design.md 与后端源码一次「出题 → 开发 → 提交 → 打分」的完整流程如下初始化智能体调用user_memory的get动作获取用户当前水平与历史记录出题根据水平生成难度适配的题目或搜索真实案例开发指导用户在本地开发过程中随时向智能体提问获得针对性建议提交用户在前端上传.zip压缩包/api/upload_project把文件以{uuid}_{filename}保存到outputs/uploads/并构造提示词「请根据当前题目要求编写 pytest 测试用例并使用 code_test 工具进行测试打分最后给出反馈并更新用户水平记录」驱动智能体测试智能体编写 pytest 用例支持子目录动态导入→ 调用code_test解压、写test_generated.py、运行pytest -v、返回评分与测试日志反馈与更新智能体依据测试输出给出打分和代码审查报告区分逻辑错误与项目结构错误随后调用user_memory的update动作记录题目并视情况升级水平前端侧边栏同步刷新。这一闭环把「因材施教」记忆机制、「全链路自动化」出题到打分与「前后端分离」清晰架构、易于扩展三个项目亮点落到了实处。八、快速开始本地部署与运行环境要求Python 3.10推荐 Conda 环境。以下步骤与仓库 README 保持一致1. 安装依赖pip install -r requirements.txt2. 配置 API 密钥cp .env.example .env.env文件内容示例需替换为真实密钥LLM_API_KEYyour_api_key_here LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/ LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct3. 运行项目conda activate hello-agent-homework cd Co-creation-projects/angelen-SoftwareDevHelper export PYTHONPATH$PYTHONPATH:$(pwd) uvicorn src.main:app --reload打开浏览器访问http://127.0.0.1:8000即可开始对话。常见问题排查修改.env后不生效uvicorn --reload默认只监听.py文件变化改完 API Key 或模型配置后需Ctrl C停止服务并重新启动端口被占用若报[Errno 48] Address already in use可换端口启动uvicorn src.main:app --reload --port 8001或用lsof -ti :8000 | xargs kill -9释放 8000 端口macOS/Linux。注意.env文件由src/main.py通过load_dotenv(os.path.join(os.path.dirname(__file__), ../.env))加载即相对于src/上一级目录因此请将.env放在项目根目录。九、从源码结构看可扩展方向从目录结构与源码可以推断该项目预留了清晰的扩展点数据目录约定data/sessions/会话、data/user_memory.json用户记忆、outputs/uploads/上传压缩包、outputs/extracted/解压目录职责分明可轻松对接更复杂的存储方案src/utils/为空目录说明工具与逻辑还可进一步抽取复用打分逻辑returncode 0 ? 100 : 0在源码注释中明确标注「可根据 pytest 输出优化」例如按通过用例比例计算得分是升级评分精度的天然切入点多模型适配Config(todowrite_enabledFalse)展示了 HelloAgents 配置项的灵活性为接入 Azure / Gemini 等对 schema 严格校验的模型扫清了障碍。十、总结SoftwareDevHelper 是一个麻雀虽小、五脏俱全的 HelloAgents 实战范例它以SimpleAgent为大脑以UserMemoryTool与CodeTestTool为双手以 FastAPI 为躯干以三栏 Web 界面为面孔完整演示了「记忆 → 出题 → 指导 → 自动测试 → 打分 → 记忆更新」的教育类 Agent 闭环。对于想学习 HelloAgents 自定义工具开发、多会话上下文恢复、LLM 驱动动态测试生成的开发者而言这份仓库的源码helper_agent.py、main.py与设计文档Agent_Design.md都是不可多得的参考。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考