python-authoring

编写 Python

编写满足请求且符合 easy-cheese 规范的最小可读 Python 改动。

这是一项仓库本地技能。请将其保留在 .agents/skills/python-authoring/ 下；不要将其复制到已发布的 skills/ 目录树中，也不要添加 agents/openai.yaml。重命名此目录时，必须更新 .gitignore 中匹配的 !.agents/skills/<dir>/ 行——该路径列表是允许列表，重命名后的目录如果没有对应条目，就会在不提示的情况下变成未跟踪状态。

按以下顺序操作

1. 阅读根配置、所属技能、目标导出项、直接调用方和附近的惯例。
2. 确保每一处改动都能追溯到请求。不要臆造编排、兼容层、抽象、依赖或面向未来的灵活性。
3. 将代码放在所属包中，并保留包的边界。
4. 在边界处验证一次不可信输入，然后使用带类型的可信数据。
5. 选择清晰简洁的 Python 写法；不要为了压缩代码而降低可读性。
6. 只清理此次改动引入的冗余，以及被此次改动弃用的代码。
7. 使用 basedpyright 对改动文件进行类型检查，运行针对性测试，重新构建受影响的包，然后运行 just check。

运行时代码优先使用标准库

• 目标 Python 3.12。直接使用其语言和类型标注特性；不要为旧版本添加兼容代码。
• 对 src/ 下打包的辅助工具，将标准库视为默认依赖预算。任何第三方运行时依赖都必须是纯 Python，并获准加入 requirements/runtime.txt；构建包时会将内部和外部哈希解析到一个临时依赖文件中。
• 复用现有的 JSON 优先、YAML 可选的清单边界，而不是在新的打包模块中导入 PyYAML。
• 将已配置的第三方导入视为特定用途的例外：现有验证器、文档工具和清单/测试路径可使用 PyYAML；测试可使用 pytest。新增依赖需要明确的包和 CI 决策。
• 相比手写实现，优先使用 argparse、json、pathlib、tempfile、shutil、zipfile、collections、itertools 和 contextlib。

明确建模并验证数据

• 使用适当的标准库解析器解析不可信文本，要求容器形状符合预期，检查必需键和值类型，并在边界处引发特定错误。
• 当命名字段和不变量能让契约更清晰时，将已验证的映射转换为冻结数据类或领域值类型。
• 仅当映射必须保持为映射时才使用 TypedDict。它描述静态结构，不会验证运行时输入。
• 对封闭值集合使用 Enum 或 Literal；只有在结构化接口有多个实际使用方时才使用 Protocol。
• 为函数和公共方法的边界添加完整类型标注。局部类型可明确推断时，无需添加显而易见的标注。
• 如果命名记录能让契约更清晰，就不要将原始结构化字典传过解析边界。

保留技能包边界

• 将技能运行时代码保留在 src/easy_cheese/skills/<skill_name>/ 下，并在 commands.py 中声明其 CLI 接口。
• 只有在多个现有技能需要相同行为时，才将代码移至 src/easy_cheese/shared/；并将其打包到每个所属归档中。
• 不要导入其他技能的内部实现。每个归档都应包含完整的纯 Python 运行时依赖闭包。
• 将跨技能编排放在所属工作流接口处，而不是叶子辅助工具中。通过公共或持久化契约通信，以避免反向依赖和循环依赖。
• 绝不要手动编辑 skills/<skill>/scripts/<skill>.pyz。更改归档输入后运行 just wedge-build，并运行 just wedge-check 验证已提交的归档。
• 保持 CLI 模块精简：接收 argv，返回整数状态码，将诊断信息打印到 stderr，并通过非零退出码传递失败。
• .github/scripts/ 中的验证器必须只读。它们负责检查和报告，不得修改工作区。

倾向于编写简洁、易读的 Python

• 只有在确实需要基于形状分派时才使用 match；二选一的判断用简单的 if。
• 对稳定的命令到函数分派使用处理函数映射；只有一两个分支时不要创建注册表。
• 仅当赋值表达式能避免重复计算或让循环条件更清晰时才使用它。
• 对纯粹的集合查询或转换，使用 any、all、推导式和生成器表达式。如果循环需要维护状态、产生副作用，或能更清晰地提前退出，就保留循环。
• 如果结果只会被消费一次，优先使用生成器。
• 使用 enumerate、直接迭代、f 字符串、上下文管理器和 pathlib，而不要手动处理索引、拼接字符串、清理资源或操作路径。
• 只忽略明确命名且有意忽略的失败。绝不要使用不带异常类型的 except、吞掉 Exception、在失败时返回空默认值，或使用 contextlib.suppress(Exception)。
• 新增的顶层函数应控制在 40 行以内，除非将一段连续算法拆开会显得刻意。
• 优先使用单个清晰的表达式，而不是冗长的辅助代码；但如果中间变量名能说明意图，就应拆分过于密集的表达式。

