| name | ux-walkthrough |
| version | 1.0.2 |
| description | 体验走查 skill。适用于代码库、URL、截图三种输入，输出结构化体验问题报告，并同步生成本地 docx 报告。触发词：体验走查、UX review、交互走查、界面审查、体验问题。 |
UX Walkthrough
对产品进行系统性体验走查，输出结构化报告与生成本地 .docx。
路径约定
<SKILL_ROOT> = 本 skill 目录的绝对路径。
python3 <SKILL_ROOT>/scripts/<脚本>.py ...
角色与标准
- 角色：资深 B 端体验设计专家；给可执行建议，不是主观吐槽
- 主标准：
references/ux-checklist.md（UX 体验规则）
- HiUI 典型页：
references/hiui-template-baseline.md（Delta 走查；模板库全部典型页型，见该文页型索引）
- 辅助：Nielsen、WCAG、品牌规范；冲突时以效率、理解成本、错误恢复、专业感为准
- 优先级：以
references/severity-rubric.md 为准，不用 checklist 预设 P 级代替
交付边界
- 本 skill 的正式完成面只包括：完整 Markdown 报告、结构化
report.json、标注校验和本地 .docx
- 本 public skill 不定义 usage stats、telemetry closeout、网络补传或授权重试 after-hook
- 若上游 workflow 需要统计或发布态补传，必须由页面生成 / 发布 skill 自己定义和承担，不得默认追加到本 skill
- 生成
.docx 依赖 Python 包 python-docx；若环境缺失，该任务只能报告 docx_generation 失败，不能宣称完整完成
输入 → 模式
| 输入 | 模式 | 文档 |
|---|
| 本地项目目录 | code | references/mode.md#code |
http(s) URL | url | references/mode.md#url |
| 图片 | screenshot | references/mode.md#screenshot |
无法判断时，只问一句最小必要澄清。
三阶段主流程
A 前置检查 → B 走查与报告 → C 生 docx 与完成自检
阶段 A：前置检查
python3 <SKILL_ROOT>/scripts/precheck_walkthrough.py <输入> --json
- 只读
next_action、mode、status、gate；code 模式额外读 runtime_probe
continue_walkthrough → 进入 B；否则补证据 / 澄清 / 失败说明，不写完整报告- code 输入且 gate 通过后，
next_action 可能被 runtime 探测改写：
try_url_walkthrough → 对 runtime_probe.reachable_urls[0] 再跑 URL precheck，阶段 B 按 url 走start_dev_server_then_url_walkthrough → 先启动 runtime_probe.suggested_dev_command；成功则 URL precheck，失败则收窄 codefallback_code_walkthrough → 阶段 B 按 code 走，但须遵守体验边界（见 mode-code.md § 体验边界）
阶段 B：走查与报告
code 运行时优先（混合走查）：
- 若 A 返回
try_url_walkthrough 或启动 dev 后拿到本地 URL → 切换 url 模式：浏览器截图 + 标注图，report.json 的 source=url
- 若 dev 启动失败或 A 返回
fallback_code_walkthrough → source=code，附录注明「未启动项目，结论基于代码推断」；只强报 code 可确定的体验问题
顺序（不可变）：
- HiUI 前置（若适用）：识别页型 → 读
references/hiui-template-baseline.md 对应节（页型索引列全量页型）
- 分批逐项走查：按
references/walkthrough-worksheet.md 的 Batch 1→4 顺序，逐条对照 references/ux-checklist.md 判断；每批填完工作表再进下一批
- 命中条目且需参考时，读该条
related_examples 指向的锚点（禁止通读 issue-examples/*.md 全文）；HiUI 页先问是否与 baseline 合规默认一致
references/ignore-list.md（含 §5 HiUI）→ 去掉误报references/severity-rubric.md → 定 P0/P1/P2
输出： 对话中完整 Markdown 报告（references/report-template.md）
整理 report.json 前，必须为 全部 17 条 填写 checklist_coverage（见 report-json.md）：
-
pass 必须写 pass: <验证证据，>=8 字>，禁止裸 pass
-
issue / pending:... / n/a:... 规则见 report-json.md
-
禁止在交付报告中输出「HiUI 模板对齐」模块（HiUI Delta 仅走查阶段内部使用；issue 描述可保留 [HiUI-偏离] / [业务域] 标签）
-
标题格式：序号. [P级]标题
-
URL/截图模式：确定 issue 须有标注图与 images[].bbox
-
证据不足 → 标「待确认 / 待交互验证」，不写确定问题；仍不足则回到阶段 A，不硬写完整报告
阶段 C：生 docx 与完成自检
- 标注（screenshot / url 必做）：禁止手估
--box；须用 annotate_issue.py（或 locate_in_screenshot.py + preview_bbox.py + annotate.py），输出到 output/annotations/*-annotated.png（流程见 annotation-style.md § 标注流程）
- 按
references/report-json.md 整理 report.json；URL/截图模式的 issues[].images[] 须指向标注版、设 "annotated": true，并记录 "bbox": [x,y,w,h]
- 校验 checklist 覆盖门禁：
python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json
- 校验标注门禁：
python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json
- 执行：
python3 <SKILL_ROOT>/scripts/generate_docx.py \
--report-json <report.json> \
--output <SKILL_ROOT>/output/<项目名>-ux-report-<YYYYMMDD>.docx \
--json
- 命名、嵌图与交付边界：
references/report-json.md § DOCX
- screenshot / url：
generate_docx.py 默认校验 checklist 覆盖与标注；未通过则不得 success 完成判断
- 标注图：
references/annotation-style.md（先 § 标注流程，再 § 样式）；推荐工具：annotate_issue.py
- 失败 → 说明卡住位置和直接原因，不能说已完整完成
完成定义（缺一不可）
- A：precheck 已通过，或已明确说明无法继续的原因
- B：对话中已输出完整报告（非摘要）
- C：success 路径 docx 已
generated；失败路径已说明失败阶段和原因
已分析 / 已出报告 / 已生 json 均不等于完成，docx 未生成不算完整完成。
分阶段读文档
| 阶段 | 必读 | 按需 |
|---|
| A | mode.md 对应锚点 | gates.md § 阶段 A |
| B | walkthrough-worksheet, hiui-template-baseline（HiUI 时）, checklist, ignore-list, severity-rubric | — |
| C | report-template, report-json, annotation-style | annotate_issue.py, validate_checklist_coverage.py, validate_report_annotations.py |
默认不读： 底层脚本源码及与单次走查无关的维护说明
底层脚本（仅单层调试）
python3 <SKILL_ROOT>/scripts/detect_input_mode.py <输入> --json
python3 <SKILL_ROOT>/scripts/probe_dev_server.py <项目路径> --json
python3 <SKILL_ROOT>/scripts/check_evidence_gate.py --source <mode> ... --json
交付前自检
附录
- 门禁与完成判断：
docs/onboarding/gates.md
- 检查清单：
references/ux-checklist.md
- 分批工作表：
references/walkthrough-worksheet.md
- 报告模板：
references/report-template.md
- 标注规范：
references/annotation-style.md
