\r \r

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

\r 本技能将产品原型转换为详细的技术实现规范文档，深度解析HTML结构，提取完整的界面信息。\r \r

✨ 核心能力（v2.4.0 新增）\r

\r

深度HTML解析\r

本技能可从HTML原型中完整提取：\r \r | 提取内容 | 说明 | 输出格式 |\r |---------|------|---------|\r | 菜单结构 | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |\r | 筛选条件 | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |\r | 表格列 | 列名、数据类型推断（text/number/date/link等） | 表格形式 |\r | 操作按钮 | 按钮名、分类（search/action/delete等）、样式 | 表格形式 |\r | 统计卡片 | 卡片标题、数值、说明 | 表格形式 |\r | 页面视图 | 多页面识别，每个页面独立分析 | 按页面分章节输出 |\r \r

数据类型智能推断\r

表格列数据类型自动推断：\r

• text - 普通文本\r
• number - 数值（含逗号分隔）\r
• date - 日期格式（YYYY-MM-DD）\r
• link - 可点击链接/单号\r
• badge - 状态标签\r
• progress - 进度条\r
• image - 图片列\r
• currency - 金额（含¥符号）\r
• percentage - 百分比\r \r

⚠️ 安全警告（重要）\r \r 使用本技能前请阅读以下安全注意事项：\r \r

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

🛡️ 已实施的安全措施\r

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

命令注入防护\r

• URL验证：只允许 http:// 和 https:// 协议\r
• 危险字符检测：阻止Shell特殊字符（;|&$'"()\x3C>`）\r
• 长度限制：URL最大2048字符\r \r

SSRF防护（用户确认模式）\r

• 默认阻止内网URL：检测私有网络地址自动拒绝\r
• 用户确认机制：需使用 --allow-internal 参数才能访问内网\r
• 检测范围：localhost、127.x、10.x、172.16-31.x、192.168.x、169.254.x\r \r

外部API控制\r

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

无自动安装\r

• Shell脚本不执行 pip install\r
• 仅检查依赖并提示用户手动安装\r
• 避免运行时写入操作\r \r

路径安全验证\r

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

🎯 技能用途\r

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

1. URL原型 - Figma、墨刀、Axure、蓝湖、内网分享链接等\r
2. 本地HTML文件 - 导出的HTML原型文件、本地保存的网页原型\r
3. 图片原型 - 设计稿截图、高保真原型图\r
4. XMind文件 - 产品功能脑图、信息架构\r \r 输出目标：生成一份详细的技术规范文档，让大模型能据此生成相似度90%以上的系统。\r \r

🔧 当前版本能力\r

\r

✅ 已支持\r

• URL原型分析：支持Figma、墨刀、Axure等主流工具的公开/内网URL\r
• 本地HTML文件分析：支持本地导出的HTML原型文件，直接读取文件系统路径\r
• 网页内容解析：提取DOM结构、样式信息、交互元素\r
• 图片原型分析：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告\r
• XMind文件分析：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点\r \r

📋 工作流程\r

\r

第1步：原型内容解析\r

根据输入类型选择合适的解析方式：\r \r

A. URL原型解析\r

