Metadata

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推断状态值和流转规则
操作条件推断	推断操作是否需要勾选记录、特定状态等条件
生成确认问题	按优先级生成问题，让用户确认或修正推断

⚠️ 安全警告（重要）

使用本技能前请阅读以下安全注意事项：

内网URL需确认：内网URL默认被阻止。如需分析内部原型，需使用 --allow-internal 参数确认风险。请勿分析不应被访问的内部系统。

外部API默认禁用：视觉增强分析功能需要设置 ANTHROPIC_API_KEY 环境变量才会启用。默认情况下不调用外部API，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。

手动安装依赖：Shell脚本不会自动安装Python依赖。请在运行前手动执行：pip install beautifulsoup4 pillow lxml

本地文件访问：技能会读取您指定的本地文件。请确保文件路径指向预期内容。

🛡️ 已实施的安全措施

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

命令注入防护

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
仅检查依赖并提示用户手动安装
避免运行时写入操作

路径安全验证

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

🎯 技能用途

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

URL原型 - Figma、墨刀、Axure、蓝湖、内网分享链接等
本地HTML文件 - 导出的HTML原型文件、本地保存的网页原型
图片原型 - 设计稿截图、高保真原型图
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原型解析

# 使用 web_fetch 获取页面内容
# 分析HTML结构，提取关键信息

提取内容：

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

B. 本地HTML文件解析

# 使用 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

基础分析功能（当前实现）：

# 使用 image-prototype-analyzer.py 进行基础分析
python scripts/image-prototype-analyzer.py design.png markdown

提取内容：

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

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

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

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

# 使用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 (元数据)

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

提取内容：

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

智能推断功能：基于节点标题关键词，自动推断：

功能模块（包含"模块"、"管理"、"系统"）
页面结构（包含"页面"、"列表"、"详情"）
功能点（包含"功能"、"操作"、"按钮"）

输出内容：

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

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

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

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

分析输出包含：

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

第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文件路径时，直接使用本技能：

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

输出格式

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

# 标准分析报告（默认）
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

手动触发

如果需要特定分析模式，可指定参数：

# 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文件时，按照以下流程执行：

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

📊 输出文档标准

前端组件描述标准

对于每个页面组件，需要描述：

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

后端接口描述标准

对于每个API接口，需要描述：

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

数据库设计标准

对于每个业务实体，需要设计：

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

🔍 示例场景

示例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的依赖

⚠️ 技术限制

访问限制：
- 需要登录的工具（如私有Figma项目）可能无法访问完整内容
- 动态加载的内容可能无法完全捕获
- 复杂交互可能难以通过静态分析完全理解
输出质量：
- 文档详细程度直接影响生成系统的准确性
- 需要人工复核关键业务逻辑
- 建议与产品经理确认技术方案

📞 支持与反馈

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

📄 许可证

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

🤝 贡献

欢迎提交Issue和Pull Request！

Fork 本仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 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): 初始版本

别整乱七八糟的原型

安装技能

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

✨ 核心能力

深度HTML解析

数据类型智能推断

交互式业务分析（v3.0 新增）

🛡️ 已实施的安全措施

命令注入防护

SSRF防护（用户确认模式）

外部API控制

无自动安装

路径安全验证

🎯 技能用途

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

✅ 已支持

📋 工作流程

第1步：原型内容解析

A. URL原型解析

B. 本地HTML文件解析

C. 图片原型解析

D. XMind原型解析

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

第3步：功能拆解与职责划分

前端职责（纯前端实现）

后端职责（需要接口支持）

第4步：技术文档生成

4.1 系统概览

4.2 页面结构分析

4.3 前端实现方案

4.4 后端实现方案

4.5 开发注意事项

🛠️ 工具和资源

内置脚本

参考模板

输出示例

📝 使用方法

基本调用

输出格式

手动触发

输入类型自动识别

分析助手执行流程

📊 输出文档标准

前端组件描述标准

后端接口描述标准

数据库设计标准

🔍 示例场景

示例1：用户管理系统原型

示例2：电商商品页面原型

示例3：业务流程分析（交互式模式）

⚠️ 安全注意事项

1. 网络访问与SSRF风险

2. 外部API数据传输

3. 本地文件访问

4. 首次使用安全检查

⚠️ 技术限制

📞 支持与反馈

📄 许可证

🤝 贡献