要求交付完整 Python 源码、依赖清单、示例输入与预期结果、自动化测试文件和中文说明，逐步列出安装、运行示例、处理自己数据及执行测试的命令，普通用户可照着操作。
请根据下面的需求，开发并交付一个普通用户可以照着说明运行的 Python 程序。直接生成完整文件、示例数据、测试用例和中文操作说明，完成实际功能，不要只给设计方案或零散代码。 项目需求：项目需求 输入与输出：输入与输出要求 已有工程：没有则新建 目标系统：Windows 10/11 64位 网络条件：首次安装可以联网 外部条件：没有已知的账号、服务或专用软件要求 普通用户只需要保存或解压文件，按顺序安装，先运行示例，再处理自己的数据。不得要求用户补代码、猜参数、手工逐个安装缺失的库或自己编造用例文件。 一、先确定可以运行的交付范围 明确程序解决什么问题、接收什么输入、生成什么结果。需求不足以确定业务结果时，只问影响实现的关键问题；其余采用合理默认值并写清楚。不要自行编造业务或把真实接口替换成未说明的假数据。 先检查已有工程，保留与本次任务无关的文件和改动。小程序优先用标准库，确有必要再增加第三方依赖；不为简单功能搭建复杂框架。默认交付 Python 源码，不要求安装 IDE，不强行打包 exe。 确定支持的 Python 版本、系统和处理器架构，并核对依赖兼容性。运行环境不能确认时标明待验证，不直接承诺所有电脑通用。 二、必须交付完整文件 新建小型项目默认采用以下结构；文件格式根据真实业务确定，最终文件名和说明必须一致： 项目目录/ main.py 程序入口与实际业务功能 requirements.txt 完整依赖清单；无第三方依赖时留空或仅写 # 注释 安装依赖.bat 检查 Python、创建环境并安装依赖 启动程序.bat 使用项目环境启动 main.py 运行示例.bat 使用项目环境执行示例 运行测试.bat 使用项目环境执行自动化测试 使用说明.txt 安装、运行、测试及常见问题 examples/ input.* 最小可用示例输入，使用业务实际格式 expected.* 对应的预期结果或可核对的期望值 cases.json 正常、异常、边界用例及预期行为 tests/ test_main.py 能执行并作断言的测试代码 output/ 运行结果，允许程序首次运行时创建 logs/ 错误日志，允许程序首次运行时创建 其中 input.*、expected.* 只表示需要按业务选择扩展名；交付时必须给出实际文件，例如 input.csv 和 expected.json，禁止真的创建带星号的文件或留下未替换的名称。 main.py 和其他必要的 .py 文件必须完整，导入路径、函数调用和命令参数前后一致。不得留下省略号、TODO、空函数或“此处自行实现”。有配置需求时提供 config.example.json，并说明如何复制和填写，用户不应修改源代码。 有文件写入能力时，直接创建这些文件；有附件能力时提供可下载的压缩包。无法生成附件时，按“相对路径 + 完整文件内容”逐个输出，明确告诉用户保存位置和编码，不能声称附件已生成。没有明确要求，不额外生成 Markdown 文档。 三、程序本身要便于普通用户使用 main.py 使用清晰的主入口，将业务逻辑与参数解析分开。提供 --help 中文参数说明；提供 --demo，读取交付包中的示例并输出到独立的演示结果目录。没有参数时显示中文操作入口或交互引导，不直接处理未知目录、不自动执行有副作用的线上操作。 文件处理类程序提供明确的 --input 和 --output 参数；其他类型程序使用符合业务的参数。用户自己的输入通过参数、文件选择或简单配置指定，不靠修改代码切换。交付说明中必须有一条处理实际业务数据的完整命令，不能只有 --help 或 --demo。 路径使用 pathlib 等可靠方式处理。内置资源相对程序目录定位；用户传入的路径按说明中的规则解析。支持中文和空格路径。示例结果放入 output/demo 下，正常业务结果与示例分开；默认不覆盖原始输入或已有结果，重名时生成明确的新路径或要求用户选择。 输入校验要覆盖文件存在性、格式、必要字段和业务边界。成功时显示处理数量、结果文件和完整保存位置；失败时用中文说明问题及下一步操作，详细异常写入日志。成功退出码为 0，失败返回非零，不能捕获所有异常后仍报告成功。 代码命名、缩进、空行和注释统一。注释解释业务规则、参数和边界，不逐行翻译代码。复用已有函数，不堆积重复逻辑、无用依赖和无效分支。 需要外部服务、数据库、浏览器、FFmpeg、模型或账号时单独列明准备条件。真实凭据不得写进源码、示例或日志。演示模式可以使用明确标注的本地样例或模拟服务，但必须说明与真实联调的区别。 四、统一依赖与安装入口 默认以 requirements.txt 作为交付包唯一的完整安装清单，包含本程序及所附测试实际需要的第三方依赖；默认使用标准库 unittest，不为了测试额外引入框架。固定经过兼容性验证的直接和间接依赖版本，不从开发机混杂的全局环境盲目导出。无第三方依赖时文件留空或只写以 # 开头的说明，不能把普通中文句子写成依赖项；安装命令仍应能正常完成。 已有工程使用其他锁文件时，保留其唯一维护入口，并从该入口生成一致的交付清单，不能手工维护两套冲突版本。开发和打包工具不混入普通用户安装流程；确实需要的测试工具须在安装说明中交代。 源码在项目目录创建 .venv。安装、示例、业务运行和测试都使用该环境内同一个 Python，通过“该解释器 -m pip”安装依赖，不混用全局 pip，也不要求用户先激活环境。 安装依赖.bat 应定位自身所在目录，检查 Python 是否存在及版本是否支持，再创建或复用 .venv、安装清单、执行 pip check。每个关键步骤都检查退出状态；失败立即停止，保留可读提示，不能继续显示“安装成功”。重复安装不得删除用户数据、配置或结果。 没有 Python 时，安装入口应清楚提示缺少的运行环境；使用说明提供 Python 官方下载入口、具体支持版本和架构、对应安装器的安装步骤及安装后的检测命令。若当前提供的是安装管理器，要写清如何安装实际运行时，不能把管理器安装完成当成 Python 运行时已就绪。不要要求用户搜索下载地址，也不要用需要 Python 的脚本解决“未安装 Python”。 默认使用普通用户权限，不要求管理员运行，不修改全局软件源、不关闭证书校验、不修改 PowerShell 执行策略。首次准备环境和以后运行分开；每次启动不重新安装或升级依赖。离线使用时必须实际提供兼容的依赖包及所需资源，并给出离线安装命令；缺少资源时如实说明。 各 .bat 入口使用同一 .venv、同一业务入口和同一套参数规则，正确引用含空格路径，失败窗口不一闪而过。调用 Python 后立即保存退出码，再显示提示或暂停，最后原样返回该退出码，不能因暂停或其他命令把失败变成成功。移动项目后 .venv 可能失效，说明如何只重建环境而保留业务文件，不将开发机的 .venv 当作可移植交付内容。 五、用例必须有文件、有预期、有断言 examples/input.* 提供小而完整的真实格式样例，明确标注为示例数据；examples/expected.* 独立给出应有的处理结果。字段、编码、分隔符、日期和数值格式与程序一致。预期结果必须根据业务规则确定，不能通过再次调用被测函数来生成期望值。 examples/cases.json 至少包含一条正常用例、一条非法输入用例和一条关键边界用例。每项写清 id、用例名称、输入文件或输入值、执行参数、预期退出码、预期结果或错误提示，以及必要的结果核对方法。引用的文件必须全部交付。案例和命令都不能使用不存在的路径。 tests/test_main.py 必须是真正可执行的测试，读取用例资料、调用业务功能或程序入口并作断言。检查输出内容、退出状态或应发生的异常；不能只打印“通过”，也不能把没有异常当作业务结果正确。 测试输出使用临时目录，与正式 output 和用户输入分开；不修改交付样例或真实业务文件。涉及网络时，分清本地模拟测试和需要凭据的集成测试，未执行的集成测试不能计为通过。 根据项目补充空数据、缺字段、错误格式、重复数据、中文及空格路径、重名输出等相关场景。时间、随机数等不固定字段要固定条件或说明比较规则，不能只删掉全部差异来让测试通过。 六、把安装和执行写成可以照抄的步骤 使用说明.txt 必须面向第一次使用的人，先说明文件解压到哪里、如何在项目文件夹打开 PowerShell，再按下面的顺序写。每步给出完整命令、预期看到的结果、失败后怎么处理。命令单独一行，不夹杂解释文字，不把终端提示符当成命令的一部分。 以下是新建项目的 Windows PowerShell 命令结构。交付时必须按实际选择的 Python 版本、项目入口和参数核对并生成可执行命令；如果 Python 默认版本不适用，要给出明确的版本选择参数，不能保留 X.Y 之类占位符。 1. 首次安装：安装已确认兼容的 Python，重新打开终端，在项目目录检查解释器、创建环境、安装全部依赖并检查冲突。 ```powershell py --version py -m venv .venv & ".\.venv\Scripts\python.exe" -m pip install -r ".\requirements.txt" & ".\.venv\Scripts\python.exe" -m pip check ``` 如果电脑只有 python 命令而没有 py，须给出检测版本后使用 python -m venv .venv 的完整替代步骤；环境建立后的命令仍统一调用 .venv 中的解释器。某一步失败先解决该步，不要求用户继续执行后续命令。 2. 运行示例：执行下面命令，再打开明确的结果文件，与交付的预期结果核对。说明示例处理了什么、正确结果是什么、再次运行会生成什么文件。 ```powershell & ".\.venv\Scripts\python.exe" ".\main.py" --demo ``` 3. 运行测试：在项目目录执行以下命令，说明应发现的用例数和成功、失败的判断方法；没有发现测试也必须判为验证未完成。 ```powershell & ".\.venv\Scripts\python.exe" -m unittest discover -s ".\tests" -p "test_*.py" -v ``` 4. 处理自己的数据：说明输入文件应放哪里、需要哪些字段、如何填写参数，并给出与真实实现一致的完整命令。文件处理项目必须包含 --input 和 --output 的使用示例，路径包含空格时加引号。除了用户自己的文件路径和业务参数，不让用户修改命令中的解释器、程序名或脚本内容。 ```powershell & ".\.venv\Scripts\python.exe" ".\main.py" --help ``` 上面的 --help 只用于查看帮助，不能替代实际业务执行命令。请根据本次实现另外写出那条命令，并解释它的每个参数、结果位置和覆盖规则。 5. 以后使用：说明哪些安装步骤不必重复，如何通过启动程序.bat、运行示例.bat、运行测试.bat 完成对应操作，或直接使用相同的 PowerShell 命令。说明如何正常退出，以及发生错误时查看哪个日志文件。 仅对用户实际要求的操作系统提供步骤。需要兼容 Linux 或 macOS 时，分别提供经过核对的命令和解释器路径，不混用 Windows 路径或 .bat。 七、实际验证后再交付 有执行环境时，从干净的项目环境按使用说明逐条执行：依赖安装、pip check、示例处理、结果比对、自动化测试和至少一条正常业务命令。检查 .py 语法、文件是否齐全、说明中的路径和命令是否有效，以及程序失败时是否返回正确状态。 按目标平台检查双击入口、中文和空格路径、重复安装、再次运行、输入错误与输出重名。不能因为开发机能运行就宣称所有用户电脑均已验证；没有目标系统、外部服务或网络条件时，将对应项标为未执行并说明所缺条件。 输出真实验证记录：系统与 Python 版本、执行命令、测试发现数量、通过与失败情况、退出状态、示例结果核对和未验证项。预期输出、实际输出、待执行计划分开写，不伪造运行日志、截图、文件或测试结论。 最后按这个顺序交付： 1. 程序用途与运行条件。 2. 完整文件下载入口；无法附文件时给文件清单和逐文件完整内容。 3. 首次安装步骤及命令。 4. 示例输入、预期结果、运行示例命令。 5. 使用自己数据的执行步骤、完整命令及参数解释。 6. 测试用例文件、测试命令和实际验证结果。 7. 以后启动方式、结果与日志位置，以及与本项目有关的常见问题处理。 参考资料 - [Python 官方下载](https://www.python.org/downloads/)：运行环境获取入口。 - [Python Packaging User Guide：隔离环境与依赖安装](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)。 - [pip：可重复安装](https://pip.pypa.io/en/stable/topics/repeatable-installs/)。 - [Python unittest：测试与用例发现](https://docs.python.org/3/library/unittest.html)。 以上资料用于核对安装与测试方法；文件清单、中文入口、用例组织和交付顺序为本提示词的要求，不代表已替未来生成的程序完成运行验证。
编写输入明确、输出可核对、设备条件清晰的 Python 接口示例，检查复制运行、资源准备和使用说明是否完整。
请为 Python接口或模块 编写或修正可运行示例。输入：接口代码与说明、目标读者、Python及依赖版本、运行设备、必要数据文件、已有示例。 示例应能复现并核对结果，运行条件须与目标项目一致。编写 Paddle 示例时，单独说明飞桨专用检查指令、执行时限与设备要求；普通 Python 项目不直接套用这些条件。 1. 选取能够解释接口主要用途的最小业务场景，明确输入、调用和输出。补齐必要导入与初始化，去掉与理解本接口无关的大段训练、部署或数据下载代码，确保读者复制后知道从哪里开始运行。 2. 使用小而有代表性的数据，列出每个输入字段、单位或形状。需要外部文件时说明取得方式与许可条件，不能引用本机私有路径；无法取得资源时提供合法可构造的小样本，不伪装成真实生产数据。 3. 明确展示用户需要核对的结果，区分实际输出与解释性注释。随机场景设置相关随机源并说明仍可能存在的环境差异；不承诺只设置一个种子就能让所有设备和版本得到逐位一致结果。 4. 写清解释器、依赖、CPU 或加速设备要求及运行步骤。需要特定硬件时不要隐含依赖默认设备；需要联网时列出资源用途和可替代方式，避免基础使用示例因大型下载长期没有反馈。 5. 用项目支持的方式执行示例或加入已有示例检查流程，核对输出的关键属性。优先修复可检查性问题，确实需要跳过时标明原因与缺失验证，不能通过跳过全部断言声称示例可靠。 6. 从空目录或干净环境复跑关键示例，检查上下文是否依赖前一个例子留下的变量、文件或全局状态。为最常见的非法输入增加短小的错误说明，使读者知道问题来自输入、环境还是接口限制。 输出：可复制示例、必要环境与资源说明、预期输出、实际运行记录及已知限制。只在用户要求时生成独立文档，其余直接给代码和说明。没有执行环境时明确标注示例尚未实跑，不能伪造输出或把手工推导写成实测结果。 官方来源（2026-09-08 核验）： - [百度飞桨《Python 文档示例代码书写规范》](https://www.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/style_guide_and_references/code_example_writing_specification_cn.html)
