software-design-test 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 变更记录 / Changelog
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与[语义化版本](https://semver.org/lang/zh-CN/)。
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
+
+## [1.2.0] - 2026-10-04
+
+### 新增 / Added
+
+- **触发词即开始**：用户说「模拟真实用户测试」或英文等价表达（`simulate a real user test`、
+  `run a real-user simulation test`、`simulated user testing`、`test it like a real user`）时，
+  插件**立即进入真实模拟测试**：一句话确认对象 → 发权限问卷 → 建会话开跑，不再讨论方法论。
+- **测试内容清单 `TEST-CONTENT.md`**：15 类"测什么"，每类含检查项 / 怎么看 / 判据——
+  窗口与界面尺寸、鼠标速度与指针、目标尺寸与间距、工具栏与菜单、文字排版、布局层级、反馈状态、
+  效率流程、键盘焦点、可访问性、性能响应、错误恢复、数据输入、跨设备一致性、视觉打磨，
+  附阈值速查表（WCAG 2.5.8 / 2.5.5 / 1.4.3 / 1.4.4 / 1.4.10、Apple 44pt、Material 48dp、
+  0.1s–1s–10s 响应时限、悬停 300–500ms）。
+- **窗口尺寸与指针速度专项**：窗口尺寸矩阵（最小 / 默认 / 最大化 / 分屏 / 缩放 200% / 多显示器）、
+  指针总行程与精细操作测量法（录屏帧估算，不需要任何自动化工具）。
+- 会话脚手架新增 `content.md`（15 类跟踪表 + 十分钟快扫 + 尺寸/速度测量表）；
+  发现条目新增 `content`（测试内容类别）与 `criteria`（判据）字段。
+- 报告新增 **「测试内容分布」** 一节，按测试内容聚合发现、给出每类最坏级别与判据。
+- 并入已核验的调研细节：单人启发式评估的发现率（严重 42% / 轻微 32%）、严重级=频率×影响×持续性、
+  认知走查会话组织（任一问"否"即 Fail）、出声思维"不许救援"、N=5 只是发现法则、
+  检查类方法与真人会话必须交替；观察记录 11 字段与 issue record 字段清单。
+- 修正两处以讹传讹：巡游按书中的"城区"分组（Configuration / Dirty Harry 不在书内）、
+  `SFDIPOT` 而非 `SFDPOT`（补回 Interfaces 透镜）。
+- 新增 CI（`.github/workflows/verify.yml`）与 `CHANGELOG.md`。
+
+### 变更 / Changed
+
+- **插件改名为 `software-design-test`**（原 `dsh-observed-ui-test`）；主技能同名，
+  是 `/` 菜单里的直接入口；`cordis.patch.yml` 行 id 与包名同步。
+- 重心从"观察式测试"移到**"如何模拟真实用户做软件测试"**：主技能重写，
+  README / 安装说明 / 使用说明 / 框架总览 / locale / package 描述全部改为模拟优先的叙述。
+- `countTableRows` 修正为只统计文件内**第一张**表，避免 `content.md` 的测量表被计入类别数。
+
+## [1.1.0] - 2026-10-03
+
+### 新增 / Added
+
+- `user-sim-bug-hunt`（现 `software-design-test`）技能：十步工作流（P0 立项与权限 → P1 人物 →
+  P2 场景 → P3 任务卡 → P4 旅程 → P5 启发式与巡游 → P6 执行 → P7 判定 → P8 报告 → P9 复测）。
+- 人物与场景构建、Nielsen 十项、HICCUPPS(F)、SFDIPOT、Whittaker 巡游、WCAG 2.2 无障碍步骤，
+  以及带核验标记的 [SOURCES.md](skills/software-design-test/SOURCES.md)。
+- 会话脚手架新增 `personas.md` / `scenarios.md` / `journey.md` / `heuristics.md`；
+  报告新增「用户模拟覆盖」一节。
+
+## [1.0.0] - 2026-10-03
+
+### 新增 / Added
+
+- 首个版本（最初命名 `dsh-observed-ui-test`）：观察式界面测试。
+- 两个技能：`observed-ui-test`（五条硬性规则、三级操作模式、十大观察维度、取证协议、报告模板）、
+  `observed-test-plan`（权限问卷、范围六项、元素清单、用例矩阵）。
+- 脚本：`session.mjs`（会话、权限闸门、发现落盘）、`capture.mjs`（只读截屏/录屏）、
+  `guard.mjs`（只读观察输入注入线索）、`report.mjs`（中英对照报告）、`verify.mjs`（离线自检）。
+- 硬规则：真实鼠标键盘、画面唯一证据、**禁止任何内部指针注入指令**、权限闸门先行。
+- 中英对照的 README、安装说明、使用说明与框架总览。
+
+[1.2.0]: https://github.com/Inceptzws/software-design-test/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/Inceptzws/software-design-test/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/Inceptzws/software-design-test/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inceptzws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# software-design-test · 软件设计测试（模拟真实用户）/ Software Design Testing by Simulating Real Users
+
+**一个 DeepSeek Harness 插件（DSH bundle plugin），重心是「怎么模拟真实用户来测软件」：
+建人物与场景 → 拆任务卡 → 用出声思维在三级操作模式下真实操作 → 靠录屏与截屏判断功能元素是否
+完好、工具是否真的可用，系统找出断头路、绕路、误导与状态错误。人不借助任何输入注入。**
+An AI-native DSH bundle plugin whose centerpiece is **how to simulate a real user to test software**:
+personas and scenarios, executable task cards, think-aloud execution in three input modes, and
+screen-evidence judgement of element integrity and tool usability — with zero input injection.
+
+[![npm version](https://img.shields.io/npm/v/software-design-test.svg)](https://www.npmjs.com/package/software-design-test)
+[![verify](https://github.com/Inceptzws/software-design-test/actions/workflows/verify.yml/badge.svg)](https://github.com/Inceptzws/software-design-test/actions/workflows/verify.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-ecosystem-7C6CF6)](https://github.com/topics/dsh-plugin)
+
+[English](#english) | 中文
+
+---
+
+## 它是什么 / What it is
+
+用 DeepSeek Harness 做软件设计（尤其 macOS、Windows、iPhone、iPad 各种交互设备）时，
+把"改完到底好不好用"变成一套可执行、可审计的流程。**核心是模拟真实用户**：
+不是"假装点几下"，而是明确**以谁的身份（人物）、想完成什么（任务）、用什么证明（画面）**，
+然后由真人用真实鼠标键盘在他会走的路径上走一遍：
+
+- **人是唯一的手**：只用真实鼠标与键盘操作，分三级模式推进。
+- **屏幕是唯一的证据**：从录屏/截屏观察元素是否完好、工具是否可用，代码与日志只是线索。
+- **不允许内在指针指令**：不注入鼠标/触摸/按键事件，不驱动自动化框架，不调用软件内部句柄。
+- **先问权限再动手**：鼠标、键盘、录屏、截屏与系统权限逐项询问用户，未答复不开始。
+- **可以观察注入**：只读守门器盯着"有没有注入工具在跑"，命中就落盘、就进报告。
+- **中英对照**：技能内容、问卷、报告模板、文档全部中英对照。
+
+> EN: A verifiable process for "is it actually usable yet": the human is the only hand (three
+> escalating input modes), the screen is the only evidence, internal pointer directives are banned,
+> permissions are asked before anything starts, a read-only watchdog records injection clues, and
+> every artifact is bilingual.
+
+---
+
+## 安装 / Install
+
+```bash
+# 本地目录（推荐；本机工作区里就是） / local checkout (recommended)
+dsh plugin --profile desktop add link:/Users/inception/Documents/deepseek-harness/default-workspace/software-design-test
+
+# GitHub（无需克隆）/ from GitHub
+dsh plugin --profile desktop add github:Inceptzws/software-design-test
+
+# npm / from npm
+dsh plugin --profile desktop add software-design-test
+```
+
+重启 Harness，然后确认：
+
+```bash
+grep -n "software-design-test" ~/.dsh/profiles/desktop/package.json
+```
+
+（依赖里出现 `link:` 那一行、`dsh.profile.bundles` 里出现同名条目即挂载成功；
+在 `/` 菜单或 `skill` 工具里能看到两个技能是最可靠的确认。）
+
+完整安装步骤、界面安装、手动挂载、卸载与排错见 **[docs/INSTALL.zh-en.md](docs/INSTALL.zh-en.md)**
+（安装说明 / Installation，中英对照）。
+> EN: Full install guide — local, GitHub, npm, UI install, manual mount, uninstall, troubleshooting:
+> [docs/INSTALL.zh-en.md](docs/INSTALL.zh-en.md).
+
+---
+
+## 使用 / Usage
+
+1. **直接说触发词：`模拟真实用户测试`**（英文：`simulate a real user test` / `run a real-user simulation test`）——
+   插件会**立即进入真实模拟测试**：一句确认对象 → 发权限问卷 → 建会话开跑，不再跟你讨论方法论。
+   也可以说"用 software-design-test 测一下 <应用名>"，或从 `/` 菜单选 `software-design-test`。
+2. 回答权限问卷（鼠标、键盘级别、录屏、截屏、麦克风、系统权限、范围、数据边界、合规确认）。
+3. 建会话 → 记录闸门 → 只看画面列元素清单与用例矩阵。
+4. 按 **L1 仅鼠标 → L2 鼠标+键盘禁快捷键 → L3 可快捷键** 执行，逐条落盘。
+5. 生成中英对照报告（含未验证项、权限缺口、跨模式差异、注入观察）。
+
+```bash
+cd software-design-test
+node scripts/session.mjs init ./ui-test-demo-2026-10-04 --platform macos --app "Demo"
+node scripts/session.mjs gate ./ui-test-demo-2026-10-04 --mouse yes --keyboard L2 \
+  --screen-recording yes --screenshot yes --compliance yes
+node scripts/capture.mjs check
+node scripts/guard.mjs scan  ./ui-test-demo-2026-10-04
+node scripts/capture.mjs record ./ui-test-demo-2026-10-04 --label L1 --seconds 60
+node scripts/report.mjs build ./ui-test-demo-2026-10-04
+```
+
+完整用法、对话模板、FAQ 见 **[docs/USAGE.zh-en.md](docs/USAGE.zh-en.md)**
+（使用说明 / Usage，中英对照）；框架的从上到下设计见
+**[docs/FRAMEWORK.zh-en.md](docs/FRAMEWORK.zh-en.md)**。
+> EN: Full usage guide with copy-paste prompts and FAQ: [docs/USAGE.zh-en.md](docs/USAGE.zh-en.md).
+> Top-down framework: [docs/FRAMEWORK.zh-en.md](docs/FRAMEWORK.zh-en.md).
+
+---
+
+## 三个技能 / Three skills
+
+| 技能 Skill | 用途 Purpose |
+| --- | --- |
+| **`software-design-test`**（重心 centerpiece） | **模拟真实用户**：人物 → 场景 → 任务卡 → 旅程 → 启发式/巡游 → 执行 → 判定 → 报告 |
+| `observed-test-plan` | 准备：权限问卷、范围六项、只看画面的元素清单、用例矩阵与优先级 |
+| `observed-ui-test` | 执行规则：五条硬性规则、三级模式、十大观察维度、取证协议、报告模板 |
+
+技能名与插件名同名：`software-design-test` 就是本插件的主技能，也是 `/` 菜单里直接可用的入口。
+
+三个技能都是模型可调用的，请求匹配时 Agent 会自己选用。
+> EN: All three skills are model-invocable; the agent picks them up when the request matches.
+
+---
+
+## 测什么 / What to test — the content checklist
+
+用户真正关心的是**测什么**。完整清单 [TEST-CONTENT.md](skills/software-design-test/TEST-CONTENT.md)
+共 15 类，每类给出"检查项 / 怎么看 / 判据"：
+
+| 类别 | 先问什么 |
+| --- | --- |
+| §1 窗口与界面尺寸 | 这个界面的大小便于使用吗？最小尺寸、分屏、缩放 200% 还能用吗？ |
+| §2 鼠标速度与指针 | 鼠标要跑多远？要不要很慢很准？双击速度跟系统一致吗？悬停菜单会不会"路过就弹"？ |
+| §3 目标尺寸与间距 | 按钮够大吗？相邻按钮会不会误点？（24 / 44 / 48 阈值） |
+| §4 工具栏与菜单 | 图标不看提示能看懂吗？常用命令一级可达吗？变窄时会不会消失？ |
+| §5–§15 | 文字排版 · 布局层级 · 反馈状态 · 效率流程 · 键盘焦点 · 可访问性 · 性能响应 · 错误恢复 · 数据输入 · 跨设备一致性 · 视觉打磨 |
+
+阈速查（24×24 / 44×44 / 48dp、对比度 4.5:1、放大 200%、0.1s–1s–10s 响应时限、悬停 300–500ms…）见清单附 A。
+
+> The checklist answers *what we actually look at* — window size, pointer travel and speed, toolbar
+> readability, target sizes, text, layout, feedback, efficiency, keyboard, accessibility, performance,
+> errors, data, cross-device consistency and polish — with criteria such as WCAG 2.5.8.
+
+---
+
+## 模拟真实用户：十步工作流 / Simulating a real user: the ten steps
+
+完整流程写在 [skills/software-design-test/WORKFLOW.md](skills/software-design-test/WORKFLOW.md)：
+
+| # | 步骤 Step | 产出 Artifact |
+| --- | --- | --- |
+| P0 | 立项与权限 Charter & gate | `session.json` / `permissions.md` |
+| P1 | 人物 Personas（3–5 个，含依据与"会在哪放弃"） | `personas.md` |
+| P2 | 场景 Scenarios（首次成功/例行/出错恢复/中断/破坏性/交接） | `scenarios.md` |
+| P3 | 任务卡 Task cards（意图 + 画面可判定的成功标准） | `matrix.md` |
+| P4 | 旅程 Journey（进入/首次成功/熟练/出错恢复/退出再进入） | `journey.md` |
+| P5 | 启发式与巡游 Sweep（认知走查四问 → 十项启发式 → HICCUPPS/SFDIPOT → 14 条巡游） | `heuristics.md` |
+| P6 | 执行 Sessions（出声思维 × 三级模式 × 录屏截屏） | `findings.jsonl` / `evidence/` |
+| P7 | 判定 Adjudicate（分类、定级、复现与最小化） | 定稿发现 |
+| P8 | 报告 Report（去重 + 用户模拟覆盖） | `report.md` |
+| P9 | 复测 Retest（同一任务卡/人物/级别） | 追加到原条目 |
+
+配套清单：[启发式与巡游](skills/software-design-test/HEURISTICS.md)（含 Nielsen 十项、HICCUPPS(F)、
+SFDIPOT、Whittaker 巡游、WCAG 2.2 仅键盘/屏幕阅读器步骤）· [人物与场景](skills/software-design-test/PERSONAS-SCENARIOS.md) ·
+[缺陷与复现](skills/software-design-test/DEFECTS.md) · [出处](skills/software-design-test/SOURCES.md)。
+
+> EN: Ten phases from personas to retest, with heuristics, tours and accessibility checklists, all
+> composed with the three input modes and the no-injection rule. See
+> [WORKFLOW.md](skills/software-design-test/WORKFLOW.md).
+
+---
+
+## 三级操作模式 / The three input modes
+
+| 级别 | 允许 | 禁止 | 能抓到 |
+| --- | --- | --- | --- |
+| **L1 仅鼠标** | 移动、悬停、单击、双击、右键、拖拽、滚轮；预置剪贴板 + 菜单粘贴 | 一切键盘输入（含 Tab） | 无鼠标可达路径、命中区过小、必须悬停才可发现 |
+| **L2 鼠标+键盘** | 字符输入、Enter、Tab/Shift+Tab、方向键、退格、空格、Home/End/PageUp/Down；Shift 仅用于大写 | 一切修饰键组合（⌘/Ctrl/⌥/Alt/Win）、F1–F12、把 Esc 当命令键 | 键盘导航断链、焦点环错位/丢失、焦点陷阱、Tab 顺序错乱 |
+| **L3 加快捷键** | 全部放开 | 仍禁止内部指针指令 | 快捷键失效/冲突、鼠标路径与快捷键路径结果不一致 |
+
+跨模式差异本身就是结论：只在 L3 能完成 = 缺鼠标路径；只在 L1/L2 能完成 = 快捷键路径坏了。
+> EN: The difference across modes is itself the finding.
+
+---
+
+## 脚本 / Scripts
+
+| 脚本 | 作用 | 是否只读 |
+| --- | --- | --- |
+| `scripts/session.mjs` | 会话脚手架、权限闸门、发现落盘、状态统计 | 只写会话目录 |
+| `scripts/capture.mjs` | 截屏/录屏（macOS、Windows、iOS 模拟器、Android） | **只读屏，绝不注入** |
+| `scripts/guard.mjs` | 观察输入注入线索（进程表 + 测试文本） | **只读观察，绝不执行注入** |
+| `scripts/report.mjs` | 生成中英对照报告 | 只读会话目录 |
+| `scripts/verify.mjs` | 离线自检 8 项（挂载、元数据、链接、注入 API、CLI 端到端） | 只读 |
+
+---
+
+## 自检 / Verify
+
+```bash
+node scripts/verify.mjs          # 8/8 checks passed
+node --test test/*.test.mjs      # 25/25 pass
+```
+
+自检里有一项专门扫描 `lib/` 与 `scripts/`，确保这个包里**不存在任何可执行的输入注入 API**；
+另有一条测试确保 `capture.mjs` 永远不会长出一个 `input` 子命令。
+> EN: One check scans `lib/` and `scripts/` so the package can never grow an executable
+> input-injection API; another asserts `capture.mjs` never gains an `input` subcommand.
+
+---
+
+## 目录 / Layout
+
+```text
+software-design-test/
+├── package.json            # dsh.bundle.patch → cordis.patch.yml
+├── cordis.patch.yml        # 挂载：id: observed-ui-test
+├── lib/index.js            # Cordis 插件：ctx.skills provider（挂载即校验）
+├── lib/self-check.js       # 离线校验工具
+├── skills/observed-ui-test/       # SKILL.md · FRAMEWORK · LEVELS · BANNED-INPUTS · EVIDENCE · REPORT-TEMPLATE
+├── skills/observed-test-plan/     # SKILL.md · PERMISSIONS · MATRIX · PLAN-TEMPLATE
+├── skills/software-design-test/      # SKILL.md · WORKFLOW · PERSONAS-SCENARIOS · HEURISTICS · DEFECTS · SOURCES
+├── scripts/                # session · capture · guard · report · verify
+├── test/                   # node:test 用例（25 条）
+├── docs/                   # INSTALL · USAGE · FRAMEWORK（均中英对照）
+└── locale/{zh,en}.json     # Plugins 页面标题与描述
+```
+
+---
+
+## 归属与许可 / License
+
+MIT，见 [LICENSE](LICENSE)。本插件不打包任何第三方技能内容，技能文本为本项目原创。
+> EN: MIT, see [LICENSE](LICENSE). No third-party skill content is vendored; the skill text is
+> original to this project.
+
+---
+
+<a id="english"></a>
+
+## English
+
+`software-design-test` is a **DSH bundle plugin** that turns usability verification into an auditable
+process while you build software with DeepSeek Harness — especially on macOS, Windows, iPhone and
+iPad.
+
+**Five hard rules**
+
+1. **No internal pointer directives.** No injected pointer, touch or key events, no UI automation
+   drivers, no calls into the software's internals. Banned per platform with compliant alternatives in
+   `skills/observed-ui-test/BANNED-INPUTS.md`.
+2. **Evidence comes from recordings and screenshots only.** Code, DOM, logs and databases are leads,
+   never conclusions.
+3. **The permission gate comes first.** Mouse, keyboard mode, screen recording, screenshots,
+   microphone, OS capture permission, scope, data boundary and a compliance confirmation are asked
+   before anything starts; unanswered means no start. The Q&A is recorded in `session.json`.
+4. **Three input modes, in order.** L1 mouse only → L2 mouse + keyboard without shortcuts →
+   L3 with shortcuts. The difference across modes is itself a finding.
+5. **Never mark untested as passed.** `passed / failed / unverified` are three separate states.
+
+**Watching injection is not doing it.** A read-only watchdog (`scripts/guard.mjs`) may watch for
+injection tooling — it scans the process table and the session text, writes suspected clues to
+`evidence/compliance.jsonl`, and reports them in section 8 of the report. It has no injection
+capability whatsoever; it produces leads, not proof of absence.
+
+**Install**
+
+```bash
+dsh plugin --profile desktop add link:/absolute/path/to/software-design-test
+dsh --profile desktop --dump-config | grep -A3 observed-ui-test
+```
+
+**Use**
+
+Say "run an observed UI test on &lt;app&gt;", answer the permission questionnaire, scaffold the
+session, run L1 → L2 → L3, and build the bilingual report:
+
+```bash
+node scripts/session.mjs init ./ui-test-demo --platform macos --app "Demo"
+node scripts/session.mjs gate ./ui-test-demo --mouse yes --keyboard L2 --screen-recording yes \
+  --screenshot yes --compliance yes
+node scripts/report.mjs build ./ui-test-demo
+```
+
+Full guides: [install](docs/INSTALL.zh-en.md) · [usage](docs/USAGE.zh-en.md) ·
+[framework](docs/FRAMEWORK.zh-en.md). Self-check: `node scripts/verify.mjs` (8/8) and
+`node --test test/*.test.mjs` (25/25). MIT licensed.

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# ============================================================================
+# software-design-test — DSH bundle patch
+# ============================================================================
+# Mount declaration. DSH stacks each plugin bundle's patch onto the profile's
+# configuration tree at boot, so this file inserts the skill-provider row that
+# publishes the observed-UI-testing skills.
+#
+# 挂载声明。DSH 在启动时把每个插件 bundle 的 patch 叠进 profile 的配置树，
+# 这个文件插入一行 skill provider，使观察式界面测试技能在 Harness 里可见。
+#
+# Install / 安装:
+#   dsh plugin --profile desktop add link:/absolute/path/to/software-design-test
+#   dsh plugin --profile desktop add github:<owner>/software-design-test
+#   dsh plugin --profile desktop add software-design-test
+#
+# The package ships no dependencies and no build step, so no pnpm
+# `allowBuilds` approval is needed.
+# 本包无依赖、无构建步骤，不需要 pnpm 的 allowBuilds 批准。
+# ============================================================================
+
+- insert:
+    - id: software-design-test
+      name: software-design-test

package/docs/FRAMEWORK.zh-en.md

@@ -0,0 +1,149 @@
+# 框架总览（从上到下）/ Framework Overview (top-down)
+
+> 这是给人看的设计说明；Agent 执行时读的是 `skills/observed-ui-test/`、
+> `skills/observed-test-plan/` 与 `skills/software-design-test/`。
+> This is the human-facing design document; the agent executes from the two skill directories.
+
+---
+
+## 总图 / The picture
+
+```text
+                    ┌──────────────────────────────────────────────┐
+  层 0 立场         │  人 = 唯一的手      屏幕 = 唯一证据          │
+  Layer 0 Position  │  human = the only hand   screen = the only   │
+                    │                          evidence            │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 1 权限闸门     │ 鼠标 · 键盘级别 · 录屏/截屏 · 系统权限        │
+  Layer 1 Gate      │ 未答复 → 不开始 / unanswered → no start      │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 2 范围         │ 应用/版本 · 平台设备 · 输入设备 · 显示环境   │
+  Layer 2 Scope     │ 数据边界 · 退出条件                          │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 3 元素清单     │ 只看画面列出功能元素与工具 + 全部期望状态     │
+  Layer 3 Inventory │ inventory from the screen only               │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 4 用例矩阵     │ 元素 × 平台 × 模式(L1/L2/L3)，P0–P3 优先级   │
+  Layer 4 Matrix    │ case matrix with priorities                  │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 4.5 用户模拟   │ 人物 → 场景 → 任务卡 → 旅程 → 启发式/巡游   │
+  Layer 4.5 Sim     │ personas → scenarios → tasks → journey →     │
+                    │ heuristics & tours（software-design-test）      │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 5 三级执行     │ L1 仅鼠标 → L2 无快捷键 → L3 可快捷键         │
+  Layer 5 Execution │ the difference across modes IS the finding   │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 6 取证         │ 录屏 + 截屏 + 注入观察日志（只读）            │
+  Layer 6 Evidence  │ recording + screenshots + read-only watchdog │
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 7 判定         │ 缺陷 / 观察 / 疑点 / 未验证，S1–S4 分级       │
+  Layer 7 Verdict   │ defect / observation / suspicion / unverified│
+                    └──────────────────────────────────────────────┘
+                                      │
+                    ┌──────────────────────────────────────────────┐
+  层 8 报告         │ 中英对照、带证据、可复现、含权限缺口          │
+  Layer 8 Report    │ bilingual, evidenced, reproducible, with gaps│
+                    └──────────────────────────────────────────────┘
+```
+
+---
+
+## 三条不可交换的原则 / Three non-negotiables
+
+1. **真实输入 / Real input** —— 输入只来自人的真实外设。不注入、不模拟、不调用内部句柄。
+   > EN: Input comes only from the human's real peripherals. No injection, no simulation, no
+   > internal handle invocation.
+2. **画面证据 / Visual evidence** —— 结论必须能在画面上指认出来。
+   > EN: Every conclusion must be pointable-to on screen.
+3. **可复现 / Reproducible** —— 另一个操作者照步骤能重放。
+   > EN: Another operator can replay the steps.
+
+---
+
+## 测试要求 / Test requirements（用户指定的四条）
+
+| 要求 Requirement | 落地方式 How it is enforced |
+| --- | --- |
+| 不允许使用内在指针指令 | 禁用清单 + 计划文本扫描 + 进程表只读观察 + 代码级自检（`verify.mjs`） |
+| 从录屏/截屏观察元素是否完好、工具是否可行 | 十大观察维度 + 证据协议 + 一图一结论 |
+| 开始前询问鼠标/键盘/录屏等软硬件权限 | 权限问卷闸门，落盘 `session.json`，未通过不得开始 |
+| 三级操作模式 | L1 仅鼠标 → L2 鼠标+键盘禁快捷键 → L3 可用快捷键，跨模式差异登记 |
+
+> EN: No internal pointer directives (deny list, plan scan, process watchdog, code self-check);
+> judge integrity and tool usability from recordings and screenshots (ten dimensions, evidence
+> protocol); ask for mouse/keyboard/capture permissions before starting (gate recorded in
+> `session.json`); three input modes with cross-mode differences logged.
+
+---
+
+## 十大观察维度 / Ten on-screen dimensions
+
+存在 · 完好 · 可读 · 可发现 · 命中与状态 · 反馈 · 状态正确 · 层级与布局 · 数据完整 · 跨设备一致。
+> EN: existence · integrity · legibility · discoverability · hit target and states · feedback ·
+> state correctness · layering and layout · data integrity · cross-device consistency.
+
+---
+
+## 角色分工 / Roles
+
+| 角色 | 是谁 | 做什么 |
+| --- | --- | --- |
+| 操作者 Operator | 用户 | 唯一的手：真实鼠标键盘操作 |
+| 观察者 Observer | Agent + 用户 | 眼睛：读图判读元素与工具状态 |
+| 记录者 Recorder | Agent | 笔：写用例、记证据、出报告 |
+| 裁决者 Adjudicator | 用户 | 确认严重级与是否算缺陷 |
+
+> EN: the human is the only hand; the agent is the eyes and the pen; the human adjudicates severity.
+
+---
+
+## 用户模拟这一层怎么接进来（本插件的重心）/ How the simulation layer plugs in (the centerpiece)
+
+`software-design-test` 是本插件的主技能，提供"以谁、走哪条路、找哪类 bug"：人物（3–5 个，含依据）、六类场景、
+任务卡、用户旅程（五个阶段）、启发式扫描（认知走查四问 → Nielsen 十项 → HICCUPPS(F) → SFDIPOT →
+14 条巡游）、以及无障碍作为唯一"合法的模拟用户"（WCAG 2.2 仅键盘与屏幕阅读器步骤）。
+它**不改动**本框架的任何硬规则：仍然是真实鼠标键盘、画面证据、禁止内部指针指令。
+
+> EN: The simulation skill supplies who is simulated, which path, and which bugs — personas, six
+> scenario families, task cards, a five-stage journey, heuristic sweeps and accessibility lenses —
+> without relaxing a single hard rule of this framework.
+
+## 这个框架不做什么 / What it deliberately does not do
+
+- 不做自动化点击、不做录制回放、不做 RPA——那不是"真实用户路径"。
+- 不用代码/DOM/日志/数据库来"证明"界面正确——那些只是线索。
+- 不把没测到的写成通过——`未验证` 是一种正式结论。
+
+> EN: no scripted clicking, replay or RPA; no code/DOM/log/database "proof" of UI correctness; and
+> never writing untested as passed — `unverified` is a formal outcome.
+
+---
+
+## 一轮的产出 / Outputs of one round
+
+```text
+ui-test-<app>-<date>/
+├── session.json          # 闸门、范围、级别、统计
+├── permissions.md        # 权限问卷与用户答复
+├── elements.md           # 画面元素清单
+├── matrix.md             # 用例矩阵与覆盖率
+├── findings.jsonl        # 一条发现一行（含跨模式差异）
+├── report.md             # 中英对照报告（含未验证项、注入观察、合规声明）
+└── evidence/             # 截图、录屏、取证索引、注入观察日志
+```