# 使用 web_fetch 获取页面内容\r
# 分析HTML结构，提取关键信息\r
```\r
\r
**提取内容**：\r
- 页面整体布局（头部、侧边栏、主内容区、底部）\r
- 导航菜单结构（一级菜单、二级菜单）\r
- 功能模块划分（卡片、表单、列表、图表等）\r
- 交互元素（按钮、输入框、下拉框、链接等）\r
- 文本内容（标题、描述、标签、按钮文字）\r
\r
#### B. 本地HTML文件解析\r
```bash\r
# 使用 read 工具直接读取本地HTML文件\r
# 分析DOM结构，提取关键信息\r
```\r
\r
**适用场景**：\r
- 从原型工具（Figma/墨刀/Axure等）导出的HTML文件\r
- 本地保存的网页原型\r
- 需要离线分析的原型文件\r
\r
**输入方式**：\r
- 文件路径（如 `/path/to/prototype.html`）\r
- 文件内容粘贴（用户直接粘贴HTML代码）\r
\r
**提取内容**（与URL原型相同）：\r
- 页面整体布局（头部、侧边栏、主内容区、底部）\r
- 导航菜单结构（一级菜单、二级菜单）\r
- 功能模块划分（卡片、表单、列表、图表等）\r
- 交互元素（按钮、输入框、下拉框、链接等）\r
- 文本内容（标题、描述、标签、按钮文字）\r
- CSS设计系统（颜色变量、字体、间距等设计Token）\r
\r
#### C. 图片原型解析\r
\r
**适用场景**：\r
- 产品设计稿截图\r
- 高保真原型图\r
- UI设计文件导出图片\r
- 线框图/草图\r
\r
**输入方式**：\r
- 图片文件路径（如 `/path/to/design.png`）\r
- 支持格式：PNG, JPG, JPEG, GIF, WebP, BMP\r
\r
**基础分析功能**（当前实现）：\r
```bash\r
# 使用 image-prototype-analyzer.py 进行基础分析\r
python scripts/image-prototype-analyzer.py design.png markdown\r
```\r
\r
**提取内容**：\r
- 图片尺寸和比例\r
- 主要颜色方案（提取前10种主色）\r
- 布局区域推断（基于尺寸比例）\r
  - 头部区域（顶部10-15%）\r
  - 侧边栏区域（左侧15-20%）\r
  - 主内容区\r
  - 底部区域\r
- 颜色统计和配色建议\r
\r
**增强分析方案**（可选，需配置API密钥）：\r
\r
> ⚠️ **数据传输警告**：使用视觉增强分析会将图片数据发送到外部API服务。请确认图片不含敏感信息后再启用。\r
\r
图片原型分析建议配合视觉大模型获得精确结果。需设置环境变量 `ANTHROPIC_API_KEY`：\r
\r
```python\r
# 使用Claude Vision进行精确UI识别\r
# 注意：此功能会将图片发送到Anthropic服务器\r
import anthropic\r
import base64\r
import os\r
\r
# 需要设置环境变量: ANTHROPIC_API_KEY\r
api_key = os.environ.get('ANTHROPIC_API_KEY')\r
if not api_key:\r
    print("警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析")\r
    print("将使用本地基础分析（颜色提取、布局推断）")\r
\r
client = anthropic.Anthropic(api_key=api_key)\r
\r
with open('design.png', 'rb') as f:\r
    image_data = base64.b64encode(f.read()).decode()\r
