aihand 0.0.1 → 0.1.0

package/src/ui/self/discover.ts

@@ -0,0 +1,101 @@
+// 多 store 自动发现 —— Node 端(build/cold,走神经图引擎 stategraph.ts)。
+//
+// store 不只在 src/store/ —— imUIStore 在 features/IM、roleSettingModalStore 在 ChatHeader、
+// leftDrawerStore 在 mobile。被旋钮写到的 store 散落全仓,domain 要闭环就得扫到它们全部。
+// 旧实现 fs 递归 + 逐文件 tree-sitter grow(只认 callee 文本 === 'create',换别名/换工厂名漏)。
+// 现统一到引擎:ts-morph 的 type checker 按返回类型的响应式 marker 字段认 store(构造无关,
+// 不看 callee 名),一次长出全仓状态子图。marker 由调用方透传(默认 '_loading')。
+//
+// 引擎离线:跑在 build/cold load,绝不进浏览器、绝不进 per-HMR 热路径(ts-morph 拖整个 Project)。
+// grow.ts 的 tree-sitter 路径作浏览器零-AST 兜底保留,但真理源是这里。
+// 与 synth.ts 拆开:synth 是纯函数(浏览器安全),discover 拖 ts-morph(Node 限定)。
+
+import type { Grown } from './grow'
+import { existsSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { buildStateGraph, openProject } from '../../read/stategraph.js'
+
+// 从 root 向上走找到含 tsconfig(.app) 的项目根。引擎按 cwd 探 tsconfig,但 discover 的 roots
+// 是 app 的源目录(可能不在 aihand 的 cwd 下,如单测 process.cwd()=packages/aihand),
+// 故从 roots 反推真正的项目根,引擎才能解出 app 的源图(而非 aihand 自己的)。
+function projectRootFor(start: string): string {
+    let dir = statSync(start).isDirectory() ? start : dirname(start)
+    for (;;) {
+        if (['tsconfig.app.json', 'tsconfig.json'].some(f => existsSync(resolve(dir, f))))
+            return dir
+        const up = dirname(dir)
+        if (up === dir)
+            return start // 没找到 → 退回 start,openProject 会自行报错
+        dir = up
+    }
+}
+
+// 把一个根归一成绝对路径前缀,用于判断引擎长出的节点(绝对文件路径)是否落在该根下。
+// 目录 → 加尾斜杠(前缀匹配避免 src/IM 误吞 src/IMx);单文件 → 精确路径。
+function scopePrefix(root: string): string {
+    const abs = resolve(root)
+    try {
+        return statSync(abs).isDirectory() ? `${abs}/` : abs
+    }
+    catch {
+        return abs
+    }
+}
+
+// roots = 目录(递归)或单文件,任意混合。开一次 Project,跑状态子图,过滤落在 roots 内的 store。
+// anchor 用绝对路径长出(供 roots 前缀过滤),再缩成末两段保持运行时契约(与旧 grow 同形)。
+// 返回按中心性(rank)降序(StateNode extends Grown,中心性字段对运行时是无害附加)。
+export async function discover(roots: string | string[], marker: string = '_loading'): Promise<Grown[]> {
+    return (await discoverWithPaths(roots, marker)).map(({ abs: _abs, ...n }) => {
+        const i = n.anchor.lastIndexOf(':')
+        const abs = n.anchor.slice(0, i)
+        return { ...n, anchor: `${abs.split('/').slice(-2).join('/')}${n.anchor.slice(i)}` }
+    })
+}
+
+// 同 discover,但 anchor 不缩末两段,额外带未截断的绝对路径 abs。store-refs 用它 codegen import:
+// 末两段 anchor(store/appUI.ts)对深层 store(features/IM/shared/store.ts → shared/store.ts)
+// 歧义、不可 import;绝对路径才能精确解出 @/ 别名路径。create() store 的真路径源。
+export async function discoverWithPaths(
+    roots: string | string[],
+    marker: string = '_loading',
+): Promise<Array<Grown & { abs: string }>> {
+    const rawRoots = Array.isArray(roots) ? roots : [roots]
+    const list = rawRoots.map(scopePrefix)
+    const project = await openProject(projectRootFor(resolve(rawRoots[0])))
+    const { nodes } = buildStateGraph(project, abs => abs, marker)
+    return nodes
+        .filter((n) => {
+            const fp = n.anchor.slice(0, n.anchor.lastIndexOf(':'))
+            return list.some(p => p.endsWith('/') ? fp.startsWith(p) : fp === p)
+        })
+        .map(n => ({ ...n, abs: n.anchor.slice(0, n.anchor.lastIndexOf(':')) }))
+}
+
+// 按名定位 module-level export const 的声明文件(绝对路径)。store-refs 用它找 facade store
+// (botStore/memoryStore 是 plain-object,无 _loading marker,buildStateGraph 看不见),
+// 但它们仍是 `export const X = {...}` —— ts-morph 按变量名扫一次即得真路径。
+// names 命中即停,返回 名→abs;漏的名(理论上不该有)不进 map,调用方据缺失诚实报错。
+export async function locateExports(
+    roots: string | string[],
+    names: Set<string>,
+): Promise<Map<string, string>> {
+    const rawRoots = Array.isArray(roots) ? roots : [roots]
+    const project = await openProject(projectRootFor(resolve(rawRoots[0])))
+    const out = new Map<string, string>()
+    for (const sf of project.getSourceFiles()) {
+        const fp = sf.getFilePath()
+        if (fp.endsWith('.d.ts') || fp.includes('/node_modules/'))
+            continue
+        for (const v of sf.getVariableDeclarations()) {
+            const name = v.getName()
+            if (!names.has(name) || out.has(name))
+                continue
+            // module-level(变量语句的直接父是 SourceFile)—— 局部同名变量不算 export。
+            const stmt = v.getVariableStatement()
+            if (stmt && stmt.isExported())
+                out.set(name, fp)
+        }
+    }
+    return out
+}

package/src/ui/self/grow.ts

@@ -0,0 +1,121 @@
+// 第一堆的真考验:Self 的结构能否从真实代码静态长出 —— 零模型,纯 tree-sitter AST。
+//
+// 命题精确形式:aipeek 要手挂 window.__AIPEEK_SCREEN__ = () => ({ view: appUIStore.mode, … })
+// 才能让探针读到「view 能取哪些值、有哪些语义状态」。但这些东西 —— 字段名、值域(联合类型
+// 的字面量集)、声明在哪行 —— 源码里本就写着。手挂那行是在重新声明已声明的东西。
+//
+// 所以「从代码静态长出 Self」拆开才成立:静态长出的是【结构】(字段 + 值域 + anchor),
+// 不是【值】(此刻是 chat 还是 settings —— 那是运行时,归 screen 投影那一半)。grow 长结构,
+// screen 投影值,两半合起来才是完整的 self-rep。这一文件证的是:结构无需手挂,AST 即得。
+//
+// 禁正则铁律:对象字面量 + 类型注解是「有语法的东西」,只能走 AST。用 repodex 同款
+// web-tree-sitter(wasm,零模型纯语法树),不引入任何模型。
+
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { Language, Parser } from 'web-tree-sitter'
+
+// 一个语义字段的静态结构。domain 非空 = 这是个有限值域的「档位」(联合字面量类型),
+// 正是 aipeek 手挂进 __AIPEEK_SCREEN__ 的那种 view/mode 变量;domain 空 = 普通状态。
+export interface Field {
+    name: string
+    type: string          // 'string' | 'boolean' | 'string|null' | 'string[]' | union…
+    domain: string[]      // 联合字面量的取值集,如 ['chat','im','workbench'];无则 []
+    line: number          // 1-based,声明所在源码行 —— 这就是 anchor 的来源
+}
+
+// 一个 store 声明长出的结构投影。anchor 指向声明本身;fields 是它暴露的语义状态 schema。
+export interface Grown {
+    store: string         // 变量名,如 'appUIStore'
+    anchor: string        // 'file:line',声明所在(file 由调用方给,line 由 AST 给)
+    fields: Field[]
+}
+
+let langPromise: Promise<Language> | null = null
+function loadLang(): Promise<Language> {
+    if (!langPromise) {
+        langPromise = (async () => {
+            const req = createRequire(import.meta.url)
+            const wasmDir = dirname(req.resolve('@repomix/tree-sitter-wasms/out/tree-sitter-tsx.wasm'))
+            await Parser.init()
+            return Language.load(join(wasmDir, 'tree-sitter-tsx.wasm'))
+        })()
+    }
+    return langPromise
+}
+
+// 从一个 pair 节点的 value 侧推出 type + domain。两种形状:
+//   as_expression(value as Type)  → 读 Type 那一侧
+//   裸 value(true/false/数字/字符串)→ 从字面量推原始类型
+function typeOf(value: import('web-tree-sitter').Node): { type: string, domain: string[] } {
+    if (value.type === 'as_expression') {
+        // as_expression = [valueExpr, typeAnnotation];取类型注解(最后一个具名子节点)
+        const typeNode = value.namedChild(value.namedChildCount - 1)
+        if (!typeNode)
+            return { type: 'unknown', domain: [] }
+        // 联合字面量类型 → 值域。收集所有 literal_type 下的 string_fragment。
+        const literals = typeNode.descendantsOfType('literal_type')
+        const domain = literals
+            .map(l => l.descendantsOfType('string_fragment')[0]?.text)
+            .filter((s): s is string => !!s)
+        return { type: typeNode.text, domain }
+    }
+    // 裸字面量 → 原始类型
+    if (value.type === 'true' || value.type === 'false')
+        return { type: 'boolean', domain: [] }
+    if (value.type === 'number')
+        return { type: 'number', domain: [] }
+    if (value.type === 'string')
+        return { type: 'string', domain: [] }
+    if (value.type === 'array')
+        return { type: 'array', domain: [] }
+    if (value.type === 'null')
+        return { type: 'null', domain: [] }
+    return { type: value.type, domain: [] }
+}
+
+// 静态长出:扫源码,找 `const X = create({ …state… }, …)`,提取 state 对象的字段结构。
+// file 仅用于拼 anchor(AST 不知道自己的路径)。同步契约依赖 lang 已加载,故是 async。
+export async function grow(code: string, file: string): Promise<Grown[]> {
+    const lang = await loadLang()
+    const parser = new Parser()
+    parser.setLanguage(lang)
+    const tree = parser.parse(code)
+    const root = tree?.rootNode
+    if (!root)
+        return []
+
+    const out: Grown[] = []
+    // 找所有 `identifier = create(object, …)` 形态的 variable_declarator
+    for (const decl of root.descendantsOfType('variable_declarator')) {
+        const nameNode = decl.namedChild(0)
+        const valueNode = decl.childForFieldName('value')
+        if (!nameNode || nameNode.type !== 'identifier' || valueNode?.type !== 'call_expression')
+            continue
+        const callee = valueNode.namedChild(0)
+        if (callee?.type !== 'identifier' || callee.text !== 'create')
+            continue
+        const args = valueNode.childForFieldName('arguments')
+        const stateObj = args?.namedChildren.find(c => c?.type === 'object')
+        if (!stateObj)
+            continue
+
+        const fields: Field[] = []
+        for (const pair of stateObj.namedChildren) {
+            if (pair?.type !== 'pair')
+                continue
+            const key = pair.childForFieldName('key')
+            const value = pair.childForFieldName('value')
+            if (!key || !value)
+                continue
+            const { type, domain } = typeOf(value)
+            fields.push({ name: key.text, type, domain, line: key.startPosition.row + 1 })
+        }
+        out.push({
+            store: nameNode.text,
+            anchor: `${file}:${decl.startPosition.row + 1}`,
+            fields,
+        })
+    }
+    return out
+}

package/src/ui/self/install.ts

@@ -0,0 +1,100 @@
+// self-log 的运行时落地 —— 第二堆命题的真证据。
+//
+// fixture 里手填 channel 只证了「形状能收敛」;这里证「真触发能收敛」:真 patch 五路
+// 浏览器副作用(console/fetch/XHR/error/SSE),五路出口全调同一个 log。aihand runtime 在这五处
+// 各 push 各自的 ring buffer(console/network/errors 三个缓冲,五种采集形状);这里五路
+// 坍缩成一个 append。物理债没被消灭(副作用照样发生),但它的形状从五叉变一条线。
+//
+// 拦截手法本身(tee body / XHR loadend / unhandledrejection / EventSource Proxy)是物理债,
+// 复用既有做法,不重写。新的只有「出口统一」这一点 —— 它把 self.ts 的 log 纯函数接到真触发。
+
+import { log, type LogEntry } from './self'
+
+export interface Sink {
+    seq: LogEntry[]
+    now: () => number
+}
+
+// 五路的唯一出口。每一路 patch 只负责把副作用翻译成 (channel, detail),append 是同一个。
+function emit(sink: Sink, channel: LogEntry['channel'], detail: string) {
+    sink.seq = log(sink.seq, { channel, detail, ts: sink.now() })
+}
+
+// 返回 restore:把五路 patch 全部还原(测试可隔离,真页面可热重载)。
+export function installSelfLog(win: Window & typeof globalThis, sink: Sink): () => void {
+    const restores: Array<() => void> = []
+
+    // ── console ──
+    const levels = ['log', 'info', 'warn', 'error', 'debug'] as const
+    for (const level of levels) {
+        const orig = win.console[level]
+        win.console[level] = (...args: unknown[]) => {
+            emit(sink, 'console', `[${level}] ${args.map(String).join(' ')}`)
+            orig.apply(win.console, args)
+        }
+        restores.push(() => { win.console[level] = orig })
+    }
+
+    // ── fetch ──
+    const origFetch = win.fetch
+    win.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
+        const method = init?.method || 'GET'
+        try {
+            const res = await origFetch(input, init)
+            emit(sink, 'fetch', `${method} ${url} ${res.status}`)
+            return res
+        }
+        catch (e) {
+            emit(sink, 'fetch', `${method} ${url} failed: ${e instanceof Error ? e.message : String(e)}`)
+            throw e
+        }
+    }
+    restores.push(() => { win.fetch = origFetch })
+
+    // ── XHR ──
+    const XHRProto = win.XMLHttpRequest.prototype
+    const origOpen = XHRProto.open
+    const origSend = XHRProto.send
+    interface Tracked { __m?: string, __u?: string }
+    XHRProto.open = function (this: XMLHttpRequest & Tracked, method: string, url: string | URL, ...rest: unknown[]) {
+        this.__m = method
+        this.__u = typeof url === 'string' ? url : url.toString()
+        // @ts-expect-error variadic passthrough to the native signature
+        return origOpen.call(this, method, url, ...rest)
+    }
+    XHRProto.send = function (this: XMLHttpRequest & Tracked, ...args: unknown[]) {
+        this.addEventListener('loadend', () => {
+            emit(sink, 'xhr', `${this.__m ?? 'GET'} ${this.__u ?? ''} ${this.status}`)
+        })
+        // @ts-expect-error variadic passthrough to the native signature
+        return origSend.apply(this, args)
+    }
+    restores.push(() => { XHRProto.open = origOpen; XHRProto.send = origSend })
+
+    // ── error + unhandledrejection ──
+    const onError = (e: ErrorEvent) => emit(sink, 'error', e.message || String(e.error))
+    const onRejection = (e: PromiseRejectionEvent) => emit(sink, 'error', `unhandled rejection: ${String(e.reason)}`)
+    win.addEventListener('error', onError)
+    win.addEventListener('unhandledrejection', onRejection)
+    restores.push(() => {
+        win.removeEventListener('error', onError)
+        win.removeEventListener('unhandledrejection', onRejection)
+    })
+
+    // ── SSE ──
+    const OrigES = win.EventSource
+    if (OrigES) {
+        win.EventSource = new Proxy(OrigES, {
+            construct(Target, cArgs) {
+                const es = new Target(...cArgs as ConstructorParameters<typeof EventSource>)
+                const url = String(cArgs[0])
+                es.addEventListener('error', () => emit(sink, 'sse', `${url} error (readyState ${es.readyState})`))
+                return es
+            },
+        })
+        restores.push(() => { win.EventSource = OrigES })
+    }
+
+    return () => { for (const r of restores) r() }
+}

