feature

Feature：项目内功能开发

概述

基于项目架构文档（docs/ARCHITECTURE.md）的规范，安全地实现新功能或修改现有代码。

核心原则：先读懂再改，先规划再动手。改一处代码前，先理解它为什么是现在这样。

何时使用

• 用户要求开发新功能或优化现有代码
• 需要修复 bug，且需要理解项目上下文才能定位
• 代码需要重构以对齐架构规范
• 何时不用：纯文档修改、配置调整、不需要理解项目上下文的简单操作

流程

1. 加载上下文

   • 必须先读 docs/ARCHITECTURE.md，理解项目的系统架构、中间件规范、工具链配置
   • 确认本次改动是否涉及架构文档中描述的关键路径（如中间件、Agent 配置、MCP 工具链）
   • 如果架构文档过时或缺失，先运行 understand skill 更新它

2. 定位与规划

   • 找到需要修改的文件，理解现有逻辑
   • 不要直接覆盖——先读懂函数的输入/输出/调用方
   • 简述修改计划再动手

3. 代码实现

   • 保持与现有项目的代码风格一致（命名、异步处理、错误处理方式）
   • 涉及 MCP 工具调用时参考 tools.py 的包装策略
   • 涉及中间件修改时参考 middleware.py 的多层级拦截逻辑
   • 新增代码要有完善的错误处理，不能裸 except: pass

4. 自我验证

   • 确认修改没有破坏 config.py 的配置结构
   • 确认没有引入架构文档中明确禁止的模式
   • 跑一次冒烟测试确认改动生效

产出

• 修改后的代码文件
• 如涉及架构变化，同步更新 docs/ARCHITECTURE.md

常见错误

• 跳过上下文直接改 → 不读架构文档就动手，容易破坏约定（如中间件顺序、工具包装方式）
• 改了代码不更新文档 → ARCHITECTURE.md 必须与代码保持同步，否则下次进来的 agent 会基于过时信息决策
• except: pass 吞异常 → 会掩盖真实错误（如 override() API 用法错误），禁止裸吞异常

参考

• 项目架构文档：docs/ARCHITECTURE.md（开发前必读）