Taiyi Requirement

taiyi-requirement — 需求分析

进入本阶段前请优先读 .taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

Superpowers / GStack / Spec-Kit / OMO 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游检查

• change 阶段已过关（engineTruth.completedPhases 含 change 或 currentPhase 已推进）
• 无跨 change 的 AC 冲突（taiyi list 检查其他活跃 change 的 scope）

0.2 Profile 判定

0.3 触发者检查

每个 FR 必须声明触发点：

• 每个 FR 必须填写 trigger（谁调用、什么时机）
• trigger 指向的 caller_module 不在本 change scope 中 → 填 blocked_by 标注依赖
• blocked_by 非空 → 本阶段不能过关，等依赖 change 完成后再继续

"functional_requirements": [{
  "module": "orchestrator",
  "items": [{
    "id": "FR-T01",
    "description": "track(slug,role,amount) 更新 pipeline.json tokenBudget.used",
    "trigger": "executor.dispatch() 每次调用后",
    "caller_module": "packages/orchestrator/src/executor.ts",
    "blocked_by": "M4-executor"
  }]
}]

blocked_by 非空时引擎会在 status 中报 blocker，阻止进入 design 阶段。

0.4 前置检查清单

• change 阶段已过关
• 理解 CHANGE Scope 和 Out of Scope 边界
• 每个 FR 有 trigger（谁调用、什么时机）；caller 不在 scope 时填 blocked_by

步骤

工件契约

工作流：编辑 json → scripts/taiyi-forge.sh render <slug> requirement → status → continue。

详见 docs/taiyi/artifact-contract.md。

json 字段（Zod 摘要）

写作指引（填入 json，render 生成 REQUIREMENT.md）

1. 拆 User Stories

从 CHANGE.md Motivation + Scope 拆出用户故事。每条用标准格式：

## US-{N}: {标题}

As a **{角色}**
I want **{功能}**
So that **{价值}**

### Acceptance Criteria

**AC-{N}.{M}**: {描述}
Given {前置条件}
  When {操作}
  Then {预期结果}

要求：

• 每条 US 必须能追踪到 CHANGE.md 的 Motivation 或 Scope
• US 不写技术方案（不在需求层说"用 Redis"）

2. 写 AC（Acceptance Criteria）

每条 AC 使用 Given/When/Then 格式：

**AC-1.1**: 用户输入有效邮箱能通过验证
Given 用户输入了 "user@example.com"
  When 系统校验邮箱格式
  Then 返回验证通过

好 AC：

• 可量化（"返回 200"、"耗时 < 200ms"、"响应体包含字段 X"）
• 包含边界值（空输入、超长字符串、特殊字符、分页极限）
• 描述外部可见行为，不涉及内部实现
• 包含中间状态（Loading → Success / Error）
• 错误路径有明确可观测结果（HTTP 4xx / toast 提示 / 按钮置灰）

好 AC 例子：

• ✅ "用户点击重置后，表单所有字段恢复到初始空值状态"
• ✅ "搜索耗时 > 5s 时，页面展示 '搜索超时' 提示，搜索框不清空可重试"
• ✅ "删除确认弹窗点击取消，关闭弹窗且列表不刷新"
• ✅ "页面数据加载中，表格区域显示骨架屏，不显示空表头"
• ✅ "连续两次提交相同表单，第二次收到 409 Conflict，页面不跳转"
• ✅ "翻到最后一页时，加载更多按钮变为灰色文字'已加载全部'"

坏 AC：

• ❌ "校验通过"（不可验证——什么校验？校验什么？）
• ❌ "使用正则表达式验证"（在描述实现，不是行为）
• ❌ "应该正常工作"（不可测量——什么叫正常）
• ❌ "系统处理请求"（太泛，没有可观测结果）
• ❌ "调用翻译 API"（在描述内部调用链，不是用户可见行为）
• ❌ "不做过多处理"（模糊，无法写断言）
• ❌ "程序运行稳定"（无法在一次测试中验证）
• ❌ "修复以前的问题"（引用非本次 scope）
• ❌ "加好注释"（代码规范，不是 AC）

3. 提取域语言

从 US + AC 中提取关键术语，写入 REQUIREMENT.md preamble：

## 域语言

| 术语 | 定义 | 使用场景 |
|------|------|---------|
| TranslationRequest | 用户提交的翻译请求 | US-1, US-2 |
| TranslationDirection | 翻译方向枚举（dev→product 等） | US-3 |

要求：

• 域语言是代码中一致的命名来源
• 跨 change 的术语应保持一致（检查已有 CONTEXT.md）

4. Traceability

建立 AC ↔ CHANGE Success Criteria ↔ 验证方式的追踪表：

## Traceability

| AC | CHANGE SC | 验证方式 |
|----|-----------|---------|
| AC-1.1 | SC-1（API 返回 200） | curl -s -w '%{http_code}' POST /api/translate |
| AC-2.1 | SC-2（SSE 流式响应） | curl -N -s POST /api/translate/stream |

要求：

• 每条 CHANGE Success Criteria 至少对应 1 条 AC
• 验证方式必须是可执行命令（不是"写测试"）

过关（Harness）

1. 逐项检查 ## 质量自检；有未通过项则不要过关。
2. 预检：scripts/taiyi-forge.sh status <slug> --json --compact — 解析 engineTruth（qualityReady / blockers）。
3. 用户确认后过关：scripts/taiyi-forge.sh continue <slug>。
4. 过关后再 status --json --compact，读 engineTruth；若 currentPhase 已变为 design，切换到 taiyi-design Skill 并通知用户。

Legacy：npx taiyi complete <slug> requirement 仍可用；聊天优先 /taiyi:continue。

产出

• .taiyi/changes/<slug>/REQUIREMENT.md
• .taiyi/changes/<slug>/requirement.json

与下游衔接

异常处理

质量自检

• 前置门禁已通过（0.1–0.3）
• 每条 User Story 有 As a / I want / So that
• 每条 AC 用 Given/When/Then 格式
• Traceability 完整（AC ↔ CHANGE Success Criteria ↔ 验证方式）
• 域语言已提取并与已有术语一致
• 每条 FR 已声明 trigger（谁调用、什么时机）；caller 不在 scope 的已填 blocked_by
• 没有写入技术实现方案
• 每条 AC 可量化（不是"应该正常"）

引擎门控（自动，无需手动确认）

• blocked_by 验证: requirement.json 中 FR 的 blocked_by 指向不存在的 change → 阻止过关。指向未完成的 change → 日志 warn