---
description: KB 流中的执行验收：尝试执行验收命令并写入 06-automation-test.md（含策略、执行记录与输出约束）
argument-hint: "[变更目录或 scan-id] [补充说明]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
在 **`knowledge/变更/进行中/`** 变更目录下收口执行验收；必要时兼容 `knowledge/变更/归档/` 下同名目录。输出要求：**可读追溯、范围清晰、会话与文档输出受控**。不替代 `/kb-review` 的静态代码评审。

本命令名称中的“test”保留为兼容命令名，实际语义是**尝试执行验收命令并留下证据**，不是默认做全量测试工程化，也不是默认执行全量 analyze、编译或部署。

**验收分层（KB 口径，非通用测试金字塔）**：当需要/能够补充自动化时，按 **UI E2E（Playwright 等）> 集成/契约（gRPC/HTTP）> 单元（仅执行已有）** 优先；同场景有上层覆盖时，下层可记 `skipped-duplicate`（见 §2、§3）。

**输入**: 变更名称（**必须为中文**，对应目录 `knowledge/变更/进行中/<时间戳>-<中文名称>/`）。

## 子 Agent 编排（必遵）

- **策略与追溯表草案**、**脚本/目录扫描**、**与 03 对齐的缺口列表**等可拆为独立原子项时，**并行**派发 `Task`（`generalPurpose` 只读模式）；**有可执行命令时由主 Agent 使用受控 shell 实际运行**。主 Agent 合并意图与结构、控制会话输出长度，实际脚本和 `06-automation-test.md` 写入由子 Agent 执行。

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## 约束

- **变更名称必须为中文**；目录格式 `<YYYYMMDDHHMMSS>-<中文名称>`
- **验收导向、有限补自动化**：`/kb-apply` 不写测试脚手架；本命令**允许**在变更相关 `auto_test/` 补 **UI E2E（Playwright 等）** 或 **契约/集成** 脚本（须追溯 `03`）；**禁止**新建**单元测试**脚手架；**允许执行** `03` 已指定的既有 unit 命令作最后兜底
- **不新增** `kb.project.json` 的 `verify.commands`（或同类配置）作为命令来源
- **默认尝试执行**：按下方优先级收集命令并尝试运行（受控 shell）；不得以「只写策略」代替有命令时的执行
- **不写密钥与令牌**：`06-automation-test.md`、会话回复、`README` 中均不得写入真实凭据或完整 token；用环境变量名或「已配置」描述
- **输出受控**（见下文「输出规范」），避免把整段终端日志粘贴进聊天或知识库
- **stage 枚举不得发明新值**：仅使用 schema 现有值 `proposed|designed|planned|applying|applied|reviewed|review_failed|tested|archived|archived_with_debt|acceptance_reopened`。执行失败时**不得**写 `stage=tested`，保持 `reviewed`，并在 `06` 结论写失败（无 `test_failed` stage）

## 执行步骤

### 1. 加载验收与设计上下文

```bash
# 任务与验收（追溯主来源）
cat "knowledge/变更/进行中/*-<中文名称>/03-tasks.md"
# 必要时兼容读取 knowledge/变更/归档/*-<中文名称>/03-tasks.md

# 设计与接口边界（确定可自动化范围）
cat "knowledge/变更/进行中/*-<中文名称>/02-design.md"
# 必要时兼容读取 knowledge/变更/归档/*-<中文名称>/02-design.md
```

读取 `00-manifest.json` 获取任务状态；若变更目录缺失该文件，先由子 Agent 补建最小 manifest。若无 `03-tasks.md`，提示先 `/kb-plan`；自动化范围无法定义时仅写「策略与局限」，不强行编脚本。

### 2. 收集可执行命令（来源优先 + 同批层级排序）

**2.1 按来源收集**（去重后保留来源顺序）：

