Files
Agent-Workbench/docs/PYTHON-CHECKS.md
2026-11-06 14:17:57 +08:00

47 lines
4.6 KiB
Markdown

# Python工程检查契约
1.7.0将Python检查接入现有Task、检查计划、逐次确认、取消、工件、源码指纹及Git交付。Node/Python混合工程缺省仍执行原npm范围;需要Python时显式选择`python:test`、`python:compile`。
界面先「识别工程与检查」,在「选择检查范围」勾选所需名称,再「重新识别所选检查」。检查环境与执行范围进入新封存计划,确认后运行;改变选择不会修改旧计划或直接执行。
## 识别与执行范围
完整pyproject.toml使用smol-toml 1.9.1/BSD-3-Clause解析;支持明确的pytest声明或以下工作台配置,也支持常规tests/test目录的unittest识别。静态识别不导入项目、安装依赖或执行项目解释器。
```toml
[tool.agent-workbench.python]
framework = "unittest"
test-paths = ["tests"]
pattern = "test*.py"
```
pytest支持项目相对测试目录/文件和pyproject.toml/pytest.ini配置。执行固定目标,关闭环境插件自动加载、cacheprovider及配置/环境addopts;其他pytest能力和任意自定义检查命令不属于这个内置契约。
源码快照排除依赖、虚拟环境、缓存、链接和常见凭据路径。普通Node项目的默认检查选择保持;Python声明出错时明确记录错误,混合项目不因此扩大或阻断原npm检查。
## 解释器与确认
任务可通过模型工具`plan_checks`的`python_executable`指定解释器文件路径;HTTP `POST /sessions/:id/check-plans`对应字段为`pythonExecutable`。支持绝对路径或相对项目根的路径,包含空格的路径无需附加引号;不接受空值、换行或命令行参数。该选择只进入本次检查计划,不修改全局配置或旧计划,也不安装依赖。
选择顺序为:本次计划显式路径 → 检查运行器的宿主配置 → `AGENT_WORKBENCH_PYTHON_PATH` → 项目`.venv`/`venv` → 外部宿主Python。显式路径不可用时,计划如实记录missing,不悄悄换环境。支持Python 3.10+;便携包提供Node/npm和内置Python收集器,Python及pytest不捆绑安装。
外部宿主探测使用`-I -S`、明确绝对路径和临时目录。项目解释器仅静态封存路径、文件SHA256与pyvenv.cfg;直到检查获准才探测版本。启动前核对解释器、环境声明、已知基座/DLL及内置运行器;变化时拒绝探测/检查并要求重新识别。检查计划完整范围单独封存,不能通过修改记录替换执行程序。
实际检查使用`-I -B -u -X utf8`。收集器从已核对字节复制到宿主临时目录,通过stdin接收Task所属的源码/目标输入,结果写入项目外的独立文件。实际executable、argv、版本、运行器SHA256、输入SHA256和原结果字节保存为工件;当前源码和历史失败保持。
## 统计与判定
- unittest按每次startTest执行序号采集;重复用例名/同一对象、subtest失败/跳过、类初始化错误和预期失败分别核对。
- pytest从实际collection/protocol/setup/call/teardown采集;重复item对象不按nodeid去重,teardown失败覆盖之前的通过。
- 零测试、跳过、预期失败、未执行项、收集错误、非零退出码、缺失/错误的结构化结果、取消或源码变化均不能验证Task通过。stdout只能作为日志,不代替统计。
- `python:compile`对实际源码字节调用compile,不执行模块、不写项目pyc;单独编译成功不代替实际测试。
- 当前通过结果进入Git/交付报告时重新核对输入与原统计工件、执行身份和已知运行文件。证据被修改时明确要求核对;旧失败/取消记录不改写成通过。
Python测试在获准后执行项目代码;该收集器用于可靠计数与来源核对,同进程运行不是恶意代码沙箱。第三方依赖内容未整体封存,报告记录实际框架版本,不能推断全部依赖环境永久不变。重启或结果未知不自动重放。
## 开发验收环境
源码回归需安装Python 3.10+并准备`pip install -r scripts/qa-python-requirements.txt`。可将`AGENT_WORKBENCH_TEST_PYTHON`设为独立QA虚拟环境的绝对解释器路径;这项测试路径允许传给独立源码验收,不传模型Key或模型配置。实际项目解释器与开发验收解释器分别登记。
1.7.0验收状态见[QA-1.7](QA-1.7.md)。任务级解释器选择的源码修复与验证见[AH阶段验收](QA-ENGINEERING-REPAIRS-AH.md),正式部署另行记录。Python专项、桌面/390px流程、隔离工程Git和真实配置模型任务分别判定,不能将合成Provider或测试数量当作实际模型交付成功率。