项目环境准备
在 .agents/rules/workflow.json 声明启动、实施前和检查前命令。只在确有需要的阶段准备环境,准备成功不构成检查证据。
适用范围
Pi 是全局命令行工具。业务仓库声明领域工具和准备命令,不负责安装 Pi,也不导入其私有状态。全局宿主在打开交互会话前执行启动准备。实施准备在进入实施阶段或首次获准的写入/Shell 操作时触发,每个会话、任务和批准组合只执行一次。检查准备仅在实际执行质量检查前运行;进入检查阶段,或归档时复用有效证据,都不会重复准备。
工具与接口
{
"schemaVersion": 1,
"preparation": {
"schemaVersion": 1,
"startup": [{"id":"dependencies","command":["node","scripts/prepare.mjs","{{requestFile}}"],"timeoutMs":300000}],
"beforeImplement": [],
"beforeCheck": [{"id":"test-environment","whenChecks":["business-tests"],"command":["node","scripts/preflight.mjs","{{requestFile}}"]}]
}
}此可选配置位于 .agents/rules/workflow.json。prepareRepository(root, phase, context?, signal?, progress?) 是内部接口。Pi 不要求新增环境变量或领域工具包。
行为约定
命令使用参数数组,不使用经 Shell 展开的字符串。node 解析为宿主自身的可执行文件。私有临时请求文件提供 schemaVersion: 1、projectRoot、phase,以及可选的 taskId、writePaths、公开质量 scope 或 activeTask;检查选择完成后还提供 selectedChecks: string[]。
可选的 whenChecks 将准备命令绑定到选中的检查 ID,任意一项匹配即可。它只适用于 beforeImplement/beforeCheck;缺少检查选择结果会报错,而不是静默准备所有环境。实施阶段按计划写入路径与已观测改动选择检查,检查阶段使用实际完整范围。影响未知时,应先调查再准备测试环境。
请求文件在执行后删除。每阶段最多 16 条命令;超时范围为 100–300000 毫秒,默认为 120000 毫秒。输出诊断有长度限制。
启动时持有项目准备锁并记录活动会话标记。若存在另一个活动宿主,请求会带上 activeTask: true;会修改共享依赖的仓库命令应延后安装。可选的 quality-web 插件使用不可变的隔离安装,不依赖这条仓库准备流程。已退出的本地持有者会被清理,远端主机持有者按仍存活处理。
只有实现此协议的宿主参与协调;其它工具、手动包管理命令和旧 Pi 进程不受此锁约束。
启动或实施准备失败时会显示诊断,命令行仍可在既有批准范围内用于修复。检查准备失败会阻止质量执行,直到环境修复。准备成功既不是测试证据,也不是方案批准。宿主不会自行安装领域依赖或编辑业务模板。
结果与错误处理
| 条件 | 行为 |
|---|---|
| 未声明准备命令 | 保持既有工作流,不执行准备命令 |
| 模式、参数数组或超时值无效 | 返回准备错误 |
| 非零退出、超时或取消 | 提供有长度限制的可操作诊断,不生成检查成功证据 |
| 另一个参与协议的宿主仍存活 | 向仓库传入 activeTask: true |
| 启动准备失败 | 显示诊断,仍打开命令行以便修复 |
| 检查准备失败 | 不启动质量检查尝试 |