本周工作概述
日期：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_docstring=True)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：日志轮转与备份管理
- 问题：需要同时支持基于大小和基于时间的轮转策略
- 解决：针对不同日志类型选择合适的 handler（RotatingFileHandler / TimedRotatingFileHandler）
难点 3：结构化日志的性能开销
- 问题：JSON 格式化可能影响日志性能
- 解决：仅在关键业务日志使用 JSON 格式化，普通日志使用简单格式
3.2 Skill 系统难点
难点 1：技能内容的动态加载
- 问题：需要在运行时根据大模型调用动态加载技能
- 解决：实现 SkillLoader 缓存机制，首次加载后缓存到内存
难点 2：技能与 Agent 状态的集成
- 问题：需要将技能信息融入 Agent 的状态管理
- 解决：扩展 DebaterWithSkillState，添加 skill_headers 和 selected_skill 字段
难点 3：技能调用的时机判断
- 问题：大模型需要知道何时调用哪个技能
- 解决：在 prompt 中提供技能头信息列表，让大模型自主判断
四、总结
本周完成的日志系统和 Skill 系统是项目的两大基础设施：
日志系统为整个项目提供了可观测性，让每一次 API 调用、每一次 LLM 交互、每一次工具调用都有迹可循，大大提升了系统的可维护性和可调试性。
Skill 系统为辩论 Agent 提供了专业知识库，通过结构化的技能约束，确保大模型在各个辩论阶段的发言都符合专业要求，显著提升了辩论质量和专业性。
两个系统的设计都遵循了高内聚低耦合的原则，具有良好的可扩展性和可维护性，为后续功能开发奠定了坚实基础。
