企业官网建设流程全解析

ECC 的 /python-review 命令指南：PEP 8、类型安全与 Pythonic 惯用法的全量代码审查

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本指南围绕 ECC 项目中的/python-review命令展开，介绍如何通过调用python-reviewer代理对 Python 变更执行涵盖 PEP 8 合规、类型提示、安全性、性能与 Pythonic 惯用法的综合性代码审查。读完本文，你将掌握该命令的触发时机、CRITICAL / HIGH / MEDIUM 三级问题分类标准、自动执行的静态分析工具链（ruff、mypy、black、bandit 等）、报告输出格式与合并门禁判定，并能用仓库源码与规则文件佐证每一条审查结论。

命令定位：python-reviewer 代理的调用入口

/python-review是 ECC 命令体系中面向 Python 专项审查的入口。它的核心动作是调用 python-reviewer 代理（python-reviewer），该代理在agents/python-reviewer.md中被定义为"Expert Python code reviewer specializing in PEP 8 compliance, Pythonic idioms, type hints, security, and performance"，并被标记为MUST BE USED for Python projects，默认模型为sonnet，工具能力包含 Read、Grep、Glob、Bash——这意味着它既能静态阅读代码，也能在仓库中实际运行诊断命令。

代理被调用后的执行序列定义在 agents/python-reviewer.md：

1. 运行git diff -- '*.py'查看最近的 Python 文件变更；
2. 在可用时运行静态分析工具（ruff、mypy、pylint、black --check）；
3. 聚焦于被修改的.py文件；
4. 立即开始审查。

从源码结构看，命令文档与代理定义构成"命令 → 代理"的一层委托关系：命令负责声明审查范围与流程，代理负责实际执行。命令本身不重复实现分析逻辑，而是通过代理的能力边界（Bash 工具）去驱动真实的工具链。

何时使用 /python-review

根据命令文档，以下场景应当使用/python-review：

• 编写或修改 Python 代码之后；
• 提交 Python 变更之前；
• 审查包含 Python 代码的 Pull Request 时；
• 新 Python 代码库的 onboarding（入职熟悉）阶段；
• 学习 Pythonic 模式与惯用语时。

该命令与仓库中其他命令的定位互补：/code-review面向非 Python 专项问题，/python-test先行验证测试是否通过，/build-fix在静态分析工具失败时兜底修复。这种分工使/python-review能专注于 Python 语义、类型与惯用法层面的深度检查。

审查分类：CRITICAL / HIGH / MEDIUM 三级问题体系

审查结果按严重程度分为三档，全部继承自命令文档，并可在 agents/python-reviewer.md 中找到代理侧的完整优先级清单。

CRITICAL（必须修复）

安全问题与"吞掉错误"的模式属于最高优先级：

• SQL / 命令注入漏洞；
• 不安全的eval/exec使用；
• Pickle 的不安全反序列化；
• 硬编码的凭据（凭据应走环境变量，见 rules/python/security.md 中os.environ的加载方式）；
• YAML 的不安全load；
• 掩盖错误的裸except子句。

代理侧进一步明确了这些条目的判定细节：SQL 注入重点关注 f-string 拼接查询（应改用参数化查询）；命令注入关注 shell 命令中的未校验输入（应改用subprocess列表参数形式）；路径穿越关注用户可控路径（应以normpath校验并拒绝..）；弱加密（为安全目的使用 MD5/SHA1）同样属于该级别。

HIGH（建议修复）

• 公开函数缺少类型提示；
• 可变的默认参数（def f(x=[])应改为def f(x=None)）；
• 静默吞掉异常；
• 未使用上下文管理器管理资源；
• 用 C 风格循环代替列表推导式；
• 用type()而非isinstance()；
• 无锁的竞态条件（共享状态应使用threading.Lock）。

代理清单还补充了代码质量维度：超过 50 行的函数、超过 5 个参数（应改用 dataclass）、超过 4 层嵌套、重复代码模式、无命名常量的魔法数字；以及并发维度：错误混用 sync/async、循环内 N+1 查询（应批量查询）。

