Skip to content

项目环境准备 ​

文档导航

在 .agents/rules/workflow.json 声明启动、实施前和检查前命令。只在确有需要的阶段准备环境,准备成功不构成检查证据。

适用范围 ​

Pi 是全局命令行工具。业务仓库声明领域工具和准备命令,不负责安装 Pi,也不导入其私有状态。全局宿主在打开交互会话前执行启动准备。实施准备在进入实施阶段或首次获准的写入/Shell 操作时触发,每个会话、任务和批准组合只执行一次。检查准备仅在实际执行质量检查前运行;进入检查阶段,或归档时复用有效证据,都不会重复准备。

工具与接口 ​

json
{
  "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
启动准备失败显示诊断,仍打开命令行以便修复
检查准备失败不启动质量检查尝试