Tangledup-ai/lang-agent
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
lang-agent/.trae/rules/project_rules.md
Therainclouds bb91a68c78 feat: 添加项目文档和配置更新 
docs: 完善README文档结构和内容
refactor: 更新配置类注释和文档字符串
style: 统一代码格式和命名规范
fix: 修正MCP服务器配置和依赖项
2025-11-07 15:50:22 +08:00

5.8 KiB
Raw Permalink Blame History

LangChain Agent 项目编写规则

1. 项目概述

本项目是一个基于LangChain的AI助手系统，专注于茶饮场景的智能对话和工具调用。项目采用模块化设计，支持多种LLM后端和MCP工具集成。

2. 编码风格规范

2.1 基本原则

  • 代码简洁明了，避免过度设计
  • 保持一致的命名约定和代码结构
  • 注重可维护性和可扩展性
  • 遵循Python PEP 8编码规范

2.2 命名约定

  • 类名：PascalCase (例：ToolManager, PipelineConfig)
  • 函数/变量名：snake_case (例：get_tools, tool_manager)
  • 常量：UPPER_SNAKE_CASE (例：DEFAULT_HOST, MAX_RETRIES)
  • 私有成员：单下划线前缀 (例：_internal_method)
  • 特殊方法：双下划线 (例：__init__, __post_init__)

2.3 注释规范

  • 类和公共方法必须有文档字符串
  • 注释采用中英文混合，核心概念使用中文解释
  • 复杂逻辑必须添加行内注释
  • 文档字符串格式：
def method_name(param1: str, param2: int) -> bool:
    """
    方法功能简述
    
    Args:
        param1: 参数1说明
        param2: 参数2说明
        
    Returns:
        返回值说明
    """

3. 配置管理规范

3.1 配置类设计

  • 使用dataclass或pydantic模型定义配置类
  • 所有配置类必须继承自InstantiateConfig或PydanticBaseModel
  • 配置类必须包含_target字段，指向对应的实现类
  • 配置类必须实现setup()方法，用于实例化目标对象

3.2 配置类示例

@tyro.conf.configure(tyro.conf.SuppressFixed)
@dataclass
class ExampleConfig(InstantiateConfig):
    _target: Type = field(default_factory=lambda: ExampleClass)
    
    param1: str = "default_value"
    """参数1说明"""
    
    param2: int = 10
    """参数2说明"""
    
    def setup(self) -> ExampleClass:
        return self._target(self)

3.3 配置文件管理

  • 使用YAML格式存储配置文件
  • 配置文件放在configs/目录下
  • 敏感信息(如API密钥)通过环境变量获取
  • 支持配置文件覆盖和合并

4. Pydantic集成规范

4.1 使用场景

  • API请求/响应模型定义
  • 数据验证和序列化
  • 配置管理(与dataclass并存)
  • 复杂数据结构定义

4.2 Pydantic模型设计

  • 继承自PydanticBaseModel基类
  • 使用类型注解明确字段类型
  • 提供默认值和验证规则
  • 使用Field类添加元数据

4.3 Pydantic模型示例

class ExampleModel(PydanticBaseModel):
    name: str = Field(..., description="名称")
    count: int = Field(default=0, ge=0, description="计数")
    tags: List[str] = Field(default_factory=list, description="标签列表")
    
    class Config:
        extra = "forbid"  # 禁止额外字段

5. 工具开发规范

5.1 工具基类

  • 所有工具必须继承自LangToolBase
  • 实现get_tool_fnc()方法，返回工具函数列表
  • 工具函数必须包含类型注解和文档字符串

5.2 工具函数规范

  • 函数签名必须包含类型注解
  • 参数必须有默认值和说明
  • 返回值必须明确类型
  • 异步函数必须标记为async

5.3 工具注册

  • 工具通过配置类注册到ToolManager
  • 配置类名称必须以Config结尾
  • 工具配置必须包含use_tool布尔标志

6. 日志和错误处理

6.1 日志规范

  • 使用loguru库进行日志记录
  • 日志级别：DEBUG, INFO, WARNING, ERROR
  • 关键操作必须记录INFO级别日志
  • 异常必须记录ERROR级别日志

6.2 错误处理

  • 使用try-except捕获异常
  • 异常信息必须包含上下文
  • 关键路径必须有异常处理
  • 避免捕获过于宽泛的异常

7. 测试规范

7.1 测试结构

  • 单元测试放在对应模块的tests/目录
  • 集成测试放在项目根目录的tests/目录
  • 测试文件名以test_开头

7.2 测试要求

  • 所有公共方法必须有单元测试
  • 关键业务逻辑必须有集成测试
  • 测试覆盖率不低于80%
  • 使用pytest框架进行测试

8. 文档规范

8.1 代码文档

  • 所有模块必须有模块级文档字符串
  • 公共类和方法必须有文档字符串
  • 复杂算法必须有详细注释

8.2 项目文档

  • README.md包含项目介绍和快速开始指南
  • API文档放在docs/api/目录
  • 架构文档放在docs/architecture/目录

9. 版本控制规范

9.1 Git提交

  • 使用Conventional Commits规范
  • 提交格式：type(scope): description
  • 类型：feat, fix, docs, style, refactor, test, chore

9.2 分支管理

  • 主分支：main
  • 开发分支：develop
  • 功能分支：feature/功能名
  • 修复分支：fix/问题描述

10. 依赖管理

10.1 依赖规范

  • 使用pyproject.toml管理项目依赖
  • 生产依赖放在dependencies列表
  • 开发依赖放在dev-dependencies列表
  • 定期更新依赖版本

10.2 环境管理

  • 使用虚拟环境隔离依赖
  • 敏感配置通过环境变量管理
  • 使用.env文件存储本地配置

11. 性能和安全

11.1 性能考虑

  • 避免不必要的计算和IO操作
  • 使用缓存减少重复计算
  • 异步处理耗时操作
  • 监控关键性能指标

11.2 安全规范

  • 敏感信息不得硬编码
  • API密钥通过环境变量获取
  • 输入数据必须验证
  • 遵循最小权限原则

12. 云端MCP集成

12.1 MCP配置

  • 默认使用云端MCP服务：https://xiaoliang.quant-speed.com/api/mcp/
  • 支持本地MCP服务配置覆盖
  • 使用streamable-http传输协议

12.2 工具调用

  • 通过ClientToolManager管理MCP工具
  • 支持工具动态加载和调用
  • 异常处理和重试机制

13. 代码审查

13.1 审查要点

  • 代码风格一致性
  • 功能实现正确性
  • 性能和安全考虑
  • 测试覆盖率

13.2 审查流程

  • 所有代码必须经过审查
  • 使用Pull Request进行审查
  • 至少一人审查通过才能合并
  • 自动化检查必须通过
Reference in New Issue View Git Blame Copy Permalink