Skill: jermyn-zmj/bie-zheng-luan-prototype (version 2.3.3)

--- 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 [REDACTED_SECRET]'ANTHROPIC_API_KEY') if not [REDACTED_SECRET]"警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析") print("将使用本地基础分析（颜色提取、布局推断）") client = anthropic.Anthropic([REDACTED_SECRET]) 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): 初始版本


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector:  ()