物理竞赛 AI Agent 框架 - 项目总览与使用指南

项目简介

这是一套针对大学物理实验(声速测量)的 模块化 AI Agent 框架。 系统已从早期的单一长提示词文档,重构为代码可驱动执行的模块化架构,并保留了对 Web UI 的快速集成能力。

本系统提供三种核心 AI 教学角色:

  1. 疑问解答老师 (QA Teacher):引导学生完成实验预习,解答理论与操作疑问。
  2. 答题评估老师 (Grader Teacher):根据标准答案评分,并提供启发式反馈。
  3. 数据评价老师 (Data Eval Teacher):针对学生的实验测量数据,评估误差并指出潜在的操作缺陷。

核心目录结构

\\ ext / README.md # 本文档,项目总览与入口 run_agents.py # 核心运行脚本(基于 AutoGen 的终端测试入口) config.env.example # 环境变量示例(需配置模型 API Key) components/ # (规划中/逻辑映射)模块化提示词与知识库 personas/ # AI 角色设定(背景、语气、教学风格) tasks/ # 工作流要求(评估步骤、JSON 输出格式要求等) data/ # 领域知识库(专业词汇表、评分标准等 RAG 语料) json-schemas/ # 严格的结构化输出 JSON 协议 docs/ # 补充参考与文档 示例对话与快速参考.md # 典型交互用例与知识点速查 web_app_integration/ # Web / 云端集成代码与模板 prompts/ # 重点:专为 Web 云函数一键粘贴准备的合体版提示词模板 cloudfunctions/ # 腾讯云开发 (CloudBase) 云函数 Node.js 源码示例 archive/ # 归档目录(存放早期的冗余单一文档,过渡期后删除) \\


快速开始:本地运行测试

本系统支持在终端中直接进行调试与体验,动态拼装 personas/ 和 asks/ 中的提示词。

1. 环境准备

确保你已安装 Python 3.8+,并安装依赖: \\ash pip install pyautogen python-dotenv \\

2. 配置 API Key

在项目根目录创建 .env\ 文件(可复制自 \config.env.example\ 无则自建),并填入你的大模型配置: \\env

示例:使用 DeepSeek 或千问等兼容 OpenAI 格式的模型

OPENAI_API_KEY=your_api_key_here OPENAI_BASE_URL=https://api.deepseek.com/v1 MODEL_NAME=deepseek-chat \\

3. 运行交互引擎

\\ash python run_agents.py \\ 按照终端提示,选择 1(疑问)、2(评估)或 3(数据)对应的老师,即可开始交互。


快速开始:Web/云函数集成

对于前端开发者或需要在真实业务中集成该 Agent 的场景:

方案 A:直接复制一键提示词

如果您使用的是低代码平台(如 Coze, Dify)或只想要一个完整的 System Prompt: 请前往 \web_app_integration/prompts/\ 目录,直接复制对应老师的 .md\ 文件全文即可。 注意:这三份文件由 \personas\ + \ asks\ + \data\ 拼装而成,方便直接粘贴。作为单一事实来源(SSOT),深度的逻辑修改请优先更新基础模块。

方案 B:完整云开发部署

参考 \Web应用集成指南.md\(位于根目录或 web_app_integration 目录)。该指南包含:

  • CloudBase 云函数具体实现(Node.js SDK 调用)
  • 结构化 JSON 返回的处理策略
  • 前端 React 组件接入示例

进阶:如何修改 AI 逻辑

系统采用 Prompt as Code (模块化) 设计。如果您发现 AI 回答不符合预期,请定位并修改以下文件,而非修改整个长提示词:

  1. 语气或人设不好? -> 修改 \personas/xxx-teacher.md\
  2. 处理流程/评分标准不对? -> 修改 \ asks/xxx.md\ 或 \data/grading-standards.md\
  3. 前端解析 JSON 报错? -> 检查并修改 \json-schemas/evaluation-schema.json\
  4. 术语解释不准? -> 扩充 \data/physics-glossary.md\

修改完成后,重新执行 \python run_agents.py\ 验证效果。当认为效果稳定后,请同步把修改更新到 \web_app_integration/prompts/\ 下的集成模板中。


关于文件清理的说明

2026年4月重构记录: 原根目录下的三份千行提示词:

  • \疑问解答老师.md\
  • \数据评价老师.md\
  • \声速测量实验答题评估老师.md
    现已移动至 \rchive/\ 目录进行归档,未来将彻底删除。当前所有业务逻辑均由拆分后的 \personas\ 和 \ asks\ 目录承载。
仓库描述
React驱动的答题页面
自述文档 22 MiB
编程语言
Python 100%