\r
response = client.messages.create(\r
    model='claude-3-opus-20240229',\r
    max_tokens=4096,\r
    messages=[{\r
        'role': 'user',\r
        'content': [\r
            {'type': 'image', 'source': {'type': 'base64', 'media_type': 'image/png', 'data': image_data}},\r
            {'type': 'text', 'text': '''分析这张UI设计稿，提取：\r
1. 页面布局结构（头部、侧边栏、主内容区、底部）\r
2. UI组件类型（按钮、输入框、表格、卡片等）\r
3. 交互元素（可点击、可输入）\r
4. 颜色方案（主色、辅助色、背景色）\r
5. 文本内容（标题、描述、按钮文案）\r
请以结构化格式输出。'''}\r
        ]\r
    }]\r
)\r
```\r
\r
**视觉模型分析输出**：\r
- 精确的UI元素位置和类型\r
- 完整的文本内容提取\r
- 交互元素识别（按钮、链接、输入框）\r
- 样式细节（颜色、字体大小推断）\r
- 组件层级关系\r
\r
#### D. XMind原型解析\r
\r
**适用场景**：\r
- 产品功能脑图\r
- 信息架构图\r
- 业务流程图\r
- 需求结构图\r
\r
**输入方式**：\r
- XMind文件路径（如 `/path/to/product.xmind`）\r
- 支持XMind 8和XMind 2020+格式\r
\r
**技术原理**：\r
XMind文件是zip压缩包，包含：\r
- `content.json` (XMind 2020+格式)\r
- `content.xml` (XMind 8格式)\r
- `manifest.xml` (元数据)\r
\r
```bash\r
# 使用 xmind-analyzer.py 进行分析\r
python scripts/xmind-analyzer.py product.xmind markdown\r
```\r
\r
**提取内容**：\r
- 思维导图完整结构\r
- 所有节点标题和层级\r
- 节点属性（颜色、图标、备注）\r
- 统计信息（节点总数、最大层级）\r
\r
**智能推断功能**：\r
基于节点标题关键词，自动推断：\r
1. **功能模块**（包含"模块"、"管理"、"系统"）\r
2. **页面结构**（包含"页面"、"列表"、"详情"）\r
3. **功能点**（包含"功能"、"操作"、"按钮"）\r
\r
**输出内容**：\r
- YAML格式的思维导图结构\r
- 功能模块清单（含子节点）\r
- 页面结构建议（含功能点）\r
- 前端路由规划建议\r
- 后端API接口规划\r
- 数据库表设计建议\r
\r
### 第2步：功能拆解与职责划分\r
将解析出的元素拆解为细小功能单元，并判断实现方式：\r
\r
#### 前端职责（纯前端实现）\r
- 页面布局和样式\r
- 交互效果（悬停、点击动画）\r
- 本地数据操作（排序、过滤、分页）\r
- 表单验证（前端规则）\r
- 组件内部状态管理\r
\r
#### 后端职责（需要接口支持）\r
- 数据持久化（增删改查）\r
- 业务逻辑处理（计算、验证、流程）\r
- 外部系统集成（支付、消息、文件）\r
- 权限控制和安全性\r
- 批量操作和复杂查询\r
\r
**判断标准**：\r
- 是否需要保存数据？ → 后端接口\r
- 是否需要复杂计算？ → 后端接口  \r
- 是否涉及用户权限？ → 后端接口\r
- 是否只是UI交互？ → 前端实现\r
\r
### 第3步：技术文档生成\r
生成结构化技术规范文档，包含：\r
\r
#### 3.1 系统概览\r
- 原型来源和类型\r
- 分析时间和版本\r
- 总体功能描述\r
\r
#### 3.2 页面结构分析\r
- 布局分解（头部、侧边栏、主内容区、底部）\r
- 功能模块清单（每个模块的位置、内容、交互）\r
\r
#### 3.3 前端实现方案\r
- 页面路由规划\r
- 组件清单（名称、props、状态、交互逻辑）\r
- 样式方案（CSS框架、设计系统）\r
- 交互细节（按钮点击、表单提交、数据展示）\r
\r
#### 3.4 后端实现方案\r
- API接口设计（路由、HTTP方法、参数、返回值）\r
- 业务逻辑伪代码（关键算法、流程控制）\r
- 数据库表设计（表名、字段、类型、关系）\r
- 第三方服务集成\r
\r
#### 3.5 开发注意事项\r
- 技术栈建议\r
- 特殊依赖说明\r
- 性能和安全考虑\r
- 测试要点\r
\r
## 🛠️ 工具和资源\r
\r
### 内置脚本\r
- `scripts/url-prototype-analyzer.sh` - URL原型解析主脚本\r
- `scripts/html-extractor.py` - HTML内容提取工具入口（调用 html_extractor 包）\r
- `scripts/html_extractor/` - HTML解析核心模块包\r
  - `config.py` - UI框架配置\r
  - `models.py` - 数据结构定义\r
  - `detector.py` - UI框架检测器\r
  - `extractor.py` - 核心解析器\r
  - `utils.py` - 辅助函数\r
  - `main.py` - 入口函数\r
- `scripts/spec-generator.py` - 技术文档生成工具\r
- `scripts/image-prototype-analyzer.py` - 图片原型分析工具\r
- `scripts/xmind-analyzer.py` - XMind文件分析工具\r
- `scripts/run_analysis.sh` - 综合分析入口脚本\r
\r
### 参考模板\r
- `references/template-spec.md` - 技术规范文档模板\r
- `references/component-catalog.md` - 前端组件目录\r
- `references/api-design.md` - API设计规范\r
\r
### 输出示例\r
- `assets/sample-output/` - 示例输出文档\r
\r
## 📝 使用方法\r
\r
### 基本调用\r
当用户提供原型URL或本地HTML文件路径时，直接使用本技能：\r
\r
```bash\r
# 技能会自动识别输入类型并启动相应流程\r
```\r
\r
### 手动触发\r
如果需要特定分析模式，可指定参数：\r
\r
```bash\r
# URL原型分析\r
分析这个Figma原型：https://www.figma.com/file/xxx\r
\r
# 本地HTML文件分析\r
分析这个HTML原型文件：/path/to/prototype.html\r
分析这个HTML原型文件：[直接粘贴HTML内容]\r
\r
# 图片原型分析\r
分析这张设计稿截图：/path/to/design.png\r
# 配合视觉模型增强分析：\r
使用Claude Vision分析这张设计稿：/path/to/design.png\r
\r
# XMind原型分析\r
分析这个产品脑图：/path/to/product.xmind\r
分析这个信息架构：/path/to/architecture.xmind\r
```\r
\r
### 输入类型自动识别\r
技能会根据输入内容自动判断解析方式：\r
\r
| 输入内容 | 识别方式 | 解析方式 |\r
|---------|---------|---------|\r
| `https://...` | 以http/https开头 | URL原型解析 |\r
| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\r
| `\x3C!DOCTYPE html>...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\r
| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\r
| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\r
\r
### 分析助手（手上有钱）执行流程\r
作为AI助手，当用户提供本地HTML文件时，按照以下流程执行：\r
\r
1. **读取文件**：使用 `read` 工具读取HTML文件内容\r
2. **解析结构**：手动解析HTML的DOM结构，提取：\r
   - 页面布局框架\r
   - 导航和菜单\r
   - 功能模块卡片\r
   - 表单和交互元素\r
   - 数据表格\r
   - CSS设计系统（变量、颜色、字体）\r
3. **生成文档**：按照技能模板生成技术规范文档\r
4. **输出结果**：保存到指定路径或直接展示\r
\r
## 📊 输出文档标准\r
\r
### 前端组件描述标准\r
对于每个页面组件，需要描述：\r
\r
1. **组件位置**：在页面哪个区域（头部/侧边栏/主内容区）\r
2. **内容来源**：\r
   - 静态内容（写死在代码中）\r
   - 动态内容（从后端API获取）\r
   - 用户输入（表单字段）\r
3. **展示样式**：\r
   - 布局方式（Flex/Grid/绝对定位）\r
   - 尺寸和间距\r
   - 颜色和字体\r
   - 响应式行为\r
4. **交互逻辑**：\r
   - 按钮点击触发什么操作\r
   - 按钮名称和文案\r
   - 操作类型（导航/提交/删除/等）\r
   - 成功/失败反馈方式\r
\r
### 后端接口描述标准\r
对于每个API接口，需要描述：\r
\r
1. **路由信息**：\r
   - HTTP方法（GET/POST/PUT/DELETE）\r
   - URL路径（/api/resource/:id）\r
   - 接口名称和用途\r
2. **参数说明**：\r
   - 路径参数（:id）\r
   - 查询参数（?page=1&size=10）\r
   - 请求体（JSON结构）\r
   - 必填/选填字段\r
3. **返回值**：\r
   - 成功响应（HTTP 200，JSON结构）\r
   - 错误响应（HTTP 4xx/5xx，错误信息）\r
   - 分页结构（如果需要）\r
4. **业务逻辑伪代码**：\r
   - 主要处理步骤\r
   - 数据库操作（查询/插入/更新/删除）\r
   - 业务规则验证\r
   - 异常处理逻辑\r
\r
### 数据库设计标准\r
对于每个业务实体，需要设计：\r
\r
1. **表结构**：\r
   - 表名（复数形式，小写加下划线）\r
   - 主键字段（id，自增或UUID）\r
   - 业务字段（名称、类型、长度、默认值）\r
   - 索引字段（查询优化）\r
2. **表关系**：\r
   - 一对一关系\r
   - 一对多关系（外键）\r
   - 多对多关系（中间表）\r
3. **约束条件**：\r
   - 唯一约束\r
   - 非空约束\r
   - 外键约束\r
\r
## 🔍 示例场景\r
\r
### 示例1：用户管理系统原型\r
**输入**：Figma用户管理后台URL\r
\r
**输出包含**：\r
- 前端：用户列表组件、用户表单组件、权限选择组件\r
- 后端：用户CRUD接口、权限验证接口、搜索接口\r
- 数据库：users表、roles表、user_roles关联表\r
\r
### 示例2：电商商品页面原型  \r
**输入**：墨刀电商商品详情页URL\r
\r
**输出包含**：\r
- 前端：商品展示组件、购物车组件、评价组件\r
- 后端：商品查询接口、购物车接口、下单接口\r
- 数据库：products表、categories表、orders表\r
\r
## ⚠️ 安全注意事项\r
\r
> 🔴 **高风险操作警告**：请在理解以下风险后使用本技能\r
\r
### 1. 网络访问与SSRF风险\r
- **支持内网URL**：本技能可以访问内网链接（如 `http://internal.company.com/prototype`）\r
- **SSRF风险**：恶意或错误的URL可能触发服务器端请求伪造，访问未预期的内部资源\r
- **安全建议**：\r
  - 仅提供您有权访问且明确需要分析的原型链接\r
  - 不要提供包含敏感数据的内部系统URL（如管理后台、API端点）\r
  - 在受控网络环境中分析内部原型\r
