scenario

场景技能

编写和管理用于行为验证的留出场景。场景以叙述形式定义系统应该做什么，并包含可衡量的验收向量和满意度评分。它们存放在 .agents/holdout/ 中，以便实现 Agent 在开发期间无法查看。

快速开始

# Initialize holdout directory
/scenario init

# Add a scenario from a description
/scenario add "user can authenticate with valid credentials"

# List all active scenarios
/scenario list

# Validate scenarios against the schema
/scenario validate

执行步骤

步骤 1：初始化留出目录

ao scenario init

创建 .agents/holdout/，并在其中添加说明留出隔离规则的 README.md。如果目录已存在，则不执行任何操作。

README 明确说明：

• 实现 Agent 绝不能读取 .agents/holdout/
• 只有评估 Agent 和人类可以编写场景
• Hook 强制执行规则，防止实现 Agent 访问留出文件

步骤 2：编写场景

提供叙述性描述，技能便会生成符合架构规范的 JSON 场景文件。

ao scenario add "user can authenticate with valid credentials"

该技能将：

1. 生成 ID（s-YYYY-MM-DD-NNN）
2. 提示用户提供叙述、预期结果和验收向量，或推断这些内容
3. 设置默认满意度阈值（0.8）
4. 写入 .agents/holdout/s-YYYY-MM-DD-NNN.json

你也可以手动编写场景，创建符合 schemas/scenario.v1.schema.json 的 JSON。请参阅场景架构参考。

步骤 3：验证场景

ao scenario validate

根据 schemas/scenario.v1.schema.json 验证 .agents/holdout/ 中的每个 .json 文件。报告：

• 架构违规（缺少字段、类型错误）
• 重复 ID
• 过期场景（状态为 "active"，但日期早于 90 天）
• 没有检查命令的验收向量

步骤 4：列出场景

ao scenario list

显示所有场景及以下信息：

• ID、目标、状态、来源、日期
• 满意度阈值
• 验收向量数量

筛选选项：

ao scenario list --status active
ao scenario list --status draft
ao scenario list --status retired

将场景关联到 GOALS.md 指令

与 GOALS.md 指令关联的场景将成为可执行规范的一部分。ao goals scenarios --create "<goal>" --directive N 会生成一个提升后的规范场景，并建立双向关联；ao goals scenarios 会列出每条指令关联的场景；ao goals scenarios --lint 会检查关联图。通过 ao scenario add 编写的临时留出场景在提升之前不会关联。请参阅 /goals 技能和 docs/adr/ADR-0003。

关联后，场景的通过/失败结果会影响指令的适配度： ao goals measure 会将关联场景的结果汇总为每条指令的 scenario_satisfaction 比率（低于阈值时为 RED），而 ao goals trace 会呈现“指令 → 场景 → bead → 判定 → 经验”的溯源链，并检查孤立项。有关这两项功能，请参阅 /goals 技能。

步骤 5：与验证集成

/validation 技能中的步骤 1.8会使用这些场景。在验证期间，评估 Agent 会：

1. 从 .agents/holdout/ 加载所有启用的场景
2. 运行每个验收向量的检查命令
3. 计算每个场景的满意度分数（0.0-1.0）
4. 汇总为总体留出分数
5. 如果任何场景低于其阈值，则验证关卡失败

关键规则

留出隔离

场景是留出数据。实现 Agent 绝不能查看它们。这样可以防止 Agent 过度适配特定测试用例，而不是构建正确的通用行为。

• 场景存放在代码库之外的 .agents/holdout/ 中
• Hook 强制执行规则，确保实现 Agent 无法读取留出文件
• 只有评估 Agent、人类或 /validation 技能可以访问场景

满意度评分

场景采用连续满意度评分（0.0-1.0），而非布尔型通过/失败。这使得以下操作成为可能：

• 对未完成的实现给予部分分数
• 跟踪不同迭代间的趋势
• 根据场景的重要性调整各场景的阈值

每个验收向量都会产生一个分数，场景的总体分数是所有向量分数的加权平均值。

编写者规则

• 场景应由人类或评估器 Agent编写
• 实现 Agent 绝不能编写自己的场景
• source 字段用于记录来源：human、agent 或 prod-telemetry
• 评估器 Agent 编写场景时，应在独立会话中进行，且无法访问实现细节

场景生命周期

状态	含义
active	在验证期间评估此场景
retired	此场景已稳定通过；保留以供参考
blocked	无法评估此场景（缺少依赖项）
draft	此场景尚未完成；尚未评估

参考文档

• 场景架构参考 -- 场景架构的完整字段文档和 JSON 示例
• references/scenario.feature — 可执行规范：编写保留测试场景、验证架构、列出并链接到 GOALS 指令，以及馈送至 /validation（soc-qk4b）

故障排除

问题	原因	修复方法
validate 报告缺少字段	架构版本不匹配	检查 version 字段是否与架构要求一致
验证未选取场景	状态不是 active	在 JSON 中设置 "status": "active"
实现 Agent 读取了保留测试	未安装 Hook	运行 ao scenario init 以验证 Hook 设置
ID 重复错误	两个场景使用了相同的 ID	使用 s-YYYY-MM-DD-NNN 格式重命名其中一个
场景过时警告	活跃场景超过 90 天	检查并停用或刷新此场景
得分始终为 0.0	检查命令返回非零值	单独调试检查命令

另请参阅

• /validation -- 在 STEP 1.8 使用场景进行保留测试评估
• /council -- 多模型评审可以生成场景建议
• /vibe -- 代码质量验证（与行为场景互为补充）