package/src/ui/self/probe.ts

@@ -0,0 +1,105 @@
+// aihand 运行时探针的安装逻辑 —— 把 schema(virtual:store-schema)⋉ 运行时实例(__AIPEEK_STORES__)
+// 接成 4 个 window 全局(__AIPEEK_SCREEN__/__AIPEEK_VIEW__/__AISELF__/__AIHAND_ACTIONS__),供 aihand
+// /screen·/state·/action 读。这一坨原本内联在宿主 app 的 main.tsx(~90 行嵌套 .then),全是通用胶水,
+// 只有「哪个 store 是 view 轴、哪个 facade 要枚举、哪些跨店派生量、动作表」是 app 特有 —— 那些经 ProbeConfig
+// 传入。app 端塌成「import store-refs → installProbe(config)」两步。
+//
+// 框架无关:核心拓扑是「(字段值域 schema) ⋉ (运行时实例) → 投影」,与状态库无关(MobX/Zustand/Valtio/
+// Signal 都是「命名状态容器 × 字段」)。两处曾把 MobX 实现当领域真相、现已拔成可插拔策略:
+//   ① view 轴 —— 由 config.view 显式声明(probe 不靠「第一个有限值域字段」猜)。
+//   ② facade 枚举 —— enumerateFacade 默认认 MobX observable 的 setter 描述符,其它框架可覆盖。
+// 纯函数(synth/screenHook/act)各自单测;这里只负责把它们接到运行时 + 装窗。浏览器安全(不碰 ts-morph)。
+
+import type { Grown } from './grow'
+import { screenHook } from './screen-hook'
+import { synth } from './synth'
+
+interface Schema {
+    [store: string]: Grown
+}
+
+// facade 枚举策略:一个 plain-object store 暴露哪些字段当 domain。grow 静态看不见 facade(无响应式
+// marker),只能运行时枚举。默认 = MobX observable 的「带 setter 的字段」(= 被旋钮写的可变状态);
+// 换框架可传别的(如 Vue reactive 用 Reflect.ownKeys,Signal 用 .value 探测)。返回字段名数组。
+export type FacadeEnumerator = (inst: object) => string[]
+
+// 默认:MobX observable —— getOwnPropertyDescriptors 里带 set 的就是可变状态字段。
+export const enumerateMobxSetters: FacadeEnumerator = inst =>
+    Object.entries(Object.getOwnPropertyDescriptors(inst))
+        .filter(([, d]) => d.set)
+        .map(([k]) => k)
+
+// probe 写的 4 个全局。aihand 是独立包,不依赖宿主 app 的 ambient Window 声明 —— 在此本地结构化声明,
+// 宿主传 window 结构上满足即可(宿主 global.d.ts 里的 __AIPEEK_* 与这里同形)。
+export interface ProbeWindow {
+    __AIPEEK_STORES__?: Record<string, unknown>
+    __AIPEEK_SCREEN__?: () => Record<string, unknown>
+    __AIPEEK_VIEW__?: () => string
+    __AISELF__?: { self: () => unknown, schemaFieldCount: () => number, handMountedKeys: () => string[] }
+    __AIHAND_ACTIONS__?: Record<string, (...args: never[]) => unknown>
+}
+
+export interface ProbeConfig {
+    // schema(virtual:store-schema 的 build 产物:store 名 → 字段/值域)。
+    schema: Schema
+    // 名→实例 映射(virtual:store-refs 的 codegen 产物)。schema∩实例 配对喂 screenHook。
+    stores: Record<string, unknown>
+    // view 轴:app 声明哪个状态是顶层视图(probe 不猜)。如 () => String(appUIStore.mode)。
+    view: () => string
+    // synth(__AISELF__.self())用哪个 store 的 schema+实例。
+    selfStore: string
+    // 跨店派生量(grow 长不出的,如 流式中/模型/会话)。并进 domain,key 即字段名。
+    derived?: Record<string, () => unknown>
+    // facade store:grow 看不见(plain object 无 marker),运行时枚举它的字段并入 domain,前缀 `${name}.`。
+    // 值取 instance[k],异常吞成 '[error]'。
+    facades?: Record<string, object>
+    // facade 字段枚举策略(框架无关注入点)。默认 enumerateMobxSetters(认 MobX observable 的 setter)。
+    enumerateFacade?: FacadeEnumerator
+    // 一等公民语义动作(对偶状态自表示):AI 直接调绕 DOM。每个动作返回 { delta }(动作改了什么)。
+    actions?: Record<string, (...args: never[]) => Promise<void>>
+}
+
+function pick<T>(f: () => T): T | string {
+    try {
+        return f()
+    }
+    catch {
+        return '[error]'
+    }
+}
+
+export function installProbe(win: ProbeWindow, config: ProbeConfig): void {
+    win.__AIPEEK_STORES__ = config.stores
+
+    // schema 里有的 store(create 变量名 = export 名)按名配对运行时实例;schema 没有的(facade、纯派生量)
+    // 经 `in stores` 天然滤除 —— 一份 schema 当判据,清单自动闭环(手列 live 必漏)。
+    const snaps = Object.keys(config.schema)
+        .filter(name => name in config.stores)
+        .map(name => ({ schema: config.schema[name], snapshot: config.stores[name] as Record<string, unknown> }))
+
+    const enumerate = config.enumerateFacade ?? enumerateMobxSetters
+    win.__AIPEEK_SCREEN__ = () => {
+        const { domain } = screenHook(snaps)
+        for (const [name, inst] of Object.entries(config.facades ?? {})) {
+            for (const k of enumerate(inst))
+                domain[`${name}.${k}`] = pick(() => (inst as Record<string, unknown>)[k])
+        }
+        for (const [k, f] of Object.entries(config.derived ?? {}))
+            domain[k] = pick(f)
+        return domain
+    }
+
+    win.__AIPEEK_VIEW__ = config.view
+    win.__AISELF__ = {
+        self: () => synth(config.schema[config.selfStore], config.stores[config.selfStore] as Record<string, unknown>),
+        schemaFieldCount: () => Object.values(config.schema).reduce((n, s) => n + s.fields.length, 0),
+        handMountedKeys: () => Object.keys(win.__AIPEEK_SCREEN__!()),
+    }
+
+    // 动作自表示:app 把「按钮 onClick 跑的 (store-write + 真语义函数)、减去 DOM」挂成裸 fn。
+    // 反馈(改了什么 + 异步流轨迹)由 client 端唯一终端 settleAndTrace 统一接管 —— 与 click/knob
+    // 同一条 waitForStable+traceFlow 路径,无分裂、无弱化。曾在此自造 before/after 同步夹 await 的
+    // act() delta,但它捕不到异步流(generateWithPrompt 首字节即 resolve → delta 永远空),且与 client
+    // 的轨迹采集重复;现已坍缩 —— 动作只管「做」,反馈一律走 client 终端。
+    win.__AIHAND_ACTIONS__ = config.actions ?? {}
+}

