别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)
本技能将产品原型转换为详细的技术实现规范文档，帮助开发团队（尤其是大模型）准确理解需求并生成高相似度的系统。
⚠️ 安全警告（重要）
使用本技能前请阅读以下安全注意事项：
-
内网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%以上的系统。
🔧 当前版本能力
✅ 已支持
- 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内容提取工具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：自动化测试用例生成，一键生成可运行原型代码
📞 支持与反馈
📄 许可证
本项目采用 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-23
版本：2.3.0 (安全增强版)
作者：杰哥
更新日志：
- 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): 初始版本
