weichen
e6ddfab9e8
Resolve conflicts: both CURRENT claim tables (slot preserved), local multi-host coordination plan + origin phased companion, origin module-boundaries, combined PG isolation with remote product tests. FEATURE-MATRIX takes origin record_id layout; A-G done bump deferred pending evidence row apply.
72 lines
7.4 KiB
Markdown
72 lines
7.4 KiB
Markdown
# 按变更范围选择验证与证据
|
||
|
||
规则状态、owner 与生效条件见 [规范登记](./2026-09-21-policy-registry.md)。本文件是项目验证范围和报告要求的唯一来源；客户端仅引用。执行共享环境测试前，先满足 [操作规范](./2026-09-21-agent-worktree-workflow.md) 的授权、环境身份和持锁条件。
|
||
|
||
## 验证矩阵
|
||
|
||
| 变更范围 | 必需验证 | 不足以验收的证据 |
|
||
|---|---|---|
|
||
| 纯规范/普通文档 | diff、相对链接、状态、所有入口指令一致性 | 未核对来源的文案结论 |
|
||
| 治理脚本 | 临时 Git 仓库中的真实分支/锁/并发/异常退出与拒绝路径 | 仅语法检查或 stub |
|
||
| Go/接口 | 对应单测；`./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`；受影响 PG 和鉴权负例 | short 测试替代被跳过的 PG/真实链路 |
|
||
| 前端 | `web/` 中 `npm test`、`npm run build`；受影响交互的真实浏览器验证 | API 直调替代 UI 操作 |
|
||
| 迁移/运行配置 | 独立环境升级、兼容性、回退/前滚条件及就绪验证 | 重启/health 替代版本与持久性证据 |
|
||
| 产品 Agent/工作流（含运行模板/提示词） | 受影响真实产品 PI Agent Runner 链路；对应用户流程、持久状态和 UI | stub、SKIP、测试名未匹配、仅健康检查 |
|
||
|
||
多类变更取并集。按 [模块开发标准](../system-design/2026-09-20-module-development-standards.md) 追加边界与 registry parity 等范围门禁。开发阶段可用 stub；交付验收不能冒充真实执行。纯文档无需产品 PI 或全量 Go，也不为形式重建服务。
|
||
|
||
## 问题修复的回归范围
|
||
|
||
Bug/系统问题修复先按 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 确定问题类别和影响范围，再从上表选择验证层级。验收须包含：原始复现案例；通过同一机制的其他输入、措辞或入口；相关边界/异常路径；应保持不变的正常行为。场景按实际因果链选择，不机械穷举；不适用或未覆盖的项记录理由与风险。
|
||
|
||
验证机制和预期行为，不以硬编码原句、固定回复文本或单个样例通过代替回归。能在修复前复现失败的场景记录修复前后对照；不能复现时说明证据限制。报告逐项区分通过、失败、未运行与待验证；只提供分析/方案时列出验收设计，不声称已经运行或修复。
|
||
|
||
## 产品 PI 基线与精确追加
|
||
|
||
优先入口：`./scripts/run-nightly-real-pi.sh`。调用前核验并从获授权配置提供（不在命令/报告贴凭证值）：
|
||
|
||
- 独立可写 `TEST_DATABASE_URL`，不得指向真实生产业务库；确认 Runner 与测试所需工作区/`DATA_DIR` 挂载相容。
|
||
- `PI_AGENT_RUNNER_URL` 和 `PI_AGENT_RUNNER_AUTH_TOKEN` / `RUNNER_AUTH_TOKEN`；真实 Runner 可访问。
|
||
- 共享 KB 的授权连接与必要凭证；正常验收要求在线。`KB_ALLOW_OFFLINE=1` 只证明显式降级场景。
|
||
- 目标环境批准的实际模型、协议及制品；通过 `PI_AGENT_MODEL` 传入批准值并比对 Runner 实际配置。脚本默认值不构成批准，也不证明实际模型。
|
||
- 脚本可能构建候选镜像、写 promotion receipt；须满足构建身份/授权条件。`NIGHTLY_SKIP_IMAGE_BUILD=1` 不能补足缺失的制品摘要证据。
|
||
|
||
脚本当前筛选 **五项**（U8 + 四条工作流治理链）：
|
||
|
||
```text
|
||
TestMultiIntentU8_RealPI_ConfirmGenerate_PG
|
||
TestWorkflowGovernance_PiAgent_PG_FullChain
|
||
TestWorkflowGovernance_PiAgent_PG_ProductManager_FullChain
|
||
TestWorkflowGovernance_PiAgent_PG_TestManager_FullChain
|
||
TestWorkflowGovernance_PiAgent_PG_FullNoneMixedChain
|
||
```
|
||
|
||
它覆盖 main / product_manager / test_manager / FullNone 四条工作流治理链，但**不是**「全部工作流通过」，也不含 rdev P3 Go 顶层（rdev 仍用 Python 三样本 harness）。按变更范围追加精确名称，例如（前提条件已核验，且已处于相应环境执行租约/独立环境）：
|
||
|
||
```bash
|
||
go test -count=1 -timeout 2h -v ./internal/server/ -run '^TestPiAgent_FullLifecycle_MultiRole_RealWorld_E2E$'
|
||
go test -count=1 -timeout 90m -v ./internal/server/ -run '^TestWorkflowGovernance_PiAgent_PG_(FullChain|ProductManager_FullChain|TestManager_FullChain)$'
|
||
```
|
||
|
||
当前源码前提：上述 PG/U8 用例的 `piAgentRunnerHealthy` 预检固定访问 `127.0.0.1:18865`，不能仅设置其他 Runner URL 就假定能执行；FullLifecycle 配置写死 `MiniMax-M3` 且使用临时 DataDir/内存模式，不能用它单独证明 PG 持久性，也不能声称 `PI_AGENT_MODEL` 已改变该用例模型。执行前确认这些条件符合目标环境批准范围；不符时记录缺项并安排相应测试适配，不静默换模型或把 SKIP 当验收。
|
||
|
||
测试筛选区分大小写；`-run 'PI'` 不能选择名称中的 `PiAgent`。追加用例先读其环境前提；FullLifecycle 中 `RUN_FULL_ADHOC_WBS` 与 `RUN_HEAVY_STAGES` 控制额外段，不能把默认未跑段报为已覆盖。普通 PG 用例同样以源码中的精确名称/前提为准。
|
||
|
||
运行前列 `expected_tests`（含必须子场景），运行后逐项对照执行、PASS、FAIL、SKIP、未匹配及重试。退出码 0 或 nightly receipt `pass` 不能替代该对照：基线脚本逐项核对五个预期顶层测试；额外子场景/用例仍须逐项核验。缺项不记 PASS，基础设施问题记录 blocker/infra_fail。保留首轮与重试关系，不隐藏失败。
|
||
|
||
## 模型与环境证据
|
||
|
||
模型以目标环境批准配置为准；dev/test/main 的 Compose 默认值可能不同，不能将某个模型全局写成验收条件。每次记录目标环境、源码 SHA、镜像/制品摘要、schema、Runner 实际模型/协议、配置来源与核验时间；仅有环境变量不能证明实际值。发现不符先查明并记录，不为满足文档自行换模型。不得用 Herdr `context_pi` 的模型信息替代产品 Runner。
|
||
|
||
共享环境的长 E2E 持锁至结束；无权使用该环境则在独立固定环境执行。制品/候选变更后重新确认适用证据，不把旧提交 PASS 搬到新提交。
|
||
|
||
## 报告与真实性
|
||
|
||
小型文档/脚本任务可以在主文档设验证节；独立报告放 `.doc/test-reports/YYYY-MM-DD-<slug>-test-report.md`，附件放 `.doc/test-reports/assets/<report-slug>/`。任何层级至少记录：范围、被测 SHA、实际命令、环境、预期与实际、判定、证据链接、缺项/风险。命令包含秘密时记录参数名与脱敏方式，不记录值。
|
||
|
||
跨模块/业务交付使用完整报告：背景、目标、方案/环境、预期、逐例实际结果与耗时、实际执行套件汇总、结论与剩余条件。套件汇总只列本次适用并实际运行的检查，不无条件要求全量 Go。声明 PASS 必须有对应真实输入/输出或足够判定的真实片段；来源与结论可核实，脱敏不得改写结果。无需提交原始完整日志、个人信息、业务正文或秘密截图。记下删减/脱敏范围，唯一证据清理前先安全归档。
|
||
|
||
## 工程工具验收补充
|
||
|
||
本地协调与运维守卫使用 `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`，在临时真实 Git/SQLite/进程环境执行；Docker 守卫测试使用受控目标记录调用，不重建共享服务。nightly 入口现在核对最终尝试日志中五个预期顶层测试均恰好执行且 PASS；零用例、部分 SKIP 或重复拼接证据均不能生成 PASS 收据。该日志核验不是本轮执行了产品 PI 的声明。
|