package/src/ui/self/screen-hook.ts

@@ -0,0 +1,44 @@
+// 命题2 的核心 —— 决定性 head-to-head:aipeek 要开发者手挂
+//   window.__AIPEEK_SCREEN__ = () => ({ view: appUIStore.mode, streaming: ..., ... })
+// 并人工枚举哪个字段是 view、domain 有哪些 key。aiself 把这一行从源码长出:
+//   静态引擎(stategraph)已得到字段名 + 值域 + 哪个是档位(domain 非空),
+//   screenHook 据此生成同形状对象,view 字段、domain keys 全自动。
+//
+// 单店 → 多店:被旋钮写的 store 散落 11 个,domain 要覆盖它们全部才能闭环(拨任一旋钮 →
+// diff 必能看到它改的字段)。domain key 用 `store.field` 命名空间:① 避免跨店重名(多店都有
+// loading/error)② diff 行直接读成 `botStore.filterByCurrentBot: false → true`,与旋钮态射
+// `botStore.{filterByCurrentBot=...}` 同构。这就是「超越」的硬证据:aipeek diff.ts 自己承认
+// domain 状态机是 DOM 投影看不见、只能靠 __AIPEEK_SCREEN__ 手挂的;aiself 让那一行不必手写。
+
+import type { Grown } from './grow'
+import type { Snapshot } from './synth'
+
+// 一个 store 的 schema + 它此刻的运行时快照。screenHook 吃一批这个 → 合并 domain。
+export interface StoreSnap {
+    schema: Grown
+    snapshot: Snapshot
+}
+
+// 与 aipeek ScreenSnap 同形状的投影。view = 第一个有限值域字段(domain 非空)的当前值;
+// domain = 全店全字段,key 命名空间化为 `store.field`(零手写枚举,零跨店重名)。
+export interface ScreenHook {
+    view: string
+    domain: Record<string, unknown>
+}
+
+// 一批 (schema, snapshot) → aipeek __AIPEEK_SCREEN__ 同形状对象。
+// view 取第一个档位字段(有限值域),它就是 appUIStore.mode —— 把 appUIStore 放数组首位即得。
+// domain[`${store}.${field}`] = 此刻值。挂到 window.__AIPEEK_SCREEN__,aipeek /screen 读到的
+// domain 就来自源码声明,不来自任何手写枚举。
+export function screenHook(stores: StoreSnap[]): ScreenHook {
+    const domain: Record<string, unknown> = {}
+    let view = ''
+    for (const { schema, snapshot } of stores) {
+        for (const f of schema.fields) {
+            domain[`${schema.store}.${f.name}`] = snapshot[f.name]
+            if (!view && f.domain.length > 0)
+                view = String(snapshot[f.name] ?? '')
+        }
+    }
+    return { view, domain }
+}

