原型 → 开发交付物生成器

工作流程

当你收到一个原型导出目录（或单个 HTML 文件）时，按以下步骤执行：

1. 识别原型类型

脚本会自动识别工具类型，但你也应判断用户提供的是：

• 完整导出目录：包含多个 HTML 文件和资源子目录
• 单个 HTML 文件：独立的原型页面文件
• Schema JSON 文件（蓝湖）：结构化图层树数据

支持的工具及其导出特征：

2. 解析原型结构

使用 scripts/parse_axure.py 脚本解析原型（脚本名沿用旧名，但已支持多工具）。调用命令（在技能目录下执行）：

# 完整目录解析，输出可读摘要（自动识别工具类型）
python3 scripts/parse_axure.py <原型目录路径>

# 输出 JSON 摘要（推荐，便于后续程序化处理）
python3 scripts/parse_axure.py <原型目录路径> --json-summary

# 输出完整 JSON（含所有文本/控件/交互）
python3 scripts/parse_axure.py <原型目录路径> --json

# 单个 HTML 文件
python3 scripts/parse_axure.py <页面.html>

脚本会自动识别工具类型并分发到对应解析器，返回结构化数据（含 tool 字段标注工具类型、页面树、每页的文本内容、控件类型、交互事件）。拿到 JSON 后用 json.loads 解析，按页面遍历生成交付物。工具识别顺序、各工具解析深度对比与 Axure 数据键详见 解析引擎说明.md（调试降级行为或扩展工具支持时读取）。

该脚本会：

对于 Axure 完整目录：

• 从 data/document.js 中提取页面树结构（页面名称、URL、层级关系）
• 从每个页面的 HTML 中提取所有可见文本内容（标题、标签、表格数据、按钮文字等）
• 从 data.js 中提取控件类型信息（矩形、按钮、输入框、表格、树、图片等）
• 从 data.js 中提取交互事件（onClick 跳转、弹出等）
• 页面分类（page_category）：见下方"页面分类与截图拼接识别"
• 截图拼接识别（is_screenshot_composite）：见下方
• 筛选区域识别（filter_area）：见下方
• 严格字段提取（strict_fields / ambiguous_fields）：见下方

对于墨刀离线包：

• 扫描所有 HTML 文件提取页面文本和控件注释
• 从 index.html 中提取页面链接列表构建扁平页面清单
• 不含交互事件提取（墨刀离线包格式不固定）

对于 MasterGo 离线标注：

• 定位含 PAGED_FRAMES 的数据 JS 文件
• 提取画板名称和 ID 列表
• 若无数据文件，退化为通用 HTML 扫描

对于蓝湖 Schema JSON：

• 查找 .schema.json 文件，解析图层树
• 递归遍历提取 lanhutext 类型节点的文本内容
• 提取所有图层类型（lanhutext/lanhuimage/lanhubutton 等）
• 若无 schema 文件，退化为通用 HTML 扫描

对于单个 HTML 文件（任何工具）：

• 解析 HTML 中的 DOM 结构，提取所有 <span> 标签内的文本内容
• 提取控件注释（<!-- Unnamed (控件类型) -->）识别控件类型
• 提取表格结构、按钮、链接等

对于未知工具的 HTML 目录：

• 退化为通用 HTML 扫描，提取所有 HTML 文件中的文本和控件注释
• 在输出中标注"工具类型未识别，输出为降级版本"

2.1 页面分类与截图拼接识别

每页解析结果新增以下字段，所有交付物（PRD/功能清单/数据字典等）都应基于这些字段生成：

页面分类标签（page_category）：

截图拼接识别（is_screenshot_composite）：

满足以下任一条件即判定为截图拼接：

1. 多张大图：≥2 张宽度 ≥600px 的 <img>
2. 多张 background-image 切片：≥2 个不同 url 的 background-image
3. 文本极少 + 图片多：文本 ≤5 条且 <img> ≥3 张
4. 单张超大图 + 几乎无文本：一张宽度 ≥800px 的图且文本 ≤5 条

判定为截图拼接的页面，在 PRD 上必须有明确标识（见 PRD-template.md 的"截图拼接页标识"章节）。

