用途:在编写、重构、组织或审查 Python 代码与项目时提供统一规范,目标是产出同事能顺畅阅读的代码——职责命名清晰、项目形态最小够用、控制流直接、命名平实,并在代码无法表达原因处补充说明。审查或诊断只返回发现,不代为实现;一次改动请求只包含其相关的本地检查,不做仓库范围的迁移、清理、重构或发布,途中遇到的既有问题只作为摘要中的后续项。
主要能力:从仓库出发,先读取项目说明、Python 支持范围、依赖约束、邻近实现与测试及已配置检查,再决定语法、布局或工具;在未包含迁移时保持既有公共导入、已接受输入、序列化值与持久化数据兼容。职责命名:为每个函数给出调用方可见的职责,明确数据流与副作用;多阶段任务或边界不清的新模块可先用带注解签名与简短契约文档字符串的骨架暴露边界;抽取块的条件是减少读者理解成本并返回一个有名字的值、决策或效应,调用次数不决定是否成函数;先扁平化(提前返回、用映射或 match 替代常量 if/elif 链),保持解析、计算、输出分阶段相连,I/O 与共享状态变更留在编排函数中。项目形态:按项目类型选择行——脚本或 notebook 邻近代码单模块;CLI 扁平包;库或 SDK 在 init.py 暴露公共面、私有 _ 模块承载机制;领域逻辑少的 HTTP 服务用框架原生路由等、增长后按功能划分;有真实规则与多集成的应用用功能包(纯 model.py、service.py 用例、ports.py 协议、adapters/、单一组合根);数据或 ML 管道用函数式核心加入口脚本;长运行 worker 或 agent 用循环外壳、处理函数、纯决策、端口。仅在命名的触发条件时才升级结构。用 uv 管理工作流:pyproject.toml、uv.lock、uv add、uv sync、uv run;pip install 与 uv pip install 不作为常规安装方式。
使用方式与限制:注解函数、返回、模型字段、属性、模块级值和局部变量;用 dict[str, int]、list[Item]、Item | None,不用 typing.Dict 或 typing.List;导入 SDK 真实类型而非 Any;参数较多时其余用仅关键字。应用自有结构化数据默认用 Pydantic BaseModel;库或 SDK 用户不应继承 Pydantic 依赖,以及实测热点路径,则用 dataclass、NamedTuple 或普通类并在记录旁说明原因。模块保持单一可一句话说明的职责,按变更原因而非种类或行数拆分;新模块先私有,init.py 通过 all 或 from ._x import Name as Name 重导出公共面。长度约为 500 行手写一方代码时复核,1000 行时在可命名边界拆分或说明理由。为公共名补充文档字符串,保持 # noqa、# type: ignore、# ty: ignore、# pragma: no cover 等工具指令,除非该工具行为在范围内;仅文档或注释请求不授权改动签名、注解、控制流或依赖。正确性方面,每包一个异常根,按调用方处理方式派生子类并在一个接缝处翻译传输与库异常;资源所有权与异步取消显式化;通过 uv run 运行与改动行为相关的仓库检查,公共导入、输入、序列化字段、错误行为或清理路径变化时在固定输入上运行真实入口。完成的标志是实现或审查了请求结果并运行了相关检查,或报告了确切限制。资料未提供具体收费、价格、平台与效果信息。