software-design-test 1.2.0

package/skills/observed-ui-test/REPORT-TEMPLATE.md

@@ -0,0 +1,111 @@
+# 观察式界面测试报告 / Observed UI Test Report
+
+> 复制本模板生成 `report.md`，中英对照。也可以让 `scripts/report.mjs build` 自动生成初稿。
+> Copy this template into `report.md`, bilingual. `scripts/report.mjs build` generates a draft.
+
+---
+
+## 0. 基本信息 / Basics
+
+| 项目 Item | 内容 Value |
+| --- | --- |
+| 被测应用 App | |
+| 版本 / 构建 Version / Build | |
+| 平台与环境 Platform & environment | macOS 版本 / Windows 版本 / iPhone 型号+iOS / iPad 型号+iPadOS；分辨率、缩放、深浅色 |
+| 输入设备 Input devices | 鼠标 / 触控板 / 键盘布局 / 手指 / 触控笔 / 外接键鼠 |
+| 测试日期 Date | |
+| 操作者 Operator | |
+| 观察者 Observer | |
+| 会话目录 Session dir | |
+
+## 1. 权限记录 / Permission record
+
+| 权限 Permission | 用户答复 Answer | 影响 Impact |
+| --- | --- | --- |
+| 鼠标操作 Mouse operation | yes / no | |
+| 键盘 Keyboard（级别 Mode） | L1 / L2 / L3 | |
+| 屏幕录制 Screen recording | yes / no / 含光标？ | |
+| 截屏 Screenshot | yes / no | |
+| 麦克风（口述解说）Microphone | yes / no | |
+| 系统捕获权限 OS capture permission | 已授予 / 未授予 | |
+| 数据边界 Data boundary | | |
+
+**未获得的权限与替代方案 / Permissions not granted and the substitute:**
+（没有替代方案就写"因此该项未覆盖" / if there is no substitute, write "therefore not covered"）
+
+## 2. 范围与覆盖 / Scope and coverage
+
+| 维度 Dimension | 计划 Planned | 实际 Actual | 未覆盖原因 Not covered because |
+| --- | --- | --- | --- |
+| 元素 Element | | | |
+| 模式 Mode（L1/L2/L3） | | | |
+| 平台 Platform | | | |
+| 用例 Case | | | |
+
+**明确不在本次范围内 / Explicitly out of scope:**
+
+## 3. 结论摘要 / Verdict summary
+
+| 级别 Severity | 数量 Count | 说明 Notes |
+| --- | --- | --- |
+| S1 阻断 Blocking | | |
+| S2 严重 Major | | |
+| S3 次要 Minor | | |
+| S4 打磨 Polish | | |
+| U 无法判定 Undetermined | | |
+
+一句话结论 / One-line verdict:
+
+## 4. 缺陷表 / Defect table
+
+> 一行一条，`证据` 写相对路径，`跨模式` 写该用例在 L1/L2/L3 的差异。
+> One row per finding; `Evidence` holds relative paths; `Modes` holds the L1/L2/L3 difference.
+
+| ID | 级别 Sev | 平台 | 元素/工具 | 步骤（真实操作） | 期望（画面） | 实际（画面） | 跨模式 L1/L2/L3 | 证据 Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| F-001 | S2 | macOS | 工具栏「导出」按钮 | 鼠标移动到按钮 → 单击 | 弹出导出面板 | 无任何反应，按钮无按下态 | L1 失败 / L2 失败 / L3 ⌘E 成功 | `evidence/2026-10-04T093012-F-001-L1-after.png` |
+| F-002 | S3 | iPhone | 设置页「同步」开关 | 手指点击开关 | 开关变为开启 | 开关回弹，状态未变 | L1 失败 / L2 无外接键盘 / L3 不适用 | `evidence/...` |
+
+每条缺陷另附细节 / Per-defect detail:
+
+```text
+ID：F-001
+标题 / Title：
+复现率 / Repro rate：x/y
+前置条件 / Preconditions：
+步骤 / Steps（只用：移动、悬停、单击、双击、右键、拖拽、滚轮、键入、焦点移动、等待）：
+期望 / Expected：
+实际 / Actual：
+画面证据 / Visual evidence：（相对路径 + 录屏 mm:ss）
+跨模式差异 / Cross-mode difference：
+影响 / Impact：
+建议 / Suggestion：
+```
+
+## 5. 观察与疑点 / Observations and suspicions
+
+| ID | 类型 Kind（观察/疑点） | 现象 | 为什么值得记 | 下一步 |
+| --- | --- | --- | --- | --- |
+
+## 6. 未验证项 / Unverified items
+
+| 项 Item | 原因 Reason（权限/设备/时间/证据不足） | 想验证它需要什么 |
+| --- | --- | --- |
+
+> 记住 R5：**没有画面的结论不能写成通过。**
+> Remember R5: **a conclusion without a picture is never written as "passed".**
+
+## 7. 合规声明 / Compliance statement
+
+- 本次测试**未使用任何内部指针指令**：无指针/触摸/按键注入，无自动化框架驱动，
+  无内部句柄调用。输入仅来自操作者的真实外设。
+- 证据仅来自录屏与截屏；代码、日志、接口与数据库未作为结论依据。
+- 是否使用硬件宏或系统辅助（鼠标键等）：是 / 否；如是，说明：
+
+## 8. 修复建议顺序 / Suggested fix order
+
+| 顺序 Order | 缺陷 ID | 理由（影响面/根因/成本） | 复测用例 |
+| --- | --- | --- | --- |
+
+修复后复测必须用**同一用例、同一模式**，结论追加到原缺陷条目。
+Retest with the same case and mode, and append the result to the original entry.