严格字段提取（strict_fields / ambiguous_fields）：

字段说明严格基于页面出现的内容输出，禁止凭空臆想。规则：

1. 字段标签必须出现在页面 texts 中（不臆想）——以"："或":"结尾，或匹配常见字段后缀（名称/编号/状态/时间/日期/类型/分类/部门/创建时间/更新时间/手机/邮箱/地区/标签/级别 等）
2. 字段类型从对应控件推断：标签后紧跟"请选择"则下拉，"请输入"则输入框，"请选择日期"则日期选择器；若控件类型对应不上，标"待确认"
3. 必填/默认值/校验规则：原型未明确显示时，一律标"待确认"，不得凭空臆想
4. 模糊字段归入 ambiguous_fields：标签后无对应控件文本，或类型完全无法推断；必须先与用户确认后再写入 PRD/数据字典
5. 英文字段名（name）：不臆想，留空待用户/后端确认

每个 strict_fields 条目结构：

{
  "name": "",                  // 英文字段名，不臆想，留空待确认
  "label": "客户名称：",       // 字段标签，来源于页面文本
  "type": "输入框(input)",     // 控件类型，从页面控件推断
  "required": "待确认",        // 必填，原型未明确 * 必填符号时标"待确认"
  "default_value": "待确认",   // 默认值，原型未显示时标"待确认"
  "note": "字段标签来源于页面文本，类型/必填/默认值需对照原型确认",
  "source": "page_text"
}

筛选区域识别（filter_area，管理后台常见）：

后台管理页面若有筛选区域，识别并输出筛选字段说明。识别逻辑：

1. 文本中含筛选关键词（筛选/过滤/查询条件/搜索条件/查询/检索/filter/search/query）且同时存在下拉框/输入框/日期控件
2. 或文本中含筛选操作按钮（查询/搜索/重置/清空/search/filter/reset/clear）且同时存在下拉框/输入框/日期控件

筛选字段提取（filter_area.filter_fields）：从 texts 中按出现顺序提取，匹配常见筛选字段名（名称/编号/状态/时间/日期/类型/分类/部门/创建时间/更新时间/手机/邮箱/地区/标签/级别）的优先纳入。每个筛选字段含：label（筛选条件名称）/control_type（控件类型，待确认时不臆想）/required/default_value/note。

筛选操作按钮（filter_area.filter_actions）：从 texts 中提取查询/搜索/重置/清空等按钮文字。

3. 让用户选择要纳入输出材料的页面

解析完成后先不要直接全量生成，而是让用户选择"要为哪些页面生成交付物"。原型里常常混入封面页、版本记录页、废弃草稿页，让用户先圈定范围能大幅减少后续交付物的噪声。

3.1 展示页面清单

用 --list-pages 输出带序号的页面清单（含每页文本/控件/交互数量），让用户一眼看到可选范围：

python3 scripts/parse_axure.py <原型目录> --list-pages

页面较多时（如超过 15 页），可改用 --list-pages-group 按文件名前缀分组展示，便于用户按模块快速圈选：

python3 scripts/parse_axure.py <原型目录> --list-pages-group

输出示例：

📁 项目: netxalerp
📄 识别到的页面总数: 18

可选择的页面清单（序号为选择时使用的编号）：
    1. 概述       [文本×12, 控件×8, 交互×0]   overview.html
    2. 业务       [文本×5, 控件×3, 交互×2]     business.html
    ...

同时把解析摘要（页面树、页面内容摘要）一并呈现给用户，便于他判断哪些页面值得纳入。

3.2 询问选择并等待确认

向用户提供选择语法后暂停等待用户回复：

> 我已解析该原型，共识别到 18 个页面。请选择要生成交付物的页面范围：
>
> 选择语法（逗号分隔，可混合）：
>
> - all — 全部页面
> - 1,3,5 — 按序号多选（1-based）
> - 2-6 — 按序号范围（闭区间）
> - 概述,业务.html — 按页面名（带不带 .html 均可）
> - 1,3-5,概述 — 混合
>
> 直接回复即可，例如：1,3-7 或 all。

