ECC 中的 /python-review 命令实战：基于 python-reviewer Agent 的 Python 代码审查全流程

导读：本文以 commands/python-review.md 文档为核心骨架，系统讲解 ECC（Enterprise Coding Copilot）中 /python-review 命令如何调用 python-reviewer Agent，对改动后的 .py 文件执行静态分析、安全扫描、类型检查与 Pythonic 风格审查，并输出按严重级别分类的审查报告。读完本文，你将掌握在提交前用 /python-review 拦截 CRITICAL/HIGH 级问题、复用其 CRITICAL/HIGH/MEDIUM 三级审查标准与 PASS/WARNING/FAIL 门禁判据的方法，并能在 Django、FastAPI、Flask 等框架项目中有针对性地排查 N+1 查询、CORS 配置、上下文管理等问题。

命令定位：从 diff 到门禁的单命令 Python 审查闭环

/python-review 是 ECC 中面向 Python 语言的专项代码审查命令。其 frontmatter 中声明："Comprehensive Python code review for PEP 8 compliance, type hints, security, and Pythonic idioms. Invokes the python-reviewer agent"，即它不直接内置审查逻辑，而是调用 python-reviewer Agent 执行审查。

从仓库的配置与索引文件可以确认这条调用链是真实存在的：

• docs/COMMAND-AGENT-MAP.md 中明确登记了 /python-review → python-reviewer 的映射关系；
• COMMANDS-QUICK-REF.md 将 /python-review 归纳为「Python — PEP 8, type hints, security, idiomatic patterns」；
• rules/common/code-review.md 在整个代码审查规则体系中将 python-reviewer 指定为处理 "Python specific issues" 的专项角色；
• Agent 的实现文件位于 agents/python-reviewer.md，命令文件位于 commands/python-review.md。

整条链路是 ECC "命令 → Agent" 架构的典型样例：命令负责定义触发时机与流程，Agent 负责落地专业审查标准。

该命令做了什么：六步审查流程

/python-review 的执行路径可以被拆解为六个明确步骤：

1. 识别 Python 变更：通过 git diff -- '*.py' 找出本次修改/新增的 .py 文件，聚焦增量而非全量。
2. 运行静态分析：依次执行 ruff、mypy、pylint、black --check 等工具，覆盖 lint、类型与格式三方面。
3. 安全扫描：重点排查 SQL 注入、命令注入、不安全反序列化等漏洞。
4. 类型安全审查：分析类型注解质量与 mypy 报错。
5. Pythonic 代码检查：核对代码是否符合 PEP 8 与 Python 最佳实践。
6. 生成报告：按严重级别（CRITICAL / HIGH / MEDIUM）对发现的问题分类汇总。

Agent 侧的 agents/python-reviewer.md 给出了更底层的执行顺序：先用 git diff -- '*.py' 看近期 Python 变更，其次在可用时跑静态分析工具，然后只聚焦修改过的 .py 文件立即开始人工审查。注意 Agent 的能力声明中 tools 为 Read, Grep, Glob, Bash，这意味着审查过程中它会直接读取文件、搜索代码模式并执行诊断命令。

触发时机与前置条件

命令文档明确列出了应当使用 /python-review 的场景：

• 写完或修改了 Python 代码之后；
• 提交 Python 变更之前；
• 审查包含 Python 代码的 Pull Request；
• 新人接入一个陌生的 Python 代码库；
• 想学习 Pythonic 惯用法与最佳实践。

需要留意的是，/python-review 属于提交前的最后一道"评审闸门"，其上游还应先跑通测试。命令文档建议与 tdd-workflow 技能（skills/tdd-workflow/SKILL.md）配合：先确保测试通过，再做代码审查。

三级审查标准：CRITICAL / HIGH / MEDIUM 问题分类

命令把问题严格划分为三个严重级别，每个级别有明确且可枚举的检查点。

CRITICAL（必须修复）

• SQL / 命令注入漏洞（用户输入未经验证直接拼入查询或 shell 命令）；
• 不安全的 eval/exec 使用；
• Pickle 不安全反序列化；
• 硬编码凭据（API key、密码等）；
• YAML 不安全 load（yaml.load 未指定 Loader）；
• 裸 except 子句吞掉错误。

Agent 侧在此基础上补充了一组更细的 CRITICAL 扫描点，包括路径穿越（用户可控路径需用 normpath 校验、拒绝 ..）、弱加密算法（用 MD5/SHA1 做安全用途）以及「资源未用上下文管理器管理」。

