质量检查配置与工具协议
本页面向项目维护者和独立工具作者。检查可以来自仓库、插件或本次调用的专项命令;公开 JSON 与命令协议不要求工具导入 Pi。下文 TypeScript 服务签名仅用于说明内部设计。
职责与适用范围
Wenext-Pi 冻结检查计划、管理进程、保留证据,并决定任务能否完成。领域工具实现自己的测试和报告。普通命令不需要 Pi SDK、任务解析器或 test-tool 包。内置生命周期插件可以贡献 checks: CheckDefinition[];仓库与插件声明使用相同的校验和执行流程。
自动化检查与需求验收
wenext_check 返回检查结果和 automationOnly: true,通过后 archived: false。结果统计的是检查数量,不是任意工具内部的测试用例数量。智能体还需对照已有 PRD 与正式方案核对功能、交互、视觉和外部条件。
必要检查失败或证据过期仍会阻断;建议性检查失败如实保留。没有适用检查时显示未验证。阅读验收指导不新增批准、文档或检查执行,也不授权归档。测试标题、覆盖率或截图文件存在不能单独证明需求正确。
运行时服务位于 runtime/execution、runtime/scope、runtime/evidence 和 runtime/quality。质量插件使用这些服务,不创建 Git 或变更范围插件工厂。当前范围提供方是 Git,本版未实现所有版本控制系统或工具链。
本次专项检查
没有仓库配置也可由智能体执行实际验证:
{
"checks": [
{ "id": "syntax", "command": ["node", "--check", "src/main.js"] }
]
}这是 wenext_check 的工具参数。专项检查只接受 id、command、可选 cwd 与 timeoutMs,本轮执行时无条件运行,失败如实返回。每次调用只使用本次提供的清单,不与前几轮累积;省略 checks 只执行当前仓库和插件检查。专项检查不能覆盖同名仓库/插件检查,同名错误会指出具体 ID。
命令、输入指纹和结果一起冻结在 <task>/quality/check-plans/<runId>/ 中。重启和归档仍可复用完整且有效的证据;不自动重放专项命令。上一轮专项验证失败、未完成或证据失效时,归档提示重新执行 wenext_check 并明确选择当前验收需要的检查,不会自动以空检查替换失败。修复后可选择同一命令或适合当前验收的命令,失败历史始终保留。仓库/插件声明的必要检查不能通过缩减专项清单取消;专项验收的必要性由需求和方案决定,不能仅为归档而丢掉未完成的验收。
旧版 <task>/quality/task-checks.json 保留为历史,不再加载为当前质量策略,也不需要手工删除或迁移。升级后旧证据仍须通过当前配置、插件、输入和完整性校验;不匹配时重新执行适用检查,不把历史通过冒充当前通过。永久的仓库质量要求应放在仓库规则或插件中。
仓库配置与接口
外层 .agents/rules/workflow.json 保持 schemaVersion: 1。既有 quality.checks 声明继续有效:检查必需、始终执行,并以进程退出码为零作为领域契约。新增策略字段要求显式设置嵌套的 quality.schemaVersion: 2:
{
"schemaVersion": 1,
"quality": {
"schemaVersion": 2,
"requireVerified": true,
"inputs": ["src", "assets", "package.json"],
"checks": [
{
"id": "tests",
"command": ["npm", "test"],
"required": true,
"when": { "changedPaths": ["src", "assets"] }
},
{
"id": "domain-report",
"command": ["my-check", "--input", "{{requestFile}}", "--output", "{{outputDir}}"],
"resultFile": "result.json",
"artifacts": ["report.json"],
"required": false
}
]
}
}my-check 仅为示例,Pi 不会安装它。when.changedPaths 使用精确的相对文件或目录路径,不支持通配符或结尾斜杠。完整 Git 范围中没有匹配改动时跳过该检查;范围未知时保守执行。是否必需、适用性和原因在执行前冻结。建议性检查(required: false)不阻止完成,但失败仍使收据为 failed,不会虚报 passed。
命令和可选 verifyCommand 都是非空参数数组,不使用 Shell。cwd 默认为项目根,且必须位于其中。超时默认 120000 毫秒,允许 1000–86400000 毫秒;应按完整顺序执行的测试集设置预算,宿主不会从子检查超时推断总预算。仓库、插件和任务声明合计最多 16 个唯一检查 ID,使用小写字母、数字和连字符,并以字母开头。
检查顺序执行,普通命令失败会被记录,后续检查仍执行。工具或证据采集错误会留下不完整计划。env 提供字符串覆盖值,拒绝保留的 WENEXT_PI_* 键。规范化策略会保存在本地,因此不要把秘密写入配置。
artifacts 最多接受新输出目录内 32 个精确相对文件路径。产物必须为普通文件,每个最多 16 MiB;不允许路径越界、反斜杠、绝对路径或通配符。resultFile 同样会被固定到证据中,且必须包含:
{ "schemaVersion": 1, "verdict": "passed" }即使进程退出码为零,verdict: "failed" 也会阻断必需检查。结构化结果缺失或格式错误会产生诊断失败,不能授权完成。可选 status 将 passed|failed|blocked|unverified 保留为 domainStatus;可选字符串数组 reasons 提供有长度限制的诊断。passed 状态要求通过判定,其它状态均要求失败判定。
即使报告声称成功,进程非零退出仍是不成功。领域工具非零退出时,也会保留合法报告与已存在的声明产物。除非显式声明 resultFile,既有非结构化报告保持原有含义。
以下运行时签名属于内部 TypeScript 契约,不是已发布的 SDK:
executeCommand({ command, cwd, env, timeoutMs, signal? }): Promise<ExecutionResult>
ScopeService.capture(taskDirectory, inputs?): ChangeScopeEvidence
CommandEvidenceService.begin(taskDirectory, binding, checkId, cwd, scope): CommandRun
CommandEvidenceService.finish(run, result, artifacts, output): QualityCheckEvidence
CommandEvidenceService.verify(taskDirectory, binding, result): CommandRun公开输入、执行与证据
| 占位符 | 环境变量 | 含义 |
|---|---|---|
| WENEXT_PI_PROJECT_ROOT | 规范化后的仓库根目录 |
| WENEXT_PI_CHECK_OUTPUT_DIR | 新建的仓库外输出目录 |
| WENEXT_PI_CHECK_REQUEST | 公开请求 JSON |
只替换完整的参数元素;--output= 不会展开,应将选项和取值分开传入。旧 taskDir/taskId/changeScope 占位符和环境变量仍可使用,但工具无需消费它们。
公开请求保持模式版本 1,包含 checkId、projectRoot、cwd、outputDir、scope。范围保留版本 1 的 observedPaths、ambiguousPreexistingPaths、baselineAvailable、complete、attribution、inputFingerprint 字段,并新增 reasons。路径不代表改动作者。复核器收到原始请求和输出路径。
请求包含可选 scope.writeScope,记录批准路径、原生操作路径、人工确认路径、外部/待决路径、修订号与证据摘要。这些事实参与输入指纹,因此检查后做出范围决定会使旧证据过期。原始 Git 归属和覆盖含义不变,详见写入范围契约。工具无需读取私有任务文件即可消费此新增字段。
执行状态区分 succeeded、failed、cancelled、timed_out、environment_unavailable 和 tool_error;退出码与领域判定分别存储。每路日志最多 1 MiB,并记录截断。POSIX 进程在独立进程组中运行,正常退出、取消或超时时向剩余组成员发送清理信号。清理结果是 process_group_signalled,不保证回收了所有可能的守护进程;主动创建其它会话的进程可逃离此边界。清理后管道仍未关闭会产生明确的工具错误。
Windows 当前会在启动前返回 environment_unavailable/不支持;目前未实现 Windows 托管进程树执行。
私有状态位于业务仓库源码之外:
quality/check-plans/<run>/:不可变的模式版本 2 计划和结果,包括任务/项目根、规范化配置、插件版本、阶段声明、范围及各项选择原因。active-plan.json指向最新运行。quality/command-runs/<run>/:启动状态、公开请求、输出与冻结的诊断/报告。版本 2 清单绑定检查计划、任务、插件、配置和输入。收据引用为相对任务目录的{path, sha256},归档后仍有效。- 复核器拥有独立证据,绑定原命令引用。证据缺失、中断或失败都不能授权最终完成。
- 阶段模式版本 2 记录绑定任务 ID、唯一阶段运行、声明和产物摘要;不可变运行副本会与当前输出比较。旧标记仍可读取,但不能证明必需阶段实际运行过。
任务收据保持模式版本 2,新增的逐检查字段显式携带 schemaVersion: 2。旧收据/检查字段和版本 1 证据仍可读取,但不会自动变成新的完整计划;需显式重跑检查来生成当前完成证据。启动时不重放任何检查。
结果与错误处理
| 条件 | 行为 |
|---|---|
| 没有检查或全部不适用 | unverified;未要求 requireVerified 时允许完成 |
| 必需检查通过且证据仍有效 | 允许完成 |
| 必需检查失败、取消、超时、可执行文件缺失或结果格式错误 | 阻断并保留诊断 |
| 建议性命令失败 | 保留失败,本身不阻断完成 |
| 配置、插件版本、检查选择、阶段声明或任务变化 | 阻断,需新建检查运行 |
| 报告、请求、日志或清单缺失/被篡改 | 阻断 |
| 新运行之后提交更旧的成功运行 | 阻断 |
| 必需阶段输出缺失、变化或绑定其它任务/运行 | 阻断 |
| 最终复核证据缺失 | 阻断,包括直接调用任务仓储接口 |
后续 beforeFinish 钩子改变已检查输入 | 拒绝过期证据,基于当前输入重跑 |
| 同进程并发完成,或任务/会话绑定变化 | 阻断 |
宿主正常完成顺序为:显式请求的 Markdown 知识准备 → 复用当前完整成功证据 → beforeFinish 钩子/复核器 → 同步校验阶段、证据和输入 → 更新任务状态并归档。缺失或过期证据须显式调用 wenext_check,归档不执行新的检查命令。知识修改若使输入失效也须先验证;命令行和直接应用调用共用最终门禁。
最终校验与本地状态修改之间没有 await。完成租约以及任务/指针对比通过本地状态锁覆盖本地进程并发。完成后钩子只负责观测。若只准备规范且检查数为零,则仍为未验证并可完成,因为不存在输入可能过期的通过检查。
输入覆盖与运行限制
Git 范围指纹涵盖已观测的未提交/已提交路径和策略目录。显式 quality.inputs 替换自动内容选择,但策略根始终纳入;必须声明检查需要的全部输入。无 Git 时,Pi 对声明路径或整个仓库生成快照,适用性仍保持未知。
源码快照以 64 KiB 分块流式读取,默认最多访问 10000 个路径、耗时 5 秒,不设默认总字节上限;仍支持调用方显式字节预算。超限会明确失败,应缩小声明范围或拆分检查。依赖与生成的任务状态被排除。被忽略文件需要显式输入;已安装工具链、继承环境和外部服务需要领域验证。
质量尝试不成功后,可显式调用 wenext_check 重跑,无需重新批准方案或获得重试许可,包括环境修复后源码未变的情况。宿主不自动循环;并发运行和历史损坏仍会阻断。wenext_check 执行检查及既有 beforeFinish 校验钩子,不进行归档流转、知识采集或完成后观测。人工确认归档仍使用 wenext_finish,见任务执行。
已完成的复核证据会被复用,不隐式重放。预算与人工授权的失败/阻断关闭见重试与失败关闭契约,完整性门禁始终适用。有外部副作用的命令需自行保证幂等。本地哈希检测受信任本地执行中的文件变化,不是防范同用户进程的签名或沙箱。指标保留状态、耗时与选择原因,不保留标准输出、报告或配置中的环境值。
独立工具接入
通常只需在仓库规则中声明一项检查,调用已安装的独立工具,将 --input --output 作为分开的参数元素传入,并声明 resultFile 及可选 artifacts/verifyCommand。这些选项属于工具,不属于 Pi。无需仓库侧 Python/Node 工作流桥接或生命周期插件。
独立工具可以根据项目与公开范围发现包和测试入口;业务仓库通过技能、规则及普通测试/构建配置维护领域要求。
| 关注点 | Pi 的职责 | 独立工具/仓库的职责 |
|---|---|---|
| 改了什么、批准了什么 | 提供范围事实和输入指纹 | 保守使用事实,不能用未知范围作为跳过义务的理由 |
| 应测试什么 | 冻结声明检查和适用性 | 发现执行载体/用例,应用领域规则 |
| 未发现用例/缺少必需场景 | 校验声明结果与进程状态 | 返回 verdict: failed 或非零退出,并附诊断报告 |
| 领域阻断/不支持 | 保留不成功证据 | 返回失败判定或非零退出,在报告中保留领域细节 |
| 可执行文件缺失/超时/取消 | 管理执行状态和重试策略 | 不将环境错误改称领域通过 |
| 完成/批准的失败关闭 | 控制任务状态、证据与人工确认 | 绝不写入 Pi 私有任务/尝试状态 |
| 指标 | 发出通用任务/检查/尝试事实 | 无需重复上报或解析私有状态 |
公开结果模式版本 1 保留通过/失败判定,并接受新增的 status 与 reasons。它不统一测试用例数、覆盖率百分比或领域报告模式。
Pi 的 requireVerified 要求一项适用检查通过,不要求任意命令内部必须存在非零用例数。因此,直接执行 --passWithNoTests 的命令可能满足自己声明的退出码契约;领域消费方必须自行约束用例发现与覆盖义务。没有此类契约时,不能仅凭退出码为零宣称领域验证通过。
声明式插件 checks 使用同一套尝试、重试和失败关闭流程。自定义 checkRun 钩子没有标准重放/关闭契约,其存在会阻止按失败或阻断结果关闭任务。普通领域工具应使用声明式检查。用户目录动态插件加载和客户端 SDK 仍属后续能力。遵循公开 JSON 协议的新独立工具无需修改 Pi 内部,也可脱离 Pi 使用。
消费方必须拒绝不支持的请求版本、容忍未知新增字段、将输出保留在指定的新目录中,并保持源码输入不变。verifyCommand 接收原始请求/输出,并拥有独立采集的执行证据。报告缺失/篡改及输入过期会使最终复核失败。业务场景覆盖和领域报告模式由独立工具负责。
当前上报使用 v2 指标,不是领域报告格式或旧 quality_run_v3 模式。
未配置结构化报告的命令非零退出时,结果为 tool_error,附有界执行诊断。这与合法报告中的业务断言失败不同,不能授权保留失败结果关闭。
可选 Web 集成
启用 quality-web 后,插件通过自己管理的 test-tool 安装贡献 business-tests。通用质量执行器不负责 npm/更新策略。先选择适用检查,再由 prepareChecks 解析所需二进制;随后冻结提供方,命令路径将版本绑定到质量证据。
可选 when.impactPaths 区分运行相关、非运行相关和未映射路径;影响未映射或不完整时,在工具准备前阻断。字段和优先级见路由与适用性,安装行为见 Web 质量插件。
检查进度与取消
ExecutionRequest.onOutput(stream,text) 向调用方透传标准输出/标准错误;回调失败不影响执行结果。命令质量插件通过 LifecycleContext.progress(message) 提供当前检查/复核及最多 1200 字符的最新输出,wenext_check 在原工具结果中更新,不创建重复检查。
取消/超时先向主进程发送 SIGTERM,最多等待 3 秒保存中断报告;主进程退出或宽限期结束后清理整个进程组。原执行状态保留 cancelled/timed_out,绝不能因子进程写出 passed 或退出码为 0 改判成功。强制终止可能只保留工具的部分进度文件。
wenext_check 记录 task_check_interrupted.source=tool_signal|session_signal|tool_and_session_signal。这里只说明宿主传来的取消通道,不推断是用户按键或模型决定。外层超时仍以执行状态和预算区分。