ECC python-reviewer 解析：AI Python 代码审查 Agent 的完整设计、审查标准与落地实践

ECC python-reviewer 解析AI Python 代码审查 Agent 的完整设计、审查标准与落地实践【免费下载链接】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 仓库中 Kiro 集成下的python-reviewerAgent 定义为核心完整拆解其角色设定、调用流程、严重度分级审查清单、诊断命令组、结构化输出格式与审批标准并结合仓库中的同体系命令、Hook、Skill 与规则文件说明这一资深 Python 评审员是如何在真实工作流中被调起、如何输出可执行的审查报告以及如何在项目中落地使用。一、python-reviewer 是什么一个被完整定义的评审角色python-reviewer是 ECCAgent Harness 性能优化系统为 Kiro IDE 提供的一组代码评审 Agent 之一其定义文件位于 python-reviewer.md。与常见的提示词模板不同它是一份被结构化约束的角色定义--- name: python-reviewer description: Expert Python code reviewer specializing in PEP 8 compliance, Pythonic idioms, type hints, security, and performance. Use for all Python code changes. MUST BE USED for Python projects. allowedTools: - read - shell ---从 Frontmatter 可以看出几个关键设计触发语义明确description 中写明 Use for all Python code changes. MUST BE USED for Python projects即任何 Python 代码变更都应强制走该 Agent 评审这在多 Agent 体系里属于优先级声明便于上层调度器或 IDE 的 Agent 自动选择正确路由工具最小化allowedTools只开放read与shell两类能力——前者用于读取 diff 与源码后者用于运行git diff与静态分析工具。评审 Agent 只需要看和跑检查不需要写权限这从结构上保证了评审结果的客观性。同一仓库还维护了该 Agent 的多套等价实现可以对照查看文件用途差异点python-reviewer.mdKiro IDE 的 Markdown 格式 AgentallowedTools: read, shellpython-reviewer.jsonKiro CLI 的 JSON 格式 Agent经/agent swap切换同样的 prompttools: [builtin]allowedTools: [fs_read, shell]python-reviewer.mdClaude Code 版本tools: Read, Grep, Glob, Bashmodel: sonnet并额外包含一段Prompt Defense Baseline防注入基线其中 Claude Code 版本在正式 prompt 之前还加入了一段Prompt Defense Baseline见 agents/python-reviewer.md要求 Agent 不改变角色、不泄露机密、不输出未经验证的可执行内容并将外部抓取内容一律视为不可信输入。这一点值得注意代码评审 Agent 会读取 diff 中任意文本等于会接触潜在的提示注入载荷ECC 在其面向 Claude Code 的版本中显式加了防御基线而 Kiro 版本则依赖平台自身的安全边界——从源码结构看同一评审内核在不同宿主下会被加上不同的安全外壳。ECC 的 Kiro 集成入口文档 README.md 也明确将python-reviewer列在 Agent 清单中Reviews Python code for PEP 8, type hints, error handling, and best practices. 整个.kiro目录通过一条命令即可安装到任意 Kiro 项目cd .kiro ./install.sh /path/to/your/project # 安装到指定项目 ./install.sh # 安装到当前目录 ./install.sh ~ # 全局安装对所有 Kiro 项目生效安装器采用非破坏性拷贝不会覆盖已有文件。二、调用流程四步走的标准工作流Agent 定义中When invoked一节规定了被调起后的固定动作序列运行git diff -- *.py查看最近的 Python 文件变更若可用则运行静态分析工具ruff、mypy、pylint、black --check只聚焦本次修改过的.py文件立即开始评审Begin review immediately。这套流程的设计意图是清晰的把评审范围锁定在增量 diff 上而不是全库扫描。全库静态检查留给 CIAgent 的价值在于读懂这次改了什么、为什么改、有没有引入新问题。git diff -- *.py这一条同时给出了工具使用范式——allowedTools里的shell权限主要就是为这条命令和第二步的静态分析服务的。三、严重度分级体系CRITICAL / HIGH / MEDIUM 三级清单该 Agent 的核心是一份按严重度组织的审查清单。完整继承如下CRITICAL — Security安全必须拦截SQL 注入在查询中使用 f-string 拼接——应使用参数化查询命令注入shell 命令中存在未校验的输入——应使用subprocess的列表参数形式shellFalse 参数列表路径穿越用户可控路径——用normpath校验拒绝..eval/exec 滥用、不安全的反序列化如 pickle、硬编码密钥弱加密安全场景使用 MD5/SHA1、YAML 不安全加载yaml.load而非yaml.safe_load。CRITICAL — Error Handling错误处理裸 exceptexcept: pass——应捕获具体异常类型被吞掉的异常静默失败——必须记录日志并处理缺少上下文管理器手动管理文件/资源——应使用with。HIGH — Type Hints类型标注公共函数缺少类型注解本可写具体类型却使用Any可空参数缺少Optional标注。HIGH — Pythonic Patterns惯用法用列表推导式替代 C 风格循环用isinstance()而非type() 用Enum而非魔法数字循环内字符串拼接用.join()可变默认参数def f(x[])是典型的共享状态陷阱应写为def f(xNone)。HIGH — Code Quality代码质量函数超过 50 行、参数超过 5 个建议改用dataclass聚合参数嵌套深度超过 4 层重复代码模式无命名常量的魔法数字。HIGH — Concurrency并发共享状态未加锁——使用threading.Lock同步/异步混用不当循环内 N1 查询——改为批量查询。MEDIUM — Best Practices最佳实践PEP 8import 顺序、命名、间距公共函数缺少 docstring用print()代替loggingfrom module import *造成命名空间污染value None应写作value is None变量名遮蔽内建list、dict、str。这套清单的显著特征是每一条都给出反模式 修复方向而不只是这是错的。这保证了 Agent 输出的问题条目可以直接转化为修改动作也为后文的统一报告格式见第五节提供了字段来源。仓库中还有与该清单互相印证的规则文件组 rules/python/例如 rules/python/security.md 通过 frontmatter 的paths声明其仅作用于**/*.py与**/*.pyi文件并给出密钥管理示例从os.environ读取、依赖缺失即抛KeyError与 bandit 扫描命令rules/python/下另有coding-style.md、patterns.md、fastapi.md、testing.md、hooks.md构成同一主题的规则层补充。四、典型问题详解从清单条目到可运行示例以下示例取自同体系的/python-review命令文档 python-review.md它正是调用python-reviewerAgent 的入口命令展示了清单条目在实际报告中如何呈现。4.1 SQL 注入CRITICAL# 反模式用户输入直接拼接进 SQL query fSELECT * FROM users WHERE id {user_id} # 修复参数化查询 query SELECT * FROM users WHERE id %s cursor.execute(query, (user_id,))4.2 可变默认参数HIGH这是 Python 最经典的新手陷阱默认值在函数定义时只求值一次[]会在所有调用间共享。# 反模式共享状态 def process_items(items[]): items.append(new) return items # 修复以 None 为哨兵 def process_items(itemsNone): if items is None: items [] items.append(new) return items4.3 缺少上下文管理器CRITICAL 错误处理类# 反模式异常发生时文件不会被关闭 f open(config.json) data f.read() f.close() # 修复with 保证异常路径也释放资源 with open(config.json) as f: data f.read()4.4 公共函数缺少类型注解HIGH# 反模式 def get_user(user_id): return db.find(user_id) # 修复 def get_user(user_id: str) - Optional[User]: return db.find(user_id)Agent 定义的 Reference 一节还指明更细的 Python 惯用法、安全示例与代码样本应查阅python-patterns技能。该技能全文位于 skills/python-patterns/SKILL.md约 750 行覆盖类型标注含 3.9 内置泛型写法list[str]、Protocol鸭子类型、异常层级设计与raise ... from e链式抛异常、contextlib.contextmanager自定义上下文管理器、推导式与生成器、dataclass/NamedTuple、装饰器、线程/多进程/asyncio 三种并发模型等。可以推断python-reviewer的评审尺度实际上锚定在这份技能文档的好代码定义上——Agent 负责挑毛病技能文档负责定义什么样算对。五、诊断命令组Agent 手里的那套工具箱Agent 定义中的Diagnostic Commands一节给出了五条核心命令mypy . # 类型检查 ruff check . # 快速 linting black --check . # 格式检查 bandit -r . # 安全扫描 pytest --covapp --cov-reportterm-missing # 测试覆盖率/python-review命令文档在这基础上扩展为完整的自动化检查矩阵并补充了依赖审计与 import 排序# 类型检查 mypy . # Lint 与格式化 ruff check . black --check . isort --check-only . # 安全扫描 bandit -r . # 依赖审计 pip-audit safety check # 测试 pytest --covapp --cov-reportterm-missing这些工具与审查清单一一对应mypy对应 HIGH 类型标注类bandit对应 CRITICAL 安全类仓库的 rules/python/security.md 也将 bandit 列为 Python 静态安全分析工具ruff/black对应 MEDIUM 的 PEP 8 类。Agent 的角色不是替代工具而是先跑工具、再对工具抓不到的语义问题N1 查询、async/阻塞混用、可变默认参数的语义后果做人工级判断。六、审查输出格式与审批标准Agent 定义强制了统一的报告条目格式[SEVERITY] Issue title File: path/to/file.py:42 Issue: Description Fix: What to change四行结构严重度前缀、精确定位到文件与行号、问题描述、修复方案。这保证了报告可被机械解析、可逐条关闭。审批标准则把严重度映射为三种结论状态条件Approve批准无 CRITICAL 或 HIGH 问题Warning警告仅有 MEDIUM 问题可谨慎合并Block拦截发现 CRITICAL 或 HIGH 问题/python-review命令的示例报告python-review.md完整演示了这一格式逐文件列出Files Reviewed、静态工具结果✓ ruff: No issues/WARNING: black: 2 files need reformatting、按严重度分组的问题条目最后给出Recommendation: FAIL: Block merge until CRITICAL issue is fixed及需重排格式的文件列表。评审的最终心智模型写在定义文件的结尾一句话里Would this code pass review at a top Python shop or open-source project?七、框架专项检查Django / FastAPI / FlaskAgent 定义最后给出三段框架专属检查项说明它不是语言级评审器还承担了框架语义层的审查Django用select_related/prefetch_related解决 N1 查询多步写操作用atomic()包裹事务模型变更必须生成 migrationsFastAPICORS 配置正确性、Pydantic 请求校验、response model 声明、async 端点中禁止阻塞调用Flask恰当的错误处理器与 CSRF 防护。/python-review命令文档对这些框架检查做了展开例如 Django 侧还会检查能用 ORM 却写 Raw SQL、FastAPI 侧还会检查依赖注入Dependency Injection模式、Flask 侧还会检查应用上下文/请求上下文管理与Blueprint 组织见 python-review.md。此外该命令文档还附了一张Python 版本兼容性速查表用于评审时判断代码用了超出项目最低支持版本的新语法特性最低 Python 版本Type hints3.5f-strings3.6Walrus 运算符:3.8位置-only 参数3.8Match 语句3.10类型联合x \| None3.10并要求项目应在pyproject.toml或setup.py中明确最低 Python 版本。八、生态联动Hook 即时提醒 命令深度评审 技能知识底座在 ECC 体系中python-reviewer不是孤立存在的它与若干组件构成了轻量即时 重量按需的两层防线编辑即提醒python-lint-on-edit.kiro.hook 是一个 Kiro IDE Hook触发条件为fileEdited且匹配*.py动作是askAgent提示词为刚保存了一个 Python 文件检查明显的类型错误、PEP 8 违规或常见反模式。它是秒级的轻量检查按需深度评审python-review.md 定义的/python-review命令是重量级入口其文档明确列出适用时机——写完/修改 Python 代码后、提交前、评审含 Python 的 PR、接触新 Python 代码库、学习 Pythonic 惯用法时知识底座Agent 定义尾部 Reference 指向的python-patterns技能skills/python-patterns/SKILL.md提供全部正例范式另有 skills/python-testing/ 支撑测试相关判断。/python-review文档的Integration with Other Commands一节还给出组合建议先走tdd-workflow技能确认测试通过再用/python-review做提交前评审非 Python 专属问题交给/code-review。从源码结构看这套组合的分工逻辑是Hook 管别把明显错误写进去Agent 管这次变更整体能不能合并Skill 管什么是好代码的参照系。Agent 定义里的allowedToolsread shell则划定了它的能力边界——只读加执行检查从不直接改代码修复动作留给开发者或专门的修复类 Agent。九、落地使用小结在 Kiro IDE 中安装.kiro目录后可直接在会话中以/python-reviewer显式调用或由平台根据 description 中的 MUST BE USED for Python projects 语义在 Python 变更时自动选择CLI 中则通过/agent swap切换到python-reviewer或kiro-cli --agent python-reviewer直接启动用法见 .kiro/README.md。在 Claude Code 侧对应的 agents/python-reviewer.md 以Read, Grep, Glob, Bash工具集与sonnet模型声明运行并附加防注入基线。无论哪条路径交付物都是一份同构的审查报告以 diff 为范围、以三级严重度清单为判据、以[SEVERITY] / File / Issue / Fix为条目格式、以 Approve / Warning / Block 为最终结论。理解了这套结构你既可以把它当作现成的评审 Agent 直接使用也可以按同样的骨架角色 工具白名单 分级清单 诊断命令 输出契约 审批标准为其他语言或框架复制出自己的评审 Agent。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考