📦 deps(standards): vendor playbook

2025-12-14 17:55:55 +08:00
parent e75027b80a eada742d75
commit dbdde4ed48
49 changed files with 2756 additions and 0 deletions
@@ -0,0 +1,27 @@
+# 代码质量（Code Quality）
+
+本文件定义代理对代码质量的最低要求与审查清单（Python）。
+
+## 1. 总体要求
+
+- 改动聚焦目标；避免“顺手重构”。
+- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。
+- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。
+
+## 2. 可读性
+
+- 复杂逻辑拆分为具名函数/模块；避免超长函数。
+- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。
+- 注释解释“为什么”，避免注释重复代码表述。
+
+## 3. 错误处理
+
+- 失败必须可观测：返回码/异常/日志至少一种要明确。
+- CLI/自动化脚本：遇到不可恢复错误应非零退出码。
+
+## 4. Review 清单
+
+- 是否引入了不必要的新依赖？
+- 是否遵循 `pyproject.toml` 与 lint 配置？
+- 是否对 I/O（文件/网络/数据库）失败路径做了处理？
+- 是否需要补测试或示例？