别整乱七八糟的原型

SKILL.md

---
name: bie-zheng-luan-prototype
description: "将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、实体关系图、状态枚举定义。新增交互式业务分析功能，可从原型推断业务流程、状态流转，生成问题让用户确认。"
---

# 别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)

本技能将产品原型转换为详细的技术实现规范文档，**深度解析HTML结构**，提取完整的界面信息，并通过**交互式分析**推断业务流程。

## ✨ 核心能力

### 深度HTML解析
本技能可从HTML原型中完整提取：

| 提取内容 | 说明 | 输出格式 |
|---------|------|---------|
| **菜单结构** | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |
| **筛选条件** | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |
| **表格列** | 列名、数据类型推断（text/number/date/link等） | 表格形式 |
| **操作按钮** | 按钮名、分类（search/action/delete等）、样式、位置 | 表格形式 |
| **统计卡片** | 卡片标题、数值、说明 | 表格形式 |
| **页面视图** | 多页面识别，每个页面独立分析 | 按页面分章节输出 |
| **状态Tab** | 状态名称、数量、颜色类型 | 表格形式 |
| **抽屉/弹窗** | 标题、锚点导航、表单字段、统计信息 | 分章节输出 |

### 数据类型智能推断
表格列数据类型自动推断：
- `text` - 普通文本
- `number` - 数值（含逗号分隔）
- `date` - 日期格式（YYYY-MM-DD）
- `link` - 可点击链接/单号
- `badge` - 状态标签
- `progress` - 进度条
- `image` - 图片列
- `currency` - 金额（含¥符号）
- `percentage` - 百分比

### 交互式业务分析（v3.0 新增）
从HTML原型自动推断业务逻辑，生成问题让用户确认：

| 分析内容 | 说明 |
|---------|------|
| **页面角色推断** | 识别入口页面、处理页面、查看页面、配置页面 |
| **业务流程推断** | 基于菜单顺序、字段关联推断页面流转顺序 |
| **状态流转推断** | 从按钮操作和状态Tab推断状态值和流转规则 |
| **操作条件推断** | 推断操作是否需要勾选记录、特定状态等条件 |
| **生成确认问题** | 按优先级生成问题，让用户确认或修正推断 |

> ⚠️ **安全警告（重要）**
>
> 使用本技能前请阅读以下安全注意事项：
>
> 1. **内网URL需确认**：内网URL默认被阻止。如需分析内部原型，需使用 `--allow-internal` 参数确认风险。请勿分析不应被访问的内部系统。
>
> 2. **外部API默认禁用**：视觉增强分析功能需要设置 `ANTHROPIC_API_KEY` 环境变量才会启用。**默认情况下不调用外部API**，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。
>
> 3. **手动安装依赖**：Shell脚本**不会自动安装Python依赖**。请在运行前手动执行：`pip install beautifulsoup4 pillow lxml`
>
> 4. **本地文件访问**：技能会读取您指定的本地文件。请确保文件路径指向预期内容。

## 🛡️ 已实施的安全措施

本技能实施了以下安全防护措施：

### 命令注入防护
- URL验证：只允许 `http://` 和 `https://` 协议
- 危险字符检测：阻止Shell特殊字符（`;|&$`'\"()<>`）
- 长度限制：URL最大2048字符

### SSRF防护（用户确认模式）
- **默认阻止内网URL**：检测私有网络地址自动拒绝
- **用户确认机制**：需使用 `--allow-internal` 参数才能访问内网
- 检测范围：`localhost`、`127.x`、`10.x`、`172.16-31.x`、`192.168.x`、`169.254.x`

### 外部API控制
- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 时，不调用任何外部API
- **用户触发**：仅在用户主动设置环境变量后启用
- **数据传输明确**：启用后图片会通过base64发送到Anthropic

### 无自动安装
- Shell脚本**不执行** `pip install`
- 仅检查依赖并提示用户手动安装
- 避免运行时写入操作

### 路径安全验证
- 检测敏感路径关键词并发出警告
- 限制路径长度
- 验证文件存在性

## 🎯 技能用途

当产品经理提供以下任意形式的原型时，使用本技能：

1. **URL原型** - Figma、墨刀、Axure、蓝湖、内网分享链接等
2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型
3. **图片原型** - 设计稿截图、高保真原型图
4. **XMind文件** - 产品功能脑图、信息架构

**输出目标**：生成一份详细的技术规范文档，让大模型能据此生成相似度90%以上的系统。

## 🔧 当前版本能力（v3.1.0）

