尧图网页设计 
ECC Python 模式指南Protocol 鸭子类型、DTO Dataclass 与上下文管理器/生成器的工程化实践【免费下载链接】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 仓库 docs/ja-JP/rules/python/patterns.md及其英文源 rules/python/patterns.md展开。该规则文件是 ECC 规则体系中对 Python 代码的强制模式约束用于 Claude Code、Codex、Opencode、Cursor 等 Agent 在编写或评审 Python 代码时遵循统一的工程范式。读完本文你将掌握三类核心模式——Protocol 鸭子类型、Dataclass 作为 DTO、上下文管理器与生成器——并能结合仓库源码理解这些模式在真实项目中的落地形态。一、规则文件的定位面向 Agent 的 Python 模式契约docs/ja-JP/rules/python/patterns.md是 ECC 规则目录rules/python/下的核心文件之一其 front-matter 声明了该规则适用的文件路径paths: - **/*.py - **/*.pyi这意味着任何.py/.pyi文件都在该规则约束范围内。文件开头的说明明确指出它是对 rules/common/patterns.md通用模式的 Python 专属扩展。通用模式文件定义了仓库模式Repository Pattern统一封装数据访问接口findAll、findById、create、update、delete、骨架项目选取流程、API 响应信封格式等跨语言约定而 Python 规则文件则在此基础上补充了三个 Python 特有的核心主题Protocol鸭子类型—— 用结构化子类型代替显式继承Dataclass 作为 DTO—— 用数据类承载传输对象上下文管理器与生成器—— 资源管理与惰性迭代。这四个主题也正是 skills/python-patterns/SKILL.md 技能文件中Python 开发模式的浓缩版规则文件与技能文件互为表里规则约束 Agent 的行为技能提供完整知识库。二、Protocol鸭子类型面向接口而非继承规则文件给出的最小可运行示例from typing import Protocol class Repository(Protocol): def find_by_id(self, id: str) - dict | None: ... def save(self, entity: dict) - dict: ...2.1 Protocol 解决什么问题在 Python 中传统上接口通过abc.ABC与abstractmethod实现显式继承。Protocol 则提供结构化子类型structural subtyping任何类只要拥有匹配的方法签名即自动满足该协议无需显式继承——这正是鸭子类型duck typing的静态化表达。这一点与 ECC 仓库自身的抽象设计形成有趣对照。查看 src/llm/core/interface.py可以看到仓库在核心接口上选择了显式的 ABC 继承class LLMProvider(ABC): provider_type: ProviderType abstractmethod def generate(self, input: LLMInput) - LLMOutput: ... abstractmethod def list_models(self) - list[ModelInfo]: ... abstractmethod def validate_config(self) - bool: ... def supports_tools(self) - bool: return True def supports_vision(self) - bool: return False从源码结构看仓库对跨提供商、需要强制契约保障的场合如LLMProvider使用 ABC 强制实现而对插件式、松耦合、仅需特定方法存在的场合如规则文件中 Repository 这类数据访问抽象Protocol 是更轻量的选择。两种模式的分工原则可以概括为维度abc.ABCabstractmethodtyping.Protocol关联方式显式继承is-a结构匹配duck typing强制程度未实现抽象方法则无法实例化仅在类型检查阶段提示适用场景需要强契约、多态分发的核心接口依赖倒置、依赖注入、可替换实现运行时成本有继承开销无运行时开销仅类型检查2.2 工程化要点...Ellipsis作为方法体占位表示仅声明签名不实现返回值使用dict | NonePython 3.10 的联合类型语法等价于Optional[dict]表达可能查不到配合 rules/common/patterns.md 中的仓库模式业务逻辑只依赖抽象接口数据源数据库、API、文件可随时替换mock 测试也因此变得简单——这正是规则文件把 Repository 列为通用模式、又在 Python 侧给出 Protocol 实现的原因。三、Dataclass 作为 DTO数据容器的最小成本方案规则文件给出的 DTO 示例from dataclasses import dataclass dataclass class CreateUserRequest: name: str email: str age: int | None None3.1 Dataclass 与 DTO 的契合点dataclass自动生成__init__、__repr__、__eq__让纯粹装数据的类不再需要手写样板代码。age: int | None None表示可选字段缺省为None配合默认值即可表达请求中允许省略的语义。仓库 src/llm/core/types.py 是 Dataclass 承载数据的典型实例——并且全部使用frozenTrue强化不可变性dataclass(frozenTrue) class Message: role: Role ... dataclass(frozenTrue) class ToolDefinition: name: str ... dataclass(frozenTrue) class ToolCall: id: str ... dataclass(frozenTrue) class ToolResult: tool_call_id: str ...3.2 不可变 DTO 与校验frozenTrue使实例在创建后不可修改天然适合作为跨模块、跨线程传递的 DTO避免副作用。这呼应了 rules/python/coding-style.md 中的优先不可变数据结构约定from dataclasses import dataclass dataclass(frozenTrue) class User: name: str email: str更进一步的校验可在__post_init__中实现参见 skills/python-patterns/SKILL.mddataclass class CreateUserRequest: name: str email: str age: int | None None def __post_init__(self): if not in self.email: raise ValueError(fInvalid email: {self.email}) if self.age is not None and (self.age 0 or self.age 150): raise ValueError(fInvalid age: {self.age})DTO 选择速查轻量纯数据 →dataclass需要不可变 →dataclass(frozenTrue)需要紧凑的具名元组语义 →NamedTuple也具备不可变性需要复杂校验/序列化 → pydantic规则文件中未涉及但技能库与 rules/python/fastapi.md 有进一步说明。四、上下文管理器与生成器资源与内存的优雅之道规则文件的两条核心纪律资源管理使用上下文管理器with语句惰性求值与内存高效的迭代使用生成器。4.1 上下文管理器with 语句的两种实现标准库与contextlib提供了开箱即用的资源管理模式# 打开文件推荐 with open(data.txt, r) as f: content f.read() # 文件在离开 with 块后自动关闭 # 自定义计时器contextmanager 装饰器 from contextlib import contextmanager import time contextmanager def timer(name: str): start time.perf_counter() yield elapsed time.perf_counter() - start print(f{name} took {elapsed:.4f} seconds) with timer(data processing): process_large_dataset()对于更复杂的状态如数据库事务可用类实现__enter__/__exit__协议在__exit__中根据是否有异常决定提交或回滚完整示例见 skills/python-patterns/SKILL.md 的DatabaseTransaction。4.2 生成器惰性求值与内存效率def read_large_file(path: str): 逐行读取大文件内存中始终只保留一行。 with open(path) as f: for line in f: yield line.strip() for line in read_large_file(huge.txt): process(line)生成器与yield让一次性流式处理成为可能避免将整个数据集载入内存。配合生成器表达式还能显著降低中间内存占用# 推荐惰性求和不产生中间 list total sum(x * x for x in range(1_000_000)) # 不推荐先生成完整列表再求和 total sum([x * x for x in range(1_000_000)])4.3 在 Agent 场景中的意义ECC 是agent harness 性能优化系统其规则要求 Agent 生成的 Python 代码默认遵循这些模式skills/python-patterns/SKILL.md 中明确把上下文管理器用于资源管理、生成器用于大数据的惰性求值列入快速参考表并在性能小节给出__slots__减少内存占用、join代替循环内字符串拼接避免 O(n²)等补充纪律。这些约定与 rules/python/testing.mdpytest 框架 pytest --covsrc --cov-reportterm-missing覆盖率门禁共同构成 Python 代码从编写到验证的完整闭环。五、规则如何在 ECC 中生效本规则文件通过 front-matter 的paths声明作用域与 rules/python/coding-style.md、rules/python/testing.md、rules/python/security.md 等同目录规则配合由 Agent 在编写/评审**/*.py、**/*.pyi文件时自动加载。详细模式装饰器、并发、包结构、工具链配置等则由 skills/python-patterns/SKILL.md 技能文件提供可通过引用技能名python-patterns激活其description字段声明了适用时机writing or reviewing Python code and idiomatic structure, typing, or PEP 8 is in question。六、速查表与自检清单模式一句话规则仓库参考Protocol用结构化子类型声明接口替代显式继承rules/python/patterns.mdDataclass DTOdataclass承载传输对象frozenTrue增强不可变src/llm/core/types.py上下文管理器with统一资源获取与释放skills/python-patterns/SKILL.md生成器yield惰性产出控制峰值内存skills/python-patterns/SKILL.md评审或生成 Python 代码时的自检项数据访问抽象是否用 Protocol 声明业务层是否只依赖接口DTO 是否用dataclass必要时frozenTrue而非手写样板类文件、锁、连接等资源是否全部走with语句大数据集是否用生成器/生成器表达式避免整载入内存是否遵循 PEP 8 与 rules/python/coding-style.md 的格式化约定black、isort、ruff【免费下载链接】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），仅供参考 ECC Python 模式指南：Protocol 鸭子类型、DTO Dataclass 与上下文管理器/生成器的工程化实践
ECC Python 模式指南Protocol 鸭子类型、DTO Dataclass 与上下文管理器/生成器的工程化实践【免费下载链接】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 仓库 docs/ja-JP/rules/python/patterns.md及其英文源 rules/python/patterns.md展开。该规则文件是 ECC 规则体系中对 Python 代码的强制模式约束用于 Claude Code、Codex、Opencode、Cursor 等 Agent 在编写或评审 Python 代码时遵循统一的工程范式。读完本文你将掌握三类核心模式——Protocol 鸭子类型、Dataclass 作为 DTO、上下文管理器与生成器——并能结合仓库源码理解这些模式在真实项目中的落地形态。一、规则文件的定位面向 Agent 的 Python 模式契约docs/ja-JP/rules/python/patterns.md是 ECC 规则目录rules/python/下的核心文件之一其 front-matter 声明了该规则适用的文件路径paths: - **/*.py - **/*.pyi这意味着任何.py/.pyi文件都在该规则约束范围内。文件开头的说明明确指出它是对 rules/common/patterns.md通用模式的 Python 专属扩展。通用模式文件定义了仓库模式Repository Pattern统一封装数据访问接口findAll、findById、create、update、delete、骨架项目选取流程、API 响应信封格式等跨语言约定而 Python 规则文件则在此基础上补充了三个 Python 特有的核心主题Protocol鸭子类型—— 用结构化子类型代替显式继承Dataclass 作为 DTO—— 用数据类承载传输对象上下文管理器与生成器—— 资源管理与惰性迭代。这四个主题也正是 skills/python-patterns/SKILL.md 技能文件中Python 开发模式的浓缩版规则文件与技能文件互为表里规则约束 Agent 的行为技能提供完整知识库。二、Protocol鸭子类型面向接口而非继承规则文件给出的最小可运行示例from typing import Protocol class Repository(Protocol): def find_by_id(self, id: str) - dict | None: ... def save(self, entity: dict) - dict: ...2.1 Protocol 解决什么问题在 Python 中传统上接口通过abc.ABC与abstractmethod实现显式继承。Protocol 则提供结构化子类型structural subtyping任何类只要拥有匹配的方法签名即自动满足该协议无需显式继承——这正是鸭子类型duck typing的静态化表达。这一点与 ECC 仓库自身的抽象设计形成有趣对照。查看 src/llm/core/interface.py可以看到仓库在核心接口上选择了显式的 ABC 继承class LLMProvider(ABC): provider_type: ProviderType abstractmethod def generate(self, input: LLMInput) - LLMOutput: ... abstractmethod def list_models(self) - list[ModelInfo]: ... abstractmethod def validate_config(self) - bool: ... def supports_tools(self) - bool: return True def supports_vision(self) - bool: return False从源码结构看仓库对跨提供商、需要强制契约保障的场合如LLMProvider使用 ABC 强制实现而对插件式、松耦合、仅需特定方法存在的场合如规则文件中 Repository 这类数据访问抽象Protocol 是更轻量的选择。两种模式的分工原则可以概括为维度abc.ABCabstractmethodtyping.Protocol关联方式显式继承is-a结构匹配duck typing强制程度未实现抽象方法则无法实例化仅在类型检查阶段提示适用场景需要强契约、多态分发的核心接口依赖倒置、依赖注入、可替换实现运行时成本有继承开销无运行时开销仅类型检查2.2 工程化要点...Ellipsis作为方法体占位表示仅声明签名不实现返回值使用dict | NonePython 3.10 的联合类型语法等价于Optional[dict]表达可能查不到配合 rules/common/patterns.md 中的仓库模式业务逻辑只依赖抽象接口数据源数据库、API、文件可随时替换mock 测试也因此变得简单——这正是规则文件把 Repository 列为通用模式、又在 Python 侧给出 Protocol 实现的原因。三、Dataclass 作为 DTO数据容器的最小成本方案规则文件给出的 DTO 示例from dataclasses import dataclass dataclass class CreateUserRequest: name: str email: str age: int | None None3.1 Dataclass 与 DTO 的契合点dataclass自动生成__init__、__repr__、__eq__让纯粹装数据的类不再需要手写样板代码。age: int | None None表示可选字段缺省为None配合默认值即可表达请求中允许省略的语义。仓库 src/llm/core/types.py 是 Dataclass 承载数据的典型实例——并且全部使用frozenTrue强化不可变性dataclass(frozenTrue) class Message: role: Role ... dataclass(frozenTrue) class ToolDefinition: name: str ... dataclass(frozenTrue) class ToolCall: id: str ... dataclass(frozenTrue) class ToolResult: tool_call_id: str ...3.2 不可变 DTO 与校验frozenTrue使实例在创建后不可修改天然适合作为跨模块、跨线程传递的 DTO避免副作用。这呼应了 rules/python/coding-style.md 中的优先不可变数据结构约定from dataclasses import dataclass dataclass(frozenTrue) class User: name: str email: str更进一步的校验可在__post_init__中实现参见 skills/python-patterns/SKILL.mddataclass class CreateUserRequest: name: str email: str age: int | None None def __post_init__(self): if not in self.email: raise ValueError(fInvalid email: {self.email}) if self.age is not None and (self.age 0 or self.age 150): raise ValueError(fInvalid age: {self.age})DTO 选择速查轻量纯数据 →dataclass需要不可变 →dataclass(frozenTrue)需要紧凑的具名元组语义 →NamedTuple也具备不可变性需要复杂校验/序列化 → pydantic规则文件中未涉及但技能库与 rules/python/fastapi.md 有进一步说明。四、上下文管理器与生成器资源与内存的优雅之道规则文件的两条核心纪律资源管理使用上下文管理器with语句惰性求值与内存高效的迭代使用生成器。4.1 上下文管理器with 语句的两种实现标准库与contextlib提供了开箱即用的资源管理模式# 打开文件推荐 with open(data.txt, r) as f: content f.read() # 文件在离开 with 块后自动关闭 # 自定义计时器contextmanager 装饰器 from contextlib import contextmanager import time contextmanager def timer(name: str): start time.perf_counter() yield elapsed time.perf_counter() - start print(f{name} took {elapsed:.4f} seconds) with timer(data processing): process_large_dataset()对于更复杂的状态如数据库事务可用类实现__enter__/__exit__协议在__exit__中根据是否有异常决定提交或回滚完整示例见 skills/python-patterns/SKILL.md 的DatabaseTransaction。4.2 生成器惰性求值与内存效率def read_large_file(path: str): 逐行读取大文件内存中始终只保留一行。 with open(path) as f: for line in f: yield line.strip() for line in read_large_file(huge.txt): process(line)生成器与yield让一次性流式处理成为可能避免将整个数据集载入内存。配合生成器表达式还能显著降低中间内存占用# 推荐惰性求和不产生中间 list total sum(x * x for x in range(1_000_000)) # 不推荐先生成完整列表再求和 total sum([x * x for x in range(1_000_000)])4.3 在 Agent 场景中的意义ECC 是agent harness 性能优化系统其规则要求 Agent 生成的 Python 代码默认遵循这些模式skills/python-patterns/SKILL.md 中明确把上下文管理器用于资源管理、生成器用于大数据的惰性求值列入快速参考表并在性能小节给出__slots__减少内存占用、join代替循环内字符串拼接避免 O(n²)等补充纪律。这些约定与 rules/python/testing.mdpytest 框架 pytest --covsrc --cov-reportterm-missing覆盖率门禁共同构成 Python 代码从编写到验证的完整闭环。五、规则如何在 ECC 中生效本规则文件通过 front-matter 的paths声明作用域与 rules/python/coding-style.md、rules/python/testing.md、rules/python/security.md 等同目录规则配合由 Agent 在编写/评审**/*.py、**/*.pyi文件时自动加载。详细模式装饰器、并发、包结构、工具链配置等则由 skills/python-patterns/SKILL.md 技能文件提供可通过引用技能名python-patterns激活其description字段声明了适用时机writing or reviewing Python code and idiomatic structure, typing, or PEP 8 is in question。六、速查表与自检清单模式一句话规则仓库参考Protocol用结构化子类型声明接口替代显式继承rules/python/patterns.mdDataclass DTOdataclass承载传输对象frozenTrue增强不可变src/llm/core/types.py上下文管理器with统一资源获取与释放skills/python-patterns/SKILL.md生成器yield惰性产出控制峰值内存skills/python-patterns/SKILL.md评审或生成 Python 代码时的自检项数据访问抽象是否用 Protocol 声明业务层是否只依赖接口DTO 是否用dataclass必要时frozenTrue而非手写样板类文件、锁、连接等资源是否全部走with语句大数据集是否用生成器/生成器表达式避免整载入内存是否遵循 PEP 8 与 rules/python/coding-style.md 的格式化约定black、isort、ruff【免费下载链接】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），仅供参考