python-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring Python

编写Python代码

Produce the smallest readable Python change that satisfies the request and matches easy-cheese.

This is a repository-local skill. Keep it under

.agents/skills/python-authoring/

; do not mirror it into the published

skills/

tree or add

agents/openai.yaml

. Renaming this directory requires updating the matching

!.agents/skills/<dir>/

line in

.gitignore

— that path list is an allowlist, so a renamed dir without its own line is silently untracked.

生成满足需求且符合easy-cheese风格的最小可读Python代码变更。

这是一个仓库本地技能。请将其放在

.agents/skills/python-authoring/

目录下；不要将其镜像到已发布的

skills/

目录中，也不要添加

agents/openai.yaml

文件。重命名此目录时，需要更新

.gitignore

中对应的

!.agents/skills/<dir>/

行——该路径列表是允许列表，因此重命名后的目录如果没有对应的行，会被自动忽略追踪。

Work in this order

工作顺序

Read the root configuration, owning skill, target exports, immediate callers, and nearby conventions.
Keep every changed line traceable to the request. Do not invent orchestration, compatibility layers, abstractions, dependencies, or future flexibility.
Put code in the owning package and preserve the bundle boundary.
Validate untrusted input once at the boundary, then work with typed trusted data.
Choose the clearest succinct Python construct; do not compress code until it becomes harder to read.
Remove only slop introduced by the change and code that the change orphaned.
Run targeted tests, rebuild affected bundles, then run
```
just check
```
.

阅读根配置、所属技能、目标导出、直接调用方以及附近的约定。
确保每一行变更都能追溯到需求。不要凭空添加编排逻辑、兼容层、抽象、依赖或未来扩展性代码。
将代码放在所属包中，并保留捆绑边界。
在边界处对不可信输入进行一次验证，之后使用类型化的可信数据进行处理。
选择最清晰简洁的Python语法结构；不要过度压缩代码，以免降低可读性。
仅移除本次变更引入的冗余代码以及变更导致的废弃代码。
运行针对性测试，重新构建受影响的捆绑包，然后执行
```
just check
```
。

Keep runtime code stdlib-first

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

Target Python 3.12. Use its language and typing features directly; do not add compatibility code for older versions.
Treat the standard library as the dependency budget for bundled helpers under
```
src/
```
and
```
shared/scripts/
```
. Do not add Pydantic, Requests, pandas, or another runtime dependency.
Reuse the existing JSON-first, optional-YAML manifest boundary instead of importing PyYAML into new bundled modules.
Treat configured third-party imports as surface-specific exceptions: PyYAML for existing validators, docs tooling, and manifest/test paths; pytest for tests. A new dependency requires an explicit package and CI decision.

Prefer

argparse

json

pathlib

tempfile

shutil

zipfile

collections

itertools

, and

contextlib

over hand-written equivalents.

目标版本为Python 3.12。直接使用其语言和类型特性；不要为旧版本添加兼容代码。
将标准库视为
```
src/
```
和
```
shared/scripts/
```
下捆绑辅助工具的依赖预算。不要添加Pydantic、Requests、pandas或其他运行时依赖。
重用现有的JSON优先、可选YAML清单边界，不要在新的捆绑模块中导入PyYAML。
将已配置的第三方导入视为特定场景的例外情况：PyYAML用于现有验证器、文档工具以及清单/测试路径；pytest用于测试。新增依赖需要明确的包管理和CI决策。

优先使用

argparse

、

json

、

pathlib

、

tempfile

、

shutil

、

zipfile

、

collections

、

itertools

和

contextlib

，而非手写等效代码。

Model and validate data explicitly

显式建模并验证数据

Parse untrusted text with the appropriate stdlib parser, require the expected container shape, check required keys and value types, and raise a specific error at the boundary.
Convert validated mappings into frozen dataclasses or domain value types when named fields and invariants make the contract clearer.
Use
```
TypedDict
```
only when a mapping must remain a mapping. It documents a static shape; it does not validate runtime input.
Use
```
Enum
```
or
```
Literal
```
for closed value sets and
```
Protocol
```
for structural interfaces that have multiple real consumers.
Fully annotate function and public-method boundaries. Omit obvious local annotations when inference is clear.
Do not pass raw structured dictionaries beyond the parsing boundary when a named record makes the contract clearer.

使用合适的标准库解析器解析不可信文本，要求符合预期的容器结构，检查必填键和值类型，并在边界处抛出特定错误。
当命名字段和不变量能让契约更清晰时，将验证后的映射转换为冻结dataclass或领域值类型。
仅当映射必须保持为映射时才使用
```
TypedDict
```
。它用于记录静态结构，但不验证运行时输入。
对封闭值集使用
```
Enum
```
或
```
Literal
```
，对有多个实际消费者的结构化接口使用
```
Protocol
```
。
为函数和公共方法边界添加完整的类型注解。当类型推断清晰时，可以省略明显的局部变量注解。
当命名记录能让契约更清晰时，不要将原始结构化字典传递到解析边界之外。

Preserve skill package boundaries

保留技能包边界

Keep a skill-owned executable helper in its registered
```
src/<skill>/
```
source directory.
Move code to
```
shared/scripts/
```
only when multiple existing skills need the same behavior.
Register executable subcommands in
```
scripts/build_pyz.py
```
under
```
SKILLS
```
. Use
```
Shared(...)
```
for shared entry points and
```
EXTRA_MODULES
```
only for an explicit cross-skill source dependency.
Do not casually import another skill's internals. Each generated bundle must contain only its owning source plus explicitly registered local or shared dependencies.
Never edit
```
skills/<skill>/scripts/*.pyz
```
by hand. Run
```
just bundle
```
after changing
```
src/
```
,
```
shared/scripts/
```
, or bundle registration, and commit the regenerated bundle with its source when publication is in scope.
Keep CLI modules thin: accept
```
argv
```
, return an integer status, print diagnostics to stderr, and propagate failure through a nonzero exit.
Keep
```
.github/scripts/
```
validators read-only. They inspect and report; they do not mutate the workspace.