package/src/ui/self/self.ts

@@ -0,0 +1,48 @@
+// aiself — app 即自己。两堆,分治。
+//
+// 读完 aipeek 全部源码(5378 行)后的诚实账本:它的体量分两类。
+//
+// 一类是「自表示债」——fiber walk / 解 sourcemap / babel 盖 data-insp-path 戳 /
+//   手挂 __AIPEEK_STORES__,≈1000 行。全因为 app 不声明自己,只能从黑盒逆向抠。
+//   这一堆 aiself 删到 0:状态/结构/源码 anchor 是同一个声明,「感知自己」是读,非抠。
+//
+// 另一类是「物理债」——浏览器全局副作用(网络/未捕获异常/SSE 流),不在任何 app
+//   状态声明里,它们是运行时事件。这一堆谁都删不掉。aiself 不消灭它,而是把 aipeek
+//   的五处分散 patch(console/fetch/XHR/SSE/error)+ 各自 ring buffer 收敛成一条 Log。
+//
+// 所以命题不是「感知自己 0 行」(假——物理债删不掉),而是:
+//   ① 自表示债 → 0(screen 投影无函数体)
+//   ② 物理债 → 一条 self-log 原语,取代五处分散 patch
+
+// ── 第一堆:self-rep ──
+// view 是互斥档位;modal 决定底层能否操作;focus 是当前焦点;
+// state 是这个 self 暴露的语义变量;anchor 是声明自带的源码来源(非 babel 事后盖戳)。
+export interface Self {
+    view: string
+    modal: string | null
+    focus: string | null
+    state: Record<string, unknown>
+    anchor: string
+}
+
+// 感知自己 = 投影。无 walk、无 patch、无 sourcemap —— 因为 self 本就自表示。
+// 这是第一堆「自表示债 → 0」的证据:函数趋近无函数体。
+export function screen(self: Self): Self {
+    return self
+}
+
+// ── 第二堆:self-log ──
+// 一条 Log,不是五个 ring buffer。channel 标出这条记录来自哪路浏览器副作用
+// (console/fetch/xhr/sse/error),但它们流进同一个序列、同一个形状。
+// aipeek 为这五路写了五处 monkey-patch + 五个独立缓冲;这里是一个 append。
+export interface LogEntry {
+    channel: 'console' | 'fetch' | 'xhr' | 'sse' | 'error'
+    detail: string
+    ts: number
+}
+
+// 收敛点:五路副作用 → 一次 append。物理债没被消灭(浏览器副作用照样发生),
+// 但它的「形状」从五个分叉坍缩成一条线。这是第二堆的赢点 —— 统一,非删除。
+export function log(seq: LogEntry[], entry: LogEntry): LogEntry[] {
+    return [...seq, entry]
+}

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