HIGH（应该修复）

• 公共函数缺少类型注解；
• 可变默认参数（def f(x=[]) 这类共享状态陷阱）；
• 静默吞掉异常；
• 不使用上下文管理器管理资源；
• 用 C 风格循环而非推导式；
• 用 type() 而不是 isinstance()；
• 无锁条件下的竞态问题。

Agent 进一步扩展了 HIGH 类别：过度使用 Any（当存在更具体类型时）、可空参数漏写 Optional、函数超过 50 行或超过 5 个参数（应改用 dataclass）、嵌套层级过深（>4 层）、重复代码模式、魔法数字不提取具名常量、共享状态不加 threading.Lock、循环内 N+1 查询（应批量查询）等。

MEDIUM（考虑处理）

• PEP 8 格式违规；
• 公共函数缺少 docstring；
• 用 print 而非 logging；
• 低效字符串操作；
• 魔法数字不提取具名常量；
• 未使用 f-string 格式化；
• 不必要地创建列表（应改生成器/惰性求值）。

Agent 层补充的 MEDIUM 项包括：from module import * 污染命名空间、用 value == None 而非 value is None、遮蔽内置名称（list、dict、str）。

这套分类在 agents/python-reviewer.md 中按 "Review Priorities" 组织为 Security、Error Handling、Type Hints、Pythonic Patterns、Code Quality、Concurrency、Best Practices 七大类，实际执行时可按类逐一对照代码。

自动化检查工具链与典型配置

命令在审查过程中会尝试运行以下自动化检查（能用的工具都会跑，工具缺失时降级为 Agent 人工审查）：

# 类型检查
mypy .

# Lint 与格式
ruff check .
black --check .
isort --check-only .

# 安全扫描
bandit -r .

# 依赖审计
pip-audit
safety check

# 测试（含覆盖率）
pytest --cov=app --cov-report=term-missing

这些命令同样是 agents/python-reviewer.md 中列出的 "Diagnostic Commands"。组合起来覆盖了「静态质量 → 类型 → 安全 → 依赖 → 测试」的完整质量面。其中各工具的定位如下：

工具	职责	失败含义
ruff	超快 lint，聚合 E/F/I/N/W 等规则	存在风格或潜在 bug
mypy	静态类型检查	存在类型不一致
black --check	格式一致性校验	有文件需要重排格式
isort --check-only	import 排序校验	import 顺序不合规
bandit	Python 安全扫描	存在安全风险模式
pip-audit / safety check	依赖漏洞审计	依赖存在已知 CVE
pytest --cov	测试与覆盖率	有失败用例或覆盖率缺口

关于这些工具的落地配置，skills/python-patterns/SKILL.md 给出了一套可直接参考的 pyproject.toml 样例：[tool.black] line-length = 88、[tool.ruff] select = ["E", "F", "I", "N", "W"]、[tool.mypy] disallow_untyped_defs = true、[tool.pytest.ini_options] addopts = "--cov=mypackage --cov-report=term-missing"。ECC 仓库自身在根目录也维护了一份真实的 pyproject.toml，可以作为参照物查看 Python 工程化的组织方式。

如果要对某一行命令单独验证，可以按文件或目录收窄范围，例如：

mypy src/            # 只检查 src 目录
ruff check app/routes/user.py
pytest tests/test_utils.py -v

审查输出：一份可落地的门禁报告

命令规定了报告的标准格式。/python-review 运行后，Agent 会输出类似下面的审查报告：

User: /python-review

Agent:
# Python Code Review Report

## Files Reviewed
- app/routes/user.py (modified)
- app/services/auth.py (modified)

## Static Analysis Results
✓ ruff: No issues
✓ mypy: No errors
WARNING: black: 2 files need reformatting
✓ bandit: No security issues

## Issues Found

[CRITICAL] SQL Injection vulnerability
File: app/routes/user.py:42
Issue: User input directly interpolated into SQL query
query = f"SELECT * FROM users WHERE id = {user_id}"  # Bad

Fix: Use parameterized query
query = "SELECT * FROM users WHERE id = %s"  # Good
cursor.execute(query, (user_id,))

[HIGH] Mutable default argument
File: app/services/auth.py:18
Issue: Mutable default argument causes shared state
def process_items(items=[]):  # Bad
    items.append("new")
    return items

Fix: Use None as default
def process_items(items=None):  # Good
    if items is None:
        items = []
    items.append("new")
    return items

