山东大学项目实训（五）DebateLab—多智能体辩论与复盘平台

本周工作概述日期2026.5.13本周主要完成了项目的两大核心基础设施建设日志系统和Skill 系统。这两个系统是整个辩论 Agent 框架的重要支撑为后续的功能扩展和系统稳定性奠定了坚实基础。一、日志系统建设1.1 系统架构设计日志系统采用分层设计包含三个核心层次配置层logging/config.py负责日志的初始化配置服务层logging/service.py提供统一的日志记录接口应用层各业务模块通过 LoggingService 调用日志功能1.2 核心功能实现多通道日志记录实现了5 个独立的日志通道每个通道服务于不同的业务场景API 日志通道api记录所有 HTTP 请求的详细信息包括请求端点、方法、请求数据、响应状态码用于追踪 API 调用链路服务层日志通道service记录业务逻辑层的运行状态包括辩论请求、自由辩论请求等业务事件用于监控核心业务流程LLM 调用日志通道llm_calls详细记录大模型的输入输出包含模型名称、消息内容、token 使用情况支持按天轮转保留 30 天历史记录用于分析 LLM 调用模式和优化 prompt工具调用日志通道tool_calls记录所有工具函数的调用情况包括工具名称、参数、返回结果支持按天轮转保留 30 天历史记录用于追踪 Agent 的工具使用行为参数校验日志通道validation记录参数校验失败的情况包括字段名、字段值、错误信息用于快速定位输入问题日志轮转与存储策略应用日志app.log基于大小轮转单文件最大 10MB保留 10 个备份错误日志error.log独立记录 ERROR 级别以上日志便于问题排查LLM 调用日志llm_calls.log按天轮转保留 30 天工具调用日志tool_calls.log按天轮转保留 30 天校验日志validation.log基于大小轮转记录 WARNING 级别以上结构化日志格式采用JSON 格式化关键业务日志包括时间戳、服务名、方法名错误类型、错误信息上下文信息context请求/响应数据1.3 集成应用日志系统已深度集成到项目的各个层面API 中间件层自动记录所有 HTTP 请求和响应服务层在 DebateService 中记录辩论请求处理流程错误处理在服务层错误时记录详细上下文参数校验在参数校验失败时记录具体字段和值1.4 技术亮点统一的日志接口通过 LoggingService 提供静态方法避免重复创建 logger异步安全所有日志方法均为同步阻塞避免并发问题性能优化使用缓存机制避免重复创建 handler可追溯性每条业务日志都包含完整的上下文信息可维护性日志级别和输出位置集中配置便于调整二、Skill 系统建设2.1 系统设计理念Skill 系统是辩论 Agent 的核心知识库用于约束和指导大模型在辩论各阶段的发言。系统采用文件化配置 动态加载的设计模式。2.2 核心组件SkillLoader技能加载器实现了完整的技能管理功能classSkillLoader:-初始化指定 skill 目录路径-解析 frontmatter提取技能元数据-加载所有技能头信息缓存机制优化性能-加载完整技能内容去除 frontmatter返回纯约束内容-缓存机制避免重复读取文件关键技术点使用 frontmatter 格式存储技能元数据name、description实现内容缓存减少文件 IO 操作支持动态指定技能目录便于测试和扩展Skill Tool技能工具创建了供大模型调用的工具函数tool(parse_docstringTrue)defload_skill_content(skill_name:str)-str:根据 skill 名称加载完整的 skill 约束内容功能特点通过 LangChain 的tool 装饰器封装支持自然语言调用返回完整的技能约束文本包括发言要求、语言风格、字数要求等2.3 技能库建设目前已完成5 个核心辩论阶段的技能定义1开篇立论技能skill_opening_statement功能约束开篇立论阶段的发言核心要求开场问候与立场表明关键概念定义核心论点阐述2-3 个论点价值升华与总结字数200-500 字2攻辩/质询技能skill_cross_examination功能约束攻辩环节的质询和回应核心要求提出有力的质询问题封闭式问题优先准备回应对方可能的反驳适当进行论点补充字数200-500 字3攻辩小结技能skill_cross_summary功能总结攻辩环节为后续做铺垫核心要求总结己方在攻辩中的优势指出对方论证的漏洞为自由辩论和总结陈词做铺垫字数200-500 字4自由辩论技能skill_free_debate功能约束自由辩论阶段的快速反驳核心要求针对对方观点进行反驳维护己方核心论点积极参与节奏紧凑字数100-300 字较短5总结陈词技能skill_closing_statement功能约束总结陈词阶段的收尾发言核心要求总结己方核心论点反驳对方主要观点升华主题强调立场字数300-600 字较长2.4 技能文件格式规范每个技能采用统一的 Markdown 文件格式SKILL.md--- name: skill_name description: 技能描述 --- # 技能标题 ## 技能描述 ... ## 发言要求 ### 1. 要求 - 子要求 1 - 子要求 2 ## 语言风格 - 风格 1 - 风格 2 ## 字数要求 ... ## 注意事项 - 注意 1 - 注意 22.5 与 Agent 系统集成Skill 系统已深度集成到 Debater 类中classDebaterWithSkillState(TypedDict):messages:List topic:strside:strposition:strstage:stropponent_speech:Optional[str]debate_history:List[dict]current_round:intskill_headers:List[dict]# 可用技能列表selected_skill:Optional[str]# 已选择的技能工作流程初始化时加载所有技能头信息在发言生成节点中提供 skill_tool 给大模型大模型根据当前阶段和辩论历史判断是否需要调用 skill_tool调用 skill_tool 获取完整技能约束将技能约束注入 prompt生成符合要求的发言2.6 技术亮点模块化设计每个技能独立成文件夹便于维护和扩展缓存优化技能内容和头信息均实现缓存减少 IO 操作工具化调用通过 LangChain tool 实现自然语言调用结构化约束统一的文件格式便于解析和使用可扩展性新增技能只需添加对应文件夹和 SKILL.md 文件三、技术难点与解决方案3.1 日志系统难点难点 1多通道日志的并发安全问题多个线程同时写入日志可能导致内容混乱解决使用 Python logging 模块的内置锁机制所有 handler 线程安全难点 2日志轮转与备份管理问题需要同时支持基于大小和基于时间的轮转策略解决针对不同日志类型选择合适的 handlerRotatingFileHandler / TimedRotatingFileHandler难点 3结构化日志的性能开销问题JSON 格式化可能影响日志性能解决仅在关键业务日志使用 JSON 格式化普通日志使用简单格式3.2 Skill 系统难点难点 1技能内容的动态加载问题需要在运行时根据大模型调用动态加载技能解决实现 SkillLoader 缓存机制首次加载后缓存到内存难点 2技能与 Agent 状态的集成问题需要将技能信息融入 Agent 的状态管理解决扩展 DebaterWithSkillState添加 skill_headers 和 selected_skill 字段难点 3技能调用的时机判断问题大模型需要知道何时调用哪个技能解决在 prompt 中提供技能头信息列表让大模型自主判断四、总结本周完成的日志系统和 Skill 系统是项目的两大基础设施日志系统为整个项目提供了可观测性让每一次 API 调用、每一次 LLM 交互、每一次工具调用都有迹可循大大提升了系统的可维护性和可调试性。Skill 系统为辩论 Agent 提供了专业知识库通过结构化的技能约束确保大模型在各个辩论阶段的发言都符合专业要求显著提升了辩论质量和专业性。两个系统的设计都遵循了高内聚低耦合的原则具有良好的可扩展性和可维护性为后续功能开发奠定了坚实基础。