安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install product-ux-audit
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 product-ux-audit。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

产品 UX 审计是 Openclaw Skills 的工作流，用于评估特定产品功能或用户流程在实际中的表现。它会绘制路由和用户旅程，检查业务规则中的缺漏和矛盾，依据 Nielsen 启发式原则评估界面，并查找死胡同、恢复机制缺失和未处理的边缘情况。
此技能刻意采用只读方式：不会修改项目文件，并会将带时间戳的报告写入 _Reports 输出文件夹。每项发现都必须以具体文件、行、屏幕或代码片段为依据，并关联到用户或业务影响。其分阶段、限定范围的方法让 Openclaw Skills 能够提供可执行的产品评审，同时避免将 UX 分析与安全审计或一般代码质量评审混为一谈。

应用场景

从产品和可用性角度评估某项功能是否已准备好投入生产。
找出用户流程中缺失、相互矛盾或执行不一致的业务规则。
评审用户旅程的顺畅路径和异常路径，包括错误、取消和恢复。
识别明确模块中的 UX 阻力、不可访问的控件、死胡同和边缘情况。
评估 monorepo 中由产品需求驱动的模块化情况和跨功能依赖。
针对指定流程生成有文档记录的审计报告，而不更改代码库源文件。

工作原理

定义范围： 每次调用只指定一个功能、模块或用户流程。若未指定范围进行产品审计，应选择关键的面向用户流程，而不是一次审计整个代码库。
建立上下文： 记录代码库的 Git 提交、分支和工作区状态；梳理相关路由、屏幕、API、角色和外部依赖。
阅读实现： 在得出结论前检查范围内的路由、页面、组件和服务。使用快速搜索定位未完成逻辑、错误处理、加载状态和验证逻辑。
绘制流程： 记录从入口到完成及退出的流程，包括用户画像或角色以及涉及的文件。
执行审计阶段： 评审产品逻辑、Nielsen 启发式原则及相关无障碍性、阻力和边缘情况，以及产品驱动的架构。仅在用户要求或提供所需上下文时创建可选的旅程图或基准比较。
记录基于证据的发现： 包含具体引用、观察到的行为、预期行为或标准、用户影响，以及切实可行的修复方向。根据用户或业务影响分配严重级别。
复核严重发现： 对照代码重新检查 Critical 和 High 级发现；若可用，则使用新的 subagent，否则进行全新的人工复核。
交付报告： 验证各阶段报告，生成主摘要和汇总后的最终报告，并将所有输出保存在带时间戳的报告文件夹中。

配置指南

针对特定产品流程、功能或模块调用此技能，例如 /product-ux-audit，并说明任何限制或可选评审目标。每次调用都应限定范围；将宽泛的审计拆分为单独的流程级任务。
此技能会在用户桌面的 _Reports 目录下解析带时间戳的输出文件夹，并在审查代码前记录 Git 上下文。它对项目源代码采用只读方式：不要运行迁移、修改性脚本、重构或会更改代码库的命令。报告只写入指定的输出文件夹。

示例：发现路由和 API（根据代码库调整路径）

rg --files apps/web/src/app apps/api/src --glob "page.tsx" --glob "route.ts" --glob "*.ts"

定位路由处理程序和页面组件

rg "app\.(get|post|put|delete|patch)|fastify\.(get|post|put|delete|patch)|export default function" --type ts --type tsx -l

为报告标题收集代码库上下文

git rev-parse --short HEAD
git branch --show-current
git status --short

数据架构

此技能会在带时间戳的 Reports 文件夹中生成 Markdown 审计文档；不会生成或修改应用数据。报告包含代码库上下文（路径、Git HEAD、分支）、范围和有证据支持的发现。各阶段输出组织如下：
文档 内容
audit_0_flow-map.md 流程、步骤、路由/文件、角色和外部依赖
audit_1_product-logic.md 业务规则缺漏、矛盾和流程不一致之处
audit_2_heuristics.md 各屏幕的启发式评分和备注，以及最薄弱的启发式原则
audit_3_friction-edgecases.md 按优先级排列的阻力、边缘情况矩阵，以及顺畅/异常路径
audit_4_journey-map.md 可选的用户画像旅程、阶段、接触点、痛点和指标
audit_5_architecture.md 功能到模块的映射、跨模块依赖和产品驱动的建议
audit_6_benchmark.md 可选：与用户提供的竞争对手或标准进行比较
audit_master_summary.md 严重程度汇总、关键发现和建议的修复顺序
FINAL_product-audit.md 汇总报告，首先列出主摘要，并将各阶段报告分开以便追溯
适用阶段中的发现采用一致的结构：位置和严重程度；观察到的行为；预期行为或标准；用户影响；以及修复方向。严重程度分为 Critical、High、Medium、Low 和 Note，依据用户或业务影响判定。每项发现都需要具体的代码或屏幕引用；没有证据的一般性建议不予纳入。