@@ -0,0 +1,123 @@
+// aihand/self —— store 实例映射的 build 时 codegen。对偶于 store-schema(那个 emit 值域 schema,
+// 这个 emit 运行时实例)。
+//
+// 绿色通道(executeKnob)要拿真 store 实例直写字段,实例来源 window.__AIPEEK_STORES__。
+// 旧实现是 main.tsx 一份手抄清单 —— 加旋钮引新 store 没机制强制并入,会无声腐烂(实测漏过
+// memoryStore + 5 个 store)。这里把那份清单 codegen 掉:从「被旋钮写的 store 名」(knob schema 的
+// 真理源)精确长出 import,main.tsx 塌成一行 import('virtual:store-refs')。
+//
+// 范围 = 旋钮引用的 store(非全仓发现的 ~21 个)。create 类从 discoverWithPaths 拿路径,
+// facade 类(botStore/memoryStore,无 _loading marker)= 旋钮集 ∖ 发现集,按名 locateExports 定位。
+// 引擎离线:跑在 build/cold load,ts-morph + tree-sitter 绝不进浏览器。
+
+import { relative } from 'node:path'
+import { buildPanel } from '../../read/panel.js'
+import { discoverWithPaths, locateExports } from './discover.js'
+
+const VIRTUAL = 'virtual:store-refs'
+const RESOLVED = `\0${VIRTUAL}`
+
+interface Options {
+    // store 发现的根(绝对路径),同 storeSchema。create() store 从这里的状态子图长出。
+    roots: string | string[]
+    // 旋钮提取扫的组件文件(绝对路径 tsx/jsx)。store 名集合 = 这些文件里旋钮写到的 store。
+    knobFiles: string[]
+    // 项目源根(绝对路径,= <projectRoot>/src),codegen 的 @/ 别名据此从 abs 反解。
+    srcRoot: string
+    storeMarker?: string
+}
+
+export interface StoreRef {
+    name: string // export 名 = 变量名,如 'botStore'
+    alias: string // import 路径,如 '@/store/bot'
+}
+
+// 绝对路径 → @/ 别名 import 路径。strip srcRoot 前缀 + 去扩展名,逐字符(无正则,本仓铁律)。
+// '/p/src/features/IM/shared/store.tsx' + '/p/src' → '@/features/IM/shared/store'
+export function toAlias(abs: string, srcRoot: string): string {
+    let rel = relative(srcRoot, abs)
+    for (const ext of ['.tsx', '.ts', '.jsx', '.js']) {
+        if (rel.endsWith(ext)) {
+            rel = rel.slice(0, -ext.length)
+            break
+        }
+    }
+    return `@/${rel}`
+}
+
+// facade 集 = 旋钮引用的 store 名 ∖ marker 发现的 store 名。补集,零手列。
+export function pickFacades(knobNames: Set<string>, discoveredNames: Set<string>): string[] {
+    return [...knobNames].filter(n => !discoveredNames.has(n))
+}
+
+// codegen 虚拟模块文本。同 alias 路径去重(appUIStore/updateStore 同文件 → 一行 import 两名),
+// 末尾聚合 export const stores = { ...全部名 }。
+export function emitModule(refs: StoreRef[]): string {
+    const byAlias = new Map<string, string[]>()
+    for (const r of refs) {
+        const names = byAlias.get(r.alias) ?? []
+        names.push(r.name)
+        byAlias.set(r.alias, names)
+    }
+    const imports: string[] = []
+    for (const [alias, names] of byAlias)
+        imports.push(`import { ${[...new Set(names)].sort().join(', ')} } from '${alias}'`)
+    const all = [...new Set(refs.map(r => r.name))].sort()
+    return `${imports.join('\n')}\nexport const stores = { ${all.join(', ')} }\n`
+}
+
+export function storeRefs(options: Options) {
+    const roots = Array.isArray(options.roots) ? options.roots : [options.roots]
+    let cache: string | null = null
+
+    const build = async (): Promise<string> => {
+        if (cache)
+            return cache
+        // 1. create 类:状态子图发现,带未截断绝对路径。
+        const discovered = await discoverWithPaths(roots, options.storeMarker)
+        const byName = new Map(discovered.map(d => [d.store, d.abs]))
+
+        // 2. 旋钮引用的 store 名集合(真理源:绿色通道实际需要的精确集)。
+        const knobs = await buildPanel(options.knobFiles)
+        const knobNames = new Set(knobs.map(k => k.store).filter(Boolean))
+
+        // 3. facade 类:旋钮集 ∖ 发现集,按名定位真路径。
+        const facadeNames = new Set(pickFacades(knobNames, new Set(byName.keys())))
+        const facadePaths = facadeNames.size ? await locateExports(roots, facadeNames) : new Map<string, string>()
+
+        // 4. needed = 旋钮引用的 store。create 取发现路径,facade 取 locate 路径;路径缺失 → 跳过 + warn。
+        const refs: StoreRef[] = []
+        const missing: string[] = []
+        for (const name of knobNames) {
+            const abs = byName.get(name) ?? facadePaths.get(name)
+            if (!abs) {
+                missing.push(name)
+                continue
+            }
+            refs.push({ name, alias: toAlias(abs, options.srcRoot) })
+        }
+        if (missing.length)
+            console.warn(`[aihand:store-refs] 旋钮引用但定位不到声明的 store(已跳过): ${missing.join(', ')}`)
+
+        cache = emitModule(refs)
+        return cache
+    }
+
+    return {
+        name: 'aihand:store-refs',
+        resolveId(id: string) {
+            if (id === VIRTUAL)
+                return RESOLVED
+        },
+        async load(id: string) {
+            if (id !== RESOLVED)
+                return
+            return build()
+        },
+        // store 文件或组件改动 → 失效缓存,下次 cold load 重 codegen(加旋钮引新 store → 自动并入)。
+        handleHotUpdate(ctx: { file: string }) {
+            if (roots.some(r => ctx.file.startsWith(r)) || ctx.file.endsWith('.tsx') || ctx.file.endsWith('.jsx'))
+                cache = null
+        },
+    }
+}