### ✅ 已支持
- **URL原型分析**：支持Figma、墨刀、Axure等主流工具的公开/内网URL
- **本地HTML文件分析**：支持本地导出的HTML原型文件，直接读取文件系统路径
- **网页内容解析**：提取DOM结构、样式信息、交互元素
- **图片原型分析**：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告
- **XMind文件分析**：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点
- **交互式业务分析**：从原型推断业务流程，生成问题让用户确认，循环迭代直到理解完整业务逻辑
- **多UI框架适配**：自动检测并适配企业后台、标准后台、移动端H5等UI框架

## 📋 工作流程

### 第1步：原型内容解析
根据输入类型选择合适的解析方式：

#### A. URL原型解析
```bash
# 使用 web_fetch 获取页面内容
# 分析HTML结构，提取关键信息
```

**提取内容**：
- 页面整体布局（头部、侧边栏、主内容区、底部）
- 导航菜单结构（一级菜单、二级菜单）
- 功能模块划分（卡片、表单、列表、图表等）
- 交互元素（按钮、输入框、下拉框、链接等）
- 文本内容（标题、描述、标签、按钮文字）

#### B. 本地HTML文件解析
```bash
# 使用 read 工具直接读取本地HTML文件
# 分析DOM结构，提取关键信息
```

**适用场景**：
- 从原型工具（Figma/墨刀/Axure等）导出的HTML文件
- 本地保存的网页原型
- 需要离线分析的原型文件

**输入方式**：
- 文件路径（如 `/path/to/prototype.html`）
- 文件内容粘贴（用户直接粘贴HTML代码）

**提取内容**（与URL原型相同）：
- 页面整体布局（头部、侧边栏、主内容区、底部）
- 导航菜单结构（一级菜单、二级菜单）
- 功能模块划分（卡片、表单、列表、图表等）
- 交互元素（按钮、输入框、下拉框、链接等）
- 文本内容（标题、描述、标签、按钮文字）
- CSS设计系统（颜色变量、字体、间距等设计Token）

#### C. 图片原型解析

**适用场景**：
- 产品设计稿截图
- 高保真原型图
- UI设计文件导出图片
- 线框图/草图

**输入方式**：
- 图片文件路径（如 `/path/to/design.png`）
- 支持格式：PNG, JPG, JPEG, GIF, WebP, BMP

**基础分析功能**（当前实现）：
```bash
# 使用 image-prototype-analyzer.py 进行基础分析
python scripts/image-prototype-analyzer.py design.png markdown
```

**提取内容**：
- 图片尺寸和比例
- 主要颜色方案（提取前10种主色）
- 布局区域推断（基于尺寸比例）
  - 头部区域（顶部10-15%）
  - 侧边栏区域（左侧15-20%）
  - 主内容区
  - 底部区域
- 颜色统计和配色建议

**增强分析方案**（可选，需配置API密钥）：

> ⚠️ **数据传输警告**：使用视觉增强分析会将图片数据发送到外部API服务。请确认图片不含敏感信息后再启用。

图片原型分析建议配合视觉大模型获得精确结果。需设置环境变量 `ANTHROPIC_API_KEY`：

```python
# 使用Claude Vision进行精确UI识别
# 注意：此功能会将图片发送到Anthropic服务器
import anthropic
import base64
import os

# 需要设置环境变量: ANTHROPIC_API_KEY
api_key = os.environ.get('ANTHROPIC_API_KEY')
if not api_key:
    print("警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析")
    print("将使用本地基础分析（颜色提取、布局推断）")

client = anthropic.Anthropic(api_key=api_key)

with open('design.png', 'rb') as f:
    image_data = base64.b64encode(f.read()).decode()

response = client.messages.create(
    model='claude-3-opus-20240229',
    max_tokens=4096,
    messages=[{
        'role': 'user',
        'content': [
            {'type': 'image', 'source': {'type': 'base64', 'media_type': 'image/png', 'data': image_data}},
            {'type': 'text', 'text': '''分析这张UI设计稿，提取：
1. 页面布局结构（头部、侧边栏、主内容区、底部）
2. UI组件类型（按钮、输入框、表格、卡片等）
3. 交互元素（可点击、可输入）
4. 颜色方案（主色、辅助色、背景色）
5. 文本内容（标题、描述、按钮文案）
请以结构化格式输出。'''}
        ]
    }]
)
```

**视觉模型分析输出**：
- 精确的UI元素位置和类型
- 完整的文本内容提取
- 交互元素识别（按钮、链接、输入框）
- 样式细节（颜色、字体大小推断）
- 组件层级关系

#### D. XMind原型解析

**适用场景**：
- 产品功能脑图
- 信息架构图
- 业务流程图
- 需求结构图