将技能所属的可执行辅助工具放在其注册的
```
src/<skill>/
```
源目录中。
仅当多个现有技能需要相同行为时，才将代码移至
```
shared/scripts/
```
目录。
在
```
scripts/build_pyz.py
```
的
```
SKILLS
```
下注册可执行子命令。对共享入口点使用
```
Shared(...)
```
，仅在存在明确跨技能源依赖时使用
```
EXTRA_MODULES
```
。
不要随意导入其他技能的内部代码。每个生成的捆绑包必须仅包含其所属源以及明确注册的本地或共享依赖。
切勿手动编辑
```
skills/<skill>/scripts/*.pyz
```
文件。修改
```
src/
```
、
```
shared/scripts/
```
或捆绑注册后，执行
```
just bundle
```
，并在需要发布时将重新生成的捆绑包与其源文件一起提交。
保持CLI模块精简：接收
```
argv
```
，返回整数状态码，将诊断信息打印到stderr，并通过非零退出码传播失败状态。
保持
```
.github/scripts/
```
下的验证器为只读状态。它们仅用于检查和报告，不要修改工作区。

Prefer succinct, readable Python

优先选择简洁、可读的Python代码

Use
```
match
```
for genuine shape-based dispatch; keep a simple
```
if
```
for a binary decision.
Use
```
any
```
,
```
all
```
, comprehensions, and generator expressions for pure collection queries or transformations. Keep a loop when it carries state, side effects, or clearer early exits.
Prefer generators when the result is consumed once.
Use
```
enumerate
```
, direct iteration, f-strings, context managers, and
```
pathlib
```
instead of manual indexing, string assembly, cleanup, or path manipulation.
Ignore only named, intentional failures. Never use a bare
```
except
```
, swallow
```
Exception
```
, return an empty default on failure, or use
```
contextlib.suppress(Exception)
```
.
Keep new top-level functions at 40 lines or fewer unless one contiguous algorithm is clearer than an artificial split.
Delete narration comments and docstrings that restate the code. Keep non-obvious rationale and public API documentation.
Prefer one clear expression to verbose scaffolding, but split dense expressions when intermediate names explain intent.

对真正基于结构的分发使用
```
match
```
；对于二元决策，保持使用简单的
```
if
```
。
对纯集合查询或转换使用
```
any
```
、
```
all
```
、推导式和生成器表达式。当循环需要携带状态、副作用或更清晰的提前退出时，保留循环写法。
当结果仅被消费一次时，优先使用生成器。
使用
```
enumerate
```
、直接迭代、f-strings、上下文管理器和
```
pathlib
```
，而非手动索引、字符串拼接、清理或路径操作。
仅忽略明确命名的预期失败。切勿使用裸
```
except
```
、吞掉
```
Exception
```
、失败时返回空默认值或使用
```
contextlib.suppress(Exception)
```
。
新增的顶级函数保持在40行以内，除非一个连续的算法比人为拆分更清晰。
删除重复代码的叙述性注释和文档字符串。保留非显而易见的原理说明和公共API文档。
优先使用清晰的表达式，而非冗长的框架代码，但当中间变量能解释意图时，拆分复杂表达式。

Test and finish

测试与收尾

Test observable behavior and the reason it matters; do not add assertions that can pass when the implementation is broken.
Keep filesystem tests inside
```
tmp_path
```
or an equivalent temporary directory. Do not depend on user paths, repository-external state, network access, or auto-loaded pytest plugins.
For bundle changes, exercise the generated
```
.pyz
```
with repository imports unavailable and verify cross-skill code is absent unless explicitly registered.
Run the most focused affected tests first.
Run
```
just bundle
```
when bundle inputs changed.
Run
```
just check
```
as the final project gate.

测试可观察的行为及其重要性；不要添加在实现损坏时仍能通过的断言。
将文件系统测试放在
```
tmp_path
```
或等效的临时目录中。不要依赖用户路径、仓库外部状态、网络访问或自动加载的pytest插件。
对于捆绑包变更，在无法访问仓库导入的情况下测试生成的
```
.pyz
```
，并验证跨技能代码仅在明确注册时才存在。
首先运行最聚焦的受影响测试。
当捆绑包输入变更时，执行
```
just bundle
```
。
将
```
just check
```
作为最终的项目检查关卡。

Completion check

完成检查

Confirm:

Runtime imports obey the stdlib-first, surface-specific dependency policy.
Boundary input is validated once and converted into an appropriate trusted representation.
Code lives in the owning skill source or a justified shared module.
Bundle registration and generated
```
.pyz
```
files match their sources when applicable.
CLI and validator failures remain loud, read-only validators remain read-only, and tests are hermetic.
No silent failures, speculative abstractions, narration comments, unnecessary local annotations, or unrelated cleanup remain.
A fresh
```
just check
```
run passed.

确认：

运行时导入遵循“标准库优先、特定场景例外”的依赖策略。
边界输入仅被验证一次，并转换为合适的可信表示形式。
代码位于所属技能源目录或合理的共享模块中。
适用时，捆绑注册和生成的
```
.pyz
```
文件与其源文件匹配。
CLI和验证器的失败提示清晰，只读验证器保持只读状态，测试是封闭环境的。
不存在静默失败、推测性抽象、叙述性注释、不必要的局部注解或无关的清理操作。
全新的
```
just check
```
运行已通过。