高级特性

严格的范围约束：
要求每次只审查一个流程或模块，防止审计范围悄然扩展至整个代码库。
多阶段工作流：
分开处理流程映射、产品逻辑、启发式评估、边缘情况、可选旅程研究和模块化评审。
Nielsen 启发式评分：
根据 10 项可用性启发式原则评估屏幕，并额外考量与上下文相关的无障碍性和认知负荷。
流程专属技术检查：
包括 SSE 重新连接和状态过时行为、Electron IPC 故障处理、OS 休眠后的恢复，以及相关的
contextIsolation
检查。
证据和严重程度标准：
将发现关联到具体实现引用，并依据对用户和业务的影响确定优先级，而非依据可利用性或代码风格。
复核环节：
若可用，则使用新的 subagent 重新验证 Critical 和 High 级发现；否则进行全新的人工代码审查。
可选扩展：
为主要流程添加旅程图，或与用户提供的竞争对手和标准进行基准比较；不会臆造竞争对手，也不会擅自获取外部数据。
可追溯报告：
验证各阶段交付物，避免跨阶段重复发现，并将带时间戳的阶段报告汇编为一份汇总最终文档。

name: product-ux-audit description: Read-only, multi-phase audit of product logic, UX heuristics, user journeys, edge cases, and architecture modularity. Use this skill when the user invokes /product-ux-audit, asks for a "product audit", "UX audit", "product logic audit", "usability check", a heuristic evaluation, a user-journey review, or an edge-case / happy-path-vs-exception-path analysis. Complements forensic-audit (security/architecture) — this skill focuses on product logic, UX quality, and user-facing flow consistency, not vulnerabilities. MANDATORY: never run on an entire repo in a single pass — scope each invocation to one user flow / module (use a task list to split large codebases).

Skill: product-ux-audit

Trigger

Use this skill when the user asks for:

a product logic audit ("product logic audit", "business logic audit")
a UX/heuristic evaluation ("UX audit", "usability review")
user journey mapping or happy-path vs exception-path analysis
edge-case / boundary-condition discovery for a flow or feature
a codebase modularization / separation-of-concerns review (product-driven, not security)
a lightweight "is this feature production-ready from a product POV" check

STRICT READ-ONLY: Never modify, refactor, or create files inside the project repository. Only write reports to the _Reports output folder. Do not run mutating commands, migrations, or scripts.

For security/auth/crypto/data-integrity audits, use forensic-audit instead. For pure code-quality/refactor reviews, use code-review or simplify.

Mission

Produce a structured, evidence-based audit of how a product (or a specific feature/flow) behaves from the user's and business's perspective — independent of whether the code is "secure" or "clean". Goals:

Map the actual user flow(s) as implemented (not as documented).
Find business-logic gaps, contradictions, and missing rules.
Evaluate UX against Nielsen's heuristics.
Find dead ends, friction points, and missing recovery/error paths.
Enumerate edge cases and boundary conditions per flow.
Compare happy path vs exception paths for completeness.
Check architecture for product-feature modularity (each feature owns its slice).
Optionally benchmark against competitors/industry standards if the user supplies that context.

Pre-flight

Scope: Ask (or infer from the request) which feature/flow/area is in scope. If unscoped and the user says "audit the product", scope to the most user-facing flows (auth, onboarding, core feature loop, billing/queue if present) — don't try to cover the entire app in one pass. For this monorepo, also record which app(s) each in-scope flow belongs to (apps/web client-facing, apps/desktop client, apps/desktop-operator, apps/desktop-admin). Carry this per-flow app/persona label through every phase — e.g. don't apply Phase 2's elderly-client accessibility lens (#11) to an apps/desktop-operator/apps/desktop-admin screen unless evidence suggests the same users use it.
Resolve output path: $outDir = "$env:USERPROFILE\Desktop_Reports\product-audit_$(Get-Date -Format 'yyyy-MM-dd_HHmm')". Create it; abort if it fails.
Repo context (embed in every report header): git rev-parse --short HEAD, git branch --show-current, git status --short.
Directory/route snapshot for the in-scope area — orient before opining:

# Next.js 14 App Router pages/routes + Fastify API routes

rg --files apps/web/src/app apps/api/src --glob "page.tsx" --glob "route.ts" --glob "*.ts"
rg "app.(get|post|put|delete|patch)|fastify.(get|post|put|delete|patch)|export default function" --type ts --type tsx -l

# Electron IPC bridges & SSE streams (apps/desktop*, apps/api)

rg "ipcMain.handle|ipcRenderer.invoke|reply.raw.write|text/event-stream" --type ts -l

Adjust globs to the project's actual structure (check apps/*/src layout first if unfamiliar). Use Glob to check whether each in-scope page.tsx has sibling loading.tsx/error.tsx/not-found.tsx (App Router convention for loading/error UI) — note absences for Phase 3.
Quick signal scan — fast candidates for Phases 1/3 before deep reading:

# Stubs / unfinished logic

rg "TODO|FIXME|not implemented|HACK" --type ts --type tsx

# Silent failure / swallowed errors

rg "catch\s*(.)\s{\s*}" --type ts --type tsx

# Where error/loading states exist (and by omission, where they don't)

rg "isLoading|isPending|isError|skeleton|Spinner" --type tsx -l
rg "catch|onError|throw new Error" --type ts --type tsx -l

# Duplicated validation (cross-check FE vs BE in Phase 5)

rg ".min(|.max(|.required(|z.string()" --type ts --type tsx -l

Read before writing: read the relevant routes/pages/components/services for the scoped flow(s) before forming any opinion. Don't audit from memory or assumptions.

Report Header Template

# [Phase Title]

Date: YYYY-MM-DD HH:MM Repo: [repo root path] Git HEAD: [short hash] ([branch]) Scope: [feature/flow(s) under audit]

Finding Format (Phases 1-3, 5)
[file:line or screen/step] SEVERITY — short title

Observed: what the code/UI actually does (cite file:line) Expected/Standard: what product logic, heuristic, or convention implies User impact: confusion, data loss, dead end, inconsistent state, etc. Fix direction: concrete next step (no code unless trivial)

Severity: CRITICAL / HIGH / MEDIUM / LOW / NOTE. Severity reflects user/business impact, not exploitability.

Actionable vs Not Actionable

A finding is actionable only if it has a concrete file:line / screen reference AND a specific, real consequence for a user or the business. Generic UX best-practice statements without a concrete anchor in this codebase are not findings — drop them or fold them into context for an actionable one.

Actionable: [CheckoutForm.tsx:142] MEDIUM — submit button stays enabled during pending request, allowing duplicate charges on double-click
Not actionable: "Consider adding more whitespace for better visual hierarchy" (no file:line, no concrete user consequence)

Avoid

Do not propose a redesign, new design system, or new framework/library — that's out of scope for an audit.
Do not invent personas, competitors, or KPIs not evidenced by the code, copy, or supplied by the user.
Do not pad phases with generic UX textbook statements ("ensure consistency", "improve feedback") — every claim needs a concrete anchor.
Do not re-score a heuristic based on assumed intent ("they probably meant to add a spinner") — score what's actually there.

Phase Discipline

