aihand 0.0.1 → 0.1.0

package/src/ui/self/store-schema.ts

@@ -0,0 +1,65 @@
+// aihand/self —— 把 self-rep 的「状态/输出端」结构从 app 构建管线正向投影出来。
+//
+// 对偶于 knobSchema(旋钮/输入端):那个把旋钮态射(拨它 → store.{field=to})从 onClick
+// 长出,这个把 store 的值域(`'chat'|'im'|'workbench'`)从类型注解长出。两者同形:build 时
+// 静态分析(stategraph 神经图引擎,ts-morph type checker,Node 侧)、运行时纯 JSON、浏览器零 AST。
+// 控制面板宪法 (旋钮 × 状态) 的两半,并列在 aihand() 一个插件里。
+//
+// 数学终点的最后一跳:值域是 TS 类型注解,tsc 编译后擦除,运行时 store 只剩 'chat' 这一个
+// 字符串。要让 screen(store) 读到完整值域,信息必须在 build 时(类型还在场时)被捞回来、
+// 注入运行时。这就是 discover/stategraph 引擎做的事:类型注解声明值域一次,插件投影成
+// virtual:store-schema,运行时直读 —— 开发者一字不改 store,零重复声明。
+
+import { discover } from './discover'
+import type { Grown } from './grow'
+
+const VIRTUAL = 'virtual:store-schema'
+const RESOLVED = '\0' + VIRTUAL
+
+interface Options {
+    // 要扫的根(绝对路径)：目录(递归扫)或单文件,任意混合。aihand() 传 scan(config) 解出的
+    // 全仓文件清单 —— store 散落全仓(src/store + features/IM + ChatHeader + mobile + …),
+    // 不靠人列:引擎按返回类型的响应式 marker 认状态节点,非 store 文件自动过滤掉。
+    roots: string | string[]
+    // store 工厂注入的响应式指纹字段(构造无关判据);来自 config.runtime.storeMarker。默认 '_loading'。
+    storeMarker?: string
+}
+
+// vite 插件:dev/build 时扫 storeDir,把每个 create() store 的字段结构(名/值域/anchor)
+// 长成 Grown[],经 virtual:store-schema 暴露给运行时。运行时 `import { schema } from
+// 'virtual:store-schema'` 即得全仓 store 的可投影 schema,无需任何运行时 AST。
+export function storeSchema(options: Options) {
+    let cache: Grown[] | null = null
+
+    const roots = Array.isArray(options.roots) ? options.roots : [options.roots]
+    const build = async (): Promise<Grown[]> => {
+        if (!cache)
+            cache = await discover(roots, options.storeMarker)
+        return cache
+    }
+
+    return {
+        name: 'aihand:store-schema',
+        resolveId(id: string) {
+            if (id === VIRTUAL)
+                return RESOLVED
+        },
+        async load(id: string) {
+            if (id !== RESOLVED)
+                return
+            const grown = await build()
+            // schema = store 名 → Grown。运行时按 store 名取自己的 schema 喂 synth。
+            const byStore: Record<string, Grown> = {}
+            for (const g of grown)
+                byStore[g.store] = g
+            return `export const schema = ${JSON.stringify(byStore)}\n`
+        },
+        // store 文件改动 → 失效缓存。下次 cold load 重跑引擎(~2s),值域改了 schema 跟着变。
+        // 不在 handleHotUpdate 里同步重投影:引擎离线纪律,绝不让 ts-morph 进同步 HMR 热路径 ——
+        // 值域是类型注解(改动罕见),下次 load 拿到即可,不值得为它在热路径养一个常驻 Project。
+        handleHotUpdate(ctx: { file: string }) {
+            if (roots.some(r => ctx.file.startsWith(r)))
+                cache = null
+        },
+    }
+}

package/src/ui/self/synth.ts