package/skills/observed-ui-test/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: observed-ui-test
+description: 观察式界面测试：只用真实鼠标和键盘操作软件，靠录屏与截屏判断功能元素是否完好、工具是否可用。用于 macOS、Windows、iPhone、iPad 及其他交互设备的软件测试与找 bug，按三级模式推进（仅鼠标 / 鼠标+键盘无快捷键 / 鼠标+键盘+快捷键），禁止任何内部指针注入指令，开始前先向用户申请鼠标、键盘与录屏等权限。Observed UI testing: drive software with a real mouse and keyboard only, and judge element integrity and tool usability from screen recordings and screenshots, on macOS, Windows, iPhone and iPad, in three escalating input modes, with zero synthetic pointer injection, after asking the user for mouse, keyboard and capture permissions.
+---
+
+# 观察式界面测试 / Observed UI Testing
+
+用 DeepSeek Harness 做软件设计时，用这套方法做验收、找 bug、验工具。核心只有一句：
+**人是唯一的手，屏幕是唯一的证据。**
+
+A method for acceptance testing, bug hunting and tool verification while designing software with
+DeepSeek Harness. One sentence holds it together:
+**the human is the only hand, the screen is the only evidence.**
+
+---
+
+## 0. 首次被调用时，第一句话必须是权限申请 / First response is always the permission request
+
+在开始任何测试动作之前，先原样问出下面这段（可按需裁剪，不可省略问项）：
+
+Before any test action, ask this first (trim if needed, never drop a field):
+
+> 开始测试前需要你确认权限 / Before we start, please confirm permissions:
+>
+> 1. **鼠标操作**：允许我按你的真实鼠标操作来记录和判定吗？/ May I judge from your real mouse actions? `yes / no`
+> 2. **键盘操作**：允许使用键盘吗？允许到哪一级？/ Keyboard allowed, and up to which mode? `仅鼠标 / 鼠标+键盘无快捷键 / 可用快捷键`
+> 3. **屏幕录制**：允许录屏吗？录屏会包含光标吗？/ Screen recording allowed, cursor included? `yes / no`
+> 4. **截屏**：允许随时截屏取证吗？/ Screenshots for evidence? `yes / no`
+> 5. **软硬件权限**：系统设置里的屏幕录制权限（macOS）、屏幕截图/录屏与麦克风（Windows）、iPhone/iPad 的屏幕录制与信任（iOS）、旁白解说用麦克风——这些你愿意开哪些？/ Which OS-level capture and microphone permissions will you grant?
+> 6. **被测对象**：应用名、版本、平台、涉及的设备（macOS / Windows / iPhone / iPad / 其他）。/ App under test, version, platform, devices.
+> 7. **范围与时长**：这次测哪些功能、大概多久、有没有不可触碰的数据（真实账号、生产库）。/ Scope, duration, and any data that must not be touched.
+
+用户没有明确同意之前，**不要**开始步骤 1 之后的任何操作。权限被拒绝时不要绕过，改为记录为"未验证项"并降级（见 §5）。
+
+Until the user explicitly agrees, do **not** start anything past step 0. If a permission is denied,
+do not work around it: record it as an unverified item and degrade the plan (see §5).
+
+---
+
+## 1. 五条硬性规则 / Five hard rules
+
+**R1 — 不许使用内在指针指令 / No internal pointer directives.**
+任何"在程序内部合成指针、触摸或按键"的手段都禁止：不注入、不模拟、不调用内部句柄触发功能。
+完整的禁止清单见 [BANNED-INPUTS.md](BANNED-INPUTS.md)。只允许两种输入来源：**人的真实外设**，
+以及**用户明确授权后、由被授权者手动发起**的等价真实操作。
+
+No directive that synthesizes a pointer, touch or key event inside the program: no injection, no
+simulation, no invoking internal handles to trigger features. Full deny list:
+[BANNED-INPUTS.md](BANNED-INPUTS.md). Exactly two input sources are legal: **the human's real
+peripherals**, and **the same real action performed by hand by an authorised person**.
+
+**观察注入 ≠ 执行注入 / Watching injection is not doing it.** 被测机器上**可以有**一个只读守门器
+一直盯着"有没有注入工具在跑"，这正是 `guard.mjs` 做的事：它扫描进程表与测试文本，把疑似注入线索
+写进 `evidence/compliance.jsonl`，最终出现在报告里。它是**观察者**，不是**手**——它没有任何注入
+能力。测试前扫一次、测试期间后台盯一遍，偷用注入就会留下痕迹。
+
+A read-only watchdog **may** watch for injection tooling, and `guard.mjs` does exactly that: it scans
+the process table and the session text, writing suspected injection clues to
+`evidence/compliance.jsonl` and into the report. It is an **observer**, never a **hand** — it has no
+injection capability at all. Scan before the run and watch during it; a smuggled injection leaves a
+trace.
+
+**R2 — 证据只来自录屏与截屏 / Evidence comes from recording and screenshots only.**
+"元素是否完好""工具是否能用"必须从画面判定。代码、DOM、日志、接口返回、数据库只能当线索，
+不能当结论。Agent 用 `read_image` 读截图，逐帧/逐张看图说话。
+
+Element integrity and tool usability are judged from the picture. Code, DOM, logs, API responses and
+databases are leads, never conclusions. The agent reads screenshots with `read_image` and speaks about
+what is visible.
+
+**R3 — 权限闸门先行 / Permission gate first.**
+§0 的问项没被回答，测试不开始。答案写进会话文件，可追溯。
+
+No answers, no testing. The answers are written into the session file and stay auditable.
+
+**R4 — 三级模式按序执行 / Three modes, in order.**
+仅鼠标 → 鼠标+键盘（禁快捷键）→ 鼠标+键盘+快捷键。同一个用例在三级的差异本身就是结论：
+只在高级别能完成 = 缺少鼠标可达路径；只在低级别能完成 = 快捷键路径有问题。
+见 [LEVELS.md](LEVELS.md)。
+
+Mouse only → mouse + keyboard without shortcuts → with shortcuts. The difference across modes *is* a
+finding: passing only at a higher mode means no mouse-reachable path exists; passing only at a lower
+mode means the shortcut path is broken. See [LEVELS.md](LEVELS.md).
+
+**R5 — 没测到不许写成通过 / Never mark untested as passed.**
+三种状态分开记：`通过 / 失败 / 未验证`。证据不足以判定的写"未验证（证据不足）"。
+每条缺陷都要有该模式下的真实操作步骤和对应截图/录屏时间点。
+
+Three separate states: `passed / failed / unverified`. Insufficient evidence is
+"unverified (insufficient evidence)". Every defect carries real steps under that mode plus the
+screenshot or recording timestamp that shows it.
+
+---
+
+## 2. 从上到下的执行流程 / Top-down workflow
+
+| # | 步骤 Step | 做什么 What | 产物 Artifact |
+| --- | --- | --- | --- |
+| 0 | 权限闸门 Gate | §0 的问项，用户逐条回答 | `session.json` 的 `gate` 段 |
+| 1 | 建会话 Session | 建目录与清单骨架 | `node scripts/session.mjs init <dir> --platform macos` |
+| 2 | 划范围 Scope | 被测版本、设备、账号、不可触碰的数据、退出条件 | 会话里的 `scope` |
+| 3 | 列元素 Inventory | **只看画面**列出功能元素与工具，不看代码 | `elements.md` |
+| 4 | 排用例 Matrix | 元素 × 平台 × 三级模式，标优先级 | `matrix.md` |
+| 5 | 跑 L1 仅鼠标 | 全用例只用鼠标，截屏留证 | `findings.jsonl`、`evidence/` |
+| 6 | 跑 L2 无快捷键 | 复跑全部用例；L1 的失败在此复现性登记 | 同上 |
+| 7 | 跑 L3 快捷键 | 每条功能至少走"菜单/鼠标"与"快捷键"两条路径并比对结果一致性 | 同上 |
+| 8 | 判定与报告 Verdict | 汇总、分级、写未验证项与权限缺口 | `report.md`（中英对照） |
+
+会话脚手架、取证与报告都可由插件自带脚本生成；脚本只**读屏**，绝不注入输入：
+
+```bash
+node <skill-directory>/../scripts/session.mjs init  ./ui-test-<app>-<date> --platform macos --app "<app>"
+node <skill-directory>/../scripts/capture.mjs check
+node <skill-directory>/../scripts/guard.mjs scan    ./ui-test-<app>-<date>   # 只读观察注入线索
+node <skill-directory>/../scripts/capture.mjs record ./ui-test-<app>-<date> --label L1 --seconds 60
+node <skill-directory>/../scripts/guard.mjs watch   ./ui-test-<app>-<date> --seconds 600
+node <skill-directory>/../scripts/report.mjs build  ./ui-test-<app>-<date>
+```
+
+The session scaffold, evidence capture, injection watchdog and report are generated by the scripts
+shipped with this plugin. The scripts only **read the screen and the process table**; they never
+inject input. 脚本只读屏、只读进程表，绝不注入输入。
+
+---
+
+## 3. 三级操作模式速查 / The three modes at a glance
+
+| 级别 Level | 允许 Inputs | 禁止 Forbidden | 目的在于 Catches |
+| --- | --- | --- | --- |
+| **L1 仅鼠标** | 移动、单击、双击、右键菜单、拖拽、滚轮、悬停 | 一切键盘输入（含 Tab 导航）；预置剪贴板后用菜单粘贴是允许的 | 无鼠标路径、命中区过小、必须悬停才可发现的控件 |
+| **L2 鼠标+键盘** | L1 全部 + 字符输入、Enter、Tab/Shift+Tab、方向键、退格/删除、空格、Home/End/PageUp/PageDown；Shift 仅用于输入大写 | 一切修饰键组合（⌘/Ctrl/⌥/Alt/Win）+ 按键；F1–F12；把 Esc 当"取消/关闭"用 | 键盘导航断链、焦点环错位/丢失、焦点陷阱、顺序错乱 |
+| **L3 鼠标+键盘+快捷键** | 全部，含 ⌘/Ctrl 组合与功能键 | 仍然禁止内部指针指令（R1 永不放开） | 快捷键失效/冲突，鼠标路径与快捷键路径结果不一致 |
+
+判定样例 / Worked examples：`仅 L3 可完成` = 无鼠标可达路径 → 可用性缺陷；
+`L1、L2 可完成、L3 反而失败` = 快捷键路径有缺陷；`三级都失败` = 功能本身坏了。
+细节与逐键白名单见 [LEVELS.md](LEVELS.md)。
+
+---
+
+## 4. 屏幕观察清单 / What to look for on screen
+
+对清单里的每个元素，按这十个维度看图 / For every element in the inventory, inspect these ten
+dimensions in the picture:
+
+1. **存在 Existence** — 元素出现了吗，是否只在特定状态出现。
+2. **完好 Integrity** — 图标、文字、边框、圆角、阴影是否正确渲染；破图、缺字（tofu）、错位、重影。
+3. **可读 Legibility** — 对比度、字号、截断、换行、深色模式、高对比度模式。
+4. **可发现 Discoverability** — 不看文档能不能找到；悬停提示、空状态引导是否存在。
+5. **命中与状态 Hit target & states** — 点击区域与视觉是否一致；悬停/按下/选中/禁用/忙碌态是否都有。
+6. **反馈 Feedback** — 操作后有即时反馈吗；加载、成功、错误提示是否出现且看得懂。
+7. **状态正确 State correctness** — 取消、返回、切换后是否回到正确状态；焦点环在哪。
+8. **层级与布局 Layering & layout** — 弹窗遮挡、滚动条、内容裁剪、窗口缩放、iPad 横竖屏与分屏。
+9. **数据完整 Data integrity** — 输入是否被正确保存与回显，列表是否刷新。
+10. **跨设备一致 Consistency** — macOS / Windows / iPhone / iPad 之间同一功能的表现是否一致。
+
+"工具是否可行"就是这一条：软件提供的工具（工具栏、绘图、导出、查找、设置、批量操作等）
+能否只用真实鼠标键盘走通，并且在画面上看得到正确结果。/
+
+"Tool usability" is exactly this: can each tool the software offers (toolbar, drawing, export, find,
+settings, batch operations) be completed with a real mouse and keyboard, with a correct visible
+result on screen.
+
+---
+
+## 5. 权限被拒或缺失时 / When a permission is denied or missing
+
+| 缺口 Gap | 不要做 Don't | 改为 Do instead |
+| --- | --- | --- |
+| 无录屏 No screen recording | 用日志/代码臆断结果 | 改用逐步截屏取证，并在报告里标注"无连续录屏" |
+| 无截屏 No screenshots | 凭记忆写结论 | 停止测试，说明无法取证；或由用户口头描述并标为"未验证" |
+| 无键盘 No keyboard | 偷偷用快捷键 | 只跑 L1，L2/L3 记为未覆盖 |
+| 不能碰真实数据 Real data off-limits | 照测不误 | 用演示数据/测试账号，或在报告中明确数据边界 |
+| 设备不在手边 Device unavailable | 用模拟器冒充真机 | 标为"未在真机验证（模拟器/仿真器）" |
+
+状态栏里出现的任何"自动化"选项都不要开；测试期间关闭其他自动化工具与宏，避免污染观察。
+
+Never enable an "automation" option to get around this; turn other automation tools and macros off
+during a session so the observation stays clean.
+
+---
+
+## 6. 报告要求 / Report requirements
+
+用 [REPORT-TEMPLATE.md](REPORT-TEMPLATE.md) 的结构，中英对照，至少包含：
+测试环境与版本、权限记录、覆盖率（元素/模式/平台）、缺陷表（含步骤、期望、实际、证据、级别与
+三级模式下的差异）、未验证项与原因、结论与建议修复顺序。
+
+Use the structure in [REPORT-TEMPLATE.md](REPORT-TEMPLATE.md), bilingual, covering at least:
+environment and versions, permission record, coverage over elements/modes/platforms, the defect table
+(steps, expected, actual, evidence, severity, and behaviour across the three modes), unverified items
+with reasons, and a verdict plus fix order.
+
+级别 / Severity：`S1` 崩溃/数据丢失/主流程完全不可用 · `S2` 主流程受阻但有绕行 · `S3` 次要功能或视觉缺陷 ·
+`S4` 打磨与建议 · `U` 证据不足无法判定。
+
+---
+
+## 7. 本技能的资源文件 / Files in this skill
+
+| 文件 File | 内容 Content |
+| --- | --- |
+| [FRAMEWORK.md](FRAMEWORK.md) | 完整框架：从上到下的设计、角色、退出条件、原语 |
+| [LEVELS.md](LEVELS.md) | 三级模式的逐键白名单、升降级规则、判定句式 |
+| [BANNED-INPUTS.md](BANNED-INPUTS.md) | 各平台禁止的内部指针指令清单与合规替代做法 |
+| [EVIDENCE.md](EVIDENCE.md) | 录屏/截屏取证协议：命名、时间点、可读性、留证边界 |
+| [REPORT-TEMPLATE.md](REPORT-TEMPLATE.md) | 中英对照报告模板 |
+
+配套的计划与权限技能是 `observed-test-plan`；开始前需要权限问卷与用例矩阵时先用它。
+The companion planning skill is `observed-test-plan`; use it first for the permission questionnaire
+and the case matrix.