Fresh pass per phase — don't rely on prior-phase memory; re-read relevant files for each phase's specific lens.
Cross-phase dedup — Phase 1 (logic) and Phase 3 (edge cases) often surface the same spot (e.g. "empty input not validated"). Ownership:
Phase 1 owns findings about missing/contradictory business rules (what should happen, per spec/business sense).
Phase 3 owns findings about unhandled input/state permutations (what happens when it's not handled, regardless of whether a rule exists).

If a finding fits both, record it fully in its owning phase and reference it by file:line from the other ("see Phase 1 finding at X — not re-litigated here").

Sequential phases — Phase N+1 starts only after Phase N's deliverable is written and verified (see below).
Verify write: after each phase, confirm the deliverable file exists and contains at least one substantive finding/table row (not just the header template). If a phase genuinely has zero findings, write an explicit "No findings — checked: [what was checked]" line rather than leaving a near-empty file.
Phase 0 — Flow Map & Scope

Role: Senior Product Strategist + Solution Architect.

Enumerate the screens/routes/API endpoints that make up each in-scope flow, end to end (entry → completion → all exits).
Note personas/roles involved (e.g. CLIENT, OPERATOR, ADMIN) and which steps each can reach.
Note external systems touched (payment, queue, notifications, telephony, etc.) per flow.

Deliverable: $outDir\audit_0_flow-map.md — table of flows, steps, files, roles, external deps.

Phase 1 — Product Logic Audit

Role: Senior Product Strategist (prompt source: "Product Logic Audit").

For each in-scope flow, check:

Business logic gaps: rules implied by the UI/copy but not enforced in code (or vice versa).
Contradictory rules: two code paths or screens that disagree on the same rule (e.g. a limit enforced on one endpoint but not another, a status that two places compute differently).
User flow inconsistencies: same action behaves differently depending on entry point.
Missing edge cases: see Phase 3 for the dedicated pass, but flag any glaring ones here.

Deliverable: $outDir\audit_1_product-logic.md — findings in standard format, severity = Critical/High/Medium/Low.

Phase 2 — Heuristic Evaluation (Nielsen's 10 + Accessibility)

Role: UX Expert.

For each in-scope screen/flow, score 1-10 against each heuristic and give 1-2 concrete improvements where score < 8:

Visibility of system status

Match between system and real world

User control and freedom

Consistency and standards

Error prevention

Recognition rather than recall

Flexibility and efficiency of use

Aesthetic and minimalist design

Help users recognize, diagnose, and recover from errors

Help and documentation

Accessibility & cognitive load for the actual user base — when the in-scope flow is client/family-facing (lower tech literacy, older users): are tap/click targets large enough, is contrast/font size sufficient (check Tailwind classes like text-xs, arbitrary text-[Npx]), and are destructive/irreversible actions (cancel session, delete account, end call) clearly confirmed rather than a single accidental tap? Skip this heuristic for operator/admin-only screens unless evidence suggests the same concern applies.

Base scores on actual component code/markup (loading states, error messages, confirmation dialogs, copy, Tailwind classes), not assumptions.

Deliverable: $outDir\audit_2_heuristics.md — per-screen table (heuristic × score × note) + summary of weakest 3 heuristics across the product.

Phase 3 — Friction, Dead Ends & Edge Cases

Role: UX Forensic Analyst + QA Edge-Case Hunter.

For each in-scope flow:

Dead ends: states with no visible next action (e.g. error screen with no retry/back, empty list with no CTA).
Friction points: steps with unnecessary required fields, re-authentication, redundant confirmations, or unclear copy.
Missing recovery paths: what happens on network failure, validation failure, partial completion, session expiry mid-flow?
Offline & reconnection UX (SSE/Electron-specific): for flows backed by SSE (e.g. queue-sse.ts), does the UI show a reconnecting/stale state when the connection drops, or does it silently show outdated data? For Electron apps, what happens when the app wakes from OS sleep — does it refetch/reconnect, or sit on a dead connection? Check whether the SSE handler registers reply.raw.on('close', ...) (or equivalent) to detect client disconnects, and whether the client's EventSource/SSE consumer has an onerror/reconnect path.
IPC failure handling (Electron-specific): when an ipcRenderer.invoke call fails or times out (e.g. RustDesk launch failure), does the renderer surface an error state, or does the UI hang in isLoading/spinner indefinitely? Also check the relevant BrowserWindow's webPreferences for contextIsolation: true — if it's missing or false, flag it (note in summary that depth coverage belongs to forensic-audit, but a flow-breaking IPC bridge issue is in scope here).
Edge cases / boundary conditions: empty inputs, max-length inputs, zero/negative/huge numbers, concurrent submissions, duplicate actions (double-click submit), timezone/locale edges, permission changes mid-session.
Happy path vs exception paths: for each flow, list the happy path steps, then for each step list the exception paths and whether the UI/code handles them (cite file:line) or not.

Deliverable: $outDir\audit_3_friction-edgecases.md — pain-point map (prioritized) + edge-case matrix (scenario | handled? | file:line | severity) + happy/unhappy path table.

Phase 4 — User Journey Map (optional, on request or for the primary flow)

Role: UX Researcher.

For the primary persona/goal in scope, produce:

Journey overview: persona, goal, timeline/stages.
Stage breakdown: actions, touchpoints (UI/API), thoughts/feelings (inferred from friction found in Phase 3), pain points, opportunities.
Touchpoint analysis: channels (web/desktop/email/push), effectiveness, gaps.
Metrics: what KPIs/events would reveal whether this journey works (note if instrumentation exists or is missing).

Deliverable: $outDir\audit_4_journey-map.md.

Phase 5 — Architecture & Modularization (product-driven)

Role: Solution Architect (prompt source: "Architecture Review" + "Modularization").

This is not a security pass (see forensic-audit for that). Focus on whether the codebase structure matches product structure:

Does each in-scope feature live in a cohesive module/folder, or is its logic scattered across unrelated directories?
Cross-feature dependencies: does feature A reach directly into feature B's internals (services, types, DB models) instead of a shared/owned interface?
Monorepo boundaries: are shared types, Prisma schema, and utilities isolated in @imma-help/db / @imma-help/desktop-shared and consumed via those packages — or does apps/web, apps/api, or an apps/desktop* app reach into another app's src directly, or duplicate DB/schema logic locally instead of importing the shared package?
UI/logic/data separation: are business rules duplicated between frontend validation and backend validation (and do they agree — cross-check with Phase 1)?
Single points of failure for the in-scope flow (one service/util that, if it fails, breaks multiple unrelated features)?
Scalability/perf notes only as they affect product behavior (e.g. "list grows unbounded → UI will eventually paginate badly") — defer deep perf/security findings to forensic-audit.

Deliverable: $outDir\audit_5_architecture.md — module map (table: feature → primary files → cross-deps) + refactoring suggestions with rationale. Optional Mermaid diagram of flow/module boundaries.

Phase 6 — Competitive / Industry Benchmark (optional)

Only run if the user provides competitor names, target industry, or specific standards to check against — do not invent competitors or fetch external data without being asked.

Map in-scope features to the named competitors' known capabilities (as supplied by the user).
Identify gaps and differentiators.

If the user asks for positioning copy, write a short (3-paragraph) draft.

Deliverable: $outDir\audit_6_benchmark.md.

Challenge Pass (before Final Deliverable)

Before writing the master summary, validate every CRITICAL/HIGH finding from Phases 1, 2, 3, and 5.

If subagents are available: spawn one fresh Agent (subagent_type "claude", no shared context, read-only) per batch of findings. Give it only the finding text + repo path — not your reasoning. Ask it to verify each finding against the actual code/UI and answer for each: Confirmed / Overstated (downgrade severity) / Not an issue (drop), with a one-line reason.
If subagents are not available: re-read the cited file:line yourself with fresh eyes and apply the same three-way verdict.

For Phase 2 (heuristic scores) specifically, challenge any score that seems to assume unverified intent — re-derive the score strictly from what's in the code/markup.

Apply the verdicts (drop/downgrade/keep) before building the rollup table. Note in the master summary how many findings were dropped/downgraded and why — this is a signal of audit quality, not a failure.

Final Deliverable

Write $outDir\audit_master_summary.md:

Severity rollup table across Phases 1, 3, 5 (Critical/High/Medium/Low/Note counts)
Top 5 product-logic issues (Phase 1)
Weakest heuristics + worst screens (Phase 2)
Top 5 friction/dead-end fixes (Phase 3)
Architecture/modularity highlights (Phase 5)
Recommended fix order (quick wins first, then structural)

Consolidated FINAL report

After all phase files and the master summary are written, concatenate everything into one combined file: $outDir\FINAL_product-audit_$(Get-Date -Format 'yyyy-MM-dd_HHmm').md.

Order: audit_master_summary.md first, then audit_0_flow-map.md, audit_1_product-logic.md, audit_2_heuristics.md, audit_3_friction-edgecases.md, audit_4_journey-map.md (if produced), audit_5_architecture.md, audit_6_benchmark.md (if produced) — separate each section with a --- and a # heading so the source phase stays traceable. This single file is the primary artifact to hand to the user; the per-phase files remain for traceability/reference.

Constraints

READ-ONLY on project source. Zero writes inside the repository — reports only go to $outDir under _Reports.
Evidence-only: every finding cites a file:line, screen name, or concrete code excerpt. No speculation framed as fact.
Timestamped output — never overwrite previous runs.
Scope discipline: don't silently expand scope to the whole app; if you think broader scope is warranted, say so in the summary instead of just doing it.
No overlap duplication with forensic-audit: if a security/data-integrity issue surfaces, note it briefly with a pointer ("see forensic-audit for security depth") rather than producing a full security finding here.
Severity = user/business impact, not exploitability or code elegance.

Forensic Audit

Yeelight WiFi LAN Control