3.3 按选择重新解析（过滤）

拿到用户选择后，用 --pages <spec> 重新跑解析脚本，得到只含选中页面的 JSON：

# 仅解析用户选中的页面，输出过滤后的 JSON
python3 scripts/parse_axure.py <原型目录> --pages "1,3-7" --json > prototype.json

脚本支持的 --pages 语法与 3.2 展示给用户的完全一致：

过滤后 JSON 的 pages 数组只保留选中页面，total_pages / selected_page_count / selected_indices 字段同步更新；page_tree 保留完整层级结构供交付物引用父子关系。后续步骤（询问交付物、生成交付物）都基于这份过滤后的 JSON 执行。

3.4 选择环节的边界处理

• 用户尚未指定页面 → 必须先展示清单并询问，不得默认 all 直接进入交付物生成
• 用户回复 all 或"全部" → 跳过过滤，按全量 JSON 继续
• 用户输入无法识别的项 → 脚本会打印 警告: 以下选择项无法识别，已忽略：xxx 到 stderr，识别成功部分仍生效；若全部失败脚本以 exit code 2 退出，此时向用户重新解释语法并请求再次输入
• 单个 HTML 文件（非目录）→ 无页面可选，直接跳到步骤 4
• MasterGo / 蓝湖画板级原型 → 画板即页面，按相同语法选择
• 用户选完后又想改 → 允许他在交付物生成前再次给出新的选择字符串，重新跑 3.3

4. 询问用户要生成的交付物

基于步骤 3 过滤后的页面集合，将解析结果整理后呈现给用户，展示后暂停等待用户确认范围再继续，然后询问：

> 我已经解析了该原型，共识别到 X 个页面，结构如下：
> [页面树]
> 主要页面内容摘要：...
>
> 请选择要生成的交付物（可多选）：
>
> 1. 📄 PRD（产品需求文档） - Markdown，7 章节（文档信息/产品概述/页面结构/功能需求/非功能需求/页面流程图/附录）
> 2. 📋 功能清单 - xlsx，8 列（功能编号/模块/功能名称/功能描述/优先级/所属页面/关联功能/备注），按页面分组
> 3. 🧪 测试用例 - xlsx，8 列（用例编号/模块/功能点/用例标题/前置条件/测试步骤/预期结果/优先级），按模块分组
> 4. 📊 数据字典 - md，9 列字段表（字段名/中文名/类型/长度/必填/默认值/说明/所属页面/备注），按页面分组
> 5. 🔗 页面跳转关系图 - md，含 Mermaid 流程图 + 跳转详表 + 孤立页面清单
> 6. 🎯 用户故事（User Story） - md，含角色定义 + 故事地图 + 详表 + 验收标准汇总
> 7. 📅 开发计划 - md，含模块拆分表 + 4 里程碑 + 风险项
> 8. 💡 自定义组合 - 你指定格式

何时跳过询问直接生成（避免让用户重复已经说清楚的事）：

• 用户 prompt 中已明确指定要生成什么（如"生成 PRD"、"做一份功能清单和测试用例"、"分析页面"对应单页分析报告）→ 跳过询问，直接生成指定的交付物，但仍先展示解析摘要让用户确认范围
• 用户指定了输出格式（如"xlsx 格式"、"Markdown"、"Word"）→ 按指定格式输出，不问格式
• 用户只说"分析这个原型"但未指定交付物 → 必须询问要生成什么
• 用户说"生成所有交付物"或"能生成的都生成" → 跳过询问，生成全部7类
• 解析后发现的页面数/结构与用户描述严重不符（如用户说"3个页面"实际解析到20个）→ 暂停，先告知差异让用户确认，再继续生成

这样做的原因：用户已经明确说出来的需求，再问一遍是冗余且让用户觉得"没被听见"；但模糊的指令必须澄清，避免做错方向。

> 注意：步骤 3 已让用户圈定页面范围，步骤 4 的"让用户确认范围"指的是确认交付物清单与选中页面集合是否符合预期，而非再次选择页面。

5. 生成交付物