1. **用户本轮明示的命令**
2. **`03-tasks.md` 验收标准中的定向 shell/命令**
3. **变更相关 `auto_test/` 下 README 或约定入口**（Playwright / 契约 / 冒烟脚本）

**2.2 命令分层**（写入 `06` 执行记录时须标层级）：

| 层级 | 典型形态 | 识别线索（示例） |
|------|----------|------------------|
| **ui** | 浏览器 E2E、Playwright | `playwright`、`npx playwright`、`e2e/`、`auto_test/**/ui/` |
| **contract** | gRPC/HTTP 契约、API 集成冒烟 | `grpcurl`、`curl`+契约脚本、`auto_test/**/contract/` |
| **unit** | 既有单测入口 | `npm test`、`pytest` 某文件、`go test` 等（**仅执行已有**，不新建脚手架） |
| **other** | 无法归类但仍可执行的定向命令 | 手工标注 |

**2.3 同批内执行顺序**：三源汇集后，**不改变来源优先序**；在**同一来源批次内**按 **ui → contract → unit → other** 排序后执行。

**2.4 覆盖降级（skipped-duplicate）**：若某 `03` 验收条已有 **ui** 层执行且通过，同条目的 **contract/unit** 命令默认**不重复跑**，执行记录备注 `skipped-duplicate`；`03` **明示**须跑下层时除外。

**三者皆无**时：

- 仍须写入/更新 `06-automation-test.md`，写清「无可执行命令」策略与局限
- **不得**标假通过或伪造成功执行
- 推荐：`stage` 仍可写 `tested`，但执行记录写 `skipped: no runnable commands`，结论标明「无执行证据，非执行通过」
- 备选：保持 `reviewed`（若团队希望 stage 严格表示「有执行证据」）

**有可执行命令时**：

- **必须**用受控 shell **实际运行**
- **任一失败** → 不得 `stage=tested`，保持 `reviewed`；在 `06` 结论写失败；会话报告**阻断**，不得当验收通过
- 全部成功（或明确跳过且理由成立）→ 可写 `stage=tested`，并在执行记录表留下证据行

### 3. 从验收记录角度整理策略（写入 06 的核心）

在产出或更新 `06-automation-test.md` 时**必须**体现以下维度（允许表格化，避免长文）：

| 维度 | 要求 |
|------|------|
| **范围与层级** | 标明 **ui（Playwright 等）/ contract（gRPC/HTTP）/ unit（仅已有）/ other**；补写自动化时优先 ui>contract>unit；场景聚焦、可重复、低副作用；注明 `skipped-duplicate` 与未覆盖原因 |
| **可追溯性** | 每一组自动化或「必须手工」的项，**对应 `03-tasks.md` 中的任务或验收条**（ID 或原文摘要） |
| **前置与数据** | 环境、账号、服务地址、依赖迁移是否已执行；**测试数据**如何准备与是否可重复 |
| **期望与通过准则** | 每条场景：触发条件 → 期望现象（状态码/错误码/DB 侧可观察点）→ **失败时如何判责**（脚本问题 vs 服务问题） |
| **风险与未覆盖** | 明确写出**未自动化**的原因（如 DDL、仅日志可证、需 DBA）与残留风险 |
| **清理与副作用** | 是否写库、是否需手工回滚；破坏性步骤须标 **⚠** 并与 README 一致 |

### 4. 脚本与 `auto_test/`（按需）

- **允许补写**：`auto_test/` 下 **Playwright UI E2E** 或 **契约/集成** 脚本（建议 `auto_test/e2e/`、`auto_test/contract/`）；每条须对应 `03` 验收条
- **禁止补写**：**单元测试**脚手架（`tests/`、`__tests__/` 等标准单测布局不在本命令范围）
- 新增或调整脚本时：目录、入口命令、**环境变量开关**、默认行为（建议默认**非破坏**）
- 脚本内日志：**关键步骤**打印即可；避免无意义刷屏（与「输出规范」一致）
- 不强制新建任一层脚本、不执行部署或迁移 SQL；无 ui/契约可跑时仍可按 `03` 执行既有 unit 命令