@@ -0,0 +1,37 @@
+// 合成:把两半接成一个完整 Self。
+//
+// 静态引擎给【schema】—— 字段名、值域、源码 anchor(stategraph 离线长出)。
+// 运行时给【snapshot】—— 每个字段此刻的值(动态,从 store 读)。
+// 完整的 self-rep = schema ⋉ snapshot:知道「能取哪些值」+「此刻取哪个值」。
+//
+// 关键:aipeek 手挑 `view: appUIStore.mode` —— 人来决定哪个字段是「主视图档位」。
+// 但 schema 里这个判断是结构性的:domain 非空 = 这是个有限值域的档位(联合字面量),
+// 就是 view 类。无需手挑,引擎已经把它标出来了。view = 第一个有 domain 的字段的当前值。
+//
+// 纯函数,无 fs/ts-morph —— 故浏览器安全(synth 在真页面里把 schema ⋉ live store 读)。
+// 多 store 发现(discover)走 ts-morph 引擎,是 Node 端,拆到 discover.ts,不污染这里。
+
+import type { Grown } from './grow'
+import type { Self } from './self'
+
+// store 当前的运行时快照:字段名 → 当前值。真页面里这就是 mobx store 的普通读取
+// (appUIStore.mode 等),测试里直接喂对象。schema 决定读哪些 key,snapshot 给值。
+export type Snapshot = Record<string, unknown>
+
+// schema(一个 store 的 Grown)⋉ snapshot → Self。
+// view = 第一个 domain 非空字段的当前值(结构性识别,非手挑);
+// state = 全字段当前值;anchor = store 声明位置;modal/focus 留给运行时另投(DOM 焦点态,
+// 不在 store schema 里 —— 那是 screen 的活,这里只合成 store 能声明的部分)。
+export function synth(schema: Grown, snapshot: Snapshot): Self {
+    const viewField = schema.fields.find(f => f.domain.length > 0)
+    const state: Record<string, unknown> = {}
+    for (const f of schema.fields)
+        state[f.name] = snapshot[f.name]
+    return {
+        view: viewField ? String(snapshot[viewField.name] ?? '') : '',
+        modal: null,
+        focus: null,
+        state,
+        anchor: schema.anchor,
+    }
+}

package/src/ui/server/cli.ts