完成前清理冗余内容

• 删除复述代码的说明性注释和文档字符串。保留不明显的设计理由和公共 API 文档。
• 除非当前任务需要这个扩展点，否则移除只有一个具体调用方的抽象。
• 根据领域概念命名值，而不是根据容器或实现类型命名。
• 按行为合并重复测试；不要添加浅层的输入变体测试。
• 修复根本的 lint 问题，而不是添加抑制项。

使用 basedpyright 进行类型检查

• 完成前运行 basedpyright <changed .py files>（如果找不到该二进制文件，则改用 uvx basedpyright）。修改过的文件必须报告零错误和警告。
• 仓库配置位于 pyproject.toml 的 [tool.basedpyright] 中：包含路径、pythonVersion = "3.12"，以及一个将 src/easy_cheese_schemas 固定为 3.11 的执行环境，以符合已发布 wheel 的 requires-python >=3.11。有意不设置 typeCheckingMode——basedpyright 默认使用 recommended，会启用所有规则，并区分错误和警告，同时启用 failOnWarnings，因此全量检查遇到警告也会失败。
• 整个仓库均通过 basedpyright 检查，just typecheck（已接入 just check、just ci 和 validate 工作流）会强制要求零错误和警告。你的改动引出的任何诊断都必须在完成前修复——没有基线问题，也没有可延后处理的既存积压。导入会通过 .venv-typing 解析；just typecheck-install 会根据 requirements/typing.txt（重新）创建该环境。
• basedpyright 比原版 pyright 更严格；其额外规则在此处必须遵守：将有意忽略的调用结果赋给 _（reportUnusedCallResult），合并隐式字符串拼接，并使用 cast 将不可信边界读取转换为已验证的类型。
• 对不包含在 wheel 中的仅构建模块，使用 importlib.import_module 加上经 cast 类型标注的 getattr 加载；不要使用检查器无法解析的静态导入。
• 在源头修复类型问题。确实无法避免抑制时，使用针对规则的 # pyright: ignore[ruleName]，绝不要使用不带规则的 # type: ignore 或文件级开关——reportIgnoreCommentWithoutRule 会标记未指定规则的忽略项。
• 工具需要机器可读的诊断信息时，使用 --outputjson。在 GitHub Actions 中，CLI 会自动检测 CI 环境并生成内联 PR 注释，无需额外标志。
• 正确解读退出码：0 表示无问题，1 表示报告了诊断，2 表示发生致命内部错误，3 表示配置无法读取，4 表示 CLI 参数错误。将 2–4 视为工具故障，需要修复或报告，绝不要将其当作类型问题。
• 该二进制由 mise 管理并固定到确切版本（上游建议精确固定版本以保证可复现性）；pyright 和 pyright-langserver 这两个 shim 实际会解析为 basedpyright。

测试与完成

• 测试可观察行为及其重要原因；不要添加实现出错时仍能通过的断言。
• 将文件系统测试限制在 tmp_path 或等效的临时目录中。不要依赖用户路径、仓库外部状态、网络访问或自动加载的 pytest 插件。
• 先运行受影响范围最小的测试。聚焦的 pytest 和浏览器命令会执行已提交的 skills/<skill>/scripts/<skill>.pyz 归档，不会重新构建。测试归档隔离时，确保无法导入仓库中的模块。
• 归档输入发生变化后，先运行 just wedge-build，再运行 just wedge-check，然后才能让聚焦测试执行归档。生成的运行时源文件发生变化时，运行 just update-generated。
• 将 just check 作为最终项目检查。

完成检查

确认：

• 运行时导入遵循标准库优先、按功能面区分的依赖策略。
• 边界输入只验证一次，并转换为适当的可信表示。
• 代码位于所属技能的源文件中，或位于有充分理由的共享模块中。
• 命令注册、生成的运行时源文件和已提交的归档在适用时均与其输入一致（scripts/runtime_gates.py、just wedge-check）。
• CLI 和验证器出错时会明确报错；只读验证器保持只读；测试相互隔离。
• 不存在静默失败、臆测性的抽象、叙述性注释、不必要的局部类型注解或无关清理。
• 更改过的 Python 文件通过 basedpyright 检查，错误和警告均为零。
• 已重新运行 just check 并通过。