### 5. 执行命令并写入 `06-automation-test.md`（子 Agent 写入）

路径：`knowledge/变更/进行中/*-<中文名称>/06-automation-test.md`；若用户明确选择归档目录中的变更继续补验收记录，则写入对应 `knowledge/变更/归档/*-<中文名称>/06-automation-test.md`

06 文件在 manifest 标注 `source: "test"`、`kind: "change_doc"`。

按第 2 步结果更新 `00-manifest.json.stage`：

| 情况 | stage |
|------|-------|
| 有命令且全部通过 | `"tested"` |
| 有命令且任一失败 | 保持 `"reviewed"`（会话阻断） |
| 无可执行命令（写清策略） | 推荐 `"tested"` + 执行记录 `skipped: no runnable commands` |

需要时为 `tasks[]` 追加验证证据摘要。

结构以 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md)「10」为准；大段须 `## 1、` … `## 7、` 阿拉伯数字编号，**禁止**中文序号大段（如 `## 一、`）。全文以表格与短列表为主，总篇幅建议明显短于 `03-tasks.md`：

| 段 | 标题 | 要点 |
|---|---|---|
| 1 | 测试策略与范围 | 层级、目标、与验收关系一句话 |
| 2 | 局限与未自动化原因 | 不测什么、为何；无可执行命令时写清策略局限 |
| 3 | 验收追溯表 | 任务/验收 ↔ 自动化或手工 ↔ 证据类型 |
| 4 | 场景摘要 | 场景名/前置/期望/步骤指针；采集命令、冒烟清单等用 `### 4.1` `4.2` |
| 5 | 脚本位置与环境 | 链到 `auto_test/.../README.md`，只写变量**名** |
| 6 | 输出与记录规范 | 指向下文「输出规范」，保持 06 内仅一行原则说明 |
| 7 | 执行记录 | 仅表格，**一行一次执行**；列含**层级**（ui/contract/unit/other）；含 `skipped-duplicate`、`skipped: no runnable commands` 或失败摘要 |

### 6. 输出规范（会话 + 文档）

**在对话中回复用户时**：

- **只给摘要**：例如「冒烟：通过/失败/跳过」「阻断项 ≤ 3 条（条列）」「环境：测试 / GRPC_SERVER=…（勿贴秘密）」
- **禁止**：整屏 `npm test` 原文、大量 JSON、含 token 的日志
- 若用户需要详情：引导其本地查看终端或 `auto_test/...` 内说明，**不在聊天复述长日志**
- 执行失败时：明确**阻断**，不得宣称验收通过

**在 `06-automation-test.md` 中**：

- **禁止**粘贴完整终端输出；执行记录用表格字段概括（日期、环境、命令、结果、备注）
- 备注列只写**结论性**一词或短语（如「ui 通过」「skipped-duplicate」「skipped: no runnable commands」「命令 exit 1」）

## 在工作流中的位置

```
propose → design → plan → apply → review → test → archive（含 commit+push + 可选 external sync）
  提案      设计    分解    实现    评审   执行验收    归档     提交
```

- **位置**：`/kb-review` 之后、`/kb-archive` 之前
- **输入**: `02-design.md`、`03-tasks.md`；可选 `04-review.md` 中未关闭项
- **输出**: `auto_test/`（按需）+ `06-automation-test.md`（含执行记录）
- **后续**: 通过后可 `/kb-archive`；**archive 不因缺少 `06` 阻断**（见 `/kb-archive` 2B 口径）

## 注意事项

- 全部使用**简体中文**
- 与 `/kb-review` 分工：**review** 偏实现与规范；**test** 偏**执行验收证据**与追溯，二者不合并为一篇冗长文档
- `flow = lite`：**豁免**强制执行测试（见 orchestrator / archive 轻量短路径）；本命令被显式调用时仍按上文尽力收集并尝试执行