@@ -0,0 +1,102 @@
+/* eslint-disable no-console -- this is a CLI; stdout is its output channel */
+import process from 'node:process'
+import pc from 'picocolors'
+
+// aihand fusion: argv is injected by the unified router (src/cli.ts) after it
+// strips the leading `ui` segment. Falls back to process.argv when run directly.
+let args = process.argv.slice(2)
+let flags = parseFlags(args)
+
+function parseFlags(a: string[]) {
+    return Object.fromEntries(
+        a.filter(x => x.startsWith('--')).map((x) => {
+            const body = x.slice(2)
+            const eq = body.indexOf('=') // split on the FIRST = only — values may contain = (e.g. CSS sel)
+            return eq === -1 ? [body, 'true'] : [body.slice(0, eq), body.slice(eq + 1)]
+        }),
+    )
+}
+
+// argv → the /__aihand HTTP endpoint to hit. The subcommand is positional (screen/dom/click);
+// every flag except port/help becomes a query param (?text=…&sel=…), so action commands work
+// through the CLI, not just curl. `full` is a bare flag (?full). Values may contain `=` and
+// non-ASCII (CSS selectors) — parseFlags splits on the first `=`, encodeURIComponent escapes them.
+export function buildUiUrl(argv: string[]): { url: string, sub: string } {
+    const flags = parseFlags(argv)
+    const sub = argv.filter(a => !a.startsWith('--'))[0] || ''
+    const path = sub ? `/${sub}` : ''
+    const reserved = new Set(['port', 'help'])
+    const query = Object.entries(flags)
+        .filter(([k]) => !reserved.has(k))
+        .map(([k, v]) => (k === 'full' ? 'full' : `${k}=${encodeURIComponent(v)}`))
+        .join('&')
+    const port = flags.port || '5173'
+    return { url: `http://localhost:${port}/__aihand${path}${query ? `?${query}` : ''}`, sub }
+}
+
+async function main() {
+    if (flags.help) {
+        console.log(`
+${pc.bold('aihand runtime')} — runtime snapshot from Vite dev server
+
+${pc.dim('Inspect:')}
+  aihand runtime                    Full summary
+  aihand runtime screen             State-machine view (start here)
+  aihand runtime check              Health check (pass/fail)
+  aihand runtime console            Console logs
+  aihand runtime errors/1 --full    Error detail (untruncated)
+
+${pc.dim('Drive (params as flags — the CLI URL-encodes values for you, CJK included):')}
+  aihand runtime click --text=群聊          Click by visible text
+  aihand runtime fill --sel=input --value=hi   Set an input value
+  aihand runtime wait --text=Done --timeout=8000
+
+${pc.dim('UI → code (reverse morphism):')}
+  aihand read source <file:line>      Which symbol owns this line + its callers/callees
+                                     (also eats /dom's data-insp-path raw)
+
+${pc.dim('Options:')}
+  --port=<port>    Dev server port (default: 5173)
+  --full           Untruncated output
+  --help           Show this help
+
+${pc.dim('Setup:')}
+  Add aihand() to your vite.config.ts plugins array.
+`)
+        process.exit(0)
+    }
+
+    const { url: endpoint, sub } = buildUiUrl(args)
+
+    const resp = await fetch(endpoint)
+    if (!resp.ok && resp.status !== 417) {
+        const text = await resp.text()
+        console.error(pc.red(`Error ${resp.status}: ${text}`))
+        process.exit(1)
+    }
+
+    const text = await resp.text()
+    // color check results — assertions are one per line: "✓ name" / "✗ name: detail"
+    if (sub === 'check') {
+        const colored = text.split('\n').map((line) => {
+            if (line.startsWith('✓'))
+                return pc.green(line)
+            if (line.startsWith('✗'))
+                return pc.red(line)
+            return line
+        }).join('\n')
+        console.log(colored)
+        process.exit(resp.status === 417 ? 1 : 0)
+    }
+
+    console.log(text)
+}
+
+export async function run(argv: string[]) {
+    args = argv
+    flags = parseFlags(args)
+    await main().catch((err) => {
+        console.error(pc.red(`Error: ${err.message}`))
+        process.exit(1)
+    })
+}

package/src/ui/server/dispatch.ts

