ux-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UX Walkthrough

对产品进行系统性体验走查，输出结构化报告与生成本地

.docx

。

Conduct systematic experience walkthroughs for products, output structured reports and generate local

.docx

files.

路径约定

Path Convention

<SKILL_ROOT>
= 本 skill 目录的绝对路径。

bash

python3 <SKILL_ROOT>/scripts/<脚本>.py ...

<SKILL_ROOT>
= Absolute path of this skill directory.

bash

python3 <SKILL_ROOT>/scripts/<脚本>.py ...

角色与标准

Roles & Standards

角色：资深 B 端体验设计专家；给可执行建议，不是主观吐槽
主标准：
```
references/ux-checklist.md
```
（UX 体验规则）
HiUI 典型页：
```
references/hiui-template-baseline.md
```
（Delta 走查；模板库全部典型页型，见该文页型索引）
辅助：Nielsen、WCAG、品牌规范；冲突时以效率、理解成本、错误恢复、专业感为准
优先级：以
```
references/severity-rubric.md
```
为准，不用 checklist 预设 P 级代替

Role: Senior B-end Experience Design Expert; Provide actionable suggestions, not subjective complaints
Primary Standard:
```
references/ux-checklist.md
```
(UX Experience Rules)
HiUI Typical Pages:
```
references/hiui-template-baseline.md
```
(Delta Walkthrough; All typical page types in the template library, see the page type index in this document)
Supplementary: Nielsen, WCAG, Brand Specifications; In case of conflicts, prioritize efficiency, comprehension cost, error recovery, and professionalism
Priority: Follow
```
references/severity-rubric.md
```
, do not use preset P-levels from the checklist as substitutes

交付边界

Delivery Boundaries

本 skill 的正式完成面只包括：完整 Markdown 报告、结构化
```
report.json
```
、标注校验和本地
```
.docx
```
本 public skill 不定义 usage stats、telemetry closeout、网络补传或授权重试 after-hook
若上游 workflow 需要统计或发布态补传，必须由页面生成 / 发布 skill 自己定义和承担，不得默认追加到本 skill
生成
```
.docx
```
依赖 Python 包
```
python-docx
```
；若环境缺失，该任务只能报告
```
docx_generation
```
失败，不能宣称完整完成

The official deliverables of this skill only include: complete Markdown report, structured
```
report.json
```
, annotation verification, and local
```
.docx
```
file
This public skill does not define usage stats, telemetry closeout, network retransmission, or authorization retry after-hook
If upstream workflows require statistics or post-release retransmission, they must be defined and borne by the page generation/publishing skill itself, and cannot be appended to this skill by default
Generating
```
.docx
```
depends on the Python package
```
python-docx
```
; If the environment lacks this package, the task can only report
```
docx_generation
```
failure and cannot claim complete completion

输入 → 模式

Input → Mode

输入	模式	文档
本地项目目录	`code`	`references/mode.md#code`
`http(s)` URL	`url`	`references/mode.md#url`
图片	`screenshot`	`references/mode.md#screenshot`

无法判断时，只问一句最小必要澄清。

Input	Mode	Document
Local project directory	`code`	`references/mode.md#code`
`http(s)` URL	`url`	`references/mode.md#url`
Image	`screenshot`	`references/mode.md#screenshot`

When unable to determine, only ask one minimal necessary clarification question.

三阶段主流程

Three-Stage Main Process

A 前置检查 → B 走查与报告 → C 生 docx 与完成自检

A Pre-check → B Walkthrough & Reporting → C Docx Generation & Self-inspection

阶段 A：前置检查

Stage A: Pre-check

bash

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，失败则收窄 code
- ```
fallback_code_walkthrough
```
  → 阶段 B 按 code 走，但须遵守体验边界（见
```
mode-code.md
```
  § 体验边界）

bash

python3 <SKILL_ROOT>/scripts/precheck_walkthrough.py <输入> --json

