# 物理竞赛 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\ 目录承载。