- name
- bie-zheng-luan-prototype
- description
- 将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、实体关系图、状态枚举定义。
别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)
本技能将产品原型转换为详细的技术实现规范文档，深度解析HTML结构，提取完整的界面信息。
✨ 核心能力（v2.4.0 新增）
深度HTML解析
本技能可从HTML原型中完整提取：
| 提取内容 | 说明 | 输出格式 |
|---|---|---|
| 菜单结构 | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |
| 筛选条件 | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |
| 表格列 | 列名、数据类型推断（text/number/date/link等） | 表格形式 |
| 操作按钮 | 按钮名、分类（search/action/delete等）、样式 | 表格形式 |
| 统计卡片 | 卡片标题、数值、说明 | 表格形式 |
| 页面视图 | 多页面识别，每个页面独立分析 | 按页面分章节输出 |
数据类型智能推断
表格列数据类型自动推断：
text- 普通文本number- 数值（含逗号分隔）date- 日期格式（YYYY-MM-DD）link- 可点击链接/单号badge- 状态标签progress- 进度条image- 图片列currency- 金额（含¥符号）percentage- 百分比
⚠️ 安全警告（重要） 使用本技能前请阅读以下安全注意事项： 1. 内网URL需确认：内网URL默认被阻止。如需分析内部原型，需使用--allow-internal参数确认风险。请勿分析不应被访问的内部系统。 2. 外部API默认禁用：视觉增强分析功能需要设置ANTHROPIC_API_KEY环境变量才会启用。默认情况下不调用外部API，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。 3. 手动安装依赖：Shell脚本不会自动安装Python依赖。请在运行前手动执行：pip install beautifulsoup4 pillow lxml4. 本地文件访问：技能会读取您指定的本地文件。请确保文件路径指向预期内容。
🛡️ 已实施的安全措施
本技能实施了以下安全防护措施：
命令注入防护
- 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%以上的系统。
🔧 当前版本能力
✅ 已支持
- URL原型分析：支持Figma、墨刀、Axure等主流工具的公开/内网URL
- 本地HTML文件分析：支持本地导出的HTML原型文件，直接读取文件系统路径
- 网页内容解析：提取DOM结构、样式信息、交互元素
- 图片原型分析：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告
- XMind文件分析：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点
📋 工作流程
第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步：功能拆解与职责划分
将解析出的元素拆解为细小功能单元，并判断实现方式：
前端职责（纯前端实现）
- 页面布局和样式
- 交互效果（悬停、点击动画）
- 本地数据操作（排序、过滤、分页）
- 表单验证（前端规则）
- 组件内部状态管理
后端职责（需要接口支持）
- 数据持久化（增删改查）
- 业务逻辑处理（计算、验证、流程）
- 外部系统集成（支付、消息、文件）
- 权限控制和安全性
- 批量操作和复杂查询
判断标准：
- 是否需要保存数据？ → 后端接口
- 是否需要复杂计算？ → 后端接口
- 是否涉及用户权限？ → 后端接口
- 是否只是UI交互？ → 前端实现
第3步：技术文档生成
生成结构化技术规范文档，包含：
3.1 系统概览
- 原型来源和类型
- 分析时间和版本
- 总体功能描述
3.2 页面结构分析
- 布局分解（头部、侧边栏、主内容区、底部）
- 功能模块清单（每个模块的位置、内容、交互）
3.3 前端实现方案
- 页面路由规划
- 组件清单（名称、props、状态、交互逻辑）
- 样式方案（CSS框架、设计系统）
- 交互细节（按钮点击、表单提交、数据展示）
3.4 后端实现方案
- API接口设计（路由、HTTP方法、参数、返回值）
- 业务逻辑伪代码（关键算法、流程控制）
- 数据库表设计（表名、字段、类型、关系）
- 第三方服务集成
3.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 - 核心解析器 - 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文件路径时，直接使用本技能：
# 技能会自动识别输入类型并启动相应流程手动触发
如果需要特定分析模式，可指定参数：
# 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的DOM结构，提取：
- 页面布局框架 - 导航和菜单 - 功能模块卡片 - 表单和交互元素 - 数据表格 - CSS设计系统（变量、颜色、字体）
- 生成文档：按照技能模板生成技术规范文档
- 输出结果：保存到指定路径或直接展示
📊 输出文档标准
前端组件描述标准
对于每个页面组件，需要描述：
- 组件位置：在页面哪个区域（头部/侧边栏/主内容区）
- 内容来源：
- 静态内容（写死在代码中） - 动态内容（从后端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表
⚠️ 安全注意事项
🔴 高风险操作警告：请在理解以下风险后使用本技能
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项目）可能无法访问完整内容 - 动态加载的内容可能无法完全捕获 - 复杂交互可能难以通过静态分析完全理解
- 输出质量：
- 文档详细程度直接影响生成系统的准确性 - 需要人工复核关键业务逻辑 - 建议与产品经理确认技术方案
📈 后续扩展计划
- V2.1：集成视觉模型API，实现图片原型精确UI识别
- V2.2：支持多原型合并分析，生成完整系统架构
- V2.3：添加Figma API直接解析（需授权）
- V3.0：自动化测试用例生成，一键生成可运行原型代码
📞 支持与反馈
- 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-04-29* *作者：杰哥*
更新日志：
- 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可适配任何业务领域（仓储、ERP、WMS、CMS等）。动态生成路由、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): 初始版本