claw/docs/superpowers/specs/2026-04-18-scene-generator-ops-console-design.md

# Scene Generator Ops Console Design

> **Status:** Draft  
> **Date:** 2026-04-18  
> **Author:** Codex

## Problem Statement

当前 `http://127.0.0.1:3210/` 页面虽然已经具备 scene 选择、深度分析、Skill 生成和日志展示能力，但页面默认形态仍然更接近“开发调试控制台”，而不是“运维执行工作台”。

当前主要问题包括：

1. 首屏信息过多，配置项、分析结果、技术细节和日志同时展开，认知负担过高
2. 大量英文标题、字段名和技术术语直接暴露给运维人员，理解成本高
3. `Scene IR`、`workflowArchetype`、`requestTemplate`、`evidence` 等调试信息默认可见，不符合运维默认使用场景
4. 页面目前优先服务开发者调试，而不是运维执行、结果确认和问题定位

因此，该页面需要从“调试面板”收敛为“面向运维的场景 Skill 生成工作台”，并通过信息分层、中文化和双模式设计降低使用门槛。

## Goal

在不削弱原有分析和生成能力的前提下，将 scene generator 页面重构为：

1. 默认服务运维执行
2. 默认中文化
3. 默认只展示结论、操作和结果
4. 将技术细节折叠为调试层

页面重构后的阶段性目标是让运维人员可以不理解底层 `Scene IR` 和 archetype 术语，也能完成以下任务：

1. 选择场景目录
2. 启动分析
3. 判断是否可生成
4. 启动生成
5. 查看结果目录或失败原因

## Non-Goals

1. 不在本轮界面优化中修改 scene generator 后端接口协议
2. 不在本轮优化中重构分析算法或生成逻辑
3. 不要求删除现有调试信息，只要求调整默认显隐与信息分层
4. 不要求一次性完成全部视觉风格重设计

## User Roles

页面需要明确区分两类使用者：

### 1. 运维执行者

主要关注：

1. 处理哪个场景
2. 当前是否可生成
3. 为什么不能生成
4. 生成结果在哪里
5. 是否需要人工确认

### 2. 开发 / 调试者

主要关注：

1. `workflowArchetype`
2. `Scene IR`
3. `requestTemplate`
4. `evidence`
5. `bootstrap`
6. 原始日志流

默认界面必须优先服务运维执行者，开发 / 调试者通过“技术详情”进入二级信息层。

## Design Principles

### 1. 默认运维模式

首页默认展示“运维执行工作台”，而不是“技术调试面板”。

### 2. 先结论后证据

首屏先展示：

1. 当前状态
2. 场景识别结果
3. 可执行性评估
4. 风险摘要
5. 生成结果

技术证据、原始结构和底层日志应延后展示。

### 3. 默认中文化

面向运维的标题、按钮、状态、风险说明和结果文案应全部中文化。

### 4. 技术细节折叠

`Scene IR`、`evidence`、`requestTemplate`、`workflow steps` 等信息应进入“技术详情（调试用）”，默认折叠。

### 5. 状态表达业务化

不直接向运维展示 `Readiness A/B/C` 或 `workflowArchetype` 等底层字段，而应映射为可读的业务状态。

## Information Architecture

页面建议收敛为以下五个区域：

## 1. 顶部总览区

用于一眼说明页面用途和当前总体状态。

建议包含：

1. 页面标题
2. 页面副标题
3. 服务状态
4. 当前状态
5. 最近操作时间

## 2. 左侧主操作区

用于承载运维日常需要使用的输入与动作。

建议包含：

1. 场景目录
2. 场景名称
3. 输出目录
4. 开始分析
5. 生成 Skill
6. 重新开始
7. 高级设置（折叠）

## 3. 右侧结果摘要区

这是首屏核心区域，负责承载：

1. 场景识别结果
2. 可执行性评估
3. 风险提示
4. 生成结果

## 4. 底部执行过程区

用于展示中文化后的关键执行过程日志，而不是开发流原始 SSE 输出。

## 5. 技术详情区

默认折叠，仅在开发和排障时查看。

建议包含：

1. 场景识别详情
2. 接口与请求信息
3. 执行步骤
4. 模式信息
5. 识别依据
6. 风险与缺失项
7. 原始 JSON / Scene IR
8. 原始技术日志

## Default Page Layout

建议页面结构如下：

```text
[标题区]
场景 Skill 生成工作台
当前状态 | 服务状态 | 最近操作时间

[左侧：操作区]
场景目录
场景名称
输出目录
开始分析
生成 Skill
高级设置（折叠）

[右侧：结果摘要区]
卡片1：场景识别结果
卡片2：可执行性评估
卡片3：风险提示
卡片4：生成结果

[底部：执行过程]
中文摘要日志

[折叠区：技术详情（调试用）]
场景识别详情
工作流步骤
模式信息
请求模板
证据与风险
原始 JSON
原始技术日志
```