根据用户选择，生成对应的交付物。每种交付物有独立的格式规范文件（位于 references/，给模型读取的列定义/便签纳入规则）+ 独立生成脚本（位于 scripts/，可执行生成真正可打开的 xlsx/md）：

工作分工：

• references/ 规范文档（.md）— 给模型读取：列定义、工作表/文档结构、便签纳入规则、优先级评定、使用要点。决定"生成什么样子"
• scripts/ 生成脚本（.py）— 给机器执行：可独立跑，按规范产出真正可打开的 .xlsx（openpyxl 生 Excel 二进制）/ .md。决定"怎么生成"

为什么不把代码塞进 reference：skill 规范里 references/ 放给模型读的文档、scripts/ 放可执行代码——职责分离便于独立调试、复用、升级。reference 只描述"应该生成什么"，脚本负责"真正生成出来"。

典型生成流程（以功能清单为例）：

# 1. 先用 parse_axure.py 拿到解析 JSON
python3 scripts/parse_axure.py <原型目录> --json > prototype.json

# 2. 跑对应生成脚本（脚本会读 reference 规范推断逻辑）
python3 scripts/generate_feature_list.py prototype.json output/功能清单.xlsx

生成脚本接受统一参数：<解析JSON> [输出路径]，默认输出到 CWD。脚本内的推断函数（如 infer_features_for_page）实现了对应 reference 规范中描述的列定义、分组、便签纳入规则——若需调整推断逻辑，直接编辑脚本对应函数即可。

各交付物生成要点（列结构见步骤 4 交付物菜单；便签纳入规则见「便签/备注说明的解析与纳入」章节；详细规范以对应 reference 文件为准，生成前必须读取）：

• PRD 由模型 inline 生成（结构灵活），其余 6 类交付物优先跑生成脚本产出文件
• PRD 的功能需求中，每个功能项在"功能描述"后按 references/PRD-template.md 增加「截图」与「相关页面」小节：「相关页面」嵌入该功能所属页面的原型截图（截图导出到 output/screenshots/，PRD 中用相对路径引用），「截图」放用户另行提供的现状界面截图（如有）；无对应素材的功能项省略小节
• 截图询问（生成 PRD 前必做，不得静默省略截图小节）：写 PRD 前向用户确认两件事——
  1. 「相关页面」原型截图：Axure 等工具导出自带页面图片时，直接复制/导出到 output/screenshots/；原型为纯 HTML（页面无 <img> 素材）时，询问"是否将各页渲染为全页截图嵌入"（可用 Playwright/Chrome headless 渲染），用户同意后渲染导出，拒绝则省略「相关页面」小节
  2. 「截图」现状截图：询问用户是否有现状界面截图需要纳入；有则请其提供文件路径并复制到 output/screenshots/，无则全部功能项省略「截图」小节
• 测试用例的用例编号全局递增，不按模块重置
• 用户要求的输出格式与默认格式不同时（如测试用例要 md 而非 xlsx），仍按对应 reference 的列结构 inline 生成，不改变列定义

6. 输出文件管理

• 所有输出存放在原型目录下的 output/ 文件夹中
• 按交付物类型单文件命名：PRD.md、功能清单.xlsx、测试用例.xlsx、数据字典.md、页面跳转关系图.md、用户故事.md、开发计划.md
• xlsx 单文件多 sheet：功能清单/测试用例各自独立 xlsx，主表 + 副表「说明」共 2 张 sheet；不合并不同交付物到同一 xlsx
• md 交付物各自独立单文件，不合并
• 如果用户指定了输出位置，则保存到指定位置

7. 可选流程：调用 requirement-analysis 进行需求澄清与分析

触发时机：在步骤 6 完成交付物输出归档（所有文件已写入 output/）之后。

前置条件（任一满足即可询问）：

• 已生成 PRD（output/PRD.md）
• 已生成功能清单（output/功能清单.xlsx）
• 已生成用户故事（output/用户故事.md）

> 若本次仅生成了页面跳转关系图/数据字典/开发计划等非"需求主体"交付物，仍可询问，但向用户说明"需求澄清对 PRD/功能清单类交付物收益更大"。