**输入方式**：
- XMind文件路径（如 `/path/to/product.xmind`）
- 支持XMind 8和XMind 2020+格式

**技术原理**：
XMind文件是zip压缩包，包含：
- `content.json` (XMind 2020+格式)
- `content.xml` (XMind 8格式)
- `manifest.xml` (元数据)

```bash
# 使用 xmind-analyzer.py 进行分析
python scripts/xmind-analyzer.py product.xmind markdown
```

**提取内容**：
- 思维导图完整结构
- 所有节点标题和层级
- 节点属性（颜色、图标、备注）
- 统计信息（节点总数、最大层级）

**智能推断功能**：
基于节点标题关键词，自动推断：
1. **功能模块**（包含"模块"、"管理"、"系统"）
2. **页面结构**（包含"页面"、"列表"、"详情"）
3. **功能点**（包含"功能"、"操作"、"按钮"）

**输出内容**：
- YAML格式的思维导图结构
- 功能模块清单（含子节点）
- 页面结构建议（含功能点）
- 前端路由规划建议
- 后端API接口规划
- 数据库表设计建议

### 第2步：交互式业务分析（v3.0 新增）

当分析HTML原型时，技能会自动进入交互式分析模式：

1. **页面角色推断**：识别每个页面是入口页面、处理页面还是查看页面
2. **业务流程推断**：基于菜单顺序和字段关联推断页面流转顺序
3. **状态流转推断**：从按钮操作和状态Tab推断状态值和流转规则
4. **生成确认问题**：按优先级生成问题，让用户确认或修正推断
5. **循环迭代**：用户回答后继续深入分析，直到理解完整业务逻辑

**分析输出包含**：
- 业务流程顺序（页面流转图）
- 每个页面的操作列表和执行条件
- 状态流转规则（状态机图）
- 关键字段和筛选维度
- 需要用户确认的问题清单

### 第3步：功能拆解与职责划分
将解析出的元素拆解为细小功能单元，并判断实现方式：

#### 前端职责（纯前端实现）
- 页面布局和样式
- 交互效果（悬停、点击动画）
- 本地数据操作（排序、过滤、分页）
- 表单验证（前端规则）
- 组件内部状态管理

#### 后端职责（需要接口支持）
- 数据持久化（增删改查）
- 业务逻辑处理（计算、验证、流程）
- 外部系统集成（支付、消息、文件）
- 权限控制和安全性
- 批量操作和复杂查询

**判断标准**：
- 是否需要保存数据？ → 后端接口
- 是否需要复杂计算？ → 后端接口  
- 是否涉及用户权限？ → 后端接口
- 是否只是UI交互？ → 前端实现

### 第4步：技术文档生成
生成结构化技术规范文档，包含：

#### 4.1 系统概览
- 原型来源和类型
- 分析时间和版本
- 总体功能描述

#### 4.2 页面结构分析
- 布局分解（头部、侧边栏、主内容区、底部）
- 功能模块清单（每个模块的位置、内容、交互）

#### 4.3 前端实现方案
- 页面路由规划
- 组件清单（名称、props、状态、交互逻辑）
- 样式方案（CSS框架、设计系统）
- 交互细节（按钮点击、表单提交、数据展示）

#### 4.4 后端实现方案
- API接口设计（路由、HTTP方法、参数、返回值）
- 业务逻辑伪代码（关键算法、流程控制）
- 数据库表设计（表名、字段、类型、关系）
- 第三方服务集成

#### 4.5 开发注意事项
- 技术栈建议
- 特殊依赖说明
- 性能和安全考虑
- 测试要点

## 🛠️ 工具和资源

### 内置脚本
- `scripts/url-prototype-analyzer.sh` - URL原型解析主脚本
- `scripts/html-extractor.py` - HTML内容提取工具入口（调用 html_extractor 包）
- `scripts/html_extractor/` - HTML解析核心模块包
  - `config.py` - UI框架配置
  - `models.py` - 数据结构定义
  - `detector.py` - UI框架检测器
  - `extractor.py` - 核心解析器
  - `analyzer.py` - 业务流程分析器（v3.0 新增）
  - `utils.py` - 辅助函数
  - `main.py` - 入口函数
- `scripts/spec-generator.py` - 技术文档生成工具
- `scripts/image-prototype-analyzer.py` - 图片原型分析工具
- `scripts/xmind-analyzer.py` - XMind文件分析工具
- `scripts/run_analysis.sh` - 综合分析入口脚本

### 参考模板
- `references/template-spec.md` - 技术规范文档模板
- `references/component-catalog.md` - 前端组件目录
- `references/api-design.md` - API设计规范

### 输出示例
- `assets/sample-output/` - 示例输出文档