## Default Field Visibility

### 一级信息：运维必须看

默认始终可见：

1. 场景目录
2. 场景名称
3. 输出目录
4. 当前状态
5. 场景类型
6. 可执行性评估
7. 风险摘要
8. 生成结果
9. 输出目录 / 结果文件

### 二级信息：运维偶尔看

默认展示简版：

1. 目标系统
2. 输出类型
3. 最近一次执行结果
4. 阻断原因

### 三级信息：开发 / 调试看

默认折叠：

1. `scene-id`
2. `scene-kind`
3. `targetUrl override`
4. `workflow archetype override`
5. `requestTemplate`
6. `staticParams`
7. `evidence`
8. `confidence`
9. `bootstrap domain`
10. `workflow steps`
11. `endpoints`
12. 原始 SSE 日志

## Chinese Copy Strategy

## Page Title

建议使用：

- `场景 Skill 生成工作台`

副标题建议：

- `用于分析场景、生成 Skill，并查看内网执行准备情况`

## Main Action Labels

建议按钮文案：

1. `选择目录`
2. `开始分析`
3. `生成 Skill`
4. `重新开始`
5. `恢复默认`
6. `打开输出目录`
7. `查看结果文件`

## Section Titles

建议区块标题：

1. `场景操作`
2. `分析结果`
3. `场景识别结果`
4. `可执行性评估`
5. `风险提示`
6. `生成结果`
7. `执行过程`
8. `技术详情（调试用）`

## Status Copy

建议页面主状态：

1. `待选择场景`
2. `已选择场景，待分析`
3. `分析中`
4. `分析完成`
5. `可直接生成`
6. `可生成但需确认`
7. `暂不建议生成`
8. `生成中`
9. `生成完成`
10. `生成失败`

## Readiness Mapping

不建议直接向运维展示 `Readiness A/B/C`，建议映射为：

1. `A -> 可直接生成`
2. `B -> 可生成但需确认`
3. `C -> 暂不建议生成`

## Archetype Mapping

不建议直接向运维展示英文 archetype，建议映射为：

1. `single_request_table -> 单页报表`
2. `wrapped_single_mode -> 单页报表`
3. `multi_mode_request -> 多模式报表`
4. `paginated_enrichment -> 分页明细`
5. `page_state_eval -> 页面检测`
6. `embedded_page_tool -> 工具场景`
7. `page_exec_check -> 检测场景`

## Result Copy Examples

可执行性评估区建议使用中文业务态说明，例如：

1. `已识别完整查询链与报表输出链，可直接生成`
2. `主要流程已识别，但存在部分风险，建议确认后生成`
3. `当前缺少关键执行信息，暂不建议直接生成`

风险提示区建议使用简短中文风险，例如：

1. `未识别完整分页链`
2. `导出规则识别不完整`
3. `目标系统地址存在冲突`
4. `场景类型识别置信度偏低`
5. `存在宿主桥接依赖，需内网环境验证`

执行过程区建议使用中文摘要日志，例如：

1. `已开始分析场景`
2. `已完成基础信息识别`
3. `已完成深度分析`
4. `已识别场景类型：多模式报表`
5. `已开始生成 Skill`
6. `Skill 已生成完成`
7. `输出目录：xxx`
8. `生成失败：未识别完整分页补数链`

## Interaction Model

### Default Flow

运维默认流程应收敛为：

1. 选择场景目录
2. 点击开始分析
3. 查看分析摘要
4. 点击生成 Skill
5. 查看结果目录或失败原因

### Advanced Flow

只有在分析失败、生成失败或需要排障时，才进入以下流程：

1. 展开风险详情
2. 展开技术详情
3. 查看原始日志和识别依据

## Implementation Priorities

本界面优化建议按以下顺序推进：

1. 默认中文化
2. 默认隐藏技术细节
3. 默认只展示“状态摘要 + 操作 + 结果”
4. 日志区中文化
5. 高级设置折叠
6. 技术详情折叠

## Acceptance Criteria

本界面优化完成的标志是：

1. 运维人员不理解 `Scene IR`、`workflowArchetype` 等术语，也能完成场景分析和 Skill 生成
2. 首屏不再出现大面积未经翻译的英文标题和底层技术字段
3. 首屏主要承载“状态摘要 + 操作 + 结果”，技术细节默认折叠
4. 页面默认服务运维执行，技术调试仍可通过二级区域完成

## Open Questions

1. 是否需要显式提供“运维模式 / 调试模式”切换，而不是仅通过折叠区分层
2. 结果文件是否需要在页面内提供直接打开入口
3. 风险提示区是否需要区分“阻断项”和“提醒项”