7.1 询问用户是否调用

生成交付物后，主动询问用户是否需要调用 requirement-analysis skill 进行需求澄清和分析：

> 📦 交付物已生成至 output/ 目录。
>
> 原型解析生成的 PRD/功能清单基于原型可见内容推断，可能存在：
>
> - 🔴 模糊描述（如"管理用户信息"无具体操作）
> - 🟡 边界不明（如"导出数据"未说明格式/范围）
> - 🟢 缺失上下文（如审批流程未定义审批角色）
>
> 是否调用 requirement-analysis skill 进行需求澄清与分析？
>
> - A. ✅ 调用 — 启动 requirement-analysis skill，对已生成的 PRD/功能清单进行需求澄清、冲突检测、INVEST 质量评估
> - B. ⏭️ 跳过 — 当前交付物已满足需求，流程结束

7.2 调用 requirement-analysis skill

用户选择 A 后，调用 requirement-analysis skill，并传入以下上下文：

传入参数：

• 数据来源：本次原型解析生成的交付物文件路径
• output/PRD.md（主输入，PRD 是 requirement-analysis 的核心处理对象）
• output/功能清单.xlsx（若已生成，作为补充输入）
• output/用户故事.md（若已生成，作为补充输入）
• output/_prototype.json（解析 JSON，供 requirement-analysis 读取原始页面数据）
• 原型信息：原型目录路径、工具类型、页面数、页面树
• 本次生成范围：用户在步骤 3 选中的页面集合

调用方式：

使用 use_skill 工具调用 requirement-analysis skill，arguments 中传入上述上下文。调用后由 requirement-analysis skill 接管流程，执行其 8 阶段工作流（文档扫描 → 解析 → 功能提取 → 智能整合 → 需求澄清 → 用户确认 → 生成 PRD → 可选推送）。

调用示例：

use_skill:
  name: requirement-analysis
  arguments: |
    数据来源：本次原型解析生成的交付物
    原型目录：/Users/wikky/Documents/Axure/HTML/v2.2.3x 线索自动分配
    工具类型：axure
    页面数：8
    已生成交付物：
      - output/PRD.md（主输入）
      - output/用户故事.md（补充输入）
      - output/_prototype.json（解析 JSON）
    请对已生成的 PRD 进行需求澄清、冲突检测与 INVEST 质量评估。

7.3 requirement-analysis skill 接管后的行为

requirement-analysis skill 被调用后，将基于传入的 PRD/功能清单执行：

1. 阶段 1-2 文档扫描与解析：读取 output/PRD.md、output/功能清单.xlsx 等，解析为统一中间格式
2. 阶段 3 功能提取：从 PRD 的功能清单章节提取原子级功能
3. 阶段 4 智能整合：语义去重、信息补充、冲突检测
4. 阶段 4.5 整合摘要确认：展示整合结果供用户确认
5. 阶段 5 需求澄清：检测模糊描述、边界不明、歧义表述等问题，按严重程度分级，逐批与用户交互澄清
6. 阶段 6 用户确认：确认所有 🔴 严重矛盾已解决
7. 阶段 7 生成 PRD：生成最终的标准化 PRD.md（覆盖或增量更新 output/PRD.md）
8. 阶段 8 PRD 推送（可选）：询问用户是否推送到飞书/Git/FTP 等

输出物：

• output/PRD.md — 经需求澄清与质量评估后的最终 PRD（覆盖原型解析生成的初版 PRD）
• output/需求澄清报告.md — requirement-analysis 生成的澄清报告（若该 skill 支持）
• output/质量评估报告.md — INVEST 六维质量评估报告（若该 skill 支持）

7.4 边界处理

