用途:对 Python 代码库做微层面(函数、类、测试文件)质量审计,而非基础设施层面。
主要能力:依次执行八步分析——类型标注检查(覆盖度、Any、现代泛型语法、pyright/mypy 严格模式、py.typed)、代码风格(PEP 8、命名、导入分组、88 字符行长、Google 风格文档字符串、Ruff)、函数设计(单一职责、长度与复杂度、提前返回、副作用隔离、dataclass、关键字参数)、数据校验(Pydantic 边界、校验器、pydantic-settings)、错误处理(异常特指性、自定义异常层级、日志级别)、模块结构(src/ 布局、all、分层边界、循环导入)、测试质量(pytest 发现与命名、fixture、parametrize、mock 纪律、集成测试隔离与标记),最后汇总为 Markdown 报告。
标准来源:优先读取仓库内 agent-rules/rules/python/ 下的 typing.md、code-style.md、function-design.md、data-validation.md、error-handling.md、module-structure.md、testing-unit.md、testing-integration.md,不存在时通过 GitHub raw 拉取(https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/python/)。
使用方式:可走 CLI 路径(somnio run)或 Claude 会话内的 orchestrator 并行子代理路径,两者产出同一报告。报告文件名固定为 reports/<YYYY-MM-DD>-<project>-python-best-practices.md;项目名由 origin 远程 URL 推导并转为 kebab-case,无远程时用主检出目录名,非 git 仓库用当前目录名。通过 somnio run 运行时须沿用 CLI 给出的完整路径,不可重算。报告末尾必须包含 Report Metadata 表(Generated by 行保持模板原文)。
限制:要求基于代码证据,缺失证据须写 Unknown;不假设、不臆造。运行环境、依赖安装与收费信息暂未提供。