package/skills/software-design-test/DEFECTS.md

@@ -0,0 +1,205 @@
+# 观察记录、缺陷分类与报告 / Observation Log, Defect Taxonomy and Reporting
+
+---
+
+## 一、观察记录 / The observation log
+
+模拟用户的产出不是"印象"，是**带时间戳的观察条目**。每条四要素：
+
+| 要素 Element | 要求 Requirement |
+| --- | --- |
+| 发生了什么 What happened | 用户在画面上做了什么、屏幕上出现了什么（引号原样抄界面文字） |
+| 当时的意图 Intent | 这条任务此时想达成什么（意图，不是步骤） |
+| 预期 vs 实际 Expected vs observed | 分开写，不许混成一句 |
+| 证据 Evidence | 截图相对路径 + 录屏 `mm:ss` |
+
+**观察记录字段 / Observation-log fields**（一行 = 一个可观察事件，**不含解释**）：
+
+```text
+会话 ID · 日期 · 人物 · 任务 ID · 时间戳（mm:ss）
+观察到的动作（用户做了什么）
+原话引用（verbatim，操作者当时的说法）
+他声称的期望（"我以为这会保存"）
+结果：成功 / 失败 / 需要协助
+错误类型：走错路 / 误触 / 找不到 / 状态不符
+牵涉的启发式或认知走查问题（第几问失败）
+证据链接（截图 + 录屏 mm:ss）
+观察者 · 严重级候选
+```
+
+**纪律 / Discipline**
+
+- 观察与解释分开写：`观察：按钮无按下态` / `解释：可能是热区没绑事件`。
+- 只写"画面可见 / 画面不可见"，不写"应该是""大概"。
+- 立刻写，别攒到最后回忆；每个任务卡结束就落盘一条。
+- 看不清就写"证据不足"，标 `未验证`。
+
+```json
+{
+  "id": "F-003",
+  "at": "2026-10-04T01:10:00.000Z",
+  "level": "L1",
+  "persona": "P-01 新手 Novice",
+  "scenario": "S-01 首次导出 First export",
+  "task_outcome": "partial",
+  "heuristic": "可发现性 Discoverability",
+  "element": "E-07 工具栏「导出」",
+  "title_zh": "只有快捷键才能导出，鼠标路径不存在",
+  "title_en": "Export is shortcut-only; no mouse path exists",
+  "steps_zh": "移动鼠标到工具栏，逐个悬停；打开菜单栏逐项查看",
+  "steps_en": "Hover each toolbar item; open every menu",
+  "expected_zh": "菜单或工具栏出现「导出」",
+  "expected_en": "Export is visible in a menu or toolbar",
+  "actual_zh": "只有「分享/打印/同步」，无导出",
+  "actual_en": "Only Share/Print/Sync are present",
+  "modes": "L1 fail / L2 fail / L3 ⌘E pass",
+  "severity": "S2",
+  "kind": "defect",
+  "repro_rate": "3/3",
+  "evidence": ["evidence/2026-10-04T01-10-00-P01-S01-L1.png"]
+}
+```
+
+---
+
+## 二、四类结论 / Four verdicts
+
+| 类别 Kind | 判据 Test | 后续 Next |
+| --- | --- | --- |
+| 缺陷 Defect | 有画面证据、可复现、期望与实际不符 | 定 S1–S4，进修复顺序 |
+| 观察 Observation | 现象为真，但不确定是否违背设计意图 | 交裁决者（用户）判断 |
+| 疑点 Suspicion | 疑似问题但未复现 | 标"待复现"，写怀疑依据 |
+| 未验证 Unverified | 权限/设备/证据不足 | 写原因与所需条件，**不许写成通过** |
+
+### 2.1 失败的四分类 / Four-way failure classification
+
+任何一次"没成功"，先归类再写报告——**只有 (c) 才是缺陷**：
+
+| 类别 | 含义 | 处理 |
+| --- | --- | --- |
+| (a) 测试者错误 Tester error | 操作者点错了、理解错了任务卡 | 修正操作重跑；**不计入缺陷**，但若"误解本身很容易发生"则记入可发现性 |
+| (b) 观察错误 Observation error | 截图模糊/证据不足，判读不出来 | 重拍；仍然判不了就记"未验证" |
+| (c) 产品缺陷 Genuine defect | 真实操作 + 画面证据 + 期望不符 | 进缺陷表 |
+| (d) 环境/权限故障 Environment or permission fault | 断网、权限被拒、设备不在 | 记为覆盖缺口或"未验证"，并说明需要什么条件 |
+
+> 依据：GUI 智能体（如 UI-TARS）把"纠错轨迹"与"事后反思"分开训练——**同一个区分用在这里，
+> 可以避免把测试事故写成产品缺陷**。
+
+### 2.2 观察前的状态描述 / Describe the state before judging
+
+在判定"这个界面有没有问题"之前，先用文字把画面抄一遍：有哪些元素、哪些可用/禁用、可见文字是什么、
+布局如何。**先描述，再判断**——跳过描述直接下结论，是最常见的判断偏差来源。
+
+> Before judging, transcribe the screen into text: elements, enabled/disabled, visible text, layout.
+> Describe first, then judge.
+
+---
+
+## 三、缺陷分类法 / Defect taxonomy
+
+照着这张表走一遍，比盯着空白页想"还有什么问题"有效得多。
+
+| 类别 Category | 画面上长什么样 On screen | 典型发现 Typical |
+| --- | --- | --- |
+| 功能 Function | 点了没反应、结果与预期不符 | 按钮失效、命令报错、结果算错 |
+| 状态 State | 选中态/禁用态/焦点态不对，返回后状态丢失 | 开关回弹、返回后回到首页、草稿丢失 |
+| 反馈 Feedback | 没有加载/成功/失败提示，或提示看不懂 | 长时间空白、错误码直接抛给用户 |
+| 可发现性 Discoverability | 入口藏太深、术语陌生、必须悬停才知道 | 只有快捷键能到、图标无文字 |
+| 导航与焦点 Navigation & focus | Tab 走不到、顺序乱、焦点环丢失 | 焦点陷阱、焦点跑到弹窗背后 |
+| 可访问性 Accessibility | 朗读内容缺失、对比度不足、动态字体破版 | 图标按钮无标签、放大后文字被裁 |
+| 布局与渲染 Layout | 重叠、裁切、错位、破图、缺字 | 长文本溢出、弹窗被任务栏挡 |
+| 内容 Content | 文案歧义、错别字、术语不一致 | "保存"和"应用"含义不同 |
+| 性能 Performance | 卡顿、无响应、动画掉帧 | 大列表滚动掉帧、切页白屏 2 秒 |
+| 数据完整 Data integrity | 输入被吞、重复写入、列表不刷新 | 中文输入丢字、重复提交 |
+| 错误处理 Error handling | 出错无恢复路径、提示指向错误位置 | 断网后卡死、权限被拒无引导 |
+| 跨设备 Cross-device | 同一功能在不同端表现不一致 | iPad 横屏布局错、Windows 上快捷键不同 |
+
+---
+
+## 四、严重级与优先级 / Severity and priority
+
+**严重级 Severity（看伤害）**：
+
+| 级别 | 定义 | 例子 |
+| --- | --- | --- |
+| **S1 阻断** | 崩溃、数据丢失、主流程完全不可用、隐私泄露 | 导出导致工程损坏；未保存即丢数据 |
+| **S2 严重** | 主流程受阻，但有绕行；或关键功能只在部分人物下可用 | 新手只有快捷键能导出 |
+| **S3 次要** | 次要功能缺陷、明显视觉问题、需要绕路 | 深色模式下图标看不清 |
+| **S4 打磨** | 不影响完成的体验问题 | 间距不齐、文案不统一 |
+| **U 无法判定** | 证据不足 | 截图模糊 |
+
+**优先级 Priority（看修的顺序）** 不等于严重级：S3 但阻塞所有新手 → 高优先；S2 但只影响 0.1% 的
+冷门路径 → 低优先。报告里两者都要写，别用一个词糊过去。
+
+**谁定 / Who decides**：**严重级由测试方定**（产品影响：崩溃、数据、可达性、绕行方案）；
+**优先级由产品/管理层定**（业务紧迫性）。分歧要升级讨论，不许一方覆盖另一方。
+四象限处理顺序：高严重高优先 → 低严重高优先（例如品牌文案类）→ 高严重低优先。
+把两个字段合成一个，会让分诊变成政治，还会掩盖"这个问题有绕行方案"这一关键信息。
+
+---
+
+## 五、复现与最小化 / Reproduce and minimize
+
+1. **复现率**：`x/y`，写清 y 是几次尝试。不复现的写"疑点（待复现）"。
+2. **最短可靠路径**：一步步删掉不必要的动作，直到再删就不复现。**必须仍然由人手操作完成**，
+   不许用脚本"最小化"。
+3. **隔离变量**：窗口大小、缩放、深浅色、语言、账号、网络状态、外接屏——一次只改一个。
+4. **重拍证据**：最小化之后重新截图，报告里用最小路径的那张。
+5. **记录"没复现"**：同一个动作在第 4 次才失败，也要写下来（时序/竞态类缺陷往往如此）。
+
+---
+
+## 六、缺陷条目的解剖 / Anatomy of a good defect entry
+
+```text
+标题 / Title：[人物/级别] 症状 + 位置
+  差：导出有问题
+  好：[P-01 新手 / L1] 工具栏找不到导出，只有 ⌘E 可用
+环境 / Environment：macOS 14.5 · 1920×1080 · 100% · 浅色 · 鼠标（无外接键盘）
+前置 / Preconditions：示例工程 sample-01 已打开，无未保存修改
+步骤 / Steps：1. … 2. …（只用真实鼠标键盘动作）
+预期 / Expected（画面上可见）：…
+实际 / Actual（画面上可见）：…
+跨模式 / Cross-mode：L1 失败 / L2 失败 / L3 成功
+复现率 / Repro rate：3/3
+证据 / Evidence：evidence/….png；录屏 00:42–00:58
+影响 / Impact：新用户在 L1 无法完成导出，属于"缺鼠标可达路径"
+建议 / Suggestion：把「导出」放进「分享」菜单第一层
+```
+
+**完整条目字段 / Full issue-record fields**：ID · 标题 · 描述 · 人物 × 任务 · 证据时间点 ·
+**频率**（多少个操作者/多少次尝试能复现，写成 `x/y`）· **持续性**（每次都能？还是偶发？）· 影响 ·
+根因或违反的启发式 · 严重级（0–4 或 S1–S4；多人评分取均值）· 建议 · 负责人与状态 · 复现步骤。
+
+**"那又怎样"测试 / The "so what?" test**：每条缺陷都要能回答"哪个用户在什么情况下会受损"。
+回答不出来的，降级成"观察"，别硬说成缺陷。
+
+**追踪闭环 / Traceability**：每条缺陷都要能顺着
+`观察记录 → 证据文件 → 任务卡/人物 → 测试目标` 一路追回去；追不回去的条目说明记录漏了字段。
+
+---
+
+## 七、报告与去重 / Synthesis and de-duplication
+
+- **按根因合并**：同一根因造成的 5 个症状写成 1 条主缺陷 + 5 个复现点，别把数量刷上去。
+- **按人物×场景给覆盖**：报告要能回答"P-01 在新手路径上遇到几条 S2 以上问题"。
+- **给出修复顺序**：S1 先行；同根因合并；高影响面的先修。
+- **复测纪律**：修复后用**同一任务卡、同一人物、同一级别**复测，结论追加到原条目。
+
+---
+
+## 八、模拟人物的效度边界 / Validity limits of simulated personas
+
+本工作流里的"人物"是**你自己扮演的观察视角**，不是用户研究结论。三条硬边界：
+
+1. **不许把你的模拟结论写成真实用户结论**。报告里永远写"在 P-01 这个模拟视角下"，
+   而不是"新手用户都找不到导出"。
+2. **对抗"人物太配合"**：
+   - 明确要求每个人物"必须找茬"，而不是"确认能用"；
+   - 每个场景至少逼出一次"如果这里失败，用户会怎么做"的回答；
+   - 允许并鼓励把结论写成失败；把"一切正常"当成需要额外证据的强主张。
+3. **不许用模拟替代真实测试**：高风险功能（支付、医疗、安全）必须补真人会话，
+   模拟只用于**扩大覆盖面、提前发现明显问题**。
+
+> 一句话：模拟用户提高的是**发现率**，不是**结论的权威性**。
+> Simulated personas raise the **detection rate**, not the **authority** of a conclusion.