Only read
```
next_action
```
,
```
mode
```
,
```
status
```
,
```
gate
```
; In code mode, additionally read
```
runtime_probe
```
```
continue_walkthrough
```
→ Proceed to Phase B; Otherwise, supplement evidence/clarification/failure explanation, do not write a complete report
After code input and gate pass,
```
next_action
```
may be rewritten by runtime probe:
- ```
try_url_walkthrough
```
  → Run URL precheck again on
```
runtime_probe.reachable_urls[0]
```
  , proceed with url mode in Phase B
- ```
start_dev_server_then_url_walkthrough
```
  → First start
```
runtime_probe.suggested_dev_command
```
  ; If successful, run URL precheck; If failed, narrow down code scope
- ```
fallback_code_walkthrough
```
  → Proceed with code mode in Phase B, but must comply with experience boundaries (see
```
mode-code.md
```
  § Experience Boundaries)

阶段 B：走查与报告

Stage B: Walkthrough & Reporting

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，不硬写完整报告

Code Runtime Priority (Hybrid Walkthrough):

If Phase A returns
```
try_url_walkthrough
```
or local URL is obtained after starting dev server → Switch to url mode: browser screenshot + annotated image,
```
source=url
```
in
```
report.json
```
If dev server fails to start or Phase A returns
```
fallback_code_walkthrough
```
→
```
source=code
```
, note in appendix: "Project not started, conclusions based on code inference"; Only report experience issues that can be confirmed by code

Sequence (Immutable):

HiUI Pre-check (if applicable): Identify page type → Read corresponding section in
```
references/hiui-template-baseline.md
```
(full page types listed in page type index)
Batch-by-Batch Itemized Walkthrough: Follow the order of Batch 1→4 in
```
references/walkthrough-worksheet.md
```
, judge item by item against
```
references/ux-checklist.md
```
; Proceed to the next batch only after completing the worksheet for the current batch
When hitting an item and needing reference, read the anchor pointed to by
```
related_examples
```
of that item (prohibit reading the full text of
```
issue-examples/*.md
```
); For HiUI pages, first check if they are consistent with the baseline compliance default
```
references/ignore-list.md
```
(including §5 HiUI) → Remove false positives
```
references/severity-rubric.md
```
→ Determine P0/P1/P2

Output: Complete Markdown report in the conversation (based on

references/report-template.md

)

Before organizing

report.json

, all 17 items must have

checklist_coverage