MEDIUM（考虑改进）

• PEP 8 格式违规；
• 公开函数缺少 docstring；
• 用print而非logging；
• 低效的字符串操作（循环内拼接应改用"".join()）；
• 无命名常量的魔法数字；
• 格式化未使用 f-strings；
• 不必要的列表创建（可用生成器表达式做惰性求值）。

代理清单补充了 MEDIUM 层的惯用法条目：from module import *命名空间污染、value == None（应使用value is None）、遮蔽内建名（list、dict、str）。

自动执行的检查工具链

命令文档列出审查时会运行的自动化检查，全部以 Bash 命令形式给出：

# 类型检查 mypy . # リンティングとフォーマット（lint 与格式） ruff check . black --check . isort --check-only . # セキュリティスキャン（安全扫描） bandit -r . # 依存関係監査（依赖审计） pip-audit safety check # テスト（测试与覆盖率） pytest --cov=app --cov-report=term-missing

这套工具链与仓库的工程实践完全一致：

• pyproject.toml 实际配置了[tool.ruff]（target-version = "py311"、select = ["E", "F", "I", "N", "W", "UP"]）与[tool.mypy]（warn_return_any = true、warn_unused_ignores = true），证明 ruff 与 mypy 是本仓库的正式质量门禁；
• rules/python/coding-style.md 明确规定 black 负责代码格式化、isort 负责 import 排序、ruff 负责 lint；
• rules/python/security.md 指定 bandit 做静态安全分析（bandit -r src/）；
• rules/python/testing.md 指定 pytest 为测试框架并给出覆盖率命令；
• pyproject.toml 中[tool.pytest.ini_options]配置了testpaths = ["tests"]与asyncio_mode = "auto"，而仓库 tests/ 目录下也确实存在test_claude_provider.py、test_executor.py、test_resolver.py等 pytest 测试文件（源码结构佐证）。

需要注意pytest --cov=app中的app是文档示例包名，实际项目中应替换为自身包名（本仓库的 coverage 配置位于 pyproject.toml，source = ["src/llm"]）。

审查报告的输出格式

命令文档给出了完整的交互示例：用户输入/python-review后，代理输出一份结构化报告，包含：被审查文件清单、静态分析结果（✓通过 /WARNING警告）、按严重度分类的问题列表（每条含文件与行号、问题描述、坏示例与好示例代码）、问题统计摘要、合并建议、以及需要格式化时的black <file>命令。

代理侧的输出契约定义在 agents/python-reviewer.md：

[SEVERITY] Issue title File: path/to/file.py:42 Issue: Description Fix: What to change

报告中每个问题都遵循"严重度 → 位置 → 问题 → 修复"的四要素结构，便于直接落入工单或 PR 评论。文档示例中的典型修复对包括：

SQL 注入（CRITICAL）

query = f"SELECT * FROM users WHERE id = {user_id}" # 坏：直接拼接用户输入 query = "SELECT * FROM users WHERE id = %s" # 好：参数化查询 cursor.execute(query, (user_id,))

可变默认参数（HIGH）

def process_items(items=[]): # 坏：默认列表被所有调用共享 items.append("new") return items def process_items(items=None): # 好：None 哨兵 + 每次新建 if items is None: items = [] items.append("new") return items

缺失类型提示（MEDIUM）

def get_user(user_id): # 坏 return db.find(user_id) def get_user(user_id: str) -> Optional[User]: # 好 return db.find(user_id)

未使用上下文管理器（MEDIUM）

f = open("config.json") # 坏：异常时文件不会关闭 data = f.read() f.close() with open("config.json") as f: # 好：with 保证资源释放 data = f.read()

批准标准与合并门禁

命令文档以表格形式定义了三种判定状态，这也与代理定义中的 Approval Criteria 一致：

判定逻辑是：任何 CRITICAL 或 HIGH 问题都直接阻塞合并；只有 MEDIUM 问题时允许带警告合并。示例报告末尾的Recommendation: FAIL: Block merge until CRITICAL issue is fixed演示了该规则的实际应用。

常见修复模式速查