## 📝 使用方法

### 基本调用
当用户提供原型URL或本地HTML文件路径时，直接使用本技能：

```bash
# 技能会自动识别输入类型并启动相应流程
```

### 输出格式
HTML分析支持三种输出格式：

```bash
# 标准分析报告（默认）
python scripts/html-extractor.py prototype.html markdown

# JSON格式数据
python scripts/html-extractor.py prototype.html json

# 交互式业务分析（包含流程推断和问题）
python scripts/html-extractor.py prototype.html interactive
```

### 手动触发
如果需要特定分析模式，可指定参数：

```bash
# URL原型分析
分析这个Figma原型：https://www.figma.com/file/xxx

# 本地HTML文件分析
分析这个HTML原型文件：/path/to/prototype.html
分析这个HTML原型文件：[直接粘贴HTML内容]

# 图片原型分析
分析这张设计稿截图：/path/to/design.png
# 配合视觉模型增强分析：
使用Claude Vision分析这张设计稿：/path/to/design.png

# XMind原型分析
分析这个产品脑图：/path/to/product.xmind
分析这个信息架构：/path/to/architecture.xmind
```

### 输入类型自动识别
技能会根据输入内容自动判断解析方式：

| 输入内容 | 识别方式 | 解析方式 |
|---------|---------|---------|
| `https://...` | 以http/https开头 | URL原型解析 |
| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |
| `<!DOCTYPE html>...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |
| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |
| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |

### 分析助手执行流程
作为AI助手，当用户提供本地HTML文件时，按照以下流程执行：

1. **读取文件**：使用 `read` 工具读取HTML文件内容
2. **解析结构**：调用 html_extractor 包解析HTML的DOM结构，提取：
   - 页面布局框架
   - 导航和菜单
   - 功能模块卡片
   - 表单和交互元素
   - 数据表格
   - CSS设计系统（变量、颜色、字体）
3. **业务分析**：调用 BusinessFlowAnalyzer 推断业务流程和状态流转
4. **交互确认**：生成问题让用户确认，循环迭代
5. **生成文档**：按照技能模板生成技术规范文档
6. **输出结果**：保存到指定路径或直接展示

## 📊 输出文档标准

### 前端组件描述标准
对于每个页面组件，需要描述：

1. **组件位置**：在页面哪个区域（头部/侧边栏/主内容区）
2. **内容来源**：
   - 静态内容（写死在代码中）
   - 动态内容（从后端API获取）
   - 用户输入（表单字段）
3. **展示样式**：
   - 布局方式（Flex/Grid/绝对定位）
   - 尺寸和间距
   - 颜色和字体
   - 响应式行为
4. **交互逻辑**：
   - 按钮点击触发什么操作
   - 按钮名称和文案
   - 操作类型（导航/提交/删除/等）
   - 成功/失败反馈方式

### 后端接口描述标准
对于每个API接口，需要描述：

1. **路由信息**：
   - HTTP方法（GET/POST/PUT/DELETE）
   - URL路径（/api/resource/:id）
   - 接口名称和用途
2. **参数说明**：
   - 路径参数（:id）
   - 查询参数（?page=1&size=10）
   - 请求体（JSON结构）
   - 必填/选填字段
3. **返回值**：
   - 成功响应（HTTP 200，JSON结构）
   - 错误响应（HTTP 4xx/5xx，错误信息）
   - 分页结构（如果需要）
4. **业务逻辑伪代码**：
   - 主要处理步骤
   - 数据库操作（查询/插入/更新/删除）
   - 业务规则验证
   - 异常处理逻辑

### 数据库设计标准
对于每个业务实体，需要设计：

1. **表结构**：
   - 表名（复数形式，小写加下划线）
   - 主键字段（id，自增或UUID）
   - 业务字段（名称、类型、长度、默认值）
   - 索引字段（查询优化）
2. **表关系**：
   - 一对一关系
   - 一对多关系（外键）
   - 多对多关系（中间表）
3. **约束条件**：
   - 唯一约束
   - 非空约束
   - 外键约束

## 🔍 示例场景

### 示例1：用户管理系统原型
**输入**：Figma用户管理后台URL

**输出包含**：
- 前端：用户列表组件、用户表单组件、权限选择组件
- 后端：用户CRUD接口、权限验证接口、搜索接口
- 数据库：users表、roles表、user_roles关联表

### 示例2：电商商品页面原型  
**输入**：墨刀电商商品详情页URL

**输出包含**：
- 前端：商品展示组件、购物车组件、评价组件
- 后端：商品查询接口、购物车接口、下单接口
- 数据库：products表、categories表、orders表

### 示例3：业务流程分析（交互式模式）
**输入**：本地HTML原型文件

**输出包含**：
- 业务流程顺序（页面流转图）
- 每个页面的操作列表和执行条件
- 状态流转规则（状态机图）
- 关键字段和筛选维度
- 需要用户确认的问题清单

## ⚠️ 安全注意事项

> 🔴 **高风险操作警告**：请在理解以下风险后使用本技能

### 1. 网络访问与SSRF风险
- **支持内网URL**：本技能可以访问内网链接（如 `http://internal.company.com/prototype`）
- **SSRF风险**：恶意或错误的URL可能触发服务器端请求伪造，访问未预期的内部资源
- **安全建议**：
  - 仅提供您有权访问且明确需要分析的原型链接
  - 不要提供包含敏感数据的内部系统URL（如管理后台、API端点）
  - 在受控网络环境中分析内部原型