\r
### 2. 外部API数据传输\r
- **视觉增强分析**：使用Claude Vision需要将图片发送到Anthropic服务器\r
- **数据泄露风险**：设计稿可能包含敏感业务信息、知识产权内容\r
- **安全建议**：\r
  - 启用视觉增强前确认图片不含敏感信息\r
  - 不设置 `ANTHROPIC_API_KEY` 时使用本地基础分析（不传输数据）\r
  - 对敏感设计稿仅使用本地分析功能\r
\r
### 3. 本地文件访问\r
- **读取范围**：技能会读取您指定的本地文件路径\r
- **误操作风险**：错误路径可能读取非预期的敏感文件\r
- **安全建议**：\r
  - 确保文件路径准确指向目标原型文件\r
  - 不要将技能指向包含密钥、配置文件的目录\r
\r
### 4. 首次使用安全检查\r
- **脚本审查**：首次使用前建议检查 `scripts/` 目录下的Python脚本\r
- **隔离测试**：建议在虚拟环境或沙箱中首次运行\r
- **依赖安装**：在虚拟环境中安装requirements.txt的依赖\r
\r
## ⚠️ 技术限制\r
\r
1. **访问限制**：\r
   - 需要登录的工具（如私有Figma项目）可能无法访问完整内容\r
   - 动态加载的内容可能无法完全捕获\r
   - 复杂交互可能难以通过静态分析完全理解\r
