# 场景生成与能力补全工作流

## 目录

- 输入归一化
- PC 系统交互基线
- 场景匹配
- Sisyphus 校准
- 能力缺口检查
- Ant Design 与项目组件补全
- 确定性校验与规范门卫
- 停止条件

## 输入归一化

将截图和自然语言统一转换为 `SceneSpec`。截图只提供视觉证据，不把不可见的接口、权限、路由和业务状态当作已知事实。

必须区分：

- 视觉确认：标题、字段标签、表格列、Tab、按钮、分区、布局
- 需求确认：按钮行为、校验、跳转、保存方式、权限
- 项目推断：路由、请求、状态、目录约定
- 未决事项：缺少且会影响生成结果的信息

## PC 系统交互基线

用户明确的业务需求始终是必须满足的上层约束。对 PC 系统建模和生成时，其余证据按以下顺序决策：

1. 注册场景结构：确定页面结构、导航关系、表单所有权和校验边界。
2. Sisyphus MCP API/demo：确定组件、公开属性、类型和组合方式。
3. 项目既有约定：只适配路由、请求、权限、状态、目录和命名。
4. 截图差异方案：最后处理间距、尺寸、颜色等视觉差异。

低优先级证据不得覆盖高优先级基线。发生冲突时保留高优先级实现，并把未采纳的差异写入交付说明；截图不得驱动已确认交互结构的重构。强制安全规则或无法绕过的项目规则与基线冲突时停止生成并报告。

## 场景匹配

使用 `assets/templates/scene-registry.json` 计算需求能力与注册场景能力的覆盖关系：

- `exact`：注册场景完整覆盖需求，且没有额外布局能力
- `partial`：某个注册场景覆盖主要结构，但存在新增或组合能力
- `none`：没有场景覆盖主要结构，或强行归类会改变页面交互

复合场景允许组合多个注册场景。例如“Tab 列表跳转多 Tab 详情”由 `tab-list + detail-navigation + tab-detail` 组成，不创建重复大模板。

## Sisyphus 校准

任何匹配级别都执行相同门禁：

1. MCP 列出当前版本组件。
2. 为候选组件读取完整 API。
3. 为具体交互读取 demo。
4. 记录版本、组件、API 和 demo 证据。
5. 用证据填充结构模板，不复制 demo 中与目标项目无关的代码。

### exact

加载结构模板，再用 MCP 校准 import、props、类型、组件组合和内置能力。

### partial

先组合已有页面原语，再针对差异查询 demo。不得因为“最接近某模板”而丢失用户明确提出的能力。

### none

从需求能力反向搜索 Sisyphus 组件与 demo，生成仅服务本次任务的临时场景结构。除非用户明确要求维护技能，否则不修改场景注册表。

## 能力缺口检查

每条 `CapabilityRequirement` 必须对应一条 `ComponentDecision`。

| 状态       | 判定                             | 下一步              |
| ---------- | -------------------------------- | ------------------- |
| covered    | API 与 demo 足以实现             | 进入生成            |
| partial    | 需要多个 Sisyphus 原语或项目适配 | 继续组合并复查      |
| missing    | MCP 明确无对应能力               | 允许查询 Ant Design |
| unverified | MCP 不可用、版本不符或证据不足   | 立即阻断            |

不得把“搜索没找到”“白名单没写”“记忆中不存在”判为 `missing`。

## Ant Design 与项目组件补全

进入 Ant Design 前输出一条具体说明：

```text
缺口：<需求能力>
Sisyphus 证据：<查询过的组件/API/demo>
无法满足原因：<明确原因>
```

随后查询 antd 6 的 MCP API 和 demo；平台没有 Ant Design MCP 时使用 Context7 官方文档。只实现缺口，不替换 Sisyphus 已覆盖部分。

Ant Design 仍无法覆盖时检索项目公共组件。只使用有源码、调用示例和目标项目兼容证据的组件。修改已有符号前执行 GitNexus impact。

## 确定性校验与规范门卫

代码生成后先运行 `validate-scaffold.mjs`，传入本轮使用的同一份 `ProjectProfile` 和全部 `ComponentDecision`。确定性校验失败时先修复对应错误，不创建规范门卫。

确定性校验通过后读取 `references/review-guard.md` 和 `references/review-standard.md`，并通过平台原生能力创建独立只读规范门卫子代理。输入严格限定为用户需求与豁免摘要、`SceneSpec`、项目根目录、目标目录、本次生成或修改的文件清单、`ProjectProfile`、`ComponentDecision`、审查轮次，以及复审时的上一轮问题和修复摘要。门卫可读取直接依赖和项目规则取证，但只能报告清单内问题，不能编辑文件。

门卫输出保存到任务临时目录，再通过 `scripts/evaluate-review-gate.mjs --root <项目根目录> --report-root <任务临时目录>` 校验门卫身份、真实目标与文件清单、规则/Sisyphus 证据、固定段落、结论、问题等级和轮次。主 Agent 不自行解释或放宽不一致的报告。

门卫结论的处理规则：

- `通过` 且问题清单为“未发现规范问题”：进入项目 typecheck、lint、相关测试、页面验收和 GitNexus 检查。
- `部分通过` 或 `不通过`：主 Agent 按问题编号在文件清单内执行最小修复，然后重新运行确定性校验并创建新的门卫子代理复审。
- `无法判断`：立即阻断，不猜测缺失证据。
- 自动修复最多 2 轮；两轮后 P0、P1、P2 任一遗留问题都阻断交付，不允许忽略 P2。
- 修复需要变更文件清单之外的源码、公共 API、路由、权限、依赖或全局布局时停止并报告，不扩大范围。
- 平台无法创建独立只读子代理时阻断；不得降级为主 Agent 自审。

每次复审必须创建新子代理并基于当前文件重新取证，不能复用上一轮“通过”或问题清单。

## 停止条件

出现任一情况即停止代码生成：

- 项目不是最新目标版本的 antd 6 或 Sisyphus 4
- Sisyphus MCP 版本与目标版本不一致
- 必需能力处于 `unverified`
- 项目指令文件存在同级冲突
- Sisyphus、Ant Design 和项目组件均无法覆盖必需能力
- 无法确认会改变公共接口或业务数据流的关键需求
- 平台无法创建独立只读规范门卫子代理
- 门卫结论为“无法判断”
- 最多 2 轮自动修复后仍存在 P0、P1 或 P2 问题
- 门卫修复要求超出本次生成或修改的文件清单

停止时输出已完成的证据、未解决能力、建议的独立前置任务，不用占位代码伪装完成。