4.5 KiB
物理竞赛 AI Agent 框架 - 项目总览与使用指南
项目简介
这是一套针对大学物理实验(声速测量)的 模块化 AI Agent 框架。 系统已从早期的单一长提示词文档,重构为代码可驱动执行的模块化架构,并保留了对 Web UI 的快速集成能力。
本系统提供三种核心 AI 教学角色:
- 疑问解答老师 (QA Teacher):引导学生完成实验预习,解答理论与操作疑问。
- 答题评估老师 (Grader Teacher):根据标准答案评分,并提供启发式反馈。
- 数据评价老师 (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 回答不符合预期,请定位并修改以下文件,而非修改整个长提示词:
- 语气或人设不好? -> 修改 \personas/xxx-teacher.md\
- 处理流程/评分标准不对? -> 修改 \ asks/xxx.md\ 或 \data/grading-standards.md\
- 前端解析 JSON 报错? -> 检查并修改 \json-schemas/evaluation-schema.json\
- 术语解释不准? -> 扩充 \data/physics-glossary.md\
修改完成后,重新执行 \python run_agents.py\ 验证效果。当认为效果稳定后,请同步把修改更新到 \web_app_integration/prompts/\ 下的集成模板中。
关于文件清理的说明
2026年4月重构记录: 原根目录下的三份千行提示词:
- \疑问解答老师.md\
- \数据评价老师.md\
- \声速测量实验答题评估老师.md
现已移动至 \rchive/\ 目录进行归档,未来将彻底删除。当前所有业务逻辑均由拆分后的 \personas\ 和 \ asks\ 目录承载。