\r
2. **输出质量**：\r
   - 文档详细程度直接影响生成系统的准确性\r
   - 需要人工复核关键业务逻辑\r
   - 建议与产品经理确认技术方案\r
\r
## 📈 后续扩展计划\r
\r
1. **V2.1**：集成视觉模型API，实现图片原型精确UI识别\r
2. **V2.2**：支持多原型合并分析，生成完整系统架构\r
3. **V2.3**：添加Figma API直接解析（需授权）\r
4. **V3.0**：自动化测试用例生成，一键生成可运行原型代码\r
\r
## 📞 支持与反馈\r
\r
- **GitHub仓库**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\r
- **问题反馈**: 通过GitHub Issues提交\r
- **功能建议**: 通过GitHub Discussions讨论\r
\r
## 📄 许可证\r
\r
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\r
\r
## 🤝 贡献\r
\r
欢迎提交Issue和Pull Request！\r
\r
1. Fork 本仓库\r
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\r
3. 提交更改 (`git commit -m 'Add some amazing feature'`)\r
4. 推送到分支 (`git push origin feature/amazing-feature`)\r
5. 开启 Pull Request\r
\r
---\r
\r
*最后更新：2026-04-29*\r
*作者：杰哥*\r
\r
**更新日志**：\r
- v2.9.2 (2026-04-29): 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）、补充作者信息和项目链接，响应平台安全审查建议\r
- v2.9.1 (2026-04-29): 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）\r
- v2.9.0 (2026-04-29): 完全通用化重构：移除所有硬编码的业务专有名词（如"采购"、"供应商"、"质检"、"入库"等），使skill可适配任何业务领域（仓储、ERP、WMS、CMS等）。动态生成路由、API接口、数据库表，不依赖特定业务词汇映射。\r
- v2.8.0 (2026-04-29): 增强技术实现推断能力：智能路由解析（处理javascript:void(0)等特殊值）、增强按钮位置识别（多层级父元素检查）、业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义\r
- v2.7.0 (2026-04-29): 模块化重构：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块），提高可维护性\r
- v2.6.0 (2026-04-24): 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息、状态筛选Tab、进度条组件\r
- v2.5.0 (2026-04-24): 补充缺失解析模块：消息通知卡片、采购员进度卡片、页面标签栏、用户信息区、子标签切换；优化表格层级识别和数据类型推断\r
- v2.4.0 (2026-04-24): 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮、多页面视图\r
- v2.3.0 (2026-04-23): 内网URL默认阻止需用户确认、禁止自动pip安装、外部API默认禁用\r
- v2.2.0 (2026-04-23): 实施命令注入防护、URL/路径输入验证\r
- v2.1.0 (2026-04-23): 增加安全警告、声明可选API凭证\r
- v2.0.0 (2026-04-22): 新增图片/XMind分析功能\r
- v1.0.0 (2026-04-21): 初始版本\r