dong90 taiyi-change — 变更提案
进入本阶段前请优先读
.taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。
框架集成
本阶段使用以下框架：
| 框架 | 用途 | 何时加载 |
|---|---|---|
| Harness | 阶段门禁与推进（status → continue；legacy：npx taiyi complete） |
全程 |
| OMO | 作为 workflow 入口，承接 /taiyi:new 命令 |
进入时 |
| Superpowers | brainstorming — 可选，当需求不清晰时加载协助梳理 |
可选 |
| OpenSpec | 将 CHANGE.md 同步到 openspec/changes/<slug>/ |
可选（taiyi sync-openspec） |
Spec-Kit 和 GStack 在本阶段不涉及。
前置门禁（Pre-flight）
0.1 架构级变更检测
命中任一 → 反问用户确认：
- 改模块结构（新增/拆分/合并目录）
- 动 ADR（架构决策记录）
- 改公共契约（API 签名、CLI 参数、DB Schema）
- 跨服务编排（涉及 2+ 独立服务）
0.2 Profile 判定
| Profile | CHANGE.md 要求 |
|---|---|
full |
完整：Motivation + In/Out Scope + Risks + Success Criteria |
api/ui |
同上，Out of scope ≥ 1 条 |
lite |
可省略 Risks 段，其余照常 |
micro/spike |
仅 Motivation + Success Criteria，Out of scope 可选 |
nano |
可跳过本阶段（引擎自动通过） |
0.3 前置检查清单
- slug 命名合理（小写+连字符，如
fix-login-timeout） - 用户已确认变更目标（不是 AI 自己推断的需求）
- 不与其他活跃 change 的 Scope 重叠（
taiyi list确认）
步骤
工件契约
| 层 | 路径 | 职责 |
|---|---|---|
| 语义真源 | change.json |
Zod（src/schemas/change.ts）— Agent 优先编辑 |
| 生成视图 | CHANGE.md |
hbs（src/templates/change.hbs）— 人读 / PR |
| 流程 | 本 Skill | 门禁、写作纪律、下游衔接 |
工作流：编辑 json → scripts/taiyi-forge.sh render <slug> change → status --json --compact → 用户确认 → continue --approver "名"。
详见 docs/taiyi/artifact-contract.md。
json 字段（Zod 摘要）
| 字段 | 要求 |
|---|---|
title |
描述性标题 |
motivation |
谁痛、现状代价、改善指标（具体，不笼统） |
scope.includes |
In scope 条目 |
scope.excludes |
≥1 条 Out of scope；关联 change 写 slug |
success_criteria |
≥1 条；id + description；每条可映射到测试 |
risks |
full/api 推荐：risk / probability / impact / mitigation |
impact_map |
可选；模块影响面声明 |
evidence |
success_criteria[].is_checked=true 时必填真跑命令 |
1. 编辑 change.json
/taiyi:new 已 seed change.json + CHANGE.md。
Motivation 好/坏例子（写入 motivation）：
好：当前翻译需人工复制粘贴到 DeepL，每次约 10 分钟。集成 API 后翻译可在 5 秒内完成，消除手动步骤。
坏：需要改进翻译功能。
Success Criteria（写入 success_criteria[]）：
- 每条可验证：curl / npm test / UI 操作步骤
- 不是「代码写好了」这类不可测试描述
要求：
- Motivation 说清「谁痛、现状代价、改善指标」，不笼统
- Out of Scope ≥ 1 条，标注关联 change slug（如有）
- Success Criteria 每条可直接映射到测试
- 影响面声明：是否需改 REQUIREMENT / 触及架构（
impact_map或 motivation 中说明） - 不要写实现细节；不要推断用户未确认的范围
2. 渲染 CHANGE.md
scripts/taiyi-forge.sh render <slug> change
Zod 校验通过后从 json 重生成 md（去掉 seed 标记）。continue 前若 json 已改且 md 仍是 seed/快照态，引擎也会自动 sync。人只改 md 时引擎可 reverse-sync 拉回 json；显式 render 会覆盖 md。
3. 过关（Harness）
- 逐项检查
## 质量自检；有未通过项则不要过关。 - 预检：
scripts/taiyi-forge.sh status <slug> --json --compact— 解析engineTruth（qualityReady/blockers）。 - 用户确认后过关：
scripts/taiyi-forge.sh continue <slug> --approver "名"（change 人工门）。 - 过关后再
status --json --compact，读engineTruth；若currentPhase已变为requirement，切换到 taiyi-requirement Skill 并通知用户。
Legacy：npx taiyi complete <slug> change --approver "名" 仍可用；聊天优先 /taiyi:continue。
产出
.taiyi/changes/<slug>/CHANGE.md.taiyi/changes/<slug>/change.json
与下游衔接
| 下游 | 需要 |
|---|---|
taiyi-requirement |
Motivation + Scope → User Stories 边界；Success Criteria → AC Traceability；Out of scope → 不写 US 的范围 |
taiyi-design |
影响面声明 → 架构决策范围；Success Criteria → 验证标准 |
异常处理
| 场景 | 处理 |
|---|---|
continue 被拒（非零退出） |
读错误输出 → 缺少人工审批还是工件不完整。缺少审批 → 提示提供 --approver。工件不完整 → 补全后重试 status 再 continue。最多 1 次自动重试 |
| CHANGE 与已有 change 范围重叠 | 在 Scope 中标注关联 slug，与用户确认是否需要合并或拆分 |
| 用户对 CHANGE 内容有争议 | 停止写入，等用户修改指示。不要自行协商修改范围 |
| Profile 判定 skip 但门禁拦截 | 确认 profile → 如是 nano 说明可跳过的理由，人工放行 |
| 误过关后续阶段 | change 为基石不可 undo；用 scripts/taiyi-forge.sh undo <slug> requirement（或更后阶段 id）回滚；仅需改 CHANGE 时直接编辑工件后 status |
质量自检
- 前置门禁三项全部通过（0.1–0.3）
- Motivation 说清了"谁痛、现状代价、改善指标"
- Out of scope ≥ 1 条
- In/Out 格式清晰（### 子节或 - In: 风格）
- Success Criteria 每条可映射到测试
- Risks 已记录（full/api profile）或说明"无显著风险"
- 架构级变更已检测（0.1）且结果已记录
- 影响面声明已写入
引擎门控（自动，无需手动确认）
- WIP 限制: 活跃种子 ≥
TAIYI_MAX_SEEDS(默认10) → 阻止创建。--force或TAIYI_SEED_LIMIT=0跳过 - 复杂度重评估: change 过关时按已填 CHANGE.md 重算复杂度（不再总是 "low"）
- SC 可量化: 所有 SC 均无数字/%/状态码 → agent 日志 warn（不阻止，人审兜底）