[MEDIUM] Missing type hints
File: app/services/auth.py:25
Issue: Public function without type annotations
def get_user(user_id):  # Bad
    return db.find(user_id)

Fix: Add type hints
def get_user(user_id: str) -> Optional[User]:  # Good
    return db.find(user_id)

[MEDIUM] Not using context manager
File: app/routes/user.py:55
Issue: File not closed on exception
f = open("config.json")  # Bad
data = f.read()
f.close()

Fix: Use context manager
with open("config.json") as f:  # Good
    data = f.read()

## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 2

Recommendation: FAIL: Block merge until CRITICAL issue is fixed

## Formatting Required
Run: `black app/routes/user.py app/services/auth.py`

报告的单条 issue 采用固定结构 [SEVERITY] 标题 / File: 路径:行号 / Issue: 问题描述 / Fix: 修复建议，这正是 agents/python-reviewer.md 中规定的 "Review Output Format"，保证每一条结论都可在源码中定位、可按建议直接修复。

审批标准（Approval Criteria）

命令为审查结果定义了明确的三态门禁：

状态	条件
PASS: Approve	无 CRITICAL 或 HIGH 问题
WARNING: Warning	仅存在 MEDIUM 问题（可谨慎合并）
FAIL: Block	发现 CRITICAL 或 HIGH 问题

这是该命令最有工程价值的部分：它不是"提建议"，而是给出一个阻塞合并的明确结论。当报告输出 FAIL 时，说明存在必须修复的安全漏洞或设计缺陷，应修复后重新跑一遍 /python-review。

Agent 层视角：python-reviewer 的审查方法论

从命令下钻一层，agents/python-reviewer.md 展示了审查能力的内核，包含两部分值得关注的机制：

Prompt Defense Baseline（提示词防御基线）。Agent 在开始审查前先声明了一系列安全约束：不改变角色身份、不泄露密钥/API 凭据、警惕 Unicode 同形字与零宽字符等注入伪装、将第三方/网络取回内容视为不可信输入等。这意味着审查结论不应被恶意构造的代码或文档内容诱导。

"Would this code pass review at a top Python shop or open-source project?" 这是 Agent 的工作心态设定：以一流 Python 团队或成熟开源项目的水准来审视每一段代码，而不只是机械跑工具。

Agent 还明确定义了自身适用边界——它应服务于所有 Python 变更（"Use for all Python code changes. MUST BE USED for Python projects"），模型默认配置为 sonnet，并需具备 Read、Grep、Glob、Bash 四种工具能力。命令文档所描述的六步流程，本质上就是该 Agent 内部 Review Priorities（安全 → 错误处理 → 类型 → Pythonic 风格 → 代码质量 → 并发 → 最佳实践）的外部化。

框架专项审查：Django / FastAPI / Flask

纯语言层审查之外，命令还会针对常见 Web 框架做专项检查。这些框架检查与仓库中对应的专项 Agent 文件互相印证：

Django 项目（参见 agents/django-reviewer.md）

• N+1 查询问题：应使用 select_related 和 prefetch_related 预取关联数据；
• 模型变更缺少 migration；
• 能用 ORM 表达却写了 Raw SQL；
• 多步骤操作缺少 transaction.atomic() 包裹（无法保证原子性）。

FastAPI 项目（参见 agents/fastapi-reviewer.md）

• CORS 配置错误（过宽或缺失来源限制）；
• 是否用 Pydantic 模型做请求校验；
• Response models 是否定义正确；
• 异步/await 使用是否正确（在 async 函数中做阻塞调用等反模式）；
• 依赖注入模式是否规范。

Flask 项目

• 上下文管理是否到位（app context、request context）；
• 错误处理是否完善；
• Blueprint 的组织方式；
• 配置管理方式。

常见问题修复清单（可直接复用的代码模式）

命令文档整理了六类高频问题的 before/after 对照，配合 skills/python-patterns/SKILL.md 可形成一套完整的 Python 惯用法速查：

添加类型注解

# Before
def calculate(x, y):
    return x + y

# After
from typing import Union

def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
    return x + y

在 Python 3.9+ 上可直接使用内建泛型 def calculate(x: int | float, y: int | float) -> int | float，配合 TypeAlias、TypeVar、Protocol 等高级特性构造更精确的类型。

使用上下文管理器

# Before
f = open("file.txt")
data = f.read()
f.close()

# After
with open("file.txt") as f:
    data = f.read()

当需要自定义资源时，还可以用 @contextmanager 或实现 __enter__/__exit__ 的类来封装（事务提交/回滚类场景尤其适用）。