### 2. 外部API数据传输
- **视觉增强分析**：使用Claude Vision需要将图片发送到Anthropic服务器
- **数据泄露风险**：设计稿可能包含敏感业务信息、知识产权内容
- **安全建议**：
  - 启用视觉增强前确认图片不含敏感信息
  - 不设置 `ANTHROPIC_API_KEY` 时使用本地基础分析（不传输数据）
  - 对敏感设计稿仅使用本地分析功能

### 3. 本地文件访问
- **读取范围**：技能会读取您指定的本地文件路径
- **误操作风险**：错误路径可能读取非预期的敏感文件
- **安全建议**：
  - 确保文件路径准确指向目标原型文件
  - 不要将技能指向包含密钥、配置文件的目录

### 4. 首次使用安全检查
- **脚本审查**：首次使用前建议检查 `scripts/` 目录下的Python脚本
- **隔离测试**：建议在虚拟环境或沙箱中首次运行
- **依赖安装**：在虚拟环境中安装requirements.txt的依赖

## ⚠️ 技术限制

1. **访问限制**：
   - 需要登录的工具（如私有Figma项目）可能无法访问完整内容
   - 动态加载的内容可能无法完全捕获
   - 复杂交互可能难以通过静态分析完全理解

2. **输出质量**：
   - 文档详细程度直接影响生成系统的准确性
   - 需要人工复核关键业务逻辑
   - 建议与产品经理确认技术方案

## 📞 支持与反馈

- **GitHub仓库**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype
- **问题反馈**: 通过GitHub Issues提交
- **功能建议**: 通过GitHub Discussions讨论

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🤝 贡献

欢迎提交Issue和Pull Request！

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

---

*最后更新：2026-05-18*
*版本：v3.1.0*
*作者：杰哥*

**更新日志**：
- v3.1.0 (2026-05-18): 优化交互式分析：改进页面名称匹配（通过菜单page_id匹配view_id）、过滤无效按钮（去重和过滤纯图标按钮）、清理状态Tab名称（分离名称和数量）、增强UI框架适配（新增scm-view容器模式）
- v3.0.0 (2026-05-18): 新增交互式业务分析功能：从原型推断业务流程和状态流转、生成问题让用户确认、循环迭代直到理解完整业务逻辑。新增BusinessFlowAnalyzer模块。
- v2.9.2 (2026-04-29): 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）、补充作者信息和项目链接，响应平台安全审查建议
- v2.9.1 (2026-04-29): 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）
- v2.9.0 (2026-04-29): 完全通用化重构：移除所有硬编码的业务专有名词，使skill可适配任何业务领域。动态生成路由、API接口、数据库表，不依赖特定业务词汇映射。
- v2.8.0 (2026-04-29): 增强技术实现推断能力：智能路由解析（处理javascript:void(0)等特殊值）、增强按钮位置识别（多层级父元素检查）、业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义
- v2.7.0 (2026-04-29): 模块化重构：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块），提高可维护性
- v2.6.0 (2026-04-24): 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息、状态筛选Tab、进度条组件
- v2.5.0 (2026-04-24): 补充缺失解析模块：消息通知卡片、人员进度卡片、页面标签栏、用户信息区、子标签切换；优化表格层级识别和数据类型推断
- v2.4.0 (2026-04-24): 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮、多页面视图
- v2.3.0 (2026-04-23): 内网URL默认阻止需用户确认、禁止自动pip安装、外部API默认禁用
- v2.2.0 (2026-04-23): 实施命令注入防护、URL/路径输入验证
- v2.1.0 (2026-04-23): 增加安全警告、声明可选API凭证
- v2.0.0 (2026-04-22): 新增图片/XMind分析功能
- v1.0.0 (2026-04-21): 初始版本