software-design-test 1.2.0

package/scripts/verify.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * verify.mjs — offline, read-only verification of this plugin.
+ *
+ * It never touches the screen, the network or an input device. It checks that:
+ *   1. the plugin mounts and publishes every skill through the ctx.skills seam;
+ *   2. every SKILL.md has valid, bilingual frontmatter;
+ *   3. every relative markdown link resolves;
+ *   4. no shipped code contains an input-injection API;
+ *   5. the session / gate / finding / guard / report CLIs work end to end in a temp directory.
+ *
+ * 离线自检：挂载、技能元数据、相对链接、注入 API 扫描、脚本端到端冒烟。
+ *
+ * Usage / 用法: node scripts/verify.mjs
+ */
+
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  checkContentRequirements,
+  checkRelativeLinks,
+  checkSkills,
+  mentionsGuardObservation,
+  scanForInjectionApis,
+} from '../lib/self-check.js'
+import { apply } from '../lib/index.js'
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+const results = []
+
+async function check(name, run) {
+  try {
+    const detail = await run()
+    results.push({ name, ok: true, detail: detail ?? '' })
+  } catch (error) {
+    results.push({ name, ok: false, detail: error.message })
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message)
+}
+
+const node = process.execPath
+const run = (args, options = {}) =>
+  spawnSync(node, args, { encoding: 'utf8', cwd: packageRoot, ...options })
+
+await check('mount: plugin publishes every skill through ctx.skills', async () => {
+  let provider
+  const ctx = { skills: { registerProvider: (factory) => { provider = factory() } } }
+  apply(ctx, {})
+  assert(provider !== undefined, 'registerProvider was not called')
+  const candidates = await provider.list()
+  const names = candidates.map((candidate) => candidate.name)
+  assert(candidates.length >= 3, `expected at least 3 skills, got ${names.join(', ')}`)
+  for (const skill of ['observed-ui-test', 'observed-test-plan', 'software-design-test']) {
+    assert(names.includes(skill), `${skill} skill missing`)
+  }
+  for (const candidate of candidates) {
+    assert('rank' in candidate, 'rank should exist on the internal candidate')
+    assert(candidate.provider === 'software-design-test', 'wrong provider name')
+  }
+  return `${names.join(', ')} (${candidates.length} skills)`
+})
+
+await check('mount: provider.get returns body without leaking rank/locator', async () => {
+  let provider
+  apply({ skills: { registerProvider: (factory) => { provider = factory() } } }, {})
+  const candidates = await provider.list()
+  for (const candidate of candidates) {
+    const loaded = await provider.get(candidate, {})
+    assert(typeof loaded.content === 'string' && loaded.content.length > 100, `${candidate.name}: empty body`)
+    assert(!('locator' in loaded), `${candidate.name}: locator leaked`)
+    assert(!('rank' in loaded), `${candidate.name}: rank leaked`)
+  }
+  return 'bodies load, internals stay internal'
+})
+
+await check('skills: frontmatter is valid and bilingual', () => {
+  const { problems, skills } = checkSkills(packageRoot)
+  assert(problems.length === 0, problems.join('\n  '))
+  return skills.map((skill) => skill.name).join(', ')
+})
+
+await check('links: every relative markdown link resolves', () => {
+  const problems = checkRelativeLinks(packageRoot)
+  assert(problems.length === 0, problems.join('\n  '))
+  return 'all relative links resolve'
+})
+
+await check('ban: shipped code contains no input-injection API', () => {
+  const problems = scanForInjectionApis(packageRoot)
+  assert(problems.length === 0, problems.join('\n  '))
+  return 'lib/ and scripts/ are injection-free'
+})
+
+await check('content: method requirements are documented bilingually', () => {
+  const problems = checkContentRequirements(packageRoot)
+  assert(problems.length === 0, problems.join('\n  '))
+  assert(mentionsGuardObservation(packageRoot), 'guard.mjs observation wording missing')
+  return 'three modes, gate, banned list and guard are documented'
+})
+
+await check('cli: session init / gate / finding / guard / report end to end', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'observed-ui-test-'))
+  try {
+    const target = join(dir, 'session')
+
+    let result = run(['scripts/session.mjs', 'init', target, '--platform', 'macos', '--app', 'Demo'])
+    assert(result.status === 0, `init failed: ${result.stderr}`)
+    for (const file of ['session.json', 'permissions.md', 'elements.md', 'matrix.md', 'findings.jsonl', 'report.md']) {
+      assert(existsSync(join(target, file)), `init did not create ${file}`)
+    }
+    assert(existsSync(join(target, 'evidence')), 'init did not create evidence/')
+
+    // The gate blocks while capture permission is missing.
+    result = run(['scripts/session.mjs', 'gate', target, '--mouse', 'yes', '--keyboard', 'L1', '--screen-recording', 'no', '--screenshot', 'no', '--compliance', 'yes'])
+    assert(result.status === 1, `gate should block without capture permission, got ${result.status}`)
+    assert(result.stdout.includes('NOT CONFIRMED'), 'gate did not report NOT CONFIRMED')
+
+    // Denied mouse is fatal.
+    result = run(['scripts/session.mjs', 'gate', target, '--mouse', 'no', '--keyboard', 'L1', '--screen-recording', 'yes', '--screenshot', 'yes', '--compliance', 'yes'])
+    assert(result.status === 1, 'gate should block when the mouse is denied')
+
+    // Full answer passes.
+    result = run(['scripts/session.mjs', 'gate', target, '--mouse', 'yes', '--keyboard', 'L2', '--screen-recording', 'yes', '--screenshot', 'yes', '--microphone', 'no', '--os-permission', 'yes', '--cursor', 'yes', '--compliance', 'yes', '--data-boundary', 'demo account only'])
+    assert(result.status === 0, `gate should confirm: ${result.stdout}${result.stderr}`)
+    assert(result.stdout.includes('CONFIRMED'), 'gate did not confirm')
+
+    result = run(['scripts/session.mjs', 'status', target])
+    assert(result.status === 0 && result.stdout.includes('已通过'), 'status did not report a confirmed gate')
+
+    const finding = JSON.stringify({
+      level: 'L1',
+      element: 'E-07 toolbar export button',
+      title_zh: '导出按钮点击无反应',
+      title_en: 'Export button does nothing',
+      steps_zh: '移动鼠标到导出按钮，单击',
+      steps_en: 'Move the mouse to Export, click',
+      expected_zh: '弹出导出面板',
+      expected_en: 'Export dialog opens',
+      actual_zh: '无任何反应，无按下态',
+      actual_en: 'Nothing happens, no pressed state',
+      severity: 'S2',
+      kind: 'defect',
+      modes: 'L1 fail / L2 fail / L3 pass',
+      evidence: ['evidence/x.png'],
+    })
+    result = run(['scripts/session.mjs', 'finding', target, '--json', finding])
+    assert(result.status === 0, `finding failed: ${result.stderr}`)
+    assert(result.stdout.includes('F-001'), 'finding did not get an id')
+
+    result = run(['scripts/guard.mjs', 'scan', target])
+    assert(result.status === 0 || result.status === 1, `guard scan crashed: ${result.stderr}`)
+    assert(result.stdout.includes('输入注入观察'), 'guard scan output missing')
+    assert(existsSync(join(target, 'evidence', 'compliance.jsonl')), 'guard did not log compliance')
+
+    result = run(['scripts/report.mjs', 'build', target])
+    assert(result.status === 0, `report failed: ${result.stderr}`)
+    const report = readFileSync(join(target, 'report.md'), 'utf8')
+    assert(report.includes('Observed UI Test Report'), 'report missing title')
+    assert(report.includes('F-001'), 'report missing the finding')
+    assert(report.includes('导出按钮点击无反应'), 'report missing the Chinese title')
+    assert(report.includes('输入注入监控'), 'report missing the injection-watch section')
+    assert(report.includes('No internal pointer directives were used'), 'report missing compliance statement')
+
+    return 'init → gate(block/confirm) → finding → guard → report all behave'
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+await check('cli: capture.mjs exposes no input subcommand and checks availability', () => {
+  const result = run(['scripts/capture.mjs', 'check'])
+  assert(result.status === 0, `capture check failed: ${result.stderr}`)
+  assert(result.stdout.includes('只读捕获自检'), 'capture check output missing')
+  const source = readFileSync(join(packageRoot, 'scripts/capture.mjs'), 'utf8')
+  for (const forbidden of ['SendInput', 'CGEventPost', 'adb shell input', 'input tap']) {
+    assert(!source.includes(forbidden), `capture.mjs must not mention ${forbidden}`)
+  }
+  for (const command of ['shot', 'record', 'check']) {
+    assert(source.includes(`command === '${command}'`), `capture.mjs lost its ${command} command`)
+  }
+  assert(!/command === 'input'/.test(source), 'capture.mjs must not gain an input command')
+  return 'read-only capture CLI verified'
+})
+
+const failed = results.filter((result) => !result.ok)
+for (const result of results) {
+  process.stdout.write(`${result.ok ? 'PASS' : 'FAIL'}  ${result.name}\n`)
+  if (result.detail) {
+    for (const line of String(result.detail).split('\n')) {
+      process.stdout.write(`        ${line}\n`)
+    }
+  }
+}
+process.stdout.write(
+  `\n${results.length - failed.length}/${results.length} checks passed` +
+    ` — 注入能力: 无 / capability to inject input: none\n`,
+)
+process.exitCode = failed.length === 0 ? 0 : 1

package/skills/observed-test-plan/MATRIX.md

@@ -0,0 +1,99 @@
+# 元素清单与用例矩阵 / Inventory and Case Matrix
+
+---
+
+## 一、元素清单 / Element inventory
+
+来源只有一个：**截图上的像素**。/ One source only: the pixels in a screenshot.
+
+| 字段 Field | 说明 Notes |
+| --- | --- |
+| ID | `E-01` 顺序编号 |
+| 界面 Surface | 元素所在的界面/窗口/页面 |
+| 元素 / 工具 Element / tool | 用画面上的名字（按钮上的文字、图标含义） |
+| 类型 Type | 按钮/输入框/菜单/工具栏/列表/表格/滚动区/弹窗/开关/选择器/状态提示/画布工具/导航 |
+| 期望状态 Expected states | 默认·悬停·按下·选中·禁用·加载·错误·空（缺一不可） |
+| 是否常用 Common? | 决定优先级 |
+| 证据 Screenshot | 该元素所在的截图文件名 |
+
+英文对照表头 / English header:
+
+```text
+ID | Surface | Element / tool | Type | Expected states | Priority | Evidence
+```
+
+**反例 / Anti-pattern**：清单里出现"`onSubmit()` 函数"、"`/api/export` 接口"、"`users` 表"——
+这些不是画面元素，说明你去看代码了。删掉。
+
+---
+
+## 二、用例模板 / Case template
+
+```text
+用例 ID：C-012
+标题 / Title：导出当前画布为 PNG
+元素 / Element：E-07 工具栏「导出」按钮
+平台 / Platform：macOS 14.5 · 1920x1080 · 100% · 浅色
+前置 / Preconditions：已打开示例工程 sample-01；无未保存修改
+模式 / Mode：L1 仅鼠标
+步骤 / Steps：
+  1. 移动鼠标到工具栏「导出」按钮，悬停 1 秒，观察是否出现提示
+  2. 单击
+  3. 等待导出面板出现（最多 5 秒）
+期望（画面）/ Expected (on screen)：
+  - 出现模态面板，标题为「导出」；默认选中 PNG；有取消与确认按钮
+  - 悬停时按钮有可见的悬停态；点击时有按下态反馈
+证据 / Evidence：前后各一张截图 + 录屏 mm:ss
+结果 / Result：通过 / 失败 / 未验证
+```
+
+**期望结果的写法 / How to write expectations**：写成"画面上能看见什么"。
+"数据写入成功"不合格；"列表首行出现名为 sample-01 的条目，且状态列显示『已同步』"才合格。
+
+---
+
+## 三、矩阵 / The matrix
+
+```text
+C-012｜E-07 导出按钮｜L1｜P0｜macOS
+C-012｜E-07 导出按钮｜L2｜P1｜macOS
+C-012｜E-07 导出按钮｜L3｜P1｜macOS
+C-020｜E-11 同步开关｜L1｜P0｜iPhone
+C-020｜E-11 同步开关｜L2｜P2｜iPhone（需外接键盘，若无则记"不适用"）
+```
+
+裁剪规则 / Trimming: 不常用的元素（P3）在 L2/L3 可以只跑一次基线；
+但 **P0/P1 必须三级全跑**，因为它们的跨模式差异最有价值。
+P0/P1 must run at all three modes; their cross-mode difference is the highest-value output.
+
+---
+
+## 四、优先级 / Priority
+
+| 级别 | 含义 | 举例 |
+| --- | --- | --- |
+| P0 | 主流程，跑不通软件就没法用 | 打开工程、保存、导出、登录 |
+| P1 | 常用功能与数据正确性 | 列表增删改、搜索、同步、设置生效 |
+| P2 | 边缘与异常 | 空输入、超长文本、无权限、离线、快速重复点击、窗口缩放、iPad 旋转 |
+| P3 | 打磨与一致性 | 动效、间距、深色模式配色、文案、跨端一致性 |
+
+---
+
+## 五、覆盖率怎么算 / Coverage arithmetic
+
+```text
+元素覆盖率 = 已执行用例覆盖的元素数 / 清单元素总数
+模式覆盖率 = 每元素实际执行的模式数 / 计划模式数
+平台覆盖率 = 实际测过的平台数 / 计划平台数
+用例执行率 = 已执行 / 计划
+```
+
+报告里必须给出这四个数，并列出未覆盖项与原因。/ Report all four, with uncovered items and reasons.
+
+---
+
+## 六、抽样策略（用例太多时）/ Sampling when the matrix explodes
+
+1. 先跑**每类元素各一个代表**的冒烟集（10–20 条），找出会崩的地方。
+2. P0 全量，P1 抽样 50%，P2 每类至少 1 条，P3 只跑视觉基线。
+3. 抽样规则必须写在计划里，事后不能改（改了就是选择偏差）。

package/skills/observed-test-plan/PERMISSIONS.md

@@ -0,0 +1,109 @@
+# 权限清单与授予路径 / Permissions and Where to Grant Them
+
+> 本方法只需要**捕获（看）**权限，**永远不需要控制（动）权限**。
+> This method needs **capture (read)** permission and **never** control (inject) permission.
+>
+> 如果某个工具要求"辅助功能/输入监控/自动化"权限才能工作，那它超出了本方法的需要，不要授予。
+> If a tool asks for accessibility, input-monitoring or automation permission, it exceeds what this
+> method needs. Do not grant it.
+
+---
+
+## 一、需要向用户确认的权限 / Permissions to confirm with the user
+
+| 权限 Permission | 必需 Required | 用途 Purpose | 被拒时 If denied |
+| --- | --- | --- | --- |
+| 鼠标操作 Mouse | 必需 | 一切界面操作 | 无法测试 |
+| 键盘操作 Keyboard | 按级别 | L2/L3 的输入与导航 | 只跑 L1，L2/L3 记"未覆盖" |
+| 屏幕录制 Screen recording | 与截屏二选一 | 过程、时序、动效、误触发 | 改用逐步截屏，报告注明"无连续录屏" |
+| 截屏 Screenshot | 与录屏二选一 | 单点状态与元素细节 | 无法取证 → 停止测试 |
+| 麦克风 Microphone | 建议 | 口述操作、对齐录屏时间点 | 改由操作者手写时间点 |
+| 数据边界 Data boundary | 必需 | 避免把隐私录进证据 | 无法保证合规 → 缩小范围或停止 |
+
+---
+
+## 二、macOS
+
+1. **系统设置 → 隐私与安全性 → 屏幕录制**：勾选运行 Harness / 终端 / 录屏工具的应用。
+   授予后**需要重启该应用**才生效。
+2. **麦克风**：系统设置 → 隐私与安全性 → 麦克风（要口述解说时）。
+3. **不需要**：辅助功能（Accessibility）、输入监控（Input Monitoring）、自动化（Automation）。
+   如果你发现被测机器上这些权限给了非必要应用，收回它们。
+4. 光标：`screencapture -v` 录屏默认包含光标；QuickTime 录屏也含。若不含，必须用截屏补记指针位置。
+5. 试拍验证：
+
+```bash
+node scripts/capture.mjs check
+node scripts/capture.mjs shot "<session>" --label permission-probe
+```
+
+首次执行会触发系统权限提示；若返回黑屏或纯桌面图，说明权限未授予或未重启应用。
+
+---
+
+## 三、Windows
+
+1. **设置 → 隐私和安全性 → 屏幕截图和录制**：允许应用访问屏幕。
+2. **游戏栏 / Xbox Game Bar**：设置 → 游戏 → Xbox Game Bar 打开；`Win+G` 由**人手动**触发录制。
+3. **麦克风**：设置 → 隐私和安全性 → 麦克风。
+4. **不需要**：UI Automation 控制、`SendInput` 类自动化权限；不要安装/运行自动化框架。
+5. 只读截屏验证：`node scripts/capture.mjs shot "<session>" --label permission-probe`
+   （走 PowerShell `System.Drawing` 只读截屏，不注入输入）。
+6. 若桌面是远程会话（RDP），画面与真机不同，必须在报告里注明。
+
+---
+
+## 四、iPhone / iPad（iOS / iPadOS）
+
+1. **真机指纹/密码解锁**，并在设备上信任用于录制的电脑（如用 QuickTime 连续互通录制）。
+2. **控制中心 → 屏幕录制**：按住录制按钮可选择是否开启麦克风；开始前确认要录的是整块屏。
+3. **模拟器**：`xcrun simctl io booted screenshot` / `recordVideo` 需要 Xcode 命令行工具，不需要额外授权。
+4. **不必开**：开发者模式（仅当测试你自己的构建、需要安装包时才用，且要写进报告）。
+5. 人用手操作真机；模拟器上人用**真实鼠标**点击模拟器窗口——这不是注入。
+6. 注意 DRM 内容在录制时可能黑屏，这不是缺陷，报告里注明。
+7. 横竖屏、分屏、动态字体大小属于环境变量，测试前固定并记录。
+
+---
+
+## 五、Android 与其他设备 / Android and others
+
+1. `adb exec-out screencap -p`（截屏）、`adb shell screenrecord`（录屏）为只读捕获，允许。
+2. **禁止** `adb shell input ...` 与任何自动化驱动（见 `observed-ui-test` 技能的 BANNED-INPUTS.md）。
+3. 电视/车机/手表：用厂商投屏或采集卡做只读录制，遥控器与触摸由人操作。
+
+---
+
+## 六、英文问卷 / The English questionnaire
+
+```text
+Before the observed UI test starts, please confirm:
+
+[Input]
+1. Mouse: may I base findings on your real mouse actions? (yes / no)
+2. Keyboard: allowed, and up to which mode?
+   A. Mouse only (L1)
+   B. Mouse + keyboard, shortcuts forbidden (L2)
+   C. Mouse + keyboard + shortcuts (L3)
+
+[Capture]
+3. Screen recording: allowed? Include the cursor? (yes / no; with / without cursor)
+4. Screenshots: allowed as evidence at any time? (yes / no)
+5. Microphone: allowed for spoken narration to line up the recording timeline? (yes / no)
+6. OS capture permission:
+   macOS: System Settings -> Privacy & Security -> Screen Recording (restart the app after granting)
+   Windows: Settings -> Privacy & security -> Screenshots and recording / Game Bar
+   iPhone/iPad: Control Centre screen recording (press and hold for the microphone)
+   Which will you grant?
+
+[Scope]
+7. App under test: name, version, platform, devices (macOS / Windows / iPhone / iPad / other)
+8. Scope: which features are in, which are explicitly out
+9. Data boundary: which account/data; what must never appear in a recording (names, phone numbers,
+   keys, production data)
+10. Exit criteria: what makes us stop immediately (crash, data loss, privacy leak, production damage)
+
+[Compliance]
+This test uses no internal pointer directives: no injected pointer, touch or key events, no UI
+automation drivers, no calls into the software's internals. Input comes only from your real
+peripherals; evidence comes only from screen recording and screenshots. Do you confirm? (yes / no)
+```

package/skills/observed-test-plan/PLAN-TEMPLATE.md

@@ -0,0 +1,93 @@
+# 观察式界面测试计划 / Observed UI Test Plan
+
+> 计划阶段产物，中英对照。测试目录里的 `matrix.md` / `elements.md` 由脚手架生成。
+> Phase-one artifact, bilingual. The session directory's `matrix.md` / `elements.md` come from the
+> scaffold.
+
+---
+
+## 1. 目标 / Objective
+
+本次要回答的问题（写成可判定的问题）/ The questions this run must answer:
+
+1.
+2.
+3.
+
+不回答的问题（明确排除）/ Explicitly out of scope:
+
+-
+
+## 2. 被测对象 / System under test
+
+| 项目 Item | 内容 Value |
+| --- | --- |
+| 应用 App | |
+| 版本 / 构建 Version / Build | |
+| 平台 Platform | macOS / Windows / iPhone / iPad / other |
+| 设备 Device | 型号 + 系统版本 |
+| 安装方式 Install source | 应用商店 / 安装包 / 开发构建 / 模拟器 |
+| 关键依赖 Dependencies | 网络、账号、外部设备 |
+
+## 3. 测试环境 / Environment
+
+分辨率与缩放 · 深色/浅色 · 动态字体大小 · 语言与区域 · 网络状态（在线/弱网/离线） ·
+外接屏数量 · iPad 方向与分屏状态。
+
+## 4. 权限与合规 / Permissions and compliance
+
+| 项目 Item | 值 Value |
+| --- | --- |
+| 鼠标 Mouse | yes / no |
+| 键盘 Keyboard | L1 / L2 / L3 |
+| 屏幕录制 Screen recording | yes / no（含光标 / 不含） |
+| 截屏 Screenshot | yes / no |
+| 麦克风 Microphone | yes / no |
+| 数据边界 Data boundary | |
+| 内部指针指令 Internal pointer directives | **不使用 / none** |
+| 硬件宏或系统辅助 Hardware macro / OS assist | 无 / 有（说明） |
+
+## 5. 范围与优先级 / Scope and priority
+
+P0：
+P1：
+P2：
+P3（抽样）：
+
+## 6. 排期 / Schedule
+
+| 阶段 Phase | 内容 | 预计时长 |
+| --- | --- | --- |
+| 准备 Preparation | 权限、清单、矩阵 | |
+| L1 | 仅鼠标全量 | |
+| L2 | 无快捷键全量 | |
+| L3 | 快捷键 + 双路径一致性 | |
+| 汇总 Report | 判定、报告、复测建议 | |
+
+## 7. 退出与中止条件 / Exit and abort criteria
+
+**立即中止 / Abort immediately**：崩溃且无法恢复、数据损坏、隐私内容进入画面、误改生产数据、
+设备过热或异常。
+
+**提前结束 / End early**：S1 阻断导致主流程完全不可用（先出中间报告）。
+
+## 8. 角色与产出 / Roles and artifacts
+
+| 角色 Role | 人 Person |
+| --- | --- |
+| 操作者 Operator | |
+| 观察者 Observer | |
+| 记录者 Recorder | |
+| 裁决者 Adjudicator | |
+
+产出 / Artifacts：会话目录（`session.json`、`elements.md`、`matrix.md`、`findings.jsonl`、
+`evidence/`）与最终 `report.md`。
+
+## 9. 风险 / Risks
+
+| 风险 Risk | 影响 | 缓解 Mitigation |
+| --- | --- | --- |
+| 无录屏权限 | 过程类缺陷无法取证 | 逐步截屏 + 操作者口述时间点 |
+| 只有一台设备 | 跨端一致性无法验证 | 标"未验证"，列入下一轮 |
+| 用例太多 | 跑不完 | 按抽样规则裁剪并写明 |
+| 真实数据 | 隐私风险 | 用测试账号与演示数据 |

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

@@ -0,0 +1,135 @@
+---
+name: observed-test-plan
+description: 观察式界面测试的测试前准备：向用户发出鼠标、键盘、录屏、截屏与软硬件权限问卷，确定被测范围与三级模式，只看画面建立功能元素清单，排出用例矩阵与优先级，并用脚手架脚本生成会话目录。Observed UI testing, preparation phase: ask the user the mouse/keyboard/screen-recording/screenshot and OS-permission questionnaire, pin scope and the three input modes, build the on-screen element inventory, and lay out the case matrix, generating the session scaffold.
+---
+
+# 测试前准备 / Test Preparation
+
+这是 `observed-ui-test` 的第一阶段：**在碰软件之前**把权限、范围、元素清单和用例矩阵定下来。
+没有这一步，后面的缺陷会无法复现、覆盖会说不清。
+
+The phase before touching the app: pin permissions, scope, inventory and matrix. Skip it and the
+later defects will not reproduce and coverage cannot be explained.
+
+---
+
+## 1. 权限问卷（先问，必须问全）/ The permission questionnaire (ask first, ask all)
+
+把下面整段发给用户，等他逐条回答后再动。/ Send the whole block, wait for answers:
+
+```text
+开始观察式界面测试前，需要你确认以下几项权限与边界：
+
+【输入权限】
+1. 鼠标：允许使用真实鼠标操作并据此判定吗？（yes / no）
+2. 键盘：允许使用键盘吗？到哪一级？
+   A. 仅鼠标（L1）
+   B. 鼠标 + 键盘，但不许使用快捷键（L2）
+   C. 鼠标 + 键盘 + 快捷键（L3）
+
+【取证权限】
+3. 屏幕录制：允许录屏吗？录屏里要不要包含光标？（yes / no；含光标 / 不含）
+4. 截屏：允许随时截屏作为证据吗？（yes / no）
+5. 麦克风：允许口述操作解说、方便定位录屏时间点吗？（yes / no）
+6. 系统捕获权限：
+   macOS：系统设置 → 隐私与安全性 → 屏幕录制（授予后需重启应用）
+   Windows：设置 → 隐私和安全性 → 屏幕截图和录制 / 游戏栏
+   iPhone/iPad：控制中心录屏（长按可开麦克风）；如用模拟器则无需此步
+   你愿意授予哪些？（逐项回答）
+
+【测试范围】
+7. 被测应用：名称、版本、平台、设备（macOS / Windows / iPhone / iPad / 其他）
+8. 本次范围：要测哪些功能；哪些明确不测
+9. 数据边界：用哪个账号/数据；哪些内容绝对不能录进画面（真实姓名、手机号、密钥、生产数据）
+10. 退出条件：出现什么情况立即停止（崩溃、数据损坏、隐私泄露、误删生产数据）
+
+【合规声明】
+本次测试不会使用任何内部指针指令：不注入鼠标/触摸/按键事件，不驱动自动化框架，
+不调用软件内部句柄。输入只来自你的真实外设；证据只来自录屏与截屏。
+你是否确认这一点？（yes / no）
+```
+
+English version of the same questionnaire is in [PERMISSIONS.md](PERMISSIONS.md)；平台权限的具体授予
+路径与"没权限时怎么办"也在那里。
+
+Rules:
+- `screenRecording` 与 `screenshot` **至少一个为 yes**，否则无法进行观察式测试，直接停下并说明。
+- 任何一项回答"待定"→ 不要开始，先把待定项变成明确答复。
+- 拒绝的项记录在案，不允许绕过、不允许"偷偷用一下"。
+
+---
+
+## 2. 范围六项 / The six scope fields
+
+被测应用名+版本+构建号 · 平台与设备 · 输入设备 · 显示环境（分辨率/缩放/深浅色/动态字体） ·
+数据边界 · 退出条件。写进 `session.json` 的 `scope`，见 [PLAN-TEMPLATE.md](PLAN-TEMPLATE.md)。
+
+---
+
+## 3. 只看画面建元素清单 / Element inventory from the screen only
+
+1. 打开被测软件，把每个界面截图（用 `scripts/capture.mjs shot`）。
+2. 对着截图列出**看得见**的功能元素与工具：按钮、输入框、菜单、工具栏、列表、弹窗、
+   开关、选择器、状态提示、画布与工具、导航。
+3. 每个元素写全期望状态：默认 / 悬停 / 按下 / 选中 / 禁用 / 加载 / 错误 / 空。
+4. **不许**打开代码、DOM 检查器、日志或数据库来补全清单；那些是线索不是清单来源。
+
+产出一张 `elements.md`（脚手架已生成表头）。
+
+---
+
+## 4. 用例矩阵与优先级 / Case matrix and priority
+
+矩阵 = 元素 × 平台 × 模式（L1/L2/L3）。规则与样例见 [MATRIX.md](MATRIX.md)。
+每条用例的"期望结果"必须是**画面上能看到的东西**。优先级 P0 主流程 → P1 常用与数据 → P2 边缘异常 →
+P3 打磨一致性；P2 至少覆盖空输入、超长输入、无权限、离线、快速重复点击、窗口缩放/旋转。
+
+---
+
+## 5. 生成会话脚手架 / Generate the session scaffold
+
+```bash
+node <skill-directory>/../scripts/session.mjs init ./ui-test-<app>-<date> \
+  --platform macos --app "<应用名>" --levels L1,L2,L3 --tester "<操作者>"
+```
+
+生成 / Creates:
+
+```text
+ui-test-<app>-<date>/
+├── session.json          # 闸门、范围、平台、级别、权限记录
+├── permissions.md        # 权限问卷与答复存根（中英对照）
+├── elements.md           # 元素清单表头
+├── matrix.md             # 用例矩阵表头
+├── findings.jsonl        # 一条缺陷一行
+├── report.md             # 报告初稿
+└── evidence/             # 截图与录屏
+```
+
+记录权限答复 / Record the answers:
+
+```bash
+node <skill-directory>/../scripts/session.mjs gate ./ui-test-<app>-<date> \
+  --mouse yes --keyboard L2 --screen-recording yes --screenshot yes \
+  --microphone no --os-permission yes --cursor yes --data-boundary "仅测试账号"
+```
+
+闸门未通过时不要开始测试；`status` 会告诉你还缺什么：
+`node <skill-directory>/../scripts/session.mjs status ./ui-test-<app>-<date>`。
+
+---
+
+## 6. 准备完成检查表 / Readiness checklist
+
+- [ ] 权限问卷逐条有明确答复，并已落盘
+- [ ] 至少一种取证方式可用（录屏或截屏），且已实际试拍成功
+- [ ] 范围六项写全，退出条件写清
+- [ ] 元素清单来自截图，不是来自代码
+- [ ] 每个元素的期望状态列全
+- [ ] 用例矩阵覆盖 P0 与 P2 的最低要求
+- [ ] 被测机器上自动化工具、宏软件全部退出；辅助功能权限未授予任何非必要应用
+- [ ] 已跑 `guard.mjs scan <session>`，注入线索已落盘（只读观察，不执行注入）
+- [ ] 操作者与观察者分工确认（谁操作、谁读图、谁记录）
+
+全部打勾后，切到 `observed-ui-test` 技能开始按 L1 → L2 → L3 执行。
+When every box is ticked, switch to the `observed-ui-test` skill and run L1 → L2 → L3.