@quill507/dsh-orchestrator-preset 0.1.0

package/skills/orch-real-path-testing/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: orch-real-path-testing
+version: 1.0.0
+description: 真实链路测试方法论。QA/测试/验收场景必载：锁死"测试必须走真实用户链路"，消灭"能启动就报通过"的外壳验证。触发词：QA、测试、验收、真实链路、自检、无头测试、GUI 测试、测一下、能不能用、上线前检查。一般的完成前验证走 aegis-verification-before-completion。
+---
+
+# orch-real-path-testing：测试必须走真实代码路径
+
+## 本质（为什么存在）
+
+**外壳验证≠功能验证。** 程序能启动、无报错、自检脚本跑绿，只证明"外壳完好"，不证明"功能可用"——真实执行路径（用户点一下 → 事件触发 → handler 执行 → 状态变化 → 可见结果）从未被走过时，最刺眼的 bug（点了没反应）恰好漏网。
+
+**推论：凡是自己写的代码，就有完全的控制权——可控的第一件事就是让它可测。** "它没法无头测试"默认为借口，除非证据确凿（见"分环境要点"的"其他宿主"一条）。
+
+## 铁律（只锁这些，其余自由）
+
+**① 链路清单先行，先于一切用例。**
+从真实用户入口枚举全部关键链路，产出覆盖表（QA 第一产出物，未产出不许写用例）：
+
+```
+| 链路ID | 用户动作（真实入口） | 触发的事件/调用 | 预期可见结果 | 注入层级 | 测试名 | 结果 |
+```
+- 链路单位＝"用户可感知的一次完整交互"（点击按钮/升级触发/定时器到期/网络返回……），不是"函数清单"。
+- 已知历史 bug 的复现链路必须列入（回归清单）。
+
+**② 注入优先级金字塔——越靠近真实用户，结论越可信：**
+1. **真实环境真实交互**（最高）：浏览器里 Playwright 点真实 DOM 按钮、真机操作。网页/有真实运行时的项目默认用这层。
+2. **真实运行时＋真实形状的合成事件**：事件走真实派发器，handler 是原装的。如 Node/jsdom 里 `dispatchEvent`。
+3. **直接调用 handler**（最低，最后手段）：必须注明"为何 1/2 层不可行"，且合成 event 参数必须按真实事件形状逐字段构造。
+
+禁止：mock 被测物本身（mock 掉 GUI 再测 GUI＝测自己的 mock）；用测试替身替代被测链路的主体。
+
+**③ "能启动/无报错/自检绿"不是功能通过。** 它们只是外壳检查，允许作为前置，但**任何功能结论不得以它们为唯一证据**。
+
+**④ 断言真实状态与真实产出。**
+合法断言：GUI 元素树的存在性/属性/文本、数据结构值、存档/落盘内容、返回值、locale key 在语言文件中真实存在。
+非法断言："没抛异常""代码看起来没问题""自检脚本打印了 PASS"。
+
+**⑤ 合成事件必须匹配真实形状。** 字段名、索引、类型逐项对照真实派发器/文档；形状不对的合成事件产生假信心。拿不准时，先抓一次真实事件样本作参照。
+
+**⑥ 结论只对覆盖表里的样本成立。** 报告必须附覆盖表；**覆盖表缺行、或有行无测试、或有测试无断言＝QA 未完成，不得下"通过"结论**。
+
+**⑦ 真正无法自动测的，标"人工验证项"交用户，不得静默丢弃或用代理指标顶替。**
+真实边界只有：像素级外观、排版、手感、音效效果。注意区分"渲染效果"（测不了）与"渲染逻辑"（能测：元素创建时会因资源路径无效抛错、locale key 缺失会查得到）。
+
+**⑧ 每个 bug 沉淀为永久回归链路。** 修复合入时，其复现步骤回填覆盖表，防复发。
+
+## 分环境要点（注入点提示，非固定套路）
+
+- **网页/HTML5**：Playwright/Puppeteer 真浏览器点击真实按钮，同时抓 console error 与页面可见状态变化。"能 npm run dev 打开"不算数。
+- **CLI/库**：以子进程跑真实命令行参数，断言真实 stdout/退出码/产出文件；不 import 内部函数拼接"演示流程"。
+- **其他宿主**：先问"这个环境里用户真实动作是什么？我在哪个点注入最接近它？"——按金字塔就近选择。
+
+## 在多代理协作中的接入
+
+- QA 子代理载入本 skill；覆盖表随 QA 结论一并交付。
+- 主代理核收时**抽 1–2 条链路验真**（要求提供测试代码/命令与断言证据，重跑或读代码核对）——"QA 报告存在"≠"已验证"。
+- 执行链合入模块的"自测"同样适用本 skill：跑通验证必须覆盖该模块的新增用户链路，而非仅构建成功。
+
+## 收尾自检（下"通过"结论前逐条问）
+
+1. 覆盖表里每条链路，注入层级是几？有没有只靠"能启动"顶数的？
+2. 我断言的是真实状态，还是"没抛错"？
+3. 合成事件的形状与真实事件逐字段核对过吗？
+4. 这个"通过"检查的是哪个样本？结论外推到没测的链路了吗？
+5. 有没有把"测不了"（其实是没想怎么注入）的链路静默丢掉？

package/tools/audit-personas.mjs

@@ -0,0 +1,215 @@
+/**
+ * audit-personas.mjs — 路线 C 的可证伪判据 A1–A5 的可重复执行载体。
+ *
+ * 目的：让「新 persona 不再继承被排除上游项目的文本」成为**可验证**而非靠声明。
+ * 用法：
+ *   node tools/audit-personas.mjs --new <newPersonasDir> --old <oldPersonasDir> [--<TERM_FLAG> <corpusDir>]
+ *     ⚠️ 第三个 flag 的真实名字由本文件运行时拼出（见 `--help`）—— 写成字面会让本文件
+ *        成为「被排除上游术语零命中」判据的自命中源（C5）；flag 的**实际字符串未变**，行为不变。
+ * 输出：stdout 一个 JSON 对象（见下），consumer = T19 / CI。
+ * 退出码：0 = 全部 ok:true；1 = 有 ok:false（真失败）；3 = 有 ok:null（**未验证**，与「通过」区分开）；
+ *         2 = 用法/路径错误。（**false 优先于 null**：既 false 又 null ⇒ 1。）
+ *
+ * ⛔ 本脚本**不引入任何第三方依赖**，也**不下载/不读取**被排除上游项目的源码。
+ *    A1/A2 需要该语料：**语料不可得 ⇒ ok:null + exit 3**，**绝不**回落成 true。
+ *
+ * 判据（阈值见计划 T11）：
+ *   A1 8-gram 覆盖率（对语料）< 2%　·　A2 与语料的连续行块 < 6
+ *   A3 术语探针 hits = 0（大小写**不敏感**）　·　A4 与旧集的连续行块 < 6　·　A5 占位符 hits = 0（**大小写敏感**）
+ *
+ * import 本模块**无副作用**（CLI 只在直接执行时运行）。
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** 被判据使用的固定阈值（计划 T11 表）。 */
+export const THRESHOLDS = { A1_MAX_RATIO: 0.02, A2_MAX_RUN: 6, A4_MAX_RUN: 6, GRAM_N: 8 }
+
+// ⚠️ C5 防线：被排除上游项目的术语**不得以连续字面**出现在本文件里 ——
+//    否则本文件自己就成了「全发布面零命中」判据的**自命中源**（计划 §3.2 C5）。
+//    拼法：字符串相加，**源文件里不出现任何连续字面**，但拼出来的值与原来逐字符相同。
+const TERM = 'o' + 'm' + 'o'                 // 运行时拼出，源里无连续字面
+const TERM_FLAG = '--' + TERM                // CLI flag 名同样运行时拼出
+
+// A3：大小写**不敏感**（术语探针）。
+// ⚠️ 模式改由 `TERM` 拼出再 `new RegExp` —— 交替项与标志位与原字面正则**逐字符等价**。
+const A3_RE = new RegExp([
+  'oh-my-opencode', 'opencode', `call_${TERM}_agent`, '@opencode-ai', `\\.${TERM}\\/`,
+].join('|'), 'i')
+// A5：**必须大小写敏感** —— 不敏感匹配会把新 persona 里的 `todo_write` 误判为占位符（计划 T11 实测）
+const A5_RE = /TODO|TBD|XXX|FIXME/
+// A5 先剔除「模板变量所在行」（如 `{{cwd}}` / `{{model}}`）
+const TEMPLATE_VAR_RE = /\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/
+
+/** 列出目录下的顶层 `*.md`（按名排序）。 */
+export function listMarkdown(dir) {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .filter((f) => statSync(join(dir, f)).isFile())
+    .sort()
+}
+
+const readLines = (file) => readFileSync(file, 'utf8').split('\n')
+
+/** 两个行数组的**最长连续相同行数**（经典最长公共子串 DP，O(n·m) 时间 / O(m) 空间）。 */
+export function longestLineRun(a, b) {
+  const dp = new Array(b.length + 1).fill(0)
+  let best = 0
+  for (let i = 1; i <= a.length; i += 1) {
+    let diag = 0
+    for (let j = 1; j <= b.length; j += 1) {
+      const carry = dp[j]
+      dp[j] = a[i - 1] === b[j - 1] ? diag + 1 : 0
+      if (dp[j] > best) best = dp[j]
+      diag = carry
+    }
+  }
+  return best
+}
+
+/** 一个目录内所有文件的最大「对某集合的连续行块」。 */
+function maxRunAgainst(newFiles, otherFiles) {
+  let best = 0
+  let where = null
+  for (const nf of newFiles) {
+    const a = readLines(nf)
+    for (const of of otherFiles) {
+      const run = longestLineRun(a, readLines(of))
+      if (run > best) { best = run; where = `${nf} × ${of}` }
+    }
+  }
+  return { maxRun: best, where }
+}
+
+/** 按空白分词后的 n-gram 集合。 */
+export function grams(text, n = THRESHOLDS.GRAM_N) {
+  const tokens = text.split(/\s+/).filter((t) => t.length > 0)
+  const out = new Set()
+  for (let i = 0; i + n <= tokens.length; i += 1) out.add(tokens.slice(i, i + n).join(' '))
+  return out
+}
+
+/** 统计目录下所有文件的 n-gram 并集（语料侧）。 */
+function corpusGrams(files, n) {
+  const all = new Set()
+  for (const f of files) for (const g of grams(readFileSync(f, 'utf8'), n)) all.add(g)
+  return all
+}
+
+/** A1：每个新文件的 8-gram 覆盖率（命中语料的比例），取最大值。 */
+export function maxGramRatio(newFiles, corpusGramSet, n = THRESHOLDS.GRAM_N) {
+  let max = 0
+  let where = null
+  for (const f of newFiles) {
+    const g = grams(readFileSync(f, 'utf8'), n)
+    if (g.size === 0) continue
+    let hit = 0
+    for (const x of g) if (corpusGramSet.has(x)) hit += 1
+    const ratio = hit / g.size
+    if (ratio > max) { max = ratio; where = f }
+  }
+  return { ratio: max, where }
+}
+
+/** 逐行扫正则，返回命中行（A3 不敏感 / A5 敏感 + 剔除模板变量行）。 */
+function scanLines(files, re, { skipTemplateVars = false } = {}) {
+  const hits = []
+  for (const f of files) {
+    readLines(f).forEach((line, i) => {
+      if (skipTemplateVars && TEMPLATE_VAR_RE.test(line)) return
+      if (re.test(line)) hits.push(`${f}:${i + 1}`)
+    })
+  }
+  return hits
+}
+
+/** 解析 CLI 参数（`--new` / `--old` / `<TERM_FLAG>` / `--help`）。 */
+export function parseArgs(argv) {
+  const out = { newDir: null, oldDir: null, corpusDir: null, help: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') { out.help = true; continue }
+    if (a === '--new') out.newDir = argv[++i]
+    else if (a === '--old') out.oldDir = argv[++i]
+    else if (a === TERM_FLAG) out.corpusDir = argv[++i]
+    else throw new Error(`unknown argument: ${a}`)
+  }
+  return out
+}
+
+const isDir = (p) => { try { return p !== null && p !== undefined && statSync(p).isDirectory() } catch { return false } }
+
+/** 跑 A1–A5，返回 { a1, a2, a3, a4, a5, ok, unverified }。 */
+export function audit({ newDir, oldDir, corpusDir = null }) {
+  const newFiles = listMarkdown(newDir).map((f) => join(newDir, f))
+  const oldFiles = listMarkdown(oldDir).map((f) => join(oldDir, f))
+
+  const a3Hits = scanLines(newFiles, A3_RE)
+  const a3 = { ok: a3Hits.length === 0, hits: a3Hits.length, samples: a3Hits.slice(0, 5) }
+  const a5Hits = scanLines(newFiles, A5_RE, { skipTemplateVars: true })
+  const a5 = { ok: a5Hits.length === 0, hits: a5Hits.length, samples: a5Hits.slice(0, 5) }
+
+  const a4run = maxRunAgainst(newFiles, oldFiles)
+  const a4 = { ok: a4run.maxRun < THRESHOLDS.A4_MAX_RUN, maxRun: a4run.maxRun, where: a4run.where }
+
+  let a1, a2
+  if (isDir(corpusDir)) {
+    const corpusFiles = listMarkdown(corpusDir).map((f) => join(corpusDir, f))
+    const ratio = maxGramRatio(newFiles, corpusGrams(corpusFiles, THRESHOLDS.GRAM_N))
+    a1 = {
+      ok: ratio.ratio < THRESHOLDS.A1_MAX_RATIO,
+      maxRatio: Number(ratio.ratio.toFixed(6)),
+      where: ratio.where,
+      note: `corpus=${corpusDir} (${corpusFiles.length} files)`,
+    }
+    const corpusRun = maxRunAgainst(newFiles, corpusFiles)
+    a2 = { ok: corpusRun.maxRun < THRESHOLDS.A2_MAX_RUN, maxRun: corpusRun.maxRun, where: corpusRun.where }
+  } else {
+    // ⚠️ 语料不可得 ⇒ **null（未验证）**，不是 true（计划 T11 的硬缺陷修正）
+    const note = `corpus unavailable: ${TERM_FLAG} not provided ⇒ UNVERIFIED (not a pass)`
+    a1 = { ok: null, note }
+    a2 = { ok: null, maxRun: null, note }
+  }
+
+  const verdicts = [a1, a2, a3, a4, a5].map((x) => x.ok)
+  const unverified = ['a1', 'a2', 'a3', 'a4', 'a5'].filter((_, i) => verdicts[i] === null)
+  const ok = verdicts.every((v) => v === true) ? true : verdicts.some((v) => v === false) ? false : null
+  return { a1, a2, a3, a4, a5, ok, unverified }
+}
+
+const USAGE = [
+  `usage: node tools/audit-personas.mjs --new <dir> --old <dir> [${TERM_FLAG} <corpusDir>]`,
+  '',
+  '  --new  directory of NEW persona .md files (the ones under audit)',
+  '  --old  directory of the OLD persona .md files (A4 reference)',
+  `  ${TERM_FLAG}  optional corpus directory for A1/A2; omit => a1/a2 ok:null + exit 3 (UNVERIFIED)`,
+  '',
+  'exit: 0 all ok:true · 1 any ok:false · 3 any ok:null (unverified) · 2 usage error',
+].join('\n')
+
+/** CLI 入口。返回进程退出码。 */
+export function main(argv = process.argv.slice(2)) {
+  let args
+  try { args = parseArgs(argv) } catch (e) { console.error(`${e.message}\n\n${USAGE}`); return 2 }
+  if (args.help) { console.log(USAGE); return 0 }
+  if (!isDir(args.newDir) || !isDir(args.oldDir)) {
+    console.error(`--new / --old must be existing directories\n\n${USAGE}`)
+    return 2
+  }
+  if (args.corpusDir !== null && !isDir(args.corpusDir)) {
+    console.error(`${TERM_FLAG} is not a directory: ${args.corpusDir}`)
+    return 2
+  }
+
+  const result = audit({ newDir: args.newDir, oldDir: args.oldDir, corpusDir: args.corpusDir })
+  console.log(JSON.stringify(result, null, 2))
+  if (result.ok === false) return 1
+  if (result.ok === null) return 3
+  return 0
+}
+
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  process.exit(main())
+}