SuperAPI AI 工具集

pythonic-code

编程与开发

查看项目

更新于 10-15 17:24

技能介绍

用途:该技能用于编写、重构和审查 Python 代码,目标是让领域行为对人和 AI 读者都清晰可见。它主张选择最简单、最符合 Python 习惯且易于验证的设计,核心方法是 Constructive Domain Modeling:先定义程序可以构造的有效取值和结果,再让类型把义务传递给消费方。

主要能力:

  1. 编码前先定位环境:阅读仓库的 AGENTS.md 或 CLAUDE.md、docs/ENGINEERING_STYLE.md、以及涉及领域语言、归属、身份、事实来源或生命周期时的 docs/DOMAIN_MODEL.md,并完整阅读待改文件,识别 Python 版本、工具与需保持稳定的行为。项目本地规则优先于通用风格建议。
  2. 决策优先级:先保持正确性、领域不变量和公开行为,再遵循仓库约定与兼容约束,让数据流、控制流、错误和副作用显式,选择当下最能降低认知负荷的最小抽象,并用类型、测试和仓库工具证明结果。
  3. 建模正面空间:用 frozen dataclass 的必需字段乘积表示单一有效状态,用 Python 3.12 类型别名构造封闭并集表示有意义的备选;在 API、CLI、MCP、配置和持久化边界使用 Pydantic 与可辨识联合做运行时校验或序列化,边界解析一次后内部传递更窄的领域值。用显式 match 消费封闭并集,配合 typing.assert_never 证明穷尽,避免掩盖新变体的兜底分支。
  4. 函数优先于层级:从完整的普通函数开始;需要命名相关状态或结果时配 dataclass;行为确实随首参运行类型变化时用 functools.singledispatch;真正可替换行为用窄 Protocol;需要身份、可变状态、生命周期或资源所有权时才用具体类。避免单一实现的 manager、factory、base、adapter、strategy、registry 抽象。
  5. 保持推理本地:能自上而下读懂的工作流就放在一起;仅当名称体现领域操作、隔离副作用或约束、去除实质重复、形成可测试计算时才提取辅助函数。以 prepare、resolve、apply、build 长链为再思考数据流的信号。
  6. 写显式 Python:按领域概念命名,使用完整注解与窄类型,不用 Any、宽泛 cast、投机 getattr 或非结构化字典掩盖不确定性;区分缺失与假值;让异步、资源所有权、取消与清理可见;不变量或外部操作失败时用具体错误快速失败,不用异常做常规领域分支,避免静默回退与宽泛异常处理;注释决策与约束而非机制;只优化实测热点。

使用方式:按请求的模式工作。Write 模式先建立有效状态、结果与边界解析器,实现直接路径,让封闭变体穷尽,再按真实变化、状态或边界添加抽象。Refactor 模式保持可观察行为、聚焦 diff,行为有风险时新增或更新回归测试,只在小构造模型能消除真实不支持状态时改写。Review 模式报告具体的可读性、抽象、类型、生命周期与领域模型风险,给出最小可行改进,不主动编辑除非用户要求。

验证:先运行证明改动的最窄命令再按风险扩大:针对改动的聚焦测试;项目配置的格式化器、linter 与类型检查器(对封闭并集用类型检查器证明消费者穷尽);涉及边界时运行仓库健康、打包、集成或完整门禁。最终回复先给结果与验证,设计选择仅在非显而易见或对后续工作有实质影响时解释。

限制:资料未提供具体支持的语言版本下限(仅示例提到 Python 3.12 类型别名)、完整工具清单、性能数据或与其他技能的依赖关系,暂未提供。