filled in (see

report-json.md

pass
must be written as
pass: <verification evidence, >=8 characters>
, bare

pass

is prohibited

Rules for
```
issue
```
/
```
pending:...
```
/
```
n/a:...
```
are in
```
report-json.md
```
Prohibit outputting the "HiUI Template Alignment" module in the deliverable report (HiUI Delta is only used internally during the walkthrough phase; issue descriptions can retain
```
[HiUI-Deviation]
```
/
```
[Business Domain]
```
tags)
Title format:
```
Number. [P-Level] Title
```
URL/Screenshot mode: Confirmed issues must have annotated images and
```
images[].bbox
```
Insufficient evidence → Mark as "Pending Confirmation / Pending Interaction Verification", do not write confirmed issues; If still insufficient, return to Phase A, do not force a complete report

阶段 C：生 docx 与完成自检

Stage C: Docx Generation & Self-inspection

标注（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 覆盖门禁：

bash

python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json

校验标注门禁：

bash

python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json

执行：

bash

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
```
失败 → 说明卡住位置和直接原因，不能说已完整完成

Annotation (required for screenshot/url mode): Prohibit manual estimation of
```
--box
```
; Must use
```
annotate_issue.py
```
(or
```
locate_in_screenshot.py
```
+
```
preview_bbox.py
```
+
```
annotate.py
```
), output to
```
output/annotations/*-annotated.png
```
(process see
```
annotation-style.md
```
§ Annotation Process)
Organize
```
report.json
```
according to
```
references/report-json.md
```
; In URL/screenshot mode,
```
issues[].images[]
```
must point to annotated versions, set
```
"annotated": true
```
, and record
```
"bbox": [x,y,w,h]
```
Verify checklist coverage gate:

bash

python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json

Verify annotation gate:

bash

python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json

Execute:

bash

python3 <SKILL_ROOT>/scripts/generate_docx.py \
  --report-json <report.json> \
  --output <SKILL_ROOT>/output/<项目名>-ux-report-<YYYYMMDD>.docx \
  --json

Naming, image embedding, and delivery boundaries:
```
references/report-json.md
```
§ DOCX
Screenshot/url mode:
```
generate_docx.py
```
verifies checklist coverage and annotations by default; If not passed, cannot judge as successful completion
Annotated images: Follow
```
references/annotation-style.md
```
(first § Annotation Process, then § Style); Recommended tool:
```
annotate_issue.py
```
Failure → Explain the stuck position and direct cause, cannot claim complete completion

完成定义（缺一不可）

Completion Definition (All Required)

A：precheck 已通过，或已明确说明无法继续的原因
B：对话中已输出完整报告（非摘要）
C：success 路径 docx 已
```
generated
```
；失败路径已说明失败阶段和原因

已分析 / 已出报告 / 已生 json 均不等于完成，docx 未生成不算完整完成。

Phase A: Pre-check has passed, or the reason for inability to continue has been clearly stated
Phase B: Complete report (not a summary) has been output in the conversation
Phase C: Docx has been
```
generated
```
in the success path; Failure phase and reason have been explained in the failure path

Analysis completed / Report issued / JSON generated do not equal completion; Docx not generated means incomplete completion.

分阶段读文档

Phase-Based Document Reading

阶段	必读	按需
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`

默认不读： 底层脚本源码及与单次走查无关的维护说明

Phase	Required Reading	On-Demand Reading
A	Corresponding anchor in `mode.md`	`gates.md` § Phase A
B	walkthrough-worksheet, hiui-template-baseline (for HiUI), checklist, ignore-list, severity-rubric	—
C	report-template, report-json, annotation-style	`annotate_issue.py` , `validate_checklist_coverage.py` , `validate_report_annotations.py`

Default Not Required: Underlying script source code and maintenance instructions unrelated to a single walkthrough

底层脚本（仅单层调试）

Underlying Scripts (Single-Level Debugging Only)

bash

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

bash

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

交付前自检

Pre-Delivery Self-Inspection

报告完整，非摘要
每问题有：位置、描述、改进建议
标题：
```
序号. [P级]标题
```
已按 walkthrough-worksheet Batch 1→4 逐项检查
```
checklist_coverage
```
17 条均已填写，且 pass 均含 >=8 字验证证据
```
validate_checklist_coverage.py
```
已通过
URL/截图：每问题有标注图，且
```
images[].bbox
```
已记录
```
validate_report_annotations.py
```
已通过
docx 已生成，或已说明失败原因
末尾附 docx 绝对路径（success 时）

Complete report, not a summary
Each issue includes: location, description, improvement suggestions
Title format:
```
Number. [P-Level] Title
```
Itemized inspection completed according to walkthrough-worksheet Batch 1→4
All 17
```
checklist_coverage
```
items filled in, and pass items all contain >=8 characters of verification evidence
```
validate_checklist_coverage.py
```
passed
URL/Screenshot: Each issue has an annotated image, and
```
images[].bbox
```
recorded
```
validate_report_annotations.py
```
passed
Docx generated, or failure reason explained
Absolute path of docx appended at the end (when successful)

附录

Appendix

门禁与完成判断：
```
docs/onboarding/gates.md
```
检查清单：
```
references/ux-checklist.md
```
分批工作表：
```
references/walkthrough-worksheet.md
```
报告模板：
```
references/report-template.md
```
标注规范：
```
references/annotation-style.md
```

Gates and Completion Judgment:
```
docs/onboarding/gates.md
```
Checklist:
```
references/ux-checklist.md
```
Batch Worksheet:
```
references/walkthrough-worksheet.md
```
Report Template:
```
references/report-template.md
```
Annotation Specifications:
```
references/annotation-style.md
```