@@ -0,0 +1,276 @@
+import type { ActionArgs, ActionResult } from '../core/action'
+import type { ErrorEntry, LogEntry, NetworkRequest, ScreenSnap } from '../core/types'
+import type { ServerBridge } from '../bridge/transport'
+import { resolveAction, TYPES } from '../core/action'
+
+// transport 无关的命令执行 + 渲染。出口1(Vite HMR)和出口2(CDP)同一份:
+// 各自把自己的通道包成 ServerBridge 传进来,dispatch 只调 bridge.request + 内核渲染。
+// 本轮只填 screen + 动作(click|fill|press|hover|wait)——证明同一内核可被第二出口复用即停。
+// Vite HTTP 专属(?since= token、realclick CDP 握手、screenshot 落盘、federation)不进这里,
+// 留 plugin.ts 原位 short-circuit。
+
+export interface ScreenReply {
+    screen: string
+    canvas: string
+    snap: ScreenSnap
+    console: LogEntry[]
+    network: NetworkRequest[]
+    errors: ErrorEntry[]
+}
+
+export interface DispatchResult {
+    status: number
+    body: string
+}
+
+// executeAction is generic: it ships {type,args} over the bridge and in-page performAction handles
+// any ActionType, returning a screen delta. So the HTTP/chain action set = the full TYPES source of
+// truth (action.ts) MINUS the four whose output contract differs and which own their own route:
+//   · screenshot — binary PNG (server.ts:/screenshot, not a screen-delta reply)
+//   · realclick  — electron-only trusted-event path (no electronAPI in a headless chromium parachute)
+//   · query/assert — return matched data / pass-fail, not the changed-screen delta these dispatch
+// Deriving from TYPES (not a hand-kept second list) means a new action added to TYPES is reachable
+// over HTTP automatically — the two exits can never drift (drag/scrollIntoView/drop/clipboard were
+// silently unreachable on exit-2 for exactly that drift; exit-1 plugin.ts had them, this list didn't).
+const SPECIAL_CONTRACT = new Set(['screenshot', 'realclick', 'query', 'assert'])
+const ACTION_TYPES = TYPES.filter(t => !SPECIAL_CONTRACT.has(t))
+
+export function isDispatchAction(type: string): boolean {
+    return ACTION_TYPES.includes(type as (typeof ACTION_TYPES)[number])
+}
+
+// URLSearchParams → ActionArgs。出口1(plugin.ts)与出口2(probe/server.ts)同一份解析,
+// 不各抄一遍(避免 query→args 第三份漂移)。
+export function argsFromQuery(q: URLSearchParams): ActionArgs {
+    return {
+        sel: q.get('sel') || undefined,
+        text: q.get('text') || undefined,
+        value: q.has('value') ? q.get('value')! : undefined,
+        key: q.get('key') || undefined,
+        timeout: q.has('timeout') ? Number(q.get('timeout')) : undefined,
+        gone: q.has('gone') ? q.get('gone') !== 'false' : undefined,
+        enabled: q.has('enabled') ? q.get('enabled') !== 'false' : undefined,
+        button: q.get('button') === 'right' ? 'right' : q.get('button') === 'left' ? 'left' : undefined,
+        x: q.has('x') ? Number(q.get('x')) : undefined,
+        y: q.has('y') ? Number(q.get('y')) : undefined,
+        screen: q.get('screen') || undefined,
+        equals: q.has('equals') ? q.get('equals')! : undefined,
+        to: q.get('to') || undefined,
+        files: q.has('files') ? q.get('files')!.split(',').map(s => s.trim()).filter(Boolean) : undefined,
+        mode: q.get('mode') === 'write' ? 'write' : q.get('mode') === 'read' ? 'read' : undefined,
+    }
+}
+
+// /screen 的新鲜读(无 ?since)——语义布局树 + 字符画,两半同源一个 snap。
+// since-diff 是 HTTP token ring 专属,留 plugin.ts。
+export async function dispatchScreen(
+    bridge: ServerBridge,
+    opts?: { tab?: string, form?: string },
+): Promise<{ reply: ScreenReply, result: DispatchResult }> {
+    const reply = await bridge.request<ScreenReply>('aihand:collect-screen', 'aihand:screen', { form: opts?.form }, { tab: opts?.tab })
+    const body = [reply.canvas, reply.screen].filter(Boolean).join('\n\n')
+    return { reply, result: { status: 200, body: body || '(empty)' } }
+}
+
+// 跨整页导航回填:出口2 点链接触发 example→iana 整页导航时,探针随旧文档销毁——它的
+// settleAndTrace after 帧在「导航已触发、旧文档未销毁」的窗口里采,采到的是旧页残影(focus 变了),
+// 采不到新页。导航信号不靠事后轮询 url 猜:cdpBridge 派发动作撞整页导航(上下文销毁异常)时经
+// request 的 onNav 回调同步交出——撞 = 确凿导航,没撞 = 同文档动作,100% 准确零成本。导航发生才
+// settle 新文档(cdpBridge 已做) + renavScreen 采新页全貌回填。出口1(Vite)无整页导航,不传 afterNav。
+export interface NavProbe {
+    // 动作前读 URL(回填 from 头需要)。O(1) 同步读,非轮询。
+    url: () => Promise<string>
+    // settle(等新文档 commit)后采新页一帧 + 读 toUrl,返回换页确认行(navigated 头 + 新页语义树)。
+    // toUrl 必须在 settle 内读:动作回执到达时(reply ~62ms)新文档尚未 commit,此刻 page.url() 仍是旧值。
+    renavScreen: (fromUrl: string) => Promise<string | undefined>
+    // SPA 同文档路由切换(Turbo/React Router pushState)事后等待。整页导航 onNav 闩在 reply 前竞速成功;
+    // 同文档导航上下文存活、reply 快速带残缺 screen 先回,真换页 morph 在 reply 后 ~0.2~1.4s 才到——故
+    // 这条信号必须 outlive reply。两段:arm() 在动作派发前调(订阅就位),返回的 wait(capMs) 在 reply
+    // 后调,与 capMs 竞速;URL 真变的 navigatedWithinDocument 在窗口内 fire → true(立即短路)。
+    armSameDocNav?: () => { wait: (capMs: number) => Promise<boolean>, cancel: () => void }
+}
+
+// chain 的单步执行结果(出口注入的 runStep 返回这个,runChain 只管循环+渲染+fail-fast)。
+// ok/detail/error/screen/actions 对齐 ActionResult 的渲染字段;label 是步骤动词(type 或 'knob')。
+export interface ChainStepResult {
+    ok: boolean
+    label: string
+    detail?: string
+    error?: string
+    screen?: string
+    actions?: string
+}
+
+export type ChainStep = { type: string } & ActionArgs
+
+// chain:POST 一串动作,逐步 settle、fail-fast、一往返跑完整个交互。循环/渲染/skipped 汇报
+// 是两出口共用的纯逻辑——抽进内核,出口只注入各自的单步执行器 runStep(出口1 带 knob 特例 +
+// runAction,出口2 纯 dispatchAction)。渲染与 plugin.ts 旧内联逐字一致:每步 `[i] ✓/✗ label: …`,
+// 失败带 clickable fallback、缩进 screen delta,末尾 skipped 汇总 + recent actions 尾。
+export async function runChain(
+    steps: ChainStep[],
+    runStep: (type: string, args: ActionArgs, index: number) => Promise<ChainStepResult>,
+): Promise<DispatchResult> {
+    const lines: string[] = []
+    let lastActions = ''
+    let allOk = true
+    for (let i = 0; i < steps.length; i++) {
+        const { type, ...args } = steps[i]
+        const r = await runStep(type, args, i)
+        lines.push(`[${i}] ${r.ok ? '✓' : '✗'} ${r.label}: ${r.ok ? (r.detail || 'ok') : r.error}`)
+        // 失败步骤带 clickable fallback,与单发路径一致——chain 里的失败步不能比单发更瞎
+        // (丢 detail 会把「列出的 label 可重试」的可恢复态坍缩成死路)。
+        if (!r.ok && r.detail)
+            lines.push(`    clickable: ${r.detail}`)
+        // 每步的状态机转移(view/modal/focus + 新 error)缩进显示在它的源步骤下。
+        if (r.screen)
+            lines.push(r.screen.split('\n').map(l => `    ${l}`).join('\n'))
+        if (r.actions)
+            lastActions = r.actions
+        if (!r.ok) {
+            allOk = false
+            break
+        }
+    }
+    // ker(report) ⊆ ker(execute):fail-fast 跳过剩余步骤,就 SAY 跳过了——否则 agent 得回去数
+    // 输入数组才知道页面停在 N 步未跑的半成品态。
+    if (!allOk && lines.length) {
+        const ran = lines.filter(l => l.startsWith('[')).length
+        const skipped = steps.length - ran
+        if (skipped > 0)
+            lines.push(`[${ran}..${steps.length - 1}] skipped (${skipped} step${skipped > 1 ? 's' : ''} not run — chain stopped at first failure)`)
+    }
+    const chainActions = lastActions ? `\n\n--- recent actions ---\n${lastActions}` : ''
+    return { status: allOk ? 200 : 422, body: `${lines.join('\n')}${chainActions}` }
+}
+
+// 动作:校验 → 一次 request 等 aihand:result → 渲染 head + recent actions + changed + flow。
+// 渲染与 plugin.ts 单发路径(~1294)逐字一致,故出口2 与出口1 输出同形。
+// id 由调用方给(出口1 复用 plugin 的 actionId 计数器,与 runAction/chain 同一空间不撞;
+// 出口2 自己的计数器),保证 progress ping 的 id 与 bridge.request 的 id 对得上。
+// 执行动作并应用跨导航回填,返回结构化结果(invalid → status 400 + error,无 result)。
+// 单发(dispatchAction)与 chain 单步共用此处:执行+nav-backfill 是一份,渲染各取所需,
+// 不在 chain 里重解析已渲染的 body 串(那会把格式化输出当数据二次解析,脆)。
+export interface ExecutedAction {
+    status: number
+    result?: ActionResult
+    changed?: string // result.screen,跨导航时被新页全貌覆盖
+    navigated?: boolean // 动作触发了整页导航 → 旧页动作环是噪音,抑制 recent actions 尾
+}
+
+// SPA 同文档路由切换的确认窗口:实测 GitHub Turbo 的 navigatedWithinDocument(URL 真变)在动作后
+// ~0.2~1.4s 才到(冷热差异大),1500 留安全边际。仅在「门控命中」的 click/press 上付这个上限,且
+// fire 即短路——故真换页通常远快于 1500ms 返回,只有「click/press 了但没换路由」才付满。
+const SPA_NAV_CAP = 1500
+
+// 该动作的即时 diff 是否「平凡」——空(no state change)或只有 focus 行。SPA 路由 click 的即时 diff
+// 恰恰只有 focus(换页 morph 在 reply 后才到),而开面板/弹窗/换 view 的 click 会立刻产出 panel/
+// modal/view 行。故「平凡 diff」是「这次 click 看起来什么都没发生 → 可能是慢路由切换」的门控:非平凡
+// diff 立即返回零额外税,只有平凡 diff 才值得等 SPA 信号。纯结构判据,不写死站点。
+export function trivialDiff(changed: string | undefined): boolean {
+    if (!changed)
+        return true
+    const lines = changed.split('\n').map(l => l.trim()).filter(Boolean)
+    return lines.length === 0
+        || lines.every(l => l === '(no state change)' || l.startsWith('focus:') || l.startsWith('--- '))
+}
+
+async function executeAction(
+    bridge: ServerBridge,
+    type: string,
+    args: ActionArgs,
+    ctx: { nextId: () => number, tab?: string, afterNav?: NavProbe },
+): Promise<ExecutedAction> {
+    const check = resolveAction(type, args)
+    if (!check.valid)
+        return { status: 400 }
+    const id = ctx.nextId()
+    // wait actions own their timeout; give the channel that long + slack (matches plugin.ts sendAction)
+    const fullMs = Math.max(args.timeout ?? 0, 3000) + 2000
+    const preUrl = ctx.afterNav ? await ctx.afterNav.url() : undefined
+    // SPA 同文档路由切换的事后监听必须在动作派发前 arm(否则 @0.2s 的快信号在 reply 后才订阅就漏)。
+    // 仅 click/press 可能触发路由,fill/hover/wait 不 arm → 零额外开销。
+    const spaArm = ctx.afterNav?.armSameDocNav && (type === 'click' || type === 'press')
+        ? ctx.afterNav.armSameDocNav()
+        : undefined
+    // navigated:动作派发若撞整页导航,cdpBridge 经 onNav 同步置位(出口1 永不调 → 恒 false)。
+    let navigated = false
+    const result = await bridge.request<ActionResult>('aihand:action', 'aihand:result', { id, type, args }, { tab: ctx.tab, timeoutMs: fullMs, onNav: () => { navigated = true } })
+    // 跨导航回填:探针给的 result.screen 是旧页残影;动作确实触发了整页导航才采新页全貌覆盖换页确认。
+    // 同文档动作 navigated 恒 false → 整块跳过 → 零额外延迟(不再盲等 2s 轮询窗口)。
+    let changed = result.screen
+    if (ctx.afterNav && result.ok && navigated) {
+        const renav = await ctx.afterNav.renavScreen(preUrl ?? '')
+        if (renav)
+            changed = renav
+    }
+    // SPA 路由切换回填:整页导航没撞(navigated 仍 false)、动作成功时分两情况:
+    //   平凡 diff(focus-only,看起来没发生什么 → 可能是慢路由切换):等满 SPA_NAV_CAP 一小窗,
+    //     fire → renavScreen 采新路由全貌;只有「click 没换路由」才付满,fire 即短路。
+    //   非平凡 diff(开了面板/弹窗/换 view):不能等满税普通 click,但若 navigatedWithinDocument
+    //     已 fire(react.dev 这类即时客户端导航 ~40ms,内容同时变所以 diff 富)——用 wait(0) 零阻塞
+    //     探一下「是否已 fire」,已 fire 才回填 navigated:URL 头(内容富 diff 已在,URL 跃迁是额外信号,
+    //     绝不能因为内容也变了就吞掉「你换页了」)。没 fire → 退订零税。
+    else if (spaArm && result.ok && !navigated) {
+        const cap = trivialDiff(changed) ? SPA_NAV_CAP : 0
+        if (await spaArm.wait(cap)) {
+            navigated = true
+            const renav = await ctx.afterNav!.renavScreen(preUrl ?? '')
+            if (renav)
+                changed = renav
+        }
+    }
+    // arm 了但没走 wait 分支(整页导航命中)→ 直接退订,不留悬挂订阅。
+    else if (spaArm) {
+        spaArm.cancel()
+    }
+    return { status: result.ok ? 200 : 422, result, changed, navigated }
+}
+
+export async function dispatchAction(
+    bridge: ServerBridge,
+    type: string,
+    args: ActionArgs,
+    ctx: { nextId: () => number, tab?: string, afterNav?: NavProbe },
+): Promise<DispatchResult> {
+    const ex = await executeAction(bridge, type, args, ctx)
+    if (!ex.result) {
+        const check = resolveAction(type, args)
+        return { status: 400, body: check.error ?? 'invalid action' }
+    }
+    const { result } = ex
+    const head = result.ok ? (result.detail || 'ok') : `${result.error}${result.detail ? `\n\nclickable: ${result.detail}` : ''}`
+    // 跨整页导航后,result.actions 是旧页的动作环(常是 "(no actions)")——changed 的 navigated+新页全貌
+    // 已结清,旧页动作环纯噪音。同文档动作 navigated 为 false → 照常显示当前页真动作环,零回归。
+    const actionsTail = result.actions && !ex.navigated ? `\n\n--- recent actions ---\n${result.actions}` : ''
+    const changedTail = ex.changed ? `\n\n--- changed ---\n${ex.changed}` : ''
+    const flowTail = result.flow ? `\n\n--- flow ---\n${result.flow}` : ''
+    return { status: result.ok ? 200 : 422, body: `${head}${actionsTail}${changedTail}${flowTail}` }
+}
+
+// chain 单步执行器(出口2 用):纯动作 → 结构化 ChainStepResult(无 knob 特例)。导出供 server.ts 注入。
+export async function dispatchChainStep(
+    bridge: ServerBridge,
+    type: string,
+    args: ActionArgs,
+    ctx: { nextId: () => number, tab?: string, afterNav?: NavProbe },
+): Promise<ChainStepResult> {
+    if (!isDispatchAction(type))
+        return { ok: false, label: type, error: `probe chain supports ${ACTION_TYPES.join('/')} only (got ${type})` }
+    const ex = await executeAction(bridge, type, args, ctx)
+    if (!ex.result) {
+        const check = resolveAction(type, args)
+        return { ok: false, label: type, error: check.error ?? 'invalid action' }
+    }
+    const { result } = ex
+    return {
+        ok: result.ok,
+        label: type,
+        detail: result.detail,
+        error: result.error,
+        // 单发把 flow 单列一段尾;chain 单步把 changed + flow 都当缩进 delta 显示在步下。
+        screen: [ex.changed, result.flow].filter(Boolean).join('\n') || undefined,
+        // 导航步的旧页动作环同样是噪音(与单发 dispatchAction 一致),抑制。
+        actions: ex.navigated ? undefined : result.actions,
+    }
+}