别整乱七八糟原型分析技能 (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 文件了解详情。

🤝 贡献#

欢迎提交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): 初始版本