• 用户选择 B（跳过） → 流程直接结束，不调用 requirement-analysis
• requirement-analysis skill 未安装 → 检测 ~/.atomcode/skills/requirement-analysis/ 是否存在；不存在则告知用户"requirement-analysis skill 未安装，跳过需求澄清，可手动安装后重试"，流程结束
• requirement-analysis skill 调用失败 → 捕获错误，告知用户"需求澄清调用失败：[错误信息]，当前交付物保留在 output/ 目录"，流程结束
• 用户在步骤 4 已明确说"调用 requirement-analysis"或"进行需求澄清" → 跳过 7.1 询问，直接执行 7.2 调用
• 用户在步骤 4 已明确说"不需要需求澄清" → 跳过整个步骤 7
• PRD 未生成但功能清单已生成 → 仍可调用，requirement-analysis 会以功能清单为主输入反推 PRD
• 本次仅生成了页面跳转关系图 → 询问时说明"需求澄清对 PRD/功能清单类交付物收益更大，当前仅有页面跳转关系图，建议先在步骤 4 选择生成 PRD"

7.5 流程总览

步骤 1-2: 识别原型类型 → 解析原型结构
    ↓
步骤 3: 用户选择页面范围
    ↓
步骤 4: 用户选择交付物类型
    ↓
步骤 5: 生成交付物 → 写入 output/
    ↓
步骤 6: 输出文件管理（output/ 归档）
    ↓
步骤 7: 询问是否调用 requirement-analysis 进行需求澄清
    ├── A. 调用 → use_skill("requirement-analysis", ...) → requirement-analysis 接管 8 阶段流程
    └── B. 跳过 → 流程结束

便签/备注说明的解析与纳入

已支持：解析脚本 parse_axure.py 在解析每页 HTML 时已提取便签（Axure 中以 id 后缀 _ann 的 div 标识）和矩形内备注说明（以"备注"字样开头的矩形/文本段落），归入每页的 notes 字段。

所有交付物都应纳入 notes 字段，具体纳入方式见各 reference 文件的"便签/备注说明的纳入"章节：

• PRD：补入功能需求的"备注说明"项和附录的便签汇总
• 功能清单：补为独立功能条目或备注列
• 测试用例：补为业务规则用例或前置条件
• 数据字典：优先填入"说明"和"备注"列
• 页面跳转关系图：补入跳转条件与备注列
• 用户故事：补为独立故事、验收标准或角色识别依据
• 开发计划：影响工时估算与风险评估

在每份交付物末尾的"数据来源说明"章节标注：便签/矩形内备注说明已纳入。

注意事项

1. 原型完整性检查：解析前用 os.path.exists 检查 data/document.js 是否存在，判断是完整目录还是单个文件
2. 中文优先：默认生成中文文档，如果用户要求英文则切换
3. 内容推断：当原型中的文本不足以明确功能时，基于页面结构和控件类型做合理推断，并在输出中标注"（推测）"
4. 交互识别：从 data.js 中提取 onClick 等交互事件，用于生成页面跳转图和用户操作流程
5. xlsx 输出：使用 openpyxl 库生成 Excel 文件，确保格式工整
6. Word 输出：如果用户要求 Word 格式的 PRD，使用 python-docx 库生成
7. 不要过度脑补：原型中未体现的内容不要编造，标注为"待补充"
8. 输出前确认：生成前先展示解析摘要，让用户确认后再生成完整文档

边界条件与异常处理

出现异常按以下 fallback 处理，不要静默失败。原则：即使原型不完整，也要交付一份降级版文档，而非直接报错退出。

1. 路径不存在 → 报告用户 + glob 父目录搜候选让用户选 + 不自行假设路径
2. parse_axure.py 报错 → 单独跑一次捕获 stderr 展示 + 降级为直接 read_file HTML 提取 <span> 文本和控件注释（标注"降级输出，未含交互/树结构"）+ 降级也失败则终止告知
3. files/<页面名>/data.js 缺失 → 仅 HTML 解析，标注"本页无 data.js，交互事件未提取"
4. 页面 HTML 无 <span> 文本 → 标注"本页无可见文本，可能为纯图片/流程图页面"，保留条目功能描述写"（待补充）"
5. document.js 解析后页面数为 0 或树构建失败 → 降级扁平扫描 glob *.html（排除 index/start），标注"层级关系待补充"
6. _output/ 不可写 → 尝试用户指定路径 → CWD → /tmp/，告知实际保存路径