命令文档附带了六组可直接套用的常见修复，全部与 skills/python-patterns/ 中的惯用法互为印证：

添加类型提示

# 变更前 def calculate(x, y): return x + y # 变更后 from typing import Union def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]: return x + y

使用上下文管理器

# 变更前 f = open("file.txt") data = f.read() f.close() # 变更后 with open("file.txt") as f: data = f.read()

使用列表推导式

# 变更前 result = [] for item in items: if item.active: result.append(item.name) # 变更后 result = [item.name for item in items if item.active]

修正可变默认值

# 变更前 def append(value, items=[]): items.append(value) return items # 变更后 def append(value, items=None): if items is None: items = [] items.append(value) return items

使用 f-strings（Python 3.6+）

# 变更前 name = "Alice" greeting = "Hello, " + name + "!" greeting2 = "Hello, {}".format(name) # 变更后 greeting = f"Hello, {name}!"

修复循环内字符串拼接

# 变更前：O(n²)，字符串不可变导致反复拷贝 result = "" for item in items: result += str(item) # 变更后：O(n) result = "".join(str(item) for item in items)

后两条修复的原理细节（字符串不可变导致的 O(n²) 复杂度、join的线性复杂度）在 skills/python-patterns/ 中有更充分的展开；rules/python/patterns.md 则补充了 Protocol 鸭子类型、dataclass 作为 DTO、上下文管理器与生成器惰性求值等模式规范。

框架特定审查

命令文档对主流 Python Web 框架给出了专项检查清单：

Django 项目

• N+1 查询问题（使用select_related与prefetch_related）；
• 模型变更缺少迁移；
• 能用 ORM 时却使用裸 SQL；
• 多步骤操作缺少transaction.atomic()。

FastAPI 项目

• CORS 误配置；
• 使用 Pydantic 模型做请求校验；
• 响应模型的正确性；
• async/await 的恰当使用；
• 依赖注入模式。

Flask 项目

• 上下文管理（app context、request context）；
• 恰当的错误处理；
• Blueprint 的组织方式；
• 配置管理。

代理侧还额外标注了 FastAPI 审查要关注"异步中是否存在阻塞调用"（No blocking in async），以及 Flask 需要关注 CSRF 防护。

Python 版本兼容性提示

审查器会对使用了较新版本特性的代码给出提示，确保项目声明的requires-python与代码实际用到的语法匹配：

文档要求确认项目的pyproject.toml或setup.py指定了正确的最低 Python 版本。以本仓库为例，pyproject.toml 声明requires-python = ">=3.11"，ruff 的target-version = "py311"与之对齐，这正是一个"声明版本与工具目标版本一致"的良好范本。

与其他命令及技能的集成

命令文档给出了推荐的使用编排：

• 先使用/python-test确认测试通过（对应 python-testing skill 的 pytest 与 TDD 方法论）；
• /code-review负责 Python 之外的非专项问题；
• 提交前使用/python-review；
• 静态分析工具失败时使用/build-fix。

底层依赖为 python-patterns skill（提供惯用法、类型提示、上下文管理器、推导式、dataclass、装饰器、并发模式等完整参考）与 python-testing skill（提供 pytest fixtures、参数化、mock、覆盖率与 TDD 流程），审查时的判定标准也可对照 rules/python/ 目录下的 coding-style、security、testing、patterns 规则文件。

总结

/python-review是 ECC 为 Python 项目提供的一条完整质量门禁命令：它通过git diff定位变更、借助 ruff / mypy / black / isort / bandit / pytest 等真实工具链做自动检查、按 CRITICAL / HIGH / MEDIUM 三级组织问题报告、以"无 CRITICAL/HIGH 即批准"的规则输出合并决策，并对 Django、FastAPI、Flask 提供框架专项检查。在 ECC 仓库中，这条命令与 python-reviewer 代理、python-patterns / python-testing 技能以及 rules/python 规则体系共同构成了从"写出代码"到"安全合入"的完整审查链路，同时 pyproject.toml 中的实际工具配置为其可行性提供了仓库级证据。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC