aihand 0.0.1 → 0.1.0

package/src/ui/core/diff.ts

@@ -0,0 +1,253 @@
+import type { DiffResult, ErrorEntry, LogEntry, NetworkRequest, RawState, RegionDigest, ScreenSnap } from './types'
+import { isSecretKey, redactSecretValue } from './candidates'
+
+// The DOM-only view-change judge. A human knows "the page changed" without reading any store —
+// they see the page's main body get replaced. before/after are the >5% viewport region digests.
+//
+// What separates "navigated to another view" from "opened a modal" is GONE, not appeared. A modal
+// overlays the page: the old regions all REMAIN underneath (gone≈0), it only ADDS. Navigation
+// replaces part of the body: some old regions vanish. Live-measured on chat (the outer shell —
+// html/body/sidebar/main container — is shared across views, so it's never all-or-nothing):
+//   chat→im   gone 9/23=0.39, appeared 3   → view change
+//   im→chat   gone 3/13=0.23, appeared 9   → view change
+//   open 设置  gone 1/23=0.04, appeared 15  → modal (NOT a view change — gone stays ~0)
+// So: gone/before past a low floor (the shared shell keeps it modest, 0.15 sits in the safe gap
+// between modal's 0.04 and navigation's 0.23) AND appeared>0 (guards pure removal — closing a
+// panel drops regions with nothing new). Full-page scroll isn't defended — it's a human gesture,
+// never inside an action's before/after. The first cut required a symmetric 30%-both gate and漏判
+// the asymmetric real shape; the second over-corrected to gone≥50% and漏判 the shared-shell dilution.
+const GONE_FRAC = 0.15
+export function regionsChanged(before: RegionDigest[], after: RegionDigest[]): boolean {
+    if (!before.length || !after.length)
+        return false
+    const afterKeys = new Set(after.map(r => r.key))
+    const beforeKeys = new Set(before.map(r => r.key))
+    const gone = before.filter(r => !afterKeys.has(r.key)).length
+    const appeared = after.filter(r => !beforeKeys.has(r.key)).length
+    return gone >= before.length * GONE_FRAC && appeared > 0
+}
+
+// A big region appeared (or vanished) WITHOUT a navigation or a modal — an autocomplete dropdown,
+// a popover, an inline expansion, a toast. regionsChanged only fires on navigation (gone≥15%); a
+// pure ADD has gone≈0, so it slips through every diff branch and the action reads as "no state
+// change" even though a 11-item suggestions list is now on screen (live: Wikipedia fill → dropdown
+// at ~40ms, 30% viewport, reported nothing). A human watching would say "a list appeared" — this
+// recovers exactly that. Returns the appeared region's cheap label (role/tag + child count), or the
+// vanished one's, so the delta is self-sufficient (the agent learns there's a thing to click /
+// dismiss without a second /screen). Caller only consults this when nav & modal both said nothing.
+// A child-bearing region (≥2 blocks) is a structural layer — a list, menu, card stack. A bare or
+// single-child region that merely changed size is reflow jitter (an input growing, a wrapper
+// resizing), keyed differently but not a new layer. Require structure to fire.
+const POPOVER_MIN_CHILDREN = 2
+export function popoverChange(before: RegionDigest[], after: RegionDigest[]): string | undefined {
+    const beforeKeys = new Set(before.map(r => r.key))
+    const afterKeys = new Set(after.map(r => r.key))
+    const appeared = after.filter(r => !beforeKeys.has(r.key))
+    const gone = before.filter(r => !afterKeys.has(r.key))
+    // Most-childful changed region = the meaningful one (a list/menu, not a reflowed wrapper).
+    const top = (rs: RegionDigest[]) => rs.reduce<RegionDigest | undefined>((m, r) => !m || childCount(r) > childCount(m) ? r : m, undefined)
+    // Net add (a true overlay adds a layer; a reflow swaps one key for another, appeared≈gone) — and
+    // the layer must have structure. Together these reject the size-jitter false positive.
+    const add = top(appeared)
+    if (appeared.length > gone.length && add && childCount(add) >= POPOVER_MIN_CHILDREN)
+        return `panel: appeared (${add.label})`
+    const rm = top(gone)
+    if (gone.length > appeared.length && rm && childCount(rm) >= POPOVER_MIN_CHILDREN)
+        return `panel: dismissed (${rm.label})`
+    return undefined
+}
+
+// childcount is the `#N` suffix the region key already carries — parse it back for ranking.
+function childCount(r: RegionDigest): number {
+    const i = r.key.lastIndexOf('#')
+    return i < 0 ? 0 : Number(r.key.slice(i + 1)) || 0
+}
+
+// The change a single action caused: the state-machine transition (view/modal/focus)
+// plus any errors/failed requests it triggered. AI reads "what moved", then drills into
+// /ui or /dom for detail if it needs more — the response carries the delta, not a snapshot.
+// Pure: caller passes before/after snaps and the already-diffed error/request deltas.
+export function diffScreen(
+    before: ScreenSnap,
+    after: ScreenSnap,
+    newErrors: LogEntry[],
+    newExceptions: ErrorEntry[],
+    newFailedRequests: NetworkRequest[],
+): string[] {
+    const lines: string[] = []
+    // Track whether a body/modal transition was named — a popover appearance is the fallback only
+    // when nav & modal said nothing (else it'd double-report a body replacement or a dialog open).
+    let bodyOrModalNamed = false
+    if (after.view !== before.view) {
+        lines.push(`view: ${before.view} → ${after.view}`)
+        bodyOrModalNamed = true
+    }
+    // DOM-only fallback: the app didn't inject __AIPEEK_VIEW__ (both frames '(unknown)'), so the
+    // store-projected view name is blind. Infer view-change from the page body being replaced —
+    // honest precision: we can't name the new view, only report it changed. Skipped when the app
+    // DID name the view (the branch above already showed chat→im) — store name wins, no dup.
+    // Also skipped while a modal is open (after.modal !== 'none'): an open dialog overlays and
+    // reflows the body, and its content keeps rendering for several frames after it appears — every
+    // such frame churns big regions (live: settle frames mid-open cross the 0.15 floor) but that's
+    // the modal, not navigation. A human with a dialog open reads the dialog, never says "the page
+    // changed". The `modal: opened` line names it. View-change inference only has meaning with no
+    // modal covering the page. A more specific transition wins (ker 诊断 ⊆ ker 动作).
+    else if (before.view === '(unknown)' && after.modal === 'none' && regionsChanged(before.regions ?? [], after.regions ?? [])) {
+        lines.push('view: changed (DOM 区域指纹)')
+        bodyOrModalNamed = true
+    }
+    if (after.modal !== before.modal) {
+        if (after.modal === 'none')
+            lines.push(`modal: closed (${before.modal})`)
+        else if (before.modal === 'none')
+            lines.push(`modal: opened ${after.modal}`)
+        else
+            lines.push(`modal: ${before.modal} → ${after.modal}`)
+        bodyOrModalNamed = true
+    }
+    // Popover/dropdown/toast: a big region appeared or vanished that's neither a nav nor a modal.
+    // Only the fallback — nav & modal are more specific and already named the body change.
+    if (!bodyOrModalNamed) {
+        const pop = popoverChange(before.regions ?? [], after.regions ?? [])
+        if (pop)
+            lines.push(pop)
+    }
+    if (after.focus !== before.focus)
+        lines.push(`focus: ${after.focus}`)
+    // The app's domain state machine (from __AIPEEK_SCREEN__) — these transitions are
+    // the ones a DOM-only projector can't see (流式 false → true never touches the DOM).
+    const beforeDomain = before.domain ?? {}
+    const afterDomain = after.domain ?? {}
+    for (const key of new Set([...Object.keys(beforeDomain), ...Object.keys(afterDomain)])) {
+        const b = redactDomain(key, beforeDomain[key])
+        const a = redactDomain(key, afterDomain[key])
+        if (b !== a)
+            lines.push(`${key}: ${b} → ${a}`)
+    }
+    for (const e of newErrors)
+        lines.push(`+error: ${e.text}`)
+    for (const e of newExceptions)
+        lines.push(`+exception: ${e.message}`)
+    for (const r of newFailedRequests)
+        lines.push(`+failed: ${r.method} ${r.url} → ${r.status || 'failed'}`)
+    return lines
+}
+
+// An async action (send a message → think → stream → done) is a *trajectory* through the
+// state machine, not a single transition. diffScreen has a 2-point domain — it collapses the
+// whole trajectory to its first and last frame. traceFlow lifts that to N frames: it applies
+// diffScreen to each adjacent pair and stamps the elapsed time, so the output reads as
+//   @0ms     流式中: false → true
+//     ╎ 230ms
+//   @230ms   思考中: false → true
+//     ╎ 870ms
+//   @1100ms  思考中: true → false
+// i.e. the state changes AND the Δt between them. It owns no diff logic of its own — strip the
+// time stamping and it IS diffScreen. Frames are pre-sampled by the caller (waitForStable's
+// MutationObserver, one per real DOM-change burst), each carrying ms since the action started.
+//
+// Returns [] unless the trajectory has at least TWO distinct timed transitions. A flow whose whole
+// movement happens in a single burst (a dialog opening: one @t group, no ╎ Δt) is exactly what the
+// 2-frame `--- changed ---` already shows — emitting it again as a degenerate one-line "flow" is
+// pure noise. The Δt between transitions IS the reason flow exists; with fewer than two timed
+// transitions there's no Δt to show, so it degrades to "no flow" and the caller omits the section.
+const MAX_FLOW_FRAMES = 40
+
+export function traceFlow(frames: { snap: ScreenSnap, t: number }[]): string[] {
+    // Bound the trajectory: a very long stream can emit many domain-change frames. Keep the
+    // head (where it starts) and the tail (where it lands), drop the dense middle — but say so,
+    // never silently truncate (the diagnostic-fiber law: a clipped trace must announce the clip).
+    let kept = frames
+    let dropped = 0
+    if (frames.length > MAX_FLOW_FRAMES) {
+        const head = Math.ceil(MAX_FLOW_FRAMES / 2)
+        const tail = MAX_FLOW_FRAMES - head
+        dropped = frames.length - MAX_FLOW_FRAMES
+        kept = [...frames.slice(0, head), ...frames.slice(frames.length - tail)]
+    }
+
+    const lines: string[] = []
+    let transitions = 0
+    let prevT = kept[0]?.t ?? 0
+    for (let i = 0; i < kept.length - 1; i++) {
+        const moved = diffScreen(kept[i].snap, kept[i + 1].snap, [], [], [])
+        if (!moved.length)
+            continue
+        const at = `@${Math.round(kept[i + 1].t)}ms`
+        // The first emitted transition prints alone; each subsequent one is preceded by the gap
+        // from the previous *emitted* transition's time. transitions>0 == we've emitted before.
+        if (transitions)
+            lines.push(`  ╎ ${Math.round(kept[i + 1].t - prevT)}ms`)
+        for (let j = 0; j < moved.length; j++)
+            lines.push(`${j === 0 ? at.padEnd(9) : ' '.repeat(9)} ${moved[j]}`)
+        transitions++
+        prevT = kept[i + 1].t
+        // Mark the seam where the dense middle was dropped, right after the head's last frame.
+        if (dropped && i === Math.ceil(MAX_FLOW_FRAMES / 2) - 1)
+            lines.push(`  ┄ … ${dropped} 帧省略`)
+    }
+    // Fewer than two timed transitions == no Δt to show == the `--- changed ---` 2-frame diff
+    // already covers it. Degrade to no-flow so the caller omits a redundant single-line section.
+    return transitions >= 2 ? lines : []
+}
+
+// One-line, bounded, comparison-stable stringification of a domain value. Used both to
+// detect change (string equality) and to render the transition. Objects compare by their
+// JSON — good enough for the shallow domain maps __AIPEEK_SCREEN__ returns.
+function stringifyDomain(v: unknown): string {
+    if (v === null || v === undefined)
+        return String(v)
+    if (typeof v === 'object')
+        return JSON.stringify(v).slice(0, 80)
+    return String(v).slice(0, 80)
+}
+
+// stringifyDomain, but redact the value when the field KEY names a secret (sessionToken,
+// apiKey, *_token…). The domain map is `store.field → value`; an app's __AIPEEK_SCREEN__ can
+// surface a credential there, and both echo points (/screen's domain block AND every
+// --- changed --- diff) must mask it. Length-preserving so "empty vs set / roughly how long"
+// stays observable. The single key-level chokepoint — see candidates.isSecretKey.
+export function redactDomain(key: string, v: unknown): string {
+    const s = stringifyDomain(v)
+    if (!isSecretKey(key))
+        return s
+    const raw = v === null || v === undefined ? '' : String(v)
+    return raw ? redactSecretValue(raw) : s
+}
+
+export function diffState(prev: RawState | null, curr: RawState): DiffResult {
+    if (!prev) {
+        return {
+            newErrors: curr.console.filter(l => l.level === 'error'),
+            newExceptions: [...curr.errors],
+            newFailedRequests: curr.network.filter(r => r.status >= 400 || r.failed),
+            uiGone: false,
+            clean: curr.console.filter(l => l.level === 'error').length === 0
+                && curr.errors.length === 0
+                && curr.network.filter(r => r.status >= 400 || r.failed).length === 0,
+        }
+    }
+
+    const prevErrorTexts = new Set(prev.console.filter(l => l.level === 'error').map(l => l.text))
+    const newErrors = curr.console.filter(l => l.level === 'error' && !prevErrorTexts.has(l.text))
+
+    const prevExceptionMsgs = new Set(prev.errors.map(e => e.message))
+    const newExceptions = curr.errors.filter(e => !prevExceptionMsgs.has(e.message))
+
+    const prevFailedKeys = new Set(
+        prev.network.filter(r => r.status >= 400 || r.failed).map(r => `${r.method}|${r.url}|${r.status}`),
+    )
+    const newFailedRequests = curr.network
+        .filter(r => r.status >= 400 || r.failed)
+        .filter(r => !prevFailedKeys.has(`${r.method}|${r.url}|${r.status}`))
+
+    const uiGone = prev.ui.trim().length > 0 && curr.ui.trim().length === 0
+
+    return {
+        newErrors,
+        newExceptions,
+        newFailedRequests,
+        uiGone,
+        clean: newErrors.length === 0 && newExceptions.length === 0 && newFailedRequests.length === 0 && !uiGone,
+    }
+}

package/src/ui/core/emit.ts

@@ -0,0 +1,198 @@
+import type { CheckResult, CompactState, DiffResult, PerformanceData, RawState } from './types'
+import pc from 'picocolors'
+import { nameOf } from './compact'
+import { compactPerformance } from './perf'
+import { compactUrl, truncate } from './util'
+
+// --- Full emit (for ?full) ---
+
+const SECTIONS = ['ui', 'console', 'network', 'errors', 'state', 'performance'] as const
+const COUNTED_SECTIONS: Record<string, keyof CompactState['counts']> = {
+    console: 'console',
+    network: 'network',
+    errors: 'errors',
+    state: 'state',
+}
+
+export function emit(state: CompactState): string {
+    const sections: string[] = []
+
+    for (const key of SECTIONS) {
+        if (state[key]) {
+            const countKey = COUNTED_SECTIONS[key]
+            const count = countKey ? state.counts?.[countKey] ?? 0 : 0
+            const attr = count ? ` count="${count}"` : ''
+            sections.push(`<${key}${attr}>\n${state[key]}\n</${key}>`)
+        }
+    }
+
+    if (!sections.length) {
+        sections.push('<empty/>')
+    }
+
+    return `<aihand url="${state.url}">\n\n${sections.join('\n\n')}\n\n</aihand>\n\ndetail: GET /__aihand/{section}/{index}?full`
+}
+
+// --- Summary emit (default, high-density) ---
+
+export function emitSummary(raw: RawState): string {
+    const consoleErrors = raw.console.filter(l => l.level === 'error')
+    const consoleWarns = raw.console.filter(l => l.level === 'warn')
+    const failedReqs = raw.network.filter(r => r.status >= 400 || r.failed)
+    const hasIssues = consoleErrors.length > 0 || raw.errors.length > 0 || failedReqs.length > 0
+
+    const lines: string[] = []
+
+    // ui — always 1-line summary
+    if (raw.ui.trim()) {
+        lines.push(`ui: ${summarizeUI(raw.ui)}`)
+    }
+
+    // console — 1-line if clean, expand errors/warns if dirty
+    if (raw.console.length) {
+        if (consoleErrors.length || consoleWarns.length) {
+            const parts: string[] = []
+            for (const e of consoleErrors) parts.push(`  [error] ${truncate(e.text, 150)}`)
+            for (const w of consoleWarns) parts.push(`  [warn] ${truncate(w.text, 150)}`)
+            const rest = raw.console.length - consoleErrors.length - consoleWarns.length
+            if (rest > 0)
+                parts.push(`  … ${rest} more`)
+            lines.push(`console (${raw.console.length}):`)
+            lines.push(...parts)
+        }
+        else {
+            lines.push(`console: ${raw.console.length} logs`)
+        }
+    }
+
+    // network — 1-line if clean, expand failures if dirty
+    if (raw.network.length) {
+        if (failedReqs.length) {
+            lines.push(`network (${raw.network.length}):`)
+            for (const r of failedReqs) {
+                const body = r.responseBody ? ` "${truncate(r.responseBody, 80)}"` : ''
+                lines.push(`  ${r.method} ${compactUrl(r.url)} ${r.status}${body}`)
+            }
+            const ok = raw.network.length - failedReqs.length
+            if (ok > 0)
+                lines.push(`  … ${ok} ok`)
+        }
+        else {
+            lines.push(`network: ${raw.network.length} ok`)
+        }
+    }
+
+    // errors — always expand (these are uncaught exceptions)
+    if (raw.errors.length) {
+        lines.push(`errors (${raw.errors.length}):`)
+        for (const e of raw.errors) lines.push(`  ${truncate(e.message, 150)}`)
+    }
+
+    // perf — only show when jank (dropped >10%)
+    if (raw.performance) {
+        const all = raw.performance.buckets.find(b => b.name === '__all__')
+        if (all) {
+            const droppedPct = all.frames.total > 0 ? (all.frames.long / all.frames.total) * 100 : 0
+            if (droppedPct > 10) {
+                lines.push(compactPerformance(raw.performance))
+            }
+        }
+    }
+
+    // state — 1-line: store names + key counts
+    const storeNames = Object.keys(raw.state)
+    if (storeNames.length) {
+        const parts = storeNames.map((n) => {
+            const v = raw.state[n]
+            const keys = typeof v === 'object' && v !== null ? Object.keys(v).length : 0
+            return keys > 0 ? `${n}(${keys})` : n
+        })
+        lines.push(`state: ${parts.join(', ')}`)
+    }
+
+    if (!lines.length)
+        return '<aihand>empty</aihand>'
+
+    const status = hasIssues
+        ? `${consoleErrors.length + raw.errors.length + failedReqs.length} issues`
+        : 'ok'
+
+    return `<aihand url="${raw.url}" status="${status}">\n${lines.join('\n')}\n</aihand>${hasIssues ? '\n\ndetail: GET /__aihand/{section}/{index}' : ''}`
+}
+
+function summarizeUI(tree: string): string {
+    // extract top-level component names (depth 0-1)
+    const components: string[] = []
+    const counts = new Map<string, number>()
+
+    for (const line of tree.split('\n')) {
+        const trimmed = line.trimStart()
+        if (!trimmed)
+            continue
+        const indent = line.length - trimmed.length
+        if (indent > 2)
+            continue // only depth 0-1
+
+        const name = nameOf(trimmed)
+        if (!name)
+            continue
+
+        // extract state markers
+        const focused = trimmed.includes('[focused]')
+        const generating = trimmed.includes('[generating]')
+        const loading = trimmed.includes('[loading]')
+
+        const existing = counts.get(name) || 0
+        if (existing > 0) {
+            counts.set(name, existing + 1)
+            continue
+        }
+        counts.set(name, 1)
+
+        let label = name
+        if (focused)
+            label += '[focused]'
+        if (generating)
+            label += '[generating]'
+        if (loading)
+            label += '[loading]'
+        components.push(label)
+    }
+
+    // apply counts
+    const result = components.map((c) => {
+        const name = c.split('[')[0]
+        const count = counts.get(name) || 1
+        return count > 1 ? `${c}(×${count})` : c
+    })
+
+    return result.join(', ') || 'empty'
+}
+
+// --- Check emit ---
+
+export function emitCheck(result: CheckResult): string {
+    const lines = result.assertions.map(a =>
+        a.pass
+            ? `✓ ${a.name}`
+            : `✗ ${a.name}${a.detail ? `: ${a.detail}` : ''}`,
+    )
+    return `<aihand-check pass="${result.pass}">\n${lines.join('\n')}\n</aihand-check>`
+}
+
+// --- Diff emit (terminal, colored) ---
+
+export function emitDiff(diff: DiffResult): string {
+    const issues: string[] = []
+    for (const e of diff.newErrors) issues.push(pc.red(`  [error] ${e.text}`))
+    for (const e of diff.newExceptions) issues.push(pc.red(`  [exception] ${e.message}`))
+    for (const r of diff.newFailedRequests) issues.push(pc.yellow(`  [network] ${r.method} ${r.url} ${r.status}`))
+    if (diff.uiGone)
+        issues.push(pc.magenta('  [ui] component tree disappeared'))
+
+    if (!issues.length)
+        return ''
+
+    const count = issues.length
+    return `${pc.bold('[aihand]')} ${pc.red(`✗ ${count} issue${count > 1 ? 's' : ''} after HMR`)}\n${issues.join('\n')}`
+}

package/src/ui/core/knob-exec.ts

@@ -0,0 +1,137 @@
+// 绿色通道执行器 — 把 build 时静态投影出的旋钮态射(KnobProjection.ops)变成运行时可执行算子。
+//
+// 对照「模拟人工」(/click /fill 走 DOM):此处直接写 store 字段,绕过选择器解析 / disabled / 遮挡门控。
+// 92 个旋钮零手挂——main.tsx 不再逐个抄函数,executeKnob 按 ops 的 kind 分派即可覆盖。
+//
+// 纯函数铁律:不读 window。stores 由调用方注入(client.ts 传 window.__AIPEEK_STORES__,
+// vitest 传 mock store)→ 行为可单测钉死。
+
+import type { KnobProjection } from '../server/knob-schema'
+
+// 字面量原文 → 运行时值。剥引号 / 解析 true|false|null|数字;绝不 eval(安全 + 确定性)。
+export function parseLiteral(s: string): unknown {
+    if (s === 'true') return true
+    if (s === 'false') return false
+    if (s === 'null') return null
+    if (s.length >= 2) {
+        const q = s[0]
+        if ((q === '\'' || q === '"' || q === '`') && s[s.length - 1] === q)
+            return s.slice(1, -1)
+    }
+    // 纯数字
+    let numeric = s.length > 0
+    let dot = 0
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i]
+        if (ch === '-' && i === 0) continue
+        if (ch === '.') { dot++; if (dot > 1) { numeric = false; break } continue }
+        if (ch < '0' || ch > '9') { numeric = false; break }
+    }
+    if (numeric && s !== '-' && s !== '.') return Number(s)
+    return s // 兜底:原样返回(理论上 classify 已挡住非字面量进 assign/nullary)
+}
+
+// miss 时的恢复纤维(ker 诊断 ⊆ ker 动作):列出的 available 必须全是「能当 ?knob= 传的合法 label」。
+// 两类垃圾要剔/规整,否则 AI 拿去重试继续 miss:
+//   ① `<Tag>` 形 —— 纯图标旋钮无文本,keyOf 退回 `<button>`/`<div>` 当 join 键(/screen 的 DOM 侧也这么 fallback,
+//      forward join 需要它)。但它不是可读 label,传它寻址要么再 miss 要么命中无意义巨桶 —— 从恢复表剔除。
+//   ② 多行 label —— 源码 title 写成 `'深度研究\n多步搜索…'`,tree-sitter 读原始文本(labelOf 不解转义),
+//      故 schema 里是字面两字符反斜杠+n(非真换行)。available 是 ` | ` 单行拼接,在字面 `\n` 处截首行守一行一项契约。
+// 排序去重,稳定可测。
+const NL = '\\n' // 字面反斜杠 + n(两字符),不是真换行 —— 见 labelOf 读原始源码文本
+export function availableLabels(sem: Record<string, KnobProjection>): string[] {
+    const out = new Set<string>()
+    for (const key of Object.keys(sem)) {
+        const label = key.slice(0, key.lastIndexOf(' '))
+        if (label.startsWith('<') && label.endsWith('>')) continue // 组件名 fallback,非可调 label
+        const nl = label.indexOf(NL)
+        out.add(nl === -1 ? label : label.slice(0, nl))
+    }
+    return [...out].sort()
+}
+
+// join 表里挑出 label 命中的投影。key 形如 `label file`(knob-schema.keyOf)。
+// 0 命中 → 列可用 label;1 → 命中;>1 且无 file → 列候选让 AI 区分;>1 有 file → file 末段子串唯一化。
+export function resolveKnob(
+    sem: Record<string, KnobProjection>,
+    label: string,
+    file?: string,
+): { ok: true, proj: KnobProjection, key: string } | { ok: false, error: string } {
+    const prefix = `${label} `
+    const hits = Object.keys(sem).filter(k => k.startsWith(prefix))
+    if (hits.length === 0)
+        return { ok: false, error: `no knob labeled "${label}". available: ${availableLabels(sem).join(' | ')}` }
+    if (hits.length === 1)
+        return { ok: true, proj: sem[hits[0]], key: hits[0] }
+    // 多命中:用 file 末段子串消歧。
+    if (file) {
+        const narrowed = hits.filter(k => k.slice(prefix.length).includes(file))
+        if (narrowed.length === 1)
+            return { ok: true, proj: sem[narrowed[0]], key: narrowed[0] }
+    }
+    const candidates = hits.map(k => `  ${k.slice(prefix.length)} → ${sem[k].store}.{ ${sem[k].transitions} }`)
+    return { ok: false, error: `"${label}" is ambiguous (${hits.length} matches). pass &file= to disambiguate:\n${candidates.join('\n')}` }
+}
+
+// @kN 可寻址 ref → 命中的投影。纯函数:refs 表(@kN→{label,files})由调用方注入(client.ts 传
+// window.__aihandKnobRefs,vitest 传 mock),不读 window。两步:
+//   ① 翻译 —— @kN 形 → 查表得 {label,files};表里没有(号过期/没发过)→ 响亮列可用号,绝不静默把
+//      裸 @k 当 label 去 prefix 匹配(那必 miss,把可恢复态坍缩成死局,违 ker 诊断 ⊆ ker 动作)。
+//      非 @k 形 → 原样当 label(/action?knob=群聊 直传仍走老路)。
+//   ② 消歧 —— files 是 leaf+callsite 两候选,runtime 分不清 handler 写在哪,逐个喂 resolveKnob 命中任一。
+export function resolveKnobRef(
+    sem: Record<string, KnobProjection>,
+    knob: string,
+    refs: Record<string, { label: string, files: string[] }> | undefined,
+    file?: string,
+): { ok: true, proj: KnobProjection, key: string } | { ok: false, error: string } {
+    let label = knob
+    let files = file ? [file] : []
+    if (knob.startsWith('@k')) {
+        const hit = refs?.[knob]
+        if (!hit) {
+            const avail = refs ? Object.keys(refs).sort((a, b) => Number(a.slice(2)) - Number(b.slice(2))) : []
+            return { ok: false, error: `${knob} 已过期或未编号(先读 /screen 取新号)。当前可用: ${avail.join(' ') || '(无,/screen 未采集)'}` }
+        }
+        label = hit.label
+        files = hit.files
+    }
+    let resolved = resolveKnob(sem, label, files[0])
+    for (let i = 1; i < files.length && !resolved.ok; i++)
+        resolved = resolveKnob(sem, label, files[i])
+    return resolved
+}
+
+// 执行一个旋钮的全部 ops,直接写注入的 store。返回写过的字段名(给反馈用)。
+// executable:false / 缺 value / store 缺失 都 throw 明确文案,绝不静默假成功。
+export function executeKnob(
+    proj: Pick<KnobProjection, 'ops' | 'arity' | 'store' | 'executable'>,
+    value: unknown | undefined,
+    stores: Record<string, any>,
+): { wrote: string[] } {
+    if (!proj.executable) {
+        const ctx = proj.ops.find(o => o.kind === 'context')
+        throw new Error(`knob 依赖运行时上下文(${ctx?.reason ?? '未知'}),无法字面 replay。用 /fill 或 /click 走模拟人工。`)
+    }
+    const store = stores[proj.store]
+    if (!store)
+        throw new Error(`store "${proj.store}" 未注册(window.__AIPEEK_STORES__ 缺它)`)
+    if (proj.arity === 'param' && value === undefined)
+        throw new Error(`此旋钮需要参数,带 ?value= 调用(如 ?value=8)`)
+
+    const wrote: string[] = []
+    for (const op of proj.ops) {
+        if (op.kind === 'assign') {
+            store[op.field] = op.arity === 'param' ? value : parseLiteral(op.to ?? '')
+        }
+        else if (op.kind === 'toggle') {
+            store[op.field] = !store[op.field]
+        }
+        else if (op.kind === 'call') {
+            const method = op.field.slice(0, -2) // 去尾 '()'
+            store[method]()
+        }
+        wrote.push(op.field)
+    }
+    return { wrote }
+}