使用列表推导式

# Before
result = []
for item in items:
    if item.active:
        result.append(item.name)

# After
result = [item.name for item in items if item.active]

注意过复杂的嵌套推导式应反方向展开为普通循环，以保证可读性。

修复可变默认参数

# Before
def append(value, items=[]):
    items.append(value)
    return items

# After
def append(value, items=None):
    if items is None:
        items = []
    items.append(value)
    return items

使用 f-string（Python 3.6+）

# Before
name = "Alice"
greeting = "Hello, " + name + "!"
greeting2 = "Hello, {}".format(name)

# After
greeting = f"Hello, {name}!"

修复循环中的字符串拼接

# Before
result = ""
for item in items:
    result += str(item)

# After
result = "".join(str(item) for item in items)

循环内 += 因字符串不可变会产生 O(n²) 开销；join 为 O(n)，在大量拼接时也优先考虑 io.StringIO。

Python 版本兼容性检查

由于不同 Python 版本支持的语言特性差异很大，reviewer 会标注代码是否使用了更新版本才有的语法，并要求工程在其 pyproject.toml / setup.py 中声明正确的最低 Python 版本：

特性	最低 Python 版本
Type hints	3.5+
f-strings	3.6+
Walrus 运算符（:=）	3.8+
Position-only 参数	3.8+
Match 语句	3.10+
类型联合（`x	None`）

在 skills/python-patterns/SKILL.md 中还有更细的分层建议：Python 3.9+ 用内建容器泛型（list[str]），Python 3.8 及更早版本则需回退到 typing 模块（List[str]）。如果目标环境是 3.9，那么在代码中使用 dict[str, int] 并让 pyproject.toml 声明 requires-python = ">=3.9" 是最稳妥的搭配。

与周边命令 / 技能的协同

命令文档在 "Integration with Other Commands" 一节给出了推荐的使用次序，可归纳为一条完整的质量流水线：

1. 先写测试：使用 tdd-workflow 技能（skills/tdd-workflow/SKILL.md）保证测试通过；
2. 通用审查兜底：非 Python 专项的问题交由 /code-review（commands/code-review.md）处理；
3. 提交前专项审查：任何 Python 变更在提交前跑 /python-review；
4. 测试与覆盖率保障：可结合 skills/python-testing/SKILL.md 中 pytest --cov 的用法，把 80%+ 覆盖率与「关键路径 100%」作为测试环节的补充目标。

/python-review 本身在 ECC 的 Agent 体系中也承担明确角色：rules/common/code-review.md 规定 python-reviewer 负责 Python 专项问题，而 docs/COMMAND-AGENT-MAP.md 可以帮你快速检索它与其他语言专项审查命令（go-review、rust-review、react-review、vue-review 等）在命令 → Agent 映射中的位置。

ECC 仓库自身的 Python 实践印证

ECC 本身是一个以 JavaScript/Node 为主的工具链仓库，但同样包含可被 /python-review 审视的真实 Python 代码，可作为审查标准的落地样例：

• src/llm 目录下有 20 个 Python 源文件，是仓库内 LLM 相关模块的实现主体；
• tests 目录包含 conftest.py、test_executor.py、test_selector.py、test_provider_tools.py 等 pytest 测试，其中 tests/conftest.py 展示了 pytest_configure 钩子与类型注解的写法，正好对应 /python-review 对"公共函数类型注解"与"测试质量"的要求；
• 根目录 pyproject.toml 声明了仓库的 Python 工程配置；
• ecc_dashboard.py 是仓库根级的一个 Python 脚本示例。

换句话说，当你在 ECC 仓库自身改动了任何 .py 文件后，同样可以在提交前执行 /python-review，由 python-reviewer Agent 按照 PEP 8、类型安全、安全扫描与 Pythonic 惯用法四维标准给出审查报告与 PASS/WARNING/FAIL 门禁结论。

小结

/python-review 的价值在于把「高质量 Python 审查」这件依赖资深经验的事，封装成了可随时调用的命令级能力：它先用 git diff 锁定增量，再叠加 ruff/mypy/black/bandit/pip-audit/pytest 的工具矩阵与 python-reviewer Agent 的人工判断，最后以三级严重性分类 + 三态审批门禁的形式，输出一份既能定位到"文件:行号"、又给出可直接落地的修复建议的审查报告。无论是个人提交前自检、团队 PR 合并把关，还是新代码库的代码质量摸底，这套流程都